ATWINC15x0 ATWINC15x0 Wi-Fi® Network Controller Software Design Guide Introduction Microchip’s SmartConnect ATWINC15x0 is an IEEE® 802.11 b/g/n network controller SoC for Internet of Things (IoT) applications. It is an ideal add-on to the existing microcontroller (MCU) solutions bringing WiFi and network capabilities through an SPI-to-Wi-Fi interface. The ATWINC15x0 connects to any Microchip AVR® or Microchip SMART™ MCU with minimal resource requirements. Features • Wi-Fi IEEE 802.11 b/g/n STA, and AP modes • Wi-Fi Protected Setup (WPS) • Support of WEP, WPA/WPA2 Personal, and WPA/WPA2 Enterprise Security – EAP-TLS – EAP-PEAPv0/1 with TLS – EAP-TTLSv0 with MSCHAPv2 – EAP-PEAPv0/1 with MSCHAPv2 • Embedded network stack protocols to offload work from the MCU (minimize the host CPU requirements). This allows the Wi-Fi Network Controller (WINC) to operate with a wide range of MCUs including low-end MCUs. • Embedded uIP TCP/IP stack with BSD-Style socket API • Embedded network protocols – DHCP client/server – DNS resolver client – SNTP client for UTC time synchronization • Embedded TLS security abstracted behind BSD-style socket API • HTTP server for provisioning over AP mode • Ultra-low C IEEE 802.11 b/g/n RF/PH/MAC SoC • Fast boot from On-Chip boot ROM • 8 Mb (WINC1510) and 4 Mb (WINC1500) internal Flash memory with Over-the-Air (OTA) firmware upgrade • WINC1510 support Host File Download feature which can be used for host MCU over the air firmware update • Low-power consumption with different Power Save modes • Low footprint host driver with the following capabilities: – Can run on 8-, 16-, and 32-bit MCU using SPI interface – Little- and big-endian support © 2018 Microchip Technology Inc. User Guide DS00002389B-page 1 Table of Contents Introduction......................................................................................................................1 Features.......................................................................................................................... 1 1. Host Driver Architecture............................................................................................ 5 1.1. WLAN API.................................................................................................................................... 5 1.2. Socket API....................................................................................................................................5 1.3. Host Interface (HIF)......................................................................................................................6 1.4. Board Support Package (BSP).....................................................................................................6 1.5. Serial Bus Interface......................................................................................................................6 2. ATWINC15x0 System Architecture............................................................................7 2.1. Bus Interface................................................................................................................................ 7 2.2. Nonvolatile Storage......................................................................................................................8 2.3. CPU..............................................................................................................................................8 2.4. IEEE 802.11 MAC Hardware........................................................................................................8 2.5. Program Memory..........................................................................................................................8 2.6. Data Memory................................................................................................................................8 2.7. Shared Packet Memory................................................................................................................8 2.8. IEEE 802.11 MAC Firmware........................................................................................................ 8 2.9. Memory Manager......................................................................................................................... 8 2.10. Power Management..................................................................................................................... 9 2.11. WINC RTOS.................................................................................................................................9 2.12. WINC IoT Library..........................................................................................................................9 3. WINC Initialization and Simple Application..............................................................11 3.1. BSP Initialization.........................................................................................................................11 3.2. WINC Host Driver Initialization................................................................................................... 11 3.3. Socket Layer Initialization...........................................................................................................11 3.4. WINC Event Handling................................................................................................................ 12 3.5. Example Code............................................................................................................................13 4. ATWINC15x0 Configuration.....................................................................................14 4.1. Device Parameters.....................................................................................................................14 4.2. WINC Modes of Operation......................................................................................................... 14 4.3. Network Parameters...................................................................................................................16 4.4. Power Save Modes.................................................................................................................... 17 4.5. Configuring Listen Interval and DTIM Monitoring.......................................................................18 5. Wi-Fi Station Mode.................................................................................................. 20 5.1. Scan Configuration Parameters................................................................................................. 20 5.2. Wi-Fi Scan..................................................................................................................................20 5.3. Wi-Fi Security.............................................................................................................................21 5.4. On Demand Wi-Fi Connection................................................................................................... 22 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 2 5.5. Default Connection.....................................................................................................................25 5.6. Encrypted Credential Storage.................................................................................................... 26 5.7. Simple Roaming.........................................................................................................................27 5.8. Multiple Gain Table.....................................................................................................................29 5.9. Host File Download.................................................................................................................... 30 6. Socket Programming............................................................................................... 39 6.1. Overview.................................................................................................................................... 39 6.2. Sockets API................................................................................................................................39 6.3. Socket Connection Flow.............................................................................................................47 6.4. Example Code............................................................................................................................51 7. Transport Layer Security (TLS)............................................................................... 56 7.1. TLS Overview.............................................................................................................................56 7.2. TLS Connection Establishment..................................................................................................56 7.3. Server Certificate Installation..................................................................................................... 58 7.4. WINC TLS Limitations................................................................................................................59 7.5. SSL Client Code Example..........................................................................................................60 8. Wi-Fi AP Mode........................................................................................................ 62 8.1. Overview.................................................................................................................................... 62 8.2. Setting the WINC AP Mode........................................................................................................62 8.3. Limitations.................................................................................................................................. 62 8.4. Sequence Diagram.....................................................................................................................62 8.5. AP Mode Code Example............................................................................................................63 9. Provisioning............................................................................................................. 65 9.1. HTTP Provisioning..................................................................................................................... 65 9.2. Limitations.................................................................................................................................. 68 9.3. Wi-Fi Protected Setup (WPS).....................................................................................................68 10. Over-The-Air Upgrade.............................................................................................71 10.1. Overview.................................................................................................................................... 71 10.2. OTA Image Architecture............................................................................................................. 71 10.3. OTA Download Sequence Diagram........................................................................................... 72 10.4. OTA Firmware Rollback............................................................................................................. 72 10.5. OTA Limitations..........................................................................................................................73 10.6. OTA Code Example....................................................................................................................73 11. Multicast Sockets.....................................................................................................74 11.1. Overview.................................................................................................................................... 74 11.2. How to Use Filters......................................................................................................................74 11.3. Multicast Socket Code Example.................................................................................................74 12. WINC Serial Flash Memory.....................................................................................78 12.1. Overview and Features.............................................................................................................. 78 12.2. Accessing to Serial Flash...........................................................................................................78 12.3. Read/Write/Erase Operations.................................................................................................... 78 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 3 13. Host Interface (HIF) Protocol...................................................................................81 13.1. Transfer Sequence Between the HIF Layer and the WINC Firmware........................................82 13.2. HIF Message Header Structure..................................................................................................84 13.3. HIF Layer APIs...........................................................................................................................84 13.4. Scan Code Example...................................................................................................................85 14. WINC SPI Protocol..................................................................................................90 14.1. Introduction.................................................................................................................................90 14.2. Message Flow for Basic Transactions......................................................................................101 14.3. SPI Level Protocol Example.....................................................................................................105 15. Appendix A. How to Generate Certificates............................................................128 15.1. Introduction...............................................................................................................................128 15.2. Steps........................................................................................................................................ 128 15.3. Limitations................................................................................................................................ 128 16. Appendix B. X.509 Certificate Format and Conversion.........................................129 16.1. Introduction...............................................................................................................................129 16.2. Conversion Between Different Formats................................................................................... 129 17. References............................................................................................................ 131 18. Document Revision History................................................................................... 132 The Microchip Web Site.............................................................................................. 133 Customer Change Notification Service........................................................................133 Customer Support....................................................................................................... 133 Microchip Devices Code Protection Feature............................................................... 133 Legal Notice.................................................................................................................134 Trademarks................................................................................................................. 134 Quality Management System Certified by DNV...........................................................135 Worldwide Sales and Service......................................................................................136 ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 4 1. Host Driver Architecture The following figure shows the architecture of the WINC host driver software, which runs on the host MCU. Figure 1-1. Host Driver Software Architecture The ATWINC15x0 host driver software is a C library, which provides the host MCU application with necessary APIs to perform necessary WLAN and socket operations. The components of the host driver are described in the following sub-sections. 1.1 WLAN API This module provides an interface to the application for all Wi-Fi operations and any non-IP related operations. This includes the following services: • Wi-Fi STA management operations – Wi-Fi scan – Wi-Fi connection management (connect, disconnect, connection status, and so on) – WPS activation/deactivation • Wi-Fi AP enable/disable • Wi-Fi power save control API This interface is defined in the m2m_wifi.h file. 1.2 Socket API This module provides the socket communication APIs that are mostly compliant with the well-known BSD sockets to enable rapid application development. To comply with the nature of the MCU application environment, there are differences in API prototypes and in usage of some APIs between the WINC sockets and BSD sockets. This interface is defined in the socket.h file. ATWINC15x0 Host Driver Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 5 The detailed description of the socket operations is provided in Socket Programming. 1.3 Host Interface (HIF) The HIF is responsible for handling the communication between the host driver and the WINC firmware. This includes interrupt handling, DMA and HIF command/response management. The host driver communicates with the firmware in the form of commands and responses formatted by the HIF layer. The interface is defined in the m2m_hif.h file. The detailed description of the HIF design is provided in Host Interface Protocol. 1.4 Board Support Package (BSP) The Board Support Package abstracts the functionality of a specific host MCU platform. This allows the driver to be portable to a wide range of hardware and hosts. Abstraction includes: pin assignment, power on/off sequence, reset sequence and peripheral definitions (Push buttons, LEDs, and so on). The minimum required BSP functionality is defined in the nm_bsp.h file. 1.5 Serial Bus Interface The Serial Bus Interface module abstracts the hardware associated with implementing the bus between the Host and the WINC. The serial bus interface abstracts I2C, SPI, or UART bus (Currently, host driver supports only SPI bus interface). The basic bus access operations (Read and Write) are implemented in this module as appropriate for the interface type and the specific hardware. The bus interface APIs are defined in the nm_bus_wrapper.h file. ATWINC15x0 Host Driver Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 6 2. ATWINC15x0 System Architecture The following figure shows the ATWINC15x0 system architecture. In addition to its built-in Wi-Fi IEEE-802.11 physical layer and RF front end, the WINC ASIC contains an embedded APS3S-Cortus 32- bit CPU to run the WINC firmware. The firmware comprises the Wi-Fi IEEE-802.11 MAC layer and embedded protocol stacks which offload the host MCU. The components of the system are described in the following sub-sections. Figure 2-1. ATWINC15x0 System Architecture 2.1 Bus Interface Hardware logic for the supported bus types for the ATWINC15x0 communications. Note:  SPI is currently the bus interface supported by the Host Driver. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 7 2.2 Nonvolatile Storage The ATWINC1510 has an integrated 8 Mb and the ATWINC1500 has an integrated 4 Mb serial Flash inside the WINC package (SIP). This stores the WINC firmware image and can store a second image to support OTA. It also stores information used by the WINC firmware in the run-time. The detailed description of the serial Flash is provided in WINC Serial Flash Memory. 2.3 CPU The SoC contains an APS3S-Cortus 32-bit CPU running at 40 MHz clock speed which executes the embedded WINC firmware. 2.4 IEEE 802.11 MAC Hardware The SoC contains a hardware accelerator to ensure fast and compliant implementation of the IEEE 802.11 MAC layer and associated timing. It offloads IEEE 802.11 MAC functionality from firmware to improve performance and boost the MAC throughput. The accelerator includes hardware encryption/ decryption of Wi-Fi traffic and traffic filtering mechanisms to avoid unnecessary processing in software. 2.5 Program Memory 128 KB Instruction RAM is provided for execution of the ATWINC15x0 firmware code. 2.6 Data Memory 64 KB RAM is provided for the ATWINC15x0 firmware data storage. 2.7 Shared Packet Memory 128 KB memory is provided for TX/RX packet management. It is shared between the MAC hardware and the CPU. This memory is managed by the Memory Manager SW component. 2.8 IEEE 802.11 MAC Firmware The system supports IEEE 802.11 b/g/n Wi-Fi MAC including WEP and WPA/WPA2 security supplicant. Between the MAC hardware and the firmware, a full range of IEEE 802.11 features are implemented and supported including beacon generation and reception, control packet generation and reception, and packet aggregation and de-aggregation. 2.9 Memory Manager The memory manager is responsible for the allocation and de-allocation of memory chunks in both shared packet memory and data memory. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 8 2.10 Power Management The Power Management module is responsible for handling different Power Save modes supported by the WINC and coordinating these modes with the Wi-Fi transceiver. 2.11 WINC RTOS The firmware includes a low-footprint real-time scheduler which allows concurrent multi-tasking on the ATWINC15x0 CPU. The ATWINC15x0 RTOS provides semaphores and timer functionality. 2.12 WINC IoT Library The WINC IoT library provides a set of networking protocols in the WINC firmware. It offloads the host MCU from networking and transport layer protocols. The following sections describe the components of the WINC IoT library. 2.12.1 WINC TCP/IP STACK The WINC TCP/IP is an IPv4.0 stack based on the uIP (pronounced micro IP) TCP/IP stack. uIP is a low footprint TCP/IP stack which has the ability to run on a memory-constrained microcontroller platform. It was originally developed by Adam Dunkels, licensed under a BSD style license, and further developed by a wide group of developers. The WINC TCP/IP stack is a customized version of the original uIP implementation which has several enhancements to boost TCP and UDP throughput. 2.12.2 DHCP CLIENT/SERVER A DHCP client is embedded in the WINC firmware that can automatically obtain an IP configuration after connecting to a Wi-Fi network. The WINC firmware provides an instance of a DHCP server that automatically starts when the WINC AP mode is enabled. When the host MCU application activates the AP mode, it is allowed to configure the DHCP Server IP address pool range within the AP configuration parameters. 2.12.3 DNS RESOLVER The WINC firmware contains an instance of an embedded DNS resolver. This module can return an IP address by resolving the host domain names supplied with the socket API call gethostbyname. 2.12.4 SNTP The SNTP (Simple Network Time Protocol) module implements an SNTP client used to synchronize the WINC internal clock to the UTC clock. 2.12.5 Enterprise Security The Enterprise Security module implements the following authentication protocols for establishing a Wi-Fi connection with an AP by WPA/WPA2-Enterprise Security. • EAP with TLS • EAP-PEAPv0/v1 with MSCHAPV2 • EAP-TTLSv0 with MSCHAPv2 • EAP-PEAPv0/v1 with MSCHAPv2 2.12.6 TRANSPORT LAYER SECURITY For TLS implementation, refer to Section 7 “Transport Layer Security (TLS)” for details. ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 9 2.12.7 WI-FI PROTECTED SETUP For WPS protocol implementation, refer to Section 10.3 “Wi-Fi Protected Setup (WPS)” for details. 2.12.8 CRYPTO LIBRARY The Crypto Library contains a set of cryptographic algorithms used by the common security protocols. This library has an implementation of the following algorithms: • MD4 Hash algorithm (used only for MsChapv2.0 digest calculation) • MD5 Hash algorithm • SHA-1 Hash algorithm • SHA-256 Hash algorithm • DES Encryption (used only for MsChapv2.0 digest calculation) • MS-CHAPv2.0 (used as the EAP-TTLS inner authentication algorithm) • MS-CHAPv2.0 (used as the EAP-PEAP and EAP-TTLS inner authentication algorithm) • AES-128, AES-256 Encryption (used for securing WPS and TLS traffic) • BigInt module for large integer arithmetic (for Public Key Cryptographic computations) • RSA Public Key cryptography algorithms (includes RSA Signature and RSA Encryption algorithms) ATWINC15x0 ATWINC15x0 System Architecture © 2018 Microchip Technology Inc. User Guide DS00002389B-page 10 3. WINC Initialization and Simple Application After powering-up the WINC device, a set of synchronous initialization sequences must be executed, for the correct operation of the Wi-Fi functions. This chapter aims to explain the different steps required during the initialization phase of the system. After initialization, the host MCU application is required to call the WINC driver entry point to handle events from the WINC firmware. • BSP Initialization • WINC Host Driver Initialization • Socket Layer Initialization • Call WINC Driver Entry Point Note:  The initialization sequence must be completed to successfully operate the WINC start-up procedure. 3.1 BSP Initialization The BSP is initialized by calling the nm_bsp_init API. The BSP initialization routine performs the following steps: • Resets the WINC1 using the corresponding host MCU control GPIOs. • Initializes the host MCU GPIO which connects to the WINC interrupt line. It configures the GPIO as an interrupt source to the host MCU. During runtime, the WINC interrupts the host to notify the application of events and data pending inside the WINC firmware. • Initializes the host MCU delay function used within nm_bsp_sleep implementation. 3.2 WINC Host Driver Initialization The WINC host driver is initialized by calling the m2m_wifi_init API. The host driver initialization routine performs the following steps: • Initializes the bus wrapper and SPI peripheral. The compilation flag CONF_WINC_USE_SPI must be enabled in conf_winc.h (bus interfaces CONF_WINC_USE_UART and CONF_WINC_USE_I2C are currently not supported). • Registers an application-defined Wi-Fi event handler. • Initializes the driver and ensures compatibility between the WINC firmware version and the driver version. • Initializes the host interface and the Wi-Fi layer and registers the BSP Interrupt. Note:  A Wi-Fi event handler is required for the correct operation of any WINC application. 3.3 Socket Layer Initialization Socket layer initialization is carried out by calling the socketInit API. It must be called prior to any socket activity. For more information about socket initialization and programming, refer to WINC Sockets API. 1 Refer to the ATWINC15x0-MR210xB Data Sheet (DS70005304) for more information about the hardware power-up/down sequence. ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 11 3.4 WINC Event Handling The WINC host driver API allows the host MCU application to interact with the WINC firmware. To facilitate interaction, the WINC driver implements the Host Interface (HIF) Protocol as described in Section 15 “Host Interface (HIF) Protocol”. The HIF protocol defines how to serialize and de-serialize API requests and response callbacks over the serial bus interface SPI (I2C and UART are currently not supported). Figure 3-1. WINC System Architecture The WINC host driver API provides services to the host MCU applications that are mainly divided in two major categories: Wi-Fi control services and Socket services. The Wi-Fi control services allow actions such as channel scanning, network identification, connection and disconnection. The Socket control services allow application data transfer once a Wi-Fi connection is established. 3.4.1 Asynchronous Events Some APIs in the ATWINC15x0 host driver are synchronous function calls, where the result is ready by the return of the function. However, most API functions in the ATWINC15x0 host driver are asynchronous. This means that when the application calls an API to request a service, the call is non-blocking and returns immediately, before the requested action is completed. When completed, a notification is provided in the form of a HIF protocol message from the WINC firmware to the host which, in turn, is delivered to the application via a callback2 function. Asynchronous operation is essential when the requested service such as Wi-Fi connection may take significant time to complete. In general, the ATWINC15x0 firmware uses asynchronous events to signal the host driver about status change or pending data. The HIF uses push architecture where the data and events are pushed from the ATWINC15x0 firmware to the host MCU in a First-Come First-Served (FCFS) manner. For instance, the host MCU application has two open sockets: socket 1 and socket 2. If the ATWINC15x0 receives socket 1 data followed by socket 2 data, then HIF delivers socket data in two HIF protocol messages in the order in which it is received. HIF does not allow reading socket 2 data before socket 1 data. 3.4.2 Interrupt Handling The HIF interrupts the host MCU when one or more events are pending in the ATWINC15x0 firmware. The host MCU application is a big state machine which processes received data and events when the 2 The callback is C function which contains an application-defined logic. The callback is registered using the ATWINC15x0 host driver registration API to handle the result of the requested service. ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 12 ATWINC15x0 driver calls the event callback function(s). To receive event callbacks, the host MCU application is required to call the m2m_wifi_handle_events API to let the host driver retrieve and process the pending events from the ATWINC15x0 firmware. It is recommended to call this function if any of the following events occur: • The host MCU application polls the API in main loop or a dedicated task • When the host MCU receives an interrupt from the ATWINC15x0 firmware Note:  All the application-defined event callback functions registered with the ATWINC15x0 driver run in the context m2m_wifi_handle_events API. The above HIF architecture allows the ATWINC15x0 host driver to be flexible to run in the following configurations: • Host MCU with no operating system configuration – the MCU main loop is responsible to handle deferred work from the interrupt handler • Host MCU with operating system configuration – a dedicated task or thread is required to call m2m_wifi_handle_events to handle deferred work from the interrupt handler Note:  1. Host driver entry point m2m_wifi_handle_events is non-reentrant. In the operating system configuration, it is required to protect the host driver from reentrance by a synchronization object. 2. When the host MCU is polling m2m_wifi_handle_events, the API checks for pending unhandled interrupt from the ATWINC15x0. If no interrupt is pending, it returns immediately. If an interrupt is pending, m2m_wifi_handle_events sequentially reads all the pending HIF messages and dispatches the HIF message content to the respective registered callback. If a callback is not registered to handle the type of message, the HIF message content is discarded. 3.5 Example Code The following example code shows the initialization flow, as described in the previous sections. static void wifi_cb(uint8_t u8MsgType, void *pvMsg) { } int main (void) { tstrWifiInitParam param; nm_bsp_init(); m2m_memset((uint8*)¶m, 0, sizeof(param)); param.pfAppWifiCb = wifi_cb; /*intilize the WINC Driver*/ ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret){ M2M_ERR("Driver Init Failed <%d>\n",ret); while(1); } while(1){ /* Handle the app state machine plus the WINC event handler */ while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } } ATWINC15x0 WINC Initialization and Simple Application © 2018 Microchip Technology Inc. User Guide DS00002389B-page 13 4. ATWINC15x0 Configuration The ATWINC15x0 firmware offers a set of configurable parameters that control its behavior. There is a set of APIs provided to the host MCU application to configure these parameters. The configuration APIs are categorized according to their functionality, into device, network and power saving parameters. Any parameters left unset by the host MCU application use their default values assigned during the initialization of the ATWINC15x0 firmware. A host MCU application needs to configure its parameters when coming out of cold boot or when a specific configuration change is required. 4.1 Device Parameters 4.1.1 System Time It is important to set the WINC system to UTC time to ensure a proper validity check of the X509 certificate expiration date. Since the WINC does not contain a built-in Real-Time Clock (RTC), there are two ways to obtain UTC time: • Using the internal SNTP client – this is enabled by default in the WINC firmware at start-up. The SNTP client synchronizes the WINC system clock to the UTC time from the time servers. The NTP server that SNTP client uses can be configured using the API m2m_wifi_configure_sntp. The default NTP server used by the WINC is time-c.nist.gov. The SNTP client uses a default update cycle of one day. • From the host MCU RTC – if the host MCU has a RTC, the application may disable the SNTP client by calling m2m_wifi_enable_sntp(0) (by passing zero as the argument) after the WINC initialization. The application provisions the WINC system time by calling m2m_wifi_set_system_time API. 4.1.2 Firmware and Driver Version During initialization (m2m_wifi_init), the host driver checks the compatibility between the driver and the WINC firmware. The relevant parameters are: • M2M_HIF_MAJOR_VALUE • M2M_HIF_MINOR_VALUE Note:  These parameters are stated in release note version information as “Host Interface Level: X.Y”. If the driver and the WINC firmware have the same values of M2M_HIF_MAJOR_VALUE, then they are deemed compatible and m2m_wifi_init returns with M2M_SUCCESS. If the driver and the WINC firmware have different values of M2M_HIF_MAJOR_VALUE, then they are deemed incompatible and m2m_wifi_init returns with M2M_ERR_FW_VER_MISMATCH. In this case, communication is limited; the only permitted communication is for the driver to request the WINC firmware to switch to the WINC firmware image in the inactive partition of WINC flash, via m2m_wifi_check_ota_rb and m2m_ota_switch_firmware. Example code to handle this situation is available in the driver file m2m_ota.h. 4.2 WINC Modes of Operation The WINC firmware supports the following modes of operation: ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 14 • Idle mode • Wi-Fi STA mode • Wi-Fi Hotspot (AP) Figure 4-1. WINC Modes of Operation IDLE AP STA m2_wifi_connect m2m_wifi_default_connect M2M_WIFI_RESP_CON_STATE_CHANGED m2m_wifi_disconnect m2m_wifi_disable_ap m2m_wifi_enable_ap 4.2.1 Idle Mode After the host MCU application calls the ATWINC15x0 driver initialization m2m_wifi_init API, the ATWINC15x0 remains in Idle mode waiting for any command to change the mode or to update the configuration parameters. In this mode, the ATWINC15x0 enters into Power Save mode which disables the IEEE 802.11 radio and all unneeded peripherals and suspends the ATWINC15x0 CPU. If the ATWINC15x0 receives any configuration commands from the host MCU, it updates the configuration, sends back the response to the host MCU, and then returns to the Power Save mode. 4.2.2 Wi-Fi Station Mode The ATWINC15x0 enters Station (STA) mode when the host MCU requests connection to an AP using the m2m_wifi_connect or m2m_wifi_default_connect APIs. Note:  m2m_wifi_connect is deprecated from v19.6.1 and above. For more details, see 5.3 Wi-Fi Security. The ATWINC15x0 exits STA mode when it receives a disconnect request from the Wi-Fi AP conveyed to the host MCU application via the event callback M2M_WIFI_RESP_CON_STATE_CHANGED or when the host MCU application decides to terminate the connection via m2m_wifi_disconnect API. Note:  The supported API functions in this mode use the HIF command types: tenuM2mConfigCmd and tenuM2mStaCmd. See the full list of commands in the m2m_types.h header file. For more information about STA mode, refer to Wi-Fi Station Mode. 4.2.3 Wi-Fi Hotspot (AP) Mode In AP mode, the WINC allows Wi-Fi stations to connect and obtain the IP address from the WINC DHCP server. To enter AP mode, the host MCU application calls m2m_wifi_enable_ap API. To exit AP mode, the application calls m2m_wifi_disable_ap API. The supported API functions in this mode use the HIF command types: tenuM2mApCmd and tenuM2mConfigCmd. See the full list of commands in the m2m_types.h header file. For more information about this mode, refer to Wi-Fi AP Mode. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 15 4.3 Network Parameters 4.3.1 Wi-Fi MAC Address The WINC firmware provides two methods to assign the WINC MAC address: • Assignment from the host MCU – this method occurs when the host MCU application calls the m2m_wifi_set_mac_address API after initialization using m2m_wifi_init API. • Assignment from the WINC OTP (One-Time-Programmable) memory – the WINC supports an internal MAC address assignment method through a built-in OTP memory. If MAC address is programmed in the WINC OTP memory, the WINC working MAC address defaults to the OTP MAC address unless the host MCU application programmatically sets a different MAC address after initialization using the API m2m_wifi_set_mac_address. Note:  • OTP MAC address is programmed in the WINC OTP memory at the time of manufacturing. • Use m2m_wifi_get_otp_mac_address API to check if there is a valid programmed MAC address in the WINC OTP memory. The host MCU application can also use the same API to read the OTP MAC address octets. m2m_wifi_get_otp_mac_address API not to be confused with the m2m_wifi_get_mac_address API which reads the working WINC MAC address in the WINC firmware regardless from whether it is assigned from the host MCU or from the WINC OTP. • For more details on API, refer to the Atmel Software Framework for ATWINC1500 (Wi-Fi). 4.3.2 IP Address The ATWINC15x0 firmware uses the embedded DHCP client to automatically obtain an IP configuration after a successful Wi-Fi connection. DHCP is the preferred method and therefore it is used as a default method. After the IP configuration is obtained, the host MCU application is notified by the asynchronous event M2M_WIFI_REQ_DHCP_CONF. Alternatively, the host MCU application can set a static IP configuration by calling the m2m_wifi_set_static_ip API. Before setting a static IP address, it is recommended to disable DHCP using the API m2m_wifi_enable_dhcp(0) and then set the static IP as shown below. In Main(), disable dhcp after m2m_wifi_init as shown below /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) {} } m2m_wifi_enable_dhcp(0); Set Static IP when WINC is connected to AP as shown below. static void wifi_cb(uint8_t u8MsgType, void *pvMsg) { switch (u8MsgType) { case M2M_WIFI_RESP_CON_STATE_CHANGED: { tstrM2mWifiStateChanged *pstrWifiState = (tstrM2mWifiStateChanged *)pvMsg; if (pstrWifiState->u8CurrState == M2M_WIFI_CONNECTED){ printf("Wi-Fi connected\r\n"); tstrM2MIPConfig ip_client; ip_client.u32StaticIP = _htonl(0xc0a80167); // Provide the required Static IP ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 16 ip_client.u32DNS = _htonl(0xc0a80101); // Provide DNS server details ip_client.u32SubnetMask = _htonl(0xFFFFFF00); // Provide the SubnetMask for the currently connected AP ip_client.u32Gateway = _htonl(0xc0a80101); // Provide the GAteway IP for the AP printf("Wi-Fi setting static ip\r\n"); m2m_wifi_set_static_ip(&ip_client); } } } 4.4 Power Save Modes The WINC firmware supports multiple Power Save modes which provide flexibility to the host MCU application to tweak the system power consumption. The host MCU can configure the WINC Power Saving policy using the m2m_wifi_set_sleep_mode and m2m_wifi_set_lsn_int APIs. The WINC supports the following Power Save modes: • M2M_PS_MANUAL • M2M_PS_DEEP_AUTOMATIC • M2M_PS_AUTOMATIC (deprecated, not be used in new implementations) • M2M_PS_H_AUTOMATIC (deprecated, not be used in new implementations) Note:  M2M_PS_DEEP_AUTOMATIC mode recommended for most applications. 4.4.1 M2M_PS_MANUAL This is a fully host-driven Power Save mode. • The WINC sleeps when the host uses the m2m_wifi_request_sleep API. During this period, the host MCU can also sleep for extended durations. • The WINC wakes up when the host MCU application requests services from the WINC by calling any host driver API function, for example, Wi-Fi or socket operation. Note:  In M2M_PS_MANUAL mode, when the WINC sleeps due to m2m_wifi_request_sleep API, the WINC does not wake up to receive and monitor AP beacon. Beacon monitoring is resumed when the host MCU application wakes up the WINC. For an active Wi-Fi connection, the AP may exit the connection if the WINC is unavailable due to long sleep time. If connection is dropped, the WINC detects the disconnection on the next wake-up cycle and notifies the host to reconnect to the AP again. To maintain an active Wi-Fi connection for extended durations, the host MCU application must periodically wake up the WINC in order to send a keep-alive Wi-Fi frame to the AP. The host must carefully choose the sleep period to satisfy the tradeoff between keeping the Wi-Fi connection uninterrupted and minimizing the system power consumption. This mode is useful for applications which send notifications very rarely due to a certain trigger. It also fits applications which periodically send notifications with a very long spacing between notifications. Careful power planning is required when using this mode. If the host MCU decides to sleep for a longer period, it may use M2M_PS_MANUAL or may power off the WINC3 . The advantage of this mode compared to powering off the WINC is that M2M_PS_MANUAL saves the time required for the WINC firmware to boot since the firmware is always loaded in the WINC memory. The real advantage and disadvantage depend on the nature of the application. In some applications, the sleep duration can be long enough to be a 3 Refer to the ATWINC15x0-MR210xB Data Sheet (DS70005304) for more information about the hardware power-up/down sequence. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 17 power-efficient decision to power off the WINC and then power it on again and reconnect to the AP when the host MCU wakes up. In other situations, a latency-sensitive application may choose to use M2M_PS_MANUAL to avoid the WINC firmware boot latency on the expense of slightly increased power consumption. During the WINC Sleep mode, the WINC in M2M_PS_MANUAL mode saves more power than M2M_PS_DEEP_AUTOMATIC mode. In M2M_PS_MANUAL mode, the WINC skips beacon monitoring whereas in M2M_PS_DEEP_AUTOMATIC mode, it wakes up to receive beacons. The comparison also includes the effect of the host MCU sleep duration: if the host MCU sleeps for a longer period, the Wi-Fi connection may frequently drop and the power advantage of the M2M_PS_MANUAL mode is lost due to the power consumed in the Wi-Fi reconnection. In contrast, the M2M_PS_DEEP_AUTOMATIC mode can keep the Wi-Fi connection for long durations at the expense of waking up the WINC to monitor the AP beacon. 4.4.2 M2M_PS_AUTOMATIC This mode is deprecated and kept for backward compatibility and development reasons. It is not recommended to use in new implementations. 4.4.3 M2M_PS_H_AUTOMATIC This mode is deprecated and kept for backward compatibility and development reasons. It is not recommended to use in new implementations. 4.4.4 M2M_PS_DEEP_AUTOMATIC This mode implements the Wi-Fi standard power-saving method in the WINC module. The WINC sleeps and periodically wakes up to monitor AP beacons. The AP is required to buffer data while stations are in Power Save mode and transmit data when stations wake-up. The AP periodically transmits a beacon frame to synchronize with a network for every beacon period. A station, which is in Power Save mode, periodically wakes up to receive the beacon. The beacon conveys information to the station about pending unicast data, which are buffered inside the AP while the station was in Sleep mode. The beacon also provides information about the broadcast/multicast data. In this mode, the WINC module enters into Sleep state by turning off the IEEE 802.11 radio, MAC, and system clock. Prior to entering the Sleep mode, the ATWINC15x0 programs a hardware timer (running on an internal low-power oscillator) with a sleep period determined by the WINC firmware power management module. Any of the following events can wake-up the WINC module from Sleep state: • Expiry of the hardware sleep timer. The WINC wakes up to receive the upcoming beacon from AP. • The WINC wakes up4 when the host MCU application requests services from the WINC by calling any host driver API function, for example, Wi-Fi or socket operation. 4.5 Configuring Listen Interval and DTIM Monitoring The WINC allows the host MCU application to tweak system power consumption by configuring beacon monitoring parameters. The AP periodically send beacons for every DTIM period (for example, 100 ms). The beacon contains a TIM element which informs the station about the unicast data for the station that are buffered in the AP. The station negotiates with the AP for a listen interval. The listen interval tells the AP for how many beacon periods the station will sleep before it wakes up to receive data buffered in the 4 The wake-up sequence is internally handled in the WINC host driver by the hif_chip_wake API. Refer to Section 15 “Host Interface Protocol” for more information. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 18 AP. Some APs might drop buffered data after Listen Interval elapses if the data is not retrieved by the station. The WINC driver allows the host MCU application to configure beacon monitoring parameters as follows: • Configure DTIM monitoring – that is to enable or disable reception of broadcast/multicast data using the following API: – m2m_wifi_set_sleep_mode(desired_mode, 1) to receive broadcast data – m2m_wifi_set_sleep_mode(desired_mode, 0) to ignore broadcast data • Configure the listen interval – using the m2m_wifi_set_lsn_int API Note:  Listen interval value provided to the m2m_wifi_set_lsn_int API is expressed in the unit of beacon period. ATWINC15x0 ATWINC15x0 Configuration © 2018 Microchip Technology Inc. User Guide DS00002389B-page 19 5. Wi-Fi Station Mode This chapter provides information about the WINC Wi-Fi Station (STA) mode as described in Wi-Fi Station Mode. The STA mode involves a scan operation; association to an AP using parameters (SSID and credentials) provided by the host MCU or using AP parameters stored in the WINC nonvolatile storage (default connection). The chapter also provides information about supported security modes along with code examples. 5.1 Scan Configuration Parameters 5.1.1 Scan Region The number of RF channels supported varies by geographical region. For example, 13 channels are supported in Asia while 11 channels are supported in North America. By default, the WINC initial region configuration is equal to 14 channels, but this can be changed by setting the scan region using the m2m_wifi_set_scan_region API. The scan region can be selected from the enum tenuM2mScanRegion. 5.1.2 Scan Options During Wi-Fi scan operation, the WINC sends probe request Wi-Fi frames and waits for the scan wait time to receive probe response frames in the current Wi-Fi channel. After the scan wait time, the WINC switches to the next channel. Increasing the scan wait time increases the possibility to detect more number of access points during scan operation but this leads to more power consumption and overall scan duration. The WINC firmware default scan wait time is optimized to provide the tradeoff between the power consumption and scan accuracy. The WINC firmware provides flexible configuration options to allow the host MCU application to set the scan time. For more details, refer to the m2m_wifi_set_scan_options API. 5.2 Wi-Fi Scan A Wi-Fi scan operation can be initiated by calling the m2m_wifi_request_scan API. The scan can be performed on all 2.4GHz Wi-Fi channels or on a specific requested channel. The scan response time depends on the scan options which can be set by calling m2m_wifi_set_scan_options(tstrM2MScanOption* ptstrM2MScanOption). For instance, if the host MCU application requests to scan all channels, the scan time is equal to NoOfChannels (13) * ptstrM2MScanOption->u8NumOfSlot * ptstrM2MScanOption->u8SlotTime. The scan operation is illustrated in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 20 Figure 5-1. Wi-Fi Scan Operation 5.3 Wi-Fi Security The following types of security are supported in the WINC Wi-Fi STA mode. • OPEN • WEP (Wired Equivalent Protocol) • WPA/WPA2 (Wi-Fi Protected Access - Personal Security mode that is Passphrase) • 802.1X (WPA/WPA2-Enterprise security) For 802.1X Enterprise Security, the following authentication methods are supported from ATWINC1500 firmware version 19.6.1. • EAP-TLS • EAP-PEAPv0/TLS • EAP-PEAPv1/TLS • EAP-TTLSv0/MSCHAPv2 • EAP-PEAPv0/MSCHAPv2 ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 21 • EAP-PEAPv1/MSCHAPv2 The m2m_wifi_connect is deprecated from v19.6.1 and above firmware. The legacy APIs m2m_wifi_connect and m2m_wifi_connect_sc are available as wrappers for the new APIs. Functionally its behavior is unchanged from previously released drivers. The recommended API for various security type such as OPEN, WEP, WPA/WPA2, 802.1X are summarized in the Table 5-1. All new connect APIs, enable connection to a particular access point by specifying its BSSID and the SSID. To restrict connection to a specific access point, the application can specify the BSSID (in addition to SSID) in the argument tstrNetworkId -> pu8Bssid. The application can instruct the WINC whether to store the credentials or not to store in Flash and also whether the saved credentials must be encrypted or not. This is done by configuring the enum tenuCredStoreOption. For enterprise security, the application can configure WINC to send actual identity or use anonymous identity during phase 1 authentication. This can be done by setting or clearing bUnencryptedUserName in argument tstrAuth1xTls or tstrAuth1xMschap2. For more details on usage of API m2m_wifi_connect_1x_tls, refer ASF (v3.42 or above) example "WINC1500 Connecting a EAP-TLS / PEAPv0 with TLS / PEAPv1 with TLS Secured AP Example". For more details on usage of API m2m_wifi_connect_1x_mschap2, refer ASF (v3.42 or above) example "WINC1500 Connecting a EAP-TTLSv0 with MSCHAPv2 / EAP-PEAPv0 with MSCHAPv2 / EAP-PEAPv1 with MSCHAPv2 Secured AP Example". 5.4 On Demand Wi-Fi Connection The host MCU application may establish a Wi-Fi connection on demand when all the required connection parameters (SSID, security credentials, and so on.) are known to the application. To start a Wi-Fi connection on demand, the application calls the following APIs based on the security type. Table 5-1. List of APIs based on Security Type Security Type API Open m2m_wifi_connect_open WEP m2m_wifi_connect_wep WPA/WPA2 m2m_wifi_connect_psk 802.1x with MSCHAPv2 m2m_wifi_connect_1x_mschap2 802.1x with TLS m2m_wifi_connect_1x_tls Alternatively, the application can call the API m2m_wifi_connect to connect with an access point which supports Open, WEP, WPA/WPA2 and 802.1x with MSCHAPv2. m2m_wifi_connect is deprecated in v19.6.1 and is kept for legacy purpose. Note:  Using the API in the Table 5-1 implies that the host MCU application has prior knowledge of the connection parameters. For instance, connection parameters can be stored on nonvolatile storage attached to the host MCU. The Wi-Fi on demand connection operation is described in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 22 Figure 5-2. On-demand Wi-Fi Connection 5.4.1 Example Code 5.4.1.1 Example Code for Connecting to Enterprise Network (PEAP and TTLSv0) with MSCHAPv2 as Phase2 Authentication #define MAIN_WLAN_SSID "WINC1500_ENTERPRISE" /**< Destination SSID */ #define MAIN_WLAN_802_1X_USR_NAME "DEMO_USER" /**< RADIUS user account name */ #define MAIN_WLAN_802_1X_PWD "DemoPassword" /**< RADIUS user account password */ int main(void) { int8_t ret; tstrWifiInitParam param; tstrNetworkId networkId; tstrAuth1xMschap2 mschapv2_credential; /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /* Initialize Wi-Fi parameters structure. */ memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) { } } ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 23 networkId.pu8Bssid = NULL; networkId.pu8Ssid = (uint8 *)MAIN_WLAN_SSID; networkId.u8SsidLen = strlen(MAIN_WLAN_SSID); networkId.enuChannel = M2M_WIFI_CH_ALL; mschapv2_credential.pu8Domain = NULL; //mschapv2_credential.u16DomainLen = strlen(mschapv2_credential.pu8Domain); mschapv2_credential.pu8UserName = (uint8 *)MAIN_WLAN_802_1X_USR_NAME; mschapv2_credential.pu8Password = (uint8 *)MAIN_WLAN_802_1X_PWD; mschapv2_credential.u16UserNameLen = strlen(MAIN_WLAN_802_1X_USR_NAME); mschapv2_credential.u16PasswordLen = strlen(MAIN_WLAN_802_1X_PWD); mschapv2_credential.bUnencryptedUserName = false; mschapv2_credential.bPrependDomain = true; printf("Connecting to %s\r\n\tUsername:%s\r\n", MAIN_WLAN_SSID, MAIN_WLAN_802_1X_USR_NAME); m2m_wifi_connect_1x_mschap2( WIFI_CRED_SAVE_ENCRYPTED, &networkId, &mschapv2_credential); /* Infinite loop to handle a event from the WINC1500. */ while (1) { while (m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } return 0; } 5.4.1.2 Example Code for Connecting to PEAP Enterprise Network with TLS as Phase2 Authentication and EAP- TLS /** security information for Wi-Fi connection */ #define MAIN_WLAN_SSID "WINC1500_ENTERPRISE" /**< Destination SSID */ #define MAIN_WLAN_802_1X_USR_NAME "DEMO_USER" /**< RADIUS user account name */ const uint8_t modulus[] = { /** private key modulus extracted from key file */ }; const uint8_t exponent[] = { /** private key exponent coefficient extracted from key file */ }; const uint8_t certificate[] = { /** certificate coefficient corresponding to Private Key */ }; int main(void) { int8_t ret; tstrWifiInitParam param; tstrNetworkId networkId; tstrAuth1xTls tls_credential; /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /* Initialize Wi-Fi parameters structure. */ memset((uint8_t *)¶m, 0, sizeof(tstrWifiInitParam)); /* Initialize Wi-Fi driver with data and status callbacks. */ param.pfAppWifiCb = wifi_cb; ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { printf("main: m2m_wifi_init call error!(%d)\r\n", ret); while (1) { } } printf("Username:%s\r\n",MAIN_WLAN_802_1X_USR_NAME); /* Connect to the enterprise network. */ networkId.pu8Bssid = NULL; networkId.pu8Ssid = (uint8 *)MAIN_WLAN_SSID; networkId.u8SsidLen = strlen(MAIN_WLAN_SSID); networkId.enuChannel = M2M_WIFI_CH_ALL; ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 24 tls_credential.pu8Domain = NULL; tls_credential.pu8UserName = (uint8 *)MAIN_WLAN_802_1X_USR_NAME; tls_credential.pu8PrivateKey_Mod = (uint8 *)modulus; tls_credential.pu8PrivateKey_Exp = (uint8 *)exponent; tls_credential.pu8Certificate = (uint8 *)certificate; tls_credential.u16UserNameLen = strlen(MAIN_WLAN_802_1X_USR_NAME); tls_credential.u16PrivateKeyLen = sizeof(modulus); tls_credential.u16CertificateLen = sizeof(certificate); tls_credential.bUnencryptedUserName = true; tls_credential.bPrependDomain = true; printf("Connecting to %s...\r\n\t\tUsername:%s\r \n",networkId.pu8Ssid,tls_credential.pu8UserName); m2m_wifi_connect_1x_tls(WIFI_CRED_SAVE_ENCRYPTED, &networkId, &tls_credential); /* Infinite loop to handle a event from the WINC1500. */ while (1) { while (m2m_wifi_handle_events(NULL) != M2M_SUCCESS) { } } return 0; } 5.5 Default Connection The host MCU application establishes the default connection based on the connection profile stored in the WINC serial Flash using the m2m_wifi_default_connect API. This API does not require AP information to establish the connection. Note:  The connection profile information is automatically stored in the WINC Flash when on-demand WiFi connection API is called (see Table 5-1). Saving of this connection profile is dependent on the enum tenuCredStoreOption. The credentials such as passphrase of the AP or Enterprise certificate and other parameters like SSID, IP address, BSSID are encrypted using AES128-CBC before they are written into the serial Flash. This makes it difficult for an attacker to retrieve the sensitive information even if an attacker has physical access to the device. If there is no cached profile or if a connection cannot be established with any of the cached profile, an event of type M2M_WIFI_RESP_DEFAULT_CONNECT is delivered to the host driver indicating failure. Upon successful default connection, the host application can read the current Wi-Fi connection status by calling m2m_wifi_get_connection_info API. The m2m_wifi_get_connection_info is an asynchronous API. The actual connection information is provided in the asynchronous event M2M_WIFI_RESP_CONN_INFO in Wi-Fi callback. The callback parameter of type tstrM2MConnInfo provides information about AP SSID, RSSI (AP received power level), security type, IP address obtained by DHCP. Note:  A connection profile is cached in the serial Flash if and only if the connection is successfully established with the target AP. The Wi-Fi default connection operation is shown in the following figure. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 25 Figure 5-3. Wi-Fi Default Connection 5.6 Encrypted Credential Storage In ATWINC15x0 firmware v19.6.1 and above, the credentials such as passphrase of the AP or Enterprise certificate and other parameters like SSID, IP address, BSSID are encrypted using AES128-CBC before they are written into the serial Flash. This makes it difficult for an attacker to retrieve the sensitive information inspite of having physical access to the device. The encryption provided by this feature must not be considered secure. The encryption is only intended to prevent credentials being revealed in plain text by an opportunistic read of ATWINC15x0 Flash. Therefore, other security practices must be followed where possible, such as changing passwords regularly and deleting credentials when they are no longer required. When requesting for a connection to a network, the application can specify how the connection credentials must be stored in ATWINC15x0 Flash. The options are as follows: • Do not store credentials • Store credentials unencrypted • Store credentials encrypted The credentials consist of: • SSID • BSSID (if provided) • WEP key (for WEP connection) • Passphrase and PSK (for WPA/WPA2 PSK connection) • Domain, User name and Password (for WPA/WPA2 1x MSCHAPv2 connection) • Domain, User name, Certificate and Private Key (for WPA/WPA2 1x TLS connection) ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 26 The credentials are stored in ATWINC15x0 Flash when connection succeeds, and only one set of credentials is stored at a time; if new credentials need to be stored then the old credentials are removed (overwritten with 0’s). If credentials are stored in ATWINC15x0 Flash, then the application can request subsequent connections without providing the credentials again, using m2m_wifi_default_connect. If roaming is enabled, roaming can take place regardless of whether the credentials are stored in ATWINC15x0 Flash. (They are stored in data memory for the duration of a connection.) The application can delete credentials from ATWINC15x0 Flash using m2m_wifi_delete_sc. Note:  Version 19.6.1 firmware implements a new format for the ATWINC15x0 Flash store for connection parameters. The effects of this are: • During a firmware upgrade to v19.6.1, previously stored credentials are reformatted. After the first successful connection to an access point, these stored credentials are encrypted. • During a firmware upgrade to v19.6.1, previously stored IP address and Wi-Fi channel are deleted. • After a firmware downgrade from v19.6.1 to previous firmware, credentials stored by v19.6.1 firmware are not readable by the previous firmware. The operation of the previous firmware is otherwise unaffected. 5.7 Simple Roaming Simple Roaming is a custom feature which is supported by WINC firmware version 19.6.1 and above. With Simple Roaming feature enabled, the ATWINC1500 configured as station can move around in an ESS area with multiple access point. The WINC automatically switches to another AP which has the same SSID, authentication procedure and credentials with better signal strength. Roaming enables a station to change its AP while remaining connected to the network. The following figure explains the simple roaming feature. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 27 Figure 5-4. Simple Roaming STA AP in Range New AP Old AP (1) Probe Request (Ch 1) (2) Probe Response (Ch 1) (1) Probe Request (Ch n) (2) Probe Response (Ch n) (5) Authentication Request (6) Authentication Reply (7) Reassociation Request (12) Reassociation Reply (8) Send Security Block (9) Ack Security Block (10) Move Notify (11) Move Response In v19.6.1, the WINC roam occurs on link-loss detection with the existing AP, which is determined by tracking beacons and sending NULL frame keep-alive packets. ISO/OSI Layer 2 roaming occurs when the WINC roams from one AP to another AP, both of which are inside the same IP subnet. Layer 3 roaming occurs when the WINC roams from one AP to another AP which are in different subnets, whereby the WINC attempts to obtain a new IP address within the new subnet via DHCP. As a result of layer 3 roaming, any existing network connections is broken, and the upper layer protocols handle this IP address change if a continuous connection is required in layers 4 and above. Roaming algorithm is internal to WINC firmware. The Host MCU can enable or disable the roaming functionality using the API's m2m_wifi_enable_roaming and m2m_wifi_disable_roaming. The roaming must be called after the WINC initialization. When roaming is enabled, if the WINC successfully roamed to a new AP, then the M2M_WIFI_RESP_CON_STATE_CHANGED message with state as M2M_WIFI_ROAMED is sent to host MCU. If the WINC is not able to find a new AP, then M2M_WIFI_RESP_CON_STATE_CHANGED message with state as M2M_WIFI_DISCONNECTED is sent to the host MCU. The API call m2m_wifi_enable_roaming() sets the ATWINC15x0 to detect link-loss, and when link loss is detected with the existing access point, the following roaming steps are performed. • A precautionary de-authentication frame is sent to the old AP. • Scanning is performed to determine if there is an AP within the same ESS as the previous AP in the vicinity. • If an AP is found, authentication and re-association messages are exchanged with the new AP, followed by a normal 4-way security handshake in the case of WPA/WPA2, or an EAPOL exchange in the case of 802.1x Enterprise security. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 28 • A DHCP request is sent to the new AP to attempt to retain the same IP address. A notification event is sent to the host MCU of type M2M_WIFI_RESP_CON_STATE_CHANGE with the state of M2M_WIFI_ROAMED. Additionally, an M2M_WIFI_REQ_DHCP_CONF event conveying either the same or a new IP address is sent to the host MCU. • If there is any problem with the connection, or DHCP fails, then a de-authentication message is sent to the AP, and an M2M_WIFI_RESP_CON_STATE_CHANGED event is sent to the host MCU with the state set as M2M_WIFI_DISCONNECTED. The bEnableDhcp parameter enables control of whether or not a DHCP request is sent after roaming to a new AP. The API call m2m_wifi_disable_roaming is used to disable roaming. 5.8 Multiple Gain Table There are restrictions regarding the maximum transmit power of a wireless device according to the regulatory agencies of the region. For Wi-Fi devices, the maximum transmit power is limited according the regulation of the region in which the Wi-Fi device is used. The gain table can be used to configure the transmission power in WINC. The digital gain (DG) that are used for different channels and different data rates are stored in ATWINC15x0 Flash as a table called Gain table. In ATWINC15x0, the Power Amplifier (PA) and Pre-power Amplifier (PPA) values are configured in the firmware directly. The following figure shows the format of the gain table. Figure 5-5. Gain Table 1 2 3 4 5 6 7 8 9 10 11 12 13 14 1 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 2 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 5.5 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 11 -10 -9 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 6 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 9 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 12 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 18 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 24 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 36 -11 -7 -7 -7 -7 -7 -7 -7 -7 -7 -9 -7 -7 -7 48 -11 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 -8 54 -11 -9 -9 -9 -8 -8 -8 -8 -8 -8 -9 -8 -8 -8 mcs0 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs1 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs2 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs3 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs4 -12 -7 -7 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs5 -12 -8 -8 -7 -7 -7 -7 -7 -7 -7 -10 -7 -7 -7 mcs6 -12 -9 -8 -8 -8 -8 -8 -8 -8 -8 -10 -8 -8 -8 mcs7 -12 -10 -9 -9 -9 -9 -9 -9 -9 -9 -10 -9 -9 -9 1e9c 0 1edc 0 Data Rates Channels Digital Gain Specific Configuration The Gain tables are provided as part of firmware update package in form of .csv file available at src/ firmware/Tools/gain_builder/gain_sheets folder. The gain values are downloaded as part of complete download process. For more details, see "WINC Devices – Integrated Serial Flash Memory Download Procedure" document. Prior to v19.6.1 only one gain table was supported in ATWINC15x0, with which the WINC can only operate in one regulatory region without requiring different Flash content. The ATWINC15x0 firmware version 19.6.1 or above supports multiple gain table and the Flash can store up to four gain tables. The table can be selected by the Host MCU using the API m2m_wifi_set_gain_table_idx. If the ATWINC15x0 has to operate in multiple region with maximum ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 29 transmit power allowed in that region, multiple gain table feature can be used to select gain table (by Host MCU) based on the region in which the ATWINC15x0 is operated. 5.8.1 Writing the Gain Table to ATWINC15x0 The gain builder application uses multiple .csv files (up to a maximum of 4) and perform the necessary maths operations on the gain table to calculate the gain values and write them to the Flash: gain_builder [-table ] [-index ][-no_wait] [-port] Note:  The img_path* parameters specify the separate tables, and the index parameter specifies the default table to use on power up. 5.8.2 Selecting a Specific Gain Table Setting the specific gain table index is achieved using API m2m_wifi_set_gain_table_idx. The m2m_wifi_set_gain_table_idx must be called after the initialization and before any connection request. The corresponding gain tables must be available in the Flash. Note:  The ATWINC15x0 firmware release v19.6.1 contains only one gain table that can be used in all the region. 5.9 Host File Download The Host File Download is a feature supported in the ATWINC15x0 firmware version 19.6.1 and above. This feature is supported only in the ATWINC1510 device which has 8 Mb Flash. The ATWINC1500 only has 4 Mbit of Flash memory and therefore this feature is not supported for the ATWINC1500. With Host file download feature, the Host MCU can instruct the ATWINC1510 to download a file and save it in the ATWINC1510 Flash. The ATWINC1510 can download the file from a HTTP or a HTTPS web server only. The maximum size of file that can be stored in the ATWINC1510 is 508 KB. This feature is ideal for updating the firmware of host MCU. However, the feature is not limited to MCU OTA only. When performing MCU OTA updates, there is no enforced file format, so the Application Developer can choose a strategy to perform integrity check validation on the received file. The WINC does not perform any integrity check on the downloaded file and therefore, it is recommended that the Application do it instead. The feature is designed for single file support and allows for a maximum size of 508 KB. The driver protects against invalid access to the file stored in the WINC’s Flash by using file handlers to identify each file. If a new download starts or if the file is erased, access to the file partition is denied. Also, the application can request an explicit erase to delete the file from the ATWINC’s Flash, destroying any potentially confidential data. The API m2m_ota_host_file_get is used to download file from remote location and store it in ATWINC1500 Flash. The m2m_ota_host_file_get can be used to download only one file at a time. When the get file API is called again, the previously stored file is erased and new file download is initiated. To retrieve the downloaded file from the ATWINC1510 Flash, m2m_ota_host_file_read_spi or m2m_ota_host_file_read_hif API can be used by the host MCU. The completion of file download is notified through the callback registered in m2m_ota_host_file_get API. The user can use the m2m_ota_host_file_read_spi or m2m_ota_host_file_read_hif API by passing required arguments to initiate the file read from the WINC Flash. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 30 5.9.1 Overview Whenever an application needs information which is stored in a file somewhere in a remote location, the application can use the Host File Download feature to retrieve the file from the remote location and temporarily store it in the WINC’s Flash. When a download is successfully completed, a file handler is generated and stored in NVM in the WINC, therefore it is valid even after a WINC reset. After a handler is generated, access to the file is possible via the provided APIs and reading of a file is possible via two mechanisms, HIF and SPI. In either case, the read operation requires the file handler of the file which the application is trying to access, if the handler being requested and the handler internally stored match, then the access is granted. The same procedure is valid for erasing the file. The use of a file handler avoids access to invalid data, for example when trying to concurrently access the file. The following figure depicts the steps which the WINC follows when performing a Host File Download. Figure 5-6. Host File Download Operation within the WINC OTA File Get Check Available Space Start Download OTA Get Successful OTA Get Failed Notify Host of the Result OK Failed Completed Failed The download starts only if the space available in Flash is enough to store the file which is requested to be downloaded. If Host File Download is requested in the ATWINC1500 (4 Mb Flash), the download fails since there is no Host File partition in Flash and therefore no space to store the file. The “Start Download” step causes any previously available valid file handler to be invalidated. When “OTA Get Successful” message is received, a new file handler is generated along with the status and the total size of the downloaded file, they are included in the Download completion notification sent to the host. 5.9.2 OTA Initialization To use the Host File Download feature, the WINC and the OTA driver must be initialized. The following is the procedure for OTA initialization: 1. m2m_wifi_init or m2m_wifi_reinit – this API is required to initialize the WINC and to set up the callback for the HIF communication. After this step, the WINC can be configured to connect to a network and download a file. For more details to understand when to use each of these two options, see the API documentation. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 31 2. m2m_ota_init – this API registers the OTA callback, which is required to execute any callbacks configured through the Host File Download APIs and to notify the Application of file download status. 5.9.3 Using Host File Download for MCU OTA Host File Download allows an application to download a file from a remote location. The link to the file can be through a secure connection and once the file is downloaded, it is stored in the WINC's Flash and the Application is notified about it. The files to download can be of any kind and are not limited to MCU binaries, making this feature both flexible and powerful. One example would be the download of text files, which can hold, for instance, a file checksum, which can later be used by the Application to verify the integrity of the downloaded binary. An Host MCU OTA requires the following steps: • Provide an http/https link to the file to tell WINC to download the file from a specific remote location, which can be done using API m2m_ota_host_file_get. • Read the image from the WINC using spi_flash_read. Since there is a limitation currently in which the bootloader would also need to perform m2m_wifi_init, m2m_ota_init and only then it should do m2m_ota_host_file_read_spi to read the image from WINC. m2m_ota_host_file_read_hif and m2m_ota_host_file_read_spi are not used in the ASF Example for MCU OTA to keep the driver footprint small while working around the limitation described above. However, this limitation is only present when the Application needs to be reset, or in this case switch to a bootloader, the WINC driver will lose track of the file handler and will have to load it again through the initialization process. If no reset or shutdown need to be performed and if no different Application needs to be loaded after downloading the file, these two APIs can be used. Figure 5-7. Example Host File Download for MCU OTA File Get CB Application WINC Bootloader WINC File Integrity Check Switch to Bootloader Switch to Application File Handler inval File Handler gen MCU & WINC Reset m2m_wifi_init() m2m_ota_init() **Connect to Wi-Fi network** m2m_ota_host_file_get() HIF Msg M2M_OTA_RESP_HOST_FILE_DOWNLOAD m2m_wifi_download_mode() spi_flash_read() ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 32 Other steps that must be considered by the Application Developer are: • It is recommended to verify the integrity of the image using a checksum calculation and match it against a previously known checksum. The user can design the validation mechanism since no predefined file format is enforced for MCU OTA. • There is an option to erase the file from Flash. Although this is not mandatory before requesting a new download, it can be useful for security purposes, ensuring that sensitive data is unavailable after its use. Note:  The WINC does not perform any integrity check of any of the downloaded files via Host File Download and that must be checked by the application. 5.9.4 API Description For a more detailed description of the APIs, refer to WINC1500_SW_API.chm. 5.9.4.1 OTA File Get NMI_API sint8 m2m_ota_host_file_get ( unsigned char *pcDownloadUrl, tpfFileGetCb pfHFDGetCb ); This API is used to get a file which links to the file stored remotely. The link is passed to the WINC to establish a TCP connection to retrieve the file from that location. It is also possible to use a server configured for TLS. A callback must also be provided so that it is executed when the File Get operation completes. The status of the File Get is passed onto this callback and if the status is successful, the file handler generated by the WINC and the total size of the downloaded file is passed correctly to the callback. 5.9.4.2 File Get Callback typedef void (*tpfFileGetCb) ( uint8 u8Status, uint8 u8Handler, uint32 u32Size ); The callback for the File Get receives three arguments; status of the File Get request, file handler ID and the total size of the file. If the status is OTA_STATUS_SUCCESS, then the file handler and size can be used, otherwise its values are not populated. From the Application’s point of view, they must not be considered valid. The file handler is auto-generated in the WINC and it identifies the file. Only when a download finishes successfully, the corresponding file handler is generated. The handler is required to both read from the file or erase the file. Similarly, if the download is aborted or interrupted, then the handler is not generated, instead the handler will have the value of HFD_INVALID_HANDLER, which blocks any further operation on the Flash through the APIs. When the file download completes successfully, the total size of the download file is passed to the callback to notify the application. Using which the application tracks the total size of the downloaded data and the amount of data read. 5.9.4.3 OTA File Read HIF NMI_API sint8 m2m_ota_host_file_read_hif ( uint8 u8Handler, uint32 u32Offset, uint32 u32Size, ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 33 tpfFileReadCb pfHFDReadCb ); When the download completes, the file is stored in the WINC’s Flash. This API can be used to read the file from the WINC using HIF messages. It is mandatory to have a valid handler, not having one could mean that the file has been invalidated and therefore it must be unavailable for any operation. This protects read against invalid or corrupted data. The offset marks the position in bytes of Flash to read from, counting from the beginning of the file. Therefore, an offset of zero is translated as reading from the beginning of the file. Size specifies the amount of bytes to read, starting at the offset defined. The last argument is the callback to be executed when the read is complete. Advantages (vs SPI read) • While reading a file using HIF messages, the host can continue operation, being notified by an interrupt from the WINC when data read is complete. • Does not require the WINC to be reset after the read is complete. Disadvantages (vs SPI read) • File reads via HIF are slightly slower than reads via SPI. 5.9.4.4 File Read HIF Callback typedef void (*tpfFileReadCb) ( uint8 u8Status, void *pBuff, uint32 u32Size ); The callback is only executed after a file read via HIF messages and it receives three arguments. • The first argument is the status of the read, if the read is unsuccessful, then the other arguments will have irrelevant values. • The second argument is a pointer to the buffer of data read. • The third argument is size, which indicates the amount of data read and therefore contained in the buffer (maximum 128 bytes). Specifying large amounts of data to be read via the HIF may exceed the buffer maximum size (128 bytes), therefore it is recommended to use u32Size to offset a second read from within this callback. This requires the application to track the total size of the file and the amount of bytes read, requesting the reading of each section at a time until the end of the file is reached. 5.9.4.5 OTA File Read SPI NMI_API sint8 m2m_ota_host_file_read_spi ( uint8 u8Handler, uint8 *pu8Buff, uint32 u32Offset, uint32 u32Size ); The file read via SPI is similar to the read via HIF. The use of a callback is not considered, because to access the WINC’s Flash via SPI, the WINC must be set into a certain mode to allow for safe read/write of its Flash. Therefore, it is typical to use a loop to read all the data necessary while the WINC is in that state and then restart the WINC. To use this API, the application must call m2m_wifi_download_mode to make the WINC safe for read/ write Flash access and once the read is completed, the WINC must be reinitialized (m2m_wifi_reinit, ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 34 m2m_ota_init) and to connect to the network again if the Application based on the request. pu8Buff is a pointer to a buffer provided by the Application and to where the data will be read to. Advantages (vs HIF read) • SPI read is faster than HIF Read. Disadvantages (vs HIF read) • Requires the WINC to set into a special mode and restart later. • Generally blocks as the read are done within a loop to minimize WINC reset. 5.9.4.6 OTA File Erase API NMI_API sint8 m2m_ota_host_file_erase ( uint8 u8Handler, tpfFileEraseCb pfHFDEraseCb ); The File Erase API requires the following two arguments: • The first argument is a handler of the file to erase, to ensure that it is valid to perform a Flash erase. • The second argument is a callback which executes when the erase is complete. Having a callback to tell the Application when the erase has been completed is useful to act as a trigger for a subsequent operation (example, download a second file). Note:  The file erase performs an erase of the entire host file partition and any file handler is destroyed regardless of the end result of the erase operation in the WINC. Since the data in the Flash is partially or completely destroyed, the handlers are invalidated when the process starts for safety. 5.9.4.7 File Erase Callback typedef void (*tpfFileEraseCb) ( uint8 u8Status ); The callback for a File Erase receives the erase status of the operation. A status of OTA_STATUS_SUCCESS ensures that the data has been completely erased, any other result does not ensure that the data is still valid, but also do not ensure that the data has been completely erased. 5.9.4.8 OTA Abort API NMI_API sint8 m2m_ota_abort ( void ); If a Host File Download has been started and the Application decides to cancel the download, it can issue a call to this API to do so. This does not require any input parameter. Note:  This API is shared with the WINC OTA and if issued when a WINC OTA is in progress, the WINC OTA is canceled. 5.9.5 Limitations • Out of 512 KB of Flash in the ATWINC1510, the first sector (of size 4 KB) is used by the WINC for storing the file information for host file download feature. Which means that a total of 508 KB size of Flash can be used by application to store the host file. • The feature is only supported in ATWINC1510 since the ATWINC1500 only has 4 Mbit of Flash memory, which means there is no space to store a file. ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 35 • There is no file system and only one file is stored at a time. When the get file is called again, the previously stored file is erased and a new file download is initiated. • The WINC OTA firmware download and the Host OTA file download cannot run concurrently. • The WINC interprets 404 Not Found error when application attempts to download a broken or dead link and provides the OTA_STATUS_SERVER_ERROR error status. The WINC does not interpret any other message for broken link. The WINC downloads the error message into SPI Flash and indicates Host as file download. It is the application’s responsibility to check if the file is valid. 5.9.6 Built in Automated Test Equipment (ATE) Mechanism A factory flashed ATWINC15x0 module running the v19.6.1 firmware has a special ATE firmware in the Flash space reserved for OTA transfers (which is overwritten by the first OTA update). A host API can be called during WINC initialization that causes the device to boot into this special firmware (m2m_ate_init). The API to control the ATE functions provided by this firmware is detailed in \ASF\common\components\wifi\winc1500\driver\include\m2m_ate_mode.h. The following is the sample code. int main(void) { /* Initialize the board. */ system_init(); /* Initialize the UART console. */ configure_console(); printf(STRING_HEADER); /* Initialize the BSP. */ nm_bsp_init(); /*Check if initialization of ATE firmware is succeeded or not*/ if(M2M_SUCCESS == m2m_ate_init()) { /*Run TX test case if defined*/ #if (M2M_ATE_RUN_TX_TEST_CASE == ENABLE) start_tx_test(M2M_ATE_TX_RATE_1_Mbps_INDEX); #endif /*Run RX test case if defined*/ #if (M2M_ATE_RUN_RX_TEST_CASE == ENABLE) start_rx_test(); #endif /*De-Initialization of ATE firmware test mode*/ m2m_ate_deinit(); } else { M2M_ERR("Failed to initialize ATE firmware.\r\n"); while(1); } #if ((M2M_ATE_RUN_RX_TEST_CASE == ENABLE) && (M2M_ATE_RUN_TX_TEST_CASE == ENABLE)) M2M_INFO("Test cases have been finished.\r\n"); #else M2M_INFO("Test case has been finished.\r\n"); #endif while(1); } #if (M2M_ATE_RUN_TX_TEST_CASE == ENABLE) static void start_tx_test(uint8_t tx_rate) { tstrM2mAteTx tx_struct; ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 36 /*Initialize parameter structure*/ m2m_memset((uint8 *)&tx_struct, 0 , sizeof(tx_struct)); /*Set TX Configuration parameters, *refer to tstrM2mAteTx for more information about parameters*/ tx_struct.channel_num = M2M_ATE_CHANNEL_11; tx_struct.data_rate = m2m_ate_get_tx_rate(tx_rate); tx_struct.dpd_ctrl = M2M_ATE_TX_DPD_DYNAMIC; tx_struct.duty_cycle = M2M_ATE_TX_DUTY_1; tx_struct.frame_len = 1024; tx_struct.num_frames = 0; tx_struct.phy_burst_tx = M2M_ATE_TX_SRC_MAC; tx_struct.tx_gain_sel = M2M_ATE_TX_GAIN_DYNAMIC; tx_struct.use_pmu = M2M_ATE_PMU_DISBLE; tx_struct.cw_tx = M2M_ATE_TX_MODE_CW; tx_struct.xo_offset_x1000 = 0; /*Start TX Case*/ if(M2M_ATE_SUCCESS == m2m_ate_start_tx(&tx_struct)) { uint32 u32TxTimeout = M2M_ATE_TEST_DURATION_IN_SEC; M2M_INFO(">>Running TX Test case on CH<%02u>.\r\n", tx_struct.channel_num); do { nm_bsp_sleep(1000); printf("%02u\r", (unsigned int)u32TxTimeout); }while(--u32TxTimeout); if(M2M_ATE_SUCCESS == m2m_ate_stop_tx()) { M2M_INFO("Completed TX Test successfully.\r\n"); } } else { M2M_INFO("Failed to start TX Test case.\r\n"); } } #endif #if (M2M_ATE_RUN_RX_TEST_CASE == ENABLE) static void start_rx_test(void) { tstrM2mAteRx rx_struct; /*Initialize parameter structure*/ m2m_memset((uint8 *)&rx_struct, 0, sizeof(rx_struct)); /*Set RX Configuration parameters*/ rx_struct.channel_num = M2M_ATE_CHANNEL_6; rx_struct.use_pmu = M2M_ATE_PMU_DISBLE; rx_struct.xo_offset_x1000 = 0; /*Start RX Case*/ if(M2M_ATE_SUCCESS == m2m_ate_start_rx(&rx_struct)) { tstrM2mAteRxStatus rx_data; uint32 u32RxTimeout = M2M_ATE_TEST_DURATION_IN_SEC; M2M_INFO(">>Running RX Test case on CH<%02u>.\r\n", rx_struct.channel_num); do { m2m_ate_read_rx_status(&rx_data); M2M_INFO("Num Rx PKTs: %d, Num ERR PKTs: %d, PER: %1.3f", (int)rx_data.num_rx_pkts, (int)rx_data.num_err_pkts, (rx_data.num_rx_pkts>0)?((double)rx_data.num_err_pkts/ (double)rx_data.num_rx_pkts):(0)); nm_bsp_sleep(1000); }while(--u32RxTimeout); printf("\r\n"); if(M2M_ATE_SUCCESS == m2m_ate_stop_rx()) { M2M_INFO("Compeleted RX Test successfully.\r\n"); } } ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 37 else { M2M_INFO("Failed to start RX Test case.\r\n"); } } #endif ATWINC15x0 Wi-Fi Station Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 38 6. Socket Programming 6.1 Overview The ATWINC15x0 socket Application Programming Interface (API) allows the host MCU application to interact with intranet and remote internet hosts. The ATWINC15x0 socket API is based on the BSD (Berkeley) sockets. This chapter explains the ATWINC15x0 socket programming and how it differs from regular BSD sockets. Note:  The reader must have a basic understanding of the following topics before reading this chapter: • BSD sockets • TCP • UDP • Internet protocols 6.1.1 Socket Types The ATWINC15x0 socket API provides two types of sockets: • Datagram sockets (connectionless sockets) – uses the UDP protocol • Stream sockets (connection-oriented sockets) – uses the TCP protocol 6.1.2 Socket Properties Each ATWINC15x0 socket is identified by a unique combination of the following: • Socket ID – a unique identifier for each socket. This is the return value of the socket API. • Local socket address – a combination of the ATWINC15x0 IP address and port number assigned by the ATWINC15x0 firmware for the socket. • Protocol – transport layer protocol, either TCP or UDP. • Remote socket address – applicable only for TCP stream sockets. This is necessary since TCP is connection oriented. Each connection made to a specific IP address and port number requires a separate socket. The remote socket address can be obtained in the socket event callback which is described in the succeeding section. Note:  TCP port 53 and UDP port 53 represent two different sockets. 6.1.3 Limitations • The ATWINC15x0 sockets API support up to 7 TCP sockets and 4 UDP sockets. • The ATWINC15x0 sockets API support only IPv4. It does not support IPv6. 6.2 Sockets API 6.2.1 API Prerequisites • C header file socket.h – this includes all the necessary socket API function declarations. When using any ATWINC15x0 socket API as described in the following sections, the host MCU application must include the socket.h header file. • Initialization – the ATWINC15x0 socket API initializes once before calling any socket API function. This is done using the socketInit API described in Socket API Functions. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 39 6.2.2 Non-blocking Asynchronous Socket APIs Most ATWINC15x0 socket APIs are asynchronous function calls that do not block the host MCU application. The behavior of the ATWINC15x0 asynchronous APIs are described in Asynchronous Events. For example, the host MCU application can register an application-defined socket event callback function using the ATWINC15x0 socket API registerSocketCallback. When the host MCU application calls the socket API connect, the API returns a zero value (SUCCESS) immediately indicating that the request is accepted. The host MCU application must then wait for the ATWINC15x0 socket API to call the registered socket callback when the connection is established or if a connection time-out occurred. The socket callback function provides the necessary information to determine the connection status. 6.2.3 Socket API Functions The ATWINC15x0 socket API provides the following functions. 6.2.3.1 socketInit The host MCU application must call the API socketInit once during initialization. The API is a synchronous API. 6.2.3.2 registerSocketCallback The registerSocketCallback function allows the host MCU application to provide the ATWINC15x0 sockets with application-defined event callbacks for socket operations. The API is a synchronous API. The API registers the following callbacks: • The socket event callback • The DNS resolve callback The socket event callback is an application-defined function that is called by the ATWINC15x0 socket API whenever a socket event occurs. Within this handler, the host MCU application must provide an application-defined logic that handles the events of interest. The DNS resolve event handler is the application-defined function that is called by the ATWINC15x0 socket API to return the results of gethostbyname. By implication, this only occurs after the host MCU application has called the gethostbyname function. If successful, the callback provides the IP address for the desired domain name. 6.2.3.3 socket The socket function creates a new socket of a specified type and returns the corresponding socket ID. The API is a synchronous API. The socket ID is required by most other socket functions and is also passed as an argument to the socket event callback function to identify which socket generated the event. 6.2.3.4 connect The connect function is used with TCP sockets to establish a new connection to a TCP server. The connect function results in a SOCKET_MSG_CONNECT sent to the socket event handler callback upon completion. The connect event is sent when the TCP server accepts the connection or, if no remote host response is received, after a time-out interval of approximately 30 seconds. Note:  The SOCKET_MSG_CONNECT event callback provides a tstrSocketConnectMsg containing an error code. The error code value indicates: • Zero value to indicate the successful connection or ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 40 • Negative value to indicate an error due to a time-out condition or if connect is used with UDP socket. The following figure shows the ATWINC15x0 socket API connect to remote server host. Figure 6-1. TCP Client API Call Sequence 6.2.3.5 bind The bind function can be used for server operation for both UDP and TCP sockets. It is used to associate a socket with an address structure (port number and IP address). The bind function call results to a SOCKET_MSG_BIND event sent to the socket callback handler with the bind status. Calls to listen, send, sendto, recv, and recvfrom functions must not be issued until the bind callback is received. 6.2.3.6 listen The listen function is used for server operations with TCP stream sockets. After calling the listen API, the socket accepts a connection request from a remote host. The listen function causes a SOCKET_MSG_LISTEN event notification to be sent to the host after the socket port is ready to indicate listen operation success or failure. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 41 When a remote peer establishes a connection, a SOCKET_MSG_ACCEPT event notification is sent to the application. 6.2.3.7 accept The accept function is deprecated and calling this API has no effect. It is kept only for backward compatibility. Note:  The listen API implicitly accepts the TCP remote peer connections request. Figure 6-2. TCP Server API Call Sequence Although the accept function is deprecated, the SOCKET_MSG_ACCEPT event occurs whenever a remote host connects to the ATWINC15x0 TCP server. The event message contains the IP address and port number of the connected remote host. 6.2.3.8 send The send function is used by the application to send data to a remote host. The send function can be used to send either UDP or TCP data depending on the type of socket. • For a TCP socket a connection must be established first. • For a UDP socket, the recommended way is to use sendto API, where the destination address is defined. However, it is possible to use send API instead of sendto API. For this, at least one successful call must be made to sendto API prior to the consecutive calls of send function. This ensures that the destination address is saved in the ATWINC15x0 firmware. The send function generates a SOCKET_MSG_SEND event callback after the data is transmitted to the remote host. For TCP sockets, this event guarantees that the data is delivered to the remote host TCP/IP stack (the remote application must use the recv function to read the data). For UDP sockets, it means that the data is transmitted, but there is no guarantee that the data is delivered to the remote host as per UDP protocol. The application is responsible to guarantee data delivery in the UDP sockets case. The SOCKET_MSG_SEND event callback returns the size of the data transmitted of the transmission in the success case and zero or negative value in case of an error. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 42 6.2.3.9 sendto The sendto function is used by the application to send UDP data to a remote host. It can only be used with UDP sockets. The IP address and port of the destination remote host is included as a parameter to the sendto function. The SOCKET_MSG_SENDTO event callback returns the size of the data transmitted in the success case and zero or negative value in case of an error. 6.2.3.10 recv/recvfrom The recv and recvfrom functions are used to read data from TCP and UDP sockets, respectively, and their operation is otherwise identical. The host MCU application calls the recv or recvfrom function with a pre allocated buffer. When the SOCKET_MSG_RECV or SOCKET_MSG_RECVFROM event callback arrives, this buffer must have the received data. The received data size indicates the status as follows: • Positive – data is received • Zero – socket connection is terminated • Negative – indicates an error In the case of TCP sockets, it is recommended to call the recv function after each successful socket connection (client or server). Otherwise, the received data is buffered in the ATWINC15x0 firmware wasting the system's resources until the socket is explicitly closed using a close function call. 6.2.3.11 close The close function is used to release the resources allocated to the socket and, for a TCP stream socket, also terminate an open connection. Each call to the socket function must match with a call to the close function. In addition, sockets that are accepted on a server socket port must be closed using this function. 6.2.3.12 setsockopt The setsockopt function may be used to set socket options to control the socket behavior. The options supported are as follows: • SO_SET_UDP_SEND_CALLBACK – enables or disables the send /sendto event callbacks. The user may want to disable the sendto event callback for UDP sockets to enhance the socket connection throughput. • IP_ADD_MEMBERSHIP – enables subscribe to an IP Multicast address. • IP_DROP_MEMBERSHIP – enables unsubscribe to an IP Multicast address. • SOL_SSL_SOCKET – sets SSL Socket. The following are the options supported for SSL socket: – SO_SSL_BYPASS_X509_VERIF command allows opening of the SSL socket to bypass the X509 certification verification process. Example: struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 43 SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* Enable X509 bypass verification */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_BYPASS_X509_VERIF,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof(struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } – SO_SSL_SNI command sets the Server Name Indicator (SNI). During TLS handshake process, client can indicate which hostname it is trying to connect by setting Server Name in (extended) client hello. SNI allows a server to present multiple certificates on the same IP address and TCP port number and hence allows multiple secure websites to be served by the same IP address without requiring all of the websites to use the same certificate. – SO_SSL_ENABLE_SNI_VALIDATION enables SNI validation functionality in case SNI is set. The server name validation is disabled by default. To enable server name validation, both SO_SSL_SNI and SO_SSL_ENABLE_SNI_VALIDATION must be set by the application through setsockopt() as shown in the example code snippet. When the SNI validation is enabled, the SNI is compared with the common name (CN) in the received server certificate. If the supplied SNI does not match the CN, the SSL connection will be forcibly closed by the ATWINC15x0 firmware. Example: #define MAIN_HOST_NAME "www.google.com" struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* set SNI on SSL Socket */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_SNI, MAIN_HOST_NAME,sizeof(MAIN_HOST_NAME)); /* Enable SSL SNI validation */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET, SO_SSL_ENABLE_SNI_VALIDATION,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof( ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 44 struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } – SO_SSL_ENABLE_SESSION_CACHING command allows the TLS to cache the session information to speed up the future TLS session establishment. Example: struct sockaddr_in addr_in; int optVal =1; addr_in.sin_family = AF_INET; addr_in.sin_port = _htons(MAIN_HOST_PORT); addr_in.sin_addr.s_addr = gu32HostIp; /* Create secure socket */ if (tcp_client_socket < 0) { tcp_client_socket = socket(AF_INET, SOCK_STREAM, SOCKET_FLAGS_SSL); } /* Check if socket was created successfully */ if (tcp_client_socket == -1) { printf("socket error.\r\n"); close(tcp_client_socket); return -1; } /* Enable SSL Session cache */ setsockopt(tcp_client_socket, SOL_SSL_SOCKET,SO_SSL_ENABLE_SESSION_CACHING,&optVal,sizeof(optVal)); /* If success, connect to socket */ if (connect(tcp_client_socket, (struct sockaddr *)&addr_in, sizeof(struct sockaddr_in)) != SOCK_ERR_NO_ERROR) { printf("connect error.\r\n"); return SOCK_ERR_INVALID; } WARNING SO_SSL_BYPASS_X509_VERIF is only provided for debugging and testing purposes. It is NOT recommended to use this socket option in production software applications. 6.2.3.13 gethostbyname The gethostbyname function is used to resolve a host name (for example, URL) to a host IP address via the Domain Name System (DNS). This is limited only to IPv4 addresses. The operation depends on the configuration of a DNS server IP address and access to the DNS hierarchy through the internet. After gethostbyname is called, a callback to the DNS resolver handler is made. If the IP address is determined, a positive value is returned. If it cannot be determined or if the DNS server is not accessible (30-second time-out), an IP address value of zero is indicated. Note:  An IP returns a zero value to indicate an error (for example, the internet connection is down or DNS is unavailable) and the host MCU application may try the function call gethostbyname again later. 6.2.4 Summary The following table summarizes the ATWINC15x0 socket API and shows its compatibility with BSD socket APIs. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 45 Table 6-1. ATWINC15x0 Socket API Summary BSD API ATWINC15x0 API ATWINC15x0 API Type Server/ Client TCP/UD P Brief socket socket Synchronous Both Both Creates a new socket. connect connect Asynchronous Client TCP Initializes a TCP connection request to a remote server. bind bind Asynchronous Server Both Binds a socket to an address (address/port). listen listen Asynchronous Server TCP Allows a bound socket to listen to remote connections for its local port. accept accept Deprecated, Implicit accept in listen. send send Asynchronous Both Both Sends packet. sendto sendto Asynchronous Both UDP Sends packet over UDP sockets. write - Not supported recv recv Asynchronous Both Both Receives packet. recvfrom recvfrom Asynchronous Both Both Receives packet. read - Not supported close close Synchronous Both Both Terminates the TCP connection and release system resources. gethostbyname gethostbyname Asynchronous Both Both Gets the IP address of a certain host name gethostbyaddr - Not supported select - Not supported poll - Not supported setsockopt setsockopt Synchronous Both Both Sets socket option. getsockopt Not supported htons/ntohs _htons/_ntohs Synchronous Both Both Converts 2 byte integer from the host representation to the Network byte order representation (and vice versa). ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 46 ...........continued BSD API ATWINC15x0 API ATWINC15x0 API Type Server/ Client TCP/UD P Brief htonl/ntohl21 _htonl/_ntohl Synchronous Both Both Converts 4 byte integer from the host representation to the Network byte order representation (and vice versa). 6.3 Socket Connection Flow In the following sub-sections, the TCP and UDP (client and server) operations are described in details. Figure 6-3. Typical Socket Connection Flow ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 47 6.3.1 TCP Client Operation The following figure shows the flow for transferring data with a TCP client. Figure 6-4. TCP Client Sequence Diagram Note:  1. The host application must register a socket notification callback function. The function must be of tpfAppSocketCb type and must handle socket event notifications appropriately. 2. If the client knows the IP of the server, it may call connect directly as shown in the figure above. If only the server URL is known, then the application must resolve the server URL first calling the gethostbyname API. ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 48 6.3.2 TCP Server Operation Figure 6-5. TCP Server Sequence Diagram Note:  The host application must register a socket notification callback function. The function must be of type tpfAppSocketCb and must handle socket event notifications appropriately. 6.3.3 UDP Client Operation The following figure shows the flow for transferring data with a UDP client. Figure 6-6. UDP Client Sequence Diagram ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 49 Note:  1. The first send message must be performed with the sendto API with the destination address specified. 2. If further messages are sent to the same address, the send API can also be used. For more details, refer to send. 3. recv can be used instead of recvfrom. 6.3.4 UDP Server Operation The following figure shows the flow for transferring data after establishing a UDP server. Figure 6-7. UDP Server Sequence Diagram 6.3.5 DNS Host Name Resolution The following figure shows the flow of DNS host name resolution. Figure 6-8. DNS Resolution Sequence ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 50 Note:  1. The host application requests to resolve hostname (for example, http://www.foobar.com), by calling the function gethostbyname. 2. Before calling the gethostbyname, the application must register a DNS response callback function using the function registerSocketCallback. 3. After the ATWINC15x0 DNS_Resolver module obtains the IP Address (hostIP) corresponding to the given HostName, the dnsResolveCB is called with the hostIP. 4. If an error occurs or if the DNS request encounters a time-out, the dnsResolveCB is called with IP Address value zero indicating a failure to resolve the domain name. 6.4 Example Code This section provides code examples for different socket applications. For additional socket code examples, refer to the Wi-Fi Network Controller Software Programming Guide. 6.4.1 TCP Client Example Code SOCKET clientSocketHdl; uint8 rxBuffer[256]; /* Socket event handler. */ void tcpClientSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(sock == clientSocketHdl) { if(u8Msg == SOCKET_MSG_CONNECT) { // Connect Event Handler. tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; if(pstrConnect->s8Error == 0) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // send data send(clientSocketHdl, acSendBuffer, u16MsgSize, 0); // Recv response from server. recv(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("TCP Connection Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message. // Close the socket. close(clientSocketHdl); } } } } // This is the DNS callback. The response of gethostbyname is here. void dnsResolveCallback(uint8* pu8HostName, uint32 u32ServerIP) { struct sockaddr_in strAddr; ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 51 if(u32ServerIP != 0) { clientSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(clientSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(443); strAddr.sin_addr.s_addr = u32ServerIP; connect(clientSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } else { printf("DNS Resolution Failed\n"); } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void tcpConnect(char *pcServerURL) { // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(tcpClientSocketEventHandler, dnsResolveCallback); // Resolve Server URL. gethostbyname((uint8*)pcServerURL); } 6.4.2 TCP Server Example Code SOCKET listenSocketHdl, acceptedSocketHdl; uint8 rxBuffer[256]; uint8 bIsfinished = 0; /* Socket event handler. */ void tcpServerSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(u8Msg == SOCKET_MSG_BIND) { tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; if(pstrBind->status == 0) { listen(listenSocketHdl, 0); } else { printf("Bind Failed\n"); } } else if(u8Msg == SOCKET_MSG_LISTEN) { tstrSocketListenMsg *pstrListen = (tstrSocketListenMsg*)pvMsg; if(pstrListen->status != 0) { printf("listen Failed\n"); } } else if(u8Msg == SOCKET_MSG_ACCEPT) { // New Socket is accepted. tstrSocketAcceptMsg *pstrAccept = (tstrSocketAcceptMsg *)pvMsg; if(pstrAccept->sock >= 0) { // Get the accepted socket. acceptedSocketHdl = pstrAccept->sock; recv(acceptedSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 52 { printf("Accept Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message // Perform data exchange uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // Send some data. send(acceptedSocketHdl, acSendBuffer, u16MsgSize, 0); // Recv response from client. recv(acceptedSocketHdl, rxBuffer, sizeof(rxBuffer), 0); // Close the socket when finished. if(bIsfinished) { close(acceptedSocketHdl); close(listenSocketHdl); } } } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void tcpStartServer(uint16 u16ServerPort) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(tcpServerSocketEventHandler, NULL); // Create the server listen socket. listenSocketHdl = socket(AF_INET, SOCK_STREAM, 0); if(listenSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(u16ServerPort); strAddr.sin_addr.s_addr = 0; //INADDR_ANY bind(listenSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } 6.4.3 UDP Client Example Code SOCKET clientSocketHdl; uint8 rxBuffer[256], acSendBuffer[256]; /* Socket event handler */ void udpClientSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if((u8Msg == SOCKET_MSG_RECV) || (u8Msg == SOCKET_MSG_RECVFROM)) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { uint16 len; // Format a message in the acSendBuffer and put its length in len sendto(clientSocketHdl, acSendBuffer, len, 0, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); recvfrom(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 53 // Close the socket after finished close(clientSocketHdl); } } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main.*/ void udpClientStart(char *pcServerIP) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(udpClientSocketEventHandler, NULL); clientSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(clientSocketHdl >= 0) { uint16 len; strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(1234); strAddr.sin_addr.s_addr = nmi_inet_addr(pcServerIP); // Format some message in the acSendBuffer and put its length in len sendto(clientSocketHdl, acSendBuffer, len, 0, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); recvfrom(clientSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } } 6.4.4 UDP Server Example Code SOCKET serverSocketHdl; uint8 rxBuffer[256]; /* Socket event handler.*/ void udpServerSocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(u8Msg == SOCKET_MSG_BIND) { tstrSocketBindMsg *pstrBind = (tstrSocketBindMsg*)pvMsg; if(pstrBind->status == 0) { // call Recv recvfrom(serverSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("Bind Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data // Send some data to the same address. sendto(acceptedSocketHdl, acSendBuffer, u16MsgSize, 0, pstrRecvMsg-> strRemoteAddr, sizeof(pstrRecvMsg-> strRemoteAddr)); // call Recv recvfrom(serverSocketHdl, rxBuffer, sizeof(rxBuffer), 0); // Close the socket when finished. close(serverSocketHdl); } ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 54 } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main. */ void udpStartServer(uint16 u16ServerPort) { struct sockaddr_in strAddr; // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(udpServerSocketEventHandler, NULL); // Create the server listen socket. listenSocketHdl = socket(AF_INET, SOCK_DGRAM, 0); if(listenSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(u16ServerPort); strAddr.sin_addr.s_addr = 0; //INADDR_ANY bind(serverSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } ATWINC15x0 Socket Programming © 2018 Microchip Technology Inc. User Guide DS00002389B-page 55 7. Transport Layer Security (TLS) Transport Layer Security (TLS) layer sits on top of TCP and provides security services including privacy, authenticity, and message integrity. Various security methods are available with TLS in the WINC firmware. 7.1 TLS Overview The ATWINC15x0 features an embedded low-memory footprint TLS protocol stack bundled within the WINC firmware. It features the following functionality: • Supports TLS versions TLS1.0, TLS1.1 and TLS1.2. • Supports TLS client operation with TLS client authentication. • Supports TLS Server mode. • A simple application interface to the TLS stack. The TLS functionality is abstracted by the ATWINC15x0 socket interface, hiding the implementation complexity from the application developer and minimizing the effort to port existing plain TCP code to TLS. 7.2 TLS Connection Establishment From the application’s point of view, the TLS functionality is wrapped behind the socket APIs. This hides the complexity of TLS from the application which can use the TLS in the same way as the TCP (non-TLS) client and server. The main difference between the TLS sockets and the regular TCP sockets is that the application sets the SOCKET_FLAGS_SSL while creating the TLS client and server listening sockets. The detailed sequence of TLS connection establishment is described in the following figure. Note:  • For proper TLS Client operation, ensure that both SOCKET_FLAGS_SSL flag and the correct port number is set in the TLS client application. For instance, an HTTP client application uses no flag when calling socket API function and connect to port 80. The same application source code becomes an HTTPS client application if you use the flag SOCKET_FLAGS_SSL and change the port number in connect API to port 433. • For proper TLS server operation, ensure that both SOCKET_FLAGS_SSL flag and the correct port number is set in the TLS server application. For instance, an HTTP server application uses no flag when calling socket API function and bind to port 80. The same application source code becomes an HTTPS server application, if you use the flag SOCKET_FLAGS_SSL and change the port number in bind API to port 443. ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 56 Figure 7-1. TLS Client Application Connection Establishment ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 57 Figure 7-2. TLS Server Application Connection Establishment 7.3 Server Certificate Installation 7.3.1 Technical Background 7.3.1.1 Public Key Infrastructure The TLS security is based on the Public Key Infrastructure PKI, in which: • A server has its public key stored in a digital certificate with X.509 standard format. • The server must have its X.509 certificate issued by Certificate Authority (CA) which in turn may be certified by another CA. ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 58 • This structure forms a chain of X.509 certificates known as chain of trust. • The top most CA of the Chain is known to be the Trusted Root Certificate Authority of the chain. 7.3.1.2 TLS Server Authentication • When a TLS client initiates a connection with a server, the server sends its X.509 certificate chain (may or may not include the root certificate) to the client. • The client must authenticate the Server (verify the Server identity) before starting data exchange. • The client must verify the entire certificate chain and also verify that the root certificate authority of the chain is in the client’s trusted root certificate store. 7.3.2 Adding a Certificate to the WINC Trusted Root Certificate Store • Before connecting to a TLS Server, the root certificate of the server must be installed on the ATWINC15x0. If this is not done, the TLS connection to the server is locally aborted by the WINC. • The root certificate must be in DER format. If it is not provided in DER format, it must be converted before installation. Refer to Section 17 “How to Generate Certificates” for certificate formats and conversion methods. • To install the certificate, execute root_certificate_downloader.exe with the following syntax: root_certificate_downloader.exe -n N File1.cer File2.cer .... FileN.cer 7.4 WINC TLS Limitations 7.4.1 Concurrent Connections Only 2 TLS concurrent connections are allowed. 7.4.2 TLS Supported Ciphers The ATWINC15x0 supports the following cipher suites (for both client and server modes). • TLS_DHE_RSA_WITH_AES_128_CBC_SHA • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 • TLS_RSA_WITH_AES_128_CBC_SHA • TLS_RSA_WITH_AES_128_CBC_SHA256 The ATWINC15x0 also optionally support the following ECC cipher suites. • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 • TLS_ECDHE_ ECDSA _WITH_AES_128_CBC_SHA256 7.4.3 Supported Hash Algorithms The current implementation (WINC firmware version 19.5.2 onwards) supports the following hash algorithms: • MD5 • SHA-1 • SHA256 • SHA384 • SHA512 • RSA 4096 ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 59 7.4.4 TLS Certificate Constraints For TLS server and TLS client authentication, the ATWINC15x0 can accept the following certificate types: • RSA certificates with key size no more than 2048 bits • ECDSA certificates only for NIST P256 EC Curve (secp256r1); conditionally supported 7.4.5 ECC Cipher Suite The ATWINC15x0 TLS library features support of ECC cipher suites. Although, the ATWINC15x0 device does not contain a built-in hardware accelerator for ECC math, the WINC TLS library leverages the ECC math from the host MCU. To perform the ECC computations needed by the ECC ciphers, an ECC hardware accelerator (or software library) on the host MCU is mandatory. The WINC TLS initializes with the ECC cipher suites disabled by default. The host MCU application can enable the ciphers via the API sslSetActiveCipherSuites. 7.5 SSL Client Code Example SOCKET sslSocketHdl; uint8 rxBuffer[256]; /* Socket event handler. */ void SSL_SocketEventHandler(SOCKET sock, uint8 u8Msg, void * pvMsg) { if(sock == sslSocketHdl) { if(u8Msg == SOCKET_MSG_CONNECT) { // Connect event tstrSocketConnectMsg *pstrConnect = (tstrSocketConnectMsg*)pvMsg; if(pstrConnect->s8Error == 0) { // Perform data exchange. uint8 acSendBuffer[256]; uint16 u16MsgSize; // Fill in the acSendBuffer with some data here // Send some data. send(sock, acSendBuffer, u16MsgSize, 0); // Recv response from server. recv(sslSocketHdl, rxBuffer, sizeof(rxBuffer), 0); } else { printf("SSL Connection Failed\n"); } } else if(u8Msg == SOCKET_MSG_RECV) { tstrSocketRecvMsg *pstrRecvMsg = (tstrSocketRecvMsg*)pvMsg; if((pstrRecvMsg->pu8Buffer != NULL) && (pstrRecvMsg->s16BufferSize > 0)) { // Process the received message here // Close the socket if finished. close(sslSocketHdl); } } } } /* This is the DNS callback. The response of gethostbyname is here. */ void dnsResolveCallback(uint8* pu8HostName, uint32 u32ServerIP) { struct sockaddr_in strAddr; if(u32ServerIP != 0) { ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 60 sslSocketHdl = socket(AF_INET,SOCK_STREAM,u8Flags); if(sslSocketHdl >= 0) { strAddr.sin_family = AF_INET; strAddr.sin_port = _htons(443); strAddr.sin_addr.s_addr = u32ServerIP; connect(sslSocketHdl, (struct sockaddr*)&strAddr, sizeof(struct sockaddr_in)); } } else { printf("DNS Resolution Failed\n"); } } /* This function needs to be called from main function. For the callbacks to be invoked correctly, the API m2m_wifi_handle_events should be called continuously from main.*/ void SSL_Connect(char *pcServerURL) { // Initialize the socket layer. socketInit(); // Register socket application callbacks. registerSocketCallback(SSL_SocketEventHandler, dnsResolveCallback); // Resolve Server URL. gethostbyname((uint8*)pcServerURL); } ATWINC15x0 Transport Layer Security (TLS) © 2018 Microchip Technology Inc. User Guide DS00002389B-page 61 8. Wi-Fi AP Mode 8.1 Overview This chapter provides an overview of the WINC Access Point (AP) mode and describes how to setup this mode and configure its parameters. In ATWINC1500 v19.6.1 firmware and above, the DHCP default gateway, DNS server and subnet mask can be customized when entering AP and provisioning modes. Earlier, the default gateway and DNS server is the same as the host IP of the WINC and the subnet mask is 255.255.255.0. Configuring these values allow the use of 0.0.0.0 for the default gateway and DNS server, allowing mobile devices to connect to the WINC AP without disconnecting from the mobile network. Using IPs other than 0.0.0.0 is possible but it is of no use since only one device can connect to the WINC AP at any time. 8.2 Setting the WINC AP Mode Set the WINC AP mode configuration parameters using the tstrM2MAPConfig structure. There are two functions to enable/disable the WINC AP mode: • sint8 m2m_wifi_enable_ap (CONST tstrM2MAPConfig* pstrM2MAPConfig) • sint8 m2m_wifi_disable_ap (void) For more details on API, refer to the Atmel Software Framework for ATWINC1500 (Wi-Fi). In ATWINC1500 v19.6.1 firmware and above, to maintain backwards compatibility with older drivers, new structures and APIs were introduced. To customize these fields when entering AP or provisioning mode the tstrM2MAPModeConfig structure must be populated and passed to the new m2m_wifi_enable_ap_ext() or m2m_wifi_start_provision_mode_ext() APIs. The tstrM2MAPModeConfig structure contains the original tstrM2MAPConfig structure for storing the AP SSID, password, and so on. and another tstrM2MAPConfigExt structure for configuring the default router, DNS server and subnet mask. 8.3 Limitations • The AP can only support a single associated station. Further connection attempts are rejected. • The ATWINC15x0 supports WPA2 security feature starting from the firmware version 19.5.x. • Concurrency (simultaneous STA and AP mode) is not supported. Prior to activating the AP mode, the host MCU application must disable the mode that is currently running. 8.4 Sequence Diagram Once AP mode is established, data interface does not exist before a station associates to the AP; therefore, the application needs to wait until it receives a notification via an event callback. This process is shown in the following figure. ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 62 Figure 8-1. ATWINC15x0 AP Mode Establishment 8.5 AP Mode Code Example The following example shows how to configure the ATWINC15x0 AP mode with WINC_SSID as broadcasted SSID on channel one with open security and an IP address equals 192.168.1.1. #include "m2m_wifi.h" #include "m2m_types.h" void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { switch(u8WiFiEvent) { case M2M_WIFI_REQ_DHCP_CONF: { uint8 *pu8IPAddress = (uint8*)pvMsg; printf("Associated STA has IP Address \"%u.%u.%u.%u\"\n", pu8IPAddress[0], pu8IPAddress[1], pu8IPAddress[2], pu8IPAddress[3]); } break; default: break; } } int main() { tstrWifiInitParam param; /* Platform specific initializations. */ ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 63 param.pfAppWifiCb = wifi_event_cb; if (!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; strcpy(apConfig.au8SSID, "WINC_SSID"); // Set SSID apConfig.u8SsidHide = SSID_MODE_VISIBLE; // Set SSID to be broadcasted apConfig.u8ListenChannel = 1; // Set Channel apConfig.u8SecType = M2M_WIFI_SEC_WEP; // Set Security to WEP apConfig.u8KeyIndx = 0; // Set WEP Key Index apConfig.u8KeySz = WEP_40_KEY_STRING_SIZE; // Set WEP Key Size strcpy(apConfig.au8WepKey, "1234567890"); // Set WEP Key // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[3] = 1; // Start AP mode m2m_wifi_enable_ap(&apConfig); while(1) { m2m_wifi_handle_events(NULL); } } } Note:  Power Save mode is not supported in the ATWINC15x0 AP mode. ATWINC15x0 Wi-Fi AP Mode © 2018 Microchip Technology Inc. User Guide DS00002389B-page 64 9. Provisioning For normal operation the ATWINC15x0 device requires certain parameters to be loaded. In particular, when operating in Station mode, it must know the identity (SSID) and credentials of the access point to which it needs to connect. The entry of this information is facilitated through the following provisioning steps. The current ATWINC15x0 software supports the following methods of provisioning: • HTTP-based (browser) provisioning, while the WINC is in AP mode • Wi-Fi Protected Setup (WPS) 9.1 HTTP Provisioning In this method, the ATWINC15x0 is placed in AP mode and another device with a browser capability (mobile phone, tablet, PC, and so on) is instructed to connect to the ATWINC15x0 HTTP server. Once connected, the desired configuration can be entered. The HTTP Provisioning home page is as shown in the following figure. Figure 9-1. ATWINC15x0 HTTP Provisioning Page ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 65 9.1.1 Provisioning Control Flow Figure 9-2. HTTP Provisioning Sequence Diagram The preceding figure shows the provisioning operation for a WINC device. The detailed steps are described as follows: 1. The WINC device starts the HTTP Provisioning mode. 2. A user with a smartphone finds the WINC AP SSID in the Wi-Fi search list. 3. The user connects to the WINC AP. 4. The user launches the web browser and writes the WINC home page in the address bar. 5. If the HTTP redirect bit (bEnableHttpRedirect) is set in m2m_wifi_start_provision_mode API, then all http traffic (http://URL) from the associated device (Phone, PC, and so on) are redirected to the WINC HTTP Provisioning home page. Some phones display a notification message “sign in to Wi-Fi networks?” which, when accepted, automatically loads the WINC home page. The WINC home page, as shown in Figure 10.1, appears on the browser. 6. To discover the list of Wi-Fi APs in the area, the user can press “Refresh”. 7. The desired AP is then selected from the search list (by one click or one touch) and its name automatically appears in the “Network Name” text box. ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 66 8. The user must then enter the correct AP passphrase (for WPA/WPA2 personal security) in the “Pass Phrase” text box. If the desired AP uses open security, (M2M_WIFI_SEC_OPEN) then the Pass Phrase field is left empty. 9. A WINC device name may be optionally configured, if desired, by the user in the “Device Name” text box. 10. Then user should press Connect. The WINC turns off AP mode and start connecting to the provisioned AP. 9.1.2 HTTP Redirect Feature The ATWINC15x0 HTTP Provisioning server supports the HTTP redirect feature, which forces all HTTP traffic originating from the associated user device to be redirected to the ATWINC15x0 Provisioning home page. This simplifies the mechanism of loading the provisioning page instead of typing the exact web address of the HTTP Provisioning server. To enable this feature, set the redirect flag when calling the API m2m_wifi_start_provision_mode. For further details, refer to the following code example. 9.1.3 Provisioning Code Example void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { if(u8WiFiEvent == M2M_WIFI_RESP_PROVISION_INFO) { tstrM2MProvisionInfo *provInfo = (tstrM2MProvisionInfo*)pvMsg; if(provInfo->u8Status == M2M_SUCCESS) { // connect to the provisioned AP. m2m_wifi_connect((char*)provInfo->au8SSID, strlen(provInfo ->au8SSID), provInfo->u8SecType, provInfo->au8Password, M2M_WIFI_CH_ALL); printf("PROV SSID : %s\n", provInfo->au8SSID); printf("PROV PSK : %s\n", provInfo->au8Password); } else { printf("(ERR) Provisioning Failed\n"); } } } int main() { tstrWifiInitParam param; // Platform specific initializations. // Driver initialization. param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { tstrM2MAPConfig apConfig; uint8 bEnableRedirect = 1; strcpy(apConfig.au8SSID, "WINC_AP"); apConfig.u8ListenChannel = 1; apConfig.u8SecType = M2M_WIFI_SEC_OPEN; apConfig.u8SsidHide = 0; // IP Address apConfig.au8DHCPServerIP[0] = 192; apConfig.au8DHCPServerIP[1] = 168; apConfig.au8DHCPServerIP[2] = 1; apConfig.au8DHCPServerIP[0] = 1; m2m_wifi_start_provision_mode(&apConfig, "atmelconfig.com", bEnableRedirect); ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 67 while(1) { m2m_wifi_handle_events(NULL); } } } 9.2 Limitations The current implementation of the HTTP Provisioning has the following limitations: • The ATWINC15x0 AP limitations are applicable to the Provisioning mode. For a list of AP mode limitations, refer to Limitations. • Provisioning uses AP mode with open security. No Wi-Fi security nor application level security (for example, TLS) is used; therefore, the AP credentials entered by the user are sent on the clear and can be seen by eavesdroppers. • The WINC Provisioning home page is a static HTML page. No server-side scripting allowed in the WINC HTTP server. • Only APs with WPA-personal security (passphrase based) and no security (Open network) can be provisioned. WEP and WPA-Enterprise APs cannot be provisioned. • The Provisioning is responsible to deliver the connection parameters to the application, the connection procedure and the connection parameters validity are the application's responsibility. 9.3 Wi-Fi Protected Setup (WPS) Most modern Access Points support Wi-Fi Protected Setup method, typically using the push button method. From the user’s perspective WPS is a simple mechanism to make a device connect securely to an AP without remembering passwords or passphrases. WPS uses asymmetric cryptography to form a temporary secure link which is then used to transfer a passphrase (and other information) from the AP to the new station. After the transfer, secure connections are made as for normal static PSK configuration. 9.3.1 WPS Configuration Methods There are two authentication methods that can be used with WPS: 1. PBC (push button) method – A physical button is pressed on the AP which puts the AP into WPS mode for a limited period of time. WPS is initiated on the ATWINC15x0 by calling m2m_wifi_wps with input parameter WPS_PBC_TRIGGER. 2. PIN method – The AP is always available for WPS initiation but requires proof that the user has knowledge of an 8-digit PIN, usually printed on the body of the AP. Since the WINC is often used in headless devices (no user interface), it is necessary to reverse this process and force the AP to use a PIN number provided with the WINC device. Some APs allow the PIN to be changed through configuration. WPS is initiated on the ATWINC15x0 by calling m2m_wifi_wps with input parameter WPS_PIN_TRIGGER. Given the difficulty of this approach, it is not recommend for most applications. The flow of messages and actions for WPS operation is shown in the following figure. ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 68 9.3.2 WPS Control Flow Figure 9-3. WPS Operation for Push Button Trigger 9.3.3 WPS Limitations • WPS is used to transfer the WPA/WPA2 key only; other security types are not supported. • The WPS standard rejects the session (WPS response fail) if the WPS button is pressed on more than one AP in the same proximity, and the application can try again after a couple of minutes. • If no WPS button is pressed on the AP, the WPS scan will time-out after two minutes since the initial WPS trigger. • The WPS is responsible to deliver the connection parameters to the application, the connection procedure and the connection parameters’ validity is the application's responsibility. 9.3.4 WPS Code Example void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { if(u8WiFiEvent == M2M_WIFI_REQ_WPS) { tstrM2MWPSInfo *pstrWPS = (tstrM2MWPSInfo*)pvMsg; if(pstrWPS->u8AuthType != 0) { printf("WPS SSID : %s\n",pstrWPS->au8SSID); printf("WPS PSK : %s\n",pstrWPS->au8PSK); printf("WPS SSID Auth Type : %s\n", pstrWPS->u8AuthType == M2M_WIFI_SEC_OPEN ? "OPEN" : "WPA/WPA2"); printf("WPS Channel : %d\n",pstrWPS->u8Ch + 1); // Establish Wi-Fi connection m2m_wifi_connect((char*)pstrWPS->au8SSID, (uint8)m2m_strlen(pstrWPS->au8SSID), pstrWPS->u8AuthType, pstrWPS->au8PSK, pstrWPS->u8Ch); } ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 69 else { printf("(ERR) WPS Is not enabled OR Timedout\n"); } } } int main() { tstrWifiInitParam param; // Platform specific initializations. // Driver initialization. param.pfAppWifiCb = wifi_event_cb; if(!m2m_wifi_init(¶m)) { // Trigger WPS in Push button mode. m2m_wifi_wps(WPS_PBC_TRIGGER, NULL); while(1) { m2m_wifi_handle_events(NULL); } } } ATWINC15x0 Provisioning © 2018 Microchip Technology Inc. User Guide DS00002389B-page 70 10. Over-The-Air Upgrade 10.1 Overview The ATWINC15x0 supports OTA upgrade of firmware on internal serial Flash. No host Flash memory resources are required to store the firmware. The ATWINC15x0 uses an internal HTTP client to retrieve the firmware from a remote server. 10.2 OTA Image Architecture The WINC serial Flash can store two copies of the firmware image: a working image and a rollback image. Upon first-time boot, the working image is the factory image and the rollback image will not be available in the WINC Flash. Instead ATE firmware will be available in rollback image firmware section. On performing the OTA firmware upgrade, the ATE firmware will be erased and the newly received firmware will be written into the Roll back image section. The WINC has insufficient internal memory to save the whole image in RAM during an OTA upgrade; therefore, each block of downloaded data is written to the Flash as it is received. In the event that the OTA fails, the existing (Working) image is retained and the rollback image is invalidated. If the transfer succeeds, the Flash control structure is updated to reflect a new working image and the existing image is marked as a valid rollback image. Figure 10-1. OTA Image Organization ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 71 10.3 OTA Download Sequence Diagram Figure 10-2. OTA Image Download and Install 10.4 OTA Firmware Rollback Figure 10-3. OTA Image Rollback Sequence ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 72 10.5 OTA Limitations • Rollback is allowed, only after at least one successful OTA download. • Rollback image is overwritten by any new successful or failed OTA attempt. 10.6 OTA Code Example /*! */ static void OtaUpdateCb(uint8 u8OtaUpdateStatusType ,uint8 u8OtaUpdateStatus) { if(u8OtaUpdateStatusType == DL_STATUS) { if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) { //switch to the upgraded firmware m2m_ota_switch_firmware(); } } else if(u8OtaUpdateStatusType == SW_STATUS) { if(u8OtaUpdateStatus == OTA_STATUS_SUCSESS) { M2M_INFO("Now OTA suceesfully done"); //start the host SW upgrade then system reset is required (Reintilize the driver) } } } void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg) { case M2M_WIFI_REQ_DHCP_CONF: { //after suceesfull connection, start the over air upgrade m2m_ota_start_update(OTA_URL); } break; default: break; } int main (void) { tstrWifiInitParam param; tstr1xAuthCredentials gstrCred1x = AUTH_CREDENTIALS; nm_bsp_init(); m2m_memset((uint8*)¶m, 0, sizeof(param)); param.pfAppWifiCb = wifi_event_cb; //intilize the WINC Driver ret = m2m_wifi_init(¶m); if (M2M_SUCCESS != ret) { M2M_ERR("Driver Init Failed <%d>\n",ret); while(1); } //intilize the ota module m2m_ota_init(OtaUpdateCb,NULL); //connect to AP that provide connection to the OTA server m2m_wifi_default_connect(); while(1) { while(m2m_wifi_handle_events(NULL) != M2M_SUCCESS) {} } } Note:  For more details on example codes, refer to the Wi-Fi Network Controller Software Programming Guide. ATWINC15x0 Over-The-Air Upgrade © 2018 Microchip Technology Inc. User Guide DS00002389B-page 73 11. Multicast Sockets 11.1 Overview The purpose of the multicast filters is to provide the ability to send/receive messages to/from multicast addresses. This feature is useful for one-to-many communication over networks, whether it’s intended to send Internet Protocol (IP) datagrams to a group of interested receivers in a single transmission, participate in a zero-configuration networking or listening to a multicast stream or any other application. 11.2 How to Use Filters Whenever the application wishes to use a multicast IP address, for either sending or receiving, a filter is needed. The application can establish this through setting the IP_ADD_MEMBERSHIP option for the required socket accompanied by the multicast address that the application wants to use. If subsequently the host wants to stop receiving the multicast stream, set the IP_DROP_MEMBERSHIP option for the required socket accompanied with the multicast address. Adding or removing a multicast address filter causes the WINC chip firmware to add/remove both MAC layer filter and IP layer filter in order to pass or prevent messages from reaching to the host. 11.3 Multicast Socket Code Example To illustrate the functionality, a simple example is implemented where the host application responds to mDNS (Multicast Domain Name System) queries sent from a computer/mobile application. The computer/ mobile is looking for devices which support the zero configuration service as indicated by an mDNS response. The WINC responds, notifying its presence and its capability of sending and receiving multicast messages. The example consists of a UDP server that binds on port 5353 (mDNS port) and waits for messages, parsing them and replying with a previously saved response message. • Server Initialization: void MDNS_ServerInit() { tstrSockAddr strAddr ; unsigned int MULTICAST_IP = 0xE00000FB; //224.0.0.251 socketInit(); dns_server_sock = socket( AF_INET, SOCK_DGRAM,0); MDNS_INFO("DNS_server_init \n"); setsockopt(dns_server_sock,1,IP_ADD_MEMBERSHIP,&MULTICAST_IP,sizeof(MULTICAST_IP)); strAddr.u16Port =HTONS(MDNS_SERVER_PORT); bind(dns_server_sock,(struct sockaddr*)&strAddr,sizeof(strAddr)); registerSocketCallback(UDP_SocketEventHandler,AppServerCb); } • Sockets Events Handler: void MDNS_RecvfromCB(signed char sock,unsigned char *pu8RxBuffer,signed short s16DataSize, unsigned char *pu8IPAddr,unsigned short u16Port,void *pvArg) { MDNS_INFO("DnsServer_RecvfromCB \n"); if((pu8RxBuffer != 0) && (s16DataSize > 0)) { tstrDnsHdr strDnsHdr; strdnsquery; MDNS_INFO("DNS Packet Recieved \n"); ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 74 if(MDNS_ParseQuery(&pu8RxBuffer[0], &strDnsHdr,&strDnsQuery)) MDNS_SendResp (sock,pu8IPAddr, u16Port,&strDnsHdr,&strDnsQuery ); } else { MDNS_INFO("DnsServer_RecvfromCB Error !\n"); } } • Server Socket Callback: void MDNS_RecvfromCB(signed char sock,unsigned char *pu8RxBuffer,signed short s16DataSize,unsigned char *pu8IPAddr,unsigned short u16Port,void *pvArg) { MDNS_INFO("DnsServer_RecvfromCB \n"); if((pu8RxBuffer != 0) && (s16DataSize > 0)) { tstrDnsHdr strDnsHdr ; strdnsquery ; MDNS_INFO("DNS Packet Recieved \n"); if(MDNS_ParseQuery(&pu8RxBuffer[0], &strDnsHdr,&strDnsQuery)) MDNS_SendResp (sock,pu8IPAddr, u16Port,&strDnsHdr,&strDnsQuery ); } else { MDNS_INFO("DnsServer_RecvfromCB Error !\n"); } } • Parse mDNS Query: int MDNS_ParseQuery(unsigned char * pu8RxBuffer, tstrDnsHdr *pstrDnsHdr, strdnsquery *pstrDnsQuery ) { unsigned char dot_size,temp=0; unsigned short n=0,i=0,u16index=0; int bDNSmatch = 0; /* ----Identification--------------------------|QR| Opcode |AA|TC|RD|RA|Z|AD|CD| Rcode | */ /* ----Total Questions------------------------|-----------------Total Answer RRs---------------*/ /* ----Total Authority RRs --------------------|----------------Total Additional RRs------------*/ /* --------------------------------- Questions --------------------------------- */ /* ------------------------------------ Answer RRs ------------------------------------------*/ /* ----------------------------------- Authority RRs ----------------------------------*/ /* -----------------------------------Additional RRs ----------------------------------*/ MDNS_INFO("Parsing DNS Packet\n"); pstrDnsHdr->id = (( pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("id = %.4x \n",pstrDnsHdr->id); u16index+=2; pstrDnsHdr->flags1= pu8RxBuffer[u16index++]; pstrDnsHdr->flags2= pu8RxBuffer[u16index++]; MDNS_INFO ("flags = %.2x %.2x \n",pstrDnsHdr->flags1,pstrDnsHdr->flags2); pstrDnsHdr->numquestions = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numquestions = %.4x \n",pstrDnsHdr->numquestions); u16index+=2; pstrDnsHdr->numanswers = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numanswers = %.4x \n",pstrDnsHdr->numanswers); u16index+=2; pstrDnsHdr->numauthrr = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numauthrr = %.4x \n",pstrDnsHdr->numauthrr); u16index+=2; pstrDnsHdr->numextrarr = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); MDNS_INFO ("numextrarr = %.4x \n",pstrDnsHdr->numextrarr); u16index+=2; dot_size =pstrDnsQuery->query[n++]= pu8RxBuffer[u16index++]; pstrDnsQuery->u16size=1; ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 75 while (dot_size--!=0) //(pu8RxBuffer[++u16index] != 0) { pstrDnsQuery->query[n++]=pstrDnsQuery->queryForChecking[i++]=pu8RxBuffer[u16index++] ; pstrDnsQuery->u16size++; gu8pos=temp; if (dot_size == 0 ) { pstrDnsQuery->queryForChecking[i++]= '.' ; temp=u16index; dot_size =pstrDnsQuery->query[n++]= pu8RxBuffer[u16index++]; pstrDnsQuery->u16size++; } } pstrDnsQuery->queryForChecking[--i] = 0; MDNS_INFO("parsed query <%s>\n",pstrDnsQuery->queryForChecking); // Search for any match in the local DNS table. for(n = 0; n < DNS_SERVER_CACHE_SIZE; n++) { MDNS_INFO("Saved URL <%s>\n",gpacDnsServerCache[n]); if(strcmp(gpacDnsServerCache[n], pstrDnsQuery->queryForChecking) ==0) { bDNSmatch= 1; MDNS_INFO("MATCH \n"); } else { MDNS_INFO("Mismatch\n"); } } pstrDnsQuery->u16class = ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); u16index+=2; pstrDnsQuery->u16type= ((pu8RxBuffer[u16index]<<8)| (pu8RxBuffer[u16index+1])); return bDNSmatch; } • Send mDNS Response: void MDNS_SendResp (signed char sock,unsigned char * pu8IPAddr, unsigned short u16Port,tstrDnsHdr *pstrDnsHdr,strdnsquery *pstrDnsQuery) { unsigned short u16index=0; tstrSockAddr strclientAddr ; unsigned char * pu8sendBuf; char * serviceName2 = (char*)malloc(sizeof(serviceName)+1); unsigned int MULTICAST_IP = 0xFB0000E0; pu8sendBuf= gPu8Buf; memcpy(&strclientAddr.u32IPAddr,&MULTICAST_IP,IPV4_DATA_LENGTH); strclientAddr.u16Port=u16Port; MDNS_INFO("%s \n",pstrDnsQuery->query); MDNS_INFO("Query Size = %d \n",pstrDnsQuery->u16size); MDNS_INFO("class = %.4x \n",pstrDnsQuery->u16class); MDNS_INFO("type = %.4x \n",pstrDnsQuery->u16type); MDNS_INFO("PREPARING DNS ANSWER BEFORE SENDING\n"); /*----------------------------ID 2 Bytes -----------------------------*/ pu8sendBuf [u16index++] =0; //( pstrDnsHdr->id>>8); pu8sendBuf [u16index++] = 0;//( pstrDnsHdr->id)&(0xFF); MDNS_INFO ("(ResPonse) id = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------Flags 2 Bytes----------------------------*/ pu8sendBuf [u16index++] = DNS_RSP_FLAG_1; pu8sendBuf [u16index++] = DNS_RSP_FLAG_2; MDNS_INFO ("(ResPonse) Flags = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------No of Questions--------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x01; MDNS_INFO ("(ResPonse) Questions = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*---------------------------No of Answers----------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x01; MDNS_INFO ("(ResPonse) Answers = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 76 /*---------------------------No of Authority RRs------------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x00; MDNS_INFO ("(ResPonse) Authority RRs = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*----------------------------No of Additional RRs----------------------*/ pu8sendBuf [u16index++] =0x00; pu8sendBuf [u16index++] =0x00; MDNS_INFO ("(ResPonse) Additional RRs = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*--------------------------------Query-----------------------------*/ memcpy(&pu8sendBuf[u16index],pstrDnsQuery->query,pstrDnsQuery->u16size); MDNS_INFO("\nsize = %d \n",pstrDnsQuery->u16size); u16index+=pstrDnsQuery->u16size; /*-------------------------------Query Type----------------------------*/ pu8sendBuf [u16index++] = ( pstrDnsQuery->u16type>>8);//MDNS_TYPE>>8; pu8sendBuf [u16index++] = ( pstrDnsQuery->u16type)&(0xFF);//(MDNS_TYPE&0xFF); MDNS_INFO ("Query Type = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*------------------------------Query Class-----------------------------------*/ pu8sendBuf [u16index++] =MDNS_CLASS>>8;//(( pstrDnsQuery->u16class>>8)|0x80); pu8sendBuf [u16index++] = (MDNS_CLASS & 0xFF);//( pstrDnsQuery->u16class)&(0xFF); MDNS_INFO ("Query Class = %.2x %.2x \n", pu8sendBuf[u16index-2],pu8sendBuf[u16index-1]); /*########################Answers#########################*/ /*------------------------------Name---------------------------------*/ pu8sendBuf [u16index++]= 0xC0 ; //pointer to query name location pu8sendBuf [u16index++]= 0x0C ; // instead of writing the whole query name again /*-----------------------------Type----------------------------------*/ pu8sendBuf [u16index++] =MDNS_TYPE>>8; //Type 12 PTR (domain name Pointer). pu8sendBuf [u16index++] =(MDNS_TYPE&0xFF); /*------------------------------Class-----------------------------------*/ pu8sendBuf [u16index++] =0x00;//MDNS_CLASS; //Class IN, Internet. pu8sendBuf [u16index++] =0x01;// (MDNS_CLASS & 0xFF); /*-----------------------------TTL----------------------------------*/ pu8sendBuf [u16index++] =(TIME_TO_LIVE >>24); pu8sendBuf [u16index++] =(TIME_TO_LIVE >>16); pu8sendBuf [u16index++] =(TIME_TO_LIVE >>8); pu8sendBuf [u16index++] =(TIME_TO_LIVE ); /*---------------------------Date Length----------------------------------*/ pu8sendBuf [u16index++] =(sizeof(serviceName)+2)>>8;//added 2 bytes for the pointer pu8sendBuf [u16index++] =(sizeof(serviceName)+2); /*-----------------------------DATA--------------------------------*/ convertServiceName(serviceName,sizeof(serviceName),serviceName2); memcpy(&pu8sendBuf[u16index],serviceName2,sizeof(serviceName)+1); u16index+=sizeof(serviceName); pu8sendBuf [u16index++] =0xC0;//Pointer to .local (from name) pu8sendBuf [u16index++] =gu8pos;//23 /*###########################################################*/ strclientAddr.u16Port=HTONS(MDNS_SERVER_PORT); // MultiCast RESPONSE sendto( sock, pu8sendBuf,(uint16)u16index,0,(struct sockaddr*)&strclientAddr,sizeof(strclientAddr)); strclientAddr.u16Port=u16Port; memcpy(&strclientAddr.u32IPAddr,pu8IPAddr,IPV4_DATA_LENGTH); } • Service Name: static char gpacDnsServerCache[DNS_SERVER_CACHE_SIZE][MDNS_HOSTNAME_SIZE] = { "_services._dns-sd._udp.local","_workstation._tcp.local","_http._tcp.local" }; unsigned char gPu8Buf [MDNS_BUF_SIZE]; unsigned char gu8pos ; signed char dns_server_sock ; #define serviceName "_ATMELWIFI._tcp" ATWINC15x0 Multicast Sockets © 2018 Microchip Technology Inc. User Guide DS00002389B-page 77 12. WINC Serial Flash Memory 12.1 Overview and Features The WINC has internal serial (SPI) Flash memory of 4 Mb capacity in the ATWINC1500 and 8 Mb capacity in the ATWINC1510. The Flash memory is used to store: • User configuration • Firmware • Connection Profiles During start-up and mode changes, firmware is loaded from the serial Flash into program memory (IRAM) in which the firmware is executed. The Flash is accessed at other points during run time to retrieve configuration and profile data. A minimum of 4 Mb Flash is required for OTA feature in order to store both working and rollback images. The Flash memory can be read, written and erased directly from the host without co-operation with the WINC firmware. However, if operational firmware is already loaded, it is necessary to halt any running WINC firmware first before accessing the serial Flash to avoid access conflict between the host and the WINC processor. 12.2 Accessing to Serial Flash • The host has transparent access to the serial (SPI) Flash through the WINC SPI Master. • The host can program the serial (SPI) Flash without the need for operational firmware in the WINC. The function m2m_wifi_download_mode must be called first. Figure 12-1. System Block Diagram showing SPI Flash Connection 12.3 Read/Write/Erase Operations SPI Flash can be accessed to be read, written and erased. It is required to change the WINC’s mode to Download mode first before attempting to access the SPI Flash by calling: sint32 m2m_wifi_download_mode(); ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 78 All SPI Flash functions are blocking. A return of M2M_SUCCESS indicates that the requested operation is successfully completed. The following is a list of Flash functions that may be used: • Query the size of the SPI Flash: uint32 spi_flash_get_size(); This function returns with the size of the SPI Flash in Mb. • Read data from the SPI Flash: sint8 spi_flash_read(uint8 *pu8Buf, uint32 u32offset, uint32 u32Sz) Where the size of data is limited by the SPI Flash size. • Erase sectors in the SPI Flash: sint8 spi_flash_erase(uint32 u32Offset, uint32 u32Sz) Note:  The size is limited by the SPI Flash size. Prior to writing to any sector, erase this sector first. If some data needs to be changed within a sector, it is advised to read the sector first, modify the data and then erase and write the whole sector again. • Write data to the SPI Flash: sint8 spi_flash_write(uint8* pu8Buf, uint32 u32Offset, uint32 u32Sz) If the application wants to write any number of bytes within any sector, it has to erase the entire sector first. It may be necessary to read the entire sector, erase the sector and then write back with modifications. It is also recommended to verify that data is written after it returns success by reading data again and compare it with the original. 12.3.1 Flash Read, Erase, and Write Code Examples #include "spi_flash.h" #define DATA_TO_REPLACE "THIS IS A NEW SECTOR IN FLASH" int main() { uint8 au8FlashContent[FLASH_SECTOR_SZ] = {0}; uint32u32FlashTotalSize = 0, u32FlashOffset = 0; // Platform specific initializations. ret = m2m_wifi_download_mode(); if(M2M_SUCCESS != ret) { printf("Unable to enter download mode\r\n"); } else { u32FlashTotalSize = spi_flash_get_size(); } while((u32FlashTotalSize > u32FlashOffset) && (M2M_SUCCESS == ret)) { ret = spi_flash_read(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to read SPI sector\r\n"); break; } memcpy(au8FlashContent, DATA_TO_REPLACE, strlen(DATA_TO_REPLACE)); ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 79 ret = spi_flash_erase(u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to erase SPI sector\r\n"); break; } ret = spi_flash_write(au8FlashContent, u32FlashOffset, FLASH_SECTOR_SZ); if(M2M_SUCCESS != ret) { printf("Unable to write SPI sector\r\n"); break; } u32FlashOffset += FLASH_SECTOR_SZ; } if(M2M_SUCCESS == ret) { printf("Successful operations\r\n"); } else { printf("Failed operations\r\n"); } while(1); return M2M_SUCCESS; } ATWINC15x0 WINC Serial Flash Memory © 2018 Microchip Technology Inc. User Guide DS00002389B-page 80 13. Host Interface (HIF) Protocol Communication between the user application and the WINC device is facilitated by the driver software. This driver implements the Host Interface (HIF) Protocol and exposes an API to the application with various services. The services are broadly divided in two categories: Wi-Fi device control and IP Socket. The Wi-Fi device control services allow actions such as channel scanning, network identification, connection and disconnection. The Socket services allow data transfer once a connection is established and similar to BSD socket definitions. The host driver implements services asynchronously. This means that when the application calls an API to request a service action, the call is non-blocking and returns immediately, often before the action is completed. Where appropriate a notification that an action has completed is provided in a subsequent message from the WINC device to the host which is delivered to the application via a callback function. In general, the WINC firmware uses asynchronous events to signal the host driver of certain status changes. Asynchronous operation is essential where functions (such as Wi-Fi connection) may take significant time. When an API is called, a sequence of layers is activated to format the request and arranging to transfer it to the WINC device through the serial protocol. Note:  Dealing with HIF messages in the host MCU application is an advanced topic. For most applications, it is recommended to use Wi-Fi and socket layers. Both layers hide the complexity of the HIF APIs. After the application sends request, the Host Driver (Wi-Fi/Socket layer) formats the request and sends it to the HIF layer which then interrupts the WINC device to notify that a new request is posted. Upon receipt, the WINC firmware parses the request and starts the required operation. Figure 13-1. WINC Driver Layers The Host Interface Layer is responsible for handling communication between the host MCU and the WINC device. This includes interrupt handling, DMA control and management of the communication logic between the firmware driver in the host and the WINC firmware. The Request/Response sequence between the host and the WINC chip is shown in the following figure. ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 81 Figure 13-2. The Request/Response Sequence Diagram 13.1 Transfer Sequence Between the HIF Layer and the WINC Firmware The following section shows the individual steps taken during a HIF frame transmit (HIF message to the WINC) and a HIF frame receive (HIF message from the WINC). 13.1.1 Frame Transmit The following figure shows the steps and states involved in sending a message from the host to the WINC device. Figure 13-3. HIF Frame Transmit to WINC ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 82 Table 13-1. Steps in HIF Frame Transmit to WINC Step Description Step (1) Wake up the WINC device Wake up the device to be able to receive the host requests. Step (2) Interrupt the WINC device Prepare and set the HIF layer header to NMI_STATE_REG register (4 bytes header describing the sent packet). Set BIT [1] of WIFI_HOST_RCV_CTRL_2 register to raise an interrupt to the WINC chip. Step (3) Poll for DMA address Wait until the WINC chip clears BIT [1] of WIFI_HOST_RCV_CTRL_2 register. Get the DMA address (for the allocated memory) from register 0x150400. Step (4) Write data Write the data blocks in sequence, the HIF header then the Control buffer (if any) then the Data buffer (if any). Step (5) TX Done Interrupt Send a notification that writing the data is completed by setting BIT [1] of WIFI_HOST_RCV_CTRL_3 register. Step (6) Allow the WINC device to Sleep Allow the WINC device to enter Sleep mode again (if it wishes). 13.1.2 Frame Receive The following figure shows the steps and states involved in sending a message from the WINC device to the host. Figure 13-4. HIF Frame Receive from WINC to Host Table 13-2. Steps in HIF Frame Receive from WINC to Host Step Description Step (1) Wake up the WINC device Wake up the device to be able to receive host requests. Step (2) Check for Interrupt Monitor BIT [0] of WIFI_HOST_RCV_CTRL_0 register. Disable the host from receiving interrupts (until this interrupt is processed). Step (3) Clear interrupt Write zero to BIT [0] of WIFI_HOST_RCV_CTRL_0 register. ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 83 ...........continued Step Description Step (4) Read data Get the address of the data block from WIFI_HOST_RCV_CTRL_1 register. Read data block with size obtained from WIFI_HOST_RCV_CTRL_0 register BIT [13] <-> BIT [2]. Step (5) Process Request Parse the HIF header at the start of the data and forward the data to the appropriate registered Callback function. Step (6) HOST RX Done Raise an interrupt for the chip to free the memory holding the data by setting BIT [1] of WIFI_HOST_RCV_CTRL_0 register. Enable host interrupt reception again. Step (7) Allow the WINC device to Sleep Allow the WINC device to enter Sleep mode again (if it wishes). 13.2 HIF Message Header Structure The HIF message is the data structure exchanged back and forth between the Host Interface and the WINC firmware. The HIF message header structure consists of three fields: • The Group ID (8-bit) – a group ID is the category of the message. Valid categories are enumerated in tenuM2mReqGroup. • Op Code (8-bit) – is a command number. Valid command number is a value enumerated in: tenuM2mConfigCmd and tenuM2mStaCmd, tenuM2mApCmd, and tenuM2mP2pCmd corresponding to configuration, STA mode, AP mode, and P2P mode commands. Note:  • Refer to the m2m_types.h for the full list of commands. • The P2P mode is not supported after release v19.5.3. • Payload Length (16-bit) – the payload length is shown in bytes (does not include header). 13.3 HIF Layer APIs The interface between the application and the driver is done at the higher layer API interface (Wi-Fi / Socket.) As explained previously, the driver upper layer uses a lower layer API to access the services of the Host Interface Protocol. This section describes the Host Interface APIs that the upper layers use: The following API functions are described: ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 84 • hif_chip_wake • hif_chip_sleep • hif_register_cb • hif_isr • hif_receive • hif_send • hif_set_sleep_mode • hif_get_sleep_mode For all functions, the return value is either M2M_SUCCESS (zero) in case of success or a negative value in case of failure. • sint8 hif_chip_wake (void) – this function wakes the WINC chip from Sleep mode using clockless register access. It sets bit '1' of register 0x01 and sets the value of WAKE_REG register to WAKE_VALUE. • sint8 hif_chip_sleep (void) – this function enables Sleep mode for the WINC chip by setting the WAKE_REG register to a value of SLEEP_VALUE and clearing bit '1' of register 0x01. • sint8 hif_register_cb (uint8 u8Grp, tpfHifCallBack fn) – this function sets the callback function for different components (for example, M2M_WIFI, M2M_HIF, M2M_OTA and so on.). A callback is registered by upper layers to receive specific events of a specific message group. • sint8 hif_isr (void) – this is the host interface interrupt service routine. It handles interrupts generated by the WINC chip and parses the HIF header to call back the appropriate handler. • sint8 hif_receive (uint32 u32Addr, uint8 *pu8Buf, uint16 u16Sz, uint8 is Done) – this function causes the host driver to read data from the WINC chip. The location and length of the data must be known in advance and specified. This is typically extracted from an earlier part of a transaction. • sint8 hif_send (uint8 u8Gid, uint8 u8Opcode, uint8 *pu8CtrlBuf, uint16 u16CtrlBufSize, uint8 *pu8DataBuf, uint16 u16DataSize, uint16 16DataOffset) – this function causes the host driver to send data to the WINC chip. The WINC chip must be prepared for reception according to the flow described in the previous section. • void hif_set_sleep_mode (uint8 u8Pstype) – this function is used to set the Sleep mode of the HIF layer. • uint8 hif_get_sleep_mode (void) – this function return the Sleep mode of the HIF layer. 13.4 Scan Code Example The following code example illustrates the Request/Response flow on a Wi-Fi Scan request. Note:  For more details on example codes, refer to the Wi-Fi Network Controller Software Programming Guide. • The application requests a Wi-Fi scan. { m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } • The host driver Wi-Fi layer formats the request and forward it to HIF (Host Interface) layer. sint8 m2m_wifi_request_scan(uint8 ch) { tstrM2MScan strtmp; sint8 s8Ret = M2M_ERR_SCAN_IN_PROGRESS; ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 85 strtmp.u8ChNum = ch; s8Ret = hif_send(M2M_REQ_GRP_WIFI, M2M_WIFI_REQ_SCAN, (uint8*)&strtmp, sizeof(tstrM2MScan),NULL, 0,0); return s8Ret; } • The HIF layer sends the request to the WINC chip. sint8 hif_send(uint8 u8Gid,uint8 u8Opcode,uint8 *pu8CtrlBuf,uint16 u16CtrlBufSize, uint8 *pu8DataBuf,uint16 u16DataSize, uint16 u16DataOffset) { sint8 ret = M2M_ERR_SEND; volatile tstrHifHdr strHif; strHif.u8Opcode = u8Opcode&(~NBIT7); strHif.u8Gid = u8Gid; strHif.u16Length = M2M_HIF_HDR_OFFSET; if(pu8DataBuf != NULL) { strHif.u16Length += u16DataOffset + u16DataSize; } else { strHif.u16Length += u16CtrlBufSize; } /* TX STEP (1) */ ret = hif_chip_wake(); if(ret == M2M_SUCCESS) { volatile uint32 reg, dma_addr = 0; volatile uint16 cnt = 0; reg = 0UL; reg |= (uint32)u8Gid; reg |= ((uint32)u8Opcode<<8); reg |= ((uint32)strHif.u16Length<<16); ret = nm_write_reg(NMI_STATE_REG,reg); if(M2M_SUCCESS != ret) goto ERR1; reg = 0; /* TX STEP (2) */ reg |= (1<<1); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_2, reg); if(M2M_SUCCESS != ret) goto ERR1; dma_addr = 0; for(cnt = 0; cnt < 1000; cnt ++) { ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_2,(uint32 *)®); if(ret != M2M_SUCCESS) break; if (!(reg & 0x2)) { /* TX STEP (3) */ ret = nm_read_reg_with_ret(0x150400,(uint32 *)&dma_addr); if(ret != M2M_SUCCESS) { /*in case of read error clear the dma address and return error*/ dma_addr = 0; } /*in case of success break */ break; } } if (dma_addr != 0) { volatile uint32 u32CurrAddr; u32CurrAddr = dma_addr; strHif.u16Length=NM_BSP_B_L_16(strHif.u16Length); /* TX STEP (4) */ ret = nm_write_block(u32CurrAddr, (uint8*)&strHif, M2M_HIF_HDR_OFFSET); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += M2M_HIF_HDR_OFFSET; if(pu8CtrlBuf != NULL) { ret = nm_write_block(u32CurrAddr, pu8CtrlBuf, u16CtrlBufSize); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += u16CtrlBufSize; } ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 86 if(pu8DataBuf != NULL) { u32CurrAddr += (u16DataOffset - u16CtrlBufSize); ret = nm_write_block(u32CurrAddr, pu8DataBuf, u16DataSize); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += u16DataSize; } reg = dma_addr << 2; reg |= (1 << 1); /* TX STEP (5) */ ret = nm_write_reg(WIFI_HOST_RCV_CTRL_3, reg); if(M2M_SUCCESS != ret) goto ERR1; } else { /* ERROR STATE */ M2M_DBG("Failed to alloc rx size\r"); ret = M2M_ERR_MEM_ALLOC; goto ERR1; } } else { M2M_ERR("(HIF)Fail to wakup the chip\n"); goto ERR1; } /* TX STEP (6) */ ret = hif_chip_sleep(); ERR1: return ret; } • The WINC chip processes the request and interrupts the host after finishing the operation. • The HIF layer then receives the response. static sint8 hif_isr(void) { sint8 ret = M2M_ERR_BUS_FAIL; uint32 reg; volatile tstrHifHdr strHif; /* RX STEP (1) */ ret = hif_chip_wake(); if(ret == M2M_SUCCESS) { /* RX STEP (2) */ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0, ®); if(M2M_SUCCESS == ret) { /* New interrupt has been received */ if(reg & 0x1) { uint16 size; nm_bsp_interrupt_ctrl(0); /*Clearing RX interrupt*/ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0,®); if(ret != M2M_SUCCESS)goto ERR1; reg &= ~(1<<0); /* RX STEP (3) */ ret=nm_write_reg(WIFI_HOST_RCV_CTRL_0,reg); if(ret != M2M_SUCCESS)goto ERR1; /* read the rx size */ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0, ®); if(M2M_SUCCESS != ret) { M2M_ERR("(hif) WIFI_HOST_RCV_CTRL_0 bus fail\n"); nm_bsp_interrupt_ctrl(1); goto ERR1; } gu8HifSizeDone = 0; size = (uint16)((reg >> 2) & 0xfff); if (size > 0) { uint32 address = 0; /** start bus transfer **/ ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 87 /* RX STEP (4) */ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_1, &address); if(M2M_SUCCESS != ret) { M2M_ERR("(hif) WIFI_HOST_RCV_CTRL_1 bus fail\n"); nm_bsp_interrupt_ctrl(1); goto ERR1; } ret = nm_read_block(address, (uint8*)&strHif, sizeof(tstrHifHdr)); strHif.u16Length = NM_BSP_B_L_16(strHif.u16Length); if(M2M_SUCCESS != ret) { M2M_ERR("(hif) address bus fail\n"); nm_bsp_interrupt_ctrl(1); goto ERR1; } if(strHif.u16Length != size) { if((size - strHif.u16Length) > 4) { M2M_ERR("(hif) Corrupted packet Size = %u \n", size, strHif.u16Length, strHif.u8Gid, strHif.u8Opcode); nm_bsp_interrupt_ctrl(1); ret = M2M_ERR_BUS_FAIL; goto ERR1; } } /* RX STEP (5) */ if(M2M_REQ_GRP_WIFI == strHif.u8Gid) { if(pfWifiCb) { pfWifiCb(strHif.u8Opcode,strHif.u16Length - M2M_HIF_HDR_OFFSET, address + M2M_HIF_HDR_OFFSET); } } else if(M2M_REQ_GRP_IP == strHif.u8Gid) { if(pfIpCb) { pfIpCb(strHif.u8Opcode,strHif.u16Length - M2M_HIF_HDR_OFFSET, address + M2M_HIF_HDR_OFFSET); } } else if(M2M_REQ_GRP_OTA == strHif.u8Gid) { if(pfOtaCb) { pfOtaCb(strHif.u8Opcode,strHif.u16Length - M2M_HIF_HDR_OFFSET, address + M2M_HIF_HDR_OFFSET); } } else { M2M_ERR("(hif) invalid group ID\n"); ret = M2M_ERR_BUS_FAIL; goto ERR1; } /* RX STEP (6) */ if(!gu8HifSizeDone) { M2M_ERR("(hif) host app didn't set RX Done\n"); ret = hif_set_rx_done(); } } else { ret = M2M_ERR_RCV; M2M_ERR("(hif) Wrong Size\n"); goto ERR1; } } else ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 88 { #ifndef WIN32 M2M_ERR("(hif) False interrupt %lx",reg); #endif } } else { M2M_ERR("(hif) Fail to Read interrupt reg\n"); goto ERR1; } } else { M2M_ERR("(hif) FAIL to wakeup the chip\n"); goto ERR1; } /* RX STEP (7) */ ret = hif_chip_sleep(); ERR1: return ret; } • The appropriate handler in the Wi-Fi layer (called from the HIF layer). static void m2m_wifi_cb(uint8 u8OpCode, uint16 u16DataSize, uint32 u32Addr) { // …code eliminated… else if (u8OpCode == M2M_WIFI_RESP_SCAN_DONE) { tstrM2mScanDone strState; gu8scanInProgress = 0; if(hif_receive(u32Addr, (uint8*)&strState, sizeof(tstrM2mScanDone), 0) == M2M_SUCCESS) { gu8ChNum = strState.u8NumofCh; if (gpfAppWifiCb) gpfAppWifiCb(M2M_WIFI_RESP_SCAN_DONE, &strState); } } // …code eliminated… } • The Wi-Fi layer sends the response to the application through its callback function. if (u8MsgType == M2M_WIFI_RESP_SCAN_DONE) { tstrM2mScanDone *pstrInfo = (tstrM2mScanDone*) pvMsg; if( (gu8IsWiFiConnected == M2M_WIFI_DISCONNECTED) && (gu8WPS == WPS_DISABLED) && (gu8Prov == PROV_DISABLED) ) { gu8Index = 0; gu8Sleep = PS_WAKE; if (pstrInfo->u8NumofCh >= 1) { m2m_wifi_req_scan_result(gu8Index); gu8Index++; } else { m2m_wifi_request_scan(M2M_WIFI_CH_ALL); } } } ATWINC15x0 Host Interface (HIF) Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 89 14. WINC SPI Protocol The WINC main interface is SPI. The WINC device employs a protocol to allow exchange of formatted binary messages between the WINC firmware and the host MCU application. The WINC protocol uses raw bytes exchanged on the SPI bus to form high level structures like requests and callbacks. The WINC SPI protocol consists of three layers: • Layer 1 – the WINC SPI Slave protocol, which allows the host MCU application to perform register/ memory read and write operation in the ATWINC15x0 device using raw SPI data exchange. • Layer 2 – the host MCU application uses the register and memory read and write capabilities to exchange the host interface frames with the WINC firmware. It also provides asynchronous callback from the WINC firmware to the host MCU through interrupts and the host interface RX frames. For more information on this layer, refer to Section 15 “Host Interface (HIF) Protocol”. • Layer 3 – allows the host MCU application to exchange high level messages (for example, Wi-Fi scan, socket connection, or TCP data received) with the WINC firmware to employ in the host MCU application logic. Figure 14-1. WINC SPI Protocol Layers 14.1 Introduction The WINC SPI Protocol is implemented as a command-response transaction and assumes one party is the Master and the other is the Slave. The roles correspond to the Master and Slave devices on the SPI bus. Each message has an identifier in the first byte indicating the type of message: • Command • Response ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 90 • Data In the case of Command and Data messages, the last byte is used as data integrity check. The format of Command and Response and Data frames are described in the following sections. The following points apply: • There is a response for each command. • Transmitted/received data is divided into packets with fixed size. • For a WR transaction (Slave is receiving data packets), the Slave sends a response for each data packet. • For a RD transaction (Master is receiving data packets), the Master does not send a response. If there is an error, the Master requests a retransmission on the lost data packet. • Protection of commands and data packets by CRC is optional. 14.1.1 Command Format The following frame format is used for commands where the host supports a DMA address of three bytes. The first byte contains two fields: • The CMD/Data Start field indicates that this is a Command frame. • The CMD type field specifies the command to be executed. The CMD type may be one of 15 commands: • DMA write • DMA read • Internal register write • Internal register read • Transaction termination • Repeat data packet • DMA extended write • DMA extended read • DMA single-word write • DMA single-word read • Soft Reset The Payload field contains command specific data and its length depends on the CMD type. The CRC field is optional and generally computed in software. The Payload field can be one of four types each having a different length: • A: Three bytes • B: Five bytes • C: Six bytes • D: Seven bytes ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 91 Type A commands include: • DMA single-word RD • internal register RD • Transaction termination command • Repeat data PKT command • Soft Reset command Type B commands include: • DMA RD Transaction • DMA WR Transaction Type C commands include: • DMA Extended RD transaction • DMA Extended WR transaction • Internal register WR Type D commands include: • DMA single-word WR Full details of the frame format fields are provided in the following table: Table 14-1. Frame Format Fields Field Size Description CMD Start 4 bits Command Start: 4’b1100 CMD Type 4 bits Command type: 4’b0001: DMA write transaction 4’b0010: DMA read transaction 4’b0011: Internal register write 4’b0100: Internal register read 4’b0101: Transaction termination 4’b0110: Repeat data Packet command 4’b0111: DMA extended write transaction 4’b1000: DMA extended read transaction 4’b1001: DMA single-word write 4’b1010: DMA single-word read 4’b1111: Soft Reset command ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 92 ...........continued Field Size Description Payload A: 3 The Payload field may be of Type A, B, C, or D Type A (length 3) 1- DMA single-word RD Param: Read Address: Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] 2- internal register RD Param: Offset address (two bytes): Payload bytes: B0: OFFSET-ADDR[15:8] B1: OFFSET-ADDR[7:0] B2: 0 3- Transaction termination command Param: none Payload bytes: B0: 0 B1: 0 B2: 0 4- Repeat Data PKT command Param: none Payload bytes: B0: 0 B1: 0 B2: 0 5- Soft Reset command Param: none Payload bytes: B0: 0xFF B1: 0xFF B2: 0xFF ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 93 ...........continued Field Size Description Payload B: 5 Type B (length 5) 1- DMA RD Transaction Params: DMA Start Address: 3 bytes DMA count: 2 bytes Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] B3: COUNT[15:8] B4: COUNT[7:0] 2- DMA WR Transaction Params: DMA Start Address: 3 bytes DMA count: 2 bytes Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] B3: COUNT[15:8] B4: COUNT[7:0] ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 94 ...........continued Field Size Description Payload C: 6 Type C (length 6) 1- DMA Extended RD transaction Params: DMA Start Address: 3 bytes DMA extended count: 3 bytes Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] B3: COUNT[23:16] B4: COUNT[15:8] B5: COUNT[7:0] 2- DMA Extended WR transaction Params: DMA Start Address: 3 bytes DMA extended count: 3 bytes Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] B3: COUNT[23:16] B4: COUNT[15:8] B5: COUNT[7:0] ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 95 ...........continued Field Size Description Payload C: 6 3- Internal register WR* Params: Offset address: 3 bytes Write data: 3 bytes * “clocked or clockless registers” Payload bytes: B0: OFFSET-ADDR[15:8] B1: OFFSET-ADDR [7:0] B2: DATA[31:24] B3: DATA [23:16] B4: DATA [15:8] B5: DATA [7:0] Payload D: 7 Type D (length 7) 1- DMA single-word WR Params: Address: 3 bytes DMA Data: 4 bytes Payload bytes: B0: ADDRESS[23:16] B1: ADDRESS[15:8] B2: ADDRESS[7:0] B3: DATA[31:24] B4: DATA [23:16] B5: DATA [15:8] B6: DATA [7:0] CRC7 1 byte Optional data integrity field comprising two subfields: bit 0: fixed value ‘1’ bits 1-7: 7 bit CRC value computed using polynomial G(x) = X^7 + X^3 + 1 with seed value: 0x7F ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 96 The following table summarizes the different commands according to the payload type (DMA address = 3 bytes): Table 14-2. Commands in Payload Payload Type Payload Size Command Packet Size with CRC Commands Type A 3 bytes 5 bytes 1- DMA Single-Word Read 2- Internal Register Read 3- Transaction Termination 4- Repeat Data Packet 5- Soft Reset Type B 5 bytes 7 bytes 1- DMA Read 2- DMA Write Type C 6 bytes 8 bytes 1- DMA Extended Read 2- DMA Extended Write 3- Internal Register Write Type D 7 bytes 9 bytes 1- DMA Single-Word Write 14.1.2 Response Format The following frame format is used for responses sent by the WINC device as the result of receiving a Command or certain Data frames. The Response message has a fixed length of two bytes. The first byte contains two fields of four bits each to identify the response message and the response type. The second byte indicates the status of the WINC after receiving and, where possible, executing the command/data. This byte contains two sub fields: • B0-B3: Error state • B4-B7: DMA state States that may be indicated are: • DMA state: – DMA ready for any transaction – DMA engine is busy • Error state: – No error – Unsupported command – Receiving unexpected data packet – Command CRC7 error ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 97 Table 14-3. Response Format Field Size Description Response Start 4 bits Response Start : 4’b1100 Response Type 4 bits If the response packet is for Command: • Contains of copy of the Command Type field in the Command. If the response packet is for received Data Packet: • 4’b0001: first data packet is received • 4’b0010: Receiving data packets • 4’b0011: last data packet is received • 4’b1111: Reserved value State 1 byte This field is divided into two subfields: DMA State : • 4’b0000: DMA ready for any transaction • 4’b0001: DMA engine is busy Error State: • 4’b0000: No error • 4’b0001: Unsupported command • 4’b0010: Receiving unexpected data packet • 4’b0011: Command CRC7 error • 4’b0100: Data CRC16 error • 4’b0101: Internal general error 14.1.3 Data Packet Format The Data Packet Format is used in either direction (Master to Slave or Slave to Master) to transfer opaque data. A command frame is used either to inform the Slave that a data packet is about to be sent or to request the Slave to send a data packet to the Master. In the case of Master to Slave, the Slave sends a response after the command and each subsequent data frame. The format of a data packet is shown below. To support DMA hardware, a large data transfer may be fragmented into multiple smaller Data Packets. This is controlled by the value of DATA_PACKET_SIZE which is agreed between the Master and the Slave in software and is a fixed value such as 256B, 512B, 1KB (default), 2KB, 4KB, or 8KB. If a transfer has a length of m, which exceeds DATA_PACKET_SIZE, the sender must split it into multiple DATA_PACKET_SIZE as shown in Equation 1: ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 98 (m – (n-1)* DATA_PACKET_SIZE) -------------------------- Equation 1 Where, 1.. n-1 = length of the DATA_PACKET_SIZE n = frame length This is illustrated below. • If DMA count <= DATA_PACKET_SIZE: The data packet is “DATA_Header + DMA count +optional CRC16“, that is no padding. • If DMA count > DATA_PACKET_SIZE: • If remaining data < DATA_PACKET_SIZE, the last data packet is: “DATA_Header + remaining data + optional CRC16 “, that is no padding. The frame fields are described in detail in the following table: Table 14-4. Frame Field Field Size Description Data Start 4 bits 4’b1111 (Default) (Can be changed to any value by programming DATA_START_CTRL register) Packet Order 4 bits 4’b0001: First packet in this transaction 4’b0010: Neither the first or the last packet in this transaction 4’b0011: Last packet in this transaction 4’b1111: Reserved Data bytes DATA_PACKET_SIZE User data CRC16 2 bytes Optional data integrity field comprising a 16-bit CRC value encoded in two bytes. The most significant 8 bits are transmitted first in the frame. The CRC16 value is computed on data bytes only based on the polynomial: G(x) = X^16 + X^12 + X^5 + 1, seed value: 0xFFFF ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 99 14.1.4 Error Recovery Mechanism Table 14-5. Error Recovery Mechanism Error Type Recovery Mechanism Master CRC error in command 1. Error response received from Slave. 2. Retransmit the command. CRC error in received data 1. Issue a repeat command for the data packet that has a CRC error. 2. Slave sends a response to the previous command. 3. Slave keeps the start DMA address of the previous data packet, so it can retransmit it. 4. Receive the data packet again. No response is received from Slave • Synchronization is lost between the Master and Slave. • The worst case is when Slave is in receiving data state. • Solution: The Master must wait for max DATA_PACKET_SIZE period then generate a Soft Reset command. Unexpected response Retransmit the command. TX/RX Data count error Retransmit the command. No response to Soft Reset command • Transmit all ones until Master receives a response of all ones from the Slave. • Then deactivate the output data line. Slave Unsupported command • Send response with error. • Returns to command monitor state. Receive command CRC error • Send response with error. • Wait for command retransmission. Received data CRC error • Send response with error. • Wait for retransmission of the data packet. Internal general error • The Master must do a Soft Reset on the Slave. TX/RX Data count error • Only the Master can detect this error. • Slave operates with the data count received until the count finishes or the Master terminates the transaction. • In both cases, the Master can retry the command from the start. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 100 ...........continued Error Type Recovery Mechanism No response to Soft Reset command 1. First received 4’b1001, it decides data start. 2. Then received packet order 4’b1111 that is reserved value. 3. Then monitors for 7 bytes all ones to decide Soft Reset action. 4. The Slave must activate the output data line. 5. Waits for deactivation for the received line. 6. The Slave then deactivates the output data line and returns to the CMD/ DATA start monitor state. General Notes • The Slave must monitor the received line for command reception at any time. • When a CMD start is detected, the Slave receives 8 bytes then return again to the command reception state. • When the Slave is transmitting data, it must also monitor for command reception. • When the Slave is receiving data, it monitors for command reception between the data packets. • Issuing a Soft Reset command is detected in all cases. 14.1.5 Clockless Registers Access Clockless register access allows a host device to access registers on the WINC device while it is held in a reset state. This type of access can only be done using the “internal register read” and “internal register write” commands. For clockless access, bit 15 of the Offset_addr in the command must be ‘1’ to differentiate between the Clockless and Clocked access mode. For Clockless register write: - the protocol Master must wait for the response as shown here: For Clockless register read: - according to the interface, the protocol Slave may not send CRC16. One or two byte padding depends on three or four byte DMA addresses. 14.2 Message Flow for Basic Transactions This section shows the essential message exchanges and timings associated with the following commands: • Read Single Word • Read Internal Register (clockless) ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 101 • Read Block • Write Single Word • Write Internal Register (clockless) • Write Bock 14.2.1 Read Single Word 14.2.2 Read Internal Register (for clockless registers) 14.2.3 Read Block Normal transaction: Master － issues a DMA read transaction and waits for a response. Slave － sends a response after CMD_RES_PERIOD. Master － waits for a data packet start. Slave － sends the data packets, separated by DATA_DATA_PERIOD[1] where DATA_DATA_PERIOD is controlled by software and has one of these values: NO_DELAY (default), 4_BYTE_PERIOD, 8_BYTE_PERIOD, and 16_BYTE_PERIOD. Slave － continues sending until the count ends. Master － receives data packets. No response is sent for data packets but a termination/retransmit command may be sent if there is an error. The message sequence for this case is shown below: Termination command is issued: Master － can issue a termination command at any time during the transaction. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 102 Master － monitors for RES_START after CMD_RESP_PERIOD. Slave － cuts off the current running data packet if there is any. Slave － responds to the termination command after CMD_RESP_PERIOD from the end of the termination command packet. Repeat command is issued: 1. Master － can issue a repeat command at any time during the transaction. 2. Master － monitors for RES_START after CMD_RESP_PERIOD. 3. Slave － cuts off the current running data packet, if any. 4. Slave － responds to the repeat command after CMD_RESP_PERIOD from the end of the repeat command packet. 5. Slave － sends the data packet again that has an error then continues the transaction as normal. [1] The period between the data packets is “DATA_DATA_PERIOD + DMA access time.” The Master monitors for DATA_START directly after DATA_DATA_PERIOD. 14.2.4 Write Single Word 1. Master － issues DMA single-word write command, including the data. 2. Slave － takes the data and sends a command response. 14.2.5 Write Internal Register (for clockless registers) 1. Master － issues an internal register write command, including the data. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 103 2. Slave － takes the data and sends a command response. 14.2.6 Write Block • Case 1: Master waits for a command response: 1.1. Master － issues a DMA write command and waits for a response. 1.2. Slave － sends response after CMD_RES_PERIOD. 1.3. Master － sends the data packets after receiving response. 1.4. Slave － sends a response packet for each data packet received after DATA_RES_PERIOD. 1.5. Master － does not wait for the data response before sending the following data packet notes: CMD_RES_PERIOD is controlled by SW taking one of the values: NO_DELAY (default), 1_BYTE_PERIOD, 2_BYTE_PERIOD and 3_BYTE_PERIOD The Master must monitor for RES_START after CMD_RES_PERIOD DATA_RES_PERIOD is controlled by SW taking one of the values: NO_DELAY (default), 1_BYTE_PERIOD, 2_BYTE_PERIOD and 3_BYTE_PERIOD • Case 2: Master does not wait for a command response: 2.1. Master － sends the data packets directly after the command but it still monitors for a command response after CMD_RESP_PERIOD. 2.2. Master － retransmits the data packets if there is an error in the command. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 104 14.3 SPI Level Protocol Example To illustrate how the WINC SPI protocol works, the SPI bytes from the scan request example are dumped and the sequence is described below. 14.3.1 TX (Send Request) 1. First step in hif_send() API is to wake up the chip. sint8 nm_clkless_wake(void) { ret = nm_read_reg_with_ret(0x1, ®); /* Set bit 1 */ ret = nm_write_reg(0x1, reg | (1 << 1)); // Check the clock status ret = nm_read_reg_with_ret(clk_status_reg_adr, &clk_status_reg); // Tell Firmware that Host waked up the chip ret = nm_write_reg(WAKE_REG, WAKE_VALUE); return ret; } Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 2. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. 3. The WINC chip sends the value of the register 0x01 which equals 0x01. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 105 Command CMD_INTERNAL_WRITE: C3 /* internal register write */ BYTE [0] = CMD_INTERNAL_WRITE BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = u32data >> 24; /* Data = 0x03 */ BYTE [4] = u32data >> 16; BYTE [5] = u32data >> 8; BYTE [6] = u32data; 4. The WINC acknowledges the command by sending two bytes [C3] [0]. Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x0F */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 5. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. 6. The WINC chip sends the value of the register 0x01 which equals 0x07. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 106 Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WAKE_REG address = 0x1074 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* WAKE_VALUE Data = 0x5678 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; 7. The chip acknowledges the command by sending two bytes [C9] [0]. 8. At this point, HIF finishes executing the clockless wake up of the WINC chip. 9. The HIF layer prepares and sets the HIF layer header to NMI_STATE_REG register (4 byte or 8 byte header describing the packet to be sent). 10. Set bit '1' of WIFI_HOST_RCV_CTRL_2 register to raise an interrupt to the chip. sint8 hif_send(uint8 u8Gid,uint8 u8Opcode,uint8 *pu8CtrlBuf,uint16 u16CtrlBufSize, uint8 *pu8DataBuf,uint16 u16DataSize, uint16 u16DataOffset) { volatile tstrHifHdr strHif; volatile uint32 reg; strHif.u8Opcode = u8Opcode&(~NBIT7); strHif.u8Gid = u8Gid; strHif.u16Length = M2M_HIF_HDR_OFFSET; strHif.u16Length += u16CtrlBufSize; ret = nm_clkless_wake(); reg = 0UL; reg |= (uint32)u8Gid; reg |= ((uint32)u8Opcode<<8); reg |= ((uint32)strHif.u16Length<<16); ret = nm_write_reg(NMI_STATE_REG,reg); ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 107 reg = 0; reg |= (1<<1); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_2, reg); Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* NMI_STATE_REG address = 0x108c */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* Data = 0x000C3001 */ BYTE [5] = u32data >> 16; /* 0x0C is the length and equals 12 */ BYTE [6] = u32data >> 8; /* 0x30 is the Opcode = M2M_WIFI_REQ_SET_SCAN_REGION */ BYTE [7] = u32data; /* 0x01 is the Group ID = M2M_REQ_GRP_WIFI */ 11. The WINC acknowledges the command by sending two bytes [C9] [0]. Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_2address = 0x1078*/ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* Data = 0x02 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 108 12. The WINC acknowledges the command by sending two bytes [C9] [0]. 13. Then HIF polls for DMA address. for (cnt = 0; cnt < 1000; cnt ++) { ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_2,(uint32 *)®); if(ret != M2M_SUCCESS) break; if (!(reg & 0x2)) { ret = nm_read_reg_with_ret(0x150400,(uint32 *)&dma_addr); /*in case of success break */ break; } } Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_2 address = 0x1078 */ BYTE [2] = address >> 8; BYTE [3] = address; 14. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 15. The WINC chip sends the value of the register 0x1078, which equals 0x00. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 109 Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* address = 0x1504 */ BYTE [2] = address >> 8; BYTE [3] = address; 16. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 17. The WINC chip sends the value of the register 0x1504, which equals 0x037AA0. 18. The WINC writes the HIF header to the DMA memory address. u32CurrAddr = dma_addr; strHif.u16Length=NM_BSP_B_L_16(strHif.u16Length); ret = nm_write_block(u32CurrAddr, (uint8*)&strHif, M2M_HIF_HDR_OFFSET); Command CMD_DMA_EXT_WRITE: 0xC7 /* DMA extended write */ BYTE [0] = CMD_DMA_EXT_WRITE BYTE [1] = address >> 16; /* address = 0x037AA0 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = size >> 16; /* size = 0x08 */ BYTE [5] = size >> 8; BYTE [6] = size; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 110 19. The WINC acknowledges the command by sending three bytes [C7] [0] [F3]. 20. The HIF layer writes the data. 21. The HIF writes the Control Buffer data (part of the framing of the request). if (pu8CtrlBuf != NULL) { ret = nm_write_block(u32CurrAddr, pu8CtrlBuf, u16CtrlBufSize); if(M2M_SUCCESS != ret) goto ERR1; u32CurrAddr += u16CtrlBufSize; } Command CMD_DMA_EXT_WRITE: 0xC7 /* DMA extended write */ BYTE [0] = CMD_DMA_EXT_WRITE BYTE [1] = address >> 16; /* address = 0x037AA8 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = size >> 16; /* size = 0x04 */ BYTE [5] = size >> 8; BYTE [6] = size; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 111 22. The WINC acknowledges the command by sending three bytes [C7] [0] [F3]. 23. The HIF layer writes the data. 24. The HIF finished writing the request data to memory and is going to interrupt the chip notifying that host TX is done. reg = dma_addr << 2; reg |= (1 << 1); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_3, reg); Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_3 address = 0x106C */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* Data = 0x000DEA82 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 112 25. The WINC acknowledges the command by sending two bytes [C9] [0]. 26. The HIF layer allows the chip to enter Sleep mode again. sint8 hif_chip_sleep(void) { sint8 ret = M2M_SUCCESS; uint32 reg = 0; ret = nm_write_reg(WAKE_REG, SLEEP_VALUE); /* Clear bit 1 */ ret = nm_read_reg_with_ret(0x1, ®); if(reg&0x2) { reg &=~(1 << 1); ret = nm_write_reg(0x1, reg); } } Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WAKE_REG address = 0x1074 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* SLEEP_VALUE Data = 0x4321 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; 27. The WINC acknowledges the command by sending two bytes [C9] [0]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 113 Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 28. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. 29. The WINC chip sends the value of the register 0x01 which equals 0x03. Command CMD_INTERNAL_WRITE: C3 /* internal register write */ BYTE [0] = CMD_INTERNAL_WRITE BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = u32data >> 24; /* Data = 0x01 */ BYTE [4] = u32data >> 16; BYTE [5] = u32data >> 8; BYTE [6] = u32data; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 114 30. The WINC chip acknowledges the command by sending two bytes [C3] [0]. 31. At this point, the HIF layer has completed posting the scan Wi-Fi request to the WINC chip for processing. 14.3.2 RX (Receive Response) After finishing the required operation (scan Wi-Fi), the WINC interrupts the host to notify of the processing of the request. The host handles this interrupt to receive the response. 1. First step in hif_isr is to wake up the WINC chip. sint8 nm_clkless_wake(void) { ret = nm_read_reg_with_ret(0x1, ®); /* Set bit 1 */ ret = nm_write_reg(0x1, reg | (1 << 1)); // Check the clock status ret = nm_read_reg_with_ret(clk_status_reg_adr, &clk_status_reg); // Tell Firmware that Host waked up the chip ret = nm_write_reg(WAKE_REG, WAKE_VALUE); return ret; } Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 2. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 115 3. The WINC chip sends the value of the register 0x01 which equals 0x01. Command CMD_INTERNAL_WRITE: C3 /* internal register write */ BYTE [0] = CMD_INTERNAL_WRITE BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = u32data >> 24; /* Data = 0x03 */ BYTE [4] = u32data >> 16; BYTE [5] = u32data >> 8; BYTE [6] = u32data; 4. The WINC acknowledges the command by sending two bytes [C3] [0]. Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x0F */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 5. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 116 6. Then WINC chip sends the value of the register 0x01 which equals 0x07. Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WAKE_REG address = 0x1074 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* WAKE_VALUE Data = 0x5678 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; 7. The chip acknowledges the command by sending two bytes [C9] [0]. 8. Read register WIFI_HOST_RCV_CTRL_0 to check if there is a new interrupt, and clear it. static sint8 hif_isr(void) { sint8 ret ; uint32 reg; volatile tstrHifHdr strHif; ret = hif_chip_wake(); ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0, ®); if(reg & 0x1) /* New interrupt has been received */ ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 117 { uint16 size; /*Clearing RX interrupt*/ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0,®); reg &= ~(1<<0); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_0,reg); Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; 9. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 10. The WINC chip sends the value of the register 0x1070 which equals 0x31. Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; 11. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 118 12. The WINC chip sends the value of the register 0x1070 which equals 0x31. 13. Clear the WINC Interrupt. Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* Data = 0x30 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; 14. The chip acknowledges the command by sending two bytes [C9] [0]. 15. The HIF reads the data size. /* read the rx size */ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0, ®); Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 119 16. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 17. The WINC chip sends the value of the register 0x1070 which equals 0x30. 18. The HIF reads hif header address. /** start bus transfer**/ ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_1, &address); Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_1 address = 0x1084 */ BYTE [2] = address >> 8; BYTE [3] = address; 19. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 20. The WINC chip sends the value of the register 0x1078 which equals 0x037AB0. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 120 21. The HIF reads the hif header data (as a block). ret = nm_read_block(address, (uint8*)&strHif, sizeof(tstrHifHdr)); Command CMD_DMA_EXT_READ: C8 /* dma extended read */ BYTE [0] = CMD_DMA_EXT_READ BYTE [1] = address >> 16; /* address = 0x037AB0*/ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = size >> 16; BYTE [5] = size >>; BYTE [6] = size; 22. The WINC acknowledges the command by sending three bytes [C8] [0] [F3]. 23. The WINC sends the data block (four bytes). 24. The HIF calls the appropriate handler according to the hif header received which tries to receive the Response data payload. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 121 Note:  hif_receive obtains additional data. sint8 hif_receive(uint32 u32Addr, uint8 *pu8Buf, uint16 u16Sz, uint8 isDone) { uint32 address, reg; uint16 size; sint8 ret = M2M_SUCCESS; ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0,®); size = (uint16)((reg >> 2) & 0xfff); ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_1,&address); /* Receive the payload */ ret = nm_read_block(u32Addr, pu8Buf, u16Sz); } Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; 25. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 26. The WINC chip sends the value of the register 0x1070 which equals 0x30. Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_1 address = 0x1084 */ BYTE [2] = address >> 8; BYTE [3] = address; 27. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 122 28. The WINC chip sends the value of the register 0x1078 which equals 0x037AB0. Command CMD_DMA_EXT_READ: C8 /* dma extended read */ BYTE [0] = CMD_DMA_EXT_READ BYTE [1] = address >> 16; /* address = 0x037AB8*/ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = size >> 16; BYTE [5] = size >>; BYTE [6] = size; 29. The WINC acknowledges the command by sending three bytes [C8] [0] [F3]. 30. The WINC sends the data block (four bytes). ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 123 31. After the HIF layer received the response, it interrupts the chip to send the notification that the host RX is done. static sint8 hif_set_rx_done(void) { uint32 reg; sint8 ret = M2M_SUCCESS; ret = nm_read_reg_with_ret(WIFI_HOST_RCV_CTRL_0,®); /* Set RX Done */ reg |= (1<<1); ret = nm_write_reg(WIFI_HOST_RCV_CTRL_0,reg); } Command CMD_SINGLE_READ: 0xCA /* single word (4 bytes) read */ BYTE [0] = CMD_SINGLE_READ BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; 32. The WINC acknowledges the command by sending three bytes [CA] [0] [F3]. 33. The WINC chip sends the value of the register 0x1070 which equals 0x30. Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WIFI_HOST_RCV_CTRL_0 address = 0x1070 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* Data = 0x32*/ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 124 34. The chip acknowledges the command by sending two bytes [C9] [0]. 35. The HIF layer allows the chip to enter Sleep mode again. sint8 hif_chip_sleep(void) { sint8 ret = M2M_SUCCESS; uint32 reg = 0; ret = nm_write_reg(WAKE_REG, SLEEP_VALUE); /* Clear bit 1 */ ret = nm_read_reg_with_ret(0x1, ®); if(reg&0x2) { reg &=~(1 << 1); ret = nm_write_reg(0x1, reg); } } Command CMD_SINGLE_WRITE:0XC9 /* single word write */ BYTE [0] = CMD_SINGLE_WRITE BYTE [1] = address >> 16; /* WAKE_REG address = 0x1074 */ BYTE [2] = address >> 8; BYTE [3] = address; BYTE [4] = u32data >> 24; /* SLEEP_VALUE Data = 0x4321 */ BYTE [5] = u32data >> 16; BYTE [6] = u32data >> 8; BYTE [7] = u32data; 36. The WINC acknowledges the command by sending two bytes [C9] [0]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 125 Command CMD_INTERNAL_READ: 0xC4 /* internal register read */ BYTE [0] = CMD_INTERNAL_READ BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = 0x00; 37. The WINC acknowledges the command by sending three bytes [C4] [0] [F3]. 38. Then WINC chip sends the value of the register 0x01 which equals 0x03. Command CMD_INTERNAL_WRITE: C3 /* internal register write */ BYTE [0] = CMD_INTERNAL_WRITE BYTE [1] = address >> 8; /* address = 0x01 */ BYTE [1] |= (1 << 7); /* clockless register */ BYTE [2] = address; BYTE [3] = u32data >> 24; /* Data = 0x01 */ BYTE [4] = u32data >> 16; BYTE [5] = u32data >> 8; BYTE [6] = u32data; 39. The WINC chip acknowledges the command by sending two bytes [C3] [0]. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 126 40. Scan Wi-Fi request is sent to the WINC chip and the response is successfully sent to the host. ATWINC15x0 WINC SPI Protocol © 2018 Microchip Technology Inc. User Guide DS00002389B-page 127 15. Appendix A. How to Generate Certificates 15.1 Introduction This chapter explains the required procedures to create and sign custom certificates using OpenSSL. To use this guide you must install OpenSSL on your machine. OpenSSL is an open-source implementation of the SSL and TLS protocols. The core library, written in the C programming language, implements basic cryptographic functions and provides various utility functions. OpenSSL can be downloaded from the following URL: https://www.openssl.org/related/binaries.html. 15.2 Steps After installing OpenSSL, open a CMD prompt and navigate to the directory where OpenSSL was installed (For example: C:\OpenSSL-Win64\bin). 1. Generate a key for the CA (certification authority). To generate a 4096-bit long RSA (creates a new file CA_KEY.key to store the random key), using the following command (CMD): openssl genrsa -out CA_KEY.key 4096 2. Create your self-signed root CA certificate CA_CERT.crt; you need to provide some data for your Root certificate, using the following command (CMD): openssl req -new -x509 -days 1826 -key CA_KEY.key -out CA_CERT.crt 3. Create the custom certificate, which is signed by the CA root certificate created earlier. First, generate the Custom.key, using the following command (CMD): openssl genrsa -out Custom.key 4096 4. To generate a certificate request file (CSR) using this generated key, use the following command (CMD): openssl req -new -key Custom.key -out CertReq.csr 5. Process the request for the certificate and get it signed by the root CA, using the following command (CMD): openssl x509 -req -days 730 -in CertReq.csr -CA CA_CERT.crt -CAkey CA_KEY.key - set_serial 01 -out CustomCert.crt 15.3 Limitations The following are the limitations of BigInt_ModExp() API. 1. DHE greater than 2048-bit is not supported. 2. RSA signature verification greater than 2048-bit is done in software; 4096-bit takes 4 seconds per verification, assuming a typical public key of 2^16+1. 3. RSA signature generation greater than 2048-bit is not supported. ATWINC15x0 Appendix A. How to Generate Certificates © 2018 Microchip Technology Inc. User Guide DS00002389B-page 128 16. Appendix B. X.509 Certificate Format and Conversion 16.1 Introduction The most known encodings for the X.509 digital certificates are PEM and DER formats. The PEM format is base64 encoding of the DER enclosed with messages "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----". 16.2 Conversion Between Different Formats The current implementation of the WINC root_certificate_downloader supports only DER format. If the certificate is not in DER format, it must be converted first. The conversion between different formats are done in several methods: 16.2.1 Using Windows From Windows® 7, double click on the .crt certificate file and then go to the Details Tab and press “Copy to File”. Follow the Certificate Export Wizard until the Finish button. 16.2.2 Using OpenSSL The OpenSSL is used for certificate conversion by the following command. openssl x509 -outform der -in certificate.pem -out certificate.der ATWINC15x0 Appendix B. X.509 Certificate Format and C... © 2018 Microchip Technology Inc. User Guide DS00002389B-page 129 16.2.3 Online Conversion There are useful online tools which provide conversion between the certificate formats, which can be found through searching online using keywords such as "OpenSSL". ATWINC15x0 Appendix B. X.509 Certificate Format and C... © 2018 Microchip Technology Inc. User Guide DS00002389B-page 130 17. References The following documents can be used for further study: • ATWINC15x0 Wi-Fi Network Controller Software Programming Guide • ATWINC15x0-MR210xB Data Sheet The following web page can be referred for further study on API: • Atmel Software Framework for ATWINC1500 (Wi-Fi) ATWINC15x0 References © 2018 Microchip Technology Inc. User Guide DS00002389B-page 131 18. Document Revision History Rev B - 10/2018 Section Changes 6.2.3.12 setsockopt Added SOL_SSL_SOCKET information with example. 10. Over-The-Air Upgrade Removed “no HTTPS supported” from the chapter. 8.5 AP Mode Code Example Added Power Save note. Document Removed the content related to Wi-Fi Direct mode and Wi-Fi Sniffer mode. 4.2 WINC Modes of Operation Updated WINC modes of operation. 8.1 Overview and 8.2 Setting the WINC AP Mode Updated the Wi-Fi AP mode chapter corresponding to WINC1500 v19.6.1 firmware. 5. Wi-Fi Station Mode Added support for Encrypted Credential Storage, Simple Roaming, Multiple Gain Table, and Host File Download for Wi-Fi Station mode. Rev A - 05/2017 Section Changes Document • Updated from Atmel to Microchip template. • Assigned a new Microchip document number. Previous version is Atmel 42420 revision B. • ISBN number added. ATWINC15x0 Document Revision History © 2018 Microchip Technology Inc. User Guide DS00002389B-page 132 The Microchip Web Site Microchip provides online support via our web site at http://www.microchip.com/. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives Customer Change Notification Service Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at http://www.microchip.com/. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. Customer Support Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or Field Application Engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support Microchip Devices Code Protection Feature Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 133 • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Legal Notice Information contained in this publication 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 unless otherwise stated. Trademarks The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BitCloud, chipKIT, chipKIT logo, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq, Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB, OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, SAM-BA, SpyNIC, SST, SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of Microchip Technology Incorporated in the U.S.A. Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, memBrain, Mindi, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 134 © 2018, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 978-1-5224-3632-4 Quality Management System Certified by DNV ISO/TS 16949 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. ATWINC15x0 © 2018 Microchip Technology Inc. User Guide DS00002389B-page 135 AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Tel: 317-536-2380 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 Tel: 951-273-7800 Raleigh, NC Tel: 919-844-7510 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Tel: 408-436-4270 Canada - Toronto Tel: 905-695-1980 Fax: 905-695-2078 Australia - Sydney Tel: 61-2-9868-6733 China - Beijing Tel: 86-10-8569-7000 China - Chengdu Tel: 86-28-8665-5511 China - Chongqing Tel: 86-23-8980-9588 China - Dongguan Tel: 86-769-8702-9880 China - Guangzhou Tel: 86-20-8755-8029 China - Hangzhou Tel: 86-571-8792-8115 China - Hong Kong SAR Tel: 852-2943-5100 China - Nanjing Tel: 86-25-8473-2460 China - Qingdao Tel: 86-532-8502-7355 China - Shanghai Tel: 86-21-3326-8000 China - Shenyang Tel: 86-24-2334-2829 China - Shenzhen Tel: 86-755-8864-2200 China - Suzhou Tel: 86-186-6233-1526 China - Wuhan Tel: 86-27-5980-5300 China - Xian Tel: 86-29-8833-7252 China - Xiamen Tel: 86-592-2388138 China - Zhuhai Tel: 86-756-3210040 India - Bangalore Tel: 91-80-3090-4444 India - New Delhi Tel: 91-11-4160-8631 India - Pune Tel: 91-20-4121-0141 Japan - Osaka Tel: 81-6-6152-7160 Japan - Tokyo Tel: 81-3-6880- 3770 Korea - Daegu Tel: 82-53-744-4301 Korea - Seoul Tel: 82-2-554-7200 Malaysia - Kuala Lumpur Tel: 60-3-7651-7906 Malaysia - Penang Tel: 60-4-227-8870 Philippines - Manila Tel: 63-2-634-9065 Singapore Tel: 65-6334-8870 Taiwan - Hsin Chu Tel: 886-3-577-8366 Taiwan - Kaohsiung Tel: 886-7-213-7830 Taiwan - Taipei Tel: 886-2-2508-8600 Thailand - Bangkok Tel: 66-2-694-1351 Vietnam - Ho Chi Minh Tel: 84-28-5448-2100 Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 Finland - Espoo Tel: 358-9-4520-820 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Garching Tel: 49-8931-9700 Germany - Haan Tel: 49-2129-3766400 Germany - Heilbronn Tel: 49-7131-67-3636 Germany - Karlsruhe Tel: 49-721-625370 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Rosenheim Tel: 49-8031-354-560 Israel - Ra’anana Tel: 972-9-744-7705 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Padova Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Norway - Trondheim Tel: 47-72884388 Poland - Warsaw Tel: 48-22-3325737 Romania - Bucharest Tel: 40-21-407-87-50 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 Sweden - Gothenberg Tel: 46-31-704-60-40 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service © 2018 Microchip Technology Inc. User Guide DS00002389B-page 136

MPLAB Harmony Help MPLAB Harmony Copyright (c) 2013 Microchip Technology Inc. All rights reserved. Table of Contents 1 Start Here 1-1 MPLAB Harmony Help 1 1 Start Here This topic describes how to get started using the MPLAB Harmony Integrated Software Framework. 1. First Time Users Name Description Before You Start Before you start using MPLAB Harmony, be sure to install the MPLAB X IDE Plug-In modules. What is MPLAB Harmony? This topic provides an overview of key concepts necessary to understand the MPLAB Harmony architecture. Project Layout This topic explains how an MPLAB Harmony project is organized. The Main File This topic describes the logic of the "main.c" file and the C-language "main" function in an MPLAB Harmony project. The Application File(s) This topic describes the normal structure of MPLAB Harmony application files. More Information Describes what is available from the MPLAB Harmony web page. Description Software Building Blocks MPLAB Harmony is a framework of software modules that serve as building blocks for your application. If this is the first time you've used MPLAB Harmony, the "First Time Users" section is the best place to start learning. If you're an experienced MPLAB Harmony developer, be sure to look at the "Release Notes & Information" section to find out what is in this release and what is new. 1 MPLAB Harmony Help 1-1 1.1 1. First Time Users 1.1.1 Before You Start Before you start using MPLAB Harmony, be sure to install the MPLAB X IDE Plug-In modules. Description Before you start using MPLAB Harmony, you should install the following MPLAB X IDE plug in modules, included in the MPLAB Harmony installation. 1. The MPLAB Harmony "Help" plug-in module. (Located at: /doc/org-microchip-harmony_help.nbm) 2. The MPLAB Harmony Configurator plug-in module. (Located at: /utilities/configurator/com-microchip-harmonyconfigurator.nbm) Installing the Plug In Modules 1. Start MPLAB X IDE and select "Plugins" from the "Tools" menu as shown below. 2. Click the "Add Plugins..." button, navigate to and open the "com-microchip-harmonyconfigurator.nbm" plug-in file, as shown below. 1.1 1. First Time Users MPLAB Harmony Help Before You Start 1-2 3. Ensure that the box under "Install" for the "MPLAB Harmony Configurator" plug-in is selected and click "Install" as shown below. 1.1 1. First Time Users MPLAB Harmony Help Before You Start 1-3 4. Follow the prompts from the installation and continue until the installation completes. (Do not worry if the version you're installing is "signed" but not "trusted". Just click "continue"). Once the installation has finished you can close the "Plugins" dialog box. You should now see a "MPLAB Harmony Configurator" option under the "Tools" menu. This indicates that the project Configurator has been successfully installed. 1.1.2 What is MPLAB Harmony? This topic provides an overview of key concepts necessary to understand the MPLAB Harmony architecture. Description Introduction Microchip MPLAB® Harmony is the result of a holistic, aggregate approach to creating firmware solutions for embedded systems using Microchip microcontrollers. MPLAB® Harmony Block Diagram 1.1 1. First Time Users MPLAB Harmony Help What is MPLAB Harmony? 1-4 MPLAB Harmony Overview Designed almost completely in the C language (with support for C++), MPLAB Harmony takes key elements of modular and object-oriented design, adds in the flexibility to use a Real-Time Operating System (RTOS) or work without one if you prefer, and provides a framework of software modules that are easy to use, configurable for your specific needs, and that work together in complete harmony. Portability Portability is a concern that is often overlooked when a silicon manufacturer provides software. However, breadth of solutions is a hallmark strength of Microchip, and MPLAB Harmony provides simple libraries to abstract away part-specific details and make Microchip microcontrollers easy to use, regardless of which part you choose. Any time you design a new product or update an existing one you have to balance capabilities against cost, but cost is more than just the bill of materials. It’s also the Non-Refundable Engineering (NRE) cost to design and develop your solution. MPLAB Harmony provides peripheral libraries, device drivers, and other libraries that use clear and consistent interfaces, requiring little or no change in your application code and minimizing the engineering time and effort for each new design. Device Drivers The primary purpose of an MPLAB Harmony device driver (or “driver”) is to provide a simple and highly abstracted interface to a peripheral, allowing your application (or other module in the system) to interact with a peripheral through a consistent set of functions. A device driver is responsible for managing access to a peripheral, so that requests from different modules do not conflict with each other, and for managing the state of that peripheral so that it always operates correctly. Peripheral Libraries A Peripheral Library (PLIB) is a simple access library that provides a consistent (but very low level) interface to a peripheral that is “on board” the microcontroller. PLIBs hide register details, making it easier to write drivers that support multiple microcontroller families, but they are not normally used by applications directly to interact with peripherals, as they provide little abstraction, and because they require the caller to manage the detailed operation of a peripheral (including preventing conflicting requests from other modules). Because of the lack of conflict protection in a PLIB, only one module in a system should directly access the PLIB for a peripheral. Therefore, PLIBs are primarily used to implement device drivers (and some system services) to make them portable. Modularity MPLAB Harmony libraries are modular software “building blocks” that allow you to divide-and-conquer your firmware design. The interface to each library consists of a highly cohesive set of functions (not globally accessible variables or shared registers), so that each module can manage its own resources. If one module needs to use the resources of another module, it calls that module’s interface functions to do so. Interfaces between modules are kept simple with minimal inter-dependencies so that modules are loosely coupled to each other. This approach helps to eliminate conflicts between modules and allows them to be more easily used together like building blocks to create the solutions you need. 1.1 1. First Time Users MPLAB Harmony Help What is MPLAB Harmony? 1-5 Middleware Libraries The normal usage models of some of the more complex peripherals, (i.e., USB or network interfaces) requires interpreting complex protocols or may require substantial additional processing to produce useable results, such as drawing graphical images on an LCD screen with an LCD controller peripheral. Therefore, while a device driver may be completely sufficient for a simple peripheral like a UART, some peripherals require what is frequently called “middleware” (aptly named because it sits between your application and the hardware abstraction layer or “driver” layer). MPLAB Harmony provides several middleware library “stacks” to manage these more complex peripherals and provide the functionality you need and expect. MPLAB Harmony middleware “stacks” are usually built upon device drivers and system services (explained below) so that they can be supported on any Microchip microcontroller for which the required driver or service is supported. However, special purpose implementations may be available that integrate the driver, certain services, and various modules within the “stack” for efficiency. System Services MPLAB Harmony system services are responsible for managing shared resources so that other modules (drivers, middleware, and applications) do not conflict on shared resources. For example, if the TCP/IP, USB, and Graphics stacks attempted to concurrently use the Timer2 peripheral to perform some periodic task, they would very likely interfere with each other. However, if instead they used a timer system service (as the following image illustrates), it is the responsibility of the system service to keep the separate requests from interfering with each other. The timer service can be configured as desired for a specific system (for example, you might decide to use Timer3 instead of Timer2) isolating the necessary changes to the configuration of a single module and preventing potential conflicts. The use of a system service is very similar the use of a device driver, except that a driver normally requires the caller to “open” it to create unique client-to-driver association. A system service does not normally require the caller to open the service before using it because system services are frequently shared by many clients within the system. Compatibility MPLAB Harmony modules (drivers, system services, and middleware – excluding PLIBs) are “active”. This means when an application calls a module’s interface function, the call will usually return immediately and the module will continue working on its own to complete the operation. Most modules will then provide a notification mechanism so the caller (i.e., client) can determine when the operation has finished. Harmony modules are implemented as cooperative state machines. The following image shows the basic idea of how this works. Each module has an “Initialize” function and each module has one (or more) “Tasks” function(s) to maintain its state machine(s). The state machines of all modules are initialized, shortly after the system comes out of reset in “main”. After that (in a polled 1.1 1. First Time Users MPLAB Harmony Help What is MPLAB Harmony? 1-6 configuration, with no OS), the system drops into a “super loop” where each module’s state machine function is repeatedly called, one after the other, to allow it to do the next “task” necessary to keep its state machine running. This allows the system to keep all modules running using a cooperative or shared “multi-tasking” technique. Modules (under control of your application) interact with each other by calling the interface functions of other modules (as illustrated below) and the system-wide “super loop” keeps all modules in the system running so they stay “active” and do their jobs. This method is not suitable for all needs; therefore, other configurations are possible. However, a polled configuration is the simplest to understand and it best illustrates the basic concept of how MPLAB Harmony modules work together, as shown below. It is also easy to implement, easy to understand, and easy to debug. Flexibility The basic MPLAB Harmony model of cooperating state-machine driven modules, when combined with a little configurability, becomes flexible enough to meet the needs of almost any embedded system. For example, if you’re using multiple identical peripherals, MPLAB Harmony has “dynamic” driver implementations that can manage all instances of a peripheral with a single instance of the driver code. You might also have a need for multiple “client” modules to use the same instance of a peripheral at the same time (like the timer example, described previously). To manage this need, MPLAB Harmony has driver implementations that are intelligent enough to manage requests from multiple clients. On the other hand, your needs may be simpler than that. So, static and single client drivers are also available to help reduce the amount of code and data storage needed for your system. Or, your system may need to combine several middleware stacks and multiple, potentially independent, applications. If that is the 1.1 1. First Time Users MPLAB Harmony Help What is MPLAB Harmony? 1-7 case, the simple polling operation, using the “super loop” method frequently seen in simple embedded systems may not be sufficient. However, when you start adding more modules, it becomes more and more difficult to meet the timing requirements of all peripherals using a simple polled super loop. Fortunately, MPLAB Harmony modules are written so that (where appropriate) their state machines can be run directly from an Interrupt Service Routine (ISR) or an RTOS thread. Using an ISR allows you to eliminate the latency of waiting for the execution of other modules in the loop to finish before a time-critical event is serviced, and it allows you to use the interrupt prioritization capabilities available on some Microchip devices to ensure that your system responds to events in the real world in real-time. Additionally, the ability to schedule and prioritize different tasks for different modules can be obtained for modules that are not associated with a specific processor interrupt (such as many middleware modules and your application) using a Real-Time Operating System (RTOS). In fact, that is one of the main reasons to use an RTOS. When your system becomes complex enough that you start struggling to meet your timing requirements using the super loop method, it’s time to use an RTOS. Fortunately, the MPLAB Harmony module state machines functions can be called from a loop in an RTOS thread just as easily as they can be called from a polled “super loop” in a system without an RTOS. To allow this, modules are designed to be “thread safe” by calling semaphore and mutex operations (and a few others, as necessary) through an Operating System Abstraction Layer (OSAL). The OSAL provides a consistent set of functions to call, regardless of which RTOS is being used (or even if no RTOS is used). The choice of RTOS to use, if any, is a configuration option. MPLAB Harmony supports several OS and non-OS configurations and support for more operating systems is possible. All that is required is to implement the OSAL functions appropriately for the desired OS. Configurability Most MPLAB Harmony libraries support a variety of build-time configuration options. • Selection of supported Microchip microcontroller • Interrupt-driven or polled execution • Static-or-dynamic peripheral instance selection (for drivers) • Single-or-multi-client support (for drivers) • Other library-specific options The need for selection of the microcontroller and execution environment has been previously explained. In addition, most drivers and other library modules are designed to allow you to select a variety of configuration options to tailor them to your specific usage. For example, you may be able to select buffer sizes for data transfer modules or clock sources for timer modules. The set of configuration options for each module is identified and explained in the help documentation (along with the interface and usage information) and peripheral initializer (MPLAB Harmony “Pi”) and configuration tools are provided to help simplify the process of configuring your system exactly the way you want and to get you started with a set of initial source files for your project. Project Structure To facilitate configurability, MPLAB Harmony projects are normally structured in a way that isolates the code necessary to 1.1 1. First Time Users MPLAB Harmony Help What is MPLAB Harmony? 1-8 configure a “system” from the library modules themselves and from your application code. The following illustrates this concept, while the second figure shows how the files might appear in an MPLAB X IDE project. In an MPLAB Harmony project, the “main.c” file is kept very simple and consistent (containing primarily, just the super-loop previously discussed). The application files (app.c and app.h in the example to the left) are separate from the configuration files in the “system_config” folder, so it is possible for a single application to have more than one configuration. (Usage of this capability can be seen in example and demonstration projects included with the installation of MPLAB Harmony.) The library modules that make up the MPLAB Harmony framework (in the “framework” folder) use the definitions provided in the selected configuration header (system_config.h, highlighted in the illustration) to specify the configuration options you selected when you configured the project. Finally the processor-specific peripheral libraries (if used) are provided as both a prebuilt binary (“.a” linker file) and as in-line source code to allow for maximum build efficiency for your firmware projects. Conclusion MPLAB Harmony provides a complete framework for developing your firmware solutions using Microchip microcontrollers and development tools. The firmware libraries and tools that make up the MPLAB Harmony framework are modular and compatible, making them simple to use. They’re flexible and configurable, making them easy to tailor to your specific needs. And, they’re portable across a wide range of Microchip microcontrollers so you’re sure to find a supported part that meets your needs. 1.1 1. First Time Users MPLAB Harmony Help Project Layout 1-9 1.1.3 Project Layout This topic explains how an MPLAB Harmony project is organized. Description A sample project has been created to show you the structure of an MPLAB Harmony project. The "sample" project is available in the following folder, directly under your MPLAB Harmony installation root folder. /apps/examples/sample/firmware/sample.X You should open this project in MPLAB X IDE and follow along with this guide. An MPLAB Harmony Project is organized as shown below within MPLAB X IDE. This organization consists of a few key "logical" folders and C-language files, as described below. The "app" folder, which contains: • The "main.c" file • The "app.c" file The "app" (short for "application") folder holds all of the application's firmware source files for the project. In a simple project, the "app" folder will directly contain the "main.c" file and the "app.c" file. More complex projects will very likely contain additional files, as needed. In an MPLAB Harmony project, the "main.c" file normally contains the C-language "main" function and little or nothing else. This "main" logic is usually consistent across all MPLAB Harmony projects and should not need to be changed. The "app.c" file normally contains the logic of the application itself. This is where the desired over-all behavior of your system is usually implemented (although complex applications may have additional files). The "system_config" folder 1.1 1. First Time Users MPLAB Harmony Help Project Layout 1-10 The "system_config" folder contains one or more subdirectories, each of which corresponds to a configuration of your application or, more accurately, "system". MPLAB Harmony projects may have multiple configuration. In each configuration, you can select a different set of libraries or modules, different build parameters for each module and different source files for your application. A configuration consists of a specific set of properties (tools settings) in MPLAB X IDE and a set of source files that define the build parameters and source code that control which modules are initialized and maintained in your system. In MPLAB X IDE, the tools configuration can be selected by using a "pull down" menu in the tool bar at the top of the window or buy "Right-clicking' on the project name and selecting "Properties". In most example and demo projects distributed with MPLAB Harmony, name of each MPLAB X IDE configuration will match the name of the associated folder under the "system_config" folder in the project (the "pic32mx_default" folder in the sample project). When a specific MPLAB X IDE configuration is selected, the configuration files for that configuration are included in the build and the configuration files in other configuration folders are excluded from the build. Note: This is project convention used by example and demo projects provided with MPLAB Harmony. You, of course, may organize your own projects any way you wish. But, we recommend following this convention if you use multiple configurations in your projects. We think you'll appreciate the power and flexibility of it. Configuration Files • The "system_config.h" file • The "system_init.c" file • The "system_tasks.c" file • The "system_int.c" file (optionally) A set of three or four files normally make up a complete configuration of the system. The purpose of each of these files is described in more detail in the following sections. But, the basic idea is that you may want different configurations of your application for different physical hardware boards, different Microchip microcontrollers, or different feature sets, depending on your specific needs. Allowing different configurations of the same application logic makes your application more flexible and provides a well-organized way to deal with the sort of variation that usually occurs in any project of sufficient size and complexity. This technique helps to eliminate the duplication of code (and labor) that would otherwise be necessary to manage multiple related projects. Of course, if you don't need or want that flexibility, all of these files are specifically created for your project and you can make any modifications to them that you like. The choice is always yours. 1.1 1. First Time Users MPLAB Harmony Help Project Layout 1-11 Important! The relative path, from the MPLAB X IDE project folder to the configuration folder (containing the "system_config.h" file) for each project configuration must be placed in the "Includes directories" list in the compiler properties for each configuration of the MPLAB X IDE project. The "framework" folder The "framework" logical folder contains the source files for the MPLAB Harmony framework and libraries. Depending on your project configuration, there can be many, many files and sub folders under this folder. These files are for MPLAB Harmony libraries that you should not need to edit. In fact, the framework source files are not normally located in your project. Instead, these files are included in your project directly from the MPLAB Harmony installation (using relative directory paths). All of the actual files stay in the MPLAB Harmony installation folder, out of the way. Notes 1. You always have the option of copying the framework files directly into your project's source folder, if desired. In fact, doing so is a good idea if you plan to move or distribute your project separately from the MPLAB Harmony installation. 2. In most cases, the "logical folder" organization within the MPLAB X IDE project matches exactly with the physical directory organization within the MPLAB Harmony installation (and within your project directory) on your disk drive. This is done to keep things simple and consistent so you only need to learn a single layout. But, there are a couple of notable exceptions. • MPLAB has a convention of splitting out "Header Files" (".h" files) and "Source Files" (".c" files), so the virtual folder organization in the MPLAB X IDE project separates the files in to these two groups and the physical directories on disk do not. • In an MPLAB Harmony example or demo project, the "app" folder will correspond to the "src" directory on disk under the application's main folder. 1.1.4 The Main File This topic describes the logic of the "main.c" file and the C-language "main" function in an MPLAB Harmony project. Description The C-language entry point for an MPLAB Harmony embedded application is the "main" function. This function is defined in the "main.c" file, contained in the project's "app" folder (or "src" directory on disk). The "main" function (see example, below) implements a simple "super loop", commonly used in embedded applications that do not make use of an operating system. Example "main" Function Logic int main ( void ) { /* Initialize the system. */ SYS_Initialize ( NULL ); while ( true ) { /* Perform system tasks. */ SYS_Tasks ( ); } /* Should not come here during normal operation. */ SYS_ASSERT ( false , "Error! Exiting main" ); return ( EXIT_FAILURE ); } The "SYS_Initialize" Function 1.1 1. First Time Users MPLAB Harmony Help The Main File 1-12 The first thing the main function does is call a function called "SYS_Initialize". The purpose of the "SYS_Initialize" function is to initialize every software module in the system. MPLAB Harmony is based upon a model of cooperating state machines. So, this function must ensure that every module's state machine is placed in a valid initial state. The implementation of this function is one of the things that must be done to configure an MPLAB Harmony system. This function's definition is normally located in the "system_init.c" file and is normally implemented by you since you're the only one who knows which software modules you want to include in your project. However, MPLAB Harmony provide a project Configurator to help you get started. Note: The "SYS_Initialize" function signature has a "void *" input parameter. This is so that it may later be implemented in a library and an arbitrary initialization data structure may be passed into it. However, for a statically implemented "SYS_Initialize" function (which will normally be the case if you implement it yourself), this parameter is unnecessary and can be passed as "NULL". (Note: You could eliminate the parameter, but that may lead to future incompatibilities and the compiler will remove it automatically for you when optimizations are enabled.) The "Super Loop" After all of the modules in the system have been initialized, the "main" function executes an infinite loop to keep the system running. This is commonly called a "super loop" as it is the outer-most loop, within which the entire system operates. This loop never exits. So, the code that exists after the end of that loop should never be executed and is only included there for safety, clarity, and syntactical completeness. The "SYS_Tasks" Function Inside of the "super loop", the "main" function calls the "SYS_Tasks" function. The purpose of the "SYS_Tasks" function is to poll every module in the system to ensure that it continues to operate. This is how the system maintains the state machine of all polled modules. (Note that some modules may be interrupt driven and thus, not called from the "SYS_Tasks" function.) The implementation of the "SYS_Tasks" function is also one of the things that you must normally do as part of the system configuration, again because you are the only one who knows which modules you want to include in your project. You might also have guessed that this function's definition is normally located in the "system_tasks.c" file. Of course, the MPLAB Harmony project Configurator can help with this also. 1.1.5 The Application File(s) This topic describes the normal structure of MPLAB Harmony application files. Description From the point of view of an MPLAB Harmony system, an application consists of two basic functions. • APP_Initialize() • APP_Tasks() The application's initialization function (APP_Initialize) is normally called from the "SYS_Initialize" function, called from "main" before entering the top-level loop. The application's "tasks" function (APP_Tasks) is normally called from the "SYS_Tasks" function, called from "main" from inside the top-level loop. This is how the application's state machine is initialized and "polled" so that it can do it's job. The "SYS_Initialize" function is normally implemented in the "system_init.c" file and the "SYS_Tasks" function is normally implemented in the "sys_tasks.c" file. That is the convention for example and demo projects distributed with MPLAB Harmony and that is the case for the sample project. You may do as you choose in your own projects, but we recommend following this convention as it will make it easier to manage multiple configurations if you need them and it will be consistent with the MPLAB Harmony project Configurator and other tools. Application Initialization An application's initialization function places the application's state machine in its initial state and may perform additional initialization if necessary. This function must not block and it should not call the routines of any other modules that may block. If 1.1 1. First Time Users MPLAB Harmony Help The Application File(s) 1-13 something needs to be initialized that may take time to complete, that initialization should be done in the application's state machine (i.e. in it's "Tasks" function). Sample Application Initialization Function: void APP_Initialize( void ) { /* Copy the message string to a buffer. */ strncpy(appData.buffer, APP_HELLO_STRING, APP_BUFFER_SIZE); /* Prepare a buffer object for transfer using the USART driver. */ appData.bufferObject.buffer = appData.buffer; appData.bufferObject.bufferSize = min(APP_BUFFER_SIZE, strlen(appData.buffer)); appData.bufferObject.flags = DRV_USART_BUFFER_FLAG_WRITE; /* Place the App state machine in it's initial state. */ appData.state = APP_STATE_INIT; } The sample project's initialization function initializes an internal buffer to prepare a "Hello World" message for transmission on a USART and places the application's state machine in its initial state by assigning the "APP_STATE_INIT" enumeration value into the "state" member of the data structure that contains all of the data required by the application (appData). This structure is defined globally, but is only ever accessed by the application itself. The application's initialization function is called from the "SYS_Initialize" function (defined in "system_init.c") which is called from "main" after a system reset. Using this technique, the application is initialized (along with the rest of the system) whenever the system comes out of reset. Application Tasks The application's state machine breaks up the job that the application must do into several short "tasks" that it can complete quickly, but between which it must wait for some other module to complete some tasks of its own. (In this case the other module is the USART driver.) Once each short task has completed successfully, the application transitions to another state to perform the next short task. Example Application Tasks Function: void APP_Tasks( void ) { /* Status of USART driver */ DRV_USART_CLIENT_STATUS usartStatus; /* Status of buffer submitted to USART */ DRV_USART_BUFFER_STATUS bufferStatus; /* Check the application state*/ switch ( appData.state ) { /* Keep trying to open the driver until we succeed. */ case APP_STATE_INIT: { /* open an instance of USART driver */ appData.usartHandle = DRV_USART_Open(SYS_USART_DRIVER_INDEX, DRV_IO_INTENT_READWRITE); if (appData.usartHandle != DRV_HANDLE_INVALID ) { /* Update the state */ appData.state = APP_STATE_WAIT_FOR_READY; } break; } /* Send the message when the driver is ready. */ case APP_STATE_WAIT_FOR_READY: { 1.1 1. First Time Users MPLAB Harmony Help The Application File(s) 1-14 /* Get the USART driver status */ usartStatus = DRV_USART_ClientStatus( appData.usartHandle ); if ( usartStatus == DRV_USART_CLIENT_STATUS_READY ) { /* Submit buffer to USART */ appData.usartBufferHandle = DRV_USART_BufferAdd(appData.usartHandle, &appData.bufferObject); if ( appData.usartBufferHandle != DRV_HANDLE_INVALID ) { /* Buffer is accepted. Driver will transmit. */ appData.state = APP_STATE_WAIT_FOR_DONE; } } break; } case APP_STATE_WAIT_FOR_DONE: { bufferStatus = DRV_USART_BufferStatus(appData.usartHandle, appData.usartBufferHandle); if ( DRV_USART_BUFFER_COMPLETED == bufferStatus ) { /* Work is done, move to idle state. */ appData.state = APP_STATE_IDLE; } } /* Idle state (do nothing) */ case APP_STATE_IDLE: default: break; } } Sample Application States The sample application's "tasks" function breaks the operation of the application down in to the following states using a "switch" statement with the following "cases". • APP_STATE_INIT • APP_STATE_WAIT_FOR_READY • APP_STATE_WAIT_FOR_DONE • APP_STATE_IDLE The sample application is placed into the "APP_STATE_INIT" state when by the application's initialization function before the "tasks" function is ever called. So, the first time the "APP_Tasks" function is called, the switch statement executes the code under this case and the first short "task" the sample application attempts to do is open the USART driver to obtain a handle so that it can transfer data over the USART. Notice that the application checks the value of the handle returned from the "DRV_USART_Open" function to ensure that it is valid before it transitions to the "APP_STATE_WAIT_FOR_READY" state. If the value of the handle retuned be the driver's "open" function is invalid (equal to "DRV_HANDLE_INVALID"), then the application stays in the "APP_STATE_INIT" state and keeps trying to open the USART driver every time it's "tasks" function is called. Once the application has a valid handle to the USART driver, it executes the code under the "APP_STATE_WAIT_FOR_READY" case the next time its "APP_Tasks" function is called . In this state, the application calls a USART driver status routine (DRV_USART_ClientStatus) to see if the driver is ready to transfer data . If the driver is ready, the application calls a USART driver data transfer routine (DRV_USART_BufferAdd) to send the data buffer it prepared in the "APP_Initiaize" function to the USART. Then, it checks the handle returned by the "DRV_USART_BufferAdd" routine to see if it is valid. If the buffer handle is valid, it indicates that the USART driver has accepted the buffer and will take responsibility for the 1.1 1. First Time Users MPLAB Harmony Help The Application File(s) 1-15 data transfer from that point forward. The application does not have to do anything else to cause the data transfer to occur, but it may want to know when the transfer has completed, so it transitions to the "APP_STATE_WAIT_FOR_DONE" state. However, if the buffer is not accepted by the driver (in which case the handle returned by the "DRV_USART_BufferAdd" function would be invalid), the application stays in the "APP_STATE_WAIT_FOR_READY" and tries again the next time the "APP_Tasks" function is called by the system (i.e. the "SYS_Tasks" function). Once the application is in the "APP_STATE_WAIT_FOR_DONE" state, it calls a buffer status routine (DRV_USART_BufferStatus) to check and see if the buffer it sent has completed. Note that it passes the handle value returned from the "DRV_USART_BufferAdd" function (stored in the "usartBufferHandle" member of the global "appData" structure) into the buffer status function to identify the buffer on which it wishes to check status. If the buffer status routine returns "DRV_USART_BUFFER_COMPLETED", then the transfer has completed and the application transitions to the "APP_STATE_IDLE" state where it stays and does nothing any time its "tasks" function is called. It's job is done! A more complex application would go on to some other task or potentially begin the process again. But, this is a simple "Hello World" sample application. Note: The application is normally initialized last, after all other modules in the system have been initialized. But, it should never assume that any other module that it must call has completed its initialization when the application is initialized or when it's "tasks" function is first called. Instead, it should always check the return value or status from any other module it calls to ensure that the call succeeded before moving on to the next state. Following this rule makes applications more robust and allows then to handle errors more effectively. 1.1.6 System Configurations 1.1.6.1 system_config.h This topic describes the purpose of system configuration header file. Description System Configuration In MPLAB Harmony, most library modules have a set of build time configuration options that define a variety of parameters (such as buffer sizes, maximum or minimum limits, and default behavior). These configuration options normally have acceptable default values. However, if you want to configure a library for your specific needs, its configuration options can be defined using C-language pre-processor "#define" statements. The set of configuration options supported is described for each library in the "Configuring the Library" section of its help document and most libraries provide a template and example configuration header files in a "config" sub-folder under their "src" folder. To obtain its build configuration options, every library includes the same common top-level configuration file that must be called "system_config.h" and that must be defined as part of your application or, more specifically, as part of your system configuration. The relative directory path to configuration directory that contains this file must be defined in the build properties of your project so that the compiler can find it in it's include file search path. Example Configuration "system_config.h" Header // ***************************************************************************** // ***************************************************************************** // Section: Application Configuration // ***************************************************************************** // ***************************************************************************** 1.1 1. First Time Users MPLAB Harmony Help System Configurations 1-16 /* Define the size of the application's message buffer. */ #define APP_BUFFER_SIZE 15 #define APP_UART_BAUDRATE 9600 /* Define the application's "hello world" message string. */ #define APP_HELLO_STRING "Hello World\r\n" // ***************************************************************************** // ***************************************************************************** // Section: System Services Configuration // ***************************************************************************** // ***************************************************************************** /* Define the index for the driver we'll use. */ #define SYS_USART_DRIVER_INDEX DRV_USART_INDEX_0 /* Define the hardware (PLIB) index associted with this instance of the driver. */ #define SYS_USART_ID USART_ID_2 // ***************************************************************************** // ***************************************************************************** // Section: UART Driver Configuration // ***************************************************************************** // ***************************************************************************** #define DRV_USART_INSTANCES_NUMBER 1 #define DRV_USART_CLIENTS_NUMBER 1 #define DRV_USART_INTERRUPT_MODE false #define DRV_USART_XFER_BUFFER_NUMBER 10 #define DRV_USART_INTERRUPT_SOURCE_TX INT_SOURCE_USART_2_TRANSMIT #define DRV_USART_CONFIG_BYTE_Q_SIZE_TX 1 #define DRV_USART_CONFIG_BYTE_Q_SIZE_RX 1 #define DRV_USART_CONFIG_BLOCK_DEVICE_MODE #define DRV_USART_INTERRUPT_MODE false #define DRV_USART_INSTANCES_NUMBER 1 #define DRV_USART_CLIENTS_NUMBER 1 #define DRV_USART_INTERRUPT_SOURCE_TX INT_SOURCE_USART_2_TRANSMIT #define DRV_USART_INTERRUPT_SOURCE_RX INT_SOURCE_USART_2_RECEIVE The example above defines configuration options for the application, system services, and USART driver used in the "pic32mx_default" configuration of the sample project.. 1.1.6.2 system_init.c This topic describes the purpose of the system initialization file. Description In an MPLAB Harmony project, the "SYS_Initialization" function is called from the "main" function in order to initialize all modules in the system. This function is implemented as part of a system configuration, normally in a file called "system_init.c". This file may also include other necessary global system items that must be implemented in order to initialize a system such as processor configuration bits and system-wide global data structures. Example "system_init.c" File // **************************************************************************** 1.1 1. First Time Users MPLAB Harmony Help System Configurations 1-17 // **************************************************************************** // Section: Configuration Bits // **************************************************************************** // **************************************************************************** #pragma config FPLLODIV = DIV_1, FPLLMUL = MUL_20, FPLLIDIV = DIV_2 #pragma config FWDTEN = OFF, FCKSM = CSECME, FPBDIV = DIV_1 #pragma config OSCIOFNC = ON, POSCMOD = XT, FSOSCEN = ON, FNOSC = PRIPLL #pragma config CP = OFF, BWP = OFF, PWP = OFF #pragma config ICESEL = ICS_PGx2 // ***************************************************************************** // ***************************************************************************** // Section: Driver Initialization Data // ***************************************************************************** // ***************************************************************************** static DRV_USART_INIT uartInit = { /* System module initialization */ .moduleInit = {0} , /* Identifies USART hardware module (PLIB-level) ID */ .usartID = SYS_USART_ID , /* Operation Modes of the driver */ .operationMode = DRV_USART_OPERATION_MODE_RS232 , /* Flags for the usart initialization */ .initFlags = 0 , /* Control the line control configuration */ .lineControlMode = DRV_USART_LINE_CONTROL_MODE_8NONE1 , /* Baud Rate value to be used, if not using auto baud */ .brgValue = APP_UART_BAUDRATE , /* Operation mode initialization data */ .operationModeInit = {{0}}, /* Handshake Mode */ .handShakeMode = DRV_USART_HANDSHAKE_MODE_NONE , /* Interrupt Source for TX Interrupt */ .txInterruptSource = INT_SOURCE_USART_2_TRANSMIT , /* Interrupt Source for RX Interrupt */ .rxInterruptSource = INT_SOURCE_USART_2_RECEIVE , /* Interrupt Source for Error Interrupt */ .errorInterruptSource = INT_SOURCE_USART_2_ERROR, /* Receive Queue length */ .rxQueueSize = 3, /* Transmit Queue length */ .txQueueSize = 3 }; // ***************************************************************************** // ***************************************************************************** // Section: System Data // ***************************************************************************** // ***************************************************************************** 1.1 1. First Time Users MPLAB Harmony Help System Configurations 1-18 /* Structure to hold the sample application's system data. */ SAMPLE_SYSTEM_OBJECTS sysSample; // **************************************************************************** // **************************************************************************** // Section: System Initialization // **************************************************************************** // **************************************************************************** void SYS_Initialize ( void* data ) { /* Inialize the system */ sysSample.usart = DRV_USART_Initialize(SYS_USART_DRIVER_INDEX, (SYS_MODULE_INIT *)&uartInit ); /* Initialize the Application */ APP_Initialize ( ); } In addition to the "SYS_Initialize" function implementation, the above example "system_init.c" file from the "pic32mx_default" configuration of the "sample" project defines the processor configuration bits, a data structure used to initialize the USART driver, and a global "sysSample" data structure used to hold a global handle to the USART driver object returned by the driver's initialization function. Notice that the "SYS_Initialize" function initializes first the driver, then the application. These are the only two active modules in this system. 1.1.6.3 system_tasks.c This topic describes the purpose of the system tasks file. Description Since MPLAB Harmony modules are state machine driven, they each have a "Tasks" function that must be called repeatedly (from the system-wide "super" loop in "main" or from an ISR or OS thread). The "Tasks" functions are all called from the top-level "SYS_Initialize" function that is normally implemented in a file called "system_tasks.c" that is part of a system configuration. Example "system_tasks.c" File void SYS_Tasks ( void ) { /* Call the "tasks" functions for any modules in the system. */ DRV_USART_TasksTX(sysSample.usart); /* Call the application's tasks routine */ APP_Tasks ( ); } The "system_tasks.c" file for the "pic32mx_default" configuration of the "sample" project, contains only the implementation of the "SYS_Tasks" function for that configuration. This function calls the USART driver's transmitter tasks function "DRV_USART_TasksTX", passing in the driver's object handle returned from the driver's initialization routine, and it calls the application's tasks function "APP_Tasks" to keep both the driver and the application's state machines running. 1.1.6.4 system_int.c This topic describes the purpose of the system interrupts file. 1.1 1. First Time Users MPLAB Harmony Help System Configurations 1-19 Description In an interrupt-driven configuration, any modules (such as drivers or system services) that can be driven from an interrupt must have their interrupt-capable tasks function(s) called from an Interrupt Service Routine (ISR) "vector" function instead of from the "SYS_Tasks" function. The form of the definition of the ISR vector function is dependent on what type of PIC microcontroller on which the system is running. So, any vector functions required are normally implemented as part of the a specific system configuration in a file normally called "system_int.c" Example "system_int.c" File void __ISR ( _UART_2_VECTOR ) _InterruptHandler_USART_2_stub ( void ) { if ( SYS_INT_SourceStatusGet ( APP_USART_INT_SOURCE_TX ) ) { /* Call the USART driver's "Tasks" routine */ DRV_USART_TasksTX ( sysSample.usart ); } } Notice that, in this example, the ISR function must determine if the interrupt occurred because of a transmitter (TX) interrupt because on the PIC32 part used by this configuration of the application, this interrupt vector is shared with other types of interrupts for this USART. Once it has determined that the interrupt is indeed a transmitter interrupt, the ISR calls the USART driver's TX tasks routine and passed in the USART object handle returned from the driver's initialization function. Note: The USART driver's "DRV_USART_TasksTX" function is interrupt capable when the USART driver is built with the correct configuration options. 1.1.7 More Information Describes what is available from the MPLAB Harmony web page. Description Information on MPLAB Harmony is available from microchip.com/harmony. From this landing page, information on additional downloads, links to a MPLAB Harmony discussion forum, among others is available. 1.1 1. First Time Users MPLAB Harmony Help More Information 1-20 1.2 2. Creating Your Own Applications This section describes the steps necessary to create your own MPLAB Harmony applications. Description To support the framework, the application (or MPLAB Harmony "system") is responsible for the following: 1. Create a New Project: This can be accomplished by either running the MPLAB X IDE new project wizard or copying and using a basic template located in the /apps/examples/templates directory. If you copy the template to a new location, you may be required you to modify your include paths. To use the project wizard, select Microchip Embedded > Standalone Project. Next, choose the device. The device you choose will determine what peripheral libraries are included in your MPLAB Harmony project. Continue in the new project Wizard, selecting your hardware and software tools. When you name and locate your project, there are two choices: 1) You can locate it in the ‘apps’ folder of the MPLAB Harmony installation or 2) You can locate it outside of the Harmony installation. Placing the project in the ‘apps’ folder of MPLAB Harmony will require you to copy it if you install a new version of MPLAB Harmony. Installing your project outside of the MPLAB Harmony installation will require you to modify your include paths when a new version of MPLAB Harmony is installed. It is recommend to use relative paths when installing in the ‘apps’ folder in MPLAB Harmony. Make sure that your new project is set to the main (active) project. 2. Determine which MPLAB Harmony Modules are needed for your Application: Modules are divided into four categories; Peripheral Libraries, System Services, Device Drivers and other libraries (commonly called middleware). To determine your needs, read the MPLAB Harmony Overview and the Introductory sections for the modules of interest. Some modules have dependencies while others do not. Peripheral Libraries have no dependencies. Drivers depend on peripheral libraries. System Services depend on Peripheral Libraries and or Drivers. Your application or its middleware will typically use drivers or system services. 3. Add the required Module Source Files to your Project: This can be accomplished by reading the help for each module to determine what source files you need and manually entering them into your project. Alternatively, the MPLAB Harmony Configurator can be used to select the modules from a list or tree and it will automatically insert the source files into your project and optionally generate a skeletal template for your project. Note that some modules have multiple implementations each optimized for different purposes. Others may implement optional features in multiple files. Be sure to select the source file right for your implementation and be sure to include the pre-built peripheral library binary “.a” file for the processor you selected in your project. 4. Configure The Modules: With the exceptions of the Peripheral Libraries, every MPLAB Harmony module will require some set of build time configuration options implemented using ‘c’ language macros ‘#define’. Descriptions of the supported options are available in the "Configuring the Library" section in the help document for every MPLAB Harmony library. These options must be defined in the system_config.h header that is part of your project template generated by the MPLAB Harmony Configurator. Every MPLAB Harmony source file that supports build time configuration options will include this header. As such, this file must be part of every MPLAB Harmony Project. 5. Initialize System: This task involves completing the system_init.c file. First add the necessary configuration bits for your processor. These are defined in the Special Features section of your device's data sheet. The next step is to complete the SYS_Initialize function. Finish any necessary processor initialization (wait states, cache control, etc.) MPLAB Harmony may provide services to accomplish this in the System Services Module. Initialize any features specific to the board that are not initialized by other modules such as drivers or system services. Next, initialize all library modules selected in step 2 above used by your application. To do this you must first define the initialization data structure for each module. This can be done statically in the system_init.c file and passed in by pointer to the appropriate initialization function for each library. Needed initialization structures can be found in the help section for each module. Add a call to the initialization function for each library module into the SYS_Initialize function. Each initialization function will return an object handle for the module instance. These should be captured so that they can be passed to the module task routine. Finally, add the call to APP_Initialize function into the SYS_Initialize function. 6. Call System State Machine Tasks: The system must call the various task state machine functions at appropriate times. This is accomplished by either adding the call into the SYS_Tasks function for polled modules or adding the call to the interrupt handler for interrupt driven modules. The object handle saved during the initialization process is used as an argument for the various task state machine functions. The SYS_Tasks function is typically implemented in the system_tasks.c file while the interrupt handlers are defined in the system_int.c file. 1.2 2. Creating Your Own Applications MPLAB Harmony Help 1-21 7. Develop Application State Machine: You are now ready to develop your application. Since Harmony is based on cooperative state machines, your application should also be state machine driven. At minimum, the APP_Initialize function must put your application in its initial state. It may perform other initialization as long as it does not have to wait for other modules. Any initialization that depends on other modules should be implemented as part of the application state machine. Finally, complete your application functionality by implementing the APP_Tasks state machine function. 1.2 2. Creating Your Own Applications MPLAB Harmony Help 1-22 1.3 3. Release Notes & Information This section contains release notes for this release and information on version numbers and release types. 1.3.1 Release Notes Release notes for MPLAB Harmony v0.70b. Target Release Date: November 18, 2013. Description Please refer to Release Contents for a complete list of modules that are provided in this release. MPLAB Harmony is a framework of system services, device drivers, and other libraries that are built upon a base of portable peripheral libraries to provide flexible, portable, and consistent software “building blocks” which you can use to develop your embedded PIC32 applications. This is the first fully public release of MPLAB Harmony. Previous releases were internal to Microchip and had very limited external distribution. A complete list of the contents of this release is provided in the Release Contents section. You can find these contents under the installation folder you selected in the following sub-folders: • “apps” – Contains all demo and example applications provide with this installation. • “bin” – Contains pre-built binary libraries (“.a” files) for the MPLAB Harmony peripheral libraries for each supported processor and for key libraries provided in binary form. • “bsp” – Contains MPLAB Harmony board support packages provided for selected Microchip demo and development boards. • “build” – Provides MPLAB X IDE projects that you can use to re-build the libraries provide under the “bin” folder (in case you want to use different build settings). • “doc” – Contains the MPLAB Harmony help documentation in PDF and MPLAB X IDE “.nbm” plug-in formats. • “framework” – Contains source code and API headers for all MPLAB Harmony libraries that are provided in source form. • “third_party” – Contains MPLAB Harmony compatible libraries and Real-Time Operating Systems (RTOS) provided with this installation. • “utilities” – Contains design and development utilities and MPLAB X IDE plug-in utilities provided with MPLAB Harmony. Please review the following key help topics (and their subtopics) to gain an initial understanding of what MPLAB Harmony is and how to use it. • Start Here > First Time Users • Start Here > Creating your Own Applications • MPLAB Harmony Configurator Help • The “Introduction” sections of the individual help topics for the system services, drivers, and libraries that are of interest to you • Applications Help > Applications Overview • The “Introduction” sections of the individual applications help topics Once you have a basic understanding of MPLAB Harmony, you can begin using the provided demo and example applications to explore it’s capabilities and begin developing your own applications. 1.3 3. Release Notes & Information MPLAB Harmony Help Release Notes 1-23 Before developing your own applications, be sure to look at the example “template” application provided in the “/apps/examples/templates” folder. The following sections provide a brief overview of items that are new in this release and known issues at the time of the release. Refer to the “Release Notes” section under the help topic for each individual library, application, or utility for additional details. Refer to the “Using the Library” section for each individual library for a description of how to use library functions to accomplish the tasks that the library was intended to support. Refer to the “Library Interface” section for each individual library for a programmer’s reference or dictionary of functions and data types defined by that library’s interface. New This Release: • Significant SD Card Driver improvements. • The SPI driver has had configuration and interoperability improvements. • The NVM driver now handles sector erasing during writes. • USB Driver demonstrations • TCP/IP Stack updates (see the TCP/IP Stack Library Help) • Graphics Library API has been updated • File System Service Library has been updated • The following System Services have been added: Clock and Device Control • USART Driver has been updated • USB Driver has been updated • Peripheral Libraries now support PIC32MZ devices • FreeRTOS now supports PIC32MZ devices • CyaSSL Library has been added Known Issues: • The SD Card driver has had limited testing and is missing a few desired features • The SPI driver does not support slave mode or DMA • The NVM driver has only been tested in it’s current memory configuration • NVM Driver demonstration has limited testing • SPI Driver demonstration has limited testing and hardware support • USART Driver demonstration does not support PIC32MZ devices • USB demonstrations (see the related Release Notes) • USB Host Stack has limited testing and functional limitations (see the related Release Notes) • USB Device Stack has limited testing and functional limitations (see the related Release Notes) • No multi-display support for the Graphics Primitive Library • File System Service Library does not support MIP16 mode, has limited testing and functional limitations (see the related Release Notes) • USART Driver has flow control and parity mode limitations and no multi-client support • MRF24W Wi-Fi Driver Library has limited demonstration support and testing (see the related Release Notes) 1.3 3. Release Notes & Information MPLAB Harmony Help Release Contents 1-24 1.3.2 Release Contents This topic lists the contents of this release and identifies the individual version numbers of each module. Description This table lists the contents of this release, including a brief description of each module. Cryptographic Applications: /apps/crypto/ Crypto Demonstration Crypto Library Demonstration 1.00 Example Applications: /apps/examples/ peripheral/blocking/pic32mz Simple blocking PLIB examples. 1.00 peripheral/blocking/pic32mx Simple blocking PLIB examples 1.00 state_driven Simple MPLAB Harmony compliant state-driven Peripheral Library examples 1.00 sample Sample “Hello World” demonstration used in “Getting Started” guide in Help system N/A DEMOS: Driver Application demos: /apps/driver/ nvm demo NVM demonstration application 1.00 usart demo USART demonstration application 1.00 spi demo SPI demonstration application 1.00 DEMOS : RTOS Application demos: /apps/rtos/ freertos FreeRTOS demonstration application 1.00 openrtos OpenRTOS demonstration application 1.00 File System Applications: /apps/fs/ nvm_fat_single_disk Single-disk Non-Volatile Memory FAT FS Demonstration 1.00 nvm_sdcard_fat_multi_disk Multi-disk Non-Volatile Memory FAT FS Demonstration 1.00 sdcard_fat_single_disk SD Card FAT Disk demonstration 1.00 nvm_mpfs_single_disk Single-disk Non-Volatile Memory 1.00 nvm_sdcard_fat_mpfs_multi_disk Multi-disk Non-Volatile Memory FAT MPFS Demostration 1.00 DEMOS: Graphics Applications: /apps/gfx/ lcc Low-Cost Controllerless Graphics Demonstration 4.00b object Graphics Object Layer Demonstration 4.00b primitive Graphics Primitives Layer Demonstration 4.00b s1d13517 Epson S1D13517 LCD Controller Demonstration 4.00b ssd1926 Solomon Systech SSD1926 Controller Demonstration 4.00b 1.3 3. Release Notes & Information MPLAB Harmony Help Release Contents 1-25 DEMOS: TCP/IP Applications & Utilities: /apps/tcpip/ tcpip_web_server TCP/IP Web Server Demonstration 1.01 bsd_tcp_server TCP/IP BSD Server Demonstration 1.00 bsd_tcp_client TCP/IP BSD Client Demonstration 1.00 bsd_udp_server TCP/IP BSD Server Demonstration 1.00 bsd_udp_client TCP/IP BSD Client Demonstration 1.00 tcpip_tcp_server TCP/IP TCP Server Demonstration 1.00 tcpip_tcp_client TCP/IP TCP Client Demonstration 1.00 tcpip_udp_server TCP/IP UDP Server Demonstration 1.00 tcpip_udp_client TCP/IP UDP Client Demonstration 1.00 wolf_ssl wolf ssl Demonstration 1.00 wifi_console TCP/IP Wi-Fi Console Demonstration wifi_easyconf TCP/IP Wi-Fi Easy Configuration Demonstration DEMOS: USB Device (Function) Applications: /apps/usb/device/ audio_speaker USB Audio Device Speaker Demonstration 1.00 cdc_com_port_dual CDC Dual Serial COM Ports Emulation Demonstration 1.00 cdc_com_port_single CDC Single Serial COM Port Emulation Demonstration 1.00 generic_device Microchip Generic USB Device Demonstration 1.00 hid_basic Basic USB Human Interface Device (HID) Demonstration 1.00 hid_joystick USB HID-Class Joystick Device Demonstration 1.00 hid_keyboard USB HID-Class Keyboard Device Demonstration 1.00 hid_mouse USB HID-Class Mouse Device Demonstration 1.00 msd_basic USB Mass Storage Device Demonstration 1.00 cdc_serial_emulator CDC Serial Emulation Demonstration 1.00 DEMOS: USB Host Applications: /apps/usb/host/ msd_simple_thumb_drive USB MSD Host Simple Thumb Drive Demonstration 1.00 cdc_basic USB CDC Basic Demonstration 1.00 cdc_serial USB CDC Serial Demonstration 1.00 hid_keyboard USB HID-Class Joystick Host Demonstration 1.00 hid_mouse USB HID-Class Mouse Host Demonstration 1.00 generic_device Microchip Generic USB Host Demonstration 1.00 Pre-built Binaries: /bin/ framework/peripheral Pre-built Peripheral Libraries 1.00 framework/math/dsp Pre-built DSP libraries for PIC32MZ devices 1.00 framework/math/libq Pre-built fixed-point math libraries for PIC32MZ devices 1.00 1.3 3. Release Notes & Information MPLAB Harmony Help Release Contents 1-26 Board Support Packages (BSPs): /bsp/ explorer16/pic32mx795f512l Explorer 16 Development Board and PIC32MX795F512L PIM 1.00 sk_pic32_mx_usb PIC32 USB Starter Kit 1.00 sk_pic32_mz PIC32MZ Embedded Connectivity (EC) Starter Kit 1.00 usb_audio_pic32mx PIC32 USB Starter Kit II 1.00 gfx Graphics (GFX) boards 1.00 Documentation: /doc doc/org-microchip-harmony_help.nbm MPLAB Harmony Help MPLAB X IDE Plug-In 0.70b doc/harmony_help.pdf MPLAB Harmony Help 0.70b Middleware & Libraries: /framework/ Crypto (Software) Microchip Cryptographic Libraries 1.00 GFX Graphics Library 4.00b MATH/DSP API header for PIC32MZ DSP Libraries 1.00 MATH/LIBQ API header for PIC32MX fixed-point libraries 1.00 AAC/MP3 Audio Decoder Libraries 1.00 TCP/IP TCP/IP Network Stack 7.10 USB Host USB Host Stack 0.02b USB Device USB Device Stack 0.05b Device Drivers: /framework/driver/ adc Analog-to-Digital Converter Driver 0.01b ethmac Ethernet Media Access Controller Driver 7.10 ethphy Ethernet Physical Interface Driver 7.10 gfx/gfx_lcc Low-Cost Controllerless Graphics Driver 4.00b gfx/gfx_otm2201a OTM LCD Controller Driver 4.00b gfx/gfx_s1d13517 Epson S1D13517 LCD Controller Driver 4.00b gfx/gfx_ssd1926 Solomon Systech SSD1926 Controller Driver 4.00b nvm Non-Volatile Memory Driver 0.50b pmp Parallel Master Port Driver 0.50b sdcard SD Card Driver (Client of SPI Driver) 0.50b spi Serial Peripheral Interface (SPI) Driver 0.50b tmr Timer Driver 0.50b usart Universal Synchronous/Asynchronous Receiver/Transmitter (USART) Driver 0.50b usb/usbhs Universal Serial Bus (USB) Controller Driver 0.05b wifi/mrf24w Wi-Fi MAC driver for the MRF24W controller 3.0.0 1.3 3. Release Notes & Information MPLAB Harmony Help Release Contents 1-27 Operating System Abstraction Layer (OSAL): /framework/osal osal.h OSAL Interface 0.52b osal_freertos.h osal_freertos.c OSAL Implementation for FreeRTOS 0.52b osal_openrtos.h osal_openrtos.c OSAL Implementation for OpenRTOS 0.52b osal_impl_basic.h OSAL “bare metal” (no OS) implementation 0.52b osal_imple_none.h OSAL implementation that removes the OSAL when not used 0.52b osal_ucos3.h osal_ucos3.c OSAL Implementation for Micrium µCOS-III 0.52b osal_ucos2.h osal_ucos2.c OSAL Implementation for Micrium µCOS-II N/A osal_threadx.h OSAL Implementation for Express Logic ThreadX N/A osal_threadx.c N/A Peripheral Libraries: / framework/peripheral Peripheral Library Source Code for all Supported PIC32 Processors 0.70b Build Framework: /build/framework/ crypto/test Test Vector App for crypto/zlib 1.00 crypto/zlib zlib library 1.00 crypto/crypto crypto library 1.00 peripheral Peripheral Library build project 1.00 math/libq libq library build project 1.00 math/DSP DSP library build project 1.00 System Services: /framework/system/ clk Clock Services Library 0.04a common Common Services 0.02a devcon Devcon Services Library 0.02b fs File System Services Library 0.50b int Interrupt Services Library 0.04a msg Message Services Library 0.01a ports Input/Output Ports Services Library 0.02b tmr Software Timer Services Library 0.02a wdt Watchdog Timer Services Library 0.02b Third-Party Software: /third_party/ 1.3 3. Release Notes & Information MPLAB Harmony Help Release Contents 1-28 rtos/FreeRTOSV7.5.2 FreeRTOS Source Distribution v7.5 with support for PIC32MZ devices Yes (Vendor Version) rtos/FreeRTOSVX.XX.XX FreeRTOS Source Distribution v7.5 with support for PIC32MX devices Yes (Vendor Version) rtos/OpenRTOSVx.x.x OpenRTOS Source Distribution vx.x.x with support for PIC32MZ devices Yes (Vendor Version) rtos/OpenRTOSVx.x.x OpenRTOS Source Distribution vx.x.x with support for PIC32MX devices Yes (Vendor Version) uC/OS-III Micrium uC/OS-III Binary Demonstration with support for PIC32MZ devices Yes (Vendor Version) uC/OS-III Micrium uC/OS-III Binary Demonstration with support for PIC32MX devices Maybe (Vendor Version) uC/OS-II Micrium uC/OS-II Binary Demonstration (PIC32MZ) uC/OS-II Micrium uC/OS-II Binary Demonstration (PIC32MX) ThreadX Express Logic (ThreadX) Demonstration with Support for PIC32MZ devices CyaSSL Embedded SSL Library Open Source based demonstration 2.8.0 (Vendor Version) CyaSSL Embedded SSL Library Open Source based demonstration Yes (Vendor Version) InterNiche Technologies, Inc. Suitable TCP/IP demonstrations Yes (Vendor Version) Utilities: /utilities/ MPLAB Configurator MPLAB Harmony Project/Library Configurator MPLAB X IDE Plug-In 0.02a gfx/gdd Graphics Display Designer 2.00b gfx/grc Graphics Resource Compiler 4.00.39 mib2bib/mib2bib.jar Compiles Custom Microchip MIB script (snmp.mib) to generate snmp.bib and mib.h 2.00 mpfs_generator/mpfs2.jar TCP/IP MPFS File Generator and Upload Utility 2.02.06 tcpip_discoverer/tcpip_discoverer.jar TCP/IP Microchip Node Discoverer Utility 2.00 1.3.3 Version Numbers This section describes the version numbers and their meaning. 1.3 3. Release Notes & Information MPLAB Harmony Help Version Numbers 1-29 Description MPLAB Harmony Version Numbering Scheme Libraries released with MPLAB Harmony each have their own version number, using the following scheme. .[.<“dot”>][] • Major revision (architecture or paradigm shift) • Minor revision (new features, regular releases) • “Dot” release (bug fixes, unscheduled releases) • Release Type (‘a’ = alpha, ‘b’ = beta, Full release versions 1.0 or above have no type letter) Items in square brackets are only present when needed (see examples, below). Examples: • MPLAB Harmony USB Library v2.6 (“dot” of ‘0’ implied) • MPLAB Harmony Graphics Library v1.12.02 Note: The version number of the over all MPLAB Harmony release is not related to the version numbers of each individual library or module included in the release and has no bearing on the versions of any libraries it includes. It is merely a way to keep track of what libraries (and what versions of what libraries) are included in each release. Refer to the current release notes to identify what libraries are included and what their version numbers are. 1.3.4 Release Types This section describes the release types and their meaning. Description MPLAB Harmony module releases can be of three different types, based on the version type. Alpha Release An alpha release version of a module is usually an initial release. Alpha releases will have complete implementations of their basic feature set, they are unit tested (usually by the original developer) and will build correctly in their basic configuration. An 1.3 3. Release Notes & Information MPLAB Harmony Help Release Types 1-30 alpha release is a great "preview" of what a new development Microchip is working on and it can be very helpful for exploring new features. However, it has not gone through a formal test process and it is almost certain that some of its interface will change before the full version is released. It is not recommended for production use. Beta Release A beta release version of a module has gone through the internal interface review process and has had formal testing of its functionality. Also, issues reported from the alpha release will have been fixed or documented. When a module is in a beta version, you can expect it to function correctly in normal circumstances and you can expect that its interface is very close to the final form (although changes can still be made if required). However, it has not had stress testing or been tested and it may not fail gracefully if used incorrectly. A beta release is not recommended for production use, but it can be used for development. 1.0+ Release By the time a module is released as a 1.0 version or above, it is feature complete, fully tested, and its interface is "frozen". All known issues from previous releases will have been fixed or documented. The existing interface will not change in future releases. It may be expanded with additional features and additional interface functions, but existing interface functions will not change. This is stable code with a stable Application Program Interface (API) that you can rely on for production purposes. 1.3 3. Release Notes & Information MPLAB Harmony Help Release Types 1-31 1.4 4. Previous Releases This topic contains information about past version(s) of MPLAB Harmony. 1.4.1 v0.51.03b Release notes for MPLAB Harmony v0.51.03b. Description This topic contains the release notes for MPLAB Harmony v0.51.03b. Please refer to the Release Contents topic for a complete list modules that are provided in this release. This release will support MPLAB X IDE v1.95 and XC32 v1.30 tc9 and above. New this Release • Updated the Documentation • Updated Peripheral Pre-Built Binary Libraries (".a" files) • Added IPv6 API for generation of the Unique Local Address (ULA) Known Issues 1. No documentation available for the Crypto libraries and peripheral libraries example applications. 2. For TCP/IP stack running on PIC32MZ platforms the write-back mode is not supported yet. Write-through has to be used for now. 3. Early samples of the PIC32MZ silicon do not have a factory pre-programmed MAC address. This will cause the TCP/IP stack and related applications to not properly run in most network configuration. Manual update of the related "network_config.h" file with a valid MAC address is required. 4. The Wi-Fi driver for the TCP/IP stack and the supporting demos are not part of this release. This table lists the contents of this release, gives a brief description Module Description Version File System Applications: /apps/fs/ nvm_fat_single_disk Single-disk Non-Volatile Memory FAT FS Demonstration 0.02a nvm_sdcard_fat_multi_disk Multi-disk Non-Volatile Memory FAT FS Demonstration 0.02a sdcard_fat_single_disk SD-Card FAT Disk Demonstration 0.02a nvm_mpfs_single_disk Single-disk Non-Volatile Memory MPFS Demonstration 0.02a nvm_sdcard_fat_mpfs_multi_disk Multi-disk Non-Volatile Memory FAT MPFS Demonstration 0.02a Graphics Applications: /apps/gfx/ lcc Low-Cost Controllerless Graphics Demonstration 0.51b object Graphics Object Layer Demonstration 0.51b 1.4 4. Previous Releases MPLAB Harmony Help v0.51.03b 1-32 primitive Graphics Primitives Layer Demonstration 0.51b ssd1926 Solomon Systech SSD1926 Controller Demonstration 0.51b TCP/IP Applications & Utilities: /apps/tcpip/ tcpip_web_server TCPIP Web Server Demonstration 7.02a utilities/mpfs_generator/mpfs2.jar TCP/IP MPFS File Generator and Upload Utility 2.2.5 utilities/tcpip_dicoverer/tcpip_discoverer.jar TCP/IP Microchip Node Discoverer Utility 2.0 utilities/mib2bib/mib2bib.jar Compiles Custom Microchip MIB script ( snmp.mib) to generate snmp.bib and mib.h 2.0 USB Device (Function) Applications: /apps/usb/device/ audio_speaker USB Audio Device - Speaker Demonstration 0.51b cdc_com_port_dual CDC Dual Serial COM Ports Emulation Demonstration 0.51b cdc_com_port_single CDC Single Serial COM Ports Emulation Demonstration 0.51b generic_device Generic USB Device Demonstration 0.51b hid_basic USB Human Interface Device (HID) Demonstration 0.51b hid_joystick USB HID Joystick Device Demonstration 0.51b hid_keyboard USB HID Keyboard Device Demonstration 0.51b hid_mouse USB HID Mouse Device Demonstration 0.51b msd_basic USB Mass Storage Device Demonstration 0.51b USB Host Applications: /apps/usb/host/ cdc_serial USB CDC Host Demonstration 0.51b Crypto Applications: /apps/ crypto Wolf SSL Cryptographic Demonstration 0.01a PIC32MZ Applications: /apps/ pic32mz PIC32MZ Device Demonstration 0.51.01b Example Applications: /apps/examples peripheral Peripheral Demonstration 0.51b sample Sample Demonstration 0.51b Board Support Packages (BSPs): /bsp/ explorer16/pic32mx795f512l Explorer 16 Development Board and PIC32MX795F512L PIM pic32_sk/pic32_usb_sk PIC32 USB Starter Kit pic32_sk\pic32mz_sk PIC32MZ Starter Kit pic32mx_usb_audio PIC32 USB Digital Audio Accessory Board Third Party Software: /third_party/ rtos/FreeRTOSV7.5.0 FreeRTOS Source Distribution v7.5.0 7.5.0 Middleware: /framework/ 1.4 4. Previous Releases MPLAB Harmony Help v0.51.03b 1-33 gfx Graphics Library 0.51b tcpip TCP/IP Network Stack 7.02a usb USB Host & Device Stack 0.51b Crypto Library: /framework/ crypto Wolf SSL Cryptographic Libraries 0.01a System Services: /framework/system/ clk Clock Services Library 0.03a debug Debug Services Library 0.01a fs File System Services Library 0.02a int Interrupt Services Library 0.03a msg Message Services Library 0.01a ports Input-Output Ports Services Library 0.01a reset System Reset Services Library 0.01a tmr Software Timer Services Library 0.01a wdt Watchdog Timer Services Library 0.01a Device Drivers: /framework/driver/ adc Analog-to-Digital Converter Driver 0.01a ethmac Ethernet Media Access Controller Driver 0.03a ethphy Ethernet Physical Interface Driver 0.03a gfx/gfx_lcc Low-Cost Controllerless Graphics Driver 0.51b gfx/gfx_s1d13517 Epson S1D13517 LCD Controller Driver 0.51b gfx/gfx_ssd1926 Solomon Systech SSD1926 Controller Driver 0.51b nvm Non-Volatile Memory Driver 0.01a pmp Parallel Master Port Driver 0.01a sdcard SD Card Driver (Client of SPI Driver) 0.01a spi Serial Peripheral Interface (SPI) Driver 0.01a tmr Timer Driver 0.01a usart Universal Synchronous/Asynchronous Receiver/Transmitter (USART) Driver 0.01a usb Universal Serial Bus (USB) Controller Driver 0.51b usbhs Hi-Speed USB Controller Driver 0.51b wifi Wi-Fi Driver 0.01a Peripheral Libraries (PLIBs): / framework/peripheral Peripheral Library Source Code 0.51b bin/framework/peripheral Peripheral Pre-Built Binary Libraries for all PIC32 Processors 0.51b build/framework/peripheral Project used for Peripheral Library Prebuilt Binary Libraries Creation 0.51b 1.4 4. Previous Releases MPLAB Harmony Help v0.51.03b 1-34 Operating System Abstraction Layer (OSAL): /framework/osal/ osal.h osal.c OSAL interface 0.51b osal_impl_none.h OSAL implementation that removes the OSAL when not used 0.51b osal_impl_basic.h OSAL "bare metal" (no OS) implemenrtation 0.51b osal_freertos.h osal_freertos.c OSAL implementation for FreeRTOS 0.51b osal_ucos.h osal_ucos.c OSAL implementation for Micrium uCOS-III 0.51b 1.4 4. Previous Releases MPLAB Harmony Help v0.51.03b 1-35 1.5 5. Tips and Tricks This topic provides a few helpful tips and tricks to keep in mind while developing your MPLAB Harmony projects. Description You may find the following MPLAB Harmony "tips" and "tricks" helpful when developing your own MPLAB Harmony projects. 1. After creating a new MPLAB X IDE project, use the project wizard to add MPLAB Harmony libraries to your project and create a set if initial files for your project. After that, your job is to ensure that the necessary initialization and configuration data and definitions are in place and to write your own application. 2. You can use MPLAB Harmony example and demo projects to put together a "first approximation" of your application. 1. Copy the source files from the various example or demo apps to your project. 2. Rename the "APP_Initialize" and "APP_Tasks" functions so that they are all different and will build in your application by simply appending a descriptive name to the end of the existing function names. (Note: you may also need to rename any global data "objects" that conflict with each other from the examples). 3. Call the individual "APP_Initialize" and "APP_Tasks" functions from the "SYS_Initialize" and "SYS_Tasks" functions in your application's configuration files. 4. Use the project wizard to add any required drivers, services, or middleware. 5. At this point, you now have your application made out of several independent state machines. Now, you can begin to develop your own custom application code and modifying any of the code copied from the provided applications to behave as you desire. 1.5 5. Tips and Tricks MPLAB Harmony Help 1-36 1.6 6. Glossary This section contains a glossary of general MPLAB Harmony terms. Description Glossary of Harmony Terms Term Definition Application One or more application modules define the over all behavior of an MPLAB Harmony system. Applications are either demonstrations or examples provided with the installation or are implemented by you, using MPLAB Harmony libraries to accomplish a desired task. Client A client module is any module that uses the services (calls the interface functions) of another module. Configuration An MPLAB Harmony configuration consists of static definitions (C-language "#define" statements), executable source code, and other definitions in a set of files that are necessary to create a working MPLAB Harmony system. (See Start Here for additional information.) Configuration Options Configuration options are the specific set of "#define" statements that are required by any specific MPLAB Harmony library to specify certain parameters (such as buffer sizes, minimum and maximum values, etc.) build that library. Configuration options are defined in the "system_config.h" system-wide configuration header. Driver A "driver" (AKA device driver) is an MPLAB Harmony software module designed to control and provide access to a specific peripheral, either built into the microcontroller or external to it. Driver Index Dynamic MPLAB Harmony drivers (and other dynamic modules) can manage the more than one instance of the peripheral (and other resources) that they control. The "driver index" is a static index number (0, 1, 2,...) that identifies which instance of the driver is to be used. Note: The driver index is not necessarily identical to the peripheral index. The association between these two is made when the driver is initialized. Driver Instance An instance of a driver (or other module) consists of a complete set of the memory (and other resources) controlled by the driver's code. Selection of which set of resources to control is made using a driver index. Note: Even though there may be multiple instances of the resources managed by a dynamic driver, there is only ever one instance of the actual object code. However, static drivers always maintain a 1:1 relationship between resource and code instances. Framework The MPLAB Harmony framework consists of a set of libraries (and the rules and conventions used to create those libraries) that can be used to create MPLAB Harmony systems. Initialization Overrides Initialization overrides are configuration options that can be defined to statically override (at build time) parameters that are normally passed into the "Initialize" function of a driver or other MPLAB Harmony module. This mechanism allows you to statically initialize a module, instead of dynamically initializing the module. Interface The interface to a module is the set of functions, data types, and other definitions that must be used to interact with that module. Middleware The term "middleware" is used to describe any software that fits between the application and the device drivers within an MPLAB Harmony system. It is something of a catch all term that is loosely used to describe libraries that use drivers to access peripheral and then implement communication protocols (such as TCP/IP, USB protocols, and graphics image processing) and other more complex processing that is required to use certain peripherals, but is not properly part of controlling the peripheral itself. Module An MPLAB Harmony software module is a closely related group of functions controlling a related set of resources (memory and registers) that can be initialized and maintained by the system. Most MPLAB Harmony modules provide an interface for client interaction. However, "headless" modules with no interface are possible. 1.6 6. Glossary MPLAB Harmony Help 1-37 Peripheral Index A peripheral index is a static label (usually an C-language "enum" value) that is used to identify a specific instance of a peripheral. Note: Unlike a driver index, which always starts at '0', a peripheral index may be internally represented as any number, letter, or even a base address and the user should not rely on the value itself - only the label. Peripheral Instance An instance of a peripheral is a complete set of the registers (and internal physical resources) necessary to provide the core functionality of a given type of peripheral (either built into the microcontroller or external to it). Note: A specific peripheral instance is identified using a peripheral index. System An MPLAB Harmony system is a complete set of libraries, applications, and configuration items loaded and executing on a specific hardware platform (microcontroller, board, and external peripherals) or the source items necessary to build such a system. Note: Since a system can multiple configurations, one MPLAB Harmony project may support multiple systems through multiple supported configurations. See the demo applications included in the installation for examples. System Service A system service is an MPLAB Harmony module that provides access to and/or control of common system resources (memory and registers) with which other modules (drivers, middleware, libraries and application) may interact. Note: System services, much like drivers, manage sharing of resources so as to avoid conflicts between modules that would otherwise occur if each module attempted to manage the share resource itself. But, unlike drivers, system services do not normally need to be "opened" in order to use them. 1.6 6. Glossary MPLAB Harmony Help 1-38 2 MPLAB Harmony Configurator Help 2 MPLAB Harmony Help 2-39 2.1 MPLAB Harmony Configurator 2.1.1 Introduction This topic provides an overview of the MPLAB Harmony Configurator. Description The MPLAB Harmony Configurator is a MPLAB X IDE plug-in. It must be installed into your MPLAB X IDE installation to be used. 2.1.2 Release Notes MPLAB Harmony Version: v0.70b Release Date: 18Nov2013 Description ==================================== Version 0.02a MPLAB Harmony Configurator Plug-in November 2013 ==================================== Operating System Support MPLAB Harmony Configurator Plug-in was tested on the following operating systems:. • Windows XP SP3 and Windows 7 • Linux OS - Ubuntu • Mac OS v8 Supported Features: • Provides a simple hierarchical way for users to select the MPLAB Harmony modules to be used in the project and adds the selected module source files with the necessary configuration and project settings (include path) into the created MPLAB X IDE project. • Supports importing project related files from relative path. • Adds predefined source and header template files to the MPLAB X IDE project. • Library Configuration is supported only for the TCP/IP and USB libraries. Unsupported Features: • System-related API calls are not added automatically to the system_init.c, main.c, and system_tasks.c files. Only the standard C templates are added to the project. The application code must be added by the user in the application source and header 2.1 MPLAB Harmony Configurator MPLAB Harmony Help Release Notes 2-40 files for a successful compilation of the project. • Library Configuration is not supported for the Graphics library, OSAL, Drivers and Third-Party libraries. However, the corresponding source and header files of the selected modules could be added to the created MPLAB X IDE project using this Configurator. Notes for Users: 1. The terms "MPLAB Configurator" and "MPLAB Configuration Wizard" are used interchangeably throughout the MPLAB Harmony Help. 2. Check for "TODO" tags that are placed in added template files for directions on what sections in the code should be modified or code to be added by the user. Look for system_config.h, system_init.c, system_int.c, system_tasks.c, app.c, app.h, and main.c files. Known Issues: • The Configurator Plug-in generated template files are stored in the MPLAB X IDE project folder (inside the MPLABX_Project.X folder). Users need to add the current directory ‘.’ Path in the MPLAB X Project “properties” > gcc >” include path settings” for removing “the template file not found error”. • The created project may compile but not work, as application and system related API calls are not added automatically to the system_init.c, main.c and system_tasks.c. Only the standard C templates are added to the project. • The MPLAB Harmony Configurator version during installation or in the plug-in description is shown as 0.0.2 where as the actual version of the tool is “0.02a”. • Certain TCP/IP configuration files are getting modified from the default MPLAB Harmony installation directory if the TCP/IP stack is configured using the Configurator. It is recommended to backup these default configuration files: tcpip_config.h, http_config.h, snmp_config.h, ssl_config.h, and telnet_config.h, in case it is necessary to revert back to the default configuration. • TCPIP system_config.h file is not modified in this release of the Configurator to add the configurations from “ * *_config.h”. As explained above, the specific module files get updated. • The Configurator is not preserving the previous project configuration if the TCP/IP sub-modules are selected using the ‘Select to add default modules’ checkbox in the “TCPIP Stack -> tcpip” module tree. • Warning message about ‘template files getting overwritten (if already present)’ is not shown if the USB library configuration is selected. 2.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 2.1 MPLAB Harmony Configurator MPLAB Harmony Help SW License Agreement 2-41 2.2 Using the Configurator 2.2.1 Installing the Configurator Plug-in The MPLAB Harmony Configurator is a MPLAB X IDE plug-in. It must be installed into your MPLAB X IDE installation to be used. Description Location The MPLAB Harmony Configurator (MPLAB X IDE plug-in) is located in the following folder in the MPLAB Harmony installation. \utilities\configurator\com-microchip-harmonyconfigurator.nbm Installation 1. Start MPLAB X IDE and select "Plugins" from the "Tools" menu as shown below. 2. Select the “Downloaded” tab. 3. Click the "Add Plugins..." button, browse to \utilities\configurator\ and open the plug in file "com-microchip-harmonyconfigurator.nbm" as shown below 2.2 Using the Configurator MPLAB Harmony Help Installing the Configurator Plug-in 2-42 4. Ensure that the Check box for the "MPLAB Harmony Configurator" plug-in is selected. Click "Install" as shown below. 2.2 Using the Configurator MPLAB Harmony Help Installing the Configurator Plug-in 2-43 5. Follow the prompts from the installation wizard and continue until the installation completes. Just click "continue”. Once the installation wizard has finished you can close the "Plugins" dialog box. You should now see a "MPLAB Harmony Configurator" option under the "Tools" menu. This indicates that the project wizard was successfully installed. 2.2.2 Running the Configurator Plug-in This session describes how to run the MPLAB Harmony Configurator to add required files from selected modules into MPLAB X IDE project. Note: This version of the Configurator provides Project Configuration (to add files into MPLAB X IDE project) and limited Library Configuration (only for configuring a few sub-modules of the TCP/IP and USB middleware) capability. Description 1. To run the Configurator, select "MPLAB Harmony Configurator" from the "Tools" menu. 2. Browse to the root installation folder of the version of MPLAB Harmony that you're using. This folder must contain "manifest.xml". This file has the information and the path of various software modules available in the installed MPLAB Harmony version. manifest.xml file should not be moved or deleted from Root directory. Click "Next" when the root path is set. 2.2 Using the Configurator MPLAB Harmony Help Running the Configurator Plug-in 2-44 Note: It is recommended that you create and maintain your MPLAB X IDE project under a subdirectory of the "/apps" folder and use a relative path to this project. 3. In the Left-hand pane of the "Select Modules and Configurations" dialog, select the desired modules and respective sub-modules. The right-hand pane shows a brief introduction of the selected module. Click "Next" when the required modules for the project are selected. 2.2 Using the Configurator MPLAB Harmony Help Running the Configurator Plug-in 2-45 The tool has two configuration sections. • Project Configuration: All the required modules and Sub modules could be selected here. The respective files would be added into the MPLAB X IDE project. (example: Graphics, TCP/IP, USB CDC, USB HID selection) • Library Configuration: The individual configuration of each module could be done here. (Configuration for selected module from the selected section.) If the user is required to add their custom module into the MPLAB Harmony directory structure and add the files into the project through Configurator, the manifest.xml should be modified to accommodate the custom module files. This would allow the Project Configurator to add the files to the MPLAB X IDE project from the manifest.xml for the custom module. This would not provide custom configuration capability, however the files can be added to the MPLAB X IDE project. 4. If there are any XML modifications those can be reflected by reloading the tree. To reload the project tree structure, right-click on “harmony” tree node and click "Reload Tree". 5. To get back to default project configuration of MPLAB Harmony, right-click on “harmony” tree node and click "Load default". 2.2 Using the Configurator MPLAB Harmony Help Running the Configurator Plug-in 2-46 Note: Next window pane is for individual library (Modules and Sub modules) configuration. Currently only TCP/IP and USB library configuration is supported. Though all the sub-modules of TCP/IP can be enabled or disabled through project configuration window pane, the individual sub module configuration is supported only for HTTP, SSL, SNMP and Telnet server. For USB, only CDC and HID class configuration basic support is provided. Library Configuration 1. In the "Project configuration" pane, to configure USB CDC select the respective modules and click “Next”. Next window pane is Library Configuration window as shown below. Configure USB CDC as required, click “Next”. 2.2 Using the Configurator MPLAB Harmony Help Running the Configurator Plug-in 2-47 2. In the "Application Template" pane, select the "Include application template" check box and select "Finish" to add the module files and template files to the MPLAB X IDE project. 2.2 Using the Configurator MPLAB Harmony Help Running the Configurator Plug-in 2-48 Note: The generate project may compile for PIC32MZ devices, but not necessarily work on the hardware. The set of template files added to the MPLAB X IDE project would require to be modified with additional configuration information and the custom application code. Later versions of the configuration tool may provide additional configuration options and sample application code for each library, to create a executable project. 2.2.3 Tutorial This tutorial explains about creating a new MPLAB X IDE project and configuring this project using the MPLAB Harmony Configurator. The tutorial provides step by step instructions on how to create a MPLAB X IDE project for the TCP/IP Stack. Description This tutorial explains about creating a MPLAB X IDE project for TCP/IP library by adding required configurations and TCP/IP library files, template files and Peripheral Library modules to the selected MPLAB X IDE project using the Configurator. In this tutorial user would, 1. Create a new project in MPLAB X IDE. 2. Add required source and header files with required configurations for TCP/IP application using MPLAB Harmony Configurator to the MPLAB X IDE project. 3. Add the required Peripheral header files and template files to the MPLAB X IDE project. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-49 Creating an MPLAB X IDE Project 1. Open MPLAB X IDE, and select File > New Project to open a project explorer window. 2. In Categories, select “Microchip Embedded” and in Projects, select “Standalone Project”. Click Next. 3. Select the PIC device. 4. Select optional Debug Header. Click Next. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-50 5. Select a hardware tool and Click Next. 6. Select the appropriate compiler. Click Next. 7. Name the MPLAB X IDE project and specify its path. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-51 For this tutorial, create a project by name “MyHarmoyConfDemoProject”. Set the project as main project. Click Finish. Now the project MyHarmonyConfDemoProject” is created. Note: It is recommended that you maintain your project under a subdirectory of the "/apps" folder and use a relative path to your project. Once the MPLAB X IDE project is created, you should see a screen similar to the picture as shown below. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-52 Using MPLAB Harmony Configurator 1. After creating the MPLAB X IDE project, select “Tools -> MPALB Harmony Configuration wizard” to open this plug-in with MPLAB X IDE. "MPLAB Harmony Configurator" will open in a new dialogue, as shown below. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-53 2. Browse to the root directory path under "MPLAB Harmony Root Directory" option. This path is remembered by the Configurator for subsequent usage. Check or uncheck the "Relative Path" check box as required. Once the path is set, click "Next". 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-54 3. Now configure required middleware modules and Peripheral Library modules. Peripheral Library headers are selected by default by the tool. For this tutorial user will configure TCP/IP Library. Select the required configuration modules of TCP/IP modules and also other middleware modules in the Tree structure. Click "Next" once the selection is complete. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-55 For this release, both the TCP/IP and USB module Library Configuration Pane will appear. For this Tutorial, the TCP/IP module is selected (default selection ”tcpip ”node) in tree, we get the Library Configuration as below. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-56 4. Select the required configurable items of TCP/IP, and click next (Next button in “Library configuration navigation pane) which takes to next TCP/IP configuration pane, and continue until the last configuration pane. Once TCP/IP configuration is done, click Next(Next button at the bottom of TCP/IP Library configuration pane) which takes into the next window "Application Template" to include template files. 5. Select to Include MPLAB Harmony Application template files. Tool would add template files (main.c, app.c, system_init.c, system_tasks.c, system_int.c, system_config.h and app.h) to MPLAB X IDE project. Click "Finish". 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-57 6. Check for selected files being added in MPLAB X IDE project. The following figure shows the MPLAB X IDE project with the added files. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-58 The "MPLAB Harmony Assembly Generator" window in MPLAB X IDE shows the list of files added from "MPLAB Harmony Configurator" to the MPLAB X IDE project. 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-59 2.2 Using the Configurator MPLAB Harmony Help Tutorial 2-60 3 Applications Help 3 MPLAB Harmony Help 3-61 3.1 Applications Overview Applications use MPLAB Harmony libraries and define the behavior of a system. Description Applications determine how MPLAB Harmony libraries (device drivers, middleware, and system services) are used to do something useful. In an MPLAB Harmony system, there may be one main application, there may be multiple independent applications or there may be one or more Operating System (OS) specific applications. Applications interact with MPLAB Harmony libraries through well defined interfaces. Applications may operate in a strictly polling environment, they may be interrupt driven, they may be executed in OS-specific threads, or they may be written so as to be flexible and easily configured for any of these environments. Applications generally fit into one of the following categories: Demo Applications: Demos applications are provided (with MPLAB Harmony or in separate installations) to demonstrate typical or interesting usage models of one or more MPLAB Harmony libraries. Demonstration applications can demonstrate realistic solutions to real-life problems. Sample Applications: Sample applications are extremely simple applications provided with MPLAB Harmony as examples of how to use individual features of a library. They will not normally accomplish anything useful on their own. They are provided primarily as "documentation" to show how to use a library. Skeletal Applications: Skeletal applications are provided as bare-bones “skeletons” (potentially targeted to a specific usage or market) that MPLAB Harmony developers can use as a starting point to for writing their own applications. Skeleton applications contain the necessary calls, configuration definitions and subroutine stubs with “To Do” items clearly marked for MPLAB Harmony developers to fill in as desired to create a working application. Customer Applications: Customer applications are (of course) not provide by Microchip. Rather, they are any applications developed by customers to suit specific hardware and software needs. Refer to the Start Here help topic for information on the structure and to learn how to develop your own MPLAB Harmony applications. Application Directories Applications are contained in the "/apps" folder. Under the "apps" folder, they are grouped by technology, board, and/or market segment. Examples: Folder Type of Demos /apps/examples/peripheral Contains simple peripheral library example applications /apps/fs Contains graphics library demonstration applications /apps/gfx Contains TCP/IP networking stack demonstration applications /apps/tcpip Contains USB device demonstration applications 3.1 Applications Overview MPLAB Harmony Help 3-62 /apps/usb/device Contains USB host demonstration applications Additional Information Refer to Release Notes & Information for a complete listing of applications included with this release. Refer to the help documentation for each individual application for build instructions and information on required hardware and application usage. 3.1.1 System Overview To support the framework, the application (or application developer) is responsible for the following: • Configuring the Framework - Required, unless using a pre-built library. Each driver, middleware layer, and system service require build-time configuration options that must be defined for the specific application, board, and processor that is used by any particular demo or customer application. Please refer to the help file of that module on the list of configuration options, and how they apply to the application.The application can use the board support package configuration file or define its own configuration for the board. • Building the Framework Library - Required, unless using a prebuilt library • Implementing the System Initialization service. Please refer to the help file for the system initialization service for information on implementing it statically or dynamically • Implementing a Interrupt Service Routine (ISR) - Required, unless polled. Please refer to the help file for system tasks service for examples on implementing ISRs. • Implementing the System Tasks routine - Please refer to the help file for system tasks service for how to implement it statically or dynamically 3.1 Applications Overview MPLAB Harmony Help System Overview 3-63 3.2 File System Demonstrations 3.2.1 Introduction MPLAB Harmony File System Demonstration Help Description This help file contains instructions and associated information about MPLAB Harmony File System demonstration applications, which are contained in the MPLAB Harmony Library distribution. 3.2.2 Release Notes MPLAB Harmony Version: v0.70b File System Demonstrations Version : 0.01a Release Date: 18Nov2013 The interface can change in the beta and\or 1.0 release. For the latest release information, please refer to the File System Service Library Release Notes section. New This Release: Nothing to report for this release. Known Issues: Nothing to report for this release. 3.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have 3.2 File System Demonstrations MPLAB Harmony Help SW License Agreement 3-64 paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.2.4 Demonstrations Provides instructions on how to run the demonstration applications. Description The following demonstration applications are available in this release of the MPLAB Harmony File System framework. 3.2.4.1 Overview Provides an overview of how most of the File System Demonstration applications are structured. Description The MPLAB Harmony File System Demonstration Applications show example usage of the File System framework. These demonstration applications also contain example configurations of media drivers such as Internal Flash and SD Card, that can be used readily in the end application with the some changes to initialization parameters, if required. A demonstration application may have multiple MPLAB X IDE project configurations (for different demonstration hardware and microcontrollers). The relevant configuration should be selected in the MPLAB X IDE before compiling the demonstration. Figure 1 shows the dialog box in MPLAB X IDE that allows selection of different configurations. Figure 1: Demonstration MPLAB X IDE Configurations The project will contain files which are configuration specific. Wherever applicable, these configuration files are placed in separate MPLAB X IDE project logical folders. Figure 2 shows how the configuration dependant nvm_disk_images.c file is included in the project. In this case two configurations (pic32mx_usb_sk_Int_dyn and pic32mz_sk_int_dyn) are supported in the project. Figure 2: Configuration specific file in File System Demonstration Projects. Note that some demonstration projects may not support all configurations. In general, the following the demonstration project contain the following MPLAB X IDE configurations: • pic32mx_usb_sk_int_dyn: This configuration runs on the PIC32 USB Starter Kit. The media drivers are configured for interrupt and dynamic operation 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-65 • pic32mz_sk_int_dyn: This configuration runs on the PIC33MZ Embedded Connectivity (EC) Starter Kit. Some demonstration projects that support this configuration may need the Multimedia Expansion Board II (MEB II) to attached to the starter kit. The media drivers in this configuration are configured for interrupt and dynamic operation. Unless specified, the File System demonstration application are structured as indicated in Figure 3. Figure 3: File System Demonstration Application General Architecture Here are some general notes while working with the demonstration applications: 1. The system and application is initialized in SYS_Initialize() function, implemented in sys_init.c. The sys_init.c file is configuration specific. The SYS_Initialize() function initializes the application (APP_Initialize() function) and the BSP (BSP_Initialize() function). 2. The application then calls SYS_Tasks() function in an infinite loop. This function updates the state machines of all system components in the demonstration application and also calls the APP_Tasks() function. The is implemented in file sys_tasks.c which is configuration specific. 3. All Interrupt service routines are implemented in sys_interrupt.c. This file is configuration specific. 3.2.4.2 nvm_fat_single_disk This demonstration uses a FAT12 image of file on NVM flash memory and demonstrates the working of all file system functions. Description This demonstration shows an example of implementing a FAT12 disk in device Flash memory. The demonstration contains a FAT12 disk image consisting of a Master Boot Record (MBR) sector, Logical Boot Sector, File Allocation Table, Root Directory Area. The demonstration opens an existing file named "FILE.TXT" and performs all file system related function calls on the file viz. SYS_FS_FileStat, SYS_FS_FileSize, SYS_FS_FileSeek, SYS_FS_FileEOF. Finally, the string "Hello World" is written to this file. The file is then closed and reopend for read. The read string is then compared with the string which was written to the file. If the string compare is successful, LED indication is provided. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-66 3.2.4.2.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - Following board is supported for PIC32MZ devices: - Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.2.4.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.2.4.2.3 Running the Demonstration Provides instructions on how to build and run the NVM FAT single disk demonstration. Description Select the MPLAB X IDE project configuration: - • pic32mx_usb_sk_int_dyn -- For PIC32MX devices • pic32mz_sk_int_dyn -- For PIC32MZ devices Build the selected configuration in the MPLAB X IDE project and program the demonstration board. The execution status (pass/fail) of the demonstration is indicated by LEDs on the demonstration board. Demonstration Board Demonstration Successful Demonstration Failure PIC32 USB Starter Kit II LED3 LED1 PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED About the demonstration: This demonstration shows an example of - implementing a FAT12 disk in device Flash memory. - opening a file for read or write. - implements all the file system functions. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-67 - closing a file. The demonstration contains a FAT12 disk image consisting of a Master Boot Record (MBR) sector, Logical Boot Sector, File Allocation Table, Root Directory Area. This image is implemented in the file nvm_disk_images.c (this is project configuration specific file and is contained in the nvm_disk_images logical folder in the MPLAB X IDE project). The image contains a single file named "FILE.TXT" which contains the string "Data". The demonstration opens an existing file named "FILE.TXT" and performs all file system related function calls on the file viz. SYS_FS_FileStat, SYS_FS_FileSize, SYS_FS_FileSeek, SYS_FS_FileEOF. Finally, the string "Hello World" is written to this file. The file is then closed and reopened for read. The read string is then compared with the string which was written to the file. If the string compare is successful, LED indication is provided. The demonstration application logic is implemented as a state machine in the APP_Tasks() function in the file main.c. 1. The disk is first mounted using the SYS_FS_Mount() function. The "/dev/nvma1" path instructs the mount command to mount an internal flash volume. The volume is mounted against a FAT type file system and mounted at "/mnt/myDrive/". 2. If the mount is successful, the application opens a file "FILE.TXT" for reading and writing (SYS_FS_FILE_OPEN_READ_PLUS) with a SYS_FS_FileOpen() function. The valid file handle is received once a successful opening of file is performed. 3. If file open is successful, the status of file "FILE.TXT" is stored in the appData.fileStatus structure, using SYS_FS_FileStat() function. 4. If the file status check is successful, the size of the "FILE.TXT" is checked by passing the file handle to the SYS_FS_FileSize() function. 5. If the file size check is successful, the size of file is compared with the size element received earlier as a part of appData.fileStatus structure. If both value matches, then the code moves to the next step of file seek. 6. The file pointer is then moved by 4 bytes from the start of the file by calling the function SYS_FS_FileSeek() and passing parameter as SYS_FS_SEEK_SET (seek from the beginning of the file). 7. If the file seek operation is successful, the file pointer should have reached the end of the file. This is because, the content of the FILE.TXT had only 4 byte string = "Data". The end of file is verified by calling the function SYS_FS_FileEOF(). If the function returns "true" (end of file reached), the next step is performed. 8. In the next step, the file pointer is moved again by [(-1)*size of file], from the end of the file by calling the function SYS_FS_FileSeek() and passing parameter SYS_FS_SEEK_END (seek from the end of the file). 9. If the file seek operation is successful, the file pointer should have reached the beginning of the file. 4 Bytes are read from the file using SYS_FS_FileRead() function (into a buffer). 10. If the read is successful, the content of file (present in the buffer) is compared with the "Data" string. If the comparison passed, the code moves to the next step. 11. In the next step, the file pointer is moved again by [(-1)*size of file], from the end of the file by calling the function SYS_FS_FileSeek() and passing parameter SYS_FS_SEEK_END (seek from the end of the file). 12. If the file seek operation is successful, the string "Hello World" is written to the file using SYS_FS_FileWrite() function. 13. If the write operation is successful, the file is closed. 14. The file "FILE.TXT" is opened again in read mode (SYS_FS_FILE_OPEN_READ). 15. If the file open is successful, the content of the file is read using SYS_FS_FileRead() function (into a buffer). 16. If the read operation is successful, the content of the file (present in the buffer) is compared with the "Hello World" string using the strcmp() function. A LED indicates the success of the demonstration. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-68 3.2.4.3 sd_card_fat_single_disk This demonstration uses the SDTM Card with FAT file system as media and performs a read/ write / verify operation on the files using long file names (LFN). Description This demonstration shows an example of using the MPLAB Harmony File System to access and modify the contents of an SDTM Card. The demonstration opens a file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG" on the SD Card, reads the content of the file and writes the content into another file "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" (create a copy of one file into another file). The input file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG" is not provided along with the release package. It could be any arbitrary JPG (picture) file chosen by user and then suitably renamed to "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG". The reason for choosing a JPG file for test purpose is that the duplicate file "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" created by the FS demonstration could be easily verified for correctness by inserting the SD card in computer and opening the "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" file. If the file "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" opens for viewing on the computer, the test is deemed to have passed. Otherwise, if the "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" does not open (is corrupted), the test will be considered as failed. 3.2.4.3.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demonstration Board (click link for board information) PIC32MX795F512L Plug-In-Module (PIM) PICtail Daughter Board for SD and MMC Note: This board can not be used by itself. An Explorer 16 Development Board is required. Following board is supported for PIC32MZ devices: - Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - Note: This board can not be used by itself. An Multimedia Expansion Board II (MEB II) is required to run the demonstration. 3.2.4.3.2 Configuring the Hardware Describes how to configure the supported hardware. Description Explorer 16 Development Board Based Demonstrations Use the following instructions for all Explorer 16 Development Board-based demonstration boards: PIC32MX795F512L PIM 1. Insert the PIM into the Explorer 16 Development Board PIM connector. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-69 2. Jumpers JP1, JP2 and JP3 on the SD Card PICtail Daughter Board should connect to points 2 and 3 on their respective connectors as shown here. 3. Insert the SD Card PICtail Daughter Board into the PICtail Plus connector on the Explorer 16 Development Board. 4. Insert a SD card into the SD card connector on the SD Card PICtail Daughter Board. 5. Power up the board. Multimedia Expansion Board II (MEB II) No hardware setting change is required. Insert the micro SD card into the connector and power up the board. 3.2.4.3.3 Running the Demonstration Provides instructions on how to build and run the SD card FAT single disk demonstration. Description Select the MPLAB X IDE project configuration: - • exp16_32mx_int_dyn -- For PIC32MX devices • pic32mz_sk_int_dyn -- For PIC32MZ devices Insert the SD card, which contains the file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG". The file can be of any size. Compile the selected configuration in the MPLAB X IDE project and run the code. After a few seconds, once the LED glows, remove the SD card from the SD Card PICtail Daughter Board (for PIC32MX) or MEB2 Board (for PIC32MZ) and insert it into the SD card reader on a PC. Examine the contents of the SD card and another file named "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" would have been created. "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" will be a copy of "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG". Verify both the files opens for viewing on the PC. Demonstration Board Demonstration Successful Demonstration Failure Explorer 16 Development Board LED5 (D5) LED6 (D6) PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED About the demonstration: This demonstration shows an example of - implementing a FAT File system (FAT16/ FAT32) on SD card. - implementing long file name (LFN). - opening a file for read or write. - closing a file. The demonstration opens a file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG" on the SD Card, reads the content of the file and writes the content into another file "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" (create a copy of one file into another file). The demonstration application logic is implemented as a state machine in the APP_Tasks() function in the file main.c. 1. The disk is first mounted using the SYS_FS_Mount() function. The "/dev/mmcblka1" path instructs the mount command to mount a SD card volume. The volume is mounted against a FAT type file system and mounted at "/mnt/myDrive/". 2. If mount is successful, the volume is unmouned by passing the mount name "/mnt/myDrive" to SYS_FS_Unmount() function. This unmounting is done for demonstration purpose only. Real application do not need to unmount unless it is required for the application. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-70 3. If unmount is successful, the mounting process is repeated. 4. If the mount is successful, the application opens a file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG" for reading with a SYS_FS_FileOpen() function. 3. If the file open is successful, the application opens a file "FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG" for writing with SYS_FS_FileOpen() function. The attributes for file write is selected as "SYS_FS_FILE_OPEN_WRITE". Hence, if the file does not exist on the drive, the file is created. 4. If the file open is successful, 512Bytes from the file "FILE_TOO_LONG_NAME_EXAMPLE_123.JPG" is read into application buffer using SYS_FS_FileRead() function. 5. If the file read successful, the 512Bytes is written from the application buffer to the FILE_TOO_LONG_NAME_EXAMPLE_123_1.JPG file using SYS_FS_FileWrite() function. 6. If the write operation is successful, the end of file for FILE_TOO_LONG_NAME_EXAMPLE_123.JPG is checked. If the end of file is not reached, the process of reading and writing continues (step - 4 and step - 5). 7. Once end of file is reached, both the files are closed with SYS_FS_FileClose() function. 8. Finally, a LED indicates the success of the demonstration. 3.2.4.4 nvm_sdcard_fat_multi_disk This demonstration uses NVM and SDTM Card as 2 media and reads files from one media and write onto another media. Description This demonstration shows an example of using the MPLAB Harmony File System to access files across multiple media. The demonstration contains a FAT12 disk image consisting of a Master Boot Record (MBR) sector, Logical Boot Sector, File Allocation Table, Root Directory Area, placed in the internal flash memory (NVM). Also, a SD card is used as another disk, which might have FAT16 or FAT32 implemented on it (depends on the formatting of SD card).The demonstration reads the contents of "FILE.TXT" in NVM and copies the contents to "FILE.TXT" in the SDTM Card. If the write operation is successful, LED indication is provided. 3.2.4.4.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demonstration Board (click link for board information) PIC32MX795F512L Plug-In-Module (PIM) PICtail Daughter Board for SD and MMC Note: This board can not be used by itself. An Explorer 16 Development Board is required. Following board is supported for PIC32MZ devices: - Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - Note: This board can not be used by itself. An Multimedia Expansion Board II (MEB II) is required to run the demonstration. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-71 3.2.4.4.2 Configuring the Hardware Describes how to configure the supported hardware. Description Explorer 16 Development Board Based Demonstrations Use the following instructions for all Explorer 16 Development Board-based demonstration boards: PIC32MX795F512L PIM 1. Insert the PIM into the Explorer 16 Development Board PIM connector. 2. Jumpers JP1, JP2 and JP3 on the SD Card PICtail Daughter Board should connect to points 2 and 3 on their respective connectors as shown here. 3. Insert the SD Card PICtail Daughter Board into the PICtail Plus connector on the Explorer 16 Development Board. 4. Insert a SD card into the SD card connector on the SD Card PICtail Daughter Board. 5. Power up the board. Multimedia Expansion Board II (MEB II) No hardware setting change is required. Insert the micro SD card into the connector and power up the board. 3.2.4.4.3 Running the Demonstration Provides instructions on how to build and run the NVM SD card FAT multi disk demonstration. Description Select the MPLAB X IDE project configuration: - • exp16_32mx_int_dyn -- For PIC32MX devices • pic32mz_sk_int_dyn -- For PIC32MZ devices Insert the SD card, which contains the file "FILE.TXT" and the file contains "abc" (some arbitrary existing content). Compile the selected configuration in the MPLAB X IDE project and run the code. After a few seconds, once the LED glows, remove the SD card from the Board and insert it into the SD card reader on a PC. Examine the contents of the file named "FILE.TXT". The file should contain the string "This data is from NVM Disk". Demonstration Board Demonstration Successful Demonstration Failure Explorer 16 Development Board LED5 (D5) LED6 (D6) PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED About the demonstration: This demonstration shows an example of: - implementing a multi disk demonstration with FAT12 on internal flash memory (NVM) and FAT File system (FAT16/ FAT32) on SD card. - opening two files from two different disks, read content of file from first disk and write into the file of second disk. - closing the files. The demonstration contains a FAT12 disk image consisting of a Master Boot Record (MBR) sector, Logical Boot Sector, File Allocation Table, Root Directory Area, placed in the internal flash memory (NVM). Also, a SD card is used as another disk, which 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-72 might have FAT16 or FAT32 implemented on it (depends on the formatting of SD card).The demonstration reads the contents of "FILE.TXT" in NVM and copies the contents to "FILE.TXT" in the SDTM Card. If the write operation is successful, LED indication is provided. The demonstration application logic is implemented as a state machine in the APP_Tasks() function in the file main.c. 1. The first disks is mounted using the SYS_FS_Mount() function. The "/dev/nvma1" path instructs the mount command to mount a internal flash volume. The volume is mounted against a FAT type file system and mounted at "/mnt/myDrive1/". 2. If the mount is successful, the second disks is mounted using the SYS_FS_Mount() function. The "/dev/mmcblka1" path instructs the mount command to mount a SD card volume. The volume is mounted against a FAT type file system and mounted at "/mnt/myDrive2/". 3. If the mount is successful, the application opens a file "FILE.TXT" from "/mnt/myDrive1/" for reading and "FILE.TXT" from "/mnt/myDrive2/" for writing with a SYS_FS_FileOpen() function. 4. If the file open is successful, the application reads 27Bytes from "FILE.TXT" of internal flash volume using SYS_FS_FileRead(). 5. If the read is successful, the application closes the "FILE.TXT" from internal flash volume and then writes the 27Bytes into "FILE.TXT" of SD card volume using SYS_FS_FileWrite(). 6. If the write is successful, the application closes the "FILE.TXT" from SD card volume. 7. If file close is successful, LED indicates the success of the operation. 3.2.4.5 nmv_mpfs_single_disk This demonstration uses a MPFS image of 3 files on NVM flash memory and demonstrates the working of all file system functions. Description This demonstration shows an example of implementing a MPFS disk in device Flash memory. The demonstration contains a MPFS disk image in the internal flash memory. The disk image contains 3 files named: - "FILE.txt" , Size = 11Bytes. The content of the file is -- "Hello World". "ABC.txt", Size = 31744Bytes. The content of the file is not important. Just a file of sufficiently big size. "TEST.txt" , Size = 72Bytes. The content of the file is -- "This file contains a test string and it is meant for testing. 1234567890". The demonstration performs all file system related function calls on the file viz. SYS_FS_FileRead, SYS_FS_FileStat, SYS_FS_FileSize, SYS_FS_FileSeek, SYS_FS_FileEOF. If all the test succeeds, LED indication is provided. 3.2.4.5.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-73 Following board is supported for PIC32MZ devices: - Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.2.4.5.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.2.4.5.3 Running the Demonstration Provides instructions on how to build and run the NVM MPFS single disk demonstration. Description Select the MPLAB X IDE project configuration: - • pic32mx_usb_sk_int_dyn -- For PIC32MX devices • pic32mz_sk_int_dyn -- For PIC32MZ devices Build the selected configuration in the MPLAB X IDE project and program the demonstration board. The execution status (pass/fail) of the demonstration is indicated by LEDs on the demo board. Demonstration Board Demonstration Successful Demonstration Failure PIC32 USB Starter Kit II LED3 LED1 PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED About the demonstration: This demonstration shows an example of - implementing a MPFS disk in device Flash memory. - opening a file for read. - implements all the file system functions. - closing a file. This demonstration shows an example of implementing a MPFS disk in device Flash memory. The demonstration contains a MPFS disk image in the internal flash memory. The disk image contains 3 files named: - "FILE.txt" , Size = 11Bytes. The content of the file is -- "Hello World". "ABC.txt", Size = 31744Bytes. The content of the file is not important. Just a file of sufficiently big size. "TEST.txt" , Size = 72Bytes. The content of the file is -- "This file contains a test string and it is meant for testing. 1234567890". The demonstration application logic is implemented as a state machine in the APP_Tasks() function in the file main.c. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-74 1. The disk is first mounted using the SYS_FS_Mount() function. The "/dev/nvma1" path instructs the mount command to mount an internal flash volume. The volume is mounted against a MPFS2 type file system and mounted at "/mnt/myDrive/". 2. If the mount is successful, the application opens a file "FILE.txt" for reading with a SYS_FS_FileOpen() function. 3. If the open is successful, the application opens another file "TEST.txt" for reading with SYS_FS_FileOpen() function. 4. If open is successful, the application checks the status of another file "ABC.txt" using SYS_FS_FileStat() function and stores the status of the file into the structure "appData.fileStatus". 5. If file status check is successful, the application compares the size of file (from "appData.fileStatus" structure) with the known value of 31744 (Bytes). 6. If the comparison is successful, the application checks for size of file "FILE.txt", by passing the handle obtained during file open, to the function SYS_FS_FileSize(). 7. If the file size matches the known value of 11 (Bytes), the application moves the file pointer for the file "TEST.txt" 10Bytes from the end of file, using the function SYS_FS_FileSeek(). 8. If file seek is successful, 10 Bytes of content of the file "TEST.txt" is read into the application buffer, using the function SYS_FS_FileRead(). 9. If read is successful, the application buffer content is compared with the known string of "1234567890" using the strncmp() function. 10. If the comparison is successful, the application checks if the file pointer for file "TEST.txt" has reached the end of file using the SYS_FS_FileEOF() function. 11. If end of file is reached, a LED indicates the success of the demonstration. 3.2.4.6 nvm_sdcard_fat_mpfs_multi_disk This demonstration uses NVM and SDTM Card with MPFS and FAT image of file and performs a read/ write/ verify operation from file of one media to another media. Description This demonstration shows an example of using the MPLAB Harmony File System to access files across multiple disks and multiple file system. The demonstration contains a MPFS disk image in the internal flash memory. The disk image contains a file named "abc.txt" with content "Hello World". Another disk is a SD card, which is formatted to FAT (FAT16 or FAT32). The demonstration reads the contents of "abc.txt" from the disk implemented on internal flash memory and writes the contents to "FILE.TXT" on the SDTM Card. A successful write is indicated by a LED glow. 3.2.4.6.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demonstration Board (click link for board information) PIC32MX795F512L Plug-In-Module (PIM) PICtail Daughter Board for SD and MMC Note: This board can not be used by itself. An Explorer 16 Development Board is required. 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-75 Following board is supported for PIC32MZ devices: - Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - Note: This board can not be used by itself. An Multimedia Expansion Board II (MEB II) is required to run the demonstration. 3.2.4.6.2 Configuring the Hardware Describes how to configure the supported hardware. Description Explorer 16 Development Board Based Demonstrations Use the following instructions for all Explorer 16 Development Board-based demonstration boards: PIC32MX795F512L PIM 1. Insert the PIM into the Explorer 16 Development Board PIM connector. 2. Jumpers JP1, JP2 and JP3 on the SD Card PICtail Daughter Board should connect to points 2 and 3 on their respective connectors as shown here. 3. Insert the SD Card PICtail Daughter Board into the PICtail Plus connector on the Explorer 16 Development Board. 4. Insert a SD card into the SD card connector on the SD Card PICtail Daughter Board. 5. Power up the board. Multimedia Expansion Board II (MEB II) No hardware setting change is required. Insert the micro SD card into the connector and power up the board. 3.2.4.6.3 Running the Demonstration Provides instructions on how to build and run the NVM SD card FAT MPFS multi disk demonstration. Description Select the MPLAB X IDE project configuration: - • exp16_32mx_int_dyn -- For PIC32MX devices • pic32mz_sk_int_dyn -- For PIC32MZ devices Insert the SD card, which contains the file "FILE.TXT" and the file contains "abc" (some arbitrary existing content). Compile the selected configuration in the MPLAB X IDE project and run the code. After a few seconds, once the LED glows, remove the SD card from the SD Card PICtail Daughter Board and insert it into the SD card reader on a PC. Examine the contents of the file named "FILE.TXT". The file should contain the string "Hello World". Demonstration Board Demonstration Successful Demonstration Failure Explorer 16 Development Board LED5 (D5) LED6 (D6) PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED About the demonstration: This demonstration shows an example of - implementing a multi disk demonstration with MPFS on internal flash memory (NVM) and FAT File system (FAT16/ FAT32) on 3.2 File System Demonstrations MPLAB Harmony Help Demonstrations 3-76 SD card. - opening two files from two different disks, read content of file from first disk and write into the file of second disk. - closing the files. The demonstration contains a MPFS disk image in the internal flash memory. The disk image contains a file named "abc.txt" with content "Hello World". Another disk is a SD card, which is formatted to FAT (FAT16 or FAT32). The demonstration reads the contents of "abc.txt" from the disk implemented on internal flash memory and writes the contents to "FILE.TXT" on the SDTM Card. A successful write is indicated by a LED glow. The demonstration application logic is implemented as a state machine in the APP_Tasks() function in the file main.c. 1. The first disks is mounted using the SYS_FS_Mount() function. The "/dev/nvma1" path instructs the mount command to mount a internal flash volume. The volume is mounted against a MPFS2 type file system and mounted at "/mnt/myDrive1/". 2. If the mount is successful, the second disks is mounted using the SYS_FS_Mount() function. The "/dev/mmcblka1" path instructs the mount command to mount a SD card volume. The volume is mounted against a FAT type file system and mounted at "/mnt/myDrive2/". 3. If the mount is successful, the application opens a file "abc.txt" from "/mnt/myDrive1/" for reading and "FILE.TXT" from "/mnt/myDrive2/" for writing with a SYS_FS_FileOpen() function. 4. If the file open is successful, the application reads 13Bytes from "abc.txt" of internal flash volume using SYS_FS_FileRead(). 5. If the read is successful, the application closes the "abc.txt" from internal flash volume and then writes the 13Bytes into "FILE.TXT" of SD card volume using SYS_FS_FileWrite(). 6. If the write is successful, the application closes the "FILE.TXT" from SD card volume. 7. If file close is successful, LED indicates the success of the operation. 3.2.5 Demonstration Board Information Information on Hardware used by the File System Demonstration Applications. Description The File System Library Demonstration Applications can be tried across different hardware boards. This section provide details on these hardware boards. 3.2.5.1 PIC32 USB Starter Kit II Hardware Information: 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-77 SW1 - Application switch. Tied to RD6. SW2 - Application switch. Tied to RD7. SW3 - Application switch. Tied to RD13. LED1 - Application LED. Tied to RD0. LED2 - Application LED. Tied to RD1. LED3 - Application LED. Tied to RD2. More Information Product webpage 3.2.5.2 Explorer 16 Development Board Hardware Information: 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-78 S1 - Reset button (MCLR) S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM). S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use. D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use. More Information: Product webpage 3.2.5.3 PIC32MX795F512 Plug-In-Module (PIM) More Information Product webpage 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-79 3.2.5.4 PICtail Daughter Board for SD and MMC More Information: Product webpage. 3.2.5.5 PIC32MZ Embedded Connectivity (EC) Starter Kit Provides details information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-80 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-81 3.2.5.6 Multimedia Expansion Board II (MEB II) Provides details information on the Multimedia Expansion Board II (MEB) II. Description Microchip Part Number: DM320005-2 Product Page The front side of the MEB II includes these key features, as shown in Figure 1: 1. Display daughter board connector (60-pin Hirose board-to-board connector). 2. mTouch™ buttons. 3. Push Button. 4. Power LED. 5. User LEDs. 6. VGA Camera (OVM7690). 7. PICtail™ Connector. 8. Analog temperature sensor. Figure 1: Multimedia Expansion Board II Layout (Front) The underside of the MEB II includes these key features, as shown in Figure 2: 1. Regulated 5V and 3.3V power supply for powering the board via a 9-15V DC Adapter. 2. PIC32 Starter Kit connector (168-pin Hirose board-to-board connector). 3. 24-bit stereo audio codec (AK4953A). 4. Integrated 802.11bg wireless module (MRF24WG0MA). 5. Low-cost Bluetooth® HCI transceiver (BTM805). 6. EBI SRAM memory (IS61WV102416BLL). 7. microSD slot. 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-82 8. Analog accelerometer (ADXL325). Figure 2: Multimedia Expansion Board II Layout (Back) 3.2 File System Demonstrations MPLAB Harmony Help Demonstration Board Information 3-83 3.3 Graphics Demonstrations 3.3.1 Introduction Graphics Library Demonstrations Applications Help Description This distribution package contains a variety of Graphics-related firmware projects that demonstrate the capabilities of the MPLAB Harmony Graphics library. This help file describes the hardware requirement and procedures to run these firmware projects on Microchip graphics boards. To know more about MPLAB Harmony Graphics, configuring the library and the APIs provided; refer to the Graphics Library documentation. Graphic Demonstration Description Primitive Cyclically demonstrates various types of shapes and images, which include circles, lines, and rectangles that can be created from the Graphics Library. Object Touch interactive demonstration of various pages of objects that can be created from the Graphics Library. ssd1926 Touch interactive demonstration of JPEG decoded images from an SD card utilizing the JPEG decoder of the Solomon Systech SSD1926 graphics controller. lcc Demonstrates the advanced capabilities of the Graphics Library utilizing the software graphics controller. 3.3.2 Release Notes MPLAB Harmony Version: v0.70b Graphics Demonstrations Version : 4.00b Release Date: 18Nov2013 New This Release: Nothing to report for this release. Known Issues: LCC Demonstration: For the PIC32MZ Embedded Connectivity (EC) Starter Kit, after programming, the application may not display the UI folders as expected. If this occurs, to activate the UI display, touch the screen in the folder icons area. This issue will be addressed in the next release of MPLAB Harmony. 3.3 Graphics Demonstrations MPLAB Harmony Help SW License Agreement 3-84 3.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.3.4 Demonstrations This topic provides information on how to run the Graphics Library demonstration applications included in this release. Description All demonstrations provided should be built using the MPLAB X IDE development environment tool supplied by Microchip. The information that follows, communicate the general steps to building the graphics demos. • Using MPLAB X IDE, click the File drop-down, select "Open Project...". Navigate to your Harmony installation folder. The default location on Windows will be: C:\Microchip\Harmony\\apps\gfx. • In the \app\gfx folder there will be the object, primitive, lcc, and ssd1926 demonstration applications. • Within each demonstration folder, there will be a firmware folder. In the firmware folder will exist the MPLAB X IDE project specific to each demonstration. • Select the project and click "Open Project" • To configure the project specific to a preset board configuration, right click on the project and select "Set Configuration". This will set the build configuration to match the supported board configuration. 3.3.4.1 lcc_demo Demonstrates the advanced capabilities of the Graphics Library utilizing the software graphics controller. Description This demonstration provides the ability to display alpha blend and gradient colors through the software graphics controller. The demonstration renders four folders for alpha blend, gradient, picture-in-picture (PIP), and performance for all PIC32 devices. For PIC32MX devices, the demonstration runs on the PICtail Plus LCC Daughter Board, and on PIC32MZ devices, it runs on the Multimedia Expansion Board II (MEB II). 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-85 3.3.4.1.1 Supported Demonstration Boards Lists supported demo and development hardware boards. Description Demo Board (click link for board information) Notes PIC32 USB Starter Kit II - Graphics PICtail LCC Board AC164144 - WQVGA 480x272 Board AC164127-6 - Multimedia Expansion Board II (MEB II) - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.3.4.1.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. Multimedia Expansion Board II (MEB II) The MEB II has two memory options: External or Internal. This demonstration requires External EBI memory, which is configured using the following J9 jumper settings: • EBIOE and LCD_PCLK (jumper is closed) • EBIWE (jumper is open) 3.3.4.1.3 Running the Demonstration Provides instructions on how to build and run the LCC demo. Description Select one of the following build configurations to build the LCC demo: • pic32mxusbsk_pictaillcc_wqvga -- For PIC32MX devices • pic32mzsk_meb2_wqvga -- For PIC32MZ devices Build the selected configuration in the MPLAB X IDE project and program the demonstration board. The demonstration renders four folders for alpha blend, gradient, picture-in-picture (PIP), and performance. Touch one of the folders to activate the demonstration. Short Name Long Name pic32mxusbsk PIC32 USB Starter Kit II pic32mzsk PIC32MZ Embedded Connectivity (EC) Starter Kit meb2 Multimedia Expansion Board II (MEB II) 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-86 wqvga Graphics Display Powertip 4.3" 480 × 272 Board (AC164127-6) 3.3.4.2 primitive_demo An example of primitive drawing capabilities of the Graphics Library. Description The Primitive example demonstrates the various types of shapes and images which include: circles, lines, rectangles that exist in the Graphics Library. This example shows the following primitives: • GFX_LineDraw • GFX_CircleDraw • GFX_CircleFillDraw • GFX_RectangleRoundDraw • GFX_RectangleRoundFillDraw • GFX_RectangleFillDraw • GFX_ArcDraw • GFX_PolygonDraw • GFX_FontSet • GFX_TextStringXYPut • GFX_ImageDraw • GFX_ScreenClear 3.3.4.2.1 Supported Demonstration Boards Lists supported demo and development hardware boards. Description Following boards are supported for PIC32MX devices: Demo Board (click link for board information) Notes PIC32 USB Starter Kit II - Graphics LCD Controller PICtail Plus SSD1926 Board AC164127-5 - QVGA 320x240 Board AC164127-4 - Following board is supported for PIC32MZ devices: Demo Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - Multimedia Expansion Board II (MEB II) - 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-87 3.3.4.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.3.4.2.3 Running the Demonstration Provides instructions on how to build and run the primitive demo. Description Navigate to the apps/gfx/primitive/firmware folder and open the primitive project, and then select one of the following build configurations to build the Primitive demo: • pic32mxusbsk_pictails1d_wqvga -- For PIC32MX devices • pic32mxusbsk_pictailssd_qvga -- For PIC32MX devices • pic32mzsk_meb2_wqvga -- For PIC32MZ devices Once the project is loaded and executed on the target board, a continuous display of primitive graphics will appear on the LCD. Short Name Long Name pic32mxusbsk PIC32 USB Starter Kit II pic32mzsk PIC32MZ Embedded Connectivity (EC) Starter Kit pictails1d Graphics LCD Controller PICtail Plus S1D1357 Board pictailssd Graphics LCD Controller PICtail Plus SSD1926 Board meb2 Multimedia Expansion Board II (MEB II) qvga Graphics Display Truly 3.2" 240 × 320 Board (AC164127-4) wqvga Graphics Display Powertip 4.3" 480 × 272 Board (AC164127-6) 3.3.4.3 object_demo An example of standard user-interface widgets of the Graphics Library. Description The Object example demonstrates the standard types of objects/widgets that exist in the Graphics Library Graphics Object Layer (GOL). The demonstration is composed of several pages of examples. The demonstration requires that the user touch the screen to begin the demo. The user is expected to navigate to the next or previous page by selecting the buttons on the far right and left locations of the screen. This example shows the following widgets: • GFX_GOL_ButtonCreate 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-88 • GFX_GOL_ButtonTextSet • GFX_GOL_CheckboxCreate • GFX_GOL_GroupboxCreate • GFX_GOL_RadioButtonCreate • GFX_GOL_GroupboxCreate • GFX_GOL_StaticTextCreate • GFX_GOL_ScrollBarCreate • GFX_GOL_ProgressBarCreate • GFX_GOL_ListboxCreate • GFX_GOL_ScrollBarCreate • GFX_GOL_Editbox_Create • GFX_GOL_MeterCreate • GFX_GOL_DigitalMeterCreate • GFX_GOL_RoundDialCreate • GFX_GOL_PictureCreate • GFX_GOL_CustomControlCreate 3.3.4.3.1 Supported Demonstration Boards Lists supported demo and development hardware boards. Description Following boards are supported for PIC32MX devices: Demo Board (click link for board information) Notes PIC32 USB Starter Kit II - Graphics LCD Controller PICtail Plus SSD1926 Board AC164127-5 - QVGA 320x240 Board AC164127-4 - Following board is supported for PIC32MZ devices: Demo Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - Multimedia Expansion Board II (MEB II) - 3.3.4.3.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-89 No hardware related configuration or jumper setting changes are necessary. 3.3.4.3.3 Running the Demonstration Provides instructions on how to build and run the object demo. Description Navigate to the apps/gfx/object/firmware and open the object project, and then select one of the following build configurations to build the Object demo: • pic32mxusbsk_pictailssd_qvga -- For PIC32MX devices • pic32mzsk_meb2_wqvga -- For PIC32MZ devices Once the project is loaded and executed on the target board, various objects are displayed. Touch the forward or back arrow to view additional objects. Short Name Long Name pic32mxusbsk PIC32 USB Starter Kit II pic32mzsk PIC32MZ Embedded Connectivity (EC) Starter Kit pictailssd Graphics LCD Controller PICtail Plus SSD1926 Board meb2 Multimedia Expansion Board II (MEB II) qvga Graphics Display Truly 3.2" 240 × 320 Board (AC164127-4) 3.3.4.4 ssd_demo Shows how to display JPEG images using the Solomon Systech (SSD1926) graphics controller that resides on the PICtail™ Plus SSD1926 Board. Description The SSD1926 demo shows how to decode of JPEG images from an SD card utilizing the JPEG decoder capabilities of the Solmon Systech SSD1926 graphics controller. 3.3.4.4.1 Supported Demonstration Boards Lists supported demo and development hardware boards. Description Following board is supported for PIC32MX devices: Demo Board (click link for board information) Notes PIC32 USB Starter Kit II - Graphics LCD Controller PICtail Plus SSD1926 Board AC164127-5 - QVGA 320x240 Board AC164127-4 - 3.3.4.4.2 Configuring the Hardware Describes how to configure the supported hardware. 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstrations 3-90 Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. 3.3.4.4.3 Running the Demonstration Provides instructions on how to build and run the SSD1926 demo. Description Navigate to the apps/gfx/ssd1926/firmware and open the ssd1926 project, and then select one of the following build configurations to build the SSD1926 demo: • pic32mxusbsk_pictailssd_qvga -- For PIC32MX devices Once the project is loaded and executed on the target board, various JPEG images, which are stored on a SD card are displayed. Short Name Long Name pic32mxusbsk PIC32 USB Starter Kit II pictalssd Graphics LCD Controller PICtail Plus SSD13517 Board qvga Graphics Display Truly 3.2" 240 × 320 Board (AC164127-4) 3.3.5 Demonstration Board Information This topic provides specific information about the development boards available for the demonstration applications. 3.3.5.1 PIC32 USB Starter Kit II Provides information on the PIC32 USB Starter II. Description SW1 - Application switch. Tied to RD6. SW2 - Application switch. Tied to RD7. 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-91 SW3 - Application switch. Tied to RD13. LED1 - Application LED. Tied to RD0. LED2 - Application LED. Tied to RD1. LED3 - Application LED. Tied to RD2. This board supports the following USB Device demonstrations: • CDC Single COM port (cdc_com_port_single). • CDC Dual COM port (cdc_com_port_dual) • HID Basic (hid_basic) • HID Mouse (hid_mouse) • HID Keyboard (hid_keyboard) • HID Joystick (hid_joystick) • MSD Flash Drive (msd_basic) • Generic USB Device (generic_device) More Information Microchip Part Number : DM320003-2 3.3.5.2 PIC32MZ Embedded Connectivity (EC) Starter Kit Provides details information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-92 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-93 Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-94 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.3.5.3 PICtail Plus SSD1926 Daughter Board This topic provides information about the Graphics LCD Controller PICtail™ Plus SSD1926 Board. Description More Information Microchip Part Number: AC164127-5 Microchip Product Page 3.3.5.4 PICtail Plus S1D13517 Daughter Board This topic provides information about the Graphics LCD Controller PICtail™ Plus SSD1926 Daughter Board. Description More Information Microchip Part Number: AC164127-7 Microchip Product Page 3.3.5.5 PICtail Plus LCC Daughter Board This topic provides information about the Graphics LCD Controller PICtail™ Plus LCC Daughter Board. Description More Information 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-95 Microchip Part Number: AC164144 Microchip Product Page 3.3.5.6 PIC32MX795F512L Plug-In-Module (PIM) Provides information on the PIC32MX795F512L Plug-In-Module (PIM). Description This PIM is required while using the Explorer 16 Development Board. More Information Microchip Part Number: MA320003 microchipDIRECT Product Page 3.3.5.7 Multimedia Expansion Board (MEB) This topic provides information about the Multimedia Expansion Board (MEB). 3.3.5.8 Multimedia Expansion Board II (MEB II) Provides details information on the Multimedia Expansion Board II (MEB) II. Description Description Microchip Part Number: DM320005-2 Product Page The front side of the MEB II includes these key features, as shown in Figure 1: 1. Display daughter board connector (60-pin Hirose board-to-board connector). 2. mTouch™ buttons. 3. Push Button. 4. Power LED. 5. User LEDs. 6. VGA Camera (OVM7690). 7. PICtail™ Connector. 8. Analog temperature sensor. 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-96 Figure 1: Multimedia Expansion Board II Layout (Front) The underside of the MEB II includes these key features, as shown in Figure 2: 1. Regulated 5V and 3.3V power supply for powering the board via a 9-15V DC Adapter. 2. PIC32 Starter Kit connector (168-pin Hirose board-to-board connector). 3. 24-bit stereo audio codec (AK4953A). 4. Integrated 802.11bg wireless module (MRF24WG0MA). 5. Low-cost Bluetooth® HCI transceiver (BTM805). 6. EBI SRAM memory (IS61WV102416BLL). 7. microSD slot. 8. Analog accelerometer (ADXL325). Figure 2: Multimedia Expansion Board II Layout (Back) 3.3 Graphics Demonstrations MPLAB Harmony Help Demonstration Board Information 3-97 3.4 Peripheral Library Example Applications This topic describes the peripheral library example applications. 3.4.1 Introduction Peripheral Library Example Applications for MPLAB Harmony The example applications for MPLAB peripheral libraries (PLIBs) provide very simple single-purpose examples of how to use MPLAB Harmony peripheral libraries. Description Peripheral libraries (PLIBs) are the lowest level libraries provided with MPLAB Harmony. They provide a functional abstraction of the peripherals available on Microchip microcontrollers to hide differences in register details that can exist from part to part. However, they do not maintain any state data (at least not any that isn't stored in the hardware registers) from call to call and they do not provide any protection of the peripheral's resources. As such, any code that calls the PLIB for a peripheral must take responsibility for ownership of that peripheral and is responsible for managing the behavior of that peripheral. As such, PLIBs are normally only used by MPLAB Harmony device drivers or system services. However, there are some times when it is necessary and appropriate to interact with a PLIB directly from an application. So, simple examples are provided to show how to use the interfaces the peripheral libraries. These examples are available in the MPLAB Harmony installation in the following location. Location of Example Applications /apps/examples/peripheral Examples are divided into two different groups: • Blocking Examples • State-Driven Examples Most MPLAB Harmony applications use a state-machine driven structure. So, examples are provided that follow this structure in the "state_driven" subdirectory. However, it is sometimes easier to understand a simple blocking example (one that sits in a loop for ever or until its task is done). So, simple blocking examples are also provided in the "blocking" subdirectory. Blocking examples are divided into PIC32MX and PIC32MZ variants. PIC32MX examples are written for the Explorer16 Development Board with a PIC32MX795F512L PIM. PIC32MZ examples are written for the PIC32MZ Embedded Connectivity (EC) Starter Kit. The state-driven examples are tested and working on the Explorer 16 Development Board, the PIC32 USB Starter Kit II, and the PIC32MZ Embedded Connectivity (EC) Starter Kit, and the appropriate board configuration for each project can be selected in MPLAB X IDE. 3.4 Peripheral Library Example Applications MPLAB Harmony Help Release Notes 3-98 3.4.2 Release Notes MPLAB Harmony Version: v0.70b Peripheral Library Example Applications Version: 0.01a Release Date: 18Nov2013 The interface can change in the beta and\or 1.0 release. New This Release: Nothing to report for this release. Known Issues: Nothing to report for this release. 3.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.4.4 Blocking Applications This topic contains a list of the MPLAB Harmony blocking peripheral library (PLIB) example applications. Description The tables below list and summarizes the simple blocking peripheral library example applications. Location /apps/examples/peripheral/blocking/pic32mx PIC32MX PLIB-based Applications 3.4 Peripheral Library Example Applications MPLAB Harmony Help Blocking Applications 3-99 Name Subdirectory Description ADC Potentiometer adc/adc_pot Repeatedly reads the Explorer 16 Development Board potentiometer and outputs a pattern on the LEDs corresponding to the potentiometer's position. Memory Partition bmx/mem_partition Partitions flash memory and ram. Explorer 16 Development Board LEDs are turned on if the RAM partition sizes are correct and the partitioning completed successfully. Simple Comparator cmp/simple_comparator Toggles the LEDs on the Explorer 16 Development Board, depending on which input of the comparator is at a higher voltage. Triangle Wave cvref/triangle_wave This example will generate a triangular wave on the CVREF output pin. LED Pattern dma/led_pattern Blinks LEDs on the Explorer 16 Development Board using a pattern stored in Flash memory. It uses the DMA controller to transfer data from flash to the I/O port controlling the LEDs. Master-Slave i2c/master_slave The I2C1 module is setup to operate as the master, while the I2C2 module operates as the slave. The master sends a string to the slave, which stores the data into an array. Simple Input-Capture ic/simple_input_capture When a rising edge is output to the Input Capture 1 pin (RD8), it triggers an interrupt, which then stores the captured timer value into the 'CaptureTime' variable. Flash Modify nvm/flash_modify Reads, writes and erases data in the program Flash memory. PWM Example oc/oc_pwm Generates a 40 kHz PWM with a 25% duty cycle on the OC1 output pin. Oscillator Configuration osc/osc_config Demonstrates how to change the system clock source and PLL values during run-time. LCD Example pmp/pmp_lcd Writes two lines of text to the LCD screen on the Explorer 16 Development Board. Blinky Leds ports/blinky_leds Toggles the Explorer 16 Development Board LEDs in an infinite loop. Change Notice ports/cn_interrupt When SW4 (the right most button on Explorer 16 Development Board) is pressed, it triggers a change notice interrupt, which then toggles the Explorer 16 Development Board LEDs. Sleep Mode power/sleep_mode This example demonstrates how to put the device into Sleep mode and then awake the device using the Watchdog Timer. Reset Handler reset/reset_handler This example does checks on various reset flags, assigning each one to an Explorer 16 Development Board LED. If the flag is set, the LED is turned on and the reset flag is cleared. RTCC Alarm rtcc/rtcc_alarm Sets up the RTCC module to function as an alarm, which goes off at 6:00am every morning. SPI Loopback spi/spi_loopback This example assumes that the SPI SDO (output) is connected to the SDI (input). Data is then transferred directly from the output to the input and the Explorer 16 Development Board LEDs are turned on if the data transfer is successful. Timer Example tmr/timer2_interrupt Uses Timer2 in 32-bit mode to generate an interrupt every one second, blinking the LEDs on the Explorer 16 Development Board. Simple UART uart/simple_uart When the Explorer 16 Development Board is connected to a PC with an RS-232 cable, the device will echo what characters the user types into a terminal program (e.g., Putty) and write the corresponding 8-bit character pattern to the Explorer 16 Development Board LEDs. Simple WDT wdt/simple_wdt Demonstrates how to setup the Watchdog Timer and detect whether or not a time-out reset has occurred. Location /apps/examples/peripheral/blocking/pic32mz 3.4 Peripheral Library Example Applications MPLAB Harmony Help Blocking Applications 3-100 PIC32MZ PLIB-based Applications Name Subdirectory Description Triangle Wave cvref/triangle_wave This example will generate a triangular wave on the CVref output pin. LED Pattern dma/led_pattern Blinks LEDs on the PIC32MZ Starter-Kit using a pattern stored in flash memory. It uses the DMA controller to transfer data from flash to the I/O port controlling the LEDs. Master-Slave i2c/master_slave The I2C1 module is setup to operate as the master, while the I2C2 module operates as the slave. The master sends a string to the slave, which stores the data into an array. Flash Modify nvm/flash_modify Reads, writes and erases data in the program flash memory. PWM Example oc/oc_pwm Generates a 40KHz PWM with a 25% duty cycle on the OC1 output pin. Oscillator Configuration osc/osc_config Demonstrates how to change the system clock source and PLL values during run-time. Blinky Leds ports/blinky_leds Toggles the PIC32MZ Starter-Kit LEDs in an infinite loop. Change Notice ports/cn_interrupt When SW1 is pressed, it triggers a change notice interrupt, which then toggles the PIC32MZ Starter-Kit LEDs. Sleep Mode power/sleep_mode This example demonstrates how to put the device into sleep mode and then awake the device using the watchdog timer. Reset Handler reset/reset_handler This example does checks on various reset flags, assigning each one to an LED. If the flag is set, the LED is turned on and the reset flag is cleared. RTCC Alarm rtcc/rtcc_alarm Sets up the RTCC module to function as an alarm, which goes off at 6:00am every morning. SPI Loopback spi/spi_loopback This example assumes that the SPI SDO (output) is connected to the SDI (input). Data is then transferred directly from the output to the input and the LEDs are turned on if the data transfer is successful. Timer Example tmr/timer2_interrupt Uses Timer 2 in 32-bit mode to generate an interrupt every one second, blinking the LEDs on the PIC32MZ Starter-Kit. Simple UART uart/simple_uart When the PIC32MZ Starter-Kit is connected to a PC with an RS-232 cable, the device will echo what characters the user types into a terminal program (e.g. Putty). Simple WDT wdt/simple_wdt Demonstrates how to setup the watchdog timer and detect whether or not a timeout reset has occurred. 3.4.5 State-Driven Applications Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 3.4 Peripheral Library Example Applications MPLAB Harmony Help State-Driven Applications 3-101 3.5 NVM Driver Demonstration 3.5.1 Introduction This help file contains instructions and associated information about MPLAB Harmony NVM driver application demonstrations, which are contained in the MPLAB Harmony Library distribution. Description This application demonstrates the capabilities of the MPLAB Harmony NVM driver. This help file describes the hardware requirement and procedures to build, run the demo project on Microchip development tools. In this demo application, NVM driver is used to access the internal flash memory of PIC32 MX and PIC32 MZ Devices to perform Write and Read operations and indicates the result by LED display. To know more about MPLAB Harmony NVM driver, configuring the NVM driver and API's provided by the NVM driver, refer to MPLAB Harmony NVM Driver Library documentation. 3.5.2 Release Notes MPLAB Harmony Version: v0.70b NVM Driver Demonstration Version: 0.01a Release Date: 18Nov2013 New This release: This is the first release of this NVM Driver demonstration application. This demonstration has been developed to support PIC32MX and PIC32MZ devices. Known Issues: • This Demo application is tested only up to 150 bytes in interrupt mode in PIC32MZ devices • Changes in NVM driver interfaces will have impact on this demo application as well in subsequent releases 3.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 3.5 NVM Driver Demonstration MPLAB Harmony Help SW License Agreement 3-102 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.5.4 Hardware This section describes how to select and use an appropriate development board and steps to configure the hardware to run this NVM driver demo. 3.5.4.1 Required Hardware This section describes the overview of required hardware family and supported demonstration boards for running this NVM driver demo application. Description To run this demonstration project. you will require one of the following sets of hardware. 3.5.4.1.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Following board is supported for PIC32MX devices: - Demo Board (click link for board information) Notes PIC32 USB Starter Kit II - Explorer 16 Development Board - PIC32MX795F512L Plug-in Module (PIM) - Following board is supported for PIC32MZ devices: - Demo Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.5.4.1.2 Hardware Information Information on hardware used by the NVM driver demo application. Description The NVM driver demo application can be tried on different hardware boards. This section provide details on the different hardware boards that this demo application supports. 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-103 3.5.4.1.2.1 PIC32 USB Starter Kit II Provides information on the PIC32 USB Starter Kit II. Description SW1 - Application switch. Tied to RD6. SW2 - Application switch. Tied to RD7. SW3 - Application switch. Tied to RD13. LED1 - Application LED. Tied to RD0. LED2 - Application LED. Tied to RD1. LED3 - Application LED. Tied to RD2. More Information Microchip Part Number : DM320003-2 3.5.4.1.2.2 Explorer 16 Development Board Provides information on the Explorer 16 Development Board. 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-104 Description S1 - Reset button (MCLR) S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM). S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use. D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use. More Information: Microchip Part Number: DM240001 3.5.4.1.2.3 PIC32MX795F512L Plug-in Module (PIM) Provides information on the PIC32MX795F512L Plug-In-Module (PIM). Description This PIM is required while using the Explorer 16 Development Board. 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-105 More Information Microchip Part Number: MA320003 microchipDIRECT Product Page 3.5.4.1.2.4 PIC32MZ Embedded Connectivity (EC) Starter Kit Provides information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-106 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.5.4.1.2.5 Multimedia Expansion Board II (MEB II) Provides information on the Multimedia Expansion Board II (MEB II). Description Microchip Part Number: DM320005-2 Product Page The front side of the MEB II includes these key features, as shown in Figure 1: 1. Display daughter board connector (60-pin Hirose board-to-board connector). 2. mTouch™ buttons. 3. Push Button. 4. Power LED. 5. User LEDs. 6. VGA Camera (OVM7690). 7. PICtail™ Connector. 8. Analog temperature sensor. 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-107 Figure 1: Multimedia Expansion Board II Layout (Front) The underside of the MEB II includes these key features, as shown in Figure 2: 1. Regulated 5V and 3.3V power supply for powering the board via a 9-15V DC Adapter. 2. PIC32 Starter Kit connector (168-pin Hirose board-to-board connector). 3. 24-bit stereo audio codec (AK4953A). 4. Integrated 802.11bg wireless module (MRF24WG0MA). 5. Low-cost Bluetooth® HCI transceiver (BTM805). 6. EBI SRAM memory (IS61WV102416BLL). 7. microSD slot. 8. Analog accelerometer (ADXL325). Figure 2: Multimedia Expansion Board II Layout (Back) 3.5 NVM Driver Demonstration MPLAB Harmony Help Hardware 3-108 3.5.4.2 Configuring the Hardware Describes how to configure the supported hardware. Description Explorer 16 Development Board This demonstration application is demonstrated using Explorer 16 Development Board, PIC32 USB Starter Kit II and PIC32MZ Embedded Connectivity (EC) Starter Kit. The following hardware configuration should be set up before running this application. 1. Before attaching the PIC32MX795F512L PIM to the Explorer 16 Development Board, ensure that the processor select switch (S2) is in the PIM Position. 2. Short JP2 on the Explorer 16 Development Board to enable the LEDs. PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.5.5 Building the Application This section describes how to build this demonstration project. Description Once the hardware is configured, you are ready to build this application. Project Setup : From the MPLAB X IDE, Select "open project" and browse to this demo location. This demo application is available in "/apps/driver/nvm/nvm_read_write/firmware/nvm_read_write.X". This directory contains all the application related source files, header files as well as MPLAB X IDE project related workspace files. How to build this demonstration application: To build this demo in debug mode, Go to "Run" menu in MPLAB X IDE and select "Build Main Project" or select "Build Main Project" in toolbar. Once the project gets compiled successfully, you can run this demonstration application. For more information on how to compile and program projects, refer to the MPLAB X IDE help available through the help menu in MPLAB X IDE. Note:The appropriate project configurations should be selected before building the project for the configured hardware. 3.5.5.1 Configuring the Application This section describes the list of configuration options, build options, and how they are configured for this demonstration application. Build options: This application supports both PIC32MX and PIC32MZ devices. From project properties of MPLAB X IDE, select "pic32mx_usb_starterkit_II" configuration if the target hardware is a PIC32MX device, or select "pic32mz_sk" configuration if the 3.5 NVM Driver Demonstration MPLAB Harmony Help Building the Application 3-109 target hardware is a PIC32MZ device. The default target device is "PIC32MX795F512L" for "pic32mx_usb_starterkit_II" configuration and "PIC32MZ2048ECH144" for "pic32mz_sk" configuration with optimization level as "0". The various optimization levels can be selected from the list to run this demonstration. Note: If the target device is changed, the appropriate PIM needs to be used to run this demonstration application. Configuration options: All of the demonstration application related configuration options are available in "system_config.h" file. This file is available in the "apps/driver/nvm/nvm_read_write/firmware/src/system_config/pic32mx_usb_starterkit_II" or "apps/driver/nvm/nvm_read_write/firmware/src/system_config/pic32mz_sk"directory based on the configuration selected. This file has the following list of configurations: • General System Clock Services • NVM Driver • Interrupt services Note: Based on the configurations, the demo application behavior will be changed. 3.5.5.2 Configuring the Libraries This section describes the configuration options provided by MPLAB Harmony Libraries used by the application. Macro Name Description #define DRV_NVM_INSTANCES_NUMBER This definition selects the maximum number of hardware instances that can be supported by the dynamic NVM driver #define DRV_NVM_CLIENTS_NUMBER This definition selects the maximum number of clients that the NVM driver can support at run time #define DRV_NVM_INTERRUPT_MODE This macro controls the operation of the driver in the interrupt mode of operation #define DRV_NVM_ROW_SIZE This macro defines the row size of target Flash #define DRV_NVM_PAGE_SIZE This macro selects the NVM page size size #define NVM_BASE_ADDRESS This macro defines the address to which the data is written and read 3.5.5.3 Customizing the Application This section explains the steps involved in customizing the existing demonstration application. Customizing Existing Demonstration Application: In this demo application, the NVM driver operates in interrupt mode. Following are the steps to be used to customize this application in olling mode. 1. Change #define DRV_NVM_INTERRUPT_MODE as false in "system_config.h" file 2. Remove the NVM ISR routine from "system_int.c" file 3. Call the DRV_NVM_Tasks function in "system_task.c" file After changing the above configurations, compile the customized application and program the target device. 3.5 NVM Driver Demonstration MPLAB Harmony Help Running the Application 3-110 3.5.6 Running the Application This section demonstrates how to run the NVM Driver demonstration. Description This is a simple demonstration to show how to configure and make use of NVM driver API's to implement and access on-board Flash memory of PIC32MX and PIC32MZ devices. How to run this demonstration application: Once the demonstration application is compiled successfully, you are ready to program the firmware in the target device. To run the demonstration in debug mode, below are the steps to be followed. 1. Select appropriate configuration from project properties based on the target hardware. 2. Select your device programmer from the "hardware tool" in MPLAB X IDE. 3. Select the "Debug Main Project" in "Debug" menu or select the "Debug Main Project" in toolbar. Build the selected configuration in the MPLAB X IDE project and program the demonstration board. The execution status (pass/fail) of the demonstration is indicated by LEDs on the demonstration board. Demonstration Board Successful Indication Failure Indication PIC32 USB Starter Kit II LED2 LED1 PIC32MZ Embedded Connectivity (EC) Starter Kit Green LED Red LED This demonstration first reads the data from specific NVM address define in system_config.h header file and erases the entire sector, write 150 bytes of data and reads back. The Pass/Fail criteria is indicated using LEDs as defined above. 3.5.7 Files This section provides a complete list of source files required by the application and describes the purpose of adding each files. MPLAB Harmony installation follows a standard directory structure for all application solutions. In this directory structure, the driver, plib, system services related source files, header files for this demonstration application are available in "/framework/". Below are the list of files added in this demonstration application. Files Description driver.h Driver Library Interface Header drv_common.h This file defines all common macros and definitions used by the driver drv_nvm.h NVM device driver interface file. system.h System Service Interface Headers sys_common.h This file contains system Common definitions and declarations sys_module.h This file contains system module definitions system_config.h This is file contains all the system configurations system_definitions.h This contains system prototypes and definitions 3.5 NVM Driver Demonstration MPLAB Harmony Help Files 3-111 app.h This file contains application related definitions and prototypes config_performance.c BSP file for Explorer 16 Development Board drv_nvm_dynamic.c This file contains NVM device driver dynamic implementation plib_int_pic32.c Interrupt Source implementation for PIC32 devices sys_int_pic32.c This file contains functions related to the Interrupt System Service for PIC32 devices app.c This file contains application related implementations main.c This file contains application's main entry point system_init.c This file contains source code necessary to initialize the system system_int.c This file contains a definitions of the raw ISRs required to support the interrupt sub-system system_tasks.c This file will contain any source code necessary to maintain various tasks in the system 3.5 NVM Driver Demonstration MPLAB Harmony Help Files 3-112 3.6 RTOS Demonstrations 3.6.1 Introduction RTOS Demonstration Applications Help Description This distribution package contains a variety of RTOS based firmware projects that demonstrate the capabilities of the MPLAB Harmony services and stacks integrated with RTOS running on PIC32 devices. This help file describes the hardware requirement and procedures to run these firmware projects on Microchip demonstration and development boards. To learn more about MPLAB Harmony stacks and libraries refer to the related Framework help documentation. 3.6.2 Release Notes MPLAB Harmony Version: v0.70b RTOS Demonstrations Version: 0.01a Release Date: 18Nov2013 New This Release: This release contains the FreeRTOS basic project. Known Issues: Nothing to report for this release. 3.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. 3.6 RTOS Demonstrations MPLAB Harmony Help SW License Agreement 3-113 MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.6.4 Demonstrations This topic provides information on how to run the RTOS demonstration applications included in this release. Description All demonstrations provided should be built using the MPLAB X IDE development environment tool supplied by Microchip. The following information communicates the general steps to building the demonstrations. • Using MPLAB X IDE, click the File drop-down, select "Open Project...". Navigate to your Harmony installation folder. The default location on Windows will be: C:\Microchip\Harmony\\apps\rtos • In the \app\rtos folder there will be the demonstration applications. • Within each demonstration folder, there will be a MPLAB X IDE project specific to each demonstration • Select the project and click "Open Project" • To configure the project specific to a preset board configuration, right click on the project and select "Set Configuration" This will set the build configuration to match the supported board configuration. 3.6.4.1 FreeRTOS_basic_demo 3.6.4.1.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.6.4.1.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstrations 3-114 3.6.4.1.3 Running the Demonstration Provides instructions on how to build and run the FreeRTOS basic demonstration. Description Please use the following procedure to run the demonstration: 1. Load demonstration project into MPLAB X IDE. 2. Connect the mini-B debugger port on-board the PIC32MX or PIC32MZ Starter board to an USB port on the development computer using the USB cable provided in the kit. 3. Build, Download, and Run demonstration project on the target board. The demonstration application features the following: • Application creates one queue and four tasks. One task that sends the data using FreeRTOS queue to the two tasks that waits for the data in the queue. (QueueReceiveTask2 priority is higher than the QueueReceiveTask1 priority.) • QueueReceiveTask2 receives the data first, toggles the LED, and then sleeps for the specified time • QueueReceiveTask1 receives the next data since QueueReceiveTask2 is not in running state • QueueReceiveTask1 receives the data, toggles the LED and waits for the data arrival 3.6.4.2 uC_OS_III_basic_demo 3.6.4.2.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.6.4.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.6.4.2.3 Running the Demonstration Provides instructions on how to build and run the uC_OS_III basic demonstration. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstrations 3-115 Description Demonstration applications are available in the following folders: • \app\rtos\freeRTOS\gfx • \app\rtos\uC_OS_III\gfx • \app\rtos\freeRTOS\basic • \app\rtos\uC_OS_III\basic Within each demonstration folder, there will be a MPLAB X IDE project specific to each demonstration Select the project and click "Open Project" These demos will show the following: • <\gfx> The selected RTOS integrated in with the Harmony compliant Graphics stack. • <\basic> The basic blink LED demo showing the selected RTOS running with the hardware. Once the demo is up running an LED will toggle every 500ms. This demo will show the RTOS running with the selected hardware. 3.6.4.3 FreeRTOS RTOS with Graphics 3.6.4.3.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.6.4.3.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.6.4.3.3 Running the Demonstration Provides instructions on how to build and run the FreeRTOS RTOS with Graphics demonstration. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstrations 3-116 Description Demonstration applications are available in the following folders: • \app\rtos\freeRTOS\gfx • \app\rtos\uC_OS_III\gfx • \app\rtos\freeRTOS\basic • \app\rtos\uC_OS_III\basic Within each demonstration folder, there will be a MPLAB X IDE project specific to each demonstration Select the project and click "Open Project" These demos will show the following: • <\gfx> The selected RTOS integrated in with the Harmony compliant Graphics stack. • <\basic> The basic blink LED demo showing the selected RTOS running with the hardware. Once the demo is up running the screen color on the graphics display will change once every 500ms. A LED will toggle every 500ms. The projects have been setup to use relative paths from the project folder and must remain under the apps\rtos\ root folders in order to build correctly. 3.6.4.4 Micrium uC_OS_III with Graphics 3.6.4.4.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.6.4.4.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstrations 3-117 3.6.4.4.3 Running the Demonstration Provides instructions on how to build and run the Micrium uC_OS_III with Graphics demonstration. Description Demonstration applications are available in the following folders: • \app\rtos\freeRTOS\gfx • \app\rtos\uC_OS_III\gfx • \app\rtos\freeRTOS\basic • \app\rtos\uC_OS_III\basic Within each demonstration folder, there will be a MPLAB X IDE project specific to each demonstration Select the project and click "Open Project" These demos will show the following: • <\gfx> The selected RTOS integrated in with the Harmony compliant Graphics stack. • <\basic> The basic blink LED demo showing the selected RTOS running with the hardware. Once the demo is up running the screen color on the graphics display will change once every 500ms. A LED will toggle every 500ms. The projects have been setup to use relative paths from the project folder and must remain under the apps\rtos\ root folders in order to build correctly. Under the uC_OS_III\ folder, an extra step must be taken to build the project successfully. The RTOS source code and appropriate port for the selected hardware must be download from Micrium and installed into the follow folder, \third_party\rtos\. 3.6.5 Demonstration Board Information 3.6.5.1 PIC32 USB Starter Kit II Provides information on the PIC32 USB Starter II. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstration Board Information 3-118 Description SW1 - Application switch. Tied to RD6. SW2 - Application switch. Tied to RD7. SW3 - Application switch. Tied to RD13. LED1 - Application LED. Tied to RD0. LED2 - Application LED. Tied to RD1. LED3 - Application LED. Tied to RD2. More Information Microchip Part Number : DM320003-2 3.6.5.2 PIC32MZ Embedded Connectivity (EC) Starter Kit Provides details information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstration Board Information 3-119 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstration Board Information 3-120 Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstration Board Information 3-121 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.6 RTOS Demonstrations MPLAB Harmony Help Demonstration Board Information 3-122 3.7 SPI Driver Demonstrations 3.7.1 Introduction This help file contains instructions and associated information about MPLAB Harmony SPI driver application demonstrations, which are contained in the MPLAB Harmony Library distribution. Description This application demonstrates the capabilities of the MPLAB Harmony SPI driver. This help file describes the hardware requirement and procedures to build, run the demo project on Microchip development tools. In this demo application, SPI driver is used to access the external EEPROM in the Explorer 16 Development Board to perform Write and Read operations and indicates the result by LED display. To know more about MPLAB Harmony SPI driver, configuring the SPI driver and API's provided by the SPI driver, refer to the SPI Driver Library documentation. 3.7.2 Release Notes MPLAB Harmony Version: v0.70b SPI Driver Demonstrations Version: 0.01a Release Date: 18Nov2013 New This release: This is the first release of this SPI driver demonstration application. This demo has been developed to support PIC32MX devices only. The following demonstration shows the usage of the SPI driver: • serial_eeprom Limitations and Known Issues: • Demo application is only developed and tested in Interrupt mode • Changes in SPI driver interfaces will have impact on this demo application as well in subsequent releases • This demo will support to run only on Explorer 16 Development Board 3.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 3.7 SPI Driver Demonstrations MPLAB Harmony Help SW License Agreement 3-123 FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.7.4 Hardware This section describes how to select and use an appropriate development board and steps to configure the hardware to run this SPI driver demo. 3.7.4.1 Required Hardware This section describes the overview of required hardware family and supported demonstration boards for running this SPI driver demo application. Description To run this demonstration project. you will require one of the following sets of hardware. 3.7.4.1.1 Supported Demonstration Boards The following demo boards are supported in this release. Description Demonstration Board Notes Explorer 16 Development board - 3.7.4.1.2 Hardware Information Information on hardware used by the SPI driver demo application. Description The SPI driver demo application can be tried across on hardware boards. This section provide details on the different hardware boards that are used by the demo application. 3.7.4.1.2.1 Explorer 16 Development Board Provides information on the Explorer 16 Development Board . 3.7 SPI Driver Demonstrations MPLAB Harmony Help Hardware 3-124 Description S1 - Reset button (MCLR) S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM). S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use. D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use. More Information: Microchip Part Number: DM240001 3.7.4.1.2.2 PIC32MX795F512L Plug-in Module (PIM) Provides information on the PIC32MX795F512L Plug-In-Module (PIM). Description This PIM is required while using the Explorer 16 Development Board. 3.7 SPI Driver Demonstrations MPLAB Harmony Help Hardware 3-125 More Information Microchip Part Number: MA320003 Information Sheet 3.7.4.2 Configuring the Hardware Describes how to configure the supported hardware. Description serial_eeprom demo This application is demonstrated using Explorer 16 Development Board. the following hardware configuration should be done before running this application. 1. Before attaching the PIC32MX795F512L PIM to the Explorer 16 Development Board, ensure that the processor select switch (S2) is in the PIM Position. 2. Short JP2 on the Explorer 16 Development Board to enable the LEDs. Complete the previously described hardware configuration setup to to run this demo. 3.7.5 Building the Application This section describes how to build this demo project. Description Once the hardware is configured, you are ready to build this application. Project Setup : From MPLAB X IDE, Select "open project" and browse to this demo location. This demo application is available in "/apps/driver/spi/serial_eeprom.X". This directory contains all the application related source files, header files as well as MPLAB X IDE project related workspace files. How to build this demo application: To build this demo in debug mode, Go to "Run" menu in MPLAB X IDE and select "Build Main Project" or select "Build Main Project" in toolbar. Once the project gets compiled successfully, you can run this demo application. For more information on how to compile and program projects, refer to the MPLAB X IDE help available through the help menu in MPLAB X IDE. Note: The appropriate project configurations should be selected before building the project for the configured hardware. 3.7.5.1 Customizing the Application This section explains the steps involved in customizing the existing demo application. Customizing Existing Demo Application: In this demo application, the SPI driver is operates in interrupt mode. Below are the steps to be followed to customize this application in polling mode. 3.7 SPI Driver Demonstrations MPLAB Harmony Help Building the Application 3-126 1. Change #define DRV_SPI_INTERRUPT_MODE as false in "system_config.h" file 2. Remove the SPI interrupt source Priority and sub priority set functions calls from "system_init.c" file 3. Remove the SPI ISR routine from "system_int.c" file 4. Call the DRV_SPI_Tasks function in "system_task.c" file After changing the above configurations, compile the customized application and program the target device. 3.7.5.2 Configuring the Libraries This section describes the configuration options provided by MPLAB Harmony Libraries used by the application. #define DRV_SPI_INSTANCES_NUMBER This definition selects the maximum number of hardware instances that can be supported by the dynamic SPI driver #define DRV_SPI_CLIENTS_NUMBER This definition selects the maximum number of clients that the SPI driver can support at run time #define DRV_SPI_INTERRUPT_MODE This macro controls the operation of the driver in the interrupt mode of operation #define DRV_SPI_PORTS_REMAP_USAGE This macro selects the SPI pins remap #define DRV_SPI_BUFFER_SIZE This macro selects the SPI buffer size #define DRV_SPI_FRAME_SYNC_PULSE_DIRECTION This macro selects the SPI frame sync pulse direction #define DRV_SPI_FRAME_SYNC_PULSE_POLARITY This macro selects the SPI frame sync pulse polarity #define DRV_SPI_FRAME_SYNC_PULSE_EDGE This macro selects the SPI frame sync pulse edge 3.7.5.3 Configuring the Application This section describes the list of configuration options , build options and how they are configured for this demo application. Build options: This application supports only to demonstrate the SPI driver in master mode. This option "spi_master_explorer16" can be selected from the project properties in MPLAB X IDE or from the configuration drop down in toolbar. The default target device is selected as "PIC32MX795F512L" with optimization level as "0". The various optimization levels can be selected from the list to run this demo. Note: If the target device is changed, then appropriate PIM needs to be used to run this demo application Configuration options: All the demo application related configuration options are available in "system_config.h" file. This file is available in the "/apps/driver/spi/src/system_config/" directory based on the configured hardware. This file has the followingconfigurations, • General System Clock Services • SPI Driver Note: Based on the configurations, the demo application behavior will be changed. 3.7 SPI Driver Demonstrations MPLAB Harmony Help Running the Application 3-127 3.7.6 Running the Application This section demonstrates how to run the SPI driver demo. Description This is a simple demo to show how to configure and make use of SPI driver API's to implement and access on board EEPROM chip in the Explorer 16 Development Board. How to run this demo application Once the demo application is compiled successfully, you are ready to program the firmware in the target device. To run the demo in debug mode, below are the steps to be followed. 1. Select your device programmer from the "hardware tool" in MPLAB X IDE. 2. Select the "Debug Main Project" in "Debug" menu or select the "Debug Main Project" in toolbar. Once the device is successfully programmed, you can observe LED in the Explorer 16 Development Board will be turned ON. This shows the demo project has ran successfully and based on the LED "D4" or "D3" the demo application indicates the PASS/FAIL. Notes: If LED "D3" is turned ON, it indicates the EEPROM W/R functionality has failed. If LED "D4" is turned ON, it indicates the EEPROM W/R functionality has passed. 3.7.7 Files This section provides a complete list of source files required by the application and describes the purpose of adding each files. MPLAB Harmony installation follows a standard directory structure for all application solutions. In this directory structure, the driver, plib, system services related source files, header files for this demo application are available in "/framework/". Below are the list of files added in this demo application. Files Description driver.h Driver Library Interface Header drv_common.h This file defines all common macros and definitions used by the driver drv_spi.h SPI device driver interface file. system.h System Service Interface Headers sys_common.h This file contains system Common definitions and declarations sys_module.h This file contains system module definitions system_config.h This is file contains all the system configurations system_definitions.h This contains system prototypes and definitions app.h This file contains application related definitions and prototypes config_performance.c BSP file for Explorer 16 Development Board drv_spi_dynamic.c This file contains SPI device driver dynamic implementation 3.7 SPI Driver Demonstrations MPLAB Harmony Help Files 3-128 plib_int_pic32.c Interrupt Source implementation for PIC32 devices sys_clk.c This file contains clock system service implementation sys_clk_pic32.c This file contains clock system service implementation specific to PIC32 devices sys_queue.c This file contains system queue services sys_int_pic32.c This file contains functions related to the Interrupt System Service for PIC32 devices sys_ports.c This file contains Ports System Service interface implementation. app.c This file contains application related implementations main.c This file contains application's main entry point system_init.c This file contains source code necessary to initialize the system system_int.c This file contains a definitions of the raw ISRs required to support the interrupt sub-system system_tasks.c This file will contain any source code necessary to maintain various tasks in the system 3.7 SPI Driver Demonstrations MPLAB Harmony Help Files 3-129 3.8 TCP/IP Demonstrations 3.8.1 Introduction TCP/IP Web Server Demonstration Applications Help Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 3.8.2 Release Notes MPLAB Harmony Version: v0.70b TCP/IP Demonstrations Version: 0.01a Release Date: 18Nov2013 The interface can change in the beta and\or 1.0 release. New This Release: Nothing to report for this release. Known Issues: Nothing to report for this release. 3.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-130 3.8.4 Demonstrations Description of TCP/IP Stack Library Demonstration Application Description This section describes Microchip's TCP/IP Demonstration projects, including information about demonstration-hardware compatibility and also provides the information about how to configure and run the demonstration. 3.8.4.1 web_server 3.8.4.1.1 pic32_ethernet_starter_kit This section describes the steps necessary to begin using Microchip's TCP/IP Web server Demonstration Application. Description This section describes Microchip's TCP/IP Web Server Demonstration project, including information about demonstration-hardware compatibility and also provides the information about how to configure and run the demonstration. 3.8.4.1.1.1 Supported Hardware Lists supported demonstration and development hardware boards. Description Demo Board (click link for board information) Notes PIC32 Ethernet Starter Kit -- PIC32MZ Embedded Connectivity (EC) Starter Kit -- 3.8.4.1.1.2 Configuring the Hardware Describes how to configure the supported hardware. Description No hardware related configuration or jumper setting changes are necessary. 3.8.4.1.1.3 Running the Demonstration Provides instructions on how to build and run the TCP/IP Web Server demonstration. Description This demonstration hosts a HTTP server when connected to a network. To view the web page hosted by the demonstration application open a web browser, type http://mchpboard in the address bar and press the enter key. Please use the following procedure to run the demonstration: 1. Load demonstration project into MPLAB X IDE. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-131 2. Connect the mini-B debugger port on-board the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter Kit board to an USB port on the development computer using the USB cable provided in the kit. 3. Connect the RJ-45 Ethernet port on the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter Kit board to a network hub or an Ethernet port on the development computer using the Ethernet patch cord provided in the kit. 4. Build, Download, and Run demonstration project on the target board. 5. A HTTP server is hosted by the demonstration application. Open a web browser, type http://mchpboard in the address bar and press the enter key. The demonstration application features following: a) Real-time hardware control and Dynamic Variables - On the Overview page the the LEDs can be clicked to toggle LEDs on the Ethernet Starter Board. The buttons on Ethernet Starter Board can be pressed to see the Buttons on the webpage toggle. The dynamic variables can be updated in real time on the HTTP server. b) Form Processing - Input can be handled from the client by using GET and POST methods. c) Authentication - Shows an example to restricted access feature commonly used. d) File Uploads - Shows an example of file upload using POST method. The HTTP server can accept a user defined MPFS/MPFS2 image file for webpages. e) Board Configuration - MAC address, host name and IP address of the PIC32 Ethernet starter board can be viewed in the Network Configuration page and some configuration can be updated. Note: LED functionality part of the demonstration is not implemented for PIC32MZ devices. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-132 3.8.4.1.2 web_server_sdcard_fatfs This section describes the steps necessary to begin using Microchip's TCP/IP Web server Demonstration Application. Description The TCP/IP SDCARD FATFS web server demo (‘apps/tcpip/web_server_sdcard_fatfs/firmware/pic32_ethernet_starter_kit.X’) exercises the HTTP web server running on PIC32 devices. SDCARD (Secure Digital Card) FATFS (File Allocation Table File System) web server demo has the web pages stored in external SD CARD and accessed through FATFS API. This demo currently only works with PIC32MZ using the Multimedia Expansion Board II (MEB II) Setup. PIC32MZ Testing and Fixes in progress. 3.8.4.1.2.1 Supported Hardware Lists supported demonstration and development hardware boards. Description Demo Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit -- Multimedia Expansion Board II (MEB II) -- 3.8.4.1.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description • Plug the PIC32MZ Embedded Connectivity (EC) Starter Kit into application board connector on the MEB II • Make sure a microSD card is formatted and loaded with the web pages provided under ‘apps/tcpip/web_server_sdcard_fatfs/firmware/src/web_pages2_sdcard’ directory • Insert the microSD card with the web pages into the microSD card slot (J8) on the MEB II 3.8.4.1.2.3 Running the Demonstration This section provides instructions on how to build and run the TCP/IP SD CARD FS Web Server demonstration. Description To view the web page hosted by the demonstration application open a web browser, type http://mchpboard_e in the address bar and press the Enter key. Please use the following procedure to run the demonstration: 1. Load demonstration project into MPLAB X IDE. 2. Connect the mini-B debugger port on-board the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter Kit to a USB port on the Development computer using the USB cable provided in the kit. 3. Connect the RJ-45 Ethernet port on the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter Kit board to a network hub or an Ethernet port on the development computer using the Ethernet patch cord provided in the kit. 4. Make sure the microSD card with the web pages is inserted into the microSD card slot on the MEB II. 5. Build, Download, and Run demonstration project on the target board. 6. A HTTP server is hosted by the demonstration application. Open a web browser, type http://mchpboard_e in the address bar and press the Enter key. The demonstration application features following: 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-133 a. Real-time hardware control and Dynamic Variables - On the Overview page the LEDs can be clicked to toggle LEDs on the Ethernet Starter Board. The buttons on Ethernet Starter Board can be pressed to see the Buttons on the web page toggle. The dynamic variables can be updated in real time on the HTTP server. Note: LED functionality part of the demonstration is somewhat limited due to errata items related to the functional multiplexing on GPIO and Ethernet pins. b. Form Processing - Input can be handled from the client by using GET and POST methods. c. Authentication - Shows an example to restricted access feature commonly used. d. Cookies – Shows the example of storing small text stings on the client side. e. File Uploads - Shows an example of file upload using POST method. The HTTP server can accept a user defined MPFS/MPFS2 image file for web pages. f. Send E-mail – Shows a simple SMTP POST methods. g. Dynamic DNS – Exercise Dynamic DNS capabilities. h. Network Configuration - MAC address, host name and IP address of the PIC32 Ethernet starter board can be viewed in the Network Configuration page and some configuration can be updated. 3.8.4.1.3 web_server_nvm_mpfs This section describes the steps necessary to begin using Microchip's TCP/IP Web server Demonstration Application. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-134 Description The TCP/IP NVM MPFS web server demo (‘apps/tcpip/web_server_nvm_mpfs/firmware/pic32_ethernet_starter_kit.X’) exercises the HTTP web server running on PIC32 devices. The Non-Volatile Memory (NVM) MPFS (Microchip Proprietary File System) web server demonstration has the web pages stored in internal Flash and accessed through the MPFS API. 3.8.4.1.3.1 Supported Hardware Lists supported demonstration and development hardware boards. Description Demo Board (click link for board information) Notes PIC32 Ethernet Starter Kit -- PIC32MZ Embedded Connectivity (EC) Starter Kit -- 3.8.4.1.3.2 Configuring the Hardware Describes how to configure the supported hardware. Description No hardware related configuration or jumper setting changes are necessary. 3.8.4.1.3.3 Running the Demonstration This section provides instructions on how to build and run the TCP/IP Web Server demonstration. Description To view the web page hosted by the demonstration application open a web browser, type http://mchpboard_e in the address bar and press the enter key. Please use the following procedure to run the demonstration: 1. Load demonstration project into MPLAB X IDE. 2. Connect the mini-B debugger port on-board the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter KitStarter board to a USB port on the Development computer using the USB cable provided in the kit. 3. Connect the RJ-45 Ethernet port on the PIC32MZ Embedded Connectivity (EC) Starter Kit or PIC32MZ Ethernet Starter Kit board to a network hub or an Ethernet port on the development computer using the Ethernet patch cord provided in the kit. 4. Build, Download, and Run demonstration project on the target board. 5. A HTTP server is hosted by the demonstration application. Open a web browser, type http://mchpboard_e in the address bar and press the enter key. The demonstration application features following: a. Real-time hardware control and Dynamic Variables - On the Overview page the LEDs can be clicked to toggle LEDs on the Ethernet Starter Board. The buttons on Ethernet Starter Board can be pressed to see the Buttons on the web page toggle. The dynamic variables can be updated in real time on the HTTP server. Note: LED functionality part of the demonstration is somewhat limited due to errata items related to the functional multiplexing on GPIO and Ethernet pins. b. Form Processing - Input can be handled from the client by using GET and POST methods. c. Authentication - Shows an example to restricted access feature commonly used. d. Cookies – Shows the example of storing small text stings on the client side. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstrations 3-135 e. File Uploads - Shows an example of file upload using POST method. The HTTP server can accept a user defined MPFS/MPFS2 image file for web pages. f. Send E-mail – Shows a simple SMTP POST methods. g. Dynamic DNS – Exercise Dynamic DNS capabilities. h. Network Configuration - MAC address, host name and IP address of the PIC32 Ethernet starter board can be viewed in the Network Configuration page and some configuration can be updated. 3.8.5 Demonstration Board Information Information on Hardware used by the TCP/IP Demonstration Applications. Description This section provide details on the different hardware boards that are used by the demonstration applications. 3.8.5.1 PIC32 Ethernet Starter Kit Information on PIC32 Ethernet Starter Kit Hardware. Description This board provides a low-cost, modular development system for Microchip’s line of 32-bit Microcontrollers (MCUs) 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-136 PIC32 Ethernet Starter Kit More Information Microchip Part Number: DM320004 Microchip Product Page 3.8.5.2 PIC32MZ Embedded Connectivity (EC) Starter Kit Information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-137 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-138 Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-139 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.8.5.3 Multimedia Expansion Board II (MEB II) Provides details information on the Multimedia Expansion Board II (MEB) II. Description Microchip Part Number: DM320005-2 Product Page The front side of the MEB II includes these key features, as shown in Figure 1: 1. Display daughter board connector (60-pin Hirose board-to-board connector). 2. mTouch™ buttons. 3. Push Button. 4. Power LED. 5. User LEDs. 6. VGA Camera (OVM7690). 7. PICtail™ Connector. 8. Analog temperature sensor. 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-140 Figure 1: Multimedia Expansion Board II Layout (Front) The underside of the MEB II includes these key features, as shown in Figure 2: 1. Regulated 5V and 3.3V power supply for powering the board via a 9-15V DC Adapter. 2. PIC32 Starter Kit connector (168-pin Hirose board-to-board connector). 3. 24-bit stereo audio codec (AK4953A). 4. Integrated 802.11bg wireless module (MRF24WG0MA). 5. Low-cost Bluetooth® HCI transceiver (BTM805). 6. EBI SRAM memory (IS61WV102416BLL). 7. microSD slot. 8. Analog accelerometer (ADXL325). Figure 2: Multimedia Expansion Board II Layout (Back) 3.8 TCP/IP Demonstrations MPLAB Harmony Help Demonstration Board Information 3-141 3.9 USART Driver Demonstration 3.9.1 Introduction This help manual contains instructions and information about MPLAB Harmony USART driver demo application, which are contained in the MPLAB Harmony Library distribution. Description This application demonstrates how to use the MPLAB Harmony USART driver. This help manual describes the hardware requirement and procedures to build and execute the demo project on Microchip development tools. In this demo application, USART driver will initially transmit strings of data and then accept and characters received and transmit the data back. Error or success status is indicated by LED display. To know more about MPLAB Harmony USART driver, configuring the USART driver and API's provided by the USART driver, refer to USART Driver Library documentation. 3.9.2 Release Notes MPLAB Harmony Version: v0.70b USART Driver Demonstration: 0.01a Release Date: 18Nov2013 New This Release: This is the first release of this USART driver demo application. This demo has been developed to support PIC32MX devices only. Known Issues: • Changes in USART driver interfaces will have impact on this demo application as well in subsequent releases • This demo is has not been developed to run on PIC32MZ devices. Users must add a new configuration if intended to run on PIC32MZ devices. 3.9.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS 3.9 USART Driver Demonstration MPLAB Harmony Help SW License Agreement 3-142 BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.9.4 Hardware This section describes how to select and use an appropriate development board and steps to configure the hardware to run this USART driver demo. 3.9.4.1 Required Hardware This section describes the overview of required device family and supported demonstration boards to run this USART driver demo application. Description This section describes the hardware required to execute the Harmony USART driver demo application. 3.9.4.1.1 Supported Demonstration Boards Lists supported demonstration and hardware development boards. Description Demonstration Board Notes Explorer 16 Development Board - 3.9.4.1.2 Hardware Information Information on hardware used by the USART driver demo application. Description The USART driver demo application can be tried across on hardware boards. This section provide details on the different hardware boards that are used by the demo application. 3.9.4.1.2.1 Explorer 16 Development Board Provides information on the Explorer 16 Development Board . 3.9 USART Driver Demonstration MPLAB Harmony Help Hardware 3-143 Description S1 - Reset button (MCLR) S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM). S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use. D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use. More Information: Microchip Part Number: DM240001 3.9.4.1.2.2 PIC32MX795F512L Plug-in Module (PIM) Provides information on the PIC32MX795F512L Plug-In-Module (PIM). Description This PIM is required while using the Explorer 16 Development Board. 3.9 USART Driver Demonstration MPLAB Harmony Help Hardware 3-144 More Information Microchip Part Number: MA320003 Information Sheet 3.9.4.2 Configuring the Hardware This section describes how to configure the supported hardware. Description Explorer 16 Development Board Below are the hardware hardware configuration settings required to execute this demo 1. Before attaching the PIC32MX795F512L PIM to the Explorer 16 Deveolpment Board, ensure that the processor select switch (S2) is in the PIM Position. 2. Short JP2 on the Explorer 16 Development Board to enable the LEDs. 3.9.5 Building the Application This section describes how to build this demo project. 3.9 USART Driver Demonstration MPLAB Harmony Help Building the Application 3-145 Description Once the hardware is configured, you are ready to build this application. Project Setup: From MPLAB X IDE, Select "open project" and browse to this demo project location. This demo application is available in "/apps/driver/usart/usart_echo/firmware/usart_echo.X". This directory contains all the application related source files, header files as well as MPLAB X IDE project related workspace files. How to build this demo application: To build this demo in debug mode, Go to "Run" menu in MPLAB X IDE and select "Build Main Project" or select "Build Main Project" in toolbar. Once the project gets compiled successfully, you can run this demo application. For more information on how to compile and program projects, refer to the MPLAB X IDE help available through the help menu in MPLAB X IDE. Note: The appropriate project configurations should be selected before building the project for the configured hardware. 3.9.5.1 Configuring the Application This section describes the list of configuration options , build options and how they are configured for this demo application. Build options: The default target device is selected as "PIC32MX795F512L" with optimization level as "0". The various optimization levels can be selected from the list to run this demo. Note: If the target device is changed, then appropriate PIM needs to be used to run this demo application Configuration options: All the demo application related configuration options are available in "system_config.h" file. This file is available in the "apps/driver/usart/usart_echo/firmware/src/system_config/pic32mx_default" directory based on the configured hardware. Note: Based on the configurations, the demo application behavior will be changed. 3.9.5.2 Configuring the Libraries This section describes the configuration options provided by MPLAB Harmony Libraries used by the application. The below parameters are defined in "system_config.h" header file. Parameter Name Description #define DRV_USART_INSTANCES_NUMBER This macro defines the maximum number of hardware instances that will be used by the application. The USART driver will support a maximum of that many hardware instances. #define DRV_USART_CLIENTS_NUMBER This macro defines the maximum number of clients that will be used by the application. The USART driver will support a maximum of that many clients. #define DRV_USART_INTERRUPT_MODE If this macro is set to "true", the application will run in interrupt mode. If this macro is set to "false", the application will run in polling mode #define DRV_USART_INTERRUPT_SOURCE_TX This macro defines the transmit interrupt source #define DRV_USART_INTERRUPT_SOURCE_RX This macro defines the receive interrupt source 3.9 USART Driver Demonstration MPLAB Harmony Help Building the Application 3-146 #define SYS_USART_ID This macro defines the USART module number used in the appilcation #define DRV_USART_XFER_BUFFER_NUMBER This macro defines the number of transfer buffers used in the application #define APP_UART_BAUDRATE This macro defines the baud rate to be used 3.9.5.3 Customizing the Application This section explains the steps involved in customizing the existing demo application. Customizing Existing Demo Application: Changing the USART module In system_config.h header file, modify the SYS_USART_ID macro to change the USART module number. Changing the demo to interrupt mode By default, the USART demo application will run in polling mode. Below are the steps to be followed to run the demo in interrupt mode. 1. Change #define DRV_USART_INTERRUPT_MODE to true in "system_config.h" file 2. Remove the DRV_USART_Tasks function call in sys_tasks in "system_task.c" file 3. Call the DRV_USART_Tasks function in ISR in "system_int.c" file Changing USART settings To change the USART related parameters such as baud rate, parity settings, number of stop bits, etc., select appropriate values in drvUSARTInit structure in system_init.c file After changing the above configurations, compile the customized application and program the target device. 3.9.6 Running the Application This section demonstrates how to run the USART driver demo. Description Once the demo application has been compiled successfully for the intended configuration, program the firmware into the target device. Upon execution, the application will transmit the following strings through USART with settings as defined in the application. /**************************************************** Welcome to Microchip USART Echo Demo App. Press any character. Data will be echoed back. Press 'ESC' key to exit the application /**************************************************** After transmitting the above text, the firmware will read any characters received through USART and it will transmit back the same data. If the received character is "ESC" (0x1B), the program will enetr into idle mode. Once in Idle mode, the firmware will neither transmit nor receive any data. If the application enters Idle mode, LED 5 of the Explorer 16 Development Board will 3.9 USART Driver Demonstration MPLAB Harmony Help Running the Application 3-147 illuminate. If any error occurs, LED 9 of the Explorer 16 Development Board will illuminate. 3.9.7 Files This section provides a complete list of source and header files used by the application and describes the purpose of adding each files. MPLAB Harmony installation follows a standard directory structure for all application solutions. In this directory structure, the driver, plib, system services related source files, header files for this demo application are available in "/framework/". Below are the list of files added in this demo application. Files Description driver.h Driver Library Interface Header drv_common.h This file defines all common macros and definitions used by the driver drv_usart.h USART device driver interface file. system.h System Service Interface Headers sys_common.h This file contains system Common definitions and declarations sys_module.h This file contains system module definitions system_config.h This is file contains all the system configurations system_definitions.h This contains system prototypes and definitions app.h This file contains application related definitions and prototypes config_performance.c BSP file for the Explorer 16 Development Board drv_usart_dynamic.c This file contains USART device driver dynamic implementation plib_int_pic32.c Interrupt Source implementation for PIC32 devices sys_clk.c This file contains clock system service implementation sys_clk_pic32.c This file contains clock system service implementation specific to PIC32 devices sys_queue.c This file contains system queue services sys_int_pic32.c This file contains functions related to the Interrupt System Service for PIC32 devices sys_ports.c This file contains Ports System Service interface implementation. app.c This file contains application related implementations main.c This file contains application's main entry point system_init.c This file contains source code necessary to initialize the system system_int.c This file contains a definitions of the raw ISRs required to support the interrupt sub-system system_tasks.c This file will contain any source code necessary to maintain various tasks in the system 3.9 USART Driver Demonstration MPLAB Harmony Help Files 3-148 3.10 USB Demonstrations 3.10.1 USB Demonstrations 3.10.1.1 Introduction USB Library Demonstration Applications Help Description This distribution package contains a variety of USB-related firmware projects that demonstrate the capabilities of the MPLAB Harmony USB stack. This help file describes the hardware requirement and procedures to run these firmware projects on Microchip demonstration and development boards. To know more about MPLAB Harmony USB stack and configuring the USB stack and the APIs provided by the USB stack, refer to the USB Library documentation. 3.10.1.2 Release Notes MPLAB Harmony Version: v0.70b USB Demonstration: 0.01a Release Date: 18Nov2013 New This Release: Nothing to report in this release. Known Issues: Device Stack Demonstration Applications: All Device Stack Demonstration applications uses a custom Board Support Package (BSP) to access demonstration board switches and LEDs. The board support package does not use PORTS Peripheral Library. In the next release, all Device Stack Demonstration Applications will be updated to use the standard Harmony BSP. The demonstration application specific issues are listed here: cdc_com_port_single: Nothing to report in this release. cdc_com_port_dual: Nothing to report in this release. cdc_serial emulator: • This version of the demo does not support baud rate change. The supported baud rate is 9600bps, 1 stop bit and no parity. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-149 • The application code accesses the UART2 peripheral SFR directly. This will be updated in the next release to use the USART driver and the System Clock Service. hid_basic: Nothing to report in this release. hid_keyboard: Nothing to report in this release. hid_joystick: Nothing to report in this release. hid_mouse: Nothing to report in this release. audio_speaker: While running the pic32mz_sk_meb2_int_dyn configuration, a periodic glitch is heard in the output audio. This is a known issue and will be fixed in the next release of the stack. Host Stack Demonstration Applications: All Host Stack Demonstration applications uses a custom Board Support Package (BSP) to access demonstration board switches and LEDs. The board support package does not use PORTS Peripheral Library. In the next release, all Host Stack Demonstration Applications will be updated to use the standard Harmony BSP. cdc_basic: This demo is not tested for the pic32mx_usb_sk_int_dyn configuration and may not function when built for this configuration. msd_basic: While running this demo, if the USB Flash drive already contains a file named “File.txt”, the file contents may become corrupted. 3.10.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-150 3.10.1.4 Demonstration Application Configurations This topic provides information on the USB demonstration project configuration that are available in MPLAB Harmony. Description The available USB Demonstration application MPLAB X IDE projects feature support for multiple configurations. Selecting these configurations allow for the demonstration projects to run across different PIC32 microcontrollers and development boards. The following project configurations are available: • pic32mx_usb_sk_int_dyn – Selecting this configuration will set up the demonstration application to run on the PIC32 USB Starter Kit II development board, with the PIC32MX795F512L microcontroller. The system will be configured for interrupt mode operation and drivers will be configured for dynamic operation mode. • pic32mz_sk_int_dyn – Selecting this configuration will set up the demonstration application to run on the PIC32MZ Embedded Connectivity (EC) Starter Kit development board, with the PIC32MZ2048ECH144 microcontroller. The system will be configured for interrupt mode operation and drivers will be configured for dynamic operation mode. • explorer16_pic32mx795f512l_int_dyn – Selecting this configuration will set up the demonstration application to run on the Explorer 16 Development Board along with the PIC32MX795F512L microcontroller Plug In Module . The system will be configured for interrupt mode operation and drivers will be configured for dynamic operation mode. • pic32mx_usb_audio_int_dyn - Selecting this configuration will set up the demonstration application to run on PIC32 USB Digital Audio Accessory Board along with the PIC32MX250F128B microcontroller. The system will be configured for interrupt mode operation and drivers will be configured for dynamic operation mode. • pic32mz_sk_meb2_int_dyn – Selecting this configuration will set up the demonstration application to run on the PIC32MZ EC Starter Kit development board, with the PIC32MZ2048ECH144 microcontroller board attached to the Multimedia Expansion Board II (MEB II). The system will be configured for interrupt mode operation and drivers will be configured for dynamic operation mode. The following figure shows how a configuration can be selected in MPLAB X IDE. Alternatively, the active configuration can be selected in the Project Properties dialog box. The following table shows the availability of a configuration across available USB device demonstration applications. Green indicates support. Red indicates no support. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-151 The following table shows the availability of a configuration across available USB device demonstration applications. Green indicates support. Red indicates no support. 3.10.1.5 Demonstrations Description of USB Demonstrations Description The USB Demonstrations are grouped into USB Device Stack and USB Host Stack Demonstrations. 3.10.1.5.1 Device 3.10.1.5.1.1 cdc_com_port_single Demonstrates a USB CDC device, emulating a serial COM port. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-152 Description This demonstration application creates a USB CDC Device that enumerates as a single COM port on the host PC. The application demonstrates two-way communication between the USB device and the PC host. 3.10.1.5.1.1.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.1.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.1.3 Running the Demonstration Provides instructions on how to build and run the CDC single COM port demonstration. Description This demonstration allows the device to appear like a serial (COM) port to the host. In order to run this demonstration first compile and program the target device. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32M USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. Attach the device to the host. If the host is a PC and this is the first time you have plugged this device into the computer then you may be asked for a .inf file. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-153 Select the “Install from a list or specific location (Advanced)” option. Point to the “/apps/usb/device/cdc_com_port_single/inf” directory. Once the device is successfully installed, open up a terminal program, such as HyperTerminal. Select the appropriate COM port. On most machines this will be COM5 or higher. Once connected to the device, there are two ways to run this example project. Typing a key in the terminal window will result in the device echoing the key pressed. So if the user presses “b”, the device will echo “c”. If the pushbutton SW1 is pressed the device will echo "PUSH BUTTON PRESSED" to the terminal window. Note: Some terminal programs, like HyperTerminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again in order to reconnect to the device. 3.10.1.5.1.2 cdc_com_port_dual Demonstrates a USB CDC device, emulating dual serial COM ports - one looping back into the other. Description This demonstration application creates a USB CDC Device that enumerates as 2 serial ports on USB Host PC. This application demonstrates the ability of the MPLAB Harmony USB stack to support multiple instances of the same device class. 3.10.1.5.1.2.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-154 No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.2.3 Running the Demonstration Provides instructions on how to build and run the CDC dual COM port demonstration. Description This demonstration allows the device to appear like dual serial (COM) ports to the host. In order to run this demonstration first compile and program the target device. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32 USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. Attach the device to the host. If the host is a PC and this is the first time you have plugged this device into the computer then you may be asked for a .inf file. Select the “Install from a list or specific location (Advanced)” option. Point to the “/apps/usb/device/cdc_com_port_dual/inf” directory. Once the device is successfully installed, open up two instances of a terminal program, such as HyperTerminal. Select the appropriate COM port for each of these terminal instance. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-155 To run the demonstration, type a character or string in one terminal window. The same character or string appears on the second terminal window. Similarly, any character typed on second window appears on the first window. Note: Some terminal programs, like HyperTerminal, require users to click the disconnect button before removing the device from the computer. Failing to do so may result in having to close and open the program again in order to reconnect to the device. 3.10.1.5.1.3 cdc_serial_emulator This application demonstrates the use of the CDC device class in implementing a USB-to-Serial Dongle. Description This application demonstrates the use of the CDC device class in implementing a USB-to-Serial Dongle. The application enumerates a COM port on the PC. Data received through the CDC USB interface is forwarded to a UART. Data received on the UART is forwarded to the CDC USB interface. This emulates a USB-to-Serial Dongle. 3.10.1.5.1.3.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB PIC32MX795F512L Plug-In Module (PIM) 1 Any commercially available USB-to-Serial dongle - Note 1: This board cannot be used by itself. It requires an Explorer 16 Development Board (DM240001) and a USB PICtail Plus Daughter Board (AC164131) in order to operate. 3.10.1.5.1.3.2 Configuring the Hardware Describes how to configure the supported hardware. Description Explorer 16 Development Board Based Demonstrations For all of the Explorer 16-based demonstration boards, please follow the following instructions: 1. Connect the USB PICtail Plus Daughter Board to the Explorer 16 Development Board. 2. Short JP2 and JP3 on the USB PICtail Plus Daughter Board 3. Open JP1 and JP4 on the USB PICtail Plus Daughter Board 4. Make sure that S2 on the Explorer 16 Development Board is switched to the "PIM" setting. 5. Short JP2 on the Explorer 16 Development Board to enable the LEDs. 6. Follow any processor specific instructions below. All instructions apply to the PIM unless otherwise stated: PIC32MX795F512L PIM 7. Open J10. 8. Short pins 1 (marked "USB") and pin 2 (center) of jumpers J1 and J2. 3.10.1.5.1.3.3 Running the Demonstration Provides instructions on how to build and run the CDC Serial Emulator Demonstration. Please refer to Release Notes for demonstration limitations, if any. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-156 Description This application demonstrates the use of the CDC device class in implementing a USB to Serial Dongle. The application enumerates a COM port on the PC. Data received through the CDC USB interface is forwarded to a UART. Data received on the UART is forwarded to the CDC USB interface. This emulates a USB-to-Serial Dongle. 1. Open the project in MPLAB X IDE. Make sure that exp16_pic32mx795f512l_int_dyn configuration is selected. 2. Build the code and program the device. 3. Connect the USB PICtail Plus Daughter Board to the Explorer 16 Development Board. 4. Power up the Explorer 16 Development Board and connect a debugger/programmer of your choice to the Explorer 16 Development Board. 5. Build the code and program the device. 6. Connect the mini-B device connector on the USB PICtail Plus Daughter Board to the PC. If the host is a PC and this is the first time you have plugged this device into the computer, you may be asked for a .inf file. 7. Select the “Install from a list or specific location (Advanced)” option. Point to the “/apps/usb/device/cdc_serial_emulator/inf” directory. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-157 When enumerated successfully, LED D5 will be the only LED illuminated on the Explorer 16 Development board. 8. Open a terminal emulation program of your choice and select the enumerated USB COM port. 9. Connect the USB-to-Serial Dongle to the same PC. 10. Open another instance of the terminal emulation program and select the USB-to-Serial Dongle. 11. Connect the serial connector of the USB-to-Serial Dongle to the UART connector (P1) on the Explorer 16 Development Board. 12. Choose a baud rate of 9600, 1 stop bit and no parity while opening both of the terminal emulation programs. The setup should be similar to the following diagram. Any text entered into the terminal 1 program will be echoed on terminal 2 and vice versa. 3.10.1.5.1.4 hid_basic This demonstration application creates a custom HID device that can be controlled by a PC based utility. Description This application creates a custom HID device that can be controlled by a PC based utility. The device allows the USB Host utility to control the LEDs on the board and query the status of a switch. 3.10.1.5.1.4.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.4.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-158 PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.4.3 Running the Demonstration Provides instructions on how to build and run the HID Basic demonstration. Description This demonstration uses the selected hardware platform as a HID class USB device, but uses the HID class for general purpose I/O operations. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32 USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. Typically, the HID class is used to implement human interface products, such as mice and keyboards. The HID protocol is however quite flexible, and can be adapted and used to send/receive general purpose data to/from a USB device. Using the HID class for general purpose I/O operations is quite advantageous, in that it does not require any kind of custom driver installation process. HID class drivers are already provided by and are distributed with common operating systems. Therefore, upon plugging in a HID class device into a typical computer system, no user installation of drivers is required, the installation is fully automatic. HID devices primarily communicate through one interrupt IN endpoint and one interrupt OUT endpoint. In most applications, this effectively limits the maximum achievable bandwidth for full speed HID devices to 64 kBytes/s of IN traffic, and 64 kBytes/s of OUT traffic (64 kB/s, but effectively “full duplex”). The GenericHIDSimpleDemo.exe program, and the associated firmware demonstrate how to use the HID protocol for basic general purpose USB data transfer. Before you can run the GenericHIDSimpleDemo.exe executable, you will need to have the Microsoft® .NET Framework Version 2.0 Redistributable Package (later versions probably okay, but not tested) installed on your computer. Programs which were built in the Visual Studio® .NET languages require the .NET redistributable package in order to run. The redistributable package can be freely downloaded from Microsoft’s website. Users of Windows Vista® operating systems will not need to install the .NET framework, as it comes pre-installed as part of the operating system. To launch the application, simply double click on the executable “GenericHIDSimpleDemo.exe” in the “\apps\usb\device\hid_basic\bin” directory. A window like that shown below should appear: If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 2.0 Redistributable Package has not yet been installed. Please install it and try again. In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for HID class USB devices with VID = 0x04D8 and PID = 0x003F. The device descriptor in the firmware project meant to be used with this demonstration uses the same VID/PID. If you plug in a USB device programmed with the correct pre-compiled .hex file, and hit the “Connect” button, the other push buttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware. Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the HID class USB peripheral device. The data will arrive on the interrupt OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demonstration board. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-159 The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the interrupt OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state. Following table shows the button that has to be pressed on the demonstration board to see the push button state changing. Demonstration Board Button PIC32 USB Starter Kit II SW1 3.10.1.5.1.5 hid_mouse Demonstrates a USB HID device, emulating a mouse pointing device. Description This demonstration application creates a USB HID based 2 button mouse device. When connected, the device emulates mouse operation by moving the cursor in a circular pattern. 3.10.1.5.1.5.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.5.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.5.3 Running the Demonstration Provides instructions on how to build and run the HID Mouse Demonstration. Description This demonstration uses the selected hardware platform as a USB mouse. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32 USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. Before connecting the board to the computer through the USB cable please be aware that the device will start moving the mouse cursor around on the computer. There are two ways to stop the device from making the cursor to continue to move. The first way is to disconnect the device from the computer. The second is to press the correct button on the hardware platform. Pressing the button again will cause the mouse cursor to start moving in a circle again. Following table shows the button that has to be pressed on the demonstration board to stop the circular motion: 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-160 Demonstration Board Button PIC32 USB Starter Kit II SW1 3.10.1.5.1.6 hid_keyboard Demonstrates a USB HID device, emulating a keyboard. Description This demonstration application creates a Generic HID keyboard. Pressing a key on the board emulates a keyboard key press. 3.10.1.5.1.6.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.6.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.6.3 Running the Demonstration Provides instructions on how to build and run the USB HID Keyboard demonstration. Description This demonstration uses the selected hardware platform as a USB keyboard. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32 USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. Before pressing the button, select a window in which it is safe to type text freely. Pressing the button on the demonstration board will cause the device to print a character on the screen. Following table shows the button that has to be pressed on the demonstration board to print a character. Demonstration Board Button PIC32 USB Starter Kit II SW1 3.10.1.5.1.7 hid_joystick Demonstrates a USB HID device emulating a joystick. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-161 Description This demonstration application creates a custom HID joystick. This application is only intended to demonstrate creation of Joystick HID Report descriptors and may not be a definite end solution. The end application requirements may need the report descriptor to be modified. 3.10.1.5.1.7.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Starter Kit II - PIC32MZ Embedded Connectivity (EC) Starter Kit - 3.10.1.5.1.7.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Starter Kit II No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit No hardware related configuration or jumper setting changes are necessary. 3.10.1.5.1.7.3 Running the Demonstration Provides instructions on how to build and run the USB HID Josytick demonstration. Description This demonstration uses the selected hardware platform as a USB Joystick. While compiling, select the pic32mx_usb_sk_xxx_xxx configurations for the PIC32 USB Starter Kit II or select the pic32mz_sk_xxx_xxx configurations for PIC32MZ Embedded Connectivity (EC) Starter Kit. To test the joystick feature, go to the “\apps\usb\device\generic_device\bin” directory. A window like that shown below should appear: If instead of this window, an error message pops up while trying to launch the application, it is likely the Microsoft .NET Framework Version 3.5 Redistributable Package has not yet been installed. Please install it and try again. In order to begin sending/receiving packets to the device, you must first find and “connect” to the device. As configured by default, the application is looking for USB devices with VID = 0x04D8 and PID = 0x0204. The device descriptor in the firmware project meant to be used with this demonstration uses the same VID/PID. To run the demonstration program the USB device with the correct precompiled .hex file. If you are connecting the device for the first time, Windows pops up a window asking you 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-165 to install the driver for the device. When asked for the driver point it to the inf file provided along with the demonstration. Windows takes while to install the driver for the USB device that is just plugged in. Open the Device manager and ensure that the USB device is listed under the ‘Libusb Demo Devices’. Once the driver is installed hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware. If a different VID/PID combination from the default is desired, then the descriptors in the firmware must be changed as well as the inf file. The easiest way to change the inf file is to use the utility provided with the LibUSB download for windows on the LibUSB website. This utility can create a new inf file based on a connected device. So make sure to change the VID/PID combination first in the firmware, connect the device, and then run the inf file creator utility. After completing the utility, a new signed driver with inf file is created. Once the driver is installed hit the “Connect” button, the other pushbuttons should become enabled. If hitting the connect button has no effect, it is likely the USB device is either not connected, or has not been programmed with the correct firmware. Hitting the Toggle LED(s) should send a single packet of general purpose generic data to the Custom class USB peripheral device. The data will arrive on the Bulk OUT endpoint. The firmware has been configured to receive this generic data packet, parse the packet looking for the “Toggle LED(s)” command, and should respond appropriately by controlling the LED(s) on the demonstration board. The “Get Pushbutton State” button will send one packet of data over the USB to the peripheral device (to the Bulk OUT endpoint) requesting the current pushbutton state. The firmware will process the received Get Pushbutton State command, and will prepare an appropriate response packet depending upon the pushbutton state. The PC then requests a packet of data from the device (which will be taken from the Bulk IN endpoint). Once the PC application receives the response packet, it will update the pushbutton state label. Try experimenting with the application by holding down the appropriate pushbutton on the demonstration board, and then simultaneously clicking on the “Get Pushbutton State” button. Then try to repeat the process, but this time without holding down the pushbutton on the demonstration board. Following table shows the button that has to be pressed on the demonstration board to see the push button state changing. Demonstration Board Button PIC32 USB Starter Kit II SW1 3.10.1.5.1.10 audio_speaker Demonstrates a USB Audio Device that emulates a USB speaker. Description This demonstration application creates uses the USB Audio Device class to implement a speaker. 3.10.1.5.1.10.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32 USB Digital Audio Accessory Board - PIC32MZ Embedded Connectivity (EC) Starter Kit - Multimedia Expansion Board II (MEB II) - 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-166 3.10.1.5.1.10.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32 USB Digital Audio Accessory Board No hardware related configuration or jumper setting changes are necessary. PIC32MZ Embedded Connectivity (EC) Starter Kit and Multimedia Expansion Board II (MEB II) 1) Fix the PIC32MZ Embedded Connectivity (EC) Starter Kit on the MEB II board. 2) Connect a Headphone to the HP OUT jack on the MEB II board. 3.10.1.5.1.10.3 Running the Demonstration Provides instructions on how to build and run the Audio Speaker Demonstration. Description This demonstration functions as a speaker when plugged into a computer. Using any feature on the computer that normal produces sound on the speaker will work with this demonstration. The feature unit only supports the Mute control. Please note that some applications lock into a sound source when they open or close (such as some web browsers or plug-ins), so that if you plug in the speaker with the web page or video already playing, the sound might not get redirected to the USB based speakers until you close and reopen the browser. The audio device created in this demonstration has the following characteristics: • Sampling rate of 48 kHz • 2 Channel (Stereo) • PCM Format - 16 bits per Sample • Asynchronous Audio Endpoint 3.10.1.5.2 Host 3.10.1.5.2.1 cdc_basic This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. Description This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. The application uses the USB Host layer and CDC class driver to enumerate a CDC USB device. The demonstration host application then operates and uses the functionality of the attached CDC Device. 3.10.1.5.2.1.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-167 Description Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - PIC32 USB Starter Kit II - Hardware required for USB Device CDC Serial Emulator Demonstration Application - 3.10.1.5.2.1.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ Embedded Connectivity (EC) Starter Kit This hardware does not require any configuration. PIC32 Starter Kit USB II This hardware does not require any configuration. 3.10.1.5.2.1.3 Running the Demonstration Provides instructions on how to build and run the USB Host CDC Basic Demo. Please refer to the Release Notes for demonstration limitations, if any. Description This application demonstrates the use of the CDC Host Class Driver to enumerate and operate a CDC Device. The application uses the USB Host layer and CDC class driver to enumerate a CDC USB device. The demonstration host application then operates and uses the functionality of the attached CDC Device. 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. Follow the directions for setting up and running the cdc_serial_emulator USB device demonstration. 4. Connect the UART (P1) port on the Explorer 16 Development Board (running the cdc_serial_emulator demonstration) to a USB Host PC via a commercially available Serial-to-USB Dongle. 5. Start a terminal program on the USB Host PC and select the Serial-to-USB Dongle as the communication port. Select the baud rate as 9600, no parity, 1 stop bit and no flow control. 6. Connect the mini – B connector on the USB PICtail Plus Daughter Board , of the cdc_serial_emulator demonstration setup, to the Type – A USB host connector on the starter kit. 7. A prompt (“LED : “) will be displayed immediately on the terminal emulation program. 8. Pressing either the 1, 2, or 3 key on the USB Host keyboard will cause LED 1, 2, or 3 on the PIC32 Starter kit (running the USB CDC Host application) to switch on, respectively. 9. The prompt will again be displayed on terminal emulation program, and step 8 can be repeated. The setup should be similar to the following diagram. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-168 The cdc_serial_emulator demonstration emulates a USB-to-Serial Dongle. The CDC Host (running the cdc_basic demonstration application) sends the prompt message to the CDC device. The CDC device forwards the prompt to the UART port from where it is transmitted to the PC USB Host through the USB-to-Serial Dongle. A key press on the PC USB Host is transmitted to the CDC device, which in turn presents the key press data to the CDC host. The cdc_basic demonstration then analyzes the key press data and switches on the respective LED. 3.10.1.5.2.2 msd_basic This application demonstrates the use of the MSD Host Class Driver to write a file to USB Flash Drive. Description This application demonstrates the use of the MSD Host Class Driver to write a file to a USB Flash drive. The application uses the USB Host layer , MSD class driver and the MPLAB Harmony File System Framework to enumerate a USB Flash drive and to write a file to it. 3.10.1.5.2.2.1 Supported Demonstration Boards Lists supported demonstration and development hardware boards. Description Demonstration Board (click link for board information) Notes PIC32MZ Embedded Connectivity (EC) Starter Kit - PIC32 USB Starter Kit II - 3.10.1.5.2.2.2 Configuring the Hardware Describes how to configure the supported hardware. Description PIC32MZ Embedded Connectivity (EC) Starter Kit This hardware does not require any configuration. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-169 PIC32 Starter Kit USB II This hardware does not require any configuration. 3.10.1.5.2.2.3 Running the Demonstration Provides instructions on how to build and run the USB Host MSD Basic demonstration. Please refer to theRelease Notes for demonstration limitations, if any. Description This application demonstrates the use of the MSD Host Class Driver to write a file to USB Flash drive. The application uses the USB Host layer, MSD class driver and the MPLAB Harmony File System Framework to enumerate a USB Flash drive and to write a file to it. 1. Open the project in MPLAB X IDE and select the desired project configuration. 2. Build the code and program the device. 3. With the code running, attach a USB Flash drive to the Host connector on the starter kit. 4. The demonstration application will then create a file named “File.txt”. It will then write the text “Hello World” to this file, and then close the file. 5. The demonstration will then move to Idle mode, which is indicated when LED 2 on the starter kit lights up. 6. The USB Flash drive can then be attached to a USB Host PC to verify the demonstration application operation. 7. Steps 3 through 6 can be repeated. 8. If the USB Flash drive already contains a file with the name “File.txt”, the demonstration application will append the text “Hello World” to the end of the file name. 3.10.1.6 Demonstration Board Information Information on Hardware used by the USB Library Demo Applications. Description The USB Library Demo Applications can be tried across on hardware boards. This section provide details on the different hardware boards that are used by the demo applications. 3.10.1.6.1 PIC32 USB Starter Kit II Provides details information on the PIC32 USB Starter II. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-170 Description SW1 - Application switch. Tied to RD6. SW2 - Application switch. Tied to RD7. SW3 - Application switch. Tied to RD13. LED1 - Application LED. Tied to RD0. LED2 - Application LED. Tied to RD1. LED3 - Application LED. Tied to RD2. This board supports the following USB Device demonstrations: • CDC Single COM port (cdc_com_port_single). • CDC Dual COM port (cdc_com_port_dual) • HID Basic (hid_basic) • HID Mouse (hid_mouse) • HID Keyboard (hid_keyboard) • HID Joystick (hid_joystick) • MSD Flash Drive (msd_basic) • Generic USB Device (generic_device) More Information Microchip Part Number : DM320003-2 3.10.1.6.2 Explorer 16 Development Board Provides information on the Explorer 16 Development Board 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-171 Description S1 - Reset button (MCLR) S2 - Processor switch. This switch determines which processor is running, the processor on the board or the processor on the Plug-In-Module (PIM). S3, S4, S5, S6 - Application switches. For information about what pin is connected to this switch, please refer to the information for the PIM in use. D3 through D10 - Application LEDs. For information about what pin is connected to this LED, please refer to the information for the PIM in use. This board support the following USB Host demos: 1. CDC Host (cdc_serial) More Information: Microchip Part Number: DM240001 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-172 3.10.1.6.3 PIC32MX795F512L Plug-In-Module (PIM) Provides information on the PIC32MX795F512L Plug-In-Module (PIM). Description This PIM is required while using the Explorer 16 Development Board. More Information Microchip Part Number: MA320003 Information Sheet 3.10.1.6.4 PIC32 USB Digital Audio Accessory Board Provides information on the PIC32 USB Digital Audio Accessory Board Description This board support the following USB Device demonstration: Audio Speaker (audio_speaker) More Information: Microchip Part Number: DM320014 3.10.1.6.5 PIC32MZ Embedded Connectivity (EC) Starter Kit Provides details information on the PIC32MZ Embedded Connectivity (EC) Starter Kit. Description Microchip Part Number: DM320006 (without Crypto) or DM320006-C (with Crypto) The top assembly of the board includes these key features, as indicated in Figure 1: 1. PIC32MZ2048ECH144 32-bit microcontroller. 2. Green power indicator LED. 3. On-board crystal or oscillator for precision microcontroller clocking (12 MHz). 4. USB connectivity for on-board debugger communications. 5. Green debug indicator LED. 6. Three push button switches for user-defined inputs. 7. Three user-defined indicator LEDs. 8. USB Type A receptacle connectivity for PIC32 host-based applications. 9. HOST mode power jumper. 10. Daughter board connectors for flexible Ethernet PHY options. 11. 32 kHz oscillator for RTCC and Timer1 (optional). 12. External 2 GB SQI memory for expanded memory application. 13. Jumper for using or disconnecting the on-board debugger. NOTE: When running self-powered USB device applications, open the jumper JP1 to prevent possibly back-feeding voltage onto the Vbus from one port on the host to another (or from one host to another). 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-173 Figure 1: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Front) The bottom assembly of the board includes these key features, as indicated in Figure 2: 1. PIC24FJ256GB106 USB microcontroller for on-board debugging. 2. Regulated +3.3V power supply for powering the starter kit via USB or expansion board. 3. Connector for various expansion boards. 4. USB Type micro-AB receptacle for OTG and USB device connectivity for PIC32 OTG/device-based applications. 5. 50 MHz Ethernet PHY oscillator. 6. USB Host and OTG power supply for powering PIC32 USB applications. Figure 2: PIC32MZ Embedded Connectivity (EC) Starter Kit Layout (Back) 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-174 3.10.1.6.6 Multimedia Expansion Board II (MEB II) Provides details information on the Multimedia Expansion Board II (MEB) II. Description Microchip Part Number: DM320005-2 Product Page The front side of the MEB II includes these key features, as shown in Figure 1: 1. Display daughter board connector (60-pin Hirose board-to-board connector). 2. mTouch™ buttons. 3. Push Button. 4. Power LED. 5. User LEDs. 6. VGA Camera (OVM7690). 7. PICtail™ Connector. 8. Analog temperature sensor. Figure 1: Multimedia Expansion Board II Layout (Front) The underside of the MEB II includes these key features, as shown in Figure 2: 1. Regulated 5V and 3.3V power supply for powering the board via a 9-15V DC Adapter. 2. PIC32 Starter Kit connector (168-pin Hirose board-to-board connector). 3. 24-bit stereo audio codec (AK4953A). 4. Integrated 802.11bg wireless module (MRF24WG0MA). 5. Low-cost Bluetooth® HCI transceiver (BTM805). 6. EBI SRAM memory (IS61WV102416BLL). 7. microSD slot. 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-175 8. Analog accelerometer (ADXL325). Figure 2: Multimedia Expansion Board II Layout (Back) 3.10 USB Demonstrations MPLAB Harmony Help USB Demonstrations 3-176 4 Building Projects Help 4 MPLAB Harmony Help 4-177 4.1 Building Projects 4.1.1 Introduction This section describes the MPLAB X IDE projects that are provided to build binary (.a file) versions of key MPLAB Harmony libraries. Description The following MPLAB Harmony libraries are provided in prebuilt binary (“.a” file) format because source code is not released or to provide optimal performance for users of the free version of the compiler. The MPLAB X IDE projects used to build these libraries are provided so that you can rebuild these libraries with different build parameters, optimization settings, and/or debug symbols if desired. Note: Building these libraries with high optimization settings will require a fully licensed version of the necessary Microchip XC compiler. Build Projects Folder: “/build” Library Description framework/crypto MPLAB Harmony Encryption/Decryption Library framework/zlib MPLAB Harmony Compress/Decompression Library framework/math/dsp MPLAB Harmony Digital Signal Processing Library framework/math/libq MPLAB Harmony Fixed-point Math Library framework/peripheral MPLAB Harmony Peripheral Library Build Project 4.1.2 Release Notes MPLAB Harmony Version: v0.70b Building Projects: 0.70b Release Date: 18Nov2013 New This Release: Peripheral Libraries • Nothing to report in this release Known Issues: Peripheral Libraries • Build configurations were not created for all PIC32 devices. As a workaround, select any configuration and choose a different processor from the Project Properties dialog. This will require you to change the name of the output file to match the name of the selected processor. 4.1 Building Projects MPLAB Harmony Help Using the Build Projects 4-178 4.1.3 Using the Build Projects This section describes how to use the MPLAB Harmony build projects to generate binary (“.a” file) libraries that can be linked into your project. Description The following information describes how to use the MPLAB Harmony build projects to generate binary (“.a” file) libraries that can be linked into your project. Prerequisites To build MPLAB Harmony libraries, you must have the following installed on your development workstation: • MPLAB X IDE (v1.95 or higher) • MPLAB XC32 Compiler (v1.30 or higher) • Appropriate compiler license for your desired optimization settings Build Instructions The following general instructions apply to all MPLAB Harmony library build projects. Refer to the related “Libraries” section for additional information about building specific libraries. 1. Start MPLAB X IDE. 2. Open the desired build project. 3. Set it as the “main” project. 4.1 Building Projects MPLAB Harmony Help Using the Build Projects 4-179 4. Select the desired build configuration. Note: Different libraries provide different build configurations, depending on the set of possible choices that are relevant to that library. For example, the build project for the PIC32MX peripheral libraries (shown above) allows you to select the desired PIC32MX processor. Other libraries may allow you to choose the desired optimization level or feature set. Refer to the related “Libraries” section for information on the configurations provided by the build project for the library you want to build. 5. If required, select the desired processor (or other project settings, if desired). Note: Projects that provide processor-specific configurations will not require this step. a. Open the “Project Properties” dialog box. b. Select the desired processor. 4.1 Building Projects MPLAB Harmony Help Using the Build Projects 4-180 6. Build the library. 7. Copy the binary “.a” library file to your project folder. 8. Add the binary “.a” library file to your project. 4.1.4 Supported Libraries 4.1.4.1 Crypto Library This section describes MPLAB X IDE projects used to build the MPLAB Harmony Crypto libraries. Description The Crypto Library project is contained in the build/framework/crypto folder in the crypto.X project. The library contains functions for operations on blocks of data. Encryption/decryption operations can be done using AES, RSA, DES, Triple DES, and ECC. Authentication/hashing can be done using MD5, SHA-1, SHA-256, SHA-384, and SHA-512. Password-based key derivation can be done with HMAC. Compression and decompression can be done using Huffman Encoding. Random numbers can be created either one at a time or in a block. 4.1.4.2 Compression Library This section describes MPLAB X IDE projects used to build the MPLAB Harmony compression/decompression “zlib” libraries. Description The “zlib” libraries consists of routines for handling gzip (.gz) files, include compression and decompression. The library also contains functions that provide the Huffman compression available in the Crypto library. 4.1.4.3 DSP Math Library This section describes MPLAB X IDE projects used to build the MPLAB Harmony DSP math libraries. Description The DSP Math Library consists of routines that are optimized in assembly to take advantage of the microAptivTM core of the PIC32MZ devices. The library operates on fixed point integers, which are scaled to represent floating point numbers. Many functions are available in both 16-bit and 32-bit numerical formats. The library contains functions for mathematical operations on a vector (or array) of values, complex scalar values and matrixes. 4.1 Building Projects MPLAB Harmony Help Supported Libraries 4-181 Operations include add, subtract, multiply, power, data generation, and in the cases of vectors more complex functions including statistics. The DSP Math Library also contains a full set of digital filtering functions which include FIR and IIR primitives, as well as more complex architectures (e.g., cascade and parallel bi-quad structures). Finally the library contains a number of transform functions include FFT and inverse FFT, as well as a number of windowing functions. Some functions in the DSP Math Library require the use of the LIBQ Fixed Point Math library as well. In those cases the LIBQ library must also be installed with your project. Details on dependent functions are found in the DSP Math Library help file under the remarks section for that specific function. 4.1.4.4 Fixed-Point Math Library This section describes MPLAB X IDE projects used to build the MPLAB Harmony fixed-point math “libq” libraries. Description The Fixed-Point Math Library consists of routines in optimized assembly for performing advanced mathematical operations on a scalar. This is similar in construction to the floating point equivalent math.h file that is included with the compiler. All functions are performed using fixed-point integer operations and generally available in both high precision and low precision variants. Lower precision functions generally perform faster and may be suited for time critical operations. 4.1.4.5 Peripheral Libraries This section describes MPLAB X IDE projects used to build the MPLAB Harmony peripheral libraries. Description The MPLAB Harmony peripheral libraries are implemented almost entirely using C-language inline functions. This is done for efficiency so that the compiler can generate a few simple instructions in place of multiple layers of function calls when function parameters are passed as constants. However, if the project that uses the peripheral library is built with low optimization settings, the compiler may generate a function call instead of “inlining” the function implementation. Unfortunately, this will cause an “undefined symbol” error at link time if the linker cannot find an actual implementation of the function to which it can link the “call”. To satisfy the liker (and to provide optimized PLIB operation, even when low compiler optimization settings are used in your project), the MPLAB Harmony peripheral libraries must be prebuilt as ‘.a’ file, linkable libraries. The appropriate MPLAB X IDE peripheral library “.a” file for the processor in use must be added to the MPLAB X IDE project so that the linker can use them. Note: Prebuilt binary “.a” files are provided for all supported processors in the MPLAB Harmony installation in the following folder: /bin/framework/peripheral. The MPLAB Harmony peripheral library “.a” file build projects are provided so that you may rebuild the binary peripheral library “.a” files using any desired optimization settings. However, if you do this, you must have the appropriate xC compiler and you must copy the resultant “.a” file to your project folder and add it to your MPLAB X IDE project. (See the “Build Instructions” section for details of how to build the library.). Build Configurations Different MPLAB X IDE projects are provided for different processor families to build the peripheral libraries for MPLAB Harmony. Each project provides a set of MPLAB X IDE configurations, one for each supported processor. For example, the “mplab_pic32mx_plib.X” project provides configurations for each device in the PIC32MX family. To identify which devices are supported, open the MPLAB X IDE project that is named after the device family in which you are interested, select the MPLAB X IDE configuration named after the device you want to use, and look at the project properties to verify the device that is selected. 4.1 Building Projects MPLAB Harmony Help Supported Libraries 4-182 Key Configuration Options To build the peripheral library binary “.a” files, there are two key configuration options that must be defined, as follows: #define INLINE_API extern #define INLINE static inline These two configuration items are defined in the source file (“peripehral.c”), which then directly includes the peripheral library implementation headers. Note: This has already been done for you. This information is provided strictly for reference. During normal peripheral library use, both of these options are defined as “extern inline” so that the compiler can choose between generating a function call or generating inline code, directly in the calling function (as described above). However, to build the binary library “.a” files the peripheral library Application Program Interface (API) functions must be exposed as global “external” symbols. The “INLINE_API” attribute is placed as an attribute on all PLIB API function implementations. So, defining it as “extern” allows the compiler to expose these functions within the library “.a” file so that the linker can find them. The VREG and other “internal” functions prefixed by the “INLINE” attribute are then defined as “static inline” functions for efficiency. 4.1 Building Projects MPLAB Harmony Help Supported Libraries 4-183 5 Framework Help 5 MPLAB Harmony Help 5-184 5.1 Driver Library Help 5.1.1 Driver Library Overview A device driver provides a simple well-defined interface to a hardware peripheral that can be used without operating system support or that can be easily ported to a variety of operating systems. The basic driver operations allow an application to interact with a device, reading and writing data, as if it was a simple file. More specific operations are present on most drivers and the kind of specific operations available depends on the peripheral whose functionality is being exposed by the driver. A driver has the following fundamental responsibilities: 1. Providing a highly-abstracted interface to a peripheral 2. Controlling access to a peripheral 3. Managing the state of a peripheral The diagram below illustrates how a driver interacts with the other pieces of the system. • The application calls the well defined driver interface to use the services provided by the driver. • The driver calls various system services to perform the tasks that are possibly shared across other drivers. • The driver also calls the peripheral library of the peripheral that its abstracting the interface to. • Driver State machine can be invoked by the system task service (polling system) or the driver state machine can be invoked from an ISR. The driver provided the interfaces which can be broken down into the following two categories : ( is the abbreviation identifying the module) • System Operation - The interfaces for the system operation should be called by the system. Each driver can support all of the system interfaces, or it can choose to not support the optional system interfaces. The system interfaces are • DRV__Initialize - This routine initializes hardware for the index instance of the module, using the hardware initialization given data. It also initializes any internal data structures. The DRV__Status operation will return SYS_STATUS_READY when this operation has completed. Every driver module should define its own initialization 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-185 data structure type named “DRV__INIT”. This structure must be an extension of the SYS_MODULE_INIT structure (i.e. its first member must be the SYS_MODULE_INIT structure or equivalent). Any parameter that can change the power state of the module must be included in the data structure. Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. • DRV__Reinitialize - This routine reinitializes and refreshes the hardware using the hardware initialization given data. The DRV__Status operation will return SYS_STATUS_READY when this operation has completed. It does not clear or reinitialize internal data structures (although it may change the value of a few appropriate data items necessary to manage the new hardware state) and it does not disconnect or interrupt any ongoing client operations.This operation can be used to change the power state of the peripheral the module manages. • DRV__Deinitialize - This routine de-initializes the index instance of the module, disabling its operation (and any hardware for driver modules).The DRV__Status operation will return SYS_STATUS_READY when this operation has completed. • DRV__Status - The Status operation can be used to determine when any of the other three module operations has completed. If the Status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the Status operation returns “SYS_STATUS_READY”, any previous operations have completed. • The value of SYS_STATUS_READY is 1. Values between 1 and 10 are reserved for system defined “ready” states. A module may define module-specific “ready” or “run” states greater than or equal to 10 (SYS_STATUS_READY_EXTENDED). • The value of SYS_STATUS_ERROR is -1. Values between -1 and -10 are reserved for system-defined errors. A module may define module-specific error values of less than or equal to -10 (SYS_STATUS_ERROR_EXTENDED). • If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. (Remember to check the value returned by the Status routine after calling any of the module operations to find out when they have completed.) • DRV__Tasks - Used to maintain the driver’s state machine and implement its ISR. It is normally only called by the system’s tasks routine or by an Interrupt Service Routine (ISR). The usage model of the system interfaces is demonstrated in the diagram below: The system is also responsible for either calling the Tasks routine through an ISR or poll the Tasks routine in a polling environment. • Client Operation - The interfaces provided by the driver for client operation, can be called by the application. Each driver can provide a set of client interfaces, which supports the operation model of the peripheral that the driver is supporting. The client interfaces can include 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-186 • DRV__Open - This routine opens a driver for use by any client module and provides an “open-instance” handle that must be provided to any of the other driver operations to identify the caller and the instance of the driver/hardware module. • DRV__Close - This routine closes an opened-instance of a driver, invalidating the given handle. This routine is optional, if the driver is designed to never be closed. • DRV__ClientStatus - This routine provides the client, the status of the driver. • DRV__ - This is the basic format of a driver interface routine. Driver interface routines (other than the system module routines and the basic device driver routines) should follow this format. The general usage model of the client interfaces is demonstrated in the diagram below, each driver will document usage model specific to the driver in the driver help file. Driver Configuration A driver provides a set of configurations which can be divided into following categories: 1. Build Configuration Selection Configurations - The driver supports selecting the driver instance at build time (static configuration) or at run time (dynamic configuration). A driver also supports selecting the number of clients that can possibly connect to an hardware instance. All drivers will provide DRV__DRIVER_OBJECTS_NUMBER, when this configuration macro is defined driver is built in dynamic driver configuration, else it is built in static driver configuration. The number assigned to DRV__DRIVER_OBJECTS_NUMBER controls the maximum number of driver objects that can be used. If a driver supports multiple clients it will provide DRV__CLIENT_OBJECTS_NUMBER, when this configuration macro is defined driver is built to support multiple clients, else the driver is built to support single client. The number assigned to DRV__DRIVER_OBJECTS_NUMBER controls the maximum number of client objects that can be used. 2. Initialization Overrides - Initialization overrides are provided to enable configuration of the hardware statically and with low run time overhead. These override the parameters if also passed dynamically to Initialize or Reinitialize routine. 3. Other operational configurations - These can control the functionality of the driver or other setting of the driver that are required for support core or optional functionality. A driver allows the application to use the dynamic interface for all the above configuration when the application chooses the appropriate configurations at build time. This is the preferred method of usage for the drivers. As an exception, if the application wants to use multiple configurations in the same build for a driver type, or it needs to use multiple instances of the same driver type, it needs to directly use the static single - client configuration interfaces, or it needs to use the static multiple - client configuration interfaces. While using the driver the static single client driver configuration, the application and system can choose to ignore the SYS_MODULE_INDEX, SYS_MODULE_OBJ and DRV_HANDLE passed and returned to the driver and system interfaces. While using the driver the static multiple client driver configuration, the application and system can choose to ignore the 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-187 SYS_MODULE_INDEX and SYS_MODULE_OBJ passed and returned to the driver and system interfaces. 5.1.1.1 Data Types Enumerations Name Description DRV_CLIENT_STATUS Identifies the current status/state of a client's connection to a driver. DRV_IO_BUFFER_TYPES Identifies to which buffer a device operation will apply. DRV_IO_INTENT Identifies the intended usage of the device when it is opened. Types Name Description DRV_HANDLE Handle to an opened device driver. Description 5.1.1.1.1 DRV_CLIENT_STATUS Enumeration C typedef enum { DRV_CLIENT_STATUS_ERROR_EXTENDED = -10, DRV_CLIENT_STATUS_ERROR = -1, DRV_CLIENT_STATUS_CLOSED = 0, DRV_CLIENT_STATUS_BUSY = 1, DRV_CLIENT_STATUS_READY = 2, DRV_CLIENT_STATUS_READY_EXTENDED = 10 } DRV_CLIENT_STATUS; Description Driver Client Status This enumeration identifies the current status/state of a client's link to a driver. Members Members Description DRV_CLIENT_STATUS_ERROR_EXTENDED = -10 Indicates that a non-system defined error has occurred. DRV_CLIENT_STATUS_ERROR = -1 An un-specified error has occurred. DRV_CLIENT_STATUS_CLOSED = 0 An operation is currently in progress DRV_CLIENT_STATUS_BUSY = 1 An operation is currently in progress DRV_CLIENT_STATUS_READY = 2 Any previous operations have succeeded and the module is ready for additional operations DRV_CLIENT_STATUS_READY_EXTENDED = 10 Indicates that the module is in a non-system defined ready/run state. Remarks The enumeration used as the return type for the client-level status routines defined by each device driver or system module (for example, DRV_USART_ClientStatus) must be based on the values in this enumeration. 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-188 5.1.1.1.2 DRV_HANDLE Type C typedef uintptr_t DRV_HANDLE; Description Device Handle This handle identifies the open instance of a device driver. It must be passed to all other driver routines (except the initialization, deinitialization, or power routines) to identify the caller. Remarks Every application or module that wants to use a driver must first call the driver's open routine. This is the only routine that is absolutely required for every driver. If a driver is unable to allow an additional module to use it, it must then return the special value DRV_HANDLE_INVALID. Callers should check the handle returned for this value to ensure this value was not returned before attempting to call any other driver routines using the handle. 5.1.1.1.3 DRV_IO_BUFFER_TYPES Enumeration C typedef enum { DRV_IO_BUFFER_TYPE_NONE = 0x00, DRV_IO_BUFFER_TYPE_READ = 0x01, DRV_IO_BUFFER_TYPE_WRITE = 0x02, DRV_IO_BUFFER_TYPE_RW = DRV_IO_BUFFER_TYPE_READ|DRV_IO_BUFFER_TYPE_WRITE } DRV_IO_BUFFER_TYPES; Description Device Driver IO Buffer Identifier This enumeration identifies to which buffer (read, write, both, or neither) a device operation will apply. This is used for "flush" (or similar) operations. Members Members Description DRV_IO_BUFFER_TYPE_NONE = 0x00 Operation does not apply to any buffer DRV_IO_BUFFER_TYPE_READ = 0x01 Operation applies to read buffer DRV_IO_BUFFER_TYPE_WRITE = 0x02 Operation applies to write buffer DRV_IO_BUFFER_TYPE_RW = DRV_IO_BUFFER_TYPE_READ|DRV_IO_BUFFER_TYPE_WRITE Operation applies to both read and write buffers 5.1.1.1.4 DRV_IO_INTENT Enumeration C typedef enum { DRV_IO_INTENT_READ, DRV_IO_INTENT_WRITE, DRV_IO_INTENT_READWRITE, DRV_IO_INTENT_BLOCKING, DRV_IO_INTENT_NONBLOCKING, DRV_IO_INTENT_EXCLUSIVE, DRV_IO_INTENT_SHARED 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-189 } DRV_IO_INTENT; Description Device Driver I/O Intent This enumeration identifies the intended usage of the device when the caller opens the device. It identifies the desired behavior of the device driver for the following: • Blocking or non-blocking I/O behavior (do I/O calls such as read and write block until the operation is finished or do they return immediately and require the caller to call another routine to check the status of the operation) • Support reading and/or writing of data from/to the device • Identify the buffering behavior (sometimes called "double buffering" of the driver. Indicates if the driver should maintain its own read/write buffers and copy data to/from these buffers to/from the caller's buffers. • Identify the DMA behavior of the peripheral Members Members Description DRV_IO_INTENT_READ Read DRV_IO_INTENT_WRITE Write DRV_IO_INTENT_READWRITE Read and Write DRV_IO_INTENT_BLOCKING The driver will block and will return when the operation is complete DRV_IO_INTENT_NONBLOCKING The driver will return immediately DRV_IO_INTENT_EXCLUSIVE The driver will support only one client at a time DRV_IO_INTENT_SHARED The driver will support multiple clients at a time Remarks The buffer allocation method is not identified by this enumeration. Buffers can be allocated statically at build time, dynamically at run-time, or even allocated by the caller and passed to the driver for its own usage if a driver-specific routine is provided for such. This choice is left to the design of the individual driver and is considered part of its interface. These values can be considered "flags". One selection from each of the groups below can be ORed together to create the complete value passed to the driver's open routine. 5.1.1.2 Constants Macros Name Description DRV_CONFIG_NOT_SUPPORTED Not supported configuration. DRV_HANDLE_INVALID Invalid device handle. DRV_IO_ISBLOCKING Returns if the I/O intent provided is blocking DRV_IO_ISEXCLUSIVE Returns if the I/O intent provided is non-blocking. DRV_IO_ISNONBLOCKING Returns if the I/O intent provided is non-blocking. 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-190 Description 5.1.1.2.1 DRV_CONFIG_NOT_SUPPORTED Macro C #define DRV_CONFIG_NOT_SUPPORTED (((unsigned short) -1)) Description Not supported configuration If the configuration option is not supported on an instance of the peripheral, use this macro to equate to that configuration. This option should be listed as a possible value in the description of that configuration option. 5.1.1.2.2 DRV_HANDLE_INVALID Macro C #define DRV_HANDLE_INVALID (((DRV_HANDLE) -1)) Description Invalid Device Handle If a driver is unable to allow an additional module to use it, it must then return the special value DRV_HANDLE_INVALID. Callers should check the handle returned for this value to ensure this value was not returned before attempting to call any other driver routines using the handle. Remarks None. 5.1.1.2.3 DRV_IO_ISBLOCKING Macro C #define DRV_IO_ISBLOCKING(intent) (intent & DRV_IO_INTENT_BLOCKING) Description Device Driver Blocking Status Macro This macro returns if the I/O intent provided is blocking. Remarks None. 5.1.1.2.4 DRV_IO_ISEXCLUSIVE Macro C #define DRV_IO_ISEXCLUSIVE(intent) (intent & DRV_IO_INTENT_EXCLUSIVE) Description Device Driver Exclusive Status Macro This macro returns if the I/O intent provided is non-blocking. 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-191 Remarks None. 5.1.1.2.5 DRV_IO_ISNONBLOCKING Macro C #define DRV_IO_ISNONBLOCKING(intent) (intent & DRV_IO_INTENT_NONBLOCKING ) Description Device Driver Non Blocking Status Macro This macro returns if the I/ intent provided is non-blocking. Remarks None. 5.1.1.3 Files Files Name Description driver.h This file aggregates all of the driver library interface headers. driver_common.h This file defines the common macros and definitions used by the driver definition and implementation headers. Description 5.1.1.3.1 driver.h Driver Library Interface Header This file aggregates all of the driver library interface headers so client code only needs to include this one single header to obtain prototypes and definitions for the interfaces to all driver libraries. A device driver provides a simple well-defined interface to a hardware peripheral that can be used without operating system support or that can be easily ported to a variety of operating systems. A driver has the fundamental responsibilities: • Providing a highly-abstraced interface to a peripheral • Controlling access to a peripheral • Managing the state of a peripheral Remarks The directory in which this file resides should be added to the compiler's search path for header files. File Name drv.h Company Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help Driver Library Overview 5-192 5.1.1.3.2 driver_common.h Driver Common Header This file defines the common macros and definitions used by the driver definition and the implementation header. Remarks The directory in which this file resides should be added to the compiler's search path for header files. Enumerations Name Description DRV_CLIENT_STATUS Identifies the current status/state of a client's connection to a driver. DRV_IO_BUFFER_TYPES Identifies to which buffer a device operation will apply. DRV_IO_INTENT Identifies the intended usage of the device when it is opened. Macros Name Description DRV_CONFIG_NOT_SUPPORTED Not supported configuration. DRV_HANDLE_INVALID Invalid device handle. DRV_IO_ISBLOCKING Returns if the I/O intent provided is blocking DRV_IO_ISEXCLUSIVE Returns if the I/O intent provided is non-blocking. DRV_IO_ISNONBLOCKING Returns if the I/O intent provided is non-blocking. Types Name Description DRV_HANDLE Handle to an opened device driver. File Name drv_common.h Company Microchip Technology Inc. 5.1.2 ADC Driver Library 5.1.2.1 Introduction ADC Driver for Microchip Microcontrollers This Analog-to-Digital Converter (ADC) driver provides an interface to manage the ADC module on the Microchip family of microcontrollers. Description Overview An ADC is a vital part of any system that interfaces to real-world signals. While there are many techniques for analog-to-digital 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-193 conversion, the Microchip family of microcontrollers uses Successive Approximation as one of its primary techniques. 5.1.2.2 Release Notes MPLAB Harmony Version: v0.70b ADC Driver Library Version : 0.02a Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.2.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.2.4 Using the Library This topic describes the basic architecture of the ADC Driver Library and provides information and examples on how to use it. Interface Header File: drv_adc.h The interface to the ADC Driver Library is defined in the "drv_adc.h" header file. Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.2.4.1 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The following table lists the interface section and its brief description. Section Description Configuring the Library Provides macros for configuring the system. It is required that the system configures the driver to build correctly by choosing appropriate configuration options as listed in this section. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-194 System Interaction Functions Provides system module interfaces, Device initialization, deinitialization, reinitialization and status functions. Client Core Configuration Functions Provides interfaces for core functionality of the driver. 5.1.2.4.2 Abstraction Model The ADC driver is modeled using the abstraction model, as shown in the following diagram. • DRV_ADC_InputsRegister allows selection of inputs • DRV_ADC_SamplesRead and DRV_ADC_SamplesReadLatest allow reading of the sample from the result buffer • DRV_ADC_Start and DRV_ADC_Stop will control the operation of the ADC 5.1.2.4.3 How the Library Works The library provides interfaces to support: • System Interaction • Client Core Functionality 5.1.2.4.3.1 System Initialization This section describes the system initialization and reinitialization settings for the ADC Peripheral Library. Description System Initialization and Reinitialization The system initialization and the reinitialization settings, effect only the instance of the peripheral that is being initialized or re-initialized. During system initialization configure each instance of the module with the following configuration settings that are supported by the specific ADC device hardware (refer to DRV_ADC_INIT) 1. Device requested power state: One of the system module power states. 2. Acquisition time: If the hardware supports this feature, configure this variable from DRV_ADC_ACQUISITION_TIME. 3. Voltage reference: If the hardware supports this feature, select the one from the available options(from DRV_ADC_VOLTAGE_REFERENCE). 4. Conversion clock: If the hardware supports this feature, select the conversion clock prescaler value (from DRV_ADC_CONVERSION_CLOCK_PRESCALER). 5. Conversion clock source: If the hardware supports this feature, select the conversion clock prescaler value (from DRV_ADC_CONVERSION_CLOCK_SOURCE). 6. Clock frequency: Peripheral clock frequency configured for the device. 7. Conversion trigger source: If the hardware supports this feature, select the conversion trigger source(from DRV_ADC_CONVERSION_TRIGGER_SOURCE). 8. Samples per interrupt: Configure the number of samples before to be generating interrupt(from 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-195 DRV_ADC_SAMPLES_PER_INTERRUPT). 9. Output data format: Select the output data format. 10. Interrupt source: Select the interrupt source. Example: Auto Sampling Mode #define MY_ADC_INSTANCE DRV_ADC_INDEX_0 SYS_MODULE_OBJ myAdcObj; DRV_ADC_INIT adcInitData; SYS_STATUS adcStatus; // Populate the adcInitData structure adcInitData.plibModuleId = ADC_ID_1; adcInitData.acquisitionTime = PLIB_ADC_ACQUISITION_TIME_20_TAD; adcInitData.voltageReference = PLIB_ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; adcInitData.clockFrequency = 4000000; //4MHz adcInitData.conversionClock = PLIB_ADC_CONV_CLOCK_20_TCY; adcInitData.conversionClockSource = PLIB_ADC_CLOCK_SRC_SYSTEM_CLOCK; adcInitData.conversionTriggerSource = PLIB_ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; adcInitData.dataOutputFormat = PLIB_ADC_OUTPUT_FORMAT_INTEGER_16BIT; adcInitData.initFlags = DRV_ADC_AUTO_SAMPLING; adcInitData.interruptSource= PLIB_INT_SOURCE_ADC_1; adcInitData.samplesPerInterrupt = PLIB_ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; myAdcObj = DRV_ADC_Initialize(MY_ADC_INSTANCE, (SYS_MODULE_INIT*)&adcInitData); adcStatus = DRV_ADC_Status(myAdcObj); if (SYS_STATUS_BUSY == adcStatus) { // do something else and check back later } else if (SYS_STATUS_ERROR >= adcStatus) { // Handle error } 5.1.2.4.3.2 Client Core Functionality Core functionality provides a basic interface for the driver operation. Description General Client Operation Core functionality provides a basic interface for the driver operation. Applications using the timer core functionality, need to perform the following: 1. The system should have completed necessary initialization and DRV_ADC_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_ADC_Open (the timer driver supports exclusive access only). 3. Registers the inputs to be used by the clients using DRV_ADC_InputsRegister. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-196 4. Start the driver using DRV_ADC_Start. 5. Poll for the elapse status using DRV_ADC_SamplesAvailable, and then read the samples using either DRV_ADC_SamplesReadLatest or DRV_ADC_SamplesRead. 6. The client will be able to stop the started ADC instance using DRV_ADC_Stop at any point and will be able to close it using DRV_ADC_Close when it is no longer required. Example: DRV_HANDLE adcHandle; //Handle returned by DRV_ADC_Open function. uint16_t dataBuffer; //Buffer to which the data will be written. /* Open a new client. The handle returned by the this function should be used a passing parameter for all the specific client related operations. */ adcHandle = DRV_ADC_Open(MY_ADC_INSTANCE, DRV_IO_INTENT_NONBLOCKING); DRV_ADC_InputsRegister ( adcHandle ,PLIB_ADC_INPUT_AN1|PLIB_ADC_INPUT_AN2 ); /* ADC is not yet enabled. Enable it once the inputset is registered. Starts automatically since auto sample mode is enabled. */ DRV_ADC_Start(adcHandle); if ( DRV_ADC_SamplesAvailable(adcHandle) ) { DRV_ADC_SamplesReadLatest ( adcHandle, &dataBuffer, 1); /* Once the above function returns success, the data is in 'dataBuffer'. Application can use this data. */ } 5.1.2.4.3.3 Code Examples Example1 //PIC32/PIC24 in auto sampling , Polling mode #define MY_ADC_INSTANCE DRV_ADC_INDEX_0 DRV_HANDLE adcHandle; //Handle returned by DRV_ADC_Open function. uint16_t dataBuffer; //Buffer to which the data will be written. /* Open a new client. The handle returned by the this function should be used a passing parameter for all the specific client related operations. */ adcHandle = DRV_ADC_Open(MY_ADC_INSTANCE, DRV_IO_INTENT_NONBLOCKING); ipHandle = DRV_ADC_InputsRegister ( adcHandle ,inputSetConfig ); /* ADC is not yet enabled. Enable it once the inputset is registered. Starts automatically since auto sample mode is enabled. */ DRV_ADC_Start(adcHandle); while (DRV_ADC_SampleAvailable(adcHandle)) { DRV_ADC_InputSetRead ( adcHandle, &dataBuffer, 1); 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-197 /* Once the above function returns success, the data is in 'dataBuffer'. Application can use this data. */ } Example 2: //PIC32/PIC24 in Manual triggering , Polling mode #define MY_ADC_INSTANCE DRV_ADC_INDEX_0 int main() { SYS_MODULE_OBJ myAdcObj; //Object returned by DRV_ADC_Initialize function. DRV_ADC_INIT adcInitData; //Contains all the initialization values. DRV_HANDLE adcHandle; //Handle returned by DRV_ADC_Open function. DRV_ADC_INPUTSET_HANDLE ipHandle; //Handle returned by DRV_ADC_InputSetRegister function. DRV_ADC_INPUTSET_CONFIG inputSetConfig;//Contains all values to configure the inputset. uint16_t dataBuffer; //Buffer to which the data will be written. /* These initialization values should be based on the requirement of the application and the way it wants the hardware to be operating. Most of these values will be written directly to the hardware registers. */ adcInitData.plibModuleId = ADC_ID_1; adcInitData.acquisitionTime = PLIB_ADC_ACQUISITION_TIME_15_TAD; adcInitData.voltageReference = PLIB_ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; adcInitData.clockFrequency = 4000000; //4MHz adcInitData.conversionClock = PLIB_ADC_CONV_CLOCK_5_TCY; adcInitData.conversionClockSource = PLIB_ADC_CLOCK_SRC_INTERNAL_RC; adcInitData.conversionTriggerSource = PLIB_ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; adcInitData.dataOutputFormat = PLIB_ADC_OUTPUT_FORMAT_INTEGER_16BIT; adcInitData.interruptSource= PLIB_INT_SOURCE_ADC_1; adcInitData.samplesPerInterrupt = PLIB_ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; myAdcObj = DRV_ADC_Initialize(MY_ADC_INSTANCE, (SYS_MODULE_INIT*)&adcInitData); /* Open a new client. The handle returned by the this function should be used a passing parameter for all the specific client related operations. */ adcHandle = DRV_ADC_Open(MY_ADC_INSTANCE, DRV_IO_INTENT_NONBLOCKING); /* Driver invokes the registered callback function every successful data read. Application can perform an action or do a state change in the callback */ inputSetConfig.callback = adcCallback; inputSetConfig.input = POTENTIOMETER_ANALOG_INPUT; inputSetConfig.errorTolerance = 10; inputSetConfig.samplingFrequency = 40000; ipHandle = DRV_ADC_InputSetRegister ( adcHandle ,inputSetConfig ); /* ADC is not yet enabled. Enable it once the inputset is registered. Starts automatically since auto sample mode is enabled. */ DRV_ADC_Start(adcHandle); while (1) { /* 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-198 This function can be either called in a sequential way or it could be called from a timer periodically */ triggerAdc(); DRV_HANDLE handle; DRV_ADC_Tasks (myAdcObj); DRV_ADC_InputSetRead ( adcHandle, &dataBuffer, 1); /* Once the above function returns success, the data is in 'dataBuffer'. Application can use this data. */ } } void adcCallback (void) { // Application can do something here } void triggerAdc(void) { DRV_ADC_OperationSetup(handle, DRV_ADC_START_SAMPLING); /* Give some delay between the two operations. */ for (i=0; i<100; i++); DRV_ADC_OperationSetup(handle, DRV_ADC_START_CONVERSION); } Example 3: //PIC32/PIC24 in auto sampling , Interrupt mode #define MY_ADC_INSTANCE DRV_ADC_INDEX_0 int main() { SYS_MODULE_OBJ myAdcObj; //Object returned by DRV_ADC_Initialize function. DRV_ADC_INIT adcInitData; //Contains all the initialization values. DRV_HANDLE adcHandle; //Handle returned by DRV_ADC_Open function. DRV_ADC_INPUTSET_HANDLE ipHandle; //Handle returned by DRV_ADC_InputSetRegister function. DRV_ADC_INPUTSET_CONFIG inputSetConfig;//Contains all values to configure the inputset. uint16_t dataBuffer; //Buffer to which the data will be written. /* These initialization values should be based on the requirement of the application and the way it wants the hardware to be operating. Most of these values will be written directly to the hardware registers. */ adcInitData.plibModuleId = ADC_ID_1; adcInitData.acquisitionTime = PLIB_ADC_ACQUISITION_TIME_15_TAD; adcInitData.voltageReference = PLIB_ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; adcInitData.clockFrequency = 4000000; //4MHz adcInitData.conversionClock = PLIB_ADC_CONV_CLOCK_5_TCY; adcInitData.conversionClockSource = PLIB_ADC_CLOCK_SRC_INTERNAL_RC; adcInitData.conversionTriggerSource = PLIB_ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; adcInitData.dataOutputFormat = PLIB_ADC_OUTPUT_FORMAT_INTEGER_16BIT; adcInitData.initFlags = DRV_ADC_AUTO_SAMPLING; adcInitData.interruptSource= PLIB_INT_SOURCE_ADC_1; adcInitData.samplesPerInterrupt = PLIB_ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-199 myAdcObj = DRV_ADC_Initialize(MY_ADC_INSTANCE, (SYS_MODULE_INIT*)&adcInitData); /* Open a new client. The handle returned by the this function should be used a passing parameter for all the specific client related operations. */ adcHandle = DRV_ADC_Open(MY_ADC_INSTANCE, DRV_IO_INTENT_NONBLOCKING); /* Driver invokes the registered callback function every successful data read. Application can perform an action or do a state change in the callback */ inputSetConfig.callback = adcCallback; inputSetConfig.input = POTENTIOMETER_ANALOG_INPUT; inputSetConfig.errorTolerance = 10; inputSetConfig.samplingFrequency = 40000; ipHandle = DRV_ADC_InputSetRegister ( adcHandle ,inputSetConfig ); /* ADC is not yet enabled. Enable it once the inputset is registered. Starts automatically since auto sample mode is enabled. */ DRV_ADC_Start(adcHandle); while (1) { /* Task function need not be called. Task function is registered as ISR in case of interrpt mode */ DRV_ADC_InputSetRead ( adcHandle, &dataBuffer, 1); /* Once the above function returns success, the data is in 'dataBuffer'. Application can use this data. */ } } void adcCallback (void) { // Application can do something here } // Do something else... } while(total < MY_BUFFER_SIZE); Example 4: //PIC32/PIC24 in Manual triggering , Interrupt mode #define MY_ADC_INSTANCE DRV_ADC_INDEX_0 int main() { SYS_MODULE_OBJ myAdcObj; //Object returned by DRV_ADC_Initialize function. DRV_ADC_INIT adcInitData; //Contains all the initialization values. DRV_HANDLE adcHandle; //Handle returned by DRV_ADC_Open function. DRV_ADC_INPUTSET_HANDLE ipHandle; //Handle returned by DRV_ADC_InputSetRegister function. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-200 DRV_ADC_INPUTSET_CONFIG inputSetConfig;//Contains all values to configure the inputset. uint16_t dataBuffer; //Buffer to which the data will be written. /* These initialization values should be based on the requirement of the application and the way it wants the hardware to be operating. Most of these values will be written directly to the hardware registers. */ adcInitData.plibModuleId = ADC_ID_1; adcInitData.acquisitionTime = PLIB_ADC_ACQUISITION_TIME_15_TAD; adcInitData.voltageReference = PLIB_ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; adcInitData.clockFrequency = 4000000; //4MHz adcInitData.conversionClock = PLIB_ADC_CONV_CLOCK_5_TCY; adcInitData.conversionClockSource = PLIB_ADC_CLOCK_SRC_INTERNAL_RC; adcInitData.conversionTriggerSource = PLIB_ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; adcInitData.dataOutputFormat = PLIB_ADC_OUTPUT_FORMAT_INTEGER_16BIT; adcInitData.interruptSource= PLIB_INT_SOURCE_ADC_1; adcInitData.samplesPerInterrupt = PLIB_ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; myAdcObj = DRV_ADC_Initialize(MY_ADC_INSTANCE, (SYS_MODULE_INIT*)&adcInitData); /* Open a new client. The handle returned by the this function should be used a passing parameter for all the specific client related operations. */ adcHandle = DRV_ADC_Open(MY_ADC_INSTANCE, DRV_IO_INTENT_NONBLOCKING); /* Driver invokes the registered callback function every successful data read. Application can perform an action or do a state change in the callback */ inputSetConfig.callback = adcCallback; inputSetConfig.input = POTENTIOMETER_ANALOG_INPUT; inputSetConfig.errorTolerance = 10; inputSetConfig.samplingFrequency = 40000; ipHandle = DRV_ADC_InputSetRegister ( adcHandle ,inputSetConfig ); /* ADC is not yet enabled. Enable it once the inputset is registered. Starts automatically since auto sample mode is enabled. */ DRV_ADC_Start(adcHandle); while (1) { /* This function can be either called in a sequential way or it could be called from a timer periodically */ triggerAdc(); /* Task function need not be called. Task function is registered as ISR in case of interrpt mode */ DRV_ADC_InputSetRead ( adcHandle, &dataBuffer, 1); /* Once the above function returns success, the data is in 'dataBuffer'. Application can use this data. */ } 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-201 } void adcCallback (void) { // Application can do something here } void triggerAdc(void) { DRV_ADC_OperationSetup(handle, DRV_ADC_START_SAMPLING); /* Give some delay between the two operations. */ for (i=0; i<100; i++); DRV_ADC_OperationSetup(handle, DRV_ADC_START_CONVERSION); } 5.1.2.5 Configuring the Library The configuration of the ADC device driver is based on the file sys_config.h This header file contains the configuration selection for the ADC device driver build. Based on the selections made here and the system setup the ADC device driver will support or not selected features. These configuration settings will apply to all instances of the device driver. This header can be placed anywhere in the application specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Overview section for more details. 5.1.2.6 Building the Library Files Name Description drv_adc.c ADC Driver source file. drv_adc_client_multi.c ADC Driver multiple client implementations. drv_adc_client_single.c ADC Driver single client implementations. drv_adc_hw_dynamic.c ADC Driver build variant implementation for the dynamic driver. drv_adc_hw_static.c ADC Driver build variant implementation for the static driver. Description 5.1.2.6.1 drv_adc.c ADC Driver Source File This file implements the ADC Driver Interface routines. While building the driver from source, ALWAYS use this file in the build. File Name drv_adc.c Company Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-202 5.1.2.6.2 drv_adc_client_multi.c ADC Driver Multiple Client This file implements the functions for the multiple client support. While building the driver from source, use this file in the build when DRV_ADC_CLIENTS_NUMBER is defined in the system configuration or when DRV_ADC_INSTANCES_NUMBER is defined in the system configuration. File Name drv_adc_client_multi.c Company Microchip Technology Inc. 5.1.2.6.3 drv_adc_client_single.c ADC Driver Single Client This file implements the functions for the single client support While building the driver from source, use this file in the build when DRV_ADC_CLIENTS_NUMBER is not defined in system configuration. File Name drv_adc_client_single.c Company Microchip Technology Inc. 5.1.2.6.4 drv_adc_hw_dynamic.c ADC Driver Build Variant implementation for dynamic driver This file defines the build variant implementations for the dynamic driver. While building the driver from source, use this file in the build when DRV_ADC_INSTANCES_NUMBER is defined in the system configuration. File Name drv_adc_hw_dynamic.c Company Microchip Technology Inc. 5.1.2.6.5 drv_adc_hw_static.c ADC Driver build variant implementation for static driver This file defines the build variant implementations for the static driver. While building the driver from source, use this file in the build when DRV_ADC_INSTANCES_NUMBER is not defined in the system configuration. File Name drv_adc_hw_static.c Company Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-203 5.1.2.7 Library Interface Data Types and Constants Name Description DRV_ADC_CLIENT_STATUS Defines the client-specific status of the ADC driver. DRV_ADC_INIT Defines the data required to initialize or reinitialize the ADC driver. DRV_ADC_INIT_FLAGS Identifies the initialization flags of the ADC module. DRV_ADC_ACQUISITION_TIME Defines the acquisition time. DRV_ADC_ALTERNATE_INPUT_SAMPLING_ENABLE Enable the alternate input sampling feature of the ADC. DRV_ADC_ANALOG_INPUT Defines the analog input channel. DRV_ADC_AUTO_SAMPLING_ENABLE Rnable the suto-sampling feature of the ADC. DRV_ADC_CLIENTS_NUMBER Selects the miximum number of clients. DRV_ADC_CONVERSION_CLOCK_PRESCALER Defines the conversion clock. DRV_ADC_CONVERSION_CLOCK_SOURCE Defines the conversion clock source. DRV_ADC_CONVERSION_TRIGGER_SOURCE Defines the conversion trigger source. DRV_ADC_INDEX ADC static index selection. DRV_ADC_INDEX_0 ADC driver index definitions. DRV_ADC_INDEX_1 This is macro DRV_ADC_INDEX_1. DRV_ADC_INDEX_2 This is macro DRV_ADC_INDEX_2. DRV_ADC_INDEX_COUNT Number of valid ADC driver indices. DRV_ADC_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_ADC_INTERNAL_BUFFER_SIZE Define the internal buffer size. DRV_ADC_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ADC_INTERRUPT_SOURCE Defines the interrupt source of the static driver. DRV_ADC_PERIPHERAL_ID ADC PLIB ID Selection DRV_ADC_POWER_STATE Controls the power state of the ADC. DRV_ADC_RESULT_FORMAT Defines the data output format. DRV_ADC_SAMPLES_PER_INTERRUPT Define the sample per interrupt. DRV_ADC_STOP_ON_CONVERSION_ENABLE Enable the stop on conversion feature of the ADC. DRV_ADC_VOLTAGE_REFERENCE Defines the voltage reference. Client Core Configuration Functions Name Description DRV_ADC_ClientStatus Gets the current client-specific status the ADC driver. DRV_ADC_Close Closes an opened-instance of the ADC driver. DRV_ADC_InputsRegister Registers an input set with the driver for sampling. DRV_ADC_Open Opens the specified ADC driver instance and returns a handle to it. DRV_ADC_SamplesAvailable Identifies if any the ADC driver has any samples available to read. DRV_ADC_Start Starts the ADC driver sampling and converting analog to digital values. DRV_ADC_Stop Stops the ADC driver from sampling and converting analog to digital values. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-204 Other Functions Name Description DRV_ADC_SampleMaxGet Gets the max sample value. DRV_ADC_SampleMinGet Gets the min sample value. DRV_ADC_SamplesRead Reads the converted sample data from the ADC driver. DRV_ADC_SamplesReadLatest Reads the most recently converted sample data from the ADC driver. System Interaction Functions Name Description DRV_ADC_Deinitialize Deinitializes the specified instance of the ADC driver module. DRV_ADC_Initialize Initializes the ADC driver. DRV_ADC_Reinitialize Reinitializes the ADC instance for the specified module ID. DRV_ADC_Status Provides the current status of the ADC driver module. DRV_ADC_Tasks Maintains the driver's state machine and implements its ISR. Description 5.1.2.7.1 System Interaction Functions 5.1.2.7.1.1 DRV_ADC_Deinitialize Function C void DRV_ADC_Deinitialize( SYS_MODULE_OBJ object ); Description This function deinitializes the specified instance of the ADC driver module, disabling its operation (and any hardware). Invalidates all the internal data. Preconditions The DRV_ADC_Initialize function should have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from DRV_ADC_Initialize Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_ADC_Status operation. The system has to use DRV_ADC_Status to find out when the module is in the ready state. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-205 Example SYS_MODULE_OBJ object; // Returned from DRV_ADC_Initialize SYS_STATUS status; DRV_ADC_Deinitialize(object); status = DRV_ADC_Status(object); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.2.7.1.2 DRV_ADC_Initialize Function C SYS_MODULE_OBJ DRV_ADC_Initialize( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ); Description This function initializes the ADC driver, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Remarks This function must be called before any other ADC function is called. This function should only be called once during system initialization unless DRV_ADC_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_ADC_Status operation. The system must use DRV_ADC_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this function. Example DRV_ADC_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the init structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.adcID = ADC_ID_1; 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-206 init.initFlags = DRV_ADC_AUTO_SAMPLING; init.clockFrequency = 4000000; // 4MHz init.acquisitionTime = ADC_ACQUISITION_TIME_15_TAD; init.voltageReference = ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; init.conversionClockPrescaler = ADC_CONV_CLOCK_5_TCY; init.conversionClockSource = ADC_CLOCK_SRC_INTERNAL_RC; init.conversionTriggerSource = ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; init.samplesPerInterrupt = ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; init.resultFormat = ADC_RESULT_FORMAT_INTEGER_16BIT; init.analogInput = ADC_INPUT_AN2 init.interruptSource = INT_SOURCE_ADC_1; // Initialize the ADC driver objectHandle = DRV_ADC_Initialize(DRV_ADC_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.1.2.7.1.3 DRV_ADC_Reinitialize Function C void DRV_ADC_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); Description This function reinitializes and refreshes the hardware for the index instance of the ADC module using the hardware initialization given data. It does not clear or reinitialize internal data structures (although it may change the value of a few appropriate data items necessary to manage the new hardware state). Preconditions The DRV_ADC_Initialize function should have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from the DRV_ADC_Initialize Returns None. Example DRV_ADC_INIT init; SYS_MODULE_OBJ objectHandle; // Returned from DRV_ADC_Initialize SYS_STATUS adcStatus; // Populate the init structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.adcID = ADC_ID_1; init.initFlags = DRV_ADC_AUTO_SAMPLING; init.clockFrequency = 4000000; // 4MHz init.acquisitionTime = ADC_ACQUISITION_TIME_15_TAD; init.voltageReference = ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS; init.conversionClockPrescaler = ADC_CONV_CLOCK_5_TCY; init.conversionClockSource = ADC_CLOCK_SRC_INTERNAL_RC; init.conversionTriggerSource = ADC_CONVERSION_TRIGGER_INTERNAL_COUNT; init.samplesPerInterrupt = ADC_SAMPLE_PER_INTERRUPT_AT_EACH_SAMPLE; init.resultFormat = ADC_RESULT_FORMAT_INTEGER_16BIT; init.analogInput = ADC_INPUT_AN2 init.interruptSource = INT_SOURCE_ADC_1; 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-207 // Reinitialize the ADC driver DRV_ADC_Reinitialize(objectHandle, (SYS_MODULE_INIT*)&init); // Check the status of the driver adcStatus = DRV_ADC_Status(myAdcObj); if (SYS_STATUS_BUSY == adcStatus) { // do something else and check back later } else if (SYS_STATUS_ERROR >= adcStatus) { // Handle error } Remarks: This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_ADC_Status operation. The system must use DRV_ADC_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this function. 5.1.2.7.1.4 DRV_ADC_Status Function C SYS_STATUS DRV_ADC_Status( SYS_MODULE_OBJ object ); Description This function provides the current status of the ADC driver module. Preconditions The DRV_ADC_Initialize function must have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from the DRV_ADC_Initialize Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-208 The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize SYS_STATUS status; status = DRV_ADC_Status(object); else if (SYS_STATUS_ERROR >= status) { // Handle error } 5.1.2.7.1.5 DRV_ADC_Tasks Function C void DRV_ADC_Tasks( SYS_MODULE_OBJ object ); Description This function is used to maintain the driver's internal state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_ADC_Initialize function must have been called for the specified ADC driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_ADC_Initialize) Returns None Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks) or by the apropriate raw ISR. This function may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_ADC_Initialize while (true) { DRV_ADC_Tasks (object); // Do other tasks } 5.1.2.7.2 Client Core Configuration Functions 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-209 5.1.2.7.2.1 DRV_ADC_ClientStatus Function C DRV_ADC_CLIENT_STATUS DRV_ADC_ClientStatus( DRV_HANDLE handle ); Description This function gets the client-specfic status of the ADC driver associated with the given handle. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns A DRV_ADC_CLIENT_STATUS value describing the current status of the driver. Remarks This function will not block for hardware access and will immediately return the current status. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open DRV_ADC_CLIENT_STATUS status; status = DRV_ADC_ClientStatus(handle); if(DRV_ADC_CLIENT_STATUS_ERROR >= status) { // Handle the error } 5.1.2.7.2.2 DRV_ADC_Close Function C void DRV_ADC_Close( DRV_HANDLE handle ); Description This function closes an opened-instance of the ADC driver, invalidating the handle. Preconditions The DRV_ADC_Initialize function must have been called for the specified ADC driver instance. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns None 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-210 Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver functions. A new handle must be obtained by calling DRV_ADC_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_ADC_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open DRV_ADC_Close(handle); 5.1.2.7.2.3 DRV_ADC_InputsRegister Function C void DRV_ADC_InputsRegister( DRV_HANDLE handle, uint32_t inputsMask ); Description This function registers an input set with the driver for sampling. Preconditions The DRV_ADC_Initialize function must have been called for the specified ADC device instance and the DRV_ADC_Status must have returned SYS_STATUS_READY. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function inputsMask Mask bits recognising the various Analog Channels Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open DRV_ADC_InputsRegister (handle, ADC_INPUT_AN2|ADC_INPUT_AN3); 5.1.2.7.2.4 DRV_ADC_Open Function C DRV_HANDLE DRV_ADC_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-211 Description This function opens the specified ADC driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions The DRV_ADC_Initialize function must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_ADC_Close function is called. This function will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_ADC_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. Example DRV_HANDLE handle; handle = DRV_ADC_Open(DRV_ADC_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.2.7.2.5 DRV_ADC_SamplesAvailable Function C bool DRV_ADC_SamplesAvailable( DRV_HANDLE handle ); Description This function identifies if any the ADC driver has any samples available to read. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. The desired analog input set must have been selected by calling DRV_ADC_InputsRegister. DRV_ADC_Start must have been called to start the driver sampling and converting analog input samples to digital values. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-212 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns • true - If one or more samples are available for the registered input set • false - If no samples are available Remarks None. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open DRV_ADC_SAMPLE buffer; // An input set must have been registered and the ADC started. if (DRV_ADC_SamplesAvailable(handle)) { DRV_ADC_SamplesRead(handle, &buffer, sizeof(buffer)); } 5.1.2.7.2.6 DRV_ADC_Start Function C void DRV_ADC_Start( DRV_HANDLE handle ); Description This function starts the ADC driver sampling the selected analog inputs and converting the samples to digital values. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. The desired analog input set must have been selected by calling DRV_ADC_InputsRegister. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns None. Remarks Call DRV_ADC_SamplesAvailable to find out when one or more samples is available. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open // Use DRV_ADC_InputsRegister to register the desired inputs. DRV_ADC_Start(handle); 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-213 5.1.2.7.2.7 DRV_ADC_Stop Function C void DRV_ADC_Stop( DRV_HANDLE handle ); Description This function stops the ADC driver from sampling analog inputs and converting the samples to digital values. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns None. Remarks Call DRV_ADC_Start to restart sampling and conversion of analog inputs to digital values. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open DRV_ADC_Stop(handle); 5.1.2.7.3 Other Functions 5.1.2.7.3.1 DRV_ADC_SampleMaxGet Function C ADC_SAMPLE DRV_ADC_SampleMaxGet( DRV_HANDLE handle ); Description This function returns the max sample value. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns Max sample value. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-214 Remarks None Example DRV_HANDLE handle; // Returned from DRV_ADC_Open ADC_SAMPLE maxValue, minValue; maxValue = DRV_ADC_SampleMaxGet(handle); minValue = DRV_ADC_SampleMinGet(handle); adcRange = maxValue - minValue; 5.1.2.7.3.2 DRV_ADC_SampleMinGet Function C ADC_SAMPLE DRV_ADC_SampleMinGet( DRV_HANDLE handle ); Description This function returns the min sample value. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Returns Min sample value. Remarks None Example DRV_HANDLE handle; // Returned from DRV_ADC_Open ADC_SAMPLE maxValue, minValue; maxValue = DRV_ADC_SampleMaxGet(handle); minValue = DRV_ADC_SampleMinGet(handle); adcRange = maxValue - minValue; 5.1.2.7.3.3 DRV_ADC_SamplesRead Function C unsigned short DRV_ADC_SamplesRead( DRV_HANDLE handle, ADC_SAMPLE * buffer, unsigned short bufferSize ); Description This function reads converted sample data from the ADC driver into the given buffer. How many samples depends on how many samples are available and on the relative sizes of the samples and the buffer passed in. Zero (0) samples are copied if the bufferSize is less than the size of a complete set of samples for the registered inputs. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-215 N sets of samples where the bufferSize / size of a complete set of samples = N, unless less than N samples are currently available. Then, the number of samples currently available are copied. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. The desired analog input set must have been selected by calling DRV_ADC_InputsRegister. DRV_ADC_Start must have been called to start the driver sampling and converting analog input samples to digital values. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function buffer A pointer to the buffer to where the sample data will be copied bufferSize Size of the buffer (in bytes) Returns Number of bytes of sample data copied to the specified buffer. Remarks The DRV_ADC_SamplesAvailable function can be used to determine if any sample data is available. Calling this function removes the samples from the driver's internal buffer queue of samples. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open ADC_SAMPLE buffer; // An input set must have been registered and the ADC started. if (DRV_ADC_SamplesAvailable(handle)) { DRV_ADC_SamplesRead(handle, &buffer, sizeof(buffer)); } 5.1.2.7.3.4 DRV_ADC_SamplesReadLatest Function C unsigned short DRV_ADC_SamplesReadLatest( DRV_HANDLE handle, ADC_SAMPLE * buffer, unsigned short bufferSize ); Description This function reads only the most recenly converted sample data from the ADC driver into the given buffer. Only the data for a single set of samples for the registerd inputs is copied to the caller's buffer. If the buffer size is less than the size of a complete set of samples for the registerd inputs, no data is copied to the caller's buffer. Also, no sample data is copied to the caller's buffer if no sample data is currently available. Preconditions The DRV_ADC_Initialize function must have been called. DRV_ADC_Open must have been called to obtain a valid opened device handle. The desired analog input set must have been selected by calling DRV_ADC_InputsRegister. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-216 DRV_ADC_Start must have been called to start the driver sampling and converting analog input samples to digital values. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function buffer A pointer to the buffer to where the sample data will be copied bufferSize Size of the buffer (in bytes) Returns Number of bytes of sample data copied to the specified buffer. Remarks The DRV_ADC_SamplesAvailable function can be used to determine if any sample data is available. This function does not remove any data from the driver's internal buffer queue of sample data. Example DRV_HANDLE handle; // Returned from DRV_ADC_Open ADC_SAMPLE buffer; // An input set must have been registered and the ADC started. if (DRV_ADC_SamplesAvailable(handle)) { DRV_ADC_SamplesReadLatest(handle, &buffer, sizeof(buffer)); } 5.1.2.7.4 Data Types and Constants 5.1.2.7.4.1 DRV_ADC_CLIENT_STATUS Enumeration C typedef enum { DRV_ADC_CLIENT_STATUS_STARTED, DRV_ADC_CLIENT_STATUS_STOPPED, DRV_ADC_CLIENT_STATUS_READY, DRV_ADC_CLIENT_STATUS_BUSY, DRV_ADC_CLIENT_STATUS_INVALID, DRV_ADC_CLIENT_STATUS_OVERFLOW, DRV_ADC_CLIENT_STATUS_BUFFER_TOO_SMALL } DRV_ADC_CLIENT_STATUS; Description ADC Client Status This enumeration defines the client-specific status codes of the ADC driver. Members Members Description DRV_ADC_CLIENT_STATUS_STARTED ADC Started DRV_ADC_CLIENT_STATUS_STOPPED stopped on error DRV_ADC_CLIENT_STATUS_READY Driver OK, ready for client operations DRV_ADC_CLIENT_STATUS_BUSY An operation is currently in progress DRV_ADC_CLIENT_STATUS_INVALID Client in an invalid (or un-opened) state DRV_ADC_CLIENT_STATUS_OVERFLOW Driver Overflowed 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-217 DRV_ADC_CLIENT_STATUS_BUFFER_TOO_SMALL Input Set Read Buffer Too Small Remarks Returned by the DRV_ADC_ClientStatus function. 5.1.2.7.4.2 DRV_ADC_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; ADC_MODULE_ID adcId; DRV_ADC_INIT_FLAGS initFlags; uint32_t clockFrequency; ADC_ACQUISITION_TIME acquisitionTime; ADC_VOLTAGE_REFERENCE voltageReference; ADC_CONVERSION_CLOCK conversionClockPrescaler; ADC_CLOCK_SOURCE conversionClockSource; ADC_CONVERSION_TRIGGER_SOURCE conversionTriggerSource; ADC_SAMPLES_PER_INTERRUPT samplesPerInterrupt; ADC_RESULT_FORMAT resultFormat; ADC_INPUTS_POSITIVE analogInput; INT_SOURCE interruptSource; } DRV_ADC_INIT; Description ADC Driver Initialization Data This structure defines the data required to initialize or reinitialize the ADC driver. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization ADC_MODULE_ID adcId; Identifies timer hardware module (PLIB-level) ID DRV_ADC_INIT_FLAGS initFlags; Initialization Flags uint32_t clockFrequency; Clock Frequency ADC_ACQUISITION_TIME acquisitionTime; Acquisition Time ADC_VOLTAGE_REFERENCE voltageReference; Voltage Reference Selection ADC_CONVERSION_CLOCK conversionClockPrescaler; Clock Setup for the Conversion ADC_CLOCK_SOURCE conversionClockSource; Clock Source for Conversion ADC_CONVERSION_TRIGGER_SOURCE conversionTriggerSource; Conversion Trigger Source ADC_SAMPLES_PER_INTERRUPT samplesPerInterrupt; Samples Per Interrupt valid values = 0- 15 ADC_RESULT_FORMAT resultFormat; Result Format ADC_INPUTS_POSITIVE analogInput; Input Channel to convert INT_SOURCE interruptSource; Interrupt Source for the module Remarks Not all init features are available for all devices. Refer to the specific data sheet to determine availability. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-218 5.1.2.7.4.3 DRV_ADC_INIT_FLAGS Enumeration C typedef enum { DRV_ADC_STOP_CONVERSION_ON_INTERRUPT, DRV_ADC_ALTERNATE_INPUT_SAMPLING, DRV_ADC_AUTO_SAMPLING, DRV_ADC_MANUAL_SAMPLING } DRV_ADC_INIT_FLAGS; Description ADC Initialization Flags This data type identifies the initialization flags of the ADC module. Members Members Description DRV_ADC_STOP_CONVERSION_ON_INTERRUPT Stops the conversion on the interrupt DRV_ADC_ALTERNATE_INPUT_SAMPLING Alternate Input Sampling DRV_ADC_AUTO_SAMPLING Begin sampling automaticaly after previous conversion DRV_ADC_MANUAL_SAMPLING Manual Sampling Remarks Not all modes are available on all devices. Refer to the specific data sheet to determine availability. 5.1.2.7.4.4 DRV_ADC_ACQUISITION_TIME Macro C #define DRV_ADC_ACQUISITION_TIME ADC_ACQUISITION_TIME_4_TAD Description ADC Acquisition Time This macro defines the acquistition time of the ADC driver. This provides static override of the dynamic selection of the acquisition time. If this macro is defined, this will be used for setting up the acquisition time and not the acquisition time value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.5 DRV_ADC_ALTERNATE_INPUT_SAMPLING_ENABLE Macro C #define DRV_ADC_ALTERNATE_INPUT_SAMPLING_ENABLE false Description ADC Alternate Input Sampling Enable This macro enables the alternate input sampling feature of the ADC. This macro can take the following values: • true - Enables the alternate Input sampling feature of the ADC • false - Disables the alternate Input sampling feature of the ADC • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-219 Remarks None. 5.1.2.7.4.6 DRV_ADC_ANALOG_INPUT Macro C #define DRV_ADC_ANALOG_INPUT ADC_INPUT_AN2 Description ADC Analog input channel This macro defines the analog input channel for the ADC driver. This provides static override of the dynamic selection of the analog input. If this macro is defined, this will be used for setting up the analog input and not the analog input value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.7 DRV_ADC_AUTO_SAMPLING_ENABLE Macro C #define DRV_ADC_AUTO_SAMPLING_ENABLE true Description ADC Auto Sampling Enable This macro enables the auto-sampling feature of the ADC. This macro can take the following values: • true - Enables the auto-sampling feature of the ADC • false - Disables the auto-sampling feature of the ADC • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance Remarks None. 5.1.2.7.4.8 DRV_ADC_CLIENTS_NUMBER Macro C #define DRV_ADC_CLIENTS_NUMBER 1 Description ADC Maximum Number of Clients This definition selectd the maximum number of clients that the ADC driver can support at run time. Remarks None. 5.1.2.7.4.9 DRV_ADC_CONVERSION_CLOCK_PRESCALER Macro C #define DRV_ADC_CONVERSION_CLOCK_PRESCALER ADC_CONV_CLOCK_4_TCY 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-220 Description ADC Conversion Clock This macro defines the conversion clock for the ADC driver. This provides static override of the dynamic selection of the conversion clock. If this macro is defined, this will be used for setting up the conversion clock and not the conversion clock value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.10 DRV_ADC_CONVERSION_CLOCK_SOURCE Macro C #define DRV_ADC_CONVERSION_CLOCK_SOURCE ADC_CLOCK_SRC_SYSTEM_CLOCK Description ADC Conversion Clock Source This macro defines the conversion clock source for the ADC driver. This provides static override of the dynamic selection of the conversion clock source. If this macro is defined, this will be used for setting up the conversion clock source and not the conversion clock source value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.11 DRV_ADC_CONVERSION_TRIGGER_SOURCE Macro C #define DRV_ADC_CONVERSION_TRIGGER_SOURCE ADC_CONVERSION_TRIGGER_INTERNAL_COUNT Description Conversion Trigger Source This macro defines the conversion trigger source for the ADC driver. This provides static override of the dynamic selection of the conversion trigger source. If this macro is defined, this will be used for setting up the conversion trigger source and not the conversion trigger source value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.12 DRV_ADC_INDEX Macro C #define DRV_ADC_INDEX DRV_ADC_INDEX_0 Description ADC Static Index Selection ADC static index selection for the driver object reference. Remarks This index is required to make a reference to the driver object. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-221 5.1.2.7.4.13 DRV_ADC_INDEX_0 Macro C #define DRV_ADC_INDEX_0 0 Description Driver ADC Module Index Numbers These constants provide ADC driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_ADC_Initialize function to identify the driver instance in use. 5.1.2.7.4.14 DRV_ADC_INDEX_1 Macro C #define DRV_ADC_INDEX_1 1 Description This is macro DRV_ADC_INDEX_1. 5.1.2.7.4.15 DRV_ADC_INDEX_2 Macro C #define DRV_ADC_INDEX_2 2 Description This is macro DRV_ADC_INDEX_2. 5.1.2.7.4.16 DRV_ADC_INDEX_COUNT Macro C #define DRV_ADC_INDEX_COUNT _ADC_EXISTS Description Driver ADC Driver Module Index Count This constant identifies ADC driver index definitions. Remarks This constant should be used in place of hard-coded numeric literals. This value is device-specific. 5.1.2.7.4.17 DRV_ADC_INSTANCES_NUMBER Macro C #define DRV_ADC_INSTANCES_NUMBER 1 Description ADC hardware instance configuration This macro sets up the maximum number of hardware instances that can be supported. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-222 Remarks None. 5.1.2.7.4.18 DRV_ADC_INTERNAL_BUFFER_SIZE Macro C #define DRV_ADC_INTERNAL_BUFFER_SIZE 2 Description ADC Internal buffer size This macro defines the internal buffer size. Remarks None. 5.1.2.7.4.19 DRV_ADC_INTERRUPT_MODE Macro C #define DRV_ADC_INTERRUPT_MODE true Description ADC Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of adc operation is desired • false - Select if polling mode of adc operation is desired Not defining this option to true or false will result in a build error. Remarks None. 5.1.2.7.4.20 DRV_ADC_INTERRUPT_SOURCE Macro C #define DRV_ADC_INTERRUPT_SOURCE PLIB_INT_SOURCE_ADC_1 Description ADC Interrupt Source Macro to define the interrupt source of the static driver. Remarks Refer to the Interrupt Peripheral Library document for more information on the PLIB_INT_SOURCE enumeration. 5.1.2.7.4.21 DRV_ADC_PERIPHERAL_ID Macro C #define DRV_ADC_PERIPHERAL_ID ADC_ID_1 Description ADC PLIB ID Selection 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-223 This macro selects the ADC PLIB ID Selection. This is an intialization override of the adcID member of the intialization configuration. Remarks None. 5.1.2.7.4.22 DRV_ADC_POWER_STATE Macro C #define DRV_ADC_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description ADC power state configuration This macro controls the power state of the ADC. Remarks This feature may not be available in the device or the ADC module selected. 5.1.2.7.4.23 DRV_ADC_RESULT_FORMAT Macro C #define DRV_ADC_RESULT_FORMAT ADC_RESULT_FORMAT_INTEGER_16BIT Description ADC Data Output Format This macro defines the data output format for the ADC driver. This provides static override of the dynamic selection of the data output format. If this macro is defined, this will be used for setting up the data output format and not the data output format value provided by DRV_ADC_INIT. Remarks None. 5.1.2.7.4.24 DRV_ADC_SAMPLES_PER_INTERRUPT Macro C #define DRV_ADC_SAMPLES_PER_INTERRUPT 2 Description Samples per Interrupt This macro defines the samples per interrupt of the ADC driver. This provides static override of the dynamic selection of the sample per interrupt. If this macro is defined, this will be used for setting up the samples per interrupt and not the samples per interrupt value provided by DRV_ADC_INIT. Remarks Select this size based on the device available and the number of samples that are required to form a set. 5.1.2.7.4.25 DRV_ADC_STOP_ON_CONVERSION_ENABLE Macro C #define DRV_ADC_STOP_ON_CONVERSION_ENABLE false 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-224 Description ADC Stop on conversion Enable This macro enables the stop on conversion feature of the ADC. This macro can take the following values: • true - Enables the ADC to stop on conversion • false - Disables the ADC to stop on conversion • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance Remarks None. 5.1.2.7.4.26 DRV_ADC_VOLTAGE_REFERENCE Macro C #define DRV_ADC_VOLTAGE_REFERENCE ADC_VREF_POS_TO_VDD_VREF_NEG_TO_VSS Description ADC Voltage Reference This macro defines the voltage reference of the ADC driver. This provides static override of the dynamic selection of the voltage reference. If this macro is defined, this will be used for setting up the voltage reference and not the voltage reference value provided by DRV_ADC_INIT. Remarks None. 5.1.2.8 Files Files Name Description drv_adc.h ADC Driver interface definition. Description 5.1.2.8.1 drv_adc.h ADC Driver Interface Definition The ADC device driver provides a simple interface to manage the ADC modules on Microchip microcontrollers. This file defines the interface definition for the ADC driver. Enumerations Name Description DRV_ADC_CLIENT_STATUS Defines the client-specific status of the ADC driver. DRV_ADC_INIT_FLAGS Identifies the initialization flags of the ADC module. 5.1 Driver Library Help MPLAB Harmony Help ADC Driver Library 5-225 Functions Name Description DRV_ADC_ClientStatus Gets the current client-specific status the ADC driver. DRV_ADC_Close Closes an opened-instance of the ADC driver. DRV_ADC_Deinitialize Deinitializes the specified instance of the ADC driver module. DRV_ADC_Initialize Initializes the ADC driver. DRV_ADC_InputsRegister Registers an input set with the driver for sampling. DRV_ADC_Open Opens the specified ADC driver instance and returns a handle to it. DRV_ADC_Reinitialize Reinitializes the ADC instance for the specified module ID. DRV_ADC_SampleMaxGet Gets the max sample value. DRV_ADC_SampleMinGet Gets the min sample value. DRV_ADC_SamplesAvailable Identifies if any the ADC driver has any samples available to read. DRV_ADC_SamplesRead Reads the converted sample data from the ADC driver. DRV_ADC_SamplesReadLatest Reads the most recently converted sample data from the ADC driver. DRV_ADC_Start Starts the ADC driver sampling and converting analog to digital values. DRV_ADC_Status Provides the current status of the ADC driver module. DRV_ADC_Stop Stops the ADC driver from sampling and converting analog to digital values. DRV_ADC_Tasks Maintains the driver's state machine and implements its ISR. Macros Name Description DRV_ADC_INDEX_0 ADC driver index definitions. DRV_ADC_INDEX_1 This is macro DRV_ADC_INDEX_1. DRV_ADC_INDEX_2 This is macro DRV_ADC_INDEX_2. DRV_ADC_INDEX_COUNT Number of valid ADC driver indices. Structures Name Description DRV_ADC_INIT Defines the data required to initialize or reinitialize the ADC driver. File Name drv_adc.h Company Microchip Technology Inc. 5.1.3 Ethernet MAC Driver Library 5.1.3.1 Introduction Ethernet (Media Access) Controller Driver Library for 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-226 Microchip Microcontrollers This library provides a driver-level abstraction of the on-chip Ethernet Controller found on many PIC32 devices. The "Host-To-Network" layer of a TCP/IP stack organization covers the Data Link and Physical Layers of the standard OSI stack. The Ethernet Controller provides the Data Link or Media Access Control Layer, in addition to other functions discussed below. An external Ethernet "PHY" provides the Physical layer, providing conversion between the digital and analog. Description The PIC32 Ethernet Controller is a bus master module that interfaces with an off-chip PHY in order to implement a complete Ethernet node in a system. The following are some of the key features of this module: • Supports 10/100 Ethernet • Full-Duplex and Half-Duplex operation • Broadcast, Multicast and Unicast packets • Manual and automatic flow control • Supports Auto-MDIX enabled PHYs • Reduced Media Independent Interface (RMII) and Media Independent Interface (MII) PHY data interfaces • Performance statistics metrics in hardware. • RAM descriptor based DMA operation for both receive and transmit path • Fully configurable interrupts • Configurable receive packet filtering using: • 64-bit Hash Table • 64-byte Pattern Match • Magic Packet™Filtering • Runt Packet Detection and Filtering • Supports Packet Payload Checksum calculation • CRC Check Support for the Serial Management Interface (SMI) (also known as the MIIM interface) is provided by the Ethernet PHY Driver Library. 5.1.3.2 Release Notes MPLAB Harmony Version: v0.70b Ethernet MAC Library Version : 7.10 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-227 licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.3.4 Using the Library This topic describes the basic architecture of the Ethernet MAC Driver Library and provides information and examples on how to use it. Interface Header File: drv_ethmac.h The interface to the Ethernet MAC library is defined in the "drv_ethmac.h" header file. This file is included by the "drv_ethmac.h" file. Any C language source (.c) file that uses the Ethernet MAC Driver Library should include "drv.h". Library File: The Ethernet MAC Driver Library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.1.3.4.1 Abstraction Model The Ethernet Controller provides the modules needed to implement a 10/100 Mbps Ethernet node using an external Ethernet PHY chip. The PHY chip provides a digital-analog interface as part of the Physical Layer and the controller provides the Media Access Controller (MAC) layer above the PHY. As shown in Figure 1, the Ethernet Controller consists of the following modules: • Media Access Control (MAC) block: Responsible for implementing the MAC functions of the Ethernet IEEE 802.3 Specification • Flow Control (FC) block: Responsible for control of the transmission of PAUSE frames. (Reception of PAUSE frames is handled within the MAC.) • RX Filter (RXF) block: This module performs filtering on every receive packet to determine whether each packet should be accepted or rejected • TX DMA/TX Buffer Management Engine: The TX DMA and TX Buffer Management engines perform data transfers from the memory (using descriptor tables) to the MAC Transmit Interface • RX DMA/RX Buffer Management Engine: The RX DMA and RX Buffer Management engines transfer receive packets from the MAC to the memory (using descriptor tables) 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-228 Figure 1: Ethernet Controller Block Diagram For completeness, we also need to look at the interface diagram of a representative Ethernet PHY. As shown in Figure 2, the PHY has two interfaces, one for configuring and managing the PHY (SMI/MIIM) and another for transmit and receive data (RMII or MII). The SMI/MIIM interface is the responsibility of the Ethernet PHY Driver Library. When setting up the Ethernet PHY this library calls primitives from the Ethernet PHY Driver library. The RMII/MII interface is the responsibility of the Ethernet MAC Driver Library (this library). 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-229 Figure 2: Ethernet PHY Interfaces 5.1.3.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Ethernet MAC Driver Library. Library Interface Section Description Client Level Functions PIC32MACOpen, PIC32MACClose, and PIC32MACSetup to support the TCP/IP Stack. Plus link status and power options. Get and Put Functions Get/Put functions for bytes, byte arrays, and Ethernet headers. Base Address and Buffer Size Functions Base address and sizes for buffers. Receive Functions Receive routines. Transmit Functions Transmit routines. Events Ethernet event support routines. Other Functions Checksum support, memory copying, version support. Data Types and Constants Typedefs and #defines. 5.1.3.4.3 MPLAB Harmony vs. Unified Stack Functions The following is a cross-reference linking MPLAB Harmony functions with functions from the legacy TCP/IP Stack: 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-230 MPLAB Harmony Function: MCHP_tcpip_unified Function: DRV_ETHMAC_BaseAddrTxGet DRV_ETHMAC_RxPacketDiscard DRV_ETHMAC_EventAck DRV_ETHMAC_EventDeInit DRV_ETHMAC_EventInit DRV_ETHMAC_EventNotifyClear DRV_ETHMAC_EventNotifyHandlerSet DRV_ETHMAC_EventNotifySet DRV_ETHMAC_EventPendingGet DRV_ETHMAC_ByteArrayGet DRV_ETHMAC_HeaderGet DRV_ETHMAC_IPBufferChecksumCalc DRV_ETHMAC_LinkCheck DRV_ETHMAC_MemoryCopyIsDone DRV_ETHMAC_PIC32MACClose DRV_ETHMAC_PIC32MACOpen DRV_ETHMAC_PIC32MACSetup DRV_ETHMAC_PIC32MACTeardown DRV_ETHMAC_PowerMode DRV_ETHMAC_ByteArrayPut DRV_ETHMAC_HeaderPut DRV_ETHMAC_ReadPointerBaseSet DRV_ETHMAC_ReadPointerSet DRV_ETHMAC_RxChecksumCalc DRV_ETHMAC_RxHashTableEntrySet DRV_ETHMAC_RxReadPointerGet DRV_ETHMAC_RxReadPointerSet DRV_ETHMAC_TxBufferFlush DRV_ETHMAC_TxIsReady DRV_ETHMAC_VersionGet DRV_ETHMAC_VersionStrGet DRV_ETHMAC_WritePointerSet PIC32MACGetTxBaseAddr PIC32MACDiscardRx PIC32MACEventAck PIC32MACEventDeInit PIC32MACEventInit PIC32TCPIP_MAC_EventNotifyClear PIC32MACEventSetNotifyHandler PIC32MACEventSetNotifyEvents PIC32MACEventGetPending PIC32MACGetArray PIC32MACGetHeader PIC32MACCalcIPBufferChecksum PIC32MACCheckLink PIC32MACIsMemCopyDone PIC32MACClose PIC32MACOpen PIC32MACInitialize PIC32MACDeinitialize PIC32MACPowerMode PIC32MACPutArray PIC32MACPutHeader PIC32MACSetBaseReadPtr PIC32MACSetReadPtr PIC32MACCalcRxChecksum PIC32MACSetRXHashTableEntry PIC32MACGetReadPtrInRx PIC32MACSetReadPtrInRx PIC32MACFlush PIC32MACIsTxReady -none- -nonePIC32MACSetWritePtr 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-231 MCHP_tcpip_unified Function MPLAB Harmony Function: PIC32MACCalcIPBufferChecksum PIC32MACCalcRxChecksum PIC32MACCheckLink PIC32MACDeinitialize PIC32MACDiscardRx PIC32MACEventAck PIC32MAC_EventNotifyClear PIC32MACEventDeInit PIC32MACEventGetPending PIC32MACEventInit PIC32MACEventSetNotifyEvents PIC32MACEventSetNotifyHandler PIC32MACFlush PIC32MACGetArray PIC32MACGetHeader PIC32MACGetReadPtrInRx PIC32MACGetTxBaseAddr PIC32MACIsMemCopyDone PIC32MACIsTxReady PIC32MACDeinitialize PIC32MACInitialize PIC32MACOpen PIC32MACClose PIC32MACPowerMode PIC32MACPutArray PIC32MACPutHeader PIC32MACSetBaseReadPtr PIC32MACSetRXHashTableEntry PIC32MACSetReadPtr PIC32MACSetReadPtrInRx PIC32MACSetWritePtr DRV_ETHMAC_IPBufferChecksumCalc DRV_ETHMAC_RxChecksumCalc DRV_ETHMAC_LinkCheck DRV_ETHMAC_PIC32MACTeardown DRV_ETHMAC_RxPacketDiscard DRV_ETHMAC_EventAck DRV_ETHMAC_EventNotifyClear DRV_ETHMAC_EventDeInit DRV_ETHMAC_EventPendingGet DRV_ETHMAC_EventInit DRV_ETHMAC_EventNotifySet DRV_ETHMAC_EventNotifyHandlerSet DRV_ETHMAC_TxBufferFlush DRV_ETHMAC_ByteArrayGet DRV_ETHMAC_HeaderGet DRV_ETHMAC_RxReadPointerGet DRV_ETHMAC_BaseAddrTxGet DRV_ETHMAC_MemoryCopyIsDone DRV_ETHMAC_TxIsReady DRV_ETHMAC_PIC32MACTeardown DRV_ETHMAC_PIC32MACSetup DRV_ETHMAC_PIC32MACOpen DRV_ETHMAC_PIC32MACClose DRV_ETHMAC_PowerMode DRV_ETHMAC_ByteArrayPut DRV_ETHMAC_HeaderPut DRV_ETHMAC_ReadPointerBaseSet DRV_ETHMAC_RxHashTableEntrySet DRV_ETHMAC_ReadPointerSet DRV_ETHMAC_RxReadPointerSet DRV_ETHMAC_WritePointerSet DRV_ETHMAC_VersionGet DRV_ETHMAC_VersionStrGet 5.1.3.4.4 Support for Legacy "Ethernet Controller Library" These routines (DRV_ETHMAC_Legacy*) provide MPLAB Harmony support for applications that use the "Ethernet Controller Library for Microchip PIC32MX Microcontrollers" that is installed with XC32 compilers. (See Microchip\xc32\v1.20\docs\pic32-lib-help\hlpETH.chm for information on this legacy support.) For some functions the argument list is the same, but for others the addition of an index value from the ETH_MODULE_ID enumeration has been added to make the function work from within the context of this MPLAB Harmony driver. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-232 Legacy Controller Library MPLAB Harmony EthClose EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthInit EthMACGetAddress EthMACOpen EthMACSetAddress EthMACSetMaxFrame EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxGetBuffer EthRxGetPacket EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket DRV_ETHMAC_LegacyClose DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove PLIB_ETH_LegacyEventsClr PLIB_ETH_LegacyEventsEnableClr PLIB_ETH_LegacyEventsEnableGet PLIB_ETH_LegacyEventsEnableSet PLIB_ETH_LegacyEventsEnableWrite PLIB_ETH_LegacyEventsGet DRV_ETHMAC_LegacyInit PLIB_ETH_LegacyMACGetAddress DRV_ETHMAC_LegacyMACOpen PLIB_ETH_LegacyMACSetAddress PLIB_ETH_LegacyMACSetMaxFrame DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend PLIB_ETH_LegacyRxFiltersClr PLIB_ETH_LegacyRxFiltersHTSet PLIB_ETH_LegacyRxFiltersPMClr PLIB_ETH_LegacyRxFiltersPMSet PLIB_ETH_LegacyRxFiltersSet PLIB_ETH_LegacyRxFiltersWrite DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket PLIB_ETH_LegacyRxSetBufferSize PLIB_ETH_LegacyStatRxAlgnErrCnt PLIB_ETH_LegacyStatRxFcsErrCnt PLIB_ETH_LegacyStatRxOkCnt PLIB_ETH_LegacyStatRxOvflCnt PLIB_ETH_LegacyStatTxMColCnt PLIB_ETH_LegacyStatTxOkCnt PLIB_ETH_LegacyStatTxSColCnt DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-233 MAC Driver Function Legacy Controller Library DRV_ETHMAC_LegacyClose DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove DRV_ETHMAC_LegacyInit DRV_ETHMAC_LegacyMACOpen DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket EthClose EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthInit EthMACOpen EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxGetBuffer EthRxGetPacket EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket 5.1.3.5 Configuring the Library Macros Name Description DRV_ETHMAC_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHMAC_INDEX Ethernet MAC static index selection. DRV_ETHMAC_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHMAC_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ETHMAC_INTERRUPT_SOURCE Defines an override of the interrupt source in case of static driver. DRV_ETHMAC_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHMAC_POWER_STATE Defines an override of the power state of the Ethernet MAC driver. Description The configuration of the Ethernet MAC Driver is based on the file sys_config.h This header file contains the configuration selection for the Ethernet MAC Driver. Based on the selections made, the Ethernet MAC Driver will support or not support selected features. These configuration settings will apply to all instances of the Ethernet MAC DRiver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-234 5.1.3.5.1 DRV_ETHMAC_CLIENTS_NUMBER Macro C #define DRV_ETHMAC_CLIENTS_NUMBER 1 Description Ethernet MAC Maximum Number of Clients This definition select the maximum number of clients that the Ethernet MAC driver can support at run time. Not defining it means using a single client. Remarks None. 5.1.3.5.2 DRV_ETHMAC_INDEX Macro C #define DRV_ETHMAC_INDEX DRV_ETHMAC_INDEX_1 Description Ethernet MAC Static Index Selection This definition selects the Ethernet MAC static index for the driver object reference Remarks This index is required to make a reference to the driver object. 5.1.3.5.3 DRV_ETHMAC_INSTANCES_NUMBER Macro C #define DRV_ETHMAC_INSTANCES_NUMBER 1 Description Ethernet MAC hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Not defining it means using a static driver. Remarks None. 5.1.3.5.4 DRV_ETHMAC_INTERRUPT_MODE Macro C #define DRV_ETHMAC_INTERRUPT_MODE true Description Ethernet MAC Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-235 • true - Select if interrupt mode of timer operation is desired • false - Select if polling mode of timer operation is desired Not defining this option to true or false will result in a build error. Remarks None. 5.1.3.5.5 DRV_ETHMAC_INTERRUPT_SOURCE Macro C #define DRV_ETHMAC_INTERRUPT_SOURCE INT_SOURCE_ETH_1 Description Ethernet MAC Interrupt Source Defines an override of the interrupt source in case of static driver. Remarks Refer to the INT PLIB document for more information on INT_SOURCE enumeration. 5.1.3.5.6 DRV_ETHMAC_PERIPHERAL_ID Macro C #define DRV_ETHMAC_PERIPHERAL_ID ETHMAC_ID_1 Description Ethernet MAC Peripheral ID Selection Defines an override of the peripheral ID, using macros. Remarks Some devices also support ETHMAC_ID_0 5.1.3.5.7 DRV_ETHMAC_POWER_STATE Macro C #define DRV_ETHMAC_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description Ethernet MAC power state configuration Defines an override of the power state of the Ethernet MAC driver. Remarks This feature may not be available in the device or the Ethernet MAC module selected. 5.1.3.6 Building the Library This section list the files that are available in the \src of the Ethernet MAC Driver. It lists which files need to be included in the 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-236 build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.3.7 Library Interface Data Types and Constants Name Description ETH_CLOSE_FLAGS Defines the possible disable codes of Ethernet controller "DRV_ETHMAC_LegacyClose" call. ETH_LINK_STATUS Defines the possible status flags of Ethernet link. ETH_MODULE_STATUS Defines the possible status codes of the Ethernet controller. ETH_OPEN_FLAGS Supported open configuration flags for the Ethernet module (EthMACOpen). ETH_PAUSE_TYPE Defines the possible Ethernet MAC pause types. ETH_RESULT_CODE Defines the possible results of Ethernet operations that can succeed or fail ETHPHY_CONFIG_FLAGS flags for DRV_ETHPHY_Setup() call DRV_ETHMAC_INDEX_1 This is macro DRV_ETHMAC_INDEX_1. DRV_ETHPHY_INDEX_1 This is macro DRV_ETHPHY_INDEX_1. Client Level Functions Name Description DRV_ETHMAC_PIC32MACClose Closes a client instance of the PIC32 MAC Driver. DRV_ETHMAC_PIC32MACGetConfig Supports PIC32 Ethernet MAC by copying its configuration.. DRV_ETHMAC_PIC32MACLinkCheck Checks current link status. DRV_ETHMAC_PIC32MACOpen Opens a client instance of the PIC32 MAC Driver. DRV_ETHMAC_PIC32MACSetup Supports PIC32 Ethernet MAC setup. DRV_ETHMAC_PIC32MACTeardown Supports PIC32 Ethernet MAC Teardown (opposite of setup). Event Functions Name Description DRV_ETHMAC_PIC32MACEventAcknowledge This function acknowledges and re-enables processed events. Multiple events can be orr-ed together as they are processed together. The events acknowledged by this function should be the events that have been retrieved from the stack by calling DRV_ETHMAC_PIC32MACEventPendingGet() or have been passed to the user by the stack using the notification handler (PIC32MACEventSetNotifyHandler()) and have been processed and have to be re-enabled. DRV_ETHMAC_PIC32MACEventMaskSet Enables the MAC events. DRV_ETHMAC_PIC32MACEventPendingGet Returns the currently pending events. Other Functions Name Description DRV_ETHMAC_PIC32MACPowerMode Powers down the Ethernet MAC. DRV_ETHMAC_PIC32MACProcess MAC periodic processing function. Receive Functions Name Description DRV_ETHMAC_PIC32MACPacketRx A packet is returned if such a pending packet exists. DRV_ETHMAC_PIC32MACPacketTx A packet is submitted to the MAC driver for transmission. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-237 Transmit Functions Name Description DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Calculates a CRC-32 and sets the approriate bit in the ETHHTx registers Description 5.1.3.7.1 Client Level Functions 5.1.3.7.1.1 DRV_ETHMAC_PIC32MACClose Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACClose( TCPIP_MAC_HANDLE hMac ); Description This function closes a client instance of the PIC32 MAC Driver. Preconditions DRV_ETHMAC_PIC32MACOpen should have been called. Parameters Parameters Description macId MAC idenfification, from the TCPIP_STACK_MODULE enumeration Returns TCPIP_MAC_RES_OK if initialization completed; otherwise, the error enumeration value. Example 5.1.3.7.1.2 DRV_ETHMAC_PIC32MACGetConfig Function C size_t DRV_ETHMAC_PIC32MACGetConfig( TCPIP_STACK_MODULE modId, void* configBuff, size_t buffSize, size_t* pConfigSize ); Description Supports PIC32 Ethernet MAC Teardown (opposite of Setup). Used by tcpip_module_manager. Preconditions Supports PIC32 Ethernet MAC by copying its configuration.. Parameters Parameters Description modId Module ID from TCPIP_STACK_MODULE enumeration, identifying MAC. configBuff Pointer to configuration buffer to be copied 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-238 buffSize Size of configuration buffer provided by configBuff pConfigSize Pointer to size of configuration buffer copied. Returns Size of configuration buffer copied. Remarks This function deinitializes the Eth controller, the MAC and the associated PHY. It should be called to be able to schedule any Eth transmit or receive operation. Example 5.1.3.7.1.3 DRV_ETHMAC_PIC32MACLinkCheck Function C bool DRV_ETHMAC_PIC32MACLinkCheck( TCPIP_MAC_HANDLE hMac ); Description This function checks the link status, performing a MAC reconfiguration if the link went up after being down. Preconditions None. Parameters Parameters Description hMac Ethernet MAC client handle Returns • true - If the link is up • false - If the link is not up Remarks If auto negotiation is enabled the MAC we may have to be reconfigured. Example 5.1.3.7.1.4 DRV_ETHMAC_PIC32MACOpen Function C TCPIP_MAC_HANDLE DRV_ETHMAC_PIC32MACOpen( TCPIP_STACK_MODULE macId ); Description This function opens a client instance of the PIC32 MAC Driver. Used by tcpip_module_manager. Preconditions DRV_ETHMAC_PIC32MACSetup should have been called. Parameters Parameters Description macId MAC idenfification, from the TCPIP_STACK_MODULE enumeration 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-239 Returns TCPIP_MAC_HANDLE - handle (pointer) to MAC client Example 5.1.3.7.1.5 DRV_ETHMAC_PIC32MACSetup Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACSetup( TCPIP_MAC_MODULE_CTRL* const stackData, const TCPIP_MODULE_MAC_PIC32INT_CONFIG* initData ); Description This function supports setup of the PIC32 Ethernet MAC. Used by tcpip_module_manager. Preconditions DRV_ETHMAC_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description pStackData Pointer to stack data initData Pointer to initialization data Returns TCPIP_MAC_RES_OK if initialization completed; otherwise, error enumeration value. Remarks This function initializes the Ethernet controller, the MAC and the associated PHY. It should be called to be able to schedule any Ethernet transmit or receive operation. Example 5.1.3.7.1.6 DRV_ETHMAC_PIC32MACTeardown Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACTeardown( const TCPIP_MAC_MODULE_CTRL* const stackData ); Description This function supports teardown of the PIC32 Ethernet MAC (opposite of setup). Used by tcpip_module_manager. Preconditions DRV_ETHMAC_PIC32MACSetup must have been called to setup the driver. Parameters Parameters Description pStackData Pointer to Stack Data Returns TCPIP_MAC_RES_OK if initialization completed, error enumeration value otherwise. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-240 Remarks This function deinitializes the Ethernet controller, the MAC and the associated PHY. It should be called to be able to schedule any Ethernet transmit or receive operation. Example 5.1.3.7.2 Get and Put Functions 5.1.3.7.3 Base Address and Buffer Size Functions 5.1.3.7.4 Receive Functions 5.1.3.7.4.1 DRV_ETHMAC_PIC32MACPacketRx Function C TCPIP_MAC_PACKET* DRV_ETHMAC_PIC32MACPacketRx( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat ); Description This is the MAC receive function. Once a pending packet is available in the MAC driver internal RX queues this function will dequeue the packet and hand it over to the MAC driver's client - i.e. the stack - for further processing. The flags for a RX packet have to be updated by the MAC driver: • TCPIP_MAC_PKT_FLAG_RX has to be set If the MAC supports it, it should set: • TCPIP_MAC_PKT_FLAG_UNICAST has to be set if that packet is a unicast packet • TCPIP_MAC_PKT_FLAG_BCAST has to be set if that packet is a broadcast packet • TCPIP_MAC_PKT_FLAG_MCAST has to be set if that packet is a multicast packet • TCPIP_MAC_PKT_FLAG_QUEUED has to be set • TCPIP_MAC_PKT_FLAG_SPLIT has to be set if the packet has multiple data segments Additional information about the packet is available by providing the pRes and ppPktStat fields. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. Parameters Parameters Description hMac Ethernet MAC client handle pRes optional pointer to an address that will receive an additional result associated with the operation. Can be 0 if not needed. ppPktStat optional pointer to an address that will receive the received packet status. Note that this pointer cannot be used once the packet acknowledgement function was called. Can be 0 if not needed. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-241 Returns a valid pointer to an available RX packet 0 if no packet pending/available Remarks The MAC driver dequeues and return to the caller just one single packet. Once the higher level layers in the stack are done with processing the RX packet, they have to call the corresponding packet acknowledgement function that tells the MAC driver that it can resume control of that packet. Once the stack modules are done processing the RX packets and the acknowledge function is called the MAC driver will reuse the RX packets. The MAC driver may use the DRV_ETHMAC_PIC32MACProcess() for obtaining new RX packets if needed. Example 5.1.3.7.4.2 DRV_ETHMAC_PIC32MACPacketTx Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACPacketTx( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket ); Description This is the MAC transmit function. The MAC driver has to suport internal queueing! A packet is to be rejected only if it's not properly formatted. Otherwise it has to be scheduled for transmission in an internal queue! Once the packet is scheduled for transmission the MAC driver has to set the TCPIP_MAC_PKT_FLAG_QUEUED flag so that the stack is aware that this packet is under processing cnd cannot be modified! Once the packet is transmitted, the TCPIP_MAC_PKT_FLAG_QUEUED has to be cleared, the proper packet acknowledgement result (ackRes) has to be set and the packet acknowledgement function (ackFunc) has to be called. It is implementation dependant if all these steps are implemented as part of the ackFunc itself or as discrete steps. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. Parameters Parameters Description hMac Ethernet MAC client handle ptrPacket pointer to a TCPIP_MAC_PACKET that's completely formatted and ready to be transmitted over the network Returns TCPIP_MAC_RES_OK if the packet transmitted, TCPIP_MAC_RES errocode for not properly formatted packets, etc. Example 5.1.3.7.5 Transmit Functions 5.1.3.7.5.1 DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet( 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-242 TCPIP_MAC_HANDLE hMac, TCPIP_MAC_ADDR* DestMACAddr ); Description This function salculates a CRC-32 using polynomial 0x4C11DB7 and then, using bits 28 through 23 of the CRC, sets the appropriate bit in the ETHHT0-ETHHT1 registers. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. Parameters Parameters Description hMac Ethernet MAC client handle DestMACAddr 6-byte group destination MAC address to allow through the Hash Table Filter. If DestMACAddr is set to '0000 0000 0000', the hash table will be cleared of all entries and the filter will be disabled. Returns TCPIP_MAC_RES_OK if success, an eror code otherwise. Remarks Sets the appropriate bit in the ETHHT0/1 registers to allow packets sent to DestMACAddr to be received and enabled the Hash Table receive filter There is no way to individually unset destination MAC addresses from the hash table since it is possible to have a hash collision and therefore multiple MAC addresses relying on the same hash table bit. The stack would have to individually store each 6 byte MAC address to support this feature, which would waste a lot of RAM and be unnecessary in most applications. As a simple compromise, you can call DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet() using a 00-00-00-00-00-00 destination MAC address, which will clear the entire hash table and disable the hash table filter. This will allow you to then readd the necessary destination addresses. Example 5.1.3.7.6 Event Functions 5.1.3.7.6.1 DRV_ETHMAC_PIC32MACEventAcknowledge Function C bool DRV_ETHMAC_PIC32MACEventAcknowledge( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_EVENT tcpAckEv ); Description This function acknowledges and re-enables processed events. Multiple events can be orr-ed together as they are processed together. The events acknowledged by this function should be the events that have been retrieved from the stack by calling DRV_ETHMAC_PIC32MACEventPendingGet() or have been passed to the user by the stack using the notification handler (PIC32MACEventSetNotifyHandler()) and have been processed and have to be re-enabled. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-243 Parameters Parameters Description hMac Ethernet MAC client handle tcpAckEv the events that the user processed and need to be re-enabled Returns true if events acknowledged false if no events to be acknowledged Remarks All events should be acknowledged, in order to be re-enabled. Some events are fatal errors and should not be acknowledged (TCPIP_MAC_EV_RX_BUSERR, TCPIP_MAC_EV_TX_BUSERR). Stack re-initialization is needed under such circumstances. Some events are just system/application behavior and they are intended only as simple info (TCPIP_MAC_EV_RX_OVFLOW, TCPIP_MAC_EV_RX_BUFNA, TCPIP_MAC_EV_TX_ABORT, TCPIP_MAC_EV_RX_ACT). The TCPIP_MAC_EV_RX_FWMARK and TCPIP_MAC_EV_RX_EWMARK events are part of the normal flow control operation (if auto flow control was enabled). They should be enabled alternatively, if needed. The events are persistent. They shouldn't be re-enabled unless they have been processed and the condition that generated them was removed. Re-enabling them immediately without proper processing will have dramatic effects on system performance. Example DRV_ETHMAC_PIC32MACEventAcknowledge( hMac, stackNewEvents ); 5.1.3.7.6.2 DRV_ETHMAC_PIC32MACEventMaskSet Function C bool DRV_ETHMAC_PIC32MACEventMaskSet( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable ); Description This function sets the enabled events. Multiple events can be orr-ed together. All events that are set will be added to the notification process. The old events will be disabled. The stack (or stack user) has to catch the events that are notified and process them: • The stack should process the TCPIP_MAC_EV_RX_PKTPEND/TCPIP_MAC_EV_RX_DONE, TCPIP_MAC_EV_TX_DONE transfer events • Process the specific condition and acknowledge them calling DRV_ETHMAC_PIC32MACEventAcknowledge() so that they can be re-enabled. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. Parameters Parameters Description hMac Ethernet MAC client handle macEvMask events the user of the stack wants to add/delete for notification enable if true, the events will be enabled, else disabled 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-244 Returns always true, operation succeeded. Remarks The event notification system enables the user of the TCPIP stack to call into the stack for processing only when there are relevant events rather than being forced to periodically call from within a loop. If the notification events are nill the interrupt processing will be disabled. Otherwise the event notification will be enabled and the interrupts relating to the requested events will be enabled. Note that once an event has been caught by the stack ISR (and reported if a notification handler is in place) it will be disabled until the DRV_ETHMAC_PIC32MACEventAcknowledge() is called. Example DRV_ETHMAC_PIC32MACEventMaskSet( hMac, TCPIP_MAC_EV_RX_OVFLOW | TCPIP_MAC_EV_RX_BUFNA, true ); 5.1.3.7.6.3 DRV_ETHMAC_PIC32MACEventPendingGet Function C TCPIP_MAC_EVENT DRV_ETHMAC_PIC32MACEventPendingGet( TCPIP_MAC_HANDLE hMac ); Description This function returns the currently pending events belonging to a group. Multiple events can be orr-ed together as they accumulate. The stack should be called for processing whenever a stack managed event (TCPIP_MAC_EV_RX_PKTPEND, TCPIP_MAC_EV_TX_DONE) is present. The other, non critical events, may not be managed by the stack and passed to an user. They will have to be eventually acknowledged if re-enabling is needed. Preconditions DRV_ETHMAC_PIC32MACSetup should have been called. Parameters Parameters Description hMac parameter identifying the intended MAC client Returns The currently stack pending events. Remarks This is the preferred method to get the current pending MAC events. The stack maintains a proper image of the events from their occurrence to their acknowledgement. Even with a notification handler in place it's better to use this function to get the current pending events rather than using the events passed by the notification handler which could be stale. The events are persistent. They shouldn't be re-enabled unless they have been processed and the condition that generated them was removed. Re-enabling them immediately without proper processing will have dramatic effects on system performance. The returned value is just a momentary value. The pending events can change any time. Example TCPIP_MAC_EVENT currEvents = DRV_ETHMAC_PIC32MACEventPendingGet( hMac); 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-245 5.1.3.7.7 Library Functions 5.1.3.7.8 Other Functions 5.1.3.7.8.1 DRV_ETHMAC_PIC32MACPowerMode Function C bool DRV_ETHMAC_PIC32MACPowerMode( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_POWER_MODE pwrMode ); Description This function powers down the Ethernet MAC. Preconditions None. Parameters Parameters Description hMac Ethernet MAC client handle pwrMode Power Mode (?) Returns None. Example 5.1.3.7.8.2 DRV_ETHMAC_PIC32MACProcess Function C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACProcess( TCPIP_MAC_HANDLE hMac ); Description This is a function that allows for internal processing by the MAC driver. It is meant for processing that cannot be done from within ISR. Some of the processing that this is intended for: • the MAC driver can process its pending TX queues (although it should do that preferrably from within the TX ISR) • RX buffers replenishing. If the number of packets in the RX queue falls below a specified limit, the MAC driver can use this function to allocate some extra RX packets. Similarly, if there are too many allocated RX packets, the MAC driver can free some of them. Normally this function will be called in response to an TX and/or RX event signalled by the driver. This is specified by the MAC driver at initialization time using TCPIP_MAC_MODULE_CTRL. An alternative approach is that the MAC driver uses a system service to create a timer signal that will call the TCPIP_MAC_Process on a periodic basis. Preconditions DRV_ETHMAC_PIC32MACSetup() should have been called. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-246 Parameters Parameters Description hMac Ethernet MAC client handle Returns TCPIP_MAC_RES_OK if all processing went on OK a TCPIP_MAC_RES error code if processing failed for some reason Remarks The MAC driver may use the DRV_ETHMAC_PIC32MACProcess() for obtaining new RX packets if needed. Example 5.1.3.7.9 Data Types and Constants 5.1.3.7.9.1 ETH_CLOSE_FLAGS Enumeration C typedef enum { ETH_CLOSE_GRACEFUL, ETH_CLOSE_DEFAULT = (0) } ETH_CLOSE_FLAGS; Description Ethernet Close Flags This enumeration defines the close capabilities of the Ethernet module. Members Members Description ETH_CLOSE_GRACEFUL Wait for the current TX/RX op to finish ETH_CLOSE_DEFAULT = (0) Default close options 5.1.3.7.9.2 ETH_LINK_STATUS Enumeration C typedef enum { ETH_LINK_ST_DOWN, ETH_LINK_ST_UP, ETH_LINK_ST_LP_NEG_UNABLE, ETH_LINK_ST_REMOTE_FAULT, ETH_LINK_ST_PDF, ETH_LINK_ST_LP_PAUSE, ETH_LINK_ST_LP_ASM_DIR, ETH_LINK_ST_NEG_TMO, ETH_LINK_ST_NEG_FATAL_ERR } ETH_LINK_STATUS; Description Ethernet Link Status Codes This enumeration defines the flags describing the status of the Ethernet link. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-247 Members Members Description ETH_LINK_ST_DOWN No connection to the LinkPartner ETH_LINK_ST_UP Link is up ETH_LINK_ST_LP_NEG_UNABLE LP non negotiation able ETH_LINK_ST_REMOTE_FAULT LP fault during negotiation ETH_LINK_ST_PDF Parallel Detection Fault encountered (when ETH_LINK_ST_LP_NEG_UNABLE) ETH_LINK_ST_LP_PAUSE LP supports symmetric pause ETH_LINK_ST_LP_ASM_DIR LP supports asymmetric TX/RX pause operation ETH_LINK_ST_NEG_TMO LP not there ETH_LINK_ST_NEG_FATAL_ERR An unexpected fatal error occurred during the negotiation Remarks Multiple flags can be set. 5.1.3.7.9.3 ETH_MODULE_STATUS Enumeration C typedef enum { ETH_ST_RXBUSY, ETH_ST_TXBUSY, ETH_ST_BUSY } ETH_MODULE_STATUS; Description Ethernet Controller Status Codes This enumeration defines the flags describing the status of the Ethernet controller. Members Members Description ETH_ST_RXBUSY A packet is currently received ETH_ST_TXBUSY A packet is currently transmitted ETH_ST_BUSY Module is on or completing a transaction 5.1.3.7.9.4 ETH_OPEN_FLAGS Enumeration C typedef enum { ETH_OPEN_AUTO, ETH_OPEN_FDUPLEX, ETH_OPEN_HDUPLEX, ETH_OPEN_100, ETH_OPEN_10, ETH_OPEN_HUGE_PKTS, ETH_OPEN_MAC_LOOPBACK, ETH_OPEN_PHY_LOOPBACK, ETH_OPEN_MDIX_AUTO, ETH_OPEN_MDIX_NORM, ETH_OPEN_MDIX_SWAP, ETH_OPEN_RMII, ETH_OPEN_MII, ETH_OPEN_DEFAULT = (ETH_OPEN_AUTO|ETH_OPEN_FDUPLEX|ETH_OPEN_HDUPLEX| ETH_OPEN_100|ETH_OPEN_10|ETH_OPEN_MDIX_AUTO) 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-248 } ETH_OPEN_FLAGS; Description Ethernet Open Configuration Settings This enumeration defines the various configuration options for the Ethernet module. These values can be ORed together to create a configuration mask passed to the EthMACOpen routine. Members Members Description ETH_OPEN_AUTO Use auto negotiation. set the following flags to specify your choices ETH_OPEN_FDUPLEX Use full duplex or full duplex negotiation capability needed ETH_OPEN_HDUPLEX Use half duplex or half duplex negotiation capability needed ETH_OPEN_100 Use 100MBps or 100MBps negotiation capability needed ETH_OPEN_10 Use 10MBps or 10MBps negotiation capability needed ETH_OPEN_HUGE_PKTS Allow huge packets RX/TX ETH_OPEN_MAC_LOOPBACK Loopbacked at the MAC level ETH_OPEN_PHY_LOOPBACK When PHY is loopback-ed, negotiation will be disabled! ETH_OPEN_MDIX_AUTO Use Auto MDIX ETH_OPEN_MDIX_NORM Use normal MDIX when Auto MDIX disabled ETH_OPEN_MDIX_SWAP Use swapped MDIX when Auto MDIX disabled ETH_OPEN_RMII RMII connection ETH_OPEN_MII MII connection ETH_OPEN_DEFAULT = (ETH_OPEN_AUTO|ETH_OPEN_FDUPLEX|ETH_OPEN_HDUPLEX| ETH_OPEN_100|ETH_OPEN_10|ETH_OPEN_MDIX_AUTO) All capabilities default Remarks When Auto-negotiation is specified: • If multiple capability flags are set (ETH_OPEN_FDUPLEX, ETH_OPEN_HDUPLEX, ETH_OPEN_100, ETH_OPEN_10 ) they are all advertised as this link side capabilities. • If no setting is passed, the lowest one is taken, i.e., ETH_OPEN_HDUPLEX and ETH_OPEN_10. • Auto-MDIX requires Auto-Negotiation; ETH_OPEN_MDIX_NORM or ETH_OPEN_MDIX_SWAP setting irrelevant. When No Auto-negotiation is specified: • If multiple settings, the highest priority setting is taken, i.e. ETH_OPEN_FDUPLEX over ETH_OPEN_HDUPLEX and ETH_OPEN_100 over ETH_OPEN_10. • If no setting, the lowest setting is taken, i.e., ETH_OPEN_HDUPLEX and ETH_OPEN_10. • The MDIX is set based on the ETH_OPEN_MDIX_NORM/ETH_OPEN_MDIX_SWAP setting. 5.1.3.7.9.5 ETH_PAUSE_TYPE Enumeration C typedef enum { ETH_MAC_PAUSE_TYPE_NONE, ETH_MAC_PAUSE_TYPE_PAUSE, ETH_MAC_PAUSE_TYPE_ASM_DIR, 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-249 ETH_MAC_PAUSE_TYPE_EN_TX, ETH_MAC_PAUSE_TYPE_EN_RX, ETH_MAC_PAUSE_ALL = (ETH_MAC_PAUSE_TYPE_PAUSE|ETH_MAC_PAUSE_TYPE_ASM_DIR| ETH_MAC_PAUSE_TYPE_EN_TX|ETH_MAC_PAUSE_TYPE_EN_RX), ETH_MAC_PAUSE_CPBL_MASK = ETH_MAC_PAUSE_ALL } ETH_PAUSE_TYPE; Description Ethernet MAC Pause Types This enumeration defines the pause capabilities of the Ethernet MAC. Members Members Description ETH_MAC_PAUSE_TYPE_NONE No PAUSE capabilities ETH_MAC_PAUSE_TYPE_PAUSE Supports symmetric PAUSE ETH_MAC_PAUSE_TYPE_ASM_DIR Supports ASM_DIR ETH_MAC_PAUSE_TYPE_EN_TX Enable MAC TX pause support ETH_MAC_PAUSE_TYPE_EN_RX Enable MAC RX pause support ETH_MAC_PAUSE_ALL = (ETH_MAC_PAUSE_TYPE_PAUSE|ETH_MAC_PAUSE_TYPE_ASM_DIR| ETH_MAC_PAUSE_TYPE_EN_TX|ETH_MAC_PAUSE_TYPE_EN_RX) All types of pause ETH_MAC_PAUSE_CPBL_MASK = ETH_MAC_PAUSE_ALL All pause capabilities our MAC supports 5.1.3.7.9.6 ETH_RESULT_CODE Enumeration C typedef enum { ETH_RES_OK, ETH_RES_NO_PACKET, ETH_RES_PACKET_QUEUED, ETH_RES_OUT_OF_MEMORY, ETH_RES_NO_DESCRIPTORS, ETH_RES_USPACE_ERR, ETH_RES_RX_SIZE_ERR, ETH_RES_RX_PKT_SPLIT_ERR, ETH_RES_NEGOTIATION_UNABLE, ETH_RES_NEGOTIATION_INACTIVE, ETH_RES_NEGOTIATION_NOT_STARTED, ETH_RES_NEGOTIATION_ACTIVE, ETH_RES_NEGOTIATION_LINKDOWN, ETH_RES_DTCT_ERR, ETH_RES_CPBL_ERR, ETH_RES_CFG_ERR } ETH_RESULT_CODE; Description Ethernet Operation Result Codes This enumeration defines the possible results of any of the Ethernet library operations that have the possibilty of failing. This result should be checked to ensure that the operation achieved the desired result. Members Members Description ETH_RES_OK Everything ok ETH_RES_NO_PACKET No such packet exist ETH_RES_PACKET_QUEUED Packet is queued (not transmitted or received and not processed) 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-250 ETH_RES_OUT_OF_MEMORY Some memory allocation failed ETH_RES_NO_DESCRIPTORS Not enough descriptors available ETH_RES_USPACE_ERR We don't support user space buffers. ETH_RES_RX_SIZE_ERR The size of the receive buffers too small ETH_RES_RX_PKT_SPLIT_ERR A received packet spans more buffers/descriptors than supplied ETH_RES_NEGOTIATION_UNABLE No negotiation support ETH_RES_NEGOTIATION_INACTIVE No negotiation active ETH_RES_NEGOTIATION_NOT_STARTED Negotiation not started yet ETH_RES_NEGOTIATION_ACTIVE Negotiation active ETH_RES_NEGOTIATION_LINKDOWN Link down after negotiation, negotiation failed ETH_RES_DTCT_ERR No Phy was detected or it failed to respond to reset command ETH_RES_CPBL_ERR No match between the capabilities: the Phy supported and the open requested ones ETH_RES_CFG_ERR Hardware configuration doesn't match the requested open mode 5.1.3.7.9.7 ETHPHY_CONFIG_FLAGS Enumeration C typedef enum { ETH_PHY_CFG_RMII, ETH_PHY_CFG_MII, ETH_PHY_CFG_ALTERNATE, ETH_PHY_CFG_DEFAULT, ETH_PHY_CFG_AUTO } ETHPHY_CONFIG_FLAGS; Description flags for DRV_ETHPHY_Setup() call Members Members Description ETH_PHY_CFG_RMII RMII data interface in configuration fuses. ETH_PHY_CFG_MII MII data interface in configuration fuses. ETH_PHY_CFG_ALTERNATE Configuration fuses is ALT ETH_PHY_CFG_DEFAULT Configuration fuses is DEFAULT ETH_PHY_CFG_AUTO Use the fuses configuration to detect if you are RMII/MII and ALT/DEFAULT configuration 5.1.3.7.9.8 DRV_ETHMAC_INDEX_1 Macro C #define DRV_ETHMAC_INDEX_1 1 Description This is macro DRV_ETHMAC_INDEX_1. 5.1.3.7.9.9 DRV_ETHPHY_INDEX_1 Macro C #define DRV_ETHPHY_INDEX_1 1 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-251 Description This is macro DRV_ETHPHY_INDEX_1. 5.1.3.8 Files Files Name Description drv_ethernet_flags.h Ethernet driver configuration flags file. drv_ethmac.h Ethernet MAC device driver interface file. drv_ethmac_config.h Ethernet MAC driver configuration definitions template. Description 5.1.3.8.1 drv_ethernet_flags.h Ethernet Drivers Configuration Flags This file provides the definition of commonly-used configuration enumerations for use with the Ethernet PHY and Ethernet MAC Drivers. Enumerations Name Description ETH_CLOSE_FLAGS Defines the possible disable codes of Ethernet controller "DRV_ETHMAC_LegacyClose" call. ETH_LINK_STATUS Defines the possible status flags of Ethernet link. ETH_OPEN_FLAGS Supported open configuration flags for the Ethernet module (EthMACOpen). ETH_PAUSE_TYPE Defines the possible Ethernet MAC pause types. ETH_RESULT_CODE Defines the possible results of Ethernet operations that can succeed or fail ETHPHY_CONFIG_FLAGS flags for DRV_ETHPHY_Setup() call Company Microchip Technology Inc. FileName: drv_ethernet_flags.h 5.1.3.8.2 drv_ethmac.h Ethernet MAC Device Driver Interface The Ethernet MAC device driver provides a simple interface to manage the Ethernet peripheral. This file defines the interface definitions and prototypes for the Ethernet MAC driver. Enumerations Name Description ETH_MODULE_STATUS Defines the possible status codes of the Ethernet controller. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-252 Functions Name Description DRV_ETHMAC_PIC32MACClose Closes a client instance of the PIC32 MAC Driver. DRV_ETHMAC_PIC32MACEventAcknowledge This function acknowledges and re-enables processed events. Multiple events can be orr-ed together as they are processed together. The events acknowledged by this function should be the events that have been retrieved from the stack by calling DRV_ETHMAC_PIC32MACEventPendingGet() or have been passed to the user by the stack using the notification handler (PIC32MACEventSetNotifyHandler()) and have been processed and have to be re-enabled. DRV_ETHMAC_PIC32MACEventMaskSet Enables the MAC events. DRV_ETHMAC_PIC32MACEventPendingGet Returns the currently pending events. DRV_ETHMAC_PIC32MACGetConfig Supports PIC32 Ethernet MAC by copying its configuration.. DRV_ETHMAC_PIC32MACLinkCheck Checks current link status. DRV_ETHMAC_PIC32MACOpen Opens a client instance of the PIC32 MAC Driver. DRV_ETHMAC_PIC32MACPacketRx A packet is returned if such a pending packet exists. DRV_ETHMAC_PIC32MACPacketTx A packet is submitted to the MAC driver for transmission. DRV_ETHMAC_PIC32MACPowerMode Powers down the Ethernet MAC. DRV_ETHMAC_PIC32MACProcess MAC periodic processing function. DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Calculates a CRC-32 and sets the approriate bit in the ETHHTx registers DRV_ETHMAC_PIC32MACSetup Supports PIC32 Ethernet MAC setup. DRV_ETHMAC_PIC32MACTeardown Supports PIC32 Ethernet MAC Teardown (opposite of setup). Macros Name Description DRV_ETHMAC_INDEX_0 Ethernet driver index definitions. DRV_ETHMAC_INDEX_1 This is macro DRV_ETHMAC_INDEX_1. DRV_ETHMAC_INDEX_COUNT Number of valid Ethernet driver indices. Company Microchip Technology Inc. FileName: drv_ethmac.h 5.1.3.8.3 drv_ethmac_config.h ETHMAC Driver Configuration Definitions for the template version These definitions statically define the driver's mode of operation. Macros Name Description DRV_ETHMAC_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHMAC_INDEX Ethernet MAC static index selection. 5.1 Driver Library Help MPLAB Harmony Help Ethernet MAC Driver Library 5-253 DRV_ETHMAC_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHMAC_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ETHMAC_INTERRUPT_SOURCE Defines an override of the interrupt source in case of static driver. DRV_ETHMAC_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHMAC_POWER_STATE Defines an override of the power state of the Ethernet MAC driver. File Name drv_ethmac_config.h Company Microchip Technology Inc. 5.1.4 Ethernet PHY Driver Library 5.1.4.1 Introduction Ethernet PHY Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the Ethernet PHY Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description This library provides a software abstraction for configuring external Ethernet PHY devices for use with the on-chip Ethernet Controller. 5.1.4.2 Release Notes MPLAB Harmony Version: v0.70b Ethernet PHY Driver Library Version : 7.10 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-254 Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.4.4 Using the Library This topic describes the basic architecture of the Ethernet PHY Driver Library and provides information and examples on how to use it. Interface Header File: drv_ethphy.h The interface to the Ethernet PHY Driver Library is defined in the "drv_ethphy.h" header file. This file is included by the "drv_ethphy.h" file. Any C language source (.c) file that uses the Ethernet PHY Driver Library should include "drv.h". Library File: The Ethernet PHY Driver Library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.1.4.4.1 Abstraction Model Overview To understand how this library works you must first understand how an external Ethernet PHY interfaces with the Ethernet Controller. As shown in Figure 1, the PHY has two interfaces, one for managing the PHY, known as the Serial Management Interface (SMI), for configuring the device and a second, known as the Reduced Media Independent Interface (RMII), for transmit and receive data. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-255 Figure 1: Typical External PHY Interface The block diagram also shows an interrupt signal (nINT) going to a external interrupt pin on the host device and signals going to on-board LEDs to show link state and link activity. The SMI interface is also known as the MII Management (MIIM) interface. This control interface is standardized for all PHY's by Clause 22 of the 802.3 standard. It provides up to 32 16-bit registers on the PHY. The table below provides a summary of all 32 registers. Consult the data sheet for the PHY device for the specific bit fields in each register. Register Address Register Name Register Type 0 Control Basic 1 Status Basic 2,3 PHY Identifier Extended 4 Auto-Negotiation Advertisement Extended 5 Auto-Negotiation Link Partner Base Page Ability Extended 6 Auto-Negotiation Expansion Extended 7 Auto-Negotiation Next Page Transmit Extended 8 Auto-Negotiation Link Partner Received Next Page Extended 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-256 9 MASTER-SLAVE Control Register Extended 10 MASTER-SLAVE Status Register Extended 11-14 Reserved Extended 15 Extended Status Reserved 16-31 Vendor Specific Extended 5.1.4.4.2 Library Overview The Ethernet PHY Driver Library is divided into the following sections: Library Interface Section Description System Level Functions Routines that integrate the driver into the MPLAB Harmony system Client Level Functions Open, Close, Link Status, Auto Negotiation SMI/MIIM Functions SMI/MIIM Management Interface External PHY Support Functions Provides the API for PHY support routines that the driver will call when setting up the PHY. The driver library provides support for 4 PHYs. Other Functions Functions that provide software version information. Data Types and Constants C language typedefs and enums used by this library. 5.1.4.4.3 MPLAB Harmony vs. the Unified TCP/IP Stack The following is a cross-reference of MPLAB Harmony functions and the equivalent Unified TCP/IP Stack function: 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-257 MPLAB Harmony Function: Unified Stack Function: DRV_ETHPHY_ClientStatus DRV_ETHPHY_Close DRV_ETHPHY_Deinitialize DRV_ETHPHY_HWConfigFlagsGet DRV_ETHPHY_Setup DRV_ETHPHY_Initialize DRV_ETHPHY_LinkScanRead DRV_ETHPHY_LinkScanStart DRV_ETHPHY_LinkScanStop DRV_ETHPHY_LinkStatusGet DRV_ETHPHY_NegotiationIsComplete DRV_ETHPHY_NegotiationResultGet DRV_ETHPHY_Open DRV_ETHPHY_Reinitialize DRV_ETHPHY_Reset DRV_ETHPHY_RestartNegotiation DRV_ETHPHY_SMIReadResultGet DRV_ETHPHY_SMIReadStart DRV_ETHPHY_SMIScanDataGet DRV_ETHPHY_SMIScanStart DRV_ETHPHY_SMIScanStatusGet DRV_ETHPHY_SMIScanStop DRV_ETHPHY_SMIWriteStart DRV_ETHPHY_SMIisBusy DRV_ETHPHY_Status DRV_ETHPHY_Tasks DRV_ETHPHY_VersionGet DRV_ETHPHY_VersionStrGet DRV_ETHPHY_SMIClockSet -none- -none- -noneEthPhyGetHwConfigFlags EthPhyInit -noneEthPhyScanLinkRead EthPhyScanLinkStart EthPhyScanLinkStop EthPhyGetLinkStatus EthPhyNegotiationComplete EthPhyGetNegotiationResult -none- -noneEthPhyReset EthPhyRestartNegotiation EthMIIMReadResult EthMIIMReadStart EthMIIMScanResult EthMIIMScanStart -none- -noneEthMIIMWriteStart -none- -none- -none- -none- -noneEthMIIMConfig 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-258 Unified Stack Function: MPLAB Harmony Function: EthMIIMConfig EthMIIMReadResult EthMIIMReadStart EthMIIMScanResult EthMIIMScanStart EthMIIMWriteStart EthPhyGetHwConfigFlags EthPhyGetLinkStatus EthPhyGetNegotiationResult EthPhyInit EthPhyNegotiationComplete EthPhyReset EthPhyRestartNegotiation EthPhyScanLinkRead EthPhyScanLinkStart EthPhyScanLinkStop -none- -none- -none- -none- -none- -none- -none- -none- -none- -none- -none- -none- -noneDRV_ETHPHY_SMIClockSet DRV_ETHPHY_SMIReadResultGet DRV_ETHPHY_SMIReadStart DRV_ETHPHY_SMIScanDataGet DRV_ETHPHY_SMIScanStart DRV_ETHPHY_SMIWriteStart DRV_ETHPHY_HWConfigFlagsGet DRV_ETHPHY_LinkStatusGet DRV_ETHPHY_NegotiationResultGet DRV_ETHPHY_Setup DRV_ETHPHY_NegotiationIsComplete DRV_ETHPHY_Reset DRV_ETHPHY_RestartNegotiation DRV_ETHPHY_LinkScanRead DRV_ETHPHY_LinkScanStart DRV_ETHPHY_LinkScanStop DRV_ETHPHY_ClientStatus DRV_ETHPHY_Close DRV_ETHPHY_Deinitialize DRV_ETHPHY_Initialize DRV_ETHPHY_Open DRV_ETHPHY_Reinitialize DRV_ETHPHY_SMIScanStatusGet DRV_ETHPHY_SMIScanStop DRV_ETHPHY_SMIisBusy DRV_ETHPHY_Status DRV_ETHPHY_Tasks DRV_ETHPHY_VersionGet DRV_ETHPHY_VersionStrGet 5.1.4.5 Configuring the Library Macros Name Description DRV_ETHPHY_CLIENTS_NUMBER Selects the miximum number of clients. DRV_ETHPHY_INDEX Ethernet PHY static index selection. DRV_ETHPHY_INDEX_0 Ethernet PHY driver index definitions. DRV_ETHPHY_INDEX_COUNT Number of valid Ethernet PHY driver indices. DRV_ETHPHY_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHPHY_PERIPHERAL_ID Defines an override of the peripheral ID. PHY_NEG_DONE_TMO negotiation complete timeout, ms. based on IEEE 802.3 Clause 28 Table 28-9 autoneg_wait_timer value (max 1s) PHY_NEG_INIT_TMO negotiation initiation timeout, ms. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-259 PHY_RESET_CLR_TMO reset self clear timeout, ms. IEEE 802.3 Clause 22 Table 22-7 and paragraph "22.2.4.1.1 Reset" (max 0.5s) TCPIP_IF_PIC32INT We have an internal PIC32 MAC Description The configuration of the Ethernet MAC Driver Library is based on the file sys_config.h This header file contains the configuration selection for the Ethernet MAC Driver Library. Based on the selections made, the Ethernet MAC Driver Library will support or not support selected features. These configuration settings will apply to all instances of the Ethernet MAC Driver Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.4.5.1 DRV_ETHPHY_CLIENTS_NUMBER Macro C #define DRV_ETHPHY_CLIENTS_NUMBER 1 Description Ethernet PHY Maximum Number of Clients This definition select the maximum number of clients that the Ethernet PHY driver can support at run time. Not defining it means using a single client. Remarks None. 5.1.4.5.2 DRV_ETHPHY_INDEX Macro C #define DRV_ETHPHY_INDEX DRV_ETHPHY_INDEX_1 Description Ethernet PHY Static Index Selection This definition selects the Ethernet PHY static index for the driver object reference. Remarks This index is required to make a reference to the driver object. 5.1.4.5.3 DRV_ETHPHY_INDEX_0 Macro C #define DRV_ETHPHY_INDEX_0 0 Description Ethernet PHY Driver Module Index Numbers These constants provide the Ethernet PHY driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-260 These values should be passed into the DRV_ETHPHY_Initialize and DRV_ETHPHY_Open routines to identify the driver instance in use. 5.1.4.5.4 DRV_ETHPHY_INDEX_COUNT Macro C #define DRV_ETHPHY_INDEX_COUNT 1 Description Ethernet PHY Driver Module Index Count This constant identifies the number of valid Ethernet PHY driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. 5.1.4.5.5 DRV_ETHPHY_INSTANCES_NUMBER Macro C #define DRV_ETHPHY_INSTANCES_NUMBER 1 Description Ethernet PHY hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Not defining it means using a static driver. Remarks None. 5.1.4.5.6 DRV_ETHPHY_PERIPHERAL_ID Macro C #define DRV_ETHPHY_PERIPHERAL_ID ETHPHY_ID_1 Description Ethernet PHY Peripheral ID Selection Defines an override of the peripheral ID, using macros. Remarks Some devices also support ETHPHY_ID_0 5.1.4.5.7 PHY_NEG_DONE_TMO Macro C #define PHY_NEG_DONE_TMO 2000 // negotiation complete timeout, ms. Description negotiation complete timeout, ms. based on IEEE 802.3 Clause 28 Table 28-9 autoneg_wait_timer value (max 1s) 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-261 5.1.4.5.8 PHY_NEG_INIT_TMO Macro C #define PHY_NEG_INIT_TMO 1 // negotiation initiation timeout, ms. Description negotiation initiation timeout, ms. 5.1.4.5.9 PHY_RESET_CLR_TMO Macro C #define PHY_RESET_CLR_TMO 500 // reset self clear timeout, ms. Description reset self clear timeout, ms. IEEE 802.3 Clause 22 Table 22-7 and paragraph "22.2.4.1.1 Reset" (max 0.5s) 5.1.4.5.10 TCPIP_IF_PIC32INT Macro C #define TCPIP_IF_PIC32INT Description We have an internal PIC32 MAC 5.1.4.6 Building the Library This section list the files that are available in the \src of the Ethernet PHY Driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.4.7 Library Interface Data Types and Constants Name Description DRV_ETHPHY_CLIENT_STATUS Identifies the client-specific status of the Ethernet PHY driver. DRV_ETHPHY_INIT Contains all the data necessary to initialize the Ethernet PHY device. SMI_SCAN_DATA_STATUS Returns the status of the SMI of the Ethernet PHY. SYS_OBJ_HANDLE_INVALID This is macro SYS_OBJ_HANDLE_INVALID. SYS_OBJ_HANDLE_STATIC This is macro SYS_OBJ_HANDLE_STATIC. SYS_OBJ_HANDLE SYS_MODULE_OBJ is badly named. It should be SYS_MODULE_OBJ_HANDLE or something shorter. For brevity, it is renamed to SYS_OBJ_HANDLE. Client Level Functions Name Description DRV_ETHPHY_ClientStatus Gets the current client-specific status the Ethernet PHY driver. DRV_ETHPHY_Close Closes an opened instance of the Ethernet PHY driver. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-262 DRV_ETHPHY_HWConfigFlagsGet Returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags. DRV_ETHPHY_LinkScanRead Returns current link status. DRV_ETHPHY_LinkScanStart Starts an SMI scan of the link status. DRV_ETHPHY_LinkScanStop Stops the SMI scan of the link status. DRV_ETHPHY_LinkStatusGet Returns the current link status. DRV_ETHPHY_NegotiationIsComplete Returns the results of a previously initiated Ethernet PHY negotiation. DRV_ETHPHY_NegotiationResultGet Returns the link status after a completed negotiation. DRV_ETHPHY_Open Opens the specified Ethernet PHY driver instance and returns a handle to it. DRV_ETHPHY_Reset Immediately resets the Ethernet PHY. DRV_ETHPHY_RestartNegotiation Restarts auto-negotiation of the Ethernet PHY link. DRV_ETHPHY_Setup Initializes Ethernet PHY communication. External PHY Support Functions Name Description EXTPHY_MDIXCONFIGURE Configures the MDIX mode for the Ethernet PHY. EXTPHY_MIICONFIGURE Configures the Ethernet PHY in one of the MII/RMII operation modes. EXTPHY_SMIADDRESSGET Returns the SMI/MIIM address of the Ethernet PHY. EXTPHY_SMICLOCKGET Returns the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. Other Functions Name Description DRV_ETHPHY_VersionGet Gets the Ethernet PHY driver version in numerical format. DRV_ETHPHY_VersionStrGet Gets the Ethernet PHY driver version in string format. SMI/MIIM Functions Name Description DRV_ETHPHY_SMIClockSet Sets the SMI/MIIM interface clock. DRV_ETHPHY_SMIisBusy Returns a boolean 'true' if the SMI/MIIM interface is busy with a transaction. DRV_ETHPHY_SMIReadResultGet Gets the result of the SMI/MIIM register read. DRV_ETHPHY_SMIReadStart Initiates SMI/MIIM read transaction. DRV_ETHPHY_SMIScanDataGet Gets the latest SMI/MIIM scan data result. DRV_ETHPHY_SMIScanStart Starts the scan of the SMI/MIIM register. DRV_ETHPHY_SMIScanStatusGet Gets the status of the SMI/MIIM scan data. DRV_ETHPHY_SMIScanStop Stops the scan of the SMI/MIIM register. DRV_ETHPHY_SMIWriteStart Initiates a SMI/MIIM write transaction. System Level Functions Name Description DRV_ETHPHY_Deinitialize Deinitializes the specified instance of the Ethernet PHY driver module. DRV_ETHPHY_Initialize Initializes the Ethernet PHY driver. DRV_ETHPHY_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_ETHPHY_Status Provides the current status of the Ethernet PHY driver module. DRV_ETHPHY_Tasks Maintains the driver's state machine and implements its ISR. Description This section describes the Application Programming Interface (API) functions of the Ethernet PHY Driver Library. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-263 Refer to each section for a detailed description. 5.1.4.7.1 System Level Functions 5.1.4.7.1.1 DRV_ETHPHY_Deinitialize Function C void DRV_ETHPHY_Deinitialize( SYS_OBJ_HANDLE object ); Description This function deinitializes the specified instance of the Ethernet PHY driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this routine and a valid SYS_OBJ_HANDLE must have been returned. Parameters Parameters Description object Driver object handle, returned from DRV_ETHPHY_Initialize Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Example SYS_OBJ_HANDLE object; // Returned from DRV_ETHPHY_Initialize SYS_STATUS status; DRV_ETHPHY_Deinitialize(object); status = DRV_ETHPHY_Status(object); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.4.7.1.2 DRV_ETHPHY_Initialize Function C SYS_OBJ_HANDLE DRV_ETHPHY_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Description This function initializes the Ethernet PHY driver, making it ready for clients to open and use it. Preconditions None. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-264 Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_OBJ_HANDLE_INVALID. The returned object must be passed as argument to DRV_ETHPHY_Reinitialize, DRV_ETHPHY_Deinitialize, DRV_ETHPHY_Tasks and DRV_ETHPHY_Status routines. Remarks This function must be called before any other Ethernet PHY routine is called. This function should only be called once during system initialization unless DRV_ETHPHY_Deinitialize is called to de-initialize the driver instance. Example DRV_ETHPHY_INIT init; SYS_OBJ_HANDLE objectHandle; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_0; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_2; init.sExtPHYFunctions.MyPHYMIIConfigure = &SMSC8720_MIIConfigure; init.sExtPHYFunctions.MyPHYMDIXConfigure = &SMSC8720_MDIXConfiguret; init.sExtPHYFunctions.MyPHYSMIAddressGet = &SMSC8720_SMIAddressGet; init.sExtPHYFunctions.MyPHYSMIClockGet = &SMSC8720_SMIClockGet; // Do something objectHandle = DRV_ETHPHY_Initialize(DRV_ETHPHY_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_OBJ_HANDLE_INVALID == objectHandle) { // Handle error } 5.1.4.7.1.3 DRV_ETHPHY_Reinitialize Function C void DRV_ETHPHY_Reinitialize( SYS_OBJ_HANDLE object, const SYS_MODULE_INIT * const init ); Description This function reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this routine and a valid SYS_OBJ_HANDLE must have been returned. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-265 Parameters Parameters Description object Driver object handle, returned from the DRV_ETHPHY_Initialize routine init Pointer to the initialization data structure Returns None. Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. Example DRV_ETHPHY_INIT init; SYS_OBJ_HANDLE objectHandle; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_2; init.sExtPHYFunctions.MyPHYMIIConfigure = &SMSC8720_MIIConfigure; init.sExtPHYFunctions.MyPHYMDIXConfigure = &SMSC8720_MDIXConfiguret; init.sExtPHYFunctions.MyPHYSMIAddressGet = &SMSC8720_SMIAddressGet; init.sExtPHYFunctions.MyPHYSMIClockGet = &SMSC8720_SMIClockGet; DRV_ETHPHY_Reinitialize(objectHandle, (SYS_MODULE_INIT*)&init); phyStatus = DRV_ETHPHY_Status(objectHandle); if (SYS_STATUS_BUSY == phyStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= phyStatus) { // Handle error } 5.1.4.7.1.4 DRV_ETHPHY_Status Function C SYS_STATUS DRV_ETHPHY_Status( SYS_OBJ_HANDLE object ); Description This function provides the current status of the Ethernet PHY driver module. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from DRV_ETHPHY_Initialize Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-266 Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR. The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_OBJ_HANDLE object; // Returned from DRV_ETHPHY_Initialize SYS_STATUS status; status = DRV_ETHPHY_Status(object); else if (SYS_STATUS_ERROR >= status) { // Handle error } 5.1.4.7.1.5 DRV_ETHPHY_Tasks Function C void DRV_ETHPHY_Tasks( SYS_OBJ_HANDLE object ); Description This function is used to maintain the driver's internal state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_ETHPHY_Initialize routine must have been called for the specified Ethernet PHY driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_ETHPHY_Initialize) Returns None Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-267 apropriate raw ISR. This function may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_OBJ_HANDLE object; // Returned from DRV_ETHPHY_Initialize while (true) { DRV_ETHPHY_Tasks (object); // Do other tasks } 5.1.4.7.2 Client Level Functions 5.1.4.7.2.1 DRV_ETHPHY_ClientStatus Function C DRV_ETHPHY_CLIENT_STATUS DRV_ETHPHY_ClientStatus( DRV_HANDLE handle ); Description This function gets the client-specfic status of the Ethernet PHY driver associated with the given handle. Preconditions The DRV_ETHPHY_Initialize routine must have been called. DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_ETHPHY_CLIENT_STATUS value describing the current status of the driver. Remarks This function will not block for hardware access and will immediately return the current status. Example DRV_HANDLE phyHandle; // Returned from DRV_ETHPHY_Open DRV_ETHPHY_CLIENT_STATUS phyClientStatus; phyClientStatus = DRV_ETHPHY_ClientStatus(phyHandle); if(DRV_ETHPHY_CLIENT_STATUS_ERROR >= phyClientStatus) { // Handle the error } 5.1.4.7.2.2 DRV_ETHPHY_Close Function C void DRV_ETHPHY_Close( DRV_HANDLE handle ); 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-268 Description This function closes an opened instance of the Ethernet PHY driver, invalidating the handle. Preconditions The DRV_ETHPHY_Initialize routine must have been called for the specified Ethernet PHY driver instance. DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open instance handle, returned from the driver's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_ETHPHY_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_ETHPHY_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_ETHPHY_Open DRV_ETHPHY_Close(handle); 5.1.4.7.2.3 DRV_ETHPHY_HWConfigFlagsGet Function C ETHPHY_CONFIG_FLAGS DRV_ETHPHY_HWConfigFlagsGet( DRV_HANDLE handle ); Description This function returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags from the Device Configuration Fuse bits. Preconditions None. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns Ethernet PHY configuration flag, see ETHPHY_CONFIG_FLAGS enumeration for bit values. Remarks Please note, 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-269 • ETHPHY_CONFIG_FLAGS DRV_ETHPHY_HWConfigFlagsGet( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • eEthPhyCfgFlags EthPhyGetHwConfigFlags(void) Example 5.1.4.7.2.4 DRV_ETHPHY_LinkScanRead Function C ETH_LINK_STATUS DRV_ETHPHY_LinkScanRead( DRV_HANDLE handle ); Description This function returns the current link status. Preconditions DRV_ETHPHY_LinkScanStart must be called first. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns Current link status, see ETH_LINK_STATUS enumeration. Remarks See also DRV_ETHPHY_LinkStatusGet. Please note, • ETH_LINK_STATUS DRV_ETHPHY_LinkScanRead( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • eEthLinkStat EthPhyScanLinkRead(void) Example 5.1.4.7.2.5 DRV_ETHPHY_LinkScanStart Function C void DRV_ETHPHY_LinkScanStart( DRV_HANDLE handle ); Description This function starts an SMI scan of the link status. Preconditions Communication with the Ethernet PHY was already established. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-270 Returns None. Remarks This function starts an SMII scan of the Ethernet PHY link status register. It is a more efficient way of having access to the current link status, since the normal SMI frame read operation is slow. Please note, • void DRV_ETHPHY_LinkScanStart( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • void EthPhyScanLinkStart(void) Example 5.1.4.7.2.6 DRV_ETHPHY_LinkScanStop Function C void DRV_ETHPHY_LinkScanStop( DRV_HANDLE handle ); Description This function stops the SMI scan of the ink status. Preconditions Communication with the Ethernet PHY was already established. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns None. Remarks Please note, • void DRV_ETHPHY_LinkScanStop( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • void EthPhyScanLinkStop(void) Example 5.1.4.7.2.7 DRV_ETHPHY_LinkStatusGet Function C ETH_LINK_STATUS DRV_ETHPHY_LinkStatusGet( DRV_HANDLE handle, bool refresh ); Description This function returns the urrent link status. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-271 Preconditions DRV_ETHPHY_Setup should have been called. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) refresh Boolean flag, true to specify that a double read is needed Returns Current link status, see ETH_LINK_STATUS enumeration. Remarks This function reads the Ethernet PHY to get current link status If refresh is specified then, if the link is down a second read will be performed to return the current link status. Please note, • ETH_LINK_STATUS DRV_ETHPHY_LinkStatusGet( DRV_HANDLE handle, bool refresh ) replaces the legacy "Ethernet Controller Library" function: • eEthLinkStat EthPhyGetLinkStatus(int refresh) Example 5.1.4.7.2.8 DRV_ETHPHY_NegotiationIsComplete Function C ETH_RESULT_CODE DRV_ETHPHY_NegotiationIsComplete( DRV_HANDLE handle, bool waitComplete ); Description This function returns the results of a previously initiated Ethernet PHY negotiation. Preconditions DRV_ETHPHY_Setup (and DRV_ETHPHY_RestartNegotiation) should have been called. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) waitComplete Boolean flag, true if wait for completion is required Returns ETH_RES_OK if negotiation is done, ETH_RES_NEGOTIATION_INACTIVE if no negotiation in progress, ETH_RES_NEGOTIATION_NOT_STARTED if negotiation not yet started yet (means tmo if waitComplete was requested), or ETH_RES_NEGOTIATION_ACTIVE if negotiation ongoing (means tmo if waitComplete was requested). Remarks See also DRV_ETHPHY_NegotiationResultGet. Please note, • ETH_RESULT_CODE DRV_ETHPHY_NegotiationIsComplete( DRV_HANDLE handle, bool waitComplete ) replaces the legacy "Ethernet Controller Library" function: 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-272 • eEthRes EthPhyNegotiationComplete(int waitComplete) Example 5.1.4.7.2.9 DRV_ETHPHY_NegotiationResultGet Function C ETH_LINK_STATUS DRV_ETHPHY_NegotiationResultGet( DRV_HANDLE handle, ETH_OPEN_FLAGS* pFlags, ETH_PAUSE_TYPE* pPauseType ); Description This function returns the link status after a completed negotiation. Preconditions DRV_ETHPHY_Setup, DRV_ETHPHY_RestartNegotiation, and DRV_ETHPHY_NegotiationIsComplete should have been called. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) pFlags Address to store the negotiation result pPauseType Address to store the pause type supported by the link partner Returns Link status after the (completed) negotiation, see ETH_LINK_STATUS enumeration. Remarks If no negotiation possible/active/failed, most likely the flags are invalid! Please note, • ETH_LINK_STATUS DRV_ETHPHY_NegotiationResultGet( DRV_HANDLE handle, ETH_OPEN_FLAGS* pFlags, ETH_PAUSE_TYPE* pPauseType ) replaces the legacy "Ethernet Controller Library" function: • eEthLinkStat EthPhyGetNegotiationResult(eEthOpenFlags* pFlags, eEthMacPauseType* pPauseType) Example 5.1.4.7.2.10 DRV_ETHPHY_Open Function C DRV_HANDLE DRV_ETHPHY_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); Description This function opens the specified Ethernet PHY driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this function. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-273 Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_ETHPHY_Close routine is called. This function will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_ETHPHY_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. Example DRV_HANDLE handle; handle = DRV_ETHPHY_Open(DRV_ETHPHY_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.4.7.2.11 DRV_ETHPHY_Reset Function C bool DRV_ETHPHY_Reset( DRV_HANDLE handle, bool waitComplete ); Description This function immediately resets the Ethernet PHY, optionally waiting for a reset to complete. Preconditions Communication with the Ethernet PHY was already established. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) waitComplete boolean flag, if true the procedure will wait for reset to complete Returns True - If PHY reset procedure completed (or completion not required) False - Otherwise Remarks Please note, 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-274 • bool DRV_ETHPHY_Reset( DRV_HANDLE handle, bool waitComplete ) replaces the legacy "Ethernet Controller Library" function: • int EthPhyReset(int waitComplete) Example 5.1.4.7.2.12 DRV_ETHPHY_RestartNegotiation Function C void DRV_ETHPHY_RestartNegotiation( DRV_HANDLE handle ); Description This function restarts auto-negotiation of the Ethernet PHY link. Preconditions The Ethernet PHY should have been initialized with the proper duplex/speed mode. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns None. Remarks Please note, • void DRV_ETHPHY_RestartNegotiation( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • eEthRes EthPhyRestartNegotiation(void) Example 5.1.4.7.2.13 DRV_ETHPHY_Setup Function C ETH_RESULT_CODE DRV_ETHPHY_Setup( DRV_HANDLE handle, ETH_OPEN_FLAGS oFlags, ETHPHY_CONFIG_FLAGS cFlags, ETH_OPEN_FLAGS * pResFlags ); Description This function initializes the Ethernet PHY communication. It tries to detect the external Ethernet PHY, to read the capabilties and find a match with the requested features.Then it programs the Ethernet PHY accordingly. Preconditions DRV_ETHMAC_LegacyInit should have been called to initialize the Ethernet MAC. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-275 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine oFlags The requested open flags cFlags Ethernet PHY MII/RMII configuration flags pResFlags Address to store the initialization results Returns ETH_RES_OK for success; otherwise, an error code. Remarks Please note, • ETH_RESULT_CODE DRV_ETHPHY_Setup( DRV_HANDLE handle, ETH_OPEN_FLAGS oFlags, ETHPHY_CONFIG_FLAGS cFlags, ETH_OPEN_FLAGS* pResFlags ) replaces the legacy "Ethernet Controller Library" function: • eEthRes EthPhyInit(eEthOpenFlags oFlags, eEthPhyCfgFlags cFlags, eEthOpenFlags* pResFlags) Example 5.1.4.7.3 SMI/MIIM Functions 5.1.4.7.3.1 DRV_ETHPHY_SMIClockSet Function C void DRV_ETHPHY_SMIClockSet( DRV_HANDLE handle, uint32_t hostClock, uint32_t maxSMIClock ); Description This function sets SMI/MIIM interface clock base on host clock and maximum supported SMI/MIIM interface clock speed. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) hostClock Host clock speed in Hz maxSMIClock Maximum supported SMI/MIIM clock speed in Hz Returns None. Remarks Please note, • void DRV_ETHPHY_SMIClockSet( DRV_HANDLE handle, uint16_t hostClock, uint16_t maxSMIClock ) replaces the legacy "Ethernet Controller Library" function: • void EthMIIMConfig(unsigned int hostClock, unsigned int miimClock) Example 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-276 5.1.4.7.3.2 DRV_ETHPHY_SMIisBusy Function C bool DRV_ETHPHY_SMIisBusy( DRV_HANDLE handle ); Description This function returns a boolean 'true' if the SMI/MIIM interface is busy with a transaction. Preconditions MyPHYSMIClockSet() called to setup SMI/MIIM clock. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns • true - If the SMI/MIIM is busy • false - If the SMI/MIIM is not busy Example 5.1.4.7.3.3 DRV_ETHPHY_SMIReadResultGet Function C uint16_t DRV_ETHPHY_SMIReadResultGet( DRV_HANDLE handle ); Description This function gets the result of the SMI/MIIM register read. Preconditions MyPHYSMIClockSet was called to set up the SMI/MIIM clock and DRV_ETHPHY_SMIReadStart was called to initiate a SMI/MIIM register read. DRV_ETHPHY_SMIisBusy should return false. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns Result of the SMI/MIIM register read previously scheduled. Remarks Please note, • uint16_t DRV_ETHPHY_SMIReadResultGet( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • unsigned short EthMIIMReadResult ( void ) Example 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-277 5.1.4.7.3.4 DRV_ETHPHY_SMIReadStart Function C void DRV_ETHPHY_SMIReadStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd ); Description This function initiates SMI/MIIM read transaction for a given PHY address and register. Preconditions MyPHYSMIClockSet was called to set up the SMI/MIIM clock. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) rIx PHY register to be accessed phyAdd Address of PHY to be accessed Returns None. Remarks Please note, • void DRV_ETHPHY_SMIReadStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd ) replaces the legacy "Ethernet Controller Library" function: • void EthMIIMReadStart(unsigned int rIx, unsigned int phyAdd) Example 5.1.4.7.3.5 DRV_ETHPHY_SMIScanDataGet Function C uint16_t DRV_ETHPHY_SMIScanDataGet( DRV_HANDLE handle ); Description This functino gets the latest SMI/MIIM scan data result. Preconditions DRV_ETHPHY_SMIScanStart() has been called. DRV_ETHPHY_SMIScanStatusGet() should return SMI_SCAN_DATA_VALID. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns Current scan result. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-278 Remarks Scan data status must be SMI_SCAN_DATA_VALID. Please note, • uint16_t DRV_ETHPHY_SMIScanDataGet( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • unsigned short EthMIIMScanResult(void) Example 5.1.4.7.3.6 DRV_ETHPHY_SMIScanStart Function C void DRV_ETHPHY_SMIScanStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd ); Description This function starts the scan of the SMI/MIIM register. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) rIx PHY register to be accessed, 0-31 phyAdd PHY address, 0-31 Returns None. Remarks Please note, • void DRV_ETHPHY_SMIScanStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd ) replaces the legacy "Ethernet Controller Library" function: • void EthMIIMScanStart(unsigned int rIx, unsigned int phyAdd) Example 5.1.4.7.3.7 DRV_ETHPHY_SMIScanStatusGet Function C SMI_SCAN_DATA_STATUS DRV_ETHPHY_SMIScanStatusGet( DRV_HANDLE handle ); Description This function gets the status of the SMI/MIIM scan data. Preconditions DRV_ETHPHY_SMIScanStart() has been called. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-279 Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns SMI_SCAN_DATA_NOTVALID or SMI_SCAN_DATA_VALID Remarks None. Example 5.1.4.7.3.8 DRV_ETHPHY_SMIScanStop Function C void DRV_ETHPHY_SMIScanStop( DRV_HANDLE handle ); Description This function stops the scan of the SMI/MIIM register. Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) Returns None. Remarks Stops a scan transaction on the SMI interface. Please note, • void DRV_ETHPHY_SMIScanStop( DRV_HANDLE handle ) replaces the legacy "Ethernet Controller Library" function: • void EthMIIMScanStop ( void ) Example 5.1.4.7.3.9 DRV_ETHPHY_SMIWriteStart Function C void DRV_ETHPHY_SMIWriteStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, uint16_t wData ); Description This function initiates SMI/MIIM write transaction for a given PHY address and register. Preconditions MyPHYSMIClockSet was called to set up the SMI/MIIM clock. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-280 Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) rIx PHY register to be accessed phyAdd Address of PHY to be accessed wData Data to be written Returns None. Remarks Please note, • void DRV_ETHPHY_SMIWriteStart( DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, uint16_t wData ) replaces the legacy "Ethernet Controller Library" function: • void EthMIIMWriteStart(unsigned int rIx, unsigned int phyAdd, unsigned short wData) Example 5.1.4.7.4 External PHY Support Functions 5.1.4.7.4.1 EXTPHY_MDIXCONFIGURE Type C typedef ETH_RESULT_CODE (* EXTPHY_MDIXCONFIGURE)(DRV_HANDLE handle, ETH_OPEN_FLAGS oFlags); Description Pointer To Function: ETH_RESULT_CODE EXTPHY_MDIXConfigure( DRV_HANDLE handle, ETH_OPEN_FLAGS oFlags ) Configures the MDIX mode for the Ethernet PHY. Preconditions Communication to the PHY should have been established. Parameters Parameters Description handle Client's driver handle (returned from DRV_PHY_Open) oFlags Requested open flags: ETH_OPEN_MDIX_AUTO, ETH_OPEN_MDIX_NORM, or ETH_OPEN_MDIX_NORM | ETH_OPEN_MDIX_SWAP Returns ETH_RES_OK - if success; otherwise, ETH_RES_CFG_ERR. Remarks For some external PHYs, the MDIX configuration is set by pins on the device. In this case, the function will return ETH_RES_OK if the cFlags requests the already configured interface; otherwise, ETH_RES_CFG_ERR. 5.1.4.7.4.2 EXTPHY_MIICONFIGURE Type C typedef ETH_RESULT_CODE (* EXTPHY_MIICONFIGURE)(DRV_HANDLE handle, ETHPHY_CONFIG_FLAGS cFlags); 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-281 Description Pointer To Function: ETH_RESULT_CODE EXTPHY_MIIConfigure( DRV_HANDLE handle, ETHPHY_CONFIG_FLAGS cFlags ) Configures the Ethernet PHY in one of the MII/RMII operation modes. Preconditions Communication to the PHY should have been established. Parameters Parameters Description handle Client's driver handle (returned from DRV_PHY_Open) cFlags Requested configuration flags: ETH_PHY_CFG_RMII or ETH_PHY_CFG_MII Returns ETH_RES_OK - if success; otherwise, ETH_RES_CFG_ERR. Remarks For some external PHYs, the data interface is set by pins on the device or fuses in the host. In this case, the function will return ETH_RES_OK if the cFlags requests the already configured interface; otherwise, ETH_RES_CFG_ERR. 5.1.4.7.4.3 EXTPHY_SMIADDRESSGET Type C typedef unsigned int (* EXTPHY_SMIADDRESSGET)(DRV_HANDLE handle); Description Pointer To Function: uint16_t EXTPHY_SMIAddressGet( DRV_HANDLE handle ); Returns the SMI/MIIM address of the Ethernet PHY. Preconditions Communication to the PHY should have been established. Parameters Parameters Description handle Client's driver handle (returned from DRV_PHY_Open) Returns The SMI/MIIM Ethernet PHY address as an unsigned 16-bit integer. Remarks For some external PHYs, the MDIX configuration is set by pins on the device. In this case, the function will return ETH_RES_OK if the cFlags requests the already configured interface; otherwise, ETH_RES_CFG_ERR. 5.1.4.7.4.4 EXTPHY_SMICLOCKGET Type C typedef unsigned int (* EXTPHY_SMICLOCKGET)(DRV_HANDLE handle); Description Pointer to Function: uint16_t EXTPHY_SMIClockGet( DRV_HANDLE handle ); Returns the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-282 Preconditions Communication to the PHY should have been established. Parameters Parameters Description handle Client's driver handle (returned from DRV_PHY_Open) Returns The maximum SMI/MIIM clock speed as an unsigned 16-bit integer. Remarks For some external PHYs, the MDIX configuration is set by pins on the device. In this case, the function will return ETH_RES_OK if the cFlags requests the already configured interface; otherwise, ETH_RES_CFG_ERR. 5.1.4.7.5 Other Functions 5.1.4.7.5.1 DRV_ETHPHY_VersionGet Function C unsigned int DRV_ETHPHY_VersionGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the Ethernet PHY driver version. The version is encoded as major * 10000 + minor * 100 + patch. The stringed version can be obtained using DRV_ETHPHY_VersionStrGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for Returns Current driver version in numerical format. Remarks None. Example unsigned int version; version = DRV_ETHPHY_VersionGet( DRV_ETHPHY_INDEX_1 ); if(version < 110200) { // Do Something } 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-283 5.1.4.7.5.2 DRV_ETHPHY_VersionStrGet Function C char * DRV_ETHPHY_VersionStrGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the Ethernet PHY driver version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using DRV_ETHPHY_VersionGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for. Returns Current Ethernet PHY driver version in the string format. Remarks None. Example char *version; version = DRV_ETHPHY_VersionStrGet( DRV_ETHPHY_INDEX_1 ); printf("%s", version); 5.1.4.7.6 Data Types and Constants 5.1.4.7.6.1 DRV_ETHPHY_CLIENT_STATUS Enumeration C typedef enum { DRV_ETHPHY_CLIENT_STATUS_ERROR, DRV_ETHPHY_CLIENT_STATUS_CLOSED, DRV_ETHPHY_CLIENT_STATUS_BUSY, DRV_ETHPHY_CLIENT_STATUS_READY } DRV_ETHPHY_CLIENT_STATUS; Description Ethernet PHY Driver Client Status This enumeration identifies the client-specific status of the Ethernet PHY driver. Members Members Description DRV_ETHPHY_CLIENT_STATUS_ERROR Unspecified error condition DRV_ETHPHY_CLIENT_STATUS_CLOSED Client is not open DRV_ETHPHY_CLIENT_STATUS_BUSY An operation is currently in progress DRV_ETHPHY_CLIENT_STATUS_READY Up and running, no operations running 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-284 Remarks None. 5.1.4.7.6.2 DRV_ETHPHY_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; ETH_MODULE_ID ethphyId; EXTPHY_MIICONFIGURE MyPHYMIIConfigure; EXTPHY_MDIXCONFIGURE MyPHYMDIXConfigure; EXTPHY_SMIADDRESSGET MyPHYSMIAddressGet; EXTPHY_SMICLOCKGET MyPHYSMIClockGet; } DRV_ETHPHY_INIT; Description Ethernet PHY Device Driver Initialization Data This structure contains all the data necessary to initialize the Ethernet PHY device. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization ETH_MODULE_ID ethphyId; Identifies peripheral (PLIB-level) ID EXTPHY_MIICONFIGURE MyPHYMIIConfigure; Select MII or RMII data interface EXTPHY_MDIXCONFIGURE MyPHYMDIXConfigure; AutoMDIX or Manual MDIX EXTPHY_SMIADDRESSGET MyPHYSMIAddressGet; Returns PHY's SMI Address EXTPHY_SMICLOCKGET MyPHYSMIClockGet; Returns PHY's clock speed Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_ETHPHY_Initialize routine. 5.1.4.7.6.3 SMI_SCAN_DATA_STATUS Enumeration C typedef enum { SMI_SCAN_DATA_NOTVALID, SMI_SCAN_DATA_VALID } SMI_SCAN_DATA_STATUS; Description SMI Interface Scan Data Status Enumeration This enumeration returns the status of the SMI of the Ethernet PHY. Members Members Description SMI_SCAN_DATA_NOTVALID SMI interface ready for new scan/read/write SMI_SCAN_DATA_VALID SMI interface ready for new scan/read/write 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-285 Remarks None. 5.1.4.7.6.4 SYS_OBJ_HANDLE_INVALID Macro C #define SYS_OBJ_HANDLE_INVALID ( (SYS_OBJ_HANDLE) -1 ) Description This is macro SYS_OBJ_HANDLE_INVALID. 5.1.4.7.6.5 SYS_OBJ_HANDLE_STATIC Macro C #define SYS_OBJ_HANDLE_STATIC ( (SYS_OBJ_HANDLE) 0 ) Description This is macro SYS_OBJ_HANDLE_STATIC. 5.1.4.7.6.6 SYS_OBJ_HANDLE Type C typedef uintptr_t SYS_OBJ_HANDLE; Description SYS_MODULE_OBJ Rename SYS_MODULE_OBJ is badly named. It should be SYS_MODULE_OBJ_HANDLE or something shorter. For brevity, it is renamed to SYS_OBJ_HANDLE. Remarks None. 5.1.4.8 Files Files Name Description drv_ethphy.h Ethernet ETHPHY Device Driver Interface File drv_ethphy_config.h Ethernet PHY driver configuration definitions template. Description 5.1.4.8.1 drv_ethphy.h Ethernet ETHPHY Device Driver Interface The Ethernet ETHPHY device driver provides a simple interface to manage an Ethernet ETHPHY peripheral using MIIM (or SMI) interface. This file defines the interface definitions and prototypes for the Etherent ETHPHY driver. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-286 Enumerations Name Description DRV_ETHPHY_CLIENT_STATUS Identifies the client-specific status of the Ethernet PHY driver. SMI_SCAN_DATA_STATUS Returns the status of the SMI of the Ethernet PHY. Functions Name Description DRV_ETHPHY_ClientStatus Gets the current client-specific status the Ethernet PHY driver. DRV_ETHPHY_Close Closes an opened instance of the Ethernet PHY driver. DRV_ETHPHY_Deinitialize Deinitializes the specified instance of the Ethernet PHY driver module. DRV_ETHPHY_HWConfigFlagsGet Returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags. DRV_ETHPHY_Initialize Initializes the Ethernet PHY driver. DRV_ETHPHY_LinkScanRead Returns current link status. DRV_ETHPHY_LinkScanStart Starts an SMI scan of the link status. DRV_ETHPHY_LinkScanStop Stops the SMI scan of the link status. DRV_ETHPHY_LinkStatusGet Returns the current link status. DRV_ETHPHY_NegotiationIsComplete Returns the results of a previously initiated Ethernet PHY negotiation. DRV_ETHPHY_NegotiationResultGet Returns the link status after a completed negotiation. DRV_ETHPHY_Open Opens the specified Ethernet PHY driver instance and returns a handle to it. DRV_ETHPHY_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_ETHPHY_Reset Immediately resets the Ethernet PHY. DRV_ETHPHY_RestartNegotiation Restarts auto-negotiation of the Ethernet PHY link. DRV_ETHPHY_Setup Initializes Ethernet PHY communication. DRV_ETHPHY_SMIClockSet Sets the SMI/MIIM interface clock. DRV_ETHPHY_SMIisBusy Returns a boolean 'true' if the SMI/MIIM interface is busy with a transaction. DRV_ETHPHY_SMIReadResultGet Gets the result of the SMI/MIIM register read. DRV_ETHPHY_SMIReadStart Initiates SMI/MIIM read transaction. DRV_ETHPHY_SMIScanDataGet Gets the latest SMI/MIIM scan data result. DRV_ETHPHY_SMIScanStart Starts the scan of the SMI/MIIM register. DRV_ETHPHY_SMIScanStatusGet Gets the status of the SMI/MIIM scan data. DRV_ETHPHY_SMIScanStop Stops the scan of the SMI/MIIM register. DRV_ETHPHY_SMIWriteStart Initiates a SMI/MIIM write transaction. DRV_ETHPHY_Status Provides the current status of the Ethernet PHY driver module. DRV_ETHPHY_Tasks Maintains the driver's state machine and implements its ISR. DRV_ETHPHY_VersionGet Gets the Ethernet PHY driver version in numerical format. DRV_ETHPHY_VersionStrGet Gets the Ethernet PHY driver version in string format. Macros Name Description DRV_ETHPHY_INDEX_0 Ethernet PHY driver index definitions. DRV_ETHPHY_INDEX_1 This is macro DRV_ETHPHY_INDEX_1. DRV_ETHPHY_INDEX_COUNT Number of valid Ethernet PHY driver indices. 5.1 Driver Library Help MPLAB Harmony Help Ethernet PHY Driver Library 5-287 Structures Name Description DRV_ETHPHY_INIT Contains all the data necessary to initialize the Ethernet PHY device. Types Name Description EXTPHY_MDIXCONFIGURE Configures the MDIX mode for the Ethernet PHY. EXTPHY_MIICONFIGURE Configures the Ethernet PHY in one of the MII/RMII operation modes. EXTPHY_SMIADDRESSGET Returns the SMI/MIIM address of the Ethernet PHY. EXTPHY_SMICLOCKGET Returns the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. Company Microchip Technology Incorported FileName: drv_ethphy.h 5.1.4.8.2 drv_ethphy_config.h Ethernet PHY Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. Macros Name Description DRV_ETHPHY_CLIENTS_NUMBER Selects the miximum number of clients. DRV_ETHPHY_INDEX Ethernet PHY static index selection. DRV_ETHPHY_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHPHY_PERIPHERAL_ID Defines an override of the peripheral ID. PHY_NEG_DONE_TMO negotiation complete timeout, ms. based on IEEE 802.3 Clause 28 Table 28-9 autoneg_wait_timer value (max 1s) PHY_NEG_INIT_TMO negotiation initiation timeout, ms. PHY_RESET_CLR_TMO reset self clear timeout, ms. IEEE 802.3 Clause 22 Table 22-7 and paragraph "22.2.4.1.1 Reset" (max 0.5s) TCPIP_IF_PIC32INT We have an internal PIC32 MAC File Name drv_ethphy_config.h Company Microchip Technology Inc. 5.1.4.8.3 drv_ethernet_flags.h This file can be accessed through the following link: drv_ethernet_flags.h 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-288 5.1.5 Graphics (GFX) Driver Library 5.1.5.1 Introduction Graphics (GFX) Driver Library for Microchip Microcontrollers The Graphics (GFX) Driver Layer Library is the GFX library stack available for the Microchip family of microcontrollers. Description The MPLAB Harmony Graphics (GFX) Library is highly modular and is optimized for Microchip’s 32-bit microcontrollers. Additionally, the library is free for Microchip customers, easy to use, and has an open documented interface for new driver support, which requires creation of only one C file. 5.1.5.2 Release Notes MPLAB Harmony Version: v0.70b Graphics (GFX) Driver Layer Library Version : 4.00b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-289 5.1.5.4 Using the Library 5.1.5.4.1 Abstraction Model The Graphics Driver Library structure consists of the following: • Application Layer – This is the program that utilizes the Graphics Driver Library • User Message Interface- This layer should be implemented by user to provide messages for the library • Graphics Object Layer – This layer renders the widgets controls such as button, slider, window, and so on • Graphics Primitives Layer – This layer implements the primitive drawing functions • Device Display Driver – This layer is dependent on the display device being used • Graphics Display Module – This is the display device being used The library provides two configurations (Blocking and Non-Blocking). For a Blocking configuration, all draw functions are blocking calls that delay the execution of program until rendering is done. For a Non-Blocking configuration, draw functions do not wait for the drawing completion and release control to the program. In this configuration, a draw function should be called repeatedly until the rendering of that particular draw function is complete. This allows efficient use of microcontroller CPU time since it can perform other tasks if the rendering is not yet done. 5.1.5.4.2 Library Overview This layer informs the GFX library on which graphics controller is being used along with the LCD. It takes input only from the primitive layer. This layer contains all the hardware specific functions the primitive layer needs to render primitives onto the LCD. Each driver contained in the GFX library has a build time structure associated with it that informs the primitive layer which hardware specific functions are available. Thus when the primitive layer calls a specific rendering task it gets passed a pointer from the driver of that task. If the task does not exist the driver passes back a NULL and the primitive layer and either render the primitive without hardware support or let the application know that this feature is not available. 5.1.5.5 Configuring the Library The configuration of the GFX driver is based on the file drv_gfx_config.h This header file contains the configuration selection for the GFX Driver. Based on the selections made, the GFX Driver will support or not support selected features. These configuration settings will apply to all instances of the GFX Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. The configuration of the GFX driver layer is mainly dependent on making sure the needed driver has the core driver functions inside of it. The main rendering one being a PixelPut type function for the GFX primitive layer. Once the GFX driver structure (GFX_DRV_DATA) is defined along with its primitive function rendering structure (GFX_DRV_FUNCTIONS) it can be used by the GFX primitive layer. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-290 5.1.5.6 Building the Library This section lists the files that are available in the /src folder of the GFX driver. It lists which files need to be included in the build based on either a hardware feature present on the board or a configuration option selected by the system. 5.1.5.7 Library Interface Data Types and Constants Name Description GFX_DRV_DATA Structure containing the driver graphics controller data. GFX_DRV_FUNCTIONS Structure containing the driver functions used by the primitive layer. LAYER_TYPE types of Layers supported by the GFX Library PAGE_TYPE types of pages supported by the GFX Library NUM_ALPHA_LEVELS Specific to device ALPHA_DELTA This is macro ALPHA_DELTA. GFX_CONFIG_DRIVER_COUNT This is macro GFX_CONFIG_DRIVER_COUNT. GFX_ALPHA_PARAMS This is type GFX_ALPHA_PARAMS. GFX_LAYER_PARAMS This is type GFX_LAYER_PARAMS. System Functions Name Description Percentage2Alpha DriverInterfaceInit This is function DriverInterfaceInit. Description All of the drivers in the GFX library must follow certain guidelines to be used by the GFX Primitve. These guidelines are defined in gfx_gol_display_driver.h The GFX primitve calls function pointers to reference a particular GFX driver function. If the function does not exist for a particular driver (ie Alpha Blending) then the driver defines the function as NULL at buildtime. The function structure for a driver file can be seen in "Basic Renderring Routines". 5.1.5.7.1 System Functions 5.1.5.7.1.1 Percentage2Alpha Function C inline uint8_t Percentage2Alpha( uint8_t alphaPercentage ); 5.1.5.7.1.2 DriverInterfaceInit Function C inline void DriverInterfaceInit( DRV_HANDLE * pmphandle, DRV_PMP_MODE_CONFIG * config ); 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-291 Description This is function DriverInterfaceInit. 5.1.5.7.2 Data Types and Constants 5.1.5.7.2.1 GFX_DRV_DATA Structure C typedef struct { uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; uint16_t dataWidth; uint16_t horizontalPulseWidth; uint16_t horizontalBackPorch; uint16_t horizontalFrontPorch; uint16_t verticalPulseWidth; uint16_t verticalBackPorch; uint16_t verticalFrontPorch; uint8_t logicShift; enum { LCD_TFT = 1, LCD_MSTN, LCD_CSTN } LCDType; uint8_t colorType; uint8_t timingControl; GFX_DRV_FUNCTIONS PrimitiveFunction; uint8_t driverBusy; uint8_t ready; GFX_COLOR color; volatile uint8_t activePage; volatile uint8_t visualPage; } GFX_DRV_DATA; Description Structure: GFX_DRV_DATA Each driver in order to be registered with the primitive layer needs these values. they are mainly dependent on the chosen LCD. Members Members Description uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels uint16_t verticalResolution; Vertical resolution of the displayed orientation in pixels uint16_t horizontalPulseWidth; Horizontal Pulse Width of the LCD uint16_t horizontalBackPorch; Horizontal BackPorch of the LCD uint16_t horizontalFrontPorch; Horizontal FrontPorch of the LCD uint16_t verticalPulseWidth; Vertical Pulse width of the LCD uint16_t verticalBackPorch; Vertical BackPorch of the LCD uint16_t verticalFrontPorch; Vertical FrontPorch of the LCD uint8_t logicShift; Rising/Falling edge indicator of the LCD pixel clock 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-292 enum { LCD_TFT = 1, LCD_MSTN, LCD_CSTN } LCDType; LCD type uint8_t colorType; color depth (18BPP, 24BPP, 8BPP, palette) uint8_t timingControl; flag to GFX_DRV_FUNCTIONS PrimitiveFunction; List of Primitive Renderring functions available by the driver uint8_t driverBusy; Flag to indicate driver is currently busy uint8_t ready; Flag to indicate driver has been initialized and recognized by the primitive layer GFX_COLOR color; current Color set for the display driver volatile uint8_t activePage; current activepage set for the display driver volatile uint8_t visualPage; current visualPage set for the display driver 5.1.5.7.2.2 GFX_DRV_FUNCTIONS Structure C typedef struct { uint16_t (* PixelsPut)(short,short,uint16_t, uint16_t); uint16_t (* BarFill)(short,short,short,short); uint16_t* (* PixelArrayPut)(uint16_t*,short,short,uint16_t, uint16_t); uint16_t* (* PixelArrayGet)(uint16_t*,short,short,uint16_t); uint16_t (* PixelPut)(short,short); void (* ColorSet)(GFX_COLOR); void (* InstanceSet)(uint8_t); uint16_t (* PageSet)(uint8_t, uint8_t); uint16_t* (* Layer)(uint8_t, GFX_LAYER_PARAMS*); uint16_t (* PixelGet)(short,short); uint16_t* (* AlphaBlendWindow)(GFX_ALPHA_PARAMS*, uint16_t, uint16_t, uint8_t); } GFX_DRV_FUNCTIONS; Description Structure: GFX_DRV_FUNCTIONS This structure needs to be defined in the driver file to inform the primitive layer as to what functions are available. Members Members Description uint16_t (* PixelsPut)(short,short,uint16_t, uint16_t); This function sends pixels of an X,Y location to the LCD controller of a given count and linecount. uint16_t (* BarFill)(short,short,short,short); This function sends a 2D accelerated Bar command to the LCD controller uint16_t* (* PixelArrayPut)(uint16_t*,short,short,uint16_t, uint16_t); This function sends an array of pixels at an X,Y location to the LCD controller of a given count and linecount from a memory location. uint16_t* (* PixelArrayGet)(uint16_t*,short,short,uint16_t); This function gets an array of pixels at an X,Y location to the LCD controller of a given count and linecount from a memory location. uint16_t (* PixelPut)(short,short); This function sends a pixel of an X,Y location to the LCD controller. void (* ColorSet)(GFX_COLOR); This function sets the global color for the display driver void (* InstanceSet)(uint8_t); This function sets the global color for the display driver uint16_t (* PageSet)(uint8_t, uint8_t); See Primitive PageSet Defition uint16_t* (* Layer)(uint8_t, GFX_LAYER_PARAMS*); See Primitive Layer Definition uint16_t (* PixelGet)(short,short); This function gets a pixel of an X,Y location to the LCD controller. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-293 uint16_t* (* AlphaBlendWindow)(GFX_ALPHA_PARAMS*, uint16_t, uint16_t, uint8_t); See Primitive AlphaBlendWindow Definition 5.1.5.7.2.3 LAYER_TYPE Enumeration C typedef enum { PIP1 = 0, PIP2 } LAYER_TYPE; Description Enumeration: LAYER_TYPE 5.1.5.7.2.4 PAGE_TYPE Enumeration C typedef enum { ACTIVE_PAGE = 0, VISUAL_PAGE, BACKGROUND_PAGE, FOREGROUND_PAGE, DESTINATION_PAGE, TRANSITION_PAGE } PAGE_TYPE; Description Enumeration: PAGE_TYPE Members Members Description TRANSITION_PAGE Page that displays the transition 5.1.5.7.2.5 NUM_ALPHA_LEVELS Macro C #define NUM_ALPHA_LEVELS 0x20 // Specific to device Description Specific to device 5.1.5.7.2.6 ALPHA_DELTA Macro C #define ALPHA_DELTA ((NUM_ALPHA_LEVELS) << 5) Description This is macro ALPHA_DELTA. 5.1.5.7.2.7 GFX_CONFIG_DRIVER_COUNT Macro C #define GFX_CONFIG_DRIVER_COUNT 1 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-294 Description This is macro GFX_CONFIG_DRIVER_COUNT. 5.1.5.7.2.8 GFX_ALPHA_PARAMS Structure C typedef struct { uint8_t foregroundPage; short foregroundLeft; short foregroundTop; uint8_t backgroundPage; short backgroundLeft; short backgroundTop; uint8_t destinationPage; short destinationLeft; short destinationTop; uint8_t alpha; GFX_COLOR prevAlphaColor; } GFX_ALPHA_PARAMS; Description This is type GFX_ALPHA_PARAMS. 5.1.5.7.2.9 GFX_LAYER_PARAMS Structure C typedef struct { uint8_t type; uint8_t on; uint8_t page; short left; short top; uint16_t width; uint16_t height; short layerLeft; short layerTop; } GFX_LAYER_PARAMS; Description This is type GFX_LAYER_PARAMS. 5.1.5.8 Files Files Name Description drv_gfx_display.h GFX Display Driver definitions drv_gfx_config_template.h This is file drv_gfx_config_template.h. Description 5.1.5.8.1 drv_gfx_display.h GFX Display Driver definitions 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-295 This file describes the GFX Display Driver specific definitions. Enumerations Name Description LAYER_TYPE types of Layers supported by the GFX Library PAGE_TYPE types of pages supported by the GFX Library Files Name Description drv_gfx_lcc.h Interface for the graphics library where the primitives are renderred and sent to the graphics controller either external or internal drv_gfx_s1d13517.h Interface for the graphics library where the primitives are renderred and sent to the graphics controller either external or internal drv_gfx_ssd1926.h Interface for the graphics library where the primitives are renderred and sent to the graphics controller either external or internal Functions Name Description DriverInterfaceInit This is function DriverInterfaceInit. Percentage2Alpha Macros Name Description ALPHA_DELTA This is macro ALPHA_DELTA. GFX_CONFIG_DRIVER_COUNT This is macro GFX_CONFIG_DRIVER_COUNT. NUM_ALPHA_LEVELS Specific to device Structures Name Description GFX_ALPHA_PARAMS This is type GFX_ALPHA_PARAMS. GFX_DRV_DATA Structure containing the driver graphics controller data. GFX_DRV_FUNCTIONS Structure containing the driver functions used by the primitive layer. GFX_LAYER_PARAMS This is type GFX_LAYER_PARAMS. Company Microchip Technology Incorporated FileName: gfx_display_driver.h 5.1.5.8.1.1 drv_gfx_lcc.h None Enumerations Name Description DMA_ISR_TASK This is type DMA_ISR_TASK. LCC_TASK This is type LCC_TASK. Functions Name Description GFX_DRV_lcc_BrightnessSet Sets the brightness of the display backlight. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-296 GFX_DRV_lcc_Close closes an instance of the graphics controller GFX_DRV_lcc_Initialize resets LCD, initializes PMP GFX_DRV_lcc_Layer This is function GFX_DRV_lcc_Layer. GFX_DRV_lcc_Open opens an instance of the graphics controller GFX_DRV_lcc_PixelArrayGet gets an array of pixels of length count starting at *color GFX_DRV_lcc_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_lcc_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_lcc_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_lcc_SetColor Sets the color for the driver instance GFX_DRV_lcc_SetInstance Sets the instance for the driver GFX_DRV_lcc_SetPage This is function GFX_DRV_lcc_SetPage. GFX_DRV_lcc_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer GFX_PRIM_SetPIPWindow This is function GFX_PRIM_SetPIPWindow. Macros Name Description GFX_DRV_lcc_COMMANDQUEUESIZE This is macro GFX_DRV_lcc_COMMANDQUEUESIZE. PIP_BUFFER This is macro PIP_BUFFER. USE_LCC_SCROLLING This is macro USE_LCC_SCROLLING. USE_PIP This is macro USE_PIP. Structures Name Description GFX_DRV_lcc_COMMAND Structure for the commands in the driver queue. File Name drv_gfx_lcc.h Company Microchip Technology Incorporated 5.1.5.8.1.2 drv_gfx_s1d13517.h None Functions Name Description GFX_DRV_S1D13517_AlphaBlendWindow SEE primitive layer alphablendWindow definition GFX_DRV_S1D13517_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_S1D13517_Close closes an instance of the graphics controller GFX_DRV_S1D13517_GetReg returns graphics controller register value (byte access) GFX_DRV_S1D13517_Initialize resets LCD, initializes PMP GFX_DRV_S1D13517_Layer Updates a Layer depending on the layer parameters. GFX_DRV_S1D13517_Open opens an instance of the graphics controller GFX_DRV_S1D13517_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_S1D13517_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_S1D13517_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-297 GFX_DRV_S1D13517_SetColor Sets the color for the driver instance GFX_DRV_S1D13517_SetInstance Sets the instance for the driver GFX_DRV_S1D13517_SetPage Sets the page of a certain page type GFX_DRV_S1D13517_SetReg updates graphics controller register value (byte access) GFX_DRV_S1D13517_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer Structures Name Description GFX_DRV_S1D13517_COMMAND Structure for the commands in the driver queue. LAYER_REGISTERS This structure is used to describe layer registers. File Name S1D13517.h Company Microchip Technology Incorporated 5.1.5.8.1.3 drv_gfx_ssd1926.h None Functions Name Description GFX_DRV_SSD1926_BarFill Hardware accelerated barfill function GFX_DRV_SSD1926_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_SSD1926_Busy Returns non-zero if LCD controller is busy (previous drawing operation is not completed). GFX_DRV_SSD1926_Close closes an instance of the graphics controller GFX_DRV_SSD1926_GetReg returns graphics controller register value (byte access) GFX_DRV_SSD1926_Initialize resets LCD, initializes PMP GFX_DRV_SSD1926_Open opens an instance of the graphics controller GFX_DRV_SSD1926_PixelArrayGet gets an array of pixels of length count starting at *color GFX_DRV_SSD1926_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_SSD1926_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_SSD1926_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_SSD1926_SetColor Sets the color for the driver instance GFX_DRV_SSD1926_SetInstance Sets the instance for the driver GFX_DRV_SSD1926_SetReg updates graphics controller register value (byte access) GFX_DRV_SSD1926_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer Structures Name Description GFX_DRV_SSD1926_COMMAND Structure for the commands in the driver queue. GFX_DRV_SSD1926_TASK Structure for the task machine File Name SSD1926.h 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-298 Company Microchip Technology Incorporated 5.1.5.8.2 drv_gfx_config_template.h This is file drv_gfx_config_template.h. 5.1.5.9 Software Drivers 5.1.5.9.1 Low-Cost Controllerless (LCC) Graphics Driver Library 5.1.5.9.1.1 Introduction Low-Cost Controllerless Graphics Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the Low-Cost Controllerless Graphics Controller Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.9.1.2 Release Notes MPLAB Harmony Version: v0.70b Low-Cost Controllerless Graphics Driver Library Version : 4.00b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: DMA Channel 1 is non-configurable. The LCC driver will require DMA Channel 1 and not allow configuration via Harmony system services. 5.1.5.9.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-299 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.5.9.1.4 Using the Library This topic describes the basic architecture of the Low-Cost Controllerless (LCC) Graphics Driver Library and provides information and examples on how to use it. Interface Header File: gfx_drv_lcc.h The interface to the Low-Cost Controllerless (LCC) Graphics Driver library is defined in the "gfx_drv_lcc.h" header file. This file is included by the "gfx_drv_lcc.h" file. Any C language source (.c) file that uses the Low-Cost Controllerless (LCC) Graphics Driver Library should include "gfx_drv_lcc.h". Library File: The GFX Low-Cost Controller library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Low-Cost Controllerless (LCC) Graphics Driver Library interacts with the framework. 5.1.5.9.1.4.1 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Low-Cost Controllerless (LCC) Graphics Controller Driver module. Library Interface Section Description Functions This section lists the API functions available in the library. 5.1.5.9.1.4.2 Abstraction Model This library provides the low-level abstraction of the Low-Cost Controllerless (LCC) Graphics Controller Driver module on the Microchip family of graphic display controllers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Low-Cost Controllerless (LCC) Graphics Controller Driver Abstraction Block Diagram Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.9.1.5 Configuring the Library The configuration of the Low-Cost Controllerless (LCC) Graphics Driver Library is based on the file system_config.h. This header file contains the configuration selection for the GFX Low-Cost Controller. Based on the selections made, the 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-300 Low-Cost Controllerless (LCC) Graphics Driver Library will support or not support selected features. These configuration settings will apply to all instances of the Low-Cost Controllerless (LCC) Graphics Driver Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.5.9.1.6 Building the Library This section list the files that are available in the \src of theLow-Cost Controllerless (LCC) Graphics Driver Library. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • gfx_drv_lcc.c 5.1.5.9.1.7 Library Interface This section describes the Application Programming Interface (API) functions of the Low-Cost Controllerless (LCC) Graphics Driver Library. Refer to each section for a detailed description. 5.1.5.9.1.7.1 Functions Functions Name Description GFX_DRV_lcc_Close closes an instance of the graphics controller GFX_DRV_lcc_Initialize resets LCD, initializes PMP GFX_DRV_lcc_Open opens an instance of the graphics controller GFX_DRV_lcc_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer GFX_DRV_lcc_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_lcc_PixelArrayGet gets an array of pixels of length count starting at *color GFX_DRV_lcc_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_lcc_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_lcc_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_lcc_SetColor Sets the color for the driver instance GFX_DRV_lcc_SetInstance Sets the instance for the driver GFX_DRV_lcc_Layer This is function GFX_DRV_lcc_Layer. GFX_DRV_lcc_SetPage This is function GFX_DRV_lcc_SetPage. GFX_PRIM_SetPIPWindow This is function GFX_PRIM_SetPIPWindow. Description 5.1.5.9.1.7.1.1 GFX_DRV_lcc_Close Function C uint16_t GFX_DRV_lcc_Close( uint8_t instance ); 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-301 Description none Returns 0 - instance closed 2 - instance doesn't exist 3 - instance already closed 5.1.5.9.1.7.1.2 GFX_DRV_lcc_Initialize Function C uint16_t GFX_DRV_lcc_Initialize( uint8_t instance ); Description none Parameters Parameters Description instance driver instance Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1.5.9.1.7.1.3 GFX_DRV_lcc_Open Function C uint16_t GFX_DRV_lcc_Open( uint8_t instance ); Description none Returns 1 - driver not initialied 2 - instance doesn't exist 3 - instance already open instance to driver when successful 5.1.5.9.1.7.1.4 GFX_DRV_lcc_Tasks Function C void GFX_DRV_lcc_Tasks(); 5.1.5.9.1.7.1.5 GFX_DRV_lcc_BrightnessSet Function C void GFX_DRV_lcc_BrightnessSet( uint8_t instance, uint16_t level ); Description none Parameters Parameters Description 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-302 5.1.5.9.1.7.1.6 GFX_DRV_lcc_PixelArrayGet Function C uint16_t* GFX_DRV_lcc_PixelArrayGet( uint16_t * color, short x, short y, uint16_t count ); Description none Parameters Parameters Description instance driver instance *color start of the array x x coordinate of the start point. y y coordinate of the end point. count number of pixels Returns NULL - call not successful (lcc driver busy) !NULL - address of the display driver queue command 5.1.5.9.1.7.1.7 GFX_DRV_lcc_PixelArrayPut Function C uint16_t* GFX_DRV_lcc_PixelArrayPut( uint16_t * color, short x, short y, uint16_t count, uint16_t lineCount ); Description none Parameters Parameters Description instance driver instance *color start of the array x x coordinate of the start point. y y coordinate of the end point. count number of pixels Returns NULL - call not successful !NULL - handle to the number of pixels remaining 5.1.5.9.1.7.1.8 GFX_DRV_lcc_PixelPut Function C uint16_t GFX_DRV_lcc_PixelPut( short x, 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-303 short y ); Description none Parameters Parameters Description x,y pixel coordinates Returns NULL - call not successful (lcc driver busy) !NULL - address of the display driver queue command 5.1.5.9.1.7.1.9 GFX_DRV_lcc_PixelsPut Function C uint16_t GFX_DRV_lcc_PixelsPut( short x, short y, uint16_t count, uint16_t lineCount ); Description none Parameters Parameters Description x,y pixel coordinates Returns NULL - call not successful (lcc driver busy) !NULL - address of the display driver queue command 5.1.5.9.1.7.1.10 GFX_DRV_lcc_SetColor Function C void GFX_DRV_lcc_SetColor( GFX_COLOR color ); Returns none 5.1.5.9.1.7.1.11 GFX_DRV_lcc_SetInstance Function C void GFX_DRV_lcc_SetInstance( uint8_t instance ); Returns none 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-304 5.1.5.9.1.7.1.12 GFX_DRV_lcc_Layer Function C uint16_t* GFX_DRV_lcc_Layer( uint8_t instance, GFX_LAYER_PARAMS* layer ); Description This is function GFX_DRV_lcc_Layer. 5.1.5.9.1.7.1.13 GFX_DRV_lcc_SetPage Function C uint16_t GFX_DRV_lcc_SetPage( uint8_t pageType, uint8_t page ); Description This is function GFX_DRV_lcc_SetPage. 5.1.5.9.1.7.1.14 GFX_PRIM_SetPIPWindow Function C void GFX_PRIM_SetPIPWindow( uint16_t left, uint16_t top, uint16_t hlength, uint16_t vlength, uint16_t pipx, uint16_t pipy ); Description This is function GFX_PRIM_SetPIPWindow. 5.1.5.9.1.7.2 Data Types and Constants Enumerations Name Description LCC_TASK This is type LCC_TASK. DMA_ISR_TASK This is type DMA_ISR_TASK. Macros Name Description USE_LCC_SCROLLING This is macro USE_LCC_SCROLLING. USE_PIP This is macro USE_PIP. PIP_BUFFER This is macro PIP_BUFFER. GFX_DRV_lcc_COMMANDQUEUESIZE This is macro GFX_DRV_lcc_COMMANDQUEUESIZE. Structures Name Description GFX_DRV_lcc_COMMAND Structure for the commands in the driver queue. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-305 Description 5.1.5.9.1.7.2.1 USE_LCC_SCROLLING Macro C #define USE_LCC_SCROLLING Description This is macro USE_LCC_SCROLLING. 5.1.5.9.1.7.2.2 USE_PIP Macro C #define USE_PIP Description This is macro USE_PIP. 5.1.5.9.1.7.2.3 GFX_DRV_lcc_COMMAND Structure C typedef struct { uint8_t instance; union { uint32_t Val; struct { uint8_t b0 : 1; uint8_t b1 : 1; uint8_t b2 : 1; uint8_t b3 : 1; uint8_t b4 : 1; uint8_t b5 : 1; uint8_t b6 : 1; uint8_t b7 : 1; uint8_t b8 : 1; uint8_t b9 : 1; uint8_t b10 : 1; uint8_t b11 : 1; uint8_t b12 : 1; uint8_t b13 : 1; uint8_t b14 : 1; uint8_t b15 : 1; uint8_t b16 : 1; uint8_t b17 : 1; uint8_t b18 : 1; uint8_t b19 : 1; uint8_t b20 : 1; uint8_t b21 : 1; uint8_t b22 : 1; uint8_t b23 : 1; uint8_t b24 : 1; uint8_t b25 : 1; uint8_t b26 : 1; uint8_t b27 : 1; uint8_t b28 : 1; uint8_t b29 : 1; uint8_t b30 : 1; uint8_t b31 : 1; } bits; 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-306 } address; uint16_t * array; uint16_t data; uint16_t count; uint16_t lineCount; uint8_t task; } GFX_DRV_lcc_COMMAND; Description Structure: GFX_DRV_lcc_COMMAND None 5.1.5.9.1.7.2.4 PIP_BUFFER Macro C #define PIP_BUFFER (3) Description This is macro PIP_BUFFER. 5.1.5.9.1.7.2.5 LCC_TASK Enumeration C typedef enum { UPDATE_CLOCK = 0, INITIALIZE, WAIT_TRANSMIT_PIXELS, FINISH_TRANSMIT_PIXELS, WAIT_TRANSMIT_ARRAY, FINISH_TRANSMIT_ARRAY, WAIT_RECEIVE, READ_RECEIVE, PUT_ARRAY, PUT_PIXELS, GET_PIXELS, COPY_PIXELS, PAGE, LAYERS } LCC_TASK; Description This is type LCC_TASK. 5.1.5.9.1.7.2.6 GFX_DRV_lcc_COMMANDQUEUESIZE Macro C #define GFX_DRV_lcc_COMMANDQUEUESIZE 480 Description This is macro GFX_DRV_lcc_COMMANDQUEUESIZE. 5.1.5.9.1.7.2.7 DMA_ISR_TASK Enumeration C typedef enum { ACTIVE_PERIOD = 0, BLANKING_PERIOD, FINISH_LINE, 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-307 OVERFLOW, PIP, SCROLL } DMA_ISR_TASK; Description This is type DMA_ISR_TASK. 5.1.5.9.1.8 Files Files Name Description 5.1.5.9.1.8.1 drv_gfx_lcc_config_template.h • Module for Microchip Graphics Library • This file contains compile time options for the Graphics Library. ******************************************************************* • FileName: GraphicsConfig.h • Dependencies: none • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: C30 V3.00/C32 • Company: Microchip Technology, Inc. * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED ?AS IS? WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-308 • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • Anton Alkhimenok 10/28/2007 Initial Version • Pradeep Budagutta 10/28/2007 Display related defines • moved to DisplayConfig.h 5.1.5.10 Hardware Drivers 5.1.5.10.1 OTM2201A Graphics Controller Driver Library 5.1.5.10.1.1 Introduction OTM2201A Graphics Controller Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the OTM2201A Graphics Controller Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.10.1.2 Release Notes MPLAB Harmony Version: v0.70b OTM2201A Graphics Controller Driver Library Version : 4.00b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.5.10.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-309 Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.5.10.1.4 Using the Library This topic describes the basic architecture of the OTM2201A Graphics Controller Driver Library and provides information and examples on how to use it. Interface Header File: drv_gfx_otm2201a.h The interface to the OTM2201A Graphics Controller Driver library is defined in the "drv_gfx_otm2201a.h" header file. This file is included by the "gfx_primitive.h" file. Any C language source (.c) file that uses the OTM2201A Graphics Controller Driver library should include "gfx_primitive.h". Library File: The OTM2201A Graphics Controller Driver library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the OTM2201A Graphics Controller Driver interacts with the framework. 5.1.5.10.1.4.1 Abstraction Model This library provides the low-level abstraction of the OTM2201A Graphics Controller Driver module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description OTM2201A Graphics Controller Driver Abstraction Block Diagram Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.10.1.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the OTM2201 Graphics Controller Driver module. Library Interface Section Description Functions This section lists the API functions available in the library. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-310 5.1.5.10.1.5 Configuring the Driver Library The configuration of the OTM2201 Graphics Controller Driver is based on the file sys_config.h This header file contains the configuration selection for the OTM2201 Graphics Controller Driver. Based on the selections made, the OTM2201 Graphics Controller Driver will support or not support selected features. These configuration settings will apply to all instances of the OTM2201 Graphics Controller Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.5.10.1.6 Building the Library This section list the files that are available in the \src of the OTM2201A Graphics Controller Driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • drv_gfx_otm2201a.c 5.1.5.10.1.7 Library Interface This section describes the Application Programming Interface (API) functions of the OTM2201A Graphics Controller Driver Library. Refer to each section for a detailed description. 5.1.5.10.1.7.1 Functions Functions Name Description GFX_DRV_OTM2201A_AddressSet Sets the start GRAM address where pixel data to be written GFX_DRV_OTM2201A_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_OTM2201A_Busy Returns non-zero value if LCD controller is busy (previous drawing operation is not completed). GFX_DRV_OTM2201A_Close Closes an instance of the graphics controller GFX_DRV_OTM2201A_ColorSet Sets the color for the driver instance GFX_DRV_OTM2201A_Initialize Intialize OTM2201A device GFX_DRV_OTM2201A_InstanceSet Sets the instance for the driver GFX_DRV_OTM2201A_Open Opens an instance of the graphics controller GFX_DRV_OTM2201A_PixelArrayGet Gets an array of pixels of length count into an array starting at *color GFX_DRV_OTM2201A_PixelArrayPut Outputs an array of pixels of length count starting at *color GFX_DRV_OTM2201A_PixelPut Outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_OTM2201A_PixelsPut Outputs count number of pixels into the frame buffer from the given x,y coordinate. GFX_DRV_OTM2201A_RegGet Returns graphics controller register value (byte access) GFX_DRV_OTM2201A_RegSet Updates graphics controller register value (byte access) GFX_DRV_OTM2201A_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer Description 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-311 5.1.5.10.1.7.1.1 GFX_DRV_OTM2201A_AddressSet Function C uint16_t GFX_DRV_OTM2201A_AddressSet( uint32_t address ); Description Address consists of Lower 8 bit at Register REG_RAM_ADDR_LOW and Higher 8 bit at Register REG_RAM_ADDR_HIGH Parameters Parameters Description address pixel address Returns DRV_OTM2201A_ERROR_PMP_WRITE - returns error during PMP Write, DRV_OTM2201A_ERROR_NO_ERROR - returns success without any error. 5.1.5.10.1.7.1.2 GFX_DRV_OTM2201A_BrightnessSet Function C void GFX_DRV_OTM2201A_BrightnessSet( uint8_t instance, uint16_t level ); Description Sets the brightness of the display backlight. Parameters Parameters Description instance instance of the driver level Brightness level. Valid values are 0 to 100. 0 = brightness level is zero or display is turned off. 100 = brightness level is maximum. Returns none 5.1.5.10.1.7.1.3 GFX_DRV_OTM2201A_Busy Function C uint16_t GFX_DRV_OTM2201A_Busy( uint8_t instance ); Description Returns non-zero value if LCD controller is busy (previous drawing operation is not completed). Parameters Parameters Description instance driver instance Returns DRV_OTM2201A_ERROR_DEVICE_BUSY - Device is busy, DRV_OTM2201A_ERROR_NO_ERROR - Success, driver is not 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-312 busy. 5.1.5.10.1.7.1.4 GFX_DRV_OTM2201A_Close Function C uint16_t GFX_DRV_OTM2201A_Close( uint8_t instance ); Description Closes an instance if instance exists and not already closed Parameters Parameters Description instance instance of the driver Returns DRV_OTM2201A_INSTANCE_CLOSED - instance closed, DRV_OTM2201A_INSTANCE_DOESNT_EXIST - instance doesn't exist, DRV_OTM2201A_INSTANCE_ALREADY_CLOSED - instance already closed. 5.1.5.10.1.7.1.5 GFX_DRV_OTM2201A_ColorSet Function C void GFX_DRV_OTM2201A_ColorSet( GFX_COLOR color ); Description Sets the color for the driver instance Parameters Parameters Description color 16 bit 565 format color value Returns none 5.1.5.10.1.7.1.6 GFX_DRV_OTM2201A_Initialize Function C uint16_t GFX_DRV_OTM2201A_Initialize( uint8_t instance ); Description Initialize OTM2201A device by initializing PMP interface, initializing command buffer for current instance initialize device registers Parameters Parameters Description instance driver instance Returns DRV_OTM2201A_ERROR_QUEUE_FULL - OTM2201A command queue is full, DRV_OTM2201A_ERROR_REG_GET - OTM2201A Error while reading register, DRV_OTM2201A_ERROR_REG_SET - OTM2201A Error while writing register, 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-313 DRV_OTM2201A_ERROR_DEVICE_BUSY - OTM2201A device is busy, DRV_OTM2201A_ERROR_NO_ERROR - Success without any error. 5.1.5.10.1.7.1.7 GFX_DRV_OTM2201A_InstanceSet Function C void GFX_DRV_OTM2201A_InstanceSet( uint8_t instance ); Description Sets the instance for the driver Parameters Parameters Description instance driver instance Returns none 5.1.5.10.1.7.1.8 GFX_DRV_OTM2201A_Open Function C uint16_t GFX_DRV_OTM2201A_Open( uint8_t instance ); Description Opens the instance of driver if instance is valid and not already opened Parameters Parameters Description instance instance of the driver Returns DRV_OTM2201A_NEW_INSTANCE_OPEN - driver not initialied, DRV_OTM2201A_INSTANCE_DOESNT_EXIST - instance doesn't exist, DRV_OTM2201A_INSTANCE_ALREADY_OPEN - instance already open. 5.1.5.10.1.7.1.9 GFX_DRV_OTM2201A_PixelArrayGet Function C uint16_t* GFX_DRV_OTM2201A_PixelArrayGet( uint16_t * color, short x, short y, uint16_t count ); Description Gets an array of pixels of length count into an array starting at *color Parameters Parameters Description color Pointer to array where color data is to be loaded 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-314 x pixel coordinate on x axis y pixel coordinate on y axis count count number of pixels Returns DRV_OTM2201A_ERROR_QUEUE_FULL - OTM2201A command queue is full, DRV_OTM2201A_ERROR_NO_ERROR - Success without any error. 5.1.5.10.1.7.1.10 GFX_DRV_OTM2201A_PixelArrayPut Function C uint16_t* GFX_DRV_OTM2201A_PixelArrayPut( uint16_t * color, short x, short y, uint16_t count, uint16_t lineCount ); Description Outputs an array of pixels of length count starting at *color Parameters Parameters Description color pointer to array of color of pixels x pixel coordinate on x axis. y pixel coordinate on y axis. count count number of pixels lineCount lineCount number of display lines Returns handle - handle to the number of pixels remaining, DRV_OTM2201A_ERROR_QUEUE_FULL - OTM2201A command queue is full. 5.1.5.10.1.7.1.11 GFX_DRV_OTM2201A_PixelPut Function C uint16_t GFX_DRV_OTM2201A_PixelPut( short x, short y ); Description Outputs one pixel into the frame buffer at the x,y coordinate given Parameters Parameters Description x pixel coordinate on x axis y pixel coordinate on y axis Returns DRV_OTM2201A_ERROR_QUEUE_FULL - OTM2201A command queue is full, DRV_OTM2201A_ERROR_NO_ERROR - Success without any error. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-315 5.1.5.10.1.7.1.12 GFX_DRV_OTM2201A_PixelsPut Function C uint16_t GFX_DRV_OTM2201A_PixelsPut( short x, short y, uint16_t count, uint16_t lineCount ); Description Outputs count number of pixels into the frame buffer from the given x,y coordinate. Parameters Parameters Description x pixel coordinate on x axis y pixel coordinate on y axis count count number of pixels lineCount lineCount number of display lines Returns DRV_OTM2201A_ERROR_QUEUE_FULL - OTM2201A command queue is full, DRV_OTM2201A_ERROR_NO_ERROR - Success without any error. 5.1.5.10.1.7.1.13 GFX_DRV_OTM2201A_RegGet Function C uint8_t GFX_DRV_OTM2201A_RegGet( uint16_t index, uint16_t * data ); Description Returns graphics controller register value (byte access) Parameters Parameters Description index register number *data array to store register data Returns DRV_OTM2201A_ERROR_PMP_WRITE - returns error during PMP Write, DRV_OTM2201A_ERROR_PMP_READ - returns error during PMP Read, DRV_OTM2201A_ERROR_NO_ERROR - returns success without any error. 5.1.5.10.1.7.1.14 GFX_DRV_OTM2201A_RegSet Function C uint16_t GFX_DRV_OTM2201A_RegSet( uint16_t index, uint16_t value, uint32_t repeatCount ); 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-316 Description This call can set "value" of the register accessed by its "index" and can repeat the same by number of times mentioned in "repeatCount" Parameters Parameters Description index register number value value to write to register repeatCount repeatCount number of times value is to be written to the register. Returns DRV_OTM2201A_ERROR_PMP_WRITE - returns error during PMP Write, DRV_OTM2201A_ERROR_NO_ERROR - returns success without any error. 5.1.5.10.1.7.1.15 GFX_DRV_OTM2201A_Tasks Function C void GFX_DRV_OTM2201A_Tasks(); Description Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer. 5.1.5.10.1.7.2 Data Types and Constants Enumerations Name Description OTM2201A_TASK Enumeration for command type. Structures Name Description GFX_DRV_OTM2201A_COMMAND Structure for the commands in the driver queue. Description 5.1.5.10.1.7.2.1 GFX_DRV_OTM2201A_COMMAND Structure C typedef struct { uint8_t instance; uint32_t address; uint16_t * array; uint16_t data; uint16_t count; uint16_t lineCount; OTM2201A_TASK task; } GFX_DRV_OTM2201A_COMMAND; Description Structure: GFX_DRV_OTM2201A_COMMAND Structure for the commands in the driver queue. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-317 Parameters Parameters Description instance instance of the driver address pixel address array pointer to array of pixel data data pixel color count count number of pixels in one line lineCount lineCount number of lines of display task Type of task (OTM2201A_TASK enum) 5.1.5.10.1.7.2.2 OTM2201A_TASK Enumeration C typedef enum { INITIALIZE = 0, BUSY, PUT_ARRAY, PUT_PIXELS } OTM2201A_TASK; Description Enum: OTM2201A_TASK Enumeration for command type. Parameters Parameters Description INITIALIZE driver initialization task BUSY driver busy task PUT_ARRAY driver put array task PUT_PIXELS driver put pixels task 5.1.5.10.1.7.3 Files Files Name Description drv_gfx_otm2201a.h Interface for the graphics library where the primitives are renderred and sent to the graphics controller either external or internal Description 5.1.5.10.1.7.3.1 drv_gfx_otm2201a.h None Enumerations Name Description OTM2201A_TASK Enumeration for command type. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-318 Functions Name Description GFX_DRV_OTM2201A_AddressSet Sets the start GRAM address where pixel data to be written GFX_DRV_OTM2201A_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_OTM2201A_Busy Returns non-zero value if LCD controller is busy (previous drawing operation is not completed). GFX_DRV_OTM2201A_Close Closes an instance of the graphics controller GFX_DRV_OTM2201A_ColorSet Sets the color for the driver instance GFX_DRV_OTM2201A_Initialize Intialize OTM2201A device GFX_DRV_OTM2201A_InstanceSet Sets the instance for the driver GFX_DRV_OTM2201A_Open Opens an instance of the graphics controller GFX_DRV_OTM2201A_PixelArrayGet Gets an array of pixels of length count into an array starting at *color GFX_DRV_OTM2201A_PixelArrayPut Outputs an array of pixels of length count starting at *color GFX_DRV_OTM2201A_PixelPut Outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_OTM2201A_PixelsPut Outputs count number of pixels into the frame buffer from the given x,y coordinate. GFX_DRV_OTM2201A_RegGet Returns graphics controller register value (byte access) GFX_DRV_OTM2201A_RegSet Updates graphics controller register value (byte access) GFX_DRV_OTM2201A_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer Structures Name Description GFX_DRV_OTM2201A_COMMAND Structure for the commands in the driver queue. File Name drv_gfx_otm2201a.h Company Microchip Technology Incorporated 5.1.5.10.2 S1D13517 Graphics Controller Driver Library 5.1.5.10.2.1 Introduction S1D13517 Graphics Controller Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the S1D13517 Graphics Controller Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-319 5.1.5.10.2.2 Release Notes MPLAB Harmony Version: v0.70b S1D13517 Graphics Driver Library Version : 4.00b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1.5.10.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.5.10.2.4 Using the Library This topic describes the basic architecture of the S1D13517 Graphics Controller Driver Library and provides information and examples on how to use it. Interface Header File: gfx_drv_s1d13517.h The interface to the S1D13517 Graphics Controller Driver Library is defined in the "gfx_drv_s1d13517.h" header file. This file is included by the "gfx_drv_s1d13517.h" file. Any C language source (.c) file that uses the S1D13517 Graphics Controller Driver Library should include "gfx_drv_s1d13517.h". Library File: The S1D13517 Graphics Controller Driver Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the GFX S1D13517 Controller Driver interacts with the framework. 5.1.5.10.2.4.1 Abstraction Model This library provides the low-level abstraction of the S1D13517 Graphics Controller Driver module of the Microchip family of graphic display controllers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description S1D13517 Graphics Controller Driver Abstraction Block Diagram 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-320 Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.10.2.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the S1D13517 Graphics Controller Driver module. Library Interface Section Description Functions This section lists the API functions available in the library. 5.1.5.10.2.5 Configuring the Library Macros Name Description USE_ANALOGCLOCK Enable Analog Clock Object. 5.1.5.10.2.5.1 USE_ANALOGCLOCK Macro C #define USE_ANALOGCLOCK Description Enable Analog Clock Object. 5.1.5.10.2.5.2 USE_BITMAP_FLASH Macro C #define USE_BITMAP_FLASH Description Similar to Font data bitmaps can also be placed in two locations. One is in FLASH memory and the other is from external memory. Definining one or both enables the support for bitmaps located in internal flash and external memory. Define this in GraphicsConfig.h • USE_BITMAP_FLASH - Images located in internal flash memory. • USE_BITMAP_EXTERNAL - Images located in external memory (including external memory mapped to EDS).. 5.1.5.10.2.5.3 USE_BUTTON Macro C #define USE_BUTTON Description Enable Button Object. 5.1.5.10.2.5.4 USE_CHART Macro C #define USE_CHART 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-321 Description This is macro USE_CHART. 5.1.5.10.2.5.5 USE_CHECKBOX Macro C #define USE_CHECKBOX Description Enable Checkbox Object. 5.1.5.10.2.5.6 USE_COMP_RLE Macro C #define USE_COMP_RLE Description • Overview: To enable support for DEFLATE compressed images for PutImage(). • When this macro is enabled, the PutImage() function will • be able to process images generated by the Graphics Resource • Converter (GRC) that are compressed using the DEFLATE algorithm. • PutImage() will need the IPU module of the Microchip Graphics • Module to decompress. Enable this feature only when the driver • features the IPU module (example: PIC24FJ2456DA210). • Define this in GraphicsConfig.h * ****************************************************************** #define USE_COMP_IPU 5.1.5.10.2.5.7 USE_CUSTOM Macro C #define USE_CUSTOM Description Enable Custom Control Object (an example to create customized Object). 5.1.5.10.2.5.8 USE_DIGITALMETER Macro C #define USE_DIGITALMETER Description Enable DigitalMeter Object. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-322 5.1.5.10.2.5.9 USE_EDITBOX Macro C #define USE_EDITBOX Description Enable Edit Box Object. 5.1.5.10.2.5.10 USE_FONT_FLASH Macro C #define USE_FONT_FLASH 5.1.5.10.2.5.11 USE_GOL Macro C #define USE_GOL Description Enable Graphics Object Layer. 5.1.5.10.2.5.12 USE_GRADIENT Macro C #define USE_GRADIENT Description To enable support for Gradient bars and bevel primitives. Define this in GraphicsConfig.h. 5.1.5.10.2.5.13 USE_GROUPBOX Macro C #define USE_GROUPBOX Description Enable Group Box Object. 5.1.5.10.2.5.14 USE_LISTBOX Macro C #define USE_LISTBOX Description Enable List Box Object. 5.1.5.10.2.5.15 USE_METER Macro C #define USE_METER Description Enable Meter Object. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-323 5.1.5.10.2.5.16 USE_MULTIBYTECHAR Macro C #define USE_MULTIBYTECHAR Description To enable support for unicode fonts, USE_MULTIBYTECHAR must be defined. This sets the XCHAR definition (0-2^16 range). See XCHAR for details. Define this in GraphicsConfig.h 5.1.5.10.2.5.17 USE_PICTURE Macro C #define USE_PICTURE Description Enable Picture Object. 5.1.5.10.2.5.18 USE_PROGRESSBAR Macro C #define USE_PROGRESSBAR Description Enable Progress Bar Object. 5.1.5.10.2.5.19 USE_RADIOBUTTON Macro C #define USE_RADIOBUTTON Description Enable Radio Button Object. 5.1.5.10.2.5.20 USE_ROUNDDIAL Macro C #define USE_ROUNDDIAL Description Enable Dial Object. 5.1.5.10.2.5.21 USE_SLIDER Macro C #define USE_SLIDER Description Enable Slider or Scroll Bar Object. 5.1.5.10.2.5.22 USE_STATICTEXT Macro C #define USE_STATICTEXT 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-324 Description Enable Static Text Object. 5.1.5.10.2.5.23 USE_TEXTENTRY Macro C #define USE_TEXTENTRY Description Enable TextEntry Object. 5.1.5.10.2.5.24 USE_TOUCHSCREEN Macro C #define USE_TOUCHSCREEN 5.1.5.10.2.5.25 USE_WINDOW Macro C #define USE_WINDOW Description Enable Window Object. 5.1.5.10.2.5.26 COLOR_DEPTH Macro C #define COLOR_DEPTH 16 Description Specifies the color depth used in the application defined in GraphicsConfig.h. 5.1.5.10.2.5.27 DRIVER_COUNT Macro C #define DRIVER_COUNT 1 Description • Overview: For XC16 or C30 builds only: When placing fonts in internal • data memory, there is a 32K limit for data space. The total • data should not exceed 32K. When this is unavoidable, the macro • USE_GFX_FONT_IN_PROGRAM_SECTION will relocate the font in • program space. This will remove the 32K restriction but at • the expense of slower access. • Define this in GraphicsConfig.h to enable the font to be • placed in program space. * ****************************************************************** #define USE_GFX_FONT_IN_PROGRAM_SECTION 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-325 5.1.5.10.2.5.28 GFX_free Macro C #define GFX_free(pObj) free(pObj) // Description When using Operating Systems (OS), define the OS specific malloc() and free() functions for compatibility with the OS based systems. Define these in GraphicsConfig.h 5.1.5.10.2.5.29 GFX_malloc Macro C #define GFX_malloc(size) malloc(size) Description When using Operating Systems (OS), define the OS specific malloc() and free() functions for compatibility with the OS based systems. Define these in GraphicsConfig.h 5.1.5.10.2.6 Building the Library This section list the files that are available in the \src of the S1D13517 Graphics Controller Driver Library. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • drv_gfx_s1d13517.c 5.1.5.10.2.7 Library Interface This section describes the Application Programming Interface (API) functions of the S1D13517 Graphics Controller Driver Library. Refer to each section for a detailed description. 5.1.5.10.2.7.1 Functions Functions Name Description GFX_DRV_S1D13517_AlphaBlendWindow SEE primitive layer alphablendWindow definition GFX_DRV_S1D13517_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_S1D13517_Close closes an instance of the graphics controller GFX_DRV_S1D13517_GetReg returns graphics controller register value (byte access) GFX_DRV_S1D13517_Initialize resets LCD, initializes PMP GFX_DRV_S1D13517_Layer Updates a Layer depending on the layer parameters. GFX_DRV_S1D13517_Open opens an instance of the graphics controller GFX_DRV_S1D13517_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_S1D13517_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_S1D13517_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_S1D13517_SetColor Sets the color for the driver instance GFX_DRV_S1D13517_SetInstance Sets the instance for the driver GFX_DRV_S1D13517_SetPage Sets the page of a certain page type GFX_DRV_S1D13517_SetReg updates graphics controller register value (byte access) 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-326 GFX_DRV_S1D13517_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer Description 5.1.5.10.2.7.1.1 GFX_DRV_S1D13517_AlphaBlendWindow Function C uint16_t* GFX_DRV_S1D13517_AlphaBlendWindow( GFX_ALPHA_PARAMS* alphaParams, uint16_t width, uint16_t height, uint8_t alpha ); 5.1.5.10.2.7.1.2 GFX_DRV_S1D13517_BrightnessSet Function C void GFX_DRV_S1D13517_BrightnessSet( uint8_t instance, uint16_t level ); Description none Parameters Parameters Description 5.1.5.10.2.7.1.3 GFX_DRV_S1D13517_Close Function C uint16_t GFX_DRV_S1D13517_Close( uint8_t instance ); Description none Returns 0 - instance closed 2 - instance doesn't exist 3 - instance already closed 5.1.5.10.2.7.1.4 GFX_DRV_S1D13517_GetReg Function C uint8_t GFX_DRV_S1D13517_GetReg( uint8_t index ); Description none Parameters Parameters Description index register number 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-327 *data array to store data Returns 0 - when call was passed 5.1.5.10.2.7.1.5 GFX_DRV_S1D13517_Initialize Function C uint16_t GFX_DRV_S1D13517_Initialize( uint8_t instance ); Description none Parameters Parameters Description instance driver instance Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1.5.10.2.7.1.6 GFX_DRV_S1D13517_Layer Function C uint16_t* GFX_DRV_S1D13517_Layer( uint8_t type, GFX_LAYER_PARAMS* layer ); Description none Parameters Parameters Description type layer type layer parameters for Layer function call Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1.5.10.2.7.1.7 GFX_DRV_S1D13517_Open Function C uint16_t GFX_DRV_S1D13517_Open( uint8_t instance ); Description none Returns 1 - driver not initialied 2 - instance doesn't exist 3 - instance already open instance to driver when successful 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-328 5.1.5.10.2.7.1.8 GFX_DRV_S1D13517_PixelArrayPut Function C uint16_t* GFX_DRV_S1D13517_PixelArrayPut( uint16_t * color, short x, short y, uint16_t count, uint16_t lineCount ); Description none Parameters Parameters Description *color start of the array x x coordinate of the start point. y y coordinate of the end point. count number of pixels Returns NULL - call not successful (PMP driver busy) !NULL - address to the number of pixels yet to be serviced 5.1.5.10.2.7.1.9 GFX_DRV_S1D13517_PixelPut Function C uint16_t GFX_DRV_S1D13517_PixelPut( short x, short y ); Description none Parameters Parameters Description instance driver instance color color to output x,y pixel coordinates Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1.5.10.2.7.1.10 GFX_DRV_S1D13517_PixelsPut Function C uint16_t GFX_DRV_S1D13517_PixelsPut( short x, short y, uint16_t count, uint16_t lineCount ); 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-329 Description none Parameters Parameters Description instance driver instance color color to output x,y pixel coordinates Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1.5.10.2.7.1.11 GFX_DRV_S1D13517_SetColor Function C void GFX_DRV_S1D13517_SetColor( GFX_COLOR color ); Returns none 5.1.5.10.2.7.1.12 GFX_DRV_S1D13517_SetInstance Function C void GFX_DRV_S1D13517_SetInstance( uint8_t instance ); Returns none 5.1.5.10.2.7.1.13 GFX_DRV_S1D13517_SetPage Function C uint16_t GFX_DRV_S1D13517_SetPage( uint8_t pageType, uint8_t page ); Description none Parameters Parameters Description instance driver instance Returns NULL - call not successful (PMP driver busy) !NULL - address of the display driver queue command 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-330 5.1.5.10.2.7.1.14 GFX_DRV_S1D13517_SetReg Function C uint16_t GFX_DRV_S1D13517_SetReg( uint8_t index, uint8_t value ); Description none Parameters Parameters Description index register number value value to write to register Returns 1 - call was not passed 0 - call was passed 5.1.5.10.2.7.1.15 GFX_DRV_S1D13517_Tasks Function C void GFX_DRV_S1D13517_Tasks(); 5.1.5.10.2.7.2 S1D13517 Data Types and Constants Structures Name Description GFX_DRV_S1D13517_COMMAND Structure for the commands in the driver queue. LAYER_REGISTERS This structure is used to describe layer registers. Description 5.1.5.10.2.7.2.1 GFX_DRV_S1D13517_COMMAND Structure C typedef struct { uint8_t instance; short x; short y; uint16_t * array; uint16_t data; uint16_t count; uint16_t lineCount; uint8_t task; } GFX_DRV_S1D13517_COMMAND; Description Structure: GFX_DRV_S1D13517_COMMAND None 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-331 5.1.5.10.2.7.2.2 LAYER_REGISTERS Structure C typedef struct { uint8_t XStart; uint8_t XEnd; uint8_t YStart0; uint8_t YStart1; uint8_t YEnd0; uint8_t YEnd1; uint8_t StartAddress0; uint8_t StartAddress1; uint8_t StartAddress2; } LAYER_REGISTERS; Description This structure is used to describe layer registers. 5.1.5.10.2.8 Files Files Name Description 5.1.5.10.2.8.1 drv_gfx_s1d13517_config_template.h • Module for Microchip Graphics Library • This file contains compile time options for the Graphics Library. ******************************************************************* • FileName: GraphicsConfig.h • Dependencies: none • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: C30 V3.00/C32 • Company: Microchip Technology, Inc. * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-332 • SOFTWARE AND DOCUMENTATION ARE PROVIDED ?AS IS? WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • Anton Alkhimenok 10/28/2007 Initial Version • Pradeep Budagutta 10/28/2007 Display related defines • moved to DisplayConfig.h 5.1.5.10.3 SSD1926 Graphics Controller Driver Library 5.1.5.10.3.1 Introduction SSD1926 Graphics Controller Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the SSD1926 Graphics Controller Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.10.3.2 Release Notes MPLAB Harmony Version: v0.70b SSD1926 Graphics Controller Driver Library Version : 4.00b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-333 5.1.5.10.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.5.10.3.4 Using the Library This topic describes the basic architecture of the SSD1926 Graphics Controller Driver Library and provides information and examples on how to use it. Interface Header File: drv_gfx_ssd1926.h The interface to the SSD1926 Graphics Controller Driver Library is defined in the "drv_gfx_ssd1926.h" header file. This file is included by the "gfx_primitive.h" file. Any C language source (.c) file that uses the SSD1926 Graphics Controller Driver Library should include "gfx_primitive.h". Library File: The SSD1926 Graphics Controller Driver Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the SSD1926 Graphics Controller Driver Library interacts with the framework. 5.1.5.10.3.4.1 Abstraction Model This library provides the low-level abstraction of the SSD1926 Graphics Controller Driver module of the Microchip family of graphic display controllers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description SSD1926 Graphics Controller Driver Abstraction Block Diagram Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.5.10.3.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SSD1926 Graphics Controller Driver module. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-334 Library Interface Section Description Functions This section lists the API functions available in the library. 5.1.5.10.3.5 Configuring the Library The configuration of the SSD1926 Graphics Controller Driver is based on the file system_config.h. This header file contains the configuration selection for the SSD1926 Graphics Controller Driver. Based on the selections made, the SSD1926 Graphics Controller Driver will support or not support selected features. These configuration settings will apply to all instances of the SSD1926 Graphics Controller Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.5.10.3.6 Building the Library This section list the files that are available in the \src of the SSD1926 Graphics Controller Driver Library. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • drv_gfx_ssd1926.c 5.1.5.10.3.7 Library Interface This section describes the Application Programming Interface (API) functions of the SSD1926 Graphics Controller Driver Library. Refer to each section for a detailed description. 5.1.5.10.3.7.1 Functions Functions Name Description GFX_DRV_SSD1926_BarFill Hardware accelerated barfill function GFX_DRV_SSD1926_BrightnessSet Sets the brightness of the display backlight. GFX_DRV_SSD1926_Busy Returns non-zero if LCD controller is busy (previous drawing operation is not completed). GFX_DRV_SSD1926_Close closes an instance of the graphics controller GFX_DRV_SSD1926_GetReg returns graphics controller register value (byte access) GFX_DRV_SSD1926_Initialize resets LCD, initializes PMP GFX_DRV_SSD1926_Open opens an instance of the graphics controller GFX_DRV_SSD1926_PixelArrayGet gets an array of pixels of length count starting at *color GFX_DRV_SSD1926_PixelArrayPut outputs an array of pixels of length count starting at *color GFX_DRV_SSD1926_PixelPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_SSD1926_PixelsPut outputs one pixel into the frame buffer at the x,y coordinate given GFX_DRV_SSD1926_SetColor Sets the color for the driver instance GFX_DRV_SSD1926_SetInstance Sets the instance for the driver GFX_DRV_SSD1926_SetReg updates graphics controller register value (byte access) GFX_DRV_SSD1926_Tasks Task machine that renders the driver calls for the graphics library it must be called peridically to output the contents of its circular buffer 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-335 Description 5.1.5.10.3.7.1.1 GFX_DRV_SSD1926_BarFill Function C uint16_t GFX_DRV_SSD1926_BarFill( short left, short top, short right, short bottom ); Description see primitive BarFill Returns 1 - call not successful (PMP driver busy) 0 - call successful 5.1.5.10.3.7.1.2 GFX_DRV_SSD1926_BrightnessSet Function C void GFX_DRV_SSD1926_BrightnessSet( uint8_t instance, uint16_t level ); Description none Parameters Parameters Description 5.1.5.10.3.7.1.3 GFX_DRV_SSD1926_Busy Function C uint16_t GFX_DRV_SSD1926_Busy( uint8_t instance ); Description none Parameters Parameters Description instance driver instance Returns 1 - busy 0 - not busy 5.1.5.10.3.7.1.4 GFX_DRV_SSD1926_Close Function C uint16_t GFX_DRV_SSD1926_Close( uint8_t instance 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-336 ); Description none Returns 0 - instance closed 2 - instance doesn't exist 3 - instance already closed 5.1.5.10.3.7.1.5 GFX_DRV_SSD1926_GetReg Function C uint8_t GFX_DRV_SSD1926_GetReg( uint16_t index, uint8_t * data ); Description none Parameters Parameters Description index register number *data array to store data Returns 0 - when call was passed 5.1.5.10.3.7.1.6 GFX_DRV_SSD1926_Initialize Function C uint16_t GFX_DRV_SSD1926_Initialize( uint8_t instance ); Description none Parameters Parameters Description instance driver instance Returns 1 - call not successful (PMP driver busy) 0 - call successful 5.1.5.10.3.7.1.7 GFX_DRV_SSD1926_Open Function C uint16_t GFX_DRV_SSD1926_Open( uint8_t instance ); Description none 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-337 Returns 1 - driver not initialied 2 - instance doesn't exist 3 - instance already open instance to driver when successful 5.1.5.10.3.7.1.8 GFX_DRV_SSD1926_PixelArrayGet Function C uint16_t* GFX_DRV_SSD1926_PixelArrayGet( uint16_t * color, short x, short y, uint16_t count ); Description none Parameters Parameters Description instance driver instance *color start of the array x x coordinate of the start point. y y coordinate of the end point. count number of pixels Returns NULL - call not successful !NULL - address of the display driver queue command 5.1.5.10.3.7.1.9 GFX_DRV_SSD1926_PixelArrayPut Function C uint16_t* GFX_DRV_SSD1926_PixelArrayPut( uint16_t * color, short x, short y, uint16_t count, uint16_t lineCount ); Description none Parameters Parameters Description instance driver instance *color start of the array x x coordinate of the start point. y y coordinate of the end point. count number of pixels Returns NULL - call not successful !NULL - handle to the number of pixels remaining 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-338 5.1.5.10.3.7.1.10 GFX_DRV_SSD1926_PixelPut Function C uint16_t GFX_DRV_SSD1926_PixelPut( short x, short y ); Description none Parameters Parameters Description instance driver instance color color to output x,y pixel coordinates Returns NULL - call not successful !NULL - address of the display driver queue command 5.1.5.10.3.7.1.11 GFX_DRV_SSD1926_PixelsPut Function C uint16_t GFX_DRV_SSD1926_PixelsPut( short x, short y, uint16_t count, uint16_t lineCount ); Description none Parameters Parameters Description x,y pixel coordinates 5.1.5.10.3.7.1.12 GFX_DRV_SSD1926_SetColor Function C void GFX_DRV_SSD1926_SetColor( GFX_COLOR color ); Returns none 5.1.5.10.3.7.1.13 GFX_DRV_SSD1926_SetInstance Function C void GFX_DRV_SSD1926_SetInstance( uint8_t instance ); 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-339 Returns none 5.1.5.10.3.7.1.14 GFX_DRV_SSD1926_SetReg Function C uint16_t GFX_DRV_SSD1926_SetReg( uint16_t index, uint8_t value ); Description none Parameters Parameters Description index register number value value to write to register Returns 1 - call was not passed 0 - call was passed 5.1.5.10.3.7.1.15 GFX_DRV_SSD1926_Tasks Function C void GFX_DRV_SSD1926_Tasks(); 5.1.5.10.3.7.2 Data Types and Constants Structures Name Description GFX_DRV_SSD1926_COMMAND Structure for the commands in the driver queue. GFX_DRV_SSD1926_TASK Structure for the task machine Description 5.1.5.10.3.7.2.1 GFX_DRV_SSD1926_COMMAND Structure C typedef struct { uint8_t instance; uint32_t address; uint16_t * array; uint16_t data; uint16_t count; uint16_t lineCount; SSD1926_TASK task; } GFX_DRV_SSD1926_COMMAND; Description Structure: GFX_DRV_SSD1926_COMMAND None 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-340 Members Members Description uint32_t address; wether the task is complete or not 5.1.5.10.3.7.2.2 GFX_DRV_SSD1926_TASK Structure C typedef struct { uint8_t instance; uint32_t address; uint16_t color; uint8_t state; } GFX_DRV_SSD1926_TASK; Description Structure: GFX_DRV_SSD1926_TASK None 5.1.5.10.3.8 Files Files Name Description 5.1.5.10.3.8.1 drv_gfx_ssd1926_config_template.h • Module for Microchip Graphics Library • This file contains compile time options for the Graphics Library. ******************************************************************* • FileName: GraphicsConfig.h • Dependencies: none • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: C30 V3.00/C32 • Company: Microchip Technology, Inc. * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. 5.1 Driver Library Help MPLAB Harmony Help Graphics (GFX) Driver Library 5-341 * • SOFTWARE AND DOCUMENTATION ARE PROVIDED ?AS IS? WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • Anton Alkhimenok 10/28/2007 Initial Version • Pradeep Budagutta 10/28/2007 Display related defines • moved to DisplayConfig.h 5.1.6 Non-Volatile Memory (NVM) Driver Library 5.1.6.1 Introduction Non-Volatile Memory (NVM) Driver Library for Microchip Microcontrollers This library provides a low-level abstraction of the NVM Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The functions provides in the NVM Driver Library also perform certain mandatory assembly language instructions specific for access and modification of memory, which are thus abstracted. Memory Devices for PIC Microcontrollers There are two primary forms of on-chip memory available for PIC microcontrollers: programmable Flash memory and data EEPROM memory. The access mechanism for both of these types are varied and different techniques are specified for the same.: 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-342 Flash Program Memory The Flash program memory is readable, writeable, and erasable during normal operation over the entire operating voltage range. A read from program memory is executed at one byte/word at a time depending on the width of the data bus. A write to the program memory is executed in either blocks of specific sizes or a single word depending on the type of processor used. An erase is performed in blocks. A bulk erase may be performed from user code depending on the type of processor supporting the operation. Writing or erasing program memory will cease instruction fetches until the operation is complete, restricting memory access, and therefore preventing code execution. This is controlled by an internal programming timer. There are three processor dependant methods for program memory modification. • Run-Time Self Programming (RTSP) • In-Circuit Serial Programming (ICSP) • EJTAG programming This section describes the RTSP techniques. 5.1.6.2 Release Notes MPLAB Harmony Version: v0.70b NVM Driver Library Version : 0.01 Release Date: 18Nov2013 New This Release: • Internal handling of erase feature for sector write function Known Issues: • Not tested by mapping the image to different parts of the memory 5.1.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-343 5.1.6.4 Using the Library This topic describes the basic architecture of the NVM Driver Library and provides information and examples on how to use it. Interface Header File: drv_nvm.h The interface to the NVM Driver Library is defined in the "drv_nvm.h" header file. Any C language source (.c) file that uses the NVM Driver library should include "drv.h". Library File: The NVM Driver Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.6.4.1 Abstraction Model This library provides a low-level abstraction of the NVM module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description NVM Software Abstraction Block Diagram Note 1: This feature is not available on all devices. Refer to the specific device data sheet to determine availability. Abstraction Model The NVM peripheral library provides interface routines to interact with the blocks shown in the diagram. The Flash Status and Control Logic ensures that the Flash memory is configured appropriately for modification. It also provides the status of the different operations in progress as well as errors, if any. It also decides if the operation is for Flash program memory or the special device configuration registers. The Flash Read/Write block ensures that the user data is written to/read from the program memory holding latches. It provides a layer of abstraction over the sequence of processor-specific instructions that are required to access this data. Depending on the processor type either block or Word programming options area available. 5.1.6.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various subsections, each of the sub-sections addresses one of the blocks or the 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-344 overall operation of the NVM module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Core Functions Provides open, close, status and other setup functions. Client Block Transfer Functions Provides buffered data operation functions available in the core configuration. Miscellaneous Functions Provides driver miscellaneous functions related to versions and others. 5.1.6.4.3 How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the modes supported for your device. 5.1.6.4.3.1 System Initialization This section provides information for system initialization and reinitialization. Description System Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the NVM module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_NVM_INIT or by using initialization overrides) that are supported by the specific NVM device hardware: • Device requested power state: One of the system module power states. For specific details please refer to the Data Types and Constants section. • The actual peripheral ID enumerated as the PLIB level module ID (e.g., NVM_ID_0) • Defining the respective interrupt sources for transmit (TX), receive (RX), and error interrupts The DRV_NVM_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the initialize interface would be used by the other system interfaces, such as DRV_NVM_Reinitialize, DRV_NVM_Deinitialize, DRV_NVM_Status, and DRV_NVM_Tasks. Note: The system initialization and the reinitialization settings, only effect the instance of the peripheral that is being initialized or reinitialized. The SYS_MODULE_INDEX is passed to the DRV_NVM_Initialize function tol determine which type of memory is selected using: • DRV_NVM_INDEX_0 - FLASH Example: // This code snippet shows an example // of initializing the NVM Driver. DRV_NVM_INIT NVMInitData; SYS_MODULE_OBJ objectHandle; 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-345 NVMInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; NVMInitData.moduleId = NVM_ID_0; NVMInitData.flashInterruptSource = INT_SOURCE_FLASH_CONTROL; //usage of DRV_NVM_INDEX_0 indicates usage of flash realted APIs objectHandle = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT*)NVMInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will call DRV_NVM_Tasks, from system task service (in a polled environment) or DRV_NVM_Taskswill be called from the Interrupt Service Routine (ISR) of the NVM. 5.1.6.4.3.2 Client Access Operation This section provides information for general client operation. Description General Client Operation For the application to start using an instance of the module, it must call the DRV_NVM_Open function. This provides the configuration required to open the NVM instance for operation. If the driver is deinitialized using the function DRV_NVM_Deinitialize, the application must call the DRV_NVM_Open function again to set up the instance of the NVM. The function DRV_NVM_Open need not be called again if the system is reinitialized using the DRV_NVM_Reinitialize function. For the various options available for I/O INTENT please refer to the Data Types and Constants section. Example: DRV_HANDLE handle; handle = DRV_NVM_Open(DRV_NVM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.6.4.3.3 Client Basic Operation This section provides information for client basic functionality. Description An extremely basic interface for the driver operation is provided through client basic functionality. The NVM driver provides the word and row programming operations in the basic mode of operation. The type of memory on which these operations will be performed is provided as an index while initialization. The SYS_MODULE_INDEX is passed to the DRV_NVM_Initialize function to determine which type of memory is selected using: • DRV_NVM_INDEX_0 - FLASH Note: Not all devices support the word/row programming operations. It is the responsibility of the user to determine which devices support which mode of operation. The memory access method described in this document only refers to Real-Time Self-Programming (RTSP). Word Programming Operations Applications using the NVM word write functionality need to perform the following: 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-346 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_NVM_Open with the necessary intent. 3. Provide the desired mode of operation using the operation mode. 4. Write a word using DRV_NVM_WriteWord. 5. The client will be able to close itself using the DRV_NVM_Close when required. DRV_HANDLE handle; // Returned from DRV_NVM_Open char myBuffer[MY_BUFFER_SIZE]; char* nvmAddr = BASE_ADDRESS_OF_NVM_TO_WRITE_TO DRV_NVM_OPERATION_STATUS myStatus = 0; myStatus = DRV_NVM_WriteWord( handle, myBuffer, nvmAddr); if(myStatus == DRV_NVM_STATUS_OPERATION_COMPLETE) { //Write successful } Applications using the NVM word erase functionality need to perform the following: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_NVM_Open with the necessary intent. 3. Provide the desired mode of operation using the operation mode. 4. Erase a word using DRV_NVM_EraseWord. 5. The client will be able to close itself using the DRV_NVM_Close when required. DRV_HANDLE handle; // Returned from DRV_NVM_Open char* nvmAddr = BASE_ADDRESS_OF_NVM_TO_ERASE_FROM DRV_NVM_OPERATION_STATUS myStatus = 0; myStatus = DRV_NVM_EraseWord( handle, myBuffer, nvmAddr); if(myStatus == DRV_NVM_STATUS_OPERATION_COMPLETE) { //Erase successful } Row Programming Operations Applications using the NVM row erase functionality needs to perform the following: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_NVM_Open with the necessary intent. 3. Provide the desired mode of operation using the operation mode. 4. Erase a word using DRV_NVM_EraseROW. 5. The client will be able to close itself using the DRV_NVM_Close when required. DRV_HANDLE handle; // Returned from DRV_NVM_Open char* nvmAddr = BASE_ADDRESS_OF_NVM_TO_ERASE_FROM DRV_NVM_OPERATION_STATUS myStatus = 0; myStatus = DRV_NVM_EraseROW( handle, nvmAddr); if(myStatus == DRV_NVM_STATUS_OPERATION_COMPLETE) { //Erase successful 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-347 } 5.1.6.4.3.4 Client Block Data Operation Client Block Data functionality provides advanced interface for the driver operation. These block data functions depend heavily on the block sizes and boundaries of individual devices and the APIs are responsible for keeping that information transparent from the application. These operations return the number of bytes of a successfully executed operation. Block Operations Applications using the NVM block write functionality need to perform the following: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_NVM_Open with the necessary intent. 3. Provide the desired mode of operation using the operation mode. 4. Provide the source and destination addresses and begin write using DRV_NVM_Write. 5. The client will be able to close itself using the DRV_NVM_Close when required. DRV_HANDLE handle; // Returned from DRV_NVM_Open char myBuffer[2 * DRV_NVM_ROW_SIZE]; // Destination address should be row aligned. char *destAddress = (char *)NVM_BASE_ADDRESS_TO_WRITE; unsigned int count = 2 * MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Write(myNVMHandle, destAddress, &myBuffer[total], count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait till the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); Applications using the NVM block Read functionality need to perform the following: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_NVM_Open with the necessary intent. 3. Provide the desired mode of operation using the operation mode. 4. Provide the source and destination addresses and begin write using DRV_NVM_ReadBlock. 5. The client will be able to close itself using the DRV_NVM_Close when required. DRV_HANDLE handle; // Returned from DRV_NVM_Open char myBuffer[MY_BUFFER_SIZE]; char *srcAddress = NVM_BASE_ADDRESS_TO_READ_FROM; unsigned int count = MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Read(myNVMHandle, &myBuffer[total], srcAddress, count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-348 } // Wait till the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); Internally, a buffer is maintained whose status can be obtained by calling API DRV_NVM_BufferStatus. 5.1.6.5 Configuring the Library Macros Name Description DRV_NVM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_NVM_CLIENTS_NUMBER Selects the maximum number of clients DRV_NVM_ERASE_SIZE Specifies the NVM Driver Erase Page Size in bytes. DRV_NVM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_NVM_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode DRV_NVM_ROW_SIZE Specifies the NVM Driver Program Row Size in bytes. DRV_NVM_UNLOCK_KEY1 Specifies the NVM Driver Program Unlock Key 1 DRV_NVM_UNLOCK_KEY2 Specifies the NVM Driver Program Unlock Key 2 Description The configuration of the NVM Driver is based on the file sys_config.h This header file contains the configuration selection for the NVM Driver. Based on the selections made, the NVM Driver will support or not support selected features. These configuration settings will apply to all instances of the NVM Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.6.5.1 DRV_NVM_BUFFER_OBJECT_NUMBER Macro C #define DRV_NVM_BUFFER_OBJECT_NUMBER 5 Description NVM Driver maximum number of buffer objects This definition selects the maximum number of buffer objects. This indirectly also specifies the queue depth. The NVM Driver can queue up DRV_NVM_BUFFER_OBJECT_NUMBER of read/write/erase requests before return a DRV_NVM_BUFFER_HANDLE_INVALID due to the queue being full. Increasing this number increases the RAM requirement of the driver. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-349 5.1.6.5.2 DRV_NVM_CLIENTS_NUMBER Macro C #define DRV_NVM_CLIENTS_NUMBER 1 Description NVM maximum number of clients This definition selects the maximum number of clients that the NVM driver can supported at run time. Remarks None. 5.1.6.5.3 DRV_NVM_ERASE_SIZE Macro C #define DRV_NVM_ERASE_SIZE 4096 Description NVM Driver Erase Page Size. This definition specifies the NVM Driver Erase Page Size in bytes. This parameter is device specific and should be obtained from the device specific data sheet. The Erase Page Size is the minimum block size that can be erased in one erase operation. Remarks None. 5.1.6.5.4 DRV_NVM_INSTANCES_NUMBER Macro C #define DRV_NVM_INSTANCES_NUMBER 1 Description NVM Driver instance configuration This definition selects the maximum number of Driver instances that can be supported by the dynamic driver. In case of this driver, multiple instances of the driver could use the same hardware instance. Remarks None 5.1.6.5.5 DRV_NVM_INTERRUPT_MODE Macro C #define DRV_NVM_INTERRUPT_MODE false Description NVM interrupt and polled mode operation control This macro specifies operation of the driver to be in the interrupt mode or polled mode 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-350 • true - Select if interrupt mode of NVM operation is desired • false - Select if polling mode of NVM operation is desired Not defining this option to true or false will result in build error. Remarks None. 5.1.6.5.6 DRV_NVM_ROW_SIZE Macro C #define DRV_NVM_ROW_SIZE 512 Description NVM Driver Program Row Size. This definition specifies the NVM Driver Program Row Size in bytes. This parameter is device specific and should be obtained from the device specific data sheet. The Program Row Size is the minimum block size that can be programmed in one program operation. Remarks None. 5.1.6.5.7 DRV_NVM_UNLOCK_KEY1 Macro C #define DRV_NVM_UNLOCK_KEY1 0xAA996655 Description NVM Driver Program Unlock Key 1 This definition specifies the NVM Driver Program Unlock Key 1 parameter is device specific and should be obtained from the device specific data sheet. Remarks None. 5.1.6.5.8 DRV_NVM_UNLOCK_KEY2 Macro C #define DRV_NVM_UNLOCK_KEY2 0x556699AA Description NVM Driver Program Unlock Key 2 This definition specifies the NVM Driver Program Unlock Key 2 parameter is device specific and should be obtained from the device specific data sheet. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-351 5.1.6.6 Building the Library This section list the files that are available in the \src of the NVM driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.6.7 Library Interface Data Types and Constants Name Description DRV_NVM_BUFFER_HANDLE_INVALID This value defines the NVM Driver Buffer Invalid handle. DRV_NVM_INDEX_0 NVM driver index definitions DRV_NVM_INDEX_COUNT Number of valid NVM driver indices DRV_NVM_BUFFER_HANDLE This type defines the NVM Driver Buffer handle. DRV_NVM_BUFFER_STATUS Specifies the status of the buffer for the read, write and erase opeartions. DRV_NVM_CLIENT_STATUS Defines the client status DRV_NVM_INIT Defines the data required to initialize or reinitialize the NVM driver DRV_NVM_INDEX_1 This is macro DRV_NVM_INDEX_1. Client Block Data Functions Name Description DRV_NVM_Erase Erase the specified number of pages in flash memory. DRV_NVM_Read Reads a block of data from the specified address in memory. DRV_NVM_Tasks Maintains the driver's erase and write state machine and implements its ISR. DRV_NVM_Write Write a block of data to a specified address in memory. Client Core Functions Name Description DRV_NVM_ClientStatus Gets current client-specific status the NVM driver DRV_NVM_Close Closes an opened-instance of the NVM driver DRV_NVM_Open Opens the specified timer driver instance and returns a handle to it Miscellaneous Functions Name Description DRV_NVM_BufferStatus Gets the current status of the buffer. System Functions Name Description DRV_NVM_Deinitialize Deinitializes the specified instance of the NVM driver module DRV_NVM_Initialize Initializes the NVM instance for the specified driver index DRV_NVM_Status Gets the current status of the NVM driver module. Description This section describes the Application Programming Interface (API) functions of the NVM Driver Library. Refer to each section for a detailed description. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-352 5.1.6.7.1 System Functions 5.1.6.7.1.1 DRV_NVM_Deinitialize Function C void DRV_NVM_Deinitialize( SYS_MODULE_OBJ object ); Description Deinitializes the specified instance of the NVM driver module, disabling its operation (and any hardware). Invalidates all the internal data. Preconditions Function DRV_NVM_Initialize should have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from the DRV_NVM_Initialize routine Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_NVM_Status operation. The system has to use DRV_NVM_Status to find out when the module is in the ready state. Example // This code snippet shows an example // of deinitializng the driver. SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize SYS_STATUS status; DRV_NVM_Deinitialize(object); status = DRV_NVM_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.6.7.1.2 DRV_NVM_Initialize Function C SYS_MODULE_OBJ DRV_NVM_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-353 Description This routine initializes the NVM driver instance for the specified driver index, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description index Identifier for the instance to be initialized also the type of memory used init Pointer to a data structure containing any data necessary to initialize the driver. Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Remarks This routine must be called before any other NVM routine is called. This routine should only be called once during system initialization unless DRV_NVM_Deinitialize is called to de-initialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_NVM_Status operation. The system must use DRV_NVM_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this routine. Example // This code snippet shows an example // of initializing the NVM Driver. DRV_NVM_INIT NVMInitData; SYS_MODULE_OBJ objectHandle; NVMInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; NVMInitData.moduleId = NVM_ID_0; NVMInitData.flashInterruptSource = INT_SOURCE_FLASH_CONTROL; //usage of DRV_NVM_INDEX_0 indicates usage of flash realted APIs objectHandle = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT*)NVMInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.1.6.7.1.3 DRV_NVM_Status Function C SYS_STATUS DRV_NVM_Status( SYS_MODULE_OBJ object ); Description This routine provides the current status of the NVM driver module. Preconditions Function DRV_NVM_Initialize should have been called before calling this function. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-354 Parameters Parameters Description object Driver object handle, returned from the DRV_NVM_Initialize routine Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations. Note Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Remarks Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This routine will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize SYS_STATUS NVMStatus; NVMStatus = DRV_NVM _Status(object); else if (SYS_STATUS_ERROR >= NVMStatus) { // Handle error } 5.1.6.7.2 Client Core Functions 5.1.6.7.2.1 DRV_NVM_ClientStatus Function C DRV_NVM_CLIENT_STATUS DRV_NVM_ClientStatus( const DRV_HANDLE handle ); Description This routine gets the client-specfic status of the NVM driver associated with the given handle. Preconditions The DRV_NVM_Initialize routine must have been called. DRV_NVM_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-355 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_NVM_CLIENT_STATUS value describing the current status of the driver Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open DRV_NVM_CLIENT_STATUS clientStatus; clientStatus = DRV_NVM_ClientStatus(handle); if(DRV_NVM_CLIENT_STATUS_ERROR >= clientStatus) { // Handle the error } 5.1.6.7.2.2 DRV_NVM_Close Function C void DRV_NVM_Close( const DRV_HANDLE handle ); Description This routine closes an opened-instance of the NVM driver, invalidating the handle. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_NVM_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_NVM_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-356 DRV_NVM_Close(handle); 5.1.6.7.2.3 DRV_NVM_Open Function C DRV_HANDLE DRV_NVM_Open( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); Description This routine opens the specified NVM driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions Function DRV_NVM_Initialize must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "or'd" together to indicate the intended use of the driver Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_NVM_Close routine is called. This routine will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, then other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_NVM_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Example DRV_HANDLE handle; handle = DRV_NVM_Open(DRV_NVM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.6.7.3 Client Block Data Functions 5.1.6.7.3.1 DRV_NVM_Erase Function C DRV_NVM_BUFFER_HANDLE DRV_NVM_Erase( const DRV_HANDLE handle, 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-357 uint8_t * targetbuffer, const unsigned int numbytes ); Description This routine erases the specified number of pages in flash memory. It returns a buffer handle that can be queried by the DRV_NVM_BufferStatus() function to check for completion of the operation. The target address should be aligned on a DRV_NVM_PAGE_SIZE byte boundary. The number of bytes to write should be equal to or should be multiples of DRV_NVM_PAGE_SIZE. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_NVM_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine targetBuffer Start address in NVM memory from where the erase should begin. Should be aligned on a DRV_NVM_PAGE_SIZE byte boundary. numbytes Total number of pages to be erased expressed in bytes. This should be equal to or a multiple of DRV_NVM_PAGE_SIZE. Returns DRV_NVM_BUFFER_HANDLE_INVALID in case the operation was not successful. A valid handle otherwise. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_NVM_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_NVM_Open routine or the driver was built to only support non-blocking behavior the call will return immediately. Example // Returned from DRV_NVM_Open DRV_HANDLE handle; // Destination address should be row aligned. char *destAddress = (char *)NVM_BASE_ADDRESS_TO_ERASE; unsigned int count = 2 * DRV_NVM_PAGE_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Write(myNVMHandle, destAddress, count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait till the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-358 5.1.6.7.3.2 DRV_NVM_Read Function C DRV_NVM_BUFFER_HANDLE DRV_NVM_Read( const DRV_HANDLE handle, uint8_t * targetBuffer, uint8_t * srcAddress, const unsigned int numbytes ); Description This routine reads a block of data from the specified address in memory. It returns a buffer handle that can be queried by the DRV_NVM_BufferStatus() function to check for completion of the operation. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_NVM_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine targetBuffer Buffer into which the data read from the NVM instance will be placed. srcAddress The base address in NVM memory from data read should begin numbytes Total number of bytes that need to be read from the module instance (must be equal to or less than the size of the buffer) Returns DRV_NVM_BUFFER_HANDLE_INVALID in case the operation was not successful. A valid handle otherwise. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_NVM_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_NVM_Open routine or the driver was built to only support non-blocking behavior the call will return immediately, identifying how many bytes of data were actually copied into the client's buffer and the client must call DRV_NVM_Read again with adjusted parameters as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open char myBuffer[MY_BUFFER_SIZE]; char *srcAddress = NVM_BASE_ADDRESS_TO_READ_FROM; unsigned int count = MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Read(myNVMHandle, &myBuffer[total], srcAddress, count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait till the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-359 5.1.6.7.3.3 DRV_NVM_Tasks Function C void DRV_NVM_Tasks( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal write and erase state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_NVM_Initialize) Returns None. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. This routine may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize while (true) { DRV_NVM_Tasks (object); // Do other tasks } 5.1.6.7.3.4 DRV_NVM_Write Function C DRV_NVM_BUFFER_HANDLE DRV_NVM_Write( DRV_HANDLE handle, uint8_t * destination, uint8_t * source, const unsigned int nBytes ); Description This routine writes a block of data to a specified address in memory. It returns a buffer handle that can be queried by the DRV_NVM_BufferStatus() function to check for completion of the operation. The contents of the source buffer should not be changed while the operation is in progress. The target address should be aligned on a DRV_NVM_ROW_SIZE byte boundary. The number of bytes to write should be equal to or should be multiples of DRV_NVM_ROW_SIZE. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-360 DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_NVM_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine targetBuffer Buffer in NVM memory where the data from srcAddress will be placed. Should be aligned on a DRV_NVM_ROW_SIZE byte boundary. srcAddress The source buffer containing data to programmed into NVM numbytes Total number of bytes that need to be written to the NVM. This should be equal to or a multiple of DRV_NVM_ROW_SIZE. Returns DRV_NVM_BUFFER_HANDLE_INVALID in case the operation was not successful. A valid handle otherwise. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_NVM_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_NVM_Open routine or the driver was built to only support non-blocking behavior the call will return immediately. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open char myBuffer[2 * DRV_NVM_ROW_SIZE]; // Destination address should be row aligned. char *destAddress = (char *)NVM_BASE_ADDRESS_TO_WRITE; unsigned int count = 2 * MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Write(myNVMHandle, destAddress, &myBuffer[total], count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait till the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); 5.1.6.7.4 Client Basic Functions 5.1.6.7.5 Miscellaneous Functions 5.1.6.7.5.1 DRV_NVM_BufferStatus Function C DRV_NVM_BUFFER_STATUS DRV_NVM_BufferStatus( DRV_HANDLE handle, const DRV_HANDLE bufferHandle ); 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-361 Description This routine gets the current status of the buffer. The application must use this routine in case a polling based implementation is desired. Preconditions The DRV_NVM_Initialize routine must have been called. DRV_NVM_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_NVM_BUFFER_STATUS value describing the current status of the buffer Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open DRV_HANDLE bufferHandle; DRV_NVM_BUFFER_STATUS status; status = DRV_NVM_BufferStatus(handle, bufferHandle); if(status == DRV_NVM_BUFFER_COMPLETED) { // Operation Done } 5.1.6.7.6 Data Types and Constants 5.1.6.7.6.1 DRV_NVM_BUFFER_HANDLE_INVALID Macro C #define DRV_NVM_BUFFER_HANDLE_INVALID Description NVM Driver Buffer Invalid Handle This value defines the NVM Driver Buffer Invalid handle. This value is returned by read/write/erase routines when the desired operation could not be completed. Remarks None. 5.1.6.7.6.2 DRV_NVM_INDEX_0 Macro C #define DRV_NVM_INDEX_0 0 Description Driver NVM Module Index reference These constants provide NVM driver index definitions. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-362 Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_NVM_Initialize and DRV_NVM_Open routines to identify the driver instance in use. 5.1.6.7.6.3 DRV_NVM_INDEX_COUNT Macro C #define DRV_NVM_INDEX_COUNT 1 Description NVM Driver Module Index Count This constant identifies NVM driver index definitions. Remarks This constant should be used in place of hard-coded numeric literals. This value is part-specific. 5.1.6.7.6.4 DRV_NVM_BUFFER_HANDLE Type C typedef uintptr_t DRV_NVM_BUFFER_HANDLE; Description NVM Driver Buffer Handle This type defines the NVM Driver Buffer handle. Remarks None. 5.1.6.7.6.5 DRV_NVM_BUFFER_STATUS Enumeration C typedef enum { DRV_NVM_BUFFER_COMPLETED = 0, DRV_NVM_BUFFER_QUEUED = 1, DRV_NVM_BUFFER_IN_PROGRESS = 2, DRV_NVM_BUFFER_ERROR_UNKNOWN = -1 } DRV_NVM_BUFFER_STATUS; Description NVM Driver Buffer Status This type specifies the status of the buffer for the read, write and erase opeartions. Members Members Description DRV_NVM_BUFFER_COMPLETED = 0 Done OK and ready DRV_NVM_BUFFER_QUEUED = 1 Scheduled but not started DRV_NVM_BUFFER_IN_PROGRESS = 2 Currently being in transfer DRV_NVM_BUFFER_ERROR_UNKNOWN = -1 Unknown buffer 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-363 Remarks None. 5.1.6.7.6.6 DRV_NVM_CLIENT_STATUS Enumeration C typedef enum { DRV_NVM_CLIENT_STATUS_READY, DRV_NVM_CLIENT_STATUS_BUSY, DRV_NVM_WRITE_TERMINATED, DRV_NVM_ERASE_TERMINATED, DRV_NVM_LOW_VOLTAGE_ERROR, DRV_NVM_LOW_VOLTAGE_DETECT_ERROR, DRV_NVM_STATUS_INVALID } DRV_NVM_CLIENT_STATUS; Description NVM Client Status Defines the various client status codes. Members Members Description DRV_NVM_CLIENT_STATUS_READY Up and running, ready to start new operations DRV_NVM_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_NVM_WRITE_TERMINATED Write operation terminated Occured DRV_NVM_ERASE_TERMINATED Erase operation terminated Occured DRV_NVM_LOW_VOLTAGE_ERROR Low voltage Error DRV_NVM_LOW_VOLTAGE_DETECT_ERROR Low voltage Error DRV_NVM_STATUS_INVALID Client Invalid Remarks None 5.1.6.7.6.7 DRV_NVM_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; NVM_MODULE_ID nvmID; INT_SOURCE interruptSource; } DRV_NVM_INIT; Description NVM Driver Initialization Data This data type defines the data required to initialize or reinitialize the NVM driver. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization NVM_MODULE_ID nvmID; Identifies NVM hardware module (PLIB-level) ID INT_SOURCE interruptSource; Interrupt Source for Write Interrupt 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-364 Remarks Not all the init features are available for all the microcontrollers 5.1.6.7.6.8 DRV_NVM_INDEX_1 Macro C #define DRV_NVM_INDEX_1 1 Description This is macro DRV_NVM_INDEX_1. 5.1.6.8 Files Files Name Description drv_nvm.h NVM Driver Interface Definition drv_nvm_config_template.h NVM driver configuration definitions template Description 5.1.6.8.1 drv_nvm.h NVM Driver Interface Definition The NVM device driver provides a simple interface to manage the NVM modules on Microchip microcontrollers. This file defines the interface definition for the NVM driver. Enumerations Name Description DRV_NVM_BUFFER_STATUS Specifies the status of the buffer for the read, write and erase opeartions. DRV_NVM_CLIENT_STATUS Defines the client status Functions Name Description DRV_NVM_BufferStatus Gets the current status of the buffer. DRV_NVM_ClientStatus Gets current client-specific status the NVM driver DRV_NVM_Close Closes an opened-instance of the NVM driver DRV_NVM_Deinitialize Deinitializes the specified instance of the NVM driver module DRV_NVM_Erase Erase the specified number of pages in flash memory. DRV_NVM_Initialize Initializes the NVM instance for the specified driver index DRV_NVM_Open Opens the specified timer driver instance and returns a handle to it DRV_NVM_Read Reads a block of data from the specified address in memory. DRV_NVM_Status Gets the current status of the NVM driver module. DRV_NVM_Tasks Maintains the driver's erase and write state machine and implements its ISR. DRV_NVM_Write Write a block of data to a specified address in memory. 5.1 Driver Library Help MPLAB Harmony Help Non-Volatile Memory (NVM) Driver Library 5-365 Macros Name Description DRV_NVM_BUFFER_HANDLE_INVALID This value defines the NVM Driver Buffer Invalid handle. DRV_NVM_INDEX_0 NVM driver index definitions DRV_NVM_INDEX_1 This is macro DRV_NVM_INDEX_1. DRV_NVM_INDEX_COUNT Number of valid NVM driver indices Structures Name Description DRV_NVM_INIT Defines the data required to initialize or reinitialize the NVM driver Types Name Description DRV_NVM_BUFFER_HANDLE This type defines the NVM Driver Buffer handle. File Name drv_nvm.h Company Microchip Technology Incorported 5.1.6.8.2 drv_nvm_config_template.h NVM Driver Configuration Definitions for the template version These definitions statically define the driver's mode of operation. Macros Name Description DRV_NVM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_NVM_CLIENTS_NUMBER Selects the maximum number of clients DRV_NVM_ERASE_SIZE Specifies the NVM Driver Erase Page Size in bytes. DRV_NVM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_NVM_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode DRV_NVM_ROW_SIZE Specifies the NVM Driver Program Row Size in bytes. DRV_NVM_UNLOCK_KEY1 Specifies the NVM Driver Program Unlock Key 1 DRV_NVM_UNLOCK_KEY2 Specifies the NVM Driver Program Unlock Key 2 File Name drv_NVM_config_template.h Company Microchip Technology Incorported 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-366 5.1.7 Parallel Master Port (PMP) Driver Library 5.1.7.1 Introduction PMP Driver Library for Microchip Microcontrollers This library provides an interface to manage the Parallel Master Port (PMP) module on Microchip family of microcontrollers in different modes of operation. Description The Parallel Master Port (PMP) is a parallel 8-bit/16-bit I/O module specifically designed to communicate with a wide variety of parallel devices such as communications peripherals, LCDs, external memory devices and microcontrollers. Because the interfaces to parallel peripherals vary significantly, the PMP module is highly configurable. The following figure shows a generic block diagram of the ways PMP module can be used: PMP module can be used in different modes. Master and Slave are the two modes which can further have sub-modes depending on the different microcontroller families. Master Mode: In master mode, the PMP module can provide a 8-bit or 16-bit data bus, up to 16 bits of address, and all the necessary control signals to operate a variety of external parallel devices such as memory devices, peripherals and slave microcontrollers. The PMP master modes provide a simple interface for reading and writing data, but not executing program instructions from external devices, such as SRAM or Flash memories. Slave Mode: Slave modes support 8-bit data only and the module control pins are automatically dedicated when this mode is selected. 5.1.7.2 Release Notes MPLAB Harmony Version: v0.70b PMP Driver Library Version : 0.01 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-367 Known Issues: Nothing to report in this release. 5.1.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.7.4 Using the Library This topic describes the basic architecture of the PMP Driver Library and provides information and examples on how to use it. Interface Header File: drv_pmp.h The interface to the PMP Driver library is defined in the "drv_pmp.h" header file. This file is included by the "drv.h" file. Any C language source (.c) file that uses the PMP Driver Library should include "drv.h". Library File: The PMP Driver Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.7.4.1 Abstraction Model This library provides a low-level abstraction of the Parallel Master Port (PMP) module on Microchip's microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Description The PMP module provides interface routines to interact with external peripherals such as LCD, EEPROM, Flash memory, etc., as shown in the following diagram. The diagram shows the PMP module acting as a master. The PMP module can be easily configured to act as a slave. The address and data lines can be multiplexed to suit the application. The address and data buffers are up to 2-byte (16-bit) buffers for data transmitted or received by the parallel interface to the PMP bus over the data and address lines synchronized with control logic including the read and write strobe. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-368 PMP Hardware Abstraction Model Diagram The desired timing wait states to suit different peripheral timings can also be programmed using the PMP module. 5.1.7.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each sub-section addresses one of the blocks or the overall operation of the PMP module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, re-initialization, tasks, and status functions. Client Interaction Functions Provides open, close, client status and client mode configuration functions. Client Transfer Functions Provides interface for data transfer in master and slave mode. Miscellaneous Provides driver miscellaneous functions, version identification functions etc. 5.1.7.4.3 How the Library Works This section describes how the PMP Driver Library operates. Description Before the driver is ready for use, its should be configured (compile time configuration). Refer to the Configuring the Library section for more details on how to configure the driver. There are few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. To use the PMP Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. The following is the sequence in which various routines should be called: 1. Call DRV_PMP_Init to initialize the PMP Driver. Note that this may be performed by the MPLAB Harmony system module. The DRV_PMP_Status function may be used to check the status of the initialization. 2. Once initialization for a particular driver instance is done, the client wanting to use the driver can open it using API DRV_PMP_Open. 3. The DRV_PMP_ModeConfig function should now be called, which will configure the driver for the exact mode of operation required by that client. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-369 4. After configuring the mode, DRV_PMP_Write and/or DRV_PMP_Read can be called by the user application to Write/Read using the PMP module. Calling these functions does not start the PMP transfer immediately in non-interrupt mode. Instead, all of these transfer tasks are queued in an internal queue. Actual transfer starts only when the PMP Task function is called by the system/user. In interrupt mode, although transfer tasks are queued, the actual transfer starts immediately. 5. PMP Write and Read functions return an ID of that particular transfer, which should be saved by user to get the status of that transfer later. 6. The system will either call DRV_PMP_Tasks from the System Task Service (in a polled environment), or it will be called from interrupt service routine of the PMP. 7. At any time status of the transfer can be obtained by using DRV_PMP_TransferStatus. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.1.7.4.3.1 System Initialization This section describes initialization and reinitialization features. Description Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the PMP device will be initialized with the following configuration settings: Initialization member Description moduleInit System module initialization of the power state. pmpId PMP hardware module ID (peripheral library-level ID). stopInIdle Decide whether or not the module should be stopped in Idle mode. muxMode To select one of the different multiplexing modes possible for PMP module. inputBuffer Select the type of Input Buffer will be of TTL or Schmitt Trigger. polarity Select polarity of different PMP pins. ports Set the pins the user wants to use as port or PMP pins. The DRV_PMP_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the initialize interface would be used by the other system interfaces, such as DRV_PMP_Reinitialize, DRV_PMP_Deinitialize, DRV_PMP_Status, and DRV_PMP_Tasks. Example for PMP Initialization Through the DRV_PMP_INIT Structure DRV_PMP_INIT init; SYS_MODULE_OBJ object; SYS_STATUS pmpStatus; // populate the PMP init configuration structure init.inputBuffer = PMP_INPUT_BUFFER_TTL; init.polarity.addressLatchPolarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.rwStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.writeEnableStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.chipselect1Polarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.chipselect2Polarity = PMP_POLARITY_ACTIVE_LOW; init.ports.addressPortsMask = PMP_PMA0_PORT | PMP_PMA1_PORT | PMP_PMA2_TO_PMA13_PORTS | PMP_PMA14_PORT; init.ports.readWriteStrobe = PORT_ENABLE; init.ports.writeEnableStrobe = PORT_ENABLE; 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-370 init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.pmpID = PMP_ID_0; init.stopInIdle = false; init.muxMode = PMP_MUX_NONE; object = DRV_PMP_Initialize (DRV_PMP_INDEX_0, (SYS_MODULE_INIT *)&init); pmpStatus = DRV_PMP_Status(object); if ( SYS_STATUS_READY != pmpStatus) { // Handle error } Deinitialization Once the initialize operation has been called, the deinitialize operation must be called before the initialize operation can be called again. This routine may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the function will never block for hardware PMP access. If the operation requires time to allow the hardware to complete, which will be reported by DRV_PMP_Status. Status PMP status is available to query the module state before, during and after initialization, deinitialization, and reinitialization. Tasks Routine The DRV_PMP_Tasks function will see the queue status and perform the task of transferring the data accordingly. In the Blocking mode when interrupts are disabled, it will finish one of the tasks completely (that means emptying one space in queue), and then return back. Whereas in Non-Blocking mode, it will return back just after starting one word (8-bit or 16-bit) of transfer (may not be emptying one space in the queue, as that task may not be completely finished). The DRV_PMP_Tasks function can be called in two ways: • By the system task service in a polled environment • By the interrupt service routine of the PMP in an interrupt-based system Example: Polling int main( void ) { SYS_MODULE_OBJ object; object = DRV_PMP_Initialize( DRV_PMP_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_PMP_Status( object ) ) return 0; while (1) { DRV_PMP_Tasks (object); } } Example: Interrupt int main( void ) { SYS_MODULE_OBJ object; object = DRV_PMP_Initialize( DRV_PMP_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_PMP_Status( object ) ) return 0; while (1); 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-371 } /* Sample interrupt routine not specific to any device family */ void ISR PMPInterrupt(void) { //Call the PMP Tasks routine DRV_PMP_Tasks(object); } Note: A PMP transfer in Blocking mode in an interrupt environment is not supported. 5.1.7.4.3.1.1 Transfer Operation This section describes transfer operation. Description Once the PMP Driver is open and configured for a client, it is set to start Reading/Writing through DRV_PMP_Read and DRV_PMP_Write. However, these functions will not directly start reading or writing. These will just put the relevant information in a queue in non-interrupt mode and return an ID that can be used later for checking the transfer status. In Interrupt mode, the Read/Write functions will trigger the transfer immediately after storing the transfer information in the queue. The user must use a buffer pointing to character for data values. The repeatCount parameter allows the user to repeatedly write the same nBytes of data into the slave devices. Example: unsigned char myReadBuffer[300], myWriteBuffer[100]; // has to be 'char' arrays uint32_t deviceAddress, nBytes, repeatCount, i; uint32_t writeID, readID; DRV_HANDLE handle; //initialize, open and configure the driver/client /* ... */ deviceAddress = 0x0206; nBytes = 100; repeatCount = 0x01; for (i=0; i= pmpStatus) { // Handle error } 5.1.7.7.1.4 DRV_PMP_Status Function C SYS_STATUS DRV_PMP_Status( const SYS_MODULE_OBJ pmpDriverObject ); Description This function provides the current status of the PMP driver module. Preconditions The DRV_PMP_Initialize function must have been called before calling this function. Parameters Parameters Description pmpDriverObject Driver object handle, returned from the DRV_PMP_Initialize routine Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-381 Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ pmpDriverObject; // Returned from DRV_PMP_Initialize SYS_STATUS status; status = DRV_PMP_Status(pmpDriverObject); else if (SYS_STATUS_ERROR >= status) { // Handle error } 5.1.7.7.1.5 DRV_PMP_Tasks Function C void DRV_PMP_Tasks( SYS_MODULE_OBJ pmpDriverObject ); Description This function is used to maintain the queue and execute the tasks stored in the queue. It resides in the ISR of the PMP for interrupt-driven implementations. Preconditions The DRV_PMP_Initialize function must have been called for the specified PMP driver instance. Parameters Parameters Description pmpDriverObject Object handle for the specified driver instance (returned from DRV_PMP_Initialize) Returns None. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ pmpDriverObject; // Returned from DRV_PMP_Initialize while (true) { 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-382 DRV_PMP_Tasks (pmpDriverObject); // Do other tasks } 5.1.7.7.2 Client Interaction Functions 5.1.7.7.2.1 DRV_PMP_ClientStatus Function C DRV_PMP_CLIENT_STATUS DRV_PMP_ClientStatus( DRV_HANDLE hClient ); Description This function gets the client-specfic status of the PMP driver associated with the specified handle. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine Returns A DRV_PMP_CLIENT_STATUS value describing the current status of the driver. Remarks This function will not block for hardware access and will immediately return the current status. Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open DRV_PMP_CLIENT_STATUS pmpClientStatus; pmpClientStatus = DRV_PMP_ClientStatus(hClient); if(DRV_PMP_CLIENT_STATUS_ERROR >= pmpClientStatus) { // Handle the error } 5.1.7.7.2.2 DRV_PMP_Close Function C void DRV_PMP_Close( const DRV_HANDLE hClient ); Description This function closes an opened instance of the PMP driver, invalidating the handle. Preconditions The DRV_PMP_Initialize routine must have been called for the specified PMP driver instance. DRV_PMP_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-383 Parameters Parameters Description hClient A valid open instance handle, returned from the driver's open routine Returns None Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_PMP_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_PMP_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open DRV_PMP_Close(hClient); 5.1.7.7.2.3 DRV_PMP_ModeConfig Function C void DRV_PMP_ModeConfig( DRV_HANDLE hClient, DRV_PMP_MODE_CONFIG config ); Description This function configures the modes for client in which it wants to operate. Different master-slave modes, 8/16 data bits selection, address increment/decrement, interrupt mode, wait states, etc., can be configured through this function. Preconditions Function DRV_PMP_Initialize must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description hClient Client handle obtained from DRV_PMP_Open API config Structure which will have all the required PMP modes configuration Returns None. Remarks This function will NEVER block waiting for hardware. If this API is called more than once for a particular client handle, previous config setting of that client will be overwritten. Example DRV_HANDLE hClient; DRV_PMP_MODE_CONFIG config; 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-384 config.chipSelect = PMCS1_AND_PMCS2_AS_CHIP_SELECT; config.endianMode = LITTLE_ENDIAN; config.incrementMode = PMP_ADDRESS_AUTO_INCREMENT; config.intMode = PMP_INTERRUPT_NONE; config.pmpMode = PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT; config.portSize = PMP_DATA_SIZE_8_BITS; config.waitStates.dataHoldWait = PMP_DATA_HOLD_2; config.waitStates.dataWait = PMP_DATA_WAIT_THREE; config.waitStates.strobeWait = PMP_STROBE_WAIT_5; DRV_PMP_ModeConfig ( hClient, config ); 5.1.7.7.2.4 DRV_PMP_Open Function C DRV_HANDLE DRV_PMP_Open( const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent ); Description This function opens the specified PMP driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions The DRV_PMP_Initialize function must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_PMP_Close routine is called. This function will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_PMP_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Example DRV_HANDLE hClient; hClient = DRV_PMP_Open(DRV_PMP_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == hClient) { // Unable to open the driver } 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-385 5.1.7.7.2.5 DRV_PMP_Read Function C QUEUE_ELEMENT_OBJECT* DRV_PMP_Read( DRV_HANDLE hClient, uint32_t address, uint16_t* buffer, uint32_t nBytes ); Description This function reads the given number of data bytes from the given address of the external device to the MCU buffer through the selected PMP instance. This function should be used for all the master and slave modes. Proper configuration should be done using DRV_PMP_ModeConfig before calling this function. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. DRV_PMP_ModeConfig must have been called to configure the desired mode Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine address Starting address of the slave device from where data has to be read. It does not have any significance for legacy slave mode and buffer mode. In PMP enhanced slave mode i.e. addressable buffer slave mode, this parameter should be the buffer number to be used. buffer Pointer to the buffer into which the data read through the PMP instance will be placed. Even if only one word has to be tranferred, pointer should be used. nBytes Number of bytes that need to be read through the PMP instance Returns Returns the position number of the queue, where the data element was stored. Returns '0' when there is no place in the queue to store the data. Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open uint32_t deviceAddress; uint32_t nBytes; unsigned char myBuffer[nBytes]; uint32_t transferID; transferID = DRV_PMP_Read ( hClient, deviceAddress, &myBuffer, nBytes); 5.1.7.7.2.6 DRV_PMP_Write Function C QUEUE_ELEMENT_OBJECT* DRV_PMP_Write( DRV_HANDLE* hClient, bool address, uint32_t * buffer, uint32_t nBytes, uint32_t repeatCount ); Description This function transfer the given number of data bytes from the MCU buffer location to the defined address of the external device 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-386 through the selected PMP instance. It repeats the operation n (=repeatCount) number of times as well. This function should be used for all the master and slave modes. Proper configuration should be done using DRV_PMP_ModeConfig before calling this function. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. DRV_PMP_ModeConfig must have been called to configure the desired mode. Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine address Starting address of the slave device where data has to be written. It does not have any significance for legacy slave mode and buffer mode. In PMP enhanced slave mode (i.e., addressable buffer slave mode), this parameter should be the buffer number to be used. buffer Pointer to MCU Buffer from which the data will be written through the PMP instance. even if only one word has to be tranferred, pointer should be used. nBytes Total number of bytes that need to be written through the PMP instance repeatCount Number of times the data set (nBytes of data) to be repetedly written. This value should be 0 if user does not want any repetation. If repeatCount is greater than 0, then after writing every nBytes of data, the buffer starts pointing to its first element. Ideally, PMP Address should be in auto increment/decrement mode for repeatCount greater than 0. Returns Returns a 32-bit ID with which status of the transfer can be checked later. Returns '0' when there is no place in the queue to store the data. Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open uint32_t deviceAddress; uint32_t nBytes; unsigned char myBuffer[nBytes]; uint32_t repeatCount; uint32_t transferID; transferID = DRV_PMP_MasterWrite ( hClient, deviceAddress, &myBuffer, nBytes, repeatCount); 5.1.7.7.3 Client Transfer Functions 5.1.7.7.3.1 DRV_PMP_TransferStatus Function C DRV_PMP_TRANSFER_STATUS DRV_PMP_TransferStatus( QUEUE_ELEMENT_OBJECT* queueObject ); Description This function returns the status of a particular transfer whose ID has been specified as input. Parameters Parameters Description drvIndex Identifier for the object instance to be opened seqID A valid ID returned from read/write transfer functions 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-387 Returns A DRV_PMP_TRANSFER_STATUS value describing the current status of the transfer. Example uint32_8 seqID; DRV_PMP_TRANSFER_STATUS transferStatus; transferStatus = DRV_PMP_TransferStatus( DRV_PMP_INDEX_0, seqID); 5.1.7.7.4 Data Types and Constants 5.1.7.7.4.1 DRV_PMP_INDEX_COUNT Macro C #define DRV_PMP_INDEX_COUNT _PMP_EXISTS Description PMP Driver Module Index Count This constant identifies the number of valid PMP driver indices. Remarks The value of "_PMP_EXISTS" is derived from device-specific header files defined as part of the peripheral libraries. 5.1.7.7.4.2 DRV_PMP_CHIPX_STROBE_MODE Enumeration C typedef enum { PMP_RW_STROBE_WITH_ENABLE_STROBE, PMP_READ_AND_WRITE_STROBES } DRV_PMP_CHIPX_STROBE_MODE; Description PMP writeEnable/ReadWrite strobes This enumeration provides ReadWrite/WriteEnable Strobe definitions. Members Members Description PMP_RW_STROBE_WITH_ENABLE_STROBE One strobe for read/write and another for enable PMP_READ_AND_WRITE_STROBES Separate strobes for read and write operations 5.1.7.7.4.3 DRV_PMP_CLIENT_STATUS Enumeration C typedef enum { DRV_PMP_CLIENT_STATUS_INVALID, PMP_CLIENT_STATUS_CLOSED, DRV_PMP_CLIENT_STATUS_OPEN } DRV_PMP_CLIENT_STATUS; Description PMP Client Status This enumeration provides various client status possibilities. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-388 5.1.7.7.4.4 DRV_PMP_ENDIAN_MODE Enumeration C typedef enum { LITTLE, BIG } DRV_PMP_ENDIAN_MODE; Description PMP Endian modes This enumeration holds the endian configuration options. Members Members Description LITTLE Little Endian BIG Big Endian 5.1.7.7.4.5 DRV_PMP_INDEX Enumeration C typedef enum { DRV_PMP_INDEX_0, DRV_PMP_INDEX_1 } DRV_PMP_INDEX; Description PMP Driver Module Index Numbers These constants provide PMP driver index definitions. Members Members Description DRV_PMP_INDEX_0 First PMP instance DRV_PMP_INDEX_1 Second PMP instance (not avaialble for now) Remarks These values should be passed into the DRV_PMP_Initialize and DRV_PMP_Open functions to identify the driver instance in use. 5.1.7.7.4.6 DRV_PMP_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; PMP_MODULE_ID pmpID; bool stopInIdle; PMP_MUX_MODE muxMode; PMP_INPUT_BUFFER_TYPE inputBuffer; DRV_PMP_POLARITY_OBJECT polarity; DRV_PMP_PORTS ports; } DRV_PMP_INIT; Description PMP Driver Initialize Data 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-389 This data type defines data required to initialize or reinitialize the PMP driver. Members Members Description SYS_MODULE_INIT moduleInit; module power state info PMP_MODULE_ID pmpID; module PLIB ID bool stopInIdle; Stop in Idle enable PMP_MUX_MODE muxMode; MUX mode PMP_INPUT_BUFFER_TYPE inputBuffer; Input buffer type to be used DRV_PMP_POLARITY_OBJECT polarity; Polarity settings DRV_PMP_PORTS ports; PMP port settings Remarks Not all the initialization features are available for all devices. 5.1.7.7.4.7 DRV_PMP_MODE_CONFIG Structure C typedef struct { PMP_OPERATION_MODE pmpMode; PMP_INTERRUPT_MODE intMode; PMP_INCREMENT_MODE incrementMode; DRV_PMP_ENDIAN_MODE endianMode; PMP_DATA_SIZE portSize; DRV_PMP_WAIT_STATES waitStates; PMP_CHIPSELECT_FUNCTION chipSelect; } DRV_PMP_MODE_CONFIG; Description PMP modes configuration This data type controls the configuration of PMP modes. Members Members Description PMP_OPERATION_MODE pmpMode; PMP Usage Mode Type PMP_INTERRUPT_MODE intMode; Interrupt mode PMP_INCREMENT_MODE incrementMode; should be appropriately selected based on read/write requirements and operation mode setting */ address/buffer increment mode DRV_PMP_ENDIAN_MODE endianMode; it does not have any significance in PMP slave mode or 8bit data mode */ Endian modes PMP_DATA_SIZE portSize; Data Port Size DRV_PMP_WAIT_STATES waitStates; Wait states PMP_CHIPSELECT_FUNCTION chipSelect; use this when plib is fixed 5.1.7.7.4.8 DRV_PMP_POLARITY_OBJECT Structure C typedef struct { PMP_POLARITY_LEVEL addressLatchPolarity; PMP_POLARITY_LEVEL byteEnablePolarity; PMP_POLARITY_LEVEL rwStrobePolarity; PMP_POLARITY_LEVEL writeEnableStrobePolarity; 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-390 PMP_POLARITY_LEVEL chipselect1Polarity; PMP_POLARITY_LEVEL chipselect2Polarity; } DRV_PMP_POLARITY_OBJECT; Description PMP polarity object This structure holds the polarities of different entities to be configured. Members Members Description PMP_POLARITY_LEVEL addressLatchPolarity; Address latch polarity PMP_POLARITY_LEVEL byteEnablePolarity; ByteEnable port polarity PMP_POLARITY_LEVEL rwStrobePolarity; Read/Write strobe polarity PMP_POLARITY_LEVEL writeEnableStrobePolarity; Write/Enable strobe polarity PMP_POLARITY_LEVEL chipselect1Polarity; ChipSelect-1 Polarity PMP_POLARITY_LEVEL chipselect2Polarity; chipSelect-2 Polarity 5.1.7.7.4.9 DRV_PMP_PORT_CONTROL Enumeration C typedef enum { PORT_ENABLE, PORT_DISABLE } DRV_PMP_PORT_CONTROL; Description PMP port enable/disable. This enumeration provides port enable/disable values. Members Members Description PORT_ENABLE Enable the given port PORT_DISABLE Disable the given port 5.1.7.7.4.10 DRV_PMP_PORTS Structure C typedef struct { PMP_ADDRESS_PORT addressPortsMask; PMP_PMBE_PORT byteEnablePort; DRV_PMP_PORT_CONTROL readWriteStrobe; DRV_PMP_PORT_CONTROL writeEnableStrobe; } DRV_PMP_PORTS; Description PMP Ports This structure holds the ports (including the address ports) to be configured by the application to function as general purpose I/O (GPIO) or part of the PMP. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-391 Members Members Description PMP_ADDRESS_PORT addressPortsMask; User needs to put the address lines which he wants to use in OR'd fashion */ Address ports PMP_PMBE_PORT byteEnablePort; Byte enable ports DRV_PMP_PORT_CONTROL readWriteStrobe; READ/WRITE Strobe PORT DRV_PMP_PORT_CONTROL writeEnableStrobe; WRITE/ENABLE strobe port 5.1.7.7.4.11 DRV_PMP_QUEUE_ELEMENT_OBJ Type C typedef struct _DRV_PMP_QUEUE_ELEMENT_OBJ DRV_PMP_QUEUE_ELEMENT_OBJ; Description PMP Driver Queue Element Object This defines the object structure for each queue element of PMP. This object gets created for every Read/Write operations APIs. Remarks None 5.1.7.7.4.12 DRV_PMP_TRANSFER_STATUS Enumeration C typedef enum { MASTER_8BIT_TRANSFER_IN_PROGRESS = PMP_DATA_SIZE_8_BITS, MASTER_16BIT_TRANSFER_IN_PROGRESS = PMP_DATA_SIZE_16_BITS, MASTER_8BIT_BUFFER_IN_PROGRESS, MASTER_16BIT_BUFFER_IN_PROGRESS, MASTER_8BIT_BUFFER_CONTINUE, QUEUED_BUT_PMP_TRANSFER_NOT_STARTED, PMP_TRANSFER_FINISHED } DRV_PMP_TRANSFER_STATUS; Description Queue Element Transfer Status This enumeration defines the PMP transfer status. 5.1.7.7.4.13 DRV_PMP_WAIT_STATES Structure C typedef struct { PMP_DATA_HOLD_STATES dataHoldWait; PMP_STROBE_WAIT_STATES strobeWait; PMP_DATA_WAIT_STATES dataWait; } DRV_PMP_WAIT_STATES; Description PMP wait states object This structure holds the different wait states to be configured. Refer to the PMP PLIB help document for the possible values and meaning of the different wait states. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-392 Members Members Description PMP_DATA_HOLD_STATES dataHoldWait; data hold wait states PMP_STROBE_WAIT_STATES strobeWait; read/write strobe wait states PMP_DATA_WAIT_STATES dataWait; data wait strobe wait sates 5.1.7.7.4.14 QUEUE_ELEMENT_OBJECT Type C typedef struct _QUEUE_ELEMENT_OBJECT QUEUE_ELEMENT_OBJECT; Description Queue Element Object This defines the structure required for maintaining the queue element. Remarks None 5.1.7.7.4.15 MAX_NONBUFFERED_BYTE_COUNT Macro C #define MAX_NONBUFFERED_BYTE_COUNT 4 //After this number the PMP transfer should be polled to gurantee data trasnfer Description After this number the PMP transfer should be polled to gurantee data trasnfer 5.1.7.7.4.16 DRV_PMP_TRANSFER_TYPE Enumeration C typedef enum { ADDRESS, READ, WRITE, BUFFERED_WRITE } DRV_PMP_TRANSFER_TYPE; Description This is type DRV_PMP_TRANSFER_TYPE. Members Members Description ADDRESS PMP Address needs to be updated READ PMP Read Transfer WRITE PMP Write Transfer BUFFERED_WRITE PMP Array Write Transfer 5.1.7.7.5 Miscellaneous Functions 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-393 5.1.7.7.5.1 DRV_PMP_VersionGet Function C unsigned int DRV_PMP_VersionGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the PMP driver version. The version is encoded as major * 10000 + minor * 100 + patch. The stringed version can be obtained using DRV_PMP_VersionStrGet(). Preconditions None. Parameters Parameters Description drvIndex Identifier for the driver instance to get the version for Returns Current driver version in numerical format. Remarks None. Example unsigned int version; version = DRV_PMP_VersionGet( DRV_PMP_INDEX_0 ); if(version < 110200) { // Do Something } 5.1.7.7.5.2 DRV_PMP_VersionStrGet Function C char * DRV_PMP_VersionStrGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the PMP driver version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using DRV_PMP_VersionGet(). Preconditions None. Parameters Parameters Description drvIndex Identifier for the driver instance to get the version for Returns Current PMP driver version in the string format. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-394 Remarks None. Example char *version; version = DRV_PMP_VersionStrGet( DRV_PMP_INDEX_0 ); printf("%s", version); 5.1.7.8 Files Files Name Description drv_pmp.h Parallel Master Port (PMP) device driver interface file. drv_pmp_config.h PMP driver configuration definitions template Description 5.1.7.8.1 drv_pmp.h PMP Device Driver Interface The PMP device driver provides a simple interface to manage the Parallel Master and Slave ports. This file defines the interface definitions and prototypes for the PMP driver. Enumerations Name Description DRV_PMP_CHIPX_STROBE_MODE PMP writeEnable/ReadWrite strobes. DRV_PMP_CLIENT_STATUS PMP client status definitions. DRV_PMP_ENDIAN_MODE PMP endian modes. DRV_PMP_INDEX PMP driver index definitions. DRV_PMP_PORT_CONTROL PMP port enable/disable definitions. DRV_PMP_TRANSFER_STATUS Defines the PMP transfer status. DRV_PMP_TRANSFER_TYPE This is type DRV_PMP_TRANSFER_TYPE. Functions Name Description DRV_PMP_ClientStatus Gets the current client-specific status of the PMP driver. DRV_PMP_Close Closes an opened instance of the PMP driver. DRV_PMP_Deinitialize Deinitializes the specified instance of the PMP driver module DRV_PMP_Initialize Initializes the PMP driver. DRV_PMP_ModeConfig Configure the PMP modes. DRV_PMP_Open Opens the specified PMP driver instance and returns a handle to it. DRV_PMP_Read Read the data from external device. DRV_PMP_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_PMP_Status Provides the current status of the PMP driver module. DRV_PMP_Tasks Maintains the driver's state machine and implements its ISR. 5.1 Driver Library Help MPLAB Harmony Help Parallel Master Port (PMP) Driver Library 5-395 DRV_PMP_TransferStatus Returns the transfer status. DRV_PMP_VersionGet Gets the PMP driver version in numerical format. DRV_PMP_VersionStrGet Gets the PMP driver version in string format. DRV_PMP_Write Transfers the data from the MCU to the external device. Macros Name Description DRV_PMP_INDEX_COUNT Number of valid PMP driver indices. MAX_NONBUFFERED_BYTE_COUNT After this number the PMP transfer should be polled to gurantee data trasnfer Structures Name Description DRV_PMP_INIT Defines the PMP driver initialization data. DRV_PMP_MODE_CONFIG PMP modes configuration. DRV_PMP_POLARITY_OBJECT PMP polarity object. DRV_PMP_PORTS PMP port configuration. DRV_PMP_WAIT_STATES PMP wait states object. Types Name Description DRV_PMP_QUEUE_ELEMENT_OBJ Defines the object for PMP queue element. QUEUE_ELEMENT_OBJECT Defines the structure required for maintaining the queue element. Company Microchip Technology Inc. FileName: drv_pmp.h 5.1.7.8.2 drv_pmp_config.h PMP Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. Macros Name Description DRV_PMP_CLIENTS_NUMBER Selects the maximum number of clients. DRV_PMP_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_PMP_QUEUE_SIZE PMP queue size for different instances. File Name drv_pmp_config_template.h Company Microchip Technology Inc. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-396 5.1.8 Secure Digital (SD) Card Driver Library 5.1.8.1 Introduction Secure Digital (SD) Card Driver Library for Microchip Microcontrollers The SD Card driver provides the necessary interfaces to interact with an SD card. It provides the necessary abstraction for the higher layer. Description A SD Card is a non-volatile memory (Flash memory) card designed to provide high-capacity memory in a small size. Its applications are like digital video camcorders, digital cameras, handheld computers, audio players and mobile phones. 5.1.8.2 Release Notes MPLAB Harmony Version: v0.70b SD Card Library Version : Release Date: 18Nov2013 New This Release: 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-397 • Non-blocking operation • Layered architecture • Interoperability Known Issues: • Tested only with SDHC cards (Card memory more than 2 GB) • CARD detection mechanism is not so fine-tuned • Card maximum Frequency detection is not automatic. Different cards will have specific specific frequency of operation and that needs to be set in system_config.h • Not tested the drivers operation with multiple SD cards • Timeout and driver reset on failure case is not implemented 5.1.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.8.4 Using the Library This topic describes the basic architecture of the SD Card Driver Library and provides information and examples on how to use it. Interface Header File: drv_sdcard.h The interface to the SD Card Driver library is defined in the "drv _sdcard.h" header file. This file is included by the "drv.h" file. Any C language source (.c) file that uses the SD Card Driver library should include "drv.h". Library File: The SD Card Driver library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Driver interacts with the framework. 5.1.8.4.1 Abstraction Model SD Card Driver Software Abstraction Block Diagram 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-398 • SD Card driver comes in the layer below the Partition Manager in MPLAB Harmony file system architecture. • It uses the SPI driver to interact with SD card. 5.1.8.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SD Card module. Library Interface Section Description System Level Functions Includes functions for initialize the module. Client Level Functions Functions to open and close a client. Operation Functions Functions for read and write operations Module Information Functions Functions for information about the module. Version Information Functions Functions to get the software version. 5.1.8.4.3 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-399 5.1.8.5 Configuring the Library The configuration of the SD Card driver is based on the file sys_config.h This header file contains the configuration selection for the SD Card driver. Based on the selections made, the SD Card driver will support or not support selected features. These configuration settings will apply to all instances of the SD Card. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.8.6 Building the Library This section list the files that are available in the \src of the SD Card driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.8.7 Library Interface Data Types and Constants Name Description DRV_SDCARD_INDEX_0 SD Card driver index definitions DRV_SDCARD_INDEX_COUNT Number of valid SD Card driver indices DRV_SDCARD_BUFFER_HANDLE Handle to a buffer added to the process queue. DRV_SDCARD_CLIENT_STATUS Identifies the client-specific status of the SD card driver DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device SYS_MEDIA_EVENT Defines the buffer status SDCARD_MAX_LIMIT Maximum allowed SD card instances DRV_SDCARD_INDEX_1 This is macro DRV_SDCARD_INDEX_1. DRV_SDCARD_INDEX_2 This is macro DRV_SDCARD_INDEX_2. DRV_SDCARD_INDEX_3 This is macro DRV_SDCARD_INDEX_3. Client Level Functions Name Description DRV_SDCARD_ClientStatus Gets current client-specific status the SD Card driver DRV_SDCARD_Close Closes an opened-instance of the SD Card driver DRV_SDCARD_Open Opens the specified SD Card driver instance and returns a handle to it Module Information Functions Name Description DRV_SDCARD_SectorsCountGet Gets the number of sectors present in the selected SD card device. DRV_SDCARD_SectorSizeGet Gets the sector size of the selected SD card device. DRV_SDCARD_WriteProtectionIsEnabled Gets the status of write protection. Operation Functions Name Description DRV_SDCARD_SectorRead Reads data from the sectors of the SD card. DRV_SDCARD_SectorWrite Writes sector(s) of data to an SD card. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-400 DRV_SDCARD_BufferStatusGet Gets the status of an an SD card operation (read/write) DRV_SDCARD_MediaStatusGet Gets the status of the device. System Level Functions Name Description DRV_SDCARD_Deinitialize Deinitializes the specified instance of the SD Card driver module DRV_SDCARD_Initialize Initializes the SD Card driver DRV_SDCARD_Reinitialize Reinitializes the driver and refreshes any associated hardware settings DRV_SDCARD_Status Provides the current status of the SD Card driver module DRV_SDCARD_Tasks Maintains the driver's state machine Version Information Functions Name Description DRV_SDCARD_VersionGet Gets SD card driver version in numerical format. DRV_SDCARD_VersionStrGet Gets SD card driver version in string format. Description This section describes the Application Programming Interface (API) functions of the SD Card Driver. Refer to each section for a detailed description. 5.1.8.7.1 System Level Functions 5.1.8.7.1.1 DRV_SDCARD_Deinitialize Function C void DRV_SDCARD_Deinitialize( SYS_MODULE_OBJ object ); Description Deinitializes the specified instance of the SD Card driver module, disabling its operation (and any hardware). Invalidates all the internal data. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine. Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_SDCARD_Status operation. The system has to use DRV_SDCARD_Status to find out when the module is 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-401 in the ready state. Example SYS_MODULE_OBJ object; // Returned from DRV_SDCARD_Initialize SYS_STATUS status; DRV_SDCARD_Deinitialize(object); status = DRV_SDCARD_Status(object); if (SYS_MODULE_UNINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.8.7.1.2 DRV_SDCARD_Initialize Function C SYS_MODULE_OBJ DRV_SDCARD_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Description This routine initializes the SD Card driver, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to DRV_SDCARD_Reinitialize, DRV_SDCARD_Deinitialize, DRV_SDCARD_TaskRead, DRV_SDCARD_TaskWrite and DRV_SDCARD_Status routines. Remarks This routine must be called before any other SD Card routine is called. This routine should only be called once during system initialization unless DRV_SDCARD_Deinitialize is called to de-initialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_SDCARD_Status operation. The system must use DRV_SDCARD_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this routine. Example DRV_SDCARD_INIT init; SYS_MODULE_OBJ objectHandle; 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-402 // Populate the SD Card initialization structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.baudRate = 100000; init.spiId = SPI_ID_1; // Do something objectHandle = DRV_SDCARD_Initialize(DRV_SDCARD_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.1.8.7.1.3 DRV_SDCARD_Reinitialize Function C void DRV_SDCARD_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); Description This routine reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine init Pointer to the initialization data structure Returns None Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_SDCARD_Status operation. The system must use DRV_SDCARD_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this routine. Example DRV_SDCARD_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the SD Card initialization structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.baudRate = 100000; init.spiId = SPI_ID_1; 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-403 // Do something 5.1.8.7.1.4 DRV_SDCARD_Status Function C SYS_STATUS DRV_SDCARD_Status( SYS_MODULE_OBJ object ); Description This routine provides the current status of the SD Card driver module. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Note Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Remarks Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This routine will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_SDCARD_Initialize SYS_STATUS status; status = DRV_SDCARD_Status(object); else if (SYS_STATUS_ERROR >= status) { // Handle error } 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-404 5.1.8.7.1.5 DRV_SDCARD_Tasks Function C void DRV_SDCARD_Tasks( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal state machine. Preconditions The DRV_SDCARD_Initialize routine must have been called for the specified SDCARD driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SDCARD_Initialize) Returns None Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_SDCARD_Initialize while (true) { DRV_SDCARD_Tasks (object); // Do other tasks } 5.1.8.7.2 Client Level Functions 5.1.8.7.2.1 DRV_SDCARD_ClientStatus Function C DRV_SDCARD_CLIENT_STATUS DRV_SDCARD_ClientStatus( DRV_HANDLE handle ); Description This routine gets the client-specific status of the SD Card driver associated with the given handle. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-405 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_SDCARD_CLIENT_STATUS value describing the current status of the driver Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE sdcardHandle; // Returned from DRV_SDCARD_Open DRV_SDCARD_CLIENT_STATUS sdcardClientStatus; sdcardClientStatus = DRV_SDCARD_ClientStatus ( sdcardHandle ); if ( DRV_SDCARD_CLIENT_STATUS_ERROR >= sdcardClientStatus ) { // Handle the error } 5.1.8.7.2.2 DRV_SDCARD_Close Function C void DRV_SDCARD_Close( DRV_HANDLE handle ); Description This routine closes an opened-instance of the SD Card driver, invalidating the handle. Preconditions The DRV_SDCARD_Initialize routine must have been called for the specified SD Card driver instance. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SDCARD_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_SDCARD_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_SDCARD_Open 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-406 DRV_SDCARD_Close ( handle ); 5.1.8.7.2.3 DRV_SDCARD_Open Function C DRV_HANDLE DRV_SDCARD_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); Description This routine opens the specified SD Card driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "or'd" together to indicate the intended use of the driver Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_SDCARD_Close routine is called. This routine will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, then other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_SDCARD_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Example DRV_HANDLE handle; handle = DRV_SDCARD_Open ( DRV_SDCARD_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if ( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } 5.1.8.7.3 Operation Functions 5.1.8.7.3.1 DRV_SDCARD_SectorRead Function C SYS_FS_MEDIA_BUFFER_HANDLE DRV_SDCARD_SectorRead( 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-407 DRV_HANDLE handle, uint8_t * buffer, uint32_t sector_addr, uint32_t sectorCount ); Description This function reads data from the sectors of the SD card starting from the sector address and stores it in the location pointed by 'buffer'. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine sector_addr The address of the sector on the card. sectorCount Number of sectors to be read. buffer The buffer where the retrieved data will be stored. If buffer is NULL, do not store the data anywhere. Returns SYS_FS_MEDIA_BUFFER_HANDLE - Buffer handle. Remarks This routine will not block for hardware access and will immediately return the current status. Example SYS_FS_MEDIA_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_SDCARD_SectorRead ( handle, ,readData //buffer , 20 // Sector , 1 // Number of Sectors ); 5.1.8.7.3.2 DRV_SDCARD_SectorWrite Function C SYS_FS_MEDIA_BUFFER_HANDLE DRV_SDCARD_SectorWrite( DRV_HANDLE handle, uint32_t sector_addr, uint8_t * buffer, uint32_t sectorCount ); Description This function writes sector(s) of data (512 bytes) of data from the location pointed to by 'buffer' to the specified sector of the SD card. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-408 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine sector_addr The address of the sector on the card. buffer The buffer with the data to write. Returns SYS_FS_MEDIA_BUFFER_HANDLE - Buffer handle. Remarks The card expects the address field in the command packet to be a byte address. The sector_addr value is converted to a byte address by shifting it left nine times (multiplying by 512). Example SYS_FS_MEDIA_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_SDCARD_SectorWrite ( handle, ,readData //buffer , 20 // Sector , 1 // Number of Sectors ); 5.1.8.7.3.3 DRV_SDCARD_BufferStatusGet Function C SYS_FS_MEDIA_BUFFER_STATUS DRV_SDCARD_BufferStatusGet( DRV_HANDLE handle, SYS_FS_MEDIA_BUFFER_HANDLE bufferHandle ); Description This function gets the status of an an SD card operation (read/write). To be called only after a read or write is scheduled. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine bufferHandle Handle returned by a 'sector write' or a 'sector read' function. Returns SYS_FS_MEDIA_BUFFER_STATUS - Buffer status. Remarks None. Example int globalState = 0; SYS_FS_MEDIA_BUFFER_HANDLE bufferHandle; switch (globalState) { case 0: 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-409 bufferHandle = SYS_FS_MEDIA_MANAGER_SectorWrite ( handle, ,readData //buffer , 20 // Sector , 1 // Number of Sectors ); globalState++; break; case 1: if ( SYS_FS_MEDIA_MANAGER_BufferStatusGet(handle, bufferHandle) == SYS_FS_MEDIA_BUFFER_COMPLETED) { //Write complete } break; 5.1.8.7.3.4 DRV_SDCARD_MediaStatusGet Function C SYS_FS_MEDIA_STATUS DRV_SDCARD_MediaStatusGet( DRV_HANDLE handle ); Description This function gets the status of the device ( attached/detached ). Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns SYS_FS_MEDIA_STATUS - Status of the device. Remarks None. Example DRV_HANDLE sdcardHandle; // Returned from DRV_SDCARD_Open if( DRV_SDCARD_MediaStatusGet ( handle ) == SYS_FS_MEDIA_ATTACHED ) { //Device is attached } 5.1.8.7.4 Module Information Functions 5.1.8.7.4.1 DRV_SDCARD_SectorsCountGet Function C uint32_t DRV_SDCARD_SectorsCountGet( DRV_HANDLE handle ); 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-410 Description This function gets the number of sectors present in the selected SD card device. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. SD Card must have been detected and initialized by the task routine. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns The number of a sectors in the selected SD Card. Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE sdcardHandle; // Returned from DRV_SDCARD_Open DRV_SDCARD_CLIENT_STATUS sdcardClientStatus; bool status; 5.1.8.7.4.2 DRV_SDCARD_SectorSizeGet Function C uint32_t DRV_SDCARD_SectorSizeGet( DRV_HANDLE handle ); Description This function gets the card's sector size. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. SD Card must have been detected and initialized by the task routine. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns The size of a sector in the selected SD Card. Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE sdcardHandle; // Returned from DRV_SDCARD_Open DRV_SDCARD_CLIENT_STATUS sdcardClientStatus; bool status; 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-411 5.1.8.7.4.3 DRV_SDCARD_WriteProtectionIsEnabled Function C bool DRV_SDCARD_WriteProtectionIsEnabled( DRV_HANDLE handle ); Description This function returns 'true' if the write protection for the card is enabled. Preconditions The DRV_SDCARD_Initialize routine must have been called. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. SD Card must have been detected and initialized by the task routine. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns true - Write protection is enabled. false - Write protection is disabled. Remarks This routine will not block for hardware access and will immediately return the current status. Example DRV_HANDLE sdcardHandle; // Returned from DRV_SDCARD_Open bool writeProtectStatus; //Call DRV_SDCARD_Open writeProtectStatus = DRV_SDCARD_WriteProtectionIsEnabled(sdcardHandle); 5.1.8.7.5 Version Information Functions 5.1.8.7.5.1 DRV_SDCARD_VersionGet Function C unsigned int DRV_SDCARD_VersionGet( const SYS_MODULE_INDEX drvIndex ); Description This routine gets the SD card driver version. The version is encoded as major * 10000 + minor * 100 + patch. The stringized version can be obtained using DRV_SDCARD_VersionStrGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for. 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-412 Returns Current driver version in numerical format. Remarks None. Example unsigned int version; version = DRV_SDCARD_VersionGet( DRV_SDCARD_INDEX_1 ); if(version < 110200) { // Do Something } 5.1.8.7.5.2 DRV_SDCARD_VersionStrGet Function C char* DRV_SDCARD_VersionStrGet( const SYS_MODULE_INDEX drvIndex ); Description This routine gets the SD card driver version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using DRV_SDCARD_VersionGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for. Returns Current SD card driver version in the string format. Remarks None. Example char *version; version = DRV_SDCARD_VersionStrGet( DRV_SDCARD_INDEX_1 ); printf("%s", version); 5.1.8.7.6 Data Types and Constants 5.1.8.7.6.1 DRV_SDCARD_INDEX_0 Macro C #define DRV_SDCARD_INDEX_0 0 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-413 Description SD Card Driver Module Index Numbers These constants provide SD Card driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SDCARD_Initialize and DRV_SDCARD_Open routines to identify the driver instance in use. 5.1.8.7.6.2 DRV_SDCARD_INDEX_COUNT Macro C #define DRV_SDCARD_INDEX_COUNT DRV_SDCARD_INDEX_MAX Description SD Card Driver Module Index Count This constant identifies number of valid SD Card driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. 5.1.8.7.6.3 DRV_SDCARD_BUFFER_HANDLE Type C typedef uintptr_t DRV_SDCARD_BUFFER_HANDLE; Description SD Card Buffer Handle This handle identifies the a buffer in the queue(read or write). 5.1.8.7.6.4 DRV_SDCARD_CLIENT_STATUS Enumeration C typedef enum { DRV_SDCARD_CLIENT_STATUS_INVALID, DRV_SDCARD_CLIENT_STATUS_ERROR, DRV_SDCARD_CLIENT_STATUS_CLOSED, DRV_SDCARD_CLIENT_STATUS_BUSY, DRV_SDCARD_CLIENT_STATUS_READY, DRV_SDCARD_CLIENT_STATUS_STOPPED } DRV_SDCARD_CLIENT_STATUS; Description SD Card Driver Client Status This enumeration identifies the client-specific status of the SD card driver. Members Members Description DRV_SDCARD_CLIENT_STATUS_INVALID Client in an invalid state 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-414 DRV_SDCARD_CLIENT_STATUS_ERROR Unspecified error condition DRV_SDCARD_CLIENT_STATUS_CLOSED Client is not open DRV_SDCARD_CLIENT_STATUS_BUSY An operation is currently in progress DRV_SDCARD_CLIENT_STATUS_READY Up and running, no operations running DRV_SDCARD_CLIENT_STATUS_STOPPED SD Card stopped (not running), but ready to accept commands Remarks None. 5.1.8.7.6.5 DRV_SDCARD_INIT Type C typedef struct _DRV_SDCARD_INIT DRV_SDCARD_INIT; Description SD Card Device Driver Initialization Data This structure contains all the data necessary to initialize the SD Card device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_SDCARD_Initialize routine. 5.1.8.7.6.6 SYS_MEDIA_EVENT Enumeration C typedef enum { SYS_MEDIA_EVENT_SDCARD_ATTACHED, SYS_MEDIA_EVENT_SDCARD_DETACHED } SYS_MEDIA_EVENT; Description SD Card Buffer Status Defines the states that an SD Card buffer can be in during its lifetime Members Members Description SYS_MEDIA_EVENT_SDCARD_ATTACHED The media event is SD Card attach SYS_MEDIA_EVENT_SDCARD_DETACHED The media event is SD Card detach Remarks As buffers may have a limited life span, so too have the associated handles and status info. Once a buffer transfer is completed (and possibly notified and acknowledged) it will be discarded. The status of a discarded buffer is no longer maintained by the driver. 5.1.8.7.6.7 SDCARD_MAX_LIMIT Macro C #define SDCARD_MAX_LIMIT 2 Description SD Card Driver Maximum allowed limit 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-415 This constant identifies number of valid SD Card driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. 5.1.8.7.6.8 DRV_SDCARD_INDEX_1 Macro C #define DRV_SDCARD_INDEX_1 1 Description This is macro DRV_SDCARD_INDEX_1. 5.1.8.7.6.9 DRV_SDCARD_INDEX_2 Macro C #define DRV_SDCARD_INDEX_2 2 Description This is macro DRV_SDCARD_INDEX_2. 5.1.8.7.6.10 DRV_SDCARD_INDEX_3 Macro C #define DRV_SDCARD_INDEX_3 3 Description This is macro DRV_SDCARD_INDEX_3. 5.1.8.8 Files Files Name Description drv_sdcard.h SD Card Device Driver Interface File Description 5.1.8.8.1 drv_sdcard.h SD Card Device Driver Interface The SD Card device driver provides a simple interface to manage the "SD Card" peripheral. This file defines the interface definitions and prototypes for the SD Card driver. Enumerations Name Description DRV_SDCARD_CLIENT_STATUS Identifies the client-specific status of the SD card driver SYS_MEDIA_EVENT Defines the buffer status 5.1 Driver Library Help MPLAB Harmony Help Secure Digital (SD) Card Driver Library 5-416 Functions Name Description DRV_SDCARD_BufferStatusGet Gets the status of an an SD card operation (read/write) DRV_SDCARD_ClientStatus Gets current client-specific status the SD Card driver DRV_SDCARD_Close Closes an opened-instance of the SD Card driver DRV_SDCARD_Deinitialize Deinitializes the specified instance of the SD Card driver module DRV_SDCARD_Initialize Initializes the SD Card driver DRV_SDCARD_MediaStatusGet Gets the status of the device. DRV_SDCARD_Open Opens the specified SD Card driver instance and returns a handle to it DRV_SDCARD_Reinitialize Reinitializes the driver and refreshes any associated hardware settings DRV_SDCARD_SectorRead Reads data from the sectors of the SD card. DRV_SDCARD_SectorsCountGet Gets the number of sectors present in the selected SD card device. DRV_SDCARD_SectorSizeGet Gets the sector size of the selected SD card device. DRV_SDCARD_SectorWrite Writes sector(s) of data to an SD card. DRV_SDCARD_Status Provides the current status of the SD Card driver module DRV_SDCARD_Tasks Maintains the driver's state machine DRV_SDCARD_VersionGet Gets SD card driver version in numerical format. DRV_SDCARD_VersionStrGet Gets SD card driver version in string format. DRV_SDCARD_WriteProtectionIsEnabled Gets the status of write protection. Macros Name Description DRV_SDCARD_INDEX_0 SD Card driver index definitions DRV_SDCARD_INDEX_1 This is macro DRV_SDCARD_INDEX_1. DRV_SDCARD_INDEX_2 This is macro DRV_SDCARD_INDEX_2. DRV_SDCARD_INDEX_3 This is macro DRV_SDCARD_INDEX_3. DRV_SDCARD_INDEX_COUNT Number of valid SD Card driver indices SDCARD_MAX_LIMIT Maximum allowed SD card instances Types Name Description DRV_SDCARD_BUFFER_HANDLE Handle to a buffer added to the process queue. DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device Company Microchip Technology Incorporated FileName: drv_sdcard.h 5.1.9 SPI Driver Library 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-417 5.1.9.1 Introduction SPI Driver Library for Microchip Microcontrollers This library provides an interface to manage the Serial Peripheral Interface (SPI) module on the Microchip family of microcontrollers in different modes of operation. Description Overview The SPI module is a full duplex synchronous serial interface useful for communicating with other peripherals or microcontrollers in master/slave relationship and it can transfer data over short distances at high speeds. The peripheral devices may be serial EEPROMs, shift registers, display drivers, analog-to-digital converters, etc. The SPI module is compatible with Motorola’s SPI and SIOP interfaces. During data transfer devices can work either in master or in Slave mode. The source of synchronization is the system clock, which is generated by the master. The SPI module allows to connect one or more slave devices to a single master device via the same bus. The SPI serial interface consists of four pins, which are further sub-divided into data and control lines: Data lines: • MOSI – Master Data Output, Slave Data Input • MISO – Master Data Input, Slave Data Output Control lines: • SCLK – Serial Clock • /SS – Slave Select (no addressing) SPI Master-Slave Relationship The SPI module can be configured to operate using 2, 3 or 4 pins. In the 3-pin mode, slave select line is not used. In the 2-pin mode, both MOSI and SS lines are not used. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-418 Note: Third-party trademarks are property of their respective owners. 5.1.9.2 Release Notes MPLAB Harmony Version: v0.70b SPI Driver Library Version : 0.01 Release Date: 18Nov2013 New This Release: • Configurable baud rate at client level • Interoperability Known Issues: • Does not work in the Slave mode of operation • DMA is not supported 5.1.9.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.9.4 Using the Library This topic describes the basic architecture of the SPI Driver Library and provides information and examples on how to use it. Interface Header File: drv_spi.h The interface to the SPI Driver library is defined in the "drv_spi.h" header file. Any C language source (.c) file that uses the SPI Driver library should include this header. Library File: The SPI Driver library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Driver interacts with the framework. 5.1.9.4.1 Abstraction Model Different types of SPIs are available on Microchip microcontrollers. Some have an internal buffer mechanism and some do not. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-419 The buffer depth varies across part families. The SPI driver abstracts out these differences and provides a unified model for data transfer across different types of SPIs available. Both transmitter and receiver provides a buffer in the driver which transmits and receives data to/from the hardware. The SPI driver provides a set of interfaces to perform the read and the write. The diagrams below illustrates the model used by the SPI driver for transmitter and receiver. Receiver Abstraction Model Transmitter Abstraction Model 5.1.9.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various subsections, each of the sub section addresses one of the blocks or the overall operation of the SPI module. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open, close, status and other setup functions. Chip Selects Provides chip select functions available in the configuration. Client Data Transfer - Core Provides core data transfer functions available in the configuration. [Standard/Single buffer transfer] 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-420 Client Data Transfer - Advanced Provides advanced data transfer functions available in the configuration. [Enhanced/Multi buffer transfers] Miscellaneous Provides driver miscellaneous functions, data transfer status function, version identification functions etc. 5.1.9.4.3 How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all microcontrollers, please refer to the specific device data sheet to the modes that are supported for your device. 5.1.9.4.3.1 System Access System Initialization and Re-initialization The system performs the initialization and the re-initialization of the device driver with settings that affect only the instance of the device that is being initialized or re-initialized. During system initialization each instance of the SPI module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_SPI_INIT or by using Initialization Overrides) that are supported by the specific SPI device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to the Data Types section in this guide • The actual peripheral ID enumerated as the PLIB level module ID. e.g SPI_ID_2. • Defining the respective interrupt sources for Tx, Rx, and Error Interrupt. The DRV_SPI_Initialize API returns an object handle of the type SYS_MODULE_OBJ. There on, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_SPI_Reinitialize, DRV_SPI_Deinitialize, DRV_SPI_Status and DRV_SPI_Tasks. Note:The system initialization and the re-initialization settings, only effect the instance of the peripheral that is being initialized or re-initialized. Example: DRV_SPI_INIT spiInitData; SYS_MODULE_OBJ objectHandle; spiInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; spiInitData.spiId = SPI_ID_1; spiInitData.spiMode = DRV_SPI_MODE_MASTER; spiInitData.spiProtocolType = DRV_SPI_PROTOCOL_TYPE_STANDARD; spiInitData.commWidth = SPI_COMMUNICATION_8BIT_WIDE; spiInitData.baudRate = 5000; spiInitData.bufferType = DRV_SPI_BUFFER_TYPE_STANDARD; spiInitData.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; spiInitData.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE; spiInitData.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT; // INT_SOURCE_SPI_1_EVENT spiInitData.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE; // INT_SOURCE_SPI_1_EVENT spiInitData.errInterruptSource = INT_SOURCE_SPI_1_ERROR; spiInitData.pinConfig.sdiPin = PIN_6; // RPI38 spiInitData.pinConfig.sdoPin = PIN_10; // RP21 spiInitData.pinConfig.sckPin = PIN_11; // RP26 objectHandle = DRV_SPI_Initialize(DRV_SPI_INDEX_1, (SYS_MODULE_INIT*)&spiInitData); 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-421 if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will either call DRV_SPI_Tasks, from System Task Service (in a polled environment) or DRV_SPI_Tasks will be called from interrupt service routine of the SPI. 5.1.9.4.3.2 Client Access General Client Operation For the application to start using an instance of the module, it must call the DRV_SPI_Open function. This provides the configuration required to open the SPI instance for operation. If the driver is de-initialized using the function DRV_SPI_Deinitialize, the application must call the DRV_SPI_Open function again to setup the instance of the SPI. The function DRV_SPI_Open need not be called again if the system is re-initialized using the DRV_SPI_Reinitialize function. For the various options available for IO INTENT please refer to the Data Types section in this guide. Example: DRV_HANDLE handle; // Configure the instance DRV_SPI_INDEX_1 with the configuration handle = DRV_SPI_Open(DRV_SPI_INDEX_1, DRV_IO_INTENT_READWRITE); if(handle == DRV_HANDLE_INVALID) { // Client cannot open the instance. } Communication Setup: Communication entities like the SPI modes, input clock frequency, baud rates, clock mode, ports setup etc. can be configured with the help of the driver function DRV_SPI_CommunicationSetup. This is a mandatory setup before doing any data transfer. The callback function registered during the communication setup gets called after a successful data transfer. Example: DRV_HANDLE handle; // Returned from DRV_SPI_Open DRV_SPI_COMM_CONFIG config; // Populate the communication setup configuration structure config.spiMode = DRV_SPI_MODE_MASTER; config.baudRate = 5000; config.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; config.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE; config.callback = &callBackFunction; // callback registered DRV_SPI_CommunicationSetup( handle, &config ); Chip Select Control: User can control the chip/slave select signals using the driver APIs DRV_SPI_ChipSelectActivate and DRV_SPI_ChipSelectDeactivate with appropriate parameters. Example: // Activates/Enables Slave Select connected to Port A, bit 1 DRV_SPI_ChipSelectActivate( handle, PORT_CHANNEL_A, PORTS_BIT_POS_1 ); ... ... ... // Deactivates/Disables Slave Select connected to Port A, bit 1 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-422 DRV_SPI_ChipSelectDeactivate( handle, PORT_CHANNEL_A, PORTS_BIT_POS_1 ); 5.1.9.4.3.3 Cient Transfer - Core Client basic functionality provides a extremely basic interface for the driver operation. This client transfer mechanism needs to be used for the devices which support the 'Standard' SPI mode of operation [Single Buffer]. This mechanism needs to be repeated in case of buffer based data transfers for transferring multi bytes/words. The diagram below illustrates the byte/word model used for the data transfer. Note: It is not necessary to close and re-open the client between multiple transfers. Client Byte/Word transfer Functionality Application using the SPI byte/word functionality, needs to perform the following: 1. The system should have completed necessary initialization and the DRV_SPI_Tasks should either be running in polled 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-423 environment, or in an interrupt environment. 2. Open the driver using DRV_SPI_Open with the necessary intent 3. Setup the communication using the driver function DRV_SPI_CommunicationSetup 4. Enable/activate the slave using the function DRV_SPI_ChipSelectActivate 5. Put/Write a byte using DRV_SPI_Put, dummy byte in case of read only 6. Check for the current transfer status using DRV_SPI_TransferStatus until the transfer is in progress DRV_SPI_TRANSFER_STATUS_IN_PROGRESS, call the DRV_SPI_Tasks in case of a polled environment until the transfer is success 7. Get/Read the dummy/valid data using the function DRV_SPI_Get 8. Repeat from step 5 till 7 to handle buffer transmission and reception using standard mode 9. Disable/deactivate the slave using the function DRV_SPI_ChipSelectDeactivate 10. The client will be able to close the driver using the DRV_SPI_Close when required. Example: DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_BUFFER myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; DRV_SPI_COMM_CONFIG config; // Pre-initialize myBuffer with MY_BUFFER_SIZE bytes of valid data. while( 1 ) { switch( state ) { case APP_STATE_INIT: /* Initialize the SPI Driver */ object = DRV_SPI_Initialize( sysIndex, ( SYS_MODULE_INIT * )&initConf ); /* Check for the System Status */ if( SYS_STATUS_READY != DRV_SPI_Status( object ) ) return 0; /* Open the Driver */ clHandle = DRV_SPI_Open( sysIndex, DRV_IO_INTENT_EXCLUSIVE ); /* Check for the Client Open Status */ if( DRV_SPI_CLIENT_STATUS_READY != DRV_SPI_ClientStatus( clHandle ) ) return 0; /* Set up the communication medium */ DRV_SPI_CommunicationSetup( clHandle, &commConf ); /* Update the state to transfer data */ state = APP_STATE_DATA_PUT; break; case APP_STATE_DATA_PUT: /* Enable/Activate the CS */ DRV_SPI_ChipSelectActivate( handle, PORT_CHANNEL_A, PORTS_BIT_POS_1 ); /* Initiate the data transfer */ DRV_SPI_Put( clHandle, myBuffer[i++] ); /* Deactivates/Disables CS */ DRV_SPI_ChipSelectDeactivate( handle, PORT_CHANNEL_A, PORTS_BIT_POS_1 ); /* Update the state to status check */ state = APP_STATE_STATUS_CHECK; break; case APP_STATE_STATUS_CHECK: 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-424 /* Check for the successful data transfer */ if( DRV_SPI_TRANSFER_STATUS_IN_PROGRESS & DRV_SPI_TransferStatus( clHandle ) ) { DRV_SPI_Tasks (object); /* Stay here until the data transfer is executed */ state = APP_STATE_STATUS_CHECK; } else { /* Data transfer was successfull, get the data */ state = APP_STATE_DATA_GET; } break; case APP_STATE_DATA_GET: /* Read the data from the peripheral */ rxd_data = DRV_SPI_Get( clHandle ); /* Restart the process by jumping to the beginning state */ state = APP_STATE_DATA_PUT; break; default: break; } } Note: 'bufferType' attribute of the initialization structure or the configuration macro 'DRV_SPI_BUFFER_USAGE_TYPE' needs to be updated as DRV_SPI_BUFFER_TYPE_STANDARD 5.1.9.4.3.4 Client Transfer - Advanced Client basic functionality provides a extremely basic interface for the driver operation. This client transfer mechanism needs to be used for the devices which support the 'Enhanced' SPI mode of operation [Internal FIFO or buffer]. The diagram below illustrates the buffer model used for the data transfer. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-425 Note: It is not necessary to close and re-open the client between multiple transfers. Client Byte/Word transfer Functionality Application using the SPI byte/word functionality, needs to perform the following: 1. The system should have completed necessary initialization and the DRV_SPI_Tasks should either be running in polled environment, or in an interrupt environment. 2. Open the driver using DRV_SPI_Open with the necessary intent 3. Setup the communication using the driver function DRV_SPI_CommunicationSetup 4. Enable/activate the slave using the function DRV_SPI_ChipSelectActivate 5. Put/Write a byte using DRV_SPI_PutBuffer, dummy byte in case of read only 6. Check for the current transfer status using DRV_SPI_TransferStatus until the transfer is in progress DRV_SPI_TRANSFER_STATUS_IN_PROGRESS, call the DRV_SPI_Tasks in case of a polled environment until the transfer is success 7. Get/Read the dummy/valid data using the function DRV_SPI_GetBuffer 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-426 8. Repeat from step 5 till 7 to handle multi buffer transmission and reception using enhanced mode 9. Disable/deactivate the slave using the function DRV_SPI_ChipSelectDeactivate 10. The client will be able to close the driver using the DRV_SPI_Close when required. Example: DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE tx_buffer[DRV_SPI_BUFFER_SIZE] = { 0x0001, 0x0001, 0x0001, 0x0001 }; SPI_DATA_TYPE rx_buffer[DRV_SPI_BUFFER_SIZE]; unsigned int numBytes; DRV_SPI_COMM_CONFIG config; // Pre-initialize tx_buffer with DRV_SPI_BUFFER_SIZE bytes of valid data. while( 1 ) { switch( state ) { case APP_STATE_INIT: /* Initialize the SPI Driver */ object = DRV_SPI_Initialize( sysIndex, ( SYS_MODULE_INIT * )&initConf ); /* Check for the System Status */ if( SYS_STATUS_READY != DRV_SPI_Status( object ) ) return 0; /* Open the Driver */ clHandle = DRV_SPI_Open( sysIndex, DRV_IO_INTENT_EXCLUSIVE ); /* Check for the Client Open Status */ if( DRV_SPI_CLIENT_STATUS_READY != DRV_SPI_ClientStatus( clHandle ) ) return 0; /* Set up the communication medium */ DRV_SPI_CommunicationSetup( clHandle, &commConf ); /* Update the state to transfer data */ state = APP_STATE_BUFFER_PUT; break; case APP_STATE_BUFFER_PUT: /* Initiate the data transfer */ DRV_SPI_PutBuffer( clHandle, &tx_buffer, sizeof( tx_buffer )/2 ); /* Update the state to status check */ state = APP_STATE_BUFFER_CHECK; break; case APP_STATE_BUFFER_CHECK: /* Check for the successful data transfer */ if( DRV_SPI_TRANSFER_STATUS_IN_PROGRESS & DRV_SPI_TransferStatus( clHandle ) ) { DRV_SPI_Tasks (object); /* Stay here until the data transfer is executed */ state = APP_STATE_BUFFER_CHECK; } else { /* Data transfer was successfull, get the data */ state = APP_STATE_BUFFER_GET; } break; case APP_STATE_BUFFER_GET: /* Read the data from the peripheral */ DRV_SPI_GetBuffer( clHandle, &rx_buffer, sizeof( rx_buffer )/2 ); 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-427 /* Restart the process by jumping to the beginning state */ state = APP_STATE_BUFFER_PUT; break; default: break; } } Note: 'bufferType' attribute of the initialization structure or the configuration macro 'DRV_SPI_BUFFER_USAGE_TYPE' needs to be updated as DRV_SPI_BUFFER_TYPE_ENHANCED 5.1.9.5 Configuring the Library The configuration of the SPI driver is based on the file sys_config.h This header file contains the configuration selection for the SPI driver. Based on the selections made, the SPI driver will support or not support selected features. These configuration settings will apply to all instances of the SPI driver. This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.9.5.1 Client Configuration 5.1.9.5.2 System Configuration 5.1.9.5.3 Miscellaneous Configuration 5.1.9.6 Building the Library This section list the files that are available in the \src of the SPI driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.9.7 Library Interface Data Types and Constants Name Description DRV_SPI_BAUD_RATE Controls the baud rate value of the SPI driver. DRV_SPI_BAUD_RATE_CLOCK Selects the SPI baud rate clock. DRV_SPI_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_SPI_BUFFER_SIZE This is macro DRV_SPI_BUFFER_SIZE. DRV_SPI_BUFFER_USAGE_TYPE Controls the buffer type of the SPI driver. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-428 DRV_SPI_CLIENTS_NUMBER Selects the miximum number of clients. DRV_SPI_CLOCK_OPERATION_MODE Controls the clock mode of the SPI driver. DRV_SPI_COMMUNICATION_WIDTH Controls the communication width of the SPI driver. DRV_SPI_FRAME_SYNC_PULSE_COUNT Selects the SPI frame sync pulse count. DRV_SPI_FRAME_SYNC_PULSE_DIRECTION Selects the SPI frame sync pulse direction. DRV_SPI_FRAME_SYNC_PULSE_EDGE Selects the SPI frame sync pulse edge. DRV_SPI_FRAME_SYNC_PULSE_POLARITY Selects the SPI frame sync pulse polarity. DRV_SPI_FRAME_SYNC_PULSE_WIDTH Selects the SPI frame sync pulse width. DRV_SPI_INDEX SPI static index selection. DRV_SPI_INDEX_0 SPI driver index definitions. DRV_SPI_INDEX_COUNT Number of valid SPI driver indices. DRV_SPI_INPUT_SAMPLE_PHASE Selects the SPI input sample phase. DRV_SPI_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver . DRV_SPI_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_SPI_INTERRUPT_SOURCE_ERROR Defines the error interrupt source in case of static driver DRV_SPI_INTERRUPT_SOURCE_RX Defines the receive interrupt source in case of static driver. DRV_SPI_INTERRUPT_SOURCE_TX Defines the transmit/receive or transmit alone interrupt source in case of static driver. DRV_SPI_PERIPHERAL_ID SPI peripheral ID selection. DRV_SPI_PORTS_REMAP_USAGE Selects the SPI pins remap. DRV_SPI_POWER_STATE Controls the power state of the SPI driver. DRV_SPI_PROTOCOL Controls the protocol type of the SPI driver. DRV_SPI_USAGE_MODE Controls the usage mode of the SPI driver. DRV_SPI_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_SPI_BUFFER_EVENT_HANDLER Pointer to a SPI Driver Buffer Event handler function DRV_SPI_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. DRV_SPI_BUFFER_TYPE Identifies the various buffer types of the SPI module. DRV_SPI_CLIENT_SETUP Defines the data required to initialize an SPI client. DRV_SPI_CLOCK_MODE Identifies the various clock modes of the SPI module. DRV_SPI_INIT Defines the data required to initialize or reinitialize the SPI driver DRV_SPI_MODE Identifies the various usage modes of the SPI module. DRV_SPI_PROTOCOL_TYPE Identifies the various protocols of the SPI module. Client Setup Functions Name Description DRV_SPI_BufferStatus Returns the transmitter and receiver transfer status. DRV_SPI_ClientSetup Initializes a client. DRV_SPI_Close Closes an opened instance of the SPI driver DRV_SPI_Open Opens the specified SPI driver instance and returns a handle to it. Miscellaneous Functions Name Description DRV_SPI_BufferAddRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-429 DRV_SPI_BufferAddWrite Registers a buffer for a read operation. Actual transfer will happen in the Task function. DRV_SPI_BufferAddWriteRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. DRV_SPI_VersionGet Gets the SPI driver version in numerical format. DRV_SPI_VersionStrGet Gets the SPI driver version in string format. DRV_SPI_INDEX_1 This is macro DRV_SPI_INDEX_1. DRV_SPI_INDEX_2 This is macro DRV_SPI_INDEX_2. DRV_SPI_INDEX_3 This is macro DRV_SPI_INDEX_3. DRV_SPI_INDEX_4 This is macro DRV_SPI_INDEX_4. DRV_SPI_INDEX_5 This is macro DRV_SPI_INDEX_5. DRV_SPI_RX_FIFO_INTERRUPT_MODE This is macro DRV_SPI_RX_FIFO_INTERRUPT_MODE. DRV_SPI_TX_FIFO_INTERRUPT_MODE This is macro DRV_SPI_TX_FIFO_INTERRUPT_MODE. System Interaction Functions Name Description DRV_SPI_Deinitialize De-initializes the specified instance of the SPI driver module. DRV_SPI_Initialize Initializes the SPI driver. DRV_SPI_Status Provides the current status of the SPI driver module. DRV_SPI_Tasks Maintains the driver's state machine and implements its ISR. DRV_SPI_Read Gets/Reads byte(s) from SPI. The function will wait until the specified number of bytes is received. DRV_SPI_Write Writes the data to SPI. The function will wait until all the bytes are transmitted. Description This section describes the API functions of the SPI driver library. Refer to each section for a detailed description. 5.1.9.7.1 System Interaction Functions 5.1.9.7.1.1 DRV_SPI_Deinitialize Function C void DRV_SPI_Deinitialize( SYS_MODULE_OBJ object ); Description De-initializes the specified instance of the SPI driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Preconditions Function DRV_SPI_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from DRV_SPI_Initialize 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-430 Returns None. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_SPI_Status operation. The system has to use DRV_SPI_Status to find out when the module is in the ready state. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize SYS_STATUS status; DRV_SPI_Deinitialize ( object ); status = DRV_SPI_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is de-initialized. } 5.1.9.7.1.2 DRV_SPI_Initialize Function C SYS_MODULE_OBJ DRV_SPI_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Description This function initializes the SPI driver, making it ready for clients to open and use. Preconditions None. Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, a valid handle to a driver object is returned. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as an argument to the DRV_SPI_Reinitialize, DRV_SPI_Deinitialize, DRV_SPI_Tasks, and DRV_SPI_Status functions. Remarks This function must be called before any other SPI routine is called. This function should only be called once during system initialization unless DRV_SPI_Deinitialize is called to de-initialize the driver instance. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-431 reported by the DRV_SPI_Status operation. The system must use DRV_SPI_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Example DRV_SPI_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the SPI initialization structure init.spiId = SPI_ID_1; init.spiMode = DRV_SPI_MODE_MASTER; init.spiProtocolType = DRV_SPI_PROTOCOL_TYPE_STANDARD; init.commWidth = SPI_COMMUNICATION_8BIT_WIDE; init.baudRate = 5000; init.bufferType = DRV_SPI_BUFFER_TYPE_STANDARD; init.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; init.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE; init.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT; // INT_SOURCE_SPI_1_EVENT init.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE; // INT_SOURCE_SPI_1_EVENT init.errInterruptSource = INT_SOURCE_SPI_1_ERROR; // Do something objectHandle = DRV_SPI_Initialize( DRV_SPI_INDEX_0, (SYS_MODULE_INIT*)&init ); if( SYS_MODULE_OBJ_INVALID == objectHandle ) { // Handle error } 5.1.9.7.1.3 DRV_SPI_Status Function C SYS_STATUS DRV_SPI_Status( SYS_MODULE_OBJ object ); Description This function provides the current status of the SPI driver module. Preconditions The DRV_SPI_Initialize function must have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from DRV_SPI_Initialize Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-432 If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the de-initialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize SYS_STATUS status; status = DRV_SPI_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } 5.1.9.7.1.4 DRV_SPI_Tasks Function C void DRV_SPI_Tasks( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal state machine and implement its transmit ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks() function. In interrupt mode, this function should be called in the transmit interrupt service routine of the USART that is associated with this USART driver hardware instance. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SPI_Initialize) Returns None. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may execute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize while( true ) { DRV_SPI_Tasks ( object ); // Do other tasks } 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-433 5.1.9.7.1.5 DRV_SPI_Read Function C size_t DRV_SPI_Read( DRV_HANDLE handle, void* buffer, size_t noOfBytes ); Description This function gets/reads byte(s) from SPI. The function will wait until the specified number of bytes is received. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer to which the data should be written to. noOfBytes Number of bytes to be received. Returns The number of bytes read. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_SPI_Open function and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_SPI_Open function or the driver was built to only support non-blocking behavior the call will return immediately. If data is not available, a zero ('0') value will be returned and an underrun error status will be captured. To ensure that valid data is returned, the caller must first check the return value to DRV_SPI_BufferStatus, as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE myBuffer[MY_BUFFER_SIZE]; unsigned int numberOfBytesRead; numberOfBytesRead = DRV_SPI_Read ( handle, myBuffer, 10 ); if ( numberOfBytesWritten == 0 ) { // Check for the error... } 5.1.9.7.1.6 DRV_SPI_Write Function C size_t DRV_SPI_Write( DRV_HANDLE handle, void* buffer, size_t noOfBytes ); 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-434 Description This function Writes the data to SPI. The function will wait until all the bytes are transmitted. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer which contains the data. noOfBytes Number of bytes to be transmitted. Returns The number of bytes written. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_SPI_Open function and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_SPI_Open function or the driver was built to only support non-blocking behavior the call will return immediately. If the driver was not able to accept the data, an overrun error status will be captured. To ensure that the driver is ready to accept data, the caller must first check the return value to DRV_SPI_BufferStatus, as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE myBuffer[MY_BUFFER_SIZE];//fill the data unsigned int numberOfBytesWritten; numberOfBytesWritten = DRV_SPI_Write ( handle, myBuffer, 10 ); if ( numberOfBytesWritten == 0 ) { // Check the error... } 5.1.9.7.2 Client Setup Functions 5.1.9.7.2.1 DRV_SPI_BufferStatus Function C DRV_SPI_BUFFER_EVENT DRV_SPI_BufferStatus( DRV_SPI_BUFFER_HANDLE bufferHandle ); Description This returns the transmitter and receiver transfer status. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-435 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_SPI_BUFFER_STATUS value describing the current status of the transfer. Remarks The returned status may contain a value with more than one of the bits specified in the DRV_SPI_BUFFER_STATUS enumeration set. The caller should perform an AND with the bit of interest and verify if the result is non-zero (as shown in the example) to verify the desired status bit. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open if( DRV_SPI_BUFFER_STATUS_SUCCESS & DRV_SPI_BufferStatus( handle ) ) { // All transmitter data has been sent. } 5.1.9.7.2.2 DRV_SPI_ClientSetup Function C void DRV_SPI_ClientSetup( DRV_HANDLE handle, const DRV_SPI_CLIENT_SETUP * const clientSetup ); Description This function sets up the device communication parameters. Using this API user can have configurations like chip select and baud rate specific to a client. The driver will be able to switch the between clients dynamically. 'DRV_SPI_CLIENT_SPECIFIC_CONTROL' must be defined in 'system_config.h'. This function is only useful for instance which has got multiple slaves. Preconditions The DRV_SPI_Initialize routine must have been called. DRV_SPI_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open instance handle, returned from the driver's open routine clientSetup Communication parameters identified by DRV_SPI_CLIENT_SETUP Returns None Remarks This is an optional call. It is necessary only two clients using needs different configurations. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open DRV_SPI_CLIENT_SETUP clientSetup; // Populate the communication setup configuration structure 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-436 clientSetup.baudRate = 5000; clientSetup.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; clientSetup.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE; clientSetup.callback = &callBackFunction; // callback registered DRV_SPI_ClientSetup ( handle, &clientSetup ); 5.1.9.7.2.3 DRV_SPI_Close Function C void DRV_SPI_Close( DRV_HANDLE handle ); Description This function closes an opened instance of the SPI driver, invalidating the handle. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_USART_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open DRV_SPI_Close ( handle ); 5.1.9.7.2.4 DRV_SPI_Open Function C DRV_HANDLE DRV_SPI_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); Description This routine opens the specified USART driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options additionally affect the behavior of the DRV_USART_Read() and DRV_USART_Write() functions. If the ioIntent is DRV_IO_INTENT_NONBLOCKING, then these function will not block even if the required amount of data could not be processed. If the ioIntent is DRV_IO_INTENT_BLOCKING, these functions will block till the required amount of data is processed. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-437 If ioIntent is DRV_IO_INTENT_READ, the client will only be read from the driver. If ioIntent is DRV_IO_INTENT_WRITE, the client will only be able to write to the driver. If the ioIntent in DRV_IO_INTENT_READWRITE, the client will be able to do both, read and write. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Preconditions The DRV_SPI_Initialize function must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_USART_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. Remarks The handle returned is valid until the DRV_USART_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Example DRV_HANDLE handle; handle = DRV_SPI_Open( DRV_SPI_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } 5.1.9.7.3 Miscellaneous Functions 5.1.9.7.3.1 DRV_SPI_BufferAddRead Function C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddRead( DRV_HANDLE handle, void * rxBuffer, size_t size ); 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-438 Description Registers a buffer for a read operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine rxBuffer The buffer to which the data should be written to. size Number of bytes to be read. Returns None. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_SPI_Open function and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_SPI_Open function or the driver was built to only support non-blocking behavior the call will return immediately. If the driver was not able to accept the data, an overrun error status will be captured. To ensure that the driver is ready to accept data, the caller must first check the return value to DRV_SPI_BufferStatus, as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE myBuffer[MY_BUFFER_SIZE]; // PUT API returns data in any case, upto the user to use it DRV_SPI_BufferAddRead( handle, myBuffer, 10 ); if( DRV_SPI_BUFFER_STATUS_SUCCESS & DRV_SPI_BufferStatus( handle ) ) { // All transmitter data has been sent. } 5.1.9.7.3.2 DRV_SPI_BufferAddWrite Function C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWrite( DRV_HANDLE handle, void * txBuffer, size_t size ); Description Registers a buffer for a read operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-439 DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine rxBuffer The buffer to which the data should be written to. size Number of bytes to be read. Returns None. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_SPI_Open function and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_SPI_Open function or the driver was built to only support non-blocking behavior the call will return immediately. If the driver was not able to accept the data, an overrun error status will be captured. To ensure that the driver is ready to accept data, the caller must first check the return value to DRV_SPI_BufferStatus, as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; // Pre-initialize myBuffer with MY_BUFFER_SIZE bytes of valid data. numBytes = 0; // PUT API returns data in any case, upto the user to use it DRV_SPI_BufferAddRead( handle, myBuffer, 10 ); if( DRV_SPI_BUFFER_STATUS_SUCCESS & DRV_SPI_BufferStatus( handle ) ) { // All transmitter data has been sent. } 5.1.9.7.3.3 DRV_SPI_BufferAddWriteRead Function C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWriteRead( DRV_HANDLE handle, void * txBuffer, void * rxBuffer, size_t size ); Description Registers a buffer for a read operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-440 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine rxBuffer The buffer to which the data should be written to. size Number of bytes to be read. Returns None. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_SPI_Open function and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_SPI_Open function or the driver was built to only support non-blocking behavior the call will return immediately. If the driver was not able to accept the data, an overrun error status will be captured. To ensure that the driver is ready to accept data, the caller must first check the return value to DRV_SPI_BufferStatus, as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open SPI_DATA_TYPE myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; // Pre-initialize myBuffer with MY_BUFFER_SIZE bytes of valid data. numBytes = 0; // PUT API returns data in any case, upto the user to use it DRV_SPI_BufferAddWriteRead( handle, myTxBuffer, myRxBuffer, 10 ); if( DRV_SPI_BUFFER_STATUS_SUCCESS & DRV_SPI_BufferStatus( handle ) ) { // All transmitter data has been sent. } 5.1.9.7.3.4 DRV_SPI_VersionGet Function C unsigned int DRV_SPI_VersionGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the SPI driver version. The version is encoded as major * 10000 + minor * 100 + patch. The stringed version can be obtained using DRV_SPI_VersionStrGet. Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for Returns Current driver version in numerical format. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-441 Remarks None. Example unsigned int version; version = DRV_SPI_VersionGet( DRV_SPI_INDEX_0 ); if(version < 110200) { // Do Something } 5.1.9.7.3.5 DRV_SPI_VersionStrGet Function C char * DRV_SPI_VersionStrGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the SPI driver version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using DRV_SPI_VersionGet. Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for Returns Current the SPI driver version in the string format. Remarks None. Example char *version; version = DRV_SPI_VersionStrGet( DRV_SPI_INDEX_0 ); printf("%s", version); 5.1.9.7.3.6 DRV_SPI_INDEX_1 Macro C #define DRV_SPI_INDEX_1 1 Description This is macro DRV_SPI_INDEX_1. 5.1.9.7.3.7 DRV_SPI_INDEX_2 Macro C #define DRV_SPI_INDEX_2 2 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-442 Description This is macro DRV_SPI_INDEX_2. 5.1.9.7.3.8 DRV_SPI_INDEX_3 Macro C #define DRV_SPI_INDEX_3 3 Description This is macro DRV_SPI_INDEX_3. 5.1.9.7.3.9 DRV_SPI_INDEX_4 Macro C #define DRV_SPI_INDEX_4 4 Description This is macro DRV_SPI_INDEX_4. 5.1.9.7.3.10 DRV_SPI_INDEX_5 Macro C #define DRV_SPI_INDEX_5 5 Description This is macro DRV_SPI_INDEX_5. 5.1.9.7.3.11 DRV_SPI_RX_FIFO_INTERRUPT_MODE Macro C #define DRV_SPI_RX_FIFO_INTERRUPT_MODE SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_FULL Description This is macro DRV_SPI_RX_FIFO_INTERRUPT_MODE. 5.1.9.7.3.12 DRV_SPI_TX_FIFO_INTERRUPT_MODE Macro C #define DRV_SPI_TX_FIFO_INTERRUPT_MODE SPI_FIFO_INTERRUPT_WHEN_TRANSMISSION_IS_COMPLETE Description This is macro DRV_SPI_TX_FIFO_INTERRUPT_MODE. 5.1.9.7.4 Data Types and Constants 5.1.9.7.4.1 DRV_SPI_BAUD_RATE Macro C #define DRV_SPI_BAUD_RATE 8000000 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-443 Description SPI baud rate value configuration This macro controls the baud rate value of the SPI driver. Remarks None. 5.1.9.7.4.2 DRV_SPI_BAUD_RATE_CLOCK Macro C #define DRV_SPI_BAUD_RATE_CLOCK SPI_BAUD_RATE_CLOCK_MCLK Description SPI baud rate clock selection This macro selects the SPI baud rate clock. Remarks None. 5.1.9.7.4.3 DRV_SPI_BUFFER_HANDLE_INVALID Macro C #define DRV_SPI_BUFFER_HANDLE_INVALID ((DRV_SPI_BUFFER_HANDLE)(-1)) Description SPI Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_SPI_BufferAddRead() and DRV_SPI_BufferAddWrite() function if the buffer add request was not successful. Remarks None 5.1.9.7.4.4 DRV_SPI_BUFFER_SIZE Macro C #define DRV_SPI_BUFFER_SIZE 8 Description This is macro DRV_SPI_BUFFER_SIZE. 5.1.9.7.4.5 DRV_SPI_BUFFER_USAGE_TYPE Macro C #define DRV_SPI_BUFFER_USAGE_TYPE DRV_SPI_BUFFER_TYPE_STANDARD Description SPI buffer type configuration This macro controls the buffer type of the SPI driver. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-444 Remarks None. 5.1.9.7.4.6 DRV_SPI_CLIENTS_NUMBER Macro C #define DRV_SPI_CLIENTS_NUMBER 1 Description SPI maximum number of clients This definition selects the maximum number of clients that the SPI driver can support at run time. Remarks None. 5.1.9.7.4.7 DRV_SPI_CLOCK_OPERATION_MODE Macro C #define DRV_SPI_CLOCK_OPERATION_MODE DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE Description SPI clock mode configuration This macro controls the clock mode of the SPI driver. Remarks None. 5.1.9.7.4.8 DRV_SPI_COMMUNICATION_WIDTH Macro C #define DRV_SPI_COMMUNICATION_WIDTH SPI_COMMUNICATION_8BIT_WIDE Description SPI communication width configuration This macro controls the communication width of the SPI driver. Remarks None. 5.1.9.7.4.9 DRV_SPI_FRAME_SYNC_PULSE_COUNT Macro C #define DRV_SPI_FRAME_SYNC_PULSE_COUNT SPI_FRAME_SYNC_PULSE_16_CHAR Description SPI frame sync pulse count selection This macro selects the SPI frame sync pulse count. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-445 5.1.9.7.4.10 DRV_SPI_FRAME_SYNC_PULSE_DIRECTION Macro C #define DRV_SPI_FRAME_SYNC_PULSE_DIRECTION SPI_FRAME_PULSE_DIRECTION_INPUT Description SPI frame sync pulse direction selection This macro selects the SPI frame sync pulse direction. Remarks None. 5.1.9.7.4.11 DRV_SPI_FRAME_SYNC_PULSE_EDGE Macro C #define DRV_SPI_FRAME_SYNC_PULSE_EDGE SPI_FRAME_PULSE_EDGE_PRECEDES_FIRST_CLOCK Description SPI frame sync pulse edge selection This macro selects the SPI frame sync pulse edge. Remarks None. 5.1.9.7.4.12 DRV_SPI_FRAME_SYNC_PULSE_POLARITY Macro C #define DRV_SPI_FRAME_SYNC_PULSE_POLARITY SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH Description SPI frame sync pulse polarity selection This macro selects the SPI frame sync pulse polarity. Remarks None. 5.1.9.7.4.13 DRV_SPI_FRAME_SYNC_PULSE_WIDTH Macro C #define DRV_SPI_FRAME_SYNC_PULSE_WIDTH SPI_FRAME_PULSE_WIDTH_TO_ONE_WORD Description SPI frame sync pulse width selection This macro selects the SPI frame sync pulse width. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-446 5.1.9.7.4.14 DRV_SPI_INDEX Macro C #define DRV_SPI_INDEX DRV_SPI_INDEX_2 Description SPI static index selection This definition selects the SPI static index for the driver object reference. Remarks This index is required to make a reference to the driver object. 5.1.9.7.4.15 DRV_SPI_INDEX_0 Macro C #define DRV_SPI_INDEX_0 0 Description SPI Driver Module Index Numbers These constants provide the SPI driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SPI_Initialize and DRV_SPI_Open functions to identify the driver instance in use. 5.1.9.7.4.16 DRV_SPI_INDEX_COUNT Macro C #define DRV_SPI_INDEX_COUNT SPI_NUMBER_OF_MODULES Description SPI Driver Module Index Count This constant identifies the number of valid SPI driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. 5.1.9.7.4.17 DRV_SPI_INPUT_SAMPLE_PHASE Macro C #define DRV_SPI_INPUT_SAMPLE_PHASE SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE Description SPI input sample phase selection This macro selects the SPI input sample phase. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-447 5.1.9.7.4.18 DRV_SPI_INSTANCES_NUMBER Macro C #define DRV_SPI_INSTANCES_NUMBER 1 Description SPI hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Remarks None. 5.1.9.7.4.19 DRV_SPI_INTERRUPT_MODE Macro C #define DRV_SPI_INTERRUPT_MODE false Description SPI interrupt and polled mode operation control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of SPI operation is desired • false - Select if polling mode of SPI operation is desired Not defining this option to true or false will result in build error. Remarks None. 5.1.9.7.4.20 DRV_SPI_INTERRUPT_SOURCE_ERROR Macro C #define DRV_SPI_INTERRUPT_SOURCE_ERROR INT_SOURCE_SPI_1_ERROR Description SPI error interrupt source Macro to define the error interrupt source in case of static driver. Remarks Refer to the INT PLIB document for more information on INT_SOURCE enumeration 5.1.9.7.4.21 DRV_SPI_INTERRUPT_SOURCE_RX Macro C #define DRV_SPI_INTERRUPT_SOURCE_RX INT_SOURCE_SPI_1_EVENT Description SPI receive interrupt source This macro defines the receive interrupt source of the static driver. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-448 Remarks Refer to the Interrupt Peripheral Library documentation for more information on INT_SOURCE enumeration. This should be specified in case the device does not have a dedicated receive interrupt source. 5.1.9.7.4.22 DRV_SPI_INTERRUPT_SOURCE_TX Macro C #define DRV_SPI_INTERRUPT_SOURCE_TX INT_SOURCE_SPI_1_EVENT Description SPI transmit/receive or transmit alone interrupt source This macro defines the transmit/receive or transmit alone interrupt source of the static driver. Remarks Refer to the Interrupt Peripheral Library documentation for more information on the INT_SOURCE enumeration. Some devices have a single interrupt source for both transmit and receive communication, while some have a dedicated transmit interrupt source. These are handled through the DRV_SPI_INTERRUPT_SOURCE configuration switch. 5.1.9.7.4.23 DRV_SPI_PERIPHERAL_ID Macro C #define DRV_SPI_PERIPHERAL_ID SPI_ID_1 Description SPI peripheral ID selection This macro selects the SPI peripheral ID selection. This is an intialization override of the spiID member of the intialization configuration. Remarks Some devices also support SPI_ID_0. 5.1.9.7.4.24 DRV_SPI_PORTS_REMAP_USAGE Macro C #define DRV_SPI_PORTS_REMAP_USAGE false Description SPI pins remap selection This macro selects the SPI pins remap. The possible values of this macro are: • true - Remap is required • false - Remap is not required Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-449 5.1.9.7.4.25 DRV_SPI_POWER_STATE Macro C #define DRV_SPI_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description SPI power state configuration This macro controls the power state of the SPI driver. Remarks This feature may not be available in the device or the SPI module selected. 5.1.9.7.4.26 DRV_SPI_PROTOCOL Macro C #define DRV_SPI_PROTOCOL DRV_SPI_PROTOCOL_TYPE_STANDARD Description SPI protocol type configuration This macro controls the protocol type of the SPI driver. Remarks None. 5.1.9.7.4.27 DRV_SPI_USAGE_MODE Macro C #define DRV_SPI_USAGE_MODE DRV_SPI_MODE_MASTER Description SPI usage mode configuration This macro controls the usage mode of the SPI driver. Remarks None. 5.1.9.7.4.28 DRV_SPI_BUFFER_EVENT Enumeration C typedef enum { DRV_SPI_BUFFER_EVENT_PENDING, DRV_SPI_BUFFER_EVENT_COMPLETE, DRV_SPI_BUFFER_EVENT_ERROR } DRV_SPI_BUFFER_EVENT; Description SPI Driver Buffer Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_NVM_BufferAddRead or DRV_NVM_BufferAddWrite functions. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-450 Members Members Description DRV_SPI_BUFFER_EVENT_PENDING Buffer is pending to get processed DRV_SPI_BUFFER_EVENT_COMPLETE All data from or to the buffer was transferred successfully. DRV_SPI_BUFFER_EVENT_ERROR There was an error while processing the buffer transfer request. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_NVM_BufferEventHandlerSet function when a buffer transfer request is completed. 5.1.9.7.4.29 DRV_SPI_BUFFER_EVENT_HANDLER Type C typedef void (* DRV_SPI_BUFFER_EVENT_HANDLER)(DRV_SPI_BUFFER_EVENT event, DRV_SPI_BUFFER_HANDLE bufferHandle, uintptr_t context); Description SPI Driver Buffer Event Handler Function Pointer This data type defines the required function signature for the SPI driver buffer event handling callback function. A client must register a pointer to a buffer event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values and return value are described here and a partial example implementation is provided. Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the vent relates context Value identifying the context of the application that registered the event handling function. Returns None. Remarks If the event is DRV_SPI_BUFFER_EVENT_COMPLETE, it means that the data was transferred successfully. If the event is DRV_SPI_BUFFER_EVENT_ERROR, it means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_SPI_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The event handler function executes in an interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive operations with in this function. Example void APP_MyBufferEventHandler( DRV_SPI_BUFFER_EVENT event, DRV_SPI_BUFFER_HANDLE bufferHandle, uintptr_t context ) { 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-451 MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SPI_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_SPI_BUFFER_EVENT_ERROR: default: // Handle error. break; } } 5.1.9.7.4.30 DRV_SPI_BUFFER_HANDLE Type C typedef uintptr_t DRV_SPI_BUFFER_HANDLE; Description SPI Driver Buffer Handle A buffer handle value is returned by a call to the DRV_SPI_BufferAddRead()/ DRV_SPI_BufferAddWriteor DRV_SPI_BufferAddReadWrite() functions. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None 5.1.9.7.4.31 DRV_SPI_BUFFER_TYPE Enumeration C typedef enum { DRV_SPI_BUFFER_TYPE_STANDARD, DRV_SPI_BUFFER_TYPE_ENHANCED } DRV_SPI_BUFFER_TYPE; Description SPI Buffer Type Selection This enumeration identifies the various buffer types of the SPI module. Members Members Description DRV_SPI_BUFFER_TYPE_STANDARD SPI Buffer Type Standard DRV_SPI_BUFFER_TYPE_ENHANCED SPI Enhanced Buffer Type Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-452 5.1.9.7.4.32 DRV_SPI_CLIENT_SETUP Type C typedef struct _DRV_SPI_CLIENT_SETUP DRV_SPI_CLIENT_SETUP; Description SPI Client Initialization Data This structure lists the elements needed to set up an SPI client. Used by the function DRV_SPI_ClientSetup function. This data type defines the data required to initialize an SPI client. Remarks None. 5.1.9.7.4.33 DRV_SPI_CLOCK_MODE Enumeration C typedef enum { DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE, DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL, DRV_SPI_CLOCK_MODE_IDLE_HIGH_EDGE_FALL, DRV_SPI_CLOCK_MODE_IDLE_HIGH_EDGE_RISE } DRV_SPI_CLOCK_MODE; Description SPI Clock Mode Selection This enumeration identifies the various clock modes of the SPI module. Members Members Description DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE SPI Clock Mode 0 - Idle State Low & Sampling on Rising Edge DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL SPI Clock Mode 1 - Idle State Low & Sampling on Falling Edge DRV_SPI_CLOCK_MODE_IDLE_HIGH_EDGE_FALL SPI Clock Mode 2 - Idle State High & Sampling on Falling Edge DRV_SPI_CLOCK_MODE_IDLE_HIGH_EDGE_RISE SPI Clock Mode 3 - Idle State High & Sampling on Rising Edge Remarks None. 5.1.9.7.4.34 DRV_SPI_INIT Type C typedef struct _DRV_SPI_INIT DRV_SPI_INIT; Description SPI Driver Initialization Data This data type defines the data required to initialize or reinitialize the SPI driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-453 5.1.9.7.4.35 DRV_SPI_MODE Enumeration C typedef enum { DRV_SPI_MODE_MASTER, DRV_SPI_MODE_SLAVE } DRV_SPI_MODE; Description SPI Usage Modes Enumeration This enumeration identifies the various usage modes of the SPI module. Members Members Description DRV_SPI_MODE_MASTER SPI Mode Master DRV_SPI_MODE_SLAVE SPI Mode Slave Remarks None. 5.1.9.7.4.36 DRV_SPI_PROTOCOL_TYPE Enumeration C typedef enum { DRV_SPI_PROTOCOL_TYPE_STANDARD, DRV_SPI_PROTOCOL_TYPE_FRAMED, DRV_SPI_PROTOCOL_TYPE_AUDIO } DRV_SPI_PROTOCOL_TYPE; Description SPI Protocols Enumeration This enumeration identifies the various protocols of the SPI module. Members Members Description DRV_SPI_PROTOCOL_TYPE_STANDARD SPI Protocol Type Standard DRV_SPI_PROTOCOL_TYPE_FRAMED SPI Protocol Type Framed DRV_SPI_PROTOCOL_TYPE_AUDIO SPi Protocol Type Audio Remarks None. 5.1.9.8 Files Files Name Description drv_spi.h SPI device driver interface file. drv_spi_config_template.h SPI Driver configuration definitions template. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-454 Description 5.1.9.8.1 drv_spi.h SPI Driver Interface The SPI driver provides a simple interface to manage the SPI module. This file defines the interface definitions and prototypes for the SPI driver. Enumerations Name Description DRV_SPI_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_SPI_BUFFER_TYPE Identifies the various buffer types of the SPI module. DRV_SPI_CLOCK_MODE Identifies the various clock modes of the SPI module. DRV_SPI_MODE Identifies the various usage modes of the SPI module. DRV_SPI_PROTOCOL_TYPE Identifies the various protocols of the SPI module. Functions Name Description DRV_SPI_BufferAddRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. DRV_SPI_BufferAddWrite Registers a buffer for a read operation. Actual transfer will happen in the Task function. DRV_SPI_BufferAddWriteRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. DRV_SPI_BufferStatus Returns the transmitter and receiver transfer status. DRV_SPI_ClientSetup Initializes a client. DRV_SPI_Close Closes an opened instance of the SPI driver DRV_SPI_Deinitialize De-initializes the specified instance of the SPI driver module. DRV_SPI_Initialize Initializes the SPI driver. DRV_SPI_Open Opens the specified SPI driver instance and returns a handle to it. DRV_SPI_Read Gets/Reads byte(s) from SPI. The function will wait until the specified number of bytes is received. DRV_SPI_Status Provides the current status of the SPI driver module. DRV_SPI_Tasks Maintains the driver's state machine and implements its ISR. DRV_SPI_VersionGet Gets the SPI driver version in numerical format. DRV_SPI_VersionStrGet Gets the SPI driver version in string format. DRV_SPI_Write Writes the data to SPI. The function will wait until all the bytes are transmitted. Macros Name Description DRV_SPI_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_SPI_INDEX_0 SPI driver index definitions. DRV_SPI_INDEX_1 This is macro DRV_SPI_INDEX_1. DRV_SPI_INDEX_2 This is macro DRV_SPI_INDEX_2. DRV_SPI_INDEX_3 This is macro DRV_SPI_INDEX_3. DRV_SPI_INDEX_4 This is macro DRV_SPI_INDEX_4. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-455 DRV_SPI_INDEX_5 This is macro DRV_SPI_INDEX_5. DRV_SPI_INDEX_COUNT Number of valid SPI driver indices. Types Name Description DRV_SPI_BUFFER_EVENT_HANDLER Pointer to a SPI Driver Buffer Event handler function DRV_SPI_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. DRV_SPI_CLIENT_SETUP Defines the data required to initialize an SPI client. DRV_SPI_INIT Defines the data required to initialize or reinitialize the SPI driver File Name drv_spi.h Company Microchip Technology Inc. 5.1.9.8.2 drv_spi_config_template.h SPI Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. Macros Name Description DRV_SPI_BAUD_RATE Controls the baud rate value of the SPI driver. DRV_SPI_BAUD_RATE_CLOCK Selects the SPI baud rate clock. DRV_SPI_BUFFER_SIZE This is macro DRV_SPI_BUFFER_SIZE. DRV_SPI_BUFFER_USAGE_TYPE Controls the buffer type of the SPI driver. DRV_SPI_CLIENTS_NUMBER Selects the miximum number of clients. DRV_SPI_CLOCK_OPERATION_MODE Controls the clock mode of the SPI driver. DRV_SPI_COMMUNICATION_WIDTH Controls the communication width of the SPI driver. DRV_SPI_FRAME_SYNC_PULSE_COUNT Selects the SPI frame sync pulse count. DRV_SPI_FRAME_SYNC_PULSE_DIRECTION Selects the SPI frame sync pulse direction. DRV_SPI_FRAME_SYNC_PULSE_EDGE Selects the SPI frame sync pulse edge. DRV_SPI_FRAME_SYNC_PULSE_POLARITY Selects the SPI frame sync pulse polarity. DRV_SPI_FRAME_SYNC_PULSE_WIDTH Selects the SPI frame sync pulse width. DRV_SPI_INDEX SPI static index selection. DRV_SPI_INPUT_SAMPLE_PHASE Selects the SPI input sample phase. DRV_SPI_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver . DRV_SPI_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_SPI_INTERRUPT_SOURCE_ERROR Defines the error interrupt source in case of static driver DRV_SPI_INTERRUPT_SOURCE_RX Defines the receive interrupt source in case of static driver. DRV_SPI_INTERRUPT_SOURCE_TX Defines the transmit/receive or transmit alone interrupt source in case of static driver. DRV_SPI_PERIPHERAL_ID SPI peripheral ID selection. DRV_SPI_PORTS_REMAP_USAGE Selects the SPI pins remap. DRV_SPI_POWER_STATE Controls the power state of the SPI driver. 5.1 Driver Library Help MPLAB Harmony Help SPI Driver Library 5-456 DRV_SPI_PROTOCOL Controls the protocol type of the SPI driver. DRV_SPI_RX_FIFO_INTERRUPT_MODE This is macro DRV_SPI_RX_FIFO_INTERRUPT_MODE. DRV_SPI_TX_FIFO_INTERRUPT_MODE This is macro DRV_SPI_TX_FIFO_INTERRUPT_MODE. DRV_SPI_USAGE_MODE Controls the usage mode of the SPI driver. File Name drv_spi_config_template.h Company Microchip Technology Inc. 5.1.10 Timer Driver Library 5.1.10.1 Introduction Timer Driver Library for Microchip Microcontrollers This library provides an interface to manage the Timer module on the Microchip family of microcontrollers during different modes of operation. Description Overview Timers are useful for generating accurate time based periodic interrupts for software application or real time operating systems. Other uses include counting external pulses or accurate timing measurement of external events using the timer's gate functions and accurate hardware delays. Please refer to the the Data Sheet for the part that is being used. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. 5.1.10.2 Release Notes MPLAB Harmony Version: v0.70b Timer Driver Library Version : 0.02 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-457 5.1.10.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.10.4 Using the Library This topic describes the basic architecture of the Timer Driver Library and provides information and examples on how to use it. Interface Header File: drv_tmr.h The interface to the Timer Driver Library is defined in the "drv_tmr.h" header file. Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.10.4.1 Abstraction Model Microchip devices have two type of timers: • Period-Match - When the counting timer matches the configured period, this timer is said to complete one iteration and an interrupt is set • Overflow - When the counting timer overflows/rolls over, interrupt is set and restarts from its previously set counter value. In this case, the preset period value would be the maximum possible count value. The Timer Driver abstracts this difference and provides a unified model for both of these types of timers. Description Abstraction Model The abstraction model of the Timer Driver is explained in the following diagram: 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-458 The core functionality of the Timer allows access to both the counter and the period values. The unified model allows user not to worry about whether the Timer currently being used is a overflow or period match-based. The user simply updates the period and the driver automatically takes care of adjusting the respective Timer's periodicity. In case a user needs any modification into the counter's initial value (i.e., to adjust for any errors in periodicity), they are allowed to do so using the counter control interfaces. 5.1.10.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The table below lists the interface section and its brief description. Library Interface Section Description Configuration Provides macros for configuring the system. It is required that the system configures the driver to build correctly by choosing appropriate configuration options as listed in this section. These macros enable different features or modes of the timer peripheral. System Interaction Functions Provides interfaces to system layer to initialize, deinitialize and reinitialize the module. This section also describes functions to query the status of the module. Core Functions Provides interfaces for core functionality of the driver. Alarm Functions Provides interfaces to handle alarm features, if alarm functionality is enabled. Period Functions Provides interfaces to control the periodicity of the timers. Counter Control Functions Provides interfaces to update the counter values. Miscellaneous Functions Provides interfaces to get the version information, timer tick and operating frequencies. 5.1.10.4.3 How the Library Works The library provides interfaces to support: • System Interaction • Sync Mode Setup • Period Modification • Counter Modification • Client Core Functionality • Client Alarm Functionality (optional function, enabled using configuration options) • Other Optional Functionality (enabled using configuration options) Note: Any code segment pertaining to the driver interfaces will work for both the static or dynamic configurations. It is not necessary to modify the code to move from one configuration to the other (i.e., from static or dynamic or static-multi). 5.1.10.4.3.1 System Interaction This section describes Timer initialization and reinitialization. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-459 Description Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or re-initialized. During system initialization, each instance of the Timer module will be initialized with the following configuration settings (either passed dynamically at run time using DRV_TMR_INIT or by using initialization overrides) that are supported by the specific Timer module hardware: Initialization member Configuration Name Description moduleInit DRV_TMR_POWER_STATE System module initialization of the power state. tmrId DRV_TMR_PERIPHERAL_ID Timer hardware module ID (peripheral library-level ID). clockSource DRV_TMR_CLOCK_SOURCE Clock Source Selection, Enables either the internal or the external clock, using one of the possible values from TMR_CLOCK_SOURCE. timerPeriod DRV_TMR_TIMER_PERIOD Timer period value. prescale DRV_TMR_PRESCALE Sets up the prescaler, using one of the possible values from TMR_PRESCALE. sourceEdge DRV_TMR_SOURCE_EDGE Source edge selection, if supported by the hardware, selects either the rising or falling edge, using one of the possible values from TMR_CLOCK_SOURCE_EDGE. postscale DRV_TMR_POSTSCALE Sets up the postscaler, if supported by the hardware, using one of the possible values from TMR_POSTSCALE. syncMode DRV_TMR_SYNCHRONIZATION_MODE Selects the operation mode of the instance using one of the possible values from DRV_TMR_SYNC_MODE. interruptSource DRV_TMR_INTERRUPT_SOURCE Interrupt source identifier for the Timer module being initialized, which is available from the respective device's processor headers. The DRV_TMR_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_TMR_Reinitialize, DRV_TMR_Deinitialize, DRV_TMR_Status and DRV_TMR_Tasks. Example: Timer Initialization Through DRV_TMR_INIT DRV_TMR_INIT init; SYS_MODULE_OBJ object; SYS_STATUS tmrStatus; // populate the TMR init configuration structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_2; init.timerPeriod = 0xABCD; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); tmrStatus = DRV_TMR_Status(object); if ( SYS_STATUS_READY != tmrStatus) { // Handle error } 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-460 Example: Timer initialization Through Configuration Source file: SYS_MODULE_OBJ object; SYS_STATUS tmrStatus; int main( void ) { object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)NULL); tmrStatus = DRV_TMR_Status(object); if ( SYS_STATUS_READY != tmrStatus) { // Handle error } } Configuration file: sys_config.h #define DRV_TMR_POWER_STATE SYS_MODULE_POWER_RUN_FULL #define DRV_TMR_PERIPHERAL_ID TMR_ID_3 // TMR_MODULE_ID #define DRV_TMR_CLOCK_SOURCE TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK #define DRV_TMR_PRESCALE TMR_PRESCALE_TX_VALUE_256 #define DRV_TMR_SYNCHRONIZATION_MODE DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL #define DRV_TMR_INTERRUPT_SOURCE INT_SOURCE_TIMER_3 #define DRV_TMR_TIMER_PERIOD 0x0000F424 // 200ms Deinitialization Once the Initialize operation has been called, the Deinitialize operation must be called before the iIitialize operation can be called again.This routine may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the routine will never block for hardware Timer access. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TMR_Status operation. Status Timer status is available to query the module state before, during, and after initialization, deinitialization, and reinitialization. Tasks Routine The interface DRV_TMR_Tasks can be called in two ways: • By the system task service in a polled environment • By the interrupt service routine of the timer in an interrupt based system Example: Polling int main( void ) { SYS_MODULE_OBJ object; object = DRV_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_TMR_Status( object ) ) return 0; while (1) { DRV_TMR_Tasks (object); } } Example: Interrupt int main( void ) { 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-461 SYS_MODULE_OBJ object; object = DRV_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_TMR_Status( object ) ) return 0; while (1); } /* Sample interrupt routine not specific to any device family */ void ISR T1Interrupt(void) { //Call the Timer Tasks routine DRV_TMR_Tasks(object); } 5.1.10.4.3.2 Client Interaction This section describer general client operation. Description General Client Operation For the application to begin using an instance of the Timer module, it must call the DRV_TMR_Open function. This provides the configuration required to open the Timer instance for operation. If the driver is deinitialized using the function DRV_TMR_Deinitialize, the application must call the DRV_TMR_Open function again to set up the instance of the Timer. The function DRV_TMR_Open need not be called again if the system is reinitialized using the DRV_TMR_Reinitialize function. The Timer Driver supports only the 'DRV_IO_INTENT_EXCLUSIVE' IO_INTENT. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); if( handle == DRV_HANDLE_INVALID ) { // Client cannot open the instance. } The function DRV_TMR_Close closes an already opened instance of the Timer Driver, invalidating the handle. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); /*...*/ DRV_TMR_Close( handle ); The client has the option to check the status through the interface DRV_TMR_ClientStatus. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-462 if ( DRV_TMR_CLIENT_STATUS_READY != DRV_TMR_ClientStatus( handle ) ) return 0; 5.1.10.4.3.3 Sync Mode Selection This section describes the Sync mode selection process. Description Sync Mode Selection The Timer Driver can operate in various modes as described below. They can be changed using DRV_TMR_SyncModeSet, and the current mode being using by the Timer can be retrieved using DRV_TMR_SyncModeGet/ DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL - Synchronous Internal Clock Counter • This mode can be used to provide the following capabilities: • Create elapsed time measurements • Create time delays • Create periodic timer interrupts • The input clock to the Timer is provided from the internal system clock • The Timer increments in the effective delta time specified by the prescaler and the selected source clock DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL_GATED - Synchronous Internal Gated Counter • In this mode, the operation is dependent on an external signal applied to a pin assigned as a gate. When the gate signal remains high, the Timer increments. When the gate signal goes low, the operation terminates. • Input clock to the timer is provided from the internal system clock • The Timer increments in the effective delta time specified by the prescaler and the selected source clock • Gated Timer mode is not possible when the Timer is set to use external clock source DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC - Synchronous External Clock Counter • The Synchronous External Clock Counter operation provides the following capabilities: • Counting periodic or non-periodic pulses • Uses the external clock as the time base for Timers • The selected Timer increments on every rising edge of the clock input on the TxCK pin DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITH_CLKSYNC - Synchronous External Clock Counter • The clock source for the Timer is provided externally • The selected Timer increments on every rising edge of the input on the TxCK pin • External Clock sync is enabled to operate in the Synchronous mode DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC - Asynchronous External Clock Counter • The Asynchronous Timer operation provides the following capabilities: • The Timer can operate during Sleep mode and can generate an interrupt on a period register match that will wake the processor from Sleep or Idle modes. • The Timer can be clocked from the secondary oscillator for real-time clock applications • The clock source for the Timer is provided externally • The selected Timer increments on every rising edge of the clock input on the TxCK pin • Synchronization with the external clock is disabled DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITH_CLKSYNC - Asynchronous External Clock Counter 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-463 • The clock source for the Timer is provided externally • The selected Timer increments on every rising edge of the clock input on the TxCK pin • Synchronization with the external clock is enabled Changing the Sync Mode Perform the following steps before changing the sync mode. Preconditions: DRV_TMR_Open should have been called before calling this function and should have returned a valid handle. 1. Stop the TMR module using DRV_TMR_Stop. 2. Change the sync mode using DRV_TMR_SyncModeSet. 3. Update the counter using DRV_TMR_Counter[8Bit/16Bit/32Bit]Set, if applicable. 4. Start the TMR module using DRV_TMR_Start. Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); /* Stop the timer */ DRV_TMR_Stop( handle ); /* Change the sync mode */ DRV_TMR_SyncModeSet( handle, DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL ); /* Re-start the timer */ DRV_TMR_Start( handle ); Note: Not all modes are supported by all the Timer modules. Please refer the specific device data sheet to determine the supported modes for your device. 5.1.10.4.3.4 Period Modification This section describes Period modification for the different types of Timers (i.e., 8-/16-/32-bit). Description These set of functions help modify the Timer periodicity at the client level, regardless of whether it is an overflow or a period match-based Timer. This interface can be used to alter the already set periodicity at the system level interface DRV_TMR_Initialize. Period Modification Periodicity for the type of Timer (8-/16-/32-bit) can be controlled as follows: • 8-bit timer periodicity can be modified using DRV_TMR_Period8BitSet and the current period value can be obtained using DRV_TMR_Period8BitGet • 16-bit timer periodicity can be modified using DRV_TMR_Period16BitSet and the current period value can be obtained using DRV_TMR_Period16BitGet • 32-bit timer periodicity can be modified using DRV_TMR_Period32BitSet and the current period value can be obtained using DRV_TMR_Period32BitGet Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); /* ... */ 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-464 /* Update the new period */ DRV_TMR_Period16BitSet( handle, 0x0000C350); 5.1.10.4.3.5 Counter Modification This section describes counter modification for the different types of Timers (i.e., 8-/16-/32-bit). Description These set of functions help modify the initial value of the Timer counters to help adjust any errors in the periodicity. Counter Modification Initial counter values can be controlled as follows: • 8-bit timer initial value can be modified using DRV_TMR_Counter8BitSet and the current counter value can be obtained using DRV_TMR_Counter8BitGet • 16-bit timer initial value can be modified using DRV_TMR_Counter16BitSet and the current counter value can be obtained using DRV_TMR_Counter16BitGet • 32-bit timer initial value can be modified using DRV_TMR_Counter32BitSet and the current counter value can be obtained using DRV_TMR_Counter32BitGet Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); /* ... */ /* Update the counter value */ /* Following code updates the initial value from 0x0000 to 0x0010 to cover up any error in the previously set periodicity */ DRV_TMR_Counter16BitSet( handle, 0x0010); 5.1.10.4.3.6 Core Functionality This section describes core functionality of the Timer Driver. Description Core functionality provides a extremely basic interface for the driver operation. Applications using the core Timer core functionality, need to perform the following: 1. The system should have completed the necessary initialization and DRV_TMR_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_TMR_Open. The Timer Driver supports exclusive access only. 3. The Timer period will have to be updated using DRV_TMR_Period[8Bit/16Bit/32Bit]Set if the client intends to override the already preset value during the initialization. The previously set value can be retrieved using DRV_TMR_Period[8Bit/16Bit/32Bit]Get. 4. Start the driver using DRV_TMR_Start. 5. Poll for the elapse status using DRV_TMR_ElapsedStatusGetAndClear and handle the rest of the processing based on the status. 6. The client will be able to stop the started Timer instance using DRV_TMR_Stop at any time and will be able to close it using DRV_TMR_Close when it is no longer required. Example : DRV_HANDLE handle; 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-465 /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); while (1) { // Interrupt mode & hence the DRV_TMR_Tasks not being called // client handle returned by the Open API if (true == DRV_TMR_ElapsedStatusGetAndClear(handle)) { // Do something } } Notes: 1. The user needs to stop the Timer before any updates on the counter or period and restart it later. 2. The Timer elapsed status gets reset after any counter or period update. 3. The Timer elapse status remains unchanged if the user tries to stop and restart later. 5.1.10.4.3.7 Alarm Functionality This section describes the Timer Driver alarm functionality. Description The Timer Driver provides alarm functionality. This is an optional advanced feature and needs to be enabled using the configuration macros. Applications using the Timer alarm functionality, need to perform the following: 1. The system should have completed the necessary initialization and DRV_TMR_Tasks should either be running in a polled environment, or in an interrupt environment. 2. Open the driver using DRV_TMR_Open. The Timer Driver supports exclusive access only. 3. Configure the alarm using DRV_TMR_AlarmSet with DRV_TMR_ALARM_CONFIG. 4. Start the driver using DRV_TMR_Start. 5. If a callback is configured, the Timer Driver will call the callback function when the alarm expires. 6. The client will be able to stop the started Timer module instance using DRV_TMR_Stop at any time and will be able to close it using DRV_TMR_Close when it is no longer required. Precondition: For the callback to work, the switch DRV_TMR_ALARM_ENABLE needs to be defined in the configuration header. Example: DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alarmConfig; uint32_t alarmCount; /* Open the client */ handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); /* Configure the timer alarm feature */ /* Callbacks are only allowed when the configuration switch DRV_TMR_ALARM_ENABLE is defined */ alarmConfig.type = DRV_TMR_ALARM_TYPE_PERIODIC; alarmConfig.callback = &Callback; DRV_TMR_AlarmSet (handle, &alarmConfig); // Get all the alarm counters based on the number of alarm objects configured 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-466 alarmCount = DRV_TMR_AlarmCountGet (handle); // Clear the Alarm counters associated with the HW instance DRV_TMR_AlarmCountClear (handle); The callback function in the application will look like: void Callback (void) { // Do something specific on an alarm event trigger } Note: The driver tasks function calls the client registered callback after the alarm expires. 5.1.10.4.3.8 Optional Interfaces This section describes additional/optional client interfaces. Description Additional/Optional client interfaces include the following. Get Operating Frequency The function DRV_TMR_OperatingFrequencyGet provides the client with the information on the Timer operating frequency. Example: DRV_HANDLE handle; uint32_t freq; /* Open the client */ handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); freq = DRV_TMR_OperatingFrequencyGet (handle); Get Tick Frequency The function DRV_TMR_TickFrequencyGet provides the client with the information on the Timer tick frequency. Example: DRV_HANDLE handle; uint32_t freq; /* Open the client */ handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); freq = DRV_TMR_TickFrequencyGet (handle); 5.1.10.4.3.9 Example Usage of the Timer Driver This section describes typical usage of the Timer Driver for various Timer modules in polling/interrupt advanced/core modes. Description Notes: 1. The interface calls remain the same whether using dynamic or static drivers. 2. There is a possibility that the user can pass NULL to the driver initialize interface. However, the respective configurations matching the init [DRV_TMR_INIT] members need to be configured in the correct manner. Example 1: // Polling mode under 32-bit count mode for a PIC32 device using the alarm feature 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-467 SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; alConf.alType = DRV_TMR_ALARM_TYPE_PERIODIC; alConf.alCallback = &TestAlarmCallback; DRV_TMR_AlarmSet (handle, &alConf); DRV_TMR_Start (handle); while (1) { DRV_TMR_Tasks (object); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void TestAlarmCallback (void) { // Do something specific on an alarm event trigger } Example 2: // Polling mode under 16-bit count mode for a PIC32/PIC24 device using the alarm feature SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_3; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-468 object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; alConf.alType = DRV_TMR_ALARM_TYPE_PERIODIC; alConf.alCallback = &TestAlarmCallback; DRV_TMR_AlarmSet (handle, &alConf); DRV_TMR_Start (handle); while (1) { DRV_TMR_Tasks (object); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void TestAlarmCallback (void) { // Do something specific on an alarm event trigger } Example 3: // Polling mode under 16-bit count mode for a PIC18 device, with Timer3 using the alarm feature SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_3; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_T1_VALUE_8; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; alConf.alType = DRV_TMR_ALARM_TYPE_PERIODIC; alConf.alCallback = &TestAlarmCallback; DRV_TMR_AlarmSet (handle, &alConf); DRV_TMR_Start (handle); while (1) 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-469 { DRV_TMR_Tasks (object); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void TestAlarmCallback (void) { // Do something specific on an alarm event trigger } Example 4: // Interrupt mode under 32-bit count mode for a PIC32 device using the alarm feature SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; SYS_INT_Initialize (); init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; alConf.alType = DRV_TMR_ALARM_TYPE_PERIODIC; alConf.alCallback = &TestAlarmCallback; DRV_TMR_AlarmSet (handle, &alConf); SYS_INT_PrioritySet (PLIB_INT_SOURCE_TIMER_3, PLIB_INT_PRIORITY_LEVEL1); SYS_INT_SubprioritySet (PLIB_INT_SOURCE_TIMER_3, PLIB_INT_SUBPRIORITY_LEVEL1); DRV_TMR_Start (handle); while (1); DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-470 void TestAlarmCallback (void) { // Do something specific on an alarm event trigger } Example 5: // Interrupt mode under 16-bit count mode for a PIC24 device using the alarm feature SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; SYS_INT_Initialize (); init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_2; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; alConf.alType = DRV_TMR_ALARM_TYPE_PERIODIC; alConf.alCallback = &TestAlarmCallback; DRV_TMR_AlarmSet (handle, &alConf); SYS_INT_PrioritySet (PLIB_INT_SOURCE_TIMER_2, PLIB_INT_PRIORITY_LEVEL1); DRV_TMR_Start (handle); while (1); DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); //end main void TestAlarmCallback (void) { // Do something specific on an alarm event trigger } Example 6: // Polling mode under 32-bit count mode for a PIC32 device using core functionality SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-471 init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Start (handle); while (1) { DRV_TMR_Tasks (object); if (true == DRV_TMR_ElapsedStatusGetAndClear(handle)) Callback(); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void Callback (void) { // Do something specific } Example 7: // Interrupt mode under 32-bit count mode for a PIC32 device using core functionality SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; SYS_INT_Initialize (); init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-472 return 0; SYS_INT_PrioritySet (PLIB_INT_SOURCE_TIMER_3, PLIB_INT_PRIORITY_LEVEL1); SYS_INT_SubprioritySet (PLIB_INT_SOURCE_TIMER_3, PLIB_INT_SUBPRIORITY_LEVEL1); DRV_TMR_Start (handle); while (1) { if (true == DRV_TMR_ElapsedStatusGetAndClear(handle)) Callback(); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void Callback (void) { // Do something specific } Example 8: // Polling mode under 16-bit count mode for a PIC18 device, with Timer3 using core functionality SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; DRV_TMR_ALARM_CONFIG alConf; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_3; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_T1_VALUE_8; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xFF00; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Start (handle); while (1) { DRV_TMR_Tasks (object); if (true == DRV_TMR_ElapsedStatusGetAndClear(handle)) Callback(); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-473 return 0; DRV_TMR_Deinitialize (object); // end main void Callback (void) { // Do something specific } 5.1.10.5 Configuring the Library The configuration of the Timer Device Library is based on the file sys_config.h This header file contains the configuration selection for the Timer Driver Library build. Based on the selections made here and the system setup, the Timer Driver driver may or may not support selected features. These configuration settings will apply to all instances of the driver. This header can be placed anywhere in the application-specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Overview section for more details. 5.1.10.5.1 Initialization Overrides Macros Name Description DRV_TMR_CLOCK_SOURCE Timer module clock source selection. DRV_TMR_PERIPHERAL_ID Timer peripheral ID selection. DRV_TMR_POSTSCALE Macro controls post scale of the TMR DRV_TMR_PRESCALE Timer module prescale value. DRV_TMR_SOURCE_EDGE Timer module source edge. DRV_TMR_SYNCHRONIZATION_MODE Controls Synchronization mode of the Timer. DRV_TMR_TIMER_PERIOD Timer period value for an overflow or a period match-based Timer. Description This section provides initialization overrides for the run time options that can be selected using DRV_TMR_INIT when passed into DRV_TMR_Initialize and DRV_TMR_Reintiailize. When any of these options are defined, the build time override will be used. 5.1.10.5.1.1 DRV_TMR_CLOCK_SOURCE Macro C #define DRV_TMR_CLOCK_SOURCE TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK Description TMR Clock Source This macro selects the Timer module clock source based on the enumeration. Remarks If defined in the configuration, this takes priority over the initialization option. Refer to the processor peripheral header for more information. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-474 5.1.10.5.1.2 DRV_TMR_PERIPHERAL_ID Macro C #define DRV_TMR_PERIPHERAL_ID TMR_ID_1 Description TMR Peripheral ID Selection This macro selects the Timer peripheral ID. This is an intialization override of the tmrID member of the intialization configuration. Remarks Some devices also support TMR_ID_0. 5.1.10.5.1.3 DRV_TMR_POSTSCALE Macro C #define DRV_TMR_POSTSCALE TMR_POSTSCALE_1_TO_1 Description TMR post scale configuration This macro controls the post scale of the TMR Remarks This feature is not available in all modules/devices. Refer to the specific device data sheet for more information. 5.1.10.5.1.4 DRV_TMR_PRESCALE Macro C #define DRV_TMR_PRESCALE TMR_PRESCALE_TX_1_TO_256 Description TMR Prescale This macro defines the Timer module prescale value. Remarks If defined in the configuration, this takes priority over the initialization option. Refer to the processor peripheral header for more information. 5.1.10.5.1.5 DRV_TMR_SOURCE_EDGE Macro C #define DRV_TMR_SOURCE_EDGE TMR_SOURCE_EDGE_INCREMENT_ON_LOW_TO_HIGH Description TMR Source Edge This macro defines the Timer module source edge. Remarks If defined in the configuration, this takes priority over the initialization option. Refer to the processor peripheral header for more information. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-475 5.1.10.5.1.6 DRV_TMR_SYNCHRONIZATION_MODE Macro C #define DRV_TMR_SYNCHRONIZATION_MODE DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL Description TMR Synchronization mode configuration This macro controls the Synchronization mode of the Timer. It accepts one of the possible values of the enumeration DRV_TMR_SYNC_MODE. Remarks If defined in the configuration, this takes priority over the initialization option. 5.1.10.5.1.7 DRV_TMR_TIMER_PERIOD Macro C #define DRV_TMR_TIMER_PERIOD 0x4567 Description TMR period value This macro defines the Timer period value for an overflow or a period match-based Timer. Remarks If defined in the configuration, this macro takes priority over the initialization option. In addition, the limit is the maximum possible Timer count width. The user is required to provide the count value. The driver will internally adjust the value as required for the Timer hardware based on the overflow or period match functionality 5.1.10.5.2 System Config Macros Name Description DRV_TMR_COUNT_WIDTH Controls the mode of the Timer. DRV_TMR_INDEX Timer static index selection. DRV_TMR_INDEX_0 Timer driver index definitions DRV_TMR_INDEX_1 This is macro DRV_TMR_INDEX_1. DRV_TMR_INDEX_2 This is macro DRV_TMR_INDEX_2. DRV_TMR_INDEX_3 This is macro DRV_TMR_INDEX_3. DRV_TMR_INDEX_4 This is macro DRV_TMR_INDEX_4. DRV_TMR_INDEX_5 This is macro DRV_TMR_INDEX_5. DRV_TMR_INDEX_COUNT Number of valid Timer driver indices. DRV_TMR_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported by the dynamic driver. DRV_TMR_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. Description 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-476 5.1.10.5.2.1 DRV_TMR_COUNT_WIDTH Macro C #define DRV_TMR_COUNT_WIDTH 16 Description TMR mode configuration This macro controls the mode of the Timer, and selects whether the timer is to support 8-bit, 16-bit or 32-bit mode. The acceptable values of this configuration are: • 8, (Use this for 8-bit timers) • 16 (Use this for 16-bit timers) • 32 (Use this for 32-bit timers) Remarks This is a mandatory configuration option, which enables the Timer count width. 5.1.10.5.2.2 DRV_TMR_INDEX Macro C #define DRV_TMR_INDEX DRV_TMR_INDEX_2 Description TMR Static Index Selection This definition selects the Timer Static Index for the driver object reference. Remarks This index is required to make a reference to the driver object. 5.1.10.5.2.3 DRV_TMR_INDEX_0 Macro C #define DRV_TMR_INDEX_0 0 Description Timer Driver Module Index Numbers These constants provide Timer driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_TMR_Initialize and DRV_TMR_Open functions to identify the driver instance in use. 5.1.10.5.2.4 DRV_TMR_INDEX_1 Macro C #define DRV_TMR_INDEX_1 1 Description This is macro DRV_TMR_INDEX_1. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-477 5.1.10.5.2.5 DRV_TMR_INDEX_2 Macro C #define DRV_TMR_INDEX_2 2 Description This is macro DRV_TMR_INDEX_2. 5.1.10.5.2.6 DRV_TMR_INDEX_3 Macro C #define DRV_TMR_INDEX_3 3 Description This is macro DRV_TMR_INDEX_3. 5.1.10.5.2.7 DRV_TMR_INDEX_4 Macro C #define DRV_TMR_INDEX_4 4 Description This is macro DRV_TMR_INDEX_4. 5.1.10.5.2.8 DRV_TMR_INDEX_5 Macro C #define DRV_TMR_INDEX_5 5 Description This is macro DRV_TMR_INDEX_5. 5.1.10.5.2.9 DRV_TMR_INDEX_COUNT Macro C #define DRV_TMR_INDEX_COUNT TMR_NUMBER_OF_MODULES Description Timer Driver Module Index Count This constant identifies Timer driver index definitions. Remarks This constant should be used in place of hard-coded numeric literals. This value is device-specific. 5.1.10.5.2.10 DRV_TMR_INSTANCES_NUMBER Macro C #define DRV_TMR_INSTANCES_NUMBER 1 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-478 Description Hardware instances support This definition sets up the maximum number of hardware instances that can be supported by the dynamic driver. Remarks None 5.1.10.5.2.11 DRV_TMR_INTERRUPT_MODE Macro C #define DRV_TMR_INTERRUPT_MODE true Description TMR Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of timer operation is desired • false - Select if polling mode of timer operation is desired Not defining this option to true or false will result in a build error. Remarks None. 5.1.10.5.3 Alarm Config Macros Name Description DRV_TMR_ALARM_ENABLE Enables alarm functionality. DRV_TMR_ALARM_PERIODIC Alarm type configuration. Description 5.1.10.5.3.1 DRV_TMR_ALARM_ENABLE Macro C #define DRV_TMR_ALARM_ENABLE Description Alarm feature configuration option This feature enables the alarm functionality inside the Timer driver. Remarks This is an optional feature. If the user wants to be called after a time elapse, alarm callback registration is mandatory. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-479 5.1.10.5.3.2 DRV_TMR_ALARM_PERIODIC Macro C #define DRV_TMR_ALARM_PERIODIC true Description Alarm type configuration option This macro if defined, makes the alarm periodic. This macro can accept the following values: • true - Configures the alarm in periodic mode • false - Configures the alarm in one shot mode Remarks This is an optional feature, which is enabled when using this configuration. 5.1.10.5.4 Client Config Macros Name Description DRV_TMR_CLIENTS_NUMBER Selects the maximum number of clients Description 5.1.10.5.4.1 DRV_TMR_CLIENTS_NUMBER Macro C #define DRV_TMR_CLIENTS_NUMBER 1 Description Client support This definition select the maximum number of clients that the Timer driver can support at run time. Remarks None. 5.1.10.5.5 Miscellaneous Config Macros Name Description DRV_TMR_ASYNC_WRITE_ENABLE Controls Asynchronous Write mode of the Timer. DRV_TMR_PRESCALER_ENABLE Controls prescaler assignment of the Timer. Description These configuration options control the functionality and setup of the Timer Driver. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-480 5.1.10.5.5.1 DRV_TMR_ASYNC_WRITE_ENABLE Macro C #define DRV_TMR_ASYNC_WRITE_ENABLE false Description TMR Asynchronous write mode configuration This macro controls the Asynchronous Write mode of the Timer. This macro accepts the following values: • true - Configures the Timer to enable async write control • false - Configures the Timer to disable async write control • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance. Remarks This feature is not available in all modules/devices. Refer to the specific device data sheet for more information. 5.1.10.5.5.2 DRV_TMR_PRESCALER_ENABLE Macro C #define DRV_TMR_PRESCALER_ENABLE false Description TMR prescaler assignment configuration This macro controls the prescaler assignment of the TMR. This macro accepts the following values: • true - Configures the Timer for enable prescaler assignment • false - Configures the Timer for disable prescaler assignment • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance Remarks This feature is not available in all modules/devices. Refer to the specific device data sheet for more information. 5.1.10.5.6 Alarm Functionality Examples Files Name Description drv_tmr_config_alarm.h Timer driver configuration definitions for the alarm feature. Description 5.1.10.5.6.1 drv_tmr_config_alarm.h TMR Driver Configuration Definitions for Alarm feature These definitions set up the driver for the alarm feature. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-481 File Name drv_tmr_config_alarm.h Company Microchip Technology Inc. 5.1.10.6 Building the Library This section list the files that are available in the \src of the timer driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.10.7 Library Interface Data Types and Constants Name Description DRV_TMR_ALARM_CONFIG Timer module alarm configuration. DRV_TMR_ALARM_TYPE Timer driver type enumeration. DRV_TMR_CALLBACK Pointer to a Timer driver callback function data type. DRV_TMR_CLIENT_STATUS Identifies the client-specific status of the Timer driver DRV_TMR_INIT Defines the Timer driver initialization data. DRV_TMR_SYNC_MODE Identifies the synchronous modes for the Timer driver. Macros Name Description DRV_TMR_INTERRUPT_SOURCE Defines the interrupt source of the static driver. DRV_TMR_POWER_STATE Controls the power state of the Timer. DRV_TMR_UNIFIED Sets up the driver functionlity in either split or the unified mode. Alarm Functions Name Description DRV_TMR_AlarmCountClear Clears the alarm elapse counter. DRV_TMR_AlarmCountGet Provides the number of times the alarm has elapsed since the last time it was cleared. DRV_TMR_AlarmSet Initializes an alarm. Core Functions Name Description DRV_TMR_ClientStatus Gets current client-specific status of the Timer driver. DRV_TMR_Close Closes an opened instance of the Timer driver DRV_TMR_ElapsedStatusGetAndClear Provides and clears the Timer's elapse count. DRV_TMR_Open Opens the specified Timer driver instance and returns a handle to it. DRV_TMR_Start Starts the Timer counting. DRV_TMR_Stop Stops the Timer from counting. DRV_TMR_SyncModeGet Provides the Timer's current synchronization mode. DRV_TMR_SyncModeSet Changes the Timer's synchronization mode. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-482 Counter Control Functions Name Description DRV_TMR_Counter16BitGet Provides the 16-bit Timer's current counter value. DRV_TMR_Counter16BitSet Updates the 16-bit Timer's initial count value. DRV_TMR_Counter32BitGet Provides the 32-bit Timer's current counter value. DRV_TMR_Counter32BitSet Updates the 32-bit Timer's initial count value. DRV_TMR_Counter8BitGet Provides the 8-bit Timer's current counter value. DRV_TMR_Counter8BitSet Updates the 8-bit Timer's initial count value Miscellaneous Functions Name Description DRV_TMR_OperatingFrequencyGet Provides the Timer operating frequency. DRV_TMR_TickFrequencyGet Provides the Timer's counter "tick" frequency. DRV_TMR_VersionGet Gets the Timer driver version in numerical format. DRV_TMR_VersionStrGet Gets the Timer driver version in string format. Period Functions Name Description DRV_TMR_Period16BitGet Provides the 16-bit Timer's period DRV_TMR_Period16BitSet Updates the 16-bit Timer's period. DRV_TMR_Period32BitGet Provides the 32-bit Timer's period DRV_TMR_Period32BitSet Updates the 32-bit Timer's period. DRV_TMR_Period8BitGet Provides the 8-bit Timer's period. DRV_TMR_Period8BitSet Updates the 8-bit timer's period System Interaction Functions Name Description DRV_TMR_Deinitialize Deinitializes the specified instance of the Timer driver. DRV_TMR_Initialize Initializes the Timer driver . DRV_TMR_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_TMR_Status Provides the current status of the Timer driver. DRV_TMR_Tasks Maintains the driver's state machine and implements its ISR. Description This section describes the functions of the Timer Driver Library. Refer to each section for a detailed description. 5.1.10.7.1 System Interaction Functions 5.1.10.7.1.1 DRV_TMR_Deinitialize Function C void DRV_TMR_Deinitialize( SYS_MODULE_OBJ object ); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-483 Description Deinitializes the specified instance of the Timer driver, disabling its operation (and any hardware). All internal data is invalidated. Preconditions The DRV_TMR_Initialize function must have been called before calling this function and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from DRV_TMR_Initialize Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TMR_Status operation. The system has to use DRV_TMR_Status to find out when the module is in the ready state. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize SYS_STATUS status; DRV_TMR_Deinitialize(object); status = DRV_TMR_Status(object); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.10.7.1.2 DRV_TMR_Initialize Function C SYS_MODULE_OBJ DRV_TMR_Initialize( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ); Description This function initializes the Timer driver, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This pointer may be null if the user wants to provide the information via the respective configuration macros. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-484 Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to DRV_TMR_Reinitialize, DRV_TMR_Deinitialize, DRV_TMR_Tasks and DRV_TMR_Status functions. Remarks This function must be called before any other Timer function is called. This function should only be called once during system initialization unless DRV_TMR_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_TMR_Status operation. The system must use DRV_TMR_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this function. Example DRV_TMR_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the timer initialization structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_2; init.timerPeriod = 0xABCD; // Do something objectHandle = DRV_TMR_Initialize(DRV_TMR_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.1.10.7.1.3 DRV_TMR_Reinitialize Function C void DRV_TMR_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT* const init ); Description This function reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Preconditions The DRV_TMR_Initialize function must have been called before calling this function and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from DRV_TMR_Initialize 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-485 init Pointer to the initialization data structure Returns None Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_TMR_Status operation. The system must use DRV_TMR_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this function. Example DRV_TMR_INIT init; SYS_MODULE_OBJ objectHandle; // Returned from DRV_TMR_Initialize SYS_STATUS tmrStatus; // Iopulate the timer initialization structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.syncMode = DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL; init.interruptSource = INT_SOURCE_TIMER_3; init.timerPeriod = 0xABCD; DRV_TMR_Reinitialize(objectHandle, (SYS_MODULE_INIT*)&init); tmrStatus = DRV_TMR_Status(object); if (SYS_STATUS_BUSY == tmrStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= tmrStatus) { // Handle error } 5.1.10.7.1.4 DRV_TMR_Status Function C SYS_STATUS DRV_TMR_Status( SYS_MODULE_OBJ object ); Description This function provides the current status of the Timer driver. Preconditions The DRV_TMR_Initialize functino must have been called before calling this function. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-486 Parameters Parameters Description object Driver object handle, returned from DRV_TMR_Initialize Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize SYS_STATUS tmrStatus; tmrStatus = DRV_TMR_Status(object); else if (SYS_STATUS_ERROR >= tmrStatus) { // Handle error } 5.1.10.7.1.5 DRV_TMR_Tasks Function C void DRV_TMR_Tasks( SYS_MODULE_OBJ object ); Description This function is used to maintain the driver's internal state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_TMR_Initialize function must have been called for the specified Timer driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TMR_Initialize) 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-487 Returns None Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize while (true) { DRV_TMR_Tasks (object); // Do other tasks } 5.1.10.7.2 Core Functions 5.1.10.7.2.1 DRV_TMR_ClientStatus Function C DRV_TMR_CLIENT_STATUS DRV_TMR_ClientStatus( DRV_HANDLE handle ); Description This function gets the client-specfic status of the Timer driver associated with the specified handle. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_TMR_CLIENT_STATUS value describing the current status of the driver Remarks This function will not block for hardware access and will immediately return the current status. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_CLIENT_STATUS tmrClientStatus; tmrClientStatus = DRV_TMR_ClientStatus(tmrHandle); if(DRV_TMR_CLIENT_STATUS_ERROR >= tmrClientStatus) { // Handle the error } 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-488 5.1.10.7.2.2 DRV_TMR_Close Function C void DRV_TMR_Close( DRV_HANDLE handle ); Description This function closes an opened instance of the Timer driver, invalidating the handle. Preconditions The DRV_TMR_Initialize function must have been called for the specified Timer driver instance. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver functions. A new handle must be obtained by calling DRV_TMR_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior, the call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_TMR_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Close(handle); 5.1.10.7.2.3 DRV_TMR_ElapsedStatusGetAndClear Function C bool DRV_TMR_ElapsedStatusGetAndClear( DRV_HANDLE handle ); Description This function provides the Timer's elapse count and resets it to zero (0). Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-489 Parameters Parameters Description handle A valid handle, returned from the DRV_TMR_Open Returns • true - The Timer has elapsed • false - The Timer has not yet elapsed Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open bool elapseStatus; elapseStatus = DRV_TMR_ElapsedStatusGetAndClear(handle); if (elapseStatus > 0) { // The counter period has elapsed. } 5.1.10.7.2.4 DRV_TMR_Open Function C DRV_HANDLE DRV_TMR_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); Description This function opens the specified Timer driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions The DRV_TMR_Initialize functino must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Returns If successful, the function returns a valid open instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_TMR_Close function is called. This function will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_TMR_ClientStatus operation to find out 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-490 when the module is in the ready state. If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. The Timer driver does not support DRV_IO_INTENT_SHARED. It must be opened with DRV_IO_INTENT_EXCLUSIVE in the "intent" parameter. Example DRV_HANDLE handle; handle = DRV_TMR_Open(DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.10.7.2.5 DRV_TMR_Start Function C void DRV_TMR_Start( DRV_HANDLE handle ); Description This function starts the Timer counting. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Start (handle); 5.1.10.7.2.6 DRV_TMR_Stop Function C void DRV_TMR_Stop( DRV_HANDLE handle ); Description This function stops the running Timer from counting. Preconditions The DRV_TMR_Initialize function must have been called. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-491 DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Stop(handle); 5.1.10.7.2.7 DRV_TMR_SyncModeGet Function C DRV_TMR_SYNC_MODE DRV_TMR_SyncModeGet( DRV_HANDLE handle ); Description This function provides the Timer's current synchronization mode. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns Possible values from the enumeration DRV_TMR_SYNC_MODE. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_SYNC_MODE mode; mode = DRV_TMR_SyncModeGet(handle); 5.1.10.7.2.8 DRV_TMR_SyncModeSet Function C void DRV_TMR_SyncModeSet( DRV_HANDLE handle, DRV_TMR_SYNC_MODE newMode ); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-492 Description This function changes the Timer's synchronization mode. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine mode Possible values from the enumeration DRV_TMR_SYNC_MODE Returns None. Remarks The caller should stop the Timer/Counter before changing the synchronization mode and restart it afterward. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Stop(handle); DRV_TMR_SyncModeSet(handle, DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL); 5.1.10.7.3 Alarm Functions 5.1.10.7.3.1 DRV_TMR_AlarmCountClear Function C void DRV_TMR_AlarmCountClear( DRV_HANDLE handle ); Description This function clears the alarm elapse counter. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-493 DRV_TMR_AlarmCountClear(handle); 5.1.10.7.3.2 DRV_TMR_AlarmCountGet Function C unsigned int DRV_TMR_AlarmCountGet( DRV_HANDLE handle ); Description This function provides the number of times the alarm is generated since the last time it was cleared. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open Returns Alarm count value. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open unsigned int alarmCount; alarmCount = DRV_TMR_AlarmCountGet (handle); 5.1.10.7.3.3 DRV_TMR_AlarmSet Function C void DRV_TMR_AlarmSet( DRV_HANDLE handle, const DRV_TMR_ALARM_CONFIG * config ); Description This function initializes an alarm, allowing the client to receive a callback from the driver when the counter period elapses. Alarms can be one-shot or periodic. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open config Pointer to the alarm configuration structure containing any data necessary to initialize timer alarms 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-494 Returns None Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_ALARM_CONFIG alarmConfig; alarmConfig.type = DRV_TMR_ALARM_TYPE_PERIODIC; // Periodic Alarm alarmConfig.callback = &callBackFunction; // callback registered DRV_TMR_AlarmSet(handle, config); 5.1.10.7.4 Period Functions 5.1.10.7.4.1 DRV_TMR_Period16BitGet Function C uint16_t DRV_TMR_Period16BitGet( DRV_HANDLE handle ); Description This function provides the 16-bit tTmer's period. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 16-bit timer period value Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint16_t value; value = DRV_TMR_Period16BitGet(handle); 5.1.10.7.4.2 DRV_TMR_Period16BitSet Function C void DRV_TMR_Period16BitSet( DRV_HANDLE handle, uint16_t value ); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-495 Description This function updates the 16-bit Timer's period. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 16-bit Period value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Period16BitSet(handle, 0x1000); 5.1.10.7.4.3 DRV_TMR_Period32BitGet Function C uint32_t DRV_TMR_Period32BitGet( DRV_HANDLE handle ); Description This function provides the 32-bit Timer's period. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 32-bit Timer period value. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint32_t value; value = DRV_TMR_Period32BitGet(handle); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-496 5.1.10.7.4.4 DRV_TMR_Period32BitSet Function C void DRV_TMR_Period32BitSet( DRV_HANDLE handle, uint32_t value ); Description This function updates the 32-bit Timer's period. Preconditions The DRV_TMR_Initialize unction must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 32-bit Period value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Period32BitSet(handle, 0xFFFFFFFF); 5.1.10.7.4.5 DRV_TMR_Period8BitGet Function C uint8_t DRV_TMR_Period8BitGet( DRV_HANDLE handle ); Description This function provides the 8-bit Timer's period. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 8-bit timer period value. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-497 Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint8_t value; value = DRV_TMR_Period8BitGet(handle); 5.1.10.7.4.6 DRV_TMR_Period8BitSet Function C void DRV_TMR_Period8BitSet( DRV_HANDLE handle, uint8_t value ); Description This function updates the 8-bit timer's period. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 8-bit Period value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Period8BitSet(handle, 0x10); 5.1.10.7.5 Counter Control Functions 5.1.10.7.5.1 DRV_TMR_Counter16BitGet Function C uint16_t DRV_TMR_Counter16BitGet( DRV_HANDLE handle ); Description This function provides the 16-bit Timer's current counter value. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-498 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 16-bit Timer's current counter value Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint16_t value; value = DRV_TMR_Counter16BitGet(handle); 5.1.10.7.5.2 DRV_TMR_Counter16BitSet Function C void DRV_TMR_Counter16BitSet( DRV_HANDLE handle, uint16_t value ); Description This function updates the 16-bit Timer's initial count value. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 16-bit Counter value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Counter16BitSet(handle, 0x1000); 5.1.10.7.5.3 DRV_TMR_Counter32BitGet Function C uint32_t DRV_TMR_Counter32BitGet( DRV_HANDLE handle ); Description This function provides the 32-bit Timer's current counter value. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-499 Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 32-bit Timer's current counter value. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint32_t value; value = DRV_TMR_Counter32BitGet(handle); 5.1.10.7.5.4 DRV_TMR_Counter32BitSet Function C void DRV_TMR_Counter32BitSet( DRV_HANDLE handle, uint32_t value ); Description This function updates the 32-bit Timer's initial count value. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 32-bit Counter value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Counter32BitSet(handle, 0xFFFFFFFF); 5.1.10.7.5.5 DRV_TMR_Counter8BitGet Function C uint8_t DRV_TMR_Counter8BitGet( 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-500 DRV_HANDLE handle ); Description This function provides the 8-bit Timer's current counter value. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 8-bit Timer's current counter value. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint8_t value; value = DRV_TMR_Counter8BitGet(handle); 5.1.10.7.5.6 DRV_TMR_Counter8BitSet Function C void DRV_TMR_Counter8BitSet( DRV_HANDLE handle, uint8_t value ); Description This function updates the 8-bit Timer's initial count value. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value 8-bit Counter value Returns None. Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Counter8BitSet(handle, 0x10); 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-501 5.1.10.7.6 Miscellaneous Functions 5.1.10.7.6.1 DRV_TMR_OperatingFrequencyGet Function C uint32_t DRV_TMR_OperatingFrequencyGet( DRV_HANDLE handle ); Description This function provides the Timer operating frequency. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns 32-bit value corresponding to the running frequency. Remarks On most processers, the Timer's base frequency is the same as the peripheral bus clock. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint32_t clkFreq; clkFreq = DRV_TMR_OperatingFrequencyGet(handle); 5.1.10.7.6.2 DRV_TMR_TickFrequencyGet Function C uint32_t DRV_TMR_TickFrequencyGet( DRV_HANDLE handle ); Description This function provides the Timer's counter "tick" frequency. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid handle, returned from the DRV_TMR_Open Returns Clock frequency value in cycles per second (Hertz). 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-502 Remarks None. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open uint32_t clkFreq; clkFreq = DRV_TMR_TickFrequencyGet(handle); 5.1.10.7.6.3 DRV_TMR_VersionGet Function C unsigned int DRV_TMR_VersionGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the Timer driver version. The version is encoded as major * 10000 + minor * 100 + patch. The stringed version can be obtained using DRV_TMR_VersionStrGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for Returns Current driver version in numerical format. Remarks None. Example unsigned int version; version = DRV_TMR_VersionGet( DRV_TMR_INDEX_0 ); if(version < 110200) { // Do Something } 5.1.10.7.6.4 DRV_TMR_VersionStrGet Function C char * DRV_TMR_VersionStrGet( const SYS_MODULE_INDEX drvIndex ); Description This function gets the Timer driver version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using DRV_TMR_VersionGet. Preconditions None. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-503 Parameters Parameters Description drvIndex Identifier for the object instance to get the version for Returns Current Timer driver version in the string format. Remarks None. Example char *version; version = DRV_TMR_VersionStrGet( DRV_TMR_INDEX_0 ); printf("%s", version); 5.1.10.7.7 Data Types and Constants 5.1.10.7.7.1 DRV_TMR_ALARM_CONFIG Structure C typedef struct { DRV_TMR_ALARM_TYPE type; DRV_TMR_CALLBACK callback; } DRV_TMR_ALARM_CONFIG; Description TMR Alarm configuration This data type controls the configuration of the alarm. Members Members Description DRV_TMR_ALARM_TYPE type; Type of the alarm one shot or periodic DRV_TMR_CALLBACK callback; Alarm callback Remarks Not all modes are available on all devices. 5.1.10.7.7.2 DRV_TMR_ALARM_TYPE Enumeration C typedef enum { DRV_TMR_ALARM_TYPE_ONE_SHOT, DRV_TMR_ALARM_TYPE_PERIODIC } DRV_TMR_ALARM_TYPE; Description Timer Alarm Type Enumeration This data type identifies the Timer alarm type. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-504 Members Members Description DRV_TMR_ALARM_TYPE_ONE_SHOT One Shot Alarm DRV_TMR_ALARM_TYPE_PERIODIC Periodic Alarm Remarks Not all modes are available on all devices. 5.1.10.7.7.3 DRV_TMR_CALLBACK Type C typedef void (* DRV_TMR_CALLBACK)(void); Description Timer Driver Callback Function Pointer This data type defines a pointer to a Timer driver callback function. Remarks Useful only when timer alarm callback support is enabled by defining the DRV_TMR_ALARM_ENABLE configuration option. 5.1.10.7.7.4 DRV_TMR_CLIENT_STATUS Enumeration C typedef enum { DRV_TMR_CLIENT_STATUS_INVALID, DRV_TMR_CLIENT_STATUS_ERROR, DRV_TMR_CLIENT_STATUS_BUSY, DRV_TMR_CLIENT_STATUS_READY, DRV_TMR_CLIENT_STATUS_STOPPED, DRV_TMR_CLIENT_STATUS_STARTED } DRV_TMR_CLIENT_STATUS; Description Timer Driver Client Status This enumeration identifies the client-specific status of the Timer driver. Members Members Description DRV_TMR_CLIENT_STATUS_INVALID Client in an invalid (or unopened) state DRV_TMR_CLIENT_STATUS_ERROR Unspecified error condition DRV_TMR_CLIENT_STATUS_BUSY An operation is currently in progress DRV_TMR_CLIENT_STATUS_READY Up and running, no operations running DRV_TMR_CLIENT_STATUS_STOPPED Timer stopped (not running), but ready to accept commands DRV_TMR_CLIENT_STATUS_STARTED Timer started and running, processing transactions Remarks None. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-505 5.1.10.7.7.5 DRV_TMR_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; TMR_MODULE_ID tmrId; TMR_CLOCK_SOURCE clockSource; uint32_t timerPeriod; TMR_PRESCALE prescale; TMR_CLOCK_SOURCE_EDGE sourceEdge; uint8_t postscale; DRV_TMR_SYNC_MODE syncMode; INT_SOURCE interruptSource; } DRV_TMR_INIT; Description Timer Driver Initialize Data This data type defines data required to initialize or reinitialize the Timer driver. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization TMR_MODULE_ID tmrId; Identifies timer hardware module (PLIB-level) ID TMR_CLOCK_SOURCE clockSource; Clock Source select enumeration uint32_t timerPeriod; Timer Period Value TMR_PRESCALE prescale; Prescaler Selection from the processor enumeration TMR_CLOCK_SOURCE_EDGE sourceEdge; TMR Source Edge Selection uint8_t postscale; Post Scale Selection DRV_TMR_SYNC_MODE syncMode; Timer Sync Mode INT_SOURCE interruptSource; Interrupt Source for TMR module Remarks Not all initialization features are available on all devices. 5.1.10.7.7.6 DRV_TMR_SYNC_MODE Enumeration C typedef enum { DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL, DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL_GATED, DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC, DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITH_CLKSYNC, DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC, DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITH_CLKSYNC, DRV_TMR_SYNC_MODE_IDLE } DRV_TMR_SYNC_MODE; Description Timer Synchronous Modes This data type identifies the synchronous modes for the Timer driver. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-506 Members Members Description DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL Synchronous Internal Clock Counter DRV_TMR_SYNC_MODE_SYNCHRONOUS_INTERNAL_GATED Synchronous Internal Gated Counter DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC Synchronous External Clock Counter DRV_TMR_SYNC_MODE_SYNCHRONOUS_EXTERNAL_WITH_CLKSYNC Synchronous External Clock Counter DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITHOUT_CLKSYNC Asynchronous External Clock Counter DRV_TMR_SYNC_MODE_ASYNCHRONOUS_EXTERNAL_WITH_CLKSYNC Asynchronous External Clock Counter DRV_TMR_SYNC_MODE_IDLE Timer Idle Mode Remarks Not all modes are available on all devices. 5.1.10.7.8 Macros 5.1.10.7.8.1 DRV_TMR_INTERRUPT_SOURCE Macro C #define DRV_TMR_INTERRUPT_SOURCE INT_SOURCE_TIMER_1 Description TMR Interrupt Source This macro defines the interrupt source of the static driver. Remarks Refer to the Interrupt Peripheral Library documentation for more information on the INT_SOURCE enumeration. 5.1.10.7.8.2 DRV_TMR_POWER_STATE Macro C #define DRV_TMR_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description TMR power state configuration This macro controls the power state of the Timer. Remarks This feature is not available in all modules/devices. Refer to the specific device data sheet for more information. 5.1.10.7.8.3 DRV_TMR_UNIFIED Macro C #define DRV_TMR_UNIFIED false Description TMR driver configuration This definition sts up the driver functionlity in either split or the unified mode. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-507 Remarks None. 5.1.10.8 Files Files Name Description drv_tmr.h Timer device driver interface header. drv_tmr_config_template.h Timer driver configuration definitions for the template version. Description 5.1.10.8.1 drv_tmr.h Timer Device Driver Interface Definition This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Timer device driver. Enumerations Name Description DRV_TMR_ALARM_TYPE Timer driver type enumeration. DRV_TMR_CLIENT_STATUS Identifies the client-specific status of the Timer driver DRV_TMR_SYNC_MODE Identifies the synchronous modes for the Timer driver. Functions Name Description DRV_TMR_AlarmCountClear Clears the alarm elapse counter. DRV_TMR_AlarmCountGet Provides the number of times the alarm has elapsed since the last time it was cleared. DRV_TMR_AlarmSet Initializes an alarm. DRV_TMR_ClientStatus Gets current client-specific status of the Timer driver. DRV_TMR_Close Closes an opened instance of the Timer driver DRV_TMR_Counter16BitGet Provides the 16-bit Timer's current counter value. DRV_TMR_Counter16BitSet Updates the 16-bit Timer's initial count value. DRV_TMR_Counter32BitGet Provides the 32-bit Timer's current counter value. DRV_TMR_Counter32BitSet Updates the 32-bit Timer's initial count value. DRV_TMR_Counter8BitGet Provides the 8-bit Timer's current counter value. DRV_TMR_Counter8BitSet Updates the 8-bit Timer's initial count value DRV_TMR_Deinitialize Deinitializes the specified instance of the Timer driver. DRV_TMR_ElapsedStatusGetAndClear Provides and clears the Timer's elapse count. DRV_TMR_Initialize Initializes the Timer driver . DRV_TMR_Open Opens the specified Timer driver instance and returns a handle to it. DRV_TMR_OperatingFrequencyGet Provides the Timer operating frequency. DRV_TMR_Period16BitGet Provides the 16-bit Timer's period 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-508 DRV_TMR_Period16BitSet Updates the 16-bit Timer's period. DRV_TMR_Period32BitGet Provides the 32-bit Timer's period DRV_TMR_Period32BitSet Updates the 32-bit Timer's period. DRV_TMR_Period8BitGet Provides the 8-bit Timer's period. DRV_TMR_Period8BitSet Updates the 8-bit timer's period DRV_TMR_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_TMR_Start Starts the Timer counting. DRV_TMR_Status Provides the current status of the Timer driver. DRV_TMR_Stop Stops the Timer from counting. DRV_TMR_SyncModeGet Provides the Timer's current synchronization mode. DRV_TMR_SyncModeSet Changes the Timer's synchronization mode. DRV_TMR_Tasks Maintains the driver's state machine and implements its ISR. DRV_TMR_TickFrequencyGet Provides the Timer's counter "tick" frequency. DRV_TMR_VersionGet Gets the Timer driver version in numerical format. DRV_TMR_VersionStrGet Gets the Timer driver version in string format. Macros Name Description DRV_TMR_INDEX_0 Timer driver index definitions DRV_TMR_INDEX_1 This is macro DRV_TMR_INDEX_1. DRV_TMR_INDEX_2 This is macro DRV_TMR_INDEX_2. DRV_TMR_INDEX_3 This is macro DRV_TMR_INDEX_3. DRV_TMR_INDEX_4 This is macro DRV_TMR_INDEX_4. DRV_TMR_INDEX_5 This is macro DRV_TMR_INDEX_5. DRV_TMR_INDEX_COUNT Number of valid Timer driver indices. Structures Name Description DRV_TMR_ALARM_CONFIG Timer module alarm configuration. DRV_TMR_INIT Defines the Timer driver initialization data. Types Name Description DRV_TMR_CALLBACK Pointer to a Timer driver callback function data type. File Name drv_tmr.h Company Microchip Technology Inc. 5.1.10.8.2 drv_tmr_config_template.h Timer Driver Configuration Definitions for the Template Version These definitions set up the driver for the default mode of operation of the driver. 5.1 Driver Library Help MPLAB Harmony Help Timer Driver Library 5-509 Macros Name Description DRV_TMR_ALARM_ENABLE Enables alarm functionality. DRV_TMR_ALARM_PERIODIC Alarm type configuration. DRV_TMR_ASYNC_WRITE_ENABLE Controls Asynchronous Write mode of the Timer. DRV_TMR_CLIENTS_NUMBER Selects the maximum number of clients DRV_TMR_CLOCK_SOURCE Timer module clock source selection. DRV_TMR_COUNT_WIDTH Controls the mode of the Timer. DRV_TMR_INDEX Timer static index selection. DRV_TMR_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported by the dynamic driver. DRV_TMR_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_TMR_INTERRUPT_SOURCE Defines the interrupt source of the static driver. DRV_TMR_PERIPHERAL_ID Timer peripheral ID selection. DRV_TMR_POSTSCALE Macro controls post scale of the TMR DRV_TMR_POWER_STATE Controls the power state of the Timer. DRV_TMR_PRESCALE Timer module prescale value. DRV_TMR_PRESCALER_ENABLE Controls prescaler assignment of the Timer. DRV_TMR_SOURCE_EDGE Timer module source edge. DRV_TMR_SYNCHRONIZATION_MODE Controls Synchronization mode of the Timer. DRV_TMR_TIMER_PERIOD Timer period value for an overflow or a period match-based Timer. DRV_TMR_UNIFIED Sets up the driver functionlity in either split or the unified mode. File Name drv_tmr_config_template.h Company Microchip Technology Inc. 5.1.11 USART Driver Library 5.1.11.1 Introduction USART Driver Library for Microchip Microcontrollers This library provides an interface to manage the USART module on Microchip family of micro controllers in different modes of operation. Overview of USART The Universal Synchronous Asynchronous Receiver/Transmitter (USART) controller is the key component of the serial 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-510 communications subsystem of many embedded systems. The USART driver can support following modes of operation. (Refer to the Device Specific data sheet to determine which modes are supported on the part being used.) 1. RS232 RS232 is an asynchronous full duplex serial communication protocol. It uses separate lines for transmitting and receiving data, point-to-point, between a Data Terminal Equipment (DTE) item and a Data Communication Equipment (DCE) item at a maximum speed of 20 kbps with a maximum cable length of 50 feet. 2. RS485 RS485 is a multi-point communications network. It provides bi-directional, half-duplex, data transmission that allows multiple receivers and drivers in "bus" configurations. The standard specifies up to 32 drivers and 32 receivers on a single (2-wire) bus. With the introduction of "automatic" repeaters and high-impedance drivers and receivers this "limitation" can be extended to hundreds (or even thousands) of nodes on a network. 3. IrDA Some Microchip micro controllers provide an Infrared (IR) encoder and decoder and can also interface with external IR encoders and decoders. 4. Interdevice Communication USART module can be used for communication(without any external transceiver) between two devices. The maximum communication speed in this case is determined by the maximum Baud supported by the device. 5. Synchronous Master/Slave Synchronous serial transmission requires that the sender and receiver share a clock with one another or that the sender provide a strobe or other timing signal so that the receiver knows when to latch the next bit of the data. It is typically used in systems with a single master and one or more slaves. The master device contains the necessary circuitry for baud rate generation and supplies the clock for all devices in the system. Note: if a USART does not support a synchronous mode, it is called UART. However, UARTs are still controlled by the USART driver. 5.1.11.2 Release Notes MPLAB Harmony Version: v0.70b USART Driver Library Version : 0.050b Alpha Release Date: 18Nov2013 New This Release: The USART Driver supports the following modes of operation. Modes of operation • Polling Mode • Interrupt Mode Configuration modes • Asynchronous Transmit & Receive(i.e. RS232, RS485) • IrDA Mode • Loop Back Mode 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-511 Handshake modes • Flow Control Mode • No Handshake Mode Line Control modes • 8 bit, No Parity, 1 stop bit Mode • 9 bit, No Parity, 1 stop bit Mode • 8 bit, Even Parity, 1 stop bit Mode • 8 bit, Even Parity, 2 stop bits Mode • 8 bit, Odd Parity, 1 stop bit Mode • 8 bit, Odd Parity, 2 stop bits Mode Interrupt Modes • Wakeup On Start Enable • Auto Baud enable Following demo shows how to use USART Driver • usart_echo (\apps\driver\usart\drv_usart_demo) Known Issues: The following are the known issues in this release. • Although implementation exists, the driver doesn’t work in the following line control modes: • 8 bit, Even Parity, 1 stop bit Mode • 8 bit, Even Parity, 2 stop bits Mode • 8 bit, Odd Parity, 1 stop bit Mode • 8 bit, Odd Parity, 2 stop bits Mode • Deinitialize API of the driver doesn’t work. This means that the application cannot initialize the driver after deinitializing it. • When UART driver is configured for 115200 baud rate, there could be no data received or received data is corrupted • More than one client is not supported • The USART Driver does not support “Odd” and “Even” parity settings 5.1.11.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-512 paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.11.4 Using the Library This topic describes the basic architecture of the USART Driver Library and provides information and examples on how to use it. Interface Header File: drv_usart.h The interface to the USART library is defined in the "drv_usart.h" header file Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.11.4.1 Abstraction Model Different types of USARTs are available on Microchip microcontrollers. Some have a FIFO and some do not. The FIFO depth varies across part families. The USART driver abstracts out these differences and provides a unified model for data transfer across different types of USARTS available. Both transmitter and receiver provide a buffer in the driver which transmits and receives data to/from the hardware. The USART driver provides a set of interfaces to perform the read and the write. The diagrams below illustrates the model used by the USART driver for transmitter and receiver. Receiver Abstraction Model Transmitter Abstraction Model 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-513 5.1.11.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The table below lists the interface section and its brief description. Library Interface Section Description Data Types and Constants Provides macros for configuring the system. It is required that the system configures the driver to build correctly by choosing appropriate configuration options as listed in this section. System Initialization Functions Provides system module interfaces, Device initialization, de-initialization, re-initialization and status functions. Setup and Status Functions Provides open, close and other setup functions Data Transfer Functions Provides data transfer functions available in the core configuration 5.1.11.4.3 How the Library Works The library provides interfaces to support: • System Interaction • Client Core Functionality 5.1.11.4.3.1 System Initialization System Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or re-initialized. During system initialization each instance of the USART device will be initialized with the following configuration settings (either passed dynamically at run time using DRV_USART_INIT or by using Initialization Overrides) that are supported by the specific USART device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to the Data Types section in this guide • The actual peripheral ID enumerated as the PLIB level module ID. e.g USART_ID_2. • Operation Mode: Select the operation mode of the instance using one of the possible values from DRV_USART_OPERATION_MODES. Make sure that the operation mode support is enabled in the driver configuration setup. Also for RS485 operation mode, select the address to which the module instance should respond to. • Line Control Mode: Setup the line control mode using one of the possible values from 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-514 DRV_USART_LINE_CONTROL_MODES • Baud Rate Setup: Setup the baud rate by either providing the baud rate value or enabling the auto baud setup. • Configuration of the RS485 mode if enabled. • Enabling the handshake signals.e.g. Simplex, FlowControl. For specifics please refer the Data Types section in this guide. • Defining the respective interrupt sources for Tx, Rx, and Error Interrupt. The DRV_USART_Initialize API returns an object handle of the type SYS_MODULE_OBJ. There on, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_USART_Reinitialize, DRV_USART_Deinitialize, DRV_USART_Status and DRV_USART_TasksTX, DRV_USART_TasksRX. Note:The system initialization and the re-initialization settings, only effect the instance of the peripheral that is being initialized or re-initialized. Example: DRV_USART_INIT usartInitData; //Alternatively NULL can be passed to Initialize which then //makes sure that static overrides as selected by the user //will be used as default values SYS_MODULE_OBJ objectHandle; usartInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; usartInitData.moduleId = USART_ID_2; usartInitData.operationMode = DRV_USART_OPERATION_MODE_RS232; usartInitData.initFlags = 0; usartInitData.lineControlMode = DRV_USART_LINE_CONTROL_MODE_8NONE1; usartInitData.brgClock = 4000000; usartInitData.brgValue = 9600; usartInitData.operationModeInit = 0; usartInitData.handShakeMode = DRV_USART_HANDSHAKE_MODE_FLOWCONTROL; usartInitData.txInterruptSource = INT_SOURCE_USART_2_TRANSMIT; usartInitData.rxInterruptSource = INT_SOURCE_USART_2_RECEIVE; usartInitData.errorInterruptSource = INT_SOURCE_USART_2_ERROR; usartInitData.txQueueSize = 3; usartInitData.rxQueueSize = 3; objectHandle = DRV_USART_Initialize(DRV_USART_INDEX_1, (SYS_MODULE_INIT*)usartInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will either call DRV_USART_TasksTX, DRV_USART_TasksRX, from System Task Service (in a polled environment) or DRV_USART_TasksTX, DRV_USART_TasksRX will be called from interrupt service routine of the USART. 5.1.11.4.3.2 Core Functionality Core functionality provides a extremely basic interface for the driver operation. Core Transmitter Functionality Application using the USART core functionality, needs to perform the following: 1. The system should have completed necessary initialization and the DRV_USART_TasksTX should either be running in polled environment, or in an interrupt environment. 2. Open the driver using DRV_USART_Open, timer driver supports exclusive access only. 3. Write a byte using DRV_USART_WriteByte. 4. The client will be able to close itself using the DRV_USART_Close when required. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-515 Example : DRV_HANDLE handle; // Returned from DRV_USART_Open bool status; // Pre-initialize myBuffer with MY_BUFFER_SIZE bytes of valid data. status = DRV_USART_WriteByte(handle, myBuffer[numBytes++]); // Do something else... } Core Receiver Functionality Application using the USART core functionality, needs to perform the following: 1. The system should have completed necessary initialization and the DRV_USART_TasksRX should either be running in polled environment, or in an interrupt environment. 2. Open the driver using DRV_USART_Open, timer driver supports exclusive access only. 3. Write a byte using DRV_USART_ReadByte. 4. The client will be able to close itself using the DRV_USART_Close when required. Example : DRV_HANDLE handle; // Returned from DRV_USART_Open bool status; char byte; bool = DRV_USART_ReadByte(handle, &byte); // Do something else... 5.1.11.4.3.3 Client Access For the application to start using an instance of the module, it must call the DRV_USART_Open function. This provides the configuration required to open the USART instance for operation. If the driver is de-initialized using the function DRV_USART_Deinitialize, the application must call the DRV_USART_Open function again to setup the instance of the USART. The function DRV_USART_Open need not be called again if the system is re-initialized using the DRV_USART_Reinitialize function. //This i have to mod For the various options available for I/O INTENT please refer to the Data Types and Constants section. Example: DRV_HANDLE handle; handle = DRV_USART_Open(DRV_USART_INDEX_1, DRV_IOINTENT_READWRITE);// Configure the instance USART_ID_1 with the above configuration if(handle == DRV_HANDLE_INVALID) { // Client cannot open the instance. } 5.1.11.4.3.4 Data Transfer In the basic data transfer mode, the USART device driver allows the client to perform simple read or write operation on the USART. The client (who is this) has to provide a buffer where the transfer data is/will be stored. Example : Read in the RS-232 mode 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-516 // USART is operating in RS-232 Mode // Assume that DRV_USART_Open operation was called with DRV_IO_INTENT_NONBLOCKING parameter char myBuffer[MY_BUFFER_SIZE]; size_t total; size_t count; DRV_HANDLE drvHandle; // device handle obtained by a call to DRV_USART_Open // Start the transfer total = 0; do { count = DRV_USART_Read(drvHandle, myBuffer, MY_BUFFER_SIZE - total); total += count; // Do something else... } while(total < MY_BUFFER_SIZE); Example : Write in the RS-485 mode // USART is operating in RS-485 Mode // Assume that DRV_USART_Open operation was called with DRV_IO_INTENT_NONBLOCKING parameter char myBuffer[MY_BUFFER_SIZE]; size_t total; size_t count; DRV_HANDLE drvHandle; // device handle obtained by a call to DRV_USART_Open // Start the transfer total = 0; do { count = DRV_USART_WriteToAddress(drvHandle, 0x07, myBuffer, MY_BUFFER_SIZE - total); // Write the string "writestring" to the communications channel total += count; // Do something else... } while(total < MY_BUFFER_SIZE); 5.1.11.4.3.5 Advanced Data Transfer USART device client transfer is composed if various buffers that are queued internally by the driver. Each buffer is described by a buffer descriptor which contains the transfer buffer, size and an address Each buffer has associated flags that specify the behavior that the device driver has to take once that particular segment reaches a particular stage of processing. The client can add segments to the transfer by using DRV_USART_BufferAdd for adding the Read and write buffers. The client can query the status of the buffer using the function DRV_USART_BufferStatus and also can query how many bytes of the buffer are read or written if the buffer is in progress using the function DRV_USART_BufferTransferStatus. The diagram below illustrates the buffer model used by the advanced data transfer. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-517 Example: void Callback(void); uint8_t mybuffer[MY_BUFFER_SIZE]; uint8_t bytesWritten = 0; DRV_BUFFER_HANDLE bufferHandle = NULL; DRV_USART_IO_BUFFER buffer1; void Callback(void) { Nop(); } buffer1.buffer = writeBuffer2; buffer1.bufferSize = sizeof(writeBuffer2); buffer1.xferCallback = Callback; buffer1.flags = DRV_USART_BUFFER_FLAG_WRITE; // myUSARTHandle is the handle returned by the DRV_USART_Open function. bufferHandle = DRV_USART_BufferAdd(myUSARThandle, &buffer1); bufferStatus = DRV_USART_BufferStatus ( uartHandle, uartBufferHandle ); if ( DRV_USART_BUFFER_COMPLETED == bufferStatus ) { // Handle Buffer Complete }else { // Handle other } Example: void Callback(void); uint8_t mybuffer[MY_BUFFER_SIZE]; uint8_t bytesWritten = 0; DRV_BUFFER_HANDLE bufferHandle = NULL; DRV_USART_IO_BUFFER buffer1; void Callback(void) { Nop(); } buffer1.buffer = readBuffer2; buffer1.bufferSize = sizeof(readBuffer2); buffer1.xferCallback = Callback; buffer1.flags = DRV_USART_BUFFER_FLAG_READ; 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-518 // myUSARTHandle is the handle returned by the DRV_USART_Open function. bufferHandle = DRV_USART_BufferAdd(myUSARThandle, &buffer1); bufferStatus = DRV_USART_BufferStatus ( uartHandle, uartBufferHandle ); if ( DRV_USART_BUFFER_COMPLETED == bufferStatus ) { // Handle Buffer Complete }else { // Handle other } 5.1.11.5 Configuring the Library The configuration of the USART device driver is based on the file sys_config.h This header file contains the configuration selection for the USART device driver build. Based on the selections made here and the system setup the USART device driver will support or not selected features. These configuration settings will apply to all instances of the device driver. This header can be placed anywhere in the application specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Overview section for more details. Initialization overrides not supported in this version. 5.1.11.6 Building the Library This section list the files that are available in the \src of the timer driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.11.7 Library Interface Data Types and Constants Name Description DRV_USART_AUTO_BAUD_ENABLE Macro configures enabling the auto baud. DRV_USART_BAUD_RATE Macro controls operation of the driver for Baud rate configuration DRV_USART_BYTE_Q_SIZE_RX Macro controls operation of the driver for defining the size of the Rx buffer DRV_USART_BYTE_Q_SIZE_TX Macro controls operation of the driver for defining the size of the Tx buffer DRV_USART_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_USART_HANDSHAKE_MODE Configures the handshake mode DRV_USART_INDEX USART Static Index selection DRV_USART_INDEX_0 USART driver index definitions DRV_USART_INDEX_1 This is macro DRV_USART_INDEX_1. DRV_USART_INDEX_2 This is macro DRV_USART_INDEX_2. DRV_USART_INDEX_3 This is macro DRV_USART_INDEX_3. DRV_USART_INDEX_4 This is macro DRV_USART_INDEX_4. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-519 DRV_USART_INDEX_5 This is macro DRV_USART_INDEX_5. DRV_USART_INDEX_COUNT Number of valid USART driver indices DRV_USART_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_USART_INTERRUPT_MODE Macro controls operation of the driver in the interrupt mode DRV_USART_INTERRUPT_SOURCE_ERROR Defines the interrupt source for the error interrupt DRV_USART_INTERRUPT_SOURCE_RX Macro to define the Rx interrupt source in case of static driver DRV_USART_INTERRUPT_SOURCE_TX Macro to define the Tx interrupt source in case of static driver DRV_USART_LINE_CONTROL Macro defines the line control mode DRV_USART_OPERATION_MODE Defines the mode to be used for the USART driver DRV_USART_PERIPHERAL_ID Configures the PLIB id DRV_USART_POLARITY_INVERTED_RX Defines the polarity of the RX pin. DRV_USART_POLARITY_INVERTED_TX Defines the polarity of the TX pin. DRV_USART_POWER_STATE Macro controls power state of the USART DRV_USART_WAKE_ON_START_ENABLE Macro configures that the peripheral should wake up on start DRV_USART_XFER_BUFFER_NUMBER Transfer buffer depth DRV_USART_BUFFER_FLAGS Defines the IO types that can be serviced by the USART driver DRV_USART_BUFFER_STATUS Defines the buffer status DRV_USART_CALLBACK Pointer to a USART callback function DRV_USART_CLIENT_STATUS Defines the client status DRV_USART_HANDSHAKE_MODES Identifies the handshaking modes available on the USART DRV_USART_INIT Defines the data required to initialize or reinitialize the USART driver DRV_USART_INIT_FLAGS Defines specific initialization features DRV_USART_IO_BUFFER IO buffer information structure DRV_USART_LINE_CONTROL_MODES Identifies the line control modes available DRV_USART_OPERATION_MODE_INIT Defines the initialization data required for different operation modes of USART DRV_USART_OPERATION_MODES Identifies the modes of the operation of the USART module DRV_USART_TRANSFER_STATUS Specifies the status of the receive or transmit DRV_USART_XFER_HANDLE Handle for requested transfer.. Data Transfer Functions Name Description DRV_USART_BufferAdd Starts the writes to the communication channel. DRV_USART_BufferStatus Provides the status of the given buffer DRV_USART_Read Reads data from the USART DRV_USART_ReadByte Reads a byte of data from the USART DRV_USART_TransferStatus Returns the transmitter and receiver transfer status DRV_USART_Write Writes data to the USART DRV_USART_WriteByte Writes a byte of data to the USART Setup and Status Functions Name Description DRV_USART_BufferTransferStatus Gets the number of bytes which are written or read DRV_USART_ClientStatus Gets current client-specific status the USART driver DRV_USART_Close Closes an opened-instance of the USART driver 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-520 DRV_USART_Open Opens the specified timer driver instance and returns a handle to it DRV_USART_Status Gets the current status of the USART driver module. System Initialization Functions Name Description DRV_USART_Deinitialize Deinitializes the specified instance of the USART driver module DRV_USART_Initialize Initializes the USART instance for the specified driver index DRV_USART_Reinitialize Reinitializes the USART driver and refreshes any associated hardware settings DRV_USART_TasksError Maintains the driver's error-handling state machine and implements its ISR DRV_USART_TasksRX Maintains the driver's receiver state machine and implements its ISR DRV_USART_TasksTX Maintains the driver's tramsmitter state machine and implements its ISR Description This section describes the functions of the USART Driver Library. Refer to each section for a detailed description. 5.1.11.7.1 System Initialization Functions 5.1.11.7.1.1 DRV_USART_Deinitialize Function C void DRV_USART_Deinitialize( SYS_MODULE_OBJ object ); Description Deinitializes the specified instance of the USART driver module, disabling its operation (and any hardware). Invalidates all the internal data. Preconditions Function DRV_USART_Initialize should have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from the DRV_USART_Initialize routine Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_USART_Status operation. The system has to use DRV_USART_Status to find out when the module is in the ready state. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize SYS_STATUS status; 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-521 DRV_USART_Deinitialize(object); status = DRV_USART_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } 5.1.11.7.1.2 DRV_USART_Initialize Function C SYS_MODULE_OBJ DRV_USART_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Description This routine initializes the USART driver instance for the specified driver index, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the drivver. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Remarks This routine must be called before any other USART routine is called. This routine should only be called once during system initialization unless DRV_USART_Deinitialize is called to de-initialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_USART_Status operation. The system must use DRV_USART_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this routine. Example DRV_USART_INIT usartInitData; //Alternatively NULL can be passed to Initialize which then //makes sure that static overrides as selected by the user //will be used as default values SYS_MODULE_OBJ objectHandle; usartInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; usartInitData.moduleId = USART_ID_2; usartInitData.operationMode = DRV_USART_OPERATION_MODE_RS232; usartInitData.initFlags = 0; usartInitData.lineControlMode = DRV_USART_LINE_CONTROL_MODE_8NONE1; usartInitData.brgClock = 4000000; 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-522 usartInitData.brgValue = 9600; usartInitData.operationModeInit = 0; usartInitData.handShakeMode = DRV_USART_HANDSHAKE_MODE_FLOWCONTROL; usartInitData.txInterruptSource = INT_SOURCE_USART_2_TRANSMIT; usartInitData.rxInterruptSource = INT_SOURCE_USART_2_RECEIVE; usartInitData.errorInterruptSource = INT_SOURCE_USART_2_ERROR; usartInitData.txQueueSize = 3; usartInitData.rxQueueSize = 3; objectHandle = DRV_USART_Initialize(DRV_USART_INDEX_1, (SYS_MODULE_INIT*)usartInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.1.11.7.1.3 DRV_USART_Reinitialize Function C void DRV_USART_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); Description This routine reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Preconditions Function DRV_USART_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object Driver object handle, returned from the DRV_USART_Initialize routine init Pointer to the initialization data structure Returns None. Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_USART_Status operation. The system must use DRV_USART_Status to find out when the driver is in the ready state. Build configuration options may be used to staticaly override options in the "init" sructure and will take precedance over initialization data passed using this routine. Example DRV_USART_INIT usartInitData; //Alternatively NULL can be passed to Initialize which then //makes sure that static overrides as selected by the user //will be used as default values SYS_STATUS usartStatus; 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-523 SYS_MODULE_OBJ object; usartInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; usartInitData.moduleId = USART_ID_2; usartInitData.operationMode = DRV_USART_OPERATION_MODE_RS232; usartInitData.initFlags = 0; usartInitData.lineControlMode = DRV_USART_LINE_CONTROL_MODE_8NONE1; usartInitData.brgClock = 4000000; usartInitData.brgValue = 9600; usartInitData.operationModeInit = 0; usartInitData.handShakeMode = DRV_USART_HANDSHAKE_MODE_FLOWCONTROL; usartInitData.txInterruptSource = INT_SOURCE_USART_2_TRANSMIT; usartInitData.rxInterruptSource = INT_SOURCE_USART_2_RECEIVE; usartInitData.errorInterruptSource = INT_SOURCE_USART_2_ERROR; DRV_USART_Reinitialize(object, (SYS_MODULE_INIT*)usartInitData); usartStatus = DRV_USART_Status(object); if (SYS_STATUS_BUSY == usartStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= usartStatus) { // Handle error } 5.1.11.7.1.4 DRV_USART_TasksError Function C void DRV_USART_TasksError( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal error-handling state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Returns None. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. This routine may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksError (object); 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-524 // Do other tasks } 5.1.11.7.1.5 DRV_USART_TasksRX Function C void DRV_USART_TasksRX( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal receiver state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Returns None. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. This routine may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksRX (object); // Do other tasks } 5.1.11.7.1.6 DRV_USART_TasksTX Function C void DRV_USART_TasksTX( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal transmitter state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-525 Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Returns None. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. This routine may excute in an ISR context and will never block or access any resources that may cause it to block. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksTX (object); // Do other tasks } 5.1.11.7.2 Data Transfer Functions 5.1.11.7.2.1 DRV_USART_BufferAdd Function C DRV_HANDLE DRV_USART_BufferAdd( const DRV_HANDLE handle, DRV_USART_IO_BUFFER * bufferObject ); Description Starts the writes to the communication channel. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Parameters Parameters Description handle Handle of the communication channel as return by the DRV_USART_Open function. bufferObject Buffer Object that needs to be specified for the buffer that needs to be read or written. Returns The buffer handle, which should be used to query how many bytes have been written or read using the function 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-526 DRV_USART_OperationStatus Remarks If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior in an OS environment the call will block until the operation is complete. For DRV_IO_INTENT_NONBLOCKING request the driver client can call the DRV_USART_ClientStatus operation to find out when the module is in the ready state. In any circumstance, the client supplied buffer has to be non-volatile and it is not allowed to go out of scope until the operation completes. Affected by the following configuration options: • DRV_USART_CONFIG_SUPPORT_CLIENT_ACCESS_BLOCKING • DRV_USART_CONFIG_BUFFER_QUEUE_SLOTS_MAX • DRV_USART_CONFIG_SUPPORT_BUFFERQ Example void Callback(void); uint8_t mybuffer[MY_BUFFER_SIZE]; int8_t bytesWritten = 0; DRV_BUFFER_HANDLE bufferHandle = NULL; DRV_USART_IO_BUFFER buffer1; void Callback(void) { Nop(); } buffer1.buffer = writeBuffer2; buffer1.bufferSize = sizeof(writeBuffer2); buffer1.xferCallback = Callback; buffer1.flags = DRV_USART_BUFFER_FLAG_WRITE; // myUSARTHandle is the handle returned by the DRV_USART_Open function. bufferHandle = DRV_USART_BufferAdd(myUSARThandle, &buffer1); while(bytesWritten < MY_BUFFER_SIZE) { bytesWritten = DRV_USART_BufferTransferStatus(handle, bufferHandle); } 5.1.11.7.2.2 DRV_USART_BufferStatus Function C DRV_USART_BUFFER_STATUS DRV_USART_BufferStatus( DRV_HANDLE handle, const DRV_HANDLE bufferHandle ); Description This function provides the current status of the buffer identified by the given buffer handle. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-527 DRV_USART_Open call. The "bufferHandle parameter must be the return value from a call to the "DRV_USART_BufferAdd" function. Parameters Parameters Description handle Handle of the communication channel as return by the DRV_USART_Open function. bufferHandle Handle to the buffer in question. Must be the return value from a call to the "DRV_USART_BufferAdd" function. Returns The current status of the given buffer. Remarks See the definition of "DRV_USART_BUFFER_STATUS" for a complete description of all possible status values. Example DRV_USART_BUFFER_STATUS bufferStatus; bufferStatus = DRV_USART_BufferStatus ( uartHandle, uartBufferHandle ); if ( DRV_USART_BUFFER_COMPLETED == bufferStatus ) { // Handle Buffer Complete }else { // Handle other } 5.1.11.7.2.3 DRV_USART_Read Function C int DRV_USART_Read( const DRV_HANDLE handle, uint8_t * buffer, const unsigned int numbytes ); Description This routine reads data from the USART. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer into which the data read from the USART instance will be placed. numbytes Total number of bytes that need to be read from the module instance (must be equal to or less than the size of the buffer) Returns Number of bytes actually copied into the caller's buffer or -1 if there is an error (call DRV_USART_ClientStatus to identify the error). 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-528 Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_USART_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_USART_Open routine or the driver was built to only support non-blocking behavior the call will return immediately, identifying how many bytes of data were actually copied into the client's buffer and the client must call DRV_USART_Read again with adjusted parameters as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int count; unsigned int total; total = 0; do { count = DRV_USART_Read(myUSARTHandle, &myBuffer[total], MY_BUFFER_SIZE - total); total += count; // Do something else... } while( total < MY_BUFFER_SIZE ); 5.1.11.7.2.4 DRV_USART_ReadByte Function C bool DRV_USART_ReadByte( const DRV_HANDLE handle, char * byte ); Description This routine reads a byte of data from the USART. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine byte A variable in which data is read into Returns true - Read successful false - Read failed Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_USART_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_USART_Open routine or the driver was built to only support non-blocking behavior the call will return immediately. If data is not available, a zero (0) value will be returned and an underrun error status will be captured. To ensure that valid data is returned, the caller must first check the return value to DRV_USART_TransferStatus as shown in the example. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-529 Example DRV_HANDLE handle; // Returned from DRV_USART_Open bool status; char byte; bool = DRV_USART_ReadByte(handle, &byte); // Do something else... 5.1.11.7.2.5 DRV_USART_TransferStatus Function C DRV_USART_TRANSFER_STATUS DRV_USART_TransferStatus( const DRV_HANDLE handle ); Description This returns the transmitter and receiver transfer status. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_USART_TRANSFER_STATUS value describing the current status of the transfer. Remarks The returned status may contain a value with more than one of the bits specified in the DRV_USART_TRANSFER_STATUS enumeration set. The caller should perform an "AND" with the bit of interest and verify if the result is non-zero (as shown in the example) to verify the desired status bit. Example DRV_HANDLE handle; // Returned from DRV_USART_Open if (DRV_USART_TRANSFER_STATUS_TX_EMPTY & DRV_USART_TransferStatus(handle) ) { // All transmitter data has been sent. } 5.1.11.7.2.6 DRV_USART_Write Function C bool DRV_USART_Write( const DRV_HANDLE handle, const uint8_t * buffer, const uint32_t numbytes ); Description This routine writes data to the USART. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-530 Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer containing the data write to the USART instance numbytes Total number of bytes that to write to the USART instance (must be equal to or less than the size of the buffer) Returns Number of bytes actually written to the USART or -1 if there is an error (call DRV_USART_ClientStatus to identify the error) Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_USART_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_USART_Open routine or the driver was built to only support non-blocking behavior the call will return immediately, identifying how many bytes of data were actually written to the USART and the client must call DRV_USART_Write again with adjusted parameters as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int count; unsigned int total; total = 0; do { count = DRV_USART_Write(myUSARTHandle, &myBuffer[total], MY_BUFFER_SIZE - total); total += count; // Do something else... } while( total < MY_BUFFER_SIZE ); 5.1.11.7.2.7 DRV_USART_WriteByte Function C bool DRV_USART_WriteByte( const DRV_HANDLE handle, const uint8_t byte ); Description This routine writes a byte of data to the USART. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-531 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine byte Data byte to write to the USART Returns true - Write successful. false - Write failed. Remarks If the DRV_IO_INTENT_BLOCKING flag was given in the call to the DRV_USART_Open routine and the driver was built to support blocking behavior the call will block until the operation is complete. If the DRV_IO_INTENT_NONBLOCKING flag was given in the call to the DRV_USART_Open routine or the driver was built to only support non-blocking behavior the call will return immediately. If the driver was not able to accept the data, an overrun error status will be captured. To ensure that the driver is ready to accept data, the caller must first check the return value to DRV_USART_TransferStatus as shown in the example. Example DRV_HANDLE handle; // Returned from DRV_USART_Open bool status; // Pre-initialize myBuffer with MY_BUFFER_SIZE bytes of valid data. status = DRV_USART_WriteByte(handle, myBuffer[numBytes++]); // Do something else... } 5.1.11.7.3 Setup and Status Functions 5.1.11.7.3.1 DRV_USART_BufferTransferStatus Function C int8_t DRV_USART_BufferTransferStatus( const DRV_HANDLE handle, const DRV_HANDLE bufferHandle ); Description Gets the number of bytes which are written or read for the transaction handle Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. The function DRV_USART_BufferAdd should be called before calling this function and should have returned a valid buffer handle. Parameters Parameters Description handle Handle of the communication channel as return by the DRV_USART_Open function. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-532 bufferHandle Handle of the buffer returned by the DRV_USART_BufferAdd Returns The number of bytes read if the buffer id is DRV_IO_BUFFER_READ or number of bytes written when the buffer id is DRV_IO_BUFFER_WRITE. If -1 is returned Remarks None. Example void Callback(void); uint8_t mybuffer[MY_BUFFER_SIZE]; int8_t bytesWritten = 0; DRV_BUFFER_HANDLE bufferHandle = NULL; DRV_USART_IO_BUFFER buffer1; void Callback(void) { Nop(); } buffer1.buffer = writeBuffer2; buffer1.bufferSize = sizeof(writeBuffer2); buffer1.xferCallback = Callback; buffer1.flags = DRV_USART_BUFFER_FLAG_WRITE; // myUSARTHandle is the handle returned by the DRV_USART_Open function. bufferHandle = DRV_USART_BufferAdd(myUSARThandle, &buffer1); while(bytesWritten < MY_BUFFER_SIZE) { bytesWritten = DRV_USART_BufferTransferStatus(handle, bufferHandle); } 5.1.11.7.3.2 DRV_USART_ClientStatus Function C DRV_USART_CLIENT_STATUS DRV_USART_ClientStatus( const DRV_HANDLE handle ); Description This routine gets the client-specfic status of the USART driver associated with the given handle. Preconditions The DRV_USART_Initialize routine must have been called. DRV_USART_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns A DRV_USART_CLIENT_STATUS value describing the current status of the driver Remarks This routine will not block for hardware access and will immediately return the current status. 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-533 Example DRV_HANDLE handle; // Returned from DRV_USART_Open DRV_USART_CLIENT_STATUS clientStatus; clientStatus = DRV_USART_ClientStatus(handle); if(DRV_USART_CLIENT_STATUS_ERROR >= clientStatus) { // Handle the error } 5.1.11.7.3.3 DRV_USART_Close Function C void DRV_USART_Close( const DRV_HANDLE handle ); Description This routine closes an opened-instance of the USART driver, invalidating the handle. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_USART_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_USART_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Example DRV_HANDLE handle; // Returned from DRV_USART_Open DRV_USART_Close(handle); 5.1.11.7.3.4 DRV_USART_Open Function C DRV_HANDLE DRV_USART_Open( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-534 Description This routine opens the specified USART driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions Function DRV_USART_Initialize must have been called before calling this function. Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "or'd" together to indicate the intended use of the driver Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_USART_Close routine is called. This routine will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, then other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_USART_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Example DRV_HANDLE handle; handle = DRV_USART_Open(DRV_USART_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } 5.1.11.7.3.5 DRV_USART_Status Function C SYS_STATUS DRV_USART_Status( SYS_MODULE_OBJ object ); Description This routine provides the current status of the USART driver module. Preconditions Function DRV_USART_Initialize should have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from the DRV_USART_Initialize routine 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-535 Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Note Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Remarks Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR The this operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This routine will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize SYS_STATUS usartStatus; usartStatus = DRV_USART _Status(object); else if (SYS_STATUS_ERROR >= usartStatus) { // Handle error } 5.1.11.7.4 Data Types and Constants 5.1.11.7.4.1 DRV_USART_AUTO_BAUD_ENABLE Macro C #define DRV_USART_AUTO_BAUD_ENABLE true Description Auto Baud enable This macro configures enabling the auto baud. This is a static override of initialization parameter. This is the static override of the dynamic intialization passed using DRV_USART_INIT. The possible values it can take: • true - Enables Auto Baud • false - Disable Auto Baud 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-536 5.1.11.7.4.2 DRV_USART_BAUD_RATE Macro C #define DRV_USART_BAUD_RATE Description USART Baud Rate configuration This macro controls the operation of the driver for Baud rate configuration. This is the static override of the dynamic intialization passed using DRV_USART_INIT. 5.1.11.7.4.3 DRV_USART_BYTE_Q_SIZE_RX Macro C #define DRV_USART_BYTE_Q_SIZE_RX 16 Description USART Byte mode internal buffer Rx size configuration This macro controls the operation of the driver for defining the size of the Rx buffer 5.1.11.7.4.4 DRV_USART_BYTE_Q_SIZE_TX Macro C #define DRV_USART_BYTE_Q_SIZE_TX 16 Description USART Byte mode internal buffer Tx size configuration This macro controls the operation of the driver for defining the size of the Tx buffer 5.1.11.7.4.5 DRV_USART_CLIENTS_NUMBER Macro C #define DRV_USART_CLIENTS_NUMBER 2 Description USART Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Remarks None 5.1.11.7.4.6 DRV_USART_HANDSHAKE_MODE Macro C #define DRV_USART_HANDSHAKE_MODE Description Hand Shake Mode This macro configures the handshake mode. This is the static override of the dynamic intialization passed using DRV_USART_INIT. The possible values that it can take are 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-537 • DRV_USART_HANDSHAKE_MODE_FLOWCONTROL • DRV_USART_HANDSHAKE_MODE_SIMPLEX • DRV_USART_HANDSHAKE_MODE_NONE 5.1.11.7.4.7 DRV_USART_INDEX Macro C #define DRV_USART_INDEX DRV_USART_INDEX_2 Description Index - Used for static drivers USART Static Index selection for the driver object reference Remarks This index is required to make a reference to the driver object 5.1.11.7.4.8 DRV_USART_INDEX_0 Macro C #define DRV_USART_INDEX_0 0 Description Driver USART Module Index reference These constants provide timer driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_USART_Initialize and DRV_USART_Open routines to identify the driver instance in use. 5.1.11.7.4.9 DRV_USART_INDEX_1 Macro C #define DRV_USART_INDEX_1 1 Description This is macro DRV_USART_INDEX_1. 5.1.11.7.4.10 DRV_USART_INDEX_2 Macro C #define DRV_USART_INDEX_2 2 Description This is macro DRV_USART_INDEX_2. 5.1.11.7.4.11 DRV_USART_INDEX_3 Macro C #define DRV_USART_INDEX_3 3 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-538 Description This is macro DRV_USART_INDEX_3. 5.1.11.7.4.12 DRV_USART_INDEX_4 Macro C #define DRV_USART_INDEX_4 4 Description This is macro DRV_USART_INDEX_4. 5.1.11.7.4.13 DRV_USART_INDEX_5 Macro C #define DRV_USART_INDEX_5 5 Description This is macro DRV_USART_INDEX_5. 5.1.11.7.4.14 DRV_USART_INDEX_COUNT Macro C #define DRV_USART_INDEX_COUNT USART_NUMBER_OF_MODULES Description USART Driver Module Index Count This constant identifies USART driver index definitions. Remarks This constant should be used in place of hard-coded numeric literals. This value is part-specific. 5.1.11.7.4.15 DRV_USART_INSTANCES_NUMBER Macro C #define DRV_USART_INSTANCES_NUMBER 2 Description USART driver objects configuration Sets up the maximum number of hardware instances that can be supported Remarks None 5.1.11.7.4.16 DRV_USART_INTERRUPT_MODE Macro C #define DRV_USART_INTERRUPT_MODE 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-539 Description USART Interrupt Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation.The possible values it can take are • true - Enables the interrupt mode • false - Enables the polling mode 5.1.11.7.4.17 DRV_USART_INTERRUPT_SOURCE_ERROR Macro C #define DRV_USART_INTERRUPT_SOURCE_ERROR INT_SOURCE_USART_2_ERROR Description Error Interrupt Source This macro defines the interrupt source for the error interrupt. This is the static override of the dynamic intialization passed using DRV_USART_INIT. 5.1.11.7.4.18 DRV_USART_INTERRUPT_SOURCE_RX Macro C #define DRV_USART_INTERRUPT_SOURCE_RX INT_SOURCE_USART_2_RECEIVE Description RX Interrupt Source Macro to define the Rx interrupt source in case of static driver Remarks Refer to the INT PLIB document for more information on INT_SOURCE enumeration 5.1.11.7.4.19 DRV_USART_INTERRUPT_SOURCE_TX Macro C #define DRV_USART_INTERRUPT_SOURCE_TX INT_SOURCE_USART_2_TRANSMIT Description TX Interrupt Source Macro to define the Tx interrupt source in case of static driver Remarks Refer to the INT PLIB document for more information on PLIB_INT_SOURCE enumeration 5.1.11.7.4.20 DRV_USART_LINE_CONTROL Macro C #define DRV_USART_LINE_CONTROL DRV_USART_LINE_CONTROL_8N1 Description Line Control Mode This macro defines the line control mode as 8 data bits, even parity and 1 stop bit. It provides a static override of the initialization configuration of the line control mode. The possible values it can take are: 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-540 • DRV_USART_LINE_CONTROL_8E1 • DRV_USART_LINE_CONTROL_8E2 • DRV_USART_LINE_CONTROL_8O1 • DRV_USART_LINE_CONTROL_8O2 • DRV_USART_LINE_CONTROL_8N1 • DRV_USART_LINE_CONTROL_8N2 • DRV_USART_LINE_CONTROL_9N1 5.1.11.7.4.21 DRV_USART_OPERATION_MODE Macro C #define DRV_USART_OPERATION_MODE DRV_USART_OPERATION_MODE_RS232 Description USART mode This macro controls support modes of the USART driver . The possible values it can take are: • DRV_USART_OPERATION_MODE_IRDA • DRV_USART_OPERATION_MODE_RS232 • DRV_USART_OPERATION_MODE_RS485 • DRV_USART_OPERATION_MODE_SYNC_MASTER • DRV_USART_OPERATION_MODE_SYNC_SLAVE • DRV_USART_OPERATION_MODE_LOOPBACK Remarks None 5.1.11.7.4.22 DRV_USART_PERIPHERAL_ID Macro C #define DRV_USART_PERIPHERAL_ID Description Plib id This macro configures the PLIB Id for the driver. This is the static override of the dynamic intialization passed using DRV_USART_INIT. 5.1.11.7.4.23 DRV_USART_POLARITY_INVERTED_RX Macro C #define DRV_USART_POLARITY_INVERTED_RX true Description USART RX Polarity Mode. This macro defines the polarity of the RX pin. The possible values it can take are • true - polarity is inverted • false - polarity is not inverted 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-541 Remarks None. 5.1.11.7.4.24 DRV_USART_POLARITY_INVERTED_TX Macro C #define DRV_USART_POLARITY_INVERTED_TX true Description USART TX Polarity Mode. This macro defines the polarity of the TX pin. The possible values it can take are • true - polarity is inverted • false - polarity is not inverted Remarks None 5.1.11.7.4.25 DRV_USART_POWER_STATE Macro C #define DRV_USART_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description USART power state configuration This macro controls the power state of the USART Remarks This feature may not be available in the device or the USART module selected 5.1.11.7.4.26 DRV_USART_WAKE_ON_START_ENABLE Macro C #define DRV_USART_WAKE_ON_START_ENABLE Description Wake on start enable This macro configures that the peripheral should wake up on start. 5.1.11.7.4.27 DRV_USART_XFER_BUFFER_NUMBER Macro C #define DRV_USART_XFER_BUFFER_NUMBER 10 Description USART transfer buffer configuration This macro controls the transfer buffer depth Remarks This feature may not be available in the device or the USART module selected 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-542 5.1.11.7.4.28 DRV_USART_BUFFER_FLAGS Enumeration C typedef enum { DRV_USART_BUFFER_FLAG_WRITE, DRV_USART_BUFFER_FLAG_WRITE_AFTER_BREAK, DRV_USART_BUFFER_FLAG_WRITE_TO_ADDRESS, DRV_USART_BUFFER_FLAG_READ_FROM_ADDRESS, DRV_USART_BUFFER_FLAG_READ, DRV_USART_BUFFER_FLAG_STOP_ON_ERROR } DRV_USART_BUFFER_FLAGS; Description USART IO Types This enumeration defines the IO types that can be serviced by the USART driver. Members Members Description DRV_USART_BUFFER_FLAG_WRITE Write Buffer DRV_USART_BUFFER_FLAG_WRITE_AFTER_BREAK Write Buffer After Sending Break DRV_USART_BUFFER_FLAG_WRITE_TO_ADDRESS Write Buffer to the address DRV_USART_BUFFER_FLAG_READ_FROM_ADDRESS Raed Buffer from the address DRV_USART_BUFFER_FLAG_READ Read Buffer DRV_USART_BUFFER_FLAG_STOP_ON_ERROR Instructs the driver to stop processing if error is encountered Remarks None 5.1.11.7.4.29 DRV_USART_BUFFER_STATUS Enumeration C typedef enum { DRV_USART_BUFFER_COMPLETED, DRV_USART_BUFFER_QUEUED, DRV_USART_BUFFER_IN_PROGRESS, DRV_USART_BUFFER_ERROR_UNKNOWN, DRV_USART_BUFFER_ERROR_RX_OVERFLOW } DRV_USART_BUFFER_STATUS; Description USART Buffer Status Defines the states that an USART buffer can be in during its lifetime Members Members Description DRV_USART_BUFFER_COMPLETED Done OK and ready DRV_USART_BUFFER_QUEUED Scheduled but not started DRV_USART_BUFFER_IN_PROGRESS Currently being in transfer DRV_USART_BUFFER_ERROR_UNKNOWN Unknown buffer DRV_USART_BUFFER_ERROR_RX_OVERFLOW Read data lost: rx process not fast enough 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-543 Remarks As buffers may have a limited life span, so too have the associated handles and status info. Once a buffer transfer is completed (and possibly notified and acknowledged) it will be discarded. The status of a discarded buffer is no longer maintained by the driver. 5.1.11.7.4.30 DRV_USART_CALLBACK Type C typedef void (* DRV_USART_CALLBACK)(void); Description USART Callback Function This data type defines a pointer callback function. Remarks A USART callback function must have the following function signature: void MyCallBack ( DRV_USART_BUFFER_HANDLE *bufferHandle ); Where "MyCallBack" can be any name desired as the routine is called through the pointer. A pointer of this type is passed into the DRV_USART_RegisterCallbacks routine. 5.1.11.7.4.31 DRV_USART_CLIENT_STATUS Enumeration C typedef enum { DRV_USART_CLIENT_STATUS_READY, DRV_USART_CLIENT_STATUS_BUSY, DRV_USART_OVERRUN_ERROR, DRV_USART_PARITY_ERROR, DRV_USART_FRAMING_ERROR, DRV_USART_STATUS_INVALID } DRV_USART_CLIENT_STATUS; Description USART Client Status Defines the various client status codes. Members Members Description DRV_USART_CLIENT_STATUS_READY Up and running, ready to start new operations DRV_USART_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_USART_OVERRUN_ERROR Overrun Error Occured DRV_USART_PARITY_ERROR Parity Error DRV_USART_FRAMING_ERROR Framing Error DRV_USART_STATUS_INVALID client Invalid Remarks None 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-544 5.1.11.7.4.32 DRV_USART_HANDSHAKE_MODES Enumeration C typedef enum { DRV_USART_HANDSHAKE_MODE_FLOWCONTROL, DRV_USART_HANDSHAKE_MODE_SIMPLEX, DRV_USART_HANDSHAKE_MODE_NONE } DRV_USART_HANDSHAKE_MODES; Description USART Handshake Modes This data type identifies the handshaking modes available on the USART module. Members Members Description DRV_USART_HANDSHAKE_MODE_FLOWCONTROL Handshaking occurs in Flow Control Mode DRV_USART_HANDSHAKE_MODE_SIMPLEX Handshaking occurs in Simplex Mode DRV_USART_HANDSHAKE_MODE_NONE No Handshaking Remarks Not all modes are available on all micro-controllers. 5.1.11.7.4.33 DRV_USART_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; USART_MODULE_ID usartID; uint8_t operationMode; uint8_t initFlags; DRV_USART_LINE_CONTROL_MODES lineControlMode; uint32_t brgValue; DRV_USART_OPERATION_MODE_INIT operationModeInit; DRV_USART_HANDSHAKE_MODES handShakeMode; uint32_t txInterruptSource; uint32_t rxInterruptSource; uint32_t errorInterruptSource; uint32_t rxQueueSize; uint32_t txQueueSize; } DRV_USART_INIT; Description USART Driver Initialization Data This data type defines the data required to initialize or reinitialize the USART driver. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization USART_MODULE_ID usartID; Identifies USART hardware module (PLIB-level) ID uint8_t operationMode; Operation Modes of the driver uint8_t initFlags; Flags for the usart initialization DRV_USART_LINE_CONTROL_MODES lineControlMode; Control the line control configuration 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-545 uint32_t brgValue; Baud Rate value to be used, if not using auto baud DRV_USART_OPERATION_MODE_INIT operationModeInit; Operation mode initialization data DRV_USART_HANDSHAKE_MODES handShakeMode; Handshake Mode uint32_t txInterruptSource; Interrupt Source for TX Interrupt INT_SOURCE txInterruptSource; uint32_t rxInterruptSource; Interrupt Source for RX Interrupt INT_SOURCE rxInterruptSource; uint32_t errorInterruptSource; Interrupt Source for Error Interrupt INT_SOURCE errorInterruptSource; Remarks Not all the init features are available for all the microcontrollers 5.1.11.7.4.34 DRV_USART_INIT_FLAGS Enumeration C typedef enum { DRV_USART_INIT_FLAG_WAKE_ON_START_ENABLE, DRV_USART_INIT_FLAG_AUTO_BAUD_ENABLE } DRV_USART_INIT_FLAGS; Description USART Initialization flags Defines the various flags which determine specific modes Members Members Description DRV_USART_INIT_FLAG_WAKE_ON_START_ENABLE Flag to setup Wake on Start Operation DRV_USART_INIT_FLAG_AUTO_BAUD_ENABLE Flag to enable auto baud detection enable. Remarks None 5.1.11.7.4.35 DRV_USART_IO_BUFFER Structure C typedef struct { DRV_USART_BUFFER_FLAGS flags; char * buffer; uint32_t bufferSize; uint8_t address; DRV_USART_CALLBACK xferCallback; } DRV_USART_IO_BUFFER; Description USART Driver IO Buffer This structure holds information that the client must pass the driver to enqueue a buffer to be transferred by a read or write operation. Members Members Description DRV_USART_BUFFER_FLAGS flags; Defines the IO Type this buffer is associated with char * buffer; The buffer which needs to be read or written 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-546 uint32_t bufferSize; The size of the buffer which needs to be read or written uint8_t address; The address which needs to be written Remarks A pointer to an instance of this structure must be passed to the DRV_USART_BufferAdd routine. 5.1.11.7.4.36 DRV_USART_LINE_CONTROL_MODES Enumeration C typedef enum { DRV_USART_LINE_CONTROL_MODE_8NONE1, DRV_USART_LINE_CONTROL_MODE_9NONE1, DRV_USART_LINE_CONTROL_MODE_8EVEN1, DRV_USART_LINE_CONTROL_MODE_8EVEN2, DRV_USART_LINE_CONTROL_MODE_8ODD1, DRV_USART_LINE_CONTROL_MODE_8ODD2 } DRV_USART_LINE_CONTROL_MODES; Description USART Line Control Modes This data type identifies the line control modes available Members Members Description DRV_USART_LINE_CONTROL_MODE_8NONE1 8 Data Bits, No Parity, 1 Stop Bits DRV_USART_LINE_CONTROL_MODE_9NONE1 9 Data Bits, No Parity, 1 Stop Bits DRV_USART_LINE_CONTROL_MODE_8EVEN1 8 Data Bits, Even Parity, 1 Stop Bits DRV_USART_LINE_CONTROL_MODE_8EVEN2 8 Data Bits, Even Parity, 2 Stop Bits DRV_USART_LINE_CONTROL_MODE_8ODD1 8 Data Bits, Odd Parity, 1 Stop Bits DRV_USART_LINE_CONTROL_MODE_8ODD2 8 Data Bits, Odd Parity, 2 Stop Bits Remarks None 5.1.11.7.4.37 DRV_USART_OPERATION_MODE_INIT Union C typedef union { struct { uint8_t address; } RS485Init; } DRV_USART_OPERATION_MODE_INIT; Description Operation Mode Initialization This data type defines the initialization data required for different operation modes of USART. Members Members Description struct { uint8_t address; } RS485Init; Initialization for RS485 mode 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-547 uint8_t address; Address of the device. Remarks None 5.1.11.7.4.38 DRV_USART_OPERATION_MODES Enumeration C typedef enum { DRV_USART_OPERATION_MODE_IRDA = (1 << 0), DRV_USART_OPERATION_MODE_RS232, DRV_USART_OPERATION_MODE_RS485, DRV_USART_OPERATION_MODE_SYNCHRONOUS_MASTER, DRV_USART_OPERATION_MODE_SYNCHRONOUS_SLAVE, DRV_USART_OPERATION_MODE_LOOPBACK } DRV_USART_OPERATION_MODES; Description USART Modes of Operation This data type identifies the modes of the operation of the USART module. Members Members Description DRV_USART_OPERATION_MODE_RS232 RS232 Mode (Asynchronous Mode of Operation) DRV_USART_OPERATION_MODE_RS485 RS485 Mode (Asynchronous Mode of Operation) DRV_USART_OPERATION_MODE_SYNCHRONOUS_MASTER Synchronous Master Mode DRV_USART_OPERATION_MODE_SYNCHRONOUS_SLAVE Synchronous Slave Mode DRV_USART_OPERATION_MODE_LOOPBACK Loopback Mode Remarks Not all modes are available on all microcontrollers. Refer to the data sheet for the microcontroller in use. 5.1.11.7.4.39 DRV_USART_TRANSFER_STATUS Enumeration C typedef enum { DRV_USART_TRANSFER_STATUS_RX_FULL, DRV_USART_TRANSFER_STATUS_RX_DATA_PRESENT, DRV_USART_TRANSFER_STATUS_RX_EMPTY, DRV_USART_TRANSFER_STATUS_TX_FULL, DRV_USART_TRANSFER_STATUS_TX_EMPTY } DRV_USART_TRANSFER_STATUS; Description USART Driver Transfer Flags This type specifies the status of the receive or transmit operation. Members Members Description DRV_USART_TRANSFER_STATUS_RX_FULL Indicates that the core driver buffer is full DRV_USART_TRANSFER_STATUS_RX_DATA_PRESENT Indicates that at least one byte of Data has been received DRV_USART_TRANSFER_STATUS_RX_EMPTY Indicates that the core driver receiver buffer is empty 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-548 DRV_USART_TRANSFER_STATUS_TX_FULL Indicates that the core driver transmitter buffer is full DRV_USART_TRANSFER_STATUS_TX_EMPTY Indicates that the core driver transmitter buffer is empty Remarks More than one of these values may be OR'd together to create a complete status value. To test a value of this type, the bit of interrest must be AND'ed with value and checked to see if the result is non-zero. 5.1.11.7.4.40 DRV_USART_XFER_HANDLE Type C typedef uintptr_t DRV_USART_XFER_HANDLE; Description USART Transfer Handle Handle for requested transfer.. Remarks None 5.1.11.8 Files Files Name Description drv_usart.h USART Driver Interface Definition drv_usart_config_template.h USART Driver Configuration Template. Description 5.1.11.8.1 drv_usart.h USART Driver Interface Definition The USART device driver provides a simple interface to manage the USART or UART modules on Microchip microcontrollers. This file defines the interface definition for the USART driver. Enumerations Name Description DRV_USART_BUFFER_FLAGS Defines the IO types that can be serviced by the USART driver DRV_USART_BUFFER_STATUS Defines the buffer status DRV_USART_CLIENT_STATUS Defines the client status DRV_USART_HANDSHAKE_MODES Identifies the handshaking modes available on the USART DRV_USART_INIT_FLAGS Defines specific initialization features DRV_USART_LINE_CONTROL_MODES Identifies the line control modes available DRV_USART_OPERATION_MODES Identifies the modes of the operation of the USART module DRV_USART_TRANSFER_STATUS Specifies the status of the receive or transmit 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-549 Functions Name Description DRV_USART_BufferAdd Starts the writes to the communication channel. DRV_USART_BufferStatus Provides the status of the given buffer DRV_USART_BufferTransferStatus Gets the number of bytes which are written or read DRV_USART_ClientStatus Gets current client-specific status the USART driver DRV_USART_Close Closes an opened-instance of the USART driver DRV_USART_Deinitialize Deinitializes the specified instance of the USART driver module DRV_USART_Initialize Initializes the USART instance for the specified driver index DRV_USART_Open Opens the specified timer driver instance and returns a handle to it DRV_USART_Read Reads data from the USART DRV_USART_ReadByte Reads a byte of data from the USART DRV_USART_Reinitialize Reinitializes the USART driver and refreshes any associated hardware settings DRV_USART_Status Gets the current status of the USART driver module. DRV_USART_TasksError Maintains the driver's error-handling state machine and implements its ISR DRV_USART_TasksRX Maintains the driver's receiver state machine and implements its ISR DRV_USART_TasksTX Maintains the driver's tramsmitter state machine and implements its ISR DRV_USART_TransferStatus Returns the transmitter and receiver transfer status DRV_USART_Write Writes data to the USART DRV_USART_WriteByte Writes a byte of data to the USART Macros Name Description DRV_USART_INDEX_0 USART driver index definitions DRV_USART_INDEX_1 This is macro DRV_USART_INDEX_1. DRV_USART_INDEX_2 This is macro DRV_USART_INDEX_2. DRV_USART_INDEX_3 This is macro DRV_USART_INDEX_3. DRV_USART_INDEX_4 This is macro DRV_USART_INDEX_4. DRV_USART_INDEX_5 This is macro DRV_USART_INDEX_5. DRV_USART_INDEX_COUNT Number of valid USART driver indices Structures Name Description DRV_USART_INIT Defines the data required to initialize or reinitialize the USART driver DRV_USART_IO_BUFFER IO buffer information structure Types Name Description DRV_USART_CALLBACK Pointer to a USART callback function DRV_USART_XFER_HANDLE Handle for requested transfer.. Unions Name Description DRV_USART_OPERATION_MODE_INIT Defines the initialization data required for different operation modes of USART 5.1 Driver Library Help MPLAB Harmony Help USART Driver Library 5-550 File Name drv_usart.h Company Microchip Technology Incorported 5.1.11.8.2 drv_usart_config_template.h USART Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. Macros Name Description DRV_USART_AUTO_BAUD_ENABLE Macro configures enabling the auto baud. DRV_USART_BAUD_RATE Macro controls operation of the driver for Baud rate configuration DRV_USART_BYTE_Q_SIZE_RX Macro controls operation of the driver for defining the size of the Rx buffer DRV_USART_BYTE_Q_SIZE_TX Macro controls operation of the driver for defining the size of the Tx buffer DRV_USART_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_USART_HANDSHAKE_MODE Configures the handshake mode DRV_USART_INDEX USART Static Index selection DRV_USART_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_USART_INTERRUPT_MODE Macro controls operation of the driver in the interrupt mode DRV_USART_INTERRUPT_SOURCE_ERROR Defines the interrupt source for the error interrupt DRV_USART_INTERRUPT_SOURCE_RX Macro to define the Rx interrupt source in case of static driver DRV_USART_INTERRUPT_SOURCE_TX Macro to define the Tx interrupt source in case of static driver DRV_USART_LINE_CONTROL Macro defines the line control mode DRV_USART_OPERATION_MODE Defines the mode to be used for the USART driver DRV_USART_PERIPHERAL_ID Configures the PLIB id DRV_USART_POLARITY_INVERTED_RX Defines the polarity of the RX pin. DRV_USART_POLARITY_INVERTED_TX Defines the polarity of the TX pin. DRV_USART_POWER_STATE Macro controls power state of the USART DRV_USART_WAKE_ON_START_ENABLE Macro configures that the peripheral should wake up on start DRV_USART_XFER_BUFFER_NUMBER Transfer buffer depth File Name drv_usart_config_template.h Company Microchip Technology Incorported 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-551 5.1.12 USB Driver Library 5.1.12.1 Introduction USB Device Driver Library for Microchip Microcontrollers This library provides an interface to manage the USB module on Microchip family of micro controllers during different modes of operation. Description Overview of the USB Module The USB module implements the physical layer in a USB based system. In that, it allows the USB stack software to access and control the USB. The USB module on Microchip's micro controllers are compliant with the USB 2.0 specification. This help file only provides relevant information about the operation of the USB. The reader is encouraged to refer to the USB 2.0 specification available at www.usb.org for complete information about the USB. Not all Microchip microcontrollers feature a USB module. Among the ones that do, the supported features may vary. Please refer to the device specific data sheet for details on the availability of the USB module and the supported features. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. 5.1.12.2 Release Notes MPLAB Harmony Version: v0.70b USB Driver Library Version : 1.0 Release Date: 18Nov2013 New This Release: • Supports all four (Control, Bulk, Interrupt and Isochronous) USB Transfers. • Control transfers supported on endpoint 0 only. • Endpoint 0 pipe is always bidirectional. All other endpoint pipes require Receive and Transmit pipes to be opened separately. • Supports multiple clients. Device function drivers can communicate on the USB directly via the USB Driver. • Setup packet reception is automatic and does not require client intervention or scheduling. Clients receive notification when a Setup packet is received. • The static multi client version of the driver support one transfer object per Control, Bulk and Interrupt Pipe and supports 2 transfer objects per Isochronous Pipe. Known Issues: • Nothing to report in this release 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-552 5.1.12.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.12.4 Using the Library This topic describes the basic architecture of the USB Driver Library and provides information and examples on how to use it. Interface Header File: drv_usb.h The interface to the USB Driver library is defined in the "drv_usb.h" header file. Please refer to the MPLAB Harmony Overview for how the Driver interacts with the framework. 5.1.12.4.1 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various subsections, each of the sub section addresses one of the blocks or the overall operation of the USB module. Library Interface Section Description System Functions These routines are typically invoked by the MPLAB Harmony system module. Client Functions These routines are used by the driver clients to access driver functionality Pipe Functions These routines allow clients to manage pipes Transfer Functions These routines allow clients to manage transfers Other Functions These routines represent the rest of the driver functionality Data Types and Constants These data types and constants are required while interacting and configuring the driver 5.1.12.4.2 Abstraction Model Figure 1: USB Driver Device Mode Model Figure 1 shows the functioning of the USB Driver in device mode. In this mode, the driver offers services required to operate the 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-553 USB module as a USB device. The USB Driver supports multiple clients. Each client can receive notifications about USB events via callback functions. Typical clients could be the Device Layer firmware and one or more function drivers. The Device layer firmware and the function drivers communicate on the USB via pipes. A pipe is an association between the device's endpoint and host stack software. An Endpoint 0 Pipe is always bi-directional and is a message pipe. Communication on this pipe is defined by the USB specification. All other endpoints support stream pipes. The format of the data on a stream pipe is not specified by the USB specification. Stream pipes are uni-directional. Therefore, two pipes are required to transmit and receive data on a non-zero endpoint. Clients schedule USB transfers through a pipe. Transfers on non-zero endpoint pipes can be queued. The USB driver manages the transactions required to complete the transfer. This is transparent to the clients. Clients can either get an event notification or can poll to check the completion status of a transfer. Clients can register callback functions to receive USB events notification. A Transfer complete callback function can be registered while requesting a transfer. This function will be called when the transfer is terminated. While operating in device mode, the first client of the USB Driver should always be the USB Device Stack Device layer. Only the first client can schedule control transfers on endpoint 0 (via a pipe) and receive the Setup Token and Setup Handshake events (along with the other events). Other clients may or may not register an event call back function. The USB Driver uses configuration macros that control among other things, functional aspects such as maximum number of clients and maximum pipes. 5.1.12.4.3 How the Library Works Before the driver is ready for use, its should be configured. Refer to the Configuring the Library section for more details on how to configure the driver. To use the USB Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. The following is the sequence in which various routines should be called: 1. Call the DRV_USB_Init() function to initialize the USB Driver. Note that this may be performed by the MPLAB Harmony system module. 2. In USB device mode operation, the first client should always be the USB Device Stack Device Layer. The Device Layer first opens the driver via the DRV_USB_Open() function. 3. The Device layer registers an event call back function via the DRV_USB_Device_EventCallBackSet() function. 4. The Device layer assigns a setup packet buffer by using the DRV_USB_Device_SetupPacketBufferAssign() function. The driver stores the received setup packet in this buffer. Calling this function also enables the USB Device Mode and at this point the device will attach to the host and be ready to receive setup tokens from the host. 5. The Device Layer waits for the Reset Event. In this event, the device layer creates an endpoint 0 pipe by using the DRV_USB_Device_PipeSetup() function. The Device layer can optionally register a transfer complete call back function. This function will be called when a transfer on the endpoint zero is complete. 6. Based on the device enumeration process and the selected configuration, other function drivers may open the driver by using the DRV_USB_Open() function. It is strongly recommended that the above sequence be followed for correct operation on the driver. Note: Not all modes are available on all the devices, please refer to the specific device data sheet for the set of modes supported. 5.1.12.4.3.1 Driver Initialization At the time of initialization, the DRV_USB_Initialize() function requires DRV_MODULE_INIT data structure that provides information required for the function of the driver. The following data is needed: 1. Maximum number of endpoints to be supported by the driver. In case endpoints are skipped, the largest endpoint number 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-554 should be used. For example, if the application uses endpoints 0,1 and 2, then maximum number of endpoints should 3. If the application uses endpoints 0,1 and 5, then maximum number of endpoints should 6. The latter configuration is not recommended. 2. Maximum side of the endpoint 0. This should match the maximum size that is reported to the host during enumeration. 3. Pointer to byte array whose size is defined DRV_USB_WORKING_BUFFER_SIZE(nEndpoint, maxEP0Size), where nEndpoint is the maximum number of endpoint as described in point 1 above and maxEP0Size is the maximum endpoint 0 size as described in point 2 above. These values should match usbInitData.ep0MaxSize and usbInitData.nEndpoints. 4. The PLIB peripheral ID of the USB module to associated with the driver object being initialized. 5. The operation mode of the driver (host, device or OTG). Refer to the Release Notes for supported modes. 5. The ping pong mode to be used by internal endpoint buffers. Refer to the device specific data sheet for supported ping pong modes. 6. Behavior of the USB module when the microcontroller device enters IDLE mode. 7. Behavior of the USB module when the microcontroller device enters SLEEP mode. 8. Power state of the USB module. 9. USB module interrupts to be enabled. These include the general, error and OTG interrupts. Refer to the USB PLIB documentation for available module interrupts. 10. The interrupt source of the USB module to be used with the driver instance. Refer to the USB PLIB documentation for available module interrupts. The following code snippet shows an example initialization of the driver. /* The following code snippet shows an example initialization of the * driver. The USB module to be used in USB1. The maximum number of * endpoints to be used is 3 i.e endpoint 0,1 and 2. Maximum size of * endpoint 0 is 64. The module should not automatically suspend when the * micro-controller enters Sleep mode. The module should continue * operation when the module enters Idle mode. The ping pong setting * is set to full ping pong (both RX and TX endpoints have ping * pong buffers). The power state is set to run at full clock speeds.*/ DRV_USB_INIT moduleInit; uint8_t internalBuffer[[DRV_USB_WORKING_BUFFER_SIZE(3,64)] __attribute__((aligned(512))); usbInitData.usbID = USB_ID_1; usbInitData.usbModuleSetup.OpMode = USB_OPMODE_DEVICE; usbInitData.usbModuleSetup.ppMode = USB_PING_PONG__FULL_PING_PONG; usbInitData.usbModuleSetup.StopInIdle = false; usbInitData.usbModuleSetup.SuspendInSleep = false; usbInitData.usbModuleSetup.otgInterruptEnables = ~USB_OTG_INT_ALL ; usbInitData.usbModuleSetup.generalInterruptEnables = USB_INT_ALL & ~USB_INT_SOF ; usbInitData.usbModuleSetup.errorInterruptEnables = USB_ERR_INT_ALL ; usbInitData.workingBuffer = internalBuffer; usbInitData.ep0MaxSize = 64; usbInitData.nEndpoints = 3; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; usbInitData.interruptSource = INT_SOURCE_USB_1; /* This is how this data structure is passed to the initialize * function. */ 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-555 DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); 5.1.12.4.3.2 Opening the Driver Once the driver is initialized for device mode, it can be opened by clients. The client must specify which driver instance it wants to be a client to and IO mode in which the driver should be opened. The USB Device Driver while operating in USB device mode only supports non-blocking, read write and shared client access I/O intent mode. Trying to open the driver in any other mode will cause the open routine to fail. The driver treats the first client that opens it, differently from the other clients. This first client must open a bi-directional pipe on endpoint zero. It must then register a Setup Packet Buffer with the driver. The driver uses this buffer to store the 8 byte Setup command details received during the Setup stage of a Control transfer. While all clients can register a USB event callback function, only the first client receives the USB_DEVICE_SETUP_TOKEN and the USB_DEVICE_SETUP_HANDSHAKE event in its callback routine. Typically (and it is recommended that) the first client to open the driver should be the USB Device Stack Device Layer Firmware. The Device Layer firmware is responsible for enumerating the USB device and responding to host requests on the Endpoint 0 message pipe. The first client should register a USB event callback function (by using the DRV_USB_Device_EventCallbackSet() function) and Setup Packet Buffer (by using the DRV_USB_Device_SetupPacketBufferAssign() function) with the Driver. Both of these are essential for operation of the driver. Registering a Setup Packet Buffer via the DRV_USB_Device_SetupPacketBufferAssign() also enables the USB device (activates the USB module pull up resistors) for operation on the USB. The following code snippet shows an example of how a USB Device Stack Device Layer should open the driver and perform other functions. /* In this example, the USB Device Layer (myUSBDevice) opens * the USB Driver. It is assumed that the Driver is already * initialized */ myUSBDevice.usbDriverHandle = DRV_USB_Open(DRV_USB_INDEX_0, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_SHARED ); if(DRV_HANDLE_INVALID == myUSBDevice.usbDriverHandle) { /* The open function failed. We can find out why */ if(USB_CLIENT_NOTAVAIL == DRV_USB_Device_DriverClientErrorGet(DRV_USB_INDEX_0)) { /* This means that there is no space for another client. * The driver configuration needs to be modified to support * more clients. This can be done by increasing the value * of DRV_USB_CLIENTS_NUMBER */ while(1); } } /* Set the client event callback for the Device Layer. * The USBDeviceLayerEventHandler() function is the event * handler. When this event handler is invoked by the * driver, the driver returns back the second argument * specified in the below function (which in this case * is the device layer data structure). This allows the * application firmware to identify, as an example, the * device layer object associated with this callback */ DRV_USB_Device_EventCallBackSet(myUSBDevice.usbDriverHandle, (void *)&myUSBDevice, USBDeviceLayerEventHandler); /* Device Layer register setup packet buffer. The Setup Packet Bufffer * size is 8 bytes and is of the type uint8_t. Calling this function 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-556 * enables the device and the device is ready to receive a Setup token * from the host. */ DRV_USB_Device_SetupPacketBufferAssign(myUSBDevice.usbDriverHandle, setupPacketBuffer); /* Device Layer opens a endpoint 0 pipe. Refer to Setting * up a Pipe section for more details on how to set up the * pipe. This may be done in the reset event.*/ myUSBDevice.ep0Pipe = DRV_USB_Device_PipeSetup(myUSBDevice.usbDriverHandle, 0, USB_EP_TX_RX, 64, 1, USB_CONTROL_PIPE); A function driver may open the driver for use based on the configuration set by the host. Function drivers may or may not require USB Event notification and so may not need to register a USB Event Callback function. The user application can also open the driver. This allows the user application to track USB events and also communicate directly on the bus. The following code snippet shows an example of how a function driver can open the USB Driver. /* This code snippet shows an example of how the * a function driver, say CDC, could open the USB Driver. * Note that this should happen on a set configuration * event from the host. */ cdc.usbDriverHandle = DRV_USB_Open(DRV_USB_INDEX_0, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE ); if(DRV_HANDLE_INVALID == cdc.usbDriverHandle) { /* The open function failed. We can find out why */ if(USB_CLIENT_NOTAVAIL == DRV_USB_Device_DriverClientErrorGet(DRV_USB_INDEX_0)) { /* This means that there is no space for another client. * The driver configuration needs to be modified to support * more clients.This can be done by increasing the value * of DRV_USB_CLIENTS_NUMBER */ */ while(1); } } /* Set the USB Event handler for CDC. Note that * this optional and should be done only if the * function driver requires USB Events notification. */ DRV_USB_Device_EventCallBackSet(cdc.usbDriverHandle, (void *)&cdc, CDCDeviceUSBEventHandler); /* CDC Function driver opens a TX and RX bulk pipe on * endpoint 1. */ cdc.bulkRxPipe = DRV_USB_Device_PipeSetup(cdc.usbDriverHandle, 1, USB_EP_RX, 64, 3, USB_BULK_PIPE); cdc.bulkTxPipe = DRV_USB_Device_PipeSetup(cdc.usbDriverHandle, 1, USB_EP_TX, 64, 3, USB_BULK_PIPE); 5.1.12.4.3.3 Endpoint Pipes A client must open a pipe in order to schedule transfers on the USB. This is done by using the DRV_USB_Device_PipeSetup() function. From a USB perspective, an endpoint 0 pipe is a message pipe (or a control pipe). The data flowing through this pipe has a structure which defined by the USB specification. Pipes on non-zero endpoints are stream pipes and need not follow a specific format. A Pipe connects a device's endpoint to a Host Driver software. Endpoint 0 pipe is always needed and must be created for the USB device to enumerate and hence operate correctly. Non-zero endpoint pipes are created based on the configuration set by the Host. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-557 5.1.12.4.3.3.1 Pipe Setup The DRV_USB_Device_PipeSetup() function creates a pipe. The following points should be noted while using this function to create a pipe. 1. The pipeDirection argument specifies the pipe direction. An endpoint 0 pipe is always bi-directional. So this parameter is ignored when the nEndpoint parameter is 0. All other pipes must be unidirectional. Specifying USB_EP_TX as the pipe direction sets up the pipe to send data from device to host (host Read transfers). Specifying USB_EP_RX as the pipe direction sets up the pipe to receive data from host (host Write transfers). 2. The nBytesMaxSize parameter specifies the maximum size of the data packet in a transaction on that pipe. It should not exceed the maximum endpoint size communicated to the host during enumeration. Depending on the type of the USB transfer that the pipe will handle and the speed of the USB, the maximum size of the data packet may vary. If the size of the read transfer (device to host) scheduled on the pipe is greater than nBytesMaxSize, the driver will respond correctly multiple transactions that are issued by the host to complete the transfer. 3. The nXferQueueSize parameter defines the size of the transfers that can be queued up this pipe. The minimum queue size should be 1. The control pipe (endpoint 0 pipe) always has queue size of 1. Control transfers on the endpoint 0 pipe cannot be queued. Refer to the Transfer Request section for more information on how transfers are scheduled. Other non-zero endpoint pipes can have a queue size greater than or equal to 1. 4. An endpoint and direction of communication cannot be shared between two pipes. For example if a client opens a RX pipe on endpoint 1, another RX pipe on endpoint 1 cannot be opened. 5. The pipeType parameter specified the type of transfers that this pipe will handle. The client can check the return value of the DRV_USB_Device_PipeSetup() for the result. If the pipe was not setup successfully, the function returns DRV_HANDLE_INVALID. The client can then use the DRV_USB_Device_ClientPipeErrorGet() function to find out the reason for the failure. The following code snippet shows how endpoint 0 pipe and non-zero endpoint pipes are created. /* This is an example of how an endpoint 0 pipe is created. * Note that this pipe is always bi-directional and the * queue size is always 1. The maximum data packet size in this * case is 64. The pipe type is set to handle control transfers */ myUSBDevice.ep0Pipe = DRV_USB_Device_PipeSetup(myUSBDevice.usbDriverHandle, 0, USB_EP_TX_RX, 64, 1, USB_CONTROL_PIPE); if(DRV_HANDLE_INVALID == myUSBDevice.ep0Pipe) { switch(DRV_USB_Device_ClientPipeErrorGet(myUSBDevice.usbDriverHandle)) { case USB_PIPE_QUEUE_NOT_AVAILABLE: /* This means that queue size is small. Increase * the value of DRV_USB_XFERS_NUMBER. */ break; case USB_PIPE_BAD_ENDPT: /* The specified endpoint is greater than the * the maximum end points that driver is configured * to handle. */ break; case USB_PIPE_TAKEN: 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-558 /* The specified endpoint and direction are already * in use with another pipe. A non-zero endpoint * can have only one pipe in a direction. Endpoint * 0 can have one bi-directional pipe.*/ break; case USB_PIPE_NOTAVAIL: /* No pipes are available. Increase the number of pipes * by increasing the value of DRV_USB_PIPES_NUMBER. */ break; case USB_PIPE_BAD_DIRECTION: /* Non zero endpoint cannot be bi-directional. */ break; } /* This is an example of how a client creates a non-zero endpoint pipe. * In this case a TX and a RX pipe are opened on endpoint 1. The * transfer schedule queue size is 4 and maximum data packet size * is 64. Note that the maximum data packet size should match endpoint * size specified in the endpoint configuration. */ cdc.bulkRxPipe = DRV_USB_Device_PipeSetup(cdc.usbDriverHandle, 1, USB_EP_RX, 64, 3, USB_BULK_PIPE); /* Optionally check for error here by using the * DRV_USB_Device_ClientPipeErrorGet() function */ cdc.bulkTxPipe = DRV_USB_Device_PipeSetup(cdc.usbDriverHandle, 1, USB_EP_TX, 64, 3, USB_BULK_PIPE); /* Optionally check for error here by using the * DRV_USB_Device_ClientPipeErrorGet() function */ /* The following usage of DRV_USB_Device_PipeSetup() is INCORRECT and * will not work. The client must create separate TX and RX pipes for * non-zero endpoints. This function will return DRV_HANDLE_INVALID * and the DRV_USB_Device_ClientPipeErrorGet()function will return * USB_PIPE_BAD_DIRECTION. */ someDevice.bulkPipe = DRV_USB_Device_PipeSetup(someDevice.usbDriverHandle, 1, USB_EP_TX_RX, 64, 3, USB_BULK_PIPE); // Will not work! 5.1.12.4.3.3.2 Pipe Status The client can use the DRV_USB_Device_PipeStatusGet() function to obtain the status of the pipe. The client can use this information to find if a pipe is ready for transfers or if the pipe can be or is stalled. The following code snippet shows an example of the DRV_USB_Device_PipeStatusGet() function along with all the possible return values. /* This code example assumes the DRV_USB_DevicePipeSetup() function * was used to open a pipe */ DRV_USB_PIPE_HANDLE pipeHandle; DRV_USB_PIPE_STATUS pipeStatus; if(DRV_HANDLE_INVALID != pipeHandle) { pipeStatus = DRV_USB_Device_PipeStatusGet(pipeHandle); switch (pipeStatus) { case USB_PIPE_CLOSED: 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-559 /* The pipe was open and has been closed. * This pipe should not be used for transferring * data */ break; case USB_PIPE_XFER_IN_PROGRESS: /* There is a transfer in progress on the USB * through this pipe. */ break; case USB_PIPE_READY: /* Pipe is ready for transferring data. Also * indicates that there is no transfer in progress * on the USB through this pipe */ break; case USB_PIPE_STALLED: /* Pipe is stalled. No transfers will take place. */ break; } } 5.1.12.4.3.3.3 Pipe Close An open pipe can be closed by using the DRV_USB_Device_PipeRelease() function. Calling this function performs the following function 1. It aborts all transfers that are in queue. If a transfer is in progress on the USB, it is cancelled. 2. It de-allocates its transfer queue and returns it to the driver. 3. It de-allocates the pipe and returns its to the driver. The DRV_USB_Device_PipeRelease() may be called when the device stack detects detach from the host, or when a USB reset event had been detected. Because this function aborts transfers that are in progress on the USB, it is possible that calling this function while a transfer is in progress can cause the USB protocol to be violated. To avoid this, the client can use the DRV_USB_Device_PipeStatusGet() function to get the status of the pipe before closing it. In case of a USB reset event, the client can close the pipe without checking pipe status as the driver itself will cancel all transfer that are in progress. The following code snippet shows example usage of the DRV_USB_Device_PipeRelease() function. /* This code snippet assumes that this is not a reset * event. In such a case, it is recommended that any * transfers through the pipe be allowed to complete. */ while(DRV_USB_Device_PipeStatusGet(pipeHandle) == USB_PIPE_XFER_IN_PROGRESS); /* Close the pipe */ DRV_USB_Device_PipeRelease(pipeHandle); 5.1.12.4.3.3.4 Pipe Transfer Queue A pipe provides a queue for transfer requests. Clients can use the queue to reduce wait times and hence increase data throughput through the pipe. If the pipe queue size is greater than one, the transfer requests on the pipe will be added to the queue if a transfer is already in progress on the pipe. The size of queue is specified via the nXferQueueSize parameter in the DRV_USB_Device_PipeSetup() function. The queue contains transfer objects that hold information about the requested transfers. Multiple driver instance share one aggregate queue. The size of aggregate queue is defined by the DRV_USB_XFERS_NUMBER macro in the driver configuration. Pipe specific queues are formed from this aggregate queue. Figure 2 shows how this works. Figure 2: Pipe Transfer Queues. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-560 Figure 2a shows the aggregate driver queue. In this case, all the transfer objects in the queue are available for use. In figure 2b, the client creates a pipe (pipe 0) with a queue size of 1. This results in the first transfer object on the queue forming a single element queue for pipe 0. In figure 2c, the client creates a pipe (pipe 1) with a queue size of 3. This results in the next three transfer objects on the queue forming a 3 element queue for pipe 1. In figure 2d, the client creates a pipe (pipe 2) with a queue size of 4. This results in the next four transfer objects on the queue forming a 4 element queue for pipe 2. At this point, if a client tries to create another pipe with queue size of say 4, the pipe will not be created as there isn't enough space available in the queue. The size of the aggregate queue should be decided in such a way as to meet the application's dynamic requirements while taking the memory availability into consideration. 5.1.12.4.3.3.5 Pipe Stall The client can stall a pipe in response to USB events. When a pipe is stalled, it returns a STALL PID on the USB. The USB device firmware may stall endpoint 0 pipe when control requests from the host fail or are not supported. The driver automatically clears an endpoint 0 pipe stall when the host sends a SETUP packet. A non-zero endpoint pipe may be stalled when the endpoint's Halt feature is set. This is a functional stall. In this case the endpoint cannot send or receive data. Endpoint 0 pipe may not need to support functional stalls (although they can but this is rarely done). A pipe is stalled using the DRV_USB_Device_PipeStall() function and a pipe stall is cleared using the DRV_USB_Device_PipeStallClear() function. There are 3 execution threads where the driver client can stall a pipe. 1. A pipe can be stalled in the client event handler. The client can stall the pipe after receiving the USB_DEVICE_SETUP_TOKEN event. This is relevant to control transfer on endpoint 0 pipe. The firmware can stall the pipe if it does not support the command received in the Setup packet. It is recommended that both direction of the endpoint 0 pipe be stalled (this is possible because endpoint 0 pipe is always bi-directional). Figure 3 shows the transaction related to this case. Figure 3: Stalling Endpoint 0 pipe on a Control Read Transfer. Pipe is stalled after USB_DEVICE_SETUP_TOKEN event. The stall on the receive direction of the pipe will get cleared when the host issues a Setup token. The stall on the TX direction of the pipe needs to cleared by using the DRV_USB_Device_PipeStallClear() function. For endpoint 0 pipe, it is recommend that the stall on both directions be cleared. Note that is also possible to stall non-zero pipes in the USB_DEVICE_SETUP_TOKEN event. See code example below. void USBEventHandler (void * referenceHandle, 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-561 DRV_USB_EVENT eventType, DRV_USB_EVENT_DATA * eventData ) { switch ( eventType ) { /* There could be other events here as well. Only * the USB_DEVICE_SETUP_TOKEN is shown in this eaxample * for the sake of clarity */ case USB_DEVICE_SETUP_TOKEN: // Setup token received from host if(ProcessSetupPacket(eventData->setupEventData.pSetupPktBuffer) == false) { /* This means the command received in the setup packet is * not supported. The endpoint should be stalled. While * stalling endpoint 0, both directions should be stalled. * This ensures that both data stage and handshake stage * of the control transfer get stalled. */ DRV_USB_Device_PipeStall(pipe0, USB_EP_TX_RX); } else { /* Setup packet command can be processed */ if(DRV_USB_Device_PipeStatusGet(pipe0) == USB_PIPE_STALLED) { /* Clear the pipe stall */ DRV_USB_Device_PipeStallClear(pipe0, USB_EP_TX_RX); } } break; } } 2. A pipe can be stalled in the transfer complete event handler. This is more relevant to Control Write transfers. In the case of Control Write transfers, the transfer complete event handler is called after the data stage of the control transfer. If the firmware does not support the contents of the data stage, it can stall the pipe. This will result in the handshake stage of the control write transfer getting stalled. Figure 4 shows the transactions related to this case. Figure 4: Stalling Endpoint 0 pipe on a Control Write Transfer. Pipe is stalled in the Transfer Complete Callback Function. The following code snippet shows an example of this: void USBDeviceLayerXferCallback( void * referenceData, DRV_USB_PIPE_HANDLE hPipe, DRV_USB_XFER_HANDLE hTransfer, unsigned short int transferByteCount , DRV_USB_DEVICE_XFER_STATUS statusTransfer ) { /* Note that the transfer call contains the pipe * handle. This pipe handle can be used to * stall the pipe */ DRV_USB_Device_PipeStall(hPipe, USB_EP_TX_RX); } 3. A pipe can be stalled asynchronous of driver events. The client can stall a pipe based on device firmware logic. This is more applicable to non-zero endpoint pipes. Since these pipes are uni-directional, the client must specify the stall direction (USB_EP_TX or USB_EP_RX) while calling the DRV_USB_Device_PipeStall() function. Using the USB_EP_TX parameter will stall read transfers (IN tokens). Using the 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-562 USB_EP_RX parameter will stall write transfers (OUT tokens). 5.1.12.4.3.4 Event Handling Any client that opens the driver can register to receive USB events. These USB events can be used by the clients to achieve the desired functionality of the USB device. The first client to open the driver (typically the USB Stack device layer firmware) will receive additional events. The client uses the DRV_USB_Device_EventCallBackSet() to set the client event call back function. The following code snippet shows a client event handler function. /* This is the client event handler */ void ClientEventHandler (void * referenceHandle, DRV_USB_EVENT eventType, DRV_USB_EVENT_DATA * eventData ) { switch ( eventType ) { case USB_ERROR: // Bus error occurred and was reported in error interrupts break; case USB_DEVICE_RESET: // Host has commanded a device reset break; case USB_DEVICE_RESUME: // Resume detected while USB in suspend mode break; case USB_IDLE_DETECT: // Idle detected break; case USB_STALL: // Stall handshake has occurred break; case USB_DEVICE_SETUP_TOKEN: // A Setup token was received break; case USB_DEVICE_SETUP_HANDSHAKE: // Handshake stage of the control // transfer is completed. break; // Device received a Start of Frame case USB_DEVICE_GOT_SOF break; default: break; } } /* The client register the event handler * after it has opened the driver. referenceData * will be passed back to the event callback function * whenever it is invoked. */ DRV_USB_Device_EventCallBackSet(clientHandle, referenceData, ClientEventHandler); The eventData argument in the event callback function should be interpreted according to the event. The following table shows all the possible events and the value of eventData for each event. Event Type Event Details Interpretation of eventData USB_ERROR This event occurs when the USB module has detected an error on the bus eventData.usbErrorData.errorType contains a bitmap of errors (defined by USB_ERROR_TYPE) that have occurred. USB_DEVICE_RESET This event occurs when the USB module has detected a USB Reset NULL 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-563 USB_DEVICE_RESUME This event occurs when the USB module has detected Resume Signalling NULL USB_IDLE_DETECT This event occurs when the USB module has not detected any bus activity NULL USB_STALL This event occurs when a stalled endpoint has received a token eventData.stalledEnpoint.endpoint contains the stalled endpoint that recevied a token. USB_DEVICE_SETUP_TOKEN This event occurs when endpoint 0 has received a SETUP token eventData.setupEventData.pSetupPktBuffer points to a 8 byte array that contains the setup command that was received. USB_DEVICE_SETUP_HANDSHAKE This event occurs when the handshake stage of a Control Write Transfer has completed. NULL USB_DEVICE_GOT_SOF This event occurs when the USB module has received a start of frame. NULL The following code snippet shows the different USB errors that can occur USB_ERROR_TYPE error = eventData.usbErrorData.errorType; /* These are the possible errors that can occur. * Refer to the device specific data sheet for * more details on these errors. */ if (errorType & USB_ERR_INT_PID_CHECK_FAILURE) { /* Invalid or unsupported PID received */ } if ( errorType & USB_ERR_INT_BAD_CRC5) { /* A CRC 5 error was encountered */ } if ( errorType & USB_ERR_INT_BAD_CRC16) { /* A CRC 16 error was encountered */ } if ( errorType & USB_ERR_INT_BAD_DATA_FIELD_SIZE) { /* Unsupported data field size was encountered */ } if ( errorType & USB_ERR_INT_BUS_TURNAROUND_TIMEOUT) { /* A bus turn around timeout was encountered */ } if ( errorType & USB_ERR_INT_DMA_ERROR) { /* A USB DMA error was encountered */ } if ( errorType &= USB_ERR_INT_BUS_MATRIX_ERROR) { /* A Bus matrix error was encountered */ } if ( errorType & USB_ERR_INT_BIT_STUFF_ERROR) { /* A bit stuffing error was encountered */ } 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-564 5.1.12.4.3.5 Transfer Requests A USB Driver (operating in Device mode) client can receive and transmit data from the USB Host after creating a pipe. Data is transferred by using the DRV_USB_Device_TransferRequest() function. Four types of USB transfers are supported: Control, Bulk, Interrupt and Isochronous. The choice of transfer type depends on the nature of desired communication and the target functionality of the USB device. Requesting a transfer will cause the USB driver to schedule the transfer. The actual data communication takes place when the host has requested for the data. In cases where a transfer is already in progress and space is available on the pipe transfer queue, the transfer request is added to the queue and processed in turn. Transfers that are not in progress (pending in the queue) can be aborted by using the DRV_USB_Device_TransferAbort() function. Depending on the size of the endpoint and the amount of data to be transferred, the host may complete the transfer through multiple transactions. This process is handled by the driver and is transparent to the client. The client can register a transfer complete event callback function for each transfer request. This function is called when the transfer is terminated, either because its completed or aborted. Optionally the client can call the DRV_USB_Device_TransferStatusGet() function to poll the status of the transfer. The transfer complete event callback function need not be registered in this case. The DRV_USB_Device_TransferRequest() function also accepts flags that affect the processing of the transfer. The flag options are transfer type specific. The following section provides more details on how the four different transfer types can be requested: 5.1.12.4.3.5.1 Control Transfers The USB Driver supports Control Read and Write Transfers on a endpoint 0 pipe only. A control transfer (either read or write) occurs in stages: 1. The SETUP stage provides a setup command which among other things also defines if the transfer is a Control Read (data moves from device to host) or a Control Write transfer (data moves from host to device). 2. The DATA stage transports data related to the setup command in the SETUP stage. Depending on the size of the endpoint, the data stage could comprise of multiple IN or OUT transactions. A data stage may or may not be present in Control Write transfers. 3. The HANDSHAKE stage completes the Control transfer. Control Transfers should only be requested in response to a setup packet from the host. The USB Driver notifies its first client (via the client event call back function) when a SETUP packet has been received. Only the first client receives this, USB_DEVICE_SETUP_TOKEN, event. The driver generates USB_DEVICE_SETUP_HANDSHAKE client event at the completion of the handshake stage of the control write transfer. Refer to Event Handling section on more details on handling events. The client parses the 8-byte setup command available from the USB_DEVICE_SETUP_TOKEN, event. It then has the following options: 1. The client can request a control read transfer. 2. The client can request a control write transfer. 3. The client may not do anything and return from the event handler. In this case, the control transfer is treated as having no data stage and the transfer moves to the handshake stage. Note that a Control Read transfer must always have a data stage. 4. The client can stall the pipe. These cases are described here in detail. 1. Requesting a Control Read Transfer: The code snippet below shows an example of how a Control Read Transfer can be requested. In this transfer, data moves from the device to the host. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-565 /* This is an example of a Control Read Transfer. A control read * or Write transfer should be requested in response to a * USB_DEVICE_SETUP_TOKEN event. The transfer request function is * called in the USB event handler. In this example, the amount of * data to be transferred is 18 bytes. The transfer is requested * over endpoint 0 pipe. The USBDeviceLayerXferCallback() function * will be called when the transfer is terminated. The myUSBDevice * object will be passed back to the USBDeviceLayerXferCallback() * function. The USB_XFER_REGULAR indicates to the driver that this * transfer does not need a data stage ZLP */ DRV_USB_XFER_HANDLE xferHandle; void USBEventHandler (void * referenceHandle, DRV_USB_EVENT eventType, DRV_USB_EVENT_DATA * eventData ) { switch ( eventType ) { /* There could be other events here as well. Only * the USB_DEVICE_SETUP_TOKEN is shown in this eaxample * for the sake of clarity */ case USB_DEVICE_SETUP_TOKEN: // Setup token received from host ProcessSetupPacket(eventData->setupEventData.pSetupPktBuffer); xferHandle = DRV_USB_Device_TransferRequest(myUSBDevice.ep0Pipe, USB_XFER_CONTROL_READ, deviceDescriptor,18, USB_XFER_REGULAR, myUSBDevice, USBDeviceLayerXferCallback); if(DRV_HANDLE_INVALID == xferHandle) { /* If the transfer request failed, the * client can find out why. */ switch(DRV_USB_Device_PipeXferErrorGet(myUSBDevice.ep0Pipe)) { case USB_XFER_WRONG_PIPE: /* This means that either the transfer type or * does not match the pipe type or direction */ break; case USB_XFER_QUEUE_FULL: /* This means that the transfer queue on this * pipe is full. Either increase the queue size * by increasing the value of DRV_USB_XFERS_NUMBER * or wait for a slot on the queue to be available. */ break; default: break; } } } } In a case where the data to be transferred is more than the endpoint size reported to the host (also specified at the time when the control endpoint pipe is setup), the host will break up the data stage of the transfer into multiple transactions. This process is transparent to the client. If at any point a SETUP packet is received while the transfer was in progress, the transfer is aborted and client receives USB_DEVICE_SETUP_TOKEN event. If a transfer complete callback function was registered in the transfer request function, this callback function is called with transfer status as USB_XFER_ABORT. Figure 5 shows the generation of different events during the Control Read Transaction 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-566 Figure 5: Control Read Transfer. Data size is 18 bytes. Maximum Endpoint size is 64 bytes (> 18 bytes). A Control read transfer must have a data stage. In cases of control read transfers where the amount of data to be transferred is less than that requested by the host, the USB_XFER_SEND_ZLP flag must be specified. The driver will then check if the transfer size is an exact multiple of the endpoint size and then send a data stage zero length packet (ZLP). This indicates to the host that the device does not have any more data. There are two cases where specifying the USB_XFER_SEND_ZLP flag does not cause the driver to send a ZLP. - When the size of the transfer is less than requested size but is not an exact multiple of the maximum endpoint size. - The size of the transfer is less than maximum endpoint size. The following code snippet shows an example of a transfer request which sends a ZLP to the host. /* This is an example of a Control Read Transfer with the ZLP * option. Endpoint 0 maximum size is 8 bytes. The host has * requested 32 bytes but the device has only 24 bytes to send. * Specifying the USB_XFER_SEND_ZLP flag will cause the driver * to send a ZLP to the host in the fourth data transaction. */ DRV_USB_XFER_HANDLE xferHandle; xferHandle = DRV_USB_Device_TransferRequest(myUSBDevice.ep0Pipe, USB_XFER_CONTROL_READ, deviceDescriptor,24,USB_XFER_SEND_ZLP, myUSBDevice, USBDeviceLayerXferCallback); Figure 6 shows the generation of different events and the additional ZLP sent in data stage in a multi transaction Control Read Transfer. Figure 6: Multi Transaction Control Read Transfer with ZLP. Data size is 24 bytes and maximum endpoint size is 8 bytes. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-567 2. Requesting a Control Write Transfer: The code snippet below shows an example of how a Control Write Transfer can be requested. In this transfer, data moves from the host to device. The code example below shows an example of how a control write transfer is requested. Figure 7 shows the generation of different events related to the control write transfer. /* This is an example of a Control Write Transfer. A control read * or Write transfer should be requested in response to a * USB_DEVICE_SETUP_TOKEN event. The transfer request function is * called in the USB event handler. In this example, the amount of * data to be transferred is 32 bytes. The transfer is requested * over endpoint 0 pipe. The USBDeviceLayerXferCallback() function * will be called when the transfer is terminated. The myUSBDevice * object will be passed back to the USBDeviceLayerXferCallback() * function. The Control Write Transfer only supports the * USB_XFER_REGULAR flag. */ DRV_USB_XFER_HANDLE xferHandle; void USBDeviceLayerXferCallback( void * referenceData, DRV_USB_PIPE_HANDLE hPipe, DRV_USB_XFER_HANDLE hTransfer, unsigned short int transferByteCount , DRV_USB_DEVICE_XFER_STATUS statusTransfer ) { /* This function will be called when the transfer is complete. * In this case, the referenceData argument will point to the * myUSBDevice data object that was specified in the Transfer * request function. */ } void USBEventHandler (void * referenceHandle, DRV_USB_EVENT eventType, DRV_USB_EVENT_DATA * eventData ) { switch ( eventType ) { /* There could be other events here as well. Only * the USB_DEVICE_SETUP_TOKEN is shown in this eaxample * for the sake of clarity */ case USB_DEVICE_SETUP_TOKEN: // Setup token received from host ProcessSetupPacket(eventData->setupEventData.pSetupPktBuffer); xferHandle = DRV_USB_Device_TransferRequest(myUSBDevice.ep0Pipe, USB_XFER_CONTROL_WRITE, buffer,32, USB_XFER_REGULAR, myUSBDevice, USBDeviceLayerXferCallback); if(DRV_HANDLE_INVALID == xferHandle) { /* The DRV_USB_Device_PipeXferErrorGet() can be used to * find the error cause */ } } } In addition to the USB_DEVICE_SETUP_TOKEN event, the driver generates the USB_DEVICE_SETUP_HANDSHAKE event when the Control Write Handshake stage is complete. This event is generated even when the Control Write transfer does not have a data stage. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-568 Figure 7: Example of Control Write Transfer. Data size is 18 bytes and maximum endpoint size is 64 bytes (> 18 bytes). 3. Control Write Transfers with Zero Data Stage. A control write transfer can have zero data stages. One example of this is the SET ADDRESS command that the USB host send to the device during enumeration. In cases where no data stages are needed, the client should not request any transfer and return from the USB event handler. This will cause the driver to move the control transfer to the handshake stage. The USB_DEVICE_SETUP_HANDSHAKE can be used to track when the handshake stage of the transfer completes. In case of the SET ADDRESS command, the device layer firmware can change the device USB address in response to this event. The code example below shows an example of how this is done. /* This is an example of zero data stage Control Write transfer. * This is done by not issuing a transfer request after the * USB_DEVICE_SETUP_TOKEN event is received. */ DRV_USB_XFER_HANDLE xferHandle; void USBEventHandler (void * referenceHandle, DRV_USB_EVENT eventType, DRV_USB_EVENT_DATA * eventData ) { switch ( eventType ) { /* There could be other events here as well. Only * the USB_DEVICE_SETUP_TOKEN is shown in this eaxample * for the sake of clarity */ case USB_DEVICE_SETUP_TOKEN: /* Setup token received from host. In this case we assume * that this is the SET ADDRESS command. This command does * not have a data stage. So the client does not do a * transfer request*/ ProcessSetupPacket(eventData->setupEventData.pSetupPktBuffer); break; case USB_DEVICE_SETUP_HANDSHAKE: /* The last control write transfer request is complete. * In this example, the client can change the device USB address * now. */ DRV_USB_Device_AddressSet(deviceLayer, address); break; default: break; } } Figure 8 shows the generation of different events related to the transfer. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-569 Figure 8: Example of Zero data stage Control Write Transfer. 4.Stalling the Pipe: Refer to Pipe Stall section for more details on how a pipe can be stalled. 5.1.12.4.3.5.2 Bulk and Interrupt Transfers The driver can process Bulk and Interrupt transfers. On the USB, both Bulk and Interrupt transfers have the same packet structure. The following discussion therefore applies to both Bulk and Interrupt transfers. A client should use the DRV_USB_Device_TransferRequest() function to schedule Bulk and Interrupt transfers. The following sections describe Bulk/Interrupt Read Transfers and Bulk/Interrupt Write Transfers. 1. Bulk/Interrupt Read Transfers: In this transfer, data moves from device to host. The client can request a bulk/interrupt read transfer with a byte size greater than the maximum endpoint size. In this case the driver will complete the transfer and invoke the transfer complete callback function if provided. If the USB_XFER_SEND_ZLP flag is specified, the driver sends a ZLP after the last transaction if the transfer size was an exact multiple of the endpoint size. The following code snippet shows an example of a Bulk/Interrupt read transfer can be requested /* This code snippet shows an example of how a Bulk/Interrupt * read transfer can be requested */ DRV_USB_XFER_HANDLE transferHandle; transferHandle = DRV_USB_Device_TransferRequest(pipe1, USB_XFER_BULK_READ, data,120,USB_XFER_REGULAR, someReferenceData ,XferCompleteCallback); /* This transfer directs the driver to send a ZLP * after the last transaction */ transferHandle = DRV_USB_Device_TransferRequest(pipe1, USB_XFER_BULK_READ, data,128,USB_XFER_SEND_ZLP, someReferenceData ,XferCompleteCallback); Figure 9 shows a regular bulk/interrupt read transfer. Figure 10 shows a bulk/interrupt read transfer with a ZLP. Figure 9: Example of Bulk/Interrupt Read Transfer. Requested transfer size is 120 bytes. Maximum endpoint size 64 Figure 10: Example of Bulk/Interrupt Read Transfer with ZLP. Requested transfer size is 128 bytes. Maximum endpoint 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-570 size 64 2. Bulk/Interrupt Write Transfers: In this transfer, data moves from host to device. These transfers only support USB_XFER_REGULAR flag. The client can request a bulk/interrupt write transfer with a byte size greater than the maximum endpoint size. . In this case however, the driver will invoke the transfer complete callback function when a transaction completes. The callback thus gets invoked whenever the host sends any amount of data. Since the amount of data that the host sends in one transaction will not exceed the maximum endpoint size, specifying a transfer size greater than maximum endpoint size will not have any effect. The client must schedule another transfer to receive more data from the host. The following code snippet shows an example of bulk/interrupt write transfer. /* This code snippet shows an example of how a Bulk/Interrupt * write transfer can be requested. Note the data size is * equal the size of the endpoint. The client has queued up * multiple transfers.*/ DRV_USB_XFER_HANDLE transferHandle1; DRV_USB_XFER_HANDLE transferHandle1; transferHandle1 = DRV_USB_Device_TransferRequest(pipe2, USB_XFER_BULK_WRITE, data,64,USB_XFER_REGULAR, someReferenceData ,XferCompleteCallback); transferHandle1 = DRV_USB_Device_TransferRequest(pipe2, USB_XFER_BULK_WRITE, data,64,USB_XFER_REGULAR, someReferenceData ,XferCompleteCallback); Figure 11 shows a bulk/interrupt write transfer with related events Figure 11: Example of Bulk/Interrupt Write Transfer. Client has scheduled two tranfers Maximum endpoint size 64 5.1.12.4.3.5.3 Isochronous Transfers A client can request Isochronous transfers by using the DRV_USB_Device_TransferRequest() function. On the USB, Isochronous transfers are characterized by the absence of the handshake stage. The driver supports USB_XFER_REGULAR and USB_XFER_PERSIST flags for Isochronous transfers. While using the USB_XFER_REGULAR flag, the transfer request behavior is similar to Bulk and Interrupt Read/Write Transfer Requests. In that, a new transfer will require the client to call the DRV_USB_Device_TransferRequest() function. By using the USB_XFER_PERSIST flag, the driver will not discard the transfer after the transfer is complete. Instead, after the transfer is complete, the transfer is rescheduled in the queue. This way the client does not have to schedule another transfer. If the client has scheduled two Isochronous transfers with the USB_XFER_PERSIST flag, the driver will ping pong between these transfers. The transfer complete callback function is called when the transfer is completed. The code snippet below shows an example of setting up two Isochronous read transfers to create a ping pong type of transfer system. DRV_USB_XFER_HANDLE pingTransferHandle; DRV_USB_XFER_HANDLE pongTransferHandle; /* Request two transfers. Note how the USB_XFER_PERSIST flag * is specified. Note also how the pingData and pongData buffer * pointers are specified as reference data. This will make * processing in the transfer complete call back easier.. */ pingTransferHandle = DRV_USB_Device_TransferRequest(pipe0, USB_XFER_CONTROL_READ, pingData,64,USB_XFER_PERSIST, pingData ,PingXferCompleteCallback); pongTransferHandle = DRV_USB_Device_TransferRequest(pipe0, USB_XFER_CONTROL_READ, pongData,40,USB_XFER_PERSIST, pongData ,PongXferCompleteCallback); /* This is the Ping transfer Complete callback */ void PingCompleteCallback( void * referenceData, DRV_USB_PIPE_HANDLE hPipe, DRV_USB_XFER_HANDLE hTransfer, 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-571 unsigned short int transferByteCount , DRV_USB_DEVICE_XFER_STATUS statusTransfer ) { /* Note that we dont schedule one more request here. * We just add data to the buffer and return. This * same transfer will be processed again. The referenceData * points to the ping data buffer (as set in the transfer request * function. */ void * data = referenceData; UpdateBuffer(data); } /* This is the Ping transfer Complete callback */ void PongCompleteCallback( void * referenceData, DRV_USB_PIPE_HANDLE hPipe, DRV_USB_XFER_HANDLE hTransfer, unsigned short int transferByteCount , DRV_USB_DEVICE_XFER_STATUS statusTransfer ) { /* Note that we dont schedule one more request here. * We just add data to the buffer and return. This * same transfer will be processed again. The referenceData * points to the pong data buffer (as set in the transfer request * function. */ void * data = referenceData; UpdateBuffer(data); } 5.1.12.4.3.5.4 Transfer Status The driver offers to different interface to track the status of a transfer, a polling interface and a callback interface. Both these interfaces can be invoked by the application. The two interfaces are discussed here: 1. Polling interface: The client can access the polling interface by using the DRV_USB_Device_XferStatusGet() function. This interface does not provide information when a transfer is aborted. The following code snippet shows how DRV_USB_Device_XferStatusGet() is used. /* This code snippet shows the different * values that the DRV_USB_Device_XferStatusGet() * function. This function implements the polling * interface for the transfer status. */ DRV_USB_DEVICE_XFER_STATUS transferStatus; transferStatus = DRV_USB_Device_XferStatusGet(transferHandle); switch(transferStatus) { case USB_XFER_PENDING: /* This means the transfer is still in the transfer * queue. This transfer can be aborted.*/ case USB_XFER_IN_PROGRESS: /* This means the transfers is currently in progress * on the bus. This transfer cannot be aborted. */ case USB_XFER_COMPLETED: /* This measn the transfer is complete */ default: break; } 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-572 2. Callback interface: The callback interface to track the status of the transfer is implemented by using Transfer Complete Callback function. The client should specify the Transfer Complete Callback function when calling DRV_USB_Device_TransferRequest() function. The driver call this function when a transfer has terminated, either due to the transfer completing or the transfer aborting. The Transfer Complete Callback function should be of the type DRV_USB_XFER_COMPLETE_CALLBACK. The driver returns the following information while calling the Transfer Complete Callback function. 1. Handle to the pipe that contained this transfer 2. Handle to the transfer 3. Number of bytes read or written 4. A reference to a data object that was specified in the DRV_USB_Device_TransferRequest() for this transfer. 5. Transfer termination status The following code snippet shows an example of how a Transfer Complete Callback function can be used. /* This code snippet shows an example of how to use the * transfer complete callback */ DRV_USB_XFER_HANDLE transferHandle; /* Request a transfer. Note that the reference data pointer is set * to dataBuffer and the transfer complete callback function * XferCompleteCallback is specified. */ transferHandle = DRV_USB_Device_TransferRequest(pipe0, USB_XFER_CONTROL_READ, dataBuffer,18,false, dataBuffer ,XferCompleteCallback); /* This is the transfer Complete callback */ void XferCompleteCallback( void * referenceData, DRV_USB_PIPE_HANDLE hPipe, DRV_USB_XFER_HANDLE hTransfer, unsigned short int transferByteCount , DRV_USB_DEVICE_XFER_STATUS statusTransfer ) { /* The referenceData variable (the value of which * is specified in the transfer request function) * points to the data buffer associate with the * transfer. */ void * dataBuffer = referenceData; if(transferStatus == USB_XFER_COMPLETED) { ProcessDataBuffer(dataBuffer, transferByteCount); } else if(transferStatus == USB_XFER_ABORTED) { /* This transfer was not successful. Take any * remedial action as needed. */ } } 5.1.12.4.3.5.5 Transfer Abort A client can abort a USB transfer that it requested. This is achieved by using the DRV_USB_Device_TransferAbort() function. A Control read or write transfer can automatically get aborted when the host issues a SETUP token out of turn. The DRV_USB_Device_TransferAbort() will not abort a transfer if it is already in progress. Closing the pipe will however abort transfers that are in progress. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-573 When a transfer is aborted, the Transfer Complete Callback function associated with the transfer is not invoked. If the Control Read or Write transfer was aborted due to a out of turn SETUP token from the host, Transfer Complete Callback function will be called and transfer status will be USB_XFER_ABORTED. 5.1.12.5 Configuring the Library The configuration of the USB Driver is based on the file sys_config.h This header file contains the configuration selection for the USB Driver. Based on the selections made, the USB Driver will support or not support selected features. Some configuration settings will apply to all instances of the USB Driver while some configurations settings are applicable only if the driver is built for a static mode. This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.12.5.1 Initialization Overrides This section lists out the macros that need to be configured when building the static version of the driver. These values should be defined for correction operation of the driver, when the driver is built statically. Commenting the DRV_USB_INSTANCES_NUMBER macro will cause the driver to be built in a static mode. 5.1.12.5.2 Others These macros affect all instances and all build types of the driver. 5.1.12.6 Building the Library The following table lists the USB Driver files to be included in the project for the available features Features File Path Comments Needed for all features driver/usb/drv_usb.h Must be included in every source code file that access the driver API. Dynamic Build driver/usb/src/dynamic/drv_usb.c Must be included when using the dynamic version of the driver Static Multi-Client Build driver/usb/src/static_multi/drv_usb_static_multi.c Must be included when using the static multi client version of the driver 5.1.12.7 Library Interface Data Types and Constants Name Description DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE DRV_USB_HOST_PIPE_HANDLE_INVALID Defines the USB Driver Host Pipe Invalid handle DRV_USB_INDEX This is macro DRV_USB_INDEX. DRV_USB_INDEX_0 USB driver index definitions DRV_USB_INTERRUPT_SOURCE This is macro DRV_USB_INTERRUPT_SOURCE. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-574 DRV_USB_PERIPHERAL_ID This is macro DRV_USB_PERIPHERAL_ID. DRV_USB_EVENT Identifies the different events that the USB Driver provides. DRV_USB_EVENT_CALLBACK Type of the USB event callback function DRV_USB_HOST_PIPE_HANDLE Defines the USB Driver Host Pipe handle type DRV_USB_INIT Contains all the data necessary to initialize the USB device Client Functions Name Description DRV_USB_Close Closes an opened-instance of the USB driver DRV_USB_Open Opens the specified USB driver instance and returns a handle to it Other Functions Name Description DRV_USB_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the a client of USB bus events. DRV_USB_DEVICE_AddressSet This function will set the USB module address that is obtained from the host. DRV_USB_DEVICE_Attach This function will attach the device to the USB. DRV_USB_DEVICE_CurrentSpeedGet This function will return the USB speed at which device is operating. DRV_USB_DEVICE_Detach This function will detach the device from the USB. DRV_USB_DEVICE_EndpointDisable This function disables an endpoint. DRV_USB_DEVICE_EndpointDisableAll This function disables all provisioned non-zero endpoints. DRV_USB_DEVICE_EndpointEnable This function enables a endpoint for the specified direction and endpoint size. DRV_USB_DEVICE_EndpointIsEnabled This function returns the enable/ disable status of the specified endpoint and direction. DRV_USB_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USB_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. DRV_USB_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USB_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USB_DEVICE_IRPSubmit This function submits a I/O Request Packet (IRP) for processing to the USB Driver. DRV_USB_HOST_BusResetControl This is function DRV_USB_HOST_BusResetControl. DRV_USB_HOST_DeviceCurrentSpeedGet This is function DRV_USB_HOST_DeviceCurrentSpeedGet. DRV_USB_HOST_IRPCancel This is function DRV_USB_HOST_IRPCancel. DRV_USB_HOST_IRPSubmit This is function DRV_USB_HOST_IRPSubmit. DRV_USB_HOST_OperationEnable This is function DRV_USB_HOST_OperationEnable. DRV_USB_HOST_StartOfFrameControl This is function DRV_USB_HOST_StartOfFrameControl. DRV_USB_HOST_TimerIsComplete This is function DRV_USB_HOST_TimerIsComplete. DRV_USB_HOST_TimerReset This is function DRV_USB_HOST_TimerReset. DRV_USB_HOST_TimerStart This is function DRV_USB_HOST_TimerStart. DRV_USB_Tasks Maintains the driver's state machine when the driver is configured for polled mode. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-575 Pipe Functions Name Description DRV_USB_HOST_PipeSetup This is function DRV_USB_HOST_PipeSetup. DRV_USB_HOST_PipeClose This is function DRV_USB_HOST_PipeClose. System Functions Name Description DRV_USB_Initialize Initializes the USB driver DRV_USB_Status Provides the current status of the USB driver module DRV_USB_Tasks_ISR Maintains the driver's state machine and implements its ISR DRV_USB_HOST_OperationIsEnabled This is function DRV_USB_HOST_OperationIsEnabled. Description This section describes the APIs of the USB Driver. Refer to each section for a detailed description. 5.1.12.7.1 System Functions 5.1.12.7.1.1 DRV_USB_Initialize Function C SYS_MODULE_OBJ DRV_USB_Initialize( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ); Description This routine initializes the USB driver, making it ready for clients to open and use it. Preconditions None. Parameters Parameters Description drvIndex Ordinal number of driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. This should be a DRV_USB_INIT structure reference type casted to SYS_MODULE_INIT reference. Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to DRV_USB_Status routines. Remarks This routine must be called before any other USB routine is called. This routine should only be called once during system initialization unless DRV_USB_Deinitialize is called to de-initialize the driver instance. If the driver is built for static mode, then the initialization data structure is ignored. The static overrides provided in system_config.h are considered instead. Example // The following code snippet shows an example initialization of the // driver. The USB module to be used is USB1. The module should not // automatically suspend when the microcontroller enters Sleep mode. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-576 // The module should continue operation when the module enters Idle // mode. The power state is set to run at full clock speeds. Device // Mode operation should be at FULL speed. DRV_USB_INIT moduleInit; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USB_OPERATION_MODE_DEVICE; usbInitData.pingpongMode = USB_PING_PONG_FULL_PING_PONG; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); 5.1.12.7.1.2 DRV_USB_Status Function C SYS_STATUS DRV_USB_Status( SYS_MODULE_OBJ object ); Description This routine provides the current status of the USB driver module. Preconditions Function DRV_USB_Initialize must have been called before calling this Parameters Parameters Description object Driver object handle, returned from the DRV_USB_Initialize routine Returns • SYS_STATUS_READY - Indicates that the driver is ready • SYS_STATUS_UNINITIALIZED - Indicates that the driver has never been initialized Remarks None. Example SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize SYS_STATUS status; DRV_USB_INIT moduleInit; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USB_OPERATION_MODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-577 // function. object = DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); status = DRV_USB_Status(object); if(SYS_STATUS_READY == status) { // Driver is ready to be opened. } 5.1.12.7.1.3 DRV_USB_Tasks_ISR Function C void DRV_USB_Tasks_ISR( SYS_MODULE_OBJ object ); Description This routine is used to maintain the driver's internal state machine and implement its ISR for interrupt-driven implementations. Preconditions The DRV_USB_Initialize routine must have been called for the specified USB driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USB_Initialize) Returns None Remarks This routine should be called from the USB interrupt service routine. In case of multiple USB modules, it should be ensured that the correct USB driver system module object is passed to the this routine. Example SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize while (true) { DRV_USB_Tasks_ISR (object); // Do other tasks } 5.1.12.7.1.4 DRV_USB_HOST_OperationIsEnabled Function C bool DRV_USB_HOST_OperationIsEnabled( DRV_HANDLE hClient ); Description This is function DRV_USB_HOST_OperationIsEnabled. 5.1.12.7.2 Client Functions 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-578 5.1.12.7.2.1 DRV_USB_Close Function C void DRV_USB_Close( DRV_HANDLE handle ); Description This routine closes an opened-instance of the USB driver, invalidating the handle. Preconditions The DRV_USB_Initialize routine must have been called for the specified USB driver instance. DRV_USB_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_USB_Open before the caller may use the driver again. Example DRV_HANDLE handle; // Returned from DRV_USB_Open DRV_USB_Close(handle); 5.1.12.7.2.2 DRV_USB_Open Function C DRV_HANDLE DRV_USB_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ); Description This routine opens the specified USB driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The intent flag should always be DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NON_BLOCKING. Anyother setting of the intent flag will return a invalid driver handle. A driver instance can only support one client. Trying to open a driver that has an existing client will result in an unsuccessful function call. Preconditions Function DRV_USB_Initialize must have been called before calling this function. Parameters Parameters Description drvIndex Driver instance that client will use intent Should always be DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-579 Returns If successful, valid driver handle for the client to use when interfacing with the driver. If an error occurs, the return value is DRV_HANDLE_INVALID. Remarks The handle returned is valid until the DRV_USB_Close routine is called. Example // Shows an example of how to open the driver. SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize SYS_STATUS status; DRV_USB_INIT moduleInit; DRV_HANDLE handle; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USB_OPERATION_MODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.suspendInSleep = false; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. object = DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); status = DRV_USB_Status(object); if(SYS_STATUS_READY == status) { // Driver is ready to be opened. handle = DRV_USB_Open(DRV_USB_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); SYS_ASSERT(DRV_HANDLE_INVALID != handle,"Bad handle returned"); } 5.1.12.7.3 Pipe Functions 5.1.12.7.3.1 DRV_USB_HOST_PipeSetup Function C DRV_USB_HOST_PIPE_HANDLE DRV_USB_HOST_PipeSetup( DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed ); Description This is function DRV_USB_HOST_PipeSetup. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-580 5.1.12.7.3.2 DRV_USB_HOST_PipeClose Function C void DRV_USB_HOST_PipeClose( DRV_USB_HOST_PIPE_HANDLE pipeHandle ); Description This is function DRV_USB_HOST_PipeClose. 5.1.12.7.4 Transfer Functions 5.1.12.7.5 Other Functions 5.1.12.7.5.1 DRV_USB_ClientEventCallBackSet Function C void DRV_USB_ClientEventCallBackSet( DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK myEventCallBack ); Description This function sets up the event callback function that is envoked by the USB controller driver to notify the client of USB bus events. The call back is disabled by not calling this function after a USB_DRV_Open or by passing NULL for the myEventCallBack argument. When the callback function is called, the hReferenceData argument is returned. Preconditions None. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) hReferenceData object (could be a pointer) that is returned with the callback. myEventCallBack Call back function for all USB events. Returns None. Remarks Typical usage of the USB Driver requires a client to register a callback. Example // Set the client event callback for the Device Layer. // The USBDeviceLayerEventHandler() function is the event // handler. When this event handler is invoked by the // driver, the driver returns back the second argument // specified in the below function (which in this case // is the device layer data structure). This allows the // application firmware to identify, as an example, the // device layer object associated with this callback // 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-581 DRV_USB_ClientEventCallBackSet(myUSBDevice.usbDriverHandle, (uintptr_t)&myUSBDevice, USBDeviceLayerEventHandler); 5.1.12.7.5.2 DRV_USB_DEVICE_AddressSet Function C void DRV_USB_DEVICE_AddressSet( DRV_HANDLE handle, uint8_t address ); Description This function will set the USB module address that is obtained from the host in a setup transaction. The address is obtained from the SET_ADDRESS command issued by the host. The primary (first) client of the driver uses this function to set the module's USB address after decoding the setup transaction from the host. Preconditions None. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) address The address of this module on the USB bus Returns None. Remarks None. Example // This function should be called by the first client of the driver, // which is typically the device layer. The address to set is obtained // from the host during enumeration. DRV_USB_DEVICE_AddressSet(deviceLayer, 4); 5.1.12.7.5.3 DRV_USB_DEVICE_Attach Function C void DRV_USB_DEVICE_Attach( DRV_HANDLE handle ); Description This function will attach the device to the USB. It does this by enabling the pull up resistors on the D+ or D- lines. This function should be called when the driver client is ready to receive communication from the host (typically after all initialization is complete). Preconditions Client handle should be valid. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-582 Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) Returns None. Remarks None. Example // Open the device driver and attach the device to the USB. SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize SYS_STATUS status; DRV_USB_INIT moduleInit; DRV_HANDLE handle; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USB_OPERATION_MODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. object = DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); status = DRV_USB_Status(object); if(SYS_STATUS_READY == status) { // Driver is ready to be opened. handle = DRV_USB_Open(DRV_USB_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); SYS_ASSERT(DRV_HANDLE_INVALID != handle,"Bad handle returned"); // Register a callback DRV_USB_ClientEventCallBackSet(handle, (uintptr_t)&myDeviceLayer, MyDeviceLayerEventCallback); // Perform any other initialization here and then attach the device // to the bus. DRV_USB_DEVICE_Attach(handle); } 5.1.12.7.5.4 DRV_USB_DEVICE_CurrentSpeedGet Function C USB_SPEED DRV_USB_DEVICE_CurrentSpeedGet( DRV_HANDLE handle ); Description This function will return the USB speed at which device is operating. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-583 Preconditions Only valid after device is attached to host. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) Returns Returns a member of the USB_SPEED type. Remarks None. Example // Get the current speed. USB_SPEED deviceSpeed; deviceSpeed = DRV_USB_DEVICE_CurrentSpeedGet(deviceLayer); if(deviceLayer == USB_SPEED_HIGH) { // Possibly adjust buffers for higher throughput. } 5.1.12.7.5.5 DRV_USB_DEVICE_Detach Function C void DRV_USB_DEVICE_Detach( DRV_HANDLE handle ); Description This function will detach the device from the USB. It does this by disabling the pull up resistors on the D+ or D- lines. This function should be called when the application wants to disconnect the device from the bus (typically to implement a soft detach or switch to host mode operation). Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) Returns None. Remarks None. Example // Detach the device from the USB DRV_USB_DEVICE_Detach(handle); 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-584 5.1.12.7.5.6 DRV_USB_DEVICE_EndpointDisable Function C USB_ERROR DRV_USB_DEVICE_EndpointDisable( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ); Description This function disables an endpoint. If the endpoint type is control type then both directions are disabled. For non-control endpoints, the function disables one direction at a time. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks None. Example // This code snippet shows an example of how to disable // a control endpoint. Note that the direction parameter is ignored. // For a control endpoinnt, both the directions are disabled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USB_DEVICE_EndpointDisable(handle, ep ); // This code snippet shows an example of how to disable a BULK IN // endpoint USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USB_DEVICE_EndpointDisable(handle, ep ); 5.1.12.7.5.7 DRV_USB_DEVICE_EndpointDisableAll Function C USB_ERROR DRV_USB_DEVICE_EndpointDisableAll( DRV_HANDLE handle ); Description This function disables all provisioned endpoints in both directions. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-585 Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) Returns None. Remarks This function is typically called by the USB Device Layer to disable all endpoints on detecting bus reset. Example // This code snippet shows an example of how to disable // all endpoints. DRV_USB_DEVICE_EndpointDisableAll(handle); 5.1.12.7.5.8 DRV_USB_DEVICE_EndpointEnable Function C USB_ERROR DRV_USB_DEVICE_EndpointEnable( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize ); Description This function enables a endpoint for the specified direction and endpoint size. The function will enable the endpoint for communication in one direction at a time. It must be called twice if the endpoint is required to communicate in both the directions, except for control endpoints. If the endpoint type is a control endpoint, the endpoint is always bi-directional and the function needs to be called only once. The size of the endpoint must match the wMaxPacketSize reported in the endpoint descriptor for this endpoint. The function does not check if the endpoint is already in use. It is the client's responsibility to make sure that a endpoint is not accidently re-used. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. transferType Should be USB_TRANSFER_TYPE_CONTROL for control endpoint, USB_TRANSFER_TYPE_BULK for bulk endpoint, USB_TRANSFER_TYPE_INTERRUPT for interrupt endpoint and USB_TRANSFER_TYPE_ISOCHRONOUS for isochronous endpoint. endpointSize Maximum size (in bytes) of the endpoint as reported in the endpoint descriptor. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-586 Remarks None. Example // This code snippet shows an example of how to enable endpoint // 0 for control transfers. Note that for a control endpoint, the // direction parameter is ignored. A control endpoint is always // bi-directional. Endpoint sizeis 64 bytes. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_CONTROL, 64); // This code snippet shows an example of how to set up a endpoint // for BULK IN transfer. For an IN transfer, data moves from device // to host. In this example, endpoint 1 is enabled. The maximum // packet size is 64. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); // If endpoint 1 must also be set up for BULK OUT, then the enable // function must be called again, as shown here. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); DRV_USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); 5.1.12.7.5.9 DRV_USB_DEVICE_EndpointIsEnabled Function C bool DRV_USB_DEVICE_EndpointIsEnabled( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection ); Description This function returns the enable/ disable status of the specified endpoint and direction. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. Returns Returns true if the endpoint is enabled, false otherwise. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-587 Example // This code snippet shows an example of how the // DRV_USB_DEVICE_EndpointIsEnabled() function can be used to obtain the // status of the endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(DRV_USB_ENDPOINT_STATE_DISABLED == DRV_USB_DEVICE_EndpointIsEnabled(handle, ep)) { // Endpoint is disabled. Enaable endpoint. DRV_USB_DEVICE_EndpointEnable(handle, ep, USB_ENDPOINT_TYPE_BULK, 64); } 5.1.12.7.5.10 DRV_USB_DEVICE_EndpointIsStalled Function C bool DRV_USB_DEVICE_EndpointIsStalled( DRV_HANDLE client, USB_ENDPOINT endpoint ); Description This function returns the stall status of the specified endpoint and direction. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. Returns Returns true if endpoint is stalled, false otherwise. Remarks None. Example // This code snippet shows an example of how the // DRV_USB_DEVICE_EndpointIsStalled() function can be used to obtain the // stall status of the endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(true == DRV_USB_DEVICE_EndpointIsStalled (handle, ep)) { // Endpoint stall is enabled. Clear the stall. DRV_USB_DEVICE_EndpointStallClear(handle, ep); } 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-588 5.1.12.7.5.11 DRV_USB_DEVICE_EndpointStall Function C USB_ERROR DRV_USB_DEVICE_EndpointStall( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ); Description This function stalls an endpoint in the specified direction. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks None. Example // This code snippet shows an example of how to stall an endpoint. In // this case , endpoint 1 IN direction is stalled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USB_DEVICE_EndpointStall(handle, ep); 5.1.12.7.5.12 DRV_USB_DEVICE_EndpointStallClear Function C USB_ERROR DRV_USB_DEVICE_EndpointStallClear( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ); Description This function clears the stall on an endpoint in the specified direction. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-589 Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks None. Example // This code snippet shows an example of how to clear a stall. In this // example. the stall on endpoint 1 IN direction is cleared. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USB_DEVICE_EndpointStallClear(handle, ep); 5.1.12.7.5.13 DRV_USB_DEVICE_IRPCancelAll Function C USB_ERROR DRV_USB_DEVICE_IRPCancelAll( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection ); Description This function cancels all IRPs that are queued and in progress at the specified endpoint. Preconditions Client handle should be valid. Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks None. Example // This code snippet shows an exampl of how to cancel all IRPs. void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if this is setup command if(irp->status == USB_DEVICE_IRP_STATUS_SETUP) { if(IsSetupCommandSupported(irp->data) == false) { // This means that this setup command is not // supported. Stall the endpoint. DRV_USB_DEVICE_IRPCancelAll(handle, ep); 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-590 DRV_USB_DEVICE_EndpointStall(handle, ep); } } } 5.1.12.7.5.14 DRV_USB_DEVICE_IRPSubmit Function C USB_ERROR DRV_USB_DEVICE_IRPSubmit( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp ); Description This function submits a I/O Request Packet (IRP) for processing to the USB Driver. The IRP allows a client to send and receive data from the USB Host. The data will sent or received through the specified endpoint. The direction of the data transfer is indicated by the direction flag in the endpointAndDirection structure. Submitting an IRP arms the endpoint to either send data to or receive data from the host. If an IRP is under progress on the endpoint, then the subsequent IRP submit operation will result in the IRPs getting queued. The contents of the IRP should not be changed till the IRP has been processed. Particular attention should be paid to the size parameter of IRP. The following should be noted: • The size parameter while sending data to the host can be less than, greater than, equal to or be an exact multiple of maximum packet size for the endpoint. The maximum packet size for the endpoint determines the number of transactions required to process the IRP. • If the size parameter while sending data to the host is less than maximum packet size, the transfer will complete in one transaction. • If the size parameter while sending data to the host is greater than maximum packet size, the IRP will be processed in mulitple transactions. • If the size parameter while sending data to the host is equal to or an exact multiple of the maximum packet size, the client can optionally ask the driver to send a Zero Length packet by specifying the USB_DEVICE_IRP_FLAG_DATA_COMPLETE flag as the flag parameter. • The size parameter while receiving data from the host must be an exact multiple of the maximum packet size of the endpoint. If this is not the case, the driver will return a USB_ERROR_IRP_SIZE_INVALID result. If while processing the IRP, the driver receives less than maximum packet size or a ZLP from the host, the driver considers the IRP as processed. The size paramter at this point contains the actual amount of data received from the host. The IRP status is returned as USB_DEVICE_IRP_STATUS_COMPLETED_SHORT. • If a ZLP needs to be sent to host, the IRP size should be specified as 0 and flag should be set as USB_DEVICE_IRP_FLAG_DATA_COMPLETE. • If the IRP size is an exact multiple of endpoint size, the client can request the driver to not send a ZLP, by specifying the USB_DEVICE_IRP_FLAG_DATA_PENDING. This flag indicates that there is more data pending in this transfer. • Specifying a size less than endpoint size along with the USB_DEVICE_IRP_FLAG_DATA_PENDING flag will cause the driver to return a USB_ERROR_IRP_SIZE_INVALID. • If the size id greater than endpoint size, and the flag is specified as USB_DEVICE_IRP_FLAG_DATA_PENDING, the driver will send multiple of endpoint size data. Preconditions Client handle should be valid. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-591 Parameters Parameters Description handle Client's driver handle (returned from DRV_USB_Open) endpointAndDirection Specifies the endpoint and direction. irp Pointer to the USB_DEVICE_IRP structure. Returns USB_ERROR_NONE - if the IRP was submitted successful. USB_ERROR_IRP_SIZE_INVALID - if the size parameter of the IRP is not correct. USB_ERROR_IRP_QUEUE_FULL - if the driver IRP queue is full. Remarks None. Example // The following code snippet shows an example of how to schedule a // IRP to send data from device to host. Assume that max packet size // is 64 and endpoint is 1. In this example, the transfer is // processed as 3 transactions of 64, 64 and 2 bytes. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (DRV_USB_DEVICE_IRPSubmit(handle, ep, irp) != USB_ERROR_NONE) { // This means there was an error. } else { // The status of the IRP can be checked. while(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Wait or run a task routine. } } // The following code snippet shows how the client can request // the driver to send a ZLP when the size is an exact multiple of // end point size. irp.data = myDataBufferToSend; irp.size = 128; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; // Note that while receiving data from the host, the size should // be an exact multiple maximum packet size of the endpoint. In the // example below, the DRV_USB_DEVICE_IRPSubmit() function will // return a USB_DEVICE_IRP_SUBMIT_RESULT_INVALID_SIZE value. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-592 irp.data = myDataBufferToSend; irp.size = 60; // THIS SIZE IS NOT CORRECT irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; 5.1.12.7.5.15 DRV_USB_HOST_BusResetControl Function C void DRV_USB_HOST_BusResetControl( DRV_HANDLE client, bool control ); Description This is function DRV_USB_HOST_BusResetControl. 5.1.12.7.5.16 DRV_USB_HOST_DeviceCurrentSpeedGet Function C USB_SPEED DRV_USB_HOST_DeviceCurrentSpeedGet( DRV_HANDLE client ); Description This is function DRV_USB_HOST_DeviceCurrentSpeedGet. 5.1.12.7.5.17 DRV_USB_HOST_IRPCancel Function C void DRV_USB_HOST_IRPCancel( USB_HOST_IRP * inputIRP ); Description This is function DRV_USB_HOST_IRPCancel. 5.1.12.7.5.18 DRV_USB_HOST_IRPSubmit Function C USB_ERROR DRV_USB_HOST_IRPSubmit( DRV_USB_HOST_PIPE_HANDLE hPipe, USB_HOST_IRP * inputIRP ); Description This is function DRV_USB_HOST_IRPSubmit. 5.1.12.7.5.19 DRV_USB_HOST_OperationEnable Function C void DRV_USB_HOST_OperationEnable( DRV_HANDLE hClient, bool enable ); 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-593 Description This is function DRV_USB_HOST_OperationEnable. 5.1.12.7.5.20 DRV_USB_HOST_StartOfFrameControl Function C void DRV_USB_HOST_StartOfFrameControl( DRV_HANDLE client, bool control ); Description This is function DRV_USB_HOST_StartOfFrameControl. 5.1.12.7.5.21 DRV_USB_HOST_TimerIsComplete Function C bool DRV_USB_HOST_TimerIsComplete( DRV_HANDLE client ); Description This is function DRV_USB_HOST_TimerIsComplete. 5.1.12.7.5.22 DRV_USB_HOST_TimerReset Function C void DRV_USB_HOST_TimerReset( DRV_HANDLE client ); Description This is function DRV_USB_HOST_TimerReset. 5.1.12.7.5.23 DRV_USB_HOST_TimerStart Function C bool DRV_USB_HOST_TimerStart( DRV_HANDLE client, uint32_t periodInMilliseconds ); Description This is function DRV_USB_HOST_TimerStart. 5.1.12.7.5.24 DRV_USB_Tasks Function C void DRV_USB_Tasks( SYS_MODULE_OBJ object ); Description Maintains the driver's state machine when the driver is configured for polled mode. This function should be called from the 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-594 system tasks routine. Preconditions The DRV_USB_Initialize routine must have been called for the specified USB driver instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USB_Initialize) Returns None Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). This function will never block. Example SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize while (true) { DRV_USB_Tasks(object); // Do other tasks } 5.1.12.7.6 Data Types and Constants 5.1.12.7.6.1 DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE Macro C #define DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE 5.1.12.7.6.2 DRV_USB_HOST_PIPE_HANDLE_INVALID Macro C #define DRV_USB_HOST_PIPE_HANDLE_INVALID ((DRV_USB_HOST_PIPE_HANDLE)(-1)) Description USB Driver Host Pipe Handle Invalid Defines the USB Driver Host Pipe Invalid handle Remarks None. 5.1.12.7.6.3 DRV_USB_INDEX Macro C #define DRV_USB_INDEX 0 Description This is macro DRV_USB_INDEX. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-595 5.1.12.7.6.4 DRV_USB_INDEX_0 Macro C #define DRV_USB_INDEX_0 0 Description USB Driver Module Index Numbers These constants provide USB driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals and should be passed into the DRV_USB_Initialize and DRV_USB_Open routines to identify the driver instance in use. These are not indicative of the number of modules that are actually supported by the microcontroller. 5.1.12.7.6.5 DRV_USB_INTERRUPT_SOURCE Macro C #define DRV_USB_INTERRUPT_SOURCE INT_SOURCE_USB_1 Description This is macro DRV_USB_INTERRUPT_SOURCE. 5.1.12.7.6.6 DRV_USB_PERIPHERAL_ID Macro C #define DRV_USB_PERIPHERAL_ID USB_ID_1 Description This is macro DRV_USB_PERIPHERAL_ID. 5.1.12.7.6.7 DRV_USB_EVENT Enumeration C typedef enum { DRV_USB_EVENT_ERROR = 1, DRV_USB_EVENT_RESET_DETECT, DRV_USB_EVENT_RESUME_DETECT, DRV_USB_EVENT_IDLE_DETECT, DRV_USB_EVENT_STALL, DRV_USB_EVENT_SOF_DETECT, DRV_USB_EVENT_HOST_ATTACH, DRV_USB_EVENT_HOST_DETACH } DRV_USB_EVENT; Description USB Driver Events Enumeration Identifies the different events that the USB Driver provides. Members Members Description DRV_USB_EVENT_ERROR = 1 Bus error occurred and was reported DRV_USB_EVENT_RESET_DETECT Host has issued a device reset 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-596 DRV_USB_EVENT_RESUME_DETECT Resume detected while USB in suspend mode DRV_USB_EVENT_IDLE_DETECT Idle detected DRV_USB_EVENT_STALL Stall handshake has occurred 5.1.12.7.6.8 DRV_USB_EVENT_CALLBACK Type C typedef void (* DRV_USB_EVENT_CALLBACK)(uintptr_t hClient, DRV_USB_EVENT eventType, void * eventData); Description Type of the USB Event Callback Function Type of the USB event callback function. The client should register an event callback function of this type when it intends to receive events from the USB driver. The event callback function is registered using the DRV_USB_ClientEventCallBackSet() function. Parameters Parameters Description hClient handle to driver client that registered this callback function. eventType Event type eventData Event relevant data. Returns None. Remarks None. 5.1.12.7.6.9 DRV_USB_HOST_PIPE_HANDLE Type C typedef uintptr_t DRV_USB_HOST_PIPE_HANDLE; Description USB Driver Host Pipe Handle Defines the USB Driver Host Pipe handle type Remarks None. 5.1.12.7.6.10 DRV_USB_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; USB_MODULE_ID usbID; bool stopInIdle; bool suspendInSleep; INT_SOURCE interruptSource; USB_SPEED operationSpeed; USB_OPMODES operationMode; void * endpointTable; } DRV_USB_INIT; 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-597 Description USB Device Driver Initialization Data This structure contains all the data necessary to initialize the USB driver. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization USB_MODULE_ID usbID; Identifies peripheral (PLIB-level) ID bool stopInIdle; Boolean flag: true -> Stop USB module in Idle Mode bool suspendInSleep; Boolean flag: true -> Suspend USB in Sleep Mode INT_SOURCE interruptSource; Interrupt Source for USB module USB_SPEED operationSpeed; USB Operation speed USB_OPMODES operationMode; USB module operating mode void * endpointTable; Endpoint Descriptor Table buffer Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_USB_Initialize routine. 5.1.12.8 Files Files Name Description drv_usb.h USB Device Driver Interface File drv_usb_config_template.h USB driver configuration definitions template Description 5.1.12.8.1 drv_usb.h USB Device Driver Interface The USB device driver provides a simple interface to manage the "USB" peripheral. This file defines the interface definitions and prototypes for the USB driver. Enumerations Name Description DRV_USB_EVENT Identifies the different events that the USB Driver provides. Functions Name Description DRV_USB_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the a client of USB bus events. DRV_USB_Close Closes an opened-instance of the USB driver DRV_USB_DEVICE_AddressSet This function will set the USB module address that is obtained from the host. 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-598 DRV_USB_DEVICE_Attach This function will attach the device to the USB. DRV_USB_DEVICE_CurrentSpeedGet This function will return the USB speed at which device is operating. DRV_USB_DEVICE_Detach This function will detach the device from the USB. DRV_USB_DEVICE_EndpointDisable This function disables an endpoint. DRV_USB_DEVICE_EndpointDisableAll This function disables all provisioned non-zero endpoints. DRV_USB_DEVICE_EndpointEnable This function enables a endpoint for the specified direction and endpoint size. DRV_USB_DEVICE_EndpointIsEnabled This function returns the enable/ disable status of the specified endpoint and direction. DRV_USB_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USB_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. DRV_USB_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USB_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USB_DEVICE_IRPSubmit This function submits a I/O Request Packet (IRP) for processing to the USB Driver. DRV_USB_HOST_BusResetControl This is function DRV_USB_HOST_BusResetControl. DRV_USB_HOST_DeviceCurrentSpeedGet This is function DRV_USB_HOST_DeviceCurrentSpeedGet. DRV_USB_HOST_IRPCancel This is function DRV_USB_HOST_IRPCancel. DRV_USB_HOST_IRPSubmit This is function DRV_USB_HOST_IRPSubmit. DRV_USB_HOST_OperationEnable This is function DRV_USB_HOST_OperationEnable. DRV_USB_HOST_OperationIsEnabled This is function DRV_USB_HOST_OperationIsEnabled. DRV_USB_HOST_PipeClose This is function DRV_USB_HOST_PipeClose. DRV_USB_HOST_PipeSetup This is function DRV_USB_HOST_PipeSetup. DRV_USB_HOST_StartOfFrameControl This is function DRV_USB_HOST_StartOfFrameControl. DRV_USB_HOST_TimerIsComplete This is function DRV_USB_HOST_TimerIsComplete. DRV_USB_HOST_TimerReset This is function DRV_USB_HOST_TimerReset. DRV_USB_HOST_TimerStart This is function DRV_USB_HOST_TimerStart. DRV_USB_Initialize Initializes the USB driver DRV_USB_Open Opens the specified USB driver instance and returns a handle to it DRV_USB_Status Provides the current status of the USB driver module DRV_USB_Tasks Maintains the driver's state machine when the driver is configured for polled mode. DRV_USB_Tasks_ISR Maintains the driver's state machine and implements its ISR Macros Name Description DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE DRV_USB_HOST_PIPE_HANDLE_INVALID Defines the USB Driver Host Pipe Invalid handle DRV_USB_INDEX_0 USB driver index definitions Structures Name Description DRV_USB_INIT Contains all the data necessary to initialize the USB device 5.1 Driver Library Help MPLAB Harmony Help USB Driver Library 5-599 Types Name Description DRV_USB_EVENT_CALLBACK Type of the USB event callback function DRV_USB_HOST_PIPE_HANDLE Defines the USB Driver Host Pipe handle type Company Microchip Technology Incorported FileName: drv_usb.h 5.1.12.8.2 drv_usb_config_template.h USB Driver Configuration Definitions for the template version These definitions statically define the driver's mode of operation. Macros Name Description DRV_USB_INDEX This is macro DRV_USB_INDEX. DRV_USB_INTERRUPT_SOURCE This is macro DRV_USB_INTERRUPT_SOURCE. DRV_USB_PERIPHERAL_ID This is macro DRV_USB_PERIPHERAL_ID. File Name drv_usb_config_template.h Company Microchip Technology Incorported 5.1.13 MRF24W Wi-Fi Driver Library MRF24W Wi-Fi Driver Library for Microchip Microcontrollers This library provides an interface to manage the Wi-Fi module on the MRF24W family of Microchip microcontrollers in different modes of operation. Description Content pending. 5.1.13.1 Introduction MRF24W Wi-Fi Driver Library for Microchip Microcontrollers 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-600 This library provides a low-level abstraction of the MRF24W Wi-Fi Driver Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.1.13.2 Release Notes MPLAB Harmony Version: v0.70b MRF24W Wi-Fi Driver Library Version : 3.0.0 Release Date: 18Nov2013 New This Release: Nothing to report in this release. Known Issues: • No W-iFi demonstrations are available for PIC32MZ • Webserver demonstration: • Mpfsupload of image requires system boot upon completion • EasyConfig Demonstration (Explorer 16 Development Board and PIC32 Ethernet Starter Kit) • Mpfsupload of image requires system boot upon completion • Ad-Hoc mode – cannot retrieve scan info/cannot redirect network • Security (minor problem) • WEP Shared Key is not supported • Stack • Heap memory leak • TCP network traffic (Max TX Packet error detect) • Heap allocation failure • Services not verified • DNS Server • DNS Client • Dynamic DNS • Zero Conf • IPv6 • SNMPv1, SNMP2, SNMP3 • FTP • Data throughput in open air (throughput is still lower than v5 stack) • IPerf TCP RX/TX (320/102 Kbps) • IPerf UDP RX/TX (570/468 Kbps) 5.1.13.2.1 v0.51.01b Release notes for MRF24WG Wi-Fi Driver v0.51.01b 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-601 Description Due to a special circumstance for this release the MRF24WG Wi-Fi driver will compile and work with legacy peripheral drivers (plib.h), and not with the MPLAB Harmony peripheral (peripheral.h). This MRF24WG Wi-F idriver compiling issue will be fixed in a future release. Applications can still take advantage of the V6 stack features and services in this B1U dot release, along with Wi-Fi connectivity. Known Issues: 1) Stack ASSERT condition while waiting for RAW_MOVE_TO_COMPLETE 2) Web Server Demo hang or irresponsive to HTTP query Software Requirements: (1) MPLAB X IDE 1.80 (2) XC32 compiler v1.21 and later Applicable Product: (1) MRF24WG Supported Application Demos: (1) Web Server Demo a. SNMPv3, multi-port connection (Ethernet + Wi-Fi) b. Network type supported: Infrastructure (Client STA) c. Security mode supported: Open , WEP 64/128 Open, WPS, WPA/WPA2 PSK TKIP/AES Project Files: To run with Explorer 16 Development Board (EX16) Directory folder - “.\apps\tcpip\web_server\firmware\pic32_ex16.X” To run with PIC32 IO Expansion Board with Ethernet Starter Kit (ESK) Directory folder - “.\apps\tcpip\web_server\firmware\pic32_esk_mrf24w.X” (2) Console Demo a. Network benchmark debug/test support such as iPerf, etc via system command line access. b. Network type supported: Infrastructure (Client STA), Ad-Hoc, Wi-Fi Direct If testing Wifi-Direct, use RF module FW version 0x3107. RF module FW version 0x3108 does NOT have support for Wi-Fi Direct. Project File: To run with Explorer 16 Development Board (EX16) Directory “.\apps\tcpip\wifi_console\firmware\pic32_ex16_mrf24w.X” (3) EasyConfig Demo a. Network provision allowing configurations of an embedded decide on a wireless network. (SoftAP, Ad-Hoc) b. Network type supported: SoftAP, Ad-Hoc 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-602 Project File: To run with Explorer 16 Development Board (EX16) Directory “.\apps\tcpip\wifi_easyconf\firmware\pic32_ex16.X” Key Features: Verified: (1) SNMPv3 (2) DHCP Server/Client - server supports up to max 4 IPs (3) SoftAP is able to support up to max 4 clients (STAs) Requires RF module FW version 0x3108. RF module FW version 0x3107 only supports 1 client for SoftAP. (4) Ad-Hoc network with support for up to max 4 STAs (5) Multi-Ethernet ports (Ethernet and Wi-Fi) (6) Serial console 115,200 baud Supported: (1) ZeroConfig/Bonjour (with mDNS) (2) SNMP v1, 2c, v3 (3) SMTP (4) SSL (512, 1024, 2048-bit) (5) HTTP2 (6) ICMP (7) DNS (8) NBNS (9) Iperf (10) TCP/UDP modules (11) TCPIP Network Commands (12) TCPIP Storage Service (13) Announce (14) ARP (Gratuitous) (15) Berkeley API (16) ZeroConfig/Bonjour (with mDNS) (17) Power management / Power Save • Active mode (Known as normal mode in v5 stack) 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-603 • Doze mode (Known as PS-Polling mode in v5 stack) Supported But Not Verified: (1) Telnet (2) TFTP (3) SNTP (4) Reboot Server (5) IPV6 : This is currently not supported due to a defect of software multicast filter of MRF24WG 3107 or the older FW. The problem will be fixed with upcoming 3108 FW, and thereby the IPv6 will get supported for Wi-Fi. (6) FTP To test ESK board: • Ethernet Starter Kit (ESK) is valid for Web server demo • ESK + MRF24WG • Please note that in order to use the MRF24WG module with the PIC32ESK you need to use an I/O Expansion board (DM320002) and insert the MRF24WG module in one of the PICtail Plus slots (SPI1 position is the default). • You need to connect the J10/PMPA4/56 and J10/INT1/37 pins on the I/O Expansion board so that the MRF24WG interrupt signal reaches the PIC32 processor. For this configuration the MRF24WG driver uses a CN (change notice) interrupt. 5.1.13.2.2 v0.51b Release notes for MRF24WG Wi-Fi driver v0.51b. Description V6 MPLAB Harmony (v0.51b) Beta Release is limited release to demonstrate V6 stack capabilities, and was verified on one Development Board: (1) Explorer16 Development Board, with PIC32MX795F512L PIM, and MRF24WG PICtail (FW 0x3108 only) There are two Application Demos included to demonstrate some Stack services: (1) Web Server Demo (Infrastructure mode) (2) EasyConfig Demo (SoftAP and Ad-Hoc modes) a. Over-air system configuration For development work and running the above Demos, will require: (1) MPLAB X IDE v1.85 (2) XC32 compiler v1.21 or later (3) MPLAB ICD 3 (4) Windows XP SP3 or 7 PC with serial port, USB port. (5) Development boards mentioned above. (6) And MLA Stack V6 Harmony (MPLAB Harmony v0_51b) Beta Release package. Specific V6 Beta Stack features supported and demonstration included: (verified) (1) SoftAP with support for 4 STA Clients. (2) DHCP Server/Client. DHCP Server supports up to 4 clients. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-604 (3) Ad-Hoc network with support for up to 4 STAs (joiners). (4) Wi-Fi over-air system configuration (5) MRF24G supporting 802.11b/g mixed (6) 115,200 baud SPI interface (7) MPLAB X IDE and X32C compiler (8) ZeroConfig/Bonjour (with mDNS) Other V6 Stack services: (included, verified) (1) IPV4 (2) IPV6 (with Ping only) (3) SMTP (4) SSL (512, 1024, 2048-bit) (5) HTTP (6) ICMP (7) NBNS (8) IPerf (9) ARP (Gratuitous) (10) TCP/UDP modules (11) TCPIP Network Commands (12) TCPIP Storage Service Other V6 Stack services: (included, NOT VERIFIED) (1) SNMP v1, 2c (2) SNMPv3 (3) SNTP (4) DNS Client/Server (5) Telnet (6) FTP (7) TFTP (8) Announce (9) AutoIP (10) Berkeley API (11) Reboot Server Specific Stack/Wi-Fi Connection Agent supports: (1) Wi-Fi Specific Features: a. ENABLE_SOFTWARE_MULTICAST_FILTER 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-605 b. RETRIEVE_BINARY_KEY (not support in Beta) c. SAVE_WPS_CONFIDENTIALS (not support in Beta) d. DISABLE_MODULE_FW_CONNECT_MANAGER_IN_INFRASTRUCTURE e. DERIVE_KEY_FROM_PASSPHRASE_IN_HOST f. MY_DEFAULT_MAC_ADDRESS (2) Network Type: a. 802.11 b/g mixed b. 802.11 b-only c. 802.11 legacy (3) Network Mode: a. Infrastructure (Open , WEP 64/128 Open/Shared Key), WPS, WPA/WPA2 PSK TKIP/AES) b. Ad-Hoc (Open, WEP 64/128 Open/Shared Key) c. SoftAP (Open, WEP 64/128 Open Key) (4) Power Save a. Normal b. PS-Poll MLA STACK V6 MPLAB Harmony (v0.51b) Beta Release PACKAGE DEMO APPLICATION & MICROCHIP DEVELOPMENT BOARD Single Port (Wi-Fi only) - WEB Server and EasyConfig Demos Development Board Configuration: Explorer16 Development Board MRF24WG PICtail (FW 0x3108 only) PIC32MX795F512L PIM WEB Server Demo project: “…\software\isp_root\apps\tcpip\tcpip_web_server_demo_app\firmware\pic32_ex16.X” EasyConfig Demo project: “…\software\isp_root\apps\tcpip\tcpip_wifi_easyconfig_app\firmware\pic32_ex16.X” DEMO CONFIGURATION Refer to WF_Config.h and TCPIP_Config.h files in respective MPLAB X IDE demo project for network configuration and setup information. 5.1.13.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-606 licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.1.13.4 Using the Library This topic describes the basic architecture of the MRF24W Wi-Fi Driver Library and provides information and examples on how to use it. Interface Header File: drv_wifi.h The interface to the ADC Driver Library is defined in the "drv_wifi.h" header file. Please refer to the MPLAB Harmony Overview for how the driver interacts with the framework. 5.1.13.4.1 Abstraction Model This library provides a low-level abstraction of the Wi-Fi module on Microchip's microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Content pending. 5.1.13.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each sub-section addresses one of the blocks or the overall operation of the Wi-Fi module. Library Interface Section Description System Functions and System Configuration Functions Provides system module interfaces, device initialization, deinitialization, re-initialization, tasks, and status functions. Miscellaneous Provides driver miscellaneous functions, version identification functions etc. 5.1.13.4.3 How the Library Works This section describes how the Wi-Fi Driver Library operates. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-607 Description Before the driver is ready for use, its should be configured (compile time configuration). Refer to the Configuring the Library section for more details on how to configure the driver. There are few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. To use the Wi-Fi Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. The following is the sequence in which various routines should be called: Content pending. 5.1.13.4.3.1 System Initialization This section describes initialization and reinitialization features. Description Content pending. 5.1.13.4.3.2 Client Functionality This section describes core operation. Description Content pending. 5.1.13.4.3.3 Other Functionality This section describes other functionality. Description Content pending. 5.1.13.5 Configuring the Library The configuration of the MRF24W Wi-Fi driver is based on the file drv_wifi_config.h This header file contains the configuration selection for the Wi-Fi Driver. Based on the selections made, the Wi-Fi Driver will support or not support selected features. These configuration settings will apply to all instances of the Wi-Fi Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.1.13.5.1 Initialization Overrides Drag and Drop Initialization overrides 5.1.13.5.2 Files 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-608 5.1.13.5.3 Others Drag and Drop other configuration options 5.1.13.5.4 Examples - Sample Functionality Drag the example configuration header file. 5.1.13.6 Building the Library This section list the files that are available in the \src of the MRF24W Wi-Fi driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.1.13.7 Library Interface Data Types and Constants Name Description DRV_WIFI_BSSID_LENGTH This is macro DRV_WIFI_BSSID_LENGTH. DRV_WIFI_DEAUTH_REASONCODE_MASK This is macro DRV_WIFI_DEAUTH_REASONCODE_MASK. DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD ms DRV_WIFI_DEFAULT_ADHOC_HIDDEN_SSID Default values for WiFi AdHoc settings DRV_WIFI_DEFAULT_ADHOC_MODE This is macro DRV_WIFI_DEFAULT_ADHOC_MODE. DRV_WIFI_DEFAULT_PS_DTIM_ENABLED DTIM wake-up enabled (normally the case) DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL number of beacon periods DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL 100ms multiplier, e.g. 1 * 100ms = 100ms DRV_WIFI_DEFAULT_SCAN_COUNT Default values for WiFi scan context DRV_WIFI_DEFAULT_SCAN_MAX_CHANNEL_TIME ms DRV_WIFI_DEFAULT_SCAN_MIN_CHANNEL_TIME ms DRV_WIFI_DEFAULT_SCAN_PROBE_DELAY us DRV_WIFI_DEFAULT_WEP_KEY_TYPE see DRV_WIFI_SecurityWepSet() and DRV_WIFI_WEP_CONTEXT DRV_WIFI_DISABLED Do not make this an enumerated type! DRV_WIFI_DISASSOC_REASONCODE_MASK This is macro DRV_WIFI_DISASSOC_REASONCODE_MASK. DRV_WIFI_ENABLED This is macro DRV_WIFI_ENABLED. DRV_WIFI_MAX_CHANNEL_LIST_LENGTH This is macro DRV_WIFI_MAX_CHANNEL_LIST_LENGTH. DRV_WIFI_MAX_NUM_RATES This is macro DRV_WIFI_MAX_NUM_RATES. DRV_WIFI_MAX_SECURITY_KEY_LENGTH This is macro DRV_WIFI_MAX_SECURITY_KEY_LENGTH. DRV_WIFI_MAX_SSID_LENGTH This is macro DRV_WIFI_MAX_SSID_LENGTH. DRV_WIFI_MAX_WEP_KEY_LENGTH This is macro DRV_WIFI_MAX_WEP_KEY_LENGTH. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-609 DRV_WIFI_MAX_WPA_PASS_PHRASE_LENGTH must include string terminator DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH This is macro DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGT H. DRV_WIFI_MIN_WPA_PASS_PHRASE_LENGTH Key size defines DRV_WIFI_NETWORK_TYPE_ADHOC This is macro DRV_WIFI_NETWORK_TYPE_ADHOC. DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE Selection of different WiFi network types DRV_WIFI_NETWORK_TYPE_P2P not supported DRV_WIFI_NETWORK_TYPE_SOFT_AP This is macro DRV_WIFI_NETWORK_TYPE_SOFT_AP. DRV_WIFI_NO_ADDITIONAL_INFO eventInfo define for DRV_WIFI_ProcessEvent() when no additional info is supplied DRV_WIFI_RETRY_ADHOC This is macro DRV_WIFI_RETRY_ADHOC. DRV_WIFI_RETRY_FOREVER This is macro DRV_WIFI_RETRY_FOREVER. DRV_WIFI_RTS_THRESHOLD_MAX maximum RTS threshold size in bytes DRV_WIFI_SECURITY_EAP This is macro DRV_WIFI_SECURITY_EAP. DRV_WIFI_SECURITY_OPEN Selection of different WiFi security types DRV_WIFI_SECURITY_WEP_104 This is macro DRV_WIFI_SECURITY_WEP_104. DRV_WIFI_SECURITY_WEP_40 This is macro DRV_WIFI_SECURITY_WEP_40. DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY. DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS _PHRASE. DRV_WIFI_SECURITY_WPA_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA_WITH_KEY. DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRA SE. DRV_WIFI_SECURITY_WPA2_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA2_WITH_KEY. DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHR ASE. DRV_WIFI_SECURITY_WPS_PIN This is macro DRV_WIFI_SECURITY_WPS_PIN. DRV_WIFI_SECURITY_WPS_PUSH_BUTTON This is macro DRV_WIFI_SECURITY_WPS_PUSH_BUTTON. DRV_WIFI_VERSION_NUMBER WiFi Driver Version Number DRV_WIFI_WEP104_KEY_LENGTH 4 keys of 13 bytes each DRV_WIFI_WEP40_KEY_LENGTH 4 keys of 5 bytes each DRV_WIFI_WPA_KEY_LENGTH This is macro DRV_WIFI_WPA_KEY_LENGTH. DRV_WIFI_WPA2_KEY_LENGTH This is macro DRV_WIFI_WPA2_KEY_LENGTH. DRV_WIFI_WPS_PIN_LENGTH 7 digits + checksum byte DRV_WIFI_ADHOC_MODES Selection of different AdHoc connection modes DRV_WIFI_ADHOC_NETWORK_CONTEXT Contains data pertaining to WiFi AdHoc context DRV_WIFI_CONNECTION_CONTEXT Contains data pertaining to MRF24WG connection context DRV_WIFI_CONNECTION_STATES Wifi Connection states 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-610 DRV_WIFI_DEVICE_INFO Contains data pertaining to MRF24WG device type and version number DRV_WIFI_DEVICE_TYPES Codes for WiFi device types DRV_WIFI_DOMAIN_CODES Regional domain codes. DRV_WIFI_EVENT_CONN_TEMP_LOST_CODES Selection of different codes when WiFi connection is temporarily lost. DRV_WIFI_EVENT_INFO Selection of different EventInfo types DRV_WIFI_EVENTS Selections for events that can occur. DRV_WIFI_GENERAL_ERRORS This is type DRV_WIFI_GENERAL_ERRORS. DRV_WIFI_HIBERNATE_STATE This is type DRV_WIFI_HIBERNATE_STATE. DRV_WIFI_HIBERNATE_STATES Wifi Hibernate states DRV_WIFI_MAC_STATS Wifi MIB states DRV_WIFI_MGMT_ERRORS Error codes returned when a mgmt message is sent to the MRF24W DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT Contains data pertaining to WiFi Soft AP event DRV_WIFI_MULTICAST_FILTER_IDS Selections for software Multicast filter ID's DRV_WIFI_MULTICAST_FILTERS Selections for Software Multicast Filters. DRV_WIFI_POWER_SAVE_STATES Wifi Power Save states DRV_WIFI_PS_POLL_CONTEXT Contains data pertaining to WiFi PS-Poll context DRV_WIFI_REASON_CODES Selection of different codes when a deauth or disassociation event has occurred. DRV_WIFI_RECONNECT_MODES Selection of different Reconnection modes DRV_WIFI_SCAN_CONTEXT Contains data pertaining to WiFi scan context DRV_WIFI_SCAN_RESULT Contains data pertaining to WiFi scan results DRV_WIFI_SCAN_TYPES Selection of different WiFi scan types DRV_WIFI_SECURITY_CONTEXT Contains data pertaining to WiFi security. DRV_WIFI_SOFT_AP_EVENT_REASON_CODES This is type DRV_WIFI_SOFT_AP_EVENT_REASON_CODES. DRV_WIFI_SOFT_AP_STATES This is type DRV_WIFI_SOFT_AP_STATES. DRV_WIFI_STATUS_CODES Selection of different codes when WiFi connection fails due to association or authentication failure. DRV_WIFI_SWMULTICAST_CONFIG Contains data pertaining to WiFi software multicast filter configuration DRV_WIFI_TX_MODES Selections for WiFi Tx mode DRV_WIFI_WEP_CONTEXT Contains data pertaining to WiFi WEP context DRV_WIFI_WEP_KEY_TYPE Selections for WEP key type when using WEP security. DRV_WIFI_WPA_CONTEXT Contains data pertaining to WiFi WPA. DRV_WIFI_WPA_KEY_INFO Contains data pertaining to WiFi WPA Key DRV_WIFI_WPS_AUTH_TYPES This is type DRV_WIFI_WPS_AUTH_TYPES. DRV_WIFI_WPS_CONTEXT Contains data pertaining to WiFi WPS security. DRV_WIFI_WPS_CREDENTIAL Contains data pertaining to WiFi WPS Credentials DRV_WIFI_WPS_ENCODE_TYPES This is type DRV_WIFI_WPS_ENCODE_TYPES. adhocMode Selection of different AdHoc connection modes ENABLE_P2P_PRINTS not supported ENABLE_WPS_PRINTS This is macro ENABLE_WPS_PRINTS. PA6_IO debug, remove later 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-611 PA6_TRISTATE This is macro PA6_TRISTATE. SET_PA6_AS_OUTPUT This is macro SET_PA6_AS_OUTPUT. WF_WPS_PIN_LENGTH WPS PIN Length Miscellaneous Functions Name Description DRV_WIFI_ConfigDataErase Erases configuration data from the board EEPROM. DRV_WIFI_ConfigDataLoad Loads configuration data from the board EEPROM. DRV_WIFI_ConfigDataPrint Outputs to console the configuration data from the board EEPROM. DRV_WIFI_ConfigDataSave Save configuration data to the board EEPROM. DRV_WIFI_ProcessEvent Processes WiFi event DRV_WIFI_ScanGetResult Read selected scan results back from MRF24W. DRV_WIFI_SetLinkDownThreshold Sets number of consecutive WiFi Tx failures before link is considered down. DRV_WIFI_SetPSK Sets the binary WPA PSK code in WPS. DRV_WIFI_SWMultiCastFilterEnable Forces the MRF24WG to use software multicast filters instead of hardware multicast filters. DRV_WIFI_YieldPassphraseToHost Allows host to get WPS WPA-PSK passphrase and convert to binary key. System Configuration Functions Name Description DRV_WIFI_Connect Directs the MRF24WG to connect to a WiFi network. DRV_WIFI_Deinitialize Initializes the MRF24WG WiFi driver. DRV_WIFI_Disconnect Directs the MRF24WG to disconnect from a WiFi network. DRV_WIFI_Initialize Initializes the MRF24WG WiFi driver. DRV_WIFI_Scan Commands the MRF24W to start a scan operation. This will generate the WF_EVENT_SCAN_RESULTS_READY event. System Functions Name Description DRV_WIFI_BssidGet Sets the the BSSID set in DRV_WIFI_BssidSet(). DRV_WIFI_BssidSet Sets the the Basic Service Set Identifier (BSSID). DRV_WIFI_ChannelListGet Gets the the channel list. DRV_WIFI_ChannelListSet Sets the the channel list. DRV_WIFI_ConnectContextGet Gets the current WiFi connection context DRV_WIFI_ConnectionStateGet Gets the current WiFi connection state DRV_WIFI_DeviceInfoGet Retrieves MRF24WG device information DRV_WIFI_HWMulticastFilterGet Gets a multicast address filter from one of the two multicast filters. DRV_WIFI_HWMulticastFilterSet Sets a multicast address filter using one of the two hardware multicast filters. DRV_WIFI_MacAddressGet Retrieves the MRF24WG MAC address DRV_WIFI_MacAddressSet Uses a different MAC address for the MRF24W DRV_WIFI_MacStatsGet Gets MAC statistics. DRV_WIFI_NetworkTypeGet Gets the WiFi network type DRV_WIFI_NetworkTypeSet Sets the WiFi network type DRV_WIFI_PowerSaveStateGet Gets the current power-save state. DRV_WIFI_ReconnectModeGet Gets the WiFi reconnection mode. DRV_WIFI_ReconnectModeSet Sets the WiFi reconnection mode. DRV_WIFI_RegionalDomainGet Retrieves the MRF24WG Regional domain 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-612 DRV_WIFI_RtsThresholdGet Gets the RTS Threshold DRV_WIFI_RtsThresholdSet Sets the RTS Threshold. DRV_WIFI_ScanContextGet Gets the WiFi scan context. DRV_WIFI_ScanContextSet Sets the WiFi scan context. DRV_WIFI_SecurityGet Gets the current WiFi security setting DRV_WIFI_SecurityOpenSet Sets WiFi security to open (no security) DRV_WIFI_SecurityWepSet Sets WiFi security to use WEP. DRV_WIFI_SecurityWpaSet Sets WiFi security to use WPA or WPA2 DRV_WIFI_SecurityWpsSet Sets WiFi security to use WPS DRV_WIFI_SoftApEventInfoGet Gets the stored Soft AP event info DRV_WIFI_SsidGet Sets the SSID DRV_WIFI_SsidSet Sets the SSID DRV_WIFI_SWMulticastFilterSet Sets a multicast address filter using one of the software multicast filters. DRV_WIFI_TxModeGet Gets 802.11 Tx mode DRV_WIFI_TxModeSet Configures 802.11 Tx mode DRV_WIFI_TxPowerFactoryMaxGet Retrieves the factory-set max Tx power from the MRF24W. DRV_WIFI_TxPowerMaxGet Gets the Tx max power on the MRF24WG0M. DRV_WIFI_TxPowerMaxSet Sets the Tx max power on the MRF24WG0M. DRV_WIFI_WepKeyTypeGet Gets the Wep Key type DRV_WIFI_WPSCredentialsGet Gets the WPS credentials DRV_WIFI_AdhocContextSet Sets the AdHoc context. DRV_WIFI_RssiGet Gets RSSI value set in DRV_WIFI_RssiSet() DRV_WIFI_RssiSet Sets RSSI restrictions when connecting DRV_WIFI_GratuitousArpStart Starts a periodic gratuitous ARP response DRV_WIFI_GratuitousArpStop Stops a periodic gratuitous ARP. DRV_WIFI_HibernateEnable Puts the MRF24WG into hibernate mode. DRV_WIFI_isHibernateEnable Checks if MRF24W is in hibernate mode DRV_WIFI_PsPollDisable Disables PS-Poll mode. DRV_WIFI_PsPollEnable Enables PS Poll mode. Description This section describes the Application Programming Interface (API) functions of the MRF24W Wi-Fi Driver. Refer to each section for a detailed description. 5.1.13.7.1 System Functions 5.1.13.7.1.1 DRV_WIFI_BssidGet Function C void DRV_WIFI_BssidGet( uint8_t * p_bssid ); Description Retrieves the BSSID set in the previous call to DRV_WIFI_BssidSet(). 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-613 Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context pointer to where BSSID will be written. Returns None Remarks None Example uint8_t bssid[6]; DRV_WIFI_BssidGet(bssid); 5.1.13.7.1.2 DRV_WIFI_BssidSet Function C void DRV_WIFI_BssidSet( uint8_t * p_bssid ); Description This sets 6 byte (48-bit) MAC address of the Access Point that is being scanned for. It is optional to use this. Where it is useful is if there are two AP's with the same ID; the BSSID is used to connect to the specified AP. This setting can be used in lieu of the SSID. Set each byte to 0xFF (default) if the BSSID is not being used. Not typically needed. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context pointer to BSSID Returns None Remarks None Example uint8_t bssid[6]; bssid[0] = 0x00; bssid[1] = 0xe8; bssid[2] = 0xc0; bssid[3] = 0x11; bssid[4] = 0x22; bssid[5] = 0x33; DRV_WIFI_BssidSet(bssid); 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-614 5.1.13.7.1.3 DRV_WIFI_ChannelListGet Function C void DRV_WIFI_ChannelListGet( uint8_t * p_channelList, uint8_t * p_numChannels ); Description This function gets the current channel list. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_channelList pointer to where channel list will be written numChannels pointer to where number of channels in the list will be written. Returns None Remarks None Example uint8_t channelList[DRV_WIFI_MAX_CHANNEL_LIST_LENGTH]; uint8_t numChannels; DRV_WIFI_ChannelListGet(channelList, &numChannels); 5.1.13.7.1.4 DRV_WIFI_ChannelListSet Function C void DRV_WIFI_ChannelListSet( uint8_t * p_channelList, uint8_t numChannels ); Description This function sets the channel list that the MRF24WG will use when scanning or connecting. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_channelList list of channels numChannels number of channels in list; if set to 0, then MRF24WG will set its channel list to all valid channels in its regional domain. Returns None 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-615 Remarks None Example uint8_t channelList[1,6,11]; DRV_WIFI_ChannelListSet(channelList, sizeof(channelList)); 5.1.13.7.1.5 DRV_WIFI_ConnectContextGet Function C void DRV_WIFI_ConnectContextGet( DRV_WIFI_CONNECTION_CONTEXT * p_ctx ); Description This function gets the current WiFi connection context. Preconditions WiFi initialization must be complete Parameters Parameters Description p_ctx pointer to where connection context is written. See DRV_WIFI_CONNECTION_CONTEXT structure. Returns None Remarks None Example DRV_WIFI_CONNECTION_CONTEXT ctx; DRV_WIFI_ConnectContextGet(&ctx); 5.1.13.7.1.6 DRV_WIFI_ConnectionStateGet Function C void DRV_WIFI_ConnectionStateGet( uint8_t * p_state ); Description This function gets the current WiFi connection state. *p_state Description DRV_WIFI_CSTATE_NOT_CONNECTED No WiFi connection exists DRV_WIFI_CSTATE_CONNECTION_IN_PROGRESS WiFi connection in progress DRV_WIFI_CSTATE_CONNECTED_INFRASTRUCTURE WiFi connected in infrastructure mode DRV_WIFI_CSTATE_CONNECTED_ADHOC WiFi connected in adhoc mode 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-616 DRV_WIFI_CSTATE_RECONNECTION_IN_PROGRESS WiFi in process of reconnecting DRV_WIFI_CSTATE_CONNECTION_PERMANENTLY_LOST WiFi connection permanently lost Preconditions WiFi initialization must be complete Parameters Parameters Description p_state pointer to where state is written (see description) Returns None Remarks None Example uint8_t state; DRV_WIFI_ConnectionStateGet(&state); 5.1.13.7.1.7 DRV_WIFI_DeviceInfoGet Function C void DRV_WIFI_DeviceInfoGet( DRV_WIFI_DEVICE_INFO * p_deviceInfo ); Description This function retrieves MRF24WG device information. See DRV_WIFI_DEVICE_INFO structure. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_deviceInfo Pointer where device info will be written Returns None. Remarks None. Example DRV_WIFI_DEVICE_INFO info; DRV_WIFI_DeviceInfoGet(&info); 5.1.13.7.1.8 DRV_WIFI_HWMulticastFilterGet Function C void DRV_WIFI_HWMulticastFilterGet( uint8_t multicastFilterId, 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-617 uint8_t multicastAddress[6] ); Description Gets the current state of the specified Multicast Filter. Preconditions WiFi initialization must be complete. Parameters Parameters Description multicastFilterId DRV_WIFI_MULTICAST_FILTER_1 or DRV_WIFI_MULTICAST_FILTER_2 multicastAddress pointer to where 6-byte multicast filter is written. Returns None. Remarks None. Example uint8_t filterAddress[6]; DRV_WIFI_HWMulticastFilterGet(DRV_WIFI_MULTICAST_FILTER_1, filterAddress); 5.1.13.7.1.9 DRV_WIFI_HWMulticastFilterSet Function C void DRV_WIFI_HWMulticastFilterSet( uint8_t multicastFilterId, uint8_t multicastAddress[6] ); Description This function allows the application to configure up to two hardware Multicast Address Filters on the MRF24W. If two active multicast filters are set up they are OR’d together – the MRF24W will receive and pass to the Host CPU received packets from either multicast address. The allowable values for the multicast filter are: • DRV_WIFI_MULTICAST_FILTER_1 • DRV_WIFI_MULTICAST_FILTER_2 By default, both Multicast Filters are inactive. Preconditions WiFi initialization must be complete. Parameters Parameters Description multicastFilterId DRV_WIFI_MULTICAST_FILTER_1 or DRV_WIFI_MULTICAST_FILTER_2 multicastAddress 6-byte address (all 0xFF will inactivate the filter) Returns None. Remarks Cannot mix hardware and software multicast filters. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-618 Example uint8_t multicastFilterId = DRV_WIFI_MULTICAST_FILTER_1; uint8_t filterAddress[6] = {0x00 0x01, 0x5e, 0x11, 0x22, 0x33}; DRV_WIFI_HWMulticastFilterSet(multicastFilterId, filterAddress); 5.1.13.7.1.10 DRV_WIFI_MacAddressGet Function C void DRV_WIFI_MacAddressGet( uint8_t * p_mac ); Description This function retrieves the MRF24WG MAC address. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_mac Pointer where mac address will be written (must point to a 6-byte buffer) Returns None. Remarks None. Example uint8_t mac[6]; DRV_WIFI_MacAddressGet(mac); 5.1.13.7.1.11 DRV_WIFI_MacAddressSet Function C void DRV_WIFI_MacAddressSet( uint8_t * p_mac ); Description Directs the MRF24W to use the input MAC address instead of its factory-default MAC address. This function does not overwrite the factory default, which is in FLASH memory. Preconditions WiFi initialization must be complete. Cannot be called when the MRF24W is in a connected state. Parameters Parameters Description p_mac Pointer to 6-byte MAC that will be sent to MRF24WG Returns None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-619 Remarks None. Example uint8_t mac[6] = {0x00, 0x1e, 0xc0, 0x11, 0x22, 0x33}; DRV_WIFI_MacAddressSet(mac); 5.1.13.7.1.12 DRV_WIFI_MacStatsGet Function C void DRV_WIFI_MacStatsGet( DRV_WIFI_MAC_STATS * p_macStats ); Description This function gets the various MAC layer stats as maintained by the MRF24WG. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_macStats Pointer to where MAC statistics are written. See DRV_WIFI_MAC_STATS structure. Returns None. Remarks None. Example DRV_WIFI_MAC_STATS macStats; DRV_WIFI_MacStatsGet(&macStats); 5.1.13.7.1.13 DRV_WIFI_NetworkTypeGet Function C void DRV_WIFI_NetworkTypeGet( uint8_t * p_networkType ); Description This function gets the WiFi network type. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_networkType Pointer to where the network type will be written. One of the following DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE DRV_WIFI_NETWORK_TYPE_ADHOC 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-620 DRV_WIFI_NETWORK_TYPE_P2P not supported DRV_WIFI_NETWORK_TYPE_SOFT_AP Returns None Remarks None Example uint8_t networkType; DRV_WIFI_NetworkTypeGet(&networkType); 5.1.13.7.1.14 DRV_WIFI_NetworkTypeSet Function C void DRV_WIFI_NetworkTypeSet( uint8_t networkType ); Description This function selects the WiFi network type. Preconditions WiFi initialization must be complete. Parameters Parameters Description networkType One of the following: DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE DRV_WIFI_NETWORK_TYPE_ADHOC DRV_WIFI_NETWORK_TYPE_P2P not supported DRV_WIFI_NETWORK_TYPE_SOFT_AP Returns None Remarks None Example DRV_WIFI_NetworkTypeSet(DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE); 5.1.13.7.1.15 DRV_WIFI_PowerSaveStateGet Function C void DRV_WIFI_PowerSaveStateGet( uint8_t * p_powerSaveState ); Description This function gets the current MRF24WG power save state. powerSaveState Definition DRV_WIFI_PS_HIBERNATE MRF24W in hibernate state 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-621 DRV_WIFI_PS_PS_POLL_DTIM_ENABLED MRF24W in PS-Poll mode with DTIM enabled DRV_WIFI_PS_PS_POLL_DTIM_DISABLED MRF24W in PS-Poll mode with DTIM disabled DRV_WIFI_PS_POLL_OFF MRF24W is not in any power-save state Preconditions WiFi initialization must be complete. Parameters Parameters Description p_powerSaveState Pointer to where power state is written (see description) Returns None. Remarks None. Example uint8_t state; DRV_WIFI_PowerSaveStateGet(&state); 5.1.13.7.1.16 DRV_WIFI_ReconnectModeGet Function C void DRV_WIFI_ReconnectModeGet( uint8_t * p_retryCount, uint8_t * p_deauthAction, uint8_t * p_beaconTimeout, uint8_t * p_beaconTimeoutAction ); Description This function gets the reconnection mode parameters set in DRV_WIFI_ReconnectModeGet(). Preconditions WiFi initialization must be complete. Parameters Parameters Description p_retryCount Pointer where retry count is written p_deauthAction Pointer where deauth action is written p_beaconTimeout Pointer where beacon timeout is written p_beaconTimeoutAction Pointer where beacon timeout action is written. Returns None Remarks None Example uint8_t retryCount, deauthAction, beaconTimeout, beaconTimeoutAction; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-622 DRV_WIFI_ReconnectModeGet(&retryCount, &deauthAction, &beaconTimeout, &beaconTimeoutAction); 5.1.13.7.1.17 DRV_WIFI_ReconnectModeSet Function C void DRV_WIFI_ReconnectModeSet( uint8_t retryCount, uint8_t deauthAction, uint8_t beaconTimeout, uint8_t beaconTimeoutAction ); Description This function controls how the MRF24WG behaves when an existing WiFi connection is lost. The MRF24WG can lose an existing connection in one of two ways: 1) Beacon timeout 2) Deauth received from AP There are two options with respect to regaining a lost WiFi connection: 1) MRF24WG informs the host that the connection was temporarily lost and then the MRF24WG retries N times (or forever) to regain the connection. 2) MRF24WG simply informs the host application that the connection is lost, and it is up to the host to regain the connection via the API. Preconditions WiFi initialization must be complete. Parameters Parameters Description retryCount Number of times the MRF24WG should try to regain the connection (see description) deauthAction In the event of a deauth from the AP, the action the MRF24WG should take (see description) beaconTimeout Number of missed beacons before the MRF24WG designates the connection as lost (see description) beaconTimeoutAction In the event of a beacon timeout, the action the MRF24WG should take (see description) Returns None Remarks The retryCount parameter also applies when initially connecting. That is, the retryCount tells the MRF24WG how many time to try to connect to a WiFi network before giving up and generating the DRV_WIFI_EVENT_CONNECTION_FAILED event. 'retryCount' field Description 0 Do not try to regain a connection (simply report event to host) 1:254 Number of times MRF24WG should try to regain the connection 255 MRF24WG will retry forever (do not use for AdHoc connections) 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-623 'deauthAction' field Description DRV_WIFI_DO_NOT_ATTEMPT_TO_RECONNECT Do not attempt to reconnect after a deauth DRV_WIFI_ATTEMPT_TO_RECONNECT Attempt to reconnect after a deauth 'beaconTimeout' field Description 0 MRF24WG will not monitor the beacon timeout condition 1:255 Number of missed beacons before designating the connection as lost. 'beaconTimeoutAction' field Description DRV_WIFI_DO_NOT_ATTEMPT_TO_RECONNECT Do not attempt to reconnect after a beacon timeout DRV_WIFI_ATTEMPT_TO_RECONNECT Attempt to reconnect after a beacon timeout None Example // Example 1: MRF24WG should retry forever if either a deauth or beacon // timeout occurs (beacon timeout is 3 beacon periods). DRV_WIFI_ReconnectModeSet(WF_RETRY_FOREVER, WF_ATTEMPT_TO_RECONNECT, 3, WF_ATTEMPT_TO_RECONNECT); // Example 2: MRF24WG should not do any connection retries and only report // deauth events to the host. DRV_WIFI_ReconnectModeSet(0, WF_DO_NOT_ATTEMPT_TO_RECONNECT, 0, WF_DO_NOT_ATTEMPT_TO_RECONNECT); // Example 3: MRF24WG should not do any connection retries, but report deauth // and beacon timeout events to host. Beacon timeout should be 5 beacon periods. DRV_WIFI_ReconnectModeSet(0, WF_DO_NOT_ATTEMPT_TO_RECONNECT, 5, WF_DO_NOT_ATTEMPT_TO_RECONNECT); // Example 4: MRF24WG should ignore beacon timeouts, but attempt to // reconnect 3 times if a deauth occurs. DRV_WIFI_ReconnectModeSet(3, WF_ATTEMPT_TO_RECONNECT, 0, WF_DO_NOT_ATTEMPT_TO_RECONNECT); 5.1.13.7.1.18 DRV_WIFI_RegionalDomainGet Function C void DRV_WIFI_RegionalDomainGet( uint8_t * p_regionalDomain ); Description Gets the regional domain on the MRF24W. Values are: 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-624 • DRV_WIFI_DOMAIN_FCC • DRV_WIFI_DOMAIN_ETSI • DRV_WIFI_DOMAIN_JAPAN • DRV_WIFI_DOMAIN_OTHER Preconditions WiFi initialization must be complete. Parameters Parameters Description p_regionalDomain Pointer where the regional domain value will be written Returns None. Remarks None. Example uint8_t domain; DRV_WIFI_RegionalDomainGet(&domain); 5.1.13.7.1.19 DRV_WIFI_RtsThresholdGet Function C void DRV_WIFI_RtsThresholdGet( uint16_t * p_rtsThreshold ); Description Gets the RTS/CTS packet size threshold. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_rtsThreshold Pointer to where RTS threshold is written Returns None. Remarks None. Example uint16_t threshold; DRV_WIFI_RtsThresholdGet(&threshold); 5.1.13.7.1.20 DRV_WIFI_RtsThresholdSet Function C void DRV_WIFI_RtsThresholdSet( 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-625 uint16_t rtsThreshold ); Description Sets the RTS/CTS packet size threshold for when RTS/CTS frame will be sent. The default is 2347 bytes – the maximum for 802.11. It is recommended that the user leave the default at 2347 until they understand the performance and power ramifications of setting it smaller. Valid values are from 0 to DRV_WIFI_RTS_THRESHOLD_MAX (2347). Preconditions WiFi initialization must be complete. Parameters Parameters Description rtsThreshold Value of the packet size threshold Returns None. Remarks None. Example DRV_WIFI_RtsThresholdSet(DRV_WIFI_RTS_THRESHOLD_MAX); 5.1.13.7.1.21 DRV_WIFI_ScanContextGet Function C void DRV_WIFI_ScanContextGet( DRV_WIFI_SCAN_CONTEXT * p_context ); Description This function gets the WiFi scan context. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context Pointer to where scan context will be written. See DRV_WIFI_SCAN_CONTEXT structure. Returns None. Remarks None. Example DRV_WIFI_SCAN_CONTEXT context; DRV_WIFI_ScanContextSet(&context); 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-626 5.1.13.7.1.22 DRV_WIFI_ScanContextSet Function C void DRV_WIFI_ScanContextSet( DRV_WIFI_SCAN_CONTEXT * p_context ); Description This function sets the WiFi scan context. The MRF24WG defaults are fine for most applications, but they can be changed by this function. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context Pointer to scan context. See DRV_WIFI_SCAN_CONTEXT structure. Returns None. Remarks None. Example DRV_WIFI_SCAN_CONTEXT context; context.scantype = DRV_WIFI_ACTIVE_SCAN; context.scanCount = 1; context.minChannelTime = 200; // ms context.maxChannelTime = 400; // ms context.probeDelay = 20; // uS DRV_WIFI_ScanContextSet(&context); 5.1.13.7.1.23 DRV_WIFI_SecurityGet Function C void DRV_WIFI_SecurityGet( uint8_t * p_securityType, uint8_t * p_securityKey, uint8_t * p_securityKeyLength ); Description This function gets the current WiFi security setting. 'securityType' Field Key Length DRV_WIFI_SECURITY_OPEN N/A N/A DRV_WIFI_SECURITY_WEP_40 binary 4 keys, 5 bytes each (total of 20 bytes) DRV_WIFI_SECURITY_WEP_104 binary 4 keys, 13 bytes each (total of 52 bytes) DRV_WIFI_SECURITY_WPA_WITH_KEY binary 32 bytes DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE ascii 8-63 ascii characters 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-627 DRV_WIFI_SECURITY_WPA2_WITH_KEY binary 32 bytes DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE ascii 8-63 ascii characters DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY binary 32 bytes DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE ascii 8-63 ascii characters Preconditions WiFi initialization must be complete. Parameters Parameters Description p_securityType Value corresponding to the security type desired (see description) p_securityKey Binary key or passphrase (not used if security is DRV_WIFI_SECURITY_OPEN) p_securityKeyLength Number of bytes in p_securityKey (not used if security is DRV_WIFI_SECURITY_OPEN) Returns None. Remarks If security was initially set with a passphrase that the MRF24WG used to generate a binary key, this function returns the binary key, not the passphrase. Example uint8_t securityType; uint8_t securityKey[DRV_WIFI_MAX_SECURITY_KEY_LENGTH]; uint8_t keyLength; DRV_WIFI_SecurityGet(&securityType, securityKey, &keyLength); 5.1.13.7.1.24 DRV_WIFI_SecurityOpenSet Function C void DRV_WIFI_SecurityOpenSet(); Description This function sets the WiFi security to open. One can only connect to an AP that is running in open mode. Preconditions WiFi initialization must be complete. Must be in an unconnected state. Returns None Remarks None Example DRV_WIFI_SecurityOpenSet(); 5.1.13.7.1.25 DRV_WIFI_SecurityWepSet Function C void DRV_WIFI_SecurityWepSet( 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-628 DRV_WIFI_WEP_CONTEXT* p_context ); Description This function sets the WiFi security to WEP. One can only connect to an AP that is running the same WEP mode. Preconditions WiFi initialization must be complete. Must be in an unconnected state. Parameters Parameters Description p_context desired WEP context. See DRV_WIFI_WEP_CONTEXT structure. Returns None Remarks None Example DRV_WIFI_WEP_CONTEXT context; context.wepSecurityType = DRV_WIFI_SECURITY_WEP_40; context.wepKey[] = {0x5a, 0xfb, 0x6c, 0x8e, 0x77, 0xc1, 0x04, 0x49, 0xfd, 0x4e, 0x43, 0x18, 0x2b, 0x33, 0x88, 0xb0, 0x73, 0x69, 0xf4, 0x78}; context.wepKeyLength = 20; context.wepKeyType = DRV_WIFI_SECURITY_WEP_OPENKEY; DRV_WIFI_SecurityOpenSet(&context); 5.1.13.7.1.26 DRV_WIFI_SecurityWpaSet Function C void DRV_WIFI_SecurityWpaSet( DRV_WIFI_WPA_CONTEXT* p_context ); Description This function sets the WiFi security to WPA or WPA2. One can only connect to an AP that is running the same WPA mode. Preconditions WiFi initialization must be complete. Must be in an unconnected state. Parameters Parameters Description p_context desired WPA context. See DRV_WIFI_WPA_CONTEXT structure. Returns None Remarks None Example DRV_WIFI_WPA_CONTEXT context; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-629 context.wpaSecurityType = DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE; context.keyInfo.key[] = "MySecretWPA2PassPhrase"; context.keyInfo.keyLenth = strlen(context.keyInfo.key); DRV_WIFI_SecurityWpaSet(&context); 5.1.13.7.1.27 DRV_WIFI_SecurityWpsSet Function C void DRV_WIFI_SecurityWpsSet( DRV_WIFI_WPS_CONTEXT * p_context ); Description This function sets the WiFi security to WPS. One can only connect to an AP that supports WPS. Preconditions WiFi initialization must be complete. Must be in an unconnected state. Parameters Parameters Description p_context desired WPA context. See DRV_WIFI_WPS_CONTEXT structure. Returns None Remarks None Example DRV_WIFI_WPS_CONTEXT context; uint8_t wpsPin[8] = {1, 2, 3, 9, 0, 2, 1, 2}; context.wpsSecurityType = DRV_WIFI_SECURITY_WPS_PUSH_BUTTON; memcpy(context.wpsPin, wpsPin, sizeof(wpsPin)); context.wpsPinLength = 8; DRV_WIFI_SecurityWpsSet(&context); 5.1.13.7.1.28 DRV_WIFI_SoftApEventInfoGet Function C DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT * DRV_WIFI_SoftApEventInfoGet(); Description This function retrieves the additional event info after a Soft AP event has occurred. Preconditions Soft AP event must have occurred Returns None. Remarks None. Example DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT info;; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-630 DRV_WIFI_WPSCredentialsGet(&info); 5.1.13.7.1.29 DRV_WIFI_SsidGet Function C void DRV_WIFI_SsidGet( uint8_t * p_ssid, uint8_t * p_ssidLength ); Description Gets the SSID and SSID Length. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_ssid Pointer to buffer where SSID will be written ssidLength number of bytes in SSID Returns None Remarks None Example uint8_t ssid[DRV_WIFI_MAX_SSID_LENGTH]; uint8_t ssidLength; DRV_WIFI_SsidGet(ssid, &ssidLength); 5.1.13.7.1.30 DRV_WIFI_SsidSet Function C void DRV_WIFI_SsidSet( uint8_t * p_ssid, uint8_t ssidLength ); Description Sets the SSID and SSID Length. Note that an Access Point can have either a visible or hidden SSID. If an Access Point uses a hidden SSID then an active scan must be used. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_ssid Pointer to SSID buffer ssidLength number of bytes in SSID Returns None 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-631 Remarks Do not include a string terminator in the SSID length. SSID's are case- sensitive. SSID length must be less than or equal to DRV_WIFI_MAX_SSID_LENGTH. Example uint8_t ssid[] = "MySSIDName"; uint8_t ssidLength = strlen(ssid); DRV_WIFI_SsidSet(ssid, ssidLength); 5.1.13.7.1.31 DRV_WIFI_SWMulticastFilterSet Function C void DRV_WIFI_SWMulticastFilterSet( DRV_WIFI_SWMULTICAST_CONFIG * p_config ); Description This function allows the application to configure up to two Multicast Address Filters on the MRF24W. If two active multicast filters are set up they are OR’d together – the MRF24W will receive and pass to the Host CPU received packets from either multicast address. The allowable values in p_config are: filterId -- DRV_WIFI_MULTICAST_FILTER_1 thru DRV_WIFI_MULTICAST_FILTER_16 action -- DRV_WIFI_MULTICAST_DISABLE_ALL (default) The Multicast Filter discards all received multicast messages – they will not be forwarded to the Host PIC. The remaining fields in this structure are ignored. DRV_WIFI_MULTICAST_ENABLE_ALL The Multicast Filter forwards all received multicast messages to the Host PIC. The remaining fields in this structure are ignored. DRV_WIFI_MULTICAST_USE_FILTERS The MAC filter will be used and the remaining fields in this structure configure which Multicast messages are forwarded to the Host PIC. macBytes -- Array containing the MAC address to filter on (using the destination address of each incoming 802.11 frame). Specific bytes with the MAC address can be designated as ‘don’t care’ bytes. See macBitMask. This field in only used if action = DRV_WIFI_MULTICAST_USE_FILTERS. macBitMask -- A byte where bits 5:0 correspond to macBytes[5:0]. If the bit is zero then the corresponding MAC byte must be an exact match for the frame to be forwarded to the Host PIC. If the bit is one then the corresponding MAC byte is a ‘don’t care’ and not used in the Multicast filtering process. This field in only used if action = DRV_WIFI_MULTICAST_USE_FILTERS. Preconditions WiFi initialization must be complete. DRV_WIFI_SWMultiCastFilterEnable() must have been called previously. Returns None. Remarks Cannot mix hardware and software multicast filters.. Example DRV_WIFI_SWMULTICAST_CONFIG config; uint8_t macMask[] = {01, 00, 5e, ff, ff, ff}; // (0xff are the don't care bytes) // configure software multicast filter 1 to filter multicast addresses that // start with 01:00:5e config.action = DRV_WIFI_MULTICAST_USE_FILTERS; config->filterId = DRV_WIFI_MULTICAST_FILTER_1; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-632 memcpy(config->macBytes, macMask, 6); config->macBitMask = 0x38; // bits 5:3 = 1 (don't care on bytes 3,4,5) // bits 2:0 = 0 (exact match required on bytes 0,1,2) 5.1.13.7.1.32 DRV_WIFI_TxModeGet Function C void DRV_WIFI_TxModeGet( uint8_t * p_mode ); Description This function gets the MRF24WG Tx mode. Preconditions WiFi initialization must be complete Returns None. Remarks None. Example uint8_t mode; DRV_WIFI_TxModeGet(&mode); 5.1.13.7.1.33 DRV_WIFI_TxModeSet Function C void DRV_WIFI_TxModeSet( uint8_t mode ); Description This function sets the MRF24WG Tx mode. mode Description DRV_WIFI_TXMODE_G_RATES Use all 802.11g rates (default) DRV_WIFI_TXMODE_B_RATES Use only 802.11b rates DRV_WIFI_TXMODE_LEGACY_RATES Use only 1 and 2 mbps rates Preconditions WiFi initialization must be complete Parameters Parameters Description mode Tx mode value (see description) Returns None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-633 Remarks None. Example DRV_WIFI_TxModeSet(DRV_WIFI_TXMODE_G_RATES); 5.1.13.7.1.34 DRV_WIFI_TxPowerFactoryMaxGet Function C void DRV_WIFI_TxPowerFactoryMaxGet( int8_t * p_factoryMaxTxPower ); Description This function retrieves the factory-set max tx power from the MRF24WG. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_factoryMaxTxPower pointer to where factory max power is written (dbM) Returns None. Remarks None. Example int8_t maxPower; DRV_WIFI_TxPowerFactoryMaxGet(&maxPower); 5.1.13.7.1.35 DRV_WIFI_TxPowerMaxGet Function C void DRV_WIFI_TxPowerMaxGet( int8_t * p_maxTxPower ); Description Gets the Tx max power setting from the MRF24WG. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_maxTxPower pointer to where max power setting is written (dBm). Returns None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-634 Remarks None Example int8_t maxPower; DRV_WIFI_TxPowerMaxGet(&maxPower); 5.1.13.7.1.36 DRV_WIFI_TxPowerMaxSet Function C void DRV_WIFI_TxPowerMaxSet( int8_t maxTxPower ); Description After initialization the MRF24WG0M max Tx power is determined by a factory-set value. This function can set a different maximum Tx power levels. However, this function can never set a maximum Tx power greater than the factory-set value, which can be read via DRV_WIFI_TxPowerFactoryMaxGet(). Preconditions WiFi initialization must be complete. Parameters Parameters Description maxTxPower valid range (0 to 17 dBm) Returns None. Remarks No conversion of units needed, input to MRF24WG0M is in dBm. Example DRV_WIFI_TxPowerMaxSet(8); // set max Tx power to 8dBm 5.1.13.7.1.37 DRV_WIFI_WepKeyTypeGet Function C void DRV_WIFI_WepKeyTypeGet( uint8_t * p_wepKeyType ); Description This function gets the WEP key type: • DRV_WIFI_SECURITY_WEP_SHAREDKEY • DRV_WIFI_SECURITY_WEP_OPENKEY Preconditions WiFi initialization must be complete. Returns None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-635 Remarks None. Example uint8_t wepKeyType; DRV_WIFI_WepKeyTypeGet(&wepKeyType); 5.1.13.7.1.38 DRV_WIFI_WPSCredentialsGet Function C void DRV_WIFI_WPSCredentialsGet( DRV_WIFI_WPS_CREDENTIAL * p_cred ); Description This function gets the WPS credentials from the MRF24WG Preconditions WiFi initialization must be complete. Returns None. Remarks None. Example DRV_WIFI_WPS_CREDENTIAL cred;; DRV_WIFI_WPSCredentialsGet(&cred); 5.1.13.7.1.39 DRV_WIFI_AdhocContextSet Function C void DRV_WIFI_AdhocContextSet( DRV_WIFI_ADHOC_NETWORK_CONTEXT * p_context ); Description This function sets the AdHoc context. It is only applicable when the DRV_WIFI_NETWORK_TYPE_ADHOC has been selected in DRV_WIFI_NetworkTypeSet(). Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context pointer to AdHoc context data; see definition for the DRV_WIFI_ADHOC_NETWORK_CONTEXT structure. Returns None Remarks None 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-636 Example DRV_WIFI_ADHOC_NETWORK_CONTEXT adHocContext; adHocContext.mode = DRV_WIFI_ADHOC_CONNECT_THEN_START; adHocContext.hiddenSsid = false; adHocContext.beaconPeriod = DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD; DRV_WIFI_AdhocContextSet(&adHocContext); 5.1.13.7.1.40 DRV_WIFI_RssiGet Function C void DRV_WIFI_RssiGet( uint8_t * p_rssi ); Description This function retrieves the value set in Gets RSSI value set in DRV_WIFI_RssiSet(). It does not retrieve the current connection RSSI value. The scan result will yield the current RSSI. Preconditions WiFi initialization must be complete Parameters Parameters Description p_rssi pointer where rssi value is written Returns None Remarks None Example uint8_t rssi; DRV_WIFI_RssiGet(&rssi); 5.1.13.7.1.41 DRV_WIFI_RssiSet Function C void DRV_WIFI_RssiSet( uint8_t rssi ); Description This setting is only used if: 1) Neither an SSID or BSSID has been configured or 2) An SSID is defined and multiple AP's are discovered with the same SSID rssi Description 0 Connect to first network found 1-254 Only connect to network if the RSSI is greater or equal to this value 255 Connect to the highest RSSI found (default) 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-637 Preconditions WiFi initialization must be complete Parameters Parameters Description rssi See description Returns None Remarks Rarely needed Example DRV_WIFI_RssiSet(255); 5.1.13.7.1.42 DRV_WIFI_GratuitousArpStart Function C void DRV_WIFI_GratuitousArpStart( uint8_t period ); Description This function starts a gratuitous ARP response to be periodically transmitted. Preconditions WiFi initialization must be complete. Connection process must be complete. Parameters Parameters Description period period between gratuitous ARP, in seconds Returns None. Remarks None. Example DRV_WIFI_GratuitousArpStart(10); // begin sending gratuitous ARP's every // 10 seconds. 5.1.13.7.1.43 DRV_WIFI_GratuitousArpStop Function C void DRV_WIFI_GratuitousArpStop(); Description This function stops a gratuitous ARP. Preconditions WiFi initialization must be complete. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-638 Returns None. Remarks None. Example DRV_WIFI_GratuitousArpStop(); 5.1.13.7.1.44 DRV_WIFI_HibernateEnable Function C void DRV_WIFI_HibernateEnable(); Description Enables Hibernate mode on the MRF24W, which effectively turns off the device for maximum power savings. MRF24W state is not maintained when it transitions to hibernate mode. Preconditions WiFi initialization must be complete. Returns None. Remarks None Example DRV_WIFI_HibernateEnable(); 5.1.13.7.1.45 DRV_WIFI_isHibernateEnable Function C bool DRV_WIFI_isHibernateEnable(); Description Checks if MRF24W is in hibernate mode Preconditions WiFi initialization must be complete. Returns true or false Remarks None Example bool flag; flag = DRV_WIFI_isHibernateEnable(); 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-639 5.1.13.7.1.46 DRV_WIFI_PsPollDisable Function C void DRV_WIFI_PsPollDisable(); Description Disables PS Poll mode. The MRF24W will stay active and not go sleep. Preconditions WiFi initialization must be complete. Returns None. Remarks None. Example DRV_WIFI_PsPollDisable(&context); 5.1.13.7.1.47 DRV_WIFI_PsPollEnable Function C void DRV_WIFI_PsPollEnable( DRV_WIFI_PS_POLL_CONTEXT * p_context ); Description Enables PS Poll mode. PS-Poll (Power-Save Poll) is a mode allowing for longer battery life. The MRF24W coordinates with the Access Point to go to sleep and wake up at periodic intervals to check for data messages, which the Access Point will buffer. The listenInterval in the Connection Algorithm defines the sleep interval. By default, PS-Poll mode is disabled. When PS Poll is enabled, the WF Host Driver will automatically force the MRF24W to wake up each time the Host sends Tx data or a control message to the MRF24W. When the Host message transaction is complete the MRF24W driver will automatically re-enable PS Poll mode. When the application is likely to experience a high volume of data traffic then PS-Poll mode should be disabled for two reasons: 1. No power savings will be realized in the presence of heavy data traffic. 2. Performance will be impacted adversely as the WiFi Host Driver continually activates and deactivates PS-Poll mode via SPI messages. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_context Pointer to ps poll context. See DRV_WIFI_PS_POLL_CONTEXT structure. Returns None. Remarks None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-640 Example DRV_WIFI_PS_POLL_CONTEXT context; context.listenInterval = DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL; context.dtimInterval = DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL; context.useDtim = DRV_WIFI_DEFAULT_PS_DTIM_ENABLED; DRV_WIFI_PsPollEnable(&context); 5.1.13.7.2 System Configuration Functions 5.1.13.7.2.1 DRV_WIFI_Connect Function C void DRV_WIFI_Connect(); Description This function causes the MRF24WG to connect to a WiFi network. Upon connection, or a failure to connect, an event will be generated. Preconditions WiFi initialization must be complete and relevant connection parameters must have been set. Returns None Remarks None Example DRV_WIFI_Connect(); 5.1.13.7.2.2 DRV_WIFI_Deinitialize Function C bool DRV_WIFI_Deinitialize(); Description This function deinitializes the MRF24WG driver. It also saves the WiFi parameters in non-volatile storage. Preconditions None. Returns If successful returns true, else false. Remarks None 5.1.13.7.2.3 DRV_WIFI_Disconnect Function C uint16_t DRV_WIFI_Disconnect(); 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-641 Description This function causes the MRF24WG to disconnect from a WiFi network. No event is generated when a connection is terminated via the function call. Preconditions WiFi initialization must be complete and a connection must be in progress. Returns DRV_WIFI_SUCCESS or DRV_WIFI_ERROR_DISCONNECT_FAILED Remarks None Example DRV_WIFI_Disconnect(); 5.1.13.7.2.4 DRV_WIFI_Initialize Function C bool DRV_WIFI_Initialize( void* pNetIf ); Description Initialization Functions ----------------------- *************************************************************************** This function initializes the MRF24WG driver, making it ready for clients to use. Preconditions None. Parameters Parameters Description pNetIf Pointer to network interface Returns If successful returns true, else false. Remarks This function must be called before any other WiFi routine is called. Currently, this function performs no work, but that may change in the future. The WiFi initialization takes place in a state machine called by MRF24W_MACInit(). 5.1.13.7.2.5 DRV_WIFI_Scan Function C uint16_t DRV_WIFI_Scan( bool scanAll ); Description Directs the MRF24W to initiate a scan operation. The Host Application will be notified that the scan results are ready when it 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-642 receives the WF_EVENT_SCAN_RESULTS_READY event. The eventInfo field for this event will contain the number of scan results. Once the scan results are ready they can be retrieved with DRV_WIFI_ScanGetResult(). Scan results are retained on the MRF24W until: 1. Calling DRV_WIFI_Scan() again (after scan results returned from previous call). 2. MRF24W reset. Preconditions WiFi initialization must be complete. Parameters Parameters Description 5.1.13.7.3 Miscellaneous Functions 5.1.13.7.3.1 DRV_WIFI_ConfigDataErase Function C bool DRV_WIFI_ConfigDataErase(); Description This function erases configuration data from the board EEPROM. Preconditions TCPIP stack should be initialized. Returns None Remarks None. 5.1.13.7.3.2 DRV_WIFI_ConfigDataLoad Function C bool DRV_WIFI_ConfigDataLoad(); Description This function loads configuration data from the board EEPROM. If not present or corrupted then default values will be used. Preconditions TCPIP stack should be initialized. Returns None Remarks None. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-643 5.1.13.7.3.3 DRV_WIFI_ConfigDataPrint Function C void DRV_WIFI_ConfigDataPrint(); Description This function outputs configuration data from the board EEPROM. Preconditions TCPIP stack should be initialized. Returns None Remarks None. 5.1.13.7.3.4 DRV_WIFI_ConfigDataSave Function C bool DRV_WIFI_ConfigDataSave(); Description This function saves configuration data to the board EEPROM. Preconditions TCPIP stack should be initialized. Returns None Remarks None. 5.1.13.7.3.5 DRV_WIFI_ProcessEvent Function C void DRV_WIFI_ProcessEvent( uint16_t event, uint16_t eventInfo ); Description This function is called to process a WiFi event, Preconditions TCPIP stack should be initialized. Parameters Parameters Description event event code eventInfo additional information about the event. Not all events have associated info, in which case this value will be set to DRV_WIFI_NO_ADDITIONAL_INFO (0xff) 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-644 Returns None Remarks None. 5.1.13.7.3.6 DRV_WIFI_ScanGetResult Function C void DRV_WIFI_ScanGetResult( uint8_t listIndex, DRV_WIFI_SCAN_RESULT * p_scanResult ); Description After a scan has completed this function is used to read one scan result at a time from the MRF24WG. Preconditions WiFi initialization must be complete. WF_EVENT_SCAN_RESULTS_READY event must have already occurrerd. Parameters Parameters Description listIndex Index (0-based list) of the scan entry to retrieve. p_scanResult Pointer to where scan result is written. See DRV_WIFI_SCAN_RESULT structure. Returns None. Remarks None. Example DRV_WIFI_SCAN_RESULT scanResult; DRV_WIFI_ScanGetResult(0, &scanResult); // get first scan result in list 5.1.13.7.3.7 DRV_WIFI_SetLinkDownThreshold Function C void DRV_WIFI_SetLinkDownThreshold( uint8_t threshold ); Description This function allows the application to set the number of MRF24W consecutive Tx failures before the connection failure event (DRV_WIFI_LINK_LOST) is reported to the host application. Preconditions WiFi initialization must be complete Parameters Parameters Description threshold -- 0 disabled (default) 1-255 number of consecutive Tx failures before connection failure event is reported 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-645 Returns None. Remarks None. Example DRV_WIFI_SetLinkDownThreshold(0); // disable link down threshold 5.1.13.7.3.8 DRV_WIFI_SetPSK Function C void DRV_WIFI_SetPSK( uint8_t * p_psk ); Description This function is used in conjunction with DRV_WIFI_YieldPassphraseToHost(). It sends the binary key to the MRF24WG after the host has converted an ASCII passphrase to a binary key. Preconditions WiFi initialization must be complete. Parameters Parameters Description p_psk pointer to the binary key Returns None. Remarks None. Example DRV_WIFI_YieldPassphraseToHost(&info); 5.1.13.7.3.9 DRV_WIFI_SWMultiCastFilterEnable Function C void DRV_WIFI_SWMultiCastFilterEnable(); Description This function allows the application to configure up to max 16 software multicast address Filters on the MRF24WG0MA/B. Preconditions WiFi initialization must be complete. Returns None. Remarks Cannot mix hardware and software multicast filters.. Example DRV_WIFI_SWMultiCastFilterEnable(); 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-646 5.1.13.7.3.10 DRV_WIFI_YieldPassphraseToHost Function C void DRV_WIFI_YieldPassphraseToHost(); Description During WPS the MRF24WG will receive a passphrase. That passphrase must be converted to a binary key. The MRF24WG can do this, but it will take 20-30 seconds. The host MCU will be able to convert the passphrase to a binary key much faster. If that is desired, then this function should be called to request the MRF24WG to signal the DRV_WIFI_EVENT_KEY_CALCULATION_REQUEST event when the passphrase is ready. Then the host can retrieve the passphrase (see DRV_WIFI_WPSCredentialsGet()), convert to a binary key (see DRV_WIFI_ConvPassphraseToKey()), and send it back to the MRF24WG via the DRV_WIFI_SetPSK() function. Preconditions WiFi initialization must be complete. Returns None. Remarks None. Example DRV_WIFI_YieldPassphraseToHost(&info); 5.1.13.7.4 Data Types and Constants 5.1.13.7.4.1 DRV_WIFI_BSSID_LENGTH Macro C #define DRV_WIFI_BSSID_LENGTH (6) Description This is macro DRV_WIFI_BSSID_LENGTH. 5.1.13.7.4.2 DRV_WIFI_DEAUTH_REASONCODE_MASK Macro C #define DRV_WIFI_DEAUTH_REASONCODE_MASK ((uint8_t)0x80) Description This is macro DRV_WIFI_DEAUTH_REASONCODE_MASK. 5.1.13.7.4.3 DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD Macro C #define DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD (100) // ms Description ms 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-647 5.1.13.7.4.4 DRV_WIFI_DEFAULT_ADHOC_HIDDEN_SSID Macro C #define DRV_WIFI_DEFAULT_ADHOC_HIDDEN_SSID false Description WiFi AdHoc default settings These defines identify various default WiFi AdHoc settings that can be used in the DRV_WIFI_ADHOC_NETWORK_CONTEXT structure. 5.1.13.7.4.5 DRV_WIFI_DEFAULT_ADHOC_MODE Macro C #define DRV_WIFI_DEFAULT_ADHOC_MODE DRV_WIFI_ADHOC_CONNECT_THEN_START Description This is macro DRV_WIFI_DEFAULT_ADHOC_MODE. 5.1.13.7.4.6 DRV_WIFI_DEFAULT_PS_DTIM_ENABLED Macro C #define DRV_WIFI_DEFAULT_PS_DTIM_ENABLED true // DTIM wake-up enabled (normally the case) Description DTIM wake-up enabled (normally the case) 5.1.13.7.4.7 DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL Macro C #define DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL ((uint16_t)2) // number of beacon periods Description number of beacon periods 5.1.13.7.4.8 DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL Macro C #define DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL ((uint16_t)1) // 100ms multiplier, e.g. 1 * 100ms = 100ms Description 100ms multiplier, e.g. 1 * 100ms = 100ms 5.1.13.7.4.9 DRV_WIFI_DEFAULT_SCAN_COUNT Macro C #define DRV_WIFI_DEFAULT_SCAN_COUNT (1) Description WiFi Scan Context default settings 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-648 This enumeration identifies the default WiFi scan context values that can be used in the DRV_WIFI_SCAN_CONTEXT structure. 5.1.13.7.4.10 DRV_WIFI_DEFAULT_SCAN_MAX_CHANNEL_TIME Macro C #define DRV_WIFI_DEFAULT_SCAN_MAX_CHANNEL_TIME (400) // ms Description ms 5.1.13.7.4.11 DRV_WIFI_DEFAULT_SCAN_MIN_CHANNEL_TIME Macro C #define DRV_WIFI_DEFAULT_SCAN_MIN_CHANNEL_TIME (200) // ms Description ms 5.1.13.7.4.12 DRV_WIFI_DEFAULT_SCAN_PROBE_DELAY Macro C #define DRV_WIFI_DEFAULT_SCAN_PROBE_DELAY (20) // us Description us 5.1.13.7.4.13 DRV_WIFI_DEFAULT_WEP_KEY_TYPE Macro C #define DRV_WIFI_DEFAULT_WEP_KEY_TYPE DRV_WIFI_SECURITY_WEP_OPENKEY Description see DRV_WIFI_SecurityWepSet() and DRV_WIFI_WEP_CONTEXT 5.1.13.7.4.14 DRV_WIFI_DISABLED Macro C #define DRV_WIFI_DISABLED (0) Description Do not make this an enumerated type! 5.1.13.7.4.15 DRV_WIFI_DISASSOC_REASONCODE_MASK Macro C #define DRV_WIFI_DISASSOC_REASONCODE_MASK ((uint8_t)0x40) Description This is macro DRV_WIFI_DISASSOC_REASONCODE_MASK. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-649 5.1.13.7.4.16 DRV_WIFI_ENABLED Macro C #define DRV_WIFI_ENABLED (1) Description This is macro DRV_WIFI_ENABLED. 5.1.13.7.4.17 DRV_WIFI_MAX_CHANNEL_LIST_LENGTH Macro C #define DRV_WIFI_MAX_CHANNEL_LIST_LENGTH (14) Description This is macro DRV_WIFI_MAX_CHANNEL_LIST_LENGTH. 5.1.13.7.4.18 DRV_WIFI_MAX_NUM_RATES Macro C #define DRV_WIFI_MAX_NUM_RATES (8) Description This is macro DRV_WIFI_MAX_NUM_RATES. 5.1.13.7.4.19 DRV_WIFI_MAX_SECURITY_KEY_LENGTH Macro C #define DRV_WIFI_MAX_SECURITY_KEY_LENGTH (64) Description This is macro DRV_WIFI_MAX_SECURITY_KEY_LENGTH. 5.1.13.7.4.20 DRV_WIFI_MAX_SSID_LENGTH Macro C #define DRV_WIFI_MAX_SSID_LENGTH (32) Description This is macro DRV_WIFI_MAX_SSID_LENGTH. 5.1.13.7.4.21 DRV_WIFI_MAX_WEP_KEY_LENGTH Macro C #define DRV_WIFI_MAX_WEP_KEY_LENGTH (DRV_WIFI_WEP104_KEY_LENGTH) Description This is macro DRV_WIFI_MAX_WEP_KEY_LENGTH. 5.1.13.7.4.22 DRV_WIFI_MAX_WPA_PASS_PHRASE_LENGTH Macro C #define DRV_WIFI_MAX_WPA_PASS_PHRASE_LENGTH (64) // must include string terminator 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-650 Description must include string terminator 5.1.13.7.4.23 DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH Macro C #define DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH (64) Description This is macro DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH. 5.1.13.7.4.24 DRV_WIFI_MIN_WPA_PASS_PHRASE_LENGTH Macro C #define DRV_WIFI_MIN_WPA_PASS_PHRASE_LENGTH (8) Description Key size defines 5.1.13.7.4.25 DRV_WIFI_NETWORK_TYPE_ADHOC Macro C #define DRV_WIFI_NETWORK_TYPE_ADHOC (2) Description This is macro DRV_WIFI_NETWORK_TYPE_ADHOC. 5.1.13.7.4.26 DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE Macro C #define DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE (1) Description WiFi Network Types This enumeration identifies the WiFi network types that can be selected. Do NOT make these an enumerated type as they are used as a compile switch. 5.1.13.7.4.27 DRV_WIFI_NETWORK_TYPE_P2P Macro C #define DRV_WIFI_NETWORK_TYPE_P2P (3) /* not supported */ Description not supported 5.1.13.7.4.28 DRV_WIFI_NETWORK_TYPE_SOFT_AP Macro C #define DRV_WIFI_NETWORK_TYPE_SOFT_AP (4) 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-651 Description This is macro DRV_WIFI_NETWORK_TYPE_SOFT_AP. 5.1.13.7.4.29 DRV_WIFI_NO_ADDITIONAL_INFO Macro C #define DRV_WIFI_NO_ADDITIONAL_INFO ((uint16_t)0xffff) Description eventInfo define for DRV_WIFI_ProcessEvent() when no additional info is supplied 5.1.13.7.4.30 DRV_WIFI_RETRY_ADHOC Macro C #define DRV_WIFI_RETRY_ADHOC (3) Description This is macro DRV_WIFI_RETRY_ADHOC. 5.1.13.7.4.31 DRV_WIFI_RETRY_FOREVER Macro C #define DRV_WIFI_RETRY_FOREVER (255) Description This is macro DRV_WIFI_RETRY_FOREVER. 5.1.13.7.4.32 DRV_WIFI_RTS_THRESHOLD_MAX Macro C #define DRV_WIFI_RTS_THRESHOLD_MAX (2347) /* maximum RTS threshold size in bytes */ Description maximum RTS threshold size in bytes 5.1.13.7.4.33 DRV_WIFI_SECURITY_EAP Macro C #define DRV_WIFI_SECURITY_EAP (11) Description This is macro DRV_WIFI_SECURITY_EAP. 5.1.13.7.4.34 DRV_WIFI_SECURITY_OPEN Macro C #define DRV_WIFI_SECURITY_OPEN (0) Description WiFi Security Types This enumeration identifies the WiFi security types that can be selected. Do NOT make these an enumerated type as they are 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-652 used as a compile switch. 5.1.13.7.4.35 DRV_WIFI_SECURITY_WEP_104 Macro C #define DRV_WIFI_SECURITY_WEP_104 (2) Description This is macro DRV_WIFI_SECURITY_WEP_104. 5.1.13.7.4.36 DRV_WIFI_SECURITY_WEP_40 Macro C #define DRV_WIFI_SECURITY_WEP_40 (1) Description This is macro DRV_WIFI_SECURITY_WEP_40. 5.1.13.7.4.37 DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY Macro C #define DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY (7) Description This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY. 5.1.13.7.4.38 DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE Macro C #define DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE (8) Description This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE. 5.1.13.7.4.39 DRV_WIFI_SECURITY_WPA_WITH_KEY Macro C #define DRV_WIFI_SECURITY_WPA_WITH_KEY (3) Description This is macro DRV_WIFI_SECURITY_WPA_WITH_KEY. 5.1.13.7.4.40 DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE Macro C #define DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE (4) Description This is macro DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-653 5.1.13.7.4.41 DRV_WIFI_SECURITY_WPA2_WITH_KEY Macro C #define DRV_WIFI_SECURITY_WPA2_WITH_KEY (5) Description This is macro DRV_WIFI_SECURITY_WPA2_WITH_KEY. 5.1.13.7.4.42 DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE Macro C #define DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE (6) Description This is macro DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE. 5.1.13.7.4.43 DRV_WIFI_SECURITY_WPS_PIN Macro C #define DRV_WIFI_SECURITY_WPS_PIN (10) Description This is macro DRV_WIFI_SECURITY_WPS_PIN. 5.1.13.7.4.44 DRV_WIFI_SECURITY_WPS_PUSH_BUTTON Macro C #define DRV_WIFI_SECURITY_WPS_PUSH_BUTTON (9) Description This is macro DRV_WIFI_SECURITY_WPS_PUSH_BUTTON. 5.1.13.7.4.45 DRV_WIFI_VERSION_NUMBER Macro C #define DRV_WIFI_VERSION_NUMBER "3.0.0" Description WiFi Driver Version Number 5.1.13.7.4.46 DRV_WIFI_WEP104_KEY_LENGTH Macro C #define DRV_WIFI_WEP104_KEY_LENGTH (52) // 4 keys of 13 bytes each Description 4 keys of 13 bytes each 5.1.13.7.4.47 DRV_WIFI_WEP40_KEY_LENGTH Macro C #define DRV_WIFI_WEP40_KEY_LENGTH (20) // 4 keys of 5 bytes each 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-654 Description 4 keys of 5 bytes each 5.1.13.7.4.48 DRV_WIFI_WPA_KEY_LENGTH Macro C #define DRV_WIFI_WPA_KEY_LENGTH (32) Description This is macro DRV_WIFI_WPA_KEY_LENGTH. 5.1.13.7.4.49 DRV_WIFI_WPA2_KEY_LENGTH Macro C #define DRV_WIFI_WPA2_KEY_LENGTH (32) Description This is macro DRV_WIFI_WPA2_KEY_LENGTH. 5.1.13.7.4.50 DRV_WIFI_WPS_PIN_LENGTH Macro C #define DRV_WIFI_WPS_PIN_LENGTH (8) // 7 digits + checksum byte Description 7 digits + checksum byte 5.1.13.7.4.51 DRV_WIFI_ADHOC_MODES Enumeration C typedef enum adhocMode { DRV_WIFI_ADHOC_CONNECT_THEN_START = 0, DRV_WIFI_ADHOC_CONNECT_ONLY = 1, DRV_WIFI_ADHOC_START_ONLY = 2 } DRV_WIFI_ADHOC_MODES; Description AdHoc Modes This enumeration identifies the AdHoc modes that can be selelcted when connecting in AdHoc mode. Members Members Description DRV_WIFI_ADHOC_CONNECT_THEN_START = 0 try to connect existing AdHoc network, if not found then start network DRV_WIFI_ADHOC_CONNECT_ONLY = 1 only connect to existing AdHoc network DRV_WIFI_ADHOC_START_ONLY = 2 only start a new AdHoc network 5.1.13.7.4.52 DRV_WIFI_ADHOC_NETWORK_CONTEXT Structure C typedef struct { uint8_t mode; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-655 bool hiddenSsid; uint16_t beaconPeriod; } DRV_WIFI_ADHOC_NETWORK_CONTEXT; Description WiFi AdHoc Context This structure contains MRF24WG AdHoc context data. See DRV_WIFI_AdhocContextSet(). Members Members Description uint8_t mode; Defines how to start the AdHoc network. See DRV_WIFI_ADHOC_MODE. Default is DRV_WIFI_ADHOC_CONNECT_THEN_START. bool hiddenSsid; When starting an AdHoc network, the SSID can be hidden in the beacons. Set true to hide the SSID, else false. Default is false. uint16_t beaconPeriod; Sets the beacon period, in ms. Default is 100ms 5.1.13.7.4.53 DRV_WIFI_CONNECTION_CONTEXT Structure C typedef struct { uint8_t channel; uint8_t bssid[6]; } DRV_WIFI_CONNECTION_CONTEXT; Description WiFi Connection Context This structure contains MRF24WG connection context data. See DRV_WIFI_ConnectContextGet(). Members Members Description uint8_t channel; channel number of current connection uint8_t bssid[6]; bssid of connected AP 5.1.13.7.4.54 DRV_WIFI_CONNECTION_STATES Enumeration C typedef enum { DRV_WIFI_CSTATE_NOT_CONNECTED = 1, DRV_WIFI_CSTATE_CONNECTION_IN_PROGRESS = 2, DRV_WIFI_CSTATE_CONNECTED_INFRASTRUCTURE = 3, DRV_WIFI_CSTATE_CONNECTED_ADHOC = 4, DRV_WIFI_CSTATE_RECONNECTION_IN_PROGRESS = 5, DRV_WIFI_CSTATE_CONNECTION_PERMANENTLY_LOST = 6 } DRV_WIFI_CONNECTION_STATES; Description WiFi Connection States This enumeration identifies WiFi Connection states states. See DRV_WIFI_ConnectionStateGet(). Members Members Description DRV_WIFI_CSTATE_NOT_CONNECTED = 1 No WiFi connection exists 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-656 DRV_WIFI_CSTATE_CONNECTION_IN_PROGRESS = 2 WiFi connection in progress DRV_WIFI_CSTATE_CONNECTED_INFRASTRUCTURE = 3 WiFi connected in infrastructure mode DRV_WIFI_CSTATE_CONNECTED_ADHOC = 4 WiFi connected in adhoc mode DRV_WIFI_CSTATE_RECONNECTION_IN_PROGRESS = 5 WiFi in process of reconnecting DRV_WIFI_CSTATE_CONNECTION_PERMANENTLY_LOST = 6 WiFi connection permanently lost 5.1.13.7.4.55 DRV_WIFI_DEVICE_INFO Structure C typedef struct { uint8_t deviceType; uint8_t romVersion; uint8_t patchVersion; } DRV_WIFI_DEVICE_INFO; Description WiFi Device Type/Version This structure contains MRF24WG device type and version number. See DRV_WIFI_DeviceInfoGet(). Members Members Description uint8_t deviceType; MRF24W_DEVICE_TYPE uint8_t romVersion; MRF24WG ROM version number uint8_t patchVersion; MRF24WG patch version number 5.1.13.7.4.56 DRV_WIFI_DEVICE_TYPES Enumeration C typedef enum { DRV_WIFI_MRF24WB0M_DEVICE = 1, DRV_WIFI_MRF24WG0M_DEVICE = 2 } DRV_WIFI_DEVICE_TYPES; Description WiFi devices types This enumeration identifies WiFi device types. The only device supported with this driver is DRV_WIFI_MRF24WG0M_DEVICE 5.1.13.7.4.57 DRV_WIFI_DOMAIN_CODES Enumeration C typedef enum { DRV_WIFI_DOMAIN_FCC = 0, DRV_WIFI_DOMAIN_ETSI = 2, DRV_WIFI_DOMAIN_JAPAN = 7, DRV_WIFI_DOMAIN_OTHER = 7 } DRV_WIFI_DOMAIN_CODES; Description WiFi regional domain codes 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-657 This enumeration identifies WiFi regional domain codes. The regional domain can be determined by calling DRV_WIFI_RegionalDomainGet(). Members Members Description DRV_WIFI_DOMAIN_FCC = 0 FCC, available channels: 1 - 11 DRV_WIFI_DOMAIN_ETSI = 2 ESTI, available Channels: 1 - 13 DRV_WIFI_DOMAIN_JAPAN = 7 Japan, available Channels: 1 - 14 DRV_WIFI_DOMAIN_OTHER = 7 Other, available Channels: 1 - 14 5.1.13.7.4.58 DRV_WIFI_EVENT_CONN_TEMP_LOST_CODES Enumeration C typedef enum { DRV_WIFI_BEACON_TIMEOUT = 1, DRV_WIFI_DEAUTH_RECEIVED = 2, DRV_WIFI_DISASSOCIATE_RECEIVED = 3 } DRV_WIFI_EVENT_CONN_TEMP_LOST_CODES; Description 'Connection Temporarily Lost' event codes This enumeration identifies the codes for a connection temporarily lost. These codes are used in DRV_WIFI_ProcessEvent(), case DRV_WIFI_EVENT_CONNECTION_TEMPORARILY_LOST. Members Members Description DRV_WIFI_BEACON_TIMEOUT = 1 connection temporarily lost due to beacon timeout DRV_WIFI_DEAUTH_RECEIVED = 2 connection temporarily lost due to deauth received from AP DRV_WIFI_DISASSOCIATE_RECEIVED = 3 connection temporarily lost due to disassociation received from AP 5.1.13.7.4.59 DRV_WIFI_EVENT_INFO Enumeration C typedef enum { DRV_WIFI_JOIN_FAILURE = 2, DRV_WIFI_AUTHENTICATION_FAILURE = 3, DRV_WIFI_ASSOCIATION_FAILURE = 4, DRV_WIFI_WEP_HANDSHAKE_FAILURE = 5, DRV_WIFI_PSK_CALCULATION_FAILURE = 6, DRV_WIFI_PSK_HANDSHAKE_FAILURE = 7, DRV_WIFI_ADHOC_JOIN_FAILURE = 8, DRV_WIFI_SECURITY_MISMATCH_FAILURE = 9, DRV_WIFI_NO_SUITABLE_AP_FOUND_FAILURE = 10, DRV_WIFI_RETRY_FOREVER_NOT_SUPPORTED_FAILURE = 11, DRV_WIFI_LINK_LOST = 12, DRV_WIFI_TKIP_MIC_FAILURE = 13, DRV_WIFI_RSN_MIXED_MODE_NOT_SUPPORTED = 14, DRV_WIFI_RECV_DEAUTH = 15, DRV_WIFI_RECV_DISASSOC = 16, DRV_WIFI_WPS_FAILURE = 17, DRV_WIFI_P2P_FAILURE = 18 } DRV_WIFI_EVENT_INFO; Description EventInfo types 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-658 This enumeration identifies the eventInfo types used in DRV_WIFI_ProcessEvent(), case DRV_WIFI_EVENT_CONNECTION_FAILED. Members Members Description DRV_WIFI_P2P_FAILURE = 18 not supported 5.1.13.7.4.60 DRV_WIFI_EVENTS Enumeration C typedef enum { DRV_WIFI_EVENT_NONE = 0, DRV_WIFI_EVENT_CONNECTION_SUCCESSFUL = 1, DRV_WIFI_EVENT_CONNECTION_FAILED = 2, DRV_WIFI_EVENT_CONNECTION_TEMPORARILY_LOST = 3, DRV_WIFI_EVENT_CONNECTION_PERMANENTLY_LOST = 4, DRV_WIFI_EVENT_CONNECTION_REESTABLISHED = 5, DRV_WIFI_EVENT_FLASH_UPDATE_SUCCESSFUL = 6, DRV_WIFI_EVENT_FLASH_UPDATE_FAILED = 7, DRV_WIFI_EVENT_KEY_CALCULATION_REQUEST = 8, DRV_WIFI_EVENT_SCAN_RESULTS_READY = 9, DRV_WIFI_EVENT_IE_RESULTS_READY = 10, DRV_WIFI_EVENT_INVALID_WPS_PIN = 12, DRV_WIFI_EVENT_SOFT_AP = 13, DRV_WIFI_EVENT_DISCONNECT_DONE = 14, DRV_WIFI_EVENT_ERROR = 15 } DRV_WIFI_EVENTS; Description WiFi Events This enumeration identifies the WiFi events that can occur and will be sent to DRV_WIFI_ProcessEvent(). Members Members Description DRV_WIFI_EVENT_NONE = 0 No event has occurred DRV_WIFI_EVENT_CONNECTION_SUCCESSFUL = 1 Connection attempt to network successful DRV_WIFI_EVENT_CONNECTION_FAILED = 2 Connection attempt failed DRV_WIFI_EVENT_CONNECTION_TEMPORARILY_LOST = 3 Connection lost; MRF24W attempting to reconnect DRV_WIFI_EVENT_CONNECTION_PERMANENTLY_LOST = 4 Connection lost; MRF24W no longer trying to connect DRV_WIFI_EVENT_CONNECTION_REESTABLISHED = 5 Connection has been reestablished DRV_WIFI_EVENT_FLASH_UPDATE_SUCCESSFUL = 6 Update to FLASH successful DRV_WIFI_EVENT_FLASH_UPDATE_FAILED = 7 Update to FLASH failed DRV_WIFI_EVENT_KEY_CALCULATION_REQUEST = 8 Key calculation is required DRV_WIFI_EVENT_SCAN_RESULTS_READY = 9 scan results are ready DRV_WIFI_EVENT_IE_RESULTS_READY = 10 IE data ready DRV_WIFI_EVENT_INVALID_WPS_PIN = 12 Invalid WPS pin was entered DRV_WIFI_EVENT_SOFT_AP = 13 Client connection events DRV_WIFI_EVENT_DISCONNECT_DONE = 14 Disconnect done event DRV_WIFI_EVENT_ERROR = 15 WiFi error event occurred 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-659 5.1.13.7.4.61 DRV_WIFI_GENERAL_ERRORS Enumeration C typedef enum { DRV_WIFI_ERROR_IN_HIBERNATE_MODE = 100 } DRV_WIFI_GENERAL_ERRORS; Description This is type DRV_WIFI_GENERAL_ERRORS. Members Members Description DRV_WIFI_ERROR_IN_HIBERNATE_MODE = 100 invalid operation while MRF24WG is in hibernate mode 5.1.13.7.4.62 DRV_WIFI_HIBERNATE_STATE Structure C typedef struct { uint8_t state; uint8_t wakeup_notice; } DRV_WIFI_HIBERNATE_STATE; Description This is type DRV_WIFI_HIBERNATE_STATE. 5.1.13.7.4.63 DRV_WIFI_HIBERNATE_STATES Enumeration C typedef enum { DRV_WIFI_HB_NO_SLEEP = 0, DRV_WIFI_HB_ENTER_SLEEP = 1, DRV_WIFI_HB_WAIT_WAKEUP = 2 } DRV_WIFI_HIBERNATE_STATES; Description WiFi Hibernate states This enumeration identifies WiFi hibernate states. 5.1.13.7.4.64 DRV_WIFI_MAC_STATS Structure C typedef struct { uint32_t MibWEPExcludeCtr; uint32_t MibTxBytesCtr; uint32_t MibTxMulticastCtr; uint32_t MibTxFailedCtr; uint32_t MibTxRtryCtr; uint32_t MibTxMultRtryCtr; uint32_t MibTxSuccessCtr; uint32_t MibRxDupCtr; uint32_t MibRxCtsSuccCtr; uint32_t MibRxCtsFailCtr; uint32_t MibRxAckFailCtr; uint32_t MibRxBytesCtr; uint32_t MibRxFragCtr; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-660 uint32_t MibRxMultCtr; uint32_t MibRxFCSErrCtr; uint32_t MibRxWEPUndecryptCtr; uint32_t MibRxFragAgedCtr; uint32_t MibRxMICFailureCtr; } DRV_WIFI_MAC_STATS; Description WiFi MIB states This structure contains all the MIB data returned from the MRF24WG when DRV_WIFI_MacStatsGet() is called. Members Members Description uint32_t MibWEPExcludeCtr; Number of frames received with the Protected Frame subfield of the Frame Control field set to zero and the value of dot11ExcludeUnencrypted causes that frame to be discarded. uint32_t MibTxBytesCtr; Total number of Tx bytes that have been transmitted uint32_t MibTxMulticastCtr; Number of frames successfully transmitted that had the multicast bit set in the destination MAC address uint32_t MibTxFailedCtr; Number of Tx frames that failed due to the number of transmits exceeding the retry count uint32_t MibTxRtryCtr; Number of times a transmitted frame needed to be retried uint32_t MibTxMultRtryCtr; Number of times a frame was successfully transmitted after more than one retransmission. uint32_t MibTxSuccessCtr; Number of Tx frames successfully transmitted. uint32_t MibRxDupCtr; Number of frames received where the Sequence Control field indicates a duplicate. uint32_t MibRxCtsSuccCtr; Number of CTS frames received in response to an RTS frame. uint32_t MibRxCtsFailCtr; Number of times an RTS frame was not received in response to a CTS frame. uint32_t MibRxAckFailCtr; Number of times an Ack was not received in response to a Tx frame. uint32_t MibRxBytesCtr; Total number of Rx bytes received. uint32_t MibRxFragCtr; Number of successful received frames (management or data) uint32_t MibRxMultCtr; Number of frames received with the multicast bit set in the destination MAC address. uint32_t MibRxFCSErrCtr; Number of frames received with an invalid Frame Checksum (FCS). uint32_t MibRxWEPUndecryptCtr; Number of frames received where the Protected Frame subfield of the Frame Control Field is set to one and the WEPOn value for the key mapped to the transmitter?s MAC address indicates the frame should not have been encrypted. uint32_t MibRxFragAgedCtr; Number of times that fragments aged out, or were not received in the allowable time. uint32_t MibRxMICFailureCtr; Number of MIC failures that have occurred. 5.1.13.7.4.65 DRV_WIFI_MGMT_ERRORS Enumeration C typedef enum { DRV_WIFI_SUCCESS = 1, DRV_WIFI_ERROR_INVALID_SUBTYPE = 2, DRV_WIFI_ERROR_OPERATION_CANCELLED = 3, DRV_WIFI_ERROR_FRAME_END_OF_LINE_OCCURRED = 4, DRV_WIFI_ERROR_FRAME_RETRY_LIMIT_EXCEEDED = 5, DRV_WIFI_ERROR_EXPECTED_BSS_VALUE_NOT_IN_FRAME = 6, DRV_WIFI_ERROR_FRAME_SIZE_EXCEEDS_BUFFER_SIZE = 7, DRV_WIFI_ERROR_FRAME_ENCRYPT_FAILED = 8, DRV_WIFI_ERROR_INVALID_PARAM = 9, 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-661 DRV_WIFI_ERROR_AUTH_REQ_ISSUED_WHILE_IN_AUTH_STATE = 10, DRV_WIFI_ERROR_ASSOC_REQ_ISSUED_WHILE_IN_ASSOC_STATE = 11, DRV_WIFI_ERROR_INSUFFICIENT_RESOURCES = 12, DRV_WIFI_ERROR_TIMEOUT_OCCURRED = 13, DRV_WIFI_ERROR_BAD_EXCHANGE_ENCOUNTERED_IN_FRAME_RECEPTION = 14, DRV_WIFI_ERROR_AUTH_REQUEST_REFUSED = 15, DRV_WIFI_ERROR_ASSOCIATION_REQUEST_REFUSED = 16, DRV_WIFI_ERROR_PRIOR_MGMT_REQUEST_IN_PROGRESS = 17, DRV_WIFI_ERROR_NOT_IN_JOINED_STATE = 18, DRV_WIFI_ERROR_NOT_IN_ASSOCIATED_STATE = 19, DRV_WIFI_ERROR_NOT_IN_AUTHENTICATED_STATE = 20, DRV_WIFI_ERROR_SUPPLICANT_FAILED = 21, DRV_WIFI_ERROR_UNSUPPORTED_FEATURE = 22, DRV_WIFI_ERROR_REQUEST_OUT_OF_SYNC = 23, DRV_WIFI_ERROR_CP_INVALID_ELEMENT_TYPE = 24, DRV_WIFI_ERROR_CP_INVALID_PROFILE_ID = 25, DRV_WIFI_ERROR_CP_INVALID_DATA_LENGTH = 26, DRV_WIFI_ERROR_CP_INVALID_SSID_LENGTH = 27, DRV_WIFI_ERROR_CP_INVALID_SECURITY_TYPE = 28, DRV_WIFI_ERROR_CP_INVALID_SECURITY_KEY_LENGTH = 29, DRV_WIFI_ERROR_CP_INVALID_WEP_KEY_ID = 30, DRV_WIFI_ERROR_CP_INVALID_NETWORK_TYPE = 31, DRV_WIFI_ERROR_CP_INVALID_ADHOC_MODE = 32, DRV_WIFI_ERROR_CP_INVALID_SCAN_TYPE = 33, DRV_WIFI_ERROR_CP_INVALID_CP_LIST = 34, DRV_WIFI_ERROR_CP_INVALID_CHANNEL_LIST_LENGTH = 35, DRV_WIFI_ERROR_NOT_CONNECTED = 36, DRV_WIFI_ERROR_ALREADY_CONNECTING = 37, DRV_WIFI_ERROR_DISCONNECT_FAILED = 38, DRV_WIFI_ERROR_NO_STORED_BSS_DESCRIPTOR = 39, DRV_WIFI_ERROR_INVALID_MAX_POWER = 40, DRV_WIFI_ERROR_CONNECTION_TERMINATED = 41, DRV_WIFI_ERROR_HOST_SCAN_NOT_ALLOWED = 42, DRV_WIFI_ERROR_INVALID_WPS_PIN = 44 } DRV_WIFI_MGMT_ERRORS; Description Mgmt Msg Error Codes This enumeration identifies the errors that can occur when a DRV_WIFI API function call results in a mgmt message being sent, via SPI, to the MRF24W. Members Members Description DRV_WIFI_ERROR_DISCONNECT_FAILED = 38 Disconnect failed. Disconnect is allowed only when module is in connected state DRV_WIFI_ERROR_NO_STORED_BSS_DESCRIPTOR = 39 No stored scan results DRV_WIFI_ERROR_HOST_SCAN_NOT_ALLOWED = 42 Host Scan Failed. Host scan is allowed only in idle or connected state DRV_WIFI_ERROR_INVALID_WPS_PIN = 44 WPS pin was invalid 5.1.13.7.4.66 DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT Structure C typedef struct { uint8_t reason; uint8_t address[6]; } DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-662 Description WiFi Soft AP Event Information This structure contains data pertaining to Soft AP event. See DRV_WIFI_SoftApEventInfoGet(). Members Members Description uint8_t reason; reason code uint8_t address[6]; MAC address 5.1.13.7.4.67 DRV_WIFI_MULTICAST_FILTER_IDS Enumeration C typedef enum { DRV_WIFI_MULTICAST_FILTER_1 = 4, DRV_WIFI_MULTICAST_FILTER_2 = 5, DRV_WIFI_MULTICAST_FILTER_3 = 6, DRV_WIFI_MULTICAST_FILTER_4 = 7, DRV_WIFI_MULTICAST_FILTER_5 = 8, DRV_WIFI_MULTICAST_FILTER_6 = 9, DRV_WIFI_MULTICAST_FILTER_7 = 10, DRV_WIFI_MULTICAST_FILTER_8 = 11, DRV_WIFI_MULTICAST_FILTER_9 = 12, DRV_WIFI_MULTICAST_FILTER_10 = 13, DRV_WIFI_MULTICAST_FILTER_11 = 14, DRV_WIFI_MULTICAST_FILTER_12 = 15, DRV_WIFI_MULTICAST_FILTER_13 = 16, DRV_WIFI_MULTICAST_FILTER_14 = 17, DRV_WIFI_MULTICAST_FILTER_15 = 18, DRV_WIFI_MULTICAST_FILTER_16 = 19 } DRV_WIFI_MULTICAST_FILTER_IDS; Description Multicast Filter ID's This enumeration identifies the multicast filters that can be selected. See DRV_WIFI_SWMulticastFilterSet(). 5.1.13.7.4.68 DRV_WIFI_MULTICAST_FILTERS Enumeration C typedef enum { DRV_WIFI_MULTICAST_DISABLE_ALL = 0, DRV_WIFI_MULTICAST_ENABLE_ALL = 1, DRV_WIFI_MULTICAST_USE_FILTERS = 2 } DRV_WIFI_MULTICAST_FILTERS; Description Multicast Filter Modes This enumeration identifies the mode of multicast filters that can be selected. See DRV_WIFI_SWMulticastFilterSet(). Members Members Description DRV_WIFI_MULTICAST_DISABLE_ALL = 0 Discard all received multicast messages DRV_WIFI_MULTICAST_ENABLE_ALL = 1 forward all multicast messages to host MCU 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-663 DRV_WIFI_MULTICAST_USE_FILTERS = 2 Use the MAC filtering capability for multicast messages 5.1.13.7.4.69 DRV_WIFI_POWER_SAVE_STATES Enumeration C typedef enum { DRV_WIFI_PS_HIBERNATE = 1, DRV_WIFI_PS_PS_POLL_DTIM_ENABLED = 2, DRV_WIFI_PS_PS_POLL_DTIM_DISABLED = 3, DRV_WIFI_PS_OFF = 4 } DRV_WIFI_POWER_SAVE_STATES; Description WiFi Power Save states This enumeration identifies WiFi Power save states. See DRV_WIFI_PsPollEnable(). Members Members Description DRV_WIFI_PS_HIBERNATE = 1 enable hibernate mode DRV_WIFI_PS_PS_POLL_DTIM_ENABLED = 2 enable power save mode with DTIM enabled DRV_WIFI_PS_PS_POLL_DTIM_DISABLED = 3 enable power save mode with DTIM disabled DRV_WIFI_PS_OFF = 4 disable Power Save mode 5.1.13.7.4.70 DRV_WIFI_PS_POLL_CONTEXT Structure C typedef struct { uint16_t listenInterval; uint16_t dtimInterval; bool useDtim; } DRV_WIFI_PS_POLL_CONTEXT; Description WiFi PS-Poll Context This structure contains MRF24WG PS-Poll context data. See DRV_WIFI_PsPollEnable(). Members Members Description uint16_t listenInterval; Number of 100ms intervals between instances when the MRF24WG wakes up to received buffered messages from the network. Each count represents 100ms. For example, 1 = 100ms, 2 = 200ms, etc. The default is 1 (100ms). uint16_t dtimInterval; Only used if useDtim is true. The DTIM period indicates how often clients serviced by the access point should check for buffered multicast or broadcast messages awaiting pickup on the access point. The DTIM interval is measured in number of beacon periods. Default for DTIM period is 2. bool useDtim; True: (default) check for buffered multicast or broadcast messages on the dtimInterval. False: check for buffered multicast or broadcast messages on the listenInterval 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-664 5.1.13.7.4.71 DRV_WIFI_REASON_CODES Enumeration C typedef enum { DRV_WIFI_UNSPECIFIED = 1, DRV_WIFI_REASON_PREV_AUTH_NOT_VALID = 2, DRV_WIFI_DEAUTH_LEAVING = 3, DRV_WIFI_DISASSOC_DUE_TO_INACTIVITY = 4, DRV_WIFI_DISASSOC_AP_BUSY = 5, DRV_WIFI_CLASS2_FRAME_FROM_NONAUTH_STA = 6, DRV_WIFI_CLASS3_FRAME_FROM_NONASSOC_STA = 7, DRV_WIFI_DISASSOC_STA_HAS_LEFT = 8, DRV_WIFI_STA_REQ_ASSOC_WITHOUT_AUTH = 9, DRV_WIFI_INVALID_IE = 13, DRV_WIFI_MIC_FAILURE = 14, DRV_WIFI_4WAY_HANDSHAKE_TIMEOUT = 15, DRV_WIFI_GROUP_KEY_HANDSHAKE_TIMEOUT = 16, DRV_WIFI_IE_DIFFERENT = 17, DRV_WIFI_INVALID_GROUP_CIPHER = 18, DRV_WIFI_INVALID_PAIRWISE_CIPHER = 19, DRV_WIFI_INVALID_AKMP = 20, DRV_WIFI_UNSUPP_RSN_VERSION = 21, DRV_WIFI_INVALID_RSN_IE_CAP = 22, DRV_WIFI_IEEE8021X_FAILED = 23, DRV_WIFI_CIPHER_SUITE_REJECTED = 24 } DRV_WIFI_REASON_CODES; Description Deauth/Disassociate Reason Codes This enumeration identifies the reason codes for a connection lost due to a deauthorization or disassociation from the AP. 5.1.13.7.4.72 DRV_WIFI_RECONNECT_MODES Enumeration C typedef enum { DRV_WIFI_DO_NOT_ATTEMPT_TO_RECONNECT = 0, DRV_WIFI_ATTEMPT_TO_RECONNECT = 1 } DRV_WIFI_RECONNECT_MODES; Description WiFi Reconnect Modes This enumeration identifies the reconnection modes that can be used in DRV_WIFI_ReconnectModeSet(). 5.1.13.7.4.73 DRV_WIFI_SCAN_CONTEXT Structure C typedef struct { uint8_t scanType; uint8_t scanCount; uint16_t minChannelTime; uint16_t maxChannelTime; uint16_t probeDelay; } DRV_WIFI_SCAN_CONTEXT; Description WiFi Scan Context This structure contains MRF24WG scan context data. See DRV_WIFI_ScanContextSet(). 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-665 Members Members Description uint8_t scanType; 802.11 allows for active scanning, where the device sends out a broadcast probe request seeking an access point. Also allowed is passive scanning where the device only listens to beacons being broadcast from access points. Set to DRV_WIFI_ACTIVE_SCAN (default) or DRV_WIFI_PASSIVE_SCAN uint8_t scanCount; The number of times to scan a channel while attempting to find a particular access point. Default is 1 uint16_t minChannelTime; The minimum time (in milliseconds) the MRF24WG will wait for a probe response after sending a probe request. If no probe responses are received in minChannelTime then the MRF24WG will go on to the next channel, if any are left to scan, or quit. Default is 200ms. uint16_t maxChannelTime; If a probe response is received within minChannelTime then the MRF24WG will continue to collect any additional probe responses up to maxChannelTime before going to the next channel in the channelList. Units are in milliseconds. Default is 400ms. uint16_t probeDelay; The number of microseconds to delay before transmitting a probe request following the channel change during scanning. Default is 20uS. 5.1.13.7.4.74 DRV_WIFI_SCAN_RESULT Structure C typedef struct { uint8_t bssid[DRV_WIFI_BSSID_LENGTH]; uint8_t ssid[DRV_WIFI_MAX_SSID_LENGTH]; uint8_t apConfig; uint8_t reserved; uint16_t beaconPeriod; uint16_t atimWindow; uint8_t basicRateSet[DRV_WIFI_MAX_NUM_RATES]; uint8_t rssi; uint8_t numRates; uint8_t DtimPeriod; uint8_t bssType; uint8_t channel; uint8_t ssidLen; } DRV_WIFI_SCAN_RESULT; Description WiFi Scan Results This structure contains the result of WiFi scan operation. See DRV_WIFI_ScanGetResult(). apConfig Bit Mask Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 WPA2 WPA Preamble Privacy Reserved Reserved Reserved IE IE 1 if AP broadcasting one or more Information Elements, else 0 Privacy 0 : AP is open (no security) 1: AP using security, if neither WPA and WPA2 set then security is WEP. Preamble 0: AP transmitting with short preamble 1: AP transmitting with long preamble WPA Only valid if Privacy is 1. 0: AP does not support WPA 1: AP supports WPA WPA2 Only valid if Privacy is 1. 0: AP does not support WPA2 1: AP supports WPA2 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-666 Members Members Description uint8_t bssid[DRV_WIFI_BSSID_LENGTH]; Network BSSID value uint8_t ssid[DRV_WIFI_MAX_SSID_LENGTH]; Network SSID value uint8_t apConfig; Access Point config (see description) uint8_t reserved; not used uint16_t beaconPeriod; Network beacon interval uint16_t atimWindow; Only valid if bssType = DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE 5.1.13.7.4.75 DRV_WIFI_SCAN_TYPES Enumeration C typedef enum { DRV_WIFI_ACTIVE_SCAN = 1, DRV_WIFI_PASSIVE_SCAN = 2 } DRV_WIFI_SCAN_TYPES; Description WiFi Scan Types This enumeration identifies the WiFi scan types that can be selected. 5.1.13.7.4.76 DRV_WIFI_SECURITY_CONTEXT Union C typedef union { DRV_WIFI_WEP_CONTEXT wepContext; DRV_WIFI_WPA_CONTEXT wpaContext; DRV_WIFI_WPS_CONTEXT wpsContext; } DRV_WIFI_SECURITY_CONTEXT; Description WiFi security context Structure/union can be used in functions DRV_WIFI_SecurityWepSet, DRV_WIFI_SecurityWpaSet, and DRV_WIFI_SecurityWpsSet Members Members Description DRV_WIFI_WEP_CONTEXT wepContext; set WEP security context DRV_WIFI_WPA_CONTEXT wpaContext; set WPA security context DRV_WIFI_WPS_CONTEXT wpsContext; set WPS security context 5.1.13.7.4.77 DRV_WIFI_SOFT_AP_EVENT_REASON_CODES Enumeration C typedef enum { DRV_WIFI_SOFTAP_EVENT_LINK_LOST = 0, DRV_WIFI_SOFTAP_EVENT_RECEIVED_DEAUTH = 1 } DRV_WIFI_SOFT_AP_EVENT_REASON_CODES; Description This is type DRV_WIFI_SOFT_AP_EVENT_REASON_CODES. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-667 5.1.13.7.4.78 DRV_WIFI_SOFT_AP_STATES Enumeration C typedef enum { DRV_WIFI_SOFTAP_EVENT_CONNECTED = 0, DRV_WIFI_SOFTAP_EVENT_DISCONNECTED = 1 } DRV_WIFI_SOFT_AP_STATES; Description This is type DRV_WIFI_SOFT_AP_STATES. 5.1.13.7.4.79 DRV_WIFI_STATUS_CODES Enumeration C typedef enum { DRV_WIFI_UNSPECIFIED_FAILURE = 1, DRV_WIFI_CAPS_UNSUPPORTED = 10, DRV_WIFI_REASSOC_NO_ASSOC = 11, DRV_WIFI_ASSOC_DENIED_UNSPEC = 12, DRV_WIFI_NOT_SUPPORTED_AUTH_ALG = 13, DRV_WIFI_UNKNOWN_AUTH_TRANSACTION = 14, DRV_WIFI_CHALLENGE_FAIL = 15, DRV_WIFI_AUTH_TIMEOUT = 16, DRV_WIFI_AP_UNABLE_TO_HANDLE_NEW_STA = 17, DRV_WIFI_ASSOC_DENIED_RATES = 18, DRV_WIFI_ASSOC_DENIED_NOSHORTPREAMBLE = 19, DRV_WIFI_ASSOC_DENIED_NOPBCC = 20, DRV_WIFI_ASSOC_DENIED_NOAGILITY = 21, DRV_WIFI_ASSOC_DENIED_NOSHORTTIME = 25, DRV_WIFI_ASSOC_DENIED_NODSSSOFDM = 26, DRV_WIFI_S_INVALID_IE = 40, DRV_WIFI_S_INVALID_GROUPCIPHER = 41, DRV_WIFI_S_INVALID_PAIRWISE_CIPHER = 42, DRV_WIFI_S_INVALID_AKMP = 43, DRV_WIFI_UNSUPPORTED_RSN_VERSION = 44, DRV_WIFI_S_INVALID_RSN_IE_CAP = 45, DRV_WIFI_S_CIPHER_SUITE_REJECTED = 46, DRV_WIFI_TIMEOUT = 47 } DRV_WIFI_STATUS_CODES; Description status codes for connection for association or authentication failure This enumeration identifies the codes for a connection failure due to association or authentication failure. These codes are used in DRV_WIFI_ProcessEvent(), case DRV_WIFI_EVENT_CONNECTION_FAILED. 5.1.13.7.4.80 DRV_WIFI_SWMULTICAST_CONFIG Structure C typedef struct { uint8_t filterId; uint8_t action; uint8_t macBytes[6]; uint8_t macBitMask; } DRV_WIFI_SWMULTICAST_CONFIG; Description WiFi SW Multicast Filter Config This structure contains data pertaining to the configuration of the software multicast config filter. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-668 'action' Field Description DRV_WIFI_MULTICAST_DISABLE_ALL Multicast filter discards all received multicast messages. DRV_WIFI_MULTICAST_ENABLE_ALL Multicast filter forwards all received multicast messages to host. DRV_WIFI_MULTICAST_USE_FILTERS The MAC filter will be used and the remaining fields define the filter. Members Members Description uint8_t filterId; DRV_WIFI_MULTICAST_FILTER_1 thru DRV_WIFI_MULTICAST_FILTER_16 uint8_t action; configures the multicast filter (see description) uint8_t macBytes[6]; Array containing the MAC address to filter on (using the destination address of each incoming 802.11 frame). Specific bytes within the MAC address can be designated as ?don?t care? bytes. See macBitMask. This field in only used if action = WF_MULTICAST_USE_FILTERS. uint8_t macBitMask; A byte where bits 5:0 correspond to macBytes[5:0]. If the bit is zero then the corresponding MAC byte must be an exact match for the frame to be forwarded to the Host PIC. If the bit is one then the corresponding MAC byte is a ?don?t care? and not used in the Multicast filtering process. This field in only used if action = WF_MULTICAST_USE_FILTERS. 5.1.13.7.4.81 DRV_WIFI_TX_MODES Enumeration C typedef enum { DRV_WIFI_TXMODE_G_RATES = 0, DRV_WIFI_TXMODE_B_RATES = 1, DRV_WIFI_TXMODE_LEGACY_RATES = 2 } DRV_WIFI_TX_MODES; Description Tx Modes This enumeration identifies the choices the MRF24W Tx mode. It is recommended to use the DRV_WIFI_TXMODE_G_RATES for best performance. See DRV_WIFI_TxModeSet(). Members Members Description DRV_WIFI_TXMODE_G_RATES = 0 Use 802.11 'g' rates DRV_WIFI_TXMODE_B_RATES = 1 Use only 802.11 'b' rates DRV_WIFI_TXMODE_LEGACY_RATES = 2 Use only 1 and 2 mbps rates 5.1.13.7.4.82 DRV_WIFI_WEP_CONTEXT Structure C typedef struct { uint8_t wepSecurityType; uint8_t wepKey[DRV_WIFI_MAX_WEP_KEY_LENGTH]; uint8_t wepKeyLength; uint8_t wepKeyType; } DRV_WIFI_WEP_CONTEXT; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-669 Description WiFi Wep Security Context This structure contains MRF24WG WEP context. See DRV_WIFI_SecurityWepSet(). Members Members Description uint8_t wepSecurityType; DRV_WIFI_SECURITY_WEP_40 or DRV_WIFI_SECURITY_WEP_104 uint8_t wepKey[DRV_WIFI_MAX_WEP_KEY_LENGTH]; Array containing four WEP binary keys. This will be four, 5-byte keys for WEP-40 or four, thirteen-byte keys for WEP-104. uint8_t wepKeyLength; number of bytes pointed to by p_wepKey uint8_t wepKeyType; DRV_WIFI_SECURITY_WEP_OPENKEY (default) or DRV_WIFI_SECURITY_WEP_SHAREDKEY 5.1.13.7.4.83 DRV_WIFI_WEP_KEY_TYPE Enumeration C typedef enum { DRV_WIFI_SECURITY_WEP_SHAREDKEY = 0, DRV_WIFI_SECURITY_WEP_OPENKEY = 1 } DRV_WIFI_WEP_KEY_TYPE; Description WEP Key Types This enumeration identifies the choices for the WEP key type when using WEP security. The recommended key type (and default) is Open key. Members Members Description DRV_WIFI_SECURITY_WEP_SHAREDKEY = 0 use WEP shared key DRV_WIFI_SECURITY_WEP_OPENKEY = 1 use WEP open key (default) 5.1.13.7.4.84 DRV_WIFI_WPA_CONTEXT Structure C typedef struct { uint8_t wpaSecurityType; DRV_WIFI_WPA_KEY_INFO keyInfo; } DRV_WIFI_WPA_CONTEXT; Description WiFi WPA context This structure contains MRF24WG WPA context. See DRV_WIFI_SecurityWpaSet(). wpaSecurityType Description DRV_WIFI_SECURITY_WPA_WITH_KEY WPA binary key DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE WPA passphrase DRV_WIFI_SECURITY_WPA2_WITH_KEY WPA2 binary key 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-670 DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE WPA2 passphrase DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY Auto-select between WPA/WPA2 with binary key DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE Auto-select between WPA/WPA2 with passphrase Members Members Description uint8_t wpaSecurityType; desired security type (see description) DRV_WIFI_WPA_KEY_INFO keyInfo; see DRV_WIFI_WPA_KEY_INFO 5.1.13.7.4.85 DRV_WIFI_WPA_KEY_INFO Structure C typedef struct { uint8_t key[DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH]; uint8_t keyLength; } DRV_WIFI_WPA_KEY_INFO; Description WiFi WPA Key context This structure contains MRF24WG WPA key info. This structure is used in the DRV_WIFI_WPA_CONTEXT and DRV_WIFI_WPS_CONTEXT structures. Members Members Description uint8_t key[DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH]; binary key or passphrase uint8_t keyLength; number of bytes in binary key (always 32) or passphrase 5.1.13.7.4.86 DRV_WIFI_WPS_AUTH_TYPES Enumeration C typedef enum { DRV_WIFI_WPS_AUTH_OPEN = 0x01, DRV_WIFI_WPS_AUTH_WPA_PSK = 0x02, DRV_WIFI_WPS_AUTH_SHARED = 0x04, DRV_WIFI_WPS_AUTH_WPA = 0x08, DRV_WIFI_WPS_AUTH_WPA2 = 0x10, DRV_WIFI_WPS_AUTH_WPA2_PSK = 0x20 } DRV_WIFI_WPS_AUTH_TYPES; Description This is type DRV_WIFI_WPS_AUTH_TYPES. 5.1.13.7.4.87 DRV_WIFI_WPS_CONTEXT Structure C typedef struct { uint8_t wpsSecurityType; uint8_t wpsPin[DRV_WIFI_WPS_PIN_LENGTH]; uint8_t wpsPinLength; bool getPassPhrase; DRV_WIFI_WPA_KEY_INFO * p_keyInfo; } DRV_WIFI_WPS_CONTEXT; 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-671 Description WiFi WPS security context This structure contains MRF24WG WPS security context. See DRV_WIFI_SecurityWpsSet(). Members Members Description uint8_t wpsSecurityType; DRV_WIFI_SECURITY_WPS_PUSH_BUTTON or DRV_WIFI_SECURITY_WPS_PIN uint8_t wpsPin[DRV_WIFI_WPS_PIN_LENGTH]; if using DRV_WIFI_SECURITY_WPS_PIN then pointer to 8-digit pin uint8_t wpsPinLength; should always be 8 bool getPassPhrase; True if ASCII passphrase should be sent back to host so host can (more quickly) calculate binary key. False if the MRF24WG should calculate the binary key DRV_WIFI_WPA_KEY_INFO * p_keyInfo; pointer to where the WiFi driver will store passphrase info (must be global memory) 5.1.13.7.4.88 DRV_WIFI_WPS_CREDENTIAL Structure C typedef struct { uint8_t ssid[32]; uint8_t netKey[64]; uint16_t authType; uint16_t encType; uint8_t netIdx; uint8_t ssidLen; uint8_t keyIdx; uint8_t keyLen; uint8_t bssid[6]; } DRV_WIFI_WPS_CREDENTIAL; Description WiFi WPS Credentials This structure contains data pertaining to the configuration of the WiFi WPS credentials. 'authType' Field Description DRV_WIFI_WPS_AUTH_OPEN open security DRV_WIFI_WPS_AUTH_WPA_PSK WPA with PSK DRV_WIFI_WPS_AUTH_SHARED Shared key DRV_WIFI_WPS_AUTH_WPA WPA DRV_WIFI_WPS_AUTH_WPA2 WPA2 DRV_WIFI_WPS_AUTH_WPA2_PSK WPA2 with PSK 'encType' Field Description DRV_WIFI_WPS_ENC_NONE No encoding DRV_WIFI_WPS_ENC_WEP WEP encoding DRV_WIFI_WPS_ENC_TKIP WPS/TKIP encodingShared key 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-672 DRV_WIFI_ENC_AES AES encoding Members Members Description uint8_t ssid[32]; network SSID uint8_t netKey[64]; binary security key (not used if security is open) uint16_t authType; WPS authorization type (see description) uint16_t encType; Encoding type (see description) uint8_t netIdx; not used uint8_t ssidLen; number of bytes in SSID uint8_t keyIdx; Only valid encType = WF_ENC_WEP. This is the index of the WEP key being used. uint8_t keyLen; number of bytes in netKey uint8_t bssid[6]; MAC address of AP 5.1.13.7.4.89 DRV_WIFI_WPS_ENCODE_TYPES Enumeration C typedef enum { DRV_WIFI_WPS_ENC_NONE = 0x01, DRV_WIFI_WPS_ENC_WEP = 0x02, DRV_WIFI_WPS_ENC_TKIP = 0x04, DRV_WIFI_ENC_AES = 0x08 } DRV_WIFI_WPS_ENCODE_TYPES; Description This is type DRV_WIFI_WPS_ENCODE_TYPES. 5.1.13.7.4.90 ENABLE_P2P_PRINTS Macro C #define ENABLE_P2P_PRINTS ((uint8_t)(1 << 1)) /* not supported */ Description not supported 5.1.13.7.4.91 ENABLE_WPS_PRINTS Macro C #define ENABLE_WPS_PRINTS ((uint8_t)(1 << 0)) Description This is macro ENABLE_WPS_PRINTS. 5.1.13.7.4.92 PA6_IO Macro C #define PA6_IO LATAbits.LATA6 Description debug, remove later 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-673 5.1.13.7.4.93 PA6_TRISTATE Macro C #define PA6_TRISTATE TRISAbits.TRISA6 Description This is macro PA6_TRISTATE. 5.1.13.7.4.94 SET_PA6_AS_OUTPUT Macro C #define SET_PA6_AS_OUTPUT TRISAbits.TRISA6 = 0 Description This is macro SET_PA6_AS_OUTPUT. 5.1.13.7.4.95 WF_WPS_PIN_LENGTH Macro C #define WF_WPS_PIN_LENGTH 8 Description WPS PIN Length 5.1.13.8 Files Files Name Description drv_wifi.h WiFi-specific MAC function prototypes called by TCP/IP stack. Description 5.1.13.8.1 drv_wifi.h WiFi MAC interface functions The functions in this header file are accessed by the TCP/IP stack via function pointers. Enumerations Name Description adhocMode Selection of different AdHoc connection modes DRV_WIFI_ADHOC_MODES Selection of different AdHoc connection modes DRV_WIFI_CONNECTION_STATES Wifi Connection states DRV_WIFI_DEVICE_TYPES Codes for WiFi device types DRV_WIFI_DOMAIN_CODES Regional domain codes. DRV_WIFI_EVENT_CONN_TEMP_LOST_CODES Selection of different codes when WiFi connection is temporarily lost. DRV_WIFI_EVENT_INFO Selection of different EventInfo types 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-674 DRV_WIFI_EVENTS Selections for events that can occur. DRV_WIFI_GENERAL_ERRORS This is type DRV_WIFI_GENERAL_ERRORS. DRV_WIFI_HIBERNATE_STATES Wifi Hibernate states DRV_WIFI_MGMT_ERRORS Error codes returned when a mgmt message is sent to the MRF24W DRV_WIFI_MULTICAST_FILTER_IDS Selections for software Multicast filter ID's DRV_WIFI_MULTICAST_FILTERS Selections for Software Multicast Filters. DRV_WIFI_POWER_SAVE_STATES Wifi Power Save states DRV_WIFI_REASON_CODES Selection of different codes when a deauth or disassociation event has occurred. DRV_WIFI_RECONNECT_MODES Selection of different Reconnection modes DRV_WIFI_SCAN_TYPES Selection of different WiFi scan types DRV_WIFI_SOFT_AP_EVENT_REASON_CODES This is type DRV_WIFI_SOFT_AP_EVENT_REASON_CODES. DRV_WIFI_SOFT_AP_STATES This is type DRV_WIFI_SOFT_AP_STATES. DRV_WIFI_STATUS_CODES Selection of different codes when WiFi connection fails due to association or authentication failure. DRV_WIFI_TX_MODES Selections for WiFi Tx mode DRV_WIFI_WEP_KEY_TYPE Selections for WEP key type when using WEP security. DRV_WIFI_WPS_AUTH_TYPES This is type DRV_WIFI_WPS_AUTH_TYPES. DRV_WIFI_WPS_ENCODE_TYPES This is type DRV_WIFI_WPS_ENCODE_TYPES. Functions Name Description DRV_WIFI_AdhocContextSet Sets the AdHoc context. DRV_WIFI_BssidGet Sets the the BSSID set in DRV_WIFI_BssidSet(). DRV_WIFI_BssidSet Sets the the Basic Service Set Identifier (BSSID). DRV_WIFI_ChannelListGet Gets the the channel list. DRV_WIFI_ChannelListSet Sets the the channel list. DRV_WIFI_ConfigDataErase Erases configuration data from the board EEPROM. DRV_WIFI_ConfigDataLoad Loads configuration data from the board EEPROM. DRV_WIFI_ConfigDataPrint Outputs to console the configuration data from the board EEPROM. DRV_WIFI_ConfigDataSave Save configuration data to the board EEPROM. DRV_WIFI_Connect Directs the MRF24WG to connect to a WiFi network. DRV_WIFI_ConnectContextGet Gets the current WiFi connection context DRV_WIFI_ConnectionStateGet Gets the current WiFi connection state DRV_WIFI_Deinitialize Initializes the MRF24WG WiFi driver. DRV_WIFI_DeviceInfoGet Retrieves MRF24WG device information DRV_WIFI_Disconnect Directs the MRF24WG to disconnect from a WiFi network. DRV_WIFI_GratuitousArpStart Starts a periodic gratuitous ARP response DRV_WIFI_GratuitousArpStop Stops a periodic gratuitous ARP. DRV_WIFI_HibernateEnable Puts the MRF24WG into hibernate mode. DRV_WIFI_HWMulticastFilterGet Gets a multicast address filter from one of the two multicast filters. DRV_WIFI_HWMulticastFilterSet Sets a multicast address filter using one of the two hardware multicast filters. DRV_WIFI_Initialize Initializes the MRF24WG WiFi driver. DRV_WIFI_isHibernateEnable Checks if MRF24W is in hibernate mode DRV_WIFI_MacAddressGet Retrieves the MRF24WG MAC address 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-675 DRV_WIFI_MacAddressSet Uses a different MAC address for the MRF24W DRV_WIFI_MacStatsGet Gets MAC statistics. DRV_WIFI_NetworkTypeGet Gets the WiFi network type DRV_WIFI_NetworkTypeSet Sets the WiFi network type DRV_WIFI_PowerSaveStateGet Gets the current power-save state. DRV_WIFI_ProcessEvent Processes WiFi event DRV_WIFI_PsPollDisable Disables PS-Poll mode. DRV_WIFI_PsPollEnable Enables PS Poll mode. DRV_WIFI_ReconnectModeGet Gets the WiFi reconnection mode. DRV_WIFI_ReconnectModeSet Sets the WiFi reconnection mode. DRV_WIFI_RegionalDomainGet Retrieves the MRF24WG Regional domain DRV_WIFI_RssiGet Gets RSSI value set in DRV_WIFI_RssiSet() DRV_WIFI_RssiSet Sets RSSI restrictions when connecting DRV_WIFI_RtsThresholdGet Gets the RTS Threshold DRV_WIFI_RtsThresholdSet Sets the RTS Threshold. DRV_WIFI_Scan Commands the MRF24W to start a scan operation. This will generate the WF_EVENT_SCAN_RESULTS_READY event. DRV_WIFI_ScanContextGet Gets the WiFi scan context. DRV_WIFI_ScanContextSet Sets the WiFi scan context. DRV_WIFI_ScanGetResult Read selected scan results back from MRF24W. DRV_WIFI_SecurityGet Gets the current WiFi security setting DRV_WIFI_SecurityOpenSet Sets WiFi security to open (no security) DRV_WIFI_SecurityWepSet Sets WiFi security to use WEP. DRV_WIFI_SecurityWpaSet Sets WiFi security to use WPA or WPA2 DRV_WIFI_SecurityWpsSet Sets WiFi security to use WPS DRV_WIFI_SetLinkDownThreshold Sets number of consecutive WiFi Tx failures before link is considered down. DRV_WIFI_SetPSK Sets the binary WPA PSK code in WPS. DRV_WIFI_SoftApEventInfoGet Gets the stored Soft AP event info DRV_WIFI_SsidGet Sets the SSID DRV_WIFI_SsidSet Sets the SSID DRV_WIFI_SWMultiCastFilterEnable Forces the MRF24WG to use software multicast filters instead of hardware multicast filters. DRV_WIFI_SWMulticastFilterSet Sets a multicast address filter using one of the software multicast filters. DRV_WIFI_TxModeGet Gets 802.11 Tx mode DRV_WIFI_TxModeSet Configures 802.11 Tx mode DRV_WIFI_TxPowerFactoryMaxGet Retrieves the factory-set max Tx power from the MRF24W. DRV_WIFI_TxPowerMaxGet Gets the Tx max power on the MRF24WG0M. DRV_WIFI_TxPowerMaxSet Sets the Tx max power on the MRF24WG0M. DRV_WIFI_WepKeyTypeGet Gets the Wep Key type DRV_WIFI_WPSCredentialsGet Gets the WPS credentials DRV_WIFI_YieldPassphraseToHost Allows host to get WPS WPA-PSK passphrase and convert to binary key. Macros Name Description DRV_WIFI_BSSID_LENGTH This is macro DRV_WIFI_BSSID_LENGTH. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-676 DRV_WIFI_DEAUTH_REASONCODE_MASK This is macro DRV_WIFI_DEAUTH_REASONCODE_MASK. DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD ms DRV_WIFI_DEFAULT_ADHOC_HIDDEN_SSID Default values for WiFi AdHoc settings DRV_WIFI_DEFAULT_ADHOC_MODE This is macro DRV_WIFI_DEFAULT_ADHOC_MODE. DRV_WIFI_DEFAULT_PS_DTIM_ENABLED DTIM wake-up enabled (normally the case) DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL number of beacon periods DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL 100ms multiplier, e.g. 1 * 100ms = 100ms DRV_WIFI_DEFAULT_SCAN_COUNT Default values for WiFi scan context DRV_WIFI_DEFAULT_SCAN_MAX_CHANNEL_TIME ms DRV_WIFI_DEFAULT_SCAN_MIN_CHANNEL_TIME ms DRV_WIFI_DEFAULT_SCAN_PROBE_DELAY us DRV_WIFI_DEFAULT_WEP_KEY_TYPE see DRV_WIFI_SecurityWepSet() and DRV_WIFI_WEP_CONTEXT DRV_WIFI_DISABLED Do not make this an enumerated type! DRV_WIFI_DISASSOC_REASONCODE_MASK This is macro DRV_WIFI_DISASSOC_REASONCODE_MASK. DRV_WIFI_ENABLED This is macro DRV_WIFI_ENABLED. DRV_WIFI_MAX_CHANNEL_LIST_LENGTH This is macro DRV_WIFI_MAX_CHANNEL_LIST_LENGTH. DRV_WIFI_MAX_NUM_RATES This is macro DRV_WIFI_MAX_NUM_RATES. DRV_WIFI_MAX_SECURITY_KEY_LENGTH This is macro DRV_WIFI_MAX_SECURITY_KEY_LENGTH. DRV_WIFI_MAX_SSID_LENGTH This is macro DRV_WIFI_MAX_SSID_LENGTH. DRV_WIFI_MAX_WEP_KEY_LENGTH This is macro DRV_WIFI_MAX_WEP_KEY_LENGTH. DRV_WIFI_MAX_WPA_PASS_PHRASE_LENGTH must include string terminator DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH This is macro DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGT H. DRV_WIFI_MIN_WPA_PASS_PHRASE_LENGTH Key size defines DRV_WIFI_NETWORK_TYPE_ADHOC This is macro DRV_WIFI_NETWORK_TYPE_ADHOC. DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE Selection of different WiFi network types DRV_WIFI_NETWORK_TYPE_P2P not supported DRV_WIFI_NETWORK_TYPE_SOFT_AP This is macro DRV_WIFI_NETWORK_TYPE_SOFT_AP. DRV_WIFI_NO_ADDITIONAL_INFO eventInfo define for DRV_WIFI_ProcessEvent() when no additional info is supplied DRV_WIFI_RETRY_ADHOC This is macro DRV_WIFI_RETRY_ADHOC. DRV_WIFI_RETRY_FOREVER This is macro DRV_WIFI_RETRY_FOREVER. DRV_WIFI_RTS_THRESHOLD_MAX maximum RTS threshold size in bytes DRV_WIFI_SECURITY_EAP This is macro DRV_WIFI_SECURITY_EAP. DRV_WIFI_SECURITY_OPEN Selection of different WiFi security types DRV_WIFI_SECURITY_WEP_104 This is macro DRV_WIFI_SECURITY_WEP_104. DRV_WIFI_SECURITY_WEP_40 This is macro DRV_WIFI_SECURITY_WEP_40. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-677 DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY. DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS _PHRASE. DRV_WIFI_SECURITY_WPA_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA_WITH_KEY. DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRA SE. DRV_WIFI_SECURITY_WPA2_WITH_KEY This is macro DRV_WIFI_SECURITY_WPA2_WITH_KEY. DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE This is macro DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHR ASE. DRV_WIFI_SECURITY_WPS_PIN This is macro DRV_WIFI_SECURITY_WPS_PIN. DRV_WIFI_SECURITY_WPS_PUSH_BUTTON This is macro DRV_WIFI_SECURITY_WPS_PUSH_BUTTON. DRV_WIFI_VERSION_NUMBER WiFi Driver Version Number DRV_WIFI_WEP104_KEY_LENGTH 4 keys of 13 bytes each DRV_WIFI_WEP40_KEY_LENGTH 4 keys of 5 bytes each DRV_WIFI_WPA_KEY_LENGTH This is macro DRV_WIFI_WPA_KEY_LENGTH. DRV_WIFI_WPA2_KEY_LENGTH This is macro DRV_WIFI_WPA2_KEY_LENGTH. DRV_WIFI_WPS_PIN_LENGTH 7 digits + checksum byte ENABLE_P2P_PRINTS not supported ENABLE_WPS_PRINTS This is macro ENABLE_WPS_PRINTS. PA6_IO debug, remove later PA6_TRISTATE This is macro PA6_TRISTATE. SET_PA6_AS_OUTPUT This is macro SET_PA6_AS_OUTPUT. WF_WPS_PIN_LENGTH WPS PIN Length Structures Name Description DRV_WIFI_ADHOC_NETWORK_CONTEXT Contains data pertaining to WiFi AdHoc context DRV_WIFI_CONNECTION_CONTEXT Contains data pertaining to MRF24WG connection context DRV_WIFI_DEVICE_INFO Contains data pertaining to MRF24WG device type and version number DRV_WIFI_HIBERNATE_STATE This is type DRV_WIFI_HIBERNATE_STATE. DRV_WIFI_MAC_STATS Wifi MIB states DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT Contains data pertaining to WiFi Soft AP event DRV_WIFI_PS_POLL_CONTEXT Contains data pertaining to WiFi PS-Poll context DRV_WIFI_SCAN_CONTEXT Contains data pertaining to WiFi scan context DRV_WIFI_SCAN_RESULT Contains data pertaining to WiFi scan results DRV_WIFI_SWMULTICAST_CONFIG Contains data pertaining to WiFi software multicast filter configuration DRV_WIFI_WEP_CONTEXT Contains data pertaining to WiFi WEP context DRV_WIFI_WPA_CONTEXT Contains data pertaining to WiFi WPA. DRV_WIFI_WPA_KEY_INFO Contains data pertaining to WiFi WPA Key DRV_WIFI_WPS_CONTEXT Contains data pertaining to WiFi WPS security. 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-678 DRV_WIFI_WPS_CREDENTIAL Contains data pertaining to WiFi WPS Credentials Unions Name Description DRV_WIFI_SECURITY_CONTEXT Contains data pertaining to WiFi security. File Name drv_wifi_mac.h 5.1 Driver Library Help MPLAB Harmony Help MRF24W Wi-Fi Driver Library 5-679 5.2 Graphics Library Help 5.2.1 Graphics Library Porting Guide 5.2.1.1 Introduction Porting to the MPLAB Harmony Graphics Library This help file provides information for porting from the Microchip Library of Applications (MLA) version of the Graphics Library to the Graphics Library within MPLAB Harmony. 5.2.1.2 Release Notes MPLAB Harmony Version: v0.70b Release Date: Graphics Library: 4.00 18Nov2013 New This Release: This is the first release of the library. Known Issues: Nothing to report in this release. 5.2.1.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-680 5.2.1.4 Upgrading from the MLA Graphics Library to the MPLAB Harmony Graphics Library The MPLAB Harmony Graphics Library is a completely new distribution, which is included as part of the MPLAB Harmony installation. No files need to be maintained from an existing MLA Graphics Library installation. 5.2.1.4.1 MPLAB Harmony Graphics Library Key Features This topic provides a description of the key features of the MPLAB Harmony Graphics Library. Description Note: The MPLAB Harmony Graphics Library does not support any Microchip 16-bit family devices. The following are the key features of the MPLAB Harmony Graphics Library: • Multiple interfaces • Fully dynamic: • Stack initialization/deinitialization • Resource management • Configurable • Improved modularity and stack layout • Interrupt driven operation • RTOS friendly, with easy RTOS integration 5.2.1.4.2 MPLAB Harmony Graphics Library Structure This topic describes the structure of the MPLAB Harmony Graphics Library. Description The MPLAB Harmony Graphics Library consists of a graphic widget and primitive library, a display layer, a graphics driver, and demonstration applications, all of which support the following structure: • Lowercase file names • Underscores are used • System services are used instead of direct access to peripherals • Interrupts • Drivers • Timer Services • File System • Board Support Package (BSP) By default, the Graphics Library and its corresponding display drivers and demonstration applications are placed into the following locations during installation of MPLAB Harmony: • ./microchip/harmony//framework/gfx • ./microchip/harmony//framework/driver/gfx 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-681 • ./microchip/harmony//apps/gfx 5.2.1.4.3 MPLAB Harmony Graphics Library Design This topic discusses the design of the MPLAB Harmony Graphics Library. Description The MPLAB Harmony Graphics Library is designed as a part of a system running other applications, middleware, etc. Therefore, it makes use of the system services that are available to other modules in the system or to the application, such as: • File system • System interrupts • System driver services • System timers • System device drivers • System command processor • System console • System debug services Refer to the ./framework/gfx/src/system folder for the header files that expose the system wide available API. 5.2.1.4.4 MPLAB Harmony Graphics Library API Changes This topic discusses the reasons behind the API changes to the MPLAB Harmony Graphics Library. Description The API is backward compatible in functionality only. All function names and type definitions have changed to reflect the MPLAB Harmony philosophy. The changes in the library API have been minimized so that the porting process is straightforward and integration with other dependents is made simple. New functionality has been added because of new features, such as dynamic configuration and non-block of the library. Other than these new features, the changes to the API were also made to support commonality between the MPLAB Harmony Graphics Library and the 16-bit Graphics Library. The API changes are at all layers of the Graphics Library which include the GOL, Primitive, and Driver layers. 5.2.1.4.5 MPLAB Harmony Graphics Library Access Changes This topic describes the stack access updates that were made to the MPLAB Harmony Graphics Library. Description The Graphics Library no longer initializes the display driver, but requires the application to initialize the driver before calling any Graphics Library functions. For example: GFX_DRV_lcc_Initialize() Direct access to the Graphics Driver has been removed. 5.2.1.4.5.1 Graphic Primitive Layer Changes This topic discusses the changes made to the MLA Graphics Library primitive.h file to produce the equivalent MPLAB Harmony Graphics Library gfx_primitive.h file. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-682 Description Changes The changes are as follows: • Prefix: • GFX_ is the generic prefix for functions • gfx_ is the generic prefix for primitive level files • Non-blocking support - A task queue has been added to ensure that functions do not block execution of other non-graphics time-critical tasks • GFX_Initialize - This function replaces the InitGraph function. The GFX_Initialize function does the following: • Sets the line type to SOLID_LINE • Sets the current drawing color to WHITE • Sets the graphic cursor position to the upper left corner of the screen • Sets active and visual pages to page 0 • Clears the active page and disables clipping The GFX_Initialize function should be called before using the Graphics Primitive Layer. 5.2.1.4.5.2 Graphic Object Layer (GOL) Changes This topic discusses the changes made to the MLA Graphics Library GOL.h file to produce the equivalent MPLAB Harmony Graphics Library gfx_gol.h file. Description Changes The changes are as follows. • Prefix: • GFX_GOL_ is the generic prefix for all Graphic Object Level functions • gfx_gol_ is the generic prefix for all Graphic Object Level files • Non-blocking support – a task queue has been added to ensure that functions do not block execution of other non-graphics time-critical tasks • GFX_Initialize – This function replaces the MLA GOL_Init function, which overrides the equivalent primitive function. This function initializes the graphics library and creates a default style scheme with default settings referenced by the global scheme pointer. GFX_Initialize must be called before GOL functions can be used. 5.2.1.4.5.3 Graphic Display Driver Layer Changes This topic discusses the changes made to the DisplayDriver.h file. This topic discusses the changes made to the MLA Graphics Library DisplayDriver.h file to produce the equivalent MPLAB Harmony Graphics Library drv_gfx_display.h file. Description Changes The changes are as follows: • Prefix: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-683 • DRV_GFX is the generic prefix for all Graphics Driver level functions • drv_gfx is the generic prefix for all Graphics Driver level files • Common API Interface – This interface establishes the basic set of driver functions and parameters required by the Graphics Primitive Layer to display graphics content on a Liquid Crystal Display. It also lists the initialization and deinitialization functions and parameters required by the application to establish a driver. 5.2.1.4.6 MPLAB Harmony Graphics Library Initialization Changes This topic describes the initialization updates to the MPLAB Harmony Graphics Library. Description The Graphics Library include header files, gfx_gol.h and gfx_primitive.h, have been updated as follows. To initialize the library the call is now: GFX_Initialize() The default Graphics Library configuration is provided with the library distribution and consists of: • drv_gfx__config_template.h • gfx_config_template.h An example of the graphics initialization can be observed in each of the graphics demonstration distributions. Note: Both the GOL and primitive layers implement the GFX_Initialize() function; however, the primitive layer function will be over-ridden and not used if gfx_gol.c is compiled. 5.2.1.4.7 New MPLAB Harmony Graphics Library API Functions This topic describes some of the important new API functions in the MPLAB Harmony Graphics Library. Description There are many new functions available that have been introduced to support the MPLAB Harmony philosophy. However, there is no concern for the porting process regarding the new API calls as the previous library implementation did not support this kind of service. Existing applications will not port without using the new APIs: • Initialization • Steady-State 5.2.1.4.7.1 Main Program Changes This topic describes the main program changes in the MPLAB Harmony Graphics Library. Description Main Program Changes There are few changes that must be taken care of by the main program loop. A full working example is given with the file, main.c, which is provided in all of the Graphics Library demonstrations. The main program should call the following functions: • SYS_Initialize() • SYS_Tasks() • GFX_GOL_ObjectListDraw() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-684 5.2.1.4.8 MPLAB Harmony Graphics Library Configuration Changes This topic describes the configuration changes in the MPLAB Harmony Graphics Library. Description The stack configuration has a completely new structure. Each project has its own configuration folder that stores multiple configurations based on CPU platforms and hardware boards. Note: The MLA Hardware_Profile.h file cannot be reused in the MPLAB Harmony Graphics Library. The following is a list of the most important features: • system_config.h – This file contains the working set of configuration definitions • gfx_config_template.h – This file lists the entire possible graphics configuration definitions • bsp – This is the parent directory that contains hardware configuration settings for particular Microchip development boards 5.2.1.4.8.1 MPLAB Harmony Graphics Library Configuration This topic provides information on the configuration of the MPLAB Harmony Graphics Library. Description MPLAB Harmony Graphics Library Configuration Note: This content was not available at time of release and will be added in a future release of MPLAB Harmony. 5.2.1.4.8.2 MPLAB Harmony Graphics Library BSP Configuration This topic provides information on the BSP configuration of the MPLAB Harmony Graphics Library. Description MPLAB Harmony Graphics Library BSP Configuration The MPLAB Harmony Graphics Library references the following BSP configurations: • bsp/meb - contains board support content for the Multimedia Expansion Board and the Multimedia Expansion Board II (MEB II) • bsp/pcap - contains board support content for the PIC32 mTouch Capacitive Touch Evaluation Board • bsp/pictail - contains board support content for PICtail and subtending connectable liquid crystal displays (LCDs) 5.2.1.4.9 MPLAB Harmony Graphics Library Utilities This topic describes the MPLAB Harmony Graphics Library utilities. Description The MPLAB Harmony Graphics Library includes the following utilities: • Graphics Display Designer X (GDDX) - This utility can be used for designing and building graphical user interfaces (GUIs) from graphics objects • Graphics Resource Converter (GRC) - This utility can be used for converting data into logically deployable entities that can be used in a graphics application 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-685 5.2.1.5 Porting Applications from the MLA Graphics Library to the MPLAB Harmony Graphics Library Porting an application from the MLA Graphics Library into the Graphics Library within MPLAB Harmony consists of updating existing Graphics Library function names in your application to the new MPLAB Harmony function names. 5.2.1.5.1 MPLAB Harmony Graphics Library File Name Compliance This topic provides header file name mapping tables that show the MLA Graphics Library file name and the compliant name within the MPLAB Harmony Graphics Library. Description The replacement names chosen to make existing Graphics Library functions compliant with MPLAB Harmony are shown in individual tables per header file name. The files listed in the tables are located in the following two MPLAB Harmony installation folders: .\harmony\\framework\gfx .\harmony\\framework\gfx\src The following table shows the original and new names used. Note that other than name changes, no other modifications were made to the middleware functions. MLA Graphics Library File Name MPLAB Harmony Graphics Library File Name AnalogClock.h gfx_gol_analog_clock.h Button.h gfx_gol_button.h Chart.h gfx_gol_chart.h CheckBox.h gfx_gol_check_box.h DigitalMeter.h gfx_gol_digital_meter.h EditBox.h gfx_gol_edit_box.h GOL.h gfx_gol.h Graphics.h gfx.h Grid.h gfx_gol_grid.h (not supported in this release) GroupBox.h gfx_gol_group_box.h ListBox.h gfx_gol_list_box.h Meter.h gfx_gol_meter.h Palette.h gfx_palette.h Picture.h gfx_picture.h Primitive.h gfx_primitive.h ProgressBar.h gfx_gol_progress_bar.h Radiobutton.h gfx_gol_radio_button.h RoundDial.h gfx_gol_round_dial.h Slider.h gfx_gol_scrollbar.h StaticText.h gfx_gol_static_text.h 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-686 TextEntry.h gfx_gol_text_entry.h Transitions.h gfx_transitions.h Window.h gfx_gol_window.h 5.2.1.5.2 MPLAB Harmony Graphics Library Function Name Compliance This topic provides header file function mapping tables that show the MLA Graphics Library function name and the compliant name within the MPLAB Harmony Graphics Library. Description The replacement function names chosen to make the existing MLA Graphics Library function compliant with MPLAB Harmony are shown in individual tables per header file name. The files listed in the tables are located in the following MPLAB Harmony installation folder: .\harmony\\framework\gfx. Header File: gfx_display_driver.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name InitGraph() GFX_PixelsPut() PutPixel GFX_BarFill() GetPixel() GFX_PixelArrayPut() SetColor() GFX_PixelArrayGet() PutPixel GFX_PixelPut() SetColor () GFX_SetColor() GetTransparentColor() GFX_SetInstance() TransparentColorEnable() GFX_SetPage() TransparentColorDisable() GFX_Layer() Bar() GFX_PixelGet() (Content pending) GFX_AlphaBlendWindow() Header File: gfx_primitive.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name InitGraph() GFX_Initialize() PutPixel GFX_PixelPut() GetPixel() GFX_PixelGet() SetColor() GFX_ColorSet() GetColor GFX_ColorGet() TransparentColorEnable() GFX_TransparentColorSet() GetTransparentColor() GFX_TransparentColorGet() TransparentColorEnable() GFX_TransparentColorEnable() TransparentColorDisable() GFX_TransparentColorDisable() Bar() GFX_BarDraw() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-687 Header File: gfx_palette.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name PaletteInit() GFX_PaletteInit() EnablePalette() GFX_PaletteEnable() DisablePalette() GFX_PaletteDisable() IsPaletteEnabled() GFX_IsPaletteEnabled() GetPaletteChangeError() GFX_PaletteChangeErrorGet() ClearPaletteChangeError() GFX_PaletteChangeErrorClear() SetPaletteBpp() GFX_PaletteBppSet() RequestPaletteChange() GFX_PaletteChangeRequest() RequestEntirePaletteChange() GFX_EntirePaletteChangeRequest() SetPalette() GFX_PaletteSet() SetEntirePalette() GFX_EntirePalette() SetPaletteFlash() GFX_PaletteFlashSet() Header File: gfx_transitions.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name GFXIsTransitionPending No equivalent GFXExecutePendingTransition No equivalent GFXSetupTransition GFX_SetTransitionParameters() GFXTransition GFX_Transition() GFXTranslateDirection No equivalent Header File: gfx_gol.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name GetState() GFX_GOL_ObjectStateGet() ClearState() GFX_GOL_ObjectStateClear() SetState() GFX_GOL_ObjectStateSet() GOLAddObject() GFX_GOL_ObjectAdd() GOLFindObject() GFX_GOL_ObjectFind() GOLRedraw() GFX_GOL_ObjectListRedraw() GOLRedrawRec() GFX_GOL_ObjectRectangleRedraw() GOLDraw() GFX_GOL_ObjectListDraw() GOLDrawComplete() GFX_GOL_ObjectDrawComplete() GOLDrawCallback() GFX_GOL_DRAW_CALLBACK_FUNC GOLFree() GFX_GOL_ObjectListFree() GetObjType() GFX_GOL_ObjectTypeGet() GetObjID GFX_GOL_ObjectNextGet() GetObjNext() GFX_GOL_ObjectNext() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-688 GOLDeleteObject() GFX_GOL_ObjectDelete() GOLDeleteObjectByID() GFX_GOL_ObjectByIDDelete() GOLNewList() GFX_GOL_ObjectListNew() GOLGetList() GFX_GOL_ObjectListGet() GOLSetFocus() GFX_GOL_ObjectFocusSet() IsObjUpdated() GFX_GOL_ObjectUpdated() GOLInit() GFX_Initialize() GOLGetFocus() GFX_GOL_ObjectFocusGet() GOLCanBeFocused() GFX_GOL_ObjectCanBeFocused() GOLGetFocusNext() GFX_GOL_ObjectFocusNextGet() GOLGetFocusPrev() GFX_GOL_ObjectFocusPrevGet() GOLPanelDraw() GFX_GOL_PanelParameterSet() GOLPanelDrawTsk() GFX_GOL_PanelDraw() GOLTwoTonePanelDraw() GFX_GOL_TwoTonePanelDraw() Header File: gfx_gol_analog_clock.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name AcSetMinute() GFX_GOL_AnalogMinuteSet() AcSetSecond() GFX_GOL_AnalogSecondSet() AcCreate() GFX_GOL_AnalogClockCreate() AcDraw() GFX_GOL_AnalogDraw() AcSetHour() GFX_GOL_AnalogHourSet() Header File: gfx_gol_button.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name BtnCreate() GFX_GOL_ButtonCreate() BtnDraw() GFX_GOL_ButtonDraw() BtnGetText() GFX_GOL_ButtonTextGet() BtnSetText() GFX_GOL_ButtonTextSet() BtnGetBitmap() GFX_GOL_ButtonPressStateImageGet() BtnSetBitmap() GFX_GOL_ButtonPressStateImageSet() BtnMsgDefault() GFX_GOL_ButtonActionSet() BtnTranslateMsg() GFX_GOL_ButtonActionGet() Header File: gfx_gol_check_box.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name CbCreate() GFX_GOL_CheckBoxCreate() CbDraw() GFX_GOL_CheckBoxDraw() CbGetText() GFX_GOL_CheckBoxTextGet() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-689 CbSetText() GFX_GOL_CheckBoxTextSet() CbMsgDefault() GFX_GOL_CheckBoxActionSet() CbTranslateMsg() GFX_GOL_CheckBoxActionGet() Header File: gfx_gol_custom_control.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name No equivalent GFX_GOL_CustomControlGetPos () No equivalent GFX_GOL_CustomControlSetPos () No equivalent GFX_GOL_CustomControlCreate No equivalent GFX_GOL_CustomControlActionGet () No equivalent GFX_GOL_CustomControlActionGet () No equivalent GFX_GOL_CustomControlActionSet () No equivalent GFX_GOL_CustomControlDraw () Header File: gfx_gol_digital_meter.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name DmCreate() GFX_GOL_DigitalMeterCreate() DmDraw() GFX_GOL_DigitalMeterDraw() DmGetValue() GFX_GOL_DigitalMeterValueGet() DmSetValue() GFX_GOL_DigitalMeterValueSet() DmDecVal() GFX_GOL_DigitalMeterDecrement() DmIncVal() GFX_GOL_DigitalMeterIncrement() DmTranslateMsg() GFX_GOL_DigitalMeterActionGet() Header File: gfx_gol_edit_ box.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name EbCreate() GFX_GOL_EditBoxCreate() EbDraw() GFX_GOL_EditBoxDraw() EbGetText() GFX_GOL_EditBoxTextGet() EbSetText() GFX_GOL_EditBoxTextSet() EbAddChar() GFX_GOL_EditBoxCharAdd(() EbDeleteChar() GFX_GOL_EditBoxCharDelete() EbMsgDefault() GFX_GOL_EditBoxActionSet() EbTranslateMsg() GFX_GOL_EditBoxActionGet() Header File: gfx_gol_group_box.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name GbCreate() GFX_GOL_GroupBoxCreate() GbDraw() GFX_GOL_GroupBoxDraw() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-690 GbGetText() GFX_GOL_GroupBoxTextGet() GbSetText() GFX_GOL_GroupBoxTextGet() GbTranslateMsg() GFX_GOL_GroupBoxActionGet() GbCreate() GFX_GOL_GroupBoxCreate() GbDraw() GFX_GOL_GroupBoxDraw() Header File: gfx_gol_list_box.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name LbCreate() GFX_GOL_ListBoxCreate() LbDraw() GFX_GOL_ListBoxDraw() LbGetItemList() GFX_GOL_ListBoxItemListGet() LbAddItem() GFX_GOL_ListBoxtemAdd() LbAddItem() GFX_GOL_ListBoxItemAdd() LbDelItem() GFX_GOL_ListBoxItemRemove() LbChangeSel() GFX_GOL_ListBoxChangeSelection() LbSetSel() GFX_GOL_ListBoxSelectionSet() LbGetSel() GFX_GOL_ListBoxSelectionGet() LbGetFocusedItem() GFX_GOL_ListBoxFocusedItemGet() LbSetFocusedItem() GFX_GOL_ListBoxFocusedItemSet() LbGetCount(pLb) GFX_GOL_ListBoxCountGet() LbGetVisibleCount() GFX_GOL_ListBoxVisibleCountGet() LbSetBitmap() GFX_GOL_ListBoxBitmapSet() LbGetBitmap(pItem) GFX_GOL_ListBoxBitmapSet() Header File: gfx_gol_meter.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name MtrCreate() GFX_GOL_MeterCreate() MtrDraw() GFX_GOL_MeterDraw() MtrSetVa() GFX_GOL_MeterValueSet() MtrGetVal() GFX_GOL_MeterValueGet() MtrDecVal() GFX_GOL_MeterDecrementl() MtrIncVal GFX_GOL_MeterIncrement() MtrSetScaleColors GFX_GOL_MeterScaleColorsSet() MtrSetTitleFont(pMtr, pNewFont) GFX_GOL_MeterTitleFontSet() MtrSetValueFont(pMtr, pNewFont) GFX_GOL_MeterValueFontSet() MtrMsgDefault() GFX_GOL_MeterDefaultActionSet() MtrTranslateMsg() GFX_GOL_MeterActionGet() Header File: gfx_gol_picture.h 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-691 MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name PictCreat() GFX_GOL_PictureControlCreate() PictDraw() GFX_GOL_PictureControlDraw() PictSetBitmap() GFX_GOL_PictureControlBitmapSet() PictGetBitmap() GFX_GOL_PictureControlBitmapGet() PictGetScale() GFX_GOL_PictureControlScaleGet() PictSetScale() GFX_GOL_PictureControlScaleGet() PictTranslateMsg() GFX_GOL_PictureControlActionGet() Header File: gfx_gol_progress_bar.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name PbCreate() GFX_GOL_ProgressBarCreate() PbDraw() GFX_GOL_ProgressBarDraw() PbSetRange() GFX_GOL_ProgressBarRangeSet() PbGetRange() GFX_GOL_ProgressBarRangeGet() PbSetPos() GFX_GOL_ProgressBarPositionSet() PbGetPos() GFX_GOL_ProgressBarActionSet() PbTranslateMsg() GFX_GOL_ProgressBarActionGet() Header File: gfx_gol_radio_button.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name RbCreate() GFX_GOL_RadioButtonCreate() RbDraw() GFX_GOL_RadioButtonDraw() RbGetCheck() GFX_GOL_RadioButtonCheckGet() RbSetCheck() GFX_GOL_RadioButtonCheckGet() RbGetText(pRb) GFX_GOL_RadioButtonTextGet() RbSetText() GFX_GOL_RadioButtonTextGet() RbMsgDefault() GFX_GOL_RadioButtonActionSet() Header File: gfx_gol_scrollbar.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name SldCreate() GFX_GOL_ScrollBarCreate() SldDraw() GFX_GOL_ScrollBarDraw() SldSetPage() GFX_GOL_ScrollBarPageSet() SldGetPage() GFX_GOL_ScrollBarPageGet() SldSetPos() GFX_GOL_ScrollBarPositionSet() SldGetPos(pSld) GFX_GOL_ScrollBarPositionGet() SldSetRange() GFX_GOL_ScrollBarSetRange() SldGetRange() GFX_GOL_ScrollBarRangeGet() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Library Porting Guide 5-692 SldIncPos() GFX_GOL_ScrollBarPositionIncrement() SldDecPos() GFX_GOL_ScrollBarPositionDecrement() SldMsgDefault() GFX_GOL_ScrollBarActionSet() Header File: gfx_gol_static_text.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name StCreate() GFX_GOL_StaticTextCreate() StDraw() GFX_GOL_StaticTextDraw() StGetText() GFX_GOL_StaticTextGet() StSetText() GFX_GOL_StaticTextSet() StTranslateMsg() GFX_GOL_StaticTextActionGet() Header File: gfx_gol_text_entry.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name TeCreate() GFX_GOL_TextEntryCreate() TeDraw() GFX_GOL_TextEntryDraw() TeGetBuffer() GFX_GOL_TextEntryBufferGet() TeSetBuffer() GFX_GOL_TextEntryBufferSet() TeClearBuffer() GOL_GOL_TextEntryBufferClear() TeGetKeyCommand() GOL_GOL_TextEntryKeyCommandGet() TeSetKeyCommand() GOL_GOL_TextEntryKeyCommandSet() TeCreateKeyMembers() GOL_GOL_TextEntryKeyMembersCreate() TeAddChar() GOL_GOL_TextEntryCharAdd() TeIsKeyPressed() GOL_GOL_TextEntryKeyPressed() TeSpaceChar() GOL_GOL_TextEntryCharSpace() TeDelKeyMembers() GOL_GOL_TextEntryKeyMembersDelete() TeSetKeyText() GOL_GOL_TextEntrySetKeyText() TeMsgDefault() GOL_GOL_TextEntryActionSet() TeTranslateMsg() GOL_GOL_TextEntryActionGet() Header File: gfx/gfx_gol_window.h MLA Graphics Library Function Name MPLAB Harmony Graphics Library Function Name WndCreate() GFX_GOL_WindowCreate() WndDraw() GFX_GOL_WindowDraw() WndGetText() GFX_GOL_WindowTextGet() WndSetText() GFX_GOL_WindowTextSet() WndTranslateMsg() GFX_GOL_WindowActionGet() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-693 5.2.2 Graphics Object Library 5.2.2.1 Introduction Graphics Object Library for Microchip Microcontrollers This library provides the API of the Graphics Object Library that is available on the Microchip family of microcontrollers with a convenient C language interface. Description This document explains how to get started with Microchip Graphics Library solution. It presents the available resources and where to obtain these resources. It also includes the Application Programming Interface (API) of the Microchip Graphics Library. The Microchip %LibraryName% is highly modular and is optimized for Microchip’s microcontrollers. Additionally, the library is free for Microchip customers, easy to use, and has an open documented interface for new driver support, which requires creation of only one C file. The Microchip %LibraryName% Software %LibraryVersion% supports the following features: • Configurable graphic resolution • Up to 24-bit or 65K colors • 2D objects such as line, circle, text, rectangle, polygon, bar • 3D objects such as buttons, meter, dial, list box, edit box, check box, radio buttons, window, group box, slider. • Image, animation • Variety of user input device such as touch screen, keypad etc... 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-694 • Multiple fonts • Unicode fonts • PIC24 support, PIC32 support 5.2.2.2 Release Notes MPLAB Harmony Version: v0.70b Graphics Object Library Version : 4.00 Release Date: 18Nov2013 New This Release: This is the first release of the library. Known Issues: Nothing to report in this release. 5.2.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.2.2.4 Using the Library This topic describes the basic architecture of the Graphics Object Library and provides information and examples on how to use it. Interface Header File: gfx.h The interface to the Graphics Object library is defined in the "gfx.h" header file. This file is included by the "app.h" file. Any C language source (.c) file that uses the Graphics Object library should include "gfx.h". 5.2.2.4.1 Abstraction Model This library provides the API of the Graphics Object Library that is available on the Microchip family of microcontrollers with a convenient C language interface. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-695 Description Object Layer Software Abstraction Block Diagram The Graphics Object Layer organization is shown on the figure below: 5.2.2.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Object module. • General Object Layer Functions • Analog Clock Object Functions • Button Object Functions • Check Box Object Functions • Chart Object Functions • Custom Control Object Functions • Digital Meter Object Functions • Edit Box Object Functions • Grid Object Functions • Group Box Object Functions • List Box Object Functions • Meter Object Functions • Progress Bar Object Functions • Picture Object Functions • Radio Button Object Functions • Round Dial Object Functions • Scrollbar Object Functions • Static Text Object Functions • Text Entry Object Functions • Window Object Functions • Draw Functions • Image Functions 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-696 • Palette Functions • Style Scheme Functions • Global Variables • Data Types and Constants 5.2.2.4.3 How the Library Works 5.2.2.4.3.1 Objects Functionality 5.2.2.4.3.1.1 Widget Objects All the GOL objects that will be shown in the display have a corresponding data structure that keeps and maintains its parameters. Each object type has a set of functions that enables the user to change the state of the object. Each GOL object type uses a style scheme. The style scheme defines the font and color settings. User can create new style schemes and assign it to objects. Multiple style schemes can be used for different objects. To efficiently manage the different objects the first 9 fields of the structure for each object are defined the same. Collectively they are referred to as the object header structure (GFX_OBJ_HEADER). Defining the GFX_OBJ_HEADER enables the common APIs to manage the objects of different types in the same manner. The GOL operation is centered on two major processes. First is the rendering process and second is the messaging process. These processes make use of linked list objects. The field pNxtObj in GFX_OBJ_HEADER makes this possible. To manage the list a global pointer _pGolObjects is utilized. It defines the current active linked list. Newly created objects are automatically added to the end of this list. The active linked list is the list that the messaging and rendering operation parses to evaluate if the messages received affect the objects and if objects need to be redrawn. The use of the _pGolObjects pointer also provides a way to easily manage objects. In applications where multiple pages are displayed on the screen, objects can be grouped according to pages. The pointer can be manipulated to switch from one page to another depending on the page currently shown on the screen. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-697 Implementation of Multi-Page Objects Users can remove an object from a list by pointer manipulation. Objects that are removed from the list are not accessible by the rendering and messaging processes. 5.2.2.4.3.1.2 States The GOL objects follow two types of states, the Property States and the Drawing States. Property States defines action and appearance of objects. Drawing States on the other hand indicate if the object needs to be hidden, partially redrawn, or fully redrawn in the display. To store the states, the field state defined in GFX_OBJ_HEADER structure is used. Six most significant bits are allocated for Drawing States and the rest is allocated for the Property States. Some common Property States and Drawing States are shown below. • GFX_OBJ_STATE_FOCUSED • GFX_OBJ_STATE_DISABLED • GFX_OBJ_STATE_DRAW_FOCUS • GFX_OBJ_STATE_DRAW • GFX_OBJ_STATE_HIDE Individual Object drawing function (e.g. BtnDraw(), SldDraw(), etc...) does not reset the draw states instead use GFX_OBJ_Draw() to automatically reset and manage the draw states. If the call to individual drawing function cannot be avoided, draw states must be reset manually after the drawing functions returns a 1. 5.2.2.4.3.1.3 Rendering The library renders objects in a Non-Blocking manner. The Non-Blocking configuration is implemented by the use of drawing state machine. Each drawing functions groups the rendering steps into states. Every time a rendering step is executed, the drawing state is updated. Before each step is executed, the display device is checked if it is still busy with the previous rendering operation. If it is busy it returns a non-zero value. This indicates that the draw function must be called again to complete the 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-698 rendering. The drawing function can be called several times until rendering is completed. State Machine Controlled Rendering The GOL level uses the active object linked list for drawing of objects. Each object’s state in the list is parsed to determine if the object needs to be redrawn or not. The drawing order is from the head to the tail of the list. This sequence is executed by GFX_OBJ_Draw() function. The figure below explains the rendering loop of the GFX_OBJ_Draw() function. GOL Object Rendering Loop The loop shows two exit points in the sequence. First is when the end of the list is reached and the second is when an GFX_OBJ_Draw() returns a NOT DONE status. Reaching the end of the list is a normal exit. This means that all the state 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-699 machines of the draw functions of each object have reset to default. Exiting with a NOT DONE status means that the latest executed draw function was pended and the object is not yet fully rendered. To complete the rendering, GFX_OBJ_Draw() function should be called again. The next call to GFX_OBJ_Draw() will pickup the rendering on the last object that returned a not DONE status. This operation makes the rendering functions non-blocking and gives opportunity to release control to program without waiting for the rendering completion. When all objects in the active object linked list are drawn GFX_OBJ_Draw() calls user defined GFX_OBJ_DrawCallback() function. User drawing can be done in this callback function. If the function returns a zero, drawing of GOL objects in the active list is suspended. In this case color, clipping region, line type and graphic cursor will not be modified by GOL. If it returns a 1 drawing control is returned to GOL. GFX_OBJ_Draw() resume rendering of objects in the current active list. Inside the GFX_OBJ_DrawCallback() function, the active object list is not used by GFX_OBJ_Draw(). It is safe to perform modification of the list. Please refer to Configuration Settings to set Blocking or Non-Blocking configuration. 5.2.2.4.3.2 Messaging Functionality To facilitate the processing of user actions on the objects, messaging are used. User passes messages from the input devices to GOL using the GOL message structure. (See: GFX_OBJ_MESSAGE for structure information) GFX_OBJ_Message() function accepts this structure and processes the message for all objects in the active list. Messaging Flow The messaging mechanism follows this flow: 1. User Interface Module (touch screen, keypad) sends a GOL message (the GFX_OBJ_MESSAGE structure). 2. A loop evaluates which object is affected by the message. This is done inside GFX_OBJ_Message() function. 3. Affected object returns the translated message based on the GOL message parameters. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-700 4. User can change default action with the callback function. If the call back function returns a non-zero value message will be processed by default. 5. Object should be redrawn to reflect new state. The translated message is a set of actions unique to each object type. Please refer to each object translated message ID for details. Objects that are disabled will not accept any messages. GFX_OBJ_Message() function must be called when GOL drawing is completed. In this case all objects have been drawn and it is safe to change objects states. GFX_OBJ_Message() call can be done if GFX_OBJ_Draw() function returns non-zero or inside GFX_OBJ_DrawCallback() function. 5.2.2.4.3.3 Scheme Functionality All objects uses a style scheme structure that defines the font and colors used. Upon the object’s creation a user defined style scheme can be assigned to the object. In the absence of the user defined scheme, the default scheme is used. (See: GFX_GOL_OBJ_SCHEME for structure information) TextColorDisabled and ColorDisabled are used when the object is in the disabled state. Otherwise, TextColor0, TextColor1, Color0 and Color1 are used. When object Draw state is set to GFX_OBJ_STATE_HIDE, the CommonBkColor is used to fill area occupied by object. Style scheme can be created with GFX_OBJ_SchemeCreate() function that returns a pointer to the newly created GFX_GOL_OBJ_SCHEME structure with default values automatically assigned. The default values can be changed in the gfx_gol_scheme_default.c file. The application code can define its own default style scheme by defining the macro GFX_SCHEMEDEFAULT in the GraphicsConfig.h. Then, GFX_GOL_OBJ_SCHEME GFX_OBJECT_SchemeDefault must be defined in the application code with each structure member initialized to the desired values. See GOLSchemeDefault.c file for an example on how to initialize the style scheme. 5.2.2.5 Configuring the Library The configuration of the Graphics Object Layer is based on the file system_config.h This header file contains the configuration selection for the Graphics Object Layer. Based on the selections made, the Graphics Object Layer will support or not support selected features. These configuration settings will apply to all instances of the Graphics Object Layer. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.2.2.6 Building the Library This section list the files that are available in the \src of the object driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-701 5.2.2.7 Library Interface Data Types and Constants Name Description CHARTPARAM Defines the parameters for the CHART object. DATASERIES Defines a variable for the CHART object. It specifies the number of samples, pointer to the array of samples for the data series and pointer to the next data series. A member of this structure (show) is used as a flag to determine if the series is to be drawn or not. Together with the smplStart and smplEnd it will determine what kind of chart will be drawn. FileFeof This is type FileFeof. FileRead Typedefs of the used File System APIs FileSeek This is type FileSeek. FileTell This is type FileTell. FONT_ORIENTATION Types of orientation GFX_ALIGNMENT Defines the types of text alignment. The text alignment is used in GFX_TextStringBoxDraw(). 5.2.2.7.1 General Object Layer Functions 5.2.2.7.1.1 GFX_GOL_DrawCallbackSet Function C void GFX_GOL_DrawCallbackSet( GFX_GOL_DRAW_CALLBACK_FUNC pFunc ); Description This function sets the draw callback function that the application will use to call primitive function to implement application specific shapes.See GFX_GOL_DRAW_CALLBACK_FUNC definition for details on the draw callback function. Preconditions None. Parameters Parameters Description pFunc pointer to the draw callback function. Returns None. Example None. 5.2.2.7.1.2 GFX_GOL_MessageCallbackSet Function C void GFX_GOL_MessageCallbackSet( GFX_GOL_MESSAGE_CALLBACK_FUNC pFunc 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-702 ); Description This function sets the message callback function that the application will use to evaluate user inputs that affects the objects and application behavior. The callback function location is specified by the function pointer supplied in the call. See GFX_GOL_MESSAGE_CALLBACK_FUNC definition for details on the message callback function. Preconditions None. Parameters Parameters Description pFunc pointer to the message callback function. Returns None. Example None. 5.2.2.7.1.3 GFX_GOL_ObjectAdd Function C void GFX_GOL_ObjectAdd( GFX_GOL_OBJ_HEADER * pObject ); Description This function adds an object to the tail of the currently active list. The new list tail is set to point to NULL after the new object is added. Preconditions None. Returns None. Example void MoveObject( GFX_GOL_OBJ_HEADER *pSrcList, GFX_GOL_OBJ_HEADER *pDstList, GFX_GOL_OBJ_HEADER *pObjtoMove) { GFX_GOL_OBJ_HEADER *pTemp = pSrcList; if(pTemp != pObjtoMove) { while(pTemp->pNxtObj != pObjtoMove) pTemp = pTemp->pNxtObj; } pTemp->pNxtObj = pObjtoMove ->pNxt; // remove object from list GFX_GOL_ObjectListSet(pDstList); // destination as active list GFX_GOL_ObjectAdd(pObjtoMove); // add object to active list } 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-703 5.2.2.7.1.4 GFX_GOL_ObjectBackGroundSet Function C void GFX_GOL_ObjectBackGroundSet( GFX_GOL_OBJ_HEADER * pObjectHeader ); Description This function sets the background information. This is an internal function and should not be called by the application. This function is used by object's drawing functions to set the background information. Preconditions None. Returns None. Example None. 5.2.2.7.1.5 GFX_GOL_ObjectByIDDelete Function C GFX_STATUS GFX_GOL_ObjectByIDDelete( uint16_t id ); Description This function removes an object with the given user defined ID from the currently active list. Aside from the removal of the object from the list, the RAM resources consumed by the object is also freed. If there is no object with the given ID, the function exits with GFX_STATUS_FAILURE. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned if the removal was successful. GFX_STATUS_FAILURE - is returned if the removal was not successful. Example TODO:Add example code 5.2.2.7.1.6 GFX_GOL_ObjectCanBeFocused Function C GFX_STATUS GFX_GOL_ObjectCanBeFocused( GFX_GOL_OBJ_HEADER * pObject ); Description This function checks if the object can be focused or not. If the object can be focused, it returns GFX_STATUS_SUCCESS. If it cannot be focused, it returns GFX_STATUS_FAILURE. Selected objects have the focus feature. Refer to the object documentation for details. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-704 Objects that do not support focus feature will ignore any focus settings. If the object is disabled it cannot be set to focused state. Preconditions None. Parameters Parameters Description pObject pointer to the object. Returns GFX_STATUS_SUCCESS - when the object can be focused GFX_STATUS_FAILURE - when the object cannot be focused or do not support the focus feature. Example TODO:Add example code here 5.2.2.7.1.7 GFX_GOL_ObjectDelete Function C GFX_STATUS GFX_GOL_ObjectDelete( GFX_GOL_OBJ_HEADER * pObject ); Description This function removes an object from the currently active list. Aside from the removal of the object from the list, the RAM resources consumed by the object is also freed. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned if the removal was successful. GFX_STATUS_FAILURE - is returned if the removal was not successful. Example TODO:Add example code 5.2.2.7.1.8 GFX_GOL_ObjectDrawDisable Function C void GFX_GOL_ObjectDrawDisable( GFX_GOL_OBJ_HEADER * pObject ); Description This function resets the drawing state bits of the object. This function can be called to cancel any drawing state bits that has been set or clears all the drawing state bits after the object has been redrawn. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-705 Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.1.9 GFX_GOL_ObjectDrawEnable Function C void GFX_GOL_ObjectDrawEnable( GFX_GOL_OBJ_HEADER * pObject ); Description This function sets the object to be redrawn. For the redraw to be effective, the object must be in the current active list. If not, the redraw action will not be performed until the list where the object is currently inserted will be set as the active list. Preconditions None. Parameters Parameters Description pObject pointer to the object that will be redrawn. Returns None. Example void GOLRedrawRec(uint16_t left, uint16_t top, uint16_t right, uint16_t bottom) { GFX_GOL_OBJ_HEADER *pCurrentObj; int overlapX, overlapY; pCurrentObj = _pGolObjects; while(pCurrentObj != NULL) { overlapX = overlapY = 0; // check overlaps in x direction if (((pCurrentObj->left <= left) && (pCurrentObj->right >= left)) || ((pCurrentObj->left <= right) && (pCurrentObj->right >= right)) || ((pCurrentObj->left <= left) && (pCurrentObj->right >= right)) || ((pCurrentObj->left >= left) && (pCurrentObj->right <= right)) ) overlapX = 1; // check overlaps in y direction if (((pCurrentObj->top <= top) && (pCurrentObj->bottom >= top)) || ((pCurrentObj->top <= bottom) && (pCurrentObj->bottom >= bottom)) || ((pCurrentObj->top <= top) && (pCurrentObj->bottom >= bottom)) || 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-706 ((pCurrentObj->top >= top) && (pCurrentObj->bottom <= bottom)) ) overlapY = 1; // when any portion of the widget is touched by the defined rectangle the // x and y overlaps will exist. if (overlapX & overlapY) { GFX_GOL_ObjectRedraw(pCurrentObj); } pCurrentObj = (GFX_GOL_OBJ_HEADER *)pCurrentObj->pNxtObj; } //end of while } 5.2.2.7.1.10 GFX_GOL_ObjectFind Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectFind( uint16_t ID ); Description This function returns the pointer to object in the list with the user defined ID assigned to it. Preconditions None. Returns The pointer to the object in the list with the given ID. Example void CopyObject(GFX_GOL_OBJ_HEADER *pSrcList, GFX_GOL_OBJ_HEADER *pDstList, uint16_t ID) { GFX_GOL_OBJ_HEADER *pTemp; // find the object pTemp = GFX_GOL_ObjectFind(ID); if (pTemp != NULL) { // destination as active list GFX_GOL_ObjectSetList(pDstList); // add object to active list GFX_GOL_ObjectAdd(pTemp); } } 5.2.2.7.1.11 GFX_GOL_ObjectFocusGet Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectFocusGet(); Description This function returns the pointer to the object that is currently receiving keyboard input (or focused). If there are no object that can accept keyboard messages, then the function will return NULL. Objects that can be focused are those objects that can receive keyboard inputs. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-707 Preconditions None. Returns The pointer the currently focused object. Returns NULL if there is no object currently set. Example TODO:Add example code here 5.2.2.7.1.12 GFX_GOL_ObjectFocusNextGet Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectFocusNextGet(); Description This function returns the pointer to the next object in the active list of objects which can be focused. The reference point is the currently focused object. If there is no currently focused object, the searched starts from the beginning of the active list of objects. Objects that can be focused are those objects that can receive keyboard inputs. If there is no object capable of receiving keyboard inputs (i.e. none can be focused) NULL is returned. Preconditions None. Returns The pointer to the object that can be focused. Example TODO:Add example code here 5.2.2.7.1.13 GFX_GOL_ObjectFocusPrevGet Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectFocusPrevGet(); Description This function returns the pointer to the previous object in the active list of objects which can be focused. The reference point is the currently focused object. If there is no currently focused object, the searched starts from the beginning of the active list of objects. Objects that can be focused are those objects that can receive keyboard inputs. If there is no object capable of receiving keyboard inputs (i.e. none can be focused) NULL is returned. Preconditions None. Returns The pointer to the object that can be focused. Example TODO:Add example code here 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-708 5.2.2.7.1.14 GFX_GOL_ObjectFocusSet Function C GFX_STATUS GFX_GOL_ObjectFocusSet( GFX_GOL_OBJ_HEADER * pObject ); Description This function sets the specified object to be focused. If the object cannot accept keyboard messages, the object will not be set to focused state. If the object can accept keyboard messages, then the focus state will be set and will be marked to be redrawn to show the focus when the focus feature is enabled. Objects that can be focused are those objects that can receive keyboard inputs. Preconditions None. Parameters Parameters Description pObject pointer to the object. Returns GFX_STATUS_SUCCESS - when the object can be focused GFX_STATUS_FAILURE - when the object cannot be focused or do not support the focus feature. Example TODO:Add example code here 5.2.2.7.1.15 GFX_GOL_ObjectHideDraw Function C GFX_STATUS GFX_GOL_ObjectHideDraw( GFX_GOL_OBJ_HEADER * pObject ); Description This is function GFX_GOL_ObjectHideDraw. 5.2.2.7.1.16 GFX_GOL_ObjectIDGet Function C uint16_t GFX_GOL_ObjectIDGet( GFX_GOL_OBJ_HEADER * pObject ); Description This function returns the user defined ID assigned to the object. Preconditions None. Returns The user defined ID of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-709 Example void ExampleUsageOfGettingID(GFX_GOL_OBJ_HEADER *pObject) { uint16_t id; switch(id = GFX_GOL_ObjectIDGet(pObject)) { case ID_WINDOW1: // do something case ID_WINDOW2: // do something else case ID_WINDOW3: // do something else default: // do something else } } 5.2.2.7.1.17 GFX_GOL_ObjectIsRedrawSet Function C bool GFX_GOL_ObjectIsRedrawSet( GFX_GOL_OBJ_HEADER * pObject ); Description This function checks if the object needs to be redrawn or not. The function returns true if it is to be redrawn or false if it is not to be redrawn. Preconditions None. Parameters Parameters Description pObject pointer to the object that will be checked. Returns true - when the object needs to be redrawn. false - when the object does not need to be redrawn. Example int DrawButtonWindowOnly() { static GFX_GOL_OBJ_HEADER *pCurrentObj = NULL; uint16_t done = 0; if (pCurrentObj == NULL) { // get current list pCurrentObj = GFX_GOL_ObjectListGet(); } while(pCurrentObj != NULL) { if(GFX_GOL_ObjectIsRedrawSet(pCurrentObj) == true) { done = pCurrentObj->draw(pCurrentObj); // reset state of object if done if (done) GOLDrawComplete(pCurrentObj) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-710 // Return if not done. This means that Button Draw function // was not able to finish redrawing the object // and must be called again to finish rendering of // objects in the list that have new states. else return 0; } // go to the next object in the list pCurrentObj = pCurrentObj->pNxtObj; } return 1; } 5.2.2.7.1.18 GFX_GOL_ObjectListDraw Function C GFX_STATUS GFX_GOL_ObjectListDraw(); Description This function loops through the active list and redraws objects that need to be redrawn. Partial redrawing or full redraw is performed depending on the drawing states of the objects. GFX_GOL_ObjectDrawCallback() function is called by GFX_GOL_ObjectListDraw() when drawing of objects in the active list is completed. GFX_GOL_ObjectDrawCallback() is an application implemented function that allows the application the opportunity to insert application specific rendering using Primitive Layer rendering functions. The GFX_GOL_ObjectListDraw() function can return with GFX_STATUS_BUSY. In this case, it indicates that the currently redrawn object is not able to continue. Application needs to call GFX_GOL_ObjectListDraw() again to continue the redraw of the objects in the list. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned when the active list is completely parsed and redrawn. GFX_STATUS_BUSY - is returned when the active list is not completely parsed and redrawn. Example // Assume objects are created & states are set to draw objects while(1) { // parse active list and redraw objects // that needs to be redrawn if( GFX_GOL_ObjectListDraw() == GFX_STATUS_SUCCESS) { // at this point drawing is completed // it is safe to modify objects states and linked list // evaluate messages from touch screen device TouchGetMsg(&msg); // evaluate each object is affected by the message GFX_GOL_ObjectMessage(&msg); } } 5.2.2.7.1.19 GFX_GOL_ObjectListFree Function C GFX_STATUS GFX_GOL_ObjectListFree(); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-711 Description This function frees all the memory used by objects in the active list and initializes the active list pointer to NULL to start a new empty list. This function must be called only inside the GFX_GOL_ObjectDrawCallback() function when using GFX_GOL_ObjectListDraw() and GFX_GOL_ObjectMessage() functions. This requirement assures that primitive rendering settings are not altered by the rendering state machines of the objects. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned if the free was successful. GFX_STATUS_FAILURE - is returned if the free was not successful. Example void DeletePage(GFX_GOL_OBJ_HEADER *pPage) { GFX_GOL_OBJ_HEADER *pTemp; // assuming pPage is different from the current active list // save the active list pTemp = GFX_GOL_ObjectListGet(); // set list as active list GFX_GOL_ObjectListSet(pPage); // pPage objects are deleted GFX_GOL_ObjectListFree(); // restore the active list GFX_GOL_ObjectListSet(pTemp); } 5.2.2.7.1.20 GFX_GOL_ObjectListGet Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectListGet(); Description This function returns the pointer to the current active. Preconditions None. Returns Pointer (type GFX_GOL_OBJ_HEADER) to the current active list. Example See GFX_GOL_ObjectListNew() for example code. 5.2.2.7.1.21 GFX_GOL_ObjectListNew Function C GFX_STATUS GFX_GOL_ObjectListNew(); Description This function starts a new linked list of objects and resets the keyboard focus to none. This function assigns the current active list 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-712 and current focused object (receiving keyboard inputs) object pointers to NULL. Any keyboard inputs at this point will be ignored. This function does not erase the objects in the previous list. Application must save the previous list to another pointer if to be referenced later. If not needed anymore, memory used by that list should be freed by GFX_GOL_ObjectListFree() function. In this case, freeing the list with GFX_GOL_ObjectListFree() function has the same effect as GFX_GOL_ObjectListNew() where the current active list is empty. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned if the new list start was successful. GFX_STATUS_FAILURE - is returned if the new list start was not successful. Example // assume pointers to objects (pButton, pWindow and pSlider // are initialized to objects already created // GFX_GOL_OBJ_HEADER *pButton; // GFX_GOL_OBJ_HEADER *pWindow; // GFX_GOL_OBJ_HEADER *pSlider; GFX_GOL_OBJ_HEADER *pSave; // save current list pSave = GFX_GOL_ObjectListGet(); // start the new list, after the start of the list, the // current active list is empty. GFX_GOL_ObjectListNew(); // assume that objects are already created // you can now add objects to the new list GFX_GOL_ObjectAdd(pButton); GFX_GOL_ObjectAdd(pWindow); GFX_GOL_ObjectAdd(pSlider); 5.2.2.7.1.22 GFX_GOL_ObjectListSet Function C GFX_STATUS GFX_GOL_ObjectListSet( GFX_GOL_OBJ_HEADER * pList ); Description This function sets the active list to the new list. The previous list will still exist in memory. Application must save the previous list before the set is called if the previous list will be referenced later. If the previous list is not needed anymore, then the list must be removed from memory by GFX_GOL_ObjectListFree() function. Setting the active list to the new list will reset the focused pointer object to NULL. Preconditions None. Returns GFX_STATUS_SUCCESS - is returned if the set was successful. GFX_STATUS_FAILURE - is returned if the set was not successful. Example GFX_GOL_OBJ_HEADER *pSave; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-713 // save current list pSave = GFX_GOL_ObjectListSet(); // start the new list GFX_GOL_ObjectListNew(); // you can now add objects to the current list // assume that objects are already created GFX_GOL_ObjectAdd(pButton); GFX_GOL_ObjectAdd(pWindow); GFX_GOL_ObjectAdd(pSlider); // do something here on the new list // return the old list GOLSetList(pSave); 5.2.2.7.1.23 GFX_GOL_ObjectMessage Function C void GFX_GOL_ObjectMessage( GFX_GOL_MESSAGE * pMsg ); Description This function receives a GFX_GOL_MESSAGE message from user and loops through the active list of objects to check which object is affected by the message. For affected objects the message is translated and GFX_GOL_ObjectMessageCallback() is called. In the call back function, user has the ability to implement action for the message. If the call back function returns non-zero, OBJMsgDefault() is called to process message for the object by default. If zero is returned OBJMsgDefault() is not called. Please refer to GOL Messages section for details. Preconditions None. Parameters Parameters Description pMessage Pointer to the message from user. Returns None. Example // Assume objects are created & states are set to draw objects while (1) { if(GOLDraw()) { // GOL drawing is completed here // it is safe to change objects // from user interface module TouchGetMsg(&msg); // process the message GFX_GOL_ObjectMessage(&msg); } } 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-714 5.2.2.7.1.24 GFX_GOL_ObjectNextGet Function C GFX_GOL_OBJ_HEADER * GFX_GOL_ObjectNextGet( GFX_GOL_OBJ_HEADER * pObject ); Description This function returns the pointer to next object in the list after the specified object. Preconditions None. Returns The pointer to the next object in the list. Example void RedrawButtons(void) { GFX_GOL_OBJ_HEADER *pCurr; // get active list pCurr = GFX_GOL_ObjectListGet(); while(pCurr->pNxtObj != NULL) { // just select button objects and redraw them if (GFX_GOL_ObjectTypeGet(pCurr) == BUTTON) { // set to be redrawn pCurr->state = BTN_DRAW; } pCurr = GFX_GOL_ObjectNextGet(pCurr); } // redraw all buttons in the active list GFX_GOL_ObjectListDraw(); } 5.2.2.7.1.25 GFX_GOL_ObjectRectangleRedraw Function C void GFX_GOL_ObjectRectangleRedraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); Description This function marks all objects in the active list intersected by the given rectangular area to be redrawn. After calling this function, the next call to GFX_GOL_ObjectListDraw() will redraw all objects that are marked for redraw. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-715 Parameters Parameters Description left Defines the left most border of the rectangle area. top Defines the top most border of the rectangle area. right Defines the right most border of the rectangle area. bottom Defines the bottom most border of the rectangle area. Returns None. Example GFX_GOL_OBJ_HEADER *pTemp; GFX_GOL_OBJ_HEADER *pAllObjects; // assume *pAllObjects points to a list of all existing objects // created and initialized // mark all objects inside the rectangle to be redrawn GOLRedrawRec(10,10,100,100); // save the current active list pTemp = pAllObjects; // reset active list GFX_GOL_ObjectListNew(); // build the new active list with only those objects that // are marked to be redrawn while(pTemp->pNxtObj != NULL) { if (pTemp->state&0x7C00) GFX_GOL_ObjectAdd(pTemp); pTemp = pTemp->pNxtObj; } // redraw active list GFX_GOL_ObjectListDraw(); 5.2.2.7.1.26 GFX_GOL_ObjectTypeGet Function C GFX_GOL_OBJ_TYPE GFX_GOL_ObjectTypeGet( GFX_GOL_OBJ_HEADER * pObject ); Description This function returns the object type. The object type is one of the defined enumerated types of GFX_GOL_OBJ_TYPE. Preconditions None. Returns The type of the object. The type is one of the defined enumerated types of GFX_GOL_OBJ_TYPE. Example TODO:Add example code here 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-716 5.2.2.7.1.27 GFX_GOL_PanelAlphaParameterSet Function C void GFX_GOL_PanelAlphaParameterSet( uint16_t alphaValue ); Description This is function GFX_GOL_PanelAlphaParameterSet. 5.2.2.7.1.28 GFX_GOL_PanelBackgroundSet Function C void GFX_GOL_PanelBackgroundSet( GFX_GOL_OBJ_HEADER * pObjectHeader ); Description This is function GFX_GOL_PanelBackgroundSet. 5.2.2.7.1.29 GFX_GOL_PanelDraw Function C GFX_STATUS GFX_GOL_PanelDraw(); Description This is function GFX_GOL_PanelDraw. 5.2.2.7.1.30 GFX_GOL_PanelGradientParameterSet Function C void GFX_GOL_PanelGradientParameterSet( GFX_COLOR startColor, GFX_COLOR endColor ); Description This is function GFX_GOL_PanelGradientParameterSet. 5.2.2.7.1.31 GFX_GOL_PanelParameterSet Function C void GFX_GOL_PanelParameterSet( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t radius, GFX_COLOR faceClr, GFX_COLOR embossLtClr, GFX_COLOR embossDkClr, GFX_RESOURCE_HDR * pBitmap, GFX_FILL_STYLE fillStyle, uint16_t embossSize ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-717 Description This is function GFX_GOL_PanelParameterSet. 5.2.2.7.1.32 GFX_GOL_TwoTonePanelDraw Function C GFX_STATUS GFX_GOL_TwoTonePanelDraw(); Description This is function GFX_GOL_TwoTonePanelDraw. 5.2.2.7.2 Analog Clock Object Functions 5.2.2.7.2.1 GFX_AnalogClockCreate Function C GFX_GOL_ANALOGCLOCK * GFX_AnalogClockCreate( uint16_t ID, short left, short top, short right, short bottom, short hour, short minute, short radius, bool sechand, uint16_t state, void * pBitmap, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a analog clock at the given position using state, radius, pBitmap, pText, and pScheme. Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. hour Initial hour value. minute Initial minute value. radius Sets the radius of the clock. sechand Flag to indicate if the second hand will be drawn or not. state Sets the initial state of the object. pBitmap Pointer to the bitmap used on the face of the analog clock dimension of the image must match the dimension of the widget. pScheme Pointer to the style scheme used 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-718 Returns Returns a pointer to the digital meter. Example GFX_GOL_SCHEME *pScheme; uint16_t state; pScheme = GFX_GOL_SCHEMeCreate(); state = AC_DRAW; AnalogClock = GFX_AnalogClock_Create(ANALOGCLOCK_ID, 20, 64, 50, 118, 1, 20, 30, FALSE, state, NULL, pScheme); Remarks: 5.2.2.7.2.2 GFX_GOL_AnalogClockDraw Function C GFX_STATUS GFX_GOL_AnalogClockDraw( void * pAc ); Description This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. Preconditions Object must be created before this function is called. Parameters Parameters Description pAc Pointer to the object to be rendered. Returns Returns the status of the drawing • 1 - If the rendering was completed and • 0 - If the rendering is not yet finished. Next call to the function will resume the rendering on the pending drawing state. Side Effects none Example void MyGOLDraw(){ static GFX_OBJ_HEADER *pCurrentObj = NULL; int done; // There are no objects if(GFX_OBJ_ListGet() == NULL) return; // If it's last object jump to head if(pCurrentObj == NULL) pCurrentObj = GFX_OBJ_ListGet(); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-719 done = 0; // this only process Button and Window while(pCurrentObj != NULL){ // check if object state indicates redrawing if(pCurrentObj->state&0xFC00) { switch(pCurrentObj->type){ case OBJ_ANALOGCLOCK: done = AcDraw((ANALOGCLOCK*)pCurrentObj); break; case OBJ_WINDOW: done = WndDraw((WINDOW*)pCurrentObj); break; default: done = 1; break; } if(done){ // reset only the state if drawing was finished pCurrentObj->state = 0; }else{ // done processing the list return; } } // go to next object pCurrentObj = pCurrentObj->pNxtObj; } } 5.2.2.7.2.3 GFX_GOL_AnalogClockHandsDraw Function C GFX_STATUS GFX_GOL_AnalogClockHandsDraw( GFX_GOL_ANALOGCLOCK * pAc, short hand, short thickness, GFX_COLOR color ); Description Draws the current position of the clock hands with the given thickness and color. Preconditions none Parameters Parameters Description pAc The pointer to the object whose hands will be modified. hand which hand to be drawn (second, minute, hour) thickness thickness to draw the hand color color to draw the hand *pBitmap bitmap background to be redrawn Returns none Side Effects none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-720 5.2.2.7.2.4 GFX_GOL_AnalogClockHourSet Function C void GFX_GOL_AnalogClockHourSet( GFX_GOL_ANALOGCLOCK * pAc, short hour ); Description Sets the hour value of the analog clock. Preconditions none Parameters Parameters Description pAc The pointer to the object whose hands will be modified. hour New hour time. Returns none Side Effects none 5.2.2.7.2.5 GFX_GOL_AnalogClockMinuteSet Function C void GFX_GOL_AnalogClockMinuteSet( GFX_GOL_ANALOGCLOCK * pAc, short minute ); Description Sets the minute value of the analog clock. Preconditions none Parameters Parameters Description pAc The pointer to the object whose hands will be modified. minute New minute time. Returns none Side Effects none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-721 5.2.2.7.2.6 GFX_GOL_AnalogClockSecondSet Function C void GFX_GOL_AnalogClockSecondSet( GFX_GOL_ANALOGCLOCK * pAc, short second ); Description Sets the second value of the analog clock. Preconditions none Parameters Parameters Description pAc The pointer to the object whose hands will be modified. second New second time. Returns none Side Effects none 5.2.2.7.3 Button Object Functions 5.2.2.7.3.1 GFX_GOL_ButtonActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_ButtonActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_BUTTON_ACTION_PRESSED Touch Screen EVENT_PRESS, EVENT_MOVE If events occurs and the x,y position falls in the face of the GFX_GOL_BUTTON while the GFX_GOL_BUTTON is not pressed. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_CR_PRESSED or SCAN_SPACE_PRESSED while the GFX_GOL_BUTTON is not pressed. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-722 GFX_GOL_BUTTON_ACTION_STILLPRESSED Touch Screen EVENT_STILLPRESS If event occurs and the x,y position does not change from the previous press position in the face of the GFX_GOL_BUTTON. GFX_GOL_BUTTON_ACTION_RELEASED Touch Screen EVENT_RELEASE If the event occurs and the x,y position falls in the face of the GFX_GOL_BUTTON while the GFX_GOL_BUTTON is pressed. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_CR_RELEASED or SCAN_SPACE_RELEASED while the GFX_GOL_BUTTON is pressed. GFX_GOL_BUTTON_ACTION_CANCELPRESS Touch Screen EVENT_MOVE If the event occurs outside the face of the GFX_GOL_BUTTON and the GFX_GOL_BUTTON is currently pressed. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_BUTTON_ACTION_PRESSED – Object is pressed • GFX_GOL_BUTTON_ACTION_RELEASED – Object is released • GFX_GOL_BUTTON_ACTION_CANCELPRESS – Object will be released, user cancels press action on the GFX_GOL_BUTTON • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.3.2 GFX_GOL_ButtonActionSet Function C void GFX_GOL_ButtonActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-723 Translated Message Input Source Set/Clear State Bit Description GFX_GOL_BUTTON_ACTION_PRESSED Touch Screen, Set GFX_GOL_BUTTON_PRESSED_STATE Button will be redrawn in the pressed state. Keyboard GFX_GOL_BUTTON_ACTION_RELEASED Touch Screen, Clear GFX_GOL_BUTTON_PRESSED_STATE Button will be redrawn in the released state. Keyboard GFX_GOL_BUTTON_ACTION_CANCELPRESS Touch Screen, Clear GFX_GOL_BUTTON_PRESSED_STATE Button will be redrawn in the released state. Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.3.3 GFX_GOL_ButtonCreate Function C GFX_GOL_BUTTON * GFX_GOL_ButtonCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t radius, uint16_t state, GFX_RESOURCE_HDR * pPressImage, GFX_RESOURCE_HDR * pReleaseImage, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_BUTTON object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The object allows setting two images. One for the pressed state and the other for the release state. If no image is to be used for the object set both pointers to NULL. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-724 If only one image is used for both pressed and released state, set both pPressImage and pReleaseImage to the same image. The behavior of GFX_GOL_ButtonCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pPressImage and pReleaseImage is not pointing to a GFX_RESOURCE_HDR. • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. radius Radius of the rounded edge. When using gradient buttons and radius != 0, emboss size <= radius. If this is not met, the the GFX_GOL_BUTTON face will not have gradient effect. state Sets the initial state of the object. pPressImage Pointer to the image used on the face of the object when it is in the pressed state. pReleaseImage Pointer to the image used on the face of the object when it is in the pressed state. pText Pointer to the text of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_BUTTON *buttons[3]; GFX_GOL_BUTTON_STATE state; // assume pScheme is initialized to a scheme in memory. state = GFX_GOL_BUTTON_DRAW_STATE; buttons[0] = GFX_GOL_ButtonCreate( 1, 20, 64, 50, 118, 0, state, NULL, NULL, "ON", GFX_ALIGN_HCENTER | GFX_ALIGN_VCENTER, pScheme); // check if GFX_GOL_BUTTON 0 is created if (buttons[0] == NULL) return 0; buttons[1] = GFX_GOL_ButtonCreate( 2, 52, 64, 82, 118, 0, state, NULL, NULL, "OFF", GFX_ALIGN_LEFT | GFX_ALIGN_VCENTER, pScheme); // check if GFX_GOL_BUTTON 1 is created 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-725 if (buttons[1] == NULL) return 0; buttons[2] = GFX_GOL_ButtonCreate( 3, 84, 64, 114, 118, 0, state, NULL, NULL, "HI", GFX_ALIGN_RIGHT | GFX_ALIGN_VCENTER, pScheme); // check if GFX_GOL_BUTTON 2 is created if (buttons[2] == NULL) return 0; return 1; 5.2.2.7.3.4 GFX_GOL_ButtonDraw Function C GFX_STATUS GFX_GOL_ButtonDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the face of the GFX_GOL_BUTTON is drawn on top of the bitmap. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.3.5 GFX_GOL_ButtonTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_ButtonTextAlignmentGet( GFX_GOL_BUTTON * pObject ); Description This function returns the text alignment of the text string used by the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-726 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.3.6 GFX_GOL_ButtonTextAlignmentSet Function C void GFX_GOL_ButtonTextAlignmentSet( GFX_GOL_BUTTON * pObject, GFX_ALIGNMENT align ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.3.7 GFX_GOL_ButtonTextSet Function C void GFX_GOL_ButtonTextSet( GFX_GOL_BUTTON * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-727 Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be used. Returns None. Example GFX_XCHAR Label0[] = “ON―; GFX_XCHAR Label1[] = “OFF―; GFX_GOL_BUTTON GFX_GOL_BUTTON[2]; GFX_GOL_ButtonTextSet(GFX_GOL_BUTTON[0], Label0); GFX_GOL_ButtonTextSet(GFX_GOL_BUTTON[1], Label1); 5.2.2.7.4 Check Box Object Functions 5.2.2.7.4.1 GFX_GOL_CheckBoxActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_CheckBoxActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_CHECKBOX_ACTION_CHECKED Touch Screen EVENT_RELEASE If events occurs and the x,y position falls in the area of the check box while the check box is unchecked. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object's ID and parameter 2 passed matches SCAN_CR_PRESSED or SCAN_SPACE_PRESSED while the check box is unchecked. GFX_GOL_CHECKBOX_ACTION_UNCHECKED Touch Screen EVENT_RELEASE If events occurs and the x,y position falls in the area of the check box while the check box is checked. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object's ID and parameter 2 passed matches SCAN_CR_PRESSED or SCAN_SPACE_PRESSED while the check box is checked. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-728 Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_CHECKBOX_ACTION_CHECKED - Check box is checked • GFX_GOL_CHECKBOX_ACTION_UNCHECKED - Check box is unchecked • GFX_GOL_OBJECT_ACTION_INVALID - Object is not affected Example None. 5.2.2.7.4.2 GFX_GOL_CheckBoxActionSet Function C void GFX_GOL_CheckBoxActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_CHECKBOX_ACTION_CHECKED Touch Screen, Set GFX_GOL_CHECKBOX_CHECKED_STATE Check Box will be redrawn in checked state. Keyboard GFX_GOL_CHECKBOX_ACTION_UNCHECKED Touch Screen, Clear GFX_GOL_CHECKBOX_CHECKED_STATE Check Box will be redrawn in un-checked state. Keyboard Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-729 Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.4.3 GFX_GOL_CheckBoxCreate Function C GFX_GOL_CHECKBOX * GFX_GOL_CheckBoxCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_CHECKBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_CheckBoxCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pText Pointer to the text of the object. alignment text alignment of the text used in the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-730 pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_CHECKBOX *pCb[2]; pCb[0] = GFX_GOL_CheckBoxCreate( ID_CHECKBOX1, // ID 20,135,150,175, // dimension GFX_GOL_CHECKBOX_DRAW_STATE, // Draw the object "Scale", // text GFX_ALIGN_CENTER, // text alignment pScheme); // use this scheme pCb[1] = GFX_GOL_CheckBoxCreate( ID_CHECKBOX2, // ID 170,135,300,175, // dimension GFX_GOL_CHECKBOX_DRAW_STATE, // Draw the object "Animate", // text GFX_ALIGN_LEFT | GFX_ALIGN_VCENTER, // text alignment pScheme); // use this scheme 5.2.2.7.4.4 GFX_GOL_CheckBoxDraw Function C GFX_STATUS GFX_GOL_CheckBoxDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the GFX_GOL_CHECKBOX is drawn with the text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-731 5.2.2.7.4.5 GFX_GOL_CheckBoxTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_CheckBoxTextAlignmentGet( GFX_GOL_CHECKBOX * pObject ); Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.4.6 GFX_GOL_CheckBoxTextAlignmentSet Function C void GFX_GOL_CheckBoxTextAlignmentSet( GFX_GOL_CHECKBOX * pObject, GFX_ALIGNMENT align ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.4.7 GFX_GOL_CheckBoxTextSet Function C void GFX_GOL_CheckBoxTextSet( 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-732 GFX_GOL_CHECKBOX * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be used. Returns None. Example GFX_XCHAR Label0[] = “Enabled―; GFX_XCHAR Label1[] = “Disabled―; GFX_GOL_CHECKBOX GFX_GOL_CHECKBOX[2]; GFX_GOL_CheckBoxTextSet(GFX_GOL_CHECKBOX[0], Label0); GFX_GOL_CheckBoxTextSet(GFX_GOL_CHECKBOX[1], Label1); 5.2.2.7.5 Chart Object Functions 5.2.2.7.5.1 GFX_GOL_ChartActionGet Function C uint16_t GFX_GOL_ChartActionGet( void * pObj, GFX_GOL_MESSAGE * pMsg ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen and keyboard inputs. Translated Message Input Source Events Description CH_MSG_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE, EVENT_MOVE If events occurs and the x,y position falls in the area of the chart. OBJ_MSG_INVALID Any Any If the message did not affect the object. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-733 Parameters Parameters Description pCh The pointer to the object where the message will be evaluated to check if the message will affect the object. pMsg Pointer to the message struct containing the message from the user interface. Returns Returns the translated message depending on the received GOL message: • CH_MSG_SELECTED – Chart area is selected • OBJ_MSG_INVALID – Chart is not affected none. Side Effects none 5.2.2.7.5.2 GFX_GOL_ChartCreate Function C GFX_GOL_CHART * GFX_GOL_ChartCreate( uint16_t ID, short left, short top, short right, short bottom, uint16_t state, DATASERIES * pData, CHARTPARAM * pParam, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a CHART object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. Preconditions none Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pData Pointer to the data for the contents of the chart. NULL can be assigned initially when creating the object. pParam Pointer to the chart parameters. NULL can be assigned initially when creating the object and the chart parameters can be populated using the API provided. pScheme Pointer to the style scheme used. When set to NULL, the default style scheme will be used. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-734 Returns Returns the pointer to the object created. Side Effects none Example extern const FONT_FLASH GOLSmallFont; extern const FONT_FLASH GOLMediumFont; // Note that strings are declared as such to cover cases // where XCHAR type is declared as short (2 bytes). XCHAR ChTitle[] = {'E','x','a','m','p','l','e',0}; XCHAR SampleName[] = {'C','a','t','e','g','o','r','y',0}; XCHAR ValueName[] = {'#','H','i','t','s',0}; XCHAR SeriesName[2] = { {'V','1',0}, {'V','2',0}, }; V1Data[2] = { 50, 100}; V2Data[2] = { 5, 10}; GFX_OBJ_SCHEME *pScheme; CHART *pChart; CHARTPARAM Contents; uint16_t state; pScheme = GFX_OBJ_SchemeCreate(); state = CH_BAR|CH_DRAW|CH_BAR_HOR; // GFX_PRIM_BarDraw Chart to be drawn with horizontal orientation pChart = ChCreate(0x01, // ID 0, 0, // dimensions GFX_PRIM_GetMaxX(), GFX_PRIM_GetMaxY(), state, // state of the chart NULL, // data not initialized yet NULL, // no parameters yet pScheme); // style scheme used if (pMyChart == NULL) // check if chart was allocated memory return 0; ChSetTitleFont(pChart, (void*)&GOLMediumFont); ChSetTitle(pChart, ChTitle); // set the title // set the grid labels and axis labels font ChSetGridLabelFont(pChart, (void*)&GOLSmallFont); ChSetAxisLabelFont(pChart, (void*)&GOLSmallFont); // set the labels for the X and Y axis ChSetSampleLabel(pChart, (XCHAR*)SampleName); ChSetValueLabel(pChart, (XCHAR*)ValueName); ChAddDataSeries(pChart, 2, V1Data, (XCHAR*)SeriesName[0]); ChAddDataSeries(pChart, 2, V2Data, (XCHAR*)SeriesName[1]); // set the range of the sample values ChSetValueRange(pChart, 0, 100); // show all two samples to be displayed (start = 1, end = 2) ChSetSampleRange(pChart, 1, 2); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-735 GFX_OBJ_Draw(); // draw the chart 5.2.2.7.5.3 GFX_GOL_ChartDataSeriesAdd Function C DATASERIES * GFX_GOL_ChartDataSeriesAdd( GFX_GOL_CHART * pCh, uint16_t nSamples, uint16_t * pData, XCHAR * pName ); Description This function creates a DATASERIES object and populates the structure with the given parameters. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. nSamples The number of samples or data points. pData Pointer to the array of samples or data points. pName Pointer to the string used to label the data series. Returns Returns the pointer to the data variable (DATASERIES) object created. If NULL is returned, the addition of the new object failed due to not enough memory for the object. Side Effects Appends to the list of DATASERIES that the chart is operating on. By default, the show flag of the newly added data series is set to SHOW_DATA or enabled. Example See ChCreate() example. 5.2.2.7.5.4 GFX_GOL_ChartDataSeriesFree Function C void GFX_GOL_ChartDataSeriesFree( void * pObj ); Description This function removes DATASERIES object from the list of DATASERIES objects and frees the memory used of that removed object. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-736 Returns none. Side Effects none. Example void ClearChartData(CHART *pCh) { if(pCh->pChData != NULL) // remove the all data series ChFreeDataSeries(pCh; } 5.2.2.7.5.5 GFX_GOL_ChartDataSeriesRemove Function C void GFX_GOL_ChartDataSeriesRemove( GFX_GOL_CHART * pCh, uint16_t number ); Description This function removes DATASERIES object from the list of DATASERIES objects and frees the memory used of that removed object. The position of the object to be removed is specified by the number parameter. If the list has only one member, it removes the member regardless of the number given. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. number The position of the object to be removed in the list where the first object in the list is assigned a value of 1. If this parameter is set to zero, the whole list of DATA_SERIES is removed. Returns none. Side Effects none. Example void ClearChartData(CHART *pCh) { if(pCh->pChData != NULL) // remove the all data series ChRemoveDataSeries(pCh, 0); } 5.2.2.7.5.6 GFX_GOL_ChartDataSeriesSet Function C short GFX_GOL_ChartDataSeriesSet( GFX_GOL_CHART * pCh, uint16_t seriesNum, BYTE status ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-737 Description This is function GFX_GOL_ChartDataSeriesSet. 5.2.2.7.5.7 GFX_GOL_ChartDraw Function C uint16_t GFX_GOL_ChartDraw( void * pObj ); Description This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The colors of the bars of the bar chart or sectors of the pie chart can be the default color table or user defined color table set by ChSetColorTable() function. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Preconditions Object must be created before this function is called. Parameters Parameters Description pCh Pointer to the object to be rendered. Returns Returns the status of the drawing • 1 - If the rendering was completed and • 0 - If the rendering is not yet finished. Next call to the function will resume the rendering on the pending drawing state. Side Effects none. 5.2.2.7.5.8 GFX_GOL_ChartPercentRangeSet Function C void GFX_GOL_ChartPercentRangeSet( GFX_GOL_CHART * pCh, uint16_t min, uint16_t max ); Description This function sets the minimum and maximum range of percentage that the bar chart will show. The criteria is that min <= max. This affects bar charts only and CH_PERCENTAGE bit state is set. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-738 Parameters Parameters Description pCh Pointer to the chart object. min Minimum percentage value that will be displayed in the bar chart. max Maximum percentage value that will be displayed in the bar chart. Returns none. Side Effects none. 5.2.2.7.5.9 GFX_GOL_ChartSampleRangeSet Function C void GFX_GOL_ChartSampleRangeSet( GFX_GOL_CHART * pCh, uint16_t start, uint16_t end ); Description This function sets the sample start and sample end when drawing the chart. Together with the data series' SHOW_DATA flags the different way of displaying the chart data is achieved. Start & End Value The # of Data Series Flag Set Chart Description Start <= End 1 Show the data indicated by Start and End points of the DATASERIES with the flag set Start = End 1 Show the data indicated by Start or End points of the DATASERIES with the flag set Start, End = don't care > 1 Show the data indicated by Start point of the DATASERIES with the flag set. Each samples of all checked data series are grouped together according to sample number. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. start Start point of the data samples to be displayed. end End point of the data samples to be displayed. Returns none. Side Effects none. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-739 Example See ChCreate() example. 5.2.2.7.5.10 GFX_GOL_ChartValueRangeSet Function C void GFX_GOL_ChartValueRangeSet( GFX_GOL_CHART * pCh, uint16_t min, uint16_t max ); Description This function sets the minimum and maximum range of values that the bar chart will show. The criteria is that min <= max. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. min Minimum value that will be displayed in the bar chart. max Maximum value that will be displayed in the bar chart. Returns none. Side Effects none. 5.2.2.7.6 Custom Control Object Functions 5.2.2.7.6.1 GFX_GOL_CustomControlActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_CustomControlActionGet( void * pObj, GFX_GOL_MESSAGE * pMsg ); Description translates the GOL message for the custom control Preconditions none Parameters Parameters Description pMsg pointer to the GOL message pCc the pointer to the custom control 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-740 Returns translated message for the custom control Side Effects none Remarks none 5.2.2.7.6.2 GFX_GOL_CustomControlActionSet Function C void GFX_GOL_CustomControlActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObj, GFX_GOL_MESSAGE * pMsg ); Description changes the state of the object Preconditions none Parameters Parameters Description pMsg pointer to the GOL message pCc the pointer to the custom control Returns none Side Effects none Remarks none 5.2.2.7.6.3 GFX_GOL_CustomControlCreate Function C GFX_GOL_CUSTOMCONTROL * GFX_GOL_CustomControlCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_GOL_OBJ_SCHEME * pScheme ); Description creates the custom control 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-741 Preconditions none Parameters Parameters Description ID instance unique ID left, top, right, bottom dimensions of the object state state of the object pScheme pointer to the style scheme Returns returns the pointer to the object created Side Effects none Remarks none 5.2.2.7.6.4 GFX_GOL_CustomControlDraw Function C GFX_STATUS GFX_GOL_CustomControlDraw( void * pObj ); Description draws custom control Preconditions none Parameters Parameters Description pCc pointer to the custom control Returns returns the status of the drawing 0 - not completed 1 - done Side Effects none Remarks none 5.2.2.7.7 Digital Meter Object Functions 5.2.2.7.7.1 GFX_GOL_DigitalMeterActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_DigitalMeterActionGet( 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-742 void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_DIGITALMETER_ACTION_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE If events occurs and the x,y position falls in the area of the Digital Meter. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_DIGITALMETER_ACTION_SELECTED ? Object is selected. • GFX_GOL_OBJECT_ACTION_INVALID ? Object is not affected Example None. 5.2.2.7.7.2 GFX_GOL_DigitalMeterCreate Function C GFX_GOL_DIGITALMETER * GFX_GOL_DigitalMeterCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, uint32_t value, uint8_t NoOfDigits, uint8_t DotPos, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_DIGITALMETER object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-743 Preconditions None. Parameters Parameters Description instance Device instance ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. value Sets the initial value to be displayed NoOfDigits Sets the number of digits to be displayed DotPos Sets the position of decimal point in the display alignment text alignment of the text used in the object. pScheme Pointer to the style scheme. Set to NULL if default style scheme is used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_DIGITALMETER *pDm; pScheme = GFX_GOL_SchemeCreate(); state = GFX_GOL_DIGITALMETER_DRAW_STATE | GFX_GOL_DIGITALMETER_FRAME_STATE; GFX_GOL_DigitalMeterCreate( ID_DIGITALMETER1, // ID 30,80,235,160, // dimension state, // has frame and center aligned 789,4,1, // to display 078.9 GFX_ALIGN_CENTER, pScheme); // use given scheme // draw the objects while(GFX_GOL_ObjectListDraw() != GFX_STATUS_SUCCESS); 5.2.2.7.7.3 GFX_GOL_DigitalMeterDecrement Function C void GFX_GOL_DigitalMeterDecrement( GFX_GOL_DIGITALMETER * pObject, uint16_t delta ); Description This function decrements the meter value by the given delta value set. If the delta given is less than the minimum value of the meter, the value will remain to be at minimum. Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-744 Parameters Parameters Description pObject pointer to the object. Returns None. Example See GFX_GOL_DigitalMeterIncrement(). 5.2.2.7.7.4 GFX_GOL_DigitalMeterDraw Function C GFX_STATUS GFX_GOL_DigitalMeterDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.7.5 GFX_GOL_DigitalMeterIncrement Function C void GFX_GOL_DigitalMeterIncrement( GFX_GOL_DIGITALMETER * pObject, uint16_t delta ); Description This function increments the scroll bar position by the given delta value set. If the delta given exceeds the maximum value of the meter, the value will remain to be at maximum. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-745 Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example void ControlSpeed( GFX_GOL_DIGITALMETER* pObj, int setSpeed, int curSpeed) { // set page size to 1 GFX_GOL_DigitalMeterValueSet(pObj, 1); if (setSpeed < curSpeed) { while(GFX_GOL_DigitalMeterValueGet(pObj) < SetSpeed) { // increment by 1 GFX_GOL_DigitalMeterIncrement(pObj, 1); } } else if (setSpeed > curSpeed) { while(GFX_GOL_DigitalMeterValueGet(pObj) > SetSpeed) { // decrement by 1 GFX_GOL_DigitalMeterDecrement(pObj, 1); } } } 5.2.2.7.7.6 GFX_GOL_DigitalMeterValueSet Function C void GFX_GOL_DigitalMeterValueSet( GFX_GOL_DIGITALMETER * pObject, int16_t value ); Description This function sets the value of the meter. The value used should be within the range set for the object. The new value is checked to be in the minimum and maximum value range. If the value set is less than the minimum value, the value that will be set is the minimum value. If the value set is more than the maximum value, then the value that will be set is the maximum value. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. value the new value of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-746 Returns None. Example GFX_GOL_DIGITALMETER *pMeter; uint16_t ctr = 0; // create slider here and initialize parameters GFX_GOL_ObjectStateSet(pMeter, GFX_GOL_DIGITALMETER_DRAW_STATE); GFX_GOL_ObjectListDraw(); while("some condition") { GFX_GOL_DigitalMeterValueSet(pMeter, ctr); GFX_GOL_ObjectStateSet( pMeter, GFX_GOL_DIGITALMETER_UPDATE_STATE); // redraw the scroll bar GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } 5.2.2.7.8 Edit Box Object Functions 5.2.2.7.8.1 GFX_GOL_EditBoxActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_EditBoxActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_EDITBOX_ACTION_ADD_CHAR Keyboard EVENT_CHARCODE New character should be added. GFX_GOL_EDITBOX_ACTION_DEL_CHAR Keyboard EVENT_KEYPRESS Last character should be removed. GFX_GOL_EDITBOX_ACTION_TOUCHSCREEN Touch Screen GFX_GOL_EDITBOX_FOCUSED_STATE Focus will be drawn, caret displayed when enabled. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-747 Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_EDITBOX_ACTION_ADD_CHAR - New character should be added • GFX_GOL_EDITBOX_ACTION_DEL_CHAR - Last character should be removed. • GFX_GOL_EDITBOX_ACTION_TOUCHSCREEN - focus will be drawn when enabled. Careet will be drawn when enabled. • GFX_GOL_OBJECT_ACTION_INVALID - Object is not affected Example None. 5.2.2.7.8.2 GFX_GOL_EditBoxActionSet Function C void GFX_GOL_EditBoxActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_EDITBOX_ACTION_ADD_CHAR Keyboard Set GFX_GOL_EDITBOX_DRAW_STATE New character is added and Edit Box will be redrawn. GFX_GOL_EDITBOX_ACTION_DEL_CHAR KeyBoard Set GFX_GOL_EDITBOX_DRAW_STATE Last character is removed and Edit Box will be redrawn. GFX_GOL_EDITBOX_ACTION_TOUCHSCREEN Touch Screen Set GFX_GOL_EDITBOX_FOCUSED_STATE When enabled, focus will be redrawn, caret will also be redrawn if enabled. Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-748 Example None. 5.2.2.7.8.3 GFX_GOL_EditBoxCharAdd Function C GFX_STATUS GFX_GOL_EditBoxCharAdd( GFX_GOL_EDITBOX * pObject, GFX_XCHAR ch ); Description This function adds a character at the end of the text used by the object. When the object contains the maximum number of characters any addition call to this function will not affect the text in the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. ch The character to be added. Returns The status of the addition. • GFX_STATUS_SUCCESS - when the addition was successful. • GFX_STATUS_FAILURE - when the addition was not successful. Example None. 5.2.2.7.8.4 GFX_GOL_EditBoxCharRemove Function C GFX_STATUS GFX_GOL_EditBoxCharRemove( GFX_GOL_EDITBOX * pObject ); Description This function removes a character at the end of the text used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns The status of the addition. • GFX_STATUS_SUCCESS - when the removal was successful. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-749 • GFX_STATUS_FAILURE - when the removal has no effect and the buffer is empty. Example None. 5.2.2.7.8.5 GFX_GOL_EditBoxCreate Function C GFX_GOL_EDITBOX * GFX_GOL_EditBoxCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, uint16_t charMax, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_EDITBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_ListBoxCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pText Pointer to the text of the object. charMax Defines the maximum number of characters in the edit box. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example // assume pScheme to be initialized with the style scheme 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-750 #define MAX_CHAR_COUNT 15 GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_EDITBOX *pEb; GFX_GOL_EDITBOX_STATE state; GFX_XCHAR TextBuffer[MAX_CHAR_COUNT + 1]; // assume pScheme is initialized to a scheme in memory. state = GFX_GOL_EDITBOX_DRAW_STATE; pEb = GFX_GOL_EditBoxCreate( 1, 20, 64, 50, 118, state, TextBuffer, MAX_CHAR_COUNT GFX_ALIGN_CENTER, pScheme); // check if object is not created if (pEb == NULL) return 0; 5.2.2.7.8.6 GFX_GOL_EditBoxDraw Function C GFX_STATUS GFX_GOL_EditBoxDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.8.7 GFX_GOL_EditBoxTextSet Function C void GFX_GOL_EditBoxTextSet( GFX_GOL_EDITBOX * pObject, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-751 GFX_XCHAR* pText ); Description This function sets the text in the object. This function copies the text located in the address pointed to by pText to the object text buffer. The string length must be less than or equal to the maximum characters allowed in the object. The object will truncate the string once it reaches the maximum length. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be copied. Returns None. Example #define MAX_EDITBOX_CHAR_LENGTH 20 GFX_XCHAR Label0[] = “This is really a long string―; // assume pEb is a pointer initialized to an edit box that // as a buffer with 20 characters allowed. GFX_GOL_EditBoxTextSet(pEb, Label0); // at this point the edit box contains // This is really a lon" - truncated to only 20 characters. 5.2.2.7.9 Grid Object Functions 5.2.2.7.9.1 GridClearCellState Function C void GridClearCellState( GRID * pGrid, short column, short row, uint16_t state ); Description This function clears the state of the cell (or Grid Item) specified by the column and row. Preconditions none Parameters Parameters Description pGrid Pointer to the object. column column index of the cell row row index of the cell 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-752 atate specifies the state to be cleared. See Grid Item State. Returns none. Side Effects none 5.2.2.7.9.2 GridCreate Function C GRID * GridCreate( uint16_t ID, short left, short top, short right, short bottom, uint16_t state, short numColumns, short numRows, short cellWidth, short cellHeight, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GRID object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. Preconditions none Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the Object. top Top most position of the Object. right Right most position of the Object. bottom Bottom most position of the object. state Sets the initial state of the object. numColumns Sets the number of columns for the grid. numRows Sets the number of rows for the grid. cellWidth Sets the width of each cell of the grid. cellHeight Sets the height of each cell of the grid. pScheme Pointer to the style scheme used for the object. Set to NULL if default style scheme is used. Returns Returns the pointer to the object created. Side Effects none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-753 5.2.2.7.9.3 GridDraw Function C uint16_t GridDraw( void * pObj ); Description This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Preconditions Object must be created before this function is called. Parameters Parameters Description pGb Pointer to the object to be rendered. Returns Returns the status of the drawing • 1 - If the rendering was completed and • 0 - If the rendering is not yet finished. Next call to the function will resume the rendering on the pending drawing state. Side Effects none 5.2.2.7.9.4 GridFreeItems Function C void GridFreeItems( void * pObj ); Description This function removes all grid items for the given Grid and frees the memory used. Preconditions Object must be created before this function is called. Parameters Parameters Description pGrid The pointer to the Grid object. Returns none. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-754 Side Effects none 5.2.2.7.9.5 GridGetCell Function C void * GridGetCell( GRID * pGrid, short column, short row, uint16_t * cellType ); Description This function removes all grid items for the given Grid and frees the memory used. Preconditions Object must be created before this function is called. Parameters Parameters Description pGrid The pointer to the Grid object. column the column index of the cell row the row index of the cell cellType pointer that will receive the type of grid item or cell (GRIDITEM_IS_TEXT or GRIDITEM_IS_BITMAP). Returns Returns a pointer to the grid item or cell data. Side Effects none 5.2.2.7.9.6 GridMsgDefault Function C void GridMsgDefault( uint16_t translatedMsg, void * pObj, GFX_GOL_MESSAGE * pMsg ); Description This function performs the actual state change based on the translated message given. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GRID_MSG_TOUCHED Touch Screen none Grid will have no state change because of this event. GRID_MSG_ITEM_SELECTED Keyboard Set GRIDITEM_SELECTED, Grid Item selected will be redrawn. GRID_DRAW_ITEMS 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-755 GRID_MSG_UP Keyboard Set GRIDITEM_DRAW, Grid Item above the currently focused item will be redrawn. GRID_DRAW_ITEMS GRID_MSG_DOWN Keyboard Set GRIDITEM_DRAW, Grid Item below the currently focused item will be redrawn. GRID_DRAW_ITEMS GRID_MSG_LEFT Keyboard Set GRIDITEM_DRAW, Grid Item to the left of the currently focused item will be redrawn. GRID_DRAW_ITEMS GRID_MSG_RIGHT Keyboard Set GRIDITEM_DRAW, Grid Item to the right of the currently focused item will be redrawn. GRID_DRAW_ITEMS Preconditions none Parameters Parameters Description translatedMsg The translated message. pGrid The pointer to the object whose state will be modified. pMsg The pointer to the GOL message. Returns none Side Effects none 5.2.2.7.9.7 GridSetCell Function C uint16_t GridSetCell( GRID * pGrid, short column, short row, uint16_t state, void * data ); Description This function sets the Grid Item state and data. Preconditions Object must be created before this function is called. Parameters Parameters Description pGrid The pointer to the Grid object. column the column index of the cell row the row index of the cell 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-756 state sets the state of the Grid Item specified. data pointer to the data used for the Grid Item. Returns Returns the status of the operation • GRID_SUCCESS - if the set succeeded • GRID_OUT_OF_BOUNDS - if the row and column given results in an out of bounds location. Side Effects none 5.2.2.7.9.8 GridSetCellState Function C void GridSetCellState( GRID * pGrid, short column, short row, uint16_t state ); Description This function sets the state of the Grid Item or cell. Preconditions Object must be created before this function is called. Parameters Parameters Description pGrid The pointer to the Grid object. column the column index of the cell row the row index of the cell state sets the state of the Grid Item specified. Returns none. Side Effects none 5.2.2.7.9.9 GridSetFocus Function C void GridSetFocus( GRID * pGrid, short column, short row ); Description This function sets the focus of the specified Grid Item or cell. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-757 Preconditions Object must be created before this function is called. Parameters Parameters Description pGrid The pointer to the Grid object. column the column index of the cell row the row index of the cell Returns none. Side Effects none 5.2.2.7.9.10 GridTranslateMsg Function C uint16_t GridTranslateMsg( void * pObj, GFX_GOL_MESSAGE * pMsg ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GRID_MSG_TOUCHED Touch Screen none If any touch events occurs and the x,y position falls in the face of the grid. GRID_MSG_ITEM_SELECTED Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_SPACE_PRESSED or SCAN_CR_PRESSED. GRID_MSG_UP Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_UP_PRESSED. GRID_MSG_DOWN Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_DOWN_PRESSED. GRID_MSG_LEFT Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_LEFT_PRESSED. GRID_MSG_RIGHT Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object’s ID and parameter 2 passed matches SCAN_RIGHT_PRESSED. OBJ_MSG_INVALID Any Any If the message did not affect the object. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-758 Parameters Parameters Description pGrid The pointer to the object where the message will be evaluated to check if the message will affect the object. pMsg Pointer to the message struct containing the message from the user interface. Returns Returns the translated message depending on the received GOL message: • GRID_MSG_TOUCHED - when the grid object is touched. • GRID_MSG_ITEM_SELECTED – when key scan SCAN_SPACE_PRESSED or SCAN_CR_PRESSED are detected. • GRID_MSG_UP – when key scan SCAN_UP_PRESSED is detected. • GRID_MSG_DOWN – when key scan SCAN_DOWN_PRESSED is detected. • GRID_MSG_LEFT – when key scan SCAN_LEFT_PRESSED is detected. • GRID_MSG_RIGHT – when key scan SCAN_RIGHT_PRESSED is detected. • OBJ_MSG_INVALID – Button is not affected Side Effects none 5.2.2.7.10 Group Box Object Functions 5.2.2.7.10.1 GFX_GOL_GroupboxActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_GroupboxActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Events Description GFX_GOL_GROUPBOX_ACTION_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE If events occurs and the x,y position falls in the area of the group box. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-759 pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_GROUPBOX_ACTION_SELECTED // Groupbox area selected action ID. Example None. 5.2.2.7.10.2 GFX_GOL_GroupboxCreate Function C GFX_GOL_GROUPBOX * GFX_GOL_GroupboxCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_GROUPBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pImage Pointer to the image used on the face of the object. pText Pointer to the text of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_GROUPBOX *pGroupbox; GFX_GOL_GROUPBOX_STATE state; // assume pScheme is initialized to a scheme in memory. state = GFX_GOL_GROUPBOX_DRAW_STATE; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-760 pGroupbox = GFX_GOL_GroupboxCreate(1, // ID 0,0,GFX_Primitive_MaxXGet(),GFX_Primitive_MaxYGet(), // whole screen dimension state, // set state to draw all (char*)myIcon, // icon "Place Title Here.", // text NULL); // use default GOL scheme if (pWindow == NULL) return 0; return 1; 5.2.2.7.10.3 GFX_GOL_GroupboxDraw Function C GFX_STATUS GFX_GOL_GroupboxDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the face of the GFX_GOL_GROUPBOX is drawn on top of the bitmap. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.10.4 GFX_GOL_GroupboxTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_GroupboxTextAlignmentGet( GFX_GOL_GROUPBOX * pObject ); Description This function returns the text alignment of the text string used by the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-761 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.10.5 GFX_GOL_GroupboxTextAlignmentSet Function C void GFX_GOL_GroupboxTextAlignmentSet( GFX_GOL_GROUPBOX * pObject, GFX_ALIGNMENT align ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.10.6 GFX_GOL_GroupboxTextSet Function C void GFX_GOL_GroupboxTextSet( GFX_GOL_GROUPBOX * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-762 Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be used. Returns None. Example GFX_XCHAR Label0[] = ?Group One?; GFX_XCHAR Label1[] = ?Group Two?; GFX_GOL_GROUPBOX pGroupbox; GFX_GOL_GroupboxTextSet(pGroupbox, Label0); GFX_GOL_GroupboxTextSet(pGroupbox, Label1); 5.2.2.7.11 List Box Object Functions 5.2.2.7.11.1 GFX_GOL_ListBoxActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_ListBoxActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_LISTBOX_ACTION_TOUCHSCREEN Touch Screen Any Item is selected using touch screen. GFX_GOL_LISTBOX_ACTION_MOVE Keyboard EVENT_KEYSCAN Focus is moved to the next item depending on the key pressed (UP or DOWN key). GFX_GOL_LISTBOX_ACTION_SELECTED Keyboard EVENT_KEYSCAN Selection status (GFX_GOL_LISTBOX_ITEM_STATUS_SE LECTED) is set to the currently focused item. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-763 Returns • GFX_GOL_LISTBOX_ACTION_TOUCHSCREEN – Item is selected using touch screen • GFX_GOL_LISTBOX_ACTION_MOVE – Focus is moved to the next item depending on the key pressed (UP or DOWN key). • GFX_GOL_LISTBOX_ACTION_SELECTED – Selection is set to the currently focused item • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.11.2 GFX_GOL_ListBoxActionSet Function C void GFX_GOL_ListBoxActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_LISTBOX_ACTION_TOUCHSCREEN Touch Screen Set GFX_GOL_LISTBOX_FOCUSED_STATE, If focus is enabled, the focus state bit GFX_GOL_LISTBOX_FOCUSED_STATE will be set. Set GFX_GOL_LISTBOX_DRAW_FOCUS_STATE GFX_GOL_LISTBOX_DRAW_FOCUS_STATE draw state bit will force the List Box to be redrawn with focus. Set GFX_GOL_LISTBOX_DRAW_ITEMS_STATE List Box will be redrawn with selected item(s). GFX_GOL_LISTBOX_ACTION_MOVE KeyBoard Set GFX_GOL_LISTBOX_DRAW_ITEMS_STATE List Box will be redrawn with focus on one item. GFX_GOL_LISTBOX_ACTION_SELECTED KeyBoard Set GFX_GOL_LISTBOX_DRAW_ITEMS_STATE List Box will be redrawn with selection on the current item focused. Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-764 Example None. 5.2.2.7.11.3 GFX_GOL_ListBoxCreate Function C GFX_GOL_LISTBOX * GFX_GOL_ListBoxCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_LISTBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_ListBoxCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pText Pointer to the text of the object. This is used for the items of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example #define LISTBOX_ID 10 const XCHAR ItemList[] = "Line1n" "Line2n"; GFX_GOL_OBJ_SCHEME *pScheme; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-765 GFX_GOL_LISTBOX *pLb; GFX_XCHAR *pTemp; uint16_t state, counter; //assume scheme is a valid style scheme in memory pScheme = &scheme; state = GFX_GOL_LISTBOX_DRAW_STATE; // create an empty listbox with default style scheme pLb = GFX_GOL_ListBoxCreate( LISTBOX_ID, // ID number 10,10,150,200, // dimension state, // initial state NULL, // set items to be empty GFX_ALIGN_CENTER, NULL); // use default style scheme // check if Listbox was created if (pLb == NULL) return 0; // create the list of items to be placed in the listbox // Add items (each line will become one item, // lines must be separated by 'n' character) pTemp = ItemList; counter = 0; while(*pTemp) { // since each item is appended NULL is assigned to // GFX_GOL_LISTITEM pointer. if(NULL == GFX_GOL_ListBoxItemAdd( pLb, NULL, pTemp, NULL, 0, counter)) { break; } while(*pTemp++ > (unsigned GFX_XCHAR)31); if(*(pTemp-1) == 0) break; counter++; } 5.2.2.7.11.4 GFX_GOL_ListBoxDraw Function C GFX_STATUS GFX_GOL_ListBoxDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-766 Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.11.5 GFX_GOL_ListBoxItemAdd Function C GFX_GOL_LISTITEM * GFX_GOL_ListBoxItemAdd( GFX_GOL_LISTBOX * pObject, GFX_GOL_LISTITEM * pPrevItem, GFX_XCHAR * pText, GFX_RESOURCE_HDR * pImage, uint16_t status, uint16_t data ); Description This function adds an item to the list box. This function allocates the memory needed for the GFX_GOL_LISTITEM and adds it to the list box. The newly created GFX_GOL_LISTITEM will store the location of pText, pImage and other parameters describing the added item. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. pPrevItem Pointer to the item after which a new item must be inserted, if this pointer is NULL, the item will be appended at the end of the items list. pText Pointer to the text that will be inserted. Text must persist in memory for as long as it is referenced by an item in the list box. pImage Pointer to the image for the item. Image must persist in memory for as long as it is referenced by the an item in the list box. status This parameter specifies if the item being added will be selected or redrawn (LB_STS_SELECTED or LB_STS_REDRAW). Refer to LISTITEM structure for details. data User assigned data associated with the item. Returns The pointer to the created item. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-767 Example const GFX_XCHAR ItemList[] = "Line1n" "Line2n" "Line3n"; extern GFX_RESOURCE_HDR myIcon; GFX_GOL_LISTBOX *pLb; GFX_GOL_LISTITEM *pItem, *pItemList; GFX_XCHAR *pTemp; // Assume that pLb is pointing to an existing list box in memory // that is empty (no list). // Create the list of the list box // Initialize this to NULL to indicate that items will be added // at the end of the list if the list exist on the list box or // start a new list if the list box is empty. pItem = NULL; pTemp = ItemList; pItem = GFX_GOL_ListBoxItemAdd( pLb, pItem, pTemp, NULL, LB_STS_SELECTED, 1); if(pItem == NULL) return 0; GFX_GOL_ListBoxImageSet(pItem, &myIcon); // Adjust pTemp to point to the next line while((uint16_t)*pTemp++ > (uint16_t)31); // add the next item pItem = GFX_GOL_ListBoxItemAdd( pLb, pItem, pTemp, NULL, 0, 2) if(pItem == NULL) return 0; GFX_GOL_ListBoxImageSet(pItem, &myIcon); // Adjust pTemp to point to the next line while((uint16_t)*pTemp++ > (uint16_t)31); // this time insert the next item after the first item on the list pItem = LbGetItemList(pLb); pItem = GFX_GOL_ListBoxItemAdd( pLb, pItem, pTemp, NULL, 0, 3) if(pItem == NULL) return 0; GFX_GOL_ListBoxImageSet(pItem, &myIcon); 5.2.2.7.11.6 GFX_GOL_ListBoxItemFocusGet Function C int16_t GFX_GOL_ListBoxItemFocusGet( 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-768 GFX_GOL_LISTBOX * pObject ); Description This function returns the index of the focused item in the list box. First item on the list is always indexed 0. If none of the items in the list is focused, -1 is returned. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. Returns The index of the focused item in the list box. Example None. 5.2.2.7.11.7 GFX_GOL_ListBoxItemFocusSet Function C void GFX_GOL_ListBoxItemFocusSet( GFX_GOL_LISTBOX * pObject, uint16_t index ); Description This function sets the focus of the item with the index number specified by index. First item on the list is always indexed 0. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. index The index number of the item to be focused. Returns None. Example None. 5.2.2.7.11.8 GFX_GOL_ListBoxItemListRemove Function C void GFX_GOL_ListBoxItemListRemove( void * pObject ); Description This function removes the entire items list of the list box and free the memory used. The memory freed is the memory used for 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-769 the list box. The actual text or image used for the item are not removed from memory. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.11.9 GFX_GOL_ListBoxItemRemove Function C void GFX_GOL_ListBoxItemRemove( GFX_GOL_LISTBOX * pObject, GFX_GOL_LISTITEM * pItem ); Description This function removes an item from the list box and free the memory used. The memory freed is the memory used for the list box. The actual text or image used for the item are not removed from memory. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pItem pointer to the list box item that will be removed. Returns None. Example None. 5.2.2.7.11.10 GFX_GOL_ListBoxSelectionChange Function C void GFX_GOL_ListBoxSelectionChange( GFX_GOL_LISTBOX * pObject, GFX_GOL_LISTITEM * pItem ); Description This function changes the selection status of the given item in the list box. There are two cases that this function checks Case 1: The list box is set to multiple selection. • The item pointed to by pItem will toggle the selection status. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-770 Case 2: The list box is set to single selection. • If the currently selected item is not the item pointed to by pItem, the currently selected item will toggle to not selected. The item pointed to by pItem will then be set to selected. • If the currently selected item is the same item pointed to by pItem, the selection status of that item will be set to not selected. The change in the item's selection status should be redrawn to reflect the changes. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. pItem The pointer to the item that will have the selection status changed. Returns None. Example None. 5.2.2.7.11.11 GFX_GOL_ListBoxSelectionGet Function C GFX_GOL_LISTITEM * GFX_GOL_ListBoxSelectionGet( GFX_GOL_LISTBOX * pObject, GFX_GOL_LISTITEM * pFromItem ); Description This function searches for selected items from the list box. A starting position can optionally be given. If starting position is set to NULL, search will begin from the first item on the item list. The function returns the pointer to the first selected item found or NULL if there are no items selected. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. pFromItem The starting point of the search. If this is set to NULL, the search will start at the beginning of the item list. Returns The pointer to the first selected item found. NULL if there are no items selected. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-771 5.2.2.7.11.12 GFX_GOL_ListBoxVisibleItemCountGet Function C uint16_t GFX_GOL_ListBoxVisibleItemCountGet( GFX_GOL_LISTBOX * pObject ); Description This function returns the count of items visible in the list box. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. Returns The number of visible items in the list box. Example None. 5.2.2.7.12 Meter Object Functions 5.2.2.7.12.1 GFX_GOL_MeterActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_MeterActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_METER_ACTION_SET System EVENT_SET If event set occurs and the meter id is sent in parameter 1. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-772 Returns • GFX_GOL_METER_ACTION_SET – Meter id is given in parameter 1 for a TYPE_SYSTEM message. • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.12.2 GFX_GOL_MeterActionSet Function C void GFX_GOL_MeterActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_METER_ACTION_SET System Set GFX_GOL_METER_DRAW_STATE Meter will be redrawn to update the needle position and value displayed. Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.12.3 GFX_GOL_MeterCreate Function C GFX_GOL_METER * GFX_GOL_MeterCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_GOL_METER_DRAW_TYPE type, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-773 int16_t value, int16_t minValue, int16_t maxValue, GFX_RESOURCE_HDR * pTitleFont, GFX_RESOURCE_HDR * pValueFont, GFX_XCHAR * pText, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_METER object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_MeterCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • type is not one of the defined types • pTitleFont and pValueFont is not defined to a valid font GFX_RESOURC_HDR • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. type Specifies the type of Meter to be drawn (see GFX_GOL_METER_TYPE). value Initial value set to the meter. minValue The minimum value the meter will display. maxValue The maximum value the meter will display. pTitleFont Pointer to the font used for the Title. pValueFont Pointer to the font used for the value. pText Pointer to the text label of the meter. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example #define ID_METER 101 extern const FONT_FLASH GOLMediumFont; // medium font extern const FONT_FLASH GOLSmallFont; // small font 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-774 GFX_GOL_OBJ_SCHEME *pMeterScheme; GFX_GOL_METER *pMtr; // assume pMeterScheme is initialized to a scheme in memory. // draw object after creation state = GFX_GOL_METER_DRAW_STATE | GFX_GOL_METER_RING_STATE; pMtr = GFX_GOL_MeterCreate( ID_METER, // assign ID 30, 50, 150, 180, // set dimension state, GFX_GOL_METER_WHOLE_TYPE, // type of meter 0, // set initial value 0, 100, // set min and max value &GOLMediumFont, // set title font &GOLSmallFont, // set value font "Speed", // Text Label pMeterScheme); // style scheme // check if meter was created if (pMtr == NULL) return 0; // Change range colors: Normal values to WHITE // Critical values to BLUE // Danger values to RED // assume that WHITE, GREEN, YELLOW and RED have been defined. GFX_GOL_MeterScaleColorSet(pMtr, WHITE, WHITE, WHITE, GREEN, YELLOW, RED); // use GOLDraw() to draw the meter created while(!GOLDraw()); 5.2.2.7.12.4 GFX_GOL_MeterDecrement Function C void GFX_GOL_MeterDecrement( GFX_GOL_METER * pObject, uint16_t delta ); Description This function decrements the meter value by the given delta value set. If the delta given is less than the minimum value of the meter, the value will remain to be at minimum. Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example See GFX_GOL_MeterIncrement(). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-775 5.2.2.7.12.5 GFX_GOL_MeterDraw Function C GFX_STATUS GFX_GOL_MeterDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.12.6 GFX_GOL_MeterIncrement Function C void GFX_GOL_MeterIncrement( GFX_GOL_METER * pObject, uint16_t delta ); Description This function increments the scroll bar position by the given delta value set. If the delta given exceeds the maximum value of the meter, the value will remain to be at maximum. Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-776 Example void ControlSpeed( GFX_GOL_METER* pObj, int setSpeed, int curSpeed) { // set page size to 1 GFX_GOL_MeterValueSet(pObj, 1); if (setSpeed < curSpeed) { while(GFX_GOL_MeterValueGet(pObj) < SetSpeed) GFX_GOL_MeterIncrement(pObj, 1); // increment by 1 } else if (setSpeed > curSpeed) { while(GFX_GOL_MeterValueGet(pObj) > SetSpeed) GFX_GOL_MeterDecrement(pObj, 1); // decrement by 1 } } 5.2.2.7.12.7 GFX_GOL_MeterRangeSet Function C void GFX_GOL_MeterRangeSet( GFX_GOL_METER * pObject, int16_t minValue, int16_t maxValue ); Description This function sets the range of the meter. When the range is modified, object must be completely redrawn to reflect the change. minValue should always be less than maxValue. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. minValue new minimum value of the object. maxValue new maximum value of the object. Returns None. Example None. 5.2.2.7.12.8 GFX_GOL_MeterScaleColorsSet Function C void GFX_GOL_MeterScaleColorsSet( GFX_GOL_METER * pObject, GFX_COLOR color1, GFX_COLOR color2, GFX_COLOR color3, GFX_COLOR color4, GFX_COLOR color5, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-777 GFX_COLOR color6 ); Description After the object is created, this function must be called to set the arc colors of the object. Scale colors can be used to highlight values of the meter. User can set these colors to define the arc colors and scale colors. This also sets the color of the meter value when displayed. The color settings are set to the following angles: Color Boundaries Type Whole Type Half Type Quarter Arc 6 225 to 180 not used not used Arc 5 179 to 135 179 to 135 not used Arc 4 134 to 90 134 to 90 not used Arc 3 89 to 45 89 to 45 89 to 45 Arc 2 44 to 0 44 to 0 44 to 0 Arc 1 -45 to -1 not used not used As the meter is drawn colors are changed depending on the angle of the scale and label being drawn. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. color1 color assigned to Arc 1 and Scale 1. color2 color assigned to Arc 2 and Scale 2. color3 color assigned to Arc 3 and Scale 3. color4 color assigned to Arc 4 and Scale 4. color5 color assigned to Arc 5 and Scale 5. color6 color assigned to Arc 6 and Scale 6. Returns None. Example None. 5.2.2.7.12.9 GFX_GOL_MeterValueSet Function C void GFX_GOL_MeterValueSet( GFX_GOL_METER * pObject, int16_t value ); Description This function sets the value of the meter. The value used should be within the range set for the object. The new value is checked to be in the minimum and maximum value range. If the value set is less than the minimum value, the value that will be set is the minimum value. If the value set is more than the maximum value, then the value that will be set is the maximum value. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-778 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. value the new value of the object. Returns None. Example GFX_GOL_METER *pMeter; uint16_t ctr = 0; // create slider here and initialize parameters GFX_GOL_ObjectStateSet(pMeter, GFX_GOL_METER_DRAW_STATE); GFX_GOL_ObjectListDraw(); while("some condition") { GFX_GOL_MeterValueSet(pMeter, ctr); GFX_GOL_ObjectStateSet( pMeter, GFX_GOL_METER_UPDATE_DRAW_STATE); // redraw the scroll bar GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } 5.2.2.7.13 Progress Bar Object Functions 5.2.2.7.13.1 GFX_GOL_ProgressBarActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_ProgressBarActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_PROGRESSBAR_ACTION_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE, If events occurs and the x,y position falls in the area of the object. EVENT_MOVE GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-779 Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_PROGRESSBAR_ACTION_SELECTED – Object is selected • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.13.2 GFX_GOL_ProgressBarCreate Function C GFX_GOL_PROGRESSBAR * GFX_GOL_ProgressBarCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, uint16_t pos, uint16_t range, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_PROGRESSBAR object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_RadioButtonCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pos > range • range = 0 • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-780 top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pos Defines the initial position of the progress. range This specifies the maximum value of the progress bar when the progress bar is at 100% position. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example GFX_GOL_PROGRESSBAR *pPBar; void CreateProgressBar() { pPBar = PbCreate(ID_PROGRESSBAR1, // ID 50,90,270,140, // dimension PB_DRAW, // Draw the object 25, // position 50, // set the range NULL); // use default GOL scheme } 5.2.2.7.13.3 GFX_GOL_ProgressBarDraw Function C GFX_STATUS GFX_GOL_ProgressBarDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-781 5.2.2.7.13.4 GFX_GOL_ProgressBarPositionSet Function C void GFX_GOL_ProgressBarPositionSet( GFX_GOL_PROGRESSBAR * pObject, uint16_t position ); Description This function sets the position of the progress bar. The value used for the position should be within the range set for the object. Function will have an undefined behavior if the position is outside the range. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. position the new position of the scroll bar thumb. Returns None. Example GFX_GOL_PROGRESSBAR *pPb; uint8_t direction = 1; // this code increments and decrements the progress bar by 1 // assume progress bar was created and initialized before while (1) { if(direction) { if(pPb ->pos == pPb ->range) direction = 0; else GFX_GOL_ProgressBarPositionSet( pPb, GFX_GOL_ProgressBarPositionGet(pPb)+1); } else { if(pPb ->pos == 0) direction = 1; else GFX_GOL_ProgressBarPositionSet( pPb, GFX_GOL_ProgressBarPositionGet(pPb)-1); } } 5.2.2.7.13.5 GFX_GOL_ProgressBarRangeSet Function C void GFX_GOL_ProgressBarRangeSet( GFX_GOL_PROGRESSBAR * pObject, uint16_t range 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-782 ); Description This function sets the range of the progress bar. When the range is modified, object must be completely redrawn to reflect the change. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. range new range of the object. Returns None. Example None. 5.2.2.7.14 Picture Object Functions 5.2.2.7.14.1 GFX_GOL_PictureControlActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_PictureControlActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_PICTURECONTROL_ACTION_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE, EVENT_MOVE If events occurs and the x,y position falls in the area of the picture. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-783 Returns • GFX_GOL_PICTURECONTROL_ACTION_SELECTED – Object is selected • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.14.2 GFX_GOL_PictureControlCreate Function C GFX_GOL_PICTURECONTROL * GFX_GOL_PictureControlCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, int8_t scaleFactor, GFX_RESOURCE_HDR * pImage, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_PICTURECONTROL object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The object allows creation with the image set to NULL. In this case, nothing will be drawn when the object is set to be drawn and the frame is not enabled (See GFX_GOL_PICTURECONTROL_FRAME_STATE). If the frame is enabled, then only the frame will be drawn. When the assigned image's dimension is larger than the dimension of the object, partial image parameters will be set in such a way that the upper left most corner of the image that has the same dimension as the object will be used in the object. This is the default behavior. The partial parameters can be modified by calling the GFX_GOL_PictureControlPartialSet() function with the desired parial image parameters. See GFX_ImagePartialDraw() for details on the partial image rendering. The behavior of GFX_GOL_PictureControlCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pImage is not pointing to a GFX_RESOURCE_HDR. Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-784 bottom Bottom most position of the object. state Sets the initial state of the object. pImage Pointer to the image by the object pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example None. 5.2.2.7.14.3 GFX_GOL_PictureControlDraw Function C GFX_STATUS GFX_GOL_PictureControlDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When the image size The text on the face of the GFX_GOL_PICTURECONTROL is drawn on top of the bitmap. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.14.4 GFX_GOL_PictureControlPartialSet Function C void GFX_GOL_PictureControlPartialSet( GFX_GOL_PICTURECONTROL * pObject, uint16_t xOffset, uint16_t yOffset, uint16_t partialWidth, uint16_t partialHeight 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-785 ); Description This function sets the partial image parameters to be used in the object. This function allows usage of the object to specify a rectangular area of an image to be drawn as part of the object. This is useful when an image is already included in a larger image. To save memory, a separate image is not necessary for the picture object. The location of the smaller image in the larger image can be specified to show up in the picture object. This function will result in an undefined behavior when one of the following is true: • xOffset - value must not be greater than the image width. • yOffset - value must not be greater than the image height. • partialWidth - value must not be greater than image width - xoffset + 1. Value must also be less than the actual image width. • partialHeight - value must not be greater than image height - yoffset + 1. Value must also be less than the actual image height. Preconditions Object must exist in memory. The image pointer of the object must be initialized properly. Parameters Parameters Description xOffset x offset of the smaller portion of a large image yOffset y offset of the smaller portion of a large image partialWidth width of the selected portion of the image partialHeight height of the selected portion of the image Returns None. Example // assume pLargeImage is a valid GFX_RESOURCE_HDR // assume BigImage has a height and width of 100 pixels. GFX_RESOURCE_HDR *pLargeImage = &BigImage; GFX_GOL_PICTURECONTROL *pPicture; uint16_t width, height; uint16_t xOffset, yOffset; uint16_t objectWidth, objectHeight; objectWidth = 60 - 50; // 10 pixels objectHeight = 120 - 90; // 30 pixels // -1 is needed since the object dimension is inclusive pPicture = GFX_GOL_PictureControlCreate( 10, 50, 90, 50 + objectWidth - 1, 90 + objectHeight - 1, GFX_GOL_PICTURECONTROL_DRAW_STATE, largeImage, NULL); // set the parameters of the partial image to be // shown on the image // get the large image dimensions width = GFX_ImageWidthGet(pLargeImage); height = GFX_ImageHeightGet(pLargeImage); // get the offset so the middle of the large image with 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-786 // the width and height matching the object will be used. xOffset = (width - objectWidth) >> 1; yOffset = (height - objectHeight) >> 1; GFX_GOL_PictureControlPartialSet( pPicture, xOffset, yOffset, objectWidth, objectHeight); 5.2.2.7.15 Radio Button Object Functions 5.2.2.7.15.1 GFX_GOL_RadioButtonActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_RadioButtonActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_RADIOBUTTON_ACTION_CHECKED Touch Screen EVENT_PRESS If event occurs and the x,y position falls in the area of the Radio Button while the Radio Button is not checked. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object�s ID and parameter 2 passed matches SCAN_CR_PRESSED or SCAN_SPACE_PRESSED while the Radio Button is not checked. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_RADIOBUTTON_ACTION_CHECKED - Radio Button is checked • GFX_GOL_OBJECT_ACTION_INVALID - object is not affected Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-787 5.2.2.7.15.2 GFX_GOL_RadioButtonActionSet Function C void GFX_GOL_RadioButtonActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_RADIOBUTTON_ACTION_CHECKED Touch Screen, Set GFX_GOL_RADIOBUTTON_DRAW_STATE, Depending on the current value of RB_CHECKED Check Box will be redrawn. Keyboard Set/Clear GFX_GOL_RADIOBUTTON_CHECKED_STATE Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.15.3 GFX_GOL_RadioButtonCheckGet Function C uint16_t GFX_GOL_RadioButtonCheckGet( GFX_GOL_RADIOBUTTON * pObject ); Description This function returns the ID of the currently checked radio button in the group. When there is only one member of the group, then that member will have the check. When no member of the group is checked, then the id returned is (-1 or 0xFFFF). Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-788 Parameters Parameters Description pObject pointer to the object. Returns The ID of the member of the group with the check. Example static GFX_XCHAR label0[] = "RB1"; static GFX_XCHAR label1[] = "RB2"; static GFX_XCHAR label2[] = "RB3"; uint16_t state; GFX_GOL_OBJ_SCHEME *pScheme; RADIOBUTTON *pRb[3]; uint16_t ID; pScheme = GFX_GOL_ObjectSchemeCreate(); // Object will be drawn after creation // Object will be first button in the group state = GFX_GOL_RADIOBUTTON_DRAW_STATE | GFX_GOL_RADIOBUTTON_CHECKED_STATE; pRb[0] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON1, 255,40,310,80, state, label0, GFX_ALIGN_CENTER, pScheme); // Object will be drawn after creation state = GFX_GOL_RADIOBUTTON_DRAW_STATE; pRb[1] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON2, 255,85,310,125, state, label1, GFX_ALIGN_CENTER, pScheme); // Object will be drawn after creation state = GFX_GOL_RADIOBUTTON_DRAW_STATE; pRb[2] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON3, 255,130,310,170, state, label2, GFX_ALIGN_CENTER, pScheme); // draw the objects while(GFX_GOL_ObjectListDraw() != GFX_STATUS_SUCCESS); // can also use pRb[1] or pRb[0] to search the checked // radio button of the group. ID here should be ID_RADIOBUTTON1 ID = GFX_GOL_RadioButtonCheckGet(pRb[2]); if (ID == ID_RADIOBUTTON1) { // do something here then clear the check GFX_GOL_ObjectStateClear(pRb[0], RB_CHECKED); // Change the checked object. Pointer used is 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-789 // any of the three. The ID used will find the // correct object to be checked GFX_GOL_RadioButtonCheckSet(pRb[3], ID_RADIOBUTTON2); } 5.2.2.7.15.4 GFX_GOL_RadioButtonCheckSet Function C void GFX_GOL_RadioButtonCheckSet( GFX_GOL_RADIOBUTTON * pObject, uint16_t id ); Description This function sets the ID of the currently checked radio button in the group. When there is only one member of the group, then that member will have the check. When the id given does not exist in the group, the function will do nothing. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. id id of the member of the group. Returns None. Example See GFX_GOL_RadioButtonCheckGet() example. 5.2.2.7.15.5 GFX_GOL_RadioButtonCreate Function C GFX_GOL_RADIOBUTTON * GFX_GOL_RadioButtonCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_RADIOBUTTON object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_RadioButtonCreate() will be undefined if one of the following is true: • left >= right • top >= bottom 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-790 • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pText Pointer to the text of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example static GFX_XCHAR label0[] = "RB1"; static GFX_XCHAR label1[] = "RB2"; static GFX_XCHAR label2[] = "RB3"; uint16_t state; GFX_GOL_OBJ_SCHEME *pScheme; RADIOBUTTON *pRb[3]; pScheme = GFX_GOL_ObjectSchemeCreate(); // Object will be drawn after creation // Object will be first button in the group state = GFX_GOL_RADIOBUTTON_DRAW_STATE | GFX_GOL_RADIOBUTTON_CHECKED_STATE; pRb[0] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON1, 255,40,310,80, state, label0, GFX_ALIGN_CENTER, pScheme); // Object will be drawn after creation state = GFX_GOL_RADIOBUTTON_DRAW_STATE; pRb[1] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON2, 255,85,310,125, state, label1, GFX_ALIGN_CENTER, pScheme); // Object will be drawn after creation state = GFX_GOL_RADIOBUTTON_DRAW_STATE; pRb[2] = GFX_GOL_RadioButtonCreate(ID_RADIOBUTTON3, 255,130,310,170, state, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-791 label2, GFX_ALIGN_CENTER, pScheme); // draw the objects while(GFX_GOL_ObjectListDraw() != GFX_STATUS_SUCCESS); 5.2.2.7.15.6 GFX_GOL_RadioButtonDraw Function C GFX_STATUS GFX_GOL_RadioButtonDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the GFX_GOL_RADIOBUTTON is drawn with the text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.15.7 GFX_GOL_RadioButtonTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_RadioButtonTextAlignmentGet( GFX_GOL_RADIOBUTTON * pObject ); Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-792 Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.15.8 GFX_GOL_RadioButtonTextAlignmentSet Function C void GFX_GOL_RadioButtonTextAlignmentSet( GFX_GOL_RADIOBUTTON * pObject, GFX_ALIGNMENT align ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.15.9 GFX_GOL_RadioButtonTextSet Function C void GFX_GOL_RadioButtonTextSet( GFX_GOL_RADIOBUTTON * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-793 pText pointer to the text string to be used. Returns None. Example GFX_XCHAR Label0[] = “ON―; GFX_XCHAR Label1[] = “OFF―; GFX_GOL_RADIOBUTTON GFX_GOL_RADIOBUTTON[2]; GFX_GOL_RadioButtonTextSet(GFX_GOL_RADIOBUTTON[0], Label0); GFX_GOL_RadioButtonTextSet(GFX_GOL_RADIOBUTTON[1], Label1); 5.2.2.7.16 Round Dial Object Functions 5.2.2.7.16.1 GFX_GOL_RoundDailActionGet Function C uint16_t GFX_GOL_RoundDailActionGet( void * pObj, GFX_GOL_MESSAGE * pMsg ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen inputs. Translated Message Input Source Events Description RD_MSG_CLOCKWISE Touch Screen EVENT_MOVE If events occurs and the x,y position falls in the face of the Dial and moving in the clockwise rotation. RD_MSG_CTR_CLOCKWISE Touch Screen EVENT_MOVE If events occurs and the x,y position falls in the face of the Dial and moving in the counter clockwise rotation. OBJ_MSG_INVALID Any Any If the message did not affect the object. Preconditions none Parameters Parameters Description pDia The pointer to the object where the message will be evaluated to check if the message will affect the object. pMsg Pointer to the message struct containing the message from the user interface. Returns Returns the translated message depending on the received GOL message: • RD_MSG_CLOCKWISE – Dial is moved in a clockwise direction. • RD_MSG_CTR_CLOCKWISE – Dial is moved in a counter clockwise direction. • GFX_GOL_MSG_INVALID – Dial is not affected 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-794 Side Effects none Example void MyGOLMsg(GFX_GOL_MESSAGE *pMsg){ GFX_OBJ_HEADER *pCurrentObj; uint16_t objMsg; if(pMsg->event == EVENT_INVALID) return; pCurrentObj = GFX_OBJ_ListGet(); while(pCurrentObj != NULL){ // Process only ROUNDDIAL if(!GFX_OBJ_IsUpdatePending(pCurrentObj)){ switch(pCurrentObj->type){ case OBJ_ROUNDIAL: objMsg = RdiaTranslateMsg((ROUNDDIAL*)pCurrentObj, pMsg); if(objMsg == OBJ_MSG_INVALID) break; if(GFX_GOL_MESSAGECallback(objMsg,pCurrentObj,pMsg)) RdiaMsgDefault(objMsg,(ROUNDDIAL*)pCurrentObj); break; default: break; } } } pCurrentObj = pCurrentObj->pNxtObj; } 5.2.2.7.16.2 GFX_GOL_RoundDailActionSet Function C void GFX_GOL_RoundDailActionSet( uint16_t translatedMsg, void * pObj, GFX_GOL_MESSAGE * pMsg ); Description This function performs the actual state change based on the translated message given. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description ################ ########## ##### ########## RD_MSG_CLOCKWISE Touch Screen Set GFX_GOL_ROUNDDIAL_ROT_CW, Dial will be redrawn with clockwise update. Set GFX_GOL_ROUNDDIAL_DRAW RD_MSG_CTR_CLOCKWISE Touch Screen Set GFX_GOL_ROUNDDIAL_ROT_CCW, Dial will be redrawn with counter clockwise update. Set GFX_GOL_ROUNDDIAL_DRAW Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-795 Parameters Parameters Description translatedMsg The translated message pDia The pointer to the object whose state will be modified pMsg The pointer to the GOL message Returns none Side Effects none Example See RdiaTranslateMsg() example. 5.2.2.7.16.3 GFX_GOL_RoundDialCreate Function C GFX_GOL_ROUNDDIAL * GFX_GOL_RoundDialCreate( uint16_t ID, uint16_t x, uint16_t y, uint16_t radius, uint16_t state, uint16_t res, uint16_t value, uint16_t max, GFX_GOL_OBJ_SCHEME * pScheme ); Description It automatically attaches the new object into a global linked list of objects and returns the address of the object. Preconditions none Parameters Parameters Description ID Unique user defined ID for the object instance. x Location of the center of the dial in the x coordinate. y Location of the center of the dial in the y coordinate. radius Defines the radius of the dial. state Sets the initial state of the object. res Sets the resolution of the dial when rotating clockwise or counter clockwise. value Sets the initial value of the dial. max Sets the maximum value of the dial. pScheme Pointer to the style scheme used. Returns Returns the pointer to the object created. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-796 Remarks none Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_ROUNDDIAL *pDial; uint16_t state; pScheme = GFX_GOL_SchemeCreate(); state = GFX_GOL_ROUNDDIAL_DRAW; // creates a dial at (50,50) x,y location, with an initial value // of 50, a resolution of 2 and maximum value of 100. pDial = GFX_GOL_RoundDial_Create(1,50,50,25,118,0, state, 2, 50, 100, pScheme); // check if dial was created if (pDial == NULL) return 0; return 1; 5.2.2.7.16.4 GFX_GOL_RoundDialDraw Function C uint16_t GFX_GOL_RoundDialDraw( void * pObj ); Description This function renders the object on the screen using the current parameter settings. Location of the object is determined by the center (x,y) postion and the radius parameters. The colors used are dependent on the state of the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Preconditions Object must be created before this function is called. Parameters Parameters Description pDia Pointer to the object Returns Returns the status of the drawing • 1 - If the rendering was completed and • 0 - If the rendering is not yet finished. Side Effects none 5.2.2.7.16.5 RdiaCosine Function C short RdiaCosine( short v ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-797 Description This is function RdiaCosine. 5.2.2.7.16.6 RdiaSine Function C short RdiaSine( short v ); Description This is function RdiaSine. 5.2.2.7.17 Scrollbar Object Functions 5.2.2.7.17.1 GFX_GOL_ScrollBarActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_ScrollBarActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Set/Clear State Bit Description GFX_GOL_SCROLLBAR_ACTION_INC Touch Screen EVENT_PRESS, EVENT_MOVE If events occurs and the x,y position falls in the area of the slider and the slider position is to the LEFT of the x,y position for a horizontal slider or BELOW the x,y position for a vertical slider. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object�s ID and parameter 2 passed matches SCAN_UP_PRESSED or SCAN_LEFT_PRESSED. GFX_GOL_SCROLLBAR_ACTION_DEC Touch Screen EVENT_PRESS, EVENT_MOVE If events occurs and the x,y position falls in the area of the slider and the slider position is to the RIGHT of the x,y position for a horizontal slider or ABOVE the x,y position for a vertical slider. Keyboard EVENT_KEYSCAN If event occurs and parameter1 passed matches the object�s ID and parameter 2 passed matches SCAN_DOWN_PRESSED or SCAN_RIGHT_PRESSED. GFX_GOL_OBJECT_ACTION_PASSIVE Touch Screen EVENT_RELEASE If events occurs and the x,y position falls in the area of the slider. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-798 Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_SCROLLBAR_ACTION_INC – Increment scroll bar position. • GFX_GOL_SCROLLBAR_ACTION_DEC – Decrement scroll bar position. • GFX_GOL_OBJECT_ACTION_PASSIVE – Object bar is not affected • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected Example None. 5.2.2.7.17.2 GFX_GOL_ScrollBarActionSet Function C void GFX_GOL_ScrollBarActionSet( GFX_GOL_TRANSLATED_ACTION translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_SCROLLBAR_ACTION_INC Touch Screen, Set GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE Scroll Bar will be redrawn with thumb in the incremented position. Keyboard GFX_GOL_SCROLLBAR_ACTION_DEC Touch Screen, Set GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE Scroll Bar will be redrawn with thumb in the decremented position. Keyboard Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-799 Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.17.3 GFX_GOL_ScrollBarCreate Function C GFX_GOL_SCROLLBAR * GFX_GOL_ScrollBarCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, uint16_t range, uint16_t page, uint16_t pos, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_SCROLLBAR object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The object can be configured as a scroll bar or a slider. Use the state bit GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE to enable the usage of the object as a slider. If this state bit is not enabled, the object is set up as a scroll bar. The object can also be configured with vertical orientation. Use the state bit GFX_GOL_SCROLLBAR_VERTICAL_STATE to set up the object with vertical orientation. If this state bit is not set, the object is used with horizontal orientation. The behavior of GFX_GOL_ScrollBarCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • page is set to zero. • range is set to zero. • page > range. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-800 Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. range This specifies the maximum value of the slider when the thumb is on the rightmost position for a horizontal orientation and bottom most position for the vertical orientation. Minimum value is always at zero. page This is the incremental change of the slider when user action requests to move the slider thumb. This value is added or subtracted to the current position of the thumb. pos This defines the initial position of the thumb. pScheme The pointer to the style scheme used for the Object. Set to NULL if default style scheme is used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_SCROLLBAR *srollBarArray[3]; uint16_t state; pScheme = GFX_GOL_ObjectSchemeCreate(); // create a slider with // range = [0 - 50000] // delta = 500 // initial position = 25000 state = GFX_GOL_SCROLLBAR_DRAW_STATE; srollBarArray[0] = GFX_GOL_ScrollBarCreate( 5, 150, 145, 285, 181, state, 50000, 500, 25000, pScheme); if (slider[0] == NULL) return 0; // create a slider with // range = [0 - 100] // delta = 20 // initial position = 0 state = GFX_GOL_SCROLLBAR_DRAW_STATE | GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE; srollBarArray[1] = GFX_GOL_ScrollBarCreate( 6, 150, 190, 285, 220, state, 100, 20, 0, pScheme); if (slider[1] == NULL) return 0; // create a vertical scroll bars with // range = [0 - 30] // delta = 2 // initial position = 20 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-801 state = GFX_GOL_SCROLLBAR_DRAW_STATE | GFX_GOL_SCROLLBAR_VERTICAL_STATE; srollBarArray[2] = GFX_GOL_ScrollBarCreate( 7, 120, 145, 140, 220, state, 30, 2, 20, pScheme); if (slider[2] == NULL) return 0; // draw the sliders while (GFX_GOL_ObjectListDraw() == 0); return 1; 5.2.2.7.17.4 GFX_GOL_ScrollBarDraw Function C GFX_STATUS GFX_GOL_ScrollBarDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the face of the GFX_GOL_SCROLLBAR is drawn on top of the bitmap. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.17.5 GFX_GOL_ScrollBarPageGet Function C uint16_t GFX_GOL_ScrollBarPageGet( GFX_GOL_SCROLLBAR * pObject ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-802 Description This function returns the page size of the object. Page size defines the delta change of the thumb position when incremented via GFX_GOL_ScrollBarPositionIncrement() or decremented via GFX_GOL_ScrollBarPositionDecrement(). Page size minimum value is 1. Maximum value is range/2. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The page size of the object. Example uint16_t page; GFX_GOL_SCROLLBAR *pScrollBar; // assume pScrollBar is initialized to a scroll bar in memory page = GFX_GOL_ScrollBarPageGet(pScrollBar); 5.2.2.7.17.6 GFX_GOL_ScrollBarPageSet Function C void GFX_GOL_ScrollBarPageSet( GFX_GOL_SCROLLBAR * pObject, uint16_t page ); Description This function sets the page size of the object. Page size defines the delta change of the thumb position when incremented via GFX_GOL_ScrollBarPositionIncrement() or decremented via GFX_GOL_ScrollBarPositionDecrement(). Page size minimum value is 1. Maximum value is range/2. Modifying the page size at run time may require a redraw of the object to show the visual effect of the change. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. page value of the page size of the object. Returns None. Example See GFX_GOL_ScrollBarPositionIncrement() for code example. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-803 5.2.2.7.17.7 GFX_GOL_ScrollBarPositionDecrement Function C void GFX_GOL_ScrollBarPositionDecrement( GFX_GOL_SCROLLBAR * pObject ); Description This function decrements the scroll bar position by the delta change (page) value set. Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example void ControlSpeed( GFX_GOL_SCROLLBAR* pObj, int setSpeed, int curSpeed) { // set page size to 1 GFX_GOL_ScrollBarPageSet(pObj, 1); if (setSpeed < curSpeed) { while(GFX_GOL_ScrollBarPositionGet(pObj) < SetSpeed) { // increment by 1 GFX_GOL_ScrollBarPositionIncrement(pObj); } } else if (setSpeed > curSpeed) { while(GFX_GOL_ScrollBarPositionGet(pObj) > SetSpeed) { // decrement by 1 GFX_GOL_ScrollBarPositionDecrement(pObj); } } } 5.2.2.7.17.8 GFX_GOL_ScrollBarPositionGet Function C uint16_t GFX_GOL_ScrollBarPositionGet( GFX_GOL_SCROLLBAR * pObject ); Description This function returns the current position of the scroll bar thumb. The thumb is the rectangular area that slides left or right (for horizontal orientation) or slides up or down (for vertical orientation). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-804 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current position of the scroll bar thumb. Example #define MAXVALUE 100; GFX_GOL_SCROLLBAR *pScrollBar; uint32_t ctr = 0; // create scroll bar here and initialize parameters pScrollBar = GFX_GOL_ScrollBarCreate(....) GFX_GOL_ObjectStateSet(pScrollBar, GFX_GOL_SCROLLBAR_DRAW_STATE); // draw the scroll bar GFX_GOL_ObjectListDraw(); // a routine that updates the position of the thumb through some // conditions while("some condition") { GFX_GOL_ScrollBarPositionSet(pScrollBar, ctr); GFX_GOL_ObjectStateSet( pScrollBar, GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE); // update the screen GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } if (GFX_GOL_ScrollBarPositionGet(pScrollBar) > MAXVALUE) return 0; else "do something else" 5.2.2.7.17.9 GFX_GOL_ScrollBarPositionIncrement Function C void GFX_GOL_ScrollBarPositionIncrement( GFX_GOL_SCROLLBAR * pObject ); Description This function increments the scroll bar position by the delta change (page) value set. Object must be redrawn after this function is called to reflect the changes to the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-805 Parameters Parameters Description pObject pointer to the object. Returns None. Example void ControlSpeed( GFX_GOL_SCROLLBAR* pObj, int setSpeed, int curSpeed) { // set page size to 1 GFX_GOL_ScrollBarPageSet(pObj, 1); if (setSpeed < curSpeed) { while(GFX_GOL_ScrollBarPositionGet(pObj) < SetSpeed) GFX_GOL_ScrollBarPositionIncrement(pObj); // increment by 1 } else if (setSpeed > curSpeed) { while(GFX_GOL_ScrollBarPositionGet(pObj) > SetSpeed) GFX_GOL_ScrollBarPositionDecrement(pObj); // decrement by 1 } } 5.2.2.7.17.10 GFX_GOL_ScrollBarPositionSet Function C void GFX_GOL_ScrollBarPositionSet( GFX_GOL_SCROLLBAR * pObject, uint16_t position ); Description This function sets the position of the scroll bar thumb. The thumb is the rectangular area that slides left or right (for horizontal orientation) or slides up or down (for vertical orientation). The value used for the position should be within the range set for the object. Function will have an undefined behavior if the position is outside the range. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. position the new position of the scroll bar thumb. Returns None. Example GFX_GOL_SCROLLBAR *pScrollBar; uint16_t ctr = 0; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-806 // create slider here and initialize parameters GFX_GOL_ObjectStateSet(pScrollBar, GFX_GOL_SCROLLBAR_DRAW_STATE); GFX_GOL_ObjectListDraw(); while("some condition") { GFX_GOL_ScrollBarPositionSet(pScrollBar, ctr); GFX_GOL_ObjectStateSet( pScrollBar, GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE); // redraw the scroll bar GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } 5.2.2.7.17.11 GFX_GOL_ScrollBarRangeGet Function C uint16_t GFX_GOL_ScrollBarRangeGet( GFX_GOL_SCROLLBAR * pObject ); Description This function returns the range of the thumb of the scroll bar. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The range of the scroll bar. Example GFX_GOL_SCROLLBAR *pSld; uint16_t range; range = GFX_GOL_ScrollBarRangeGet(pSld); 5.2.2.7.17.12 GFX_GOL_ScrollBarRangeSet Function C void GFX_GOL_ScrollBarRangeSet( GFX_GOL_SCROLLBAR * pObject, uint16_t range ); Description This function sets the range of the thumb of the scroll bar. When the range is modified, object must be completely redrawn to reflect the change. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-807 Parameters Parameters Description pObject pointer to the object. range new range of the scroll bar. Returns None. Example GFX_GOL_SCROLLBAR *pSld; GFX_GOL_ScrollBarRangeSet(pSld, 100); // to completely redraw the object when // GFX_GOL_ObjectListDraw() is executed. GFX_GOL_ObjectStateSet(pSld, SLD_DRAW); 5.2.2.7.18 Static Text Object Functions 5.2.2.7.18.1 GFX_GOL_StaticTextActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_StaticTextActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen inputs. Translated Message Input Source Events Description GFX_GOL_STATICTEXT_ACTION_SELECTED Touch Screen EVENT_PRESS, EVENT_RELEASE If events occurs and the x,y position falls in the area of the static text. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_STATICTEXT_ACTION_SELECTED – Object is selected • GFX_GOL_OBJECT_ACTION_INVALID – Object is not affected 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-808 Example None. 5.2.2.7.18.2 GFX_GOL_StaticTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_StaticTextAlignmentGet( GFX_GOL_STATICTEXT * pObject ); Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.18.3 GFX_GOL_StaticTextAlignmentSet Function C void GFX_GOL_StaticTextAlignmentSet( GFX_GOL_STATICTEXT * pObject, GFX_ALIGNMENT align ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-809 5.2.2.7.18.4 GFX_GOL_StaticTextCreate Function C GFX_GOL_STATICTEXT * GFX_GOL_StaticTextCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_STATICTEXT object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The text can be configured to have text aligned. See GFX_ALIGNMENT for details. Text can also have multiple lines by inserting the new line character to the text string supplied to the object. Any string that exceeds the dimension of the object will be clipped. When the object is used with no background, application must manage the object when text is modified and redrawn. i.e. the previous text must be removed. Use GFX_GOL_STATICTEXT_NOBACKGROUND_STATE state bit to disable the background. The behavior of GFX_GOL_StaticTextCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • pText is an unterminated string Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pText Pointer to the text of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example // assume pScheme is initialized GFX_GOL_OBJ_SCHEME *pScheme; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-810 GFX_GOL_STATICTEXT *pSt; pScheme = GOLCreateScheme(); StCreate( ID_STATICTEXT1, // ID 30,80,235,160, // dimension GFX_GOL_STATICTEXT_DRAW_STATE, // draw the object "Static Textn Example", // 2 lines of text GFX_ALIGN_CENTER, // align text on the center pScheme); // use given scheme 5.2.2.7.18.5 GFX_GOL_StaticTextDraw Function C GFX_STATUS GFX_GOL_StaticTextDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.18.6 GFX_GOL_StaticTextGet Function C GFX_XCHAR * GFX_GOL_StaticTextGet( GFX_GOL_STATICTEXT * pObject ); Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-811 Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example GFX_XCHAR *pChar; GFX_GOL_STATICTEXT OBJECT_ARRAY[2]; pChar = GFX_GOL_StaticTextGet(OBJECT_ARRAY[0]); 5.2.2.7.18.7 GFX_GOL_StaticTextSet Function C void GFX_GOL_StaticTextSet( GFX_GOL_STATICTEXT * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be used. Returns None. Example None. 5.2.2.7.19 Text Entry Object Functions 5.2.2.7.19.1 GFX_GOL_TextEntryActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_TextEntryActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-812 Translated Message Input Source Set/Clear State Bit Description GFX_GOL_TEXTENTRY_ACTION_PRESS Touch Screen EVENT_PRESS, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed. GFX_GOL_TEXTENTRY_ACTION_RELEASED Touch Screen EVENT_MOVE If the event occurs and the x,y position falls outside the face of one of the keys of the object while the key is pressed. GFX_GOL_TEXTENTRY_ACTION_RELEASED Touch Screen EVENT_RELEASE If the event occurs and the x,y position falls does not falls inside any of the faces of the keys of the object. GFX_GOL_TEXTENTRY_ACTION_ADD_CHAR Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with no commands. GFX_GOL_TEXTENTRY_ACTION_DELETE Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with delete command. GFX_GOL_TEXTENTRY_ACTION_SPACE Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with space command. GFX_GOL_TEXTENTRY_ACTION_ENTER Touch Screen EVENT_RELEASE, EVENT_MOVE If the event occurs and the x,y position falls in the face of one of the keys of the object while the key is unpressed and the key is associated with enter command. GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_TEXTENTRY_ACTION_PRESS - A key is pressed • GFX_GOL_TEXTENTRY_ACTION_RELEASED - A key was released (generic for keys with no commands or characters assigned) • GFX_GOL_TEXTENTRY_ACTION_ADD_CHAR - A key was released with character assigned • GFX_GOL_TEXTENTRY_ACTION_DELETE - A key was released with delete command assigned • GFX_GOL_TEXTENTRY_ACTION_SPACE - A key was released with space command assigned • GFX_GOL_TEXTENTRY_ACTION_ENTER - A key was released with enter command assigned • GFX_GOL_OBJECT_ACTION_INVALID - Text Entry is not affected 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-813 Example None. 5.2.2.7.19.2 GFX_GOL_TextEntryActionSet Function C void GFX_GOL_TextEntryActionSet( uint16_t translatedMsg, void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function performs the state change of the object based on the translated action. This change can be overridden by the application using the application defined GFX_GOL_MESSAGE_CALLBACK_FUNC. When the user message is determined to affect the object, application can perform the state change in the message callback function. The following state changes are supported: Translated Message Input Source Set/Clear State Bit Description GFX_GOL_TEXTENTRY_ACTION_ADD_CHAR Touch Screen, Set GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE, Add a character in the buffer and update the text displayed. GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE, Clear GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE GFX_GOL_TEXTENTRY_ACTION_SPACE Touch Screen, Set GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE, Insert a space character in the buffer and update the text displayed. GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE, Clear GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE GFX_GOL_TEXTENTRY_ACTION_DELETE Touch Screen, Set GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE, Delete the most recent character in the buffer and update the text displayed. GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE, Clear GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE GFX_GOL_TEXTENTRY_ACTION_ENTER Touch Screen, Set GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE, User can define the use of this event in the message callback. Object will just update the key. GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE, Clear GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE GFX_GOL_TEXTENTRY_ACTION_RELEASED Touch Screen, Clear GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE A Key in the object will be redrawn in the unpressed state. Set GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE GFX_GOL_TEXTENTRY_ACTION_PRESSED Touch Screen, Set GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE A Key in the object will be redrawn in the pressed state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-814 GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE Preconditions Object must exist in memory. Parameters Parameters Description translatedMsg The action of the object based on the message. pObject The pointer to the object whose state will be modified. pMessage The pointer to the original message. Returns None. Example None. 5.2.2.7.19.3 GFX_GOL_TextEntryBufferClear Function C void GFX_GOL_TextEntryBufferClear( GFX_GOL_TEXTENTRY * pObject ); Description This function will clear the data in the display. Object must be redrawn to reflect the change in the buffer. Use the drawing state bit GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE to update the text on the screen. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.19.4 GFX_GOL_TextEntryBufferGet Function C GFX_XCHAR * GFX_GOL_TextEntryBufferGet( GFX_GOL_TEXTENTRY * pObject ); Description This function returns the buffer used to display text. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-815 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The pointer to the text buffer used to display text. Example None. 5.2.2.7.19.5 GFX_GOL_TextEntryBufferSet Function C void GFX_GOL_TextEntryBufferSet( GFX_GOL_TEXTENTRY * pObject, GFX_XCHAR * pText, uint16_t MaxSize ); Description This function sets the buffer used to display text. If the buffer is initialized with a string, the string must be a null terminated string. If the string length is greater than MaxSize, string will be truncated to MaxSize. pText must point to a valid memory location with size equal to MaxSize. The total number of characters that will be displayed on the object will be MaxSize - 1 since the last character will be the string terminator character. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the new text buffer to be displayed. maxSize maximum length of the new buffer to be used. Returns None. Example None. 5.2.2.7.19.6 GFX_GOL_TextEntryCharAdd Function C void GFX_GOL_TextEntryCharAdd( GFX_GOL_TEXTENTRY * pObject ); Description This function will insert a character to the end of the buffer. Drawing states GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE or GFX_GOL_TEXTENTRY_DRAW_STATE must be set to see the effect of the addition. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-816 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.19.7 GFX_GOL_TextEntryCreate Function C GFX_GOL_TEXTENTRY * GFX_GOL_TextEntryCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, uint16_t horizontalKeys, uint16_t verticalKeys, GFX_XCHAR * pText[], GFX_XCHAR * pBuffer, GFX_ALIGNMENT alignment, uint16_t bufferLength, GFX_RESOURCE_HDR * pDisplayFont, GFX_GOL_OBJ_SCHEME * pScheme ); Description This function creates a GFX_GOL_TEXTENTRY object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. The behavior of GFX_GOL_TextEntryCreate() will be undefined if one of the following is true: • left >= right • top >= bottom • pScheme is not pointing to a GFX_GOL_OBJ_SCHEME • horizontal key or vertical key count is 0 • pText is an unterminated string • pBuffer is initialized to an allocated memory. Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-817 left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. radius Radius of the rounded edge. When using gradient buttons and radius != 0, emboss size <= radius. If this is not met, the the GFX_GOL_BUTTON face will not have gradient effect. state Sets the initial state of the object. horizontalKeys Number of horizontal keys verticalKeys Number of vertical keys pText array of pointer to the custom "text" assigned by the user. pBuffer pointer to the buffer that holds the text to be displayed. alignment text alignment of the text used in the object. bufferLength length of the buffer assigned by the user. The choice of the length should include the string null terminator. For example if the bufferLength is set to 3, only two characters can be shown on the object since the last character will be the string terminator character. pDisplayFont pointer to the font image to be used on the edit box section of the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example TODO:Add example code. 5.2.2.7.19.8 GFX_GOL_TextEntryDraw Function C GFX_STATUS GFX_GOL_TextEntryDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-818 yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.19.9 GFX_GOL_TextEntryKeyCommandGet Function C GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE GFX_GOL_TextEntryKeyCommandGet( GFX_GOL_TEXTENTRY * pObject, uint16_t index ); Description This function will return the currently assigned command to the key with the given index. (See GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE) Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. index index or position of the key. Returns Command assigned to the key (See GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE). Example None. 5.2.2.7.19.10 GFX_GOL_TextEntryKeyCommandSet Function C bool GFX_GOL_TextEntryKeyCommandSet( GFX_GOL_TEXTENTRY * pObject, uint16_t index, GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE command ); Description This function will assign a command to a key with the given index. (See GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE) Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. index index or position of the key. command command assigned for the key. Returns TRUE - if the assignment was a success. FALSE - if the assignment was not successful. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-819 Example None. 5.2.2.7.19.11 GFX_GOL_TextEntryKeyIsPressed Function C bool GFX_GOL_TextEntryKeyIsPressed( GFX_GOL_TEXTENTRY * pObject, uint16_t index ); Description This function will test if a key given by its index in the object is pressed. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. index index or position of key that is being tested. Returns TRUE - if the key is pressed. FALSE - if the key is not pressed. Example None. 5.2.2.7.19.12 GFX_GOL_TextEntryKeyListCreate Function C KEYMEMBER * GFX_GOL_TextEntryKeyListCreate( GFX_GOL_TEXTENTRY * pObject, GFX_XCHAR * pText[] ); Description This function will create the list of KEYMEMBERS that holds the information on each key. The number of keys is determined by the equation (keycount = verticalKeys*horizontalKeys). The object creates the information holder for each key automatically and assigns each entry in the *pText[] array with the first entry automatically assigned to the key with an index of 1. The number of entries to *pText[] must be at least equal to keycount. The last key is assigned with an index of keycount-1. No checking is performed on the length of *pText[] entries to match (verticalKeys*horizontalKeys). The function behavior is undefined if the pText[] array is less than the keycount value. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the text defined by the application. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-820 Returns Returns the pointer to the newly created KEYMEMBER list. A NULL is returned if the list is not created succesfully. Example None. 5.2.2.7.19.13 GFX_GOL_TextEntryKeyMemberListDelete Function C void GFX_GOL_TextEntryKeyMemberListDelete( void * pObject ); Description This function will delete the KEYMEMBER list assigned to the object from memory. Pointer to the KEYMEMBER list is then initialized to NULL. All memory resources allocated to the key member list is freed. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.19.14 GFX_GOL_TextEntryKeyTextSet Function C bool GFX_GOL_TextEntryKeyTextSet( GFX_GOL_TEXTENTRY * pObject, uint16_t index, GFX_XCHAR * pText ); Description This function will set the text assigned to a key with the given index. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. index index or position of the key. pText pointer to the text that will be assigned to the key. Returns TRUE - if the assignment was a success. FALSE - if the assignment was not successful. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-821 Example None. 5.2.2.7.19.15 GFX_GOL_TextEntryLastCharDelete Function C void GFX_GOL_TextEntryLastCharDelete( GFX_GOL_TEXTENTRY * pObject ); Description This function will remove the last character of the buffer and replace it with a string terminator. Drawing states GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE or GFX_GOL_TEXTENTRY_DRAW_STATE must be set to see the effect of the addition. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2.2.7.19.16 GFX_GOL_TextEntrySpaceCharAdd Function C void GFX_GOL_TextEntrySpaceCharAdd( GFX_GOL_TEXTENTRY * pObject ); Description This function will insert a space character to the end of the buffer. Drawing states GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE or GFX_GOL_TEXTENTRY_DRAW_STATE must be set to see the effect of the addition. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns None. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-822 5.2.2.7.20 Window Object Functions 5.2.2.7.20.1 GFX_GOL_WindowActionGet Function C GFX_GOL_TRANSLATED_ACTION GFX_GOL_WindowActionGet( void * pObject, GFX_GOL_MESSAGE * pMessage ); Description This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the action for each event of the touch screen and keyboard inputs. Translated Message Input Source Events Description GFX_GOL_WINDOW_ACTION_TITLE Touch Screen EVENT_PRESS, EVENT_RELEASE, EVENT_MOVE If events occurs and the x,y position falls in the TITLE area of the window GFX_GOL_WINDOW_ACTION_CLIENT Touch Screen EVENT_PRESS, EVENT_RELEASE, EVENT_MOVE If events occurs and the x,y position falls in the CLIENT area of the window GFX_GOL_OBJECT_ACTION_INVALID Any Any If the message did not affect the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object where the message will be evaluated to check if the message will affect the object. pMessage Pointer to the the message from the user interface. Returns • GFX_GOL_WINDOW_ACTION_CLIENT // Window client area selected action ID. • GFX_GOL_WINDOW_ACTION_TITLE // Window title bar selected action ID. Example None. 5.2.2.7.20.2 GFX_GOL_WindowCreate Function C GFX_GOL_WINDOW * GFX_GOL_WindowCreate( uint16_t ID, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t state, void * pBitmap, GFX_XCHAR * pText, GFX_ALIGNMENT alignment, GFX_GOL_OBJ_SCHEME * pScheme 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-823 ); Description This function creates a GFX_GOL_WINDOW object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. This function returns the pointer to the newly created object. If the object is not successfully created, it returns NULL. Preconditions None. Parameters Parameters Description ID Unique user defined ID for the object instance. left Left most position of the object. top Top most position of the object. right Right most position of the object. bottom Bottom most position of the object. state Sets the initial state of the object. pImage Pointer to the image used on the face of the object. pText Pointer to the text of the object. alignment text alignment of the text used in the object. pScheme Pointer to the style scheme used. Returns Pointer to the newly created object. Example GFX_GOL_OBJ_SCHEME *pScheme; GFX_GOL_WINDOW *pWindow; GFX_GOL_WINDOW_STATE state; // assume pScheme is initialized to a scheme in memory. state = GFX_GOL_WINDOW_DRAW_STATE; pWindow = GFX_GOL_WindowCreate(1, // ID 0,0,GFX_Primitive_MaxXGet(),GFX_Primitive_MaxYGet(), // whole screen dimension state, // set state to draw all (char*)myIcon, // icon "Place Title Here.", // text NULL); // use default GOL scheme if (pWindow == NULL) return 0; return 1; 5.2.2.7.20.3 GFX_GOL_WindowDraw Function C GFX_STATUS GFX_GOL_WindowDraw( void * pObject ); Description This function renders the object on the screen based on the current state of the object. Location of the object is determined by 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-824 the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The text on the face of the GFX_GOL_WINDOW is drawn on top of the bitmap. Text alignment based on the alignment parameter set on the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. Normally, application will just call GFX_GOL_ObjectListDraw() to allow the Graphics Library to manage all object rendering. See GFX_GOL_ObjectListDraw() for more information on object rendering. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns GFX_STATUS_SUCCESS - When the object rendering is finished. GFX_STATUS_FAILURE - When the object rendering is not yet finished. Application needs to call this rendering function again to continue the rendering. Example None. 5.2.2.7.20.4 GFX_GOL_WindowTextAlignmentGet Function C GFX_ALIGNMENT GFX_GOL_WindowTextAlignmentGet( GFX_GOL_WINDOW * pObject ); Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.20.5 GFX_GOL_WindowTextAlignmentSet Function C void GFX_GOL_WindowTextAlignmentSet( GFX_GOL_WINDOW * pObject, GFX_ALIGNMENT align 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-825 ); Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.20.6 GFX_GOL_WindowTextSet Function C void GFX_GOL_WindowTextSet( GFX_GOL_WINDOW * pObject, GFX_XCHAR * pText ); Description This function sets the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pText pointer to the text string to be used. Returns None. Example GFX_XCHAR Label0[] = ?ON?; GFX_XCHAR Label1[] = ?OFF?; GFX_GOL_WINDOW pWindow; GFX_GOL_WindowTextSet(pWindow, Label0); GFX_GOL_WindowTextSet(pWindow, Label1); 5.2.2.7.21 Draw Functions 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-826 5.2.2.7.21.1 ClearPaletteChangeError Function C void ClearPaletteChangeError(); Description Clears the Palette change error status Preconditions none Returns none Side Effects none 5.2.2.7.21.2 DisablePalette Function C void DisablePalette(); Description Disables the Palette mode. Preconditions none Returns none 5.2.2.7.21.3 DrawArc Function C uint16_t DrawArc( int16_t cx, int16_t cy, int16_t r1, int16_t r2, int16_t startAngle, int16_t endAngle ); Description This renders an arc with from startAngle to endAngle with the thickness of r2-r1. The function returns 1 when the arc is rendered successfuly and returns a 0 when it is not yet finished. The next call to the function will continue the rendering. Preconditions none Parameters Parameters Description cx the location of the center of the arc in the x direction. cy the location of the center of the arc in the y direction. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-827 r1 the smaller radius of the arc. r2 the larger radius of the arc. startAngle start angle of the arc. endAngle end angle of the arc. Returns Returns 1 if the rendering is done, 0 if not yet done. Side Effects none Remarks none 5.2.2.7.21.4 EnablePalette Function C void EnablePalette(); Description Enables the Palette mode. Preconditions none Returns none 5.2.2.7.21.5 GetPaletteChangeError Function C BYTE GetPaletteChangeError(); Description Returns the Palette change error status Preconditions none Returns Returns the palette change status. 1 - If the palette change error occured 0 - If no palette change error occured Side Effects none 5.2.2.7.21.6 GFX_AlphaBlendingValueGet Function C uint16_t GFX_AlphaBlendingValueGet(); Description This function returns the current alpha value set for alpha blending rendering. See GFX_AlphaBlendingValueSet() for details of alpha blending values. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-828 Preconditions None. Returns The alpha blending value. Example TODO:Add example code 5.2.2.7.21.7 GFX_AlphaBlendingValueSet Function C GFX_STATUS GFX_AlphaBlendingValueSet( uint16_t alpha ); Description This function sets the alpha value for alpha blending rendering. Accepted values are dependent on the used alpha blending routines at build time. When using the software routines in the Primitive Layer, accepted values are 0, 25, 50, 75 and 100. If using a specific implementation in the display driver used, implementation may support the full range (0-100). When this is the case, refer to the driver alpha blending solution for details. Function operation will ignore unsupported values of alpha. Preconditions None. Parameters Parameters Description alpha Defines the alpha blending percentage to be used for alpha blending routines. Accepted values are dependent on the alpha blending routines used. For Primitive Layer 5.2.2.7.21.8 GFX_AlphaBlendWindow Function C GFX_STATUS GFX_AlphaBlendWindow( GFX_ALPHA_PARAMS * alphaParams, uint16_t width, uint16_t height, uint8_t alphaPercent ); Description None Preconditions None Parameters Parameters Description None None 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-829 Returns None Example None 5.2.2.7.21.9 GFX_BackgroundColorGet Function C GFX_COLOR GFX_BackgroundColorGet(); Description This function returns the color used in the current background. Preconditions None. Returns The color used in the current background. Example None. 5.2.2.7.21.10 GFX_BackgroundImageGet Function C GFX_RESOURCE_HDR * GFX_BackgroundImageGet(); Description This function returns the pointer to the image used in the current background. Preconditions None. Returns The pointer to the image used in the current background. Example None. 5.2.2.7.21.11 GFX_BackgroundImageLeftGet Function C uint16_t GFX_BackgroundImageLeftGet(); Description This function returns the horizontal starting position of the current background. This position defines the x position of the upper left corner of the background. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-830 Returns The horizontal starting position of the current background. Example None. 5.2.2.7.21.12 GFX_BackgroundImageTopGet Function C uint16_t GFX_BackgroundImageTopGet(); Description This function returns the vertical starting position of the current background. This position defines the y position of the upper left corner of the background. Preconditions None. Returns The vertical starting position of the current background. Example None. 5.2.2.7.21.13 GFX_BackgroundSet Function C void GFX_BackgroundSet( uint16_t left, uint16_t top, GFX_RESOURCE_HDR * pImage, GFX_COLOR color ); Description This function sets the background information. Note that the width and height of the background is only needed when the background is an image. When the background is a color (image pointer is NULL), the width and height is not needed here since the purpose of the background information is to record only the color used. Preconditions None. Parameters Parameters Description left Horizontal starting position of the background. top Vertical starting position of the background. pImage Pointer to the background image used. Set this to NULL if not used. color If the background image is NULL, background is assumed to be this color. Returns None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-831 Example None. 5.2.2.7.21.14 GFX_BackgroundTypeGet Function C GFX_BACKGROUND_TYPE GFX_BackgroundTypeGet(); Description This function returns the type of the current background. Preconditions None. Returns The type of the current background set. Example None. 5.2.2.7.21.15 GFX_BackgroundTypeSet Function C void GFX_BackgroundTypeSet( GFX_BACKGROUND_TYPE type ); Description This function sets the background type. Preconditions None. Parameters Parameters Description type Type of background that will be used. Returns None. Example None. 5.2.2.7.21.16 GFX_BarAlphaDraw Function C uint16_t GFX_BarAlphaDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-832 Description This function renders an alpha blended bar shape with the currently set color and the currently set background type (see GFX_BACKGROUND_TYPE). The parameters left, top, right bottom will define the shape dimension. The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left,top or right,bottom falls outside the frame buffer. • Colors are not set before this function is called. • When right < left • When bottom < top • When pixel locations defined by left, top and/or right, bottom are not on the frame buffer. Preconditions Color must be set by GFX_ColorSet(). Alpha blending value must be set by GFX_AlphaBlendingValueSet(). Parameters Parameters Description left defines the left most pixel of the shape. top defines the top most pixel of the shape. right defines the right most pixel of the shape. bottom defines the bottom most pixel of the shape. Returns TBA (see GFX_STATUS). Example // assume RED is a macro that define GFX_COLOR types GFX_STATUS status; // assume BackGroundImage is a valid image already draw // on the screen GFX_RESOURCE_HDR *pMyBackgroundImage = &BackGroundImage; // render an alpha blended bar with // the current contents of the frame buffer GFX_AlphaBlendingValueSet(50); GFX_BackgroundTypeSet(GFX_BACKGROUND_DISPLAY_BUFFER); GFX_ColorSet(RED); status = GFX_BarAlphaDraw(10, 110, 100, 200); // render an alpha blended bar with a background image GFX_AlphaBlendingValueSet(75); GFX_FillStyleSet(GFX_FILL_STYLE_ALPHA_COLOR); // color value here has no effect since the background set // is type GFX_BACKGROUND_IMAGE GFX_BackgroundSet(0, 0, pMyBackGroundImage, 0); GFX_BackgroundTypeSet(GFX_BACKGROUND_IMAGE); GFX_ColorSet(RED); status = GFX_BarAlphaDraw(10, 110, 100, 200); 5.2.2.7.21.17 GFX_BarDraw Function C GFX_STATUS GFX_BarDraw( 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-833 uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); Description This function renders a bar shape with: • solid color - when the fill style is set to GFX_FILL_STYLE_COLOR • alpha blended fill - when the fill style is set to GFX_FILL_STYLE_ALPHA_COLOR. Any other selected fill style will be ignored and will assume a solid color fill will be used. The parameters left, top, right bottom will define the shape dimension. When fill style is set to GFX_FILL_STYLE_ALPHA_COLOR, the bar can also be rendered with an option to select the type of background. Preconditions Fill style must be set by GFX_FillStyleSet() when alpha blended fill is desired. Color must be set by GFX_ColorSet(). Parameters Parameters Description left defines the left most pixel of the shape. top defines the top most pixel of the shape. right defines the right most pixel of the shape. bottom defines the bottom most pixel of the shape. Returns TBA (see GFX_STATUS). Example // assume RED is a macro that define GFX_COLOR types GFX_STATUS status; // assume BackGroundImage is a valid image already draw // on the screen GFX_RESOURCE_HDR *pMyBackgroundImage = &BackGroundImage; // render a RED bar GFX_FillStyleSet(GFX_FILL_STYLE_COLOR); GFX_ColorSet(RED); status = GFX_BarDraw(10, 110, 100, 200); // render an alpha blended bar with // the current contents of the frame buffer GFX_FillStyleSet(GFX_FILL_STYLE_ALPHA_COLOR); GFX_BackgroundTypeSet(GFX_BACKGROUND_DISPLAY_BUFFER); GFX_ColorSet(RED); status = GFX_BarDraw(10, 110, 100, 200); // render an alpha blended bar with a background image GFX_FillStyleSet(GFX_FILL_STYLE_ALPHA_COLOR); // color value here has no effect since the background set // is type GFX_BACKGROUND_IMAGE GFX_BackgroundSet(0, 0, pMyBackGroundImage, 0); GFX_BackgroundTypeSet(GFX_BACKGROUND_IMAGE); GFX_ColorSet(RED); status = GFX_BarDraw(10, 110, 100, 200); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-834 5.2.2.7.21.18 GFX_BarGradientDraw Function C GFX_STATUS GFX_BarGradientDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); Description This renders a bar onto the screen, but instead of one color, a gradient is drawn depending on the direction (GFX_GRADIENT_TYPE), length, and colors chosen. This function is a blocking call. Preconditions Gradient feature must be enabled. Parameters Parameters Description left x position of the left top corner. top y position of the left top corner. right x position of the right bottom corner. bottom y position of the right bottom corner. color1 start color for the gradient color2 end color for the gradient length From 0-100%. How much of a gradient is wanted direction Gradient Direction Returns Always returns a 1 since it is a blocking function. Side Effects none Remarks none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-835 Example // draw a full screen gradient background // with color transitioning from BRIGHTRED to // BLACK in the upward direction. GFX_GRADIENT_STYLE gradScheme; gradScheme.gradientType = GFX_GRADIENT_TYPE_UP; gradScheme.gradientStartColor = BRIGHTRED; gradScheme.gradientEndColor = BLACK; BarGradient(0, //left position 0, //top position GetMaxX(), //right position GetMaxY(), //bottom position gradScheme.gradientStartColor, gradScheme.gradientEndColor, 50, // at the halfway point (50%) of the rectangular area // defined by the first 4 parameters (full screen), // the color becomes BLACK and BLACK color is used until // the rectangle defined is filled up gradScheme.gradientType); // see GFX_GRADIENT_TYPE 5.2.2.7.21.19 GFX_BevelDraw Function C GFX_STATUS GFX_BevelDraw( uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2, uint16_t rad ); Description This is function GFX_BevelDraw. 5.2.2.7.21.20 GFX_BevelDrawTypeGet Function C GFX_BEVEL_RENDER_TYPE GFX_BevelDrawTypeGet(); 5.2.2.7.21.21 GFX_BevelDrawTypeSet Function C void GFX_BevelDrawTypeSet( GFX_BEVEL_RENDER_TYPE type ); 5.2.2.7.21.22 GFX_BevelGradientDraw Function C GFX_STATUS GFX_BevelGradientDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-836 uint16_t rad ); Description This renders a filled bevel with gradient color on the fill. It works the same as the fillbevel function, except a gradient out of color1 and color2 is drawn depending on the direction (GFX_GRADIENT_TYPE). This function is a blocking call. Preconditions Gradient feature must be enabled. Parameters Parameters Description left x coordinate position of the upper left center of the circle that draws the rounded corners. top y coordinate position of the upper left center of the circle that draws the rounded corners. right x coordinate position of the lower right center of the circle that draws the rounded corners. bottom y coordinate position of the lower right center of the circle that draws the rounded corners. rad defines the redius of the circle, that draws the rounded corners. When rad = 0, the object drawn is a rectangular gradient. color1 start color for the gradient color2 end color for the gradient length From 0-100%. How much of a gradient is wanted direction see GFX_GRADIENT_TYPE Returns Always returns a 1 since it is a blocking function. Side Effects none Remarks none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-837 5.2.2.7.21.23 GFX_CircleDraw Function C GFX_STATUS GFX_CircleDraw( uint16_t x, uint16_t y, uint16_t radius ); Description This function renders a circular shape using the center (x,y) and radius. The shape is rendered using the currently set line style by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). When x,y falls outside the buffer, the behavior is undefined. When color is not set before this function is called, the bahavior is undefined. When any of the following x+radius, x-radius, y+radius and y-radius falls outside the buffer, the behavior is undefined. Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description x defines the x-coordinate position of the center of the circle. y defines the y-coordinate position of the center of the circle. radius defines the radius of the circle. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.24 GFX_CircleFillDraw Function C GFX_STATUS GFX_CircleFillDraw( uint16_t x, uint16_t y, uint16_t radius ); Description This function renders a filled circle shape with the currently set fill style (see GFX_FILL_STYLE) with the given left, top, right and bottom parameters to define the shape dimension. The shape is rendered depending on the fill style. If a flat color is used, color must be set (see GFX_ColorSet()) before calling this function. If gradient color is used, gradient start and end color must be set (see GFX_GradientColorSet()) before calling this function. After the fill style and colors are set, multiple calls to this function can be performed. The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left,top or right,bottom falls outside the frame buffer. • Fill style is not set (GFX_FillStyleSet(), before this function is called. • Colors are not set before this function is called. • When the center defined by x,y is not on the frame buffer. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-838 Preconditions Fill style must be set by GFX_FillStyleSet(). Color must be set by GFX_ColorSet(). Parameters Parameters Description x defines the x-coordinate position of the center of the circle. y defines the y-coordinate position of the center of the circle. radius defines the radius of the circle. Returns TBA (see GFX_STATUS). Example // assume BLUE and RED are macros that define GFX_COLOR types GFX_STATUS status; APP_TEST_FillStyleSet(GFX_FILL_STYLE_GRADIENT_UP); GFX_GradientColorSet(BLUE, RED); status = GFX_CircleFillDraw(50, 110, 150, 200, 20); if (status == GFX_STATUS_SUCCESS) // Filled circle was drawn. else // Filled circle is not drawn or not yet // finished rendering. To finish the rendering call the // function again with the same parameters. 5.2.2.7.21.25 GFX_ColorGet Function C GFX_COLOR GFX_ColorGet(); Description This function returns the color currently set to render primitive shapes and text (See GFX_ColorSet() for more information). Preconditions None. Returns The currently set color. Example TBA 5.2.2.7.21.26 GFX_ColorSet Function C void GFX_ColorSet( GFX_COLOR newColor ); Description This function sets the color to be used to render primitive shapes and text. Any primitive shape that is set to any of the following: GFX_LINE_STYLE • GFX_LINE_STYLE_THIN_SOLID • GFX_LINE_STYLE_THIN_DOTTED 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-839 • GFX_LINE_STYLE_THIN_DASHED • GFX_LINE_STYLE_THICK_SOLID • GFX_LINE_STYLE_THICK_DOTTED • GFX_LINE_STYLE_THICK_DASHED GFX_FILL_STYLE • GFX_FILL_STYLE_COLOR will be rendered using the set color. Rendering text using the GFX_TextCharDraw(), GFX_TextStringDraw() and GFX_TextStringBoxDraw() will also use the set color. Preconditions None. Parameters Parameters Description color the rendering color set to render primitive shapes. Returns None. Example TBA 5.2.2.7.21.27 GFX_DoubleBufferAreaGet Function C GFX_RECTANGULAR_AREA * GFX_DoubleBufferAreaGet( uint16_t count ); 5.2.2.7.21.28 GFX_DoubleBufferAreaMark Function C void GFX_DoubleBufferAreaMark( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); 5.2.2.7.21.29 GFX_DoubleBufferDisable Function C GFX_STATUS GFX_DoubleBufferDisable(); 5.2.2.7.21.30 GFX_DoubleBufferEnable Function C GFX_STATUS GFX_DoubleBufferEnable(); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-840 5.2.2.7.21.31 GFX_DoubleBufferStatusGet Function C GFX_FEATURE_STATUS GFX_DoubleBufferStatusGet(); 5.2.2.7.21.32 GFX_DoubleBufferSyncAllStatusClear Function C GFX_STATUS GFX_DoubleBufferSyncAllStatusClear(); 5.2.2.7.21.33 GFX_DoubleBufferSyncAllStatusGet Function C GFX_FEATURE_STATUS GFX_DoubleBufferSyncAllStatusGet(); 5.2.2.7.21.34 GFX_DoubleBufferSyncAllStatusSet Function C GFX_STATUS GFX_DoubleBufferSyncAllStatusSet(); 5.2.2.7.21.35 GFX_DoubleBufferSyncAreaCountGet Function C unsigned int GFX_DoubleBufferSyncAreaCountGet(); 5.2.2.7.21.36 GFX_DoubleBufferSyncAreaCountSet Function C void GFX_DoubleBufferSyncAreaCountSet( unsigned int count ); 5.2.2.7.21.37 GFX_DoubleBufferSynchronize Function C GFX_STATUS GFX_DoubleBufferSynchronize(); 5.2.2.7.21.38 GFX_DoubleBufferSynchronizeCancel Function C GFX_STATUS GFX_DoubleBufferSynchronizeCancel(); 5.2.2.7.21.39 GFX_DoubleBufferSynchronizeRequest Function C GFX_STATUS GFX_DoubleBufferSynchronizeRequest(); 5.2.2.7.21.40 GFX_DoubleBufferSynchronizeSet Function C GFX_STATUS GFX_DoubleBufferSynchronizeSet(); 5.2.2.7.21.41 GFX_DoubleBufferSynchronizeStatusGet Function C GFX_FEATURE_STATUS GFX_DoubleBufferSynchronizeStatusGet(); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-841 5.2.2.7.21.42 GFX_DoubleBufferVisualPageUpdate Function C GFX_STATUS GFX_DoubleBufferVisualPageUpdate(); Description None Preconditions None Parameters Parameters Description None None Returns None Example None 5.2.2.7.21.43 GFX_DrawBufferGet Function C int GFX_DrawBufferGet(); 5.2.2.7.21.44 GFX_DrawBufferSelect Function C GFX_STATUS GFX_DrawBufferSelect( int index ); 5.2.2.7.21.45 GFX_DrawBufferSet Function C GFX_STATUS GFX_DrawBufferSet( int index, uint32_t address ); 5.2.2.7.21.46 GFX_DRV_FontSet Function C void GFX_DRV_FontSet( GFX_RESOURCE_HDR * pFont ); Description This is function GFX_DRV_FontSet. 5.2.2.7.21.47 GFX_DRV_TextStringWidthGet Function C uint16_t GFX_DRV_TextStringWidthGet( 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-842 GFX_XCHAR* textString, GFX_RESOURCE_HDR * pFont ); Description This is function GFX_DRV_TextStringWidthGet. 5.2.2.7.21.48 GFX_ExternalCharInfoGet Function C void GFX_ExternalCharInfoGet( GFX_XCHAR ch, GFX_FONT_OUTCHAR * pParam ); Description This is function GFX_ExternalCharInfoGet. 5.2.2.7.21.49 GFX_ExternalResourceCallback Function C GFX_STATUS GFX_ExternalResourceCallback( GFX_RESOURCE_HDR * pResource, uint32_t offset, uint16_t nCount, void * pBuffer ); Description This function must be implemented in the application. The library will call this function each time when the external memory data will be required. The application must copy requested uint8_ts quantity into the buffer provided. Data start address in external memory is a sum of the address in GFX_EXTDATA structure and offset. Parameters Parameters Description memory Pointer to the external memory bitmap or font structures (FONT_EXTERNAL or BITMAP_EXTERNAL). offset Data offset. nCount Number of uint8_ts to be transferred into the buffer. buffer Pointer to the buffer. Returns Returns the number of uint8_ts were transferred. Side Effects none Example // If there are several memories in the system they can be selected by IDs. // In this example, ID for memory device used is assumed to be 0. #define X_MEMORY 0 uint16_t ExternalMemoryCallback(GFX_IMAGE_HEADER* memory, int32_t offset, uint16_t nCount, void* buffer) { int i; long address; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-843 // Address of the requested data is a start address of the object referred by GFX_EXTDATA structure plus offset address = memory->address+offset; if(memory->ID == X_MEMORY){ // MemoryXReaduint8_t() is some function implemented to access external memory. // Implementation will be specific to the memory used. In this example // it reads uint8_t each time it is called. i = 0; while (i < nCount) { (uint8_t*)buffer = MemoryXReaduint8_t(address++); i++; } } // return the actual number of uint8_ts retrieved return (i); } 5.2.2.7.21.50 GFX_FillStyleGet Function C GFX_FILL_STYLE GFX_FillStyleGet(); Description This function returns the fill style used (see GFX_FILL_STYLE) when rendering filled shapes. Preconditions None. Returns The current fill style used (see GFX_FILL_STYLE). Example TBA 5.2.2.7.21.51 GFX_FillStyleSet Function C GFX_STATUS GFX_FillStyleSet( GFX_FILL_STYLE style ); Description This function sets the fill style to be used (see GFX_FILL_STYLE) when rendering filled shapes. All calls to the following: • GFX_RectangleFillDraw() • GFX_RectangleRoundFillDraw() • GFX_CircleFillDraw() will use the fill style set by this function. Preconditions None. Parameters Parameters Description style The specified fill style to be used. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-844 Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.52 GFX_FlashCharInfoGet Function C void GFX_FlashCharInfoGet( GFX_XCHAR ch, GFX_FONT_OUTCHAR * pParam ); Description This is function GFX_FlashCharInfoGet. 5.2.2.7.21.53 GFX_FontAntiAliasGet Function C GFX_FONT_ANTIALIAS_TYPE GFX_FontAntiAliasGet(); Description This function returns the font anti-aliasing mode used when rendering anti-aliased strings and characters. Default setting at initialization is GFX_FONT_ANTIALIAS_OPAQUE. Preconditions None. Returns The font anti-aliasing mode used. Example TBA 5.2.2.7.21.54 GFX_FontAntiAliasSet Function C GFX_STATUS GFX_FontAntiAliasSet( GFX_FONT_ANTIALIAS_TYPE type ); Description This function sets the font anti-aliasing mode used when rendering anti-aliased strings and characters. Preconditions None. Parameters Parameters Description type anti-aliasing mode selected. See GFX_FONT_ANTIALIAS_TYPE for details. Returns The status of the set anti-aliasing mode action. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-845 Example TBA 5.2.2.7.21.55 GFX_FontGet Function C GFX_RESOURCE_HDR* GFX_FontGet(); Description This function returns the current font used to render strings and characters. Preconditions GFX_FontSet() must be called prior to any call to this function. If this function is called first, the returned value is undefined. Returns The pointer to the current font used in rendering strings and characters. Example TBA 5.2.2.7.21.56 GFX_FontSet Function C GFX_STATUS GFX_FontSet( GFX_RESOURCE_HDR * pFont ); Description This function sets the current font used to render strings and characters. Preconditions None. Parameters Parameters Description pFont pointer to the font to be used. Returns The status of the set font action. Example TBA 5.2.2.7.21.57 GFX_FrameBufferGet Function C int GFX_FrameBufferGet(); 5.2.2.7.21.58 GFX_FrameBufferSelect Function C GFX_STATUS GFX_FrameBufferSelect( int index ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-846 5.2.2.7.21.59 GFX_GradientColorSet Function C GFX_STATUS GFX_GradientColorSet( GFX_COLOR startColor, GFX_COLOR endColor ); Description This function sets the gradient fill start and end colors (see GFX_FILL_STYLE) when rendering gradient filled shapes. All subsequent calls to the following using gradient fills: • GFX_RectangleFillDraw() • GFX_RectangleRoundFillDraw() • GFX_CircleFillDraw() will use the start and end colors set by this function. Preconditions None. Parameters Parameters Description startColor Gradient start color to be used. endColor Gradient end color to be used. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.60 GFX_GradientEndColorGet Function C GFX_COLOR GFX_GradientEndColorGet(); Description This function returns the end color used when rendering gradient filled shapes. Preconditions None. Returns The current gradient end color used. Example TBA 5.2.2.7.21.61 GFX_GradientStartColorGet Function C GFX_COLOR GFX_GradientStartColorGet(); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-847 Description This function returns the start color used when rendering gradient filled shapes. Preconditions None. Returns The current gradient start color used. Example TBA 5.2.2.7.21.62 GFX_ImageDraw Function C GFX_STATUS GFX_ImageDraw( uint16_t left, uint16_t top, GFX_RESOURCE_HDR * pImage ); Description This function renders an image to the frame buffer with the left-top corner of the image located at given left, top parameters. The rendering of this shape becomes undefined when any one of the following is true: • left, top pixel position falls outside the frame buffer. • pointer is not properly initialized to a GFX_RESOURCE_HDR object. Preconditions None. Parameters Parameters Description left Horizontal starting position of the image. top Vertical starting position of the image. pImage Pointer to the image to be rendered. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.63 GFX_ImageHeaderGet Function C inline void GFX_ImageHeaderGet( GFX_RESOURCE_HDR * pImage, GFX_MCHP_BITMAP_HEADER * pBitmapHdr ); Description This function fills the given bitmap header with the image's header information. This function results in an undefined behavior if the pointer to the image is invalid. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-848 Preconditions None. Parameters Parameters Description pImage Pointer to the image. pBitmap Pointer to the destination of the header information. Returns None. Example TBA 5.2.2.7.21.64 GFX_ImageHeightGet Function C inline int16_t GFX_ImageHeightGet( GFX_RESOURCE_HDR * pImage ); Description This function returns the height of the given image in pixels. This function results in an undefined behavior if the pointer to the image is invalid. This function return value is undefined if the given pointer does not point to a valid image resource. Preconditions None. Parameters Parameters Description pImage Pointer to the image. Returns The image height in pixels. Example TBA 5.2.2.7.21.65 GFX_ImageOffsetAddressGet Function C uint32_t GFX_ImageOffsetAddressGet( uint32_t address, uint16_t xOffset, uint16_t yOffset, uint16_t width ); Description This is function GFX_ImageOffsetAddressGet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-849 5.2.2.7.21.66 GFX_ImagePartialDraw Function C GFX_STATUS GFX_ImagePartialDraw( uint16_t destination_x, uint16_t destination_y, uint16_t source_x_offset, uint16_t source_y_offset, uint16_t source_width, uint16_t source_height, GFX_RESOURCE_HDR * pImage ); Description This function renders an image or a portion of an image to the frame buffer with the top, left corner of the image located at destination_x, destination_y. To render a full image, source_x_offset, source_y_offset, width and height are set to all 0. Using the actual image's width and height will also work if these are known. If they are not known, avoid the extra extra step to get the image's width and height by assigning 0 to the parameters. Another way to render a full image is to use the GFX_ImageDraw(). The image to be rendered is defined by the pointer pImage. The rendering of this shape becomes undefined when any one of the following is true: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-850 • destination_x, destination_y pixel position falls outside the frame buffer. • source_x_offset, source_y_offset results in a starting position beyond the image's dimension. • source_width and/or source_height is larger than the actual image's width and height. • pointer is not properly initialized to a GFX_RESOURCE_HDR object. Preconditions None. Parameters Parameters Description destination_x Horizontal starting position of the image. destination_y Vertical starting position of the image. source_x_offset Horizontal offset in pixels of the starting position of the partial area of the image to be rendered. Set to 0 along with source_y_offset when rendering the full image. source_y_offset Vertical offset in pixels of the starting position of the partial area of the image to be rendered. Set to 0 along with source_x_offset when rendering the full image. source_width The width of the partial area of the image to be rendered. Set to 0 along with source_height when rendering the full image. source_height The height of the partial area of the image to be rendered. Set to 0 along with source_width when rendering the full image. pImage Pointer to the image to be rendered. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.67 GFX_ImageWidthGet Function C inline int16_t GFX_ImageWidthGet( GFX_RESOURCE_HDR * pImage ); Description This function returns the width of the given image in pixels. This function results in an undefined behavior if the pointer to the image is invalid. This function return value is undefined if the given pointer does not point to a valid image resource. Preconditions None. Parameters Parameters Description pImage Pointer to the image. Returns The image width in pixels. Example TBA 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-851 5.2.2.7.21.68 GFX_Initialize Function C void GFX_Initialize(); Description This function initialize the Graphics Library primitive layer and Graphics Object Layer if it is enabled. The following default settings are set when this function is called. 1. font - Set to NULL. GFX_FontSet() must be called prior to any text rendering. 2. line type - Set to GFX_LINE_TYPE_THIN_SOLID (see GFX_LINE_STYLE). 3. fill type - Set to GFX_FILL_TYPE_COLOR (see GFX_FILL_STYLE). 4. text anti-alias type - Set to GFX_FONT_ANTIALIAS_OPAQUE (see GFX_FONT_ANTIALIAS_TYPE). This only affects fonts with anti-aliasing enabled. This function does not clear the screen and does not assign any color to the currently set color. Application should set the color and clear the screen. Preconditions None. Returns None. Example TBA 5.2.2.7.21.69 GFX_Layer Function C GFX_STATUS GFX_Layer( uint8_t layer, uint8_t action, uint16_t param1, uint16_t param2 ); Description None Preconditions None Parameters Parameters Description None None Returns None Example None 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-852 5.2.2.7.21.70 GFX_LineDraw Function C GFX_STATUS GFX_LineDraw( uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2 ); Description This function renders a line from x1,y1 to x2,y2 using the currently set line style set by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). If x1,y1 and/or x2,y2 is not on the frame buffer, then the behavior is undefined. If color is not set, before this function is called, the output is undefined. Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description x1 x coordinate of the line start point. y1 y coordinate of the line start point. x2 x coordinate of the line end point. y2 y coordinate of the line end point. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.71 GFX_LinePositionRelativeSet Function C GFX_STATUS GFX_LinePositionRelativeSet( int16_t x, int16_t y ); Description This function sets the line cursor to a new (x,y) position relative to the current cursor position. The new position is calculated by (x+dX, y + dY). Line cursor is used as a starting point of the line rendered by the GFX_LineToDraw() and GFX_LineToRelativeDraw() functions. Note that the parameters dX and dY are signed integers. This allows the new line cursor position to be placed to any direction from the current line cursor position. If (x+dX) and/or (y+dY) results in a position that is not on the frame buffer, then the behavior of GFX_LineToDraw() and GFX_LineToRelativeDraw() functions are undefined. If color is not set, before this function is called, the output is undefined. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-853 Parameters Parameters Description dX the offset for the x position that will define the new x-coordinate position of the line cursor. dY the offset for the y position that will define the new y-coordinate position of the line cursor. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.72 GFX_LinePositionSet Function C GFX_STATUS GFX_LinePositionSet( uint16_t x, uint16_t y ); Description This function sets the line cursor to a new (x,y) position. Line cursor is used as a starting point of the line rendered by the GFX_LineToDraw() and GFX_LineToRelativeDraw() functions. If x and/or y does not lie on the frame buffer, then the behavior of GFX_LineToDraw() and GFX_LineToRelativeDraw() functions are undefined. Preconditions None. Parameters Parameters Description x new x coordinate position of the line cursor. y new y coordinate position of the line cursor. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.73 GFX_LinePositionXGet Function C int16_t GFX_LinePositionXGet(); Description This function returns the current x position of the line cursor. Line cursor is used as a starting point of the line rendered by the GFX_LineToDraw() and GFX_LineToRelativeDraw() functions. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-854 Returns The current line cursor x position. Example TBA 5.2.2.7.21.74 GFX_LinePositionYGet Function C int16_t GFX_LinePositionYGet(); Description This function returns the current y position of the line cursor. Line cursor is used as a starting point of the line rendered by the GFX_LineToDraw() and GFX_LineToRelativeDraw() functions. Preconditions None. Returns The current line cursor y position. Example TBA 5.2.2.7.21.75 GFX_LineStyleGet Function C GFX_LINE_STYLE GFX_LineStyleGet(); Description This function returns the line style used (see GFX_LINE_STYLE) when rendering lines. Preconditions None. Returns The current line style used (see GFX_LINE_STYLE). Example TBA 5.2.2.7.21.76 GFX_LineStyleSet Function C GFX_STATUS GFX_LineStyleSet( GFX_LINE_STYLE style ); Description This function sets the line style to be used (see GFX_LINE_STYLE) when rendering lines. All calls to the following functions • GFX_LineDraw() • GFX_LineToDraw() • GFX_LineToRelativeDraw() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-855 • GFX_CircleDraw() • GFX_RectangleDraw() • GFX_PolygonDraw() will use the line style set by this function. In addition, all unfilled shapes that does specify the line style to be used will use the line style specified by this function. Preconditions None. Parameters Parameters Description style The specified line style to be used. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.77 GFX_LineToDraw Function C GFX_STATUS GFX_LineToDraw( int16_t x2, int16_t y2 ); Description This function renders a line from current line cursor position (x,y) to (x2,y2) using the currently set line style set by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). If x2 and/or y2 does not lie on the frame buffer, then the behavior is undefined. If color is not set, before this function is called, the output is undefined. Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description x2 x coordinate of the line end point. y2 y coordinate of the line end point. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.78 GFX_LineToRelativeDraw Function C GFX_STATUS GFX_LineToRelativeDraw( int16_t dX, int16_t dY 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-856 ); Description This function renders a line from current line cursor position (x,y) to (x+dX,y+dY) using the currently set line style set by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). Note that the parameters dX and dY are signed integers. This allows the line to be drawn from the line cursor to any direction. If (x+dX) and/or (y+dY) results in a position that is not on the frame buffer, then the behavior is undefined. If color is not set, before this function is called, the output is undefined. Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description dX the offset for the x starting position that will define the x-coordinate of the end of the line. dY the offset for the y starting position that will define the y-coordinate of the end of the line. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.79 GFX_PageSet Function C GFX_STATUS GFX_PageSet( uint8_t pageType, uint8_t page ); Example Remarks: 5.2.2.7.21.80 GFX_PolygonDraw Function C GFX_STATUS GFX_PolygonDraw( uint16_t numPoints, uint16_t * polyPoints ); Description This function renders a polygon using the currently set line style (see GFX_LineStyleSet()) and color (see GFX_ColorSet()). The shape of the polygon is determined by the polygon points (an ordered array of x,y pairs) where the pair count is equal to the parameter sides. If any of the x,y pairs do not lie on the frame buffer, then the behavior is undefined. If color is not set, before this function is called, the output is undefined. Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-857 Parameters Parameters Description sides the number of sides of the polygon. pPoints Pointer to the array of polygon points. The array defines the x,y points of the polygon. The sequence should be x0, y0, x1, y1, x2, y2, ... xn, yn where n is the # of polygon sides. Returns TBA (see GFX_STATUS). Example uint16_t OpenShapeXYPoints[6] = {10, 10, 20, 10, 20, 20}; uint16_t ClosedShapeXYPoints[8] = {10, 10, 20, 10, 20, 20, 10, 10}; GFX_ColorSet(WHITE); // set color SetLineType(GFX_LINE_STYLE_THIN_DOTTED); // set line style GFX_PolygonDraw(3, OpenShapeXYPoints); // draw an open shape GFX_PolygonDraw(4, ClosedShapeXYPoints); // draw a closed shape 5.2.2.7.21.81 GFX_Primitive_Initialize Function C inline void GFX_Primitive_Initialize(); Description This is function GFX_Primitive_Initialize. 5.2.2.7.21.82 GFX_RectangleDraw Function C GFX_STATUS GFX_RectangleDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); Description This function renders a rectangular shape using the given left, top, right and bottom parameters to define the shape dimension. The shape is rendered using the currently set line style by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left,top, right,bottom falls outside the frame buffer. • Color is not set, before this function is called. • right < left • bottom < top Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description left defines the left most pixel of the shape. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-858 top defines the top most pixel of the shape. right defines the right most pixel of the shape. bottom defines the bottom most pixel of the shape. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.83 GFX_RectangleFillDraw Function C GFX_STATUS GFX_RectangleFillDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom ); Description This function renders a filled rectangular shape with the currently set fill style (see GFX_FILL_STYLE) with the given left, top, right, and bottom parameters to define the shape dimension. The shape is rendered depending on the fill style. If a flat color is used, color must be set (see GFX_ColorSet()) before calling this function. If gradient color is used, gradient start and end color must be set (see GFX_GradientColorSet()) before calling this function. After the fill style and colors are set, multiple calls to this function can be performed. The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left,top or right,bottom falls outside the frame buffer. • Fill style is not set (GFX_FillStyleSet(), before this function is called. • Colors are not set before this function is called. • When right < left • When bottom < top • When pixel locations defined by left, top and/or right, bottom are not on the frame buffer. Preconditions Fill style must be set by GFX_FillStyleSet(). Color must be set by GFX_ColorSet(). Parameters Parameters Description left defines the left most pixel of the shape. top defines the top most pixel of the shape. right defines the right most pixel of the shape. bottom defines the bottom most pixel of the shape. Returns TBA (see GFX_STATUS). Example // assume BLUE and RED are macros that define GFX_COLOR types GFX_STATUS status; // render a rectangle with gradient colors from BLUE to RED 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-859 GFX_FillStyleSet(GFX_FILL_STYLE_GRADIENT_LEFT); GFX_GradientColorSet(BLUE, RED); status = GFX_RectangleFillDraw(10, 110, 100, 200); // render an alpha blended rounded rectangle with // the current contents of the frame buffer GFX_FillStyleSet(GFX_FILL_STYLE_ALPHA_COLOR); GFX_AlphaBlendingValueSet(50); GFX_BackgroundTypeSet(GFX_BACKGROUND_DISPLAY_BUFFER); GFX_ColorSet(RED); status = GFX_RectangleRoundFillDraw(10, 110, 100, 200); // render an alpha blended rectangle with an image GFX_FillStyleSet(GFX_FILL_STYLE_ALPHA_COLOR); GFX_AlphaBlendingValueSet(50); GFX_BackgroundTypeSet(GFX_BACKGROUND_IMAGE); GFX_ColorSet(RED); status = GFX_RectangleFillDraw(10, 110, 100, 200); // render a plain RED rounded rectangle GFX_FillStyleSet(GFX_FILL_STYLE_COLOR); GFX_ColorSet(RED); status = GFX_RectangleFillDraw(10, 110, 100, 200); 5.2.2.7.21.84 GFX_RectangleRoundDraw Function C GFX_STATUS GFX_RectangleRoundDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t radius ); Description This function renders a rectangular shape with rounded corner using the given left, top, right, bottom and radius parameters to define the shape dimension. radius defines the rounded corner shape. The shape is rendered using the currently set line style by GFX_LineStyleSet(). The color used is the color set by the last call to GFX_ColorSet(). Left most pixel location is defined by left - radius. Top most pixel location is defined by top - radius. Right most pixel location is defined by right + radius. Bottom most pixel location is defined by bottom + radius. When radius = 0, there are no rounded corners. In this case (left,top) will define the left, top corner and (right,bottom) will define the right, bottom corner of the shape. When left = right and top = bottom, with radius > 0, a circular object is drawn. When left < right and top < bottom and radius = 0, a rectangular object is drawn. The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left-rad , top-rad, right+rad, bottom+rad falls outside the frame buffer. • Color is not set, before this function is called. • right < left • bottom < top Preconditions Color must be set by GFX_ColorSet(). Line style must be set by GFX_LineStyleSet(). Parameters Parameters Description left Along with rad (left - rad), defines the left most pixel of the shape. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-860 top Along with rad (top - rad), defines the top most pixel of the shape. right Along with rad (right + rad), defines the right most pixel of the shape. bottom Along with rad (bottom + rad), defines the bottom most pixel of the shape. radius defines the rounded corners. When this is set to zero, there will be no rounded corners. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.85 GFX_RectangleRoundFillDraw Function C GFX_STATUS GFX_RectangleRoundFillDraw( uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint16_t radius ); Description This function renders a filled rounded rectangular shape with the currently set fill style (see GFX_FILL_STYLE) with the given left, top, right, bottom and radius parameters to define the shape dimension. The shape is rendered depending on the fill style. If a flat color is used, color must be set (see GFX_ColorSet()) before calling this function. If gradient color is used, gradient start and end color must be set (see GFX_GradientColorSet()) before calling this function. After the fill style and colors are set, multiple calls to this function can be performed. The rendering of this shape becomes undefined when any one of the following is true: • Any of the following pixel locations left,top or right,bottom falls outside the frame buffer. • Fill style is not set (GFX_FillStyleSet(), before this function is called. • Colors are not set before this function is called. • When right < left • When bottom < top • When pixel locations defined by left, top and/or right, bottom are not on the frame buffer. Preconditions Fill style must be set by GFX_FillStyleSet(). Color must be set by GFX_ColorSet(). Parameters Parameters Description left defines the left most pixel of the shape. top defines the top most pixel of the shape. right defines the right most pixel of the shape. bottom defines the bottom most pixel of the shape. radius defines the radius of the rounded corner. A zero value will result in a rectangular shape drawn. Returns TBA (see GFX_STATUS). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-861 Example // assume BLUE and RED are macros that define GFX_COLOR types GFX_STATUS status; APP_TEST_FillStyleSet(GFX_FILL_STYLE_GRADIENT_DOUBLE_VER); GFX_GradientColorSet(BLUE, RED); status = GFX_RectangleFillDraw(50, 110, 150, 200, 20); if (status == GFX_STATUS_SUCCESS) // Filled rounded rectangle shape was drawn. else // Filled rounded rectangle shape is not drawn or not yet // finished rendering. To finish the rendering call the // function again with the same parameters. 5.2.2.7.21.86 GFX_RenderingBufferGet Function C GFX_COLOR * GFX_RenderingBufferGet(); Description Returns the location of the internal rendering buffer used in rendering images and filled objects with alpha blending. Preconditions None. Returns The address of the rendering buffer. Example None. 5.2.2.7.21.87 GFX_RenderToDisplayBufferDisable Function C void GFX_RenderToDisplayBufferDisable(); Description This is function GFX_RenderToDisplayBufferDisable. 5.2.2.7.21.88 GFX_RenderToDisplayBufferDisableFlagGet Function C uint16_t GFX_RenderToDisplayBufferDisableFlagGet(); Description This is function GFX_RenderToDisplayBufferDisableFlagGet. 5.2.2.7.21.89 GFX_RenderToDisplayBufferEnable Function C void GFX_RenderToDisplayBufferEnable(); Description This is function GFX_RenderToDisplayBufferEnable. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-862 5.2.2.7.21.90 GFX_ScreenClear Function C GFX_STATUS GFX_ScreenClear(); Description This function clears the screen with the current color and sets the line cursor position to (0, 0). If color is not set, before this function is called, the output is undefined. If the function returns GFX_STATUS_FAILURE, clearing is not yet finished. Application must call the function again to continue the clearing. Preconditions Color must be set by GFX_ColorSet(). None. Returns The status of the screen clearing. • GFX_STATUS_SUCCESS - screen was cleared. • GFX_STATUS_FAILURE - screen is not yet cleared Example TBA 5.2.2.7.21.91 GFX_SetTransitionParameters Function C uint8_t GFX_SetTransitionParameters( short left, short top, GFX_TRANSITION_TYPE type, uint8_t sourcePage, uint8_t destinationPage, uint16_t delay_ms, uint16_t param1, uint16_t param2 ); Description This sets up the transition effect using the GFX_TRANSITION_TYPE and the given parameters. The actual transition execution will occur when GFXExecutePendingTransition() is called. When DOUBLE_BUFFERING is enabled, GFXExecutePendingTransition() is executed after the current screen is fully rendered. Parameters Parameters Description left left x coordinate top top y coordinate right right x coordinate bottom bottom y coordinate type Transition type delay_ms Delay in milli seconds between redraws in the screen while executing the transition param1 Transition-type specific parameter 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-863 param2 Transition-type specific parameter Returns Returns success of the setup • 0 : Parameters successfully saved for the new transition • -1 : Parameters not saved, there is a pending transition 5.2.2.7.21.92 GFX_SolidLineDraw Function C GFX_STATUS GFX_SolidLineDraw( uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2 ); Description This is function GFX_SolidLineDraw. 5.2.2.7.21.93 GFX_StyledLineDraw Function C GFX_STATUS GFX_StyledLineDraw( uint16_t x1, uint16_t y1, uint16_t x2, uint16_t y2 ); Description This is function GFX_StyledLineDraw. 5.2.2.7.21.94 GFX_TextAreaBottomGet Function C uint16_t GFX_TextAreaBottomGet(); Description This is function GFX_TextAreaBottomGet. 5.2.2.7.21.95 GFX_TextAreaBottomSet Function C void GFX_TextAreaBottomSet( uint16_t bottom ); Description This is function GFX_TextAreaBottomSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-864 5.2.2.7.21.96 GFX_TextAreaLeftGet Function C uint16_t GFX_TextAreaLeftGet(); Description This is function GFX_TextAreaLeftGet. 5.2.2.7.21.97 GFX_TextAreaLeftSet Function C void GFX_TextAreaLeftSet( uint16_t left ); Description This is function GFX_TextAreaLeftSet. 5.2.2.7.21.98 GFX_TextAreaRightGet Function C uint16_t GFX_TextAreaRightGet(); Description This is function GFX_TextAreaRightGet. 5.2.2.7.21.99 GFX_TextAreaRightSet Function C void GFX_TextAreaRightSet( uint16_t right ); Description This is function GFX_TextAreaRightSet. 5.2.2.7.21.100 GFX_TextAreaTopGet Function C uint16_t GFX_TextAreaTopGet(); Description This is function GFX_TextAreaTopGet. 5.2.2.7.21.101 GFX_TextAreaTopSet Function C void GFX_TextAreaTopSet( uint16_t top ); Description This is function GFX_TextAreaTopSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-865 5.2.2.7.21.102 GFX_TextCharDraw Function C GFX_STATUS GFX_TextCharDraw( GFX_XCHAR ch ); Description This function renders the given character using the currently set font, and color to the location defined by the text cursor position. The color is set by GFX_ColorSet() while the font is set by GFX_FontSet(). The text cursor position is set by GFX_TextCursorPositionSet() The rendering of the character becomes undefined when any one of the following is true: • Text cursor position is set to locations outside the frame buffer. • Color is not set, before this function is called. • Font is not set, before this function is called. Preconditions Color must be set by GFX_ColorSet(). Font must be set by GFX_FontSet(). Text cursor position must be set by GFX_TextCursorPositionSet(). Parameters Parameters Description ch character ID that of the character that will be rendered. Returns The status of the character rendering. • GFX_STATUS_SUCCESS - the character was rendered • GFX_STATUS_FAILURE - the character was not rendered, function must be called again to render the character. • GFX_STATUS_ERROR - the character ID passed is not a valid or points to the character glyph that does does not exist on the font table. Example // assume textString is a string of characters static uint16_t counter = 0; GFX_XCHAR ch; GFX_STATUS status; // render characters until null character while((GFX_XCHAR)(ch = *(textString + counter)) != 0) { status = GFX_TextCharDraw(ch); if (status != GFX_STATUS_SUCCESS) return (GFX_STATUS_FAILURE); counter++; } 5.2.2.7.21.103 GFX_TextCursorPositionSet Function C GFX_STATUS GFX_TextCursorPositionSet( int16_t x, int16_t y ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-866 Description This function sets the text cursor to a new (x,y) position. Text cursor is used as a starting point of the character rendered by the GFX_TextCharDraw() function. If x and/or y does not lie on the frame buffer, then the behavior of GFX_TextCharDraw() function is undefined. Preconditions None. Parameters Parameters Description x new x coordinate position of the text cursor. y new y coordinate position of the text cursor. Returns TBA (see GFX_STATUS). Example TBA 5.2.2.7.21.104 GFX_TextCursorPositionXGet Function C int16_t GFX_TextCursorPositionXGet(); Description This function returns the current x position of the text cursor. Text cursor is used as a starting point of the line rendered by the GFX_TextCharDraw() function. Preconditions None. Returns The current text cursor x position. Example TBA 5.2.2.7.21.105 GFX_TextCursorPositionYGet Function C int16_t GFX_TextCursorPositionYGet(); Description This function returns the current y position of the text cursor. Text cursor is used as a starting point of the line rendered by the GFX_TextCharDraw() function. Preconditions None. Returns The current text cursor y position. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-867 Example TBA 5.2.2.7.21.106 GFX_TextStringBoxDraw Function C GFX_STATUS GFX_TextStringBoxDraw( uint16_t x, uint16_t y, uint16_t width, uint16_t height, GFX_XCHAR * pString, GFX_ALIGNMENT align ); Description This function renders the given string using the currently color and font into the rectangular area defined by the given parameters x,y, width and height. The x,y parameters defines the left, top pixel position of the rectangular area. The width and height defines the size of the rectangular area. The rectangular area will define the area where the text will be rendered. Meaning all pixels EXCLUSIVE of the defined rectangle will be the rendering area for the text. If the given string exceeds the rectangular area, any pixels falling outside and along the defined rectangle (INCLUSIVE of the rectangle) will not be drawn. The color is set by GFX_ColorSet() while the font is set by GFX_FontSet(). Multiple lines of strings can be rendered. To define string composed of multiple lines, end each line with a new line character (character ID 0x0A). Each line will be rendered according to the text alignment (See GFX_TEXT_ALIGNMENT). The rendering of the character becomes undefined when any one of the following is true: • x, y, width and height defines an area partially or fully outside outside the frame buffer. • Color is not set, before this function is called. • Font is not set, before this function is called. Preconditions Color must be set by GFX_ColorSet(). Font must be set by GFX_FontSet(). Parameters Parameters Description x Horizontal starting position of the rectangular area. y Vertical position position of the rectangular area. width Defines the width of the rectangular area. height Defines the height of the rectangular area. pString Pointer to the location of the string that will be rendered. String can have multiple lines where each line is terminated by a new line character. Returns The status of the string rendering. • GFX_STATUS_SUCCESS - the string was rendered • GFX_STATUS_FAILURE - the string was not rendered, or is not yet finished. The function must be called again to render the remaining characters or lines. Example TODO :need to add example code 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-868 5.2.2.7.21.107 GFX_TextStringDraw Function C GFX_STATUS GFX_TextStringDraw( uint16_t x, uint16_t y, GFX_XCHAR * textString ); Description This function renders the given string of character using the currently set font, and color to the location defined by the given x,y position. The color is set by GFX_ColorSet() while the font is set by GFX_FontSet(). The rendering of the character becomes undefined when any one of the following is true: • x,y position is set to locations outside the frame buffer. • Color is not set, before this function is called. • Font is not set, before this function is called. Preconditions Color must be set by GFX_ColorSet(). Font must be set by GFX_FontSet(). Parameters Parameters Description x Horizontal starting position of the string. y Vertical position position of the string. pString Pointer to the location of the string that will be rendered. Returns The status of the string rendering. • GFX_STATUS_SUCCESS - the string was rendered • GFX_STATUS_FAILURE - the string was not rendered, or is not yet finished. The function must be called again to render the remaining characters. Example // assume textString is a string of characters static uint16_t counter = 0; GFX_XCHAR ch; GFX_STATUS status; // render characters until null character while((GFX_XCHAR)(ch = *(textString + counter)) != 0) { status = GFX_TextCharDraw(ch); if (status != GFX_STATUS_SUCCESS) return (GFX_STATUS_FAILURE); counter++; } 5.2.2.7.21.108 GFX_TextStringHeightGet Function C inline uint16_t GFX_TextStringHeightGet( GFX_RESOURCE_HDR * pFont ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-869 Description This function returns the height of the given font in pixels. The given font must be present in the system. This function return value is undefined if the given pointer does not point to a valid font. Preconditions None. Parameters Parameters Description pFont Pointer to the specified font. Returns The height of the specified font in pixels. Example // assume pMyFont is a pointer initialized to a valid font uint16_t height, x, y; // center the text on the screen height = GFX_TextStringHeightGet(pMyFont); width = GFX_TextStringWidthGet ( (GFX_XCHAR *)"Hello World", pMyFont ); y = (GFX_MaxYGet() - height) >> 1; x = (GFX_MaxXGet() - width) >> 1; GFX_TextStringDraw(x, y, (GFX_XCHAR *)"Hello World"); GFX_TextStringDraw(x, y, (GFX_XCHAR *)"Hello World"); 5.2.2.7.21.109 GFX_TextStringWidthGet Function C uint16_t GFX_TextStringWidthGet( GFX_XCHAR * textString, GFX_RESOURCE_HDR * pFont ); Description This function returns the width of the given string using the given font in pixels. The given font must be present in the system. This function return value is undefined if the given pointer does not point to a valid font or one or more characters in the given string does not exist on the given font. Preconditions None. Parameters Parameters Description pString Pointer to the specified string. pFont Pointer to the specified font. Returns The width of the specified string using the specified font in pixels. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-870 Example // assume pMyFont is a pointer initialized to a valid font uint16_t height, x, y; // center the text on the screen height = GFX_TextStringHeightGet(pMyFont); width = GFX_TextStringWidthGet ( (GFX_XCHAR *)"Hello World", pMyFont ); y = (GFX_MaxYGet() - height) >> 1; x = (GFX_MaxXGet() - width) >> 1; GFX_TextStringDraw(x, y, (GFX_XCHAR *)"Hello World"); 5.2.2.7.21.110 GFX_ThickBevelDraw Function C uint16_t GFX_ThickBevelDraw( uint16_t xL, uint16_t yT, uint16_t xR, uint16_t yB, uint16_t r1, uint16_t r2, uint8_t octant ); Description This is function GFX_ThickBevelDraw. 5.2.2.7.21.111 GFX_Transition Function C GFX_STATUS GFX_Transition( GFX_TRANSITION_PARAMS* transitionParams, short width, short height ); Description This immediately executes the transition effect using the GFX_TRANSITION_TYPE and the given parameters. Returns Returns status of transition • 0 : Transition executed successfully • -1 : Transition not executed 5.2.2.7.21.112 GFX_TransparentColorDisable Function C GFX_STATUS GFX_TransparentColorDisable(); Description This function disables the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. The transparent color feature can only be enabled when the color depth used is 24 or 16 bpp. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-871 Preconditions Transparent color feature must be enabled at build time. This is enabled by default and can be disabled by defining the macro GFX_CONFIG_TRANSPARENT_COLOR_DISABLE in the system. Returns The status of the transparent color disable action. Example // assume ScreenBackground and RibbonIcon are valid // image resources // assume BLACK is a valid GFX_COLOR value GFX_TransparentColorEnable(BLACK); GFX_ImageDraw(0,0, (void*)&ScreenBackground); GFX_ImageDraw(50,50, (void*)&RibbonIcon); // disable the transparent color feature since the // next image to render contains black pixels that // we want to render GFX_TransparentColorDisable(); GFX_ImageDraw(50,50, (void*)&OverlayImage); 5.2.2.7.21.113 GFX_TransparentColorEnable Function C GFX_STATUS GFX_TransparentColorEnable( GFX_COLOR color ); Description This function sets the transparent color used in GFX_ImageDraw() functions and enables the transparent color feature. When GFX_ImageDraw() or GFX_ImagePartialDraw() is called, any pixels in the image that matches the color value will not be rendered to the frame buffer. The transparent color feature can only be enabled when the color depth used is 24 or 16 bpp. Preconditions Transparent color feature must be enabled at build time. This is enabled by default and can be disabled by defining the macro GFX_CONFIG_TRANSPARENT_COLOR_DISABLE in the system. Parameters Parameters Description color the color value selected as the transparent color. Returns The status of the transparent color set action. Example // assume ScreenBackground and RibbonIcon are valid // image resources // assume BLACK is a valid GFX_COLOR value GFX_TransparentColorEnable(BLACK); GFX_ImageDraw(0,0, (void*)&ScreenBackground); GFX_ImageDraw(0,0, (void*)&RibbonIcon); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-872 5.2.2.7.21.114 GFX_TransparentColorGet Function C GFX_COLOR GFX_TransparentColorGet(); Description This returns the current transparent color set for the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. The transparent color feature can only be enabled when the color depth used is 24 or 16 bpp. Preconditions Transparent color feature must be enabled at build time. This is enabled by default and can be disabled by defining the macro GFX_CONFIG_TRANSPARENT_COLOR_DISABLE in the system. Returns The current transparent color used. Example // assume ScreenBackground and RibbonIcon are valid // image resources // assume BLACK is a valid GFX_COLOR value GFX_TransparentColorEnable(BLACK); GFX_ImageDraw(0,0, (void*)&ScreenBackground); GFX_ImageDraw(50,50, (void*)&RibbonIcon); // disable the transparent color feature since the // next image to render contains black pixels that // we want to render if (GFX_TransparentColorGet == BLACK) GFX_TransparentColorDisable(); GFX_ImageDraw(50,50, (void*)&OverlayImage); 5.2.2.7.21.115 GFX_TransparentColorStatusGet Function C GFX_FEATURE_STATUS GFX_TransparentColorStatusGet(); Description This returns the current transparent color set for the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. The transparent color feature can only be enabled when the color depth used is 24 or 16 bpp. Preconditions Transparent color feature must be enabled at build time. This is enabled by default and can be disabled by defining the macro GFX_CONFIG_TRANSPARENT_COLOR_DISABLE in the system. Returns The current transparent feature status (see GFX_FEATURE_STATUS for details). Example // assume ScreenBackground and RibbonIcon are valid // image resources // assume BLACK is a valid GFX_COLOR value if (GFX_TransparentColorStatusGet == GFX_FEATURE_DISABLED) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-873 GFX_TransparentColorEnable(BLACK); GFX_ImageDraw(0,0, (void*)&ScreenBackground); GFX_ImageDraw(50,50, (void*)&RibbonIcon); // disable the transparent color feature since the // next image to render contains black pixels that // we want to render if (GFX_TransparentColorGet == BLACK) GFX_TransparentColorDisable(); GFX_ImageDraw(50,50, (void*)&OverlayImage); 5.2.2.7.22 Image Functions 5.2.2.7.22.1 ImageDecoderInit Function C void ImageDecoderInit(); Description This function initializes the global variables to 0 and then initializes the driver. This must be called once before any other function of the library is called Returns None Side Effects The graphics driver will be reset Example void main(void) { ImageInit(); ... } 5.2.2.7.22.2 ImageDecodeTask Function C uint8_t ImageDecodeTask(); Description This function completes one small part of the image decode function Returns Status code - '1' means decoding is completed • '0' means decoding is not yet completed, call this function again Side Effects None Example IMG_bFullScreenDecode(pImageFile, IMG_JPEG, NULL, NULL); while(!ImageDecodeTask()); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-874 5.2.2.7.22.3 ImageLoopCallbackRegister Function C void ImageLoopCallbackRegister( IMG_LOOP_CALLBACK pFn ); Description This function registers the loop callback function so that the decoder calls this function in every decoding loop. This can be used by the application program to do maintainance activities such as fetching data, updating the display, etc... Returns None Side Effects The graphics driver will be reset Example void Mainantance(void) { ... } void main(void) { ImageInit(); ImageLoopCallbackRegister(Mainantance); ... } 5.2.2.7.22.4 IMG_vSetboundaries Function C void IMG_vSetboundaries(); Description ******* This is not for the user ******* This is used by the individual decoders 5.2.2.7.23 Palette Functions 5.2.2.7.23.1 IsPaletteEnabled Function C BYTE IsPaletteEnabled(); Description Returns if the Palette mode is enabled or not. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-875 Returns Returns the palette mode status. 1 - If the palette mode is enabled 0 - If the palette mode is disabled 5.2.2.7.23.2 PaletteInit Function C void PaletteInit(); Description Initializes the color look up table (CLUT). Preconditions none Returns none Side Effects All rendering will use the new palette entries. 5.2.2.7.23.3 RequestPaletteChange Function C void RequestPaletteChange( void * pPalette, uint16_t startEntry, uint16_t length ); Description Loads the palettes from the flash during vertical blanking period if possible, otherwise loads immediately. Preconditions Palette must be initialized by PaletteInit(). Parameters Parameters Description pPalette Pointer to the palette structure startEntry Start entry to load (inclusive) length Number of entries Returns none Side Effects There may be a slight flicker when the Palette entries are getting loaded one by one. 5.2.2.7.23.4 SetPalette Function C BYTE SetPalette( void * pPalette, uint16_t startEntry, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-876 uint16_t length ); Description Programs a block of palette entries starting from startEntry and until startEntry + length from the flash immediately. Preconditions Palette must be initialized by PaletteInit(). Parameters Parameters Description pPalette Pointer to the palette structure startEntry Start entry to load (inclusive) length Number of entries Returns Returns the status of the palette set. 0 - Set was successful 1 - Set was not successful Side Effects There may be a slight flicker when the Palette entries are getting loaded one by one. 5.2.2.7.23.5 SetPaletteBpp Function C BYTE SetPaletteBpp( uint8_t bpp ); Description Sets the color look up table (CLUT) number of valid entries. Preconditions Palette must be initialized by PaletteInit(). Parameters Parameters Description bpp Bits per pixel Returns Returns the status of the change. 0 - Change was successful 1 - Change was not successful Side Effects none 5.2.2.7.23.6 SetPaletteFlash Function C BYTE SetPaletteFlash( PALETTE_ENTRY * pPaletteEntry, uint16_t startEntry, uint16_t length ); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-877 Description Loads the palettes from the flash immediately. Preconditions Palette must be initialized by PaletteInit(). Parameters Parameters Description pPaletteEntry Pointer to the palette table in ROM startEntry Start entry to load (inclusive) length Number of entries Returns Returns the status of the palette set. 0 - Set was successful 1 - Set was not successful Side Effects There may be a slight flicker when the Palette entries are getting loaded one by one. 5.2.2.7.24 Style Scheme Functions 5.2.2.7.24.1 GFX_GOL_SchemeAlphaPrecentSet Function C inline void GFX_GOL_SchemeAlphaPrecentSet( GFX_GOL_OBJ_SCHEME * pScheme, uint16_t percent ); Description This is function GFX_GOL_SchemeAlphaPrecentSet. 5.2.2.7.24.2 GFX_GOL_SchemeBackgroundColorGet Function C inline GFX_COLOR GFX_GOL_SchemeBackgroundColorGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeBackgroundColorGet. 5.2.2.7.24.3 GFX_GOL_SchemeBackgroundColorSet Function C inline void GFX_GOL_SchemeBackgroundColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR color ); Description This is function GFX_GOL_SchemeBackgroundColorSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-878 5.2.2.7.24.4 GFX_GOL_SchemeBackgroundImageSet Function C inline void GFX_GOL_SchemeBackgroundImageSet( GFX_GOL_OBJ_SCHEME * pScheme, uint16_t left, uint16_t top, GFX_RESOURCE_HDR * image ); Description This is function GFX_GOL_SchemeBackgroundImageSet. 5.2.2.7.24.5 GFX_GOL_SchemeBackgroundTypeGet Function C inline GFX_BACKGROUND_TYPE GFX_GOL_SchemeBackgroundTypeGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeBackgroundTypeGet. 5.2.2.7.24.6 GFX_GOL_SchemeBackgroundTypeSet Function C inline void GFX_GOL_SchemeBackgroundTypeSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_BACKGROUND_TYPE type ); Description This is function GFX_GOL_SchemeBackgroundTypeSet. 5.2.2.7.24.7 GFX_GOL_SchemeColor0Get Function C inline GFX_COLOR GFX_GOL_SchemeColor0Get( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeColor0Get. 5.2.2.7.24.8 GFX_GOL_SchemeColor0Set Function C inline void GFX_GOL_SchemeColor0Set( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR color ); Description This is function GFX_GOL_SchemeColor0Set. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-879 5.2.2.7.24.9 GFX_GOL_SchemeColor1Get Function C inline GFX_COLOR GFX_GOL_SchemeColor1Get( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeColor1Get. 5.2.2.7.24.10 GFX_GOL_SchemeColor1Set Function C inline void GFX_GOL_SchemeColor1Set( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR color ); Description This is function GFX_GOL_SchemeColor1Set. 5.2.2.7.24.11 GFX_GOL_SchemeColorDisabledGet Function C inline GFX_COLOR GFX_GOL_SchemeColorDisabledGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeColorDisabledGet. 5.2.2.7.24.12 GFX_GOL_SchemeColorDisabledSet Function C inline void GFX_GOL_SchemeColorDisabledSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR disableColor ); Description This is function GFX_GOL_SchemeColorDisabledSet. 5.2.2.7.24.13 GFX_GOL_SchemeColorSet Function C inline void GFX_GOL_SchemeColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR color0, GFX_COLOR color1, GFX_COLOR disableColor ); Description This is function GFX_GOL_SchemeColorSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-880 5.2.2.7.24.14 GFX_GOL_SchemeEmbossDarkColorGet Function C inline GFX_COLOR GFX_GOL_SchemeEmbossDarkColorGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeEmbossDarkColorGet. 5.2.2.7.24.15 GFX_GOL_SchemeEmbossDarkColorSet Function C inline void GFX_GOL_SchemeEmbossDarkColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR darkColor ); Description This is function GFX_GOL_SchemeEmbossDarkColorSet. 5.2.2.7.24.16 GFX_GOL_SchemeEmbossLightColorGet Function C inline GFX_COLOR GFX_GOL_SchemeEmbossLightColorGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeEmbossLightColorGet. 5.2.2.7.24.17 GFX_GOL_SchemeEmbossLightColorSet Function C inline void GFX_GOL_SchemeEmbossLightColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR lightColor ); Description This is function GFX_GOL_SchemeEmbossLightColorSet. 5.2.2.7.24.18 GFX_GOL_SchemeEmbossSet Function C inline void GFX_GOL_SchemeEmbossSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR darkColor, GFX_COLOR lightColor, uint16_t size ); Description This is function GFX_GOL_SchemeEmbossSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-881 5.2.2.7.24.19 GFX_GOL_SchemeEmbossSizeGet Function C inline uint16_t GFX_GOL_SchemeEmbossSizeGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeEmbossSizeGet. 5.2.2.7.24.20 GFX_GOL_SchemeEmbossSizeSet Function C inline void GFX_GOL_SchemeEmbossSizeSet( GFX_GOL_OBJ_SCHEME * pScheme, uint16_t size ); Description This is function GFX_GOL_SchemeEmbossSizeSet. 5.2.2.7.24.21 GFX_GOL_SchemeFillStyleGet Function C inline GFX_FILL_STYLE GFX_GOL_SchemeFillStyleGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeFillStyleGet. 5.2.2.7.24.22 GFX_GOL_SchemeFillStyleSet Function C inline void GFX_GOL_SchemeFillStyleSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_FILL_STYLE style ); Description This is function GFX_GOL_SchemeFillStyleSet. 5.2.2.7.24.23 GFX_GOL_SchemeFontGet Function C inline GFX_RESOURCE_HDR* GFX_GOL_SchemeFontGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeFontGet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-882 5.2.2.7.24.24 GFX_GOL_SchemeFontSet Function C inline void GFX_GOL_SchemeFontSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_RESOURCE_HDR * font ); Description This is function GFX_GOL_SchemeFontSet. 5.2.2.7.24.25 GFX_GOL_SchemeGradientColorSet Function C inline void GFX_GOL_SchemeGradientColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR startColor, GFX_COLOR endColor ); Description This is function GFX_GOL_SchemeGradientColorSet. 5.2.2.7.24.26 GFX_GOL_SchemeGradientEndColorGet Function C inline GFX_COLOR GFX_GOL_SchemeGradientEndColorGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeGradientEndColorGet. 5.2.2.7.24.27 GFX_GOL_SchemeGradientEndColorSet Function C inline void GFX_GOL_SchemeGradientEndColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR endColor ); Description This is function GFX_GOL_SchemeGradientEndColorSet. 5.2.2.7.24.28 GFX_GOL_SchemeGradientStartColorGet Function C inline GFX_COLOR GFX_GOL_SchemeGradientStartColorGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeGradientStartColorGet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-883 5.2.2.7.24.29 GFX_GOL_SchemeGradientStartColorSet Function C inline void GFX_GOL_SchemeGradientStartColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR startColor ); Description This is function GFX_GOL_SchemeGradientStartColorSet. 5.2.2.7.24.30 GFX_GOL_SchemeTextColor0Get Function C inline GFX_COLOR GFX_GOL_SchemeTextColor0Get( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeTextColor0Get. 5.2.2.7.24.31 GFX_GOL_SchemeTextColor0Set Function C inline void GFX_GOL_SchemeTextColor0Set( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR textColor ); Description This is function GFX_GOL_SchemeTextColor0Set. 5.2.2.7.24.32 GFX_GOL_SchemeTextColor1Get Function C inline GFX_COLOR GFX_GOL_SchemeTextColor1Get( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeTextColor1Get. 5.2.2.7.24.33 GFX_GOL_SchemeTextColor1Set Function C inline void GFX_GOL_SchemeTextColor1Set( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR textColor ); Description This is function GFX_GOL_SchemeTextColor1Set. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-884 5.2.2.7.24.34 GFX_GOL_SchemeTextColorDisableGet Function C inline GFX_COLOR GFX_GOL_SchemeTextColorDisableGet( GFX_GOL_OBJ_SCHEME * pScheme ); Description This is function GFX_GOL_SchemeTextColorDisableGet. 5.2.2.7.24.35 GFX_GOL_SchemeTextColorDisableSet Function C inline void GFX_GOL_SchemeTextColorDisableSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR disableColor ); Description This is function GFX_GOL_SchemeTextColorDisableSet. 5.2.2.7.24.36 GFX_GOL_SchemeTextColorSet Function C inline void GFX_GOL_SchemeTextColorSet( GFX_GOL_OBJ_SCHEME * pScheme, GFX_COLOR textColor0, GFX_COLOR textColor1, GFX_COLOR disableColor ); Description This is function GFX_GOL_SchemeTextColorSet. 5.2.2.7.25 Global Variables 5.2.2.7.25.1 IMG_bAlignCenter Variable C uint8_t IMG_bAlignCenter; Description This is variable IMG_bAlignCenter. 5.2.2.7.25.2 IMG_bDownScalingFactor Variable C uint8_t IMG_bDownScalingFactor; Description This is variable IMG_bDownScalingFactor. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-885 5.2.2.7.25.3 IMG_blAbortImageDecoding Variable C uint8_t IMG_blAbortImageDecoding; Description The global variables which define the image position and size 5.2.2.7.25.4 IMG_pCurrentFile Variable C IMG_FILE * IMG_pCurrentFile; Description This is variable IMG_pCurrentFile. 5.2.2.7.25.5 IMG_pFileAPIs Variable C IMG_FILE_SYSTEM_API * IMG_pFileAPIs; Description This is variable IMG_pFileAPIs. 5.2.2.7.25.6 IMG_PixelXYColor Variable C IMG_PIXEL_XY_RGB_888 IMG_PixelXYColor; Description This is variable IMG_PixelXYColor. 5.2.2.7.25.7 IMG_pLoopCallbackFn Variable C IMG_LOOP_CALLBACK IMG_pLoopCallbackFn; Description This is variable IMG_pLoopCallbackFn. 5.2.2.7.25.8 IMG_pPixelOutput Variable C IMG_PIXEL_OUTPUT IMG_pPixelOutput; Description This is variable IMG_pPixelOutput. 5.2.2.7.25.9 IMG_wHeight Variable C uint16_t IMG_wHeight; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-886 Description This is variable IMG_wHeight. 5.2.2.7.25.10 IMG_wImageHeight Variable C uint16_t IMG_wImageHeight; Description This is variable IMG_wImageHeight. 5.2.2.7.25.11 IMG_wImageWidth Variable C uint16_t IMG_wImageWidth; Description This is variable IMG_wImageWidth. 5.2.2.7.25.12 IMG_wStartX Variable C uint16_t IMG_wStartX; Description This is variable IMG_wStartX. 5.2.2.7.25.13 IMG_wStartY Variable C uint16_t IMG_wStartY; Description This is variable IMG_wStartY. 5.2.2.7.25.14 IMG_wWidth Variable C uint16_t IMG_wWidth; Description This is variable IMG_wWidth. 5.2.2.7.25.15 DisplayUpdatePending Variable C volatile uint8_t DisplayUpdatePending; Description This is variable DisplayUpdatePending. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-887 5.2.2.7.25.16 doubleBuffEnabled Variable C uint8_t doubleBuffEnabled; Description This is variable doubleBuffEnabled. 5.2.2.7.25.17 GFX_Primitive_instance Variable C GFX_Primitive_DATA GFX_Primitive_instance; Description structure to store the primitive driver structures 5.2.2.7.25.18 primitiveTaskImage Variable C PUTIMAGE_PARAM primitiveTaskImage; Description This is variable primitiveTaskImage. 5.2.2.7.26 Data Types and Constants 5.2.2.7.26.1 CHARTPARAM Structure C typedef struct { XCHAR * pTitle; XCHAR * pSmplLabel; XCHAR * pValLabel; short seriesCount; uint16_t smplStart; uint16_t smplEnd; uint16_t valMax; uint16_t valMin; uint16_t perMax; uint16_t perMin; GFX_COLOR * pColor; void * pTitleFont; void * pAxisLabelsFont; void * pGridLabelsFont; } CHARTPARAM; Description Defines the parameters for the CHART object. Members Members Description XCHAR * pTitle; Pointer to the Title of the chart. XCHAR * pSmplLabel; Pointer to the bar chart sample axis label. Depending 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-888 XCHAR * pValLabel; Pointer to the bar chart value axis label. Depending short seriesCount; Number of data series that will be displayed when chart is drawn. uint16_t smplStart; Start point of data sample range to be displayed (minimum/default value = 1) uint16_t smplEnd; End point of data sample range to be displayed. uint16_t valMax; Maximum value of a sample that can be displayed. uint16_t valMin; Minimum value of a sample that can be displayed. uint16_t perMax; Maximum value of the percentage range that can be displayed. uint16_t perMin; Minimum value of the percentage range that can be displayed. GFX_COLOR * pColor; Pointer to the color table used to draw the chart data. void * pTitleFont; Pointer to the font used for the title label of the chart. void * pAxisLabelsFont; Pointer to the font used for X and Y axis labels. void * pGridLabelsFont; Pointer to the font used for X and Y axis grid labels. 5.2.2.7.26.2 DATASERIES Structure C typedef struct { XCHAR * pSData; uint16_t samples; BYTE show; uint16_t * pData; void * pNextData; } DATASERIES; Description Defines a variable for the CHART object. It specifies the number of samples, pointer to the array of samples for the data series and pointer to the next data series. A member of this structure (show) is used as a flag to determine if the series is to be drawn or not. Together with the smplStart and smplEnd it will determine what kind of chart will be drawn. Members Members Description XCHAR * pSData; Pointer to the data series name. uint16_t samples; Indicates the number of data samples (or data points) contained in the array specified by pData. BYTE show; The flag to indicate if the data series will be shown or not. If this flag is set to SHOW_DATA, the data series will be shown. If HIDE_DATA, the data series will not be shown. uint16_t * pData; Pointer to the array of data samples. void * pNextData; Pointer to the next data series. NULL if no other data series follows. 5.2.2.7.26.3 FileFeof Type C typedef bool (* FileFeof)(void *stream); Description This is type FileFeof. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-889 5.2.2.7.26.4 FileRead Type C typedef size_t (* FileRead)(void *ptr, size_t size, size_t n, void *stream); Description Typedefs of the used File System APIs 5.2.2.7.26.5 FileSeek Type C typedef bool (* FileSeek)(void *stream, long offset, int whence); Description This is type FileSeek. 5.2.2.7.26.6 FileTell Type C typedef long (* FileTell)(void *fo); Description This is type FileTell. 5.2.2.7.26.7 FONT_ORIENTATION Enumeration C typedef enum { ORIENT_HOR = 0, ORIENT_VER = 1 } FONT_ORIENTATION; Description GFX font orientation Remarks None. 5.2.2.7.26.8 GFX_ALIGNMENT Enumeration C typedef enum { GFX_ALIGN_LEFT = 0x0C01, GFX_ALIGN_HCENTER = 0x0C02, GFX_ALIGN_RIGHT = 0x0C04, GFX_ALIGN_TOP = 0x0C10, GFX_ALIGN_VCENTER = 0x0C20, GFX_ALIGN_BOTTOM = 0x0C40, GFX_ALIGN_CENTER = 0x0C22, GFX_ALIGN_HORIZONTAL_MASK = 0x0C07, GFX_ALIGN_VERTICAL_MASK = 0x0C70 } GFX_ALIGNMENT; Description Defines the types of text alignment. The text alignment is used in GFX_TextStringBoxDraw(). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-890 Members Members Description GFX_ALIGN_LEFT = 0x0C01 left aligned text GFX_ALIGN_HCENTER = 0x0C02 horizontal center aligned text GFX_ALIGN_RIGHT = 0x0C04 right aligned text GFX_ALIGN_TOP = 0x0C10 top aligned text GFX_ALIGN_VCENTER = 0x0C20 vertical center aligned text GFX_ALIGN_BOTTOM = 0x0C40 bottom aligned text GFX_ALIGN_CENTER = 0x0C22 vertical & horizontal center aligned text GFX_ALIGN_HORIZONTAL_MASK = 0x0C07 horizontal mask, DO NOT document this item GFX_ALIGN_VERTICAL_MASK = 0x0C70 vertical mask, DO NOT document this item DOM-IGNORE-END 5.2.2.7.26.9 GFX_BACKGROUND Structure C typedef struct { uint16_t left; uint16_t top; GFX_BACKGROUND_TYPE type; GFX_RESOURCE_HDR * pImage; GFX_COLOR color; } GFX_BACKGROUND; Description Structure describing the background information. Useful in refreshing the whole screen or an area of the screen. The background information, when used, can be one of the enumerated types in GFX_BACKGROUND_TYPE. • pBackGroundImage - pointer to a GFX_RESOURCE_HEADER with the type GFX_RESOURCE_TYPE_MCHP_MBITMAP. • backGroundColor - value of the background color used when pBackgroundImage is NULL. The pBackGroundImage has the high priority and will assume an image is used as a background when the pointer is initialized. If this is NULL the backgroundColor is assumed to be the background. Members Members Description uint16_t left; Horizontal starting position of the background. uint16_t top; Horizontal starting position of the background. GFX_BACKGROUND_TYPE type; Specifies the type of background to use. GFX_RESOURCE_HDR * pImage; Pointer to the background image used. Set this to NULL if not used. GFX_COLOR color; If the background image is NULL, background is assumed to be this color. 5.2.2.7.26.10 GFX_BACKGROUND_TYPE Enumeration C typedef enum { GFX_BACKGROUND_NONE = 0x00, GFX_BACKGROUND_COLOR = 0x01, GFX_BACKGROUND_IMAGE = 0x02, GFX_BACKGROUND_DISPLAY_BUFFER = 0x03 } GFX_BACKGROUND_TYPE; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-891 Description Defines the types of background information. Knowing the background information allows easier refresh of an area on the display buffer. Members Members Description GFX_BACKGROUND_NONE = 0x00 No background information set. GFX_BACKGROUND_COLOR = 0x01 Background is set to a color. GFX_BACKGROUND_IMAGE = 0x02 Background is set to an image. GFX_BACKGROUND_DISPLAY_BUFFER = 0x03 Background is set to the current content of the display buffer. This requires support of GFX_PixelArrayGet(). 5.2.2.7.26.11 GFX_BEVEL_RENDER_TYPE Enumeration C typedef enum { GFX_DRAW_FULLBEVEL = 0xFF, GFX_DRAW_TOPBEVEL = 0xF0, GFX_DRAW_BOTTOMBEVEL = 0x0F } GFX_BEVEL_RENDER_TYPE; Description Bevel shapes can be rendered in full or half size. The following types defines the full, top and bottom halves. Members Members Description GFX_DRAW_FULLBEVEL = 0xFF render full bevel shape GFX_DRAW_TOPBEVEL = 0xF0 render top bevel shape GFX_DRAW_BOTTOMBEVEL = 0x0F render bottom half bevel shape 5.2.2.7.26.12 GFX_COLOR Type C typedef uint32_t GFX_COLOR; Description Data type that defines the color data. This type is dependent on the COLOR_DEPTH setting. See COLOR_DEPTH. • GFX_COLOR is type uint8_t if COLOR_DEPTH <= 8 • GFX_COLOR is type uint16_t if COLOR_DEPTH = 16 • GFX_COLOR is type uint32_t if COLOR_DEPTH = 24 5.2.2.7.26.13 GFX_DOUBLE_BUFFERING_MODE Structure C typedef struct { GFX_FEATURE_STATUS gfxDoubleBufferFeature; GFX_FEATURE_STATUS gfxDoubleBufferRequestSync; GFX_FEATURE_STATUS gfxDoubleBufferFullSync; GFX_RECTANGULAR_AREA gfxDoubleBufferAreas[GFX_MAX_INVALIDATE_AREAS]; uint16_t gfxUnsyncedAreaCount; } GFX_DOUBLE_BUFFERING_MODE; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-892 Description Structure used to manage double buffering feature. 5.2.2.7.26.14 GFX_FEATURE_STATUS Enumeration C typedef enum { GFX_FEATURE_ENABLED = 1, GFX_FEATURE_DISABLED = 0 } GFX_FEATURE_STATUS; Description Defines the states of a Graphics Library feature that can nbe enabled/disabled at run time. 5.2.2.7.26.15 GFX_FILL_STYLE Enumeration C typedef enum { GFX_FILL_STYLE_NONE = 0x0B00, GFX_FILL_STYLE_COLOR, GFX_FILL_STYLE_ALPHA_COLOR, GFX_FILL_STYLE_GRADIENT_DOWN, GFX_FILL_STYLE_GRADIENT_UP, GFX_FILL_STYLE_GRADIENT_RIGHT, GFX_FILL_STYLE_GRADIENT_LEFT, GFX_FILL_STYLE_GRADIENT_DOUBLE_VER, GFX_FILL_STYLE_GRADIENT_DOUBLE_HOR } GFX_FILL_STYLE; Description Defines the types of fill styles. Members Members Description GFX_FILL_STYLE_NONE = 0x0B00 no fill GFX_FILL_STYLE_COLOR color fill GFX_FILL_STYLE_ALPHA_COLOR color fill with alpha blending GFX_FILL_STYLE_GRADIENT_DOWN gradient, vertical-down direction GFX_FILL_STYLE_GRADIENT_UP gradient, vertical-up direction GFX_FILL_STYLE_GRADIENT_RIGHT gradient, horizontal-right direction GFX_FILL_STYLE_GRADIENT_LEFT gradient, horizontal-left direction GFX_FILL_STYLE_GRADIENT_DOUBLE_VER gradient, vertical-up/down direction GFX_FILL_STYLE_GRADIENT_DOUBLE_HOR gradient, horizontal-left/right direction 5.2.2.7.26.16 GFX_FONT_ANTIALIAS_TYPE Enumeration C typedef enum { GFX_FONT_ANTIALIAS_OPAQUE = 0, GFX_FONT_ANTIALIAS_TRANSLUCENT = 1 } GFX_FONT_ANTIALIAS_TYPE; Description Transparency type when rendering characters with anti-aliasing. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-893 Members Members Description GFX_FONT_ANTIALIAS_OPAQUE = 0 Mid colors are calculated only once while rendering each character. This is ideal for rendering text over a constant background. GFX_FONT_ANTIALIAS_TRANSLUCENT = 1 Mid colors are calculated for every necessary pixel. This feature is useful when rendering text over an image or when the background is not one flat color. 5.2.2.7.26.17 GFX_FONT_CURRENT Structure C typedef struct { GFX_RESOURCE_HDR * pFont; GFX_FONT_HEADER header; GFX_ALIGNMENT alignment; FONT_ORIENTATION orientation; uint8_t antiAliasType; } GFX_FONT_CURRENT; Description GFX current font Members Members Description GFX_RESOURCE_HDR * pFont; pointer to the currently set font GFX_FONT_HEADER header; copy of the currently set font header GFX_ALIGNMENT alignment; alignment of the font FONT_ORIENTATION orientation; orientation of the font uint8_t antiAliasType; anti-alias type set Remarks None. 5.2.2.7.26.18 GFX_FONT_GLYPH_ENTRY Structure C typedef struct { uint8_t width; uint8_t offsetLSB; uint16_t offsetMSB; } GFX_FONT_GLYPH_ENTRY; Description Structures describing the glyph entry. Members Members Description uint8_t width; width of the glyph uint8_t offsetLSB; Least Significant uint8_t of the glyph location offset uint16_t offsetMSB; Most Significant (2) uint8_ts of the glyph location offset 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-894 5.2.2.7.26.19 GFX_FONT_GLYPH_ENTRY_EXTENDED Structure C typedef struct { uint32_t offset; uint16_t cursorAdvance; uint16_t glyphWidth; int16_t xAdjust; int16_t yAdjust; } GFX_FONT_GLYPH_ENTRY_EXTENDED; Description This is type GFX_FONT_GLYPH_ENTRY_EXTENDED. Members Members Description uint32_t offset; Offset Order: LSW_LSB LSW_MSB MSW_MSB MSW_MSB uint16_t cursorAdvance; x-value by which cursor has to advance after rendering the glyph uint16_t glyphWidth; width of the glyph int16_t xAdjust; x-position is adjusted as per this signed number int16_t yAdjust; y-position is adjusted as per this signed number 5.2.2.7.26.20 GFX_FONT_HEADER Structure C typedef struct { uint8_t fontID; uint8_t extendedGlyphEntry : 1; uint8_t res1 : 1; uint8_t bpp : 2; uint8_t orientation : 2; uint8_t res2 : 2; uint16_t firstChar; uint16_t lastChar; uint16_t height; } GFX_FONT_HEADER; Description Structure describing the font header. Members Members Description uint8_t fontID; User assigned value uint8_t extendedGlyphEntry : 1; Extended Glyph entry flag. When set font has extended glyph feature enabled. uint8_t res1 : 1; Reserved for future use (must be set to 0) 5.2.2.7.26.21 GFX_FONT_OUTCHAR Structure C typedef struct { GFX_FONT_SPACE GFX_FONT_GLYPH_ENTRY * pChTable; GFX_FONT_SPACE GFX_FONT_GLYPH_ENTRY_EXTENDED * pChTableExtended; uint8_t chImage[GFX_EXTERNAL_FONT_RASTER_BUFFER_SIZE]; int16_t chEffectiveGlyphWidth; uint8_t bpp; int16_t chGlyphWidth; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-895 GFX_FONT_SPACE uint8_t * pChImage; int16_t xAdjust; int16_t yAdjust; int16_t xWidthAdjust; int16_t heightOvershoot; } GFX_FONT_OUTCHAR; Description Structure for character information when rendering the character. 5.2.2.7.26.22 GFX_GOL_ANALOGCLOCK Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; short radius; short centerx; short centery; short valueS; short prev_valueS; short valueM; short prev_valueM; short valueH; short prev_valueH; void * pBitmap; } GFX_GOL_ANALOGCLOCK; Description Defines the parameters required for a clock Object. The following relationships of the parameters determines the general shape of the clock: 1. centerx and centery determine the middle of the clock. 2. radius defines the radius of the clock. 4. *pBitmap points to the background image for the analog clock. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). short radius; Radius of the clock. short centerx; center location in X-axis. short centery; center location in Y-axis. short valueS; time in Second short prev_valueS; previous time in Second short valueM; time in Minute short prev_valueM; previous time in Minute short valueH; time in Hour short prev_valueH; previous time in Hour void * pBitmap; Pointer to bitmap used. 5.2.2.7.26.23 GFX_GOL_BUTTON Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t radius; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-896 uint16_t textWidth; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; GFX_RESOURCE_HDR * pPressImage; GFX_RESOURCE_HDR * pReleaseImage; GFX_COLOR previousAlphaColor; } GFX_GOL_BUTTON; Description Defines the parameters required for a GFX_GOL_BUTTON Object. The following relationships of the parameters determines the general shape of the GFX_GOL_BUTTON: 1. Width is determined by right - left. 2. Height is determined by top - bottom. 3. Radius - specifies if the GFX_GOL_BUTTON will have a rounded edge. If zero then the GFX_GOL_BUTTON will have sharp (cornered) edge. 4. If 2*radius = height = width, the GFX_GOL_BUTTON is a circular GFX_GOL_BUTTON. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). uint16_t radius; Radius for rounded buttons. uint16_t textWidth; Computed text width, done at creation. uint16_t textHeight; Computed text height, done at creation. GFX_XCHAR * pText; Pointer to the text used. GFX_ALIGNMENT alignment; text alignment GFX_RESOURCE_HDR * pPressImage; Pointer to bitmap used. GFX_RESOURCE_HDR * pReleaseImage; Pointer to bitmap used. 5.2.2.7.26.24 GFX_GOL_BUTTON_STATE Enumeration C typedef enum { GFX_GOL_BUTTON_FOCUSED_STATE = 0x0001, GFX_GOL_BUTTON_DISABLED_STATE = 0x0002, GFX_GOL_BUTTON_PRESSED_STATE = 0x0004, GFX_GOL_BUTTON_TOGGLE_STATE = 0x0008, GFX_GOL_BUTTON_TWOTONE_STATE = 0x0100, GFX_GOL_BUTTON_NOPANEL_STATE = 0x0200, GFX_GOL_BUTTON_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_BUTTON_DRAW_STATE = 0x4000, GFX_GOL_BUTTON_HIDE_STATE = 0x8000 } GFX_GOL_BUTTON_STATE; Description Object States Definition: Members Members Description GFX_GOL_BUTTON_FOCUSED_STATE = 0x0001 Bit for focus state. GFX_GOL_BUTTON_DISABLED_STATE = 0x0002 Bit for disabled state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-897 GFX_GOL_BUTTON_PRESSED_STATE = 0x0004 Bit for press state. GFX_GOL_BUTTON_TOGGLE_STATE = 0x0008 Bit to indicate object will have a toggle behavior. GFX_GOL_BUTTON_TWOTONE_STATE = 0x0100 Bit to indicate the object is a two tone type. GFX_GOL_BUTTON_NOPANEL_STATE = 0x0200 Bit to indicate the object will be drawn without a panel (for faster drawing when the object image used is larger than the object's panel). GFX_GOL_BUTTON_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_BUTTON_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_BUTTON_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.25 GFX_GOL_CHART Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; CHARTPARAM prm; DATASERIES * pChData; } GFX_GOL_CHART; Description Defines the parameters required for a chart Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). CHARTPARAM prm; Structure for the parameters of the chart. DATASERIES * pChData; Pointer to the first chart data series in the link list of data series. 5.2.2.7.26.26 GFX_GOL_CHECKBOX Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; } GFX_GOL_CHECKBOX; Description The structure contains check box data Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). uint16_t textHeight; Pre-computed text height GFX_XCHAR * pText; Pointer to text GFX_ALIGNMENT alignment; text alignment 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-898 5.2.2.7.26.27 GFX_GOL_CHECKBOX_STATE Enumeration C typedef enum { GFX_GOL_CHECKBOX_FOCUSED_STATE = 0x0001, GFX_GOL_CHECKBOX_DISABLED_STATE = 0x0002, GFX_GOL_CHECKBOX_CHECKED_STATE = 0x0004, GFX_GOL_CHECKBOX_DRAW_CHECK_STATE = 0x1000, GFX_GOL_CHECKBOX_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_CHECKBOX_DRAW_STATE = 0x4000, GFX_GOL_CHECKBOX_HIDE_STATE = 0x8000 } GFX_GOL_CHECKBOX_STATE; Description • Object States Definition: ****************************************************************** #define GFX_GOL_CHECKBOX_FOCUSED_STATE 0x0001 // Focus state #define GFX_GOL_CHECKBOX_DISABLED_STATE 0x0002 // Disabled state #define GFX_GOL_CHECKBOX_CHECKED_STATE 0x0004 // Checked state #define GFX_GOL_CHECKBOX_HIDE_STATE 0x8000 // Check box must be removed from screen #define GFX_GOL_CHECKBOX_DRAW_FOCUS_STATE 0x2000 // Focus must be redrawn #define GFX_GOL_CHECKBOX_DRAW_STATE 0x4000 // Whole check box must be redrawn #define GFX_GOL_CHECKBOX_DRAW_CHECK_STATE 0x1000 // Check box mark should be redrawn Members Members Description GFX_GOL_CHECKBOX_FOCUSED_STATE = 0x0001 Bit for focus state. GFX_GOL_CHECKBOX_DISABLED_STATE = 0x0002 Bit to indicate object is disabled GFX_GOL_CHECKBOX_CHECKED_STATE = 0x0004 Bit to indicate object is checked GFX_GOL_CHECKBOX_DRAW_CHECK_STATE = 0x1000 Bit to indicate the check must be redrawn. GFX_GOL_CHECKBOX_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_CHECKBOX_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_CHECKBOX_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.28 GFX_GOL_CUSTOMCONTROL Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint8_t instance; uint16_t ID; void * pNxtObj; GFX_GOL_OBJ_TYPE type; uint16_t state; uint16_t left; uint16_t top; uint16_t right; uint16_t bottom; GFX_GOL_OBJ_SCHEME * pGolScheme; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-899 DRAW_FUNC draw; FREE_FUNC FreeObj; ACTIONGET_FUNC actionGet; ACTIONSET_FUNC actionSet; uint16_t pos; uint16_t prevPos; } GFX_GOL_CUSTOMCONTROL; Description The structure contains data for the control Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). uint16_t ID; instance unique ID void * pNxtObj; a pointer to the next object in the linked list GFX_GOL_OBJ_TYPE type; must be set to OBJ_CUSTOM uint16_t state; state uint16_t left; left border uint16_t top; top border uint16_t right; right border uint16_t bottom; bottom border GFX_GOL_OBJ_SCHEME * pGolScheme; the style scheme used FREE_FUNC FreeObj; function pointer to the object free function ACTIONGET_FUNC actionGet; function pointer to the object message function ACTIONSET_FUNC actionSet; function pointer to the object default message function uint16_t pos; current position uint16_t prevPos; previous position 5.2.2.7.26.29 GFX_GOL_DIGITALMETER Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t textHeight; uint32_t Cvalue; uint32_t Pvalue; uint8_t NoOfDigits; uint8_t DotPos; GFX_ALIGNMENT alignment; } GFX_GOL_DIGITALMETER; Description Digital meter parameters DigitalMeter properties. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). uint16_t textHeight; Pre-computed text height uint32_t Cvalue; Current value uint32_t Pvalue; Previous value 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-900 uint8_t NoOfDigits; Number of digits to be displayed uint8_t DotPos; Position of decimal point GFX_ALIGNMENT alignment; text alignment Remarks None. 5.2.2.7.26.30 GFX_GOL_DIGITALMETER_STATE Enumeration C typedef enum { GFX_GOL_DIGITALMETER_DISABLED_STATE = 0x0002, GFX_GOL_DIGITALMETER_FRAME_STATE = 0x0010, GFX_GOL_DIGITALMETER_DRAW_STATE = 0x4000, GFX_GOL_DIGITALMETER_UPDATE_STATE = 0x2000, GFX_GOL_DIGITALMETER_HIDE_STATE = 0x8000 } GFX_GOL_DIGITALMETER_STATE; Description Object States Definition: Members Members Description GFX_GOL_DIGITALMETER_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_DIGITALMETER_FRAME_STATE = 0x0010 Bit to indicate frame is displayed. GFX_GOL_DIGITALMETER_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_DIGITALMETER_UPDATE_STATE = 0x2000 Bit to indicate that only text must be redrawn. GFX_GOL_DIGITALMETER_HIDE_STATE = 0x8000 Bit to remove object from screen. 5.2.2.7.26.31 GFX_GOL_DRAW_CALLBACK_FUNC Type C typedef bool (* GFX_GOL_DRAW_CALLBACK_FUNC)(void); Description This callback function is implemented by the application. This is called inside the GFX_GOL_ObjectListDraw() function when the drawing of objects in the active list is completed. Any application specific rendering must be performed on this callback function so no object rendering will be affected by the application calls to primitive rendering functions. Application setting the drawing color, line style, fill style, text string cursor position and current font will not affect the object rendering. This is also the safe place to modify the active list. When the application has performed its own primitive rendering calls, this function must return true to inform the GFX_GOL_ObjectListDraw() that it is done rendering and checking for object drawing or redrawing can continue. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-901 Returns true - is returned when application rendering is done. false - is returned when application rendering is not yet finished. Example None. 5.2.2.7.26.32 GFX_GOL_EDITBOX Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; uint16_t charMax; uint16_t length; } GFX_GOL_EDITBOX; Description Defines the parameters required for a Edit Box Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). uint16_t textHeight; Pre-computed text height. GFX_XCHAR * pText; Pointer to text buffer. GFX_ALIGNMENT alignment; text alignment uint16_t charMax; Maximum number of characters in the edit box. uint16_t length; Current text length. 5.2.2.7.26.33 GFX_GOL_GROUPBOX Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t textWidth; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; } GFX_GOL_GROUPBOX; Description Defines the parameters required for a group box Object. The textwidth and textHeight is not checked with the actual dimension of the object. Clipping is not supported in group box object. It is possible for the text to exceed the dimension of the Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). uint16_t textWidth; Pre-computed text width. uint16_t textHeight; Pre-computed text height. GFX_XCHAR * pText; Text string used. GFX_ALIGNMENT alignment; text alignment 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-902 5.2.2.7.26.34 GFX_GOL_GROUPBOX_STATE Enumeration C typedef enum { GFX_GOL_GROUPBOX_DISABLED_STATE = 0x0002, GFX_GOL_GROUPBOX_DRAW_STATE = 0x4000, GFX_GOL_GROUPBOX_HIDE_STATE = 0x8000 } GFX_GOL_GROUPBOX_STATE; Description Object States Definition: Members Members Description GFX_GOL_GROUPBOX_DISABLED_STATE = 0x0002 Bit for disabled state GFX_GOL_GROUPBOX_DRAW_STATE = 0x4000 Bit to indicate group box must be redrawn GFX_GOL_GROUPBOX_HIDE_STATE = 0x8000 Bit to remove object from screen 5.2.2.7.26.35 GFX_GOL_LISTBOX Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; GFX_GOL_LISTITEM * pItemList; GFX_GOL_LISTITEM * pFocusItem; uint16_t itemsNumber; int16_t scrollY; int16_t textHeight; GFX_ALIGNMENT alignment; } GFX_GOL_LISTBOX; Description Defines the parameters required for a list box Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). GFX_GOL_LISTITEM * pItemList; Pointer to the list of items. GFX_GOL_LISTITEM * pFocusItem; Pointer to the focused item. uint16_t itemsNumber; Number of items in the list box. int16_t scrollY; Scroll displacement for the list. int16_t textHeight; Pre-computed text height. GFX_ALIGNMENT alignment; items alignment 5.2.2.7.26.36 GFX_GOL_LISTBOX_ITEM_STATUS Enumeration C typedef enum { GFX_GOL_LISTBOX_ITEM_STATUS_SELECTED = 0x0001, GFX_GOL_LISTBOX_ITEM_STATUS_REDRAW = 0x0002 } GFX_GOL_LISTBOX_ITEM_STATUS; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-903 Description Bit definitions for the status of an item Members Members Description GFX_GOL_LISTBOX_ITEM_STATUS_SELECTED = 0x0001 define LB_STS_SELECTED 0x0001 // Item is selected. GFX_GOL_LISTBOX_ITEM_STATUS_REDRAW = 0x0002 define LB_STS_REDRAW 0x0002 // Item is to be redrawn. 5.2.2.7.26.37 GFX_GOL_LISTBOX_STATE Enumeration C typedef enum { GFX_GOL_LISTBOX_FOCUSED_STATE = 0x0001, GFX_GOL_LISTBOX_DISABLED_STATE = 0x0002, GFX_GOL_LISTBOX_SINGLE_SELECT_STATE = 0x0010, GFX_GOL_LISTBOX_DRAW_ITEMS_STATE = 0x1000, GFX_GOL_LISTBOX_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_LISTBOX_DRAW_STATE = 0x4000, GFX_GOL_LISTBOX_HIDE_STATE = 0x8000 } GFX_GOL_LISTBOX_STATE; Description This is type GFX_GOL_LISTBOX_STATE. Members Members Description GFX_GOL_LISTBOX_FOCUSED_STATE = 0x0001 Bit for focus state. GFX_GOL_LISTBOX_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_LISTBOX_SINGLE_SELECT_STATE = 0x0010 Bit to indicate only one item can be selected. GFX_GOL_LISTBOX_DRAW_ITEMS_STATE = 0x1000 Bit to indicate selected items of the object must be redrawn. GFX_GOL_LISTBOX_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_LISTBOX_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_LISTBOX_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.38 GFX_GOL_LISTITEM Structure C typedef struct { void * pPrevItem; void * pNextItem; GFX_GOL_LISTBOX_ITEM_STATUS status; GFX_XCHAR * pText; GFX_RESOURCE_HDR * pImage; uint16_t data; } GFX_GOL_LISTITEM; Description Defines the parameters required for a list item used in list box. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-904 Members Members Description void * pPrevItem; Pointer to the next item void * pNextItem; Pointer to the next item GFX_GOL_LISTBOX_ITEM_STATUS status; Specifies the status of the item. GFX_XCHAR * pText; Pointer to the text for the item GFX_RESOURCE_HDR * pImage; Pointer to the image used uint16_t data; Some data associated with the item 5.2.2.7.26.39 GFX_GOL_MESSAGE Structure C typedef struct { uint8_t type; uint8_t uiEvent; int16_t param1; int16_t param2; } GFX_GOL_MESSAGE; Description GFX_GOL_MESSAGE Specifies message structure used in the library. • The types must be one of the INPUT_DEVICE_TYPE: • TYPE_UNKNOWN • TYPE_KEYBOARD • TYPE_TOUCHSCREEN • TYPE_MOUSE • uiEvent must be one of the INPUT_DEVICE_EVENT. • for touch screen: • EVENT_INVALID • EVENT_MOVE • EVENT_PRESS • EVENT_STILLPRESS • EVENT_RELEASE • for keyboard: • EVENT_KEYSCAN (param2 contains scan code) • EVENT_KEYCODE (param2 contains character code) • param1: • for touch screen is the x position • for keyboard ID of object receiving the message • param2 • for touch screen y position • for keyboard scan or key code 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-905 Members Members Description uint8_t type; Type of input device. uint8_t uiEvent; The generic events for input device. int16_t param1; Parameter 1, definition and usage is dependent on the type of input device. int16_t param2; Parameter 2, definition and usage is dependent on the type of input device. Remarks None. 5.2.2.7.26.40 GFX_GOL_METER Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; GFX_XCHAR * pText; GFX_GOL_METER_DRAW_TYPE type; int16_t value; int16_t minValue; int16_t maxValue; int16_t xCenter; int16_t yCenter; int16_t radius; int16_t xPos; int16_t yPos; GFX_COLOR color1; GFX_COLOR color2; GFX_COLOR color3; GFX_COLOR color4; GFX_COLOR color5; GFX_COLOR color6; GFX_RESOURCE_HDR * pTitleFont; GFX_RESOURCE_HDR * pValueFont; } GFX_GOL_METER; Description Defines the parameters required for a meter Object. Depending on the type selected the meter is drawn with the defined shape parameters and values set on the given fields. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see OBJ_HEADER). GFX_XCHAR * pText; The text label of the meter. GFX_GOL_METER_DRAW_TYPE type; sets the type of the meter int16_t value; Current value of the meter. int16_t minValue; minimum value the meter can display int16_t maxValue; maximum value the meter can display (range is maxValue - minValue) int16_t xCenter; The x coordinate center position. This is computed automatically. int16_t yCenter; The y coordinate center position. This is computed automatically. int16_t radius; Radius of the meter, also defines the needle length. int16_t xPos; The current x position of the needle. This is computed automatically. int16_t yPos; The current y position of the needle. This is computed automatically. GFX_COLOR color1; Arc1 and scale1 color parameter. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-906 GFX_COLOR color2; Arc2 and scale2 color parameter GFX_COLOR color3; Arc3 and scale3 color parameter GFX_COLOR color4; Arc4 and scale4 color parameter GFX_COLOR color5; Arc5 and scale5 color parameter GFX_COLOR color6; Arc6 and scale6 color parameter GFX_RESOURCE_HDR * pTitleFont; Pointer to the font used in the title of the meter GFX_RESOURCE_HDR * pValueFont; Pointer to the font used in the current reading (if displayed) of the meter 5.2.2.7.26.41 GFX_GOL_METER_DRAW_TYPE Enumeration C typedef enum { GFX_GOL_METER_WHOLE_TYPE = 0, GFX_GOL_METER_HALF_TYPE = 1, GFX_GOL_METER_QUARTER_TYPE = 2 } GFX_GOL_METER_DRAW_TYPE; Description • Meter Types Definition: MTR_WHOLE_TYPE will use all the arc colors (color1 to color6) MTR_HALF_TYPE will use arc colors (color5, color4, color3, color2) MTR_QUARTER_TYPE will use arc colors (color3, color2) Members Members Description GFX_GOL_METER_WHOLE_TYPE = 0 draw circular meter GFX_GOL_METER_HALF_TYPE = 1 draw semi circle meter GFX_GOL_METER_QUARTER_TYPE = 2 draw quarter of a circle meter 5.2.2.7.26.42 GFX_GOL_METER_STATE Enumeration C typedef enum { GFX_GOL_METER_DISABLED_STATE = 0x0002, GFX_GOL_METER_RING_STATE = 0x0004, GFX_GOL_METER_ACCURACY_STATE = 0x0008, GFX_GOL_METER_UPDATE_DRAW_STATE = 0x1000, GFX_GOL_METER_DRAW_STATE = 0x4000, GFX_GOL_METER_HIDE_STATE = 0x8000 } GFX_GOL_METER_STATE; Description Object States Definition: Members Members Description GFX_GOL_METER_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_METER_RING_STATE = 0x0004 Bit for press state. GFX_GOL_METER_ACCURACY_STATE = 0x0008 Bit to indicate object will have a toggle behavior. GFX_GOL_METER_UPDATE_DRAW_STATE = 0x1000 Bit to indicate hand update only. GFX_GOL_METER_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-907 GFX_GOL_METER_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.43 GFX_GOL_OBJ_HEADER Structure C typedef struct { uint16_t ID; void * pNxtObj; GFX_GOL_OBJ_TYPE type; uint16_t state; uint16_t left; uint16_t top; uint16_t right; uint16_t bottom; GFX_GOL_OBJ_SCHEME * pGolScheme; DRAW_FUNC DrawObj; FREE_FUNC FreeObj; ACTIONGET_FUNC actionGet; ACTIONSET_FUNC actionSet; bool imageStored; } GFX_GOL_OBJ_HEADER; Description GFX_GOL_OBJ_HEADER This structure defines the Graphics Object Layer header used in all objects in the Graphics Library. Members Members Description uint16_t ID; Unique id assigned for referencing. void * pNxtObj; A pointer to the next object. GFX_GOL_OBJ_TYPE type; Identifies the type of GOL object. uint16_t state; State of object. uint16_t left; Left position of the Object. uint16_t top; Top position of the Object. uint16_t right; Right position of the Object. uint16_t bottom; Bottom position of the Object. GFX_GOL_OBJ_SCHEME * pGolScheme; Pointer to the scheme used. DRAW_FUNC DrawObj; function pointer to the object's draw function. FREE_FUNC FreeObj; function pointer to the object's free function. ACTIONGET_FUNC actionGet; function pointer to the object's action get function. ACTIONSET_FUNC actionSet; function pointer to the object's action set function. bool imageStored; Used for alpha blending Remarks None. 5.2.2.7.26.44 GFX_GOL_OBJ_SCHEME Structure C typedef struct { GFX_COLOR EmbossDkColor; GFX_COLOR EmbossLtColor; GFX_COLOR TextColor0; GFX_COLOR TextColor1; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-908 GFX_COLOR TextColorDisabled; GFX_COLOR Color0; GFX_COLOR Color1; GFX_COLOR ColorDisabled; GFX_RESOURCE_HDR * pFont; GFX_FILL_STYLE fillStyle; GFX_COLOR CommonBkColor; uint16_t CommonBkLeft; uint16_t CommonBkTop; GFX_BACKGROUND_TYPE CommonBkType; GFX_RESOURCE_HDR * pCommonBkImage; uint16_t AlphaValue; GFX_COLOR gradientStartColor; GFX_COLOR gradientEndColor; uint16_t EmbossSize; } GFX_GOL_OBJ_SCHEME; Description GFX_GOL_OBJ_SCHEME This structure specifies the style scheme components of an object. All objects will use the style scheme when rendering. Refer to specific object documentation on how the style scheme colors are utilized by the object. The style scheme allows objects to show 3D effects as well as feedback to users. For example, in Button objects, a press and release effect on the Buttons are easily shown by manipulating the colors when the object is drawn with a pressed state and released state. The style scheme also allows effects such as gradients and alpha blending. When using alpha blending, the style scheme requires objects to be associated with background information. A background can be a flat color background or an image. The usage of a background requires the background dimension to be larger than the object. In other words, the object should be drawn within the background dimension. Multiple objects can share a common background. As long as all the objects are drawn within the dimension of the background they can share a common background. The supported background types are (See GFX_BACKGROUND_TYPE): • GFX_BACKGROUND_COLOR - this type will set the common background to be a flat color. The color used is specified by CommonBkType. • GFX_BACKGROUND_IMAGE - this tyoe will set the common background to be an image. The image used is specified by pCommonBkImage. When an object is associated with a background, it can be easily hidden or redrawn with some effects (for example alpha blending with the background). The background information allows the redrawing of the background with the object without the need to manually refreshing the background using primitive calls by the application. Members Members Description GFX_COLOR EmbossDkColor; Emboss dark color used for 3d effect. GFX_COLOR EmbossLtColor; Emboss light color used for 3d effect. GFX_COLOR TextColor0; Character color 0 used for objects that supports text. GFX_COLOR TextColor1; Character color 1 used for objects that supports text. GFX_COLOR TextColorDisabled; Character color used when object is in a disabled state. GFX_COLOR Color0; Color 0 usually assigned to an Object state. GFX_COLOR Color1; Color 1 usually assigned to an Object state. GFX_COLOR ColorDisabled; Color used when an Object is in a disabled state. GFX_RESOURCE_HDR * pFont; Font selected for the scheme. GFX_FILL_STYLE fillStyle; must be set to a gradient type when using gradient GFX_COLOR CommonBkColor; Background color used to hide Objects. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-909 uint16_t CommonBkLeft; Horizontal starting position of the background. uint16_t CommonBkTop; Horizontal starting position of the background. GFX_BACKGROUND_TYPE CommonBkType; Specifies the type of background to use. GFX_RESOURCE_HDR * pCommonBkImage; Pointer to the background image used. Set this uint16_t AlphaValue; Alpha value used for alpha blending GFX_COLOR gradientStartColor; start color of the gradient fill GFX_COLOR gradientEndColor; end color of the gradient fill uint16_t EmbossSize; Emboss size of the panel for 3-D effect. Set to zero if not used. Remarks None. 5.2.2.7.26.45 GFX_GOL_OBJ_TYPE Enumeration C typedef enum { GFX_GOL_ANALOGCLOCK_TYPE, GFX_GOL_BUTTON_TYPE, GFX_GOL_CHART_TYPE, GFX_GOL_CHECKBOX_TYPE, GFX_GOL_DIGITALMETER_TYPE, GFX_GOL_EDITBOX_TYPE, GFX_GOL_GRID_TYPE, GFX_GOL_GROUPBOX_TYPE, GFX_GOL_LISTBOX_TYPE, GFX_GOL_METER_TYPE, GFX_GOL_PICTURECONTROL_TYPE, GFX_GOL_PROGRESSBAR_TYPE, GFX_GOL_RADIOBUTTON_TYPE, GFX_GOL_SCROLLBAR_TYPE, GFX_GOL_STATICTEXT_TYPE, GFX_GOL_TEXTENTRY_TYPE, GFX_GOL_WINDOW_TYPE, GFX_GOL_CUSTOM_TYPE, GFX_GOL_UNKNOWN_TYPE } GFX_GOL_OBJ_TYPE; Description GFX_GOL_OBJ_TYPE This enumeration specifies the different object types used in the library. Members Members Description GFX_GOL_ANALOGCLOCK_TYPE Type defined for Analog Clock Object. GFX_GOL_BUTTON_TYPE Type defined for Button Object. GFX_GOL_CHART_TYPE Type defined for Chart Object. GFX_GOL_CHECKBOX_TYPE Type defined for Check Box Object. GFX_GOL_DIGITALMETER_TYPE Type defined for Digital Meter Object. GFX_GOL_EDITBOX_TYPE Type defined for Edit Box Object. GFX_GOL_GRID_TYPE Type defined for Grid Object. GFX_GOL_GROUPBOX_TYPE Type defined for Group Box Object. GFX_GOL_LISTBOX_TYPE Type defined for List Box Object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-910 GFX_GOL_METER_TYPE Type defined for Meter Object. GFX_GOL_PICTURECONTROL_TYPE Type defined for Picture Control Object. GFX_GOL_PROGRESSBAR_TYPE Type defined for Progress Bar Object. GFX_GOL_RADIOBUTTON_TYPE Type defined for Radio Button Object. GFX_GOL_SCROLLBAR_TYPE Type defined for Slider or Scroll Bar Object. GFX_GOL_STATICTEXT_TYPE Type defined for Static Text Object. GFX_GOL_TEXTENTRY_TYPE Type defined for Text-Entry Object. GFX_GOL_WINDOW_TYPE Type defined for Window Object. GFX_GOL_CUSTOM_TYPE Type defined for Custom Object. GFX_GOL_UNKNOWN_TYPE Type is undefined and not supported by the library. Remarks None. 5.2.2.7.26.46 GFX_GOL_PROGRESSBAR Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t pos; uint16_t prevPos; uint16_t range; } GFX_GOL_PROGRESSBAR; Description The structure contains data for the progress bar Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). uint16_t pos; Current progress position. uint16_t prevPos; Previous progress position. uint16_t range; Sets the range of the object. 5.2.2.7.26.47 GFX_GOL_PROGRESSBAR_STATE Enumeration C typedef enum { GFX_GOL_PROGRESSBAR_DISABLED_STATE = 0x0002, GFX_GOL_PROGRESSBAR_VERTICAL_STATE = 0x0004, GFX_GOL_PROGRESSBAR_NOPROGRESS_STATE = 0x0008, GFX_GOL_PROGRESSBAR_DRAW_BAR_STATE = 0x2000, GFX_GOL_PROGRESSBAR_DRAW_STATE = 0x4000, GFX_GOL_PROGRESSBAR_HIDE_STATE = 0x8000 } GFX_GOL_PROGRESSBAR_STATE; Description Object States Definition: Members Members Description GFX_GOL_PROGRESSBAR_DISABLED_STATE = 0x0002 Bit for disabled state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-911 GFX_GOL_PROGRESSBAR_VERTICAL_STATE = 0x0004 Bit for orientation (0- horizontal, 1 - vertical). GFX_GOL_PROGRESSBAR_NOPROGRESS_STATE = 0x0008 Bit suppress rendering of progress in text. GFX_GOL_PROGRESSBAR_DRAW_BAR_STATE = 0x2000 Bit to indicate object must be redrawn. GFX_GOL_PROGRESSBAR_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_PROGRESSBAR_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.48 GFX_GOL_RADIOBUTTON Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; GFX_GOL_OBJ_HEADER * pHead; GFX_GOL_OBJ_HEADER * pNext; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; } GFX_GOL_RADIOBUTTON; Description the structure contains data for the Radio Button Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see OBJ_HEADER). GFX_GOL_OBJ_HEADER * pHead; Pointer to the first Radio Button in the group GFX_GOL_OBJ_HEADER * pNext; Pointer to the next Radio Button in the group uint16_t textHeight; Pre-computed text height GFX_XCHAR * pText; Pointer to the text GFX_ALIGNMENT alignment; text alignment 5.2.2.7.26.49 GFX_GOL_RADIOBUTTON_STATE Enumeration C typedef enum { GFX_GOL_RADIOBUTTON_FOCUSED_STATE = 0x0001, GFX_GOL_RADIOBUTTON_DISABLED_STATE = 0x0002, GFX_GOL_RADIOBUTTON_CHECKED_STATE = 0x0004, GFX_GOL_RADIOBUTTON_GROUP_STATE = 0x0008, GFX_GOL_RADIOBUTTON_DRAW_CHECK_STATE = 0x1000, GFX_GOL_RADIOBUTTON_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_RADIOBUTTON_DRAW_STATE = 0x4000, GFX_GOL_RADIOBUTTON_HIDE_STATE = 0x8000 } GFX_GOL_RADIOBUTTON_STATE; Description Object States Definition: Members Members Description GFX_GOL_RADIOBUTTON_FOCUSED_STATE = 0x0001 Bit for focus state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-912 GFX_GOL_RADIOBUTTON_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_RADIOBUTTON_CHECKED_STATE = 0x0004 Bit to indicate Radio Button is checked. GFX_GOL_RADIOBUTTON_GROUP_STATE = 0x0008 Bit to indicate the first Radio Button in the group. Each group MUST have this bit set for its first member even for a single member group. This means that any independent or stand alone Radio Button, the RB_GROUP bit must be always set. or alone in the group. GFX_GOL_RADIOBUTTON_DRAW_CHECK_STATE = 0x1000 Bit to indicate check mark should be redrawn. GFX_GOL_RADIOBUTTON_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_RADIOBUTTON_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_RADIOBUTTON_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.50 GFX_GOL_ROUNDDIAL Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t xCenter; uint16_t yCenter; uint16_t radius; uint16_t value; uint16_t max; uint16_t res; uint16_t curr_xPos; uint16_t curr_yPos; uint16_t new_xPos; uint16_t new_yPos; short vAngle; } GFX_GOL_ROUNDDIAL; Description The curr_xPos, curr_yPos, new_xPos and new_yPos parameters are internally generated to aid in the redrawing of the dial. User must avoid modifying these values. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). uint16_t xCenter; x coordinate center position. uint16_t yCenter; y coordinate center position. uint16_t radius; Radius of the dial. uint16_t value; Initial value of the dial. uint16_t max; Maximum value of variable value (maximum = 65535). uint16_t res; Resolution of movement. uint16_t curr_xPos; Current x position. uint16_t curr_yPos; Current y position. uint16_t new_xPos; New x position. uint16_t new_yPos; New y position. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-913 5.2.2.7.26.51 GFX_GOL_SCROLLBAR Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; int16_t currPos; uint16_t prevPos; uint16_t range; int16_t pos; uint16_t page; uint16_t thWidth; uint16_t thHeight; } GFX_GOL_SCROLLBAR; Description Defines the parameters required for a slider/scrollbar Object. Depending on the GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE state bit slider or scrollbar mode is set. If GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE is set, mode is slider; if not set mode is scroll bar. For scrollbar mode, focus rectangle is not drawn. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). int16_t currPos; Position of the slider relative to minimum. uint16_t prevPos; Previous position of the slider relative to minimum. uint16_t range; User defined range of the slider. Minimum value at 0 and maximum at 0x7FFF. int16_t pos; Position of the slider in range domain. uint16_t page; User specified resolution to incrementally change the position in range domain. uint16_t thWidth; Thumb width. This is computed internally. User must not change this value. uint16_t thHeight; Thumb width. This is computed internally. User must not change this value. 5.2.2.7.26.52 GFX_GOL_SCROLLBAR_STATE Enumeration C typedef enum { GFX_GOL_SCROLLBAR_FOCUSED_STATE = 0x0001, GFX_GOL_SCROLLBAR_DISABLED_STATE = 0x0002, GFX_GOL_SCROLLBAR_VERTICAL_STATE = 0x0004, GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE = 0x0010, GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE = 0x1000, GFX_GOL_SCROLLBAR_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_SCROLLBAR_DRAW_STATE = 0x4000, GFX_GOL_SCROLLBAR_HIDE_STATE = 0x8000 } GFX_GOL_SCROLLBAR_STATE; Description Object States Definition: Members Members Description GFX_GOL_SCROLLBAR_FOCUSED_STATE = 0x0001 Bit for focus state. GFX_GOL_SCROLLBAR_DISABLED_STATE = 0x0002 Bit for disabled state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-914 GFX_GOL_SCROLLBAR_VERTICAL_STATE = 0x0004 Bit to indicate the scroll bar is drawn with vertical orientation GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE = 0x0010 Bit to indicate the scroll bar is in slider mode. GFX_GOL_SCROLLBAR_DRAW_THUMB_STATE = 0x1000 Bit to indicate that only the thumb area will be redrawn GFX_GOL_SCROLLBAR_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_SCROLLBAR_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_SCROLLBAR_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.53 GFX_GOL_STATICTEXT Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; } GFX_GOL_STATICTEXT; Description Defines the parameters required for a Static Text Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see OBJ_HEADER). GFX_XCHAR * pText; The pointer to text used. GFX_ALIGNMENT alignment; text alignment 5.2.2.7.26.54 GFX_GOL_STATICTEXT_STATE Enumeration C typedef enum { GFX_GOL_STATICTEXT_DISABLED_STATE = 0x0002, GFX_GOL_STATICTEXT_FRAME_STATE = 0x0010, GFX_GOL_STATICTEXT_NOBACKGROUND_STATE = 0x0020, GFX_GOL_STATICTEXT_DRAW_UPDATE = 0x2000, GFX_GOL_STATICTEXT_DRAW_STATE = 0x4000, GFX_GOL_STATICTEXT_HIDE_STATE = 0x8000 } GFX_GOL_STATICTEXT_STATE; Description Object States Definition: Members Members Description GFX_GOL_STATICTEXT_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_STATICTEXT_FRAME_STATE = 0x0010 Bit to indicate frame is enabled. GFX_GOL_STATICTEXT_NOBACKGROUND_STATE = 0x0020 Bit to indicate background is enabled. GFX_GOL_STATICTEXT_DRAW_UPDATE = 0x2000 Bit to indicate object must be redrawn. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-915 GFX_GOL_STATICTEXT_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_STATICTEXT_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.55 GFX_GOL_TEXTENTRY Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t horizontalKeys; uint16_t verticalKeys; GFX_XCHAR * pTeOutput; GFX_ALIGNMENT alignment; uint16_t CurrentLength; uint16_t outputLenMax; KEYMEMBER * pActiveKey; KEYMEMBER * pHeadOfList; GFX_RESOURCE_HDR * pDisplayFont; } GFX_GOL_TEXTENTRY; Description Defines the parameters required for a TextEntry Object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all objects (see GFX_GOL_OBJ_HEADER). uint16_t horizontalKeys; Number of horizontal keys uint16_t verticalKeys; Number of vertical keys GFX_XCHAR * pTeOutput; Pointer to the buffer assigned by the user which holds the text shown in the editbox. GFX_ALIGNMENT alignment; text alignment uint16_t CurrentLength; Current length of the string in the buffer. The maximum value of this is equal to outputLenMax. uint16_t outputLenMax; Maximum expected length of output buffer pTeOutput KEYMEMBER * pActiveKey; Pointer to the active key KEYMEMBER. This is only used by the Widget. User must not change the value of this parameter directly. KEYMEMBER * pHeadOfList; Pointer to head of the list GFX_RESOURCE_HDR * pDisplayFont; Pointer to the font used in displaying the text. 5.2.2.7.26.56 GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE Enumeration C typedef enum { GFX_GOL_TEXTENTRY_NONE_COM = 0x00, GFX_GOL_TEXTENTRY_DELETE_COM = 0x01, GFX_GOL_TEXTENTRY_SPACE_COM = 0x02, GFX_GOL_TEXTENTRY_ENTER_COM = 0x03 } GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE; Description Optional COMMANDS assigned to keys 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-916 Members Members Description GFX_GOL_TEXTENTRY_NONE_COM = 0x00 This type is used when the key is not assigned to any command. GFX_GOL_TEXTENTRY_DELETE_COM = 0x01 This type is used to assign a "delete" command on a key. GFX_GOL_TEXTENTRY_SPACE_COM = 0x02 This type is used to assign an insert "space" command on a key. GFX_GOL_TEXTENTRY_ENTER_COM = 0x03 This type is used to assign an "enter" (carriage return) command on a key. 5.2.2.7.26.57 GFX_GOL_TEXTENTRY_STATE Enumeration C typedef enum { GFX_GOL_TEXTENTRY_DISABLED_STATE = 0x0002, GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE = 0x0004, GFX_GOL_TEXTENTRY_ECHO_HIDE_STATE = 0x0008, GFX_GOL_TEXTENTRY_DRAW_STATE = 0x4000, GFX_GOL_TEXTENTRY_HIDE_STATE = 0x8000, GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE = 0x2000, GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE = 0x1000 } GFX_GOL_TEXTENTRY_STATE; Description Object States Definition: Members Members Description GFX_GOL_TEXTENTRY_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE = 0x0004 Bit for press state. GFX_GOL_TEXTENTRY_ECHO_HIDE_STATE = 0x0008 Bit to hide the entered characters and instead echo "*" characters to the display. GFX_GOL_TEXTENTRY_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_TEXTENTRY_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. GFX_GOL_TEXTENTRY_UPDATE_KEY_STATE = 0x2000 Bit to indicate redraw of a key is needed GFX_GOL_TEXTENTRY_UPDATE_TEXT_STATE = 0x1000 Bit to indicate redraw of the text displayed is needed. 5.2.2.7.26.58 GFX_GOL_TRANSLATED_ACTION Enumeration C typedef enum { GFX_GOL_OBJECT_ACTION_INVALID = 0x3500, GFX_GOL_OBJECT_ACTION_PASSIVE, GFX_GOL_ANALOGCLOCK_ACTION_PRESSED, GFX_GOL_ANALOGCLOCK_ACTION_RELEASED, GFX_GOL_BUTTON_ACTION_PRESSED, GFX_GOL_BUTTON_ACTION_STILLPRESSED, GFX_GOL_BUTTON_ACTION_RELEASED, GFX_GOL_BUTTON_ACTION_CANCELPRESS, GFX_GOL_CHART_ACTION_SELECTED, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-917 GFX_GOL_CHECKBOX_ACTION_CHECKED, GFX_GOL_CHECKBOX_ACTION_UNCHECKED, GFX_GOL_CUSTOMCONTROL_ACTION_SELECTED, GFX_GOL_DIGITALMETER_ACTION_SELECTED, GFX_GOL_EDITBOX_ACTION_ADD_CHAR, GFX_GOL_EDITBOX_ACTION_DEL_CHAR, GFX_GOL_EDITBOX_ACTION_TOUCHSCREEN, GFX_GOL_GRID_ACTION_TOUCHED, GFX_GOL_GRID_ACTION_ITEM_SELECTED, GFX_GOL_GRID_ACTION_UP, GFX_GOL_GRID_ACTION_DOWN, GFX_GOL_GRID_ACTION_LEFT, GFX_GOL_GRID_ACTION_RIGHT, GFX_GOL_GROUPBOX_ACTION_SELECTED, GFX_GOL_LISTBOX_ACTION_SELECTED, GFX_GOL_LISTBOX_ACTION_MOVE, GFX_GOL_LISTBOX_ACTION_TOUCHSCREEN, GFX_GOL_METER_ACTION_SET, GFX_GOL_PICTURECONTROL_ACTION_SELECTED, GFX_GOL_PROGRESSBAR_ACTION_SELECTED, GFX_GOL_RADIOBUTTON_ACTION_CHECKED, GFX_GOL_SCROLLBAR_ACTION_INC, GFX_GOL_SCROLLBAR_ACTION_DEC, GFX_GOL_STATICTEXT_ACTION_SELECTED, GFX_GOL_TEXTENTRY_ACTION_RELEASED, GFX_GOL_TEXTENTRY_ACTION_PRESSED, GFX_GOL_TEXTENTRY_ACTION_ADD_CHAR, GFX_GOL_TEXTENTRY_ACTION_DELETE, GFX_GOL_TEXTENTRY_ACTION_SPACE, GFX_GOL_TEXTENTRY_ACTION_ENTER, GFX_GOL_WINDOW_ACTION_CLIENT, GFX_GOL_WINDOW_ACTION_TITLE } GFX_GOL_TRANSLATED_ACTION; Description GFX_GOL_TRANSLATED_ACTION This enumeration specifies the different object actions supported in the library. Members Members Description GFX_GOL_OBJECT_ACTION_INVALID = 0x3500 Invalid message response. GFX_GOL_OBJECT_ACTION_PASSIVE Passive message response. No change in object needed. GFX_GOL_ANALOGCLOCK_ACTION_PRESSED Analog Clock Pressed Action GFX_GOL_ANALOGCLOCK_ACTION_RELEASED Analog Clock Released Action GFX_GOL_BUTTON_ACTION_PRESSED Button pressed action ID. GFX_GOL_BUTTON_ACTION_STILLPRESSED Button is continuously pressed ID. GFX_GOL_BUTTON_ACTION_RELEASED Button released action ID. GFX_GOL_BUTTON_ACTION_CANCELPRESS Button released action ID with button press canceled. GFX_GOL_CHART_ACTION_SELECTED Chart selected action ID GFX_GOL_CHECKBOX_ACTION_CHECKED Check Box check action ID. GFX_GOL_CHECKBOX_ACTION_UNCHECKED Check Box un-check action ID. GFX_GOL_CUSTOMCONTROL_ACTION_SELECTED Custom Control selected action ID. GFX_GOL_DIGITALMETER_ACTION_SELECTED Digital Meter selected action ID. GFX_GOL_EDITBOX_ACTION_ADD_CHAR Edit Box insert character action ID. GFX_GOL_EDITBOX_ACTION_DEL_CHAR Edit Box remove character action ID. GFX_GOL_EDITBOX_ACTION_TOUCHSCREEN Edit Box touchscreen selected action ID. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-918 GFX_GOL_GRID_ACTION_TOUCHED Grid item touched action ID. GFX_GOL_GRID_ACTION_ITEM_SELECTED Grid item selected action ID. GFX_GOL_GRID_ACTION_UP Grid up action ID. GFX_GOL_GRID_ACTION_DOWN Grid down action ID. GFX_GOL_GRID_ACTION_LEFT Grid left action ID. GFX_GOL_GRID_ACTION_RIGHT Grid right action ID. GFX_GOL_GROUPBOX_ACTION_SELECTED Group Box selected action ID. GFX_GOL_LISTBOX_ACTION_SELECTED List Box item select action ID. GFX_GOL_LISTBOX_ACTION_MOVE List Box item move action ID. GFX_GOL_LISTBOX_ACTION_TOUCHSCREEN List Box touchscreen selected action ID. GFX_GOL_METER_ACTION_SET Meter set value action ID. GFX_GOL_PICTURECONTROL_ACTION_SELECTED Picture selected action ID. GFX_GOL_PROGRESSBAR_ACTION_SELECTED Progress Bar selected action ID. GFX_GOL_RADIOBUTTON_ACTION_CHECKED Radio Button check action ID. GFX_GOL_SCROLLBAR_ACTION_INC Slider or Scroll Bar increment action ID. GFX_GOL_SCROLLBAR_ACTION_DEC Slider or Scroll Bar decrement action ID. GFX_GOL_STATICTEXT_ACTION_SELECTED Static Text selected action ID. GFX_GOL_TEXTENTRY_ACTION_RELEASED TextEntry released action ID GFX_GOL_TEXTENTRY_ACTION_PRESSED TextEntry pressed action ID GFX_GOL_TEXTENTRY_ACTION_ADD_CHAR TextEntry add character action ID GFX_GOL_TEXTENTRY_ACTION_DELETE TextEntry delete character action ID GFX_GOL_TEXTENTRY_ACTION_SPACE TextEntry add space character action ID GFX_GOL_TEXTENTRY_ACTION_ENTER TextEntry enter action ID GFX_GOL_WINDOW_ACTION_CLIENT Window client area selected action ID. GFX_GOL_WINDOW_ACTION_TITLE Window title bar selected action ID. Remarks None. 5.2.2.7.26.59 GFX_GOL_TRANSLATED_ACTION, \ GFX_GOL_OBJ_HEADER *, \ GFX_GOL_MESSAGE * \ ) Type C typedef (boolGFX_GOL_MESSAGE_CALLBACK_FUNC GFX_GOL_TRANSLATED_ACTION, \ GFX_GOL_OBJ_HEADER *, \ GFX_GOL_MESSAGE * \ ))(); Description This application defined function is called by the GFX_GOL_ObjectMessage() function allowing the application the opportunity to process the user messages and customize object behavior as well as application controlled functions. GFX_GOL_ObjectMessage() calls this function when a valid message for an object in the active list is received. Application implements any action for the message in this callback function. If this callback function returns true, the message for the object will be processed using the default action of the object. If false is returned, the default action will not be performed. In this case, it is assumed that this callback function has performed the appropriate changes to the states of the objects. Preconditions None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-919 Parameters Parameters Description GFX_GOL_TRANSLATED_ACTION Translated message for the object GFX_GOL_OBJ_HEADER * Pointer to the object that processed the message. GFX_GOL_MESSAGE * Pointer to the message from user. Returns true - When true is returned, the object will set its state depending on the translated messages. false - When false is returned, the object will not process the translated message and will assume the application has performed necessary action on the message. Example None. 5.2.2.7.26.60 GFX_GOL_WINDOW Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; uint16_t textHeight; GFX_XCHAR * pText; GFX_ALIGNMENT alignment; GFX_RESOURCE_HDR * pBitmap; } GFX_GOL_WINDOW; Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). uint16_t textHeight; Pre-computed text height GFX_XCHAR * pText; Pointer to the title text GFX_ALIGNMENT alignment; text alignment GFX_RESOURCE_HDR * pBitmap; Pointer to the bitmap for the title bar 5.2.2.7.26.61 GFX_GOL_WINDOW_STATE Enumeration C typedef enum { GFX_GOL_WINDOW_FOCUSED_STATE = 0x0001, GFX_GOL_WINDOW_DISABLED_STATE = 0x0002, GFX_GOL_WINDOW_TITLECENTER_STATE = 0x0004, GFX_GOL_WINDOW_HIDE_STATE = 0x8000, GFX_GOL_WINDOW_DRAW_CLIENT_STATE = 0x4000, GFX_GOL_WINDOW_DRAW_TITLE_STATE = 0x2000, GFX_GOL_WINDOW_DRAW_STATE = 0x6000 } GFX_GOL_WINDOW_STATE; Description Object States Definition: Members Members Description GFX_GOL_WINDOW_FOCUSED_STATE = 0x0001 Bit for focus state 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-920 GFX_GOL_WINDOW_DISABLED_STATE = 0x0002 Bit for disabled state GFX_GOL_WINDOW_TITLECENTER_STATE = 0x0004 Bit to center the text on the Title Area GFX_GOL_WINDOW_HIDE_STATE = 0x8000 Bit to indicate window must be removed from screen GFX_GOL_WINDOW_DRAW_CLIENT_STATE = 0x4000 Bit to indicate client area must be redrawn GFX_GOL_WINDOW_DRAW_TITLE_STATE = 0x2000 Bit to indicate title area must be redrawn GFX_GOL_WINDOW_DRAW_STATE = 0x6000 Bits to indicate whole window must be redrawn 5.2.2.7.26.62 GFX_GRADIENT_STYLE Structure C typedef struct { GFX_FILL_STYLE type; GFX_COLOR startColor; GFX_COLOR endColor; uint8_t length; } GFX_GRADIENT_STYLE; Description This structure is used to describe the gradient style. Members Members Description GFX_FILL_STYLE type; selected the gradient type GFX_COLOR startColor; sets the starting color of gradient transition GFX_COLOR endColor; sets the ending color of gradient transition uint8_t length; defines the length of the gradient transition in pixels 5.2.2.7.26.63 GFX_LINE_STYLE Enumeration C typedef enum { GFX_LINE_TYPE_MASK = 0x0007, GFX_LINE_THICKNESS_MASK = 0x0010, GFX_LINE_STYLE_THIN_SOLID = 0x0A00, GFX_LINE_STYLE_THIN_DOTTED = 0x0A01, GFX_LINE_STYLE_THIN_DASHED = 0x0A04, GFX_LINE_STYLE_THICK_SOLID = 0x0A10, GFX_LINE_STYLE_THICK_DOTTED = 0x0A11, GFX_LINE_STYLE_THICK_DASHED = 0x0A14, GFX_LINE_STYLE_ANTI_ALIASED = 0x0A20 } GFX_LINE_STYLE; Description Defines the types of line styles. Members Members Description GFX_LINE_TYPE_MASK = 0x0007 DO NOT document, mask for line type GFX_LINE_THICKNESS_MASK = 0x0010 DO NOT document, mask for thickness 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-921 GFX_LINE_STYLE_THIN_SOLID = 0x0A00 solid line, 1 pixel wide (default) GFX_LINE_STYLE_THIN_DOTTED = 0x0A01 dotted line, 1 pixel wide GFX_LINE_STYLE_THIN_DASHED = 0x0A04 dashed line, , 1 pixel wide GFX_LINE_STYLE_THICK_SOLID = 0x0A10 solid line, 3 pixel wide GFX_LINE_STYLE_THICK_DOTTED = 0x0A11 dotted line, 3 pixel wide GFX_LINE_STYLE_THICK_DASHED = 0x0A14 dashed line, 3 pixel wide GFX_LINE_STYLE_ANTI_ALIASED = 0x0A20 anti-aliased line (future feature) 5.2.2.7.26.64 GFX_MCHP_BITMAP_HEADER Structure C typedef struct { uint8_t bitmapType; uint8_t colorDepth; int16_t height; int16_t width; } GFX_MCHP_BITMAP_HEADER; Description Structure describing the bitmap header. Members Members Description uint8_t bitmapType; type of image, information on how to render the image 0 - no compression, palette is present for color depth = 8, 4 and 1 BPP 1 - palette is provided as a separate object (see PALETTE_HEADER) for color depth = 8, 4, and 1 BPP, ID to the palette is embedded in the bitmap. uint8_t colorDepth; Color depth used int16_t height; Image height int16_t width; Image width 5.2.2.7.26.65 GFX_PALETTE_ENTRY Union C typedef union { uint16_t value; struct { uint16_t r : 5; uint16_t g : 6; uint16_t b : 5; } color; struct { uint16_t reserved : 12; uint16_t luma : 4; } monochrome; } GFX_PALETTE_ENTRY; Description Structure used for the palette entries. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-922 • For TFT: color is defined as 5-6-5 RGB format (5-bits for RED, 6-bits for GREEN and 5-bits for BLUE. • For Monochrome: 4 bits are used to represent the luma. Members Members Description uint16_t value; a 16-bit value representing a color or palette entry struct { uint16_t r : 5; uint16_t g : 6; uint16_t b : 5; } color; color value in 5-6-5 RGB format uint16_t r : 5; represents the RED component uint16_t g : 6; represents the GREEN component uint16_t b : 5; represents the BLUE component struct { uint16_t reserved : 12; uint16_t luma : 4; } monochrome; monochrome LUMA value uint16_t reserved : 12; reserved, used as a filler uint16_t luma : 4; monochrome LUMA value 5.2.2.7.26.66 GFX_PARTIAL_IMAGE_PARAM Structure C typedef struct { uint16_t width; uint16_t height; uint16_t xoffset; uint16_t yoffset; } GFX_PARTIAL_IMAGE_PARAM; Description Structure describing the partial image area to render. Members Members Description uint16_t width; Partial Image width uint16_t height; Partial Image height uint16_t xoffset; xoffset of tha partial image (with respect to the image horizontal origin) uint16_t yoffset; yoffset of tha partial image (with respect to the image vertical origin) 5.2.2.7.26.67 GFX_Primitive_DATA Structure C typedef struct { volatile uint8_t activePage; volatile uint8_t visualPage; uint8_t transitionPage; uint8_t foregroundPage; uint8_t backgroundPage; uint8_t destinationPage; GFX_LINE_STYLE lineType; uint16_t cursorX; uint16_t cursorY; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-923 GFX_BEVEL_RENDER_TYPE bevelDrawType; GFX_COLOR currentColor; GFX_FONT_CURRENT currentFont; GFX_RESOURCE_HDR * pResource; GFX_ALPHA_PARAMS alphaArea; GFX_TRANSITION_PARAMS transitionParams; GFX_COLOR line[480]; GFX_COLOR alphaLine[480]; uint8_t InvalidatedRectangleCount; GFX_GRADIENT_STYLE gradientStyle; } GFX_Primitive_DATA; Description GFX primitive data Members Members Description uint8_t foregroundPage; Initialize Alpha Values GFX_COLOR currentColor; Current Color for the instance GFX_COLOR line[480]; Storage for line data GFX_COLOR alphaLine[480]; Storage for alpha line data uint8_t InvalidatedRectangleCount; Double Buffer Variable Remarks None. 5.2.2.7.26.68 GFX_RECTANGULAR_AREA Structure C typedef struct { uint16_t left; uint16_t top; uint16_t right; uint16_t bottom; } GFX_RECTANGULAR_AREA; Description Structure describing a rectangular area in the frame buffer. 5.2.2.7.26.69 GFX_RESOURCE Enumeration C typedef enum { GFX_RESOURCE_MEMORY_FLASH = 0x0000, GFX_RESOURCE_MEMORY_EXTERNAL = 0x0001, GFX_RESOURCE_MEMORY_RAM = 0x0004, GFX_RESOURCE_MEMORY_EDS_EPMP = 0x0005, GFX_RESOURCE_TYPE_MCHP_MBITMAP = 0x0000, GFX_RESOURCE_TYPE_JPEG = 0x0100, GFX_RESOURCE_TYPE_BINARY = 0x0200, GFX_RESOURCE_TYPE_FONT = 0x0300, GFX_RESOURCE_TYPE_PALETTE = 0x0400, GFX_RESOURCE_COMP_NONE = 0x0000, GFX_RESOURCE_COMP_RLE = 0x1000, GFX_RESOURCE_COMP_IPU = 0x2000, GFX_RESOURCE_MCHP_MBITMAP_FLASH_NONE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_MCHP_MBITMAP_FLASH_RLE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-924 GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_RLE), GFX_RESOURCE_MCHP_MBITMAP_FLASH_IPU = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_MCHP_MBITMAP_EXTERNAL_NONE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_MCHP_MBITMAP_EXTERNAL_RLE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_RLE), GFX_RESOURCE_MCHP_MBITMAP_EXTERNAL_IPU = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_MCHP_MBITMAP_EDS_EPMP_NONE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_MCHP_MBITMAP_EDS_EPMP_RLE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_RLE), GFX_RESOURCE_MCHP_MBITMAP_EDS_EPMP_IPU = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_JPEG_FLASH_NONE = (GFX_RESOURCE_TYPE_JPEG | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_JPEG_EXTERNAL_NONE = (GFX_RESOURCE_TYPE_JPEG | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_JPEG_EDS_EPMP_NONE = (GFX_RESOURCE_TYPE_JPEG | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_BINARY_FLASH_NONE = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_BINARY_FLASH_IPU = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_BINARY_EXTERNAL_NONE = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_BINARY_EXTERNAL_IPU = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_BINARY_EDS_EPMP_NONE = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_BINARY_EDS_EPMP_IPU = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_IPU), GFX_RESOURCE_FONT_FLASH_NONE = (GFX_RESOURCE_TYPE_FONT | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_FONT_EXTERNAL_NONE = (GFX_RESOURCE_TYPE_FONT | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_FONT_RAM_NONE = (GFX_RESOURCE_TYPE_FONT | GFX_RESOURCE_MEMORY_RAM | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_FONT_EDS_NONE = (GFX_RESOURCE_TYPE_FONT | GFX_RESOURCE_MEMORY_EDS_EPMP | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_PALETTE_FLASH_NONE = (GFX_RESOURCE_TYPE_PALETTE | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_PALETTE_EXTERNAL_NONE = (GFX_RESOURCE_TYPE_PALETTE | GFX_RESOURCE_MEMORY_EXTERNAL | GFX_RESOURCE_COMP_NONE), GFX_RESOURCE_PALETTE_RAM_NONE = (GFX_RESOURCE_TYPE_PALETTE | GFX_RESOURCE_MEMORY_RAM | GFX_RESOURCE_COMP_NONE) } GFX_RESOURCE; Description Memory type enumeration to determine the source of data. Used in interpreting images, fonts and palette from different memory sources. Members Members Description GFX_RESOURCE_MEMORY_FLASH = 0x0000 internal flash GFX_RESOURCE_MEMORY_EXTERNAL = 0x0001 external memory GFX_RESOURCE_MEMORY_RAM = 0x0004 RAM 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-925 GFX_RESOURCE_MEMORY_EDS_EPMP = 0x0005 memory in EPMP, base addresses are are set in the hardware profile GFX_RESOURCE_TYPE_MCHP_MBITMAP = 0x0000 data resource is type Microchip bitmap GFX_RESOURCE_TYPE_JPEG = 0x0100 data resource is type JPEG GFX_RESOURCE_TYPE_BINARY = 0x0200 data resource is type binary GFX_RESOURCE_TYPE_FONT = 0x0300 data resource is type font GFX_RESOURCE_TYPE_PALETTE = 0x0400 data resource is type palette GFX_RESOURCE_COMP_NONE = 0x0000 data resource has no compression GFX_RESOURCE_COMP_RLE = 0x1000 data resource is compressed with RLE GFX_RESOURCE_COMP_IPU = 0x2000 data resource compressed with DEFLATE (for IPU) GFX_RESOURCE_MCHP_MBITMAP_FLASH_NONE = (GFX_RESOURCE_TYPE_MCHP_MBITMAP | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE) These are common resource combinations used by the graphics library Bitmaps GFX_RESOURCE_JPEG_FLASH_NONE = (GFX_RESOURCE_TYPE_JPEG | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE) JPEGS GFX_RESOURCE_BINARY_FLASH_NONE = (GFX_RESOURCE_TYPE_BINARY | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE) Binary GFX_RESOURCE_FONT_FLASH_NONE = (GFX_RESOURCE_TYPE_FONT | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE) Fonts GFX_RESOURCE_PALETTE_FLASH_NONE = (GFX_RESOURCE_TYPE_PALETTE | GFX_RESOURCE_MEMORY_FLASH | GFX_RESOURCE_COMP_NONE) Palettes 5.2.2.7.26.70 GFX_RESOURCE_BINARY Structure C typedef struct { union { uint32_t extAddress; uint8_gfx_image_prog * progByteAddress; uint16_gfx_image_prog * progWordAddress; const char * constAddress; char * ramAddress; __eds__ char * edsAddress; } location; uint32_t size; uint32_t param1; uint32_t param2; } GFX_RESOURCE_BINARY; Description Structure for Graphics Resource - binary data. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-926 Members Members Description uint32_t extAddress; generic address uint8_gfx_image_prog * progByteAddress; for addresses in program section uint16_gfx_image_prog * progWordAddress; for addresses in program section const char * constAddress; for addresses in FLASH char * ramAddress; for addresses in RAM __eds__ char * edsAddress; for addresses in EDS uint32_t param1; Parameters used for the GFX_RESOURCE. Depending on the GFX_RESOURCE type definition of param1 can change. For IPU and RLE compressed images, param1 indicates the compressed size of the image. uint32_t param2; Parameters used for the GFX_RESOURCE. Depending on the GFX_RESOURCE type 5.2.2.7.26.71 GFX_RESOURCE_FONT Structure C typedef struct { union { uint32_t extAddress; GFX_FONT_SPACE char * progByteAddress; char * ramAddress; __eds__ char * edsAddress; } location; GFX_FONT_HEADER header; } GFX_RESOURCE_FONT; Description Structure for Graphics Resource - Fonts. Members Members Description __eds__ char * edsAddress; for addresses in EDS 5.2.2.7.26.72 GFX_RESOURCE_HDR Structure C typedef struct { GFX_RESOURCE type; uint16_t ID; union { GFX_RESOURCE_IMAGE image; GFX_RESOURCE_FONT font; GFX_RESOURCE_BINARY binary; GFX_RESOURCE_PALETTE palette; } resource; } GFX_RESOURCE_HDR; Description Structure for Graphics Resource Header. This is the common header for all Graphics Resources. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-927 Members Members Description GFX_RESOURCE type; Graphics resource type, determines the type and location of data uint16_t ID; memory ID, user defined value to differentiate between graphics resources of the same type When using EDS_EPMP the following ID values are reserved and used by the Microchip display driver 0 - reserved (do not use) 1 - reserved for base address of EPMP CS1 2 - reserved for base address of EPMP CS2 5.2.2.7.26.73 GFX_RESOURCE_IMAGE Structure C typedef struct { union { uint32_t extAddress; uint8_gfx_image_prog * progByteAddress; uint16_gfx_image_prog * progWordAddress; const char * constAddress; char * ramAddress; __eds__ char * edsAddress; } location; uint16_t width; uint16_t height; union { uint32_t compressedSize; uint32_t reserved; } parameter1; union { uint32_t rawSize; uint32_t reserved; } parameter2; uint8_t colorDepth; uint8_t type; uint16_t paletteID; } GFX_RESOURCE_IMAGE; Description Structure for Graphics Resource - image. Members Members Description uint32_t extAddress; generic address uint8_gfx_image_prog * progByteAddress; for addresses in program section uint16_gfx_image_prog * progWordAddress; for addresses in program section const char * constAddress; for addresses in FLASH char * ramAddress; for addresses in RAM __eds__ char * edsAddress; for addresses in EDS uint16_t width; width of the image uint16_t height; height of the image uint32_t compressedSize; Parameters used for the GFX_RESOURCE. Depending on the GFX_RESOURCE type definition of param1 can change. For IPU and RLE compressed images, param1 indicates the compressed size of the image. uint32_t rawSize; Parameters used for the GFX_RESOURCE. Depending on the GFX_RESOURCE type definition of param2 can change. For IPU and RLE compressed images, param2 indicates the uncompressed size of the image. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-928 uint8_t colorDepth; color depth of the image uint8_t type; type of image, information on how to render the image 0x00 - no compression, palette is present for color depth = 8, 4 and 1 BPP 0x10 - palette is provided as a separate object (see PALETTE_HEADER) for color depth = 8, 4, and 1 BPP, ID to the palette is embedded color depth = 8, 4, and 1 BPP, in the bitmap. 0xYY - reserved uint16_t paletteID; if type == MCHP_BITMAP_PALETTE_STR (0x10), this represents the unique ID of the palette being used 5.2.2.7.26.74 GFX_RESOURCE_PALETTE Structure C typedef struct { union { uint32_t extAddress; const GFX_PALETTE_ENTRY * constByteAddress; GFX_PALETTE_ENTRY * ramAddress; } location; uint16_t numberOfEntries; uint16_t paletteID; } GFX_RESOURCE_PALETTE; Description Structure for Graphics Resource - Palette. Members Members Description uint16_t paletteID; Unique ID of the palette that will match the ID in the GFX_RESOURCE_HDR if the image has palette removed and supplied as a separate object. 5.2.2.7.26.75 GFX_STATUS Enumeration C typedef enum { GFX_STATUS_FAILURE = 0, GFX_STATUS_SUCCESS = 1 } GFX_STATUS; Description Status types for rendering. 5.2.2.7.26.76 GFX_STATUS_BIT Enumeration C typedef enum { GFX_STATUS_FAILURE_BIT = 0, GFX_STATUS_SUCCESS_BIT = 1, GFX_STATUS_ERROR_BIT = 2, GFX_STATUS_BUSY_BIT = 4, GFX_STATUS_READY_BIT = 8 } GFX_STATUS_BIT; Description Bit masks for additional status information. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-929 5.2.2.7.26.77 GFX_TRANSITION_DIRECTION Enumeration C typedef enum { LEFT_TO_RIGHT = 0, RIGHT_TO_LEFT, TOP_TO_BOTTOM, BOTTOM_TO_TOP, HORIZONTAL, VERTICAL } GFX_TRANSITION_DIRECTION; Description Direction enumeration to determine the direction of the selected GFX_TRANSITION_TYPE. Members Members Description LEFT_TO_RIGHT = 0 option used in SLIDE, PUSH transition type (GFX_TRANSITION_TYPE) RIGHT_TO_LEFT option used in SLIDE, PUSH transition type (GFX_TRANSITION_TYPE) TOP_TO_BOTTOM option used in SLIDE, PUSH transition type (GFX_TRANSITION_TYPE) BOTTOM_TO_TOP option used in SLIDE, PUSH transition type (GFX_TRANSITION_TYPE) HORIZONTAL option used in EXPANDING_LINE and CONTRACTING_LINE transition type (GFX_TRANSITION_TYPE) VERTICAL option used in EXPANDING_LINE and CONTRACTING_LINE transition type (GFX_TRANSITION_TYPE) 5.2.2.7.26.78 GFX_TRANSITION_PARAMS Structure C typedef struct { uint16_t left; uint16_t top; uint16_t delay_ms; uint8_t sourcePage; uint8_t destinationPage; uint8_t type; uint8_t param1; uint8_t param2; } GFX_TRANSITION_PARAMS; Description GFX transition parameters Remarks None. 5.2.2.7.26.79 GFX_TRANSITION_TYPE Enumeration C typedef enum { EXPANDING_RECTANGLE = 0, CONTRACTING_RECTANGLE, SLIDE, PUSH, EXPANDING_LINE, CONTRACTING_LINE 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-930 } GFX_TRANSITION_TYPE; Description Transition type enumeration to determine the type of the transition. Each type will require specific parameters when setting up the transition operation (GFXSetupTransition() or GFXTransition()). GFX_TRANSITION_TYPE param1 param2 (sets the direction of transition) PLAIN pixel block size not used EXPANDING_RECTANGLE pixel block size not used CONTRACTING_RECTANGLE pixel block size not used SLIDE pixel block size LEFT_TO_RIGHT, RIGHT_TO_LEFT, TOP_TO_BOTTOM, BOTTOM_TO_TOP PUSH pixel block size LEFT_TO_RIGHT, RIGHT_TO_LEFT, TOP_TO_BOTTOM, BOTTOM_TO_TOP EXPANDING_LINE pixel block size HORIZONTAL, VERTICAL CONTRACTING_LINE pixel block size HORIZONTAL, VERTICAL Members Members Description EXPANDING_RECTANGLE = 0 param1 -> Pixel-block size CONTRACTING_RECTANGLE param1 -> Pixel-block size SLIDE param1 -> Pixel-block size, param2 -> Sliding direction LEFT_TO_RIGHT/RIGHT_TO_LEFT/TOP_TO_BOTTOM/BOTTOM_TO_TOP PUSH param1 -> Pixel-block size, param2 -> Sliding direction LEFT_TO_RIGHT/RIGHT_TO_LEFT/TOP_TO_BOTTOM/BOTTOM_TO_TOP EXPANDING_LINE param1 -> Pixel-block size, param2 -> direction HORIZONTAL/VERTICAL CONTRACTING_LINE param1 -> Pixel-block size, param2 -> direction HORIZONTAL/VERTICAL 5.2.2.7.26.80 GFX_TRIG_FUNCTION_TYPE Enumeration C typedef enum { GFX_TRIG_SINE_TYPE = 0, GFX_TRIG_COSINE_TYPE = 1 } GFX_TRIG_FUNCTION_TYPE; Description DOM-IGNORE-START ****************************************************************** • Overview: Graphics Library helper function for trigonometric sine • cosine angles are defined in a sine/cosine table. • This type enumeration specifies if the value retrieved • from that look up table is for a sine(angle) or • cosine(angle) value. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-931 5.2.2.7.26.81 GOL_PANEL_PARAM Structure C typedef struct { int16_t panelLeft; int16_t panelTop; int16_t panelRight; int16_t panelBottom; GFX_COLOR panelFaceColor; GFX_COLOR panelEmbossLtColor; GFX_COLOR panelEmbossDkColor; uint16_t panelEmbossSize; uint16_t panelRadius; GFX_RESOURCE_HDR * pPanelImage; GFX_FILL_STYLE panelFillStyle; GFX_COLOR panelGradientStartColor; GFX_COLOR panelGradientEndColor; uint16_t panelAlpha; } GOL_PANEL_PARAM; Description GOL_PANEL_PARAM This structure defines the panel parameters when rendering a panel. Remarks None. 5.2.2.7.26.82 GRID Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; short numColumns; short numRows; short cellHeight; short cellWidth; short focusX; short focusY; GRIDITEM * gridObjects; } GRID; Description Defines the parameters required for a grid Object. Clipping is not supported in grid object. Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_OBJ_HEADER). short numColumns; Number of columns drawn for the Grid. short numRows; Number of rows drawn for the Grid. short cellHeight; The height of each cell in pixels. short cellWidth; The width of each cell in pixels. short focusX; The x position of the cell to be focused. short focusY; The y position of the cell to be focused. GRIDITEM * gridObjects; The pointer to grid items 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-932 5.2.2.7.26.83 GRIDITEM Structure C typedef struct { void * data; uint16_t status; } GRIDITEM; Description Defines the grid item. Members Members Description void * data; Indicates if the Grid Item is type GRIDITEM_IS_TEXT or GRIDITEM_IS_BITMAP uint16_t status; indicates the status of the Grid Item 5.2.2.7.26.84 IMAGE_STRETCH Enumeration C typedef enum { IMAGE_NORMAL = 1, IMAGE_X2 = 2 } IMAGE_STRETCH; Description GFX image stretch Remarks None. 5.2.2.7.26.85 IMG_FILE_FORMAT Type C typedef enum _IMG_FILE_FORMAT IMG_FILE_FORMAT; Description IMG_ImageFileFormat specifies all the supported image file formats 5.2.2.7.26.86 IMG_FILE_SYSTEM_API Type C typedef struct _IMG_FILE_SYSTEM_API IMG_FILE_SYSTEM_API; Description IMG_FileSystemAPI holds function pointers to the used File System APIs 5.2.2.7.26.87 IMG_LOOP_CALLBACK Type C typedef void (* IMG_LOOP_CALLBACK)(void); Description IMG_LoopCallback is a callback function which is called in every loop of the decoding cycle so that user application can do some 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-933 maintainance activities 5.2.2.7.26.88 IMG_PIXEL_OUTPUT Type C typedef void (* IMG_PIXEL_OUTPUT)(IMG_PIXEL_XY_RGB_888 *pPix); Description IMG_PixelOutput is a callback function which receives the color information of the output pixel 5.2.2.7.26.89 IMG_PIXEL_XY_RGB_888 Type C typedef struct _IMG_PIXEL_XY_RGB_888 IMG_PIXEL_XY_RGB_888; Description IMG_PixelRgb holds the RGB information of a pixel in BYTES 5.2.2.7.26.90 INPUT_DEVICE_EVENT Enumeration C typedef enum { EVENT_INVALID = 0, EVENT_MOVE, EVENT_PRESS, EVENT_STILLPRESS, EVENT_RELEASE, EVENT_KEYSCAN, EVENT_CHARCODE, EVENT_SET, EVENT_SET_STATE, EVENT_CLR_STATE } INPUT_DEVICE_EVENT; Description INPUT_DEVICE_EVENT This enumeration specifies the different user input device events supported in the library. Members Members Description EVENT_INVALID = 0 An invalid event. EVENT_MOVE A move event. EVENT_PRESS A press event. EVENT_STILLPRESS A continuous press event. EVENT_RELEASE A release event. EVENT_KEYSCAN A keyscan event, parameters has the object ID keyboard scan code. EVENT_CHARCODE Character code is presented at the parameters. EVENT_SET A generic set event. EVENT_SET_STATE A set state event. EVENT_CLR_STATE A clear state event. Remarks None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-934 5.2.2.7.26.91 INPUT_DEVICE_TYPE Enumeration C typedef enum { TYPE_UNKNOWN = 0, TYPE_KEYBOARD, TYPE_TOUCHSCREEN, TYPE_MOUSE, TYPE_TIMER, TYPE_SYSTEM } INPUT_DEVICE_TYPE; Description INPUT_DEVICE_TYPE This enumeration specifies the different user input devices supported in the library. Members Members Description TYPE_UNKNOWN = 0 Unknown device. TYPE_KEYBOARD Keyboard. TYPE_TOUCHSCREEN Touchscreen. TYPE_MOUSE Mouse. TYPE_TIMER Timer. TYPE_SYSTEM System Messages. Remarks None. 5.2.2.7.26.92 int16_gfx_image_prog Type C typedef int16_prog_pack int16_gfx_image_prog; Description This is type int16_gfx_image_prog. 5.2.2.7.26.93 int16_prog Type C typedef __prog__ int16_t int16_prog; Description This is type int16_prog. 5.2.2.7.26.94 int16_prog_pack Type C typedef __pack_upper_byte int16_t int16_prog_pack; Description This is type int16_prog_pack. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-935 5.2.2.7.26.95 int32_gfx_image_prog Type C typedef int32_prog_pack int32_gfx_image_prog; Description This is type int32_gfx_image_prog. 5.2.2.7.26.96 int32_prog Type C typedef __prog__ int32_t int32_prog; Description This is type int32_prog. 5.2.2.7.26.97 int32_prog_pack Type C typedef __pack_upper_byte int32_t int32_prog_pack; Description This is type int32_prog_pack. 5.2.2.7.26.98 int8_gfx_image_prog Type C typedef int8_prog_pack int8_gfx_image_prog; Description This is type int8_gfx_image_prog. 5.2.2.7.26.99 int8_prog Type C typedef __prog__ int8_t int8_prog; Description This is type int8_prog. 5.2.2.7.26.100 int8_prog_pack Type C typedef __pack_upper_byte int8_t int8_prog_pack; Description This is type int8_prog_pack. 5.2.2.7.26.101 KEYMEMBER Structure C typedef struct { 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-936 uint16_t left; uint16_t top; uint16_t right; uint16_t bottom; uint16_t index; uint16_t state; bool update; GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE command; GFX_XCHAR * pKeyName; int16_t textWidth; int16_t textHeight; void * pNextKey; } KEYMEMBER; Description Defines the parameters and the strings assigned for each key. Members Members Description uint16_t left; Left position of the key uint16_t top; Top position of the key uint16_t right; Right position of the key uint16_t bottom; Bottom position of the key uint16_t index; Index of the key in the list uint16_t state; State of the key. Either Pressed (GFX_GOL_TEXTENTRY_KEY_PRESSED_STATE) or Released (0) bool update; flag to indicate key is to be redrawn with the current state GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE command; Command of the key. Either TE_DELETE_COM, TE_SPACE_COM or TE_ENTER_COM. GFX_XCHAR * pKeyName; Pointer to the custom text assigned to the key. This is displayed over the face of the key. int16_t textWidth; Computed text width, done at creation. Used to predict size and position of text on the key face. int16_t textHeight; Computed text height, done at creation. Used to predict size and position of text on the key face. void * pNextKey; Pointer to the next key parameters. 5.2.2.7.26.102 LAYER_ACTIONS Enumeration C typedef enum { ENABLE = 0x80, DISABLE = 0, UPDATE, SET_SIZE, SET_PAGE, SET_PAGE_START, SET_LAYER_START } LAYER_ACTIONS; Description GFX layering actions Remarks None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-937 5.2.2.7.26.103 PALETTE_ENTRY Union C typedef union { uint16_t value; struct { uint16_t r : 5; uint16_t g : 6; uint16_t b : 5; } color; struct { uint16_t reserved : 12; uint16_t luma : 4; } monochrome; } PALETTE_ENTRY; Description Structure used for the palette entries. • For TFT: color is defined as 5-6-5 RGB format (5-bits for RED, 6-bits for GREEN and 5-bits for BLUE. • For Monochrome: 4 bits are used to represent the luma. Members Members Description uint16_t value; a 16-bit value representing a color or palette entry struct { uint16_t r : 5; uint16_t g : 6; uint16_t b : 5; } color; color value in 5-6-5 RGB format uint16_t r : 5; represents the RED component uint16_t g : 6; represents the GREEN component uint16_t b : 5; represents the BLUE component struct { uint16_t reserved : 12; uint16_t luma : 4; } monochrome; monochrome LUMA value uint16_t reserved : 12; reserved, used as a filler uint16_t luma : 4; monochrome LUMA value 5.2.2.7.26.104 PALETTE_EXTERNAL Type C typedef GFX_EXTDATA PALETTE_EXTERNAL; Description Structure for palette stored in EXTERNAL memory space. (example: External SPI or parallel Flash, EDS_EPMP) 5.2.2.7.26.105 PALETTE_FLASH Structure C typedef struct { short type; PALETTE_HEADER header; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-938 PALETTE_ENTRY * pPaletteEntry; } PALETTE_FLASH; Description Structure for the palette stored in FLASH memory. Members Members Description short type; Type must be FLASH PALETTE_HEADER header; Contains information on the palette PALETTE_ENTRY * pPaletteEntry; Pointer to the palette. Number of entries is determined by the header. 5.2.2.7.26.106 PALETTE_HEADER Structure C typedef struct { uint16_t id; uint16_t length; } PALETTE_HEADER; Description Structure for the palette header. Members Members Description uint16_t id; User defined ID uint16_t length; number of palette entries (number of colors in the palette) 5.2.2.7.26.107 PUTIMAGE_PARAM Structure C typedef struct { uint16_t width; uint16_t height; uint16_t xoffset; uint16_t yoffset; IMAGE_STRETCH stretch; uint8_t transparentFlag; GFX_COLOR transparentColor; uint8_gfx_image_prog* image; GFX_COLOR palette[256]; } PUTIMAGE_PARAM; Description GFX put image param Members Members Description uint16_t width; Parital Image width uint16_t height; Partial Image height uint16_t xoffset; xoffset of image uint16_t yoffset; yoffset of image IMAGE_STRETCH stretch; stretch of the image uint8_t transparentFlag; transparent Color flag 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-939 GFX_COLOR transparentColor; transparent Color uint8_gfx_image_prog* image; pointer to the image GFX_COLOR palette[256]; palette used for <8BPP images Remarks None. 5.2.2.7.26.108 uint16_gfx_image_prog Type C typedef uint16_prog_pack uint16_gfx_image_prog; Description This is type uint16_gfx_image_prog. 5.2.2.7.26.109 uint16_prog Type C typedef __prog__ uint16_t uint16_prog; Description This is type uint16_prog. 5.2.2.7.26.110 uint16_prog_pack Type C typedef __pack_upper_byte uint16_t uint16_prog_pack; Description This is type uint16_prog_pack. 5.2.2.7.26.111 uint32_gfx_image_prog Type C typedef uint32_prog_pack uint32_gfx_image_prog; Description This is type uint32_gfx_image_prog. 5.2.2.7.26.112 uint32_prog Type C typedef __prog__ uint32_t uint32_prog; Description This is type uint32_prog. 5.2.2.7.26.113 uint32_prog_pack Type C typedef __pack_upper_byte uint32_t uint32_prog_pack; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-940 Description This is type uint32_prog_pack. 5.2.2.7.26.114 uint8_gfx_image_prog Type C typedef uint8_prog_pack uint8_gfx_image_prog; Description GFX Image data Types 5.2.2.7.26.115 uint8_prog Type C typedef __prog__ uint8_t uint8_prog; Description General program space data types 5.2.2.7.26.116 uint8_prog_pack Type C typedef __pack_upper_byte uint8_t uint8_prog_pack; Description This is type uint8_prog_pack. 5.2.2.7.26.117 BLACK Macro C #define BLACK GFX_RGBConvert(0, 0, 0) Description This is macro BLACK. 5.2.2.7.26.118 BLUE Macro C #define BLUE GFX_RGBConvert(0, 0, 128) Description This is macro BLUE. 5.2.2.7.26.119 BRIGHTBLUE Macro C #define BRIGHTBLUE GFX_RGBConvert(0, 0, 255) Description This is macro BRIGHTBLUE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-941 5.2.2.7.26.120 BRIGHTCYAN Macro C #define BRIGHTCYAN GFX_RGBConvert(0, 255, 255) Description This is macro BRIGHTCYAN. 5.2.2.7.26.121 BRIGHTGREEN Macro C #define BRIGHTGREEN GFX_RGBConvert(0, 255, 0) Description This is macro BRIGHTGREEN. 5.2.2.7.26.122 BRIGHTMAGENTA Macro C #define BRIGHTMAGENTA GFX_RGBConvert(255, 0, 255) Description This is macro BRIGHTMAGENTA. 5.2.2.7.26.123 BRIGHTRED Macro C #define BRIGHTRED GFX_RGBConvert(255, 0, 0) Description This is macro BRIGHTRED. 5.2.2.7.26.124 BRIGHTYELLOW Macro C #define BRIGHTYELLOW GFX_RGBConvert(255, 255, 0) Description This is macro BRIGHTYELLOW. 5.2.2.7.26.125 BROWN Macro C #define BROWN GFX_RGBConvert(255, 128, 0) Description This is macro BROWN. 5.2.2.7.26.126 BURLYWOOD Macro C #define BURLYWOOD GFX_RGBConvert(222, 184, 135) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-942 Description This is macro BURLYWOOD. 5.2.2.7.26.127 CH_CLR0 Macro C #define CH_CLR0 WHITE() Description Bright Blue 5.2.2.7.26.128 CH_CLR1 Macro C #define CH_CLR1 BLACK() Description Bright Red 5.2.2.7.26.129 CH_CLR10 Macro C #define CH_CLR10 WHITE() Description Light Blur 5.2.2.7.26.130 CH_CLR11 Macro C #define CH_CLR11 BLACK() Description Light Red 5.2.2.7.26.131 CH_CLR12 Macro C #define CH_CLR12 WHITE() Description Light Green 5.2.2.7.26.132 CH_CLR13 Macro C #define CH_CLR13 BLACK() Description Light Yellow 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-943 5.2.2.7.26.133 CH_CLR14 Macro C #define CH_CLR14 WHITE() Description Light Orange 5.2.2.7.26.134 CH_CLR15 Macro C #define CH_CLR15 BLACK() Description Gold 5.2.2.7.26.135 CH_CLR2 Macro C #define CH_CLR2 WHITE() Description Bright Green 5.2.2.7.26.136 CH_CLR3 Macro C #define CH_CLR3 BLACK() Description Bright Yellow 5.2.2.7.26.137 CH_CLR4 Macro C #define CH_CLR4 WHITE() Description Orange 5.2.2.7.26.138 CH_CLR5 Macro C #define CH_CLR5 BLACK() Description Blue 5.2.2.7.26.139 CH_CLR6 Macro C #define CH_CLR6 WHITE() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-944 Description Red 5.2.2.7.26.140 CH_CLR7 Macro C #define CH_CLR7 BLACK() Description Green 5.2.2.7.26.141 CH_CLR8 Macro C #define CH_CLR8 WHITE() Description Yellow 5.2.2.7.26.142 CH_CLR9 Macro C #define CH_CLR9 BLACK() Description Dark Orange 5.2.2.7.26.143 CHART_MARGIN Macro C #define CHART_MARGIN 2 // Margin from the edges. Description Margin from the edges. 5.2.2.7.26.144 CHART_YGRIDCOUNT Macro C #define CHART_YGRIDCOUNT 6 // defines the number of grids to be drawn on the y-axis (includes the origin at y). Description defines the number of grids to be drawn on the y-axis (includes the origin at y). 5.2.2.7.26.145 ConvertColor25 Macro C #define ConvertColor25(color) (GFX_COLOR)((color & (0x00FCFCFCul))>>2) Description This is macro ConvertColor25. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-945 5.2.2.7.26.146 ConvertColor50 Macro C #define ConvertColor50(color) (GFX_COLOR)((color & (0x00FEFEFEul))>>1) Description 75, 50, 25 percentage color conversion macros. Used in converting colors to these percentages when performing alpha blending of colors using software alpha blending operation. 5.2.2.7.26.147 ConvertColor75 Macro C #define ConvertColor75(color) (GFX_COLOR)(ConvertColor50(color) + ConvertColor25(color)) Description This is macro ConvertColor75. 5.2.2.7.26.148 CopyPageWindow Macro C #define CopyPageWindow(alphaArea, width, height) \ GFX_AlphaBlendWindow(alphaArea,width,height,100) Description None Preconditions None Parameters Parameters Description None None Returns None Example None 5.2.2.7.26.149 CYAN Macro C #define CYAN GFX_RGBConvert(0, 128, 128) Description This is macro CYAN. 5.2.2.7.26.150 DARKGRAY Macro C #define DARKGRAY GFX_RGBConvert(64, 64, 64) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-946 Description This is macro DARKGRAY. 5.2.2.7.26.151 DARKORANGE Macro C #define DARKORANGE GFX_RGBConvert(255, 140, 0) Description This is macro DARKORANGE. 5.2.2.7.26.152 GFX_ActivePageGet Macro C #define GFX_ActivePageGet GFX_Primitive_instance.activePage Preconditions None. Returns None. Example Remarks: 5.2.2.7.26.153 GFX_AlphaParamsSet Macro C #define GFX_AlphaParamsSet(fArea,fLeft,fTop,bArea,bLeft,bTop,dArea,dLeft,dTop) \ GFX_Primitive_instance.alphaArea.foregroundPage = fArea;\ GFX_Primitive_instance.alphaArea.foregroundLeft = fLeft;\ GFX_Primitive_instance.alphaArea.foregroundTop = fTop;\ GFX_Primitive_instance.alphaArea.backgroundPage = bArea;\ GFX_Primitive_instance.alphaArea.backgroundLeft = bLeft;\ GFX_Primitive_instance.alphaArea.backgroundTop = bTop;\ GFX_Primitive_instance.alphaArea.destinationPag e = dArea;\ GFX_Primitive_instance.alphaArea.destinationLef t = dLeft;\ GFX_Primitive_instance.alphaArea.destinationTop = dTop Description None 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-947 Preconditions None Parameters Parameters Description None None Returns None Example None 5.2.2.7.26.154 GFX_BUFFER1 Macro C #define GFX_BUFFER1 (0) Description This is macro GFX_BUFFER1. 5.2.2.7.26.155 GFX_BUFFER2 Macro C #define GFX_BUFFER2 (1) Description This is macro GFX_BUFFER2. 5.2.2.7.26.156 GFX_COMP_MASK Macro C #define GFX_COMP_MASK 0xF000 Description This is macro GFX_COMP_MASK. 5.2.2.7.26.157 GFX_CONFIG_OBJECT_METER_DEGREECOUNT Macro C #define GFX_CONFIG_OBJECT_METER_DEGREECOUNT 9 Description This is a Meter compile time option to define how many degrees per scale, computed per octant Example for 5 division per octant 45/5 = 9. So every 9 degrees a scale is drawn for a 5 scale division per octant. 5.2.2.7.26.158 GFX_CONFIG_OBJECT_METER_RESOLUTION Macro C #define GFX_CONFIG_OBJECT_METER_RESOLUTION 10 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-948 Description This is a Meter compile time option to define the factor that the meter widget will divide minValue, maxValue 5.2.2.7.26.159 GFX_CONFIG_OBJECT_METER_SCALE_COUNT Macro C #define GFX_CONFIG_OBJECT_METER_SCALE_COUNT 4 Description This is a Meter compile time option to define how many characters will be allocated for the scale labels. Use this define in accordance to the maxValue-minValue. Example if maxValue-minValue = 500, SCALECHARCOUNT should be 3. if maxValue-minValue = 90, SCALECHARCOUNT = 2 You must include the decimal point if this feature is enabled (see MTR_ACCURACY state bit). 5.2.2.7.26.160 GFX_FONT_SPACE Macro C #define GFX_FONT_SPACE const Description Font space section. The fonts can be located in psv (constant) or program space in PIC24/dsPIC MCUs. This define allows for switching of the pointer type used to access the font structure in memory See: GraphicsConfig.h for the application define. 5.2.2.7.26.161 GFX_FontAlignmentSet Macro C #define GFX_FontAlignmentSet(align) GFX_Primitive_instance.currentFont.alignment = align; Description • 1 when font orientation is vertical • 0 when font orientation is horizontal Preconditions None. Returns None. Example 5.2.2.7.26.162 GFX_GOL_ANALOGCLOCK_DISABLED Macro C #define GFX_GOL_ANALOGCLOCK_DISABLED 0x0002 // Bit for disabled state. Description Bit for disabled state. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-949 5.2.2.7.26.163 GFX_GOL_ANALOGCLOCK_DRAW Macro C #define GFX_GOL_ANALOGCLOCK_DRAW 0x4000 // Bit to indicate button must be redrawn. Description Bit to indicate button must be redrawn. 5.2.2.7.26.164 GFX_GOL_ANALOGCLOCK_HIDE Macro C #define GFX_GOL_ANALOGCLOCK_HIDE 0x8000 // Bit to indicate button must be removed from screen. Description Bit to indicate button must be removed from screen. 5.2.2.7.26.165 GFX_GOL_ANALOGCLOCK_PRESSED Macro C #define GFX_GOL_ANALOGCLOCK_PRESSED 0x0004 // Bit for press state. Description Bit for press state. 5.2.2.7.26.166 GFX_GOL_ANALOGCLOCK_TICK Macro C #define GFX_GOL_ANALOGCLOCK_TICK 0x1000 // Bit to tick second hand Description Bit to tick second hand 5.2.2.7.26.167 GFX_GOL_ANALOGCLOCK_UPDATE_HOUR Macro C #define GFX_GOL_ANALOGCLOCK_UPDATE_HOUR 0x2000 // Bit to indicate hour hand must be redrawn Description Bit to indicate hour hand must be redrawn 5.2.2.7.26.168 GFX_GOL_ANALOGCLOCK_UPDATE_MINUTE Macro C #define GFX_GOL_ANALOGCLOCK_UPDATE_MINUTE 0x0100 // Bit to indicate minute hand must be redrawn Description Bit to indicate minute hand must be redrawn 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-950 5.2.2.7.26.169 GFX_GOL_ANALOGCLOCK_UPDATE_SECOND Macro C #define GFX_GOL_ANALOGCLOCK_UPDATE_SECOND 0x0200 // Bit to indicate minute hand must be redrawn Description Bit to indicate minute hand must be redrawn 5.2.2.7.26.170 GFX_GOL_ButtonPressStateImageGet Macro C #define GFX_GOL_ButtonPressStateImageGet(pObject, pImage) \ (((GFX_GOL_BUTTON *)pObject)->pPressImage) Description This function gets the image used when in the pressed state. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to the image resource. Example None. 5.2.2.7.26.171 GFX_GOL_ButtonPressStateImageSet Macro C #define GFX_GOL_ButtonPressStateImageSet(pObject, pImage) \ (((GFX_GOL_BUTTON *)pObject)->pPressImage = pImage) Description This function sets the image to be used when in the pressed state. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pImage pointer to the image resource. Returns None. Example // assume ImageIcon is a valid GFX_RESOURCE_HDR 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-951 GFX_RESOURCE_HDR *pMyIcon = &ImageIcon; GFX_GOL_BUTTON *pButton; GFX_GOL_ButtonPressStateImageSet(pButton , pMyIcon); 5.2.2.7.26.172 GFX_GOL_ButtonReleaseStateImageGet Macro C #define GFX_GOL_ButtonReleaseStateImageGet(pObject, pImage) \ (((GFX_GOL_BUTTON *)pObject)->pReleaseImage) Description This function gets the image used when in the released state. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to the image resource. Example None. 5.2.2.7.26.173 GFX_GOL_ButtonReleaseStateImageSet Macro C #define GFX_GOL_ButtonReleaseStateImageSet(pObject, pImage) \ (((GFX_GOL_BUTTON *)pObject)->pReleaseImage = pImage) Description This function sets the image to be used when in the released state. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pImage pointer to the image resource. Returns None. Example // assume ImageIcon is a valid GFX_RESOURCE_HDR GFX_RESOURCE_HDR *pMyIcon = &ImageIcon; GFX_GOL_BUTTON *pButton; GFX_GOL_ButtonReleaseStateImageSet(pButton , pMyIcon); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-952 5.2.2.7.26.174 GFX_GOL_ButtonTextGet Macro C #define GFX_GOL_ButtonTextGet(pObject) (((GFX_GOL_BUTTON *)pObject)->pText) Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example GFX_XCHAR *pChar; GFX_GOL_BUTTON GFX_GOL_BUTTON[2]; pChar = GFX_GOL_ButtonTextGet(GFX_GOL_BUTTON[0]); 5.2.2.7.26.175 GFX_GOL_CHART_3D_ENABLE Macro C #define GFX_GOL_CHART_3D_ENABLE 0x0008 // Bit to indicate that bar charts are to be drawn with 3-D effect Description Bit to indicate that bar charts are to be drawn with 3-D effect 5.2.2.7.26.176 GFX_GOL_CHART_BAR Macro C #define GFX_GOL_CHART_BAR 0x0200 // Bit to indicate the chart is type bar. If both PIE and BAR types are set BAR type has higher priority. Description Bit to indicate the chart is type bar. If both PIE and BAR types are set BAR type has higher priority. 5.2.2.7.26.177 GFX_GOL_CHART_BAR_HOR Macro C #define GFX_GOL_CHART_BAR_HOR 0x0240 // These bits (with CH_BAR bit set), sets the bar chart to be drawn horizontally. Description These bits (with CH_BAR bit set), sets the bar chart to be drawn horizontally. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-953 5.2.2.7.26.178 GFX_GOL_CHART_DISABLED Macro C #define GFX_GOL_CHART_DISABLED 0x0002 // Bit for disabled state. Description Bit for disabled state. 5.2.2.7.26.179 GFX_GOL_CHART_DONUT Macro C #define GFX_GOL_CHART_DONUT 0x0140 // These bits (with CH_PIE bit set), sets the pie chart to be drawn in a donut shape. Description These bits (with CH_PIE bit set), sets the pie chart to be drawn in a donut shape. 5.2.2.7.26.180 GFX_GOL_CHART_DRAW Macro C #define GFX_GOL_CHART_DRAW 0x4000 // Bit to indicate chart must be redrawn. Description Bit to indicate chart must be redrawn. 5.2.2.7.26.181 GFX_GOL_CHART_DRAW_DATA Macro C #define GFX_GOL_CHART_DRAW_DATA 0x2000 // Bit to indicate data portion of the chart must be redrawn. Description Bit to indicate data portion of the chart must be redrawn. 5.2.2.7.26.182 GFX_GOL_CHART_HIDE Macro C #define GFX_GOL_CHART_HIDE 0x8000 // Bit to indicate chart must be removed from screen. Description Bit to indicate chart must be removed from screen. 5.2.2.7.26.183 GFX_GOL_CHART_LEGEND Macro C #define GFX_GOL_CHART_LEGEND 0x0001 // Bit to indicate that legend is to be shown. Usable only when seriesCount > 1. Description Bit to indicate that legend is to be shown. Usable only when seriesCount > 1. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-954 5.2.2.7.26.184 GFX_GOL_CHART_NUMERIC Macro C #define GFX_GOL_CHART_NUMERIC 0x0080 // This bit is used only for bar charts. If this bit is set, it indicates that the Description This bit is used only for bar charts. If this bit is set, it indicates that the bar chart labels for variables are numeric. If this bit is not set, it indicates that the bar chart labels for variables are alphabets. 5.2.2.7.26.185 GFX_GOL_CHART_PERCENT Macro C #define GFX_GOL_CHART_PERCENT 0x0010 // Bit to indicate that the pie chart will be drawn with percentage values shown for the sample data. Description Bit to indicate that the pie chart will be drawn with percentage values shown for the sample data. For bar chart, if CH_VALUE is set, it toggles the value shown to percentage. 5.2.2.7.26.186 GFX_GOL_CHART_PIE Macro C #define GFX_GOL_CHART_PIE 0x0100 // Bit to indicate the chart is type pie. If both PIE and BAR types are set BAR type has higher priority. Description Bit to indicate the chart is type pie. If both PIE and BAR types are set BAR type has higher priority. 5.2.2.7.26.187 GFX_GOL_CHART_VALUE Macro C #define GFX_GOL_CHART_VALUE 0x0004 // Bit to indicate that the values of the bar chart data or pie chart data are to be shown Description Bit to indicate that the values of the bar chart data or pie chart data are to be shown 5.2.2.7.26.188 GFX_GOL_ChartAxisLabelFontGet Macro C #define GFX_GOL_ChartAxisLabelFontGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pAxisLabelsFont) Description Macros: GFX_GOL_ChartAxisLabelFontGet(pCh) This macro returns the location of the font used for the X and Y axis labels of the chart. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-955 Parameters Parameters Description pCh Pointer to the object. Returns Returns the address of the current font used for the title text. Side Effects none 5.2.2.7.26.189 GFX_GOL_ChartAxisLabelFontSet Macro C #define GFX_GOL_ChartAxisLabelFontSet(pCh, pNewFont) (((GFX_GOL_CHART *)pCh)->prm.pAxisLabelsFont = pNewFont) Description Macros: GFX_GOL_ChartAxisLabelFontSet(pCh, pNewFont) This macro sets the location of the font used for the X and Y axis labels of the chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. pNewFont Pointer to the font used. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.190 GFX_GOL_ChartColorTableGet Macro C #define GFX_GOL_ChartColorTableGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pColor) Description Macros: GFX_GOL_ChartColorTableGet(pCh) This macro returns the current color table used for the pie and bar charts. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-956 Parameters Parameters Description pCh Pointer to the object. Returns Returns the address of the color table used. Side Effects none 5.2.2.7.26.191 GFX_GOL_ChartColorTableSet Macro C #define GFX_GOL_ChartColorTableSet(pCh, pNewTable) ((((GFX_GOL_CHART *)pCh)->prm.pColor) = pNewTable) Description Macros: GFX_GOL_ChartColorTableSet(pCh, pNewTable) This macro sets the color table used to draw the data in pie and bar charts. Preconditions none Parameters Parameters Description pCh Pointer to the object. pNewTable Pointer to the color table that will be used. Returns none. Side Effects none 5.2.2.7.26.192 GFX_GOL_ChartGridLabelFontGet Macro C #define GFX_GOL_ChartGridLabelFontGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pGridLabelsFont) Description Macros: GFX_GOL_ChartGridLabelFontGet(pCh) This macro returns the location of the font used for the X and Y axis grid labels of the chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-957 Returns Returns the address of the current font used for the title text. Side Effects none 5.2.2.7.26.193 GFX_GOL_ChartGridLabelFontSet Macro C #define GFX_GOL_ChartGridLabelFontSet(pCh, pNewFont) (((GFX_GOL_CHART *)pCh)->prm.pGridLabelsFont = pNewFont) Description Macros: GFX_GOL_ChartGridLabelFontSet(pCh, pNewFont) This macro sets the location of the font used for the X and Y axis grid labels of the chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. pNewFont Pointer to the font used. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.194 GFX_GOL_ChartPercentMaxGet Macro C #define GFX_GOL_ChartPercentMaxGet(pCh) (pCh->prm.perMax) Description Macros: ChGetPercentMax(pCh) This macro returns the current maximum value of the percentage range that will be drawn for bar charts when CH_PERCENTAGE bit state is set. Preconditions none Parameters Parameters Description pCh Pointer to the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-958 Returns Returns the maximum percentage value set when bar charts are drawn. Side Effects none 5.2.2.7.26.195 GFX_GOL_ChartPercentMinGet Macro C #define GFX_GOL_ChartPercentMinGet(pCh) (pCh->prm.perMin) Description Macros: ChGetPercentMin(pCh) This macro returns the current minimum value of the percentage range that will be drawn for bar charts when CH_PERCENTAGE bit state is set. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the minimum percentage value when bar charts are drawn. Side Effects none 5.2.2.7.26.196 GFX_GOL_ChartPercentRangeGet Macro C #define GFX_GOL_ChartPercentRangeGet(pCh) (pCh->prm.perMax - pCh->prm.perMin) Description This macro gets the percentage range for bar charts. The value returned is calculated from percentage max - min. To get the minimum use ChGetPercentMin() and to get the maximum use ChGetPercentMax(). Preconditions none Parameters Parameters Description pCh Pointer to the chart object. Returns Percentage range computed from max-min. Side Effects none. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-959 5.2.2.7.26.197 GFX_GOL_ChartSampleEndGet Macro C #define GFX_GOL_ChartSampleEndGet(pCh) ((GFX_GOL_CHART *)pCh)->prm.smplEnd Description Macros: GFX_GOL_ChartSampleEndGet(pCh) This macro returns the sampling end value. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the sample end point. Side Effects none 5.2.2.7.26.198 GFX_GOL_ChartSampleLabelGet Macro C #define GFX_GOL_ChartSampleLabelGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pSmplLabel) Description Macros: GFX_GOL_ChartSampleLabelGet(pCh) This macro returns the address of the current text string used for the sample axis label of the bar chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the pointer to the current sample axis label text of the bar chart. Side Effects none 5.2.2.7.26.199 GFX_GOL_ChartSampleLabelSet Macro C #define GFX_GOL_ChartSampleLabelSet(pCh, pNewXLabel) (((GFX_GOL_CHART *)pCh)->prm.pSmplLabel = pNewXLabel) Description Macros: GFX_GOL_ChartSampleLabelSet(pCh, pNewXLabel) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-960 This macro sets the address of the current text string used for the sample axis label of the bar chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. pNewXLabel pointer to the string to be used as an sample axis label of the bar chart. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.200 GFX_GOL_ChartSampleRangeGet Macro C #define GFX_GOL_ChartSampleRangeGet(pCh) (GFX_GOL_ChartSampleEndGet(pCh) - GFX_GOL_ChartSampleStartGet(pCh)) Description This macro gets the sample range for pie or bar charts. The value returned is calculated from smplEnd - smplStart. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. Returns Sample range computed from smplEnd - smplStart. Side Effects none. 5.2.2.7.26.201 GFX_GOL_ChartSampleStartGet Macro C #define GFX_GOL_ChartSampleStartGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.smplStart) Description Macros: GFX_GOL_ChartSampleStartGet(pCh) This macro returns the sampling start value. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-961 Parameters Parameters Description pCh Pointer to the object. Returns Returns the sample start point. Side Effects none 5.2.2.7.26.202 GFX_GOL_ChartSeriesHide Macro C #define GFX_GOL_ChartSeriesHide(pCh, seriesNum) (GFX_GOL_ChartDataSeriesSet(pCh, seriesNum, HIDE_DATA)) Description Macros: GFX_GOL_ChartSeriesHide(CHART *pCh, uint16_t seriesNum) This macro sets the specified data series number show flag to be set to HIDE_DATA. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. seriesNum The data series number that will be modified. If this number is zero, all the entries' flag in the list will be set to HIDE_DATA. Returns Returns the same passed number if successful otherwise -1 if unsuccesful. Side Effects none Example See ChShowSeries() example. 5.2.2.7.26.203 GFX_GOL_ChartShowSeriesCountGet Macro C #define GFX_GOL_ChartShowSeriesCountGet(pCh) (pCh->prm.seriesCount) Description Macros: GFX_GOL_ChartShowSeriesCountGet(pCh) This macro shows the number of data series that has its show flag set to SHOW_DATA Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-962 Parameters Parameters Description pCh Pointer to the object. Returns Returns the number of data series with its show flag set to SHOW_DATA. Side Effects none 5.2.2.7.26.204 GFX_GOL_ChartShowSeriesSet Macro C #define GFX_GOL_ChartShowSeriesSet(pCh, seriesNum) (GFX_GOL_ChartDataSeriesSet(pCh, seriesNum, SHOW_DATA)) Description Macros: short GFX_GOL_ChartShowSeriesSet(CHART *pCh, uint16_t seriesNum) This macro sets the specified data series number show flag to be set to SHOW_DATA. Preconditions none Parameters Parameters Description pCh Pointer to the chart object. seriesNum The data series number that will be modified. If this number is zero, all the entries' flag in the list will be set to SHOW_DATA. Returns Returns the same passed number if successful otherwise -1 if unsuccesful. Side Effects none Example // from the example in ChCreate() we change the items to be shown when // GFX_OBJ_Draw() is called. // reset all data series to be HIDE_DATA ChHideSeries(pMyChart, 0); // set data series 1 (V1Data) to be shown ChShowSeries(pMyChart, 1); // draw the chart GFX_OBJ_Draw(); ..... * 5.2.2.7.26.205 GFX_GOL_ChartShowSeriesStatusGet Macro C #define GFX_GOL_ChartShowSeriesStatusGet(pDSeries) (pDSeries->show) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-963 Description Macros: GFX_GOL_ChartShowSeriesStatusGet(pDSeries) This macro returns the show ID status of the DATASERIES. Preconditions none Parameters Parameters Description pDSeries Pointer to the data series(DATASERIES) that is being checked. Returns Returns the status of the show flag. 1 - (SHOW_DATA) means that the show status flag is set. 0 - (HIDE_DATA) means that the show status flag is not set. Side Effects none 5.2.2.7.26.206 GFX_GOL_ChartTitleFontGet Macro C #define GFX_GOL_ChartTitleFontGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pTitleFont) Description Macros: GFX_GOL_ChartTitleFontGet(pCh) This macro returns the location of the font used for the title of the chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the address of the current font used for the title text. Side Effects none 5.2.2.7.26.207 GFX_GOL_ChartTitleFontSet Macro C #define GFX_GOL_ChartTitleFontSet(pCh, pNewFont) (((GFX_GOL_CHART *)pCh)->prm.pTitleFont = pNewFont) Description Macros: GFX_GOL_ChartTitleFontSet(pCh, pNewFont) This macro sets the location of the font used for the title of the chart. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-964 Preconditions none Parameters Parameters Description pCh Pointer to the object. pNewFont Pointer to the font used. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.208 GFX_GOL_ChartTitleGet Macro C #define GFX_GOL_ChartTitleGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pTitle) Description Macros: GFX_GOL_ChartTitleGet(pCh) This macro returns the address of the current text string used for the title of the chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the pointer to the current title text used. Side Effects none 5.2.2.7.26.209 GFX_GOL_ChartTitleSet Macro C #define GFX_GOL_ChartTitleSet(pCh, pNewTitle) (((GFX_GOL_CHART *)pCh)->prm.pTitle = pNewTitle) Description Macros: GFX_GOL_ChartTitleSet(pCh, pNewTitle) This macro sets the address of the current text string used for the title of the chart. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-965 Parameters Parameters Description pCh Pointer to the object. pNewTitle pointer to the string to be used as a title of the chart. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.210 GFX_GOL_ChartValueLabelGet Macro C #define GFX_GOL_ChartValueLabelGet(pCh) (((GFX_GOL_CHART *)pCh)->prm.pValLabel) Description Macros: GFX_GOL_ChartValueLabelGet(pCh) This macro returns the address of the current text string used for the value axis label of the bar chart. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the pointer to the current value axis label text of the bar chart. Side Effects none 5.2.2.7.26.211 GFX_GOL_ChartValueLabelSet Macro C #define GFX_GOL_ChartValueLabelSet(pCh, pNewValueLabel) (((GFX_GOL_CHART *)pCh)->prm.pValLabel = pNewValueLabel) Description Macros: GFX_GOL_ChartValueLabelSet(pCh, pNewYLabel) This macro sets the address of the current text string used for the value axis label of the bar chart. Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-966 Parameters Parameters Description pCh Pointer to the object. pNewYLabel pointer to the string to be used as an value axis label of the bar chart. Returns none. Side Effects none Example See ChCreate() example. 5.2.2.7.26.212 GFX_GOL_ChartValueMaxGet Macro C #define GFX_GOL_ChartValueMaxGet(pCh) (pCh->prm.valMax) Description Macros: GFX_GOL_ChartValueMaxGet(pCh) This macro returns the current maximum value that will be drawn for bar charts. Preconditions none Parameters Parameters Description pCh Pointer to the object. Returns Returns the maximum value set when bar charts are drawn. Side Effects none 5.2.2.7.26.213 GFX_GOL_ChartValueMinGet Macro C #define GFX_GOL_ChartValueMinGet(pCh) (pCh->prm.valMin) Description Macros: GFX_GOL_ChartValueMinGet(pCh) This macro returns the current minimum value that will be drawn for bar charts. Preconditions none Parameters Parameters Description pCh Pointer to the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-967 Returns Returns the minimum value set when bar charts are drawn. Side Effects none 5.2.2.7.26.214 GFX_GOL_ChartValueRangeGet Macro C #define GFX_GOL_ChartValueRangeGet(pCh) (pCh->prm.valMax - pCh->prm.valMin) Description This macro gets the current range for bar charts. The value returned is calculated from the current (valMax - valMin) set. To get the minimum use ChGetValueMin() and to get the maximum use ChGetValueMax(). Preconditions none Parameters Parameters Description pCh Pointer to the chart object. Returns Value range computed from valMax-valMin. Side Effects none. 5.2.2.7.26.215 GFX_GOL_CheckBoxTextGet Macro C #define GFX_GOL_CheckBoxTextGet(pObject) (((GFX_GOL_CHECKBOX *)pObject)->pText) Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example // assume CHECK_BOX_OBJECT is a radio button that exists GFX_XCHAR *pChar; GFX_GOL_CHECKBOX *pObject = &CHECK_BOX_OBJECT; pChar = GFX_GOL_CheckBoxTextGet(pObject); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-968 5.2.2.7.26.216 GFX_GOL_CUSTOMCONTROL_DISABLED Macro C #define GFX_GOL_CUSTOMCONTROL_DISABLED 0x0002 // disabled Description disabled 5.2.2.7.26.217 GFX_GOL_CUSTOMCONTROL_DRAW Macro C #define GFX_GOL_CUSTOMCONTROL_DRAW 0x4000 // whole control must be redrawn Description whole control must be redrawn 5.2.2.7.26.218 GFX_GOL_CUSTOMCONTROL_DRAW_BAR Macro C #define GFX_GOL_CUSTOMCONTROL_DRAW_BAR 0x2000 // control bar should be redrawn Description control bar should be redrawn 5.2.2.7.26.219 GFX_GOL_CUSTOMCONTROL_HIDE Macro C #define GFX_GOL_CUSTOMCONTROL_HIDE 0x8000 // must be removed from screen Description must be removed from screen 5.2.2.7.26.220 GFX_GOL_CustomControlGetPos Macro C #define GFX_GOL_CustomControlGetPos(pCc) pCc->pos Description Macros: GFX_GOL_CustomControlGetPos(pCc) returns position Preconditions none Parameters Parameters Description pCc pointer to the object Returns current position 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-969 Side Effects none Remarks none 5.2.2.7.26.221 GFX_GOL_CustomControlSetPos Macro C #define GFX_GOL_CustomControlSetPos(pCc, position) pCc->pos = position Description Macros: GFX_GOL_CustomControlSetPos(pCc,position) sets the current position of the control Preconditions none Parameters Parameters Description pCc the pointer to the object position new position Returns none Remarks none 5.2.2.7.26.222 GFX_GOL_DIGITALMETER_INDENT Macro C #define GFX_GOL_DIGITALMETER_INDENT 0x02 Description This is a DigitalMeter compile time option to define the indent constant for the text used in the frame. 5.2.2.7.26.223 GFX_GOL_DIGITALMETER_WIDTH Macro C #define GFX_GOL_DIGITALMETER_WIDTH 16 Description This is a DigitalMeter compile time option to define the user should change this value depending on the number of digits he wants to display. 5.2.2.7.26.224 GFX_GOL_DigitalMeterValueGet Macro C #define GFX_GOL_DigitalMeterValueGet(pObject) \ (((GFX_GOL_DIGITALMETER*)pObject)->value) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-970 Description This function returns the current value of the digital meter. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current value of the object. Example #define MAXVALUE 100; GFX_GOL_DIGITALMETER *pMeter; uint32_t ctr = 0; // create scroll bar here and initialize parameters pMeter = GFX_GOL_DigitalMeterCreate(....) GFX_GOL_ObjectStateSet(pMeter, GFX_GOL_DIGITALMETER_DRAW_STATE); // draw the scroll bar GFX_GOL_ObjectListDraw(); // a routine that updates the position of the thumb through some // conditions while("some condition") { GFX_GOL_DigitalMeterValueSet(pMeter, ctr); GFX_GOL_ObjectStateSet( pMeter, GFX_GOL_DIGITALMETER_UPDATE_STATE); // update the screen GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } if (GFX_GOL_DigitalMeterValueGet(pScrollBar) > MAXVALUE) return 0; else "do something else" 5.2.2.7.26.225 GFX_GOL_FONT_DEFAULT_H_FILE Macro C #define GFX_GOL_FONT_DEFAULT_H_FILE 5.2.2.7.26.226 GFX_GOL_GroupboxTextGet Macro C #define GFX_GOL_GroupboxTextGet(pObject) (((GFX_GOL_GROUPBOX *)pObject)->pText) Description This function returns the address of the current text string used by the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-971 Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example GFX_XCHAR *pChar; GFX_GOL_GROUPBOX pGroupbox; pChar = GFX_GOL_GroupboxTextGet(pGroupbox); 5.2.2.7.26.227 GFX_GOL_ListBoxItemCountGet Macro C #define GFX_GOL_ListBoxItemCountGet(pObject) \ (((GFX_GOL_LISTBOX *)pObject)->itemsNumber) Description This function returns the count of items in the list box. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. Returns The number of items in the list box. Example None. 5.2.2.7.26.228 GFX_GOL_ListBoxItemImageGet Macro C #define GFX_GOL_ListBoxItemImageGet(pItem) (((GFX_GOL_LISTITEM *)pItem)->pImage) Description This function gets the image set for a list box item. Preconditions Object must exist in memory. Parameters Parameters Description pItem pointer to the list box item. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-972 Returns Pointer to the image used for the item. Example See GFX_GOL_ListBoxItemListGet() example. 5.2.2.7.26.229 GFX_GOL_ListBoxItemImageSet Macro C #define GFX_GOL_ListBoxItemImageSet(pItem, pImage) (((GFX_GOL_LISTITEM *)pItem)->pImage = pImage) Description This function sets the image for a list box item. Preconditions Object must exist in memory. Parameters Parameters Description pItem pointer to the list box item. pImage pointer to the image resource. Returns None. Example See GFX_GOL_ListBoxItemAdd() and GFX_GOL_ListBoxItemListGet() example. 5.2.2.7.26.230 GFX_GOL_ListBoxItemListGet Macro C #define GFX_GOL_ListBoxItemListGet(pObject) \ ((GFX_GOL_LISTITEM *)((GFX_GOL_LISTBOX *)pObject)->pItemList) Description This function returns the pointer to the item list of the list box. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. Returns The pointer to the item list of the list box. Example // assume: // pLb is a initialized to a list box in memory // myIcon is a valid image in memory 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-973 GFX_GOL_LISTITEM *pList, *pItem; GFX_RESOURCE_HDR *pMyIcon = &myIcon; pList = GFX_GOL_ListBoxItemListGet(pLb); pItem = pList; // set the image for all the items to myIcon // set the last item image to NULL do { GFX_GOL_ListBoxImageSet(pItem, &myIcon); } while(pItem->pNextItem != NULL); // get the last item's image and set to null if not null if (GFX_GOL_ListBoxItemImageGet(pItem) != NULL) GFX_GOL_ListBoxImageSet(pItem, NULL); 5.2.2.7.26.231 GFX_GOL_ListBoxItemSelectStatusClear Macro C #define GFX_GOL_ListBoxItemSelectStatusClear(pObject, pItem) \ \ if(pItem->status & GFX_GOL_LISTBOX_ITEM_STATUS_SELECTED) \ GFX_GOL_ListBoxSelectionChange((LISTBOX *)pObject, pItem); Description This function clears the selection status of the item. Preconditions Object must exist in memory. Parameters Parameters Description pObject The pointer to the object. pItem The pointer the item that will have the selected status cleared. Returns None. Example None. 5.2.2.7.26.232 GFX_GOL_ListBoxItemSelectStatusSet Macro C #define GFX_GOL_ListBoxItemSelectStatusSet(pObject, pItem) \ \ if(!(pItem->status & GFX_GOL_LISTBOX_ITEM_STATUS_SELECTED)) \ GFX_GOL_ListBoxSelectionChange((LISTBOX *)pObject, pItem); Description This function sets the selection status of the item to selected. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-974 Parameters Parameters Description pObject The pointer to the object. pItem The pointer the item that will have the selected status set to selected. Returns None. Example None. 5.2.2.7.26.233 GFX_GOL_MeterMaximumValueGet Macro C #define GFX_GOL_MeterMaximumValueGet(pObject) (((GFX_GOL_METER *)pObject)->maxValue) Description This function returns the maximum value set for the meter. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current maximum value set for the object. Example None. 5.2.2.7.26.234 GFX_GOL_MeterMinimumValueGet Macro C #define GFX_GOL_MeterMinimumValueGet(pObject) (((GFX_GOL_METER *)pObject)->minValue) Description This function returns the minimum value set for the meter. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current minimum value set for the object. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-975 5.2.2.7.26.235 GFX_GOL_MeterTitleFontSet Macro C #define GFX_GOL_MeterTitleFontSet(pObject, pNewFont) (((GFX_GOL_METER *)pObject)->pTitleFont = pNewFont) Description This function sets the meter title font used. Font pointer must be initialized to a valid GFX_RESOURCE_HDR. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pNewFont pointer to the selected font. Returns None. Example None. 5.2.2.7.26.236 GFX_GOL_MeterTypeSet Macro C #define GFX_GOL_MeterTypeSet(pObject, type) (((GFX_GOL_METER *)pObject)->type = type) Description This function sets the meter draw type. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. type the draw type selected (see GFX_GOL_METER_DRAW_TYPE for more information). Returns None. Example None. 5.2.2.7.26.237 GFX_GOL_MeterValueFontSet Macro C #define GFX_GOL_MeterValueFontSet(pObject, pNewFont) (((GFX_GOL_METER *)pObject)->pValueFont = pNewFont) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-976 Description This function sets the meter's displayed value font used. Font pointer must be initialized to a valid GFX_RESOURCE_HDR. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pNewFont pointer to the selected font. Returns None. Example None. 5.2.2.7.26.238 GFX_GOL_MeterValueGet Macro C #define GFX_GOL_MeterValueGet(pMtr) (((GFX_GOL_METER*)pMtr)->value) Description This function returns the current value of the meter. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current value of the object. Example #define MAXVALUE 100; GFX_GOL_METER *pMeter; uint32_t ctr = 0; // create scroll bar here and initialize parameters pMeter = GFX_GOL_MeterCreate(....) GFX_GOL_ObjectStateSet(pMeter, GFX_GOL_METER_DRAW_STATE); // draw the scroll bar GFX_GOL_ObjectListDraw(); // a routine that updates the position of the thumb through some // conditions while("some condition") { GFX_GOL_MeterValueSet(pMeter, ctr); GFX_GOL_ObjectStateSet( pMeter, GFX_GOL_METER_UPDATE_DRAW_STATE); 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-977 // update the screen GFX_GOL_ObjectListDraw(); // update ctr here ctr = "some source of value"; } if (GFX_GOL_MeterValueGet(pScrollBar) > MAXVALUE) return 0; else "do something else" 5.2.2.7.26.239 GFX_GOL_ObjectStateClear Macro C #define GFX_GOL_ObjectStateClear(pObject, stateBits) \ ((((GFX_GOL_OBJ_HEADER*)pObject)->state) &= (~(stateBits))) Description This function clears the state bits of the given object. Object must be redrawn to display the changes. It is possible to set several state bits with this function. Preconditions None. Parameters Parameters Description pObject Pointer to the object. stateBits Defines which state bits are to be cleared. Please refer to specific objects for object state bits definition for details Returns GFX_STATUS_SUCCESS - is returned if the clear was successful. GFX_STATUS_FAILURE - is returned if the clear was not successful. Example See GFX_GOL_ObjectStateSet() for code example. 5.2.2.7.26.240 GFX_GOL_ObjectStateGet Macro C #define GFX_GOL_ObjectStateGet(pObject, stateBits) \ (((GFX_GOL_OBJ_HEADER*)pObject)->state & stateBits) Description This function retrieves the current value of the state bits of an object. It is possible to get several state bits. Preconditions None. Parameters Parameters Description pObject Pointer to the object. stateBits Defines which state bits are to be retrieved. Please refer to specific objects for object state bits definition for details 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-978 Returns The current status of the specified state bits. Example #define BTN_HIDE 0x8000 GFX_GOL_BUTTON *pB; // pB is created and initialized // do something here to set state // Hide the button (remove from screen) if (GFX_GOL_ObjectStateGet(pB, GFX_GOL_BUTTON_HIDE_STATE)) { GFX_ColorSet(pB->pGolScheme->CommonBkColor); GFX_BarDraw(pB->left, pB->top,pB->right,pB->bottom); } 5.2.2.7.26.241 GFX_GOL_ObjectStateSet Macro C #define GFX_GOL_ObjectStateSet(pObject, stateBits) \ ((((GFX_GOL_OBJ_HEADER*)pObject)->state) |= stateBits) Description This function sets the state bits of the given object. Object must be redrawn to display the changes. It is possible to set several state bits with this function. Preconditions None. Parameters Parameters Description pObject Pointer to the object. stateBits Defines which state bits are to be cleared. Please refer to specific objects for object state bits definition for details Returns GFX_STATUS_SUCCESS - is returned if the set was successful. GFX_STATUS_FAILURE - is returned if the set was not successful. Example void SetMessage(uint16_t msg, GFX_GOL_BUTTON* pB) { switch(msg) { case GFX_GOL_BUTTON_ACTION_PRESSED: // set pressed and redraw GFX_GOL_ObjectStateSet(pB, BTN_PRESSED|BTN_DRAW); break; case GFX_GOL_BUTTON_ACTION_RELEASED: // reset pressed GFX_GOL_ObjectStateClear(pB, BTN_PRESSED); // redraw GFX_GOL_ObjectStateSet(pB, BTN_DRAW); break; default: break; } } 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-979 5.2.2.7.26.242 GFX_GOL_ProgressBarPositionGet Macro C #define GFX_GOL_ProgressBarPositionGet(pObject) (((GFX_GOL_PROGRESSBAR*)pObject)->pos) Description This function returns the current position of the progress bar. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current position of the scroll bar thumb. Example See GFX_GOL_ProgressBarPositionSet() example. 5.2.2.7.26.243 GFX_GOL_ProgressBarRangeGet Macro C #define GFX_GOL_ProgressBarRangeGet(pObject) (pObject->range) Description This function returns the range of the progress bar. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The current range used by the object. Example None. 5.2.2.7.26.244 GFX_GOL_RadioButtonTextGet Macro C #define GFX_GOL_RadioButtonTextGet(pObject) (((GFX_GOL_RADIOBUTTON *)pObject)->pText) Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-980 Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example // assume RADIO_BUTTON_OBJECT is a radio button that exists GFX_XCHAR *pChar; GFX_GOL_RADIOBUTTON *pRadioButton = &RADIO_BUTTON_OBJECT; pChar = GFX_GOL_ButtonRadioTextGet(pRadioButton); 5.2.2.7.26.245 GFX_GOL_ROUNDDIAL_DISABLED Macro C #define GFX_GOL_ROUNDDIAL_DISABLED 0x0002 // Bit for disabled state. Description Bit for disabled state. 5.2.2.7.26.246 GFX_GOL_ROUNDDIAL_DRAW Macro C #define GFX_GOL_ROUNDDIAL_DRAW 0x4000 // Bit to indicate object must be redrawn. Description Bit to indicate object must be redrawn. 5.2.2.7.26.247 GFX_GOL_ROUNDDIAL_HIDE Macro C #define GFX_GOL_ROUNDDIAL_HIDE 0x8000 // Bit to indicate object must be removed from screen. Description Bit to indicate object must be removed from screen. 5.2.2.7.26.248 GFX_GOL_ROUNDDIAL_MAX_POSITIONS Macro C #define GFX_GOL_ROUNDDIAL_MAX_POSITIONS 24 Description This is macro GFX_GOL_ROUNDDIAL_MAX_POSITIONS. 5.2.2.7.26.249 GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS Macro C #define GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS 6 Description This is macro GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-981 5.2.2.7.26.250 GFX_GOL_ROUNDDIAL_ROT_CCW Macro C #define GFX_GOL_ROUNDDIAL_ROT_CCW 0x0008 // Bit for rotate counter clockwise state. Description Bit for rotate counter clockwise state. 5.2.2.7.26.251 GFX_GOL_ROUNDDIAL_ROT_CW Macro C #define GFX_GOL_ROUNDDIAL_ROT_CW 0x0004 // Bit for rotate clockwise state. Description Bit for rotate clockwise state. 5.2.2.7.26.252 GFX_GOL_RoundDialValueDecrement Macro C #define GFX_GOL_RoundDialValueDecrement(pDia) GFX_GOL_RoundDial_ValSet(pDia, (pDia->pos - pDia->res)) Description Macros: GFX_GOL_RoundDialValueDecrement(pDia) Preconditions none Parameters Parameters Description pDia Pointer to the object. Returns none Remarks none Example Refer to GFX_GOL_RoundDialValueIncrement() example. 5.2.2.7.26.253 GFX_GOL_RoundDialValueGet Macro C #define GFX_GOL_RoundDialValueGet(pDia) (pDia)->value Description Macros: GFX_GOL_RoundDialValueGet(pDia) Preconditions none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-982 Parameters Parameters Description pDia Pointer to the object. Returns Returns the current value of the dial. Remarks none Example uint16_t currVal; GFX_GOL_ROUNDDIAL *pDia; // assuming pDia is initialized to an existing dial Object currVal = GFX_GOL_RoundDial_ValGet(pDia); 5.2.2.7.26.254 GFX_GOL_RoundDialValueIncrement Macro C #define GFX_GOL_RoundDialValueIncrement(pDia) GFX_GOL_RoundDial_ValSet(pDia, (pDia->val + pDia->res)) Description Macros: GFX_GOL_RoundDialValueIncrement(pDia) Preconditions none Parameters Parameters Description pDia Pointer to the object. Returns none none Example uint16_t updatedVal, prevVal; GFX_GOL_ROUNDDIAL *pDia; // assuming pDia is initialized to an existing dial Object // assume GetInput() is a function that retrieves source data prevVal = GFX_GOL_RoundDial_ValGet(pDia); updatedVal = GetInput(); if (updatedVal > prevVal) GFX_GOL_RoundDial_ValInc(pDia); if (updatedVal < prevVal) GFX_GOL_RoundDial_ValDec(pDia); 5.2.2.7.26.255 GFX_GOL_RoundDialValueSet Macro C #define GFX_GOL_RoundDialValueSet(pDia, newVal) (pDia)->value = newVal 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-983 Description Macros: GFX_GOL_RoundDialValueSet(pDia, newVal) Preconditions none Parameters Parameters Description pDia Pointer to the object. newVal New dial value. Returns none Remarks none Example uint16_t updatedVal; GFX_GOL_ROUNDDIAL *pDia; // assuming pDia is initialized to an existing dial Object // assume GetInput() is a function that retrieves source data updatedVal = GetInput(); GFX_GOL_RoundDialValueSet(pDia, updatedVal); 5.2.2.7.26.256 GFX_GOL_WindowImageGet Macro C #define GFX_GOL_WindowImageGet(pObject, pImage) \ (((GFX_GOL_WINDOW *)pObject)->pImage) Description This function gets the image used. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to the image resource. Example None. 5.2.2.7.26.257 GFX_GOL_WindowTextGet Macro C #define GFX_GOL_WindowTextGet(pObject) (((GFX_GOL_WINDOW *)pObject)->pText) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-984 Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. Example GFX_XCHAR *pChar; GFX_GOL_WINDOW pWindow; pChar = GFX_GOL_WindowTextGet(pWindow); 5.2.2.7.26.258 GFX_ImageStretchSet Macro C #define GFX_ImageStretchSet(value) primitiveTaskImage.stretch = value Description This is macro GFX_ImageStretchSet. 5.2.2.7.26.259 GFX_MAX_INVALIDATE_AREAS Macro C #define GFX_MAX_INVALIDATE_AREAS 5 Description This is macro GFX_MAX_INVALIDATE_AREAS. 5.2.2.7.26.260 GFX_MaxXGet Macro C #define GFX_MaxXGet (GFX_DRV_instance[0].horizontalResolution-1) Example Remarks: 5.2.2.7.26.261 GFX_MaxYGet Macro C #define GFX_MaxYGet (GFX_DRV_instance[0].verticalResolution-1) Example Remarks: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-985 5.2.2.7.26.262 GFX_MEM_MASK Macro C #define GFX_MEM_MASK 0x000F Description This is macro GFX_MEM_MASK. 5.2.2.7.26.263 GFX_PixelPut Macro C #define GFX_PixelPut(x, y) GFX_PixelsPut(x, y, 1, 1) Description This is macro GFX_PixelPut. 5.2.2.7.26.264 GFX_PixelsPut Macro C #define GFX_PixelsPut(x, y, count, lineCount) GFX_RectangleFillDraw(x, y, x+count, y+lineCount) Description None Preconditions None Parameters Parameters Description instance primitive instance x x position of the left top corner. y y position of the left top corner. count number of pixels Returns Queue handle once the primitive has been place in queue Example None 5.2.2.7.26.265 GFX_PrevAlphaColorGet Macro C #define GFX_PrevAlphaColorGet GFX_Primitive_instance.alphaArea.prevAlphaColor Example Remarks: 5.2.2.7.26.266 GFX_PrevAlphaColorSet Macro C #define GFX_PrevAlphaColorSet(color) GFX_Primitive_instance.alphaArea.prevAlphaColor = color 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-986 Example Remarks: 5.2.2.7.26.267 GFX_RGBConvert Macro C #define GFX_RGBConvert(red, green, blue) (GFX_COLOR) (((GFX_COLOR)(red) << 16) | ((GFX_COLOR)(green) << 8) | (GFX_COLOR)(blue)) Description Macros: GFX_RGBConvert(red, green, blue) This macro converts the color data to the selected COLOR_DEPTH. This macro is only valid when COLOR_DEPTH is 8, 16, or 24. COLOR_DEPTH Conversion 8 8-8-8 to 3-3-2 conversion 16 8-8-8 to to 5-6-5 conversion 24 8-8-8 to 8-8-8 conversion or no conversion Preconditions none Parameters Parameters Description red red component of the color. green green component of the color. blue blue component of the color. Returns none Side Effects none 5.2.2.7.26.268 GFX_SetFontOrientation Macro C #define GFX_SetFontOrientation(orient) GFX_Primitive_instance.currentFont.orientation = orient; Preconditions None. Parameters Parameters Description orient sets font orientation when rendering characters and strings. Returns None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-987 Example 5.2.2.7.26.269 GFX_TYPE_MASK Macro C #define GFX_TYPE_MASK 0x0F00 Description This is macro GFX_TYPE_MASK. 5.2.2.7.26.270 GFX_TYPES_FONTS_H Macro C #define GFX_TYPES_FONTS_H Description This is macro GFX_TYPES_FONTS_H. 5.2.2.7.26.271 GFX_TYPES_IMAGE_H Macro C #define GFX_TYPES_IMAGE_H Description This is macro GFX_TYPES_IMAGE_H. 5.2.2.7.26.272 GFX_TYPES_PALETTE_H Macro C #define GFX_TYPES_PALETTE_H Description This is macro GFX_TYPES_PALETTE_H. 5.2.2.7.26.273 GFX_TYPES_RESOURCE_H Macro C #define GFX_TYPES_RESOURCE_H Description This is macro GFX_TYPES_RESOURCE_H. 5.2.2.7.26.274 GFX_UXCHAR Macro C #define GFX_UXCHAR uint8_t Description This is macro GFX_UXCHAR. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-988 5.2.2.7.26.275 GFX_VisualPageGet Macro C #define GFX_VisualPageGet GFX_Primitive_instance.visualPage Preconditions None. Returns None. Example Remarks: 5.2.2.7.26.276 GFX_W3_ALICEBLUE Macro C #define GFX_W3_ALICEBLUE GFX_RGBConvert(240, 248, 255) Description This is macro GFX_W3_ALICEBLUE. 5.2.2.7.26.277 GFX_W3_ANTIQUEWHITE Macro C #define GFX_W3_ANTIQUEWHITE GFX_RGBConvert(250, 235, 215) Description This is macro GFX_W3_ANTIQUEWHITE. 5.2.2.7.26.278 GFX_W3_AQUA Macro C #define GFX_W3_AQUA GFX_RGBConvert( 0, 255, 255) Description This is macro GFX_W3_AQUA. 5.2.2.7.26.279 GFX_W3_AQUAMARINE Macro C #define GFX_W3_AQUAMARINE GFX_RGBConvert(127, 255, 212) Description This is macro GFX_W3_AQUAMARINE. 5.2.2.7.26.280 GFX_W3_AZURE Macro C #define GFX_W3_AZURE GFX_RGBConvert(240, 255, 255) Description This is macro GFX_W3_AZURE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-989 5.2.2.7.26.281 GFX_W3_BEIGE Macro C #define GFX_W3_BEIGE GFX_RGBConvert(245, 245, 220) Description This is macro GFX_W3_BEIGE. 5.2.2.7.26.282 GFX_W3_BISQUE Macro C #define GFX_W3_BISQUE GFX_RGBConvert(255, 228, 196) Description This is macro GFX_W3_BISQUE. 5.2.2.7.26.283 GFX_W3_BLACK Macro C #define GFX_W3_BLACK GFX_RGBConvert( 0, 0, 0) Description This is macro GFX_W3_BLACK. 5.2.2.7.26.284 GFX_W3_BLANCHEDALMOND Macro C #define GFX_W3_BLANCHEDALMOND GFX_RGBConvert(255, 235, 205) Description This is macro GFX_W3_BLANCHEDALMOND. 5.2.2.7.26.285 GFX_W3_BLUE Macro C #define GFX_W3_BLUE GFX_RGBConvert( 0, 0, 255) Description This is macro GFX_W3_BLUE. 5.2.2.7.26.286 GFX_W3_BLUEVIOLET Macro C #define GFX_W3_BLUEVIOLET GFX_RGBConvert(138, 43, 226) Description This is macro GFX_W3_BLUEVIOLET. 5.2.2.7.26.287 GFX_W3_BROWN Macro C #define GFX_W3_BROWN GFX_RGBConvert(165, 42, 42) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-990 Description This is macro GFX_W3_BROWN. 5.2.2.7.26.288 GFX_W3_BURLYWOOD Macro C #define GFX_W3_BURLYWOOD GFX_RGBConvert(222, 184, 135) Description This is macro GFX_W3_BURLYWOOD. 5.2.2.7.26.289 GFX_W3_CADETBLUE Macro C #define GFX_W3_CADETBLUE GFX_RGBConvert( 95, 158, 160) Description This is macro GFX_W3_CADETBLUE. 5.2.2.7.26.290 GFX_W3_CHARTREUSE Macro C #define GFX_W3_CHARTREUSE GFX_RGBConvert(127, 255, 0) Description This is macro GFX_W3_CHARTREUSE. 5.2.2.7.26.291 GFX_W3_CHOCOLATE Macro C #define GFX_W3_CHOCOLATE GFX_RGBConvert(210, 105, 30) Description This is macro GFX_W3_CHOCOLATE. 5.2.2.7.26.292 GFX_W3_CORAL Macro C #define GFX_W3_CORAL GFX_RGBConvert(255, 127, 80) Description This is macro GFX_W3_CORAL. 5.2.2.7.26.293 GFX_W3_CORNFLOWERBLUE Macro C #define GFX_W3_CORNFLOWERBLUE GFX_RGBConvert(100, 149, 237) Description This is macro GFX_W3_CORNFLOWERBLUE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-991 5.2.2.7.26.294 GFX_W3_CORNSILK Macro C #define GFX_W3_CORNSILK GFX_RGBConvert(255, 248, 220) Description This is macro GFX_W3_CORNSILK. 5.2.2.7.26.295 GFX_W3_CRIMSON Macro C #define GFX_W3_CRIMSON GFX_RGBConvert(220, 20, 60) Description This is macro GFX_W3_CRIMSON. 5.2.2.7.26.296 GFX_W3_CYAN Macro C #define GFX_W3_CYAN GFX_RGBConvert( 0, 255, 255) Description This is macro GFX_W3_CYAN. 5.2.2.7.26.297 GFX_W3_DARKBLUE Macro C #define GFX_W3_DARKBLUE GFX_RGBConvert( 0, 0, 139) Description This is macro GFX_W3_DARKBLUE. 5.2.2.7.26.298 GFX_W3_DARKCYAN Macro C #define GFX_W3_DARKCYAN GFX_RGBConvert( 0, 139, 139) Description This is macro GFX_W3_DARKCYAN. 5.2.2.7.26.299 GFX_W3_darkgoldenrod Macro C #define GFX_W3_darkgoldenrod GFX_RGBConvert(184, 134, 11) Description This is macro GFX_W3_darkgoldenrod. 5.2.2.7.26.300 GFX_W3_DARKGRAY Macro C #define GFX_W3_DARKGRAY GFX_RGBConvert(169, 169, 169) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-992 Description This is macro GFX_W3_DARKGRAY. 5.2.2.7.26.301 GFX_W3_DARKGREEN Macro C #define GFX_W3_DARKGREEN GFX_RGBConvert( 0, 100, 0) Description This is macro GFX_W3_DARKGREEN. 5.2.2.7.26.302 GFX_W3_DARKGREY Macro C #define GFX_W3_DARKGREY GFX_RGBConvert(169, 169, 169) Description This is macro GFX_W3_DARKGREY. 5.2.2.7.26.303 GFX_W3_DARKHAKI Macro C #define GFX_W3_DARKHAKI GFX_RGBConvert(189, 183, 107) Description This is macro GFX_W3_DARKHAKI. 5.2.2.7.26.304 GFX_W3_DARKMAGENTA Macro C #define GFX_W3_DARKMAGENTA GFX_RGBConvert(139, 0, 139) Description This is macro GFX_W3_DARKMAGENTA. 5.2.2.7.26.305 GFX_W3_DARKOLIVEGREEN Macro C #define GFX_W3_DARKOLIVEGREEN GFX_RGBConvert( 85, 107, 47) Description This is macro GFX_W3_DARKOLIVEGREEN. 5.2.2.7.26.306 GFX_W3_DARKORANGE Macro C #define GFX_W3_DARKORANGE GFX_RGBConvert(255, 140, 0) Description This is macro GFX_W3_DARKORANGE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-993 5.2.2.7.26.307 GFX_W3_DARKORCHID Macro C #define GFX_W3_DARKORCHID GFX_RGBConvert(153, 50, 204) Description This is macro GFX_W3_DARKORCHID. 5.2.2.7.26.308 GFX_W3_DARKRED Macro C #define GFX_W3_DARKRED GFX_RGBConvert(139, 0, 0) Description This is macro GFX_W3_DARKRED. 5.2.2.7.26.309 GFX_W3_DARKSALMON Macro C #define GFX_W3_DARKSALMON GFX_RGBConvert(233, 150, 122) Description This is macro GFX_W3_DARKSALMON. 5.2.2.7.26.310 GFX_W3_DARKSEAGREEN Macro C #define GFX_W3_DARKSEAGREEN GFX_RGBConvert(143, 188, 143) Description This is macro GFX_W3_DARKSEAGREEN. 5.2.2.7.26.311 GFX_W3_DARKSLATEBLUE Macro C #define GFX_W3_DARKSLATEBLUE GFX_RGBConvert( 72, 61, 139) Description This is macro GFX_W3_DARKSLATEBLUE. 5.2.2.7.26.312 GFX_W3_DARKSLATEGRAY Macro C #define GFX_W3_DARKSLATEGRAY GFX_RGBConvert( 47, 79, 79) Description This is macro GFX_W3_DARKSLATEGRAY. 5.2.2.7.26.313 GFX_W3_DARKSLATEGREY Macro C #define GFX_W3_DARKSLATEGREY GFX_RGBConvert( 47, 79, 79) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-994 Description This is macro GFX_W3_DARKSLATEGREY. 5.2.2.7.26.314 GFX_W3_DARKTURQUOISE Macro C #define GFX_W3_DARKTURQUOISE GFX_RGBConvert( 0, 206, 209) Description This is macro GFX_W3_DARKTURQUOISE. 5.2.2.7.26.315 GFX_W3_DARKVIOLET Macro C #define GFX_W3_DARKVIOLET GFX_RGBConvert(148, 0, 211) Description This is macro GFX_W3_DARKVIOLET. 5.2.2.7.26.316 GFX_W3_DEEPPINK Macro C #define GFX_W3_DEEPPINK GFX_RGBConvert(255, 20, 147) Description This is macro GFX_W3_DEEPPINK. 5.2.2.7.26.317 GFX_W3_DEEPSKYBLUE Macro C #define GFX_W3_DEEPSKYBLUE GFX_RGBConvert( 0, 191, 255) Description This is macro GFX_W3_DEEPSKYBLUE. 5.2.2.7.26.318 GFX_W3_DIMGRAY Macro C #define GFX_W3_DIMGRAY GFX_RGBConvert(105, 105, 105) Description This is macro GFX_W3_DIMGRAY. 5.2.2.7.26.319 GFX_W3_DIMGREY Macro C #define GFX_W3_DIMGREY GFX_RGBConvert(105, 105, 105) Description This is macro GFX_W3_DIMGREY. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-995 5.2.2.7.26.320 GFX_W3_DODGERBLUE Macro C #define GFX_W3_DODGERBLUE GFX_RGBConvert( 30, 144, 255) Description This is macro GFX_W3_DODGERBLUE. 5.2.2.7.26.321 GFX_W3_FIREBRICK Macro C #define GFX_W3_FIREBRICK GFX_RGBConvert(178, 34, 34) Description This is macro GFX_W3_FIREBRICK. 5.2.2.7.26.322 GFX_W3_FLORALWHITE Macro C #define GFX_W3_FLORALWHITE GFX_RGBConvert(255, 250, 240) Description This is macro GFX_W3_FLORALWHITE. 5.2.2.7.26.323 GFX_W3_FORESTGREEN Macro C #define GFX_W3_FORESTGREEN GFX_RGBConvert( 34, 139, 34) Description This is macro GFX_W3_FORESTGREEN. 5.2.2.7.26.324 GFX_W3_FUCHSIA Macro C #define GFX_W3_FUCHSIA GFX_RGBConvert(255, 0, 255) Description This is macro GFX_W3_FUCHSIA. 5.2.2.7.26.325 GFX_W3_GAINSBORO Macro C #define GFX_W3_GAINSBORO GFX_RGBConvert(220, 220, 220) Description This is macro GFX_W3_GAINSBORO. 5.2.2.7.26.326 GFX_W3_GHOSTWHITE Macro C #define GFX_W3_GHOSTWHITE GFX_RGBConvert(248, 248, 255) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-996 Description This is macro GFX_W3_GHOSTWHITE. 5.2.2.7.26.327 GFX_W3_GOLD Macro C #define GFX_W3_GOLD GFX_RGBConvert(255, 215, 0) Description This is macro GFX_W3_GOLD. 5.2.2.7.26.328 GFX_W3_GOLDENROD Macro C #define GFX_W3_GOLDENROD GFX_RGBConvert(218, 165, 32) Description This is macro GFX_W3_GOLDENROD. 5.2.2.7.26.329 GFX_W3_GRAY Macro C #define GFX_W3_GRAY GFX_RGBConvert(128, 128, 128) Description This is macro GFX_W3_GRAY. 5.2.2.7.26.330 GFX_W3_GREEN Macro C #define GFX_W3_GREEN GFX_RGBConvert( 0, 128, 0) Description This is macro GFX_W3_GREEN. 5.2.2.7.26.331 GFX_W3_GREENYELLOW Macro C #define GFX_W3_GREENYELLOW GFX_RGBConvert(173, 255, 47) Description This is macro GFX_W3_GREENYELLOW. 5.2.2.7.26.332 GFX_W3_GREY Macro C #define GFX_W3_GREY GFX_RGBConvert(128, 128, 128) Description This is macro GFX_W3_GREY. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-997 5.2.2.7.26.333 GFX_W3_HONEYDEW Macro C #define GFX_W3_HONEYDEW GFX_RGBConvert(240, 255, 240) Description This is macro GFX_W3_HONEYDEW. 5.2.2.7.26.334 GFX_W3_HOTPINK Macro C #define GFX_W3_HOTPINK GFX_RGBConvert(255, 105, 180) Description This is macro GFX_W3_HOTPINK. 5.2.2.7.26.335 GFX_W3_INDIANRED Macro C #define GFX_W3_INDIANRED GFX_RGBConvert(205, 92, 92) Description This is macro GFX_W3_INDIANRED. 5.2.2.7.26.336 GFX_W3_INDIGO Macro C #define GFX_W3_INDIGO GFX_RGBConvert( 75, 0, 130) Description This is macro GFX_W3_INDIGO. 5.2.2.7.26.337 GFX_W3_IVORY Macro C #define GFX_W3_IVORY GFX_RGBConvert(255, 255, 240) Description This is macro GFX_W3_IVORY. 5.2.2.7.26.338 GFX_W3_LAVENDER Macro C #define GFX_W3_LAVENDER GFX_RGBConvert(230, 230, 250) Description This is macro GFX_W3_LAVENDER. 5.2.2.7.26.339 GFX_W3_LAVENDERBLUSH Macro C #define GFX_W3_LAVENDERBLUSH GFX_RGBConvert(255, 240, 245) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-998 Description This is macro GFX_W3_LAVENDERBLUSH. 5.2.2.7.26.340 GFX_W3_LAWNGREEN Macro C #define GFX_W3_LAWNGREEN GFX_RGBConvert(124, 252, 0) Description This is macro GFX_W3_LAWNGREEN. 5.2.2.7.26.341 GFX_W3_LEMONCHIFFON Macro C #define GFX_W3_LEMONCHIFFON GFX_RGBConvert(255, 250, 205) Description This is macro GFX_W3_LEMONCHIFFON. 5.2.2.7.26.342 GFX_W3_LIGHTBLUE Macro C #define GFX_W3_LIGHTBLUE GFX_RGBConvert(173, 216, 230) Description This is macro GFX_W3_LIGHTBLUE. 5.2.2.7.26.343 GFX_W3_LIGHTCORAL Macro C #define GFX_W3_LIGHTCORAL GFX_RGBConvert(240, 128, 128) Description This is macro GFX_W3_LIGHTCORAL. 5.2.2.7.26.344 GFX_W3_LIGHTCYAN Macro C #define GFX_W3_LIGHTCYAN GFX_RGBConvert(224, 255, 255) Description This is macro GFX_W3_LIGHTCYAN. 5.2.2.7.26.345 GFX_W3_LIGHTGOLDENRODYELLOW Macro C #define GFX_W3_LIGHTGOLDENRODYELLOW GFX_RGBConvert(250, 250, 210) Description This is macro GFX_W3_LIGHTGOLDENRODYELLOW. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-999 5.2.2.7.26.346 GFX_W3_LIGHTGRAY Macro C #define GFX_W3_LIGHTGRAY GFX_RGBConvert(211, 211, 211) Description This is macro GFX_W3_LIGHTGRAY. 5.2.2.7.26.347 GFX_W3_LIGHTGREEN Macro C #define GFX_W3_LIGHTGREEN GFX_RGBConvert(144, 238, 144) Description This is macro GFX_W3_LIGHTGREEN. 5.2.2.7.26.348 GFX_W3_LIGHTGREY Macro C #define GFX_W3_LIGHTGREY GFX_RGBConvert(211, 211, 211) Description This is macro GFX_W3_LIGHTGREY. 5.2.2.7.26.349 GFX_W3_LIGHTPINK Macro C #define GFX_W3_LIGHTPINK GFX_RGBConvert(255, 182, 193) Description This is macro GFX_W3_LIGHTPINK. 5.2.2.7.26.350 GFX_W3_LIGHTSALMON Macro C #define GFX_W3_LIGHTSALMON GFX_RGBConvert(255, 160, 122) Description This is macro GFX_W3_LIGHTSALMON. 5.2.2.7.26.351 GFX_W3_LIGHTSKYBLUE Macro C #define GFX_W3_LIGHTSKYBLUE GFX_RGBConvert(135, 206, 250) Description This is macro GFX_W3_LIGHTSKYBLUE. 5.2.2.7.26.352 GFX_W3_LIGHTSLATEGRAY Macro C #define GFX_W3_LIGHTSLATEGRAY GFX_RGBConvert(119, 136, 153) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1000 Description This is macro GFX_W3_LIGHTSLATEGRAY. 5.2.2.7.26.353 GFX_W3_LIGHTSLATEGREY Macro C #define GFX_W3_LIGHTSLATEGREY GFX_RGBConvert(119, 136, 153) Description This is macro GFX_W3_LIGHTSLATEGREY. 5.2.2.7.26.354 GFX_W3_LIGHTSTEELBLUE Macro C #define GFX_W3_LIGHTSTEELBLUE GFX_RGBConvert(176, 196, 222) Description This is macro GFX_W3_LIGHTSTEELBLUE. 5.2.2.7.26.355 GFX_W3_LIGHTYELLOW Macro C #define GFX_W3_LIGHTYELLOW GFX_RGBConvert(255, 255, 224) Description This is macro GFX_W3_LIGHTYELLOW. 5.2.2.7.26.356 GFX_W3_LIGTHSEAGREEN Macro C #define GFX_W3_LIGTHSEAGREEN GFX_RGBConvert( 32, 178, 170) Description This is macro GFX_W3_LIGTHSEAGREEN. 5.2.2.7.26.357 GFX_W3_LIME Macro C #define GFX_W3_LIME GFX_RGBConvert( 0, 255, 0) Description This is macro GFX_W3_LIME. 5.2.2.7.26.358 GFX_W3_LIMEGREEN Macro C #define GFX_W3_LIMEGREEN GFX_RGBConvert( 50, 205, 50) Description This is macro GFX_W3_LIMEGREEN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1001 5.2.2.7.26.359 GFX_W3_LINEN Macro C #define GFX_W3_LINEN GFX_RGBConvert(250, 240, 230) Description This is macro GFX_W3_LINEN. 5.2.2.7.26.360 GFX_W3_MAGENTA Macro C #define GFX_W3_MAGENTA GFX_RGBConvert(255, 0, 255) Description This is macro GFX_W3_MAGENTA. 5.2.2.7.26.361 GFX_W3_MAROON Macro C #define GFX_W3_MAROON GFX_RGBConvert(128, 0, 0) Description This is macro GFX_W3_MAROON. 5.2.2.7.26.362 GFX_W3_MEDIUMAQUAMARINE Macro C #define GFX_W3_MEDIUMAQUAMARINE GFX_RGBConvert(102, 205, 170) Description This is macro GFX_W3_MEDIUMAQUAMARINE. 5.2.2.7.26.363 GFX_W3_MEDIUMBLUE Macro C #define GFX_W3_MEDIUMBLUE GFX_RGBConvert( 0, 0, 205) Description This is macro GFX_W3_MEDIUMBLUE. 5.2.2.7.26.364 GFX_W3_MEDIUMORCHID Macro C #define GFX_W3_MEDIUMORCHID GFX_RGBConvert(186, 85, 211) Description This is macro GFX_W3_MEDIUMORCHID. 5.2.2.7.26.365 GFX_W3_MEDIUMPURPLE Macro C #define GFX_W3_MEDIUMPURPLE GFX_RGBConvert(147, 112, 219) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1002 Description This is macro GFX_W3_MEDIUMPURPLE. 5.2.2.7.26.366 GFX_W3_MEDIUMSEAGREEN Macro C #define GFX_W3_MEDIUMSEAGREEN GFX_RGBConvert( 60, 179, 113) Description This is macro GFX_W3_MEDIUMSEAGREEN. 5.2.2.7.26.367 GFX_W3_MEDIUMSLATEBLUE Macro C #define GFX_W3_MEDIUMSLATEBLUE GFX_RGBConvert(123, 104, 238) Description This is macro GFX_W3_MEDIUMSLATEBLUE. 5.2.2.7.26.368 GFX_W3_MEDIUMSPRINGGREEN Macro C #define GFX_W3_MEDIUMSPRINGGREEN GFX_RGBConvert( 0, 250, 154) Description This is macro GFX_W3_MEDIUMSPRINGGREEN. 5.2.2.7.26.369 GFX_W3_MEDIUMTURQUOISE Macro C #define GFX_W3_MEDIUMTURQUOISE GFX_RGBConvert( 72, 209, 204) Description This is macro GFX_W3_MEDIUMTURQUOISE. 5.2.2.7.26.370 GFX_W3_MEDIUMVIOLETRED Macro C #define GFX_W3_MEDIUMVIOLETRED GFX_RGBConvert(199, 21, 133) Description This is macro GFX_W3_MEDIUMVIOLETRED. 5.2.2.7.26.371 GFX_W3_MIDNIGHTBLUE Macro C #define GFX_W3_MIDNIGHTBLUE GFX_RGBConvert( 25, 25, 112) Description This is macro GFX_W3_MIDNIGHTBLUE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1003 5.2.2.7.26.372 GFX_W3_MINTCREAM Macro C #define GFX_W3_MINTCREAM GFX_RGBConvert(245, 255, 250) Description This is macro GFX_W3_MINTCREAM. 5.2.2.7.26.373 GFX_W3_MISTYROSE Macro C #define GFX_W3_MISTYROSE GFX_RGBConvert(255, 228, 225) Description This is macro GFX_W3_MISTYROSE. 5.2.2.7.26.374 GFX_W3_MOCCASIN Macro C #define GFX_W3_MOCCASIN GFX_RGBConvert(255, 228, 181) Description This is macro GFX_W3_MOCCASIN. 5.2.2.7.26.375 GFX_W3_NAVAJOWHITE Macro C #define GFX_W3_NAVAJOWHITE GFX_RGBConvert(255, 222, 173) Description This is macro GFX_W3_NAVAJOWHITE. 5.2.2.7.26.376 GFX_W3_NAVY Macro C #define GFX_W3_NAVY GFX_RGBConvert( 0, 0, 128) Description This is macro GFX_W3_NAVY. 5.2.2.7.26.377 GFX_W3_OLDLACE Macro C #define GFX_W3_OLDLACE GFX_RGBConvert(253, 245, 230) Description This is macro GFX_W3_OLDLACE. 5.2.2.7.26.378 GFX_W3_OLIVE Macro C #define GFX_W3_OLIVE GFX_RGBConvert(128, 128, 0) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1004 Description This is macro GFX_W3_OLIVE. 5.2.2.7.26.379 GFX_W3_OLIVEDRAB Macro C #define GFX_W3_OLIVEDRAB GFX_RGBConvert(107, 142, 35) Description This is macro GFX_W3_OLIVEDRAB. 5.2.2.7.26.380 GFX_W3_ORANGE Macro C #define GFX_W3_ORANGE GFX_RGBConvert(255, 165, 0) Description This is macro GFX_W3_ORANGE. 5.2.2.7.26.381 GFX_W3_ORANGERED Macro C #define GFX_W3_ORANGERED GFX_RGBConvert(255, 69, 0) Description This is macro GFX_W3_ORANGERED. 5.2.2.7.26.382 GFX_W3_ORCHID Macro C #define GFX_W3_ORCHID GFX_RGBConvert(218, 112, 214) Description This is macro GFX_W3_ORCHID. 5.2.2.7.26.383 GFX_W3_PALEGOLDENROD Macro C #define GFX_W3_PALEGOLDENROD GFX_RGBConvert(238, 232, 170) Description This is macro GFX_W3_PALEGOLDENROD. 5.2.2.7.26.384 GFX_W3_PALEGREEN Macro C #define GFX_W3_PALEGREEN GFX_RGBConvert(152, 251, 152) Description This is macro GFX_W3_PALEGREEN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1005 5.2.2.7.26.385 GFX_W3_PALETURQUOISE Macro C #define GFX_W3_PALETURQUOISE GFX_RGBConvert(175, 238, 238) Description This is macro GFX_W3_PALETURQUOISE. 5.2.2.7.26.386 GFX_W3_PALEVIOLETRED Macro C #define GFX_W3_PALEVIOLETRED GFX_RGBConvert(219, 112, 147) Description This is macro GFX_W3_PALEVIOLETRED. 5.2.2.7.26.387 GFX_W3_PAPAYAWHIP Macro C #define GFX_W3_PAPAYAWHIP GFX_RGBConvert(255, 239, 213) Description This is macro GFX_W3_PAPAYAWHIP. 5.2.2.7.26.388 GFX_W3_PEACHPUFF Macro C #define GFX_W3_PEACHPUFF GFX_RGBConvert(255, 218, 185) Description This is macro GFX_W3_PEACHPUFF. 5.2.2.7.26.389 GFX_W3_PERU Macro C #define GFX_W3_PERU GFX_RGBConvert(205, 133, 63) Description This is macro GFX_W3_PERU. 5.2.2.7.26.390 GFX_W3_PINK Macro C #define GFX_W3_PINK GFX_RGBConvert(255, 192, 203) Description This is macro GFX_W3_PINK. 5.2.2.7.26.391 GFX_W3_PLUM Macro C #define GFX_W3_PLUM GFX_RGBConvert(221, 160, 221) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1006 Description This is macro GFX_W3_PLUM. 5.2.2.7.26.392 GFX_W3_POWDERBLUE Macro C #define GFX_W3_POWDERBLUE GFX_RGBConvert(176, 224, 230) Description This is macro GFX_W3_POWDERBLUE. 5.2.2.7.26.393 GFX_W3_PURPLE Macro C #define GFX_W3_PURPLE GFX_RGBConvert(128, 0, 128) Description This is macro GFX_W3_PURPLE. 5.2.2.7.26.394 GFX_W3_RED Macro C #define GFX_W3_RED GFX_RGBConvert(255, 0, 0) Description This is macro GFX_W3_RED. 5.2.2.7.26.395 GFX_W3_ROSYBROWN Macro C #define GFX_W3_ROSYBROWN GFX_RGBConvert(188, 143, 143) Description This is macro GFX_W3_ROSYBROWN. 5.2.2.7.26.396 GFX_W3_ROYALBLUE Macro C #define GFX_W3_ROYALBLUE GFX_RGBConvert( 65, 105, 225) Description This is macro GFX_W3_ROYALBLUE. 5.2.2.7.26.397 GFX_W3_SADDLEBROWN Macro C #define GFX_W3_SADDLEBROWN GFX_RGBConvert(139, 69, 19) Description This is macro GFX_W3_SADDLEBROWN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1007 5.2.2.7.26.398 GFX_W3_SALMON Macro C #define GFX_W3_SALMON GFX_RGBConvert(250, 128, 114) Description This is macro GFX_W3_SALMON. 5.2.2.7.26.399 GFX_W3_SANDYGREEN Macro C #define GFX_W3_SANDYGREEN GFX_RGBConvert(244, 164, 96) Description This is macro GFX_W3_SANDYGREEN. 5.2.2.7.26.400 GFX_W3_SEAGREEN Macro C #define GFX_W3_SEAGREEN GFX_RGBConvert( 46, 139, 87) Description This is macro GFX_W3_SEAGREEN. 5.2.2.7.26.401 GFX_W3_SEASHELL Macro C #define GFX_W3_SEASHELL GFX_RGBConvert(255, 245, 238) Description This is macro GFX_W3_SEASHELL. 5.2.2.7.26.402 GFX_W3_SIENNA Macro C #define GFX_W3_SIENNA GFX_RGBConvert(160, 82, 45) Description This is macro GFX_W3_SIENNA. 5.2.2.7.26.403 GFX_W3_SILVER Macro C #define GFX_W3_SILVER GFX_RGBConvert(192, 192, 192) Description This is macro GFX_W3_SILVER. 5.2.2.7.26.404 GFX_W3_SKYBLUE Macro C #define GFX_W3_SKYBLUE GFX_RGBConvert(135, 206, 235) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1008 Description This is macro GFX_W3_SKYBLUE. 5.2.2.7.26.405 GFX_W3_SLATEBLUE Macro C #define GFX_W3_SLATEBLUE GFX_RGBConvert(106, 90, 205) Description This is macro GFX_W3_SLATEBLUE. 5.2.2.7.26.406 GFX_W3_SLATEGRAY Macro C #define GFX_W3_SLATEGRAY GFX_RGBConvert(112, 128, 144) Description This is macro GFX_W3_SLATEGRAY. 5.2.2.7.26.407 GFX_W3_SLATEGREY Macro C #define GFX_W3_SLATEGREY GFX_RGBConvert(112, 128, 144) Description This is macro GFX_W3_SLATEGREY. 5.2.2.7.26.408 GFX_W3_SNOW Macro C #define GFX_W3_SNOW GFX_RGBConvert(255, 250, 250) Description This is macro GFX_W3_SNOW. 5.2.2.7.26.409 GFX_W3_SPRINGGREEN Macro C #define GFX_W3_SPRINGGREEN GFX_RGBConvert( 0, 255, 127) Description This is macro GFX_W3_SPRINGGREEN. 5.2.2.7.26.410 GFX_W3_STEELBLUE Macro C #define GFX_W3_STEELBLUE GFX_RGBConvert( 70, 130, 180) Description This is macro GFX_W3_STEELBLUE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1009 5.2.2.7.26.411 GFX_W3_TAN Macro C #define GFX_W3_TAN GFX_RGBConvert(210, 180, 140) Description This is macro GFX_W3_TAN. 5.2.2.7.26.412 GFX_W3_TEAL Macro C #define GFX_W3_TEAL GFX_RGBConvert( 0, 128, 128) Description This is macro GFX_W3_TEAL. 5.2.2.7.26.413 GFX_W3_THISTLE Macro C #define GFX_W3_THISTLE GFX_RGBConvert(216, 191, 216) Description This is macro GFX_W3_THISTLE. 5.2.2.7.26.414 GFX_W3_TOMATO Macro C #define GFX_W3_TOMATO GFX_RGBConvert(255, 99, 71) Description This is macro GFX_W3_TOMATO. 5.2.2.7.26.415 GFX_W3_TURQUOISE Macro C #define GFX_W3_TURQUOISE GFX_RGBConvert( 64, 224, 208) Description This is macro GFX_W3_TURQUOISE. 5.2.2.7.26.416 GFX_W3_VIOLET Macro C #define GFX_W3_VIOLET GFX_RGBConvert(238, 130, 238) Description This is macro GFX_W3_VIOLET. 5.2.2.7.26.417 GFX_W3_WHEAT Macro C #define GFX_W3_WHEAT GFX_RGBConvert(245, 222, 179) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1010 Description This is macro GFX_W3_WHEAT. 5.2.2.7.26.418 GFX_W3_WHITE Macro C #define GFX_W3_WHITE GFX_RGBConvert(255, 255, 255) Description This is macro GFX_W3_WHITE. 5.2.2.7.26.419 GFX_W3_WHITESMOKE Macro C #define GFX_W3_WHITESMOKE GFX_RGBConvert(245, 245, 245) Description This is macro GFX_W3_WHITESMOKE. 5.2.2.7.26.420 GFX_W3_YELLOW Macro C #define GFX_W3_YELLOW GFX_RGBConvert(255, 255, 0) Description This is macro GFX_W3_YELLOW. 5.2.2.7.26.421 GFX_W3_YELLOWGREEN Macro C #define GFX_W3_YELLOWGREEN GFX_RGBConvert(154, 205, 50) Description This is macro GFX_W3_YELLOWGREEN. 5.2.2.7.26.422 GFX_X11_ALICE_BLUE Macro C #define GFX_X11_ALICE_BLUE GFX_RGBConvert(0xF0, 0xF8, 0xFF) Description This is macro GFX_X11_ALICE_BLUE. 5.2.2.7.26.423 GFX_X11_ANTIQUE_WHITE Macro C #define GFX_X11_ANTIQUE_WHITE GFX_RGBConvert(0xFA, 0xEB, 0xD7) Description This is macro GFX_X11_ANTIQUE_WHITE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1011 5.2.2.7.26.424 GFX_X11_AQUA Macro C #define GFX_X11_AQUA GFX_RGBConvert(0x00, 0xFF, 0xFF) Description This is macro GFX_X11_AQUA. 5.2.2.7.26.425 GFX_X11_AQUAMARINE Macro C #define GFX_X11_AQUAMARINE GFX_RGBConvert(0x7F, 0xFF, 0xD4) Description This is macro GFX_X11_AQUAMARINE. 5.2.2.7.26.426 GFX_X11_AZURE Macro C #define GFX_X11_AZURE GFX_RGBConvert(0xF0, 0xFF, 0xFF) Description This is macro GFX_X11_AZURE. 5.2.2.7.26.427 GFX_X11_BEIGE Macro C #define GFX_X11_BEIGE GFX_RGBConvert(0xF5, 0xF5, 0xDC) Description This is macro GFX_X11_BEIGE. 5.2.2.7.26.428 GFX_X11_BISQUE Macro C #define GFX_X11_BISQUE GFX_RGBConvert(0xFF, 0xE4, 0xC4) Description This is macro GFX_X11_BISQUE. 5.2.2.7.26.429 GFX_X11_BLACK Macro C #define GFX_X11_BLACK GFX_RGBConvert(0x00, 0x00, 0x00) Description This is macro GFX_X11_BLACK. 5.2.2.7.26.430 GFX_X11_BLANCHED_ALMOND Macro C #define GFX_X11_BLANCHED_ALMOND GFX_RGBConvert(0xFF, 0xEB, 0xCD) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1012 Description This is macro GFX_X11_BLANCHED_ALMOND. 5.2.2.7.26.431 GFX_X11_BLUE Macro C #define GFX_X11_BLUE GFX_RGBConvert(0x00, 0x00, 0xFF) Description This is macro GFX_X11_BLUE. 5.2.2.7.26.432 GFX_X11_BLUE_VIOLET Macro C #define GFX_X11_BLUE_VIOLET GFX_RGBConvert(0x8A, 0x2B, 0xE2) Description This is macro GFX_X11_BLUE_VIOLET. 5.2.2.7.26.433 GFX_X11_BROWN Macro C #define GFX_X11_BROWN GFX_RGBConvert(0xA5, 0x2A, 0x2A) Description This is macro GFX_X11_BROWN. 5.2.2.7.26.434 GFX_X11_BURLY_WOOD Macro C #define GFX_X11_BURLY_WOOD GFX_RGBConvert(0xDE, 0xB8, 0x87) Description This is macro GFX_X11_BURLY_WOOD. 5.2.2.7.26.435 GFX_X11_CADEL_BLUE Macro C #define GFX_X11_CADEL_BLUE GFX_RGBConvert(0x5F, 0x9E, 0xA0) Description This is macro GFX_X11_CADEL_BLUE. 5.2.2.7.26.436 GFX_X11_CHARTEUSE Macro C #define GFX_X11_CHARTEUSE GFX_RGBConvert(0x7F, 0xFF, 0x00) Description This is macro GFX_X11_CHARTEUSE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1013 5.2.2.7.26.437 GFX_X11_CHOCOLATE Macro C #define GFX_X11_CHOCOLATE GFX_RGBConvert(0xD2, 0x69, 0x1E) Description This is macro GFX_X11_CHOCOLATE. 5.2.2.7.26.438 GFX_X11_CORAL Macro C #define GFX_X11_CORAL GFX_RGBConvert(0xFF, 0x7F, 0x50) Description This is macro GFX_X11_CORAL. 5.2.2.7.26.439 GFX_X11_CORNFLOWER_BLUE Macro C #define GFX_X11_CORNFLOWER_BLUE GFX_RGBConvert(0x64, 0x95, 0xED) Description This is macro GFX_X11_CORNFLOWER_BLUE. 5.2.2.7.26.440 GFX_X11_CORNSILK Macro C #define GFX_X11_CORNSILK GFX_RGBConvert(0xFF, 0xF8, 0xDC) Description X11: Brown Colors 5.2.2.7.26.441 GFX_X11_CRIMSON Macro C #define GFX_X11_CRIMSON GFX_RGBConvert(0xDC, 0x14, 0x3C) Description This is macro GFX_X11_CRIMSON. 5.2.2.7.26.442 GFX_X11_CYAN Macro C #define GFX_X11_CYAN GFX_RGBConvert(0x00, 0xFF, 0xFF) Description This is macro GFX_X11_CYAN. 5.2.2.7.26.443 GFX_X11_DARK_BLUE Macro C #define GFX_X11_DARK_BLUE GFX_RGBConvert(0x00, 0x00, 0x8B) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1014 Description This is macro GFX_X11_DARK_BLUE. 5.2.2.7.26.444 GFX_X11_DARK_CYAN Macro C #define GFX_X11_DARK_CYAN GFX_RGBConvert(0x00, 0x8B, 0x8B) Description This is macro GFX_X11_DARK_CYAN. 5.2.2.7.26.445 GFX_X11_DARK_GOLDENROD Macro C #define GFX_X11_DARK_GOLDENROD GFX_RGBConvert(0xB8, 0x86, 0x0B) Description This is macro GFX_X11_DARK_GOLDENROD. 5.2.2.7.26.446 GFX_X11_DARK_GREEN Macro C #define GFX_X11_DARK_GREEN GFX_RGBConvert(0x00, 0x64, 0x00) Description This is macro GFX_X11_DARK_GREEN. 5.2.2.7.26.447 GFX_X11_DARK_GREY Macro C #define GFX_X11_DARK_GREY GFX_RGBConvert(0xA9, 0xA9, 0xA9) Description This is macro GFX_X11_DARK_GREY. 5.2.2.7.26.448 GFX_X11_DARK_KHAKI Macro C #define GFX_X11_DARK_KHAKI GFX_RGBConvert(0xBD, 0xB7, 0x6B) Description This is macro GFX_X11_DARK_KHAKI. 5.2.2.7.26.449 GFX_X11_DARK_MAGENTA Macro C #define GFX_X11_DARK_MAGENTA GFX_RGBConvert(0x8B, 0x00, 0x8B) Description This is macro GFX_X11_DARK_MAGENTA. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1015 5.2.2.7.26.450 GFX_X11_DARK_OLIVE_GREEN Macro C #define GFX_X11_DARK_OLIVE_GREEN GFX_RGBConvert(0x55, 0x6B, 0x2F) Description X11: Green Colors 5.2.2.7.26.451 GFX_X11_DARK_ORANGE Macro C #define GFX_X11_DARK_ORANGE GFX_RGBConvert(0xFF, 0x8C, 0x00) Description This is macro GFX_X11_DARK_ORANGE. 5.2.2.7.26.452 GFX_X11_DARK_ORCHID Macro C #define GFX_X11_DARK_ORCHID GFX_RGBConvert(0x99, 0x32, 0xCC) Description This is macro GFX_X11_DARK_ORCHID. 5.2.2.7.26.453 GFX_X11_DARK_RED Macro C #define GFX_X11_DARK_RED GFX_RGBConvert(0x8B, 0x00, 0x00) Description This is macro GFX_X11_DARK_RED. 5.2.2.7.26.454 GFX_X11_DARK_SALMON Macro C #define GFX_X11_DARK_SALMON GFX_RGBConvert(0xEA, 0x96, 0x7A) Description This is macro GFX_X11_DARK_SALMON. 5.2.2.7.26.455 GFX_X11_DARK_SEA_GREEN Macro C #define GFX_X11_DARK_SEA_GREEN GFX_RGBConvert(0x8F, 0xBC, 0x8F) Description This is macro GFX_X11_DARK_SEA_GREEN. 5.2.2.7.26.456 GFX_X11_DARK_SLATE_BLUE Macro C #define GFX_X11_DARK_SLATE_BLUE GFX_RGBConvert(0x48, 0x3D, 0x8B) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1016 Description This is macro GFX_X11_DARK_SLATE_BLUE. 5.2.2.7.26.457 GFX_X11_DARK_SLATE_GREY Macro C #define GFX_X11_DARK_SLATE_GREY GFX_RGBConvert(0x2F, 0x4F, 0x4F) Description This is macro GFX_X11_DARK_SLATE_GREY. 5.2.2.7.26.458 GFX_X11_DARK_TURQUOISE Macro C #define GFX_X11_DARK_TURQUOISE GFX_RGBConvert(0x00, 0xCE, 0xD1) Description This is macro GFX_X11_DARK_TURQUOISE. 5.2.2.7.26.459 GFX_X11_DARK_VIOLET Macro C #define GFX_X11_DARK_VIOLET GFX_RGBConvert(0x94, 0x00, 0xD3) Description This is macro GFX_X11_DARK_VIOLET. 5.2.2.7.26.460 GFX_X11_DEEP_PINK Macro C #define GFX_X11_DEEP_PINK GFX_RGBConvert(0xFF, 0x14, 0x93) Description This is macro GFX_X11_DEEP_PINK. 5.2.2.7.26.461 GFX_X11_DEEP_SKY_BLUE Macro C #define GFX_X11_DEEP_SKY_BLUE GFX_RGBConvert(0x00, 0xBF, 0xFF) Description This is macro GFX_X11_DEEP_SKY_BLUE. 5.2.2.7.26.462 GFX_X11_DIM_GREY Macro C #define GFX_X11_DIM_GREY GFX_RGBConvert(0x69, 0x69, 0x69) Description This is macro GFX_X11_DIM_GREY. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1017 5.2.2.7.26.463 GFX_X11_DODGER_BLUE Macro C #define GFX_X11_DODGER_BLUE GFX_RGBConvert(0x1E, 0x90, 0xFF) Description This is macro GFX_X11_DODGER_BLUE. 5.2.2.7.26.464 GFX_X11_FIRE_BRICK Macro C #define GFX_X11_FIRE_BRICK GFX_RGBConvert(0xB2, 0x22, 0x22) Description This is macro GFX_X11_FIRE_BRICK. 5.2.2.7.26.465 GFX_X11_FLORAL_WHITE Macro C #define GFX_X11_FLORAL_WHITE GFX_RGBConvert(0xFF, 0xFA, 0xF0) Description This is macro GFX_X11_FLORAL_WHITE. 5.2.2.7.26.466 GFX_X11_FOREST_GREEN Macro C #define GFX_X11_FOREST_GREEN GFX_RGBConvert(0x22, 0x8B, 0x22) Description This is macro GFX_X11_FOREST_GREEN. 5.2.2.7.26.467 GFX_X11_FUCHSIA Macro C #define GFX_X11_FUCHSIA GFX_RGBConvert(0xFF, 0x00, 0xFF) Description This is macro GFX_X11_FUCHSIA. 5.2.2.7.26.468 GFX_X11_GAINSBORO Macro C #define GFX_X11_GAINSBORO GFX_RGBConvert(0xDC, 0xDC, 0xDC) Description This is macro GFX_X11_GAINSBORO. 5.2.2.7.26.469 GFX_X11_GHOST_WHITE Macro C #define GFX_X11_GHOST_WHITE GFX_RGBConvert(0xF8, 0xF8, 0xFF) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1018 Description This is macro GFX_X11_GHOST_WHITE. 5.2.2.7.26.470 GFX_X11_GOLD Macro C #define GFX_X11_GOLD GFX_RGBConvert(0xFF, 0xD7, 0x00) Description This is macro GFX_X11_GOLD. 5.2.2.7.26.471 GFX_X11_GOLDENROD Macro C #define GFX_X11_GOLDENROD GFX_RGBConvert(0xDA, 0xA5, 0x20) Description This is macro GFX_X11_GOLDENROD. 5.2.2.7.26.472 GFX_X11_GREEN Macro C #define GFX_X11_GREEN GFX_RGBConvert(0x00, 0x80, 0x00) Description This is macro GFX_X11_GREEN. 5.2.2.7.26.473 GFX_X11_GREEN_YELLOW Macro C #define GFX_X11_GREEN_YELLOW GFX_RGBConvert(0xAD, 0xFF, 0x2F) Description This is macro GFX_X11_GREEN_YELLOW. 5.2.2.7.26.474 GFX_X11_GREY Macro C #define GFX_X11_GREY GFX_RGBConvert(0x80, 0x80, 0x80) Description This is macro GFX_X11_GREY. 5.2.2.7.26.475 GFX_X11_HONEYDEW Macro C #define GFX_X11_HONEYDEW GFX_RGBConvert(0xF0, 0xFF, 0xF0) Description This is macro GFX_X11_HONEYDEW. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1019 5.2.2.7.26.476 GFX_X11_HOT_PINK Macro C #define GFX_X11_HOT_PINK GFX_RGBConvert(0xFF, 0x69, 0xB4) Description This is macro GFX_X11_HOT_PINK. 5.2.2.7.26.477 GFX_X11_INDIAN_RED Macro C #define GFX_X11_INDIAN_RED GFX_RGBConvert(0xCD, 0x5C, 0x5C) Description This is macro GFX_X11_INDIAN_RED. 5.2.2.7.26.478 GFX_X11_INDIGO Macro C #define GFX_X11_INDIGO GFX_RGBConvert(0x4B, 0x00, 0x82) Description This is macro GFX_X11_INDIGO. 5.2.2.7.26.479 GFX_X11_IVORY Macro C #define GFX_X11_IVORY GFX_RGBConvert(0xFF, 0xFF, 0xF0) Description This is macro GFX_X11_IVORY. 5.2.2.7.26.480 GFX_X11_KHAKI Macro C #define GFX_X11_KHAKI GFX_RGBConvert(0xF0, 0xE6, 0x8C) Description This is macro GFX_X11_KHAKI. 5.2.2.7.26.481 GFX_X11_LAVENDER Macro C #define GFX_X11_LAVENDER GFX_RGBConvert(0xE6, 0xE6, 0xFA) Description X11: BLUE COLORS 5.2.2.7.26.482 GFX_X11_LAVENDOR_BLUSH Macro C #define GFX_X11_LAVENDOR_BLUSH GFX_RGBConvert(0xFF, 0xF0, 0xF5) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1020 Description This is macro GFX_X11_LAVENDOR_BLUSH. 5.2.2.7.26.483 GFX_X11_LAWN_GREEN Macro C #define GFX_X11_LAWN_GREEN GFX_RGBConvert(0x7C, 0xFC, 0x00) Description This is macro GFX_X11_LAWN_GREEN. 5.2.2.7.26.484 GFX_X11_LEMON_CHIFFON Macro C #define GFX_X11_LEMON_CHIFFON GFX_RGBConvert(0xFF, 0xFA, 0xCD) Description This is macro GFX_X11_LEMON_CHIFFON. 5.2.2.7.26.485 GFX_X11_LIGHT_BLUE Macro C #define GFX_X11_LIGHT_BLUE GFX_RGBConvert(0xAD, 0xD8, 0xE6) Description This is macro GFX_X11_LIGHT_BLUE. 5.2.2.7.26.486 GFX_X11_LIGHT_CAROL Macro C #define GFX_X11_LIGHT_CAROL GFX_RGBConvert(0xF0, 0x80, 0x80) Description This is macro GFX_X11_LIGHT_CAROL. 5.2.2.7.26.487 GFX_X11_LIGHT_CYAN Macro C #define GFX_X11_LIGHT_CYAN GFX_RGBConvert(0xE0, 0xFF, 0xFF) Description This is macro GFX_X11_LIGHT_CYAN. 5.2.2.7.26.488 GFX_X11_LIGHT_GOLDENROD_YELLOW Macro C #define GFX_X11_LIGHT_GOLDENROD_YELLOW GFX_RGBConvert(0xFA, 0xFA, 0xD2) Description This is macro GFX_X11_LIGHT_GOLDENROD_YELLOW. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1021 5.2.2.7.26.489 GFX_X11_LIGHT_GRAY Macro C #define GFX_X11_LIGHT_GRAY GFX_RGBConvert(0xD3, 0xD3, 0xD3) Description This is macro GFX_X11_LIGHT_GRAY. 5.2.2.7.26.490 GFX_X11_LIGHT_GREEN Macro C #define GFX_X11_LIGHT_GREEN GFX_RGBConvert(0x90, 0xEE, 0x90) Description This is macro GFX_X11_LIGHT_GREEN. 5.2.2.7.26.491 GFX_X11_LIGHT_PINK Macro C #define GFX_X11_LIGHT_PINK GFX_RGBConvert(0xFF, 0xB6, 0xC1) Description This is macro GFX_X11_LIGHT_PINK. 5.2.2.7.26.492 GFX_X11_LIGHT_SALMON Macro C #define GFX_X11_LIGHT_SALMON GFX_RGBConvert(0xFF, 0xA0, 0x7A) Description X11: Red Colors 5.2.2.7.26.493 GFX_X11_LIGHT_SEA_GREEN Macro C #define GFX_X11_LIGHT_SEA_GREEN GFX_RGBConvert(0x20, 0xB2, 0xAA) Description This is macro GFX_X11_LIGHT_SEA_GREEN. 5.2.2.7.26.494 GFX_X11_LIGHT_SKY_BLUE Macro C #define GFX_X11_LIGHT_SKY_BLUE GFX_RGBConvert(0x87, 0xCE, 0xFA) Description This is macro GFX_X11_LIGHT_SKY_BLUE. 5.2.2.7.26.495 GFX_X11_LIGHT_SLATE_GREY Macro C #define GFX_X11_LIGHT_SLATE_GREY GFX_RGBConvert(0x77, 0x88, 0x99) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1022 Description This is macro GFX_X11_LIGHT_SLATE_GREY. 5.2.2.7.26.496 GFX_X11_LIGHT_STEEL_BLUE Macro C #define GFX_X11_LIGHT_STEEL_BLUE GFX_RGBConvert(0xB0, 0xC4, 0xDE) Description X11: BLUE COLORS 5.2.2.7.26.497 GFX_X11_LIGHT_YELLOW Macro C #define GFX_X11_LIGHT_YELLOW GFX_RGBConvert(0xFF, 0xFF, 0xE0) Description This is macro GFX_X11_LIGHT_YELLOW. 5.2.2.7.26.498 GFX_X11_LIME Macro C #define GFX_X11_LIME GFX_RGBConvert(0x00, 0xFF, 0x00) Description This is macro GFX_X11_LIME. 5.2.2.7.26.499 GFX_X11_LIME_GREEN Macro C #define GFX_X11_LIME_GREEN GFX_RGBConvert(0x32, 0xCD, 0x32) Description This is macro GFX_X11_LIME_GREEN. 5.2.2.7.26.500 GFX_X11_LINEN Macro C #define GFX_X11_LINEN GFX_RGBConvert(0xFA, 0xF0, 0xE6) Description This is macro GFX_X11_LINEN. 5.2.2.7.26.501 GFX_X11_MAGENTA Macro C #define GFX_X11_MAGENTA GFX_RGBConvert(0xFF, 0x00, 0xFF) Description This is macro GFX_X11_MAGENTA. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1023 5.2.2.7.26.502 GFX_X11_MARRON Macro C #define GFX_X11_MARRON GFX_RGBConvert(0x80, 0x00, 0x00) Description This is macro GFX_X11_MARRON. 5.2.2.7.26.503 GFX_X11_MEDIUM_AQUAMARINE Macro C #define GFX_X11_MEDIUM_AQUAMARINE GFX_RGBConvert(0x66, 0xCD, 0xAA) Description X11: CYAN COLORS 5.2.2.7.26.504 GFX_X11_MEDIUM_BLUE Macro C #define GFX_X11_MEDIUM_BLUE GFX_RGBConvert(0x00, 0x00, 0xCD) Description This is macro GFX_X11_MEDIUM_BLUE. 5.2.2.7.26.505 GFX_X11_MEDIUM_ORCHID Macro C #define GFX_X11_MEDIUM_ORCHID GFX_RGBConvert(0xBA, 0x55, 0xD3) Description This is macro GFX_X11_MEDIUM_ORCHID. 5.2.2.7.26.506 GFX_X11_MEDIUM_PURPLE Macro C #define GFX_X11_MEDIUM_PURPLE GFX_RGBConvert(0x93, 0x70, 0xDB) Description This is macro GFX_X11_MEDIUM_PURPLE. 5.2.2.7.26.507 GFX_X11_MEDIUM_SEA_GREEN Macro C #define GFX_X11_MEDIUM_SEA_GREEN GFX_RGBConvert(0x3C, 0xB3, 0x71) Description This is macro GFX_X11_MEDIUM_SEA_GREEN. 5.2.2.7.26.508 GFX_X11_MEDIUM_SLATE_BLUE Macro C #define GFX_X11_MEDIUM_SLATE_BLUE GFX_RGBConvert(0x7B, 0x68, 0xEE) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1024 Description This is macro GFX_X11_MEDIUM_SLATE_BLUE. 5.2.2.7.26.509 GFX_X11_MEDIUM_SPRING_GREEN Macro C #define GFX_X11_MEDIUM_SPRING_GREEN GFX_RGBConvert(0x00, 0xFA, 0x9A) Description This is macro GFX_X11_MEDIUM_SPRING_GREEN. 5.2.2.7.26.510 GFX_X11_MEDIUM_TURQUOISE Macro C #define GFX_X11_MEDIUM_TURQUOISE GFX_RGBConvert(0x48, 0xD1, 0xCC) Description This is macro GFX_X11_MEDIUM_TURQUOISE. 5.2.2.7.26.511 GFX_X11_MEDIUM_VIOLET_RED Macro C #define GFX_X11_MEDIUM_VIOLET_RED GFX_RGBConvert(0xC7, 0x15, 0x85) Description This is macro GFX_X11_MEDIUM_VIOLET_RED. 5.2.2.7.26.512 GFX_X11_MIDNIGHT_BLUE Macro C #define GFX_X11_MIDNIGHT_BLUE GFX_RGBConvert(0x19, 0x19, 0x70) Description This is macro GFX_X11_MIDNIGHT_BLUE. 5.2.2.7.26.513 GFX_X11_MINT_CREAM Macro C #define GFX_X11_MINT_CREAM GFX_RGBConvert(0xF5, 0xFF, 0xFA) Description This is macro GFX_X11_MINT_CREAM. 5.2.2.7.26.514 GFX_X11_MISTY_ROSE Macro C #define GFX_X11_MISTY_ROSE GFX_RGBConvert(0xFF, 0xE4, 0xE1) Description This is macro GFX_X11_MISTY_ROSE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1025 5.2.2.7.26.515 GFX_X11_MOCCASIN Macro C #define GFX_X11_MOCCASIN GFX_RGBConvert(0xFF, 0xE4, 0xB5) Description This is macro GFX_X11_MOCCASIN. 5.2.2.7.26.516 GFX_X11_NAVAJO_WHITE Macro C #define GFX_X11_NAVAJO_WHITE GFX_RGBConvert(0xFF, 0xDE, 0xAD) Description This is macro GFX_X11_NAVAJO_WHITE. 5.2.2.7.26.517 GFX_X11_NAVY Macro C #define GFX_X11_NAVY GFX_RGBConvert(0x00, 0x00, 0x80) Description This is macro GFX_X11_NAVY. 5.2.2.7.26.518 GFX_X11_OLD_LACE Macro C #define GFX_X11_OLD_LACE GFX_RGBConvert(0xFD, 0xF5, 0xE6) Description This is macro GFX_X11_OLD_LACE. 5.2.2.7.26.519 GFX_X11_OLIVE Macro C #define GFX_X11_OLIVE GFX_RGBConvert(0x80, 0x80, 0x00) Description This is macro GFX_X11_OLIVE. 5.2.2.7.26.520 GFX_X11_OLIVE_DRAB Macro C #define GFX_X11_OLIVE_DRAB GFX_RGBConvert(0x6B, 0x8E, 0x23) Description This is macro GFX_X11_OLIVE_DRAB. 5.2.2.7.26.521 GFX_X11_ORANGE Macro C #define GFX_X11_ORANGE GFX_RGBConvert(0xFF, 0xA5, 0x00) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1026 Description This is macro GFX_X11_ORANGE. 5.2.2.7.26.522 GFX_X11_ORANGE_RED Macro C #define GFX_X11_ORANGE_RED GFX_RGBConvert(0xFF, 0x45, 0x00) Description X11: Orange Colors 5.2.2.7.26.523 GFX_X11_ORCHID Macro C #define GFX_X11_ORCHID GFX_RGBConvert(0xDA, 0x70, 0xD6) Description This is macro GFX_X11_ORCHID. 5.2.2.7.26.524 GFX_X11_PALE_GOLDENROD Macro C #define GFX_X11_PALE_GOLDENROD GFX_RGBConvert(0xEE, 0xE8, 0xAA) Description This is macro GFX_X11_PALE_GOLDENROD. 5.2.2.7.26.525 GFX_X11_PALE_GREEN Macro C #define GFX_X11_PALE_GREEN GFX_RGBConvert(0x98, 0xFB, 0x98) Description This is macro GFX_X11_PALE_GREEN. 5.2.2.7.26.526 GFX_X11_PALE_TURQUOISE Macro C #define GFX_X11_PALE_TURQUOISE GFX_RGBConvert(0xAF, 0xEE, 0xEE) Description This is macro GFX_X11_PALE_TURQUOISE. 5.2.2.7.26.527 GFX_X11_PALE_VIOLET_RED Macro C #define GFX_X11_PALE_VIOLET_RED GFX_RGBConvert(0xDB, 0x70, 0x93) Description This is macro GFX_X11_PALE_VIOLET_RED. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1027 5.2.2.7.26.528 GFX_X11_PAPAYA_WHIP Macro C #define GFX_X11_PAPAYA_WHIP GFX_RGBConvert(0xFF, 0xEF, 0xD5) Description This is macro GFX_X11_PAPAYA_WHIP. 5.2.2.7.26.529 GFX_X11_PEACH_PUFF Macro C #define GFX_X11_PEACH_PUFF GFX_RGBConvert(0xFF, 0xDA, 0xB9) Description This is macro GFX_X11_PEACH_PUFF. 5.2.2.7.26.530 GFX_X11_PERU Macro C #define GFX_X11_PERU GFX_RGBConvert(0xCD, 0x85, 0x3F) Description This is macro GFX_X11_PERU. 5.2.2.7.26.531 GFX_X11_PINK Macro C #define GFX_X11_PINK GFX_RGBConvert(0xFF, 0xC0, 0xCB) Description X11: Pink Colors 5.2.2.7.26.532 GFX_X11_PLUM Macro C #define GFX_X11_PLUM GFX_RGBConvert(0xDD, 0xA0, 0xDD) Description This is macro GFX_X11_PLUM. 5.2.2.7.26.533 GFX_X11_POWDER_BLUE Macro C #define GFX_X11_POWDER_BLUE GFX_RGBConvert(0xB0, 0xE0, 0xE6) Description This is macro GFX_X11_POWDER_BLUE. 5.2.2.7.26.534 GFX_X11_PURPLE Macro C #define GFX_X11_PURPLE GFX_RGBConvert(0x80, 0x00, 0x80) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1028 Description This is macro GFX_X11_PURPLE. 5.2.2.7.26.535 GFX_X11_RED Macro C #define GFX_X11_RED GFX_RGBConvert(0xFF, 0x00, 0x00) Description This is macro GFX_X11_RED. 5.2.2.7.26.536 GFX_X11_ROSY_BROWN Macro C #define GFX_X11_ROSY_BROWN GFX_RGBConvert(0xBc, 0x8F, 0x8F) Description This is macro GFX_X11_ROSY_BROWN. 5.2.2.7.26.537 GFX_X11_ROYAL_BLUE Macro C #define GFX_X11_ROYAL_BLUE GFX_RGBConvert(0x41, 0x69, 0xE1) Description This is macro GFX_X11_ROYAL_BLUE. 5.2.2.7.26.538 GFX_X11_SADDLE_BROWN Macro C #define GFX_X11_SADDLE_BROWN GFX_RGBConvert(0x8B, 0x45, 0x13) Description This is macro GFX_X11_SADDLE_BROWN. 5.2.2.7.26.539 GFX_X11_SALMON Macro C #define GFX_X11_SALMON GFX_RGBConvert(0xFA, 0x80, 0x72) Description This is macro GFX_X11_SALMON. 5.2.2.7.26.540 GFX_X11_SANDY_BROWN Macro C #define GFX_X11_SANDY_BROWN GFX_RGBConvert(0xF4, 0xA4, 0x60) Description This is macro GFX_X11_SANDY_BROWN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1029 5.2.2.7.26.541 GFX_X11_SEA_GREEN Macro C #define GFX_X11_SEA_GREEN GFX_RGBConvert(0x2E, 0x8B, 0x57) Description This is macro GFX_X11_SEA_GREEN. 5.2.2.7.26.542 GFX_X11_SEASHELL Macro C #define GFX_X11_SEASHELL GFX_RGBConvert(0xFF, 0xF5, 0xEE) Description This is macro GFX_X11_SEASHELL. 5.2.2.7.26.543 GFX_X11_SIENNA Macro C #define GFX_X11_SIENNA GFX_RGBConvert(0xA0, 0x52, 0x2D) Description This is macro GFX_X11_SIENNA. 5.2.2.7.26.544 GFX_X11_SILVER Macro C #define GFX_X11_SILVER GFX_RGBConvert(0xC0, 0xC0, 0xC0) Description This is macro GFX_X11_SILVER. 5.2.2.7.26.545 GFX_X11_SKY_BLUE Macro C #define GFX_X11_SKY_BLUE GFX_RGBConvert(0x87, 0xCE, 0xEB) Description This is macro GFX_X11_SKY_BLUE. 5.2.2.7.26.546 GFX_X11_SLATE_BLUE Macro C #define GFX_X11_SLATE_BLUE GFX_RGBConvert(0x6A, 0x5A, 0xCD) Description This is macro GFX_X11_SLATE_BLUE. 5.2.2.7.26.547 GFX_X11_SLATE_GREY Macro C #define GFX_X11_SLATE_GREY GFX_RGBConvert(0x70, 0x80, 0x90) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1030 Description This is macro GFX_X11_SLATE_GREY. 5.2.2.7.26.548 GFX_X11_SNOW Macro C #define GFX_X11_SNOW GFX_RGBConvert(0xFF, 0xFA, 0xFA) Description This is macro GFX_X11_SNOW. 5.2.2.7.26.549 GFX_X11_SPRING_GREEN Macro C #define GFX_X11_SPRING_GREEN GFX_RGBConvert(0x00, 0xFF, 0x7F) Description This is macro GFX_X11_SPRING_GREEN. 5.2.2.7.26.550 GFX_X11_STEEL_BLUE Macro C #define GFX_X11_STEEL_BLUE GFX_RGBConvert(0x46, 0x82, 0xB4) Description This is macro GFX_X11_STEEL_BLUE. 5.2.2.7.26.551 GFX_X11_TAN Macro C #define GFX_X11_TAN GFX_RGBConvert(0xD2, 0xB4, 0x8C) Description This is macro GFX_X11_TAN. 5.2.2.7.26.552 GFX_X11_TEAL Macro C #define GFX_X11_TEAL GFX_RGBConvert(0x00, 0x80, 0x80) Description This is macro GFX_X11_TEAL. 5.2.2.7.26.553 GFX_X11_THISTLE Macro C #define GFX_X11_THISTLE GFX_RGBConvert(0xD8, 0xBF, 0xD8) Description This is macro GFX_X11_THISTLE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1031 5.2.2.7.26.554 GFX_X11_TOMATO Macro C #define GFX_X11_TOMATO GFX_RGBConvert(0xFF, 0x63, 0x47) Description This is macro GFX_X11_TOMATO. 5.2.2.7.26.555 GFX_X11_TURQUOISE Macro C #define GFX_X11_TURQUOISE GFX_RGBConvert(0x40, 0xE0, 0xD0) Description This is macro GFX_X11_TURQUOISE. 5.2.2.7.26.556 GFX_X11_VIOLET Macro C #define GFX_X11_VIOLET GFX_RGBConvert(0xEE, 0x82, 0xEE) Description This is macro GFX_X11_VIOLET. 5.2.2.7.26.557 GFX_X11_WHEAT Macro C #define GFX_X11_WHEAT GFX_RGBConvert(0xF5, 0xDE, 0xB3) Description This is macro GFX_X11_WHEAT. 5.2.2.7.26.558 GFX_X11_WHITE Macro C #define GFX_X11_WHITE GFX_RGBConvert(0xFF, 0xFF, 0xFF) Description X11: WHITE/GRAY/BLACK COLORS 5.2.2.7.26.559 GFX_X11_WHITE_SMOKE Macro C #define GFX_X11_WHITE_SMOKE GFX_RGBConvert(0xF5, 0xF5, 0xF5) Description This is macro GFX_X11_WHITE_SMOKE. 5.2.2.7.26.560 GFX_X11_YELLOW Macro C #define GFX_X11_YELLOW GFX_RGBConvert(0xFF, 0xFF, 0x00) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1032 Description X11: Yellow Colors 5.2.2.7.26.561 GFX_X11_YELLOW_GREEN Macro C #define GFX_X11_YELLOW_GREEN GFX_RGBConvert(0x9A, 0xCD, 0x32) Description This is macro GFX_X11_YELLOW_GREEN. 5.2.2.7.26.562 GFX_XCHAR Macro C #define GFX_XCHAR char Description GFX_CONFIG_FONT_CHAR_SIZE This configuration sets the text character size used in the library. To enable support for unicode fonts, GFX_CONFIG_FONT_CHAR_SIZE must be defined as 16 (size is 16 bits). For standard ascii fonts, this can be defined as 8. This changes the GFX_XCHAR definition. See GFX_XCHAR for details. Set in configuration GFX_XCHAR Description #define GFX_CONFIG_FONT_CHAR_SIZE 16 #define GFX_XCHAR uint16_t Use multiuint8_t characters (0-2^16 range). #define GFX_CONFIG_FONT_CHAR_SIZE 8 #define GFX_XCHAR uint8_t Use multiuint8_t characters (0-255 range). Remarks None. 5.2.2.7.26.563 GOLD Macro C #define GOLD GFX_RGBConvert(255, 215, 0) Description This is macro GOLD. 5.2.2.7.26.564 GRAPHICS_LIBRARY_VERSION Macro C #define GRAPHICS_LIBRARY_VERSION 0x0400 Description //////////////////// GRAPHICS_LIBRARY_VERSION ///////////////////// MSB is version, LSB is subversion 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1033 5.2.2.7.26.565 GRAY000 Macro C #define GRAY000 0 Description This is macro GRAY000. 5.2.2.7.26.566 GRAY001 Macro C #define GRAY001 1 Description This is macro GRAY001. 5.2.2.7.26.567 GRAY002 Macro C #define GRAY002 2 Description This is macro GRAY002. 5.2.2.7.26.568 GRAY003 Macro C #define GRAY003 3 Description This is macro GRAY003. 5.2.2.7.26.569 GRAY004 Macro C #define GRAY004 4 Description This is macro GRAY004. 5.2.2.7.26.570 GRAY005 Macro C #define GRAY005 5 Description This is macro GRAY005. 5.2.2.7.26.571 GRAY006 Macro C #define GRAY006 6 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1034 Description This is macro GRAY006. 5.2.2.7.26.572 GRAY007 Macro C #define GRAY007 7 Description This is macro GRAY007. 5.2.2.7.26.573 GRAY008 Macro C #define GRAY008 8 Description This is macro GRAY008. 5.2.2.7.26.574 GRAY009 Macro C #define GRAY009 9 Description This is macro GRAY009. 5.2.2.7.26.575 GRAY010 Macro C #define GRAY010 GFX_RGBConvert(10, 10, 10) Description This is macro GRAY010. 5.2.2.7.26.576 GRAY011 Macro C #define GRAY011 11 Description This is macro GRAY011. 5.2.2.7.26.577 GRAY012 Macro C #define GRAY012 12 Description This is macro GRAY012. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1035 5.2.2.7.26.578 GRAY013 Macro C #define GRAY013 13 Description This is macro GRAY013. 5.2.2.7.26.579 GRAY014 Macro C #define GRAY014 14 Description This is macro GRAY014. 5.2.2.7.26.580 GRAY015 Macro C #define GRAY015 15 Description This is macro GRAY015. 5.2.2.7.26.581 GRAY032 Macro C #define GRAY032 GFX_RGBConvert(32, 32, 32) Description This is macro GRAY032. 5.2.2.7.26.582 GRAY096 Macro C #define GRAY096 GFX_RGBConvert(96, 96, 96) Description This is macro GRAY096. 5.2.2.7.26.583 GRAY128 Macro C #define GRAY128 GFX_RGBConvert(128, 128, 128) Description This is macro GRAY128. 5.2.2.7.26.584 GRAY160 Macro C #define GRAY160 GFX_RGBConvert(160, 160, 160) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1036 Description This is macro GRAY160. 5.2.2.7.26.585 GRAY192 Macro C #define GRAY192 GFX_RGBConvert(192, 192, 192) Description This is macro GRAY192. 5.2.2.7.26.586 GRAY204 Macro C #define GRAY204 GFX_RGBConvert(204, 204, 204) Description This is macro GRAY204. 5.2.2.7.26.587 GRAY224 Macro C #define GRAY224 GFX_RGBConvert(224, 224, 224) Description This is macro GRAY224. 5.2.2.7.26.588 GRAY229 Macro C #define GRAY229 GFX_RGBConvert(229, 229, 229) Description This is macro GRAY229. 5.2.2.7.26.589 GRAY242 Macro C #define GRAY242 GFX_RGBConvert(242, 242, 242) Description This is macro GRAY242. 5.2.2.7.26.590 GREEN Macro C #define GREEN GFX_RGBConvert(0, 128, 0) Description This is macro GREEN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1037 5.2.2.7.26.591 GRID_DISABLED Macro C #define GRID_DISABLED 0x0002 // Bit for disabled state Description Bit for disabled state 5.2.2.7.26.592 GRID_DRAW_ALL Macro C #define GRID_DRAW_ALL 0x4000 // Bit to indicate whole edit box must be redrawn Description Bit to indicate whole edit box must be redrawn 5.2.2.7.26.593 GRID_DRAW_ITEMS Macro C #define GRID_DRAW_ITEMS 0x1000 // Bit to indicate that at least one item must be redrawn, but not the entire grid. Description Bit to indicate that at least one item must be redrawn, but not the entire grid. 5.2.2.7.26.594 GRID_FOCUSED Macro C #define GRID_FOCUSED 0x0001 // Bit for focused state Description Bit for focused state 5.2.2.7.26.595 GRID_HEIGHT Macro C #define GRID_HEIGHT(r, ch) ((GFX_OBJ_EMBOSS_SIZE * 2) + (r * (ch + 1)) - 1) Description This is macro GRID_HEIGHT. 5.2.2.7.26.596 GRID_HIDE Macro C #define GRID_HIDE 0x8000 // Bit to remove object from screen Description Bit to remove object from screen 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1038 5.2.2.7.26.597 GRID_MAX_COLUMNS Macro C #define GRID_MAX_COLUMNS(rw, cw) ((rw - (GFX_OBJ_EMBOSS_SIZE * 2) + 1) / (cw + 1)) Description This is macro GRID_MAX_COLUMNS. 5.2.2.7.26.598 GRID_MAX_ROWS Macro C #define GRID_MAX_ROWS(rh, ch) ((rh - (GFX_OBJ_EMBOSS_SIZE * 2) + 1) / (ch + 1)) Description This is macro GRID_MAX_ROWS. 5.2.2.7.26.599 GRID_OUT_OF_BOUNDS Macro C #define GRID_OUT_OF_BOUNDS 0x0001 // Status of an out of bounds cell GridSetCell() operation. Description Status of an out of bounds cell GridSetCell() operation. 5.2.2.7.26.600 GRID_SHOW_BORDER_ONLY Macro C #define GRID_SHOW_BORDER_ONLY 0x0010 // Draw only the outside border of the grid. Description Draw only the outside border of the grid. 5.2.2.7.26.601 GRID_SHOW_FOCUS Macro C #define GRID_SHOW_FOCUS 0x0008 // Highlight the focused cell. Description Highlight the focused cell. 5.2.2.7.26.602 GRID_SHOW_LINES Macro C #define GRID_SHOW_LINES 0x0004 // Display grid lines Description Display grid lines 5.2.2.7.26.603 GRID_SHOW_SEPARATORS_ONLY Macro C #define GRID_SHOW_SEPARATORS_ONLY 0x0020 // Draw only the lines between cells (like 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1039 Tic-tac-toe) Description Draw only the lines between cells (like Tic-tac-toe) 5.2.2.7.26.604 GRID_SUCCESS Macro C #define GRID_SUCCESS 0x0000 // Status of a successful GridSetCell() operation. Description Status of a successful GridSetCell() operation. 5.2.2.7.26.605 GRID_TYPE_MASK Macro C #define GRID_TYPE_MASK (0x0C) Description This is macro GRID_TYPE_MASK. 5.2.2.7.26.606 GRID_WIDTH Macro C #define GRID_WIDTH(c, cw) ((GFX_OBJ_EMBOSS_SIZE * 2) + (c * (cw + 1)) - 1) Description This is macro GRID_WIDTH. 5.2.2.7.26.607 GridGetFocusX Macro C #define GridGetFocusX(pGrid) pGrid->focusX Description Macros: GridGetFocusX(pGrid) This macro returns the x position of the focused cell. Preconditions none Parameters Parameters Description pGrid Pointer to the object. Returns Returns the x position of the focused cell. Side Effects none 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1040 5.2.2.7.26.608 GridGetFocusY Macro C #define GridGetFocusY(pGrid) pGrid->focusY Description Macros: GridGetFocusY(pGrid) This macro returns the y position of the focused cell. Preconditions none Parameters Parameters Description pGrid Pointer to the object. Returns Returns the y position of the focused cell. Side Effects none 5.2.2.7.26.609 GRIDITEM_DRAW Macro C #define GRIDITEM_DRAW 0x0100 // Draw this cell Description Draw this cell 5.2.2.7.26.610 GRIDITEM_IS_BITMAP Macro C #define GRIDITEM_IS_BITMAP 0x0008 // The grid item is a bitmap. Description The grid item is a bitmap. 5.2.2.7.26.611 GRIDITEM_IS_TEXT Macro C #define GRIDITEM_IS_TEXT 0x0000 // The grid item is a text string. Description The grid item is a text string. 5.2.2.7.26.612 GRIDITEM_SELECTED Macro C #define GRIDITEM_SELECTED 0x0001 // The cell is selected. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1041 Description The cell is selected. 5.2.2.7.26.613 GRIDITEM_TEXTBOTTOM Macro C #define GRIDITEM_TEXTBOTTOM 0x0040 // Bit to indicate text is top aligned. Description Bit to indicate text is top aligned. 5.2.2.7.26.614 GRIDITEM_TEXTLEFT Macro C #define GRIDITEM_TEXTLEFT 0x0020 // Text in the cell is left aligned. Description Text in the cell is left aligned. 5.2.2.7.26.615 GRIDITEM_TEXTRIGHT Macro C #define GRIDITEM_TEXTRIGHT 0x0010 // Text in the cell is right aligned. Description Text in the cell is right aligned. 5.2.2.7.26.616 GRIDITEM_TEXTTOP Macro C #define GRIDITEM_TEXTTOP 0x0080 // Bit to indicate text is bottom aligned. Description Bit to indicate text is bottom aligned. 5.2.2.7.26.617 HIDE_DATA Macro C #define HIDE_DATA 0 // Macro used to reset the data series show flag or indicate that the data series will be not be shown when the chart is drawn. Description Macro used to reset the data series show flag or indicate that the data series will be not be shown when the chart is drawn. 5.2.2.7.26.618 ImageAbort Macro C #define ImageAbort IMG_blAbortImageDecoding = 1; Description This function sets the Image Decoder's Abort flag so that decoding aborts in the next decoding loop. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1042 Returns None Side Effects None Example void callback(void); void main(void) { IMG_FILE pImageFile; IMG_vInitialize(); ImageLoopCallbackRegister(callback); pImageFile = IMG_FOPEN("Image.jpg", "r"); if(pImageFile == NULL) { <- Error handling -> } IMG_bFullScreenDecode(pImageFile, IMG_JPEG, NULL, NULL); IMG_FCLOSE(pImageFile); while(1); } void callback(void) { if(<- check for abort condition ->) { ImageAbort(); } } 5.2.2.7.26.619 ImageFullScreenDecode Macro C #define ImageFullScreenDecode(pImageFile, eImgFormat, pFileAPIs, pPixelOutput) \ ImageDecode(pImageFile, eImgFormat, 0, 0, IMG_SCREEN_WIDTH, IMG_SCREEN_HEIGHT, (IMG_ALIGN_CENTER | IMG_DOWN_SCALE), pFileAPIs, pPixelOutput) Description This function decodes and displays the image on the screen in fullscreen mode with center aligned and downscaled if required Returns Error code -> 0 means no error Side Effects None Example void main(void) { IMG_FILE pImageFile; IMG_vInitialize(); pImageFile = IMG_FOPEN("Image.jpg", "r"); if(pImageFile == NULL) { <- Error handling -> } 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1043 IMG_bFullScreenDecode(pImageFile, IMG_JPEG, NULL, NULL); IMG_FCLOSE(pImageFile); while(1); } 5.2.2.7.26.620 IMG_ALIGN_CENTER Macro C #define IMG_ALIGN_CENTER 0x0001 Description Flags 5.2.2.7.26.621 IMG_DECODE_ABORTED Macro C #define IMG_DECODE_ABORTED 0xFF Description This is macro IMG_DECODE_ABORTED. 5.2.2.7.26.622 IMG_DOWN_SCALE Macro C #define IMG_DOWN_SCALE 0x0002 Description This is macro IMG_DOWN_SCALE. 5.2.2.7.26.623 IMG_FCLOSE Macro C #define IMG_FCLOSE FSfclose Description This is macro IMG_FCLOSE. 5.2.2.7.26.624 IMG_FEOF Macro C #define IMG_FEOF IMG_pFileAPIs->pFeof Description This is macro IMG_FEOF. 5.2.2.7.26.625 IMG_FILE Macro C #define IMG_FILE void Description This is macro IMG_FILE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1044 5.2.2.7.26.626 IMG_FOPEN Macro C #define IMG_FOPEN FSfopen Description added by Paolo 9/10/08 for MultiApp Demo 5.2.2.7.26.627 IMG_FREAD Macro C #define IMG_FREAD IMG_pFileAPIs->pFread Description This is macro IMG_FREAD. 5.2.2.7.26.628 IMG_FSEEK Macro C #define IMG_FSEEK IMG_pFileAPIs->pFseek Description This is macro IMG_FSEEK. 5.2.2.7.26.629 IMG_FTELL Macro C #define IMG_FTELL IMG_pFileAPIs->pFtell Description This is macro IMG_FTELL. 5.2.2.7.26.630 IMG_SCREEN_HEIGHT Macro C #define IMG_SCREEN_HEIGHT (GetMaxY()+1) Description This is macro IMG_SCREEN_HEIGHT. 5.2.2.7.26.631 IMG_SCREEN_WIDTH Macro C #define IMG_SCREEN_WIDTH (GetMaxX()+1) Description The individual image decoders use these defines instead of directly using those provided in the Display driver file 5.2.2.7.26.632 IMG_vCheckAndAbort Macro C #define IMG_vCheckAndAbort \ 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1045 if(IMG_blAbortImageDecoding == 1) \ { \ IMG_blAbortImageDecoding = 0; \ return IMG_DECODE_ABORTED; \ } Description This is macro IMG_vCheckAndAbort. 5.2.2.7.26.633 IMG_vLoopCallback Macro C #define IMG_vLoopCallback Description This is macro IMG_vLoopCallback. 5.2.2.7.26.634 IMG_vPutPixel Macro C #define IMG_vPutPixel(x, y) if(IMG_bDownScalingFactor <= 1)\ { \ if((x) < IMG_wImageWidth && (y) < IMG_wImageHeight) { _PutPixel(IMG_wStartX + (x), IMG_wStartY + (y)); }\ } \ else if((x)%IMG_bDownScalingFactor == 0 && (y)%IMG_bDownScalingFactor == 0) \ { \ if((x) < IMG_wImageWidth && (y) < IMG_wImageHeight) { _PutPixel(IMG_wStartX + ((x)/IMG_bDownScalingFactor), IMG_wStartY + ((y)/IMG_bDownScalingFactor)); }\ } Description This is macro IMG_vPutPixel. 5.2.2.7.26.635 IMG_vSetColor Macro C #define IMG_vSetColor(handle, r, g, b) GFX_PRIM_SetColor(handle, RGBConvert((r), (g), (b))) Description This is macro IMG_vSetColor. 5.2.2.7.26.636 KHAKI Macro C #define KHAKI GFX_RGBConvert(240, 230, 140) Description This is macro KHAKI. 5.2.2.7.26.637 LIGHTBLUE Macro C #define LIGHTBLUE GFX_RGBConvert(128, 128, 255) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1046 Description This is macro LIGHTBLUE. 5.2.2.7.26.638 LIGHTCYAN Macro C #define LIGHTCYAN GFX_RGBConvert(128, 255, 255) Description This is macro LIGHTCYAN. 5.2.2.7.26.639 LIGHTGRAY Macro C #define LIGHTGRAY GFX_RGBConvert(128, 128, 128) Description This is macro LIGHTGRAY. 5.2.2.7.26.640 LIGHTGREEN Macro C #define LIGHTGREEN GFX_RGBConvert(128, 255, 128) Description This is macro LIGHTGREEN. 5.2.2.7.26.641 LIGHTMAGENTA Macro C #define LIGHTMAGENTA GFX_RGBConvert(255, 128, 255) Description This is macro LIGHTMAGENTA. 5.2.2.7.26.642 LIGHTORANGE Macro C #define LIGHTORANGE GFX_RGBConvert(255, 200, 0) Description This is macro LIGHTORANGE. 5.2.2.7.26.643 LIGHTRED Macro C #define LIGHTRED GFX_RGBConvert(255, 128, 128) Description This is macro LIGHTRED. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1047 5.2.2.7.26.644 LIGHTYELLOW Macro C #define LIGHTYELLOW GFX_RGBConvert(255, 255, 150) Description This is macro LIGHTYELLOW. 5.2.2.7.26.645 MAGENTA Macro C #define MAGENTA GFX_RGBConvert(128, 0, 128) Description This is macro MAGENTA. 5.2.2.7.26.646 MCHP_BITMAP_NORMAL Macro C #define MCHP_BITMAP_NORMAL 0x00 // no compression, palette is present Description no compression, palette is present for color depth = 8, 4 and 1 BPP 5.2.2.7.26.647 MCHP_BITMAP_PALETTE_STR Macro C #define MCHP_BITMAP_PALETTE_STR 0x10 // palette is provided as a separate Description palette is provided as a separate object (see PALETTE_HEADER) for color depth = 8, 4, and 1 BPP, ID to the palette is embedded in the bitmap. 5.2.2.7.26.648 ONEP25 Macro C #define ONEP25 81920 // 1.25 * 2^16 Description 1.25 * 2^16 5.2.2.7.26.649 ORANGE Macro C #define ORANGE GFX_RGBConvert(255, 187, 76) Description This is macro ORANGE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1048 5.2.2.7.26.650 PERU Macro C #define PERU GFX_RGBConvert(205, 133, 63) Description This is macro PERU. 5.2.2.7.26.651 RED Macro C #define RED GFX_RGBConvert(128, 0, 0) Description This is macro RED. 5.2.2.7.26.652 RequestEntirePaletteChange Macro C #define RequestEntirePaletteChange(pPalette) RequestPaletteChange(pPalette, 0, 256) Description Macro: RequestEntirePaletteChange(pPalette) Loads all the palette entries from the flash during vertical blanking period if possible, otherwise loads immediately. Preconditions PPalette must be initialized by PaletteInit(). Parameters Parameters Description pPalette Pointer to the palette structure Returns none Side Effects There may be a slight flicker when the Palette entries are getting loaded one by one. 5.2.2.7.26.653 SADDLEBROWN Macro C #define SADDLEBROWN GFX_RGBConvert(139, 69, 19) Description This is macro SADDLEBROWN. 5.2.2.7.26.654 SCAN_BS_PRESSED Macro C #define SCAN_BS_PRESSED 0x0E 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1049 Description Back space key pressed. 5.2.2.7.26.655 SCAN_BS_RELEASED Macro C #define SCAN_BS_RELEASED 0x8E Description Back space key released. 5.2.2.7.26.656 SCAN_CR_PRESSED Macro C #define SCAN_CR_PRESSED 0x1C Description Carriage return pressed. 5.2.2.7.26.657 SCAN_CR_RELEASED Macro C #define SCAN_CR_RELEASED 0x9C Description Carriage return released. 5.2.2.7.26.658 SCAN_CRA_PRESSED Macro C #define SCAN_CRA_PRESSED 0x2C Description Carriage return alternate pressed. 5.2.2.7.26.659 SCAN_CRA_RELEASED Macro C #define SCAN_CRA_RELEASED 0xAC Description Carriage return alternate released. 5.2.2.7.26.660 SCAN_DEL_PRESSED Macro C #define SCAN_DEL_PRESSED 0x53 Description Delete key pressed. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1050 5.2.2.7.26.661 SCAN_DEL_RELEASED Macro C #define SCAN_DEL_RELEASED 0xD3 Description Delete key released. 5.2.2.7.26.662 SCAN_DOWN_PRESSED Macro C #define SCAN_DOWN_PRESSED 0x50 Description Down key pressed. 5.2.2.7.26.663 SCAN_DOWN_RELEASED Macro C #define SCAN_DOWN_RELEASED 0xD0 Description Down key released. 5.2.2.7.26.664 SCAN_END_PRESSED Macro C #define SCAN_END_PRESSED 0x4F Description End key pressed. 5.2.2.7.26.665 SCAN_END_RELEASED Macro C #define SCAN_END_RELEASED 0xCF Description End key released. 5.2.2.7.26.666 SCAN_HOME_PRESSED Macro C #define SCAN_HOME_PRESSED 0x47 Description Home key pressed. 5.2.2.7.26.667 SCAN_HOME_RELEASED Macro C #define SCAN_HOME_RELEASED 0xC7 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1051 Description Home key released. 5.2.2.7.26.668 SCAN_LEFT_PRESSED Macro C #define SCAN_LEFT_PRESSED 0x4B Description Left key pressed. 5.2.2.7.26.669 SCAN_LEFT_RELEASED Macro C #define SCAN_LEFT_RELEASED 0xCB Description Left key released. 5.2.2.7.26.670 SCAN_PGDOWN_PRESSED Macro C #define SCAN_PGDOWN_PRESSED 0x51 Description Page down key pressed. 5.2.2.7.26.671 SCAN_PGDOWN_RELEASED Macro C #define SCAN_PGDOWN_RELEASED 0xD1 Description Page down key released. 5.2.2.7.26.672 SCAN_PGUP_PRESSED Macro C #define SCAN_PGUP_PRESSED 0x49 Description Page up key pressed. 5.2.2.7.26.673 SCAN_PGUP_RELEASED Macro C #define SCAN_PGUP_RELEASED 0xC9 Description Page up key released. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1052 5.2.2.7.26.674 SCAN_RIGHT_PRESSED Macro C #define SCAN_RIGHT_PRESSED 0x4D Description Right key pressed. 5.2.2.7.26.675 SCAN_RIGHT_RELEASED Macro C #define SCAN_RIGHT_RELEASED 0xCD Description Right key released. 5.2.2.7.26.676 SCAN_SPACE_PRESSED Macro C #define SCAN_SPACE_PRESSED 0x39 Description Space key pressed. 5.2.2.7.26.677 SCAN_SPACE_RELEASED Macro C #define SCAN_SPACE_RELEASED 0xB9 Description Space key released. 5.2.2.7.26.678 SCAN_TAB_PRESSED Macro C #define SCAN_TAB_PRESSED 0x0F Description Tab key pressed. 5.2.2.7.26.679 SCAN_TAB_RELEASED Macro C #define SCAN_TAB_RELEASED 0x8F Description Tab key released. 5.2.2.7.26.680 SCAN_UP_PRESSED Macro C #define SCAN_UP_PRESSED 0x48 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1053 Description Up key pressed. 5.2.2.7.26.681 SCAN_UP_RELEASED Macro C #define SCAN_UP_RELEASED 0xC8 Description Up key released. 5.2.2.7.26.682 SetEntirePalette Macro C #define SetEntirePalette(pPalette) SetPalette(pPalette, 0, 256) Description Macro: SetEntirePalette(pPalette) Programs the whole 256 entry palette with new color values from flash. Preconditions Palette must be initialized by PaletteInit(). Parameters Parameters Description pPalette Pointer to the palette structure Returns Returns the status of the palette set. 0 - Set was successful 1 - Set was not successful Side Effects There may be a slight flicker when the Palette entries are getting loaded one by one. 5.2.2.7.26.683 SHOW_DATA Macro C #define SHOW_DATA 1 // Macro used to set the data series show flag or indicate that the data series will be shown when the chart is drawn. Description Macro used to set the data series show flag or indicate that the data series will be shown when the chart is drawn. 5.2.2.7.26.684 SIENNA Macro C #define SIENNA GFX_RGBConvert(160, 82, 45) Description This is macro SIENNA. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1054 5.2.2.7.26.685 SIN45 Macro C #define SIN45 46341 // sin(45) * 2^16) Description sin(45) * 2^16) 5.2.2.7.26.686 TAN Macro C #define TAN GFX_RGBConvert(210, 180, 140) Description This is macro TAN. 5.2.2.7.26.687 TE_ROUNDEDBUTTON_RADIUS Macro C #define TE_ROUNDEDBUTTON_RADIUS 0 Description Optional settigns Set this parameter in the GraphicsConfig.h 5.2.2.7.26.688 USE_HORZ_ASCENDING_ORDER Macro C #define USE_HORZ_ASCENDING_ORDER Description use ascending order when displaying variables on horizontal mode (bar chart only) 5.2.2.7.26.689 USE_PIE_ENABLE_LABEL Macro C #define USE_PIE_ENABLE_LABEL Description use labels: A:10%,30 where each sample is labeled A-Z followed by a colon. 5.2.2.7.26.690 WHEAT Macro C #define WHEAT GFX_RGBConvert(245, 245, 220) Description This is macro WHEAT. 5.2.2.7.26.691 WHITE Macro C #define WHITE GFX_RGBConvert(255, 255, 255) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1055 Description This is macro WHITE. 5.2.2.7.26.692 YELLOW Macro C #define YELLOW GFX_RGBConvert(255, 255, 128) Description This is macro YELLOW. 5.2.2.7.26.693 GFX_GOL_EDITBOX_STATE Enumeration C typedef enum { GFX_GOL_EDITBOX_FOCUSED_STATE = 0x0001, GFX_GOL_EDITBOX_DISABLED_STATE = 0x0002, GFX_GOL_EDITBOX_ENABLE_CARET_STATE = 0x0004, GFX_GOL_EDITBOX_DRAW_CARET_STATE = 0x1000, GFX_GOL_EDITBOX_DRAW_FOCUS_STATE = 0x2000, GFX_GOL_EDITBOX_DRAW_STATE = 0x4000, GFX_GOL_EDITBOX_HIDE_STATE = 0x8000 } GFX_GOL_EDITBOX_STATE; Description Object States Definition: Members Members Description GFX_GOL_EDITBOX_FOCUSED_STATE = 0x0001 Bit for focus state. Cursor caret will be drawn when GFX_GOL_EDITBOX_ENABLE_CARET_STATE is also set. GFX_GOL_EDITBOX_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_EDITBOX_ENABLE_CARET_STATE = 0x0004 Bit to indicate cursor caret will always be shown. GFX_GOL_EDITBOX_DRAW_CARET_STATE = 0x1000 Bit to indicate the cursor caret will be drawn if GFX_GOL_EDITBOX_FOCUSED_STATE state bit is set and erase when GFX_GOL_EDITBOX_FOCUSED_STATE state bit is not set. GFX_GOL_EDITBOX_DRAW_FOCUS_STATE = 0x2000 Bit to indicate focus must be redrawn. GFX_GOL_EDITBOX_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_EDITBOX_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.694 GFX_GOL_PICTURECONTROL Structure C typedef struct { GFX_GOL_OBJ_HEADER hdr; GFX_RESOURCE_HDR * pImage; int8_t scaleFactor; uint16_t imageLeft; uint16_t imageTop; uint16_t imageRight; uint32_t * stream; uint8_t count; 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1056 uint8_t delay; uint16_t imageBottom; GFX_PARTIAL_IMAGE_PARAM partial; } GFX_GOL_PICTURECONTROL; Description The structure contains data for picture control Members Members Description GFX_GOL_OBJ_HEADER hdr; Generic header for all Objects (see GFX_GOL_OBJ_HEADER). GFX_RESOURCE_HDR * pImage; Pointer to the image int8_t scaleFactor; Scale factor for the bitmap uint16_t imageLeft; image left position when drawn uint16_t imageTop; image top position when drawn uint16_t imageRight; image right position when drawn uint8_t count; Count for the number of bitmaps to be streamed uint8_t delay; Delay in between the streaming of bitmaps uint16_t imageBottom; image bottom position when drawn GFX_PARTIAL_IMAGE_PARAM partial; structure containing partial image data 5.2.2.7.26.695 GFX_GOL_PICTURECONTROLCONTROL_STATE Enumeration C typedef enum { GFX_GOL_PICTURECONTROL_DISABLED_STATE = 0x0002, GFX_GOL_PICTURECONTROL_FRAME_STATE = 0x0004, GFX_GOL_PICTURECONTROL_STREAM_STATE = 0x0008, GFX_GOL_PICTURECONTROL_DRAW_STATE = 0x4000, GFX_GOL_PICTURECONTROL_HIDE_STATE = 0x8000 } GFX_GOL_PICTURECONTROLCONTROL_STATE; Description Object States Definition: Members Members Description GFX_GOL_PICTURECONTROL_DISABLED_STATE = 0x0002 Bit for disabled state. GFX_GOL_PICTURECONTROL_FRAME_STATE = 0x0004 Bit for state with frame. GFX_GOL_PICTURECONTROL_STREAM_STATE = 0x0008 Bit to indicate Picture is streaming GFX_GOL_PICTURECONTROL_DRAW_STATE = 0x4000 Bit to indicate object must be redrawn. GFX_GOL_PICTURECONTROL_HIDE_STATE = 0x8000 Bit to indicate object must be removed from screen. 5.2.2.7.26.696 GFX_GOL_DigitalMeterTextAlignmentGet Macro C #define GFX_GOL_DigitalMeterTextAlignmentGet(pObject) \ (((GFX_GOL_DIGITALMETER *)pObject)->alignment) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1057 Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.26.697 GFX_GOL_DigitalMeterTextAlignmentSet Macro C #define GFX_GOL_DigitalMeterTextAlignmentSet(pObject, align) \ (((GFX_GOL_DIGITALMETER *)pObject)->alignment = align) Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.26.698 GFX_GOL_EditBoxTextAlignmentGet Macro C #define GFX_GOL_EditBoxTextAlignmentGet(pObject) \ (((GFX_GOL_EDITBOX *)pObject)->alignment) Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1058 Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.26.699 GFX_GOL_EditBoxTextAlignmentSet Macro C #define GFX_GOL_EditBoxTextAlignmentSet(pObject, align) \ (((GFX_GOL_EDITBOX *)pObject)->alignment = align) Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2.2.7.26.700 GFX_GOL_EditBoxTextGet Macro C #define GFX_GOL_EditBoxTextGet(pObject) (((GFX_GOL_EDITBOX *)pObject)->pText) Description This function returns the address of the current text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to text string. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1059 Example None. 5.2.2.7.26.701 GFX_GOL_ListBoxTextAlignmentGet Macro C #define GFX_GOL_ListBoxTextAlignmentGet(pObject) \ (((GFX_GOL_LISTBOX *)pObject)->alignment) Description This function returns the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns The text alignment set in the object. See GFX_ALIGNMENT for more details. Example None. 5.2.2.7.26.702 GFX_GOL_ListBoxTextAlignmentSet Macro C #define GFX_GOL_ListBoxTextAlignmentSet(pObject, align) \ (((GFX_GOL_LISTBOX *)pObject)->alignment = align) Description This function sets the text alignment of the text string used by the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject Pointer to the object. align The alignment set for the text in the object. See GFX_ALIGNMENT for more details. Returns None. Example None. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1060 5.2.2.7.26.703 GFX_GOL_PictureControlImageGet Macro C #define GFX_GOL_PictureControlImageGet(pObject) \ (((GFX_GOL_PICTURECONTROL*)pObject)->pImage) Description This function gets the image used when in the pressed state. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. Returns Pointer to the image resource. Example None. 5.2.2.7.26.704 GFX_GOL_PictureControlImageSet Macro C #define GFX_GOL_PictureControlImageSet(pObject, pImage) \ (((GFX_GOL_PICTURECONTROL*)pObject)->pImage = pImage) Description This function sets the image to be in the object. Preconditions Object must exist in memory. Parameters Parameters Description pObject pointer to the object. pImage pointer to the image resource. Returns None. Example // assume OrigImage and NewImage are valid GFX_RESOURCE_HDR // pointers for images GFX_RESOURCE_HDR *pOrigIcon = &OrigImage; GFX_RESOURCE_HDR *pNewIcon = &NewImage; GFX_GOL_PICTURECONTROL *pPicture; pPicture = GFX_GOL_PictureControlCreate( 10, 0, 0, GFX_MaxXGet(), GFX_MaxYGet(), GFX_GOL_PICTURECONTROL_DRAW_STATE, 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1061 pOrigIcon, NULL); // change the image used GFX_GOL_PictureControlImageSet(pPicture , pNewIcon); 5.2.2.7.26.705 GFX_GOL_PictureControlScaleSet Macro C #define GFX_GOL_PictureControlScaleSet(pPict, scl) pPict->scaleFactor = scl Description This function sets the scale factor used to render the bitmap used in the object using scl. Preconditions None. Parameters Parameters Description pPict Pointer to the object scl The scale factor that will be used to display the bitmap. Returns None. Remarks None. Example None. 5.2.2.8 Files Files Name Description gfx.h The header file joins all header files used in the graphics library and contains compile options and defaults. gfx_colors.h The header file contains default color definitions for each color depth. gfx_colors_w3.h The header file contains W3 color definitions. gfx_colors_x11.h The header file contains X11 color definitions. 5.2.2.8.1 gfx.h Module for Microchip Graphics Library This header file includes all the header files required to use the Microchip Graphics Library. Library features and options defined in the Graphics Library configurations will be included in each build. Macros Name Description GRAPHICS_LIBRARY_VERSION //////////////////// GRAPHICS_LIBRARY_VERSION ///////////////////// MSB is version, LSB is subversion 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1062 File Name gfx.h Company Microchip Technology Inc. 5.2.2.8.2 gfx_colors.h Module for Microchip Graphics Library This header file provides default color definitions as well as color conversion macros. Application may or may not use this file. Application may replace this file with new color definitions that fits the application needs. Macros Name Description BLACK This is macro BLACK. BLUE This is macro BLUE. BRIGHTBLUE This is macro BRIGHTBLUE. BRIGHTCYAN This is macro BRIGHTCYAN. BRIGHTGREEN This is macro BRIGHTGREEN. BRIGHTMAGENTA This is macro BRIGHTMAGENTA. BRIGHTRED This is macro BRIGHTRED. BRIGHTYELLOW This is macro BRIGHTYELLOW. BROWN This is macro BROWN. BURLYWOOD This is macro BURLYWOOD. CYAN This is macro CYAN. DARKGRAY This is macro DARKGRAY. DARKORANGE This is macro DARKORANGE. GOLD This is macro GOLD. GRAY000 This is macro GRAY000. GRAY001 This is macro GRAY001. GRAY002 This is macro GRAY002. GRAY003 This is macro GRAY003. GRAY004 This is macro GRAY004. GRAY005 This is macro GRAY005. GRAY006 This is macro GRAY006. GRAY007 This is macro GRAY007. GRAY008 This is macro GRAY008. GRAY009 This is macro GRAY009. GRAY010 This is macro GRAY010. GRAY011 This is macro GRAY011. GRAY012 This is macro GRAY012. GRAY013 This is macro GRAY013. GRAY014 This is macro GRAY014. GRAY015 This is macro GRAY015. GRAY032 This is macro GRAY032. GRAY096 This is macro GRAY096. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1063 GRAY128 This is macro GRAY128. GRAY160 This is macro GRAY160. GRAY192 This is macro GRAY192. GRAY204 This is macro GRAY204. GRAY224 This is macro GRAY224. GRAY229 This is macro GRAY229. GRAY242 This is macro GRAY242. GREEN This is macro GREEN. LIGHTBLUE This is macro LIGHTBLUE. LIGHTCYAN This is macro LIGHTCYAN. LIGHTGRAY This is macro LIGHTGRAY. LIGHTGREEN This is macro LIGHTGREEN. LIGHTMAGENTA This is macro LIGHTMAGENTA. LIGHTORANGE This is macro LIGHTORANGE. LIGHTRED This is macro LIGHTRED. LIGHTYELLOW This is macro LIGHTYELLOW. MAGENTA This is macro MAGENTA. ORANGE This is macro ORANGE. PERU This is macro PERU. RED This is macro RED. SADDLEBROWN This is macro SADDLEBROWN. SIENNA This is macro SIENNA. TAN This is macro TAN. WHEAT This is macro WHEAT. WHITE This is macro WHITE. YELLOW This is macro YELLOW. File Name gfx_colors.h Company Microchip Technology Inc. 5.2.2.8.3 gfx_colors_w3.h Module for Microchip Graphics Library This header file provides W3 color definitions as an option of color definitions to use. Remarks http://www.w3.org/TR/SVG/types.html#ColorKeywords Macros Name Description GFX_W3_ALICEBLUE This is macro GFX_W3_ALICEBLUE. GFX_W3_ANTIQUEWHITE This is macro GFX_W3_ANTIQUEWHITE. GFX_W3_AQUA This is macro GFX_W3_AQUA. GFX_W3_AQUAMARINE This is macro GFX_W3_AQUAMARINE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1064 GFX_W3_AZURE This is macro GFX_W3_AZURE. GFX_W3_BEIGE This is macro GFX_W3_BEIGE. GFX_W3_BISQUE This is macro GFX_W3_BISQUE. GFX_W3_BLACK This is macro GFX_W3_BLACK. GFX_W3_BLANCHEDALMOND This is macro GFX_W3_BLANCHEDALMOND. GFX_W3_BLUE This is macro GFX_W3_BLUE. GFX_W3_BLUEVIOLET This is macro GFX_W3_BLUEVIOLET. GFX_W3_BROWN This is macro GFX_W3_BROWN. GFX_W3_BURLYWOOD This is macro GFX_W3_BURLYWOOD. GFX_W3_CADETBLUE This is macro GFX_W3_CADETBLUE. GFX_W3_CHARTREUSE This is macro GFX_W3_CHARTREUSE. GFX_W3_CHOCOLATE This is macro GFX_W3_CHOCOLATE. GFX_W3_CORAL This is macro GFX_W3_CORAL. GFX_W3_CORNFLOWERBLUE This is macro GFX_W3_CORNFLOWERBLUE. GFX_W3_CORNSILK This is macro GFX_W3_CORNSILK. GFX_W3_CRIMSON This is macro GFX_W3_CRIMSON. GFX_W3_CYAN This is macro GFX_W3_CYAN. GFX_W3_DARKBLUE This is macro GFX_W3_DARKBLUE. GFX_W3_DARKCYAN This is macro GFX_W3_DARKCYAN. GFX_W3_darkgoldenrod This is macro GFX_W3_darkgoldenrod. GFX_W3_DARKGRAY This is macro GFX_W3_DARKGRAY. GFX_W3_DARKGREEN This is macro GFX_W3_DARKGREEN. GFX_W3_DARKGREY This is macro GFX_W3_DARKGREY. GFX_W3_DARKHAKI This is macro GFX_W3_DARKHAKI. GFX_W3_DARKMAGENTA This is macro GFX_W3_DARKMAGENTA. GFX_W3_DARKOLIVEGREEN This is macro GFX_W3_DARKOLIVEGREEN. GFX_W3_DARKORANGE This is macro GFX_W3_DARKORANGE. GFX_W3_DARKORCHID This is macro GFX_W3_DARKORCHID. GFX_W3_DARKRED This is macro GFX_W3_DARKRED. GFX_W3_DARKSALMON This is macro GFX_W3_DARKSALMON. GFX_W3_DARKSEAGREEN This is macro GFX_W3_DARKSEAGREEN. GFX_W3_DARKSLATEBLUE This is macro GFX_W3_DARKSLATEBLUE. GFX_W3_DARKSLATEGRAY This is macro GFX_W3_DARKSLATEGRAY. GFX_W3_DARKSLATEGREY This is macro GFX_W3_DARKSLATEGREY. GFX_W3_DARKTURQUOISE This is macro GFX_W3_DARKTURQUOISE. GFX_W3_DARKVIOLET This is macro GFX_W3_DARKVIOLET. GFX_W3_DEEPPINK This is macro GFX_W3_DEEPPINK. GFX_W3_DEEPSKYBLUE This is macro GFX_W3_DEEPSKYBLUE. GFX_W3_DIMGRAY This is macro GFX_W3_DIMGRAY. GFX_W3_DIMGREY This is macro GFX_W3_DIMGREY. GFX_W3_DODGERBLUE This is macro GFX_W3_DODGERBLUE. GFX_W3_FIREBRICK This is macro GFX_W3_FIREBRICK. GFX_W3_FLORALWHITE This is macro GFX_W3_FLORALWHITE. GFX_W3_FORESTGREEN This is macro GFX_W3_FORESTGREEN. GFX_W3_FUCHSIA This is macro GFX_W3_FUCHSIA. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1065 GFX_W3_GAINSBORO This is macro GFX_W3_GAINSBORO. GFX_W3_GHOSTWHITE This is macro GFX_W3_GHOSTWHITE. GFX_W3_GOLD This is macro GFX_W3_GOLD. GFX_W3_GOLDENROD This is macro GFX_W3_GOLDENROD. GFX_W3_GRAY This is macro GFX_W3_GRAY. GFX_W3_GREEN This is macro GFX_W3_GREEN. GFX_W3_GREENYELLOW This is macro GFX_W3_GREENYELLOW. GFX_W3_GREY This is macro GFX_W3_GREY. GFX_W3_HONEYDEW This is macro GFX_W3_HONEYDEW. GFX_W3_HOTPINK This is macro GFX_W3_HOTPINK. GFX_W3_INDIANRED This is macro GFX_W3_INDIANRED. GFX_W3_INDIGO This is macro GFX_W3_INDIGO. GFX_W3_IVORY This is macro GFX_W3_IVORY. GFX_W3_LAVENDER This is macro GFX_W3_LAVENDER. GFX_W3_LAVENDERBLUSH This is macro GFX_W3_LAVENDERBLUSH. GFX_W3_LAWNGREEN This is macro GFX_W3_LAWNGREEN. GFX_W3_LEMONCHIFFON This is macro GFX_W3_LEMONCHIFFON. GFX_W3_LIGHTBLUE This is macro GFX_W3_LIGHTBLUE. GFX_W3_LIGHTCORAL This is macro GFX_W3_LIGHTCORAL. GFX_W3_LIGHTCYAN This is macro GFX_W3_LIGHTCYAN. GFX_W3_LIGHTGOLDENRODYELLOW This is macro GFX_W3_LIGHTGOLDENRODYELLOW. GFX_W3_LIGHTGRAY This is macro GFX_W3_LIGHTGRAY. GFX_W3_LIGHTGREEN This is macro GFX_W3_LIGHTGREEN. GFX_W3_LIGHTGREY This is macro GFX_W3_LIGHTGREY. GFX_W3_LIGHTPINK This is macro GFX_W3_LIGHTPINK. GFX_W3_LIGHTSALMON This is macro GFX_W3_LIGHTSALMON. GFX_W3_LIGHTSKYBLUE This is macro GFX_W3_LIGHTSKYBLUE. GFX_W3_LIGHTSLATEGRAY This is macro GFX_W3_LIGHTSLATEGRAY. GFX_W3_LIGHTSLATEGREY This is macro GFX_W3_LIGHTSLATEGREY. GFX_W3_LIGHTSTEELBLUE This is macro GFX_W3_LIGHTSTEELBLUE. GFX_W3_LIGHTYELLOW This is macro GFX_W3_LIGHTYELLOW. GFX_W3_LIGTHSEAGREEN This is macro GFX_W3_LIGTHSEAGREEN. GFX_W3_LIME This is macro GFX_W3_LIME. GFX_W3_LIMEGREEN This is macro GFX_W3_LIMEGREEN. GFX_W3_LINEN This is macro GFX_W3_LINEN. GFX_W3_MAGENTA This is macro GFX_W3_MAGENTA. GFX_W3_MAROON This is macro GFX_W3_MAROON. GFX_W3_MEDIUMAQUAMARINE This is macro GFX_W3_MEDIUMAQUAMARINE. GFX_W3_MEDIUMBLUE This is macro GFX_W3_MEDIUMBLUE. GFX_W3_MEDIUMORCHID This is macro GFX_W3_MEDIUMORCHID. GFX_W3_MEDIUMPURPLE This is macro GFX_W3_MEDIUMPURPLE. GFX_W3_MEDIUMSEAGREEN This is macro GFX_W3_MEDIUMSEAGREEN. GFX_W3_MEDIUMSLATEBLUE This is macro GFX_W3_MEDIUMSLATEBLUE. GFX_W3_MEDIUMSPRINGGREEN This is macro GFX_W3_MEDIUMSPRINGGREEN. GFX_W3_MEDIUMTURQUOISE This is macro GFX_W3_MEDIUMTURQUOISE. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1066 GFX_W3_MEDIUMVIOLETRED This is macro GFX_W3_MEDIUMVIOLETRED. GFX_W3_MIDNIGHTBLUE This is macro GFX_W3_MIDNIGHTBLUE. GFX_W3_MINTCREAM This is macro GFX_W3_MINTCREAM. GFX_W3_MISTYROSE This is macro GFX_W3_MISTYROSE. GFX_W3_MOCCASIN This is macro GFX_W3_MOCCASIN. GFX_W3_NAVAJOWHITE This is macro GFX_W3_NAVAJOWHITE. GFX_W3_NAVY This is macro GFX_W3_NAVY. GFX_W3_OLDLACE This is macro GFX_W3_OLDLACE. GFX_W3_OLIVE This is macro GFX_W3_OLIVE. GFX_W3_OLIVEDRAB This is macro GFX_W3_OLIVEDRAB. GFX_W3_ORANGE This is macro GFX_W3_ORANGE. GFX_W3_ORANGERED This is macro GFX_W3_ORANGERED. GFX_W3_ORCHID This is macro GFX_W3_ORCHID. GFX_W3_PALEGOLDENROD This is macro GFX_W3_PALEGOLDENROD. GFX_W3_PALEGREEN This is macro GFX_W3_PALEGREEN. GFX_W3_PALETURQUOISE This is macro GFX_W3_PALETURQUOISE. GFX_W3_PALEVIOLETRED This is macro GFX_W3_PALEVIOLETRED. GFX_W3_PAPAYAWHIP This is macro GFX_W3_PAPAYAWHIP. GFX_W3_PEACHPUFF This is macro GFX_W3_PEACHPUFF. GFX_W3_PERU This is macro GFX_W3_PERU. GFX_W3_PINK This is macro GFX_W3_PINK. GFX_W3_PLUM This is macro GFX_W3_PLUM. GFX_W3_POWDERBLUE This is macro GFX_W3_POWDERBLUE. GFX_W3_PURPLE This is macro GFX_W3_PURPLE. GFX_W3_RED This is macro GFX_W3_RED. GFX_W3_ROSYBROWN This is macro GFX_W3_ROSYBROWN. GFX_W3_ROYALBLUE This is macro GFX_W3_ROYALBLUE. GFX_W3_SADDLEBROWN This is macro GFX_W3_SADDLEBROWN. GFX_W3_SALMON This is macro GFX_W3_SALMON. GFX_W3_SANDYGREEN This is macro GFX_W3_SANDYGREEN. GFX_W3_SEAGREEN This is macro GFX_W3_SEAGREEN. GFX_W3_SEASHELL This is macro GFX_W3_SEASHELL. GFX_W3_SIENNA This is macro GFX_W3_SIENNA. GFX_W3_SILVER This is macro GFX_W3_SILVER. GFX_W3_SKYBLUE This is macro GFX_W3_SKYBLUE. GFX_W3_SLATEBLUE This is macro GFX_W3_SLATEBLUE. GFX_W3_SLATEGRAY This is macro GFX_W3_SLATEGRAY. GFX_W3_SLATEGREY This is macro GFX_W3_SLATEGREY. GFX_W3_SNOW This is macro GFX_W3_SNOW. GFX_W3_SPRINGGREEN This is macro GFX_W3_SPRINGGREEN. GFX_W3_STEELBLUE This is macro GFX_W3_STEELBLUE. GFX_W3_TAN This is macro GFX_W3_TAN. GFX_W3_TEAL This is macro GFX_W3_TEAL. GFX_W3_THISTLE This is macro GFX_W3_THISTLE. GFX_W3_TOMATO This is macro GFX_W3_TOMATO. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1067 GFX_W3_TURQUOISE This is macro GFX_W3_TURQUOISE. GFX_W3_VIOLET This is macro GFX_W3_VIOLET. GFX_W3_WHEAT This is macro GFX_W3_WHEAT. GFX_W3_WHITE This is macro GFX_W3_WHITE. GFX_W3_WHITESMOKE This is macro GFX_W3_WHITESMOKE. GFX_W3_YELLOW This is macro GFX_W3_YELLOW. GFX_W3_YELLOWGREEN This is macro GFX_W3_YELLOWGREEN. KHAKI This is macro KHAKI. File Name gfx_colors_w3.h Company Microchip Technology Inc. 5.2.2.8.4 gfx_colors_x11.h Module for Microchip Graphics Library This header file provides X11 color definitions as an option of color definitions to use. Macros Name Description GFX_X11_ALICE_BLUE This is macro GFX_X11_ALICE_BLUE. GFX_X11_ANTIQUE_WHITE This is macro GFX_X11_ANTIQUE_WHITE. GFX_X11_AQUA This is macro GFX_X11_AQUA. GFX_X11_AQUAMARINE This is macro GFX_X11_AQUAMARINE. GFX_X11_AZURE This is macro GFX_X11_AZURE. GFX_X11_BEIGE This is macro GFX_X11_BEIGE. GFX_X11_BISQUE This is macro GFX_X11_BISQUE. GFX_X11_BLACK This is macro GFX_X11_BLACK. GFX_X11_BLANCHED_ALMOND This is macro GFX_X11_BLANCHED_ALMOND. GFX_X11_BLUE This is macro GFX_X11_BLUE. GFX_X11_BLUE_VIOLET This is macro GFX_X11_BLUE_VIOLET. GFX_X11_BROWN This is macro GFX_X11_BROWN. GFX_X11_BURLY_WOOD This is macro GFX_X11_BURLY_WOOD. GFX_X11_CADEL_BLUE This is macro GFX_X11_CADEL_BLUE. GFX_X11_CHARTEUSE This is macro GFX_X11_CHARTEUSE. GFX_X11_CHOCOLATE This is macro GFX_X11_CHOCOLATE. GFX_X11_CORAL This is macro GFX_X11_CORAL. GFX_X11_CORNFLOWER_BLUE This is macro GFX_X11_CORNFLOWER_BLUE. GFX_X11_CORNSILK X11: Brown Colors GFX_X11_CRIMSON This is macro GFX_X11_CRIMSON. GFX_X11_CYAN This is macro GFX_X11_CYAN. GFX_X11_DARK_BLUE This is macro GFX_X11_DARK_BLUE. GFX_X11_DARK_CYAN This is macro GFX_X11_DARK_CYAN. GFX_X11_DARK_GOLDENROD This is macro GFX_X11_DARK_GOLDENROD. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1068 GFX_X11_DARK_GREEN This is macro GFX_X11_DARK_GREEN. GFX_X11_DARK_GREY This is macro GFX_X11_DARK_GREY. GFX_X11_DARK_KHAKI This is macro GFX_X11_DARK_KHAKI. GFX_X11_DARK_MAGENTA This is macro GFX_X11_DARK_MAGENTA. GFX_X11_DARK_OLIVE_GREEN X11: Green Colors GFX_X11_DARK_ORANGE This is macro GFX_X11_DARK_ORANGE. GFX_X11_DARK_ORCHID This is macro GFX_X11_DARK_ORCHID. GFX_X11_DARK_RED This is macro GFX_X11_DARK_RED. GFX_X11_DARK_SALMON This is macro GFX_X11_DARK_SALMON. GFX_X11_DARK_SEA_GREEN This is macro GFX_X11_DARK_SEA_GREEN. GFX_X11_DARK_SLATE_BLUE This is macro GFX_X11_DARK_SLATE_BLUE. GFX_X11_DARK_SLATE_GREY This is macro GFX_X11_DARK_SLATE_GREY. GFX_X11_DARK_TURQUOISE This is macro GFX_X11_DARK_TURQUOISE. GFX_X11_DARK_VIOLET This is macro GFX_X11_DARK_VIOLET. GFX_X11_DEEP_PINK This is macro GFX_X11_DEEP_PINK. GFX_X11_DEEP_SKY_BLUE This is macro GFX_X11_DEEP_SKY_BLUE. GFX_X11_DIM_GREY This is macro GFX_X11_DIM_GREY. GFX_X11_DODGER_BLUE This is macro GFX_X11_DODGER_BLUE. GFX_X11_FIRE_BRICK This is macro GFX_X11_FIRE_BRICK. GFX_X11_FLORAL_WHITE This is macro GFX_X11_FLORAL_WHITE. GFX_X11_FOREST_GREEN This is macro GFX_X11_FOREST_GREEN. GFX_X11_FUCHSIA This is macro GFX_X11_FUCHSIA. GFX_X11_GAINSBORO This is macro GFX_X11_GAINSBORO. GFX_X11_GHOST_WHITE This is macro GFX_X11_GHOST_WHITE. GFX_X11_GOLD This is macro GFX_X11_GOLD. GFX_X11_GOLDENROD This is macro GFX_X11_GOLDENROD. GFX_X11_GREEN This is macro GFX_X11_GREEN. GFX_X11_GREEN_YELLOW This is macro GFX_X11_GREEN_YELLOW. GFX_X11_GREY This is macro GFX_X11_GREY. GFX_X11_HONEYDEW This is macro GFX_X11_HONEYDEW. GFX_X11_HOT_PINK This is macro GFX_X11_HOT_PINK. GFX_X11_INDIAN_RED This is macro GFX_X11_INDIAN_RED. GFX_X11_INDIGO This is macro GFX_X11_INDIGO. GFX_X11_IVORY This is macro GFX_X11_IVORY. GFX_X11_KHAKI This is macro GFX_X11_KHAKI. GFX_X11_LAVENDER X11: BLUE COLORS GFX_X11_LAVENDOR_BLUSH This is macro GFX_X11_LAVENDOR_BLUSH. GFX_X11_LAWN_GREEN This is macro GFX_X11_LAWN_GREEN. GFX_X11_LEMON_CHIFFON This is macro GFX_X11_LEMON_CHIFFON. GFX_X11_LIGHT_BLUE This is macro GFX_X11_LIGHT_BLUE. GFX_X11_LIGHT_CAROL This is macro GFX_X11_LIGHT_CAROL. GFX_X11_LIGHT_CYAN This is macro GFX_X11_LIGHT_CYAN. GFX_X11_LIGHT_GOLDENROD_YELLOW This is macro GFX_X11_LIGHT_GOLDENROD_YELLOW. GFX_X11_LIGHT_GRAY This is macro GFX_X11_LIGHT_GRAY. GFX_X11_LIGHT_GREEN This is macro GFX_X11_LIGHT_GREEN. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1069 GFX_X11_LIGHT_PINK This is macro GFX_X11_LIGHT_PINK. GFX_X11_LIGHT_SALMON X11: Red Colors GFX_X11_LIGHT_SEA_GREEN This is macro GFX_X11_LIGHT_SEA_GREEN. GFX_X11_LIGHT_SKY_BLUE This is macro GFX_X11_LIGHT_SKY_BLUE. GFX_X11_LIGHT_SLATE_GREY This is macro GFX_X11_LIGHT_SLATE_GREY. GFX_X11_LIGHT_STEEL_BLUE X11: BLUE COLORS GFX_X11_LIGHT_YELLOW This is macro GFX_X11_LIGHT_YELLOW. GFX_X11_LIME This is macro GFX_X11_LIME. GFX_X11_LIME_GREEN This is macro GFX_X11_LIME_GREEN. GFX_X11_LINEN This is macro GFX_X11_LINEN. GFX_X11_MAGENTA This is macro GFX_X11_MAGENTA. GFX_X11_MARRON This is macro GFX_X11_MARRON. GFX_X11_MEDIUM_AQUAMARINE X11: CYAN COLORS GFX_X11_MEDIUM_BLUE This is macro GFX_X11_MEDIUM_BLUE. GFX_X11_MEDIUM_ORCHID This is macro GFX_X11_MEDIUM_ORCHID. GFX_X11_MEDIUM_PURPLE This is macro GFX_X11_MEDIUM_PURPLE. GFX_X11_MEDIUM_SEA_GREEN This is macro GFX_X11_MEDIUM_SEA_GREEN. GFX_X11_MEDIUM_SLATE_BLUE This is macro GFX_X11_MEDIUM_SLATE_BLUE. GFX_X11_MEDIUM_SPRING_GREEN This is macro GFX_X11_MEDIUM_SPRING_GREEN. GFX_X11_MEDIUM_TURQUOISE This is macro GFX_X11_MEDIUM_TURQUOISE. GFX_X11_MEDIUM_VIOLET_RED This is macro GFX_X11_MEDIUM_VIOLET_RED. GFX_X11_MIDNIGHT_BLUE This is macro GFX_X11_MIDNIGHT_BLUE. GFX_X11_MINT_CREAM This is macro GFX_X11_MINT_CREAM. GFX_X11_MISTY_ROSE This is macro GFX_X11_MISTY_ROSE. GFX_X11_MOCCASIN This is macro GFX_X11_MOCCASIN. GFX_X11_NAVAJO_WHITE This is macro GFX_X11_NAVAJO_WHITE. GFX_X11_NAVY This is macro GFX_X11_NAVY. GFX_X11_OLD_LACE This is macro GFX_X11_OLD_LACE. GFX_X11_OLIVE This is macro GFX_X11_OLIVE. GFX_X11_OLIVE_DRAB This is macro GFX_X11_OLIVE_DRAB. GFX_X11_ORANGE This is macro GFX_X11_ORANGE. GFX_X11_ORANGE_RED X11: Orange Colors GFX_X11_ORCHID This is macro GFX_X11_ORCHID. GFX_X11_PALE_GOLDENROD This is macro GFX_X11_PALE_GOLDENROD. GFX_X11_PALE_GREEN This is macro GFX_X11_PALE_GREEN. GFX_X11_PALE_TURQUOISE This is macro GFX_X11_PALE_TURQUOISE. GFX_X11_PALE_VIOLET_RED This is macro GFX_X11_PALE_VIOLET_RED. GFX_X11_PAPAYA_WHIP This is macro GFX_X11_PAPAYA_WHIP. GFX_X11_PEACH_PUFF This is macro GFX_X11_PEACH_PUFF. GFX_X11_PERU This is macro GFX_X11_PERU. GFX_X11_PINK X11: Pink Colors GFX_X11_PLUM This is macro GFX_X11_PLUM. GFX_X11_POWDER_BLUE This is macro GFX_X11_POWDER_BLUE. GFX_X11_PURPLE This is macro GFX_X11_PURPLE. GFX_X11_RED This is macro GFX_X11_RED. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1070 GFX_X11_ROSY_BROWN This is macro GFX_X11_ROSY_BROWN. GFX_X11_ROYAL_BLUE This is macro GFX_X11_ROYAL_BLUE. GFX_X11_SADDLE_BROWN This is macro GFX_X11_SADDLE_BROWN. GFX_X11_SALMON This is macro GFX_X11_SALMON. GFX_X11_SANDY_BROWN This is macro GFX_X11_SANDY_BROWN. GFX_X11_SEA_GREEN This is macro GFX_X11_SEA_GREEN. GFX_X11_SEASHELL This is macro GFX_X11_SEASHELL. GFX_X11_SIENNA This is macro GFX_X11_SIENNA. GFX_X11_SILVER This is macro GFX_X11_SILVER. GFX_X11_SKY_BLUE This is macro GFX_X11_SKY_BLUE. GFX_X11_SLATE_BLUE This is macro GFX_X11_SLATE_BLUE. GFX_X11_SLATE_GREY This is macro GFX_X11_SLATE_GREY. GFX_X11_SNOW This is macro GFX_X11_SNOW. GFX_X11_SPRING_GREEN This is macro GFX_X11_SPRING_GREEN. GFX_X11_STEEL_BLUE This is macro GFX_X11_STEEL_BLUE. GFX_X11_TAN This is macro GFX_X11_TAN. GFX_X11_TEAL This is macro GFX_X11_TEAL. GFX_X11_THISTLE This is macro GFX_X11_THISTLE. GFX_X11_TOMATO This is macro GFX_X11_TOMATO. GFX_X11_TURQUOISE This is macro GFX_X11_TURQUOISE. GFX_X11_VIOLET This is macro GFX_X11_VIOLET. GFX_X11_WHEAT This is macro GFX_X11_WHEAT. GFX_X11_WHITE X11: WHITE/GRAY/BLACK COLORS GFX_X11_WHITE_SMOKE This is macro GFX_X11_WHITE_SMOKE. GFX_X11_YELLOW X11: Yellow Colors GFX_X11_YELLOW_GREEN This is macro GFX_X11_YELLOW_GREEN. File Name gfx_colors_x11.h Company Microchip Technology Inc. 5.2.2.8.5 gfx_config_template.h • Module for Microchip Graphics Library • This file contains compile time options for the Graphics Library. ******************************************************************* • FileName: GraphicsConfig.h • Dependencies: none • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: C30 V3.00/C32 • Company: Microchip Technology, Inc. * 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1071 • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED ?AS IS? WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • Anton Alkhimenok 10/28/2007 Initial Version • Pradeep Budagutta 10/28/2007 Display related defines • moved to DisplayConfig.h Macros Name Description COLOR_DEPTH Specifies the color depth used in the application defined in GraphicsConfig.h. 5.2.2.8.6 gfx_gol.h Module for Microchip Graphics Library - Graphic Object Layer This module implements the common routines for the Graphics Object Layer of the Microchip Graphics Library. The routines are independent of the Display Driver Layer and should be compatible with any Display Driver that is compliant with the requirements of the Display Driver Layer of the Graphics Library. The module utilizes the Graphics Primitive Layer to render the objects. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1072 Enumerations Name Description GFX_GOL_OBJ_TYPE Specifies the different object types used in the library. GFX_GOL_TRANSLATED_ACTION Specifies the different object actions supported in the library. INPUT_DEVICE_EVENT Specifies the different user input device events supported in the library. INPUT_DEVICE_TYPE Specifies the different user input devices supported in the library. Functions Name Description GFX_GOL_DrawCallbackSet This function sets the draw callback function that the application will use to render application specific rendering. GFX_GOL_MessageCallbackSet This function sets the message callback function that the application will use to evaluate user inputs that affects the objects and application behavior. GFX_GOL_ObjectAdd This function adds an object to the tail of the currently active list. GFX_GOL_ObjectBackGroundSet This function sets the background information. GFX_GOL_ObjectByIDDelete This function removes an object with the given user defined ID from the currently active list. GFX_GOL_ObjectCanBeFocused Checks if the object can be focused. GFX_GOL_ObjectDelete This function removes an object from the currently active list. GFX_GOL_ObjectDrawDisable This function resets the drawing state bits of the object. GFX_GOL_ObjectDrawEnable This function sets the object to be redraw. GFX_GOL_ObjectFind This function returns the pointer to object in the list with the user defined ID assigned to it. GFX_GOL_ObjectFocusGet This function returns the pointer to the object that is currently receiving keyboard input (or focused). GFX_GOL_ObjectFocusNextGet This function returns the pointer to the next object in the active list of objects which can be focused. GFX_GOL_ObjectFocusPrevGet This function returns the pointer to the previous object in the active list of objects which can be focused. GFX_GOL_ObjectFocusSet This function sets the object to be focused. GFX_GOL_ObjectHideDraw This is function GFX_GOL_ObjectHideDraw. GFX_GOL_ObjectIDGet This function returns the object ID. GFX_GOL_ObjectIsRedrawSet This function checks if the object needs to be redrawn or not. GFX_GOL_ObjectListDraw This function redraws all objects in the current active list that has the rendering state bits set. GFX_GOL_ObjectListFree This function sets the active list to the new list. GFX_GOL_ObjectListGet This function returns the current active list. GFX_GOL_ObjectListNew This function removes an object with the given user defined ID from the currently active list. GFX_GOL_ObjectListSet This function sets the active list to the new list. GFX_GOL_ObjectMessage This function process the received message from the user to determine the affected objects. Depending on the message and the affected objects, object states are modified based on the default behaviour or user defined behaviour. GFX_GOL_ObjectNextGet This function returns the pointer to next object in the list after the specified object. GFX_GOL_ObjectRectangleRedraw This function marks all objects in the active list intersected by the given rectangular area to be redrawn. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1073 GFX_GOL_ObjectTypeGet This function returns the object type. GFX_GOL_PanelAlphaParameterSet This is function GFX_GOL_PanelAlphaParameterSet. GFX_GOL_PanelBackgroundSet This is function GFX_GOL_PanelBackgroundSet. GFX_GOL_PanelDraw This is function GFX_GOL_PanelDraw. GFX_GOL_PanelGradientParameterSet This is function GFX_GOL_PanelGradientParameterSet. GFX_GOL_PanelParameterSet This is function GFX_GOL_PanelParameterSet. GFX_GOL_TwoTonePanelDraw This is function GFX_GOL_TwoTonePanelDraw. Macros Name Description GFX_GOL_ObjectStateClear This function clears the state bits of the given object. GFX_GOL_ObjectStateGet This function retrieves the current value of the state bits of an object. GFX_GOL_ObjectStateSet This function sets the state bits of the given object. Structures Name Description GFX_GOL_MESSAGE Specifies message structure used in the library. GFX_GOL_OBJ_HEADER Specifies Graphics Object Layer structure used in objects. GOL_PANEL_PARAM Specifies panel parameters. Types Name Description GFX_GOL_DRAW_CALLBACK_FUNC Draw callback function defintion. This application defined function allows the application to perform application specific rendering. GFX_GOL_TRANSLATED_ACTION, \ GFX_GOL_OBJ_HEADER *, \ GFX_GOL_MESSAGE * \ ) Message callback function defintion. This application defined function allows the application to perform application specific processing of user messsages. File Name gfx_gol.h Company Microchip Technology Inc. 5.2.2.8.7 gfx_gol_analog_clock.h Graphics Library Implementation Refer to Microchip Graphics Library for complete documentation of the AnalogClock Object. Functions Name Description GFX_AnalogClockCreate Creates a analog clock object. GFX_GOL_AnalogClockDraw This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. GFX_GOL_AnalogClockHandsDraw Draws the current position of the clock hands with the given thickness and color. GFX_GOL_AnalogClockHourSet Sets the hour value of the analog clock. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1074 GFX_GOL_AnalogClockMinuteSet Sets the minute value of the analog clock. GFX_GOL_AnalogClockSecondSet Sets the second value of the analog clock. Macros Name Description GFX_GOL_ANALOGCLOCK_DISABLED Bit for disabled state. GFX_GOL_ANALOGCLOCK_DRAW Bit to indicate button must be redrawn. GFX_GOL_ANALOGCLOCK_HIDE Bit to indicate button must be removed from screen. GFX_GOL_ANALOGCLOCK_PRESSED Bit for press state. GFX_GOL_ANALOGCLOCK_TICK Bit to tick second hand GFX_GOL_ANALOGCLOCK_UPDATE_HOUR Bit to indicate hour hand must be redrawn GFX_GOL_ANALOGCLOCK_UPDATE_MINUTE Bit to indicate minute hand must be redrawn GFX_GOL_ANALOGCLOCK_UPDATE_SECOND Bit to indicate minute hand must be redrawn Structures Name Description 5.2.2.8.8 gfx_gol_button.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the GFX_GOL_BUTTON Object. Enumerations Name Description GFX_GOL_BUTTON_STATE Object States Definition: Functions Name Description GFX_GOL_ButtonActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_ButtonActionSet This function performs the state change of the object based on the translated action. GFX_GOL_ButtonCreate This function creates a GFX_GOL_BUTTON object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_ButtonDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_ButtonTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_ButtonTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_ButtonTextSet This function sets the address of the current text string used by the object. Macros Name Description GFX_GOL_ButtonPressStateImageGet This function gets the image used when in the pressed state. GFX_GOL_ButtonPressStateImageSet This function sets the image to be used when in the pressed state. GFX_GOL_ButtonReleaseStateImageGet This function gets the image used when in the released state. GFX_GOL_ButtonReleaseStateImageSet This function sets the image to be used when in the released state. GFX_GOL_ButtonTextGet This function returns the address of the current text string used by the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1075 Structures Name Description 5.2.2.8.9 gfx_gol_chart.h • Module for Microchip Graphics Library • GOL Layer • Chart *************************************************************************** • FileName: gfx_chart.h • Dependencies: None • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: MPLAB C30, MPLAB C32 • Linker: MPLAB LINK30, MPLAB LINK32 • Company: Microchip Technology Incorporated * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1076 * • Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • 4/8/08 ... Functions Name Description GFX_GOL_ChartActionGet This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen and keyboard inputs. GFX_GOL_ChartCreate This function creates a CHART object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_ChartDataSeriesAdd This function creates a DATASERIES object and populates the structure with the given parameters. GFX_GOL_ChartDataSeriesFree This function removes DATASERIES object from the list of DATASERIES objects and frees the memory used of that removed object. GFX_GOL_ChartDataSeriesRemove This function removes DATASERIES object from the list of DATASERIES objects and frees the memory used of that removed object. The position of the object to be removed is specified by the number parameter. If the list has only one member, it removes the member regardless of the number given. GFX_GOL_ChartDataSeriesSet This is function GFX_GOL_ChartDataSeriesSet. GFX_GOL_ChartDraw This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. The colors of the bars of the bar chart or sectors of the pie chart can be the default color table or user defined color table set by ChSetColorTable() function. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started.... more GFX_GOL_ChartPercentRangeSet This function sets the minimum and maximum range of percentage that the bar chart will show. The criteria is that min <= max. This affects bar charts only and CH_PERCENTAGE bit state is set. GFX_GOL_ChartSampleRangeSet This function sets the sample start and sample end when drawing the chart. Together with the data series' SHOW_DATA flags the different way of displaying the chart data is achieved. GFX_GOL_ChartValueRangeSet This function sets the minimum and maximum range of values that the bar chart will show. The criteria is that min <= max. Macros Name Description CH_CLR0 Bright Blue CH_CLR1 Bright Red CH_CLR10 Light Blur CH_CLR11 Light Red CH_CLR12 Light Green CH_CLR13 Light Yellow CH_CLR14 Light Orange CH_CLR15 Gold CH_CLR2 Bright Green 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1077 CH_CLR3 Bright Yellow CH_CLR4 Orange CH_CLR5 Blue CH_CLR6 Red CH_CLR7 Green CH_CLR8 Yellow CH_CLR9 Dark Orange CHART_MARGIN Margin from the edges. CHART_YGRIDCOUNT defines the number of grids to be drawn on the y-axis (includes the origin at y). GFX_GOL_CHART_3D_ENABLE Bit to indicate that bar charts are to be drawn with 3-D effect GFX_GOL_CHART_BAR Bit to indicate the chart is type bar. If both PIE and BAR types are set BAR type has higher priority. GFX_GOL_CHART_BAR_HOR These bits (with CH_BAR bit set), sets the bar chart to be drawn horizontally. GFX_GOL_CHART_DISABLED Bit for disabled state. GFX_GOL_CHART_DONUT These bits (with CH_PIE bit set), sets the pie chart to be drawn in a donut shape. GFX_GOL_CHART_DRAW Bit to indicate chart must be redrawn. GFX_GOL_CHART_DRAW_DATA Bit to indicate data portion of the chart must be redrawn. GFX_GOL_CHART_HIDE Bit to indicate chart must be removed from screen. GFX_GOL_CHART_LEGEND Bit to indicate that legend is to be shown. Usable only when seriesCount > 1. GFX_GOL_CHART_NUMERIC This bit is used only for bar charts. If this bit is set, it indicates that the bar chart labels for variables are numeric. If this bit is not set, it indicates that the bar chart labels for variables are alphabets. GFX_GOL_CHART_PERCENT Bit to indicate that the pie chart will be drawn with percentage values shown for the sample data. For bar chart, if CH_VALUE is set, it toggles the value shown to percentage. GFX_GOL_CHART_PIE Bit to indicate the chart is type pie. If both PIE and BAR types are set BAR type has higher priority. GFX_GOL_CHART_VALUE Bit to indicate that the values of the bar chart data or pie chart data are to be shown GFX_GOL_ChartAxisLabelFontGet Macros: GFX_GOL_ChartAxisLabelFontGet(pCh) This macro returns the location of the font used for the X and Y axis labels of the chart. GFX_GOL_ChartAxisLabelFontSet Macros: GFX_GOL_ChartAxisLabelFontSet(pCh, pNewFont) This macro sets the location of the font used for the X and Y axis labels of the chart. GFX_GOL_ChartColorTableGet Macros: GFX_GOL_ChartColorTableGet(pCh) This macro returns the current color table used for the pie and bar charts. GFX_GOL_ChartColorTableSet Macros: GFX_GOL_ChartColorTableSet(pCh, pNewTable) This macro sets the color table used to draw the data in pie and bar charts. GFX_GOL_ChartGridLabelFontGet Macros: GFX_GOL_ChartGridLabelFontGet(pCh) This macro returns the location of the font used for the X and Y axis grid labels of the chart. GFX_GOL_ChartGridLabelFontSet Macros: GFX_GOL_ChartGridLabelFontSet(pCh, pNewFont) This macro sets the location of the font used for the X and Y axis grid labels of the chart. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1078 GFX_GOL_ChartPercentMaxGet Macros: ChGetPercentMax(pCh) This macro returns the current maximum value of the percentage range that will be drawn for bar charts when CH_PERCENTAGE bit state is set. GFX_GOL_ChartPercentMinGet Macros: ChGetPercentMin(pCh) This macro returns the current minimum value of the percentage range that will be drawn for bar charts when CH_PERCENTAGE bit state is set. GFX_GOL_ChartPercentRangeGet This macro gets the percentage range for bar charts. The value returned is calculated from percentage max - min. To get the minimum use ChGetPercentMin() and to get the maximum use ChGetPercentMax(). GFX_GOL_ChartSampleEndGet Macros: GFX_GOL_ChartSampleEndGet(pCh) This macro returns the sampling end value. GFX_GOL_ChartSampleLabelGet Macros: GFX_GOL_ChartSampleLabelGet(pCh) This macro returns the address of the current text string used for the sample axis label of the bar chart. GFX_GOL_ChartSampleLabelSet Macros: GFX_GOL_ChartSampleLabelSet(pCh, pNewXLabel) This macro sets the address of the current text string used for the sample axis label of the bar chart. GFX_GOL_ChartSampleRangeGet This macro gets the sample range for pie or bar charts. The value returned is calculated from smplEnd - smplStart. GFX_GOL_ChartSampleStartGet Macros: GFX_GOL_ChartSampleStartGet(pCh) This macro returns the sampling start value. GFX_GOL_ChartSeriesHide Macros: GFX_GOL_ChartSeriesHide(CHART *pCh, uint16_t seriesNum) This macro sets the specified data series number show flag to be set to HIDE_DATA. GFX_GOL_ChartShowSeriesCountGet Macros: GFX_GOL_ChartShowSeriesCountGet(pCh) This macro shows the number of data series that has its show flag set to SHOW_DATA GFX_GOL_ChartShowSeriesSet Macros: short GFX_GOL_ChartShowSeriesSet(CHART *pCh, uint16_t seriesNum) This macro sets the specified data series number show flag to be set to SHOW_DATA. GFX_GOL_ChartShowSeriesStatusGet Macros: GFX_GOL_ChartShowSeriesStatusGet(pDSeries) This macro returns the show ID status of the DATASERIES. GFX_GOL_ChartTitleFontGet Macros: GFX_GOL_ChartTitleFontGet(pCh) This macro returns the location of the font used for the title of the chart. GFX_GOL_ChartTitleFontSet Macros: GFX_GOL_ChartTitleFontSet(pCh, pNewFont) This macro sets the location of the font used for the title of the chart. GFX_GOL_ChartTitleGet Macros: GFX_GOL_ChartTitleGet(pCh) This macro returns the address of the current text string used for the title of the chart. GFX_GOL_ChartTitleSet Macros: GFX_GOL_ChartTitleSet(pCh, pNewTitle) This macro sets the address of the current text string used for the title of the chart. GFX_GOL_ChartValueLabelGet Macros: GFX_GOL_ChartValueLabelGet(pCh) This macro returns the address of the current text string used for the value axis label of the bar chart. GFX_GOL_ChartValueLabelSet Macros: GFX_GOL_ChartValueLabelSet(pCh, pNewYLabel) This macro sets the address of the current text string used for the value axis label of the bar chart. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1079 GFX_GOL_ChartValueMaxGet Macros: GFX_GOL_ChartValueMaxGet(pCh) This macro returns the current maximum value that will be drawn for bar charts. GFX_GOL_ChartValueMinGet Macros: GFX_GOL_ChartValueMinGet(pCh) This macro returns the current minimum value that will be drawn for bar charts. GFX_GOL_ChartValueRangeGet This macro gets the current range for bar charts. The value returned is calculated from the current (valMax - valMin) set. To get the minimum use ChGetValueMin() and to get the maximum use ChGetValueMax(). HIDE_DATA Macro used to reset the data series show flag or indicate that the data series will be not be shown when the chart is drawn. SHOW_DATA Macro used to set the data series show flag or indicate that the data series will be shown when the chart is drawn. USE_HORZ_ASCENDING_ORDER use ascending order when displaying variables on horizontal mode (bar chart only) USE_PIE_ENABLE_LABEL use labels: A:10%,30 where each sample is labeled A-Z followed by a colon. Structures Name Description CHARTPARAM Defines the parameters for the CHART object. DATASERIES Defines a variable for the CHART object. It specifies the number of samples, pointer to the array of samples for the data series and pointer to the next data series. A member of this structure (show) is used as a flag to determine if the series is to be drawn or not. Together with the smplStart and smplEnd it will determine what kind of chart will be drawn. GFX_GOL_CHART Defines the parameters required for a chart Object. 5.2.2.8.10 gfx_gol_check_box.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the CheckBox Object. Enumerations Name Description 5.2.2.8.11 gfx_gol_custom_control.h Graphics Library Implementation Refer to Microchip Graphics Library for complete documentation of the CustomControl Object. Functions Name Description GFX_GOL_CustomControlActionGet translates the GOL message for the custom control GFX_GOL_CustomControlActionSet changes the state of the object GFX_GOL_CustomControlCreate creates the custom control GFX_GOL_CustomControlDraw draws custom control 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1080 Macros Name Description GFX_GOL_CUSTOMCONTROL_DISABLED disabled GFX_GOL_CUSTOMCONTROL_DRAW whole control must be redrawn GFX_GOL_CUSTOMCONTROL_DRAW_BAR control bar should be redrawn GFX_GOL_CUSTOMCONTROL_HIDE must be removed from screen GFX_GOL_CustomControlGetPos Macros: GFX_GOL_CustomControlGetPos(pCc) returns position GFX_GOL_CustomControlSetPos Macros: GFX_GOL_CustomControlSetPos(pCc,position) sets the current position of the control Structures Name Description GFX_GOL_CUSTOMCONTROL The structure contains data for the control Company Microchip Technology Inc. FileName: gfx_gol_custom_control.c 5.2.2.8.12 gfx_gol_digital_meter.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Digital Meter Object. Enumerations Name Description GFX_GOL_DIGITALMETER_STATE Object States Definition: Functions Name Description GFX_GOL_DigitalMeterActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_DigitalMeterCreate This function creates a GFX_GOL_DIGITALMETER object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_DigitalMeterDecrement This function decrements the meter value by the delta value set. GFX_GOL_DigitalMeterDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_DigitalMeterIncrement This function increments the meter value by the delta value set. GFX_GOL_DigitalMeterValueSet This function sets the value of the meter. Macros Name Description GFX_GOL_DIGITALMETER_INDENT This is a DigitalMeter compile time option to define the indent constant for the text used in the frame. GFX_GOL_DIGITALMETER_WIDTH This is a DigitalMeter compile time option to define the user should change this value depending on the number of digits he wants to display. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1081 GFX_GOL_DigitalMeterTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_DigitalMeterTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_DigitalMeterValueGet This function returns the current value of the digital meter. Structures Name Description GFX_GOL_DIGITALMETER Properties for a digital meter. File Name gfx_gol_digital_meter.h Company Microchip Technology Inc. 5.2.2.8.13 gfx_gol_edit_box.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Edit Box Object. Enumerations Name Description GFX_GOL_EDITBOX_STATE Object States Definition: Functions Name Description GFX_GOL_EditBoxActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_EditBoxActionSet This function performs the state change of the object based on the translated action. GFX_GOL_EditBoxCharAdd This function adds a character at the end of the text used by the object. GFX_GOL_EditBoxCharRemove This function removes a character at the end of the text used by the object. GFX_GOL_EditBoxCreate This function creates a GFX_GOL_EDITBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_EditBoxDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_EditBoxTextSet This function sets the text in the object. Macros Name Description GFX_GOL_EditBoxTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_EditBoxTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_EditBoxTextGet This function returns the address of the current text string used by the object. Structures Name Description GFX_GOL_EDITBOX Defines the parameters required for a Edit Box Object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1082 File Name gfx_gol_edit_box.h Company Microchip Technology Inc. 5.2.2.8.14 gfx_gol_font_default.h AUTO-GENERATED CODE: Graphics Resource Converter version: 4.00.39 BETA This file is generated by the Graphics Resource Converter containing resources such as images and fonts that can be used by Microchip's Graphics Library, which is part of the MLA. Macros Name Description GFX_GOL_FONT_DEFAULT_H_FILE File Name gfx_gol_font_default.h Company Microchip Technology, Inc. 5.2.2.8.15 gfx_gol_grid.h • Module for Microchip Graphics Library • Grid control *************************************************************************** • FileName: gfx_grid.h • Dependencies: none • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: MPLAB C30, MPLAB C32 • Linker: MPLAB LINK30, MPLAB LINK32 • Company: Microchip Technology Incorporated * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1083 • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • 02/29/08 ... • 04/16/10 Added Grid Item as text. Functions Name Description GridClearCellState This function clears the state of the cell (or Grid Item) specified by the column and row. GridCreate This function creates a GRID object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GridDraw This function renders the object on the screen using the current parameter settings. Location of the object is determined by the left, top, right and bottom parameters. The colors used are dependent on the state of the object. The font used is determined by the style scheme set. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. GridFreeItems This function removes all grid items for the given Grid and frees the memory used. GridGetCell This function removes all grid items for the given Grid and frees the memory used. GridMsgDefault This function performs the actual state change based on the translated message given. The following state changes are supported: GridSetCell This function sets the Grid Item state and data. GridSetCellState This function sets the state of the Grid Item or cell. GridSetFocus This function sets the focus of the specified Grid Item or cell. GridTranslateMsg This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen and keyboard inputs. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1084 Macros Name Description GRID_DISABLED Bit for disabled state GRID_DRAW_ALL Bit to indicate whole edit box must be redrawn GRID_DRAW_ITEMS Bit to indicate that at least one item must be redrawn, but not the entire grid. GRID_FOCUSED Bit for focused state GRID_HEIGHT This is macro GRID_HEIGHT. GRID_HIDE Bit to remove object from screen GRID_MAX_COLUMNS This is macro GRID_MAX_COLUMNS. GRID_MAX_ROWS This is macro GRID_MAX_ROWS. GRID_OUT_OF_BOUNDS Status of an out of bounds cell GridSetCell() operation. GRID_SHOW_BORDER_ONLY Draw only the outside border of the grid. GRID_SHOW_FOCUS Highlight the focused cell. GRID_SHOW_LINES Display grid lines GRID_SHOW_SEPARATORS_ONLY Draw only the lines between cells (like Tic-tac-toe) GRID_SUCCESS Status of a successful GridSetCell() operation. GRID_TYPE_MASK This is macro GRID_TYPE_MASK. GRID_WIDTH This is macro GRID_WIDTH. GridGetFocusX Macros: GridGetFocusX(pGrid) This macro returns the x position of the focused cell. GridGetFocusY Macros: GridGetFocusY(pGrid) This macro returns the y position of the focused cell. GRIDITEM_DRAW Draw this cell GRIDITEM_IS_BITMAP The grid item is a bitmap. GRIDITEM_IS_TEXT The grid item is a text string. GRIDITEM_SELECTED The cell is selected. GRIDITEM_TEXTBOTTOM Bit to indicate text is top aligned. GRIDITEM_TEXTLEFT Text in the cell is left aligned. GRIDITEM_TEXTRIGHT Text in the cell is right aligned. GRIDITEM_TEXTTOP Bit to indicate text is bottom aligned. Structures Name Description GRID Defines the parameters required for a grid Object. Clipping is not supported in grid object. GRIDITEM Defines the grid item. 5.2.2.8.16 gfx_gol_group_box.h Graphics Library Implementation Refer to Microchip Graphics Library for complete documentation of the Group Box Object. Enumerations Name Description GFX_GOL_GROUPBOX_STATE Object States Definition: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1085 Functions Name Description GFX_GOL_GroupboxActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_GroupboxCreate This function creates a GFX_GOL_GROUPBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_GroupboxDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_GroupboxTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_GroupboxTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_GroupboxTextSet This function sets the address of the current text string used by the object. Macros Name Description GFX_GOL_GroupboxTextGet This function returns the address of the current text string used by the object. Structures Name Description GFX_GOL_GROUPBOX Defines the parameters required for a group box Object. The textwidth and textHeight is not checked with the actual dimension of the object. Clipping is not supported in group box object. It is possible for the text to exceed the dimension of the Object. Company Microchip Technology Inc. FileName: gfx_gol_group_box.h 5.2.2.8.17 gfx_gol_list_box.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the ListBox Object. Enumerations Name Description GFX_GOL_LISTBOX_ITEM_STATUS Bit definitions for the status of an item GFX_GOL_LISTBOX_STATE This is type GFX_GOL_LISTBOX_STATE. Functions Name Description GFX_GOL_ListBoxActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_ListBoxActionSet This function performs the state change of the object based on the translated action. GFX_GOL_ListBoxCreate This function creates a GFX_GOL_LISTBOX object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1086 GFX_GOL_ListBoxDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_ListBoxItemAdd This function adds an item to the list box. GFX_GOL_ListBoxItemFocusGet This function returns the index of the focused item in the list box. GFX_GOL_ListBoxItemFocusSet This function sets the focus of the item with the index number specified by index. GFX_GOL_ListBoxItemListRemove This function removes the entire items list of the list box and free the memory used. GFX_GOL_ListBoxItemRemove This function removes an item from the list box and free the memory used. GFX_GOL_ListBoxSelectionChange This function changes the selection status of the given item in the list box. GFX_GOL_ListBoxSelectionGet This function searches for selected items from the list box. GFX_GOL_ListBoxVisibleItemCountGet This function returns the count of items visible in the list box. Macros Name Description GFX_GOL_ListBoxItemCountGet This function returns the count of items in the list box. GFX_GOL_ListBoxItemImageGet This function gets the image set for a list box item. GFX_GOL_ListBoxItemImageSet This function sets the image for a list box item. GFX_GOL_ListBoxItemListGet This function returns the pointer to the item list of the list box. GFX_GOL_ListBoxItemSelectStatusClear This function clears the selection status of the item. GFX_GOL_ListBoxItemSelectStatusSet This function sets the selection status of the item to selected. GFX_GOL_ListBoxTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_ListBoxTextAlignmentSet This function sets the text alignment of the text string used by the object. Structures Name Description GFX_GOL_LISTBOX Defines the parameters required for a list box Object. GFX_GOL_LISTITEM Defines the parameters required for a list item used in list box. File Name gfx_gol_list_box.h Company Microchip Technology Inc. 5.2.2.8.18 gfx_gol_meter.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Meter Object. Enumerations Name Description 5.2.2.8.19 gfx_gol_picture.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Picture Object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1087 Enumerations Name Description GFX_GOL_PICTURECONTROLCONTROL_STATE Object States Definition: Functions Name Description GFX_GOL_PictureControlActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_PictureControlCreate This function creates a GFX_GOL_PICTURECONTROL object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_PictureControlDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_PictureControlPartialSet This function sets the partial image parameters to be in the object. Macros Name Description GFX_GOL_PictureControlImageGet This function gets the image used when in the pressed state. GFX_GOL_PictureControlImageSet This function sets the image to be in the object. GFX_GOL_PictureControlScaleSet Sets the scale factor used to render the bitmap used in the object. Structures Name Description GFX_GOL_PICTURECONTROL The structure contains data for picture control File Name gfx_gol_picture.h Company Microchip Technology Inc. 5.2.2.8.20 gfx_gol_progress_bar.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the ProgressBar Object. Enumerations Name Description GFX_GOL_PROGRESSBAR_STATE Object States Definition: Functions Name Description GFX_GOL_ProgressBarActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_ProgressBarCreate This function creates a GFX_GOL_PROGRESSBAR object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_ProgressBarDraw This function renders the object on the screen based on the current state of the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1088 GFX_GOL_ProgressBarPositionSet This function sets the position of the progress bar. GFX_GOL_ProgressBarRangeSet This function sets the range of the progress bar. Macros Name Description GFX_GOL_ProgressBarPositionGet This function returns the current position of the progress bar. GFX_GOL_ProgressBarRangeGet This function returns the range of the progress bar. Structures Name Description GFX_GOL_PROGRESSBAR The structure contains data for the progress bar File Name gfx_gol_progress_bar.h Company Microchip Technology Inc. 5.2.2.8.21 gfx_gol_radio_button.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the RadioButton Object. Enumerations Name Description GFX_GOL_RADIOBUTTON_STATE Object States Definition: Functions Name Description GFX_GOL_RadioButtonActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_RadioButtonActionSet This function performs the state change of the object based on the translated action. GFX_GOL_RadioButtonCheckGet This function returns the ID of the currently checked radio button in the group. GFX_GOL_RadioButtonCheckSet This function sets the ID of the currently checked radio button in the group. GFX_GOL_RadioButtonCreate This function creates a GFX_GOL_RADIOBUTTON object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_RadioButtonDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_RadioButtonTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_RadioButtonTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_RadioButtonTextSet This function sets the address of the current text string used by the object. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1089 Macros Name Description GFX_GOL_RadioButtonTextGet This function returns the address of the current text string used by the object. Structures Name Description GFX_GOL_RADIOBUTTON the structure contains data for the Radio Button File Name gfx_gol_radio_button.h Company Microchip Technology Inc. 5.2.2.8.22 gfx_gol_round_dial.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Round dial Object. Functions Name Description GFX_GOL_RoundDailActionGet This function evaluates the message from a user if the message will affect the object or not. The table below enumerates the translated messages for each event of the touch screen inputs. GFX_GOL_RoundDailActionSet This function performs the actual state change based on the translated message given. The following state changes are supported: GFX_GOL_RoundDialCreate This function creates a ROUNDDIAL object with the parameters given. GFX_GOL_RoundDialDraw This function renders the object on the screen using the current parameter settings. Location of the object is determined by the center (x,y) postion and the radius parameters. The colors used are dependent on the state of the object. When rendering objects of the same type, each object must be rendered completely before the rendering of the next object is started. This is to avoid incomplete object rendering. RdiaCosine This is function RdiaCosine. RdiaSine This is function RdiaSine. Macros Name Description GFX_GOL_ROUNDDIAL_DISABLED Bit for disabled state. GFX_GOL_ROUNDDIAL_DRAW Bit to indicate object must be redrawn. GFX_GOL_ROUNDDIAL_HIDE Bit to indicate object must be removed from screen. GFX_GOL_ROUNDDIAL_MAX_POSITIONS This is macro GFX_GOL_ROUNDDIAL_MAX_POSITIONS. GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS This is macro GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS. GFX_GOL_ROUNDDIAL_ROT_CCW Bit for rotate counter clockwise state. GFX_GOL_ROUNDDIAL_ROT_CW Bit for rotate clockwise state. GFX_GOL_RoundDialValueDecrement Used to directly decrement the value. The delta change used is the resolution setting (res). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1090 GFX_GOL_RoundDialValueGet Returns the current dial value. Value is always in the 0-max range inclusive. GFX_GOL_RoundDialValueIncrement Used to directly increment the value. The delta change used is the resolution setting (res). GFX_GOL_RoundDialValueSet Sets the value to the given new value. Value set must be in 0-max range inclusive. Structures Name Description GFX_GOL_ROUNDDIAL Defines the parameters required for a dial Object. Company Microchip Technology Inc. FileName: gfx_gol_round_dial.h 5.2.2.8.23 gfx_gol_scan_codes.h Module for Microchip Graphics Library - Graphic Object Layer This header file contains scan codes for the standard AT keyboard that can be used to process user action in GOL messages. Macros Name Description SCAN_BS_PRESSED Back space key pressed. SCAN_BS_RELEASED Back space key released. SCAN_CR_PRESSED Carriage return pressed. SCAN_CR_RELEASED Carriage return released. SCAN_CRA_PRESSED Carriage return alternate pressed. SCAN_CRA_RELEASED Carriage return alternate released. SCAN_DEL_PRESSED Delete key pressed. SCAN_DEL_RELEASED Delete key released. SCAN_DOWN_PRESSED Down key pressed. SCAN_DOWN_RELEASED Down key released. SCAN_END_PRESSED End key pressed. SCAN_END_RELEASED End key released. SCAN_HOME_PRESSED Home key pressed. SCAN_HOME_RELEASED Home key released. SCAN_LEFT_PRESSED Left key pressed. SCAN_LEFT_RELEASED Left key released. SCAN_PGDOWN_PRESSED Page down key pressed. SCAN_PGDOWN_RELEASED Page down key released. SCAN_PGUP_PRESSED Page up key pressed. SCAN_PGUP_RELEASED Page up key released. SCAN_RIGHT_PRESSED Right key pressed. SCAN_RIGHT_RELEASED Right key released. SCAN_SPACE_PRESSED Space key pressed. SCAN_SPACE_RELEASED Space key released. SCAN_TAB_PRESSED Tab key pressed. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1091 SCAN_TAB_RELEASED Tab key released. SCAN_UP_PRESSED Up key pressed. SCAN_UP_RELEASED Up key released. File Name gfx_gol_scan_codes.h Company Microchip Technology Inc. 5.2.2.8.24 gfx_gol_scheme.h Module for Microchip Graphics Library - Graphic Object Layer Scheme This module implements the common routines for the Graphics Object Layer of the Microchip Graphics Library. The routines are independent of the Display Driver Layer and should be compatible with any Display Driver that is compliant with the requirements of the Display Driver Layer of the Graphics Library. The module utilizes the Graphics Primitive Layer to render the objects. Functions Name Description GFX_GOL_SchemeAlphaPrecentSet This is function GFX_GOL_SchemeAlphaPrecentSet. GFX_GOL_SchemeBackgroundColorGet This is function GFX_GOL_SchemeBackgroundColorGet. GFX_GOL_SchemeBackgroundColorSet This is function GFX_GOL_SchemeBackgroundColorSet. GFX_GOL_SchemeBackgroundImageSet This is function GFX_GOL_SchemeBackgroundImageSet. GFX_GOL_SchemeBackgroundTypeGet This is function GFX_GOL_SchemeBackgroundTypeGet. GFX_GOL_SchemeBackgroundTypeSet This is function GFX_GOL_SchemeBackgroundTypeSet. GFX_GOL_SchemeColor0Get This is function GFX_GOL_SchemeColor0Get. GFX_GOL_SchemeColor0Set This is function GFX_GOL_SchemeColor0Set. GFX_GOL_SchemeColor1Get This is function GFX_GOL_SchemeColor1Get. GFX_GOL_SchemeColor1Set This is function GFX_GOL_SchemeColor1Set. GFX_GOL_SchemeColorDisabledGet This is function GFX_GOL_SchemeColorDisabledGet. GFX_GOL_SchemeColorDisabledSet This is function GFX_GOL_SchemeColorDisabledSet. GFX_GOL_SchemeColorSet This is function GFX_GOL_SchemeColorSet. GFX_GOL_SchemeEmbossDarkColorGet This is function GFX_GOL_SchemeEmbossDarkColorGet. GFX_GOL_SchemeEmbossDarkColorSet This is function GFX_GOL_SchemeEmbossDarkColorSet. GFX_GOL_SchemeEmbossLightColorGet This is function GFX_GOL_SchemeEmbossLightColorGet. GFX_GOL_SchemeEmbossLightColorSet This is function GFX_GOL_SchemeEmbossLightColorSet. GFX_GOL_SchemeEmbossSet This is function GFX_GOL_SchemeEmbossSet. GFX_GOL_SchemeEmbossSizeGet This is function GFX_GOL_SchemeEmbossSizeGet. GFX_GOL_SchemeEmbossSizeSet This is function GFX_GOL_SchemeEmbossSizeSet. GFX_GOL_SchemeFillStyleGet This is function GFX_GOL_SchemeFillStyleGet. GFX_GOL_SchemeFillStyleSet This is function GFX_GOL_SchemeFillStyleSet. GFX_GOL_SchemeFontGet This is function GFX_GOL_SchemeFontGet. GFX_GOL_SchemeFontSet This is function GFX_GOL_SchemeFontSet. GFX_GOL_SchemeGradientColorSet This is function GFX_GOL_SchemeGradientColorSet. GFX_GOL_SchemeGradientEndColorGet This is function GFX_GOL_SchemeGradientEndColorGet. GFX_GOL_SchemeGradientEndColorSet This is function GFX_GOL_SchemeGradientEndColorSet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1092 GFX_GOL_SchemeGradientStartColorGet This is function GFX_GOL_SchemeGradientStartColorGet. GFX_GOL_SchemeGradientStartColorSet This is function GFX_GOL_SchemeGradientStartColorSet. GFX_GOL_SchemeTextColor0Get This is function GFX_GOL_SchemeTextColor0Get. GFX_GOL_SchemeTextColor0Set This is function GFX_GOL_SchemeTextColor0Set. GFX_GOL_SchemeTextColor1Get This is function GFX_GOL_SchemeTextColor1Get. GFX_GOL_SchemeTextColor1Set This is function GFX_GOL_SchemeTextColor1Set. GFX_GOL_SchemeTextColorDisableGet This is function GFX_GOL_SchemeTextColorDisableGet. GFX_GOL_SchemeTextColorDisableSet This is function GFX_GOL_SchemeTextColorDisableSet. GFX_GOL_SchemeTextColorSet This is function GFX_GOL_SchemeTextColorSet. Structures Name Description GFX_GOL_OBJ_SCHEME This structure specifies the style scheme components of an object. File Name gfx_gol_scheme.h Company Microchip Technology Inc. 5.2.2.8.25 gfx_gol_scroll_bar.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Slider Object. Enumerations Name Description GFX_GOL_SCROLLBAR_STATE Object States Definition: Functions Name Description GFX_GOL_ScrollBarActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_ScrollBarActionSet This function performs the state change of the object based on the translated action. GFX_GOL_ScrollBarCreate This function creates a GFX_GOL_SCROLLBAR object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_ScrollBarDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_ScrollBarPageGet This function returns the page size of the object. GFX_GOL_ScrollBarPageSet This function sets the page size of the object. GFX_GOL_ScrollBarPositionDecrement This function decrements the scroll bar position by the delta change (page) value set. GFX_GOL_ScrollBarPositionGet This function returns the current position of the scroll bar thumb. GFX_GOL_ScrollBarPositionIncrement This function increments the scroll bar position by the delta change (page) value set. GFX_GOL_ScrollBarPositionSet This function sets the position of the scroll bar thumb. GFX_GOL_ScrollBarRangeGet This function returns the range of the thumb of the scroll bar. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1093 GFX_GOL_ScrollBarRangeSet This function sets the range of the thumb of the scroll bar. Structures Name Description GFX_GOL_SCROLLBAR Defines the parameters required for a slider/scrollbar Object. Depending on the GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE state bit slider or scrollbar mode is set. If GFX_GOL_SCROLLBAR_SLIDER_MODE_STATE is set, mode is slider; if not set mode is scroll bar. For scrollbar mode, focus rectangle is not drawn. File Name gfx_gol_scroll_bar.h Company Microchip Technology Inc. 5.2.2.8.26 gfx_gol_static_text.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Static Text Object. Enumerations Name Description GFX_GOL_STATICTEXT_STATE Object States Definition: Functions Name Description GFX_GOL_StaticTextActionGet This function sets the text alignment of the text string used by the object. GFX_GOL_StaticTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_StaticTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_StaticTextCreate This function creates a GFX_GOL_STATICTEXT object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_StaticTextDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_StaticTextGet This function returns the address of the current text string used by the object. GFX_GOL_StaticTextSet This function sets the address of the current text string used by the object. Structures Name Description GFX_GOL_STATICTEXT Defines the parameters required for a Static Text Object. File Name gfx_gol_static_text.h Company Microchip Technology Inc. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1094 5.2.2.8.27 gfx_gol_text_entry.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Text Entry Object. Enumerations Name Description GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE Optional COMMANDS assigned to keys GFX_GOL_TEXTENTRY_STATE Object States Definition: Functions Name Description GFX_GOL_TextEntryActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_TextEntryActionSet This function performs the state change of the object based on the translated action. GFX_GOL_TextEntryBufferClear This function will clear the data in the display. GFX_GOL_TextEntryBufferGet This function returns the buffer used to display text. GFX_GOL_TextEntryBufferSet This function sets the buffer used to display text. GFX_GOL_TextEntryCharAdd This function will insert a character to the end of the buffer. GFX_GOL_TextEntryCreate This function creates a GFX_GOL_TEXTENTRY object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_TextEntryDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_TextEntryKeyCommandGet This function will return the currently assigned command to the key with the given index. GFX_GOL_TextEntryKeyCommandSet This function will assign a command to a key with the given index. GFX_GOL_TextEntryKeyIsPressed This function will test if a key given by its index in the object is pressed. GFX_GOL_TextEntryKeyListCreate This function will create the list of KEYMEMBERS that holds the information on each key. GFX_GOL_TextEntryKeyMemberListDelete This function will delete the KEYMEMBER list assigned to the object. GFX_GOL_TextEntryKeyTextSet This function will set the text assigned to a key with the given index. GFX_GOL_TextEntryLastCharDelete This function will remove the last character of the buffer and replace it with a string terminator. GFX_GOL_TextEntrySpaceCharAdd This function will insert a space character to the end of the buffer. Macros Name Description TE_ROUNDEDBUTTON_RADIUS Optional settigns Set this parameter in the GraphicsConfig.h Structures Name Description GFX_GOL_TEXTENTRY Defines the parameters required for a TextEntry Object. KEYMEMBER Defines the parameters and the strings assigned for each key. File Name gfx_gol_text_entry.h 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1095 Company Microchip Technology Inc. 5.2.2.8.28 gfx_gol_window.h Module for Microchip Graphics Library - Graphic Object Layer Refer to Microchip Graphics Library for complete documentation of the Window Object. Enumerations Name Description GFX_GOL_WINDOW_STATE Object States Definition: Functions Name Description GFX_GOL_WindowActionGet This function evaluates the message from a user if the message will affect the object or not. GFX_GOL_WindowCreate This function creates a GFX_GOL_WINDOW object with the parameters given. It automatically attaches the new object into a global linked list of objects and returns the address of the object. GFX_GOL_WindowDraw This function renders the object on the screen based on the current state of the object. GFX_GOL_WindowTextAlignmentGet This function returns the text alignment of the text string used by the object. GFX_GOL_WindowTextAlignmentSet This function sets the text alignment of the text string used by the object. GFX_GOL_WindowTextSet This function sets the address of the current text string used by the object. Macros Name Description GFX_GOL_WindowImageGet This function gets the image used. GFX_GOL_WindowTextGet This function returns the address of the current text string used by the object. Structures Name Description GFX_GOL_WINDOW The structure contains data for the window Company Microchip Technology Inc. FileName: gfx_gol_window.h 5.2.2.8.29 gfx_imageDecoder.h This is file gfx_imageDecoder.h. Functions Name Description ImageDecoderInit This function initializes the global variables to 0 and then initializes the driver. This must be called once before any other function of the library is called ImageDecodeTask This function completes one small part of the image decode function 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1096 ImageLoopCallbackRegister This function registers the loop callback function so that the decoder calls this function in every decoding loop. This can be used by the application program to do maintainance activities such as fetching data, updating the display, etc... IMG_vSetboundaries Macros Name Description ImageAbort This function sets the Image Decoder's Abort flag so that decoding aborts in the next decoding loop. ImageFullScreenDecode This function decodes and displays the image on the screen in fullscreen mode with center aligned and downscaled if required IMG_ALIGN_CENTER Flags IMG_DECODE_ABORTED This is macro IMG_DECODE_ABORTED. IMG_DOWN_SCALE This is macro IMG_DOWN_SCALE. IMG_FCLOSE This is macro IMG_FCLOSE. IMG_FEOF This is macro IMG_FEOF. IMG_FILE This is macro IMG_FILE. IMG_FOPEN added by Paolo 9/10/08 for MultiApp Demo IMG_FREAD This is macro IMG_FREAD. IMG_FSEEK This is macro IMG_FSEEK. IMG_FTELL This is macro IMG_FTELL. IMG_SCREEN_HEIGHT This is macro IMG_SCREEN_HEIGHT. IMG_SCREEN_WIDTH The individual image decoders use these defines instead of directly using those provided in the Display driver file IMG_vCheckAndAbort This is macro IMG_vCheckAndAbort. IMG_vLoopCallback This is macro IMG_vLoopCallback. IMG_vPutPixel This is macro IMG_vPutPixel. IMG_vSetColor This is macro IMG_vSetColor. Types Name Description FileFeof This is type FileFeof. FileRead Typedefs of the used File System APIs FileSeek This is type FileSeek. FileTell This is type FileTell. IMG_FILE_FORMAT IMG_ImageFileFormat specifies all the supported image file formats IMG_FILE_SYSTEM_API IMG_FileSystemAPI holds function pointers to the used File System APIs IMG_LOOP_CALLBACK IMG_LoopCallback is a callback function which is called in every loop of the decoding cycle so that user application can do some maintainance activities IMG_PIXEL_OUTPUT IMG_PixelOutput is a callback function which receives the color information of the output pixel IMG_PIXEL_XY_RGB_888 IMG_PixelRgb holds the RGB information of a pixel in BYTES Variables Name Description IMG_bAlignCenter This is variable IMG_bAlignCenter. IMG_bDownScalingFactor This is variable IMG_bDownScalingFactor. IMG_blAbortImageDecoding The global variables which define the image position and size 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1097 IMG_pCurrentFile This is variable IMG_pCurrentFile. IMG_pFileAPIs This is variable IMG_pFileAPIs. IMG_PixelXYColor This is variable IMG_PixelXYColor. IMG_pLoopCallbackFn This is variable IMG_pLoopCallbackFn. IMG_pPixelOutput This is variable IMG_pPixelOutput. IMG_wHeight This is variable IMG_wHeight. IMG_wImageHeight This is variable IMG_wImageHeight. IMG_wImageWidth This is variable IMG_wImageWidth. IMG_wStartX This is variable IMG_wStartX. IMG_wStartY This is variable IMG_wStartY. IMG_wWidth This is variable IMG_wWidth. 5.2.2.8.30 gfx_palette.h • Module for Microchip Graphics Library • Palette Support *************************************************************************** • FileName: gfx_palette.h • Dependencies: Graphics.h • Processor: PIC24, PIC32 • Compiler: MPLAB C30, MPLAB C32 • Linker: MPLAB LINK30, MPLAB LINK32 • Company: Microchip Technology Incorporated * • Software License Agreement * • Copyright © 2008 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1098 • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • 11/06/09 Initial Release • 08/20/10 Modified PALETTE_EXTERNAL to be of type GFX_EXTDATA. • 03/20/12 Modified PALETTE_ENTRY structure to have packed attribute. Functions Name Description ClearPaletteChangeError Clears the Palette change error status DisablePalette Disables the Palette mode. EnablePalette Enables the Palette mode. GetPaletteChangeError Returns the Palette change error status IsPaletteEnabled Returns if the Palette mode is enabled or not. PaletteInit Initializes the color look up table (CLUT). RequestPaletteChange Loads the palettes from the flash during vertical blanking period if possible, otherwise loads immediately. SetPalette Programs a block of palette entries starting from startEntry and until startEntry + length from the flash immediately. SetPaletteBpp Sets the color look up table (CLUT) number of valid entries. SetPaletteFlash Loads the palettes from the flash immediately. Macros Name Description RequestEntirePaletteChange Macro: RequestEntirePaletteChange(pPalette) Loads all the palette entries from the flash during vertical blanking period if possible, otherwise loads immediately. SetEntirePalette Macro: SetEntirePalette(pPalette) Programs the whole 256 entry palette with new color values from flash. Structures Name Description PALETTE_FLASH Structure for the palette stored in FLASH memory. PALETTE_HEADER Structure for the palette header. Types Name Description PALETTE_EXTERNAL Structure for palette stored in EXTERNAL memory space. (example: External SPI or parallel Flash, EDS_EPMP) 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1099 Unions Name Description 5.2.2.8.31 gfx_primitive.h Module for Microchip Graphics Library - Graphic Primitive Layer This module implements the primitive rendering routines of the Microchip Graphics Library. The routines are independent of the Display Driver Layer and should be compatible with any Display Driver that is compliant with the requirements of the Display Driver Layer of the Graphics Library. Enumerations Name Description GFX_TRIG_FUNCTION_TYPE DOM-IGNORE-START Functions Name Description DrawArc This renders an arc with from startAngle to endAngle with the thickness of r2-r1. The function returns 1 when the arc is rendered successfuly and returns a 0 when it is not yet finished. The next call to the function will continue the rendering. GFX_AlphaBlendingValueGet This function returns the current alpha value set for alpha blending rendering. GFX_AlphaBlendingValueSet This function sets the alpha value for alpha blending rendering. GFX_BackgroundColorGet This function returns the color used in the current background. GFX_BackgroundImageGet This function returns the image used in the current background. GFX_BackgroundImageLeftGet This function returns the horizontal starting position of the current background. GFX_BackgroundImageTopGet This function returns the vertical starting position of the current background. GFX_BackgroundSet This function sets the background information. GFX_BackgroundTypeGet This function returns the type of the current background. GFX_BackgroundTypeSet This function sets the background type. GFX_BarAlphaDraw This function renders a alpha blended bar shape using the currently set fill style and color. GFX_BarDraw This function renders a bar shape using the currently set fill style and color. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1100 GFX_BarGradientDraw This renders a bar onto the screen, but instead of one color, a gradient is drawn depending on the direction (GFX_GRADIENT_TYPE), length, and colors chosen. This function is a blocking call. GFX_BevelDraw This is function GFX_BevelDraw. GFX_BevelDrawTypeGet GFX_BevelDrawTypeSet GFX_BevelGradientDraw This renders a filled bevel with gradient color on the fill. It works the same as the fillbevel function, except a gradient out of color1 and color2 is drawn depending on the direction (GFX_GRADIENT_TYPE). This function is a blocking call. GFX_CircleDraw This function renders a circular shape using the currently set line style and color. GFX_CircleFillDraw This function renders a filled circle shape using the currently set fill style and colors. GFX_ColorGet This function returns the color currently set to render primitive shapes and text. GFX_ColorSet This function sets the color to be used in rendering primitive shapes and text. GFX_DoubleBufferAreaGet GFX_DoubleBufferAreaMark GFX_DoubleBufferDisable GFX_DoubleBufferEnable GFX_DoubleBufferStatusGet 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1101 GFX_DoubleBufferSyncAllStatusClear GFX_DoubleBufferSyncAllStatusGet GFX_DoubleBufferSyncAllStatusSet GFX_DoubleBufferSyncAreaCountGet GFX_DoubleBufferSyncAreaCountSet GFX_DoubleBufferSynchronize GFX_DoubleBufferSynchronizeCancel GFX_DoubleBufferSynchronizeRequest GFX_DoubleBufferSynchronizeSet GFX_DoubleBufferSynchronizeStatusGet GFX_DrawBufferGet GFX_DrawBufferSelect GFX_DrawBufferSet GFX_DRV_FontSet This is function GFX_DRV_FontSet. GFX_DRV_TextStringWidthGet This is function GFX_DRV_TextStringWidthGet. GFX_ExternalCharInfoGet This is function GFX_ExternalCharInfoGet. GFX_ExternalResourceCallback This function must be implemented in the application. The library will call this function each time when the external memory data will be required. The application must copy requested uint8_ts quantity into the buffer provided. Data start address in external memory is a sum of the address in GFX_EXTDATA structure and offset. GFX_FillStyleGet Return the fill style used when rendering filled shapes. GFX_FillStyleSet Set the fill style to be used when rendering filled shapes. GFX_FlashCharInfoGet This is function GFX_FlashCharInfoGet. GFX_FontAntiAliasGet This function returns the current font font anti-aliasing mode. GFX_FontAntiAliasSet This function sets the font anti-aliasing mode. GFX_FontGet This function returns the current font used when rendering strings and characters. GFX_FontSet This function sets the current font used when rendering strings and characters. GFX_FrameBufferGet GFX_FrameBufferSelect GFX_GradientColorSet Sets the gradient fill start and end color. GFX_GradientEndColorGet Return the gradient end color when rendering gradient filled shapes. GFX_GradientStartColorGet Return the gradient start color when rendering gradient filled shapes. GFX_ImageDraw This function renders an image to the frame buffer. GFX_ImageHeaderGet This function fills the given bitmap header with the image's header information. GFX_ImageHeightGet This function returns the height of the given image. GFX_ImageOffsetAddressGet This is function GFX_ImageOffsetAddressGet. GFX_ImagePartialDraw This function renders a portion of an image to the frame buffer. GFX_ImageWidthGet This function returns the width of the given image. GFX_Initialize Initialize the Graphics Library. GFX_LineDraw This function renders a line from x1,y1 to x2,y2 using the currently set line style (see GFX_LineStyleSet()). GFX_LinePositionRelativeSet This function sets the line cursor to a new position relative to the current position. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1102 GFX_LinePositionSet This function sets the line cursor to a new position. GFX_LinePositionXGet This function returns the current x position of the line cursor. GFX_LinePositionYGet This function returns the current y position of the line cursor. GFX_LineStyleGet Return the line style used when rendering lines. GFX_LineStyleSet Set the line style to be used when rendering lines. GFX_LineToDraw This function renders a line from current line cursor position (x,y) to (x2,y2) using the currently set line style (see GFX_LineStyleSet()). GFX_LineToRelativeDraw This function renders a line from current line cursor position (x,y) to (x+dX,y+dY) using the currently set line style (see GFX_LineStyleSet()). GFX_PolygonDraw This function renders a polygon using the currently set line style (see GFX_LineStyleSet()) and color (see GFX_ColorSet()). GFX_Primitive_Initialize This is function GFX_Primitive_Initialize. GFX_RectangleDraw This function renders a rectangular shape using the currently set line style and color. GFX_RectangleFillDraw This function renders a filled rectangular shape using the currently set fill style and colors. GFX_RectangleRoundDraw This function renders a rounded corner rectangular shape using the currently set line style and color. GFX_RectangleRoundFillDraw This function renders a filled rectangular shape with round corners using the currently set fill style and colors. GFX_RenderingBufferGet This function is an internal function and should not be called by the application. GFX_RenderToDisplayBufferDisable This is function GFX_RenderToDisplayBufferDisable. GFX_RenderToDisplayBufferDisableFlagGet This is function GFX_RenderToDisplayBufferDisableFlagGet. GFX_RenderToDisplayBufferEnable This is function GFX_RenderToDisplayBufferEnable. GFX_ScreenClear Clears the screen to the currently set color (GFX_ColorSet()). GFX_SineCosineGet This is function GFX_SineCosineGet. GFX_SolidLineDraw This is function GFX_SolidLineDraw. GFX_StyledLineDraw This is function GFX_StyledLineDraw. GFX_TextAreaBottomGet This is function GFX_TextAreaBottomGet. GFX_TextAreaBottomSet This is function GFX_TextAreaBottomSet. GFX_TextAreaLeftGet This is function GFX_TextAreaLeftGet. GFX_TextAreaLeftSet This is function GFX_TextAreaLeftSet. GFX_TextAreaRightGet This is function GFX_TextAreaRightGet. GFX_TextAreaRightSet This is function GFX_TextAreaRightSet. GFX_TextAreaTopGet This is function GFX_TextAreaTopGet. GFX_TextAreaTopSet This is function GFX_TextAreaTopSet. GFX_TextCharDraw This function renders the given character using the currently set color using the currently set font. GFX_TextCursorPositionSet This function sets the text cursor to a new position. GFX_TextCursorPositionXGet This function returns the current x position of the text cursor. GFX_TextCursorPositionYGet This function returns the current y position of the text cursor. GFX_TextStringBoxDraw This function renders the given string using the currently set color and font into a rectangular area. GFX_TextStringDraw This function renders the given string of character using the currently set color using the currently set font. GFX_TextStringHeightGet This function returns the height of the given font. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1103 GFX_TextStringWidthGet This function returns the width of the given string using the given font. GFX_ThickBevelDraw This is function GFX_ThickBevelDraw. GFX_TransparentColorDisable This function disables the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. GFX_TransparentColorEnable This function sets the transparent color used in GFX_ImageDraw() functions and enables the transparent color feature. GFX_TransparentColorGet This returns the current transparent color set for the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. GFX_TransparentColorStatusGet This returns the current state of the transparent color feature used in GFX_ImageDraw() and GFX_ImagePartialDraw() functions. GFXCirclePointGet This is function GFXCirclePointGet. Macros Name Description GFX_CosineGet This is macro GFX_CosineGet. GFX_SineGet This is macro GFX_SineGet. ONEP25 1.25 * 2^16 SIN45 sin(45) * 2^16) File Name gfx_primitive.h Company Microchip Technology Inc. 5.2.2.8.32 gfx_primitive_local.h Clock System Service Interface Definition None. Enumerations Name Description FONT_ORIENTATION Types of orientation IMAGE_STRETCH Types of image stretching LAYER_ACTIONS Functions Name Description GFX_AlphaBlendWindow GFX_DoubleBufferVisualPageUpdate GFX_Layer GFX_PageSet Macros Name Description CopyPageWindow GFX_ActivePageGet Returns the active page. GFX_AlphaParamsSet 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1104 GFX_BUFFER1 This is macro GFX_BUFFER1. GFX_BUFFER2 This is macro GFX_BUFFER2. GFX_FontAlignmentSet Sets font orientation vertical or horizontal. GFX_GradientTypeSet This is macro GFX_GradientTypeSet. GFX_ImageStretchSet This is macro GFX_ImageStretchSet. GFX_MaxXGet GFX_MaxYGet GFX_PixelPut This is macro GFX_PixelPut. GFX_PixelsPut This function renders one line of pixels of a given length GFX_PrevAlphaColorGet GFX_PrevAlphaColorSet GFX_SetFontOrientation Sets font orientation vertical or horizontal. GFX_VisualPageGet Returns the visual page. Structures Name Description GFX_FONT_CURRENT Internal structure for currently set font. GFX_GRADIENT_STYLE This structure is used to describe the gradient style. GFX_Primitive_DATA GFX_TRANSITION_PARAMS PUTIMAGE_PARAM Partial image area to render. Variables Name Description DisplayUpdatePending This is variable DisplayUpdatePending. doubleBuffEnabled This is variable doubleBuffEnabled. GFX_Primitive_instance structure to store the primitive driver structures primitiveTaskImage This is variable primitiveTaskImage. File Name gfx_primitive.h Company Microchip Technology Inc. 5.2.2.8.33 gfx_transitions.h • Module for Microchip Graphics Library • Primitive Layer • Transition *************************************************************************** • FileName: Transitions.h • Dependencies: None • Processor: PIC24F, PIC24H, dsPIC, PIC32 • Compiler: MPLAB C30, MPLAB C32 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1105 • Linker: MPLAB LINK30, MPLAB LINK32 • Company: Microchip Technology Incorporated * • Software License Agreement * • Copyright © 2010 Microchip Technology Inc. All rights reserved. • Microchip licenses to you the right to use, modify, copy and distribute • Software only when embedded on a Microchip microcontroller or digital • signal controller, which is integrated into your product or third party • product (pursuant to the sublicense terms in the accompanying license • agreement). * • You should refer to the license agreement accompanying this Software • for additional information regarding your rights and obligations. * • SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY • KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY • OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR • PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR • OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, • BREACH OF WARRANTY, OR OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT • DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, • INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, • COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY • CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), • OR OTHER SIMILAR COSTS. * • Author Date Comment *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ • Microchip 24/12/2010 Initial version Enumerations Name Description GFX_TRANSITION_DIRECTION Direction enumeration to determine the direction of the selected GFX_TRANSITION_TYPE. GFX_TRANSITION_TYPE Transition type enumeration to determine the type of the transition. Each type will require specific parameters when setting up the transition operation (GFXSetupTransition() or GFXTransition()). 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1106 Functions Name Description GFX_SetTransitionParameters This sets up the transition effect using the GFX_TRANSITION_TYPE and the given parameters. The actual transition execution will occur when GFXExecutePendingTransition() is called. When DOUBLE_BUFFERING is enabled, GFXExecutePendingTransition() is executed after the current screen is fully rendered. GFX_Transition This immediately executes the transition effect using the GFX_TRANSITION_TYPE and the given parameters. 5.2.2.8.34 gfx_types_font.h Graphics Resource Types Header for Microchip Graphics Library This header defines the different structures used for fonts resources in the Microchip Graphics Library. Macros Name Description GFX_FONT_SPACE Font space section. The fonts can be located in psv (constant) or program space in PIC24/dsPIC MCUs. This define allows for switching of the pointer type used to access the font structure in memory See: GraphicsConfig.h for the application define. GFX_TYPES_FONTS_H This is macro GFX_TYPES_FONTS_H. GFX_UXCHAR This is macro GFX_UXCHAR. GFX_XCHAR Configuration for the text character size. Structures Name Description GFX_FONT_GLYPH_ENTRY Structures describing the glyph entry. GFX_FONT_GLYPH_ENTRY_EXTENDED This is type GFX_FONT_GLYPH_ENTRY_EXTENDED. GFX_FONT_HEADER Structure describing the font header. GFX_FONT_OUTCHAR Structure for character information when rendering the character. File Name gfx_font_types.h Company Microchip Technology Inc. 5.2.2.8.35 gfx_types_image.h Graphics Resource Types Header for Microchip Graphics Library This header defines the different structures used for images resources in the Microchip Graphics Library. Macros Name Description GFX_TYPES_IMAGE_H This is macro GFX_TYPES_IMAGE_H. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1107 Structures Name Description GFX_MCHP_BITMAP_HEADER Structure describing the bitmap header. Types Name Description int16_gfx_image_prog This is type int16_gfx_image_prog. int16_prog This is type int16_prog. int16_prog_pack This is type int16_prog_pack. int32_gfx_image_prog This is type int32_gfx_image_prog. int32_prog This is type int32_prog. int32_prog_pack This is type int32_prog_pack. int8_gfx_image_prog This is type int8_gfx_image_prog. int8_prog This is type int8_prog. int8_prog_pack This is type int8_prog_pack. uint16_gfx_image_prog This is type uint16_gfx_image_prog. uint16_prog This is type uint16_prog. uint16_prog_pack This is type uint16_prog_pack. uint32_gfx_image_prog This is type uint32_gfx_image_prog. uint32_prog This is type uint32_prog. uint32_prog_pack This is type uint32_prog_pack. uint8_gfx_image_prog GFX Image data Types uint8_prog General program space data types uint8_prog_pack This is type uint8_prog_pack. File Name gfx_image_types.h Company Microchip Technology Inc. 5.2.2.8.36 gfx_types_macros.h Module for Microchip Graphics Library This module defines the data types used in the Microchip Graphics Library for use of Primitive and Driver Layers. Enumerations Name Description GFX_ALIGNMENT Defines the types of text alignment. The text alignment is used in GFX_TextStringBoxDraw(). GFX_BACKGROUND_TYPE Defines the types of background information. Knowing the background information allows easier refresh of an area on the display buffer. GFX_BEVEL_RENDER_TYPE Bevel shapes can be rendered in full or half size. The following types defines the full, top and bottom halves. GFX_FEATURE_STATUS Defines the states of a Graphics Library feature that can nbe enabled/disabled at run time. GFX_FILL_STYLE Defines the types of fill styles. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1108 GFX_FONT_ANTIALIAS_TYPE Transparency type when rendering characters with anti-aliasing. GFX_LINE_STYLE Defines the types of line styles. GFX_STATUS Status types for rendering. GFX_STATUS_BIT Bit masks for additional status information. Macros Name Description ConvertColor25 This is macro ConvertColor25. ConvertColor50 75, 50, 25 percentage color conversion macros. Used in converting colors to these percentages when performing alpha blending of colors using software alpha blending operation. ConvertColor75 This is macro ConvertColor75. GFX_MAX_INVALIDATE_AREAS This is macro GFX_MAX_INVALIDATE_AREAS. GFX_RGBConvert Macros: GFX_RGBConvert(red, green, blue) This macro converts the color data to the selected COLOR_DEPTH. This macro is only valid when COLOR_DEPTH is 8, 16, or 24. Structures Name Description 5.2.2.8.37 gfx_types_palette.h FileName: gfx_palette_types.h Dependencies: See Includes Section Processor: PIC24, PIC32 Compiler: XC16/XC32 Linker: XC16/XC32 Macros Name Description GFX_TYPES_PALETTE_H This is macro GFX_TYPES_PALETTE_H. Unions Name Description 5.2.2.8.38 gfx_types_resource.h Graphics Resource Types Header for Microchip Graphics Library This header defines the different structures used for the Graphics Resources used in the Graphics Library. This also contains helpful macros as well as data types used. Enumerations Name Description GFX_RESOURCE Memory type enumeration to determine the source of data. Used in interpreting images, fonts and palette from different memory sources. Macros Name Description GFX_COMP_MASK This is macro GFX_COMP_MASK. GFX_MEM_MASK This is macro GFX_MEM_MASK. GFX_TYPE_MASK This is macro GFX_TYPE_MASK. GFX_TYPES_RESOURCE_H This is macro GFX_TYPES_RESOURCE_H. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Object Library 5-1109 MCHP_BITMAP_NORMAL no compression, palette is present for color depth = 8, 4 and 1 BPP MCHP_BITMAP_PALETTE_STR palette is provided as a separate object (see PALETTE_HEADER) for color depth = 8, 4, and 1 BPP, ID to the palette is embedded in the bitmap. Structures Name Description GFX_RESOURCE_BINARY Structure for Graphics Resource - binary data. GFX_RESOURCE_FONT Structure for Graphics Resource - Fonts. GFX_RESOURCE_HDR Structure for Graphics Resource Header. This is the common header for all Graphics Resources. GFX_RESOURCE_IMAGE Structure for Graphics Resource - image. GFX_RESOURCE_PALETTE Structure for Graphics Resource - Palette. File Name gfx_resource_types.h Company Microchip Technology Inc. 5.2.3 Graphics Primitive Library 5.2.3.1 Introduction Graphics Primitive Library for Microchip Microcontrollers This library provides a low-level abstraction of the Graphics Primitive Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the library without the necessity of interacting directly with a graphics controller, there by hiding differences from one graphics controller variant to another. Description This module is part of a larger Graphics Library. The Primitive Layer is used to send rendered shape data to the appropriate graphics controller driver. The primitive layer is also a scheduler to make sure that shapes are rendered in the proper order. This helps ensure a widget appears on the screen correctly. Shapes (Bars, Lines, Bevels, etc.) also include text and images. 5.2.3.2 Release Notes MPLAB Harmony Version: v0.70b Graphics Primitive Library Version : 4.00b Release Date: 18Nov2013 Contents: This release consists of the Graphics Primitive Layer. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1110 Graphic Layer Description Primitive The primitive layer sends rendered shape and image data to the appropriate graphics controller driver New This Release: A summary of the new features is as follows: • Renamed Primitive API functions • Remove instance argument from APIs Feature Description Comments Multi-Display support Only one LCD display is supported in this release. Support available in upcoming release. Known Issues: • No multi-display support Feature Category Description Work-around Multi-Display support Driver Only one LCD display is supported in this release. Support available in upcoming release. 5.2.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.2.3.4 Using the Library This topic describes the basic architecture of the Graphics Primitive Library and provides information and examples on how to use it. Interface Header File: gfx_primitive.h The interface to the Graphics Primitive library is defined in the "primitive.h" header file. This file is included by the "gfx.h" file. Any C language source (.c) file that uses the Graphics Primitive library should include "primitive.h". 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1111 5.2.3.4.1 Abstraction Model The Primitive Layer provide a set of low level drawing functions. These functions include drawing lines, rectangles, circles, text, and bitmap images. 5.2.3.4.2 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Graphics module. Library Interface Section Description Setup and Management Functions Contains the APIs for setting up primitive rendering functions and managing the primitive layer Text Functions Contains the APIs for rendering text Shape Functions Contains the APIs for shapes that can be rendered Image Functions Contains the APIs for rendering images Color Functions Contains the APIs for setting/getting colors Double Buffering Functions Contains the APIs for setting double buffering 5.2.3.4.3 How the Library Works The primitive layer is defined as the mediator between the graphics object layer and the graphics controller driver layer. Once the primitive layer is initialized the application just has to make calls to which specific primitive it is rendering. This layers serves other purposes: • Schedules primitive tasks to ensure proper primitive rendering. This feature makes it possible to know that when an object is called to be drawn on a screen before another object that the order of these calls will be kept intact. This is important when using features where the image on the LCD matters before making the function call. • In the case of multiple graphics controller drivers, it organizes which driver to make the primitive update to. Below is a flow chart showing how the primitive layer works in conjunction with the driver layer and the object layer. 5.2.3.4.3.1 Core Functionality The primitive layer consists of a command based circular buffer. Primitives are scheduled in the buffer and the commands are serviced each time primitivetasks() function is called. Description The library relies on a graphics controller driver to render images to an LCD panel. Below shows how the primitive layer files interact with the driver layer files. 5.2.3.4.4 Using Primitive Rendering Functions Basic rendering functions such as LineDraw(), BarDraw(), CircleDraw() etc are referred to as functions in the Graphics Primitive 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1112 Layer. These functions can also be implemented in the device driver layer if the display device supports hardware acceleration of the function. Applications that directly calls these functions can take advantage of the hardware accelerated primitives. How these functions are used will depend on the configuration. Description All primitive rendering functions returns a handle to their location in the queue. // all primitives are non-blocking calls while(GFX_PRIM_LineDraw(instance,a,b) == NULL); while(GFX_PRIM_BarDraw(instance,c,d,e,f) == NULL); while(GFX_PRIM_BarFill(instance,c+2, d+2, e-2, f-2) == NULL); If the while check is not in place, it possible that the only primitive that you will see in the screen is the GFX_PRIM_LineDraw(). For case 2, one can also be creative in the application code and implement some form of non-blocking scheme and make use of the time while waiting for the primitives to render. Another example for case 2: uint16_t DrawMyFigure(instance, a, b, c, d, e, f) { typedef enum { DRAW_LINE, DRAW_RECT, DRAW_BAR, } DRAW_MYFIGURE_STATES; static DRAW_MYFIGURE_STATES state = DRAW_LINE; switch(state){ case DRAW_LINE: if (GFX_PRIM_LineDraw(instance, a, b) == NULL) return 0; state = DRAW_RECT; case DRAW_RECT: if(GFX_PRIM_BarDraw(instance,c,d,e,f) == NULL) return 0; state = DRAW_BAR; case DRAW_BAR: if(GFX_PRIM_BarFill(instance, c+2, d+2, e-2, f-2) == NULL); return 0; state = DRAW_LINE; return 1; } } This non-blocking code can be used in the application and the application can do other tasks whenever DrawMyFigure() returns 0. Application should call DrawMyFigure() again until it return a 1 signifying that the Line, Rectangle and GFX_PRIM_BarDraw were drawn successfully. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1113 5.2.3.4.4.1 Arcs 5.2.3.4.4.2 Gradients Below is an image that helps describe the GFX_PRIM_BarGradient() function in more detail. Below is an image that helps describe the GFX_PRIM_BevelGradient() function in more detail. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1114 5.2.3.4.4.3 Bevels 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1115 5.2.3.4.4.4 Alpha Blending This section helps describe how alpha blending works in the primitive layer. Description Alpha-Blend support are two levels. USE_ALPHABLEND_LITE and USE_ALPHA_BLEND. Alpha Blend Lite is a "desructive" alpha blend where the blending happens in one frame or window. Once the colors are blending the original color data in the visual page is lost. This method only requires one frame and GetPixel type functionality to work. The other Alpha Blending uses blocks of pixels in the memory called Windows. A window can be any rectangular area in a display buffer. The display buffer is also considered as a page. For a QVGA display buffer a page would be 320x240 pixels. A window is a certain width and height contained inside a page. Alpha blending equation: OutPut Window = Foreground Window * (Alpha) + Background Window * (1-Alpha) when done in software requires a lot of CPU bandwith. Epson Controller implements alpha blending in hardware which offloads the CPU. The Display Driver Layer of the Graphics Library utilizes the Epson Controller alpha blending through the AlphaBlendWindow() function. Three windows are specified with equal widths and heights. An alpha parameter is passed to define the level of alpha blending. The logical flow of the operation is shown below: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1116 An icon image with a given width (w) and height (h) is needed to be alpha blended into the display buffer. • Buffer A is allocated in memory and its location set by foregroundWindowAddr • Buffer B is allocated in memory and its location set by backgroundWindowAddr and • Buffer C is allocated in memory and its location set by destinationWindowAddr. Note that the destination window can be located within the display buffer. Doing this removes an intermediate step after AlphaBlendWindow() call to put the result of alpha blend in the display buffer. The final location of the icon on the Display Buffer is used to locate the affected pixels in the Display Buffer. These affected pixels are copied into Buffer B while Buffer A is filled up with the Icon Image. Once Buffers A and B are ready they are alpha blended to Buffer C. Buffer C is then copied to the Display Buffer. Note that the Icon Image has a background color of ORANGE. To have the effect of the final output Display Buffer, set the Epson Controllers transparent color to ORANGE. This is set in the TRANSPARENTCOLOR macro defined in the Epson S1D13517 Driver. This TRANSPARENTCOLOR macro is not to be confused with the TransparentColorEnable() function of the Display Device Driver Level Primitives. TRANSPARENTCOLOR is set at build time. In the future release of the Epson driver, this will be converted to use the TransparentColorEnable() function. 5.2.3.4.4.5 Images The image support on the primitive layer can be done "partially" to achieve more functionality in where a background can be updated more efficiently. More details are below: 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1117 5.2.3.4.5 Defining Colors In most cases, the application will define its own set of colors and not use the default colors that comes with the Graphics Library. This section shows an example on how to do it. Description To override or define a new set of colors follow this steps: 1. Create a new color header file. The color values and data types will depend on the GFX_COLOR type used. This data type is defined by the COLOR_DEPTH macro. See COLOR_DEPTH for details. 2. In the application code, include the created color header file ahead of the #include "Graphics/Graphics.h". When Graphics.h includes the gfxcolors.h it will ignore color macros that has been defined already in the new color header file. In the GOL Palette Demo, there is an example on how it is done. In that project there is a file in the application (or project directory) named PaletteColorDefines.h. This file contains all the color definition used in the demo. The main header file of the demo (Main.h) includes the PaletteColorDefines.h file ahead of the Graphics Library header files. Since the PaletteColorDefines.h declared the color values, the macros redefined in gfxcolors.h will be ignored. How is this done? If you look at the gfxcolors.h file you will notice that all colors defined have a check (for example BLACK()): #ifndef BLACK() 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1118 #define BLACK() 0 #endif So if BLACK() is defined previously, the definition in gfxcolors.h will not take effect. 5.2.3.4.6 Changing the Default Font The library comes with the default font (Gentium 18). This font can be changed in two ways. This instructions assumes that you have performed the conversion of your raster font or True Type font into C file. For the conversion of your raster font please see the help file of the Graphics Resource Converter utility that comes with the Graphics Library. There are two ways to replace the default font in the Graphics Library. Renaming User Font to GOLFontDefault: 1. Open the generated font file (generated by the "Graphics Resource Converter" utility) and change the font structure name to GOLFontDefault (see figure below). 2. Remove the file GOLFONTDefault.c in the project and replace it with your own font file that contains the GOLFontDefault. 3. Build and test your new font. Replacing the GOLFontDefault with any user defined fonts 1. Open the GraphicsConfig.h file and add the following lines: #define FONTDEFAULT yourFontName 2. In the project, add the generated font file (generated by the "Graphics Resource Converter" utility). 3. Build and test your new font. In this method, GOL.h and GOLFontDefault.c files checks if FONTDEFAULT is defined. If it is, it skips the declaration of the GOLFontDefault and uses the user defined font. 5.2.3.4.7 Advanced Font Features This topic explains anti aliasing, glyphs, and advanced font features. Description Fonts used in the library can be configured to use anti-aliasing and extended glyph support. Font Anti-Aliasing Anti-aliasing is a technique used to make the edges of text appear smooth. This is useful especially with characters like 'A', 'O', etc which has slant or curved lines. Since the pixels of the display are arranged in rectangular fashion, slant edges can't be represented smoothly. To make them appear smooth, a pixel adjacent to the pixels is painted with an average of the foreground and background colors as depicted in Figure 1. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1119 Figure 1: Font with Anti-Aliasing Figure 2: Font with No Anti-Aliasing When anti-aliasing is turned off, the pixels abruptly changes from background color to foreground color shown in Figure 2. To implement anti-aliasing, adjacent pixels transitions from background to foreground color using 25% or 75% mid-color values from background to foreground colors. This feature in fonts will require roughly twice the size of memory storage required for font glyphs with no anti-aliasing. Since the average of foreground and background colors needs to be calculated at runtime, the rendering of anti-aliased fonts take more time than rendering normal fonts. To optimize the rendering speed, a macro named GFX_Font_SetAntiAliasType() is available where anti-alias type can be set to ANTIALIAS_OPAQUE or ANTIALIAS_TRANSLUCENT. • ANTIALIAS_OPAQUE (default after initialization of graphics) - mid colors are calculated once while rendering each character which is ideal for rendering text over a constant background. • ANTIALIAS_TRANSLUCENT - the mid values are calculated for every necessary pixel and this feature is useful while rendering text over an image or on a non-constant color background. As a result, rendering anti-aliased text takes longer with ANTIALIAS_TRANSLUCENT type than compared to ANTIALIAS_OPAQUE type. To use anti-aliasing, enable the compiler switch #define USE_ANTIALIASED_FONTS in the GraphicsConfig.h file and enable the anti-alias checkbox in the Graphics Resource Converter (GRC) tool while selecting the font. Note: Even when anti-aliasing is enabled, normal fonts can be used without the antialias effect. Extended Glyphs Extended glyphs are needed to render characters of certain languages which use more than one byte to represent a single character. For example: Asian languages like Thai, Hindi, etc. In these character set, more than one glyph overlaps each other to form a single character of that language as shown in Figure 3. To use this feature, enable the Extended Glyph checkbox in the Graphics Resource Converter (GRC) tool while selecting the font. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1120 Figure 3: Example of a Character that is Formed by Two Overlapping Glyphs Note: The fonts used with extended glyphs are normal ANSI fonts and not Unicode fonts. 5.2.3.4.8 Double Buffering In the Microchip Graphics Library, if double-buffering is enabled, the frame buffer and draw buffer are exchanged after the changes of all the widgets on a screen are done (i.e., the new screen appears after the whole screen is updated and not after updating an individual widget). This feature is enabled only on the following drivers: • Microchip Graphics Display Driver - customizable driver for RGB Glass. Currently used in PIC24FJ256DA210 device family. • Microchip Low-Cost Controllerless (LCC) Graphics Display Driver - customizable driver for RGB Glass. Currently used for selected PIC32MX device families. Description Manipulating pixels on the screen requires direct writes to the frame buffer. While these changes are being executed, the screen is also refreshed. This means that the changes are displayed immediately as the frame buffer is being updated. This is not a suitable scheme when the changes are slow, for example, decoding an image or having a large number of widgets on a screen. The display may appear slow in that case. One solution to this problem is to use a double-buffering scheme supported by the Microchip Graphics Library. In this scheme, the changes are not directly written to the frame buffer, but instead, they are written to a separate buffer, called the ‘Draw Buffer’. After all the changes are made, the draw buffer and frame buffer are exchanged. Now the draw buffer becomes the frame buffer, and because of all the changes drawn there, the changes appear spontaneous to the user. Of course, there will be a delay, as all the changes have to be written to the draw buffer before displaying it. This delay is generally more tolerable than displaying the changes slowly. After exchanging of the buffers, the latest buffer (which is now the frame buffer) is copied to the new draw buffer in the background and then the new draw buffer is in sync with what is being displayed. New changes are then written to the draw buffer and the cycle continues. As the double-buffering scheme uses two buffers, the RAM requirement will double. In the Microchip Graphics Library, if double-buffering is enabled, the frame buffer and draw buffer are exchanged after the changes of all the widgets on a screen are done (i.e., the new screen appears after the whole screen is updated and not after updating an individual widget). The work flow of double-buffering is graphically explained along with tips on deciding when to use double buffering in the APPENDIX B of the Application note AN1368: Developing Embedded Graphics Applications using PIC® Microcontrollers with Integrated Graphics Controller. To use double buffering in an application, follow the steps described below: 1. Enable the option USE_DOUBLE_BUFFERING in GraphicsConfig.h 2. Update GFX_DISPLAY_BUFFER_LENGTH to include both the buffers in HardwareProfile.h. Note that when using external memory the GFX_DISPLAY_BUFFER_LENGTH must fit into the external memory size. For example in PIC24FJ256DA210 external memory can be added using EPMP. External memory mapped to the EPMP must be big enough to accommodate the display buffers required by double buffering. See Set Up Display Interface for more information on memory requirements. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1121 3. Check the jumper settings to enable the required RAM address space on the development board If Graphics Objects Layer (GOL) is used in the application, the switching of buffers is handled automatically in order to keep the switching task transparent to the users. If double buffering is enabled in applications using only the Primitive layer, then the switching of buffers has to be handled by the application itself as explained in the following steps. Steps required for manually handling the switching of buffers: 1. After InitGraph() is called, call the APIs InvalidateAll() followed by UpdateDisplayNow(). The two buffers are properly setup after these calls and from this point onwards, the drawing happens on the draw-buffer. 2. When a shape is drawn on the draw buffer, that rectangular area has to be marked as invalid by using the API InvalidateRectangle(left, top, right, bottom). Only the invalidated rectangular areas are copied to the frame buffer in order to reduce the copy operations thereby reducing the overall time and energy required to sync the two buffers. Hence, it is important to invalidate the changed rectangular areas failing which the change doesn’t show up on the display. 3. Call either RequestDisplayUpdate() or UpdateDisplayNow() to sync the two buffers and as a result the changes appear on the display. The former API exchanges the buffers during the next display blanking period on TFT LCDs causing the change to appear smooth and immediate whereas the latter API exchanges the two buffers at the time of the API call probably causing a slight flicker on the display. On displays which doesn’t support blanking periods (e.g. CSTN LCDs), the effect of RequestDisplayUpdate() is same as that of UpdateDisplayNow(). Even if double buffering is enabled at compile time, it can be switched off and on at run time using APIs SwitchOffDoubleBuffering() and SwitchOnDoubleBuffering(). Switching double buffering on/off at runtime is useful in applications which need some screens having fast updates like waveform or animation which requires double buffering to be switched off and some other screens where double buffering is beneficial. Note: In applications using Graphics Objects Layer and double buffering, the double buffering is not immediately enabled after the API GFX_OBJ_Initialize() is called in order to support hassles splash screens but is automatically enabled from the second screen update onwards. If double buffering is needed from the first screen itself, then follow step 1 immediately after calling GFX_OBJ_Initialize(). 5.2.3.4.9 Transitions This section describes screen transition effect when changing screens. Description Applications often require some transition effects while changing screens in order to enhance the look and feel which can be achieved by using Transition APIs provided with the Microchip Graphics Library. Refer to Appendix C of the application note AN1368: Developing Embedded Graphics Applications using PIC® Microcontrollers with Integrated Graphics Controller for a graphical illustration of how transitions can be achieved. In order to translate a new screen, the new screen has to be developed in a separate buffer and has to be copied to the frame buffer (visible display buffer) part by part. The way the new screen data is copied into the frame buffer determines the transition effect. A number of transition effects can be achieved by using the API: GFXTransition(left, top, right, bottom, type, srcpageaddr, destpageaddr, delay_ms, param1, param2). This API copies the rectangular area defined by left, top, right and bottom from address defined by srcpageaddr to the destpageaddr as per the transition defined by type, param1 and param2. The 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1122 srcpageaddr should contain the new screen data and the destpageaddr must be the frame buffer address. The speed of the transition can be configured by the parameter delay_ms which determines the delay between each copy operations. Note that this API must be called only at the end of GFX_OBJ_DrawCallback() function in order to ensure that the new screen is fully created in the RAM. If double buffering is enabled, then using transitions is made easier by another API: GFXSetupTransition(left, top, right, bottom, type, delay_ms, param1, param2). This API can be called immediately after creating the new screen and the graphics library will store the request and initiate the transition after the new screen is fully created in the RAM. Note that this API doesn’t have address parameters as the address of draw-buffer is already known to the double buffering subsystem of the graphics engine. 5.2.3.5 Configuring the Library The configuration of the Graphics Primitive Library is based on the file system_config.h This header file contains the configuration selection for the Graphics Primitive Library. Based on the selections made, the Graphics Primitive Library will support or not support selected features. These configuration settings will apply to all instances of the Graphics Primitive Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.2.3.5.1 Fonts This compile option selects if the support for unicode fonts, unsigned char or the default signed char type fonts. There are three types of font (characters) that can be used in the Graphics Library. This gives the user the option to implement multi-language application or use the default signed char type. Define in GraphicsConfig.h XCHAR type Description #define USE_MULTIBYTECHAR #define XCHAR unsigned short Enable support for multi-byte fonts such as Unicode fonts. #define USE_UNSIGNED_XCHAR #define XCHAR unsigned char Enable support for character range of 0-255. none of the two are defined #define XCHAR char Character range is set to 0-127. Note: Only one of the two or none at all are defined in GraphicsConfig.h. - #define USE_MULTIBYTECHAR - #define USE_UNSIGNED_XCHAR - when none are defined, XCHAR defaults to type char. See XCHAR for details. 5.2.3.5.2 Alpha Blending This compile option enables the Alpha-Blend feature in Primitive Layer. 5.2.3.5.3 Colors Defines the color depth of the system 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1123 5.2.3.5.4 Images 5.2.3.6 Building the Library This section list the files that are available in the \src of the primitive driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • gfx.h 5.2.3.7 Library Interface Data Types and Constants Name Description GFX_CosineGet This is macro GFX_CosineGet. GFX_GradientTypeSet This is macro GFX_GradientTypeSet. GFX_SineGet This is macro GFX_SineGet. Setup and Management Functions Name Description GFX_SineCosineGet This is function GFX_SineCosineGet. Shape Functions Name Description GFXCirclePointGet This is function GFXCirclePointGet. Description This section describes the Application Programming Interface (API) functions of the Graphics Primitive Library. 5.2.3.7.1 Setup and Management Functions 5.2.3.7.1.1 GFX_SineCosineGet Function C int16_t GFX_SineCosineGet( int16_t v, GFX_TRIG_FUNCTION_TYPE type ); Description This is function GFX_SineCosineGet. 5.2.3.7.2 Text Functions 5.2.3.7.3 Shape Functions 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1124 5.2.3.7.3.1 GFXCirclePointGet Function C void GFXCirclePointGet( int16_t radius, int16_t angle, int16_t * x, int16_t * y ); Description This is function GFXCirclePointGet. 5.2.3.7.4 Color Functions 5.2.3.7.5 Draw Functions 5.2.3.7.6 Image Functions 5.2.3.7.7 Double Buffering Functions 5.2.3.7.8 Data Types and Constants 5.2.3.7.8.1 GFX_CosineGet Macro C #define GFX_CosineGet(angle) GFX_SineCosineGet(angle, GFX_TRIG_COSINE_TYPE) Description This is macro GFX_CosineGet. 5.2.3.7.8.2 GFX_GradientTypeSet Macro C #define GFX_GradientTypeSet(value) GFX_Primitive_instance.gradientStyle.type = value Description This is macro GFX_GradientTypeSet. 5.2.3.7.8.3 GFX_SineGet Macro C #define GFX_SineGet(angle) GFX_SineCosineGet(angle, GFX_TRIG_SINE_TYPE) Description This is macro GFX_SineGet. 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1125 5.2.3.8 Files The Graphics Primitive Library files include: • gfx_colors.h • gfx_primitive.h • gfx_transistions.h • gfx_types_palette.h • gfx_config_template.h 5.2 Graphics Library Help MPLAB Harmony Help Graphics Primitive Library 5-1126 5.3 Cryptographic (Crypto) Library 5.3.1 Introduction Cryptographic Library for Microchip Microcontrollers This library provides a software Cryptographic Library that is available on the Microchip family of microcontrollers with a convenient C language interface. Description The Cryptographic Library includes functions to perform encryption, decryption, hashing, authentication, and compression within the embedded application. Random number generation (RNG) functions are also provided. Block Ciphers The library provides DES, 3DES, and AES for block cipher needs. Depending on the algorithm in use, CBC and CTR modes are supported. Public Key Cryptography The library provides RSA and Elliptic Curve Cryptography (ECC) for Public Key Cryptography, and Diffie-Hellman (DH) for key agreement arrangements. Hash Functions The library provides MD5, SHA, SHA-256, SHA-384, and SHA-512 for hashing. These functions do not require keys or initialization vectors (IV). Random Number Generation Functions The library provides functions to generate either a single pseudo-random number, or a block of such numbers. 5.3.2 Release Notes MPLAB Harmony Version: v0.70b Cryptographic Library: 1.00 Release Date: 18Nov2013 New This Release: Cryptographic Library • Provides cryptographic, authentication, compression, and random number routines for use on PIC32MX and PIC32MZ families • Authentication capabilities: 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Release Notes 5-1127 • MD5 • SHA-1 • SHA-256 • SHA-384 • SHA-512 • HMAC • Cryptographic capabilities: • AES: • 128-, 192-, 256-bit key lengths • CBC, CTR, GCM, and CCM-8 modes • RSA • DES/Triple DES • Elliptic Curve Cryptography (ECC) • Random Number capabilities: • Single random number • Block of random numbers • Compression capabilities: • Huffman Encoding Compression/Decompression “zlib” Library The library includes the following new features: • The library is a general purpose data compression library. • Read and write gzip (.gz) format with an interface similar to that of stdio • Huffman Encoding algorithms Known Issues: Cryptographic Library • Nothing to report in this release. Compression/Decompression “zlib” Library • Nothing to report in this release 5.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help SW License Agreement 5-1128 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.3.4 Using the Library This topic describes the basic architecture of the Cryptographic (Crypto) Library and provides information and examples on how to use it. Interface Header File: crypto.h The interface to the Cryptographic (Crypto) Library is defined in the "crypto.h.h" header file. This file is included by the "crypto.h.h" file. Any C language source (.c) file that uses the Cryptographic (Crypto) Library should include "crypto.h.h". Library File: The Cryptographic (Crypto) Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Cryptographic (Crypto) Library interacts with the framework. 5.3.4.1 Abstraction Model This library provides the low-level abstraction of the Cryptographic Library module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Cryptographic (Crypto) Software Abstraction Block Diagram 5.3.4.2 Library Overview The Library Interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Cryptographic (Crypto) Library module. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Configuring the Library 5-1129 5.3.5 Configuring the Library The configuration of the Cryptographic Library is based on the file sys_config.h This header file contains the configuration selection for the Cryptographic Library. Based on the selections made, the Cryptographic Library will support or not support selected features. These configuration settings will apply to all instances of the Cryptographic Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.3.6 Building the Library This section list the files that are available in the \src of the Cryptographic Library driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.3.7 Library Interface Data Types and Constants Name Description CRYPT_AES_CTX AES CRYPT_ECC_CTX ECC CRYPT_HMAC_CTX HMAC CRYPT_MD5_CTX MD5 CRYPT_RNG_CTX RNG CRYPT_RSA_CTX RSA CRYPT_SHA_CTX SHA CRYPT_SHA256_CTX SHA-256 CRYPT_SHA384_CTX SHA-384 CRYPT_SHA512_CTX SHA-512 CRYPT_TDES_CTX TDES MC_CRYPTO_API_H Defines Microchip CRYPTO API layer AES Encryption/Decryption Functions Name Description CRYPT_AES_CBC_Decrypt CRYPT_AES_CBC_Encrypt CRYPT_AES_CTR_Encrypt CRYPT_AES_DIRECT_Decrypt Direct encryption of one block of data. CRYPT_AES_DIRECT_Encrypt Direct encryption of one block of data. CRYPT_AES_IvSet 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1130 CRYPT_AES_KeySet Compression Functions Name Description CRYPT_HUFFMAN_Compress Compress a block of data. CRYPT_HUFFMAN_DeCompress Decompress a block of data. ECC Encryption/Decryption Functions Name Description CRYPT_ECC_DHE_KeyMake CRYPT_ECC_DHE_SharedSecretMake CRYPT_ECC_DSA_HashSign CRYPT_ECC_DSA_HashVerify CRYPT_ECC_Free CRYPT_ECC_Initialize CRYPT_ECC_KeySizeGet CRYPT_ECC_PrivateImport CRYPT_ECC_PublicExport CRYPT_ECC_PublicImport CRYPT_ECC_SignatureSizeGet General Functions Name Description CRYPT_ERROR_StringGet HMAC Hash Functions Name Description CRYPT_HMAC_DataAdd Add data to the HMAC calculation. CRYPT_HMAC_Finalize Complete the HMAC calculation and get the results. CRYPT_HMAC_SetKey Initialize the HMAC context and set the key for the hash. MD5 Functions Name Description CRYPT_MD5_DataAdd Updates the hash with the data provided. CRYPT_MD5_Finalize Finalizes the hash and puts the result into digest. CRYPT_MD5_Initialize Initializes the internal structures necessary for MD5 hash calculations. Random Number Generator Functions Name Description CRYPT_RNG_BlockGenerate Create several random numbers. CRYPT_RNG_Get Get one random number. CRYPT_RNG_Initialize Initialize random number generator. RSA Encryption/Decryption Functions Name Description CRYPT_RSA_EncryptSizeGet CRYPT_RSA_Free CRYPT_RSA_Initialize 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1131 CRYPT_RSA_PrivateDecrypt CRYPT_RSA_PrivateKeyDecode CRYPT_RSA_PublicEncrypt CRYPT_RSA_PublicKeyDecode SHA Hash functions Name Description CRYPT_SHA_DataAdd Updates the hash with the data provided. CRYPT_SHA_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA_Initialize Initializes the internal structures necessary for SHA hash calculations. SHA256 Hash Functions Name Description CRYPT_SHA256_DataAdd Updates the hash with the data provided. CRYPT_SHA256_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA256_Initialize Initializes the internal structures necessary for SHA256 hash calculations. SHA384 Hash Functions Name Description CRYPT_SHA384_DataAdd Updates the hash with the data provided. CRYPT_SHA384_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA384_Initialize Initializes the internal structures necessary for SHA384 hash calculations. SHA512 Hash Functions Name Description CRYPT_SHA512_DataAdd Updates the hash with the data provided. CRYPT_SHA512_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA512_Initialize Initializes the internal structures necessary for SHA512 hash calculations. Triple DES (3DES) Encryption/Decryption Functions Name Description CRYPT_TDES_CBC_Decrypt Decrypt a data block using Triple DES. CRYPT_TDES_CBC_Encrypt Encrypt a data block using Triple DES. CRYPT_TDES_IvSet Set the Initialization Vector (IV) for a Triple DES operation. CRYPT_TDES_KeySet Initialization of Triple DES context. Description This section describes the Application Programming Interface (API) functions of the Cryptographic Library. Refer to each section for a detailed description. 5.3.7.1 General Functions 5.3.7.1.1 CRYPT_ERROR_StringGet Function C int CRYPT_ERROR_StringGet( 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1132 int, char* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Remarks String needs to be >= 80 chars. Example 5.3.7.2 SHA512 Hash Functions 5.3.7.2.1 CRYPT_SHA512_DataAdd Function C int CRYPT_SHA512_DataAdd( CRYPT_SHA512_CTX*, const unsigned char*, unsigned int ); Description This function updates the hash with the data provided. Preconditions The SHA512 context must be initialized prior to the first call of this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha512 Pointer to CRYPT_SHA512_CTX strucure which holds the hash values. input Pointer to the data to use to update the hash. sz Size of the data (in bytes) of the data to use to update the hash. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha512 or input. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA512 hash, nothing must modify the context holding variable between calls to CRYPT_SHA512_DataAdd. Example CRYPT_SHA512_CTX sha512; 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1133 uint8_t buffer[1024]; uint8_t sha512Sum[SHA512_DIGEST_SIZE]; CRYPT_SHA512_Initialize(&sha512); CRYPT_SHA512_DataAdd(&sha512, buffer, sizeof(buffer)); CRYPT_SHA512_Finalize(&sha512, sha512Sum); 5.3.7.2.2 CRYPT_SHA512_Finalize Function C int CRYPT_SHA512_Finalize( CRYPT_SHA512_CTX*, unsigned char* ); Description This function finalizes the hash and puts the result into digest. Preconditions The SHA512 context must be initialized prior to calling this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha512 Pointer to CRYPT_SHA512_CTX strucure which holds the hash values. digest Pointer to byte array to store hash result. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha512 or digest. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA512 hash, nothing must modify the context holding variable between calls to CRYPT_SHA512_DataAdd and CRYPT_SHA512_Finalize. Example CRYPT_SHA512_CTX sha512; uint8_t buffer[1024]; uint8_t sha512Sum[SHA512_DIGEST_SIZE]; CRYPT_SHA512_Initialize(&sha512); CRYPT_SHA512_DataAdd(&sha512, buffer, sizeof(buffer)); CRYPT_SHA512_Finalize(&sha512, sha512Sum); 5.3.7.2.3 CRYPT_SHA512_Initialize Function C int CRYPT_SHA512_Initialize( CRYPT_SHA512_CTX* ); Description This function initializes the internal structures necessary for SHA512 hash calculations. Preconditions None. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1134 Parameters Parameters Description sha512 Pointer to CRYPT_SHA512_CTX strucure which holds the hash values. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks All SHA512 hashes have to start at a particular value before adding new data to it. This function sets the necessary values for the structure. Example CRYPT_SHA512_CTX sha512; uint8_t sha512Sum[SHA512_DIGEST_SIZE]; CRYPT_SHA512_Initialize(&sha512); CRYPT_SHA512_DataAdd(&sha512, buffer, sizeof(buffer)); CRYPT_SHA512_Finalize(&sha512, sha512Sum); 5.3.7.3 HMAC Hash Functions 5.3.7.3.1 CRYPT_HMAC_DataAdd Function C int CRYPT_HMAC_DataAdd( CRYPT_HMAC_CTX*, const unsigned char*, unsigned int ); Description This function adds data to the HMAC so that multiple blocks of data can be processed. Preconditions The CRYPT_HMAC_CTX context must be initialized using the CRYPT_HMAC_SetKey function prior to any call to this function. Parameters Parameters Description hmac Pointer to context which saves state between calls. input Pointer to the data to use to update the hash. sz Size of the input data in bytes. Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Remarks Example CRYPT_HMAC_CTX mcHmac; byte mcDigest[CRYPT_SHA512_DIGEST_SIZE]; 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1135 CRYPT_HMAC_SetKey(&mcHmac, CRYPT_HMAC_SHA, key, 4); CRYPT_HMAC_DataAdd(&mcHmac, ourData, OUR_DATA_SIZE); CRYPT_HMAC_Finalize(&mcHmac, mcDigest); 5.3.7.3.2 CRYPT_HMAC_Finalize Function C int CRYPT_HMAC_Finalize( CRYPT_HMAC_CTX*, unsigned char* ); Description This function completes the HMAC calculations. The results are placed in the location pointed to by digest. Preconditions The CRYPT_HMAC_CTX context must be initialized using the CRYPT_HMAC_SetKey function prior to any call to this function. Parameters Parameters Description hmac Pointer to context which saves state between calls. digest Pointer to place to put the final HMAC digest results. Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Remarks The area pointed to by digest must be large enough to hold the results. Example CRYPT_HMAC_CTX mcHmac; byte mcDigest[CRYPT_SHA512_DIGEST_SIZE]; CRYPT_HMAC_SetKey(&mcHmac, CRYPT_HMAC_SHA, key, 4); CRYPT_HMAC_DataAdd(&mcHmac, ourData, OUR_DATA_SIZE); CRYPT_HMAC_Finalize(&mcHmac, mcDigest); 5.3.7.3.3 CRYPT_HMAC_SetKey Function C int CRYPT_HMAC_SetKey( CRYPT_HMAC_CTX*, int, const unsigned char*, unsigned int ); Description This function initializes the HMAC context and set the key for the hash. Preconditions None. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1136 Parameters Parameters Description hmac Pointer to context which saves state between calls. 5.3.7.4 SHA384 Hash Functions 5.3.7.4.1 CRYPT_SHA384_DataAdd Function C int CRYPT_SHA384_DataAdd( CRYPT_SHA384_CTX*, const unsigned char*, unsigned int ); Description This function updates the hash with the data provided. Preconditions The SHA384 context must be initialized prior to the first call of this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha384 Pointer to CRYPT_SHA384_CTX strucure which holds the hash values. input Pointer to the data to use to update the hash. sz Size of the data (in bytes) of the data to use to update the hash. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha384 or input. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA384 hash, nothing must modify the context holding variable between calls to CRYPT_SHA384_DataAdd. Example CRYPT_SHA384_CTX sha384; uint8_t buffer[1024]; uint8_t shaSum[SHA384_DIGEST_SIZE]; CRYPT_SHA384_Initialize(&sha384); CRYPT_SHA384_DataAdd(&sha384, buffer, sizeof(buffer)); CRYPT_SHA384_Finalize(&sha384, shaSum); 5.3.7.4.2 CRYPT_SHA384_Finalize Function C int CRYPT_SHA384_Finalize( CRYPT_SHA384_CTX*, unsigned char* ); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1137 Description This function finalizes the hash and puts the result into digest. Preconditions The SHA384 context must be initialized prior to calling this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha384 Pointer to CRYPT_SHA384_CTX strucure which holds the hash values. digest Pointer to byte array to store hash result. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha384 or digest. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA384 hash, nothing must modify the context holding variable between calls to CRYPT_SHA384_DataAdd and CRYPT_SHA384_Finalize. Example CRYPT_SHA384_CTX sha384; uint8_t buffer[1024]; uint8_t shaSum[SHA384_DIGEST_SIZE]; CRYPT_SHA384_Initialize(&sha384); CRYPT_SHA384_DataAdd(&sha384, buffer, sizeof(buffer)); CRYPT_SHA384_Finalize(&sha384, shaSum); 5.3.7.4.3 CRYPT_SHA384_Initialize Function C int CRYPT_SHA384_Initialize( CRYPT_SHA384_CTX* ); Description This function initializes the internal structures necessary for SHA384 hash calculations. Preconditions None. Parameters Parameters Description sha384 Pointer to CRYPT_SHA384_CTX strucure which holds the hash values. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks All SHA384 hashes have to start at a particular value before adding new data to it. This function sets the necessary values for the structure. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1138 Example CRYPT_SHA384_CTX sha384; uint8_t shaSum[SHA384_DIGEST_SIZE]; CRYPT_SHA384_Initialize(&sha384); CRYPT_SHA384_DataAdd(&sha384, buffer, sizeof(buffer)); CRYPT_SHA384_Finalize(&sha384, shaSum); 5.3.7.5 SHA256 Hash Functions 5.3.7.5.1 CRYPT_SHA256_DataAdd Function C int CRYPT_SHA256_DataAdd( CRYPT_SHA256_CTX*, const unsigned char*, unsigned int ); Description This function updates the hash with the data provided. Preconditions The SHA256 context must be initialized prior to the first call of this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha256 Pointer to CRYPT_SHA256_CTX strucure which holds the hash values. input Pointer to the data to use to update the hash. sz Size of the data (in bytes) of the data to use to update the hash. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha256 or input. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA256 hash, nothing must modify the context holding variable between calls to CRYPT_SHA256_DataAdd. Example CRYPT_SHA256_CTX sha256; uint8_t buffer[1024]; uint8_t shaSum[SHA256_DIGEST_SIZE]; CRYPT_SHA256_Initialize(&sha256); CRYPT_SHA256_DataAdd(&sha256, buffer, sizeof(buffer)); CRYPT_SHA256_Finalize(&sha256, shaSum); 5.3.7.5.2 CRYPT_SHA256_Finalize Function C int CRYPT_SHA256_Finalize( 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1139 CRYPT_SHA256_CTX*, unsigned char* ); Description This function finalizes the hash and puts the result into digest. Preconditions The SHA256 context must be initialized prior to calling this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha256 Pointer to CRYPT_SHA256_CTX strucure which holds the hash values. digest Pointer to byte array to store hash result. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha or digest. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA256 hash, nothing must modify the context holding variable between calls to CRYPT_SHA256_DataAdd and CRYPT_SHA256_Finalize. Example CRYPT_SHA256_CTX sha256; uint8_t buffer[1024]; uint8_t shaSum[SHA256_DIGEST_SIZE]; CRYPT_SHA256_Initialize(&sha256); CRYPT_SHA256_DataAdd(&sha256, buffer, sizeof(buffer)); CRYPT_SHA256_Finalize(&sha256, shaSum); 5.3.7.5.3 CRYPT_SHA256_Initialize Function C int CRYPT_SHA256_Initialize( CRYPT_SHA256_CTX* ); Description This function initializes the internal structures necessary for SHA256 hash calculations. Preconditions None. Parameters Parameters Description sha256 Pointer to context which saves state between calls. Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Remarks All SHA hashes have to start at a particular value before adding new data to it. This function sets the necessary values for the 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1140 structure. Example CRYPT_SHA256_CTX sha; uint8_t shaSum[SHA256_DIGEST_SIZE]; CRYPT_SHA256_Initialize(&sha); CRYPT_SHA256_DataAdd(&sha, buffer, sizeof(buffer)); CRYPT_SHA256_Finalize(&sha, shaSum); 5.3.7.6 SHA Hash functions 5.3.7.6.1 CRYPT_SHA_DataAdd Function C int CRYPT_SHA_DataAdd( CRYPT_SHA_CTX*, const unsigned char*, unsigned int ); Description This function updates the hash with the data provided. Preconditions The SHA context must be initialized prior to the first call of this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha Pointer to CRYPT_SHA_CTX strucure which holds the hash values. input Pointer to the data to use to update the hash. sz Size of the data (in bytes) of the data to use to update the hash. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha or input. • 0 - Otherwise. Remarks In order to preserve the validity of the SHA hash, nothing must modify the context holding variable between calls to CRYPT_SHA_DataAdd. Example CRYPT_SHA_CTX sha; uint8_t buffer[1024]; uint8_t shaSum[SHA_DIGEST_SIZE]; CRYPT_SHA_Initialize(&sha); CRYPT_SHA_DataAdd(&sha, buffer, sizeof(buffer)); CRYPT_SHA_Finalize(&sha, shaSum); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1141 5.3.7.6.2 CRYPT_SHA_Finalize Function C int CRYPT_SHA_Finalize( CRYPT_SHA_CTX*, unsigned char* ); Description This function finalizes the hash and puts the result into digest. Preconditions The SHA context must be initialized prior to calling this function. The context must not be modified by code outside of this function. Parameters Parameters Description sha Pointer to CRYPT_SHA_CTX strucure which holds the hash values. digest Pointer to byte array to store hash result. Returns BAD_FUNC_ARG - An invalid pointer was passed to the function, either in sha or digest. 0 - Otherwise. Remarks In order to preserve the validity of the SHA hash, nothing must modify the context holding variable between calls to CRYPT_SHA_DataAdd and CRYPT_SHA_Finalize. Example CRYPT_SHA_CTX sha; uint8_t buffer[1024]; uint8_t shaSum[SHA_DIGEST_SIZE]; CRYPT_SHA_Initialize(&sha); CRYPT_SHA_DataAdd(&sha, buffer, sizeof(buffer)); CRYPT_SHA_Finalize(&sha, shaSum); 5.3.7.6.3 CRYPT_SHA_Initialize Function C int CRYPT_SHA_Initialize( CRYPT_SHA_CTX* ); Description This function initializes the internal structures necessary for SHA hash calculations. Preconditions None. Parameters Parameters Description sha Pointer to CRYPT_SHA_CTX strucure which holds the hash values. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1142 Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks All SHA hashes have to start at a particular value before adding new data to it. This function sets the necessary values for the structure. Example CRYPT_SHA_CTX sha; uint8_t shaSum[SHA_DIGEST_SIZE]; CRYPT_SHA_Initialize(&sha); CRYPT_SHA_DataAdd(&sha, buffer, sizeof(buffer)); CRYPT_SHA_Finalize(&sha, shaSum); 5.3.7.7 Random Number Generator Functions 5.3.7.7.1 CRYPT_RNG_BlockGenerate Function C int CRYPT_RNG_BlockGenerate( CRYPT_RNG_CTX*, unsigned char*, unsigned int ); Description This function generates several random numbers and places them in the space allocated. Preconditions RNG context was initialized using the CRYPT_RNG_Initialize function. Parameters Parameters Description rng Pointer to context which saves state between calls. b Pointer to buffer to store the random numbers. sz Number of 8-bit random numbers to generate. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Example #define RANDOM_BYTE_SZ 32 int ret; CRYPT_RNG_CTX mcRng; byte out[RANDOM_BYTE_SZ]; ret = CRYPT_RNG_Initialize(&mcRng); ret = CRYPT_RNG_Get(&mcRng, &out[0]); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1143 ret = CRYPT_RNG_BlockGenerate(&mcRng, out, RANDOM_BYTE_SZ); 5.3.7.7.2 CRYPT_RNG_Get Function C int CRYPT_RNG_Get( CRYPT_RNG_CTX*, unsigned char* ); Description This function gets one random number from the random number generator. Preconditions RNG context was initialized using the CRYPT_RNG_Initialize function. Parameters Parameters Description rng Pointer to context which saves state between calls. b Pointer to 8-bit location to store the result. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • <0 - An error occurred. • 0 or positive - Success. Example #define RANDOM_BYTE_SZ 32 int ret; CRYPT_RNG_CTX mcRng; byte out[RANDOM_BYTE_SZ]; ret = CRYPT_RNG_Initialize(&mcRng); ret = CRYPT_RNG_Get(&mcRng, &out[0]); ret = CRYPT_RNG_BlockGenerate(&mcRng, out, RANDOM_BYTE_SZ); 5.3.7.7.3 CRYPT_RNG_Initialize Function C int CRYPT_RNG_Initialize( CRYPT_RNG_CTX* ); Description This function initializes the context that stores information relative to random number generation. Preconditions None. Parameters Parameters Description rng Pointer to random number generator context. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1144 Returns • negative - An error occurred setting up the random number generator. • 0 - Otherwise. Example #define RANDOM_BYTE_SZ 32 int ret; CRYPT_RNG_CTX mcRng; byte out[RANDOM_BYTE_SZ]; ret = CRYPT_RNG_Initialize(&mcRng); ret = CRYPT_RNG_Get(&mcRng, &out[0]); ret = CRYPT_RNG_BlockGenerate(&mcRng, out, RANDOM_BYTE_SZ); 5.3.7.8 Compression Functions 5.3.7.8.1 CRYPT_HUFFMAN_Compress Function C int CRYPT_HUFFMAN_Compress( unsigned char*, unsigned int, const unsigned char*, unsigned int, unsigned int ); Description This function compresses a block of data using Huffman encoding. Preconditions None. Parameters Parameters Description out Pointer to location to store the compressed data. outSz Maximum size of the output data in bytes. in Point to location of source data. inSz Size of the input data in bytes. flags Flags to control how compress operates Returns • negative - error code • positive - bytes stored in out buffer Remarks Output buffer must be large enough to hold the contents of the operation. Example const unsigned char text[] = "..."; 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1145 unsigned int inSz = sizeof(text); unsigned int outSz; unsigned char cBuffer[1024]; int ret; ret = CRYPT_HUFFMAN_COMPRESS(cBuffer, sizeof(cBuffer), text, inSz, 0); 5.3.7.8.2 CRYPT_HUFFMAN_DeCompress Function C int CRYPT_HUFFMAN_DeCompress( unsigned char*, unsigned int, const unsigned char*, unsigned int ); Description This function decompresses a block of data using Huffman encoding. Preconditions None. Parameters Parameters Description out Pointer to destination buffer outSz Size of destination buffer in Pointer to source buffer to decompres inSz Size of source buffer to decompress Returns • negative - Error code • positive - Bytes stored in out buffer Remarks Output buffer must be large enough to hold the contents of the operation. Example unsigned char cBuffer[1024]; unsigned char dBuffer[1024]; int ret ret = CRYPT_HUFFMAN_DeCompress(dBuffer, sizeof(dBuffer), cBuffer, msglen); 5.3.7.9 ECC Encryption/Decryption Functions 5.3.7.9.1 CRYPT_ECC_DHE_KeyMake Function C int CRYPT_ECC_DHE_KeyMake( CRYPT_ECC_CTX*, CRYPT_RNG_CTX*, 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1146 int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.2 CRYPT_ECC_DHE_SharedSecretMake Function C int CRYPT_ECC_DHE_SharedSecretMake( CRYPT_ECC_CTX*, CRYPT_ECC_CTX*, unsigned char*, unsigned int, unsigned int* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.3 CRYPT_ECC_DSA_HashSign Function C int CRYPT_ECC_DSA_HashSign( CRYPT_ECC_CTX*, CRYPT_RNG_CTX*, unsigned char*, unsigned int, unsigned int*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1147 Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.4 CRYPT_ECC_DSA_HashVerify Function C int CRYPT_ECC_DSA_HashVerify( CRYPT_ECC_CTX*, const unsigned char*, unsigned int, unsigned char*, unsigned int, int* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.5 CRYPT_ECC_Free Function C int CRYPT_ECC_Free( CRYPT_ECC_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.6 CRYPT_ECC_Initialize Function C int CRYPT_ECC_Initialize( CRYPT_ECC_CTX* ); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1148 Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.7 CRYPT_ECC_KeySizeGet Function C int CRYPT_ECC_KeySizeGet( CRYPT_ECC_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.8 CRYPT_ECC_PrivateImport Function C int CRYPT_ECC_PrivateImport( CRYPT_ECC_CTX*, const unsigned char*, unsigned int, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1149 5.3.7.9.9 CRYPT_ECC_PublicExport Function C int CRYPT_ECC_PublicExport( CRYPT_ECC_CTX*, unsigned char*, unsigned int, unsigned int* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.10 CRYPT_ECC_PublicImport Function C int CRYPT_ECC_PublicImport( CRYPT_ECC_CTX*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.9.11 CRYPT_ECC_SignatureSizeGet Function C int CRYPT_ECC_SignatureSizeGet( CRYPT_ECC_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1150 Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.10 Triple DES (3DES) Encryption/Decryption Functions 5.3.7.10.1 CRYPT_TDES_CBC_Decrypt Function C int CRYPT_TDES_CBC_Decrypt( CRYPT_TDES_CTX*, unsigned char*, const unsigned char*, unsigned int ); Description This function decrypts a block of data using a Triple DES algorithm. Preconditions The context tdes must be set earlier using CRYPT_TDES_KeySet. The input block must be a multiple of 8 bytes long. Parameters Parameters Description tdes Pointer to context which saves state between calls. out Pointer to output buffer to store the results. in Pointer to input buffer for the source of the data. inSz Size of the input data buffer. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks Input data must have a length a multiple of 8 bytes. Output data will be zero-padded at the end if the original data was not a multiple of 8 bytes long. Example CRYPT_TDES_CTX mcDes3; int ret; byte out1[TDES_SIZE]; byte out2[TDES_SIZE]; strncpy((char*)key, "1234567890abcdefghijklmn", 24); strncpy((char*)iv, "12345678", 8); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_ENCRYPTION); ret = CRYPT_TDES_CBC_Encrypt(&mcDes3, out1, ourData, TDES_SIZE); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_DECRYPTION); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1151 ret = CRYPT_TDES_CBC_Decrypt(&mcDes3, out2, out1, TDES_TEST_SIZE); 5.3.7.10.2 CRYPT_TDES_CBC_Encrypt Function C int CRYPT_TDES_CBC_Encrypt( CRYPT_TDES_CTX*, unsigned char*, const unsigned char*, unsigned int ); Description This function encrypts a block of data using a Triple DES algorithm. Preconditions The context tdes must be set earlier using CRYPT_TDES_KeySet. The input block must be a multiple of 8 bytes long. Parameters Parameters Description tdes Pointer to context which saves state between calls. out Pointer to output buffer to store the results. in Pointer to input buffer for the source of the data. inSz Size of the input data buffer. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks The input data must be padded at the end with zeros to make the length a multiple of 8. Example CRYPT_TDES_CTX mcDes3; int ret; byte out1[TDES_SIZE]; byte out2[TDES_SIZE]; strncpy((char*)key, "1234567890abcdefghijklmn", 24); strncpy((char*)iv, "12345678", 8); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_ENCRYPTION); ret = CRYPT_TDES_CBC_Encrypt(&mcDes3, out1, ourData, TDES_SIZE); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_DECRYPTION); ret = CRYPT_TDES_CBC_Decrypt(&mcDes3, out2, out1, TDES_TEST_SIZE); 5.3.7.10.3 CRYPT_TDES_IvSet Function C int CRYPT_TDES_IvSet( CRYPT_TDES_CTX*, const unsigned char* ); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1152 Description This function changes the IV of a TDES context, but leaves the Key alone. Preconditions None. Parameters Parameters Description tdes Pointer to context which saves state between calls. iv Pointer to buffer holding the initialization vector. Must be 8 bytes in size. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks The IV must be 8 bytes long. Example CRYPT_TDES_CTX mcDes3; int ret; byte out1[TDES_SIZE]; byte out2[TDES_SIZE]; strncpy((char*)key, "1234567890abcdefghijklmn", 24); strncpy((char*)iv, "12345678", 8); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_ENCRYPTION); ret = CRYPT_TDES_IvSet(&mcDes3, iv); ret = CRYPT_TDES_CBC_Encrypt(&mcDes3, out1, ourData, TDES_SIZE); ret = CRYPT_TDES_KeySet(&mcDes3, key, iv, CRYPT_TDES_DECRYPTION); ret = CRYPT_TDES_CBC_Decrypt(&mcDes3, out2, out1, TDES_TEST_SIZE); 5.3.7.10.4 CRYPT_TDES_KeySet Function C int CRYPT_TDES_KeySet( CRYPT_TDES_CTX*, const unsigned char*, const unsigned char*, int ); Description This function sets the key and initialization vector (IV) for a set of Triple-DES operations. Preconditions None. Parameters Parameters Description tdes Pointer to context which saves state between calls. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1153 key Pointer to buffer holding the key. Must be 24 bytes in size. iv Pointer to buffer holding the initialization vector. Must be 8 bytes in size. 5.3.7.11 RSA Encryption/Decryption Functions 5.3.7.11.1 CRYPT_RSA_EncryptSizeGet Function C int CRYPT_RSA_EncryptSizeGet( CRYPT_RSA_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.11.2 CRYPT_RSA_Free Function C int CRYPT_RSA_Free( CRYPT_RSA_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.11.3 CRYPT_RSA_Initialize Function C int CRYPT_RSA_Initialize( CRYPT_RSA_CTX* ); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1154 Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.11.4 CRYPT_RSA_PrivateDecrypt Function C int CRYPT_RSA_PrivateDecrypt( CRYPT_RSA_CTX*, unsigned char*, unsigned int, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.11.5 CRYPT_RSA_PrivateKeyDecode Function C int CRYPT_RSA_PrivateKeyDecode( CRYPT_RSA_CTX*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1155 5.3.7.11.6 CRYPT_RSA_PublicEncrypt Function C int CRYPT_RSA_PublicEncrypt( CRYPT_RSA_CTX*, unsigned char*, unsigned int, const unsigned char*, unsigned int, CRYPT_RNG_CTX* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.11.7 CRYPT_RSA_PublicKeyDecode Function C int CRYPT_RSA_PublicKeyDecode( CRYPT_RSA_CTX*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12 AES Encryption/Decryption Functions 5.3.7.12.1 CRYPT_AES_CBC_Decrypt Function C int CRYPT_AES_CBC_Decrypt( CRYPT_AES_CTX*, unsigned char*, const unsigned char*, 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1156 unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12.2 CRYPT_AES_CBC_Encrypt Function C int CRYPT_AES_CBC_Encrypt( CRYPT_AES_CTX*, unsigned char*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12.3 CRYPT_AES_CTR_Encrypt Function C int CRYPT_AES_CTR_Encrypt( CRYPT_AES_CTX*, unsigned char*, const unsigned char*, unsigned int ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1157 Remarks ctr (counter), use Encrypt both ways with ENCRYPT key setup Example 5.3.7.12.4 CRYPT_AES_DIRECT_Decrypt Function C int CRYPT_AES_DIRECT_Decrypt( CRYPT_AES_CTX*, unsigned char*, const unsigned char* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12.5 CRYPT_AES_DIRECT_Encrypt Function C int CRYPT_AES_DIRECT_Encrypt( CRYPT_AES_CTX*, unsigned char*, const unsigned char* ); Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12.6 CRYPT_AES_IvSet Function C int CRYPT_AES_IvSet( CRYPT_AES_CTX*, const unsigned char* ); 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1158 Parameters Parameters Description Param1 Pointer to context which saves state between calls. Param2 Param3 - Param4 Param5 - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.12.7 CRYPT_AES_KeySet Function C int CRYPT_AES_KeySet( CRYPT_AES_CTX*, const unsigned char*, unsigned int, const unsigned char*, int ); Parameters Parameters Description aes Pointer to context which saves state between calls. key keyLen - iv dir - Returns *BAD_FUNC_ARG - An invalid pointer was passed to the function. *0 - Otherwise. Example 5.3.7.13 MD5 Functions 5.3.7.13.1 CRYPT_MD5_DataAdd Function C int CRYPT_MD5_DataAdd( CRYPT_MD5_CTX*, const unsigned char*, unsigned int ); Description This function updates the hash with the data provided. Preconditions The MD5 context must be initialized prior to the first call of this function. The context must not be modified by code outside of this function. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1159 Parameters Parameters Description md5 Pointer to CRYPT_MD5_CTX strucure which holds the hash values. input Pointer to the data to use to update the hash. sz Size of the data (in bytes) of the data to use to update the hash. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in md5 or input. • 0 - Otherwise. Remarks In order to preserve the validity of the MD5 hash, nothing must modify the context holding variable between calls to CRYPT_MD5_DataAdd. Example CRYPT_MD5_CTX md5; uint8_t buffer[1024]; uint8_t md5sum[MD5_DIGEST_SIZE]; CRYPT_MD5_Initialize(&md5); CRYPT_MD5_DataAdd(&md5, buffer, sizeof(buffer)); CRYPT_MD5_Finalize(&md5, md5sum); 5.3.7.13.2 CRYPT_MD5_Finalize Function C int CRYPT_MD5_Finalize( CRYPT_MD5_CTX*, unsigned char* ); Description This function finalizes the hash and puts the result into digest. Preconditions The MD5 context must be initialized prior to calling this function. The context must not be modified by code outside of this function. Parameters Parameters Description md5 Pointer to CRYPT_MD5_CTX strucure which holds the hash values. digest Pointer to byte array to store hash result. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function, either in md5 or digest. • 0 - Otherwise. Remarks In order to preserve the validity of the MD5 hash, nothing must modify the context holding variable between calls to CRYPT_MD5_DataAdd and CRYPT_MD5_Finalize. Example CRYPT_MD5_CTX md5; 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1160 uint8_t buffer[1024]; uint8_t md5sum[MD5_DIGEST_SIZE]; CRYPT_MD5_Initialize(&md5); CRYPT_MD5_DataAdd(&md5, buffer, sizeof(buffer)); CRYPT_MD5_Finalize(&md5, md5sum); 5.3.7.13.3 CRYPT_MD5_Initialize Function C int CRYPT_MD5_Initialize( CRYPT_MD5_CTX* md5 ); Description This function initializes the internal structures necessary for MD5 hash calculations. Preconditions None. Parameters Parameters Description md5 Pointer to CRYPT_MD5_CTX strucure which holds the hash values. Returns • BAD_FUNC_ARG - An invalid pointer was passed to the function. • 0 - Otherwise. Remarks All MD5 hashes have to start at a particular value before adding new data to it. This function sets the necessary values for the structure. Example CRYPT_MD5_CTX md5; uint8_t buffer[1024]; uint8_t md5sum[MD5_DIGEST_SIZE]; CRYPT_MD5_Initialize(&md5); CRYPT_MD5_DataAdd(&md5, buffer, sizeof(buffer)); CRYPT_MD5_Finalize(&md5, md5sum); 5.3.7.14 Data Types and Constants 5.3.7.14.1 CRYPT_AES_CTX Structure C struct CRYPT_AES_CTX { int holder[69]; }; Description AES 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1161 Members Members Description int holder[69]; big enough to hold internal, but check on init 5.3.7.14.2 CRYPT_ECC_CTX Structure C struct CRYPT_ECC_CTX { void* holder; }; Description ECC 5.3.7.14.3 CRYPT_HMAC_CTX Structure C struct CRYPT_HMAC_CTX { long long holder[67]; }; Description HMAC Members Members Description long long holder[67]; big enough to hold internal, but check on init 5.3.7.14.4 CRYPT_MD5_CTX Structure C struct CRYPT_MD5_CTX { int holder[24]; }; Description MD5 Members Members Description int holder[24]; big enough to hold internal, but check on init 5.3.7.14.5 CRYPT_RNG_CTX Structure C struct CRYPT_RNG_CTX { int holder[66]; }; Description RNG 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1162 Members Members Description int holder[66]; big enough to hold internal, but check on init 5.3.7.14.6 CRYPT_RSA_CTX Structure C struct CRYPT_RSA_CTX { void* holder; }; Description RSA 5.3.7.14.7 CRYPT_SHA_CTX Structure C struct CRYPT_SHA_CTX { int holder[24]; }; Description SHA Members Members Description int holder[24]; big enough to hold internal, but check on init 5.3.7.14.8 CRYPT_SHA256_CTX Structure C struct CRYPT_SHA256_CTX { int holder[28]; }; Description SHA-256 Members Members Description int holder[28]; big enough to hold internal, but check on init 5.3.7.14.9 CRYPT_SHA384_CTX Structure C struct CRYPT_SHA384_CTX { long long holder[32]; }; Description SHA-384 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Library Interface 5-1163 Members Members Description long long holder[32]; big enough to hold internal, but check on init 5.3.7.14.10 CRYPT_SHA512_CTX Structure C struct CRYPT_SHA512_CTX { long long holder[36]; }; Description SHA-512 Members Members Description long long holder[36]; big enough to hold internal, but check on init 5.3.7.14.11 CRYPT_TDES_CTX Structure C struct CRYPT_TDES_CTX { int holder[100]; }; Description TDES Members Members Description int holder[100]; big enough to hold internal, but check on init 5.3.7.14.12 MC_CRYPTO_API_H Macro C #define MC_CRYPTO_API_H Description Defines Microchip CRYPTO API layer 5.3.8 Files Files Name Description crypto.h Crypto Framework Libarary header for cryptographic functions. Description 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Files 5-1164 5.3.8.1 crypto.h Crypto Framework Library Header This header file contains function prototypes and definitions of the data types and constants that make up the Cryptographic Framework Library for PIC32 families of Microchip microcontrollers. Functions Name Description CRYPT_AES_CBC_Decrypt CRYPT_AES_CBC_Encrypt CRYPT_AES_CTR_Encrypt CRYPT_AES_DIRECT_Decrypt Direct encryption of one block of data. CRYPT_AES_DIRECT_Encrypt Direct encryption of one block of data. CRYPT_AES_IvSet CRYPT_AES_KeySet CRYPT_ECC_DHE_KeyMake CRYPT_ECC_DHE_SharedSecretMake CRYPT_ECC_DSA_HashSign CRYPT_ECC_DSA_HashVerify CRYPT_ECC_Free CRYPT_ECC_Initialize CRYPT_ECC_KeySizeGet CRYPT_ECC_PrivateImport CRYPT_ECC_PublicExport CRYPT_ECC_PublicImport CRYPT_ECC_SignatureSizeGet CRYPT_ERROR_StringGet CRYPT_HMAC_DataAdd Add data to the HMAC calculation. CRYPT_HMAC_Finalize Complete the HMAC calculation and get the results. CRYPT_HMAC_SetKey Initialize the HMAC context and set the key for the hash. CRYPT_HUFFMAN_Compress Compress a block of data. CRYPT_HUFFMAN_DeCompress Decompress a block of data. CRYPT_MD5_DataAdd Updates the hash with the data provided. CRYPT_MD5_Finalize Finalizes the hash and puts the result into digest. CRYPT_MD5_Initialize Initializes the internal structures necessary for MD5 hash calculations. CRYPT_RNG_BlockGenerate Create several random numbers. CRYPT_RNG_Get Get one random number. CRYPT_RNG_Initialize Initialize random number generator. CRYPT_RSA_EncryptSizeGet CRYPT_RSA_Free CRYPT_RSA_Initialize CRYPT_RSA_PrivateDecrypt CRYPT_RSA_PrivateKeyDecode CRYPT_RSA_PublicEncrypt 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Files 5-1165 CRYPT_RSA_PublicKeyDecode CRYPT_SHA_DataAdd Updates the hash with the data provided. CRYPT_SHA_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA_Initialize Initializes the internal structures necessary for SHA hash calculations. CRYPT_SHA256_DataAdd Updates the hash with the data provided. CRYPT_SHA256_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA256_Initialize Initializes the internal structures necessary for SHA256 hash calculations. CRYPT_SHA384_DataAdd Updates the hash with the data provided. CRYPT_SHA384_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA384_Initialize Initializes the internal structures necessary for SHA384 hash calculations. CRYPT_SHA512_DataAdd Updates the hash with the data provided. CRYPT_SHA512_Finalize Finalizes the hash and puts the result into digest. CRYPT_SHA512_Initialize Initializes the internal structures necessary for SHA512 hash calculations. CRYPT_TDES_CBC_Decrypt Decrypt a data block using Triple DES. CRYPT_TDES_CBC_Encrypt Encrypt a data block using Triple DES. CRYPT_TDES_IvSet Set the Initialization Vector (IV) for a Triple DES operation. CRYPT_TDES_KeySet Initialization of Triple DES context. Macros Name Description MC_CRYPTO_API_H Defines Microchip CRYPTO API layer Structures Name Description CRYPT_AES_CTX AES CRYPT_ECC_CTX ECC CRYPT_HMAC_CTX HMAC CRYPT_MD5_CTX MD5 CRYPT_RNG_CTX RNG CRYPT_RSA_CTX RSA CRYPT_SHA_CTX SHA CRYPT_SHA256_CTX SHA-256 CRYPT_SHA384_CTX SHA-384 CRYPT_SHA512_CTX SHA-512 CRYPT_TDES_CTX TDES Company Microchip Technology Inc. 5.3 Cryptographic (Crypto) Library MPLAB Harmony Help Files 5-1166 5.4 Math Library Help 5.4.1 DSP Fixed-Point Library 5.4.1.1 Introduction DSP Fixed-Point Library for Microchip Microcontrollers The DSP Fixed-Point Library is available for the PIC32MZ family of microcontrollers. This library was created from optimized assembly routines written specifically for the microAptivTM core. Description The DSP Fixed-Point Library contains building block functions for developing digital signal processing algorithms. The library supports the Q15 and Q31 fractional data formats. The functions are implemented in efficient assembly specifically targeted at the DSP extensions in this core family. The library makes these functions available in a simple C-callable structure. Functions included in the DSP Fixed-Point Library include complex math, vector math, matrix math, digital filters, and transforms. In many cases, these functions require specific data structures to operate, which are detailed in the header file and examples. 5.4.1.2 Release Notes MPLAB Harmony Version: v0.70b DSP Fixed-Point Library Version : 1.0 Release Date: 18Nov2013 New This Release: • 98 functions: • Vector math • Complex math • Transforms • Digital Filters • Matrix math • 16-bit and 32-bit fixed-point integer functions • Optimized in high performance assembly 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1167 Known Issues: • Optimized for PIC32MZ microAptivTM core only • Will not function with _Fract data type 5.4.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.4.1.4 Using the Library This topic describes the basic architecture of the DSP Fixed-Point Library and provides information and examples on how to use it. Interface Header File: dsp.h, libq.h The interface to the DSP Fixed-Point library is defined in the "dsp.h" header file. Any C language source (.c) file that uses the DSP Fixed-Point library must include "dsp.h". Some functions make special use of the optimized fixed-point math library libq.h. For use of those functions, the libq.h file must also be included in a project. The libq.h file is also installed with MPLAB Harmony. Specific notes within each function will describe if the function is dependent on the libq library. Library File: dsp.a, libq.a The DSP Fixed-Point library archive (.a) file installed with MPLAB Harmony. This library is only available in binary form, with prototypes for each function described in the dsp.h file. In the case of functions that are supported by libq, the fixed-point math function library, the libq.a library must also be installed. This library is also available in binary form and is installed with MPLAB Harmony. 5.4.1.4.1 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the DSP Fixed-Point Library. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1168 Library Interface Section Description Complex Math Functions General mathematical operations using a complex structure with the form (a + bi) Vector Math Functions Mathematical operations on a array of numbers or vector Matrix Math Functions Mathematical operations on a matrix Digital Filtering Functions FIR and IIR filtering functions with various architectures Digital Transform Functions FFT, Windows and related transform elements Support Functions Quick support functions for numerical transform The DSP Fixed-Point Library uses fixed-point fractional functions to optimize execution speed. These functions limit the accuracy of the calculations to the bits specified for the function. Due to parallelism in some operations, the 16-bit version of the functions are more efficient than their 32-bit counterparts. In many cases both 16-bit and 32-bit functions are available to give the user the choice of balance between speed and functional resolution. Fractional representation of a real number is given by: Qn.m where: • n is the number of data bits to the left of the radix point • m is the number of data bits to the right of the radix point • a signed bit is implied, and takes one bit of resolution • Shorthand may eliminate the leading 0, such as in Q0.15, which may be shortened to Q15, and similarly Q0.31, which is shortened to Q31 Qn.m numerical values are used by the library processing data as integers. In this format the n represents the number of integer bits, and the m represents the number of fractional bits. All values assume a sign bit in the most significant bit. Therefore, the range of the numerical value is: -2(n-1) to [2(n-1) - 2(-m)]; with a resolution of 2(-m) . A Q16 format number (Q15.16) would range from -32768.0 (0x8000 0000) to 32767.99998474 with a precision of 0.000015259 (or 2-16). For example, a numerical representation of the number 3.14159 in Q2.13 notation would be: 3.14159 * 213 = 25735.9 => 0x6488 And converting from the Q7.8 format with the value 0x1D89 would be: 0x1D89 / 28 = 7561 / 256 => 29.5316, accurate to 0.00391 A majority of the DSP Fixed-Point Library uses functions with variables in Q15 or Q31 format. Representations of these numbers are given in the Types section of this document, and generally are int16_t(for Q15 fractional representation) and int32_t (for Q31 fractional representation). This limits the equivalent numerical range to roughly -1.0 to 0.999999999. It is possible to represent other number ranges, but scaling before and after the function call are necessary. All library functions will saturate the output if the value exceeds the maximum or is lower than the minimum allowable value for that resolution. Some pre-scaling may be necessary to prevent unwanted saturation in functions that may otherwise create calculation errors. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1169 5.4.1.4.2 Table of Library Functions Family Function Definition Complex Math Addition DSP_ComplexAdd32 Conjugate DSP_ComplexConj32 Dot Product DSP_ComplexDotProd32 Multiplication DSP_ComplexMult32 Scalar Multiplication DSP_ComplexScalarMult32 Subtraction DSP_ComplexSub32 Digital Filter FIR DSP_FilterFIR32 FIR Decimation DSP_FilterFIRDecim32 FIR Interpolation DSP_FilterFIRInterp32 FIR LMS DSP_FilterLMS16 IIR DSP_FilterIIR16; DSP_FilterIIRSetup16 IIR Biquad DSP_FilterIIRBQ16; DSP_FilterIIRBQ16_fast; DSP_FilterIIRBQ32 IIR Biquad Cascade DSP_FilterIIRBQ16_cascade8; DSP_FilterIIRBQ16_cascade8_fast IIR Biquad Parallel DSP_FilterIIRBQ16_parallel8; DSP_FilterIIRBQ16_parallel8_fast Matrix Math Addition DSP_MatrixAdd32 Equality DSP_MatrixEqual32 Initialization DSP_MatrixInit32 Multiplication DSP_MatrixMul32 Scale DSP_MatrixScale32 Subtraction DSP_MatrixSub32 Transpose DSP_MatrixTranspose32 Transform FFT DSP_TransformFFT16; DSP_TransformFFT32 Setup factors DSP_TransformFFT16_setup; DSP_TransformFFT32_setup inverse FFT DSP_TransformIFFT16 Windows DSP_TransformWindow_Bart16; DSP_TransformWindow_Bart32; DSP_TransformWindow_Black16; DSP_TransformWindow_Black32; DSP_TransformWindow_Cosine16; DSP_TransformWindow_Cosine32; DSP_TransformWindow_Hamm16; DSP_TransformWindow_Hamm32; DSP_TransformWindow_Hann16; DSP_TransformWindow_Hann32; DSP_TransformWindow_Kaiser16; DSP_TransformWindow_Kaiser32; Window Initialization DSP_TransformWinInit_Bart16; DSP_TransformWinInit_Bart32; DSP_TransformWinInit_Black16; DSP_TransformWinInit_Black32; DSP_TransformWinInit_Cosine16; DSP_TransformWinInit_Cosine32; DSP_TransformWinInit_Hamm16; DSP_TransformWinInit_Hamm32; DSP_TransformWinInit_Hann16; DSP_TransformWinInit_Hann32; DSP_TransformWinInit_Kaiser16; DSP_TransformWinInit_Kaiser32 Vector Math Absolute value DSP_VectorAbs16; DSP_VectorAbs32 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1170 Addition DSP_VectorAdd16; DSP_VectorAdd32 Addition w/ constant DSP_VectorAddc16; DSP_VectorAddc32 Binary exponent DSP_VectorBexp16; DSP_VectorBexp32 Log, Exponent, Square root DSP_VectorExp; DSP_VectorLog10; DSP_VectorLog2; DSP_VectorLn; DSP_VectorSqrt; Multiplication & Division DSP_VectorMul16; DSP_VectorMul32; DSP_VectorDotp16; DSP_VectorDotp32; DSP_VectorMulc16; DSP_VectorMulc32; DSP_VectorDivC; DSP_VectorRecip Subtraction DSP_VectorSub16; DSP_VectorSub32 Power (sum of squares) DSP_VectorSumSquares16; DSP_VectorSumSquares32 Equality check DSP_VectorChkEqu32 Maximum DSP_VectorMax32; DSP_VectorMaxIndex32 Minimum DSP_VectorMin32; DSP_VectorMinIndex32 Copy & Fill DSP_VectorCopy; DSP_VectorFill; DSP_VectorZeroPad Shift DSP_VectorShift; DSP_VectorCopyReverse32 Negate DSP_VectorNegate Statistics DSP_VectorAutocorr16; DSP_VectorMean32; DSP_VectorRMS16; DSP_VectorStdDev16; DSP_VectorVari16; DSP_VectorVariance 5.4.1.5 Library Interface Data Types and Constants Name Description biquad16 Q15 biquad int16c Q15 complex number (a + bi) int32c Q31 complex number (a + bi) matrix32 Q31 matrix PARM_EQUAL_FILTER IIR BQ filter structure Q15 data, Q31 storage PARM_EQUAL_FILTER_16 IIR BQ filter structure Q15 PARM_EQUAL_FILTER_32 IIR BQ filter structure Q31 PARM_FILTER_GAIN filter gain structure _PARM_EQUAL_FILTER IIR BQ filter structure Q15 data, Q31 storage _PARM_EQUAL_FILTER_16 IIR BQ filter structure Q15 _PARM_EQUAL_FILTER_32 IIR BQ filter structure Q31 MAX16 maximum Q15 MAX32 maximum Q31 MIN16 minimum Q15 MIN32 minimum Q31 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1171 Complex Math Functions Name Description DSP_ComplexAdd32 Calculates the sum of two complex numbers. DSP_ComplexConj16 Calculates the complex conjugate of a complex number. DSP_ComplexConj32 Calculates the complex conjugate of a complex number. DSP_ComplexDotProd32 Calculates the dot product of two complex numbers. DSP_ComplexMult32 Multiplies two complex numbers. DSP_ComplexScalarMult32 Multiplies a complex number and a scalar number. DSP_ComplexSub32 Calculates the difference of two complex numbers. Digital Filter Functions Name Description DSP_FilterFIR32 Performs a Finite Infitire Repspose filter on a vector. DSP_FilterFIRDecim32 Performs a decimating FIR filter on the input array. DSP_FilterFIRInterp32 Performs an interpolating FIR filter on the input array. DSP_FilterIIR16 Performs a single-sample cascaded biquad Infiite Impulse Response (IIR) filter. DSP_FilterIIRBQ16 Performs a single-pass IIR Biquad Filter. DSP_FilterIIRBQ16_cascade8 Performs a single IIR Biquad Filter as a cascade of 8 series filters. DSP_FilterIIRBQ16_cascade8_fast Performs a single IIR Biquad Filter as a cascade of 8 series filters. DSP_FilterIIRBQ16_fast Performs a single-pass IIR Biquad Filter. DSP_FilterIIRBQ16_parallel8 Performs a 8 parallel single-pass IIR Biquad Filters, and sums the result. DSP_FilterIIRBQ16_parallel8_fast Performs a 8 parallel single-pass IIR Biquad Filters, and sums the result. DSP_FilterIIRBQ32 Performs a high resolution single-pass IIR Biquad Filter. DSP_FilterIIRSetup16 Converts biquad structure to coeffs array to set up IIR filter. DSP_FilterLMS16 Performs a single sample Least Mean Squares FIR Filter. Matrix Math Functions Name Description DSP_MatrixAdd32 Addition of two matrices C = (A + B). DSP_MatrixEqual32 Equality of two matrices C = (A). DSP_MatrixInit32 Initializes the first N elements of a Matrix to the value num. DSP_MatrixMul32 Multiplication of two matrices C = A x B. DSP_MatrixScale32 Scales each element of an input buffer (matrix) by a fixed number. DSP_MatrixSub32 Subtraction of two matrices C = (A - B). DSP_MatrixTranspose32 Transpose of a Matrix C = A (T). Support Functions Name Description mul16 multiply and shift integer mul16r multiply and shift Q15 mul32 multiply and shift Q31 SAT16 saturate both positive and negative Q15 SAT16N saturate negative Q15 SAT16P saturate positive Q15 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1172 Transform Functions Name Description DSP_TransformFFT16 Creates an Fast Fourier Transform (FFT) from a time domain input. DSP_TransformFFT16_setup Creates FFT coefficients for use in the FFT16 function. DSP_TransformFFT32 Creates an Fast Fourier Transform (FFT) from a time domain input. DSP_TransformFFT32_setup Creates FFT coefficients for use in the FFT32 function. DSP_TransformIFFT16 Creates an Inverse Fast Fourier Transform (FFT) from a frequency domain input. DSP_TransformWindow_Bart16 Perform a Bartlett window on a vector. DSP_TransformWindow_Bart32 Perform a Bartlett window on a vector. DSP_TransformWindow_Black16 Perform a Blackman window on a vector. DSP_TransformWindow_Black32 Perform a Blackman window on a vector. DSP_TransformWindow_Cosine16 Perform a Cosine (Sine) window on a vector. DSP_TransformWindow_Cosine32 Perform a Cosine (Sine) window on a vector. DSP_TransformWindow_Hamm16 Perform a Hamming window on a vector. DSP_TransformWindow_Hamm32 Perform a Hamming window on a vector. DSP_TransformWindow_Hann16 Perform a Hanning window on a vector. DSP_TransformWindow_Hann32 Perform a Hanning window on a vector. DSP_TransformWindow_Kaiser16 Perform a Kaiser window on a vector. DSP_TransformWindow_Kaiser32 Perform a Kaiser window on a vector. DSP_TransformWinInit_Bart16 Create a Bartlett window. DSP_TransformWinInit_Bart32 Create a Bartlett window. DSP_TransformWinInit_Black16 Create a Blackman window. DSP_TransformWinInit_Black32 Create a Blackman window. DSP_TransformWinInit_Cosine16 Create a Cosine (Sine) window. DSP_TransformWinInit_Cosine32 Create a Cosine (Sine) window. DSP_TransformWinInit_Hamm16 Create a Hamming window. DSP_TransformWinInit_Hamm32 Create a Hamming window. DSP_TransformWinInit_Hann16 Create a Hanning window. DSP_TransformWinInit_Hann32 Create a Hanning window. DSP_TransformWinInit_Kaiser16 Create a Kaiser window. DSP_TransformWinInit_Kaiser32 Create a Kaiser window. Vector Math Functions Name Description DSP_VectorAbs16 Calculate the absolute value of a vector. DSP_VectorAbs32 Calculate the absolute value of a vector. DSP_VectorAdd16 Calculate the sum of two vectors. DSP_VectorAdd32 Calculate the sum of two vectors. DSP_VectorAddc16 Calculate the sum of two vectors. DSP_VectorAddc32 Calculate the sum of two vectors. DSP_VectorAutocorr16 Computes the Autocorrelation of a Vector. DSP_VectorBexp16 Computes the maximum binary exponent of a vector. DSP_VectorBexp32 Computes the maximum binary exponent of a vector. DSP_VectorChkEqu32 Compares two input vectors, returns an integer '1' if equal, and '0' if not equal. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1173 DSP_VectorCopy Copies the elements of one vector to another. DSP_VectorCopyReverse32 Reverses the order of elements in one vector and copies them into another. DSP_VectorDivC Divides the first N elements of inVector by a constant divisor, and stores the result in outVector. DSP_VectorDotp16 Computes the dot product of two vectors, and scales the output by a binary factor. DSP_VectorDotp32 Computes the dot product of two vectors, and scales the output by a binary factor DSP_VectorExp Computes the EXP (e^x) of the first N elements of inVector, and stores the result in outVector. DSP_VectorFill Fills an input vector with scalar data. DSP_VectorLn Computes the Natural Log, Ln(x), of the first N elements of inVector, and stores the result in outVector. DSP_VectorLog10 Computes the Log10(x), of the first N elements of inVector, and stores the result in outVector. DSP_VectorLog2 Computes the Log2(x) of the first N elements of inVector, and stores the result in outVector. DSP_VectorMax32 Returns the maximum value of a vector. DSP_VectorMaxIndex32 Returns the index of the maximum value of a vector. DSP_VectorMean32 Calculates the mean average of an input vector. DSP_VectorMin32 Returns the minimum value of a vector. DSP_VectorMinIndex32 Returns the index of the minimum value of a vector. DSP_VectorMul16 Multiplication of a series of numbers in one vector to another vector. DSP_VectorMul32 Multiplication of a series of numbers in one vector to another vector. DSP_VectorMulc16 Multiplication of a series of numbers in one vector to a scalar value. DSP_VectorMulc32 Multiplication of a series of numbers in one vector to a scalar value. DSP_VectorNegate Inverses the sign (negates) the elements of a vector. DSP_VectorRecip Computes the reciprocal (1/x) of the first N elements of inVector, and stores the result in outVector. DSP_VectorRMS16 Computes the root mean square (RMS) value of a vector. DSP_VectorShift Shifts the data index of an input data vector. DSP_VectorSqrt Computes the square root of the first N elements of inVector, and stores the result in outVector. DSP_VectorStdDev16 Computes the Standard Deviation of a Vector. DSP_VectorSub16 Calculate the difference of two vectors. DSP_VectorSub32 Calculate the difference of two vectors. DSP_VectorSumSquares16 Computes the sum of squares of a vector, and scales the output by a binary factor. DSP_VectorSumSquares32 Computes the sum of squares of a vector, and scales the output by a binary factor. DSP_VectorVari16 Computes the variance of N elements of a Vector. DSP_VectorVariance Computes the variance of N elements of inVector. DSP_VectorZeroPad Fills an input vector with zeros. Description This section describes the Application Programming Interface (API) functions of the DSP Fixed-Point Library. Refer to each section for a detailed description. 5.4.1.5.1 Complex Math Functions 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1174 5.4.1.5.1.1 DSP_ComplexAdd32 Function C void DSP_ComplexAdd32( int32c * indata1, int32c * indata2, int32c * Output ); Description Function DSP_ComplexAdd32: void DSP_ComplexAdd32(int32c *indata1, int32c *indata2, int32c *Output); Calculates the sum of two complex numbers, indata1 and indata2, and stores the complex result in Output. Complex numbers must be in the structural form that includes real and imaginary components. The function saturates the output values if maximum or minimum are exceeded. All values are in Q31 fractional data format. (a + bi) + (c + di) => (a + c) + (b + d)i Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata1 pointer to input complex number (int32c) indata2 pointer to input complex number (int32c) Returns pointer to result complex numbers (int32c) None. Remarks None. Example int32c *res, result; int32c *input1, *input2; int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) int32c test_complex_2 = {0x73333333,0xB3333334}; // (0.9 - 0.6i) res=&result; input1=&test_complex_1; input2=&test_complex_2; DSP_ComplexAdd32(input1, input2, res); // result = {0x73333333, 0xC0000000} = (0.9 - 0.5i) 5.4.1.5.1.2 DSP_ComplexConj16 Function C void DSP_ComplexConj16( int16c * indata, int16c * Output ); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1175 Description DSP_ComplexConj16: void DSP_ComplexConj16(int16c *indata, int16c *Output); CCalculates the complex conjugate of Indata, and stores the result in Outdata. Both numbers must be in the complex number data structure which includes real and imaginary components. Values are in Q15 fractional data format. The function will saturate the output if maximum or minimum values are exceeded. (a + bi) => (a - bi) Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata pointer to input complex number (int16c) Returns pointer to result complex numbers (int16c) None. Remarks None. Example int16c *res, result; int16c *input1; int16c test_complex_1 = {0x4000,0x0CCC}; // (0.5 + 0.1i) res=&result; input1=&test_complex_1; DSP_ComplexConj16(input1, res); // result = {0x4000, 0xF334} = (0.5 - 0.1i) 5.4.1.5.1.3 DSP_ComplexConj32 Function C void DSP_ComplexConj32( int32c * indata, int32c * Output ); Description Function DSP_ComplexConj32: void DSP_ComplexConj32(int32c *indata, int32c *Output); Calculates the complex conjugate of indata, and stores the result in Output. Both numbers must be in the complex number data structure, which includes real and imaginary components. Values are in Q31 fractional data format. The function will saturate the output if maximum or minimum values are exceeded. (a + bi) => (a - bi) Preconditions Complex numbers must be in the int32c format. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1176 Parameters Parameters Description indata1 pointer to input complex number (int32c) Returns pointer to result complex numbers (int32c) None. Remarks None. Example int32c *res, result; int32c *input1; int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) res=&result; input1=&test_complex_1; DSP_ComplexConj32(input1, res); // result = {0x40000000, 0xF3333334} = (0.5 - 0.1i) 5.4.1.5.1.4 DSP_ComplexDotProd32 Function C void DSP_ComplexDotProd32( int32c * indata1, int32c * indata2, int32c * Output ); Description Function DSP_ComplexDotProd32: void DSP_ComplexDotProd32(int32c *indata1, int32c *indata2, int32c *Output); Calculates the dot product of two complex numbers, indata1 and indata2, and stores the result in Output. All numbers must be in complex structural format that includes real and imaginary components, and the numbers are in fractional Q31 format. The function will saturate the output if it exceeds maximum or minimum ratings. The formula for the dot product is as follows: Output(real) = (Input1.re * Input2.re) + (Input1.im * Input2.im); Output(img) = [(Input1.re * Input2.im) - (Input1.im * Input2.re)]i (a + bi) dot (c + di) => (a * c + b * d) + (a * d - b * c)i Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata1 pointer to input complex number (int32c) indata2 pointer to input complex number (int32c) Returns pointer to result complex numbers (int32c) None. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1177 Remarks None. Example int32c *res, result; int32c *input1, *input2; int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) int32c test_complex_2 = {0x73333333,0xB3333334}; // (0.9 - 0.6i) res=&result; input1=&test_complex_1; input2=&test_complex_2; DSP_ComplexDotProd32(input1, input2, res); // result = {0x31EB851E, 0xCE147AE3} = (0.39 - 0.39i) 5.4.1.5.1.5 DSP_ComplexMult32 Function C void DSP_ComplexMult32( int32c * indata1, int32c * indata2, int32c * Output ); Description Function DSP_ComplexMult32: void DSP_ComplexMult32(int32c *indata1, int32c *indata2, int32c *Output); Multiplies two complex numbers, indata1 and indata2, and stores the complex result in Output. All numbers must be in the int32c complex data structure. All data is in Q31 fractional format. The function will saturate if maximum or minimum values are exceeded. Output(real) = (Input1.re * Input2.re) - (Input1.im * Input2.im); Output(img) = [(Input1.re * Input2.im) + (Input1.im * Input2.re)]i (a + bi) x (c + di) => (a * c - b * d) + (a * d + b * c)i Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata1 pointer to input complex number (int32c) indata2 pointer to input complex number (int32c) Returns pointer to result complex numbers (int32c) None. Remarks None. Example int32c *res, result; int32c *input1, *input2; int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1178 int32c test_complex_2 = {0x73333333,0xB3333334}; // (0.9 - 0.6i) res=&result; input1=&test_complex_1; input2=&test_complex_2; DSP_ComplexMult32(input1, input2, res); // result = {0x4147AE14, 0xE51EB8551} = (0.51 - 0.21i) 5.4.1.5.1.6 DSP_ComplexScalarMult32 Function C void DSP_ComplexScalarMult32( int32c * indata, int32_t Scalar, int32c * Output ); Description Function DSP_ComplexScalarMult32: void DSP_ComplexScalarMult32(int32c *indata, int32_t Scalar, int32c *Output); Multiplies a complex number, indata, by a scalar number, Scalar, and stores the result in Output. indata and Output must be in int32c structure with real and imaginary components. All data must be in the fractional Q31 format. The function will saturate if maximum or minimum values are exceeded. Output(real) = (Input1.re * Scalar); Output(img) = [(Input1.im * Scalar)]i (a + bi) * C => (a * C + b * Ci) Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata pointer to input complex number (int32c) Scalar fractional scalar input value (int32_t) Returns pointer to result complex numbers (int32c) None. Remarks None. Example int32c *res, result; int32c *input1; int32_t scalarInput = 0x20000000; // 0.25 int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) res=&result; input1=&test_complex_1; DSP_ComplexScalarMult32(input1, scalarInput, res); // result = {0x10000000, 0x03333333} = (0.125 + 0.025i) 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1179 5.4.1.5.1.7 DSP_ComplexSub32 Function C void DSP_ComplexSub32( int32c * indata1, int32c * indata2, int32c * Output ); Description Function DSP_ComplexSub32: void DSP_ComplexSub32(int32c *indata1, int32c *indata2, int32c *Output); Calculates the difference of two complex numbers, indata1 less indata2, and stores the complex result in Output. Both numbers must be in a complex data structure, which includes real and imaginary components. The function saturates the output values if maximum or minimum are exceeded. Real and imaginary components are in the Q31 fractional data format. (a + bi) - (c + di) => (a - c) + (b - d)i Preconditions Complex numbers must be in the int32c format. Parameters Parameters Description indata1 pointer to input complex number (int32c) indata2 pointer to input complex number (int32c) Returns pointer to result complex numbers (int32c) None. Remarks None. Example int32c *res, result; int32c *input1, *input2; int32c test_complex_1 = {0x40000000,0x0CCCCCCC}; // (0.5 + 0.1i) int32c test_complex_2 = {0x73333333,0xB3333334}; // (0.9 - 0.6i) res=&result; input1=&test_complex_1; input2=&test_complex_2; DSP_ComplexSub32(input1, input2, res); // result = {0xCCCCCCCD, 0x59999998} = (-0.4 + 0.7i) 5.4.1.5.2 Digital Filter Functions 5.4.1.5.2.1 DSP_FilterFIR32 Function C void DSP_FilterFIR32( 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1180 int32_t * outdata, int32_t * indata, int32_t * coeffs2x, int32_t * delayline, int N, int K, int scale ); Description Function DSP_FilterFIR32: void DSP_FilterFIR32(int32_t *outdata, int32_t *indata, int32_t *coeffs2x, int32_t *delayline, int N, int K, int scale); Performs an FIR filter on the vector indata, and stores the output in the vector outdata. The number of samples processed in the array is given by N. The number of filter taps is given by K. The values are scaled upon input by the binary scaling factor (right shift), scale. The array of 2*K coefficients is contained in the array coeffs2x, where the values are in order b0, b1, b2... and repeated. Lastly the delayline is an array of K values that are initialized to zero and represent previous values. All values are in fractional Q31 data format. The function will saturate results if minimum or maximum values are exceeded. Preconditions The pointers outdata and indata must be aligned on 4-byte boundaries. N must be greater than or equal to four and a multiple of four. K must be greater than 2 and a multiple of 2. delayline must have K elements, and be initialized to zero. coeffs2x must have 2*K elements. Parameters Parameters Description outdata pointer to destination array of elements (int32_t) indata pointer to source array of elements (int32_t) coeffs2x pointer to an array of coefficients (int32_t) delayline pointer to an array of delay variables (int32_t) N number of points in the array to process (int) number of samples (int) K number of filter taps scale binary scaler divisor (1 / 2^scale) (int) Returns None. Remarks Filter coefs must be repeated within the array. The array is twice as large as the number of taps, and the values are repeated in order b0, b1, b2,...bn, b0, b1, b2,... bn. The function updates the delayline array, which must be K elements long. The array should be initialized to zero prior to the first processing. It will contain values for processing cascaded filters within a loop. Example #define TAPS 4 #define numPOINTS 256 int filterN = numPOINTS; int filterK = TAPS; int filterScale = 1; // scale output by 1/2^1 => output * 0.5 int32_t FilterCoefs[TAPS*2] = {0x40000000, 0x20000000, 0x20000000, 0x20000000, 0x40000000, 0x20000000, 0x20000000, 0x20000000}; // note repeated filter coefs, A B C D A B C D // 0.5, 0.25, 0.25, 0.25, 0.5, 0.25, 0.25, 0.25 int32_t outFilterData[numPOINTS]={0}; int32_t inFilterData[numPOINTS]; 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1181 int filterDelayLine[TAPS]={0}; while(true) { // put some data into input array, inFilterData, here // DSP_FilterFIR32(outFilterData, inFilterData, FilterCoefs, filterDelayLine, filterN, filterK, filterScale); } 5.4.1.5.2.2 DSP_FilterFIRDecim32 Function C void DSP_FilterFIRDecim32( int32_t * outdata, int32_t * indata, int32_t * coeffs, int32_t * delayline, int N, int K, int scale, int rate ); Description Function DSP_FilterFIRDecim32: void DSP_FilterFIRDecim32(int32_t *outdata, int32_t *indata, int32_t *coeffs, int32_t *delayline, int N, int K, int scale, int rate); Compute a FIR decimation filter on the input vector indata, and store the results to the vector outdata. The total number of output elements is set by N, and therefore the outdata array must be at least N in length. The decimation ratio is given by rate. The input is sampled every integer value of rate, skipping every (rate-1) input samples. The input array must therefore be (rate*N) samples long. The amount of filter taps is specified by K. Coeffs specifies the coefficients array. The delayline array holds delay inputs for calculation, and must be initialized to zero prior to calling the filter. Both coeffs and delayline must be K in length. Scale divides the input by a scaling factor by right shifting the number of bits (1/2^scale). All values of input, output, and coeffs are given in Q31 fractional data format. The function will saturate if the output value exceeds the maximum or minmum value. Y = b0 * X0 + (b1 * X(-1)) + (b2 * X(-2) Preconditions The pointers outdata and indata must be aligned on 4-byte boundaries. delayline must have K elements, and be initialized to zero. coeffs must have K elements. outdata must have N elements indata must have (N*rate) elements Parameters Parameters Description outdata pointer to output array of elements (int32_t) indata pointer to input array of elements (int32_t) coeffs pointer to an array of coefficients (int32_t) delayline pointer to an array of delay variables (int32_t) N number of output elements to be processed (int) K number of filter taps and coeffs (int) scale binary scaler divisor (1 / 2^scale) (int) rate decimation ratio (int) Returns None. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1182 Remarks Coefs are loaded into the arry with corresponding to the least delay first (C0, C(-1), C(-2)). K must be greater than rate. Even while decimating the input stream, every input passes through the delayline. So FIR filters of arbitrary length will give the same output as a non-decimating FIR, just with fewer responses. Example #define N 8 // number of output samples #define TAPS 5 #define SKIP 3 int testFilterN = N; // number of output elements int testFilterK = TAPS; // number of taps int testFilterRate = SKIP; // decimation rate R int32_t outFiltDataDec[N]={0}; int32_t *inTestFilter[N*SKIP]; int filtScaleNum = 1; // scale output (1 /2^n) => Y * 0.5 int32_t filtDelayTest[8]={0}; // always initialize to zero // get pointer to input buffer here // inTestFilter = &inputBuffer; DSP_FilterFIRDecim32(outFiltDataDec, inTestFilter, inTestCoefs, filtDelayTest, testFilterN, testFilterK, filtScaleNum, testFilterRate); 5.4.1.5.2.3 DSP_FilterFIRInterp32 Function C void DSP_FilterFIRInterp32( int32_t * outdata, int32_t * indata, int32_t * coeffs, int32_t * delayline, int N, int K, int scale, int rate ); Description Function DSP_FilterFIRInterp32: void DSP_FilterFIRInterp32(int32_t *outdata, int32_t *indata, int32_t *coeffs, int32_t *delayline, int N, int K, int scale, int rate); Perform an interpolating FIR filter on the first N samples of indata, and stores the result in outdata. The number of output elements is N*rate. The number of filter taps, K, must be an even multiple of N. The coefficients array, Coeffs, must be K elements long. The delay line array, delayline, must be K/R elements long, and be initialzed to zero. All data elements must be in Q31 fractional data format. Scaling is performed via binary shift on the input equvalent to (1/2^shift). The function will saturate the output if it exceeds maximum or minimum values. The function creates R output values for each input value processed. The delayline of previous values is processed with R elements of the coefficient array. Numerically: Y(1,0) = X(0)*C(0) + X(-1)*C(rate) + X(-2)*C(2*rate) ... Y(1,1) = X(0)*C(1) + X(-1)*C(rate+1) + X(-2)*C(2*rate + 1) ... Y(1,rate) = X(0)*C(N) + X(-1)*C(rate+N) + X(-2)*C(2*rate + N) ... where output Y corresponds to (input,rate) different outputs, input X has (M/rate) sample delays and C is the coefficient array. Preconditions The pointers outdata and indata must be aligned on 4-byte boundaries. delayline must have (K/R) elements, and be initialized to zero. K (taps) must be an even multiple of R (rate). outdata must have R*N elements. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1183 Parameters Parameters Description outdata pointer to output array of elements (int32_t) indata pointer to input array of elements (int32_t) coeffs pointer to an array of coefficients (int32_t) delayline pointer to an array of delay variables (int32_t) N number of output elements to be processed (int) K number of filter taps and coeffs (int) scale binary scaler divisor (1 / 2^scale) (int) rate decimation ratio (int) Returns None. Remarks The function processes each input (rate) times. With each pass, coefficients are offset so that (K/rate) multiply accumulate cycles occur. Example // interpret evenly 1/3 spaced values #define N 4 // number of output samples #define TAPS 6 #define INTERP 3 int ifiltN = N; int ifiltK = TAPS; // k must be an even multiple of R int ifiltR = INTERP; int32_t ifiltOut[N*INTERP]={0}; int32_t ifiltDelay[2]={0}; // must be initialized to zero int ifiltScale = 0; // no scaling int32_t ifiltCoefsThirds[TAPS]={0x2AAAAAA9, 0x55555555,0x7FFFFFFE, 0x55555555,0x2AAAAAA9,0x00000000}; // 0.333333, 0.6666667, 0.99999999, 0.6666667, 0.33333333, 0 int32_t ifiltInput[N]={0x0CCCCCCD, 0x19999999, 0x26666666, 0x33333333}; // 0.1, 0.2, 0.3, 0.4 DSP_FilterFIRInterp32(ifiltOut, ifiltInput, ifiltCoefsThirds, ifiltDelay, ifiltN, ifiltK, ifiltScale, ifiltR); // ifiltOut = {0x04444444, 0x08888889, 0x0CCCCCCD, 0x11111111, 0x15555555, 0x19999999, // 0x1DDDDDDD, 0x22222221, 0x26666665, 0x2AAAAAAA,0x2EEEEEEE, 0x33333332} // = 0.0333, 0.0667, 0.1, 0.1333, 0.1667, 0.2, 0.2333, 0.2667, 0.3, 0.3333, 0.3667, 0.4 5.4.1.5.2.4 DSP_FilterIIR16 Function C int16_t DSP_FilterIIR16( int16_t in, int16_t * coeffs, int16_t * delayline, int B, int scale ); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1184 Description Function DSP_FilterIIR16: int16_t DSP_FilterIIR16(int16_t in, int16_t *coeffs, int16_t *delayline, int B, int scale); Performs a single element cascaded biquad IIR filter on the input, in. The filter contains B number of biquad sections, and cascades the output of one to the input of the next. B must be greater than 2 and a multiple of 2. The int16_t output generated by the function is the computation from the final biquad stage. Delay pipeline array delayline must contain 2*B values and be initialized to zero prior to use. The coefficient array must contain 4*B elments, and must be set up in order of biquad a1, a2, b1, b2. A binary (right shift) factor, scale, will scale the output equivalent to (1/2^scale). All numerical values must be in Q15 fractional data format. The function will saturate values if maximum or minimum values are exceeded. Y = X0 + (b1 * X(-1)) + (b2 * X(-2) + (a1 * Y(-1)) + (a2 * Y(-2)) Preconditions The pointers outdata and indata must be aligned on 4-byte boundaries. B must be greater than 2 and a multiple of 2. delayline must have 2*B elements, and be initialized to zero. coeffs must have 4*B elements. Parameters Parameters Description in input data element X (int16_t) coeffs pointer to an array of coefficients (int16_t) delayline pointer to an array of delay variables (int16_t) B number of cascaded biquad filter groups to process (int) scale binary scaler divisor (1 / 2^scale) (int) Returns Sample output Y (int16_t) Example #define B 8 // use * biquad filters in cascade int dataSamples = 256; int i, j; biquad16 bquad[B]; int16_t coefs[4*B]= {0}; int16_t delaylines[2*B]= {0}; int16_t Y, X; int scaleBquad = 1; // scale output (1 /2^n) => Y * 0.5 // do something to set up coefs, for instance this example // for (j=0; jRemarks:Filter coefs must be stored within the array as a1, a2, b1, b2, a1, a2, b1, b2, in order of biquads form input to output. A function to translate the coeffs from biquad structure to coeffs is available in DSP_FilterIIRSetup16. The function updates the delayline array, which must be 2*B elements long. The array should be initialized to zero prior to the first processing. It will contain values for processing cascaded filters within a loop. 5.4.1.5.2.5 DSP_FilterIIRBQ16 Function C int16_t DSP_FilterIIRBQ16( int16_t Xin, PARM_EQUAL_FILTER * pFilter ); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1185 Description Function DSP_FilterIIRBQ16: int16_t DSP_FilterIIRBQ16(int16_t Xin, PARM_EQUAL_FILTER *pFilter); Calculates a single pass IIR biquad filter on Xin, and delivers the result as a 16-bit output. All math is performed using 32 bit instructions, with results truncated to 16-bits for the output. The delay register is stored as a 32-bit value for subsequent functions. All values are fractional Q15 and Q31, see data structure for specifics. Y = X(0)*b0 + (b1 * X(-1)) + (b2 * X(-2)) - (a1 * Y(-1)) - (a2 * Y(-2)) Preconditions Delay register values should be initialized to zero. Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER *ptrFilterEQ; PARM_EQUAL_FILTER FilterEQ; uint16_t DataIn, DataOut; ptrFilterEQ = &FilterEQ; // 48KHz sampling; 1 KHz bandpass filter; Q=0.9 // divide by 2 and convert to Q15 // b0 = 0.06761171785499065 // b1 = 0 // b2 = -0.06761171785499065 // a1 = -1.848823142275648 // a2 = 0.8647765642900187 // note all coefs are half value of original design, gain handled in algorithm ptrFiltEQ32->b[0]=0x0453; // feed forward b0 coef ptrFiltEQ32->b[1]=0; // feed forward b1 coef ptrFiltEQ32->b[2]=0xFBAD; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value ptrFiltEQ32->a[0]=0x89AD; // feedback a1 coef ptrFiltEQ32->a[1]=0x3758; // feedback a2 coef for (i=0;i<256;i++) { // *** get some input data here DataIn32 = three_hundred_hz[i]; DataOut = DSP_FilterIIRBQ16(DataIn, ptrFilterEQ); // *** do something with the DataOut here } 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1186 5.4.1.5.2.6 DSP_FilterIIRBQ16_cascade8 Function C int16_t DSP_FilterIIRBQ16_cascade8( int16_t Xin, PARM_EQUAL_FILTER * pFilter_Array ); Description Function DSP_FilterIIRBQ16_cascade8: int16_t DSP_FilterIIRBQ16_cascade8(int16_t Xin, PARM_EQUAL_FILTER *pFilter_Array); Calculates a single pass IIR biquad cascade filter on Xin, and delivers the result as a 16-bit output. The cascade of filters is 8 unique biquad filters arranged in series such that the output of one is provided as the input to the next. A unique filter coefficient set is provided to each, and 32 bit delay lines are maintained for each. All math is performed using 32 bit instructions, which results truncated to 16-bits for the output. Global gain values are available on the output. Fracgain is a Q15 fractional gain value and expgain is a binary shift gain value. The combination of the two can be utilized to normalize the output as desired. All values are fractional Q15 and Q31, see data structure for specifics. Y = Y7 <- Y6 <- Y5 <- Y4 <- Y3 <- Y2 <- Y1 <- Y0 where each Yn filter element represents a unique IIR biquad: Yn = Y(n-1)*b0 + (b1 * Y(n-2)) + (b2 * Y(n-3)) - (a1 * Yn(-1)) - (a2 * Yn(-2)) and: for Y0; Y(n-1) = Xin(0) Preconditions Delay register values should be initialized to zero. Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER filtArray[8]; uint16_t dataY, dataX; // example to use 2 filter blocks as notch filters // fill entire Filter Array with coefs for (i=0;i<8;i++) { filtArray[i].Z[0]=0; filtArray[i].Z[1]=0; // note all coefs are half value of original design, gain handled in algorithm // all pass filtArray[i].b[0]=0x4000; filtArray[i].b[1]=0; // feed forward b1 coef filtArray[i].b[2]=0; // feed forward b2 coef filtArray[i].a[0]=0; // feedback a1 coef filtArray[i].a[1]=0; // feedback a2 coef 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1187 } // Unique filters for example // 10KHz notch filter -- divide coefs by 2 b0 = 0.5883783602332997 b1 = -0.17124071441396285 b2 = 0.5883783602332997 a1 = -0.17124071441396285 a2 = 0.1767567204665992 // note all coefs are half value of original design, gain handled in algorithm filtArray[3].b[0]=0x25a7; // feed forward b0 coef filtArray[3].b[1]=0xf508; // feed forward b1 coef filtArray[3].b[2]=0x25a7; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArray[3].a[0]=0xf508; // feedback a1 coef filtArray[3].a[1]=0x0b4f; // feedback a2 coef // 1 KHz notch filter -- divide coefs by 2 b0 = 0.9087554064944908 b1 = -1.7990948352036205 b2 = 0.9087554064944908 a1 = -1.7990948352036205 a2 = 0.8175108129889816 // note all coefs are half value of original design, gain handled in algorithm filtArray[7].b[0]=0x3a29; // feed forward b0 coef filtArray[7].b[1]=0x8cdc; // feed forward b1 coef filtArray[7].b[2]=0x3a29; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArray[7].a[0]=0x8cdc; // feedback a1 coef filtArray[7].a[1]=0x3452; // feedback a2 coef for (i=0;i<256;i++) { // *** get input data here dataX = compound_300_1K_hz16[i]; dataY = DSP_FilterIIRBQ16_cascade8(dataX, filtArray); // *** do something with the DataY here } 5.4.1.5.2.7 DSP_FilterIIRBQ16_cascade8_fast Function C int16_t DSP_FilterIIRBQ16_cascade8_fast( int16_t Xin, PARM_EQUAL_FILTER_16 * pFilter_Array ); Description Function DSP_FilterIIRBQ16_cascade8_fast: int16_t DSP_FilterIIRBQ16_cascade8_fast(int16_t Xin, PARM_EQUAL_FILTER_16 *pFilter_Array); Calculates a single pass IIR biquad cascade filter on Xin, and delivers the result as a 16-bit output. The cascade of filters is 8 unique biquad filters arranged in series such that the output of one is provided as the input to the next. A unique filter coefficient set is provided to each, and 16 bit delay lines are maintained for each. All math is performed using 16 bit instructions, which results rounded to 16-bits for the output. All values are fractional Q15, see data structure for specifics. The function will saturate the output should it exceed maximum or minimum values. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1188 Y = Y7 <- Y6 <- Y5 <- Y4 <- Y3 <- Y2 <- Y1 <- Y0 where each Yn filter element represents a unique IIR biquad: Yn = Y(n-1)*b0 + (b1 * Y(n-2)) + (b2 * Y(n-3)) - (a1 * Yn(-1)) - (a2 * Yn(-2)) and: for Y0; Y(n-1) = Xin(0) Preconditions Delay register values should be initialized to zero. Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER_16 filtArray[8]; uint16_t dataY, dataX; // example to use 2 filter blocks as notch filters // fill entire Filter Array with coefs for (i=0;i<8;i++) { filtArray[i].Z[0]=0; filtArray[i].Z[1]=0; // note all coefs are half value of original design, gain handled in algorithm // all pass filtArray[i].b[0]=0x4000; filtArray[i].b[1]=0; // feed forward b1 coef filtArray[i].b[2]=0; // feed forward b2 coef filtArray[i].a[0]=0; // feedback a1 coef filtArray[i].a[1]=0; // feedback a2 coef } // Unique filters for example // 10KHz notch filter -- divide coefs by 2 b0 = 0.5883783602332997 b1 = -0.17124071441396285 b2 = 0.5883783602332997 a1 = -0.17124071441396285 a2 = 0.1767567204665992 // note all coefs are half value of original design, gain handled in algorithm filtArray[3].b[0]=0x25a7; // feed forward b0 coef filtArray[3].b[1]=0xf508; // feed forward b1 coef filtArray[3].b[2]=0x25a7; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArray[3].a[0]=0xf508; // feedback a1 coef filtArray[3].a[1]=0x0b4f; // feedback a2 coef // 1 KHz notch filter -- divide coefs by 2 b0 = 0.9087554064944908 b1 = -1.7990948352036205 b2 = 0.9087554064944908 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1189 a1 = -1.7990948352036205 a2 = 0.8175108129889816 // note all coefs are half value of original design, gain handled in algorithm filtArray[7].b[0]=0x3a29; // feed forward b0 coef filtArray[7].b[1]=0x8cdc; // feed forward b1 coef filtArray[7].b[2]=0x3a29; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArray[7].a[0]=0x8cdc; // feedback a1 coef filtArray[7].a[1]=0x3452; // feedback a2 coef for (i=0;i<256;i++) { // *** get input data here dataX = compound_300_1K_hz16[i]; dataY = DSP_FilterIIRBQ16_cascade8_fast(dataX, filtArray); // *** do something with the DataY here } 5.4.1.5.2.8 DSP_FilterIIRBQ16_fast Function C int16_t DSP_FilterIIRBQ16_fast( int16_t Xin, PARM_EQUAL_FILTER_16 * pFilter ); Description Function DSP_FilterIIRBQ16_fast: int16_t DSP_FilterIIRBQ16_fast(int16_t Xin, PARM_EQUAL_FILTER_16 *pFilter); Calculates a single pass IIR biquad filter on Xin, and delivers the result as a 16-bit output. All math is performed using 16 bit instructions, with results rounded to 16-bits for the output. The delay register is stored as a 16-bit value for subsequent functions. The function will saturate the results if maximum or minimum fractional values are exceeded. All values are fractional Q15 format. Y = X(0)*b0 + (b1 * X(-1)) + (b2 * X(-2)) - (a1 * Y(-1)) - (a2 * Y(-2)) Preconditions Delay register values should be initialized to zero. Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER_16 *ptrFilterEQ; 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1190 PARM_EQUAL_FILTER_16 FilterEQ; uint16_t DataIn, DataOut; ptrFilterEQ = &FilterEQ; // 48KHz sampling; 1 KHz bandpass filter; Q=0.9 // divide by 2 and convert to Q15 // b0 = 0.06761171785499065 // b1 = 0 // b2 = -0.06761171785499065 // a1 = -1.848823142275648 // a2 = 0.8647765642900187 // note all coefs are half value of original design, gain handled in algorithm ptrFiltEQ32->b[0]=0x0453; // feed forward b0 coef ptrFiltEQ32->b[1]=0; // feed forward b1 coef ptrFiltEQ32->b[2]=0xFBAD; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value ptrFiltEQ32->a[0]=0x89AD; // feedback a1 coef ptrFiltEQ32->a[1]=0x3758; // feedback a2 coef for (i=0;i<256;i++) { // *** get some input data here DataIn32 = three_hundred_hz[i]; DataOut = DSP_FilterIIRBQ16_fast(DataIn, ptrFilterEQ); // *** do something with the DataOut here } 5.4.1.5.2.9 DSP_FilterIIRBQ16_parallel8 Function C int16_t DSP_FilterIIRBQ16_parallel8( int16_t Xin, PARM_EQUAL_FILTER * pFilter ); Description Function DSP_FilterIIRBQ16_parallel8: int16_t DSP_FilterIIRBQ16_parallel8(int16_t Xin, PARM_EQUAL_FILTER *pFilter); Calculates a 8 parallel, single pass IIR biquad filters on Xin, sums the result and delivers the result as a 16-bit output. All math is performed using 32 bit instructions, which results truncated to 16-bits for the output. The delay register is stored as a 32-bit value for subsequent functions. Output is tuned by 2 multipier factors. First each parallel section has a fractional gain (attenuation) that enables individual scaling of that section. Second, a global binary (log2N) gain is applied to the result. The combination of gain factors enable both gain and attentuation. All values are fractional Q15 and Q31, see data structure for specifics. Y = Y7/8 + Y6/8 + Y5/8 + Y4/8 + Y3/8 + Y2/8 + Y1/8 + Y0/8 where each Yn filter element represents a unique IIR biquad: Yn = X(0)*b0 + (b1 * X(n-1)) + (b2 * X(n-2)) - (a1 * Yn(-1)) - (a2 * Yn(-2)) Preconditions Delay register values should be initialized to zero. The sum of all fracgain should be <= 1 Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1191 Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER filtArrayPara[8]; uint16_t dataY, dataX; // fill entire Filter Array with coefs for (i=0;i<8;i++) { filtArrayPara[i].Z[0]=0; filtArrayPara[i].Z[1]=0; filtArrayPara[i].G.fracGain = 0x7FFF; // gain = 1 default filtArrayPara[i].G.expGain = 1; // == 2^N; gain of 2 // note all coefs are half value of original design, gain handled in algorithm // none pass -- default filtArrayPara[i].b[0]=0; // feed forward b0 coef filtArrayPara[i].b[1]=0; // feed forward b1 coef filtArrayPara[i].b[2]=0; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[i].a[0]=0; // feedback a1 coef filtArrayPara[i].a[1]=0; // feedback a2 coef } // 1K bandpass Q=0.9 filtArrayPara[7].G.fracGain = 0x4000; // gain = 0.5 because using 2 outputs // note all coefs are half value of original design, gain handled in algorithm filtArrayPara[7].b[0]=0x04ad; filtArrayPara[7].b[1]=0; // feed forward b1 coef filtArrayPara[7].b[2]=0xfb53; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[7].a[0]=0x8a90; // feedback a1 coef filtArrayPara[7].a[1]=0x36a4; // feedback a2 coef // 300 Hz bandpass Q=0.9 filtArrayPara[6].G.fracGain = 0x1000; // gain = 0.125 as an example // note all coefs are half value of original design, gain handled in algorithm filtArrayPara[6].b[0]=0x017b; // feed forward b0 coef filtArrayPara[6].b[1]=0; // feed forward b1 coef filtArrayPara[6].b[2]=0xfe85; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[6].a[0]=0x8316; // feedback a1 coef filtArrayPara[6].a[1]=0x3d08; // feedback a2 coef for (i=0;i<256;i++) { // *** get input data here dataX = compound_300_1K_hz16[i]; dataY = DSP_FilterIIRBQ16_cascade8_fast(dataX, filtArray); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1192 // *** do something with the DataY here } 5.4.1.5.2.10 DSP_FilterIIRBQ16_parallel8_fast Function C int16_t DSP_FilterIIRBQ16_parallel8_fast( int16_t Xin, PARM_EQUAL_FILTER_16 * pFilter ); Description Function DSP_FilterIIRBQ16_parallel8_fast: int16_t DSP_FilterIIRBQ16_parallel8_fast(int16_t Xin, PARM_EQUAL_FILTER_16 *pFilter); Calculates a 8 parallel, single pass IIR biquad filters on Xin, sums the result and delivers the result as a 16-bit output. All math is performed using 16 bit instructions, which results rounded to 16-bits for the output. The delay register is stored as a 16-bit value for subsequent functions. Output is tuned by 2 multipier factors. First each parallel section has a fractional gain (attenuation) that enables individual scaling of that section. Second, a global binary (log2N) gain is applied to the result. The combination of gain factors enable both gain and attentuation. All values are fractional Q15. The function will round outputs and saturate if maximum or minimum values are exceeded. Y = Y7/8 + Y6/8 + Y5/8 + Y4/8 + Y3/8 + Y2/8 + Y1/8 + Y0/8 where each Yn filter element represents a unique IIR biquad: Yn = X(0)*b0 + (b1 * X(n-1)) + (b2 * X(n-2)) - (a1 * Yn(-1)) - (a2 * Yn(-2)) Preconditions Delay register values should be initialized to zero. The sum of all fracgain should be <= 1 Parameters Parameters Description Xin input data element X (int16_t) pFilter pointer to filter coef and delay structure Returns Sample output Y (int16_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER_16 filtArrayPara[8]; // note change in data structure uint16_t dataY, dataX; // fill entire Filter Array with coefs for (i=0;i<8;i++) { filtArrayPara[i].Z[0]=0; filtArrayPara[i].Z[1]=0; filtArrayPara[i].G.fracGain = 0x7FFF; // gain = 1 default filtArrayPara[i].G.expGain = 1; // log2N; gain of 2 // note all coefs are half value of original design, gain handled in algorithm // none pass -- default filtArrayPara[i].b[0]=0; // feed forward b0 coef 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1193 filtArrayPara[i].b[1]=0; // feed forward b1 coef filtArrayPara[i].b[2]=0; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[i].a[0]=0; // feedback a1 coef filtArrayPara[i].a[1]=0; // feedback a2 coef } // 1K bandpass Q=0.9 filtArrayPara[7].G.fracGain = 0x4000; // gain = 0.5 because using 2 outputs // note all coefs are half value of original design, gain handled in algorithm filtArrayPara[7].b[0]=0x04ad; filtArrayPara[7].b[1]=0; // feed forward b1 coef filtArrayPara[7].b[2]=0xfb53; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[7].a[0]=0x8a90; // feedback a1 coef filtArrayPara[7].a[1]=0x36a4; // feedback a2 coef // 300 Hz bandpass Q=0.9 filtArrayPara[6].G.fracGain = 0x1000; // gain = 0.125 as an example // note all coefs are half value of original design, gain handled in algorithm filtArrayPara[6].b[0]=0x017b; // feed forward b0 coef filtArrayPara[6].b[1]=0; // feed forward b1 coef filtArrayPara[6].b[2]=0xfe85; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value filtArrayPara[6].a[0]=0x8316; // feedback a1 coef filtArrayPara[6].a[1]=0x3d08; // feedback a2 coef for (i=0;i<256;i++) { // *** get input data here dataX = compound_300_1K_hz16[i]; dataY = DSP_FilterIIRBQ16_cascade8_fast(dataX, filtArray); // *** do something with the DataY here } 5.4.1.5.2.11 DSP_FilterIIRBQ32 Function C int32_t DSP_FilterIIRBQ32( int32_t Xin, PARM_EQUAL_FILTER_32 * pFilter ); Description Function DSP_FilterIIRBQ32: int32_t DSP_FilterIIRBQ32(int32_t Xin, PARM_EQUAL_FILTER_32 *pFilter); Calculates a single pass IIR biquad filter on Xin, and delivers the result as a 16-bit output. All math is performed using 32 bit instructions, with results truncated to 32-bits for the output. The delay register is stored as a 32-bit value for subsequent functions. All values are fractional Q31, see data structure for specifics. Y = X(0)*b0 + (b1 * X(-1)) + (b2 * X(-2)) - (a1 * Y(-1)) - (a2 * Y(-2)) Preconditions Delay register values should be initialized to zero. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1194 Parameters Parameters Description Xin input data element X (int32_t) pFilter pointer to high resolution filter coef and delay structure Returns Sample output Y (int32_t) Remarks The delay register values should be initialized to zero prior to the first call to the function, they are updated each pass. A gain of 2 has been hard coded into the function. This implies that all coefs should be input at half value. This is purposeful, since many filter designs need a div2 to have each coef between the required -1 Example PARM_EQUAL_FILTER_32 *ptrFiltEQ32; PARM_EQUAL_FILTER_32 FilterEQ32; int32_t DataIn32, DataOut32; ptrFiltEQ32 = &FilterEQ32; ptrFiltEQ32->Z[0]=0; ptrFiltEQ32->Z[1]=0; // 1000 Hz Q= 0.9 BP filter design, 44.1K sampling // // b0 = 0.07311778239751009 forward // b1 = 0 // b2 = -0.07311778239751009 // a1 = -1.8349811166056893 back // a2 = 0.8537644352049799 // note all coefs are half value of original design, gain handled in algorithm ptrFiltEQ32->b[0]=0x04ADF635; // feed forward b0 coef ptrFiltEQ32->b[1]=0; // feed forward b1 coef ptrFiltEQ32->b[2]=0xFB5209CB; // feed forward b2 coef // note all coefs are half value of original design, gain handled in algorithm // note subtract is handled in algorithm, so coefs go in at actual value ptrFiltEQ32->a[0]=0x8A8FAB5D; // feedback a1 coef ptrFiltEQ32->a[1]=0x36A41395; // feedback a2 coef for (i=0;i<256;i++) { // *** get input data here DataIn32 = three_hundred_hz[i]; DataOut32 = DSP_FilterIIRBQ32(DataIn32, ptrFiltEQ32); // *** do something with the DataOut32 here } 5.4.1.5.2.12 DSP_FilterIIRSetup16 Function C void DSP_FilterIIRSetup16( int16_t * coeffs, biquad16 * bq, int B ); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1195 Description Function DSP_FilterIIRSetup16: void DSP_FilterIIRSetup16(int16_t *coeffs, biquad16 *bq, int B); Converts an array of biquad coefficients, bq, into an linear array of coefficients, coeffs. The output array must be 4*B elements long. The number of biquads in the resulting factor is given by B. All numerical values must be in Q15 fractional data format. Preconditions coeffs must have 4*B elements. Parameters Parameters Description coeffs pointer to an array of coefficients (int16_t) bq pointer to array of biquad structure filter coefs (biquad16) B number of cascaded biquad filter groups to process (int) Returns None. Remarks None. Example see DSP_FilterIIR16 for example. 5.4.1.5.2.13 DSP_FilterLMS16 Function C int16_t DSP_FilterLMS16( int16_t in, int16_t ref, int16_t * coeffs, int16_t * delayline, int16_t * error, int K, int16_t mu ); Description Function DSP_FilterLMS16: int16_t DSP_FilterLMS16(int16_t in, int16_t ref, int16_t *coeffs, int16_t *delayline, int16_t *error, int K, int16_t mu); Computes an LMS adaptive filter on the input in. Filter output of the FIR is given as a 16 bit value. The filter target is ref, and the calculation difference between the output and the target is error. The filter adapts its coefficients, coefs, on each pass. The number of coefficients (filter taps) is given by the value K. The delayline array should be initialized to zero prior to calling the filter for the first time, and have K elements. The value mu is the rate at which the filter adapts. All values are Q15 fractional numbers. The function will saturate the output if it exceeds maximum or minimum values. The LMS will adapt its coefs to attempt to drive the output value toward the ref value. The rate of adaption on each pass depends on mu and the error from the previous calculation. Preconditions The pointers outdata and indata must be aligned on 4-byte boundaries. delayline must have (K) elements, and be initialized to zero. K (taps) must be a multiple of 4, and >= 8. mu must be positive. 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1196 Parameters Parameters Description in input data value (int16_t) ref target output value (int16_t) coeffs pointer to an array of coefficients (int16_t) delayline pointer to an array of delay variables (int16_t) error output minus reference (int16_t) K number of filter taps and coeffs (int) mu adaption rate (int16_t) Returns (int16_t) - FIR filter output Remarks Filter coefs may start at random or zero value, but convergence is dependent on the amount of update required. Example #define lmsTAPS 8 int16_t lmsOut; int lmsTaps = lmsTAPS; int16_t lmsCoefs[lmsTAPS]={0x5000, 0x4000,0x3000, 0x2000,0x1000, 0x0000,0xF000, 0xE000}; int16_t lmsDelay[lmsTAPS]={0}; int16_t *ptrLMSError; int16_t lmsError = 0x0200; int16_t inVal=0; int16_t refVal = 0x0CCC; // some target value = 0.1 int16_t lmsAdapt = 0x3000; ptrLMSError = &lmsError; for (i=0;i<200;i++) { // get some input value here // if (i < 100) { inVal = 0x4233; } else { inVal = 0xCF10; } lmsOut = DSP_FilterLMS16(inVal, refVal, lmsCoefs, lmsDelay, ptrLMSError, lmsTaps, lmsAdapt); } 5.4.1.5.3 Matrix Math Functions 5.4.1.5.3.1 DSP_MatrixAdd32 Function C void DSP_MatrixAdd32( matrix32 * resMat, matrix32 * srcMat1, 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1197 matrix32 * srcMat2 ); Description Function DSP_MatrixAdd32: void DSP_MatrixAdd32(matrix32 *resMat, matrix32 *srcMat1, matrix32 *srcMat2); Vector summation of two matrices, where both have 32-bit integer elements. The resulting output will saturate if element addition exceeds MAX32 or MIN32. Preconditions Both matrices must be equivalent in rows and columns. Both Matrices must be set into structure (ROWS, COLUMNS, vector_pointer). Parameters Parameters Description resMat pointer to new sum Matrix C (*int32_t) srcMat1 pointer to the Matrix A structure (*int32_t) srcMat2 pointer to the Matrix B structure (*int32_t) Returns None. Remarks Execution Time (cycles): 225 cycles + 23 / matrix_element. The function will saturate the output value if it exceeds maximum limits per element. Example #define ROW 2 #define COL 2 matrix32 *resMat, *srcMat1, *srcMat2; int32_t result[ROW*COL]; int32_t matA[ROW*COL] = {1,2,3,4}; int32_t matB[ROW*COL] = {2,4,6,8}; matrix32 mat, mat2, mat3; resMat=&mat; srcMat1=&mat2; srcMat2=&mat3; srcMat1->row=ROW; srcMat1->col=COL; srcMat1->pMatrix=matA; srcMat2->col=COL; srcMat2->row=ROW; srcMat2->pMatrix=matB; resMat->row=ROW; resMat->col=COL; resMat->pMatrix=result; DSP_MatrixAdd32(resMat, srcMat1, srcMat2); // result[i] = matA[i] + matB[i] = {3,6,9,0xA} 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1198 5.4.1.5.3.2 DSP_MatrixEqual32 Function C void DSP_MatrixEqual32( matrix32 * resMat, matrix32 * srcMat ); Description Function DSP_MatrixEqual32: void DSP_MatrixEqual32(matrix32 *resMat, matrix32 *srcMat); Vector copy of all elements from one matrix to another. C is a duplicate of A. Preconditions None. Parameters Parameters Description resMat pointer to completed new Matrix C (*int32_t) srcMat pointer to the Matrix A structure (*int32_t) Returns None. Remarks Execution Time (cycles): 163 cycles + 12 / matrix_element. Example #define ROW 2 #define COL 2 matrix32 *resMat, *srcMat1, *srcMat2; int32_t result[ROW*COL]; int32_t matA[ROW*COL] = {5,2,-3,8}; matrix32 mat, mat2; resMat=&mat; srcMat1=&mat2; srcMat1->row=ROW; srcMat1->col=COL; srcMat1->pMatrix=matA; resMat->row=ROW; resMat->col=COL; resMat->pMatrix=result; DSP_MatrixEqual32(resMat, srcMat1, srcMat2); // result[i] = matA[i] = {5, 2, -3, 8} 5.4.1.5.3.3 DSP_MatrixInit32 Function C void DSP_MatrixInit32( int32_t * data_buffer, 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1199 int N, int32_t num ); Description Function DSP_MatrixInit32: void DSP_MatrixInit32(int32_t *data_buffer, int N, int32_t num); Copy the value num into the first N Matrix elements of data_buffer. Preconditions data_buffer must be predefined to be equal to or greater than N elements. N must be a factor of four, or it will truncate to the nearest factor of four. Parameters Parameters Description data_buffer pointer to the Matrix to be initialized (int32_t[M*N]) N number of elements to be initialized (int32_t) num value to be initialized into the matrix (int32_t) Returns None. Remarks None. Example #define ROW 3 #define COL 3 int32_t numElements = 4; // multiple of 4 int valueElements = -1; int32_t matA[ROW*COL] = {5,2,-3,8,4,2,-6,8,9}; DSP_MatrixInit32(matA, numElements, valueElements); // matA[i] = {-1,-1,-1,-1,4,2,-6,8,9} 5.4.1.5.3.4 DSP_MatrixMul32 Function C void DSP_MatrixMul32( matrix32 * resMat, matrix32 * srcMat1, matrix32 * srcMat2 ); Description Function DSP_MatrixMul32: void DSP_MatrixMul32(matrix32 *resMat, matrix32 *srcMat1, matrix32 *srcMat2); Multiplication of two matrices, with inputs and outputs being in fractional Q31 numerical format. The output elements will saturate if the dot product exceeds maximum or minimum fractional values. Preconditions Matrices must be aligned such that columns of A = rows of B. resMat must have the format of rows of A, columns of B. All 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1200 Matrices must be set into structure (ROWS, COLUMNS, vector_pointer). Parameters Parameters Description resMat pointer to different Matrix C structure (*int32_t) srcMat1 pointer to the Matrix A structure (*int32_t) srcMat2 pointer to the Matrix B structure (*int32_t) Returns None. Remarks Execution Time (cycles): 319 cycles + 38 / output matrix_element. The function will saturate the output value if it exceeds maximum limits per element. Example #define ROW1 3 #define COL1 2 #define ROW2 2 #define COL2 2 matrix32 *resMat, *srcMat1, *srcMat2; int32_t result[ROW1*COL2]; int32_t test_MatrixA[ROW1*COL1]= { 0x40000000,0x20000000, // 0.5, 0.25 0xD999999A,0x4CCCCCCC, // -0.3, 0.6 0xC0000000,0x0CCCCCCD // -0.5 0.1 }; int32_t test_MatrixB[ROW2*COL2]= { 0x40000000,0x20000000, // 0.5, 0.25 0x0CCCCCCD,0xCCCCCCCD // 0.1, -0.4 }; matrix32 mat, mat2, mat3; resMat=&mat; srcMat1=&mat2; srcMat2=&mat3; srcMat1->row=ROW1; srcMat1->col=COL1; srcMat1->pMatrix=test_MatrixA; srcMat2->col=COL2; srcMat2->row=ROW2; srcMat2->pMatrix=test_MatrixB; resMat->row=ROW1; // note resulting matrix MUST have ROW1 & COL2 format resMat->col=COL2; resMat->pMatrix=result; DSP_MatrixMul32(resMat, srcMat1, srcMat2); // result[] = matA[] x matB[] = // { 0x23333333, 0x03333333 // 0.275, 0.025 // 0xF47AE147, 0xD7AE147B // -0.9, -0.315 // 0xE147AE14, 0xEAE147AE } // -0.24, -0.165 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1201 5.4.1.5.3.5 DSP_MatrixScale32 Function C void DSP_MatrixScale32( int32_t * data_buffer, int N, int32_t num ); Description Function DSP_MatrixScale32: void DSP_MatrixScale32(int32_t *data_buffer, int N, int32_t num); Multiply the first N elements of an input buffer by a fixed scalar num. The resulting value is stored back into the input buffer. N number total samples of the input buffer are processed. All values are in Q31 fractional integer format. The result of calculations is saturated to the MAX32 or MIN32 value if exceeded. Preconditions data_buffer must be predefined to be equal to or greater than N elements. N must be a factor of four, or will truncate to the nearest factor of four. Parameters Parameters Description data_buffer pointer to the Matrix to be initialized (int32_t[M*N]) N number of elements to be initialized (int) num value to be initialized into the matrix (int32_t) Returns None. Remarks Execution time (cycles): 190 + 9 cycles / element, typical. Example int32_t numScale = 0x40000000; // 0.5 int valN = 12; int32_t inputBufScale[12] = {0x40000000, 0x40000000, 0x20000000, 0x20000000, 0x19999999, 0xCCCCCCCD, 0xF3333333, 0x80000000, 0x7FFFFFFF, 0x00000000, 0x40000000, 0x70000000 }; // 0.5, 0.5, 0.25, 0.25, 0.25, 0.2, -0.4, -0.1, -1, 1, 0, 0.5, 0.875 DSP_MatrixScale32(inputBufScale,valN,numScale); // inputBufScale[i] = {0x20000000, 0x20000000, 0x10000000, 0x10000000, // 0x0CCCCCCC, 0xE6666666, 0xF9999999, 0xC0000000, // 0x3FFFFFFF, 0x00000000, 0x20000000, 0x38000000} // 0.25, 0.25, 0.125, 0.125, 0.1, -0.2, -0.05, -0.5, 0.5, 0, 0.25, 0.4375 5.4.1.5.3.6 DSP_MatrixSub32 Function C void DSP_MatrixSub32( matrix32 * resMat, matrix32 * srcMat1, matrix32 * srcMat2 ); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1202 Description Function DSP_MatrixSub32: void DSP_MatrixSub32(matrix32 *resMat, matrix32 *srcMat1, matrix32 *srcMat2); Vector subtraction of two matrices, where both have 32-bit integer elements. The resulting output will saturate if element addition exceeds MAX32 or MIN32. Preconditions Both matrices must be equivalent in rows and columns. All Matrices must be set into structure (ROWS, COLUMNS, vector_pointer) Parameters Parameters Description resMat pointer to different Matrix C structure (*int32_t) srcMat1 pointer to the Matrix A structure (*int32_t) srcMat2 pointer to the Matrix B structure (*int32_t) Returns None. Remarks Execution Time (cycles): 222 cycles + 21 / matrix_element. The function will saturate the output value if it exceeds maximum limits per element. Example #define ROW 2 #define COL 2 matrix32 *resMat, *srcMat1, *srcMat2; int32_t result[ROW*COL]; int32_t matA[ROW*COL] = {5,2,-3,8}; int32_t matB[ROW*COL] = {2,2,2,2}; matrix32 mat, mat2, mat3; resMat=&mat; srcMat1=&mat2; srcMat2=&mat3; srcMat1->row=ROW; srcMat1->col=COL; srcMat1->pMatrix=matA; srcMat2->col=COL; srcMat2->row=ROW; srcMat2->pMatrix=matB; resMat->row=ROW; resMat->col=COL; resMat->pMatrix=result; DSP_MatrixSub32(resMat, srcMat1, srcMat2); // result[i] = matA[i] - matB[i] = {3,0,-5,6} 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1203 5.4.1.5.3.7 DSP_MatrixTranspose32 Function C void DSP_MatrixTranspose32( matrix32 * desMat, matrix32 * srcMat ); Description Function DSP_MatrixTranspose32: void DSP_MatrixTranspose32(matrix32 *desMat, matrix32 *srcMat); Transpose of rows and columns of a matrix. Preconditions Matrix definitions for ROWS and COLS must be transposed prior to the function call. Parameters Parameters Description desMat pointer to transposed new Matrix C (*int32_t) srcMat pointer to the Matrix A structure (*int32_t) Returns None. Remarks Execution Time (cycles): 210 cycles + 10 / matrix_element. Example #define ROW 3 #define COL 4 matrix32 *resMat, *srcMat1; int32_t result[ROW*COL]; int32_t matA[ROW*COL] = { 1, 2, 3, 4, 5, 6, 7, 8, -1, -3, -5, -7}; matrix32 mat, mat2; resMat=&mat; srcMat1=&mat2; srcMat1->row=ROW; srcMat1->col=COL; srcMat1->pMatrix=matA; resMat->row=COL; // note the shift in columns and rows resMat->col=ROW; resMat->pMatrix=result; DSP_MatrixTranspose32(resMat, srcMat1); // result[] = matA(T)[] = { 1, 5, -1, // 2, 6, -3, // 3, 7, -5, // 4, 8, -7} 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1204 5.4.1.5.4 Transform Functions 5.4.1.5.4.1 DSP_TransformFFT16 Function C void DSP_TransformFFT16( int16c * dout, int16c * din, int16c * twiddles, int16c * scratch, int log2N ); Description Function DSP_TransformFFT16: void DSP_TransformFFT16(int16c *dout, int16c *din, int16c *twiddles, int16c *scratch, int log2N); Performs an complex FFT on the input, din, and stores the complex result in dout. Performs 2^log2N point calculation, and the working buffer scratch as well as the input and output must be 2^log2N in length. Coefficient twiddle factors come from twiddles, and may be loaded with the use of DSP_TransformFFT16_setup. All values are 16 bit (Q15) fractional. Preconditions din, dout, twiddles and scratch must have N elements N is calculated as 2^(log2N) log2N must be >= 3 FFT factors must be calculated in advance, use DSP_TransformFFT16_setup Parameters Parameters Description dout pointer to complex output array (int16c) din pointer to complex input array (int16c) twiddles pointer to an complex array of factors (int16c) scratch pointer to a complex scratch pad buffer (int16c) log2N binary exponent of number of samples (int) Returns None. Remarks Scratch must be declared but need not be initialized. Din may be aided with a window function prior to calling the FFT, but is not required. Din is a complex number array, but may be loaded solely with real numbers if no phase information is available. Example int log2N = 8; // log2(256) = 8 int fftSamples = 256; int16c *fftDin; int16c fftDout[fftSamples]; int16c scratch[fftSamples]; int16c fftCoefs[fftSamples]; int16c *fftc; fftc = &fftCoefs; DSP_TransformFFT16_setup(fftc, log2N); // call setup function while (1) 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1205 { fftDin = &fftin_8Khz_long_window16; // get 256 point complex data DSP_TransformFFT16(fftDout, fftDin, fftc, scratch, log2N); // do something with the output, fftDout }; 5.4.1.5.4.2 DSP_TransformFFT16_setup Function C void DSP_TransformFFT16_setup( int16c * twiddles, int log2N ); Description Function DSP_TransformFFT16_setup: void DSP_TransformFFT16_setup(int16c *twiddles, int log2N); Calculates the N twiddle factors required to operate the FFT16 function. These factors are done in serial fashion, and require considerable processing power. Ideally this function would be run only once prior to an ongoing FFT, and the results held in a buffer. Preconditions twiddles must be N in length N is calculated (2^log2N) Parameters Parameters Description twiddles pointer to a complex array of factors (int16c) log2N binary exponent of number of data points (int) Returns None. Remarks This function is of considerable length and executed in C. It is recommended it only be called once for any given FFT length in time sensitive applications. Example see DSP_TransformFFT16 for example. 5.4.1.5.4.3 DSP_TransformFFT32 Function C void DSP_TransformFFT32( int32c * dout, int32c * din, int32c * twiddles, int32c * scratch, int log2N ); Description Function DSP_TransformFFT32: void DSP_TransformFFT32(int32c *dout, int32c *din, int32c *twiddles, int32c *scratch, int log2N); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1206 Performs an complex FFT on the input, din, and stores the complex result in dout. Performs 2^log2N point calculation, and the working buffer scratch as well as the input and output must be 2^log2N in length. Coefficient twiddle factors come from twiddles, and may be loaded with the use of DSP_TransformFFT16_setup. All values are 16 bit (Q31) fractional. Preconditions din, dout, twiddles and scratch must have N elements N is calculated as 2^(log2N) log2N must be >= 3 FFT factors must be calculated in advance, use DSP_TransformFFT32_setup Parameters Parameters Description dout pointer to complex output array (int32c) din pointer to complex input array (int32c) twiddles pointer to an complex array of FFT factors (int32c) scratch pointer to a complex scratch pad buffer (int32c) log2N binary exponent of number of samples (int) Returns None. Remarks Scratch must be declared but need not be initialized. Din may be aided with a window function prior to calling the FFT, but is not required. Din is a complex number array, but may be loaded solely with real numbers if no phase information is available. Example int log2N = 8; // log2(256) = 8 int fftSamples = 256; int32c *fftDin; int32c fftDout[fftSamples]; int32c scratch[fftSamples]; int32c fftCoefs[fftSamples]; int32c *fftc; fftc = &fftCoefs; DSP_TransformFFT32_setup(fftc, log2N); // call setup function while (1) { fftDin = &fftin_5Khz_long_window32; // get 256 point complex data DSP_TransformFFT32(fftDout, fftDin, fftc, scratch, log2N); // do something with the output, fftDout }; 5.4.1.5.4.4 DSP_TransformFFT32_setup Function C void DSP_TransformFFT32_setup( int32c * twiddles, int log2N ); Description Function DSP_TransformFFT32_setup: void DSP_TransformFFT32_setup(int32c *twiddles, int log2N); 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1207 Calculates the N FFT twiddle factors required to operate the FFT32 function. These factors are done in serial fashion, and require considerable processing power. Ideally this function would be run only once prior to an ongoing FFT, and the results held in a buffer. Preconditions twiddles must be N in length N is calculated (2^log2N) Parameters Parameters Description twiddles pointer to a complex array of coefficients (int32c) log2N binary exponent of number of data points (int) Returns None. Remarks This function is of considerable length and executed in C. It is recommended it only be called once for any given FFT length in time sensitive applications. Example see DSP_TransformFFT32 for example. 5.4.1.5.4.5 DSP_TransformIFFT16 Function C void DSP_TransformIFFT16( int16c * dout, int16c * din, int16c * twiddles, int16c * scratch, int log2N ); Description Function DSP_TransformIFFT16: void DSP_TransformIFFT16(int16c *dout, int16c *din, int16c *twiddles, int16c *scratch, int log2N); Performs an complex Inverse FFT on the input, din, and stores the complex result in dout. Performs 2^log2N point calculation, and the working buffer scratch as well as the input and output must be 2^log2N in length. Coefficient twiddle factors come from twiddles, and may be loaded with the use of DSP_TransformFFT16_setup. All values are 16 bit (Q15) fractional. Preconditions din, dout, twiddles and scratch must have N elements N is calculated as 2^(log2N) log2N must be >= 3 FFT factors must be calculated in advance, use DSP_TransformFFT16_setup Parameters Parameters Description dout pointer to complex output array (int16c) din pointer to complex input array (int16c) twiddles pointer to an complex array of factors (int16c) scratch pointer to a complex scratch pad buffer (int16c) log2N binary exponent of number of samples (int) 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1208 Returns None. Remarks Scratch must be declared but need not be initialized. Din may be aided with a window function prior to calling the FFT, but is not required. A very similar function to the FFT is executed for the inverse FFT. This requires twiddle factors set in advance with the same method as used in the FFT. Complex conjugate and scaling are handled within the algorithm. The output is scaled using binary shifting based on log2N. Since the algorithm reduces the output by a scale factor of log2N, the resolution is reduced proportionally to the number of data points. Example int ilog2N = 10; // log2(64) = 6; log2(256) = 8; log2(1024) = 10; int ifftSamples = pow(2,ilog2N); int16c *ifftDin; int16c ifftDout[ifftSamples]; int16c iscratch[ifftSamples]; int16c ifftCoefs[ifftSamples]; int16c ifftTimeOut[ifftSamples]; // set up twiddle factors, these are used for both FFT and iFFT int16c *ifftc; ifftc = &ifftCoefs; DSP_TransformFFT16_setup( ifftc, ilog2N); // call to coef setup // in this example, we take an FFT of an original time domain (sine wave) // the output of the FFT is used as the input of the iFFT for comparison ifftDin = &fftin_800hz_verylong16; DSP_TransformFFT16(ifftDout, ifftDin, ifftc, iscratch, ilog2N); // ifftDout = frequency domain output, complex number array DSP_TransformIFFT16(ifftTimeOut, ifftDout, ifftc, iscratch, ilog2N); // do something with the output, fftTimeOut, time domain 5.4.1.5.4.6 DSP_TransformWindow_Bart16 Function C void DSP_TransformWindow_Bart16( int16_t * OutVector, int16_t * InVector, int N ); Description Function DSP_TransformWindow_Bart16: void DSP_TransformWindow_Bart16(int16_t *OutVector, int16_t *InVector, int N); Compute a Bartlett (Triangle) Window on the first N samples of the input vector, InVector. The output is stored in OutVector. Operations are performed at higher resolution and rounded for the most accuracy possible. Input and output values are in Q15 fractional format. The Bartlett Window follows the equation: Window(n) = 1 - (abs(2*n - N)/N) where n is the window sample number N is the total number of samples The functional output computes WinVector(n) = Window(n) * InVector(n) 5.4 Math Library Help MPLAB Harmony Help DSP Fixed-Point Library 5-1209 Preconditions N must be a positive number. OutWindow must be declared with N elements or larger. Parameters Parameters Description OutWindow pointer to output array of elements (int16_t) N number of samples (int) Returns None. Remarks This function is performed in C. The function may be optimized for the library. It is dependent on the floating point math library. Example int16_t OutVector16[8]={0}; int WindowN = 8; for (i=0;i 0x6488 And converting from the _Q7_8 format with the value 0x1D89 would be: 0x1D89 / 28 = 7561 / 256 => 29.5316, accurate to 0.00391 Functions in the library are prefixed with the type of the return value. For example, _LIBQ_Q16Sqrt returns a _Q16 value equal to the square root of its argument. Argument types do not always match the return type. Refer to the function prototype for a specification of its arguments. In cases where the return value is not a fixed-point type, the argument type is appended to the function name. For example, _LIBQ_ToFloatQ31 accepts a type _Q31 argument. In some cases, both the return type and the argument type are specified within the function name. For example: Function Name Return Type Argument Type _LIBQ_Q15_sin_Q2_13 _Q15 _Q2_13 _LIBQ_Q31_sin_Q2_29 _Q31 _Q2_29 5.4.2.4.2 Table of Library Functions Math Function Function Definition Divide _Q16 _LIBQ_Q16Div (_Q16 dividend, _Q16 divisor); Square Root _Q16 _LIBQ_Q16Sqrt (_Q16 x); Exponential _Q16 _LIBQ_Q16Exp (_Q16 x); Log _Q4_11 _LIBQ_Q4_11_ln_Q16 (_Q16 x); _Q3_12 _LIBQ_Q3_12_log10_Q16 (_Q16 x); _Q5_10 _LIBQ_Q5_10_log2_Q16 (_Q16 x); Power _Q16 _LIBQ_Q16Power (_Q16 x, _Q16 y); Sine _Q15 _LIBQ_Q15_sin_Q2_13 (_Q2_13 x); _Q31 _LIBQ_Q31_sin_Q2_29 (_Q2_29 x); 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1277 Cosine _Q15 _LIBQ_Q15_cos_Q2_13 (_Q2_13 x); _Q31 _LIBQ_Q31_cos_Q2_29 (_Q2_29 x); Tangent _Q7_8 _LIBQ_Q7_8_tan_Q2_13 (_Q2_13 x); _Q16 _LIBQ_Q16_tan_Q2_29 (_Q2_29 x); Arcsin _Q2_13 _LIBQ_Q2_13_asin_Q15 (_Q15 x); _Q2_29 _LIBQ_Q2_29_asin_Q31 (_Q31 x); _Q2_29 _LIBQ_Q2_29_asin_Q31_Fast (_Q31 x); Arccos _Q2_13 _LIBQ_Q2_13_acos_Q15 (_Q15 x); _Q2_29 _LIBQ_Q2_29_acos_Q31 (_Q31 x); _Q2_29 _LIBQ_Q2_29_acos_Q31_Fast (_Q31 x); Arctan _Q2_13 _LIBQ_Q2_13_atan_Q7_8 (_Q7_8 x); _Q2_29 _LIBQ_Q2_29_atan_Q16 (_Q16 x); Arctan2 _Q2_13 _LIBQ_Q2_13_atan2_Q7_8 (_Q7_8 y, _Q7_8 x); _Q2_29 _LIBQ_Q2_29_atan2_Q16 (_Q16 y, _Q16 x); Random Number _Q15 _LIBQ_Q15Rand (int64_t *pSeed); _Q31 _LIBQ_Q31Rand (int64_t *pSeed); Float float _LIBQ_ToFloatQ31 (_Q31 x); float _LIBQ_ToFloatQ15 (_Q15 x); _Q31 _LIBQ_Q31FromFloat (float x); _Q15 _LIBQ_Q15FromFloat (float x); String void _LIBQ_ToStringQ15 (_Q15 x, char *s); _Q15 _LIBQ_Q15FromString (char *s); 5.4.2.5 Library Interface Data Types and Constants Name Description _Q15_MAX Maximum value of _Q15 (~1.0) _Q15_MIN Minimum value of _Q15 (-1.0) _Q16_MAX Maximum value of _Q16 (~32768.0) _Q16_MIN Minimum value of _Q16 (-32768.0) _Q2_13_MAX Maximum value of _Q2_13 (~4.0) _Q2_13_MIN Minimum value of _Q2_13 (-4.0) _Q2_29_MAX Maximum value of _Q2_29 (~4.0) _Q2_29_MIN Minimum value of _Q2_29 (-4.0) _Q3_12_MAX Maximum value of _Q3_12 (~8.0) _Q3_12_MIN Minimum value of _Q3_12 (-8.0) _Q31_MAX Maximum value of _Q31 (~1.0) _Q31_MIN Minimum value of _Q31 (-1.0) _Q4_11_MAX Maximum value of _Q4_11 (~16.0) _Q4_11_MIN Minimum value of _Q4_11 (-16.0) _Q5_10_MAX Maximum value of _Q5_10 (~32.0) _Q5_10_MIN Minimum value of _Q5_10 (-32.0) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1278 _Q7_8_MAX Maximum value of _Q7_8 (~128.0) _Q7_8_MIN Minimum value of _Q7_8 (-128.0) _Q0_15 1 sign bit, 15 bits right of radix _Q0_31 1 sign bit, 31 bits right of radix _Q15 Short name for _Q0_15 _Q15_16 1 sign bit, 15 bits left of radix, 16 bits right of radix _Q16 Short name for _Q15_16 _Q2_13 1 sign bit, 2 bits left of radix, 13 bits right of radix _Q2_29 1 sign bit, 2 bits left of radix, 29 bits right of radix _Q3_12 1 sign bit, 3 bits left of radix, 12 bits right of radix _Q31 Short name for _Q_0_31 _Q4_11 1 sign bit, 4 bits left of radix, 11 bits right of radix _Q5_10 1 sign bit, 5 bits left of radix, 10 bits right of radix _Q7_8 1 sign bit, 7 bits left of radix, 8 bits right of radix Arccos Functions Name Description _LIBQ_Q2_13_acos_Q15 Calculates the value of acos(x). _LIBQ_Q2_29_acos_Q31 Calculates the value of acos(x). _LIBQ_Q2_29_acos_Q31_Fast Calculates the value of acos(x). This function executes faster than _LIBQ_Q2_29_acos_Q31 but is less precise. Arcsin Functions Name Description _LIBQ_Q2_13_asin_Q15 Calculates the asin value of asin(x). _LIBQ_Q2_29_asin_Q31 Calculates the value of asin(x). _LIBQ_Q2_29_asin_Q31_Fast Calculates the value of asin(x). This function executes faster than the _LIBQ_Q2_29_asin_Q31 function, but is less precise. Arctan Functions Name Description _LIBQ_Q2_13_atan_Q7_8 Calculates the value of atan(x). _LIBQ_Q2_29_atan_Q16 Calculates the value of atan(x). Arctan2 Functions Name Description _LIBQ_Q2_13_atan2_Q7_8 Calculates the value of atan2(y, x). _LIBQ_Q2_29_atan2_Q16 Calculates the value of atan2(y, x). Cosine Functions Name Description _LIBQ_Q15_cos_Q2_13 Calculates the value of cosine(x). _LIBQ_Q31_cos_Q2_29 Calculates the value of cosine(x). Divide Functions Name Description _LIBQ_Q16Div _Q16 fixed point divide. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1279 Exponential Functions Name Description _LIBQ_Q16Exp Calculates the exponential function e^x. Float Functions Name Description _LIBQ_Q15FromFloat Converts a float to a _Q15 value. _LIBQ_Q31FromFloat Converts a float to a _Q31 value. _LIBQ_ToFloatQ15 Converts a _Q15 value to a float. _LIBQ_ToFloatQ31 Converts a _Q31 value to a float. Log Functions Name Description _LIBQ_Q3_12_log10_Q16 Calculates the value of Log10(x). _LIBQ_Q4_11_ln_Q16 Calculates the natural logarithm ln(x). _LIBQ_Q5_10_log2_Q16 Calculates the value of log2(x). Power Functions Name Description _LIBQ_Q16Power Calculates the value of x raised to the y power (x^y). Random Number Functions Name Description _LIBQ_Q15Rand Generate a _Q15 random number. _LIBQ_Q31Rand Generate a _Q31 random number. Sine Functions Name Description _LIBQ_Q15_sin_Q2_13 Calculates the value of sine(x). _LIBQ_Q31_sin_Q2_29 Calculates the value of sine(x). Square Root Functions Name Description _LIBQ_Q16Sqrt Square root of a positive _Q16 fixed point value. String Functions Name Description _LIBQ_Q15FromString Ascii to _Q15 conversion. _LIBQ_ToStringQ15 _Q15 to ascii conversion. Target Functions Name Description _LIBQ_Q16_tan_Q2_29 Calculates the value of tan(x). _LIBQ_Q7_8_tan_Q2_13 Calculates the value of tan(x). Description This section describes the Application Programming Interface (API) functions, macros, and types of the LibQ Fixed Point Math Library. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1280 Refer to each section for a detailed description. 5.4.2.5.1 Divide Functions 5.4.2.5.1.1 _LIBQ_Q16Div Function C _Q16 _LIBQ_Q16Div( _Q16 dividend, _Q16 divisor ); Description Function _LIBQ_Q16Div: _Q16 _LIBQ_Q16Div (_Q16 dividend, _Q16 divisor); Quotient (_Q16) = Dividend (_Q16) / Divisor (_Q16). Preconditions Divisor must not equal 0. Parameters Parameters Description dividend The divide operation dividend (_Q16) divisor The divide operation divisor (_Q16) Returns _Q16 quotient of the divide operation Remarks The _LIBQ_Q16Div operation saturates its result. Execution Time (cycles): 143 typical (80 to 244) Program Memory 204 bytes Error <= 0.000015258789 (accurate to least significant _Q16 bit within the non-saturated range) Example _Q16 quotient, dividend, divisor; dividend = (_Q16)0x00010000; // 1 divisor = (_Q16)0x00008000; // 0.5 quotient = _LIBQ_Q16Div (dividend, divisor); // quotient now equals 2; ie. (_Q16)0x00020000; 5.4.2.5.2 Square Root Functions 5.4.2.5.2.1 _LIBQ_Q16Sqrt Function C _Q16 _LIBQ_Q16Sqrt( _Q16 x ); 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1281 Description Function _LIBQ_Q16Sqrt: _Q16 _LIBQ_Q16Sqrt(_Q16 x); Calculate the square root of a positive _Q16 fixed point value, and return the _Q16 result. Preconditions The input value must be positive. Parameters Parameters Description x The _Q16 fixed point value input from which to find the square root. Returns _LIBQ_Q16Sqrt returns the _Q16 fixed point value which is the square root of the input parameter. Remarks Execution Time (cycles): 240 typical (104 to 258) Program Memory 152 bytes Error <= 0.000015258789 (accurate to least significant _Q16 bit) Example _Q16 squareRoot; squareRoot = _LIBQ_Q16Sqrt((_Q16)0x01000000); // The square root of 256.0 is 16.0 (0x00100000) squareRoot = _LIBQ_Q16Sqrt((_Q16)0x00004000); // The square root of 0.25 is 0.5 (0x00008000) squareRoot = _LIBQ_Q16Sqrt((_Q16)0x5851f42d); // The square root of 22609.953125 is 150.366074 (0x00965db7) 5.4.2.5.3 Log Functions 5.4.2.5.3.1 _LIBQ_Q3_12_log10_Q16 Function C _Q3_12 _LIBQ_Q3_12_log10_Q16( _Q16 x ); Description Function _LIBQ_Q3_12_log10_Q16: _Q3_12 _LIBQ_Q3_12_log10_Q16 (_Q16 x); Calculates the log10(x), where log10(x) = ln(x) * log10(e). x is of type _Q16 and must be positive. The resulting value is of type _Q3_12. Preconditions The input x must be positive. Parameters Parameters Description x The input value from which to calculate log10(x). 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1282 Returns _LIBQ_Q3_12_log10_Q16 returns the _Q3_12 fixed point result from the calculation log10(x). Remarks Execution Time (cycles): 301 typical (14 to 346) Program Memory 176 bytes Error <= 0.000244140625 (accurate to least significant _Q3_12 bit) Example _Q3_12 resultLog10; resultLog10 = _LIBQ_Q3_12_log10_Q16 ((_Q16)0x12ed7d91); // _LIBQ_Q3_12_log10_Q16(4845.490494) = 3.685303 (0x3af7) 5.4.2.5.3.2 _LIBQ_Q4_11_ln_Q16 Function C _Q4_11 _LIBQ_Q4_11_ln_Q16( _Q16 x ); Description Function _LIBQ_Q4_11_ln_Q16: _Q4_11 _LIBQ_Q4_11_ln_Q16 (_Q16 x); Calculates the natural logarithm ln(x). x is of type _Q16 and must be positive. The resulting value is of type _Q4_11. Preconditions The input x must be positive. Parameters Parameters Description x The input value from which to calculate ln(x). Returns _LIBQ_Q4_11_ln_Q16 returns the _Q4_11 fixed point result from the calculation ln(x). Remarks Execution Time (cycles): 301 typical (14 to 346) Program Memory 176 bytes Error <= 0.00048828 (accurate to least significant _Q4_11 bit) Example _Q4_11 resultLN; resultLN = _LIBQ_Q4_11_ln_Q16 ((_Q16)0x00004000); // _LIBQ_Q4_11_LN_Q16(0.250000) = -1.386230 (0xf4e9) 5.4.2.5.3.3 _LIBQ_Q5_10_log2_Q16 Function C _Q5_10 _LIBQ_Q5_10_log2_Q16( _Q16 x ); Description Function _LIBQ_Q5_10_log2_Q16: 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1283 _Q5_10 _LIBQ_Q5_10_log2_Q16 (_Q16 x); Calculates the log2(x), where log2(x) = ln(x) * log2(e). x is of type _Q16 and must be positive. The resulting value is of type _Q5_10. Preconditions The input x must be positive. Parameters Parameters Description x The input value from which to calculate log2(x). Returns _LIBQ_Q5_10_log2_Q16 returns the _Q5_10 fixed point result from the calculation log2(x). Remarks Execution Time (cycles): 227 typical (14 to 268) Program Memory 164 bytes Error <= 0.0009765625 (accurate to least significant _Q5_10 bit) Example _Q5_10 resultLog2; resultLog2 = _LIBQ_Q5_10_log2_Q16 ((_Q16)0x40000000); // _LIBQ_Q5_10_log2_Q16(16384.000000) = 14.000000 (0x3800) 5.4.2.5.4 Power Functions 5.4.2.5.4.1 _LIBQ_Q16Power Function C _Q16 _LIBQ_Q16Power( _Q16 x, _Q16 y ); Description Function _LIBQ_Q16Power: _Q16 _LIBQ_Q16Power (_Q16 x, _Q16 y); Calculates the x raised to the y power. Both x and y are of type _Q16. x must be positive. The calculation will saturate if the resulting value is outside the range of the _Q16 representation. Preconditions x must be positive. Parameters Parameters Description x The _Q16 input value x from which to calculate x raised to the y. y The _Q16 input value y from which to calculate x raised to the y. Returns _LIBQ_Q16Power returns the _Q16 fixed point result from the calculation x raised to the y. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1284 Remarks Execution Time (cycles): 882 typical (586 to 1042) Program Memory 1038 bytes Error <= 0.000015258789 (accurate to least significant _Q16 bit within the non-saturated range) Example _Q16 resultPower; resultPower = _LIBQ_Q16Power ((_Q16)0x00020000, (_Q16)0xffff0000); // _LIBQ_Q16Power(2.000000, -1.000000) = 0.500000 (0x00008000) 5.4.2.5.5 Exponential Functions 5.4.2.5.5.1 _LIBQ_Q16Exp Function C _Q16 _LIBQ_Q16Exp( _Q16 x ); Description Function _LIBQ_Q16Exp: _Q16 _LIBQ_Q16Exp(_Q16 x); Calculates the exponential function e^x. The calculation will saturate if the resulting value is outside the range of the _Q16 representation. For x > 10.3972015380859375, the resulting value will be saturated to 0x7fffffff. For x < -10.3972015380859375 the resulting value will be saturated to 0. Preconditions None. Parameters Parameters Description x The exponent value Returns _LIBQ_Q16Exp returns the _Q16 fixed point result from the calculation e^x. Remarks The function _LIBQ_Q16Div is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 170 typical (18 to 292) Program Memory 446 bytes Error <= 0.000015258789 (accurate to least significant _Q16 bit within the non-saturated range) Example _Q16 expResult; expResult = _LIBQ_Q16Exp((_Q16)0x00010000); // _LIBQ_Q16Exp(1.000000) = 2.718277 (0x0002b7e1) 5.4.2.5.6 Sine Functions 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1285 5.4.2.5.6.1 _LIBQ_Q15_sin_Q2_13 Function C _Q15 _LIBQ_Q15_sin_Q2_13( _Q2_13 x ); Description Function _LIBQ_Q15_sin_Q2_13: _Q15 _LIBQ_Q15_sin_Q2_13 (_Q2_13 x); Calculates the sine(x), where x is of type _Q2_13 radians and the resulting value is of type _Q15. Preconditions None. Parameters Parameters Description x The _Q2_13 input value from which to calculate sine(x). Returns _LIBQ_Q15_sin_Q2_13 returns the _Q15 fixed point result from the calculation sine(x). Remarks Execution Time (cycles): 100 typical (100 to 102) Program Memory 220 bytes Error <= 0.00003052 (accurate to least significant _Q15 bit) Example _Q15 resultSin; resultSin = _LIBQ_Q15_sin_Q2_13 ((_Q2_13)0x4093); // _LIBQ_Q15_sin_Q2_13(2.017944) = 0.901672 (0x736a) 5.4.2.5.6.2 _LIBQ_Q31_sin_Q2_29 Function C _Q31 _LIBQ_Q31_sin_Q2_29( _Q2_29 x ); Description Function _LIBQ_Q31_sin_Q2_29: _Q31 _LIBQ_Q31_sin_Q2_29 (_Q2_29 x); Calculates the sine(x), where x is of type _Q2_29 radians and the resulting value is of type _Q31. Preconditions None. Parameters Parameters Description x The _Q2_29 input value from which to calculate sine(x). 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1286 Returns _LIBQ_Q31_sin_Q2_29 returns the _Q31 fixed point result from the calculation sine(x). Remarks Execution Time (cycles): 246 typical (244 to 266) Program Memory 598 bytes Error <= 0.00000000047 (accurate to least significant _Q31 bit) Example _Q31 resultSin; resultSin = _LIBQ_Q31_sin_Q2_29 ((_Q2_29)0x5a637cfe); // _LIBQ_Q31_sin_Q2_29( 2.824644562) = 0.311668121 (0x27e4bdb1) 5.4.2.5.7 Cosine Functions 5.4.2.5.7.1 _LIBQ_Q15_cos_Q2_13 Function C _Q15 _LIBQ_Q15_cos_Q2_13( _Q2_13 x ); Description Function _LIBQ_Q15_cos_Q2_13: _Q15 _LIBQ_Q15_cos_Q2_13 (_Q2_13 x); Calculates the cosine(x), where x is of type _Q2_13 radians and the resulting value is of type _Q15. Preconditions None Parameters Parameters Description x The _Q2_13 input value from which to calculate cosine(x). Returns _LIBQ_Q15_cos_Q2_13 returns the _Q15 fixed point result from the calculation cosine(x). Remarks Execution Time (cycles): 102 cycles Program Memory 224 bytes Error <= 0.00003052 (accurate to least significant _Q15 bit) Example _Q15 resultCos; resultCos = _LIBQ_Q15_cos_Q2_13 ((_Q2_13)0x2171); // _LIBQ_Q15_cos_Q2_13(1.045044) = 0.501862 (0x403d) 5.4.2.5.7.2 _LIBQ_Q31_cos_Q2_29 Function C _Q31 _LIBQ_Q31_cos_Q2_29( _Q2_29 x 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1287 ); Description Function _LIBQ_Q31_cos_Q2_29: _Q31 _LIBQ_Q31_cos_Q2_29 (_Q2_29 x); Calculates the cosine(x), where x is of type _Q2_29 radians and the resulting value is of type _Q31. Preconditions None. Parameters Parameters Description x The _Q2_29 input value from which to calculate cosine(x). Returns _LIBQ_Q31_cos_Q2_29 returns the _Q31 fixed point result from the calculation sine(x). Remarks Execution Time (cycles): 265 typical (22 to 288) Program Memory 746 bytes Error <= 0.00000000047 (accurate to least significant _Q31 bit) Example _Q31 resultCos; resultCos = _LIBQ_Q31_cos_Q2_29 ((_Q2_29)0x07e2e1c2); // _LIBQ_Q31_cos_Q2_29( 0.246445540) = 0.969785686 (0x7c21eff7) 5.4.2.5.8 Target Functions 5.4.2.5.8.1 _LIBQ_Q16_tan_Q2_29 Function C _Q16 _LIBQ_Q16_tan_Q2_29( _Q2_29 x ); Description Function _LIBQ_Q16_tan_Q2_29: _Q16 _LIBQ_Q16_tan_Q2_29 (_Q2_29 x); Calculates the tan(x), where x is of type _Q2_29 radians and the resulting value is of type _Q16. Preconditions None Parameters Parameters Description x The _Q2_29 input value from which to calculate tan(x). Returns _LIBQ_Q16_tan_Q2_29 returns the _Q16 fixed point result from the calculation tan(x). The resulting value is saturated. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1288 Remarks The functions _LIBQ_Q31_sin_Q2_29, _LIBQ_Q31_cos_Q2_29, and _LIBQ_Q16Div are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 703 typical (22 to 796) Program Memory 88 bytes Error <= 0.000015259 (accurate to least significant _Q16 bit for the input range -1.568 .. 1.568) Error rises from 0.0 to 0.065 for the input range -1.568 .. -1.570765808 and 1.568 .. 1.570765808) Example _Q16 resultTan; resultTan = _LIBQ_Q16_tan_Q2_29 ((_Q2_29)0x16720c36); // _LIBQ_Q16_tan_Q2_29( 0.701421838) = 0.844726562 (0x0000d840) 5.4.2.5.8.2 _LIBQ_Q7_8_tan_Q2_13 Function C _Q7_8 _LIBQ_Q7_8_tan_Q2_13( _Q2_13 x ); Description Function _LIBQ_Q7_8_tan_Q2_13: _Q7_8 _LIBQ_Q7_8_tan_Q2_13 (_Q2_13 x); Calculates the tan(x), where x is of type _Q2_13 radians and the resulting value is of type _Q7_8. Preconditions None Parameters Parameters Description x The _Q2_13 input value from which to calculate tan(x). Returns _LIBQ_Q7_8_tan_Q2_13 returns the _Q7_8 fixed point result from the calculation tan(x). Remarks Execution Time (cycles): 288 typical (18 to 346) Program Memory 980 bytes Error <= 0.00390625 (accurate to least significant _Q7_8 bit) Example _Q7_8 resultTan; resultTan = _LIBQ_Q7_8_tan_Q2_13 ((_Q2_13)0x2e20); // _LIBQ_Q7_8_tan_Q2_13(1.441406) = 7.683594 (0x07af) 5.4.2.5.9 Arcsin Functions 5.4.2.5.9.1 _LIBQ_Q2_13_asin_Q15 Function C _Q2_13 _LIBQ_Q2_13_asin_Q15( 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1289 _Q15 x ); Description Function _LIBQ_Q2_13_asin_Q15: _Q2_13 _LIBQ_Q2_13_asin_Q15 (_Q15 x); Calculates asin(x), where x is of type _Q15 and the resulting value is of type _Q2_13. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q15 input value from which to calculate asin(x). Returns _LIBQ_Q2_13_asin_Q15 returns the _Q2_13 fixed point result from the calculation asin(x). Remarks The functions _LIBQ_Q16Sqrt and _LIBQ_Q16Div are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 578 typical (22 to 656) Program Memory 336 bytes Error <= 0.00012207 (accurate to least significant _Q2_13 bit) A higher resolution version of this function exists with equivalent performance, see _LIBQ_Q2_29_asin_Q31_Fast Example _Q2_13 resultAsin; resultAsin = _LIBQ_Q2_13_asin_Q15 ((_Q15)0x3231); // _LIBQ_Q2_13_asin_Q15(0.392120) = 0.402954 (0x0ce5) 5.4.2.5.9.2 _LIBQ_Q2_29_asin_Q31 Function C _Q2_29 _LIBQ_Q2_29_asin_Q31( _Q31 x ); Description Function _LIBQ_Q2_29_asin_Q31: _Q2_29 _LIBQ_Q2_29_asin_Q31 (_Q31 x); Calculates the asin(x), where x is of type _Q31 and the resulting value is of type _Q2_29. The output value will be in radians the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q31 input value from which to calculate asin(x). 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1290 Returns _LIBQ_Q2_29_asin_Q31 returns the _Q2_29 fixed point result from the calculation asin(x). Remarks The functions _LIBQ_Q2_29_asin_Q31_Fast and_LIBQ_Q31_sin_Q2_29 are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 2525 typical (286 to 4330) Program Memory 138 bytes Error <= 0.0000000019 (accurate to least significant _Q2_29 bit for the range -0.9993..0.9993) Error <= 0.0000000346 (accurate to 5th least significant _Q2_29 bit for the range -1.0 .. -0.9993 and 0.9993 .. 1.0) A faster version of this function exists with modestly reduced accuracy, see _LIBQ_Q2_29_asin_Q31_Fast Example _Q2_29 resultAsin; resultAsin = _LIBQ_Q2_29_asin_Q31 ((_Q31)0x7fe50658); // _LIBQ_Q2_29_asin_Q31( 0.9991767816) = 1.5302172359 (0x30f78a23) 5.4.2.5.9.3 _LIBQ_Q2_29_asin_Q31_Fast Function C _Q2_29 _LIBQ_Q2_29_asin_Q31_Fast( _Q31 x ); Description Function _LIBQ_Q2_29_asin_Q31_Fast: _Q2_29 _LIBQ_Q2_29_asin_Q31_Fast (_Q31 x); Calculates the asin(x), where x is of type _Q31 and the resulting value is of type _Q2_29. The output value will be in radians the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q31 input value from which to calculate asin(x). Returns _LIBQ_Q2_29_asin_Q31_Fast returns the _Q2_29 fixed point result from the calculation asin(x). Remarks Execution Time (cycles): 507 typical (22 to 1300) Program Memory 638 bytes Error <= 0.000000911 (accurate to 9 least significant _Q2_29 bits) A higher resolution version of this function exists with reduced performance, see _LIBQ_Q2_29_asin_Q31 Example _Q2_29 resultAsin; resultAsin = _LIBQ_Q2_29_asin_Q31_Fast ((_Q31)0x7fe50658); // _LIBQ_Q2_29_asin_Q31_Fast( 0.9991767816) = 1.5302172359 (0x30f78a23) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1291 5.4.2.5.10 Arccos Functions 5.4.2.5.10.1 _LIBQ_Q2_13_acos_Q15 Function C _Q2_13 _LIBQ_Q2_13_acos_Q15( _Q15 x ); Description Function _LIBQ_Q2_13_acos_Q15: _Q2_13 _LIBQ_Q2_13_acos_Q15 (_Q15 x); Calculates the acos(x), where x is of type _Q15 and the resulting value is of type _Q2_13. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q15 input value from which to calculate acos(x). Returns _LIBQ_Q2_13_acos_Q15 returns the _Q2_13 fixed point result from the calculation acos(x). Remarks The function _LIBQ_Q2_13_asin_Q15 is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 588 typical (32 to 666) Program Memory 24 bytes Error <= 0.00012207 (accurate to least significant _Q2_13 bit) A higher precision function with equivalent performance exists, see _LIBQ_Q2_29_acos_Q31_Fast Example _Q2_13 resultAcos; resultAcos = _LIBQ_Q2_13_acos_Q15((_Q15)0x2993); // _LIBQ_Q2_13_acos_Q15(0.324799) = 1.239990 (0x27ae) 5.4.2.5.10.2 _LIBQ_Q2_29_acos_Q31 Function C _Q2_29 _LIBQ_Q2_29_acos_Q31( _Q31 x ); Description Function _LIBQ_Q2_29_acos_Q31: _Q2_29 _LIBQ_Q2_29_acos_Q31 (_Q31 x); Calculates the acos(x), where x is of type _Q31 and the resulting value is of type _Q2_29. The output value will be radians in the range pi >= result >= -pi. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1292 Preconditions None. Parameters Parameters Description x The _Q31 input value from which to calculate acos(x). Returns _LIBQ_Q2_29_acos_Q31 returns the _Q2_29 fixed point result from the calculation acos(x). Remarks The functions _LIBQ_Q2_29_asin_Q31_Fast and _LIBQ_Q31_cos_Q2_29 are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 3370 typical (70 to 4824) Program Memory 142 bytes Error <= 0.0000000019 (accurate to least significant _Q2_29 bit for the range -0.9993..0.9993) Error <= 0.0000000355 (accurate to 5th least significant _Q2_29 bit for the range -1.0 .. -0.9993 and 0.9993 .. 1.0) A similar function with higher performance and reduced precision exists, see _LIBQ_Q2_29_acos_Q31_Fast Example _Q2_29 resultAcos; resultAcos = _LIBQ_Q2_29_acos_Q31 ((_Q31)0xee63708c); // _LIBQ_Q2_29_acos_Q31(-0.1375903431) = 1.7088244837 (0x36aeb0af) 5.4.2.5.10.3 _LIBQ_Q2_29_acos_Q31_Fast Function C _Q2_29 _LIBQ_Q2_29_acos_Q31_Fast( _Q31 x ); Description Function _LIBQ_Q2_29_acos_Q31_Fast: _Q2_29 _LIBQ_Q2_29_acos_Q31_Fast (_Q31 x); Calculates the acos(x), where x is of type _Q31 and the resulting value is of type _Q2_29. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q31 input value from which to calculate acos(x). Returns _LIBQ_Q2_29_acos_Q31_Fast returns the _Q2_29 fixed point result from the calculation acos(x). Remarks The function _LIBQ_Q2_29_asin_Q31_Fast is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 517 typical (32 to 1310) Program Memory 28 bytes 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1293 Error <= 0.000000911 (accurate to 9 least significant _Q2_29 bits) A higher precision function with reduced performance exists, see _LIBQ_Q2_29_acos_Q31 Example _Q2_29 resultAcos; resultAcos = _LIBQ_Q2_29_acos_Q31_Fast ((_Q31)0xee63708c); // _LIBQ_Q2_29_acos_Q31_Fast(-0.1375903431) = 1.7088244837 (0x36aeb0af) 5.4.2.5.11 Arctan Functions 5.4.2.5.11.1 _LIBQ_Q2_13_atan_Q7_8 Function C _Q2_13 _LIBQ_Q2_13_atan_Q7_8( _Q7_8 x ); Description Function _LIBQ_Q2_13_atan_Q7_8: _Q2_13 _LIBQ_Q2_13_atan_Q7_8 (_Q7_8 x); Calculates the atan(x), where x is of type _Q7_8 and the resulting value is of type _Q2_13. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q7_8 input value from which to calculate atan(x). Returns _LIBQ_Q2_13_atan_Q7_8 returns the _Q2_13 fixed point result from the calculation atan(x). Remarks The function _LIBQ_Q2_13_atan2_Q7_8 is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 240 typical (202 to 256) Program Memory 16 bytes Error <= 0.00012207 (accurate to least significant _Q2_13 bit) Example _Q2_13 resultAtan; resultAtan = _LIBQ_Q2_13_atan_Q7_8 ((_Q7_8)0x0097); // _LIBQ_Q2_13_atan_Q7_8(0.589844) = 0.532959 (0x110e) 5.4.2.5.11.2 _LIBQ_Q2_29_atan_Q16 Function C _Q2_29 _LIBQ_Q2_29_atan_Q16( _Q16 x ); 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1294 Description Function _LIBQ_Q2_29_atan_Q16: _Q2_29 _LIBQ_Q2_29_atan_Q16 (_Q16 x); Calculates the atan(x), where x is of type _Q16 and the resulting value is of type _Q2_29. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description x The _Q16 input value from which to calculate atan(x). Returns _LIBQ_Q2_29_atan_Q16 returns the _Q2_29 fixed point result from the calculation atan(x). Remarks The function _LIBQ_Q2_29_atan2_Q16 is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 354 typical (178 to 360) Program Memory 16 bytes Error <= 0.000000003 (accurate within one least significant _Q2_29 bit) Example _Q2_29 resultAtan; resultAtan = _LIBQ_Q2_29_atan_Q16 ((_Q16)0x00098b31); // _LIBQ_Q2_29_atan_Q16(9.543716) = 1.466396 (0x2eecb7ee) 5.4.2.5.12 Arctan2 Functions 5.4.2.5.12.1 _LIBQ_Q2_13_atan2_Q7_8 Function C _Q2_13 _LIBQ_Q2_13_atan2_Q7_8( _Q7_8 y, _Q7_8 x ); Description Function _LIBQ_Q2_13_atan2_Q7_8: _Q2_13 _LIBQ_Q2_13_atan2_Q7_8 (_Q7_8 y, _Q7_8 x); Calculates the atan2(y, x), where y and x are of type _Q7_8 and the resulting value is of type _Q2_13. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description y The _Q7_8 input value from which to calculate atan2(y, x). 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1295 x The _Q7_8 input value from which to calculate atan2(y, x). Returns _LIBQ_Q2_13_atan2_Q7_8 returns the _Q2_13 fixed point result from the calculation atan2(y, x). Remarks The function _LIBQ_Q16Div is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 220 typical (22 to 250) Program Memory 288 bytes Error <= 0.00012207 (accurate to least significant _Q2_13 bit) Example _Q2_13 resultAtan2; resultAtan2 = _LIBQ_Q2_13_atan2_Q7_8 ((_Q7_8)0x589d, (_Q7_8)0xf878); // _LIBQ_Q2_13_atan2_Q7_8(88.613281, -7.531250) = 1.655518 (0x34fa) 5.4.2.5.12.2 _LIBQ_Q2_29_atan2_Q16 Function C _Q2_29 _LIBQ_Q2_29_atan2_Q16( _Q16 y, _Q16 x ); Description Function _LIBQ_Q2_29_atan2_Q16: _Q2_29 _LIBQ_Q2_29_atan2_Q16 (_Q16 y, _Q16 x); Calculates the atan(y, x), where y and x are of type _Q16 and the resulting value is of type _Q2_29. The output value will be radians in the range pi >= result >= -pi. Preconditions None. Parameters Parameters Description y The _Q16 input value from which to calculate atan2(y, x). x The _Q16 input value from which to calculate atan2(y, x). Returns _LIBQ_Q2_29_atan2_Q16 returns the _Q2_29 fixed point result from the calculation atan2(y, x). Remarks The C function __divdi3 is called by this routine and thus must be linked into the executable image. Execution Time (cycles): 348 typical (20 to 376) Program Memory 464 bytes Error <= 0.000000003 (accurate within one least significant _Q2_29 bit) Example _Q2_29 resultAtan2; resultAtan2 = _LIBQ_Q2_29_atan2_Q16 ((_Q16)0xf6276270, x(_Q16)0x34b4b4c0); // _LIBQ_Q2_29_atan2_Q16(-2520.615479, 13492.706055) = -0.184684 (0xfa1710c7) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1296 5.4.2.5.13 Random Number Functions 5.4.2.5.13.1 _LIBQ_Q15Rand Function C _Q15 _LIBQ_Q15Rand( int64_t * pSeed ); Description Function _LIBQ_Q15Rand: _Q15 _LIBQ_Q15Rand (int64_t *pSeed); Generates a _Q15 pseudo-random value based on the seed supplied as a parameter. The first time this function is called, the seed value must be supplied by the user; this initial seed value can either be constant or random, depending on whether the user wants to generate a repeatable or a non-repeatable pseudo-random sequence. The function updates the *pSeed value each time it is called. The updated *pSeed value must be passed back to the function with each subsequent call. Warning: The pseudo-random sequence generated by this function may be insufficient for cryptographic use. Preconditions None. Parameters Parameters Description pSeed A pointer to the seed value used by the function to generate a pseudo-random sequence. Returns _LIBQ_Q15Rand returns a random _Q15 value. _LIBQ_Q15Rand also updates the int64_t *pSeed value. Remarks Execution Time (cycles): 32 Program Memory 92 bytes Example // Initialize seed to a constant or random value static int64_t randomSeed = 0xA71078BE72D4C1F1; _Q15 randomValue; randomValue = _LIBQ_Q15Rand(&randomSeed); ... randomValue = _LIBQ_Q15Rand(&randomSeed); 5.4.2.5.13.2 _LIBQ_Q31Rand Function C _Q31 _LIBQ_Q31Rand( int64_t * pSeed ); Description Function _LIBQ_Q31Rand: 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1297 _Q31 _LIBQ_Q31Rand (int64_t *pSeed); Generates a _Q31 pseudo-random value based on the seed supplied as a parameter. The first time this function is called, the seed value must be supplied by the user; this initial seed value can either be constant or random, depending on whether the user wants to generate a repeatable or a non-repeatable pseudo-random sequence. The function updates the *pSeed value each time it is called. The updated *pSeed value must be passed back to the function with each subsequent call. Warning: The pseudo-random sequence generated by this function may be insufficient for cryptographic use. Preconditions None. Parameters Parameters Description pSeed A pointer to the seed value used by the function to generate a pseudo-random sequence. Returns _LIBQ_Q31Rand returns a pseudo-random _Q31 value. _LIBQ_Q31Rand also updates the int64_t *pSeed value. Remarks Execution Time (cycles): 32 Program Memory 88 bytes Example // Initialize seed to a constant or random value static int64_t randomSeed = 0x7F18BA710E72D4C1; _Q31 randomValue; randomValue = _LIBQ_Q31Rand(&randomSeed); ... randomValue = _LIBQ_Q31Rand(&randomSeed); 5.4.2.5.14 Float Functions 5.4.2.5.14.1 _LIBQ_Q15FromFloat Function C _Q15 _LIBQ_Q15FromFloat( float x ); Description Function _LIBQ_Q15FromFloat: _Q15 _LIBQ_Q15FromFloat(float x); Converts a floating point value to a _Q15 fixed point representation. The _Q15 fixed point value is returned by the function. The conversion will saturate if the value is outside the range of the _Q15 representation. Preconditions None. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1298 Parameters Parameters Description x The float point value to convert to _Q15 fixed point Returns _LIBQ_Q15FromFloat returns the _Q15 fixed point value corresponding to the floating point (float) input value. Remarks The C library functions __gesf2, __lesf2, __addsf3, __mulsf3, and __fixsfsi are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 213 typical (158 to 224) Program Memory 96 bytes Example _Q15 q15; q15 = _LIBQ_Q15FromFloat((float)0.5); // q15 now equals (_Q15)0x4000 q15 = _LIBQ_Q15FromFloat((float)-1.0); // q15 now equals (_Q15)0x8000 q15 = _LIBQ_Q15FromFloat((float)-0.233828); // q15 now equals (_Q15)0xe212 5.4.2.5.14.2 _LIBQ_Q31FromFloat Function C _Q31 _LIBQ_Q31FromFloat( float x ); Description Function _LIBQ_Q31FromFloat: _Q31 _LIBQ_Q31FromFloat(float x); Converts a floating point value to a _Q31 fixed point representation. The _Q31 fixed point value is returned by the function. The conversion will saturate if the value is outside the range of the _Q31 representation. Preconditions None. Parameters Parameters Description x The floating point value to convert to _Q31 fixed point. Returns _LIBQ_Q31FromFloat returns the _Q31 fixed point value corresponding to the floating point (float) input value. Remarks The C library functions __gesf2, __lesf2, __addsf3, __mulsf3, and __fixsfsi are called by this routine and thus must be linked into the executable image. Execution Time (cycles): 210 typical (158 to 214) Program Memory 100 bytes Example _Q31 q31; q31 = _LIBQ_Q31FromFloat((float)0.000008); // q31 now equals (_Q31)0x00004000 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1299 q31 = _LIBQ_Q31FromFloat((float)-1.0); // q31 now equals (_Q31)0x80000000 q31 = _LIBQ_Q31FromFloat((float)0.690001); // q31 now equals (_Q31)0x5851f400 5.4.2.5.14.3 _LIBQ_ToFloatQ15 Function C float _LIBQ_ToFloatQ15( _Q15 x ); Description Function _LIBQ_ToFloatQ15: float _LIBQ_ToFloatQ15(_Q15 x); Converts a _Q15 fixed point value to a floating point representation. The floating point value is returned by the function. Preconditions None. Parameters Parameters Description x The _Q15 fixed point value to convert to float Returns _LIBQ_ToFloatQ15 returns the floating point (float) value corresponding to the _Q15 input value. Remarks The C library functions __floatsisf and __divsf3 are called by this routine and thus must be linked in to the executable image. Execution Time (cycles): 158 typical (54 to 176) Program Memory 28 bytes Example float f; f = _LIBQ_ToFloatQ15((_Q15)0x4000); // f now equals 0.5 f = _LIBQ_ToFloatQ15((_Q15)0x8000); // f now equals -1.0 f = _LIBQ_ToFloatQ15((_Q15)0xb7ff); // f now equals -0.562531 5.4.2.5.14.4 _LIBQ_ToFloatQ31 Function C float _LIBQ_ToFloatQ31( _Q31 x ); Description Function _LIBQ_ToFloatQ31: float _LIBQ_ToFloatQ31(_Q31 x); Converts a _Q31 fixed point value to a floating point representation. The floating point value is returned by the function. Preconditions None. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1300 Parameters Parameters Description x The _Q31 fixed point value to convert to float Returns _LIBQ_ToFloatQ31 returns the floating point (float) value corresponding to the _Q31 input value. Remarks The C library functions __floatsisf and __divsf3 are called by this routine and thus must be linked in to the executable image. Execution Time (cycles): 163 typical (54 to 176) Program Memory 28 bytes Example float f; f = _LIBQ_ToFloatQ31((_Q31)0x00004000); // f now equals 0.000008 f = _LIBQ_ToFloatQ31((_Q31)0x80000000); // f now equals -1.0 f = _LIBQ_ToFloatQ31((_Q31)0x5851f42d); // f now equals 0.690001 5.4.2.5.15 String Functions 5.4.2.5.15.1 _LIBQ_Q15FromString Function C _Q15 _LIBQ_Q15FromString( char * s ); Description Function _LIBQ_Q15FromString: _Q15 _LIBQ_Q15FromString(char *s); Convert an ascii string into a _Q15 fixed point value. The ascii string must be in an -N.NNNNNN format. Leading spaces are ignored. The conversion stops at either the first non-conforming character in the string or the Null string terminator. There must be no spaces within the string value itself. Preconditions None. Parameters Parameters Description s A pointer to the ascii input string representing the _Q15 fixed point value. Returns _LIBQ_Q15FromString returns the _Q15 fixed point value represented by the input string. Remarks Execution Time (cycles): 296 typical (28 to 346) Program Memory 172 bytes Example _Q15 x; 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1301 x = _LIBQ_Q15FromString("0.125"); // x will equal 0.125 using // an internal value of 0x1000 x = _LIBQ_Q15FromString("-1.0"); // x will equal -1.0 using // an internal value of 0x8000 x = _LIBQ_Q15FromString("0.999969"); // x will equal 0.999969 using // an internal value of 0x7FFF 5.4.2.5.15.2 _LIBQ_ToStringQ15 Function C void _LIBQ_ToStringQ15( _Q15 x, char * s ); Description Function _LIBQ_ToStringQ15: void _LIBQ_ToStringQ15(_Q15 x, char *s); Convert a _Q15 fixed point value to an ascii string representation in a -N.NNNNNN format. Preconditions The character string "s" must be at least 10 characters long, including the Null string terminator. Parameters Parameters Description x The fixed point value to be converted into an ascii string (_Q15) s A pointer to the output string of at least 10 characters Returns An ascii string that represents the _Q15 fixed point value in -N.NNNNNN format. The output string will be terminated by a Null (0x00) character. Remarks Execution Time (cycles): 118 typical (28 to 132) Program Memory 200 bytes Example char s[10]; _LIBQ_ToStringQ15((_Q15)0x1000, s); // s will equal "0.125000" _LIBQ_ToStringQ15((_Q15)0x8000, s); // s will equal "-1.000000" _LIBQ_ToStringQ15((_Q15)0x7FFF, s); // s will equal "0.999969" 5.4.2.5.16 Data Types and Constants 5.4.2.5.16.1 _Q15_MAX Macro C #define _Q15_MAX ((_Q15)0x7FFF) // Maximum value of _Q15 (~1.0) Description Maximum value of _Q15 (~1.0) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1302 5.4.2.5.16.2 _Q15_MIN Macro C #define _Q15_MIN ((_Q15)0x8000) // Minimum value of _Q15 (-1.0) Description Minimum value of _Q15 (-1.0) 5.4.2.5.16.3 _Q16_MAX Macro C #define _Q16_MAX ((_Q16)0x7FFFFFFF) // Maximum value of _Q16 (~32768.0) Description Maximum value of _Q16 (~32768.0) 5.4.2.5.16.4 _Q16_MIN Macro C #define _Q16_MIN ((_Q16)0x80000000) // Minimum value of _Q16 (-32768.0) Description Minimum value of _Q16 (-32768.0) 5.4.2.5.16.5 _Q2_13_MAX Macro C #define _Q2_13_MAX ((_Q2_13)0x7FFF) // Maximum value of _Q2_13 (~4.0) Description Maximum value of _Q2_13 (~4.0) 5.4.2.5.16.6 _Q2_13_MIN Macro C #define _Q2_13_MIN ((_Q2_13)0x8000) // Minimum value of _Q2_13 (-4.0) Description Minimum value of _Q2_13 (-4.0) 5.4.2.5.16.7 _Q2_29_MAX Macro C #define _Q2_29_MAX ((_Q2_29)0x7FFFFFFF) // Maximum value of _Q2_29 (~4.0) Description Maximum value of _Q2_29 (~4.0) 5.4.2.5.16.8 _Q2_29_MIN Macro C #define _Q2_29_MIN ((_Q2_29)0x80000000) // Minimum value of _Q2_29 (-4.0) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1303 Description Minimum value of _Q2_29 (-4.0) 5.4.2.5.16.9 _Q3_12_MAX Macro C #define _Q3_12_MAX ((_Q3_12)0x7FFF) // Maximum value of _Q3_12 (~8.0) Description Maximum value of _Q3_12 (~8.0) 5.4.2.5.16.10 _Q3_12_MIN Macro C #define _Q3_12_MIN ((_Q3_12)0x8000) // Minimum value of _Q3_12 (-8.0) Description Minimum value of _Q3_12 (-8.0) 5.4.2.5.16.11 _Q31_MAX Macro C #define _Q31_MAX ((_Q31)0x7FFFFFFF) // Maximum value of _Q31 (~1.0) Description Maximum value of _Q31 (~1.0) 5.4.2.5.16.12 _Q31_MIN Macro C #define _Q31_MIN ((_Q31)0x80000000) // Minimum value of _Q31 (-1.0) Description Minimum value of _Q31 (-1.0) 5.4.2.5.16.13 _Q4_11_MAX Macro C #define _Q4_11_MAX ((_Q4_11)0x7FFF) // Maximum value of _Q4_11 (~16.0) Description Maximum value of _Q4_11 (~16.0) 5.4.2.5.16.14 _Q4_11_MIN Macro C #define _Q4_11_MIN ((_Q4_11)0x8000) // Minimum value of _Q4_11 (-16.0) Description Minimum value of _Q4_11 (-16.0) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1304 5.4.2.5.16.15 _Q5_10_MAX Macro C #define _Q5_10_MAX ((_Q5_10)0x7FFF) // Maximum value of _Q5_10 (~32.0) Description Maximum value of _Q5_10 (~32.0) 5.4.2.5.16.16 _Q5_10_MIN Macro C #define _Q5_10_MIN ((_Q5_10)0x8000) // Minimum value of _Q5_10 (-32.0) Description Minimum value of _Q5_10 (-32.0) 5.4.2.5.16.17 _Q7_8_MAX Macro C #define _Q7_8_MAX ((_Q7_8)0x7FFF) // Maximum value of _Q7_8 (~128.0) Description Maximum value of _Q7_8 (~128.0) 5.4.2.5.16.18 _Q7_8_MIN Macro C #define _Q7_8_MIN ((_Q7_8)0x8000) // Minimum value of _Q7_8 (-128.0) Description Minimum value of _Q7_8 (-128.0) 5.4.2.5.16.19 _Q0_15 Type C typedef int16_t _Q0_15; Description 1 sign bit, 15 bits right of radix 5.4.2.5.16.20 _Q0_31 Type C typedef int32_t _Q0_31; Description 1 sign bit, 31 bits right of radix 5.4.2.5.16.21 _Q15 Type C typedef _Q0_15 _Q15; 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1305 Description Short name for _Q0_15 5.4.2.5.16.22 _Q15_16 Type C typedef int32_t _Q15_16; Description 1 sign bit, 15 bits left of radix, 16 bits right of radix 5.4.2.5.16.23 _Q16 Type C typedef _Q15_16 _Q16; Description Short name for _Q15_16 5.4.2.5.16.24 _Q2_13 Type C typedef int16_t _Q2_13; Description 1 sign bit, 2 bits left of radix, 13 bits right of radix 5.4.2.5.16.25 _Q2_29 Type C typedef int32_t _Q2_29; Description 1 sign bit, 2 bits left of radix, 29 bits right of radix 5.4.2.5.16.26 _Q3_12 Type C typedef int16_t _Q3_12; Description 1 sign bit, 3 bits left of radix, 12 bits right of radix 5.4.2.5.16.27 _Q31 Type C typedef _Q0_31 _Q31; Description Short name for _Q_0_31 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1306 5.4.2.5.16.28 _Q4_11 Type C typedef int16_t _Q4_11; Description 1 sign bit, 4 bits left of radix, 11 bits right of radix 5.4.2.5.16.29 _Q5_10 Type C typedef int16_t _Q5_10; Description 1 sign bit, 5 bits left of radix, 10 bits right of radix 5.4.2.5.16.30 _Q7_8 Type C typedef int16_t _Q7_8; Description 1 sign bit, 7 bits left of radix, 8 bits right of radix 5.4.2.6 Files Files Name Description libq.h Optimized fixed point math functions for the PIC32MZ microAptivTM core platform. Description 5.4.2.6.1 libq.h Fixed Point Library libq.h provides a library of fixed point math functions for the PIC32MZ platform. All functions are optimized for speed. This header file specifies characteristics of each function, including execution time, memory size, and resolution. Signed fixed point types are defined as follows: Qn_m where: • n is the number of data bits to the left of the radix point • m is the number of data bits to the right of the radix point • a signed bit is implied For convenience, short names are also defined: Exact Name (# Bits) Required Short Name _Q0_15 (16) _Q15; _Q15_16 (32) _Q16; _Q0_31 (32) _Q31 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1307 Functions in the library are prefixed with the type of the return value. For example, _LIBQ_Q16Sqrt returns a Q16 value equal to the square root of its argument. Argument types do not always match the return type. Refer to the function prototype for a specification of its arguments. In cases where the return value is not a fixed point type, the argument type is appended to the function name. For example, _LIBQ_ToFloatQ31 accepts a type _Q31 argument. In some cases, both the return type and the argument type are specified within the function name. For example, Function Name (Return Type) [Argument Type]: _LIBQ_Q15_sin_Q2_13 (_Q15) [_Q2_13]; _LIBQ_Q31_sin_Q2_29 (_Q31) [_Q2_29] Table of LIBQ functions: Divide: _Q16 _LIBQ_Q16Div (_Q16 dividend, _Q16 divisor); Square root: _Q16 _LIBQ_Q16Sqrt (_Q16 x); Exponential: _Q16 _LIBQ_Q16Exp (_Q16 x); Log: _Q4_11 _LIBQ_Q4_11_ln_Q16 (_Q16 x); _Q3_12 _LIBQ_Q3_12_log10_Q16 (_Q16 x); _Q5_10 _LIBQ_Q5_10_log2_Q16 (_Q16 x); Power: _Q16 _LIBQ_Q16Power (_Q16 x, _Q16 y); Sine: _Q15 _LIBQ_Q15_sin_Q2_13 (_Q2_13 x); _Q31 _LIBQ_Q31_sin_Q2_29 (_Q2_29 x); Cosine: _Q15 _LIBQ_Q15_cos_Q2_13 (_Q2_13 x); _Q31 _LIBQ_Q31_cos_Q2_29 (_Q2_29 x); Tangent: _Q7_8 _LIBQ_Q7_8_tan_Q2_13 (_Q2_13 x); _Q16z _LIBQ_Q16_tan_Q2_29 (_Q2_29 x); Arcsin: _Q2_13 _LIBQ_Q2_13_asin_Q15 (_Q15 x); _Q2_29 _LIBQ_Q2_29_asin_Q31 (_Q31 x); _Q2_29 _LIBQ_Q2_29_asin_Q31_Fast (_Q31 x); Arccos: _Q2_13 _LIBQ_Q2_13_acos_Q15 (_Q15 x); _Q2_29 _LIBQ_Q2_29_acos_Q31 (_Q31 x); _Q2_29 _LIBQ_Q2_29_acos_Q31_Fast (_Q31 x); Arctan: _Q2_13 _LIBQ_Q2_13_atan_Q7_8 (_Q7_8 x); _Q2_29 _LIBQ_Q2_29_atan_Q16 (_Q16 x); Arctan2: _Q2_13 _LIBQ_Q2_13_atan2_Q7_8 (_Q7_8 y, _Q7_8 x); _Q2_29 _LIBQ_Q2_29_atan2_Q16 (_Q16 y, _Q16 x); Random number: _Q15 _LIBQ_Q15Rand (int64_t *pSeed); _Q31 _LIBQ_Q31Rand (int64_t *pSeed); Float: float _LIBQ_ToFloatQ31 (_Q31 x); float _LIBQ_ToFloatQ15 (_Q15 x); _Q31 _LIBQ_Q31FromFloat (float x); _Q15 _LIBQ_Q15FromFloat (float x); String: void _LIBQ_ToStringQ15 (_Q15 x, char *s); _Q15 _LIBQ_Q15FromString (char *s); Functions Name Description _LIBQ_Q15_cos_Q2_13 Calculates the value of cosine(x). _LIBQ_Q15_sin_Q2_13 Calculates the value of sine(x). _LIBQ_Q15FromFloat Converts a float to a _Q15 value. _LIBQ_Q15FromString Ascii to _Q15 conversion. _LIBQ_Q15Rand Generate a _Q15 random number. _LIBQ_Q16_tan_Q2_29 Calculates the value of tan(x). _LIBQ_Q16Div _Q16 fixed point divide. _LIBQ_Q16Exp Calculates the exponential function e^x. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1308 _LIBQ_Q16Power Calculates the value of x raised to the y power (x^y). _LIBQ_Q16Sqrt Square root of a positive _Q16 fixed point value. _LIBQ_Q2_13_acos_Q15 Calculates the value of acos(x). _LIBQ_Q2_13_asin_Q15 Calculates the asin value of asin(x). _LIBQ_Q2_13_atan_Q7_8 Calculates the value of atan(x). _LIBQ_Q2_13_atan2_Q7_8 Calculates the value of atan2(y, x). _LIBQ_Q2_29_acos_Q31 Calculates the value of acos(x). _LIBQ_Q2_29_acos_Q31_Fast Calculates the value of acos(x). This function executes faster than _LIBQ_Q2_29_acos_Q31 but is less precise. _LIBQ_Q2_29_asin_Q31 Calculates the value of asin(x). _LIBQ_Q2_29_asin_Q31_Fast Calculates the value of asin(x). This function executes faster than the _LIBQ_Q2_29_asin_Q31 function, but is less precise. _LIBQ_Q2_29_atan_Q16 Calculates the value of atan(x). _LIBQ_Q2_29_atan2_Q16 Calculates the value of atan2(y, x). _LIBQ_Q3_12_log10_Q16 Calculates the value of Log10(x). _LIBQ_Q31_cos_Q2_29 Calculates the value of cosine(x). _LIBQ_Q31_sin_Q2_29 Calculates the value of sine(x). _LIBQ_Q31FromFloat Converts a float to a _Q31 value. _LIBQ_Q31Rand Generate a _Q31 random number. _LIBQ_Q4_11_ln_Q16 Calculates the natural logarithm ln(x). _LIBQ_Q5_10_log2_Q16 Calculates the value of log2(x). _LIBQ_Q7_8_tan_Q2_13 Calculates the value of tan(x). _LIBQ_ToFloatQ15 Converts a _Q15 value to a float. _LIBQ_ToFloatQ31 Converts a _Q31 value to a float. _LIBQ_ToStringQ15 _Q15 to ascii conversion. Macros Name Description _Q15_MAX Maximum value of _Q15 (~1.0) _Q15_MIN Minimum value of _Q15 (-1.0) _Q16_MAX Maximum value of _Q16 (~32768.0) _Q16_MIN Minimum value of _Q16 (-32768.0) _Q2_13_MAX Maximum value of _Q2_13 (~4.0) _Q2_13_MIN Minimum value of _Q2_13 (-4.0) _Q2_29_MAX Maximum value of _Q2_29 (~4.0) _Q2_29_MIN Minimum value of _Q2_29 (-4.0) _Q3_12_MAX Maximum value of _Q3_12 (~8.0) _Q3_12_MIN Minimum value of _Q3_12 (-8.0) _Q31_MAX Maximum value of _Q31 (~1.0) _Q31_MIN Minimum value of _Q31 (-1.0) _Q4_11_MAX Maximum value of _Q4_11 (~16.0) _Q4_11_MIN Minimum value of _Q4_11 (-16.0) _Q5_10_MAX Maximum value of _Q5_10 (~32.0) _Q5_10_MIN Minimum value of _Q5_10 (-32.0) _Q7_8_MAX Maximum value of _Q7_8 (~128.0) _Q7_8_MIN Minimum value of _Q7_8 (-128.0) 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1309 Types Name Description _Q0_15 1 sign bit, 15 bits right of radix _Q0_31 1 sign bit, 31 bits right of radix _Q15 Short name for _Q0_15 _Q15_16 1 sign bit, 15 bits left of radix, 16 bits right of radix _Q16 Short name for _Q15_16 _Q2_13 1 sign bit, 2 bits left of radix, 13 bits right of radix _Q2_29 1 sign bit, 2 bits left of radix, 29 bits right of radix _Q3_12 1 sign bit, 3 bits left of radix, 12 bits right of radix _Q31 Short name for _Q_0_31 _Q4_11 1 sign bit, 4 bits left of radix, 11 bits right of radix _Q5_10 1 sign bit, 5 bits left of radix, 10 bits right of radix _Q7_8 1 sign bit, 7 bits left of radix, 8 bits right of radix File Name libq.h Company Microchip Technology Inc. 5.4 Math Library Help MPLAB Harmony Help LibQ Fixed-Point Math Library 5-1310 5.5 Operating System Abstraction Layer (OSAL) Library Help 5.5.1 Introduction OSAL Library for Microchip Microcontrollers The Operating System Abstraction Layer (OSAL) provides a consistent interface to an application and parts of MPLAB Harmony that allow them to take advantage of Operating System constructs when running in an OS environment OR when operating without one. It is designed to allow operation of MPLAB Harmony on any Microchip microcontroller and takes care of the underlying differences between the available OS Kernels or when no kernel is present. Description The OSAL provides the interface to commonly available RTOSes such that drivers and middleware (and optionally, applications) may be written using a single interface to a minimal set of OS-specific features needed to provide thread safety. The OSAL interface can be implemented appropriately to support almost any desired RTOS. For applications where no RTOS is available, or desired, a bare version of the OSAL supports either polled or interrupt-driven environments running directly on the hardware. This allows applications and the MPLAB Harmony stack to be executed in all three common embedded environments: polled (shared multi-tasking), interrupt-driven, or RTOS-based. Scope The OSAL is not designed to replace a commercial kernel and therefore the user is encouraged to use any of the specific features of their chosen RTOS in order to achieve best performance. As such the OSAL can also be considered to be an Operating System Compatibility Layer offering MPLAB Harmony and users the required common functions to ensure that MPLAB Harmony will correctly compile and operate in both RTOS and non-RTOS environments. The common interface presented by the OSAL is designed to offer a set of services typically found on micro-kernel and mini-scheduler systems. Because of this it has no aspirations to provide an equivalent set of capabilities as those found on large multi-tasking systems such as uCLinux. The common services are designed to allow MPLAB Harmony to implement thread-safe Drivers and Middleware. The design intention is that drivers will use the minimal set of OSAL features necessary to ensure that they can safely operate in a multi-threaded environment yet can also compile correctly when no underlying RTOS is present. The 5.5 Operating System Abstraction Layer MPLAB Harmony Help Introduction 5-1311 range of features used by a driver is typically limited to these OSAL features: • Semaphore Functions • Mutexe Functions • Critical Section Functions 5.5.2 Release Notes MPLAB Harmony Version: v0.70b OSAL Library Version : 0.1 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Three OSAL implementations: • OSAL_USE_NONE - Default implementation of the OSAL that includes no RTOS functionality and features only sufficient code to ensure that elements of MPLAB Harmony that make OSAL calls will compile correctly. 'Safe' parameters and #defines have been used so that MPLAB Harmony drivers will compile correctly. • OSAL_USE_BASIC - Minimal OSAL implementation not designed to operate in multi-threaded environments but offers some usable features so that interrupt driven applications can still compile and operate correctly. Minimal implementations include Events, Semaphores and Mutexes. • OSAL_USE_RTOS - An RTOS is being used and the relevant RTOS header file will be included in the sys_config.h file. Currently a reference implementation of the FreeRTOS(tm) and Micrium uC/OSIII operating systems have been implemented. Other operating systems implementations are under development. Known Issues: Nothing to report in this release. 5.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1312 5.5.4 Using the Library This topic describes the basic architecture of the OSAL Library and provides information and examples on how to use it. Description Interface Header File: osal.h The interface to the OSAL Library is defined in the "osal.h" header file. Any C language source (.c) file that uses the OSAL System Service library should include "osal.h". Library File: osal.c OR osal_xxxx.c The OSAL Library consists of a base implementation and individual ports of the OSAL to target operating systems. These target operating systems consist of a basic implementation (used when the macro OSAL_USE_BASIC is defined) and ports of third party RTOSs (used when the macro OSAL_USE_RTOS is defined). If no RTOS support is required then the file "osal.c" can be optionally included into the project; however, it is not required. This file provides implementations for the OSAL_USE_BASIC and configurations of the library. When an RTOS is being used (the OSAL_USE_RTOS configuration) then an external implementation file which provides the required interface wrappers should be added to the project. For instance for the FreeRTOS operating system the file "osal_freertos.c" should be added, whilst for the Micrium uC/OS-III operating system the file "osal_micrium.c" should be added. The base implementation and some generic ports are provided with the Library however it is the responsibility of third party vendors to supply the correctly implemented interface file. Please refer to the MPLAB Harmony Overview for how the OSAL Library interacts with the framework. 5.5.4.1 Abstraction Model The OSAL Library provides a predefined set of functions and types that match those services that an RTOS will typically provide. It is designed to be a lightweight model and deliberately excludes the much broader depth and breadth of services that a fully fledged RTOS provides. As such the interface defines only those core functions necessary for the MPLAB Harmony Drivers and middleware to operate in a multi-threaded environment AND some additional functionality to support RTOS independent development of middleware and user applications in the future. Description The common interface can easily be ported to many host RTOSs by third parties and the set of functions provides a basic level of RTOS compatibility. Where a specific RTOS does not implement a given architectural feature (e.g., events), the OSAL port for that RTOS should endeavor to imitate that feature using the constructs that are available. Although it is recognized that this may have a detrimental effect on the performance of that system it does allow MPLAB Harmony developers the broadest scope for using RTOS features in their designs. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1313 Include Hierarchy of osal.h 5.5.4.2 Library Overview This section provides an overview of the OSAL Library. Description Refer to the section System Services Overview for how the system services operates in a system. The OSAL Library provides a defined interface such that driver and middleware developers will be able to create MPLAB Harmony code that can safely operate in a multi-threaded environment when a supported RTOS is present yet will still compile and function correctly when MPLAB Harmony is being used in a non-RTOS environment with an interrupt or non-interrupt driven application model. The defined interface will help application developers during the early stages of their design when various platforms and architectures are still under consideration. The developer is encouraged to use the specific features of a chosen RTOS once it has been selected since this is likely to provide a more effective and rich programming environment. The OSAL Library is deliberately designed to be a thin layer over an underlying RTOS which presents a predefined interface to the common features used by the majority of RTOSes, which includes: Library Interface Section Description Semaphore Functions Binary and counting semaphores for inter thread communications. Queue Functions Arbitrary queue mechanism with pass by copy. Mutex Functions Thread and resource locking mechanism. Critical Section Functions Application and scheduler locking mechanism. Thread Functions Basic thread creation and control. Interrupt Handling Functions ISR primitives to allow RTOS calls from within an ISR context. Error Handling Functions Simple error handling. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1314 Memory Allocation Functions Memory allocation primitives or wrappers. OSAL Control Functions OS initialization and start-up. One of the primary design guidelines is that a host operating system may not be present and so any operations that the OSAL presents are designed to compile out to safe default values if no RTOS is present. This can mean the following: • Implementing a dummy function that mimics typical RTOS behavior • Implementing a #define or inline function that returns a 'safe' generic return value, such as 'TRUE' or 'Call succeeded' • Returning a OSAL_RESULT_NOT_IMPLEMENTED value to indicate an unsupported operation • Throwing an ASSERT failure to indicate a terminal error that prevents operation under specific circumstances 5.5.4.3 How the Library Works This section provides information on how the OSAL Library works. 5.5.4.3.1 Core Functionality The OSAL Library implements a lightweight abstraction layer on top of a host operating system. The OSAL functionality is designed to allow a programmer access to typical RTOS based functions than can reasonably be expected to exist on a small kernel or micro-scheduler typically found on the target Microchip Microcontrollers. The OSAL is designed to be compiled under three specific mutually exclusive operating modes: Compilation Mode Description OSAL_USE_NONE No RTOS or OSAL support is provided. The OSAL interface functions will compile to 'nothing' or are defined to have no value. OSAL_USE_BASIC Basic level of support. There is no underlying RTOS however certain facilities are replicated such as Semaphores and Mutexes. OSAL_USE_RTOS A full implementation of the OSAL interface is available and there is an underlying RTOS as part of the program. In the absence of any one of these values being defined or passed into the compiler as a command line parameter then the OSAL will default to the OSAL_USE_NONE mode of operation. The following conceptual diagram shows the common interface and how the individual implementations are derived depending upon the configured mode of compilation. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1315 The OSAL interface makes extensive use of object handles when passing RTOS parameters around the various functions. This has been done since depending on the operating mode and underlying RTOS (if any) there may be substantial differences between the C types of the variables. For instance, in the basic implementation mode a semaphore is implemented as a single 8-bit quantity to ensure atomic access on all architectures. On a third party RTOS the same semaphore may be implemented as a 16-bit index into an array of pointers whilst on another RTOS it could be represented as a size_t pointer (a pointer to the basic word type for that architecture). Because of these differences, the most convenient mechanism to maintain a regular interface is by the use of handles to implementation defined variables. The majority of the OSAL objects also provide a OSAL_XXX_Delete function. This is provided for completeness however care should be taken in its use. Many RTOS implementations do not provide the ability to delete an object and excessive use of the delete can lead to memory fragmentation and unpredictable system behavior. It is recommended that it is not used at this time, or if used, the return value should be checked for a possible failure to delete the object. In the following sections the basic behavior of the supported functions are documented. For the purposes of documentation the assumed operation mode will be that a full RTOS is present and so the behavior is that which will be observed in that scenario. 5.5.4.3.2 Other Functionality 5.5.4.3.3 Thread Operation The OSAL implements a simple threading model that assumes the use of a priority based pre-emptive scheduler. Description Each thread is implemented as a single C function which can be reused across multiple threads if desired. For this reason care should be taken if static variables are allocated within the thread function. The priority of a thread is defined using higher values to indicate higher priority. Thread priorities range from 1 up to the application defined value OSAL_CONFIG_MAX_PRIORITIES minus 1 . No importance is placed upon any specific value of priority other than that a thread with a higher priority will execute before a lower priority one if they are both in the ready state. Certain RTOS implementations may require threads to each have a unique priority; however, since MPLAB Harmony has no knowledge of the various ways in which libraries may be connected together it is not possible to define any fixed priorities. The application programmer is therefore responsible for ensuring the relative priority of threads. It is assumed that each thread is created with its own stack and that the RTOS is responsible for the correct allocation of memory resources. The requested memory size is specified in bytes and its value is normally arrived at by inspection of the program, the underlying hardware architecture (16-/32-bits) and the total available memory. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1316 No significance is placed upon the textual name given to a task and it is normally only used for diagnostic purposes. The following diagram shows the sequence of states that a typical RTOS will move a given task through during its lifetime. The pdata parameter passed during thread creation allows the application programmer to generate more sophisticated behavior based upon passing a configuration parameter to a thread. The thread can be created multiple times and perform per instance operations related to the passed parameter. The phandle parameter allows the created threads handle to be passed back to the calling code allowing later manipulation of the thread by other parts of the program. Example Code: /* Create the application thread for this test harness. This example thread * replicates the functionality of the ADC data logger thread * The priority of the application task should be selected as a middle value * since the check tasks are manipulated above and below this priority level */ OSAL_THREAD_Create(APP_Tasks, "APP", 500, OTH_APP_THREAD_PRIORITY, NULL, NULL); The OSAL supports the creation of daemon threads which are designed to allow multi-threaded drivers with their own task routine to operate with an underlying RTOS. The OSAL_THREAD_CreateDaemon function takes a single parameter, which is the name of the Daemon thread. The user is responsible for implementing the Daemon thread as appropriate for their system. This thread should then call the individual driver state machines ensuring that they continue to operate. For example, consider the following scenario: 1. The application uses a driver that has no tasks routine although it does use driver tasks called as a result of an interrupt. 2. The application also uses a driver with a state machine that needs calling every 500 us. 3. The application also uses two more drivers that can conveniently be called one after the other (perhaps it is the same driver but with two instantiations) and only needs processing every 100 ms. For item 1, no Deamon thread is required. For item 2, a Daemon thread is required that calls the driver task routine and then sleeps for 500 us. For the remaining driver, a single Daemon thread can be created that calls the driver twice (with different object handles) and then sleeps for 100 ms. 5.5.4.3.4 Events The event mechanism is based upon a single boolean value that can be set or reset by a thread. Multiple threads may pend (or block) waiting on the value to be set or flagged. The OSAL implementation of events is extremely basic and no combinatorial operations are available. Furthermore, whilst multiple threads may block on the event, only the highest priority thread will be released by the event being flagged. It is strongly suggested that developers consider the use of queues or semaphores for inter process communication or 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1317 sequencing since they provide a more deterministic response time than multiple event flags. 5.5.4.3.5 Semaphores The semaphore implements a method for thread synchronization. This synchronization can be either between one thread and another or between an interrupt service routine (ISR) and a thread. A semaphore once signalled will unblock the highest priority thread currently pending on it. Description A semaphore can be used to lock a shared resource, although it is more normal to use a mutex for such an activity. Once obtained a semaphore should be posted back to enable it to be re-taken at a later time or in another thread. /* mainline code prior to OS start */ /* declare a variable of type semaphore handle */ OSAL_SEM_DECLARE(semSync); /* create the semaphore */ OSAL_SEM_Create(&semSync, OSAL_SEM_TYPE_BINARY, 0, 0); /* thread one */ ... /* take the semaphore without waiting */ OSAL_SEM_Pend(semSync, 0); ... perform some actions /* return the semaphore */ OSAL_SEM_Post(semSync); ... /* thread two must not execute until thread one has finished its operations*/ ... /* block on the semaphore */ OSAL_SEM_Pend(semSync, OSAL_WAIT_FOREVER); ... perform some more actions /* return the semaphore */ OSAL_SEM_Post(semSync); A semaphore can be signalled multiple times and so provides a method for an ISR to release a thread waiting on it. Even though the blocked thread never returns the semaphore, because the asynchronous ISR repeatedly posts it the next time the thread wants to pend on the semaphore it will be available. By moving the majority of interrupt service processing from the ISR to a high priority thread the system response time is improved and the eventual processing can take advantage of OSAL features such as mutexes and queues which would normally be harder to implement inside the ISR. This technique is known as deferred interrupt processing. /* an example interrupt handler called from an ISR that performs task synchronization using a semaphore */ void _ISRTasksRX(void) /* N.B. pseudo-code ISR */ { ... _DRV_USART_InterruptSourceStatusClear(_DRV_USART_GET_INT_SRC_RX(_DRV_USART_OBJ(dObj, rxInterruptSource))); /* Release the receive semaphore unblocking any tasks */ OSAL_SEM_PostISR(_DRV_USART_OBJ(dObj, rxSemID)); } /* DRV_USART_TasksRX */ 5.5.4.3.6 Mutex Operation A mutex or mutual exclusion is used to protect a shared resource from access by multiple threads at the same time. A shared resource may be a common data structure in RAM or it may be a hardware peripheral. In either case a mutex can be used to 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1318 ensure the integrity of the entire resource by only allowing one thread to access it at a time. Description The program must be written in such a way that before the shared resources is accessed the mutex has to be obtained. Once obtained the accesses should occur, and once complete the mutex should then be released. While no restrictions are enforced the sequence of operations between the lock and unlock should ideally take as few lines of code as possible to ensure good system performance. The mutex may be implemented as a form of binary semaphore but an underlying RTOS will often add other features. It is normal to add the restriction that a mutex may only be unlocked from the thread that originally obtained the lock in the first place. The RTOS may also provide features to mitigate priority inversion problems (where a high priority thread blocks on a lower priority one holding a mutex) by providing priority inheritance allowing lower priority threads to be temporarily raised to complete and release a locked mutex. /* perform operations on a shared data structure */ struct myDataStructure { uint16_t x; uint8_t y; } myDataStructure; ... OSAL_MUTEX_DECLARE(mutexDS); OSAL_MUTEX_Create(&mutexDS); ... /* wait 2 seconds to obtain the mutex */ if (OSAL_MUTEX_Lock(mutexDS, 2000) == OSAL_RESULT_TRUE) { /* operate on the data structure */ myDataStructure.x = 32; OSAL_MUTEX_Unlock(mutexDS); } 5.5.4.3.7 Queue Operation This section describes the implementation of queues using the OSAL Library. Description The OSAL implements queues as a fixed structure of elements, with each element the same size. The size and number of each element is defined when the queue is created but cannot be reconfigured later. Elements are added to the queue when using the Add function call and removed on a first-in-first-out basis when using the Remove function. If the queue is full at the time of attempting to add data, the call will block for the specified time before failing. Data placed on the queue is done using a copy operation so that the source may be over written if required. For large data items it may be better to pass pointers to the data via the queue however care must be taken on ownership once the pointer has been copied between threads. It is possible to place an item at the front of a queue using the AddHead function. Since the implementation of this is heavily dependent upon the underlying RTOS the call may return with OSAL_RETURN_NOT_IMPLEMENTED if this operation is not possible. /* Create a queue */ OSAL_QUEUE_Declare(myQueue); ... /* create a queue that accepts 1 byte chars and is 4 items long */ OSAL_QUEUE_Create(&myQueue, 1, 4); /* Add data */ char c = 'A'; OSAL_QUEUE_Add(myQueue, &c, 0); c = 'B'; OSAL_QUEUE_Add(myQueue, &c, 0); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1319 c = 'C'; OSAL_QUEUE_Add(myQueue, &c, 0); /* remove data */ char d; OSAL_QUEUE_Remove(myQueue, &d, OSAL_WAIT_FOREVER); 5.5.4.3.8 Critical Section Operation This section describes how critical sections are used. Description Critical sections are used to form sequences of code that must operate in an atomic manner. The interface allows for the possibility of two types of critical section. • When the critical section is entered all interrupts on the microcontroller are disabled. This prevents the protected sequence of code from being interrupted and ensures the complete atomicity of the operation. This is denoted by the OSAL_CRIT_TYPE_HIGH value. • When the critical section is entered the RTOS scheduler is disabled. In this second case other threads are prevented from running however interrupts can still occur which allows any asynchronous events to still be received and for the temporal accuracy of the RTOS scheduler to be maintained. This is denoted by the the OSAL_CRIT_TYPE_LOW value, Since the behavior in the two cases is different the type of critical section must be identified in both the call to enter and leave. /* enter and leave a critical section disabling interrupts */ OSAL_CRIT_Enter(OSAL_CRIT_TYPE_HIGH); /* perform an atomic sequence of code */ ... /* leave the critical section */ OSAL_CRIT_Leave(OSAL_CRIT_TYPE_HIGH); The underlying RTOS may not support the second scenario, in which case the OSAL implementation will default to disabling all interrupts. 5.5.4.3.9 Interrupt Operation This section describes interrupt handling by the OSAL Library. Description Interrupt handling in the OSAL is implemented using a separate set of interrupt-only functions. Within MPLAB Harmony, interrupts are deemed to be handled at an application level,meaning the initial interrupt handler or vector is dealt with while 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1320 writing the application rather than defaulting to MPLAB Harmony provided handlers. However, within MPLAB Harmony there may be functions that are called within the context of an ISR and also during mainline program flow depending on whether MPLAB Harmony has been built with interrupt or polled drivers. Because of this, to allow the most flexible and adaptable OSAL implementation, the following call sequence should be performed. 1. At the application interrupt handler level, immediately after the interrupt has been entered and before any further calls are made, call OSAL_ISR_Enter(). 2. Once inside the ISR OR inside any descendent functions called as a result of entering the ISR ensure that only OSAL_XXX_xxxxISR variants of functions are called. 3. At the exit point(s) of the ISR call OSAL_ISR_Exit(). By following this sequence of operations, the OSAL can be made to adapt to the requirements of different underlying RTOS architectures. In the main ISR handler: void __ISR ( _TIMER_1_VECTOR ) _InterruptHandler_TMR_1_stub ( void ) { OSAL_ISR_Enter(); /* Call the timer driver's "Tasks" routine */ DRV_TMR_Tasks ( appDrvObject.tmrObject ); OSAL_ISR_Exit(); } In the called function: void _DRV_TMR_MAKE_NAME( Tasks ) ( _DRV_TMR_DYN_ARG( SYS_MODULE_OBJ object ) ) { ... /* Clear Timer Interrupt/Status Flag */ _DRV_TMR_InterruptSourceClear( _DRV_TMR_GET_INT_SRC( _DRV_TMR_OBJ(dObj, interruptSource) ) ); /* release a semaphore, note use of ISR variant */ OSAL_SEM_PostISR(&semTMR); } /* DRV_TMR_Tasks */ It is not appropriate (or logical) to block inside an ISR so all variants of the OSAL functions with ISR at the end do not take a block time parameter. The use of ISR specific versions of OSAL functions is dependent on the RTOS; however, if the xxxISR variants are used by default inside any ISRs, the actual implementation of the interface on a given RTOS can be allowed to handle the complexities on that specific platform. 5.5.4.3.10 Error Operation This section describes error handling within an OSAL function. Description If an error occurs within an OSAL function or inside the underlying RTOS, the OSAL_ErrorCallback function will be called. This callback function is declared as a _weak_ function and the programmer can override it to provide application specific error handling. Currently, only a few error codes are listed and it is normally difficult to provide any kind of constructive recovery from an internal error. The default course of action is to either block and indicate the condition using some visual means or to perform a processor reset. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Using the Library 5-1321 /* user implementation of the error callback */ void OSAL_ErrorCallback(OSAL_ERROR_CALLBACK_TYPE type) { while (1) { // a non recoverable error occurred so loop here BlinkLED(); } } 5.5.4.3.11 Memory Operation The OSAL Library provides an interface to a memory allocation mechanism. The memory required for dynamic instantiation of variables is normally provided by allocating it from the heap. However the standard C library implementation of malloc and free are not considered thread safe and so OSAL specific functions must be used if MPLAB Harmony or the application requires dynamic memory during operation. When operating without an underlying RTOS the OSAL memory allocators default to using standard malloc and free functions. However, when operating with an RTOS the calls will defer to the specific scheme used by the RTOS. This may involve multiple memory pools or it may simply involve adding a critical section around calls to malloc and free. It is left to the implementation to define the most appropriate scheme. /* allocate a large buffer */ uint8_t* buffer; buffer = OSAL_Malloc(8000); if (buffer != NULL) { ... manipulate the buffer /* free the buffer */ OSAL_Free(buffer); buffer = NULL; } 5.5.4.3.12 OSAL Operation This section describes OSAL control features. Description When the OSAL is using an underlying RTOS it may be necessary to allow the RTOS to perform one-time initialization before any calls to it are made. For instance, the RTOS might implement multiple memory pools for managing threads, queues and semaphores and it must be given the chance to create these pools before any of the objects are created. For this reason the application program should call OSAL_Initialize() early on and certainly before any MPLAB Harmony Drivers or middleware is initialized (since these may also create OSAL objects at creation time). Once the OSAL is initialized and any other remaining parts of the system are configured correctly, the OSAL can be entered with OSAL_Start(). There is no expectation that control will be returned from this function and any return is likely to indicate a fault condition. 5.5.5 Configuring the Library The configuration of the OSAL Library is based on the file sys_config.h This header file contains the configuration selection for the OSAL Library. Based on the selections made, the OSAL will support or not support selected features. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Configuring the Library 5-1322 This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. Description To configure the OSAL the compilation mode needs to be selected. Three options are currently supported and these define the implementation details for the OSAL. In all cases the same interface is present; however, the functionality at the varying levels will be different or not supported. Only one of these #define statements should be specified, and this can be either done in a common location (such as sysconfig.h) or on the build tool command line. Compilation Mode Description OSAL_USE_NONE No RTOS or OSAL support is provided. The OSAL interface functions will compile to 'nothing' or are defined to have no value. OSAL_USE_BASIC Basic level of support. There is no underlying RTOS; however, certain facilities are replicated such as Semaphores and Mutexes. OSAL_USE_RTOS A full implementation of the OSAL interface is available and there is an underlying RTOS as part of the program. 5.5.5.1 Initialization Overrides This section provides information for overriding OSAL initialization. Description The OSAL requires minimal configuration. In the case of the OSAL_USE_NONE and OSAL_USE_BASIC all of the configuration required is provided by the standard "osal.h" include file. When a particular RTOS is being used then additional OSAL configuration parameters should be placed in "sys_config.h". The primary requirement is to include the relevant interface implementation for the selected RTOS being used. This file will contain the mappings from OSAL interface types to types relevant for the chosen RTOS. /* included the name of the port specific interface file */ #include "osal_.h" Configuration parameter to define the maximum number of unique priority levels that a thread may take. Configuration Parameter Purpose OSAL_MAX_PRIORITIES Maximum number of thread priority levels allowed in the application. The assignable priorities for a thread are assumed to run from 1 to OSAL_MAX_PRIORITIES - 1. Some underlying RTOSs may permit multiple threads at the same priority level (implementing a round-robin scheduling) so the total number of threads may actually be higher than the defined value. This is an application design decision. If the application is to support multi-threaded drivers with Daemon threads then the stack size and priority of the these should be defined using the following macros: Configuration Parameter Purpose OSAL_DAEMON_STACK_SIZE Number of bytes to allocate to a daemon thread. These threads are likely to be small and require small stacks although the exact size depends on the architecture. Any OSAL port should implement safe defaults. Typical values are 800 bytes for a PIC32 or 300 for a PIC24. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Configuring the Library 5-1323 OSAL_DAEMON_PRIORITY Default priority of a daemon thread. Since these threads are typically calling MPLAB Harmony drivers and middleware their priority should be higher than the majority of the application in order to keep them from suffering driver starvation. The most appropriate value is left to the programmer to decide. 5.5.5.2 Others Drag and Drop other configuration options 5.5.5.3 Examples - Sample Functionality Example sys_config.h fragment: // ***************************************************************************** // ***************************************************************************** // Section: Application Configuration // ***************************************************************************** // ***************************************************************************** /* These definitions select the configuration options for the application */ /* configure the priorities and stack sizes for the daemon tasks */ #define OSAL_DAEMON_STACK_SIZE 800 #define OSAL_DAEMON_PRIORITY 4 /* configure the maximum number of priorities in this application */ #define OSAL_CONFIG_MAX_PRIORITIES 31 /* declare the daemon tasks used by the OSAL to implement driver tasks */ extern void osalDaemon1(void* pv); extern void osalDaemon2(void* pv); /* Include the port specific OS implementation files. The file is required to * create an implementation layer for the selected OS. This include will be * changed depending on the required OS being used */ #include "osal_freertos.h" 5.5.6 Building the Library This section list the files that are available in the \src of the OSAL Library. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. Files Name Description osal.c Bare metal implementation of OSAL functions Description As additional implementations of the OSAL Library are added to MPLAB Harmony, their interface files may be added to the \src directory. Since many RTOS vendors offer their products as a commercial and licensed offering it is likely that considerably more source files will be required than just the "osal_xxxx.c" file. These RTOS source files will be placed inside directories specific to the manufacturer and instructions on how to add them to a MPLAB Harmony project will be provided by the supplier. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Building the Library 5-1324 Summary if you are building using the default OSAL Library and have selected the OSAL_USE_NONE or OSAL_USE_BASIC compilation options then only "osal.c" needs to be added to the project. However, if a specific RTOS is being targeted and OSAL_USE_RTOS is selected, the port specific implementation file will need to be added to the project along with the files for that vendor. 5.5.6.1 osal.c Basic OSAL compatibility layer. This file contains functional implementations of the bare metal OSAL. Where it is logical and possible to implement non threading versions of the common function calls they have been implemented here directly or in the osal.h file as macros. If it is not possible, or logical, to implement a feature WITHOUT an RTOS present, the the matching definition in osal.h will be set to a NULL (or empty) implementation. File Name osal.c 5.5.7 Library Interface Data Types and Constants Name Description OSAL_MUTEX_HANDLE_TYPE Handle to a mutex, this is the default implementation and may be overridden in an actual implementation file OSAL_QUEUE_HANDLE_TYPE Handle to a queue, this is the default implementation and may be overridden in an actual implementation file OSAL_SEM_HANDLE_TYPE Handle to a semaphore, this is the default implementation and may be overridden in an actual implementation file OSAL_THREAD_HANDLE_TYPE Handle to a thread, this is the default implementation and may be overridden in an actual implementation file OSAL_USE_NONE This is macro OSAL_USE_NONE. OSAL_WAIT_FOREVER Default value indicating block forever OSAL_RESULT Enumerated type representing the general return value from OSAL functions. OSAL_SEM_TYPE Enumerated type respresenting the possible types of semaphore. Critical Section Functions Name Description OSAL_CRIT_Enter Enters a critical section with the specified severity level. OSAL_CRIT_Leave Leaves a critical section with the specified severity level. OSAL_CRIT_TYPE Enumerated type respresenting the possible types of critical section. Error Handling Functions Name Description OSAL_ERROR_CALLBACK_TYPE Enumerated type respresenting the possible types of callback message. OSAL_ErrorCallback Lightweight error handling callback function for the RTOS. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1325 Interrupt Handling Functions Name Description OSAL_ISR_Enter Informs the OSAL and RTOS that an ISR is being entered. OSAL_ISR_Exit Informs the OSAL and RTOS that an ISR is being exited. Memory Allocation Functions Name Description OSAL_Free Deallocates a block of memory and return to the default pool. OSAL_Malloc Allocates memory using the OSAL default allocator. Mutex Functions Name Description OSAL_MUTEX_Create Creates a mutex. OSAL_MUTEX_Delete Deletes a mutex. OSAL_MUTEX_Lock Locks a mutex. OSAL_MUTEX_Unlock Unlocks a mutex. OSAL_MUTEX_DECLARE Declares an OSAL mutex. OSAL Control Functions Name Description OSAL_Initialize Performs OSAL initialization. OSAL_Name Obtains the name of the underlying RTOS. OSAL_Start Starts the underlying RTOS Queue Functions Name Description OSAL_QUEUE_DECLARE Declares an OSAL queue. OSAL_QUEUE_Add Addd the specified item to the queue with a time-out if the queue is full. OSAL_QUEUE_AddHead Adds the specified item to the front of the queue with a timeout if the queue is full. OSAL_QUEUE_AddHeadISR Adds the specified item to the front of the queue from within an ISR. OSAL_QUEUE_AddISR Adds the specified item to the queue from with an ISR. OSAL_QUEUE_Create Creates a queue with the specified width and depth. OSAL_QUEUE_Delete Deletes an OSAL_QUEUE. OSAL_QUEUE_Peek Copys the item at the head of the queue but leave it on the queue. If the queue is empty, it will block up to waitMS. OSAL_QUEUE_PeekISR Copys the item at the head of the queue but leaves it on the queue. OSAL_QUEUE_Remove Removes the item at the head of the queue. If the queue is empty it will block up to waitMS. OSAL_QUEUE_RemoveISR Removes the item at the head of the queue. Semaphore Functions Name Description OSAL_SEM_Create Creates an OSAL Semaphore. OSAL_SEM_Delete Deletes an OSAL Semaphore. OSAL_SEM_GetCount Returns the current value of a counting semaphore. OSAL_SEM_Pend Waits on a semaphore. Returns true if the semaphore was obtained within the time limit. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1326 OSAL_SEM_Post Posts a semaphore or increments a counting semaphore. OSAL_SEM_PostISR Posts a semaphore or increments a counting semaphore from within an Interrupt Service Routine (ISR). OSAL_SEM_DECLARE Declares an OSAL semaphore. Thread Functions Name Description OSAL_THREAD_FUNCTION Functions that will operate as a separate thread under the OSAL should match this type. OSAL_THREAD_Create Creates an OSAL thread with the specified parameters. OSAL_THREAD_CreateDaemon Creates a Daemon thread for use with multi-threaded Harmony drivers. OSAL_THREAD_PriorityGet Gets the priority of a thread. OSAL_THREAD_PrioritySet Sets the priority of a thread. OSAL_THREAD_Resume Resumes a specified thread. OSAL_THREAD_ResumeAll Resumes all suspended threads. OSAL_THREAD_Sleep Puts the currently executing thread to sleep. OSAL_THREAD_Suspend Suspends a specified thread. OSAL_THREAD_SuspendAll Suspends all threads apart from the calling thread. Description This section describes the APIs of the OSAL Library. Refer to each section for a description. 5.5.7.1 Thread Functions 5.5.7.1.1 OSAL_THREAD_FUNCTION Type C typedef void (* OSAL_THREAD_FUNCTION)(void* pData); Description OSAL thread function template OSAL thread functions must match this type or use it explicitly. Thread functions are expected to return nothing. The pData parameter is information passed at creation time and is implementation specific. Remarks None. 5.5.7.1.2 OSAL_THREAD_Create Function C OSAL_RESULT OSAL_THREAD_Create( OSAL_THREAD_FUNCTION task, const char* name, uint16_t stack_size, uint8_t priority, void* pData, OSAL_THREAD_HANDLE_TYPE* pHandle ); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1327 Description This function creates an OSAL thread. The thread function is implemented as a simple task that will normally not return (i.e., a while(1) loop). The name is not used by the OSAL, but may be used by the RTOS for diagnostic and reporting purposes. The thread is created with a fixed stack size that is allocated from one of the available memory pools or more normally from the heap. The priority of the thread is an 8-bit quantity with higher values denoting threads of a higher priority. Optionally, a parameter may be passed to the thread function that can be used to implement per instance behavior. For example, one LED flashing task could be created several times with the LED number passed as a parameter at creation time. A handle to the created thread is returned in pHandle. Threads may be created prior to the RTOS starting, however, no execution will occur until it is started. A created thread is immediately placed into the READY state and is able to run provided that it is the highest priority thread when all threads are evaluated by the kernel, either during normal operation, or at RTOS start-up time. Preconditions Thread function must exist in program memory. Parameters Parameters Description task Name of the function that implements the thread code name Textual name of the thread. Not used by the OSAL but may be used by the RTOS for diagnostic and tracing purposes. stack_size Size of the stack associated with a thread in bytes. The RTOS will allocate this many bytes from any underlying memory pool or the heap. priority Priority of the thread from 1-255. Higher values indicate threads with higher priorities. It is left down to the underlying RTOS whether threads of the same priority are permitted or if threads should be given a unique priority. pData Pointer to data passed to the thread. Optionally, NULL may be passed. pHandle Pointer to a variable that can contain the created threads handle Returns OSAL_RESULT_TRUE - Thread successfully created OSAL_RESULT_FALSE - Thread not created or insufficient memory available Remarks None. Example // create a thread passing a data structure as a parameter during creation OSAL_THREAD_Create(threadCheck, "CHECK", 500, OTH_APP_THREAD_PRIORITY + 2, (void*) &appData, NULL); 5.5.7.1.3 OSAL_THREAD_CreateDaemon Function C OSAL_RESULT OSAL_THREAD_CreateDaemon( OSAL_THREAD_FUNCTION task ); Description This function will create a daemon or system thread designed to assist Harmony driver modules with their operation. Some Harmony drivers will incorporate state machines or other loop strucutres that must be periodically called for the driver to continue operating. For instance, a USART driver may have a state machine that manages the prioritization and transmission of data from multiple clients. This could work in addition to any processing that occurs when operating under interrupts so it will have a separate DRV_xxxx_Tasks routine (or similar) that must be periodically called. Since the prioritization and frequency of these 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1328 calls is only known to the programmer when designing the end application, the OSAL provides a lightweight thread mechanism that is primarily intended to be used internally by MPLAB Harmony. The Daemon threads have a fixed size stack (defined in system_config.h) and operate at a fixed priority. Preconditions Daemon function must exist in program memory. Parameters Parameters Description task The name of the function that implements the Daemon Returns OSAL_RESULT_TRUE - Thread successfully created OSAL_RESULT_FALSE - Thread not created or insufficient memory available Remarks None. Example // inside driver initialization routine ... OSAL_THREAD_CreateDaemon(DRV_USART_Tasks); 5.5.7.1.4 OSAL_THREAD_PriorityGet Function C uint8_t OSAL_THREAD_PriorityGet( OSAL_THREAD_HANDLE_TYPE handle ); Description This function gets the priority of a thread. The priority of the thread with the specified handle is returned. A handle value of NULL returns the priority of the thread making the call. Preconditions Thread must have been created. Parameters Parameters Description handle The thread handle. NULL indicates use the current thread. Returns 0-255 - The current priority of the thread. Higher values indicate higher priority. Remarks None. Example // raise the priority of this thread to ensure it completes a complex // operation uint8_t currPriority; currPriority = OSAL_THREAD_PriorityGet(NULL); OSAL_THREAD_PrioritySet(NULL, currPriority + 1); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1329 ... perform a time critical operation // restore the priority OSAL_THREAD_PrioritySet(NULL, currPriority); 5.5.7.1.5 OSAL_THREAD_PrioritySet Function C OSAL_RESULT OSAL_THREAD_PrioritySet( OSAL_THREAD_HANDLE_TYPE handle, uint8_t priority ); Description This function sets the priority of a thread. The priority of the thread with the specified handle is changed to the new value. If as a result of the change, it now has the highest priority and if not blocked, will start executing. Preconditions Thread must have been created. Parameters Parameters Description handle The thread handle. NULL indicates change the priority of the thread in which the call was made. priority Priority to be assigned to the thread Returns OSAL_RESULT_TRUE - Priority changed OSAL_RESULT_FALSE - Priority not changed Remarks None. Example // raise the priority of this thread to ensure it completes a complex // operation uint8_t currPriority; currPriority = OSAL_THREAD_GetPriority(NULL); OSAL_THREAD_PrioritySet(NULL, currPriority + 1); ... perform a time critical operation // restore the priority OSAL_THREAD_PrioritySet(NULL, currPriority); 5.5.7.1.6 OSAL_THREAD_Resume Function C OSAL_RESULT OSAL_THREAD_Resume( OSAL_THREAD_HANDLE_TYPE handle ); Description This functino resumes a specific thread. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1330 Preconditions Thread must have been created. Parameters Parameters Description handle The thread handle Returns OSAL_RESULT_TRUE - Thread resumed OSAL_RESULT_FALSE - Thread could not be resumed Remarks None. Example // suspend a thread until a later time OSAL_THREAD_Suspend(thread1Handle); ... // resume the suspended thread OSAL_THREAD_RESUME(thread1Handle); 5.5.7.1.7 OSAL_THREAD_ResumeAll Function C OSAL_RESULT OSAL_THREAD_ResumeAll(); Description This function resumes all suspended threads. Execution will continue with the highest priority thread that is ready to execute. Preconditions Thread must have been created. Returns OSAL_RESULT_TRUE - Successful call Remarks None. Example // resume all threads OSAL_THREAD_ResumeAll(); 5.5.7.1.8 OSAL_THREAD_Sleep Function C OSAL_RESULT OSAL_THREAD_Sleep( uint16_t waitMS ); Description This function puts the currently executing thread to sleep. Execution of the current thread is placed into a blocked state for the specified amount of time. The exact amount of time that the thread will sleep will depend upon the granularity of the underlying 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1331 pre-emptive tick. Preconditions Thread must have been created. Parameters Parameters Description waitMS Number of milliseconds the thread will be blocked Returns OSAL_RESULT_TRUE - Call succeeded Remarks None. Example while (1) { // sleep for 500ms OSAL_THREAD_Sleep(500); // toggle an LED DRV_IO_Toggle(drvHandle, LED_ID); } 5.5.7.1.9 OSAL_THREAD_Suspend Function C OSAL_RESULT OSAL_THREAD_Suspend( OSAL_THREAD_HANDLE_TYPE handle ); Description This function suspends a specific thread. If NULL is passed, the RTOS will attempt to suspend the thread in which the call was made. The thread will then only resume when unsuspended by another part of the program with an appropriate resume call. Preconditions Thread must have been created. Parameters Parameters Description handle The thread handle. NULL may be passed indicating suspend the calling thread. Returns OSAL_RESULT_TRUE - Thread suspended OSAL_RESULT_FALSE - Thread could not be suspended Remarks None. Example // suspend this thread OSAL_THREAD_Suspend(NULL); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1332 5.5.7.1.10 OSAL_THREAD_SuspendAll Function C OSAL_RESULT OSAL_THREAD_SuspendAll(); Description This function suspends all threads. Interrupts are still enabled. The calling thread will continue executing at the next instruction. Preconditions Thread must have been created. Returns OSAL_RESULT_TRUE - Threads suspended OSAL_RESULT_FALSE - Threads could not be suspended Remarks None. Example // suspend all threads OSAL_THREAD_SuspendAll(); // perform critical code sequence // NB a critical section may be a better choice here ... 5.5.7.2 Semaphore Functions 5.5.7.2.1 OSAL_SEM_Create Function C OSAL_RESULT OSAL_SEM_Create( OSAL_SEM_HANDLE_TYPE* semID, OSAL_SEM_TYPE type, uint8_t maxCount, uint8_t initialCount ); Description This function creates an OSAL binary or counting semaphore. If OSAL_SEM_TYPE_BINARY is specified, the maxcount and initialCount values are ignored; otherwise, these must contain valid values. Preconditions Semaphore must have been declared. Parameters Parameters Description semID Pointer to the Semaphore ID type OSAL_SEM_TYPE_BINARY, create a binary semaphore OSAL_SEM_TYPE_COUNTING, create a counting semaphore with the specified count values maxCount Maximum value for a counting semaphore (ignored for a BINARY semaphore) 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1333 initialCount Starting count value for the semaphore (ignored for a BINARY semaphore) Returns OSAL_RESULT_TRUE - Semaphore created OSAL_RESULT_FALSE - Semaphore creation failed semID - Updated with valid semaphore handle if call was successful Remarks None. Example OSAL_SEM_Create(&mySemID, OSAL_SEM_TYPE_COUNTING, 10, 5); 5.5.7.2.2 OSAL_SEM_Delete Function C OSAL_RESULT OSAL_SEM_Delete( OSAL_SEM_HANDLE_TYPE* semID ); Description This function deletes an OSAL semaphore, freeing up any allocated storage associated with it. Preconditions Semaphore must have been created. Parameters Parameters Description semID Pointer to the semID Returns OSAL_RESULT_TRUE - Semaphore deleted OSAL_RESULT_FALSE - Semaphore deletion failed Remarks None. Example OSAL_SEM_Delete(&mySemID); 5.5.7.2.3 OSAL_SEM_GetCount Function C uint8_t OSAL_SEM_GetCount( OSAL_SEM_HANDLE_TYPE semID ); Description This function returns the current value of a counting semaphore. The value returned is assumed to be a single value ranging from 0-255. Preconditions Semaphore must have been created. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1334 Parameters Parameters Description semID The semID Returns 0 - Semaphore is unavailable 1-255 - Current value of the counting semaphore Remarks None. Example uint8_t semCount; semCount = OSAL_SEM_GetCount(semUART); if (semCount > 0) { // obtain the semaphore if (OSAL_SEM_Pend(semUART) == OSAL_RESULT_TRUE) { // perform processing on the comm channel ... } } else { // no comm channels available ... } 5.5.7.2.4 OSAL_SEM_Pend Function C OSAL_RESULT OSAL_SEM_Pend( OSAL_SEM_HANDLE_TYPE semID, uint16_t waitMS ); Description This function is a blocking function call that waits (i.e., pends) on a semaphore. The function will return true is the semaphore has been obtained, or false if it was not available or the time limit was exceeded. Preconditions Semaphore must have been created. Parameters Parameters Description semID The semID waitMS Time limit to wait in milliseconds. 0, do not wait OSAL_WAIT_FOREVER, return only when semaphore is obtained Other values, timeout delay 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1335 Returns OSAL_RESULT_TRUE - Semaphore obtained OSAL_RESULT_FALSE - Semaphore not obtained or timeout occurred Remarks None. Example if (OSAL_SEM_Pend(semUARTRX, 50) == OSAL_RESULT_TRUE) { // character available c = DRV_USART_ReadByte(drvID); ... } else { // character not available, resend prompt ... } 5.5.7.2.5 OSAL_SEM_Post Function C OSAL_RESULT OSAL_SEM_Post( OSAL_SEM_HANDLE_TYPE semID ); Description This function posts a binary semaphore or increments a counting semaphore. The highest priority task currently blocked on the semaphore will be released and made ready to run. Preconditions Semaphore must have been created. Parameters Parameters Description semID The semID Returns OSAL_RESULT_TRUE - Semaphore posted OSAL_RESULT_FALSE - Semaphore not posted Remarks None. Example OSAL_SEM_Post(semSignal); 5.5.7.2.6 OSAL_SEM_PostISR Function C OSAL_RESULT OSAL_SEM_PostISR( OSAL_SEM_HANDLE_TYPE semID ); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1336 Description This function posts a binary semaphore or increments a counting semaphore. The highest priority task currently blocked on the semaphore will be released and made ready to run. This form of the post function should be used inside an ISR. Preconditions Semaphore must have been created. Parameters Parameters Description semID The semID Returns OSAL_RESULT_TRUE - Semaphore posted OSAL_RESULT_FALSE - Semaphore not posted Remarks This version of the OSAL_SEM_Post function should be used if the program is, or may be, operating inside an ISR. The OSAL will take the necessary steps to ensure correct operation possibly disabling interrupts or entering a critical section. The exact requirements will depend upon the particular RTOS being used. Example void __ISR(UART_2_VECTOR) _UART2RXHandler() { char c; // indicate to the OSAL that this is an interrupt function OSAL_ISR_Enter(); // read the character c = U2RXREG; // clear the interrupt flag IFS1bits.U2IF = 0; // post a semaphore indicating a character has been received OSAL_SEM_PostISR(semSignal); // indicate to the OSAL the ISR is ending OSAL_ISR_Exit(); } 5.5.7.2.7 OSAL_SEM_DECLARE Macro C #define OSAL_SEM_DECLARE(semID) OSAL_SEM_HANDLE_TYPE semID Description OSAL_SEM_Declare(semID) This function declares a data item of type OSAL_SEM_HANDLE_TYPE. Remarks None. 5.5.7.3 Mutex Functions 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1337 5.5.7.3.1 OSAL_MUTEX_Create Function C OSAL_RESULT OSAL_MUTEX_Create( OSAL_MUTEX_HANDLE_TYPE* mutexID ); Description This function creates a mutex, allocating storage if required and placing the mutex handle into the passed parameter. Preconditions Mutex must have been declared. Parameters Parameters Description mutexID Pointer to the mutex handle Returns OSAL_RESULT_TRUE - Mutex successfully created OSAL_RESULT_FALSE - Mutex failed to be created Remarks None. Example OSAL_MUTEX_HANDLE_TYPE mutexData; OSAL_MUTEX_Create(&mutexData); ... if (OSAL_MUTEX_Lock(mutexData, 1000) == OSAL_RESULT_TRUE) { // manipulate the shared data ... } 5.5.7.3.2 OSAL_MUTEX_Delete Function C OSAL_RESULT OSAL_MUTEX_Delete( OSAL_MUTEX_HANDLE_TYPE* mutexID ); Description This function deletes a mutex and frees associated storage if required. Preconditions None. Parameters Parameters Description mutexID Pointer to the mutex handle Returns OSAL_RESULT_TRUE - Mutex successfully deleted 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1338 OSAL_RESULT_FALSE - Mutex failed to be deleted Remarks None. Example OSAL_MUTEX_Delete(&mutexData); 5.5.7.3.3 OSAL_MUTEX_Lock Function C OSAL_RESULT OSAL_MUTEX_Lock( OSAL_MUTEX_HANDLE_TYPE mutexID, uint16_t waitMS ); Description This function locks a mutex, waiting for the specified timeout. If it cannot be obtained or the timeout period elapses 'false' is returned. Preconditions Mutex must have been created. Parameters Parameters Description mutexID The mutex handle waitMS Timeout value in milliseconds 0, do not wait return immediately OSAL_WAIT_FOREVER, wait until mutex is obtained before returning Other values, Timeout delay Returns OSAL_RESULT_TRUE - Mutex successfully obtained OSAL_RESULT_FALSE - Mutex failed to be obtained or timeout occurred Remarks None. Example OSAL_MUTEX_HANDLE_TYPE mutexData; OSAL_MUTEX_Create(&mutexData); ... if (OSAL_MUTEX_Lock(mutexData, 1000) == OSAL_RESULT_TRUE) { // manipulate the shared data ... // unlock the mutex OSAL_MUTEX_Unlock(mutexData); } 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1339 5.5.7.3.4 OSAL_MUTEX_Unlock Function C OSAL_RESULT OSAL_MUTEX_Unlock( OSAL_MUTEX_HANDLE_TYPE mutexID ); Description This function unlocks a previously obtained mutex. Preconditions Mutex must have been created. Parameters Parameters Description mutexID The mutex handle Returns OSAL_RESULT_TRUE - Mutex released OSAL_RESULT_FALSE - Mutex failed to be released or error occurred Remarks None. Example OSAL_MUTEX_HANDLE_TYPE mutexData; OSAL_MUTEX_Create(&mutexData); ... if (OSAL_MUTEX_Lock(mutexData, 1000) == OSAL_RESULT_TRUE) { // manipulate the shared data ... // unlock the mutex OSAL_MUTEX_Unlock(mutexData); } 5.5.7.3.5 OSAL_MUTEX_DECLARE Macro C #define OSAL_MUTEX_DECLARE(mutexID) OSAL_MUTEX_HANDLE_TYPE mutexID Description OSAL_MUTEX_Declare(mutexID) This function declares a data item of type OSAL_MUTEX_HANDLE_TYPE Remarks None 5.5.7.4 Queue Functions 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1340 5.5.7.4.1 OSAL_QUEUE_DECLARE Macro C #define OSAL_QUEUE_DECLARE(queueID) OSAL_QUEUE_HANDLE_TYPE queueID Description OSAL_QUEUE_Declare(queueID) This function declares a data item of type OSAL_QUEUE_HANDLE_TYPE. Remarks None 5.5.7.4.2 OSAL_QUEUE_Add Function C OSAL_RESULT OSAL_QUEUE_Add( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata, uint16_t waitMS ); Description This function adds the specified item to the queue by copying it. If the queue has space, the function will return immediately. If there is no space on the queue, the function will wait up to the specified time before returning. The item is added to the tail of the queue. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the data to be copied to the queue. The data item must be the same size as that specified when creating the queue. waitMS Time to wait while trying to write to a full queue before timing out Returns OSAL_RESULT_TRUE - Item successfully added to the queue OSAL_RESULT_FALSE - Item could not be written to the queue or a timeout occurred Remarks None. Example // create a queue containing 16 byte items, queue is 5 items long. OSAL_QUEUE_Create(&msgQueue, 16, 5); ... // define a message (Note 0 at end is allowed for) const char msg[16] = "Hello World...."; // write data to the queue. Wait until space is available // Note in this case that the 0 at the end of msg is also copied 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1341 OSAL_QUEUE_Add(msgQueue, (uint8_t*) msg, OSAL_WAIT_FOREVER); 5.5.7.4.3 OSAL_QUEUE_AddHead Function C OSAL_RESULT OSAL_QUEUE_AddHead( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata, uint16_t waitMS ); Description This function adds the specified item to the front of the queue by copying it. If the queue has space the function will return immediately. If there is no space on the queue then wait up to the specified time before returning. The item is added to the front of the queue. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the data to be copied to the queue. The data item must be the same size as that specified when creating the queue. waitMS Time to wait while trying to write to a full queue before timing out Returns OSAL_RESULT_TRUE - Item successfully added to the queue OSAL_RESULT_FALSE - Item could not be written to the queue or a timeout occurred OSAL_RESULT_NOT_IMPLEMENTED - Function not implemented in the current RTOS Remarks None. Example // create a queue containing byte items, queue is 5 items long. OSAL_QUEUE_Create(&msgQueue, sizeof(uint8_t), 5); ... // Send an important message uint8_t sigMsg = 42; // write data to the front of the queue. OSAL_QUEUE_AddHead(msgQueue, &sigMsg, OSAL_WAIT_FOREVER); 5.5.7.4.4 OSAL_QUEUE_AddHeadISR Function C OSAL_RESULT OSAL_QUEUE_AddHeadISR( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata ); Description This function adds the specified item to the queue by copying it. The item is added to the front of the queue. This version of Add 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1342 should be used within an ISR. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the data to be copied to the queue. The data item must be the same size as that specified when creating the queue. Returns OSAL_RESULT_TRUE - Item successfully added to the queue OSAL_RESULT_FALSE - Item could not be written to the queue OSAL_RESULT_NOT_IMPLEMENTED - Function not implemented in the current RTOS Remarks None. Example void __ISR(EXTERNAL_VECTOR) _ExternalIRQHandler() { const uint8_t msg = EMERGENCY_STOP; OSAL_ISR_Enter(); // clear the interrupt flag IFS1bit.EIF = 0; // send an emergency message to any listening task OSAL_QUEUE_AddHeadISR(myRXQueue, msg); OSAL_ISR_Exit(); } 5.5.7.4.5 OSAL_QUEUE_AddISR Function C OSAL_RESULT OSAL_QUEUE_AddISR( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata ); Description This function adds the specified item to the queue by copying it. The item is added to the tail of the queue. This version of Add should be used within an ISR. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the data to be copied to the queue. The data item must be the same size as that specified when creating the queue. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1343 Returns OSAL_RESULT_TRUE - Item successfully to the queue OSAL_RESULT_FALSE - Item could not be added to the queue Remarks None. Example void __ISR(UART_2_VECTOR) _UART2RXHandler() { char c; OSAL_ISR_Enter(); // read the character c = U2RXREG; // clear the interrupt flag IFS1bits.U2IF = 0; // post the received character onto a queue for later processing OSAL_QUEUE_AddISR(myRXQueue, c); OSAL_ISR_Exit(); } 5.5.7.4.6 OSAL_QUEUE_Create Function C OSAL_RESULT OSAL_QUEUE_Create( OSAL_QUEUE_HANDLE_TYPE* queueID, uint16_t width, uint16_t depth ); Description This function allocates storage and creates an OSAL queue entity. Each entry in the queue will be 'width' bytes in size and the queue can contain at most 'depth' items. Preconditions Queue must have been declared. Parameters Parameters Description queueID Pointer to the OSAL queue width Width in bytes of each item in the queue depth Maximum number of entries that can be stored in the queue Returns OSAL_RESULT_TRUE - Queue created OSAL_RESULT_FALSE - Queue failed to be created Remarks The function creates an OSAL_QUEUE with the specified parameters. OSAL_QUEUEs are assumed to work on copy with passed data being copied into the queue or other temporary storage so that the passed data storage is released. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1344 Example // declare a queue variable OSAL_QUEUE_Declare(serialQueue); // create a queue that contains 16bit integers and is 10 items long OSAL_QUEUE_Create(&serialQueue, sizeof(uint16_t), 10); 5.5.7.4.7 OSAL_QUEUE_Delete Function C OSAL_RESULT OSAL_QUEUE_Delete( OSAL_QUEUE_HANDLE_TYPE* queueID ); Description This function deletes an OSAL_QUEUE pointed to be the passed argument. Associated storage is released upon completion. Preconditions Queue must have been created. Parameters Parameters Description queueID Pointer to the OSAL_QUEUE object handle Returns OSAL_RESULT_TRUE - Queue deleted OSAL_RESULT_FALSE - Queue failed to be deleted Remarks None. Example // declare a queue variable OSAL_QUEUE_Declare(serialQueue); // create a queue that contains 16bit integers and is 10 items long OSAL_QUEUE_Create(&serialQueue, sizeof(uint16_t), 10); // application is terminating, delete queue object OSAL_QUEUE_Delete(&serialQueue); 5.5.7.4.8 OSAL_QUEUE_Peek Function C OSAL_RESULT OSAL_QUEUE_Peek( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata, uint16_t waitMS ); Description This function examines the queue and copy the item at the head leaving the item on the queue for the next access. If there is nothing on the queue, block until waitMS milliseconds have elapsed before returning, or until something is placed on the queue. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1345 Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the location to receive data copied from the queue. The data item must be the same size as that specified when creating the queue. waitMS Maximum time to wait before returning if the queue is empty 0, return immediately OSAL_WAIT_FOREVER, wait until data is in the queue Others, maximum blocking time in milliseconds Returns OSAL_RESULT_TRUE - Item successfully copied from the queue OSAL_RESULT_FALSE - Nothing copied from the queue or timeout occurred OSAL_RESULT_NOT_IMPLEMENTED - Operation not available on the current RTOS Remarks None. Example // copy filenames from a queue and process the data in the file // however if another filename is on the queue then abort and // restart the operation OSAL_QUEUE_Remove(rxQueue, fileName, OSAL_WAITFOREVER); while (abort == false) { // read data from the file and process it ... // check for a new filename to process if (OSAL_QUEUE_Peek(rxQueue, fileName, 0) == OSAL_RESULT_TRUE) { abort = true; } } 5.5.7.4.9 OSAL_QUEUE_PeekISR Function C OSAL_RESULT OSAL_QUEUE_PeekISR( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata ); Description This function examines the queue and copies the item at the head, leaving the item on the queue for the next access. This version should be called from inside an ISR. Preconditions Queue must have been created. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1346 Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the location to receive data copied from the queue. The data item must be the same size as that specified when creating the queue. Returns OSAL_RESULT_TRUE - Item successfully copied from the queue OSAL_RESULT_FALSE - Nothing copied from the queue OSAL_RESULT_NOT_IMPLEMENTED - Operation not available on the current RTOS Remarks None. Example uint16_t data; OSAL_QUEUE_PeekISR(myQueue, &data); 5.5.7.4.10 OSAL_QUEUE_Remove Function C OSAL_RESULT OSAL_QUEUE_Remove( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata, uint16_t waitMS ); Description This function removes the item at the head of the queue. The item is copied to the location pointed to by pdata. The user should ensure that there is sufficient space to receive the copied data. If no data is available, the function will block for waitMS before returning. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the location to receive data copied from the queue. The data item must be the same size as that specified when creating the queue. waitMS Maximum time to wait before returning if the queue is empty 0, return immediately OSAL_WAIT_FOREVER, wait until data is in the queue Others, maximum blocking time in milliseconds Returns OSAL_RESULT_TRUE - Item successfully removed from the queue OSAL_RESULT_FALSE - Nothing removed from the queue or timeout occurred Remarks None. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1347 Example char rxChar; // wait up to one second to process the next character if (OSAL_QUEUE_Remove(rxQueue, &rxChar, 1000) == OSAL_RESULT_TRUE) { // process the data ... } else { // nothing received in the last one second so perform other processing ... } 5.5.7.4.11 OSAL_QUEUE_RemoveISR Function C OSAL_RESULT OSAL_QUEUE_RemoveISR( OSAL_QUEUE_HANDLE_TYPE queueID, uint8_t* pdata ); Description This function removes the item at the head of the queue. Item is copied to the location pointed to by pdata. The user should ensure that there is sufficient space to receive the copied data. This version of the queue remove function should be used inside an ISR. Preconditions Queue must have been created. Parameters Parameters Description queueID The OSAL_QUEUE handle pdata Pointer to the location to receive data copied from the queue. The data item must be the same size as that specified when creating the queue. Returns OSAL_RESULT_TRUE - Item successfully removed from the queue OSAL_RESULT_FALSE - Nothing removed from the queue Remarks None. Example char rxChar; void __ISR(TIMER_1_VECTOR) _ET1IRQHandler() { const uint8_t msg; OSAL_ISR_Enter(); // clear the interrupt flag IFS0bits.T1IF = 0; // check for data to be sent from a queue if (OSAL_QUEUE_RemoveISR(myTXQueue, msg) == OSAL_RESULT_TRUE) { 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1348 DRV_USART_WriteByte(uart_drv, msg); } OSAL_ISR_Exit(); } 5.5.7.5 Critical Section Functions 5.5.7.5.1 OSAL_CRIT_Enter Function C void OSAL_CRIT_Enter( OSAL_CRIT_TYPE severity ); Description Critical Section group *************************************************************************** This function enters a critical section of code. It is assumed that the sequence of operations bounded by the enter and leave critical section operations is treated as one atomic sequence that will not be disturbed. Preconditions None. Parameters Parameters Description severity OSAL_CRIT_TYPE_LOW, The RTOS should disable all other running tasks effectively locking the scheduling mechanism. OSAL_CRIT_TYPE_HIGH, The RTOS should disable all possible interrupts sources including the scheduler ensuring that the sequence of code operates without interruption. Returns None. Remarks The sequence of operations bounded by the OSAL_CRIT_Enter and OSAL_CRIT_Leave form a critical section. The severity level defines whether the RTOS should perform task locking or completely disable all interrupts. Example // prevent other tasks pre-empting this sequence of code OSAL_CRIT_Enter(OSAL_CRIT_TYPE_LOW); // modify the peripheral DRV_USART_Reinitialize( objUSART, &initData); OSAL_CRIT_Leave(OSAL_CRIT_TYPE_LOW); 5.5.7.5.2 OSAL_CRIT_Leave Function C void OSAL_CRIT_Leave( OSAL_CRIT_TYPE severity ); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1349 Description This function leaves a critical section of code. It is assumed that the sequence of operations bounded by the enter and leave critical section operations is treated as one atomic sequence that will not be disturbed. The severity should match the severity level used in the corresponding OSAL_CRIT_Enter call to ensure that the RTOS carries out the correct action. Preconditions None. Parameters Parameters Description severity OSAL_CRIT_TYPE_LOW, The RTOS should disable all other running tasks effectively locking the scheduling mechanism. OSAL_CRIT_TYPE_HIGH, The RTOS should disable all possible interrupts sources including the scheduler ensuring that the sequence of code operates without interruption. Returns None. Remarks The sequence of operations bounded by the OSAL_CRIT_Enter and OSAL_CRIT_Leave form a critical section. The severity level defines whether the RTOS should perform task locking or completely disable all interrupts. Example // prevent other tasks pre-empting this sequence of code OSAL_CRIT_Enter(OSAL_CRIT_TYPE_LOW); // modify the peripheral DRV_USART_Reinitialize( objUSART, &initData); OSAL_CRIT_Leave(OSAL_CRIT_TYPE_LOW); 5.5.7.5.3 OSAL_CRIT_TYPE Enumeration C enum OSAL_CRIT_TYPE { OSAL_CRIT_TYPE_LOW, OSAL_CRIT_TYPE_HIGH }; Description OSAL Critical Type This enum represents possible critical section types. OSAL_CRIT_TYPE_LOW - Low priority critical section, can be formed by locking the scheduler (if supported by RTOS) OSAL_CRIT_TYPE_HIGH - High priority critical section, will be formed by disabling all interrupts. Remarks Critical section types 5.5.7.6 Interrupt Handling Functions 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1350 5.5.7.6.1 OSAL_ISR_Enter Function C void OSAL_ISR_Enter(); Description This function allows the OSAL and RTOS to implement any set up required should an OSAL function be called during the interrupt handler. Depending on the underlying RTOS, it may be necessary to set a global flag indicating that an interrupt is currently being executed for the correct context code to be executed during calls to the kernel. OSAL_ISR_Enter allows the RTOS to implement the required functions. Preconditions None, (in an interrupt handler). Returns None. Remarks None. Example void __ISR(UART_2_VECTOR) _UART2RXHandler() { char c; OSAL_ISR_Enter(); // perform interrupt processing and clear the flag ... OSAL_ISR_Exit(); } 5.5.7.6.2 OSAL_ISR_Exit Function C void OSAL_ISR_Exit(); Description This function allows the OSAL and RTOS to implement any restoration required after an ISR has completed. Depending on the underlying RTOS, it may be necessary to set a global flag indicating that an interrupt is currently being executed for the correct context code to be executed during calls to the kernel. OSAL_ISR_Exit allows the RTOS to implement the required functions. Preconditions None, (in an interrupt handler). Returns None. Remarks None. Example void __ISR(UART_2_VECTOR) _UART2RXHandler() { 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1351 char c; OSAL_ISR_Enter(); // perform interrupt processing and clear the flag ... OSAL_ISR_Exit(); } 5.5.7.7 Error Handling Functions 5.5.7.7.1 OSAL_ERROR_CALLBACK_TYPE Enumeration C enum OSAL_ERROR_CALLBACK_TYPE { OSAL_ERROR_CALLBACK_DEFAULT = 0, OSAL_ERROR_CALLBACK_OUT_OF_MEMORY, OSAL_ERROR_CALLBACK_STACK_OVERFLOW, OSAL_ERROR_CALLBACK_ERROR }; Description OSAL Error Callback Type This enum represents possible OSAL error callback types. OSAL_ERROR_CALLBACK_DEFAULT - Default error OSAL_ERROR_CALLBACK_OUT_OF_MEMORY - Out of memory allocating resource such as creating a task or queue OSAL_ERROR_CALLBACK_STACK_OVERFLOW - Stack overflow detected in a task OSAL_ERROR_CALLBACK_ERROR - Generic error message Remarks Error types are heavily RTOS specific so only basic types are indicated 5.5.7.7.2 OSAL_ErrorCallback Function C void OSAL_ErrorCallback( OSAL_ERROR_CALLBACK_TYPE type ); Description The callback function will be executed whenever an error occurs within an underlying RTOS. The OSAL implements this function as a weak type allowing it to be overridden by the user. The type and severity of errors that can be encountered by an RTOS will vary according to the specific implementation so this only provides lightweight error handling. There is no expectation that the function should return and if this does happen there is no guarantee that the RTOS will continue to function properly. A user application could override this function and provide simple signalling of the error such as logging a message or flashing a light. Preconditions None. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1352 Parameters Parameters Description type Type of error OSAL_ERROR_CALLBACK_DEFAULT, Default error OSAL_ERROR_CALLBACK_OUT_OF_MEMORY, Memory allocation error OSAL_ERROR_CALLBACK_STACK_OVERFLOW, Stack overflow in a thread OSAL_ERROR_CALLBACK_ERROR, Generic error Returns None Remarks None. Example // application override of the callback void OSAL_ErrorCallback(OSAL_ERROR_CALLBACK_TYPE type) { // turn on the fault light LATAbits.LATA0 = 1; // do not return while (1) { } } 5.5.7.8 Memory Allocation Functions 5.5.7.8.1 OSAL_Free Function C void OSAL_Free( void* pData ); Description This function deallocates memory and returns it to the default pool. In an RTOS-based application, the memory may have been allocated from multiple pools or simply from the heap. In non-RTOS applications, this function calls the C standard function free. Preconditions None. Parameters Parameters Description pData Pointer to the memory block to be set free Returns None. Remarks None. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1353 Example // create a working array uint8_t* pData; pData = OSAL_Malloc(32); if (pData != NULL) { ... // deallocate the memory OSAL_Free(pData); // and prevent it accidentally being used again pData = NULL; } 5.5.7.8.2 OSAL_Malloc Function C void* OSAL_Malloc( size_t size ); Description This function allocates a block of memory from the default allocator from the underlying RTOS. If no RTOS is present, it defaults to malloc. Many operating systems incorporate their own memory allocation scheme, using pools, blocks or by wrapping the standard C library functions in a critical section. Since an Harmony application may not know what target OS is being used (if any), this function ensures that the correct thread safe memory allocator will be used. Preconditions None. Parameters Parameters Description size Size of the requested memory block in bytes Returns Pointer to the block of allocated memory. NULL is returned if memory could not be allocated. Remarks None. Example // create a working array uint8_t* pData; pData = OSAL_Malloc(32); if (pData != NULL) { ... } 5.5.7.9 OSAL Control Functions 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1354 5.5.7.9.1 OSAL_Initialize Function C OSAL_RESULT OSAL_Initialize(); Description This function performs OSAL initialization .This function should be called near the start of main in an application that will use an underlying RTOS. This permits the RTOS to perform any one time initialization before the application attempts to create drivers or other items that may use the RTOS. Typical actions performed by OSAL_Initialize would be to allocate and prepare any memory pools for later use. Preconditions None. Returns OSAL_RESULT_TRUE - Initialization completed successfully. Remarks None. Example int main() { OSAL_Initialize(); App_Init(); OSAL_Start(); } 5.5.7.9.2 OSAL_Name Function C const char* OSAL_Name(); Description This function returns a const char* to the textual name of the RTOS. The name is a NULL terminated string. Preconditions None. Returns const char* - Name of the underlying RTOS or NULL Remarks None. Example // get the RTOS name const char* sName; sName = OSAL_Name(); sprintf(buff, "RTOS: %s", sName); 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1355 5.5.7.9.3 OSAL_Start Function C OSAL_RESULT OSAL_Start(); Description This function starts the underlying RTOS application. The application will not normally return from this function call since the RTOS and interrupts will be responsible for all program operation. A return from this function is usually fatal and indicates that the program has failed in some way. Preconditions None. Returns OSAL_RESULT_FALSE - The OS terminated for some reason Remarks None. Example int main() { OSAL_Initialize(); App_Init(); OSAL_Start(); } 5.5.7.10 Data Types and Constants 5.5.7.10.1 OSAL_MUTEX_HANDLE_TYPE Macro C #define OSAL_MUTEX_HANDLE_TYPE uint8_t Description Handle to a mutex, this is the default implementation and may be overridden in an actual implementation file 5.5.7.10.2 OSAL_QUEUE_HANDLE_TYPE Macro C #define OSAL_QUEUE_HANDLE_TYPE uint8_t Description Handle to a queue, this is the default implementation and may be overridden in an actual implementation file 5.5.7.10.3 OSAL_SEM_HANDLE_TYPE Macro C #define OSAL_SEM_HANDLE_TYPE uint8_t 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1356 Description Handle to a semaphore, this is the default implementation and may be overridden in an actual implementation file 5.5.7.10.4 OSAL_THREAD_HANDLE_TYPE Macro C #define OSAL_THREAD_HANDLE_TYPE uintptr_t Description Handle to a thread, this is the default implementation and may be overridden in an actual implementation file 5.5.7.10.5 OSAL_USE_NONE Macro C #define OSAL_USE_NONE Description This is macro OSAL_USE_NONE. 5.5.7.10.6 OSAL_WAIT_FOREVER Macro C #define OSAL_WAIT_FOREVER (uint16_t) 0xFFFF Description Default value indicating block forever 5.5.7.10.7 OSAL_RESULT Enumeration C enum OSAL_RESULT { OSAL_RESULT_NOT_IMPLEMENTED = -1, OSAL_RESULT_FALSE = 0, OSAL_RESULT_TRUE = 1 }; Description OSAL Result type This enum represents possible return types from OSAL functions. Remarks These enum values are the possible return values from OSAL functions where a standard success/fail type response is required. The majority of OSAL functions will return this type with a few exceptions. 5.5.7.10.8 OSAL_SEM_TYPE Enumeration C enum OSAL_SEM_TYPE { OSAL_SEM_TYPE_BINARY, 5.5 Operating System Abstraction Layer MPLAB Harmony Help Library Interface 5-1357 OSAL_SEM_TYPE_COUNTING }; Description OSAL Semaphore Type This enum represents possible semaphore types. OSAL_SEM_TYPE_BINARY - Simple binary type that can be taken once OSAL_SEM_TYPE_COUNTING - Complex type that can be taken set number of times defined at creation time Remarks Binary and counting semaphore type. 5.5.8 Files Files Name Description osal.h Common interface definitions for the Operating System Abstraction Layer (OSAL). Description 5.5.8.1 osal.h Descriptive File Name: Operating System Abstraction Layer This file defines the common interface to the Operating System Abstraction Layer. It defines the common types used by the OSAL and defines the function prototypes. Depending upon the OSAL mode, a support level specific implementation file is included by this file to give the required level of compatibility. The available support levels include, OSAL_USE_NONE, OSAL_USE_BASIC, and OSAL_USE_RTOS. Enumerations Name Description OSAL_CRIT_TYPE Enumerated type respresenting the possible types of critical section. OSAL_ERROR_CALLBACK_TYPE Enumerated type respresenting the possible types of callback message. OSAL_RESULT Enumerated type representing the general return value from OSAL functions. OSAL_SEM_TYPE Enumerated type respresenting the possible types of semaphore. Functions Name Description OSAL_CRIT_Enter Enters a critical section with the specified severity level. OSAL_CRIT_Leave Leaves a critical section with the specified severity level. OSAL_ErrorCallback Lightweight error handling callback function for the RTOS. OSAL_Free Deallocates a block of memory and return to the default pool. OSAL_Initialize Performs OSAL initialization. OSAL_ISR_Enter Informs the OSAL and RTOS that an ISR is being entered. OSAL_ISR_Exit Informs the OSAL and RTOS that an ISR is being exited. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Files 5-1358 OSAL_Malloc Allocates memory using the OSAL default allocator. OSAL_MUTEX_Create Creates a mutex. OSAL_MUTEX_Delete Deletes a mutex. OSAL_MUTEX_Lock Locks a mutex. OSAL_MUTEX_Unlock Unlocks a mutex. OSAL_Name Obtains the name of the underlying RTOS. OSAL_QUEUE_Add Addd the specified item to the queue with a time-out if the queue is full. OSAL_QUEUE_AddHead Adds the specified item to the front of the queue with a timeout if the queue is full. OSAL_QUEUE_AddHeadISR Adds the specified item to the front of the queue from within an ISR. OSAL_QUEUE_AddISR Adds the specified item to the queue from with an ISR. OSAL_QUEUE_Create Creates a queue with the specified width and depth. OSAL_QUEUE_Delete Deletes an OSAL_QUEUE. OSAL_QUEUE_Peek Copys the item at the head of the queue but leave it on the queue. If the queue is empty, it will block up to waitMS. OSAL_QUEUE_PeekISR Copys the item at the head of the queue but leaves it on the queue. OSAL_QUEUE_Remove Removes the item at the head of the queue. If the queue is empty it will block up to waitMS. OSAL_QUEUE_RemoveISR Removes the item at the head of the queue. OSAL_SEM_Create Creates an OSAL Semaphore. OSAL_SEM_Delete Deletes an OSAL Semaphore. OSAL_SEM_GetCount Returns the current value of a counting semaphore. OSAL_SEM_Pend Waits on a semaphore. Returns true if the semaphore was obtained within the time limit. OSAL_SEM_Post Posts a semaphore or increments a counting semaphore. OSAL_SEM_PostISR Posts a semaphore or increments a counting semaphore from within an Interrupt Service Routine (ISR). OSAL_Start Starts the underlying RTOS OSAL_THREAD_Create Creates an OSAL thread with the specified parameters. OSAL_THREAD_CreateDaemon Creates a Daemon thread for use with multi-threaded Harmony drivers. OSAL_THREAD_PriorityGet Gets the priority of a thread. OSAL_THREAD_PrioritySet Sets the priority of a thread. OSAL_THREAD_Resume Resumes a specified thread. OSAL_THREAD_ResumeAll Resumes all suspended threads. OSAL_THREAD_Sleep Puts the currently executing thread to sleep. OSAL_THREAD_Suspend Suspends a specified thread. OSAL_THREAD_SuspendAll Suspends all threads apart from the calling thread. Macros Name Description OSAL_MUTEX_DECLARE Declares an OSAL mutex. OSAL_MUTEX_HANDLE_TYPE Handle to a mutex, this is the default implementation and may be overridden in an actual implementation file OSAL_QUEUE_DECLARE Declares an OSAL queue. OSAL_QUEUE_HANDLE_TYPE Handle to a queue, this is the default implementation and may be overridden in an actual implementation file OSAL_SEM_DECLARE Declares an OSAL semaphore. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Files 5-1359 OSAL_SEM_HANDLE_TYPE Handle to a semaphore, this is the default implementation and may be overridden in an actual implementation file OSAL_THREAD_HANDLE_TYPE Handle to a thread, this is the default implementation and may be overridden in an actual implementation file OSAL_USE_NONE This is macro OSAL_USE_NONE. OSAL_WAIT_FOREVER Default value indicating block forever Types Name Description OSAL_THREAD_FUNCTION Functions that will operate as a separate thread under the OSAL should match this type. File Name osal.h Company Microchip Technology Inc. 5.5 Operating System Abstraction Layer MPLAB Harmony Help Files 5-1360 5.6 Peripheral Library Help This section provides descriptions of the MPLAB Harmony peripheral libraries. Description This section contains the list of peripheral libraries. 5.6.1 ADC Peripheral Library This topic describes the Analog-to-Digital Converter peripheral library interface. Description This section contains the list of topics. 5.6.1.1 Introduction ADC Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Analog-to-Digital Converter (ADC) module, which is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. ADC Overview An ADC is an analog peripheral that converts a continuous quantity to a discrete digital number. An ADC is a signal conversion process that periodically samples and converts a continuously varying signal - analog level into digital values. An ADC might be used to make an isolated measurement. ADCs are also used to quantize time-varying signals by turning them into a sequence of digital samples. This results in the signal being quantized in both time and value. The resolution of a converter indicates the number of discrete values it can produce over the range of analog values. This library currently supports 8-bit, 10-bit, and 12-bit resolution. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1361 5.6.1.2 Release Notes MPLAB Harmony Version: v0.70b ADC Peripheral Library Version: 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.1.4 Using the Library Using the Libary This topic describes the basic architecture of the ADC Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_adc.h The interface to the ADC library is defined in the "plib_adc.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the ADC library must include "peripheral.h". Library File: The ADC peripheral library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using a Microchip compiler. 5.6.1.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the ADC module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1362 Description Hardware Abstraction Model The ADC module accepts an analog signal at any one instance and converts it to a corresponding 8-bit, 10-bit, or 12-bit digital value. It can accommodate a number of analog inputs and separate reference inputs; the actual number available on a particular device depends on the package size. Hardware Abstraction Block Diagram A combination of input multiplexers can select the signal to be converted from multiple analog input pins. The entire multiplexer path includes provision for differential analog input, although the number of negative input pins is limited, and the signal difference must remain positive (i.e., unipolar). Sampling Logic: An internal Sample and Hold (S&H) circuit acquires a sample of an input signal, and then holds that value constant during the conversion process. The purpose of the S&H circuitry is to take a snapshot of the sensor signal and hold the value. The sampled voltage is held and converted to a digital value, which strictly speaking, represents the ratio of that input voltage to a reference voltage. Configuration choices can allow connection of an external reference or use of the device power and ground (AVDD and AVSS). Conversion Logic: The heart of the ADC is the conversion logic that converts the analog signal value into its equivalent discrete representation. Conversions can be started individually by program control, continuously free-running, or triggered by selected hardware events. A single channel may be repeatedly converted, alternate conversions may be performed on two channels, or any or all of the channels may be sequentially scanned and converted according to a user-defined bit map. Result Handling: The resulting conversion output is a 8-bit, 10-bit, or 12-bit digital number that can be signed or unsigned, left- or right-justified in a 16-bit word. ADC Timing Details: Sample time is the time that the ADC module’s S&H circuit is connected to the analog input pin. The sample time may be started and ended automatically by the ADC’s hardware or under direct program control. There is a minimum sample time to ensure that the S&H circuit will provide sufficient accuracy for the analog-to-digital conversion. Conversion time is the time required for the ADC to convert the voltage held by the S&H circuit. The conversion trigger ends the sampling time and begins an analog-to-digital conversion or a repeating sequence. The conversion trigger sources can be taken from a variety of hardware sources or can be controlled directly in software. Once the conversion is complete, the S&H circuit can be reconnected to the input pin and a CPU interrupt may be generated. The sum of the sample time and the analog-to-digital conversion time provides the total ADC sequence time. The following figure shows the basic conversion sequence and the relationship between intervals. ADC Sample/Convert Sequence 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1363 The conversion trigger sources can be taken from a variety of hardware sources, or can be controlled directly by software. One of the conversion trigger options is an auto-conversion, which uses a counter and the ADC clock to set the time between auto-conversions. The Auto-Sample mode and auto-conversion trigger can be used together to provide continuous automatic conversions without software intervention. A sample/convert sequence that uses multiple S&H channels can be simultaneously sampled or sequentially sampled. Simultaneously sampling multiple signals ensures that the snapshot of the analog inputs occurs at precisely the same time for all inputs. Sequential sampling takes a snapshot of each analog input just before conversion starts on that input. The sampling of multiple inputs is not correlated. Channel Multiplexers: On some devices, S&H circuits have analog multiplexers on both their non-inverting and inverting inputs to select which analog input(s) are sampled. The ADC of some devices incorporate two independent sets of input multiplexers (MUX A and MUX B), which allow users to choose the analog channels that are to be sampled. Functionally, MUX A and MUX B are very similar to each other. Both multiplexers allow any of the analog input channels to be selected for individual sampling and allow selection of a negative reference source for differential signals. In addition, MUX A can be configured for sequential analog channel scanning. By default the ADC only samples and converts the inputs selected by MUX A. There is also a possibility to alternate between two sets of inputs selected by MUX A and MUX B during successive samples. MUX Abstraction Model 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1364 When using MUX A to select analog inputs, the ADC module has the ability to scan multiple analog channels sequentially. Input Selection: The ADC module provides a flexible mechanism to select analog inputs for conversion: • Fixed input selection • Alternate input selection • Channel scanning Fixed input selection: This is achieved through one or more of the S&H channels available in the device. The S&H channels are connected to the analog input pins through the analog multiplexer. Alternate Sampling: In an Alternate Input Selection mode, the ADC completes one sweep using the MUX A selection, and then another sweep using the MUX B selection, and then another sweep using the MUX A selection, and so on. Alternate Input Selection in 2-Channel Sequential Sampling Configuration Channel Scanning: On some devices, the ADC module supports the Channel Scan mode using S&H Channel 0 (CH0). The number of inputs scanned is software selectable. Any subset of the analog inputs from AN0 to AN31 (depending on the number of analog inputs present on a specific device) can be selected for conversion. The selected inputs are converted in ascending order. For example, if the input selection includes AN4, AN1, and AN3, the conversion sequence is AN1, AN3, and AN4. Scan Four Analog Inputs Using CH0 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1365 Multi-Channel Sample Conversion: Multi-channel analog-to-digital converters typically convert each input channel sequentially using an input multiplexer. Simultaneously sampling multiple signals ensures that the snapshot of the analog inputs occurs at precisely the same time for all inputs. Certain applications require simultaneous sampling, especially when phase information exists between different channels. Sequential sampling takes a snapshot of each analog input just before conversion starts on that input. Certain ADC modules supports simultaneous sampling using two S&H or four S&H channels to sample the inputs at the same instance, and then perform the conversion for each channel sequentially. Simultaneous and Sequential Sampling Specifying Conversion Results Buffering for Devices with Direct Memory Access (DMA): The ADC module contains a single-word, read-only, dual-port register, which stores the ADC conversion result. If more than one conversion result needs to be buffered before triggering an interrupt, DMA data transfers can be used. If DMA is supported and enabled, multiple conversion results can be automatically transferred from ADC internal buffer to a user-defined buffer in the DMA RAM area. Therefore, the application can process several conversion results with minimal software overhead. 5.6.1.4.2 Library Usage Model Usage Model The set of interface routines for the ADC Peripheral Library are: Library Interface Section Description 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1366 5.6.1.4.3 How the Library Works How the Library Works The following processes are involved while using an ADC module: • Initialization • Controlling the sampling process • Controlling the conversion process • Accessing the results buffer 5.6.1.4.3.1 General The ADC conversion process can be thought of in terms of a finite state machine. The sample state represents the time that the input channel is connected to the S&H circuit and the signal is passed to the converter input. The convert state is transitory; the module enters this state as soon as it exits the sample state and transitions to a different state when that is done. The inactive state is the default state prior to module initialization and following a software-controlled conversion; it can be avoided in operation by using Auto-Sample mode. Description ADC Conversion Sequence or State Machine 5.6.1.4.3.2 Initialization This topic provides information on the different processes needed to perform an analog-to-digital conversion. Description The following processes should be followed for performing an analog-to-digital conversion: Initialize the ADC Module: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1367 Number Description Functions associated 1 Selecting the voltage reference source Idle mode control PLIB_ADC_VoltageReferenceSelect PLIB_ADC_StopInIdleEnable/ PLIB_ADC_StopInIdleDisable 2 Selecting the ADC conversion clock PLIB_ADC_ConversionClockSet 3 Input channel selection Configuring MUX A and MUX B inputs, Alternating MUX A and MUX B input selections, Scanning through several inputs Scan Mask Selection PLIB_ADC_InputScanMaskAdd PLIB_ADC_InputScanMaskRemove Positive Inputs PLIB_ADC_InputSelectPositive PLIB_ADC_MuxChannel0InputPositiveSelect PLIB_ADC_MuxChannel123InputPositiveSelect Negative Inputs PLIB_ADC_InputSelectNegative PLIB_ADC_MuxChannel0InputNegativeSelect PLIB_ADC_MuxChannel123InputNegativeSelect Scan Mode Selection PLIB_ADC_MuxAInputScanEnable PLIB_ADC_MuxAInputScanDisable 4 Enabling the ADC module PLIB_ADC_Enable 5 Determine how many S&H channels will be used PLIB_ADC_ChannelGroupSelect 6 Determine how sampling will occur Sampling Control PLIB_ADC_SamplingModeEnable PLIB_ADC_SamplingModeDisable PLIB_ADC_SampleAcqusitionTimeSet 7 Selecting Manual or Auto-Sampling PLIB_ADC_SampleAutoStartEnable PLIB_ADC_SampleAutoStartDisable PLIB_ADC_SamplingStart 8 Select conversion trigger and sampling time PLIB_ADC_ConversionStart PLIB_ADC_ConversionClockSourceSelect PLIB_ADC_ConversionTriggerSourceSelect PLIB_ADC_ConversionStopSequenceEnable/ PLIB_ADC_ConversionStopSequenceDisable 9 Select how conversion results are stored in buffer PLIB_ADC_ResultBufferModeSelect 10 Select the result format Result sign PLIB_ADC_ResultFormatSelect PLIB_ADC_ResultSignGet 11 Select the number of readings per interrupt PLIB_ADC_SamplesPerInterruptSelect 12 Select number of samples in DMA buffer for each ADC module and select how the DMA will access the ADC buffers PLIB_ADC_DMAEnable/PLIB_ADC_DMADisable PLIB_ADC_DMABufferModeSelect PLIB_ADC_DMAAddressIncrementSelect PLIB_ADC_DMAInputBufferSelect 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1368 13 Select the 10-bit or 12-bit mode PLIB_ADC_ResultSizeSelect 14 Channel pair configuration PLIB_ADC_PairTriggerSourceSelect PLIB_ADC_PairConversionStart PLIB_ADC_PairInterruptRequestEnable PLIB_ADC_PairInterruptRequestDisable 15 Miscellaneous ADC functions: Asynchronous sampling selection Early interrupt control Conversion order selection Global software trigger control User ISR jump address PLIB_ADC_AsynchronousDedicatedSamplingEnable PLIB_ADC_AsynchronousDedicatedSamplingDisable PLIB_ADC_PairInterruptAfterFirstConversion PLIB_ADC_PairInterruptAfterSecondConversion PLIB_ADC_ConversionOrderSelect PLIB_ADC_GlobalSoftwareTriggerSet PLIB_ADC_IsrJumpTableBaseAddressSet Reference Channels Initialization: Internal reference channels like band gap voltage [ADC_REFERENCE_INPUT_VBG_DIV_BY_1], half of the band gap [ADC_REFERENCE_INPUT_VBG_DIV_BY_2] or one-sixth voltage band gap [ADC_REFERENCE_INPUT_VBG_DIV_BY_6] can be enabled or disabled through the APIs PLIB_ADC_InternalReferenceChannelEnable and PLIB_ADC_InternalReferenceChannelDisable respectively with appropriate parameters. The same APIs can be used to control the internal core voltage [ADC_REFERENCE_INPUT_VDDCORE] channels. ADC Pairs Initialization: Some ADC modules convert analog inputs in pairs. The analog input pair is a combination of an even and odd numbered analog input, such as AN0 and AN1, AN2, AN3, and so on. The technique of using pairs is particularly useful in power conversion applications that require voltage and current measurement for each PWM control loop. • An interrupt request can be enabled/disabled using the API PLIB_ADC_PairInterruptRequestEnable/PLIB_ADC_PairInterruptRequestDisable • A software trigger can be activated using the API PLIB_ADC_PairConversionStart • Each ADC input pair can select an individual software trigger as a trigger source via the API PLIB_ADC_PairTriggerSourceSelect • Each ADC input pair can select the global software trigger as a trigger source via the API PLIB_ADC_GlobalSoftwareTriggerSet Each analog input uses a dedicated result register to store the converted result. For example, AN0 conversion results are always stored in the ADCBUF0 register and AN1 conversion results are always stored in the ADCBUF1 register. Conversion Result Handling Using DMA: DMA can be enabled or disabled using PLIB_ADC_DMAEnable and PLIB_ADC_DMADisable, respectively. The DMA Buffer Build mode feature controlled through PLIB_ADC_DMABufferModeSelect determines how the conversion results are filled in the DMA RAM buffer area being used for the ADC. With the parameter ADC_DMA_BUFFER_MODE_ORDER_OF_CONV, DMA buffers are written in the order of conversion; otherwise, with ADC_DMA_BUFFER_MODE_SCATTER_GATHER, DMA buffers are written in Scatter/Gather mode. In the Scatter/Gather mode, the DMA channel must be configured for Peripheral Indirect Addressing. The DMA buffer is divided into consecutive memory blocks corresponding to all available analog inputs (out of AN0-AN31). Each conversion result for a particular analog input is automatically transferred by the ADC module to the corresponding block within the user-defined DMA buffer area. Successive samples for the same analog input are stored in sequence within the block assigned to that input. The number of samples that need to be stored in the DMA buffer for each analog input is controlled by 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1369 PLIB_ADC_DMAInputBufferSelect. The rate at which this internal pointer is incremented when data is written to the DMA buffer is controlled by PLIB_ADC_DMAAddressIncrementSelect. 1. Configure the ADC interrupt (if required): • Clear the interrupt status flag • Select the ADC interrupt priority • Enable the ADC interrupt 2. Configure the DMA Channel. 3. Turn on the ADC module using API PLIB_ADC_Enable. Example Initialization: // Include all channels in scan PLIB_ADC_InputScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_SAMPLES_PER_INTERRUPT_16); // Enable scanning of channels PLIB_ADC_ScanMuxAInputEnable(MY_ADC_INSTANCE); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. 5.6.1.4.3.3 Controlling the Sampling Process This topic describes the modes and related sampling functionality for the sampling process. Description The sampling process can be set up using the following two modes: • Manual Sampling: Calling PLIB_ADC_SamplingStart causes the ADC to begin sampling. One of several options as discussed in "Controlling the Conversion Process" can be used to end sampling and complete conversions. Sampling does not resume until PLIB_ADC_SamplingStart is called again. • Automatic Sampling: Setting the ADC in the Auto-Sampling mode using PLIB_ADC_SampleAutoStartEnable automatically begins sampling a channel whenever a conversion is not active on that channel. One of several options can be used to end sampling and complete conversions, as discussed in "Controlling the Conversion Process". If the simultaneous sampling is selected using PLIB_ADC_SamplingModeEnable with parameter ADC_SAMPLING_MODE_SIMULTANEOUS, sampling on a channel resumes after the conversion of all channels completes. Other sampling related functionality: • Monitoring Sample Status: PLIB_ADC_SamplingIsActive obtains the status as sampling or holding for the ADC module. • Aborting a Sample: While in Manual Sampling mode, calling PLIB_ADC_SamplingStop will terminate sampling. If the conversion trigger source is selected as ADC_CONVERSION_TRIGGER_SAMP_CLEAR using PLIB_ADC_ConversionTriggerSourceSelect, this causes a conversion to start automatically. While in Auto-Sampling mode, calling PLIB_ADC_SampleAutoStartEnable does not terminate an outgoing sample/convert sequence; however, sampling will not resume after a subsequent conversion. • Sampling Modes: Different sampling modes can be changed using PLIB_ADC_SamplingModeEnable with the appropriate 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1370 parameter such as ADC_SAMPLING_MODE_ALTERNATE_INPUT for alternate input mode, ADC_SAMPLING_MODE_SIMULTANEOUS for simultaneous sampling mode, or ADC_SAMPLING_MODE_SEQUENTIAL for the sequential sampling mode. There is a possibility to combine the sampling modes say the Alternate input mode with either the simultaneous or the sequential sampling modes. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. 5.6.1.4.3.4 Controlling the Conversion Process The conversion trigger source will terminate sampling and start a selected sequence of conversions. It is also possible to obtain the value of the conversion clock, which is obtained by calling PLIB_ADC_ConversionClockGet. 'PLIB_ADC_ConversionTriggerSourceSelect' selects the source of the conversion trigger. Description Conversion can be started in one of the following three ways: 1. Manual Conversion Sequence: • Manual Sample Start, Manual Conversion Start: When ADC_CONVERSION_TRIGGER_SAMP_CLEAR is selected using PLIB_ADC_ConversionTriggerSourceSelect, the conversion trigger is under software control. Calls to PLIB_ADC_SamplingStop will stop the sampling and start the conversion sequence. The user must call PLIB_ADC_SamplingStart and PLIB_ADC_SamplingStop in a timed manner, to ensure adequate sampling time. Converting One Channel, Manual Sample Start, Manual Conversion Start • Automatic Sample Start, Manual Conversion Start: Automatic sampling is initiated using PLIB_ADC_SampleAutoStartEnable, calling PLIB_ADC_SamplingStop will terminate sampling and start conversion. After the conversion, the sampling starts again automatically. The user must call PLIB_ADC_SamplingStop in a timed manner, to ensure adequate sampling time. Wait for required acquisition/auto sample time (minimum of 1 TAD), and then call PLIB_ADC_SamplingStop to start the conversion process. Converting One Channel, Automatic Sample Start, Manual Conversion Start 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1371 2. Clocked Conversion Sequence: • Manual Sample Start and TAD based Conversion Start: When ADC_CONVERSION_TRIGGER_INTERNAL_COUNT is selected using PLIB_ADC_ConversionTriggerSourceSelect, the conversion trigger is under analog-to-digital clock control. PLIB_ADC_SampleAcqusitionTimeSet selects the TAD clock cycles between the start of sampling and the start of conversion. [Minimum 1 clock cycle has to be selected to ensure the sampling requirements are met]. PLIB_ADC_SamplingStart starts the sampling for the configured acquisition time, and then PLIB_ADC_SamplingStop starts the conversion process. Converting One Channel, Manual Sample Start, TAD-Based Conversion Start • Auto Sample Start and TAD based Conversion Start or Free Running Sample Conversion: With the selection of ADC_CONVERSION_TRIGGER_INTERNAL_COUNT using PLIB_ADC_ConversionTriggerSourceSelect and Automatic sampling initiation using PLIB_ADC_SampleAutoStartEnable allows the ADC module to schedule sample/conversion sequences with no intervention by the user or other device resources. Converting One Channel, Auto-Sample Start, TAD-Based Conversion Start 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1372 3. Event Trigger Conversion Start: It might be necessary to synchronize the end of sampling and the start of conversion with some other time event. The ADC module may use one of following as conversion trigger sequences: • External Pin Trigger: When ADC_CONVERSION_TRIGGER_INT0_TRANSITION is selected using PLIB_ADC_ConversionTriggerSourceSelect • General Purpose Timer Compare Match: When ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH or ADC_CONVERSION_TRIGGER_TMR5_COMPARE_MATCH is selected using PLIB_ADC_ConversionTriggerSourceSelect Both of the event trigger conversion modes previously described can be used in combination with auto-sampling (PLIB_ADC_SampleAutoStartEnable) to cause the ADC to synchronize the sample conversion events to the trigger pulse source. Users should note that some devices have additional conversion trigger sources as part of the enumeration ADC_CONVERSION_TRIGGER_SOURCE. Other operations during Conversion process: • Monitoring Conversion process: The status of the conversion can be obtained using PLIB_ADC_ConversionHasCompleted • Generating ADC Interrupt: PLIB_ADC_SamplesPerInterruptSelect controls the generation of the ADC interrupt. To enable the interrupt it is also essential to enable the ADC interrupt. • Aborting the Conversion: Calling PLIB_ADC_Disable will abort the current conversion. The result buffer is not updated with the partially completed ADC conversion sequence. • ADC pair conversion status can be obtained from PLIB_ADC_PairConversionIsPending Timing Details: • TAD - The ADC module has a maximum rate at which conversions may be completed. An analog module clock, TAD, controls the conversion timing. • TSAMP - The time required to sample and hold the sampled analog signal, configured through PLIB_ADC_SampleAcqusitionTimeSet • TCONV - The time required to convert the sampled analog signal, configured through PLIB_ADC_ConversionClockSet. The conversion clock can be verified using PLIB_ADC_ConversionClockGet. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. 5.6.1.4.3.5 Accessing the Result Buffers The result buffers can be formatted to the desired format using the function PLIB_ADC_ResultFormatSelect. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1373 Description As the analog-to-digital conversions are completed, the ADC module writes the results of the conversions into the ADC result buffer. This buffer is a RAM array of 16 words, accessed through the Special Function Register (SFR) space. User software may attempt to read each ADC conversion result as it is generated; however, this might consume too much CPU time. Generally, to minimize software overhead, the ADC module will fill the buffer with results, and then generate an interrupt when the buffer is filled. There are two different modes for accessing the result buffers. Note: Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet to determine the correct mode for accessing the result buffer for your device. • Single Buffer mode: Conversion results are automatically stored in a dedicated buffer. The module sets its interrupt flag after the conversion is complete, it also marks the conversion status as complete. After the interrupt, the conversion sequence can restart. For 8-bit results, the converted values are available through PLIB_ADC_ResultGet. • Multi Buffer mode: Conversion results are automatically stored in a dedicated position in the result buffer comprising an array of 16 words, allowing for multiple successive readings to be taken before software service is needed. Successive conversions are placed into sequential buffer positions. Alternatively, the buffer can be split into two arrays of 8 words for simultaneous conversion and read operations. The ADC module sets its interrupt flag after a selectable number of conversions, from 1 to 16, when the all buffer positions can be read. After the interrupt, the sequence restarts at the beginning of the buffer. When the interrupt flag is set, scan selections and the output buffer pointer return to their starting positions. The ADC result buffer is a set of 16 words, accessed through PLIB_ADC_ResultGetByIndex , where buffer index can be can be any value ranging from 0 to 15. • PLIB_ADC_SamplesPerInterruptSelect selects how many analog-to-digital conversions will take place before the CPU is interrupted • The buffer fill mode can be selected using PLIB_ADC_ResultBufferModeSelect with the parameter of the type ADC_BUFFER_MODE • When the conversion result buffer is split (ADC_BUFFER_MODE_TWO_8WORD_BUFFERS used as the parameter for PLIB_ADC_ResultBufferModeSelect), PLIB_ADC_ResultBufferIsFull indicates which half of the buffer is being currently written by the ADC module • DMA Buffer mode: The ADC result buffer is a single word register that stores the ADC conversion result. DMA data transfer can be used to to buffer more than one conversion result, before triggering an interrupt. If no DMA is to be used, each result should be read by the user application using PLIB_ADC_ResultGet before it is overwritten by the next conversion. ADC DMA is enabled through PLIB_ADC_DMAEnable. • The DMA buffer build mode selected using PLIB_ADC_DMABufferModeSelect with the parameter of type ADC_DMA_BUFFER_MODE, which determines how the conversion results are filled in the DMA buffer area. If ADC_DMA_BUFFER_MODE_SCATTER_GATHER is selected, the ADC module needs to provide a scatter/gather address to the DMA channel based on the index of the analog input and size of the DMA buffer. If ADC_DMA_BUFFER_MODE_ORDER_OF_CONV is selected, the ADC module provides the address of the non-DMA stand-alone buffer. • PLIB_ADC_DMAInputBufferSelect selects the number of samples that need to be stored in the DMA buffer for each analog input • Miscellaneous: • Output result sign (positive or negative) is available through PLIB_ADC_ResultSignGet • ADC pair sample availability can be checked using PLIB_ADC_PairSampleIsAvailable Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. 5.6.1.4.3.6 Power-Saving Modes This topic provides information on the power-saving modes available for use with the ADC module. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1374 Description Operation in Sleep mode: Operation in Sleep mode requires that the internal RC clock is selected using PLIB_ADC_ConversionClockSourceSelect with the parameter ADC_CLOCK_SOURCE_INTERNAL_RC. If the ADC interrupt is enabled, the device will wake up from Sleep mode on the ADC interrupt. On some microcontrollers, operation in Sleep mode requires that ADC_CONVERSION_CLOCK_FRC is selected using PLIB_ADC_ConversionClockSourceSelect. If the ADC interrupt is enabled, the device will wake up from Sleep mode on the ADC interrupt. Operation in Idle mode: PLIB_ADC_StopInIdleEnable and PLIB_ADC_StopInIdleDisable determine if the ADC module stops or continues operation in Idle mode. If PLIB_ADC_StopInIdleDisable is used, the module will continue operation in Idle mode. If the ADC interrupt is enabled, the device will wake up from Idle mode on the ADC interrupt. If PLIB_ADC_StopInIdleEnable is used, the module will stop in Idle mode. If the device enters Idle mode in the middle of conversion, the conversion is aborted. Operation in other Power-Saving modes: If the ADC module is expected to operate in a power-saving mode, configure the acquisition time and the conversion clock using the functions in accordance with the power-saving mode clock that will be used. After the power-saving mode is entered, an analog-to-digital acquisition can be started. Once the acquisition is started, the device can continue to be clocked by the same power-saving source until the conversion has completed. If desired, the device may be placed in the power-saving Idle mode during conversion. Note: Not all functionality is available on all devices. Refer to the "Analog-to-Digital Converter (ADC)" chapter in the specific device data sheet for availability. 5.6.1.4.3.7 Conversion Sequence Examples This topic provides examples on how the sampling and conversion will occur in various configurations. Description Converting Single Channel, Manual Sample Start, Manual Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; // Enabling the sampling manually PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_SAMP_CLEAR); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Connect AN2 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN2); // Manual Sample and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 2); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); Delay(); // Ensure, correct sampling time has elapsed before starting conversion. // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1375 ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Converting Single Channel, Manual Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Converting Single Channel, Automatic Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; uint8_t index; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000,320000000); // Set the interrupt every 3 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_3SAMPLES_PER_INTERRUPT); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1376 ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 2 ADC values for(index = 0; index < 2; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 1; } // Repeat Converting Single Channel, Automatic Sample Start, Conversion Trigger-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int16_t ADCValue; // General Purpose Timer 3 compare match ends sampling and starts conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSelect(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSelect(MY_ADC_INSTANCE, 1); // Configure the timer to generate period match as per the acquisition requirements TMR3 = 0x0000; // set TMR3 to time out every 125 ms PR3 = 0x3FFF; T3CON = 0x8010; // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); ADCValue += PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } Sampling and Converting a Single Channel Multiple Times // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1377 // from ADC_MODULE_ID int16_t ADCValue; uint8_t index; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 16 ADC value for(index = 0; index < 16; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 4; } // Repeat Sampling and Converting all Channels // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID int ADCValue, index; // Include all channels in scan PLIB_ADC_ScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Set the interrupt every 16 samples PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); // Enable scanning of channels 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1378 PLIB_ADC_ScanMuxAInputEnable(MY_ADC_INSTANCE); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { ADCValue = 0; // Auto Start Sampling and then go to conversion PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); // Yes, stop sample/convert PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); // Average the 16 ADC value for(index = 0; index < 16; index++) { ADCValue = ADCValue + PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, index); } ADCValue = ADCValue >> 4; } // Repeat Wait for Sample, Manual Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Internal Counter triggers conversion PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); // Connect AN12 as Positive Input PLIB_ADC_MuxChannel0InputPositiveSelect(ADC_ID_1, ADC_MUX_A, ADC_INPUT_POSITIVE_AN12); // Disabling ADC Input channels for Scan PLIB_ADC_ScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_ALL); // Sample Time = 31TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 30); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Connect AN12 as Positive Input PLIB_ADC_InputSelectPositive(MY_ADC_INSTANCE, ADC_INPUT_POSITIVE_AN12); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { Delay(); // Ensure, correct sampling time has elapsed before starting conversion. // Start Sampling PLIB_ADC_SamplingStop(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 0); } 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1379 Wait for Sample, Triggered Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Connect AN2 as Positive Input PLIB_ADC_InputSelectPositive(MY_ADC_INSTANCE, ADC_INPUT_POSITIVE_AN2); // Manual Sample and Conversion Clock PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { Delay(); // Ensure, correct sampling time has elapsed PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INT0_TRANSITION); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGet(MY_ADC_INSTANCE); } Manual Sample Start, TAD-based Conversion Start // Where MY_ADC_INSTANCE, is the instance of ADC that the application is using. It is one of the possible values // from ADC_MODULE_ID uint8_t ADCValue; // Connect AN2 as Positive Input PLIB_ADC_InputSelectPositive(MY_ADC_INSTANCE, ADC_INPUT_POSITIVE_AN2); // Sample Time = 1TAD and TAD = 2TCY PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 0); PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); // Enable the ADC PLIB_ADC_Enable(MY_ADC_INSTANCE); while(1) { // Start Sampling PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); // Is Conversion Done ?? while(!PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE)); ADCValue = PLIB_ADC_ResultGet(MY_ADC_INSTANCE); } 5.6.1.5 Configuring the Library The library is configured for the supported ADC modules with the multi-buffer interface when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1380 5.6.1.6 Library Interface Channel Pairs Control Name Description PLIB_ADC_PairConversionIsPending Informs whether conversion is pending or complete. PLIB_ADC_PairConversionStart Start conversion of the requested ADC pair. PLIB_ADC_PairInterruptAfterFirstConversion ADC pair conversion interrupt is generated after the first conversion. PLIB_ADC_PairInterruptAfterSecondConversion ADC pair conversion interrupt is generated after the second conversion. PLIB_ADC_PairInterruptRequestDisable Disable IRQ generation for the ADC pair. PLIB_ADC_PairInterruptRequestEnable Enable IRQ generation for the ADC pair. PLIB_ADC_PairSampleIsAvailable Provides status of the ADC pair sample availability in the buffer. PLIB_ADC_PairSampleStatusClear Clears the ADC pair ready status flag. PLIB_ADC_PairTriggerSourceSelect Selects trigger source for the requested ADC pair. Conversion Control Logic Name Description PLIB_ADC_ConversionStart Starts ADC module manual conversion process. PLIB_ADC_ConversionHasCompleted Provides the conversion completion status of the ADC. PLIB_ADC_ConversionTriggerSourceSelect Selects the conversion trigger source. PLIB_ADC_ConversionStopSequenceEnable Stop conversion sequence (when the first ADC module interrupt is generated). PLIB_ADC_ConversionStopSequenceDisable Normal conversion sequence. PLIB_ADC_ConversionClockSet Sets the ADC module conversion clock. PLIB_ADC_ConversionClockGet Obtains the conversion clock. PLIB_ADC_ConversionClockSourceSelect Selects the ADC module conversion clock source. PLIB_ADC_ConversionTriggerGroupSelect Selects the conversion trigger source group. PLIB_ADC_ConversionOrderSelect Selects the conversion order. Data Types & Constants Name Description ADC_MODULE_ID Identifies the supported ADC modules supported. ADC_VOLTAGE_REFERENCE Data type defining the different ADC Voltage Reference by which the ADC can be configured. ADC_INPUTS_NEGATIVE Data type defining the different ADC Negative Input Enumeration. ADC_SAMPLES_PER_INTERRUPT Data type defining the Samples Per Interrupt Enumeration. ADC_CHANNEL_GROUP Data type defines the ADC Channel Group. ADC_CLOCK_SOURCE Data type defines the ADC Clock Source Select. ADC_CONVERSION_TRIGGER_SOURCE Data type defines the ADC Conversion Trigger Source. ADC_RESULT_SIZE Data type defines the ADC Result Size. ADC_BUFFER_MODE Data type defines the ADC Buffer Mode. ADC_RESULT_BUF_STATUS Data type defines the ADC Result Buffer Status ADC_MUX Data type defining the different ADC MUX Enumeration. ADC_SAMPLING_MODE Data type defines the ADC Sampling Mode Select. ADC_INPUTS_SCAN Data type defines the ADC Scan inputs. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1381 ADC_REFERENCE_INPUT Data type defines the ADC Reference Input Enumeration. ADC_RESULT_FORMAT Data type defines the ADC Result Format. ADC_DMA_BUFFER_MODE Data type defines the ADC Buffer Mode. ADC_PAIR Data type defines the ADC Pair. ADC_CHANNEL123_INPUTS_NEG Data type defines the ADC Channel 123 Negative Input Select. ADC_CHANNEL123_INPUTS_POS Data type defines the ADC Channel 123 Positive Input Select. ADC_INPUTS_POSITIVE Data type defines the ADC inputs. ADC_CONVERSION_ORDER Data type defines the ADC Conversion Order. ADC_DMA_ADDRESS_INCREMENT Data type defines the ADC DMA Increment Rate. ADC_DMA_INPUT_BUFFER Data type defines the ADC DMA Buffer Per Input. ADC_ACQUISITION_TIME Data type defining the different ADC acquisition times by which the ADC can be configured. ADC_CONVERSION_CLOCK Data type defines the different ADC Conversion clock ADC_SAMPLE Data type defining the size of the adc sample register. DMA Transactions Name Description PLIB_ADC_DMAAddressIncrementSelect Selects the increment rate for the DMA address. PLIB_ADC_DMABufferModeSelect DMA Buffer Build mode. PLIB_ADC_DMADisable Disables the ADC Direct Memory Access (DMA). PLIB_ADC_DMAEnable Enables the ADC Direct Memory Access (DMA). PLIB_ADC_DMAInputBufferSelect Selects the number of DMA buffer locations per analog input. Feature Existence Name Description PLIB_ADC_ExistsAsynchronousDedicatedSampling Identifies whether the AsynchronousDedicatedSampling feature exists on the ADC module PLIB_ADC_ExistsCalibrationControl Identifies whether the CalibrationControl feature exists on the ADC module PLIB_ADC_ExistsChannelGroup Identifies whether the ChannelGroup feature exists on the ADC module PLIB_ADC_ExistsConversionClock Identifies whether the ConversionClock feature exists on the ADC module PLIB_ADC_ExistsConversionClockSource Identifies whether the ConversionClockSource feature exists on the ADC module PLIB_ADC_ExistsConversionControl Identifies whether the ConversionControl feature exists on the ADC module PLIB_ADC_ExistsConversionOrder Identifies whether the ConversionOrder feature exists on the ADC module PLIB_ADC_ExistsConversionStatus Identifies whether the ConversionStatus feature exists on the ADC module PLIB_ADC_ExistsConversionStopSequenceControl Identifies whether the ConversionStopSequenceControl feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerGroup Identifies whether the ConversionTriggerGroup feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerSource Identifies whether the ConversionTriggerSource feature exists on the ADC module PLIB_ADC_ExistsDMAAddressIncrement Identifies whether the DMAAddressIncrement feature exists on the ADC module 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1382 PLIB_ADC_ExistsDMABufferMode Identifies whether the DMABufferMode feature exists on the ADC module PLIB_ADC_ExistsDMABuffersPerAnalogInput Identifies whether the DMABuffersPerInput feature exists on the ADC module PLIB_ADC_ExistsDMAControl Identifies whether the DMAControl feature exists on the ADC module PLIB_ADC_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADC module. PLIB_ADC_ExistsGlobalSoftwareTrigger Identifies whether the GlobalSoftwareTrigger feature exists on the ADC module PLIB_ADC_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADC module PLIB_ADC_ExistsInternalReferenceChannelControl Identifies whether the InternalReferenceChannelControl feature exists on the ADC module PLIB_ADC_ExistsISRJumpTableBaseAddress Identifies whether the ISRJumpTableBaseAddress feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0NegativeInput Identifies whether the MuxChannel0NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0PositiveInput Identifies whether the MuxChannel0PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel123NegativeInput Identifies whether the MuxChannel123NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel123PositiveInput Identifies whether the MuxChannel123PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanControl Identifies whether the MuxInputScanControl feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelect Identifies whether the MuxInputScanSelect feature exists on the ADC module PLIB_ADC_ExistsPairConversionControl Identifies whether the PairConversionControl feature exists on the ADC module PLIB_ADC_ExistsPairInterruptOnConversion Identifies whether the PairInterruptOnConversion feature exists on the ADC module PLIB_ADC_ExistsPairInterruptRequest Identifies whether the PairInterruptRequest feature exists on the ADC module PLIB_ADC_ExistsPairSampleStatus Identifies whether the PairSampleStatus feature exists on the ADC module PLIB_ADC_ExistsPairTriggerSource Identifies whether the PairTriggerSource feature exists on the ADC module PLIB_ADC_ExistsResultBufferFillStatus Identifies whether the ResultBufferFillStatus feature exists on the ADC module PLIB_ADC_ExistsResultBufferMode Identifies whether the ResultBufferMode feature exists on the ADC module PLIB_ADC_ExistsResultFormat Identifies whether the ResultFormat feature exists on the ADC module PLIB_ADC_ExistsResultGet Identifies whether the ResultGet feature exists on the ADC module PLIB_ADC_ExistsResultGetByIndex Identifies whether the ResultGetByIndex feature exists on the ADC module PLIB_ADC_ExistsResultSign Identifies whether the ResultSign feature exists on the ADC module PLIB_ADC_ExistsResultSize Identifies whether the ResultSize feature exists on the ADC module 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1383 PLIB_ADC_ExistsSampleResolution Identifies whether the SampleResolution feature exists on the ADC module PLIB_ADC_ExistsSamplesPerInterruptSelect Identifies whether the SamplesPerInterruptSelect feature exists on the ADC module PLIB_ADC_ExistsSamplingAcquisitionTime Identifies whether the SamplingAcquisitionTime feature exists on the ADC module PLIB_ADC_ExistsSamplingAutoStart Identifies whether the SamplingAutoStart feature exists on the ADC module PLIB_ADC_ExistsSamplingControl Identifies whether the SamplingControl feature exists on the ADC module PLIB_ADC_ExistsSamplingModeControl Identifies whether the SamplingModeControl feature exists on the ADC module PLIB_ADC_ExistsSamplingStatus Identifies whether the SamplingStatus feature exists on the ADC module PLIB_ADC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the ADC module PLIB_ADC_ExistsVoltageReference Identifies whether the VoltageReference feature exists on the ADC module General Configuration Name Description PLIB_ADC_Enable ADC module is enabled (turned ON). PLIB_ADC_Disable ADC module is disabled (turned OFF). PLIB_ADC_StopInIdleDisable Continue ADC module operation when the device is in Idle mode. PLIB_ADC_StopInIdleEnable Discontinue ADC module operation when device enters Idle mode. PLIB_ADC_VoltageReferenceSelect Voltage reference configuration. PLIB_ADC_CalibrationEnable Calibration is performed on the next ADC conversion. PLIB_ADC_CalibrationDisable Normal ADC module operation (no calibration is performed). PLIB_ADC_InputSelectPositive Positive analog input channel selection. PLIB_ADC_InputSelectNegative Analog negative channel selection. PLIB_ADC_InputScanMaskAdd Select ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemove Omits ADC analog channel for input scan. PLIB_ADC_InternalReferenceChannelEnable Internal reference input is enabled. PLIB_ADC_InternalReferenceChannelDisable Internal reference input is disabled. PLIB_ADC_ChannelGroupSelect Selects channels to be utilized. Miscellaneous Name Description PLIB_ADC_AsynchronousDedicatedSamplingDisable Disables asynchronous dedicated S&H sampling. PLIB_ADC_AsynchronousDedicatedSamplingEnable Enables asynchronous dedicated S&H sampling. PLIB_ADC_GlobalSoftwareTriggerSet Global software trigger enable/set control. PLIB_ADC_IsrJumpTableBaseAddressGet Gets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. PLIB_ADC_IsrJumpTableBaseAddressSet Sets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. Mux Selection and Channel Scan Name Description PLIB_ADC_MuxAInputScanDisable Do not scan input selections for CH0+ of MUX A. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1384 PLIB_ADC_MuxAInputScanEnable Scan input selections for CH0+ of MUX A. PLIB_ADC_MuxChannel0InputNegativeSelect Channel 0 negative input select for multiplexer setting. PLIB_ADC_MuxChannel0InputPositiveSelect Channel 0 positive input select for multiplexer setting. PLIB_ADC_MuxChannel123InputNegativeSelect Channel 1, 2, and 3 negative input select. PLIB_ADC_MuxChannel123InputPositiveSelect Channel 1, 2, and 3 positive input select. Output Configuration Name Description PLIB_ADC_ResultBufferModeSelect Selects the result buffer mode. PLIB_ADC_ResultBufferStatusGet Provides the buffer fill status. PLIB_ADC_ResultFormatSelect Selects the result format. PLIB_ADC_ResultGet Obtains the ADC sample/result value. PLIB_ADC_ResultGetByIndex Provides the ADC conversion result based on the buffer index. PLIB_ADC_ResultSignGet Obtains the ADC result sign. PLIB_ADC_ResultSizeSelect Selects the ADC module mode/result size. Sample and Hold Control Logic Name Description PLIB_ADC_SampleAcqusitionTimeSet Sets the ADC acquisition/auto-sample time in TADs. PLIB_ADC_SampleAutoStartDisable Sampling auto-start is disabled. PLIB_ADC_SampleAutoStartEnable Sampling auto-start is enabled. PLIB_ADC_SampleMaxGet Provides the maximum sample value. PLIB_ADC_SampleMinGet Provides the minimum sample value. PLIB_ADC_SamplesPerInterruptSelect Interrupts at the completion of conversion for each nth sample. PLIB_ADC_SamplingIsActive Provides the ADC sampling status. PLIB_ADC_SamplingModeSelect Enable the selected sampling mode. PLIB_ADC_SamplingStart Sampling is enabled. PLIB_ADC_SamplingStop Holding is enabled. Description This section lists the interface routines, data types, constants and macros required for ADC library. 5.6.1.6.1 General Configuration 5.6.1.6.1.1 PLIB_ADC_Enable Function C void PLIB_ADC_Enable( ADC_MODULE_ID index ); Description This function enables (turns ON) the selected ADC module. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1385 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_Enable(MY_ADC_INSTANCE); 5.6.1.6.1.2 PLIB_ADC_Disable Function C void PLIB_ADC_Disable( ADC_MODULE_ID index ); Description This function disables (turns OFF) the selected ADC module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_Disable(MY_ADC_INSTANCE); 5.6.1.6.1.3 PLIB_ADC_StopInIdleDisable Function C void PLIB_ADC_StopInIdleDisable( ADC_MODULE_ID index ); Description This function enables the ADC module to continue operation when the device is in Idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1386 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsStopInIdleControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_StopInIdleDisable(MY_ADC_INSTANCE); 5.6.1.6.1.4 PLIB_ADC_StopInIdleEnable Function C void PLIB_ADC_StopInIdleEnable( ADC_MODULE_ID index ); Description This function discontinues ADC module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsStopInIdleControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_StopInIdleEnable(MY_ADC_INSTANCE); 5.6.1.6.1.5 PLIB_ADC_VoltageReferenceSelect Function C void PLIB_ADC_VoltageReferenceSelect( ADC_MODULE_ID index, ADC_VOLTAGE_REFERENCE configValue ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1387 Description This function configures the ADC module voltage reference. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured configValue One of the possible values from ADC_VOLTAGE_REFERENCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsVoltageReference in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_VoltageReferenceSelect(MY_ADC_INSTANCE, ADC_REFERENCE_VREFPLUS_TO_AVSS); 5.6.1.6.1.6 PLIB_ADC_CalibrationEnable Function C void PLIB_ADC_CalibrationEnable( ADC_MODULE_ID index ); Description This function enables calibration to be performed on the next ADC conversion. When the Calibration bit is enabled, inputs are disconnected and tied to AVss. This sets the inputs of the ADC to zero. Then, the user can perform a conversion. Use of the Calibration mode is not affected if the ADC line has been configured as analog or digital, nor by channel input selection. Any analog input switches are disconnected from the ADC module in this mode. The conversion result is stored by the user software and is used to compensate subsequent conversions. This can be done by adding the two’s complement of the result obtained during calibration to all normal ADC conversions. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsCalibrationControl in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1388 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_CalibrationEnable(MY_ADC_INSTANCE); 5.6.1.6.1.7 PLIB_ADC_CalibrationDisable Function C void PLIB_ADC_CalibrationDisable( ADC_MODULE_ID index ); Description This function enables normal ADC module operation without any calibration. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsCalibrationControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_CalibrationDisable(MY_ADC_INSTANCE); 5.6.1.6.1.8 PLIB_ADC_InputSelectPositive Function C void PLIB_ADC_InputSelectPositive( ADC_MODULE_ID index, ADC_INPUTS_POSITIVE inputs ); Description This function selects the positive analog input channel for the ADC module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1389 Remarks Valid for ADC modules without MUX A, MUX B, etc. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsInputSelect in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_InputSelectPositive(MY_ADC_INSTANCE, ADC_INPUT_POSITIVE_AN2); 5.6.1.6.1.9 PLIB_ADC_InputSelectNegative Function C void PLIB_ADC_InputSelectNegative( ADC_MODULE_ID index, ADC_INPUTS_NEGATIVE negInput ); Description This function selects a negative channel for the ADC module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured negInput One of the possible values from ADC_INPUTS_NEGATIVE Returns None. Remarks Valid for ADC modules without MUX A, MUX B, etc. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsInputSelect in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_InputSelectNegative(MY_ADC_INSTANCE, ADC_INPUT_NEGATIVE_VREF_MINUS); 5.6.1.6.1.10 PLIB_ADC_InputScanMaskAdd Function C void PLIB_ADC_InputScanMaskAdd( ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs ); Description This function selects the ADC analog channel for input scanning. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1390 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN. Inputs are added for scanning. Returns None. Remarks Multiple channels can be added simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelect in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // Single channel addition PLIB_ADC_InputScanMaskAdd(MY_ADC_INSTANCE, ADC_INPUT_SCAN_AN2); // Multiple channels addition PLIB_ADC_InputScanMaskAdd(ADC_ID_1, ADC_INPUT_SCAN_AN2 | ADC_INPUT_SCAN_AN2); 5.6.1.6.1.11 PLIB_ADC_InputScanMaskRemove Function C void PLIB_ADC_InputScanMaskRemove( ADC_MODULE_ID index, ADC_INPUTS_SCAN scanInputs ); Description This function allows the ADC analog channel to be omitted from input scanning. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured scanInputs One of the possible values from ADC_INPUTS_SCAN. Inputs are removed from scanning. Returns None. Remarks Multiple channels can be removed simultaneously by ORing. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanSelect in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1391 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // Single channel addition PLIB_ADC_InputScanMaskRemove(MY_ADC_INSTANCE, ADC_INPUT_SCAN_AN2); // Multiple channels addition PLIB_ADC_InputScanMaskRemove(ADC_ID_1, ADC_INPUT_SCAN_AN2 | ADC_INPUT_SCAN_AN3); 5.6.1.6.1.12 PLIB_ADC_InternalReferenceChannelEnable Function C void PLIB_ADC_InternalReferenceChannelEnable( ADC_MODULE_ID index, ADC_REFERENCE_INPUT input ); Description This function enables the internal reference input. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Internal reference can be the band gap or core/regulator output voltage channels. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsInternalReferenceChannelControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_InternalReferenceChannelEnable(MY_ADC_INSTANCE, ADC_REFERENCE_INPUT_VBG_DIV_BY_1); 5.6.1.6.1.13 PLIB_ADC_InternalReferenceChannelDisable Function C void PLIB_ADC_InternalReferenceChannelDisable( ADC_MODULE_ID index, ADC_REFERENCE_INPUT input ); Description This function disables the internal reference input. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1392 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Internal reference can be the band gap or core/regulator output voltage channels. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsInternalReferenceChannelControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_InternalReferenceChannelDisable(MY_ADC_INSTANCE, ADC_REFERENCE_INPUT_VBG_DIV_BY_1); 5.6.1.6.1.14 PLIB_ADC_ChannelGroupSelect Function C void PLIB_ADC_ChannelGroupSelect( ADC_MODULE_ID index, ADC_CHANNEL_GROUP chlGroup ); Description This function selects the channels to be utilized by the ADC module. Preconditions Automatic sampling must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured chlGroup One of the possible values from ADC_CHANNEL_GROUP Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsChannelGroup in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ChannelGroupSelect(MY_ADC_INSTANCE, ADC_CHANNEL_GROUP_CH0_CH1); 5.6.1.6.2 Sample and Hold Control Logic 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1393 5.6.1.6.2.1 PLIB_ADC_SampleAcqusitionTimeSet Function C void PLIB_ADC_SampleAcqusitionTimeSet( ADC_MODULE_ID index, ADC_ACQUISITION_TIME acqTime ); Description This function sets the ADC acquisition/auto-sample time in TADs. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured acqTime Unsigned value of type ADC_ACQUISITION_TIME Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAcquisitionTime in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAcqusitionTimeSet(MY_ADC_INSTANCE, 2); 5.6.1.6.2.2 PLIB_ADC_SampleAutoStartDisable Function C void PLIB_ADC_SampleAutoStartDisable( ADC_MODULE_ID index ); Description This function disables auto-sampling and enables manual sampling. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAutoStart in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1394 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAutoStartDisable(MY_ADC_INSTANCE); 5.6.1.6.2.3 PLIB_ADC_SampleAutoStartEnable Function C void PLIB_ADC_SampleAutoStartEnable( ADC_MODULE_ID index ); Description This function enables auto-sampling. Sampling begins immediately after the last conversion is completed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingAutoStart in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SampleAutoStartEnable(MY_ADC_INSTANCE); 5.6.1.6.2.4 PLIB_ADC_SampleMaxGet Function C ADC_SAMPLE PLIB_ADC_SampleMaxGet( ADC_MODULE_ID index ); Description This function provides the maximum sample value based on the supported ADC resolution. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns ADC_SAMPLE - ADC Sample 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1395 Remarks Possible maximum value that can be obtained from the converted value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSampleResolution in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_SAMPLE maxSample = PLIB_ADC_SampleMaxGet(MY_ADC_INSTANCE); 5.6.1.6.2.5 PLIB_ADC_SampleMinGet Function C ADC_SAMPLE PLIB_ADC_SampleMinGet( ADC_MODULE_ID index ); Description This function provides the minimum sample value based on the supported ADC resolution. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns ADC_SAMPLE - ADC sample Remarks Possible minimum value that can be obtained from the converted value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSampleResolution in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_SAMPLE maxSample = PLIB_ADC_SampleMinGet(MY_ADC_INSTANCE); 5.6.1.6.2.6 PLIB_ADC_SamplesPerInterruptSelect Function C void PLIB_ADC_SamplesPerInterruptSelect( ADC_MODULE_ID index, ADC_SAMPLES_PER_INTERRUPT value ); Description This function interrupts at the completion of conversion for each nth sample/convert sequence. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1396 Parameters Parameters Description index Identifier for the device instance to be configured value Possible values from ADC_SAMPLES_PER_INTERRUPT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplesPerInterruptSelect in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplesPerInterruptSelect(MY_ADC_INSTANCE, ADC_16SAMPLES_PER_INTERRUPT); 5.6.1.6.2.7 PLIB_ADC_SamplingIsActive Function C bool PLIB_ADC_SamplingIsActive( ADC_MODULE_ID index ); Description This function returns the ADC sampling status on whether the ADC is sampling or holding. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns bool - true = ADC S&H circuit is sampling • false = ADC S&H circuit is holding Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingStatus in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status = PLIB_ADC_SamplingIsActive(MY_ADC_INSTANCE); 5.6.1.6.2.8 PLIB_ADC_SamplingModeSelect Function C void PLIB_ADC_SamplingModeSelect( ADC_MODULE_ID index, ADC_SAMPLING_MODE mode ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1397 Description This function selects the sampling mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode One of the possible values from ADC_SAMPLING_MODE Returns None. Remarks Sampling mode could be alternate input or Simultaneous or Sequential mode. Alternate input can be combined with Simultaneous or Sequential modes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingModeControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplingModeSelect(MY_ADC_INSTANCE, ADC_SAMPLING_MODE_ALTERNATE_INPUT); 5.6.1.6.2.9 PLIB_ADC_SamplingStart Function C void PLIB_ADC_SamplingStart( ADC_MODULE_ID index ); Description This function starts the ADC Sample and Hold (S&H) circuit to sample the input channel. Preconditions Automatic sampling must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplingStart(MY_ADC_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1398 5.6.1.6.2.10 PLIB_ADC_SamplingStop Function C void PLIB_ADC_SamplingStop( ADC_MODULE_ID index ); Description This function stops the ADC S&H circuit from sampling and holds the sampled data. Preconditions Automatic sampling must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsSamplingControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_SamplingStop(MY_ADC_INSTANCE); 5.6.1.6.3 Conversion Control Logic 5.6.1.6.3.1 PLIB_ADC_ConversionStart Function C void PLIB_ADC_ConversionStart( ADC_MODULE_ID index ); Description This function starts the ADC module manual conversion process. Preconditions Automatic sampling must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1399 PLIB_ADC_ExistsConversionControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStart(MY_ADC_INSTANCE); 5.6.1.6.3.2 PLIB_ADC_ConversionHasCompleted Function C bool PLIB_ADC_ConversionHasCompleted( ADC_MODULE_ID index ); Description This function provides the completion status of analog-to-digital conversion. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns bool - true = ADC conversion is done/completed • false = ADC conversion is in progress or has not started Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStatus in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status = PLIB_ADC_ConversionHasCompleted(MY_ADC_INSTANCE); 5.6.1.6.3.3 PLIB_ADC_ConversionTriggerSourceSelect Function C void PLIB_ADC_ConversionTriggerSourceSelect( ADC_MODULE_ID index, ADC_CONVERSION_TRIGGER_SOURCE source ); Description This function selects the ADC module conversion trigger source. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values from ADC_CONVERSION_TRIGGER_SOURCE 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1400 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionTriggerSource in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionTriggerSourceSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT); 5.6.1.6.3.4 PLIB_ADC_ConversionStopSequenceEnable Function C void PLIB_ADC_ConversionStopSequenceEnable( ADC_MODULE_ID index ); Description This function stops conversions when the first ADC module interrupt is generated. Hardware clears the Automatic Sampling bit when the ADC interrupt is generated. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStopSequenceControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStopSequenceEnable(MY_ADC_INSTANCE); 5.6.1.6.3.5 PLIB_ADC_ConversionStopSequenceDisable Function C void PLIB_ADC_ConversionStopSequenceDisable( ADC_MODULE_ID index ); Description This function enables normal operation, wherein the buffer contents will be overwritten by the next conversion sequence. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1401 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionStopSequenceControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionStopSequenceDisable(MY_ADC_INSTANCE); 5.6.1.6.3.6 PLIB_ADC_ConversionClockSet Function C void PLIB_ADC_ConversionClockSet( ADC_MODULE_ID index, uint32_t baseFrequency, ADC_CONVERSION_CLOCK value ); Description This function sets the ADC module conversion clock prescaler. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured value Unsigned value of type ADC_CONVERSION_CLOCK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClock in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionClockSet(MY_ADC_INSTANCE, 80000000, 320000000); 5.6.1.6.3.7 PLIB_ADC_ConversionClockGet Function C ADC_CONVERSION_CLOCK PLIB_ADC_ConversionClockGet( ADC_MODULE_ID index, uint32_t baseFrequency ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1402 Description This function obtains the conversion clock that is being used by the ADC module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured baseFrequencyHz Input clock frequency to the ADC module in Hz Returns uint32_t - Conversion clock value Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClock in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. // baseFrequency is the peripheral input frequency ADC_CONVERSION_CLOCK conversionClock; // To store the conversion clock value conversionClock = PLIB_ADC_ConversionClockGet(MY_ADC_INSTANCE, 8000000); 5.6.1.6.3.8 PLIB_ADC_ConversionClockSourceSelect Function C void PLIB_ADC_ConversionClockSourceSelect( ADC_MODULE_ID index, ADC_CLOCK_SOURCE source ); Description This function selects the ADC module conversion clock source. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values from ADC_CLOCK_SOURCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionClockSource in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionClockSourceSelect(MY_ADC_INSTANCE, ADC_CLOCK_SOURCE_SYSTEM_CLOCK); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1403 5.6.1.6.3.9 PLIB_ADC_ConversionTriggerGroupSelect Function C void PLIB_ADC_ConversionTriggerGroupSelect( ADC_MODULE_ID index, ADC_CONVERSION_TRIGGER_GROUP group ); Description This function selects the ADC module conversion trigger source group. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured group One of the possible values from ADC_CONVERSION_TRIGGER_GROUP Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsConversionTriggerGroup in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionTriggerGroupSelect(MY_ADC_INSTANCE, ADC_CONVERSION_TRIGGER_GROUP_SEL); 5.6.1.6.3.10 PLIB_ADC_ConversionOrderSelect Function C void PLIB_ADC_ConversionOrderSelect( ADC_MODULE_ID index, ADC_CONVERSION_ORDER order ); Description This function selects the conversion order of the analog input. Preconditions The ADC module must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured order One of the possible values from ADC_CONVERSION_ORDER Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1404 PLIB_ADC_ExistsConversionOrder in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ConversionOrderSelect(MY_ADC_INSTANCE, ADC_CONVERSION_ORDER_ODD_FIRST); 5.6.1.6.4 DMA Transactions 5.6.1.6.4.1 PLIB_ADC_DMAAddressIncrementSelect Function C void PLIB_ADC_DMAAddressIncrementSelect( ADC_MODULE_ID index, ADC_DMA_ADDRESS_INCREMENT incRate ); Description This function selects the increment rate of the DMA address after completion of incRate number of sample/conversion operations. This gives information on how often the DMA RAM buffer pointer is incremented. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured incRate One of the possible values from ADC_DMA_ADDRESS_INCREMENT Returns None. Remarks These represent the same set of bits as does the samples per interrupt selection. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsDMAAddressIncrement in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_DMAAddressIncrementSelect(MY_ADC_INSTANCE, ADC_DMA_ADDRESS_INCREMENT_EVERY_SAMPLE); 5.6.1.6.4.2 PLIB_ADC_DMABufferModeSelect Function C void PLIB_ADC_DMABufferModeSelect( ADC_MODULE_ID index, ADC_DMA_BUFFER_MODE bufferMode ); Description This function selects the DMA Buffer Build mode regardless of the DMA buffers being written in the order of conversion or in scatter/gather mode. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1405 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured bufferMode One of the possible values from ADC_DMA_BUFFER_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsDMABufferMode in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_DMABufferModeSelect(MY_ADC_INSTANCE, ADC_DMA_BUFFER_MODE_ORDER_OF_CONV); 5.6.1.6.4.3 PLIB_ADC_DMADisable Function C void PLIB_ADC_DMADisable( ADC_MODULE_ID index ); Description This function disables the ADC Direct Memory Access (DMA). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Conversion results are stored in multiple buffers and the DMA will not be used. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsDMAControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_DMADisable(MY_ADC_INSTANCE); 5.6.1.6.4.4 PLIB_ADC_DMAEnable Function C void PLIB_ADC_DMAEnable( 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1406 ADC_MODULE_ID index ); Description This function enables the ADC Direct Memory Access (DMA). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Conversion results are stored in a single register and are transfered to RAM using DMA. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsDMAControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_DMAEnable(MY_ADC_INSTANCE); 5.6.1.6.4.5 PLIB_ADC_DMAInputBufferSelect Function C void PLIB_ADC_DMAInputBufferSelect( ADC_MODULE_ID index, ADC_DMA_INPUT_BUFFER buffer ); Description This function selects the number of DMA buffer locations per analog input and specifies the number of samples that need to be stored in the DMA buffer for each analog input. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured buffer One of the possible values from ADC_DMA_INPUT_BUFFER Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsDMABuffersPerAnalogInput in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1407 // application developer. PLIB_ADC_DMAInputBufferSelect(MY_ADC_INSTANCE, ADC_DMA_INPUT_BUFFER_1WORD); 5.6.1.6.5 Channel Pairs Control 5.6.1.6.5.1 PLIB_ADC_PairConversionIsPending Function C bool PLIB_ADC_PairConversionIsPending( ADC_MODULE_ID index, ADC_PAIR pairNum ); Description This function provides information on whether the conversion is pending or complete for the ADC pair. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum One of the possible values from ADC_PAIR Returns bool - true = Conversion of a pair of channels is pending. Set when selected trigger is asserted • false = Conversion is complete Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairConversionControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status = PLIB_ADC_PairConversionIsPending(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.2 PLIB_ADC_PairConversionStart Function C void PLIB_ADC_PairConversionStart( ADC_MODULE_ID index, ADC_PAIR pairNum ); Description This function starts conversion of the requested ADC pair. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1408 pairNum One of the possible values from ADC_PAIR Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairConversionControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairConversionStart(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.3 PLIB_ADC_PairInterruptAfterFirstConversion Function C void PLIB_ADC_PairInterruptAfterFirstConversion( ADC_MODULE_ID index ); Description This function generates an interrupt after the first conversion is completed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairInterruptOnConversion in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairInterruptAfterFirstConversion(MY_ADC_INSTANCE); 5.6.1.6.5.4 PLIB_ADC_PairInterruptAfterSecondConversion Function C void PLIB_ADC_PairInterruptAfterSecondConversion( ADC_MODULE_ID index ); Description This function generates an interrupt after the second conversion is completed. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1409 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairInterruptOnConversion in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairInterruptAfterSecondConversion(MY_ADC_INSTANCE); 5.6.1.6.5.5 PLIB_ADC_PairInterruptRequestDisable Function C void PLIB_ADC_PairInterruptRequestDisable( ADC_MODULE_ID index, ADC_PAIR pairNum ); Description This function disables IRQ generation for the requested ADC pair. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum One of the possible values from ADC_PAIR Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairInterruptRequest in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairInterruptRequestDisable(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.6 PLIB_ADC_PairInterruptRequestEnable Function C void PLIB_ADC_PairInterruptRequestEnable( ADC_MODULE_ID index, ADC_PAIR pairNum ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1410 Description This function enables IRQ generation, when requested conversion of channels associated with the pair is completed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum one of the possible values from ADC_PAIR Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairInterruptRequest in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairInterruptRequestEnable(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.7 PLIB_ADC_PairSampleIsAvailable Function C bool PLIB_ADC_PairSampleIsAvailable( ADC_MODULE_ID index, ADC_PAIR pairNum ); Description This function provides information on whether the samples for the ADC pair selected are available in the buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum One of the possible values from ADC_PAIR Returns bool - true = Data is ready in buffer • false = Data is not ready Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairSampleStatus in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_status; 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1411 my_status = PLIB_ADC_PairSampleIsAvailable(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.8 PLIB_ADC_PairSampleStatusClear Function C void PLIB_ADC_PairSampleStatusClear( ADC_MODULE_ID index, ADC_PAIR pairNum ); Description This function clears a pair conversion ready status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum One of the possible values from ADC_PAIR Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairSampleStatus in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairSampleStatusClear(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1); 5.6.1.6.5.9 PLIB_ADC_PairTriggerSourceSelect Function C void PLIB_ADC_PairTriggerSourceSelect( ADC_MODULE_ID index, ADC_PAIR pairNum, ADC_CONVERSION_TRIGGER_SOURCE trigSrc ); Description This function selects the trigger source for the requested ADC pair. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pairNum One of the possible values from ADC_PAIR Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1412 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsPairTriggerSource in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_PairTriggerSourceSelect(MY_ADC_INSTANCE, ADC_PAIR_AN0_AN1, ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH); 5.6.1.6.6 Output Configuration 5.6.1.6.6.1 PLIB_ADC_ResultBufferModeSelect Function C void PLIB_ADC_ResultBufferModeSelect( ADC_MODULE_ID index, ADC_BUFFER_MODE mode ); Description This function selects the result buffer mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode One of the possible values from ADC_BUFFER_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultBufferMode in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ResultBufferModeSelect(MY_ADC_INSTANCE, ADC_BUFFER_MODE_TWO_8WORD_BUFFERS); 5.6.1.6.6.2 PLIB_ADC_ResultBufferStatusGet Function C ADC_RESULT_BUF_STATUS PLIB_ADC_ResultBufferStatusGet( ADC_MODULE_ID index ); Description This function obtains the buffer fill status. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1413 Preconditions ADC multi-buffer support is available and configured. Parameters Parameters Description index Identifier for the device instance to be configured Returns bool - true = ADC is currently filling buffer 08-0F, user should access data in 00-07 • false = ADC is currently filling buffer 00-07, user should access data in 08-0F Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultBufferFillStatus in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_RESULT_BUF_STATUS my_status; my_status = PLIB_ADC_ResultBufferStatusGet(MY_ADC_INSTANCE); 5.6.1.6.6.3 PLIB_ADC_ResultFormatSelect Function C void PLIB_ADC_ResultFormatSelect( ADC_MODULE_ID index, ADC_RESULT_FORMAT resultFormat ); Description This function selects the result format. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured resultFormat One of the possible values from ADC_RESULT_FORMAT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultFormat in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ResultFormatSelect(MY_ADC_INSTANCE, ADC_RESULT_FORMAT_INTEGER_16BIT); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1414 5.6.1.6.6.4 PLIB_ADC_ResultGet Function C ADC_SAMPLE PLIB_ADC_ResultGet( ADC_MODULE_ID index ); Description This function obtains the ADC sample/result value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns ADC_SAMPLE - Right-/Left-justified ADC result Remarks Only applicable for 10-bit or 12-bit ADC outputs. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultGet in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_SAMPLE my_res; my_res = PLIB_ADC_ResultGet(MY_ADC_INSTANCE); 5.6.1.6.6.5 PLIB_ADC_ResultGetByIndex Function C ADC_SAMPLE PLIB_ADC_ResultGetByIndex( ADC_MODULE_ID index, uint8_t bufferIndex ); Description This function provides the ADC module conversion result based on the buffer index. Preconditions ADC multi-buffer support available and configured. Parameters Parameters Description index Identifier for the device instance to be configured bufferIndex Value ranging from 0 to 15 Returns int16_t - ADC Conversion result at the respective bufferIndex 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1415 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultGetByIndex in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. ADC_SAMPLE my_res = PLIB_ADC_ResultGetByIndex(MY_ADC_INSTANCE, 15); 5.6.1.6.6.6 PLIB_ADC_ResultSignGet Function C bool PLIB_ADC_ResultSignGet( ADC_MODULE_ID index ); Description This function obtains the ADC result sign status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns bool - true = ADC result is negative • false = ADC result is positive Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultSign in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. bool my_sign = PLIB_ADC_ResultSignGet(MY_ADC_INSTANCE); 5.6.1.6.6.7 PLIB_ADC_ResultSizeSelect Function C void PLIB_ADC_ResultSizeSelect( ADC_MODULE_ID index, ADC_RESULT_SIZE resSize ); Description This function selects the ADC module mode/result size. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1416 Parameters Parameters Description index Identifier for the device instance to be configured resSize One of the possible values from ADC_RESULT_SIZE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsResultSize in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_ResultSizeSelect(MY_ADC_INSTANCE, ADC_RESULT_SIZE_10_BITS); 5.6.1.6.7 Miscellaneous 5.6.1.6.7.1 PLIB_ADC_AsynchronousDedicatedSamplingDisable Function C void PLIB_ADC_AsynchronousDedicatedSamplingDisable( ADC_MODULE_ID index ); Description This function disables constant sampling, and starts sampling when the trigger event is detected and completes the sampling process in two ADC clock cycles. Preconditions The ADC module must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsAsynchronousDedicatedSampling in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_AsynchronousDedicatedSamplingDisable(MY_ADC_INSTANCE); 5.6.1.6.7.2 PLIB_ADC_AsynchronousDedicatedSamplingEnable Function C void PLIB_ADC_AsynchronousDedicatedSamplingEnable( 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1417 ADC_MODULE_ID index ); Description This function enables constant sampling of the dedicated S&H, and then terminates sampling as soon as the trigger pulse is detected. Preconditions The ADC module must be disabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsAsynchronousDedicatedSampling in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_AsynchronousDedicatedSamplingEnable(MY_ADC_INSTANCE); 5.6.1.6.7.3 PLIB_ADC_GlobalSoftwareTriggerSet Function C void PLIB_ADC_GlobalSoftwareTriggerSet( ADC_MODULE_ID index ); Description This function enables/sets the global software trigger. It will trigger conversions based on the trigger sources selected. Preconditions Global software trigger has to be cleared before setting back. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature/bit is automatically cleared by hardware. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsGlobalSoftwareTrigger in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_GlobalSoftwareTriggerSet(MY_ADC_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1418 5.6.1.6.7.4 PLIB_ADC_IsrJumpTableBaseAddressGet Function C int PLIB_ADC_IsrJumpTableBaseAddressGet( ADC_MODULE_ID index ); Description This function gets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns baseAddr - Upper 15 bits of the user's ADC ISR jump table address (bit 0 is a don't care) Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsISRJumpTableBaseAddress in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. unsigned int add; add = PLIB_ADC_IsrJumpTableBaseAddressGet(MY_ADC_INSTANCE); 5.6.1.6.7.5 PLIB_ADC_IsrJumpTableBaseAddressSet Function C void PLIB_ADC_IsrJumpTableBaseAddressSet( ADC_MODULE_ID index, int baseAddr ); Description This function sets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured baseAddr Upper 15 bits of the user's ADC ISR jump table address (bit 0 is a don't care) Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsISRJumpTableBaseAddress in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1419 Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_IsrJumpTableBaseAddressSet(MY_ADC_INSTANCE, 0x1000); 5.6.1.6.8 Data Types & Constants 5.6.1.6.8.1 ADC_MODULE_ID Enumeration C typedef enum { ADC_ID_1, ADC_ID_2, ADC_ID_3, ADC_ID_4, ADC_ID_5, ADC_NUMBER_OF_MODULES } ADC_MODULE_ID; Description ADC Module ID This enumeration identifies the available ADC modules. Members Members Description ADC_ID_1 ADC Module 1 ID ADC_ID_2 ADC Module 2 ID ADC_ID_3 ADC Module 3 ID ADC_ID_4 ADC Module 4 ID ADC_ID_5 ADC Module 5 ID ADC_NUMBER_OF_MODULES Number of available ADC modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules are available on all devices. Refer to the specific data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. 5.6.1.6.8.2 ADC_VOLTAGE_REFERENCE Enumeration C typedef enum { ADC_VREF_POS_TO_VDD, ADC_VREF_POS_TO_VREF_PLUS, ADC_VREF_NEG_TO_VSS, ADC_VREF_NEG_TO_VREF_MINUS, ADC_REFERENCE_VDD_TO_AVSS, ADC_REFERENCE_VREFPLUS_TO_AVSS, ADC_REFERENCE_AVDD_TO_VREF_NEG, ADC_REFERENCE_VREFPLUS_TO_VREFNEG } ADC_VOLTAGE_REFERENCE; 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1420 Description ADC Voltage Reference Enumeration This data type defines the different ADC Voltage Reference by which the ADC can be configured. Members Members Description ADC_VREF_POS_TO_VDD Positive voltage reference supplied internally by VDD ADC_VREF_POS_TO_VREF_PLUS Positive voltage reference supplied externally through VREF+ pin ADC_VREF_NEG_TO_VSS Negative voltage reference supplied internally through VSS ADC_VREF_NEG_TO_VREF_MINUS Negative voltage reference supplied externally through VREF- pin ADC_REFERENCE_VDD_TO_AVSS Positive voltage reference supplied internally by VDD and Negative voltage reference supplied internally through VSS ADC_REFERENCE_VREFPLUS_TO_AVSS Positive voltage reference supplied externally through VREF+ pin and Negative voltage reference supplied internally through VSS ADC_REFERENCE_AVDD_TO_VREF_NEG Positive voltage reference supplied internally by VDD and Negative voltage reference supplied externally through VREF- pin ADC_REFERENCE_VREFPLUS_TO_VREFNEG Positive voltage reference supplied externally through VREF+ pin and Negative voltage reference supplied externally through VREF- pin Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.3 ADC_INPUTS_NEGATIVE Enumeration C typedef enum { ADC_INPUT_NEGATIVE_VREF_MINUS, ADC_INPUT_NEGATIVE_AN1, ADC_INPUT_NEGATIVE_AN2, ADC_INPUT_NEGATIVE_AN3, ADC_INPUT_NEGATIVE_AN4, ADC_INPUT_NEGATIVE_AN5, ADC_INPUT_NEGATIVE_AN6 } ADC_INPUTS_NEGATIVE; Description ADC Negative Input Enumeration This data type defines the different ADC Negative Input Enumeration. Members Members Description ADC_INPUT_NEGATIVE_VREF_MINUS Negative input is Vref ADC_INPUT_NEGATIVE_AN1 Negative input is AN1 ADC_INPUT_NEGATIVE_AN2 Negative input is AN2 ADC_INPUT_NEGATIVE_AN3 Negative input is AN3 ADC_INPUT_NEGATIVE_AN4 Negative input is AN4 ADC_INPUT_NEGATIVE_AN5 Negative input is AN5 ADC_INPUT_NEGATIVE_AN6 Negative input is AN6 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1421 5.6.1.6.8.4 ADC_SAMPLES_PER_INTERRUPT Enumeration C typedef enum { ADC_1SAMPLE_PER_INTERRUPT, ADC_2SAMPLES_PER_INTERRUPT, ADC_3SAMPLES_PER_INTERRUPT, ADC_4SAMPLES_PER_INTERRUPT, ADC_5SAMPLES_PER_INTERRUPT, ADC_6SAMPLES_PER_INTERRUPT, ADC_7SAMPLES_PER_INTERRUPT, ADC_8SAMPLES_PER_INTERRUPT, ADC_9SAMPLES_PER_INTERRUPT, ADC_10SAMPLES_PER_INTERRUPT, ADC_11SAMPLES_PER_INTERRUPT, ADC_12SAMPLES_PER_INTERRUPT, ADC_13SAMPLES_PER_INTERRUPT, ADC_14SAMPLES_PER_INTERRUPT, ADC_15SAMPLES_PER_INTERRUPT, ADC_16SAMPLES_PER_INTERRUPT, ADC_17SAMPLES_PER_INTERRUPT, ADC_18SAMPLES_PER_INTERRUPT, ADC_19SAMPLES_PER_INTERRUPT, ADC_20SAMPLES_PER_INTERRUPT, ADC_21SAMPLES_PER_INTERRUPT, ADC_22SAMPLES_PER_INTERRUPT, ADC_23SAMPLES_PER_INTERRUPT, ADC_24SAMPLES_PER_INTERRUPT, ADC_25SAMPLES_PER_INTERRUPT, ADC_26SAMPLES_PER_INTERRUPT, ADC_27SAMPLES_PER_INTERRUPT, ADC_28SAMPLES_PER_INTERRUPT, ADC_29SAMPLES_PER_INTERRUPT, ADC_30SAMPLES_PER_INTERRUPT, ADC_31SAMPLES_PER_INTERRUPT, ADC_32SAMPLES_PER_INTERRUPT } ADC_SAMPLES_PER_INTERRUPT; Description ADC samples per Interrupt Enumeration This data type defines the Samples Per Interrupt Enumeration. Members Members Description ADC_1SAMPLE_PER_INTERRUPT Interrupts at the completion of conversion for each sample/convert sequence ADC_2SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 2nd sample/convert sequence ADC_3SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 3rd sample/convert sequence ADC_4SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 4th sample/convert sequence ADC_5SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 5th sample/convert sequence ADC_6SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 6th sample/convert sequence ADC_7SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 7th sample/convert sequence ADC_8SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 8th sample/convert sequence ADC_9SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 9th sample/convert sequence ADC_10SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 10th sample/convert sequence ADC_11SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 11th sample/convert sequence ADC_12SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 12th sample/convert sequence 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1422 ADC_13SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 13th sample/convert sequence ADC_14SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 14th sample/convert sequence ADC_15SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 15th sample/convert sequence ADC_16SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 16th sample/convert sequence ADC_17SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 17th sample/convert sequence ADC_18SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 18th sample/convert sequence ADC_19SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 19th sample/convert sequence ADC_20SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 20th sample/convert sequence ADC_21SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 21st sample/convert sequence ADC_22SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 22nd sample/convert sequence ADC_23SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 23rd sample/convert sequence ADC_24SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 24th sample/convert sequence ADC_25SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 25th sample/convert sequence ADC_26SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 26th sample/convert sequence ADC_27SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 27th sample/convert sequence ADC_28SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 28th sample/convert sequence ADC_29SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 29th sample/convert sequence ADC_30SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 30th sample/convert sequence ADC_31SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 31st sample/convert sequence ADC_32SAMPLES_PER_INTERRUPT Interrupts at the completion of conversion for each 32nd sample/convert sequence Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.5 ADC_CHANNEL_GROUP Enumeration C typedef enum { ADC_CHANNEL_GROUP_CH0_CH1_CH2_CH3, ADC_CHANNEL_GROUP_CH0_CH1, ADC_CHANNEL_GROUP_CH0 } ADC_CHANNEL_GROUP; Description ADC Channel Group This data type defines the ADC Channel Group. Members Members Description ADC_CHANNEL_GROUP_CH0_CH1_CH2_CH3 Converts Channels CH0, CH1, CH2 and CH3 ADC_CHANNEL_GROUP_CH0_CH1 Converts Channels CH0, CH1 ADC_CHANNEL_GROUP_CH0 Converts Channel CH0 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1423 5.6.1.6.8.6 ADC_CLOCK_SOURCE Enumeration C typedef enum { ADC_CLOCK_SOURCE_SYSTEM_CLOCK, ADC_CLOCK_SOURCE_INTERNAL_RC, ADC_CLOCK_SOURCE_AUXILIARY_PLL, ADC_CLOCK_SOURCE_PRIMARY_PLL } ADC_CLOCK_SOURCE; Description ADC Clock Source Select This data type defines the ADC Clock Source Select. Members Members Description ADC_CLOCK_SOURCE_SYSTEM_CLOCK A/D system clock ADC_CLOCK_SOURCE_INTERNAL_RC A/D internal RC clock ADC_CLOCK_SOURCE_AUXILIARY_PLL ADC is clocked by the auxiliary PLL (ACLK) ADC_CLOCK_SOURCE_PRIMARY_PLL ADC is clock by the primary PLL (FVCO) Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.7 ADC_CONVERSION_TRIGGER_SOURCE Enumeration C typedef enum { ADC_CONVERSION_TRIGGER_SAMP_CLEAR, ADC_CONVERSION_TRIGGER_INT0_TRANSITION, ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH, ADC_CONVERSION_TRIGGER_TMR5_COMPARE_MATCH, ADC_CONVERSION_TRIGGER_CTMU_EVENT, ADC_CONVERSION_TRIGGER_CTMU_EVENT_ALTERNATIVE, ADC_CONVERSION_TRIGGER_INTERNAL_COUNT, ADC_CONVERSION_TRIGGER_NO_CONVERSION, ADC_CONVERSION_TRIGGER_INDIVIDUAL_SFW_TRIG, ADC_CONVERSION_TRIGGER_GLOBAL_SFW_TRIG, ADC_CONVERSION_TRIGGER_PWM_PRIMARY_SPECIAL_EVENT, ADC_CONVERSION_TRIGGER_PWM_GEN1_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN2_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN3_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN4_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN5_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN6_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN7_PRIMARY, ADC_CONVERSION_TRIGGER_PWM_GEN8_PRIMARY, ADC_CONVERSION_TRIGGER_TMR1_PERIOD_MATCH, ADC_CONVERSION_TRIGGER_PWM_SECONDARY_SPECIAL_EVENT, ADC_CONVERSION_TRIGGER_PWM_GEN1_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN2_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN3_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN4_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN5_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN6_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN7_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN8_SECONDARY, ADC_CONVERSION_TRIGGER_PWM_GEN9_SECONDARY, 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1424 ADC_CONVERSION_TRIGGER_PWM_GEN1_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN2_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN3_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN4_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN5_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN6_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN7_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_PWM_GEN8_CURRENT_LMT_ADC, ADC_CONVERSION_TRIGGER_TMR2_PERIOD_MATCH } ADC_CONVERSION_TRIGGER_SOURCE; Description ADC Conversion Trigger Source This data type defines the ADC Conversion Trigger Source. Members Members Description ADC_CONVERSION_TRIGGER_SAMP_CLEAR Clearing SAMP bit (full program control) ADC_CONVERSION_TRIGGER_INT0_TRANSITION Active transition on INT0 pin (basic sync convert) ADC_CONVERSION_TRIGGER_TMR3_COMPARE_MATCH Timer3 compare match ADC_CONVERSION_TRIGGER_TMR5_COMPARE_MATCH Timer5 compare match ADC_CONVERSION_TRIGGER_CTMU_EVENT CTMU event ADC_CONVERSION_TRIGGER_CTMU_EVENT_ALTERNATIVE CTMU event Alternative ADC_CONVERSION_TRIGGER_INTERNAL_COUNT Internal counter (auto-convert) ADC_CONVERSION_TRIGGER_NO_CONVERSION No conversion enabled ADC_CONVERSION_TRIGGER_INDIVIDUAL_SFW_TRIG Individual software trigger selected ADC_CONVERSION_TRIGGER_GLOBAL_SFW_TRIG Global software trigger selected ADC_CONVERSION_TRIGGER_PWM_PRIMARY_SPECIAL_EVENT PWM Special/Primary Special Event Trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN1_PRIMARY PWM Generator 1 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN2_PRIMARY PWM Generator 2 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN3_PRIMARY PWM Generator 3 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN4_PRIMARY PWM Generator 4 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN5_PRIMARY PWM Generator 5 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN6_PRIMARY PWM Generator 6 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN7_PRIMARY PWM Generator 7 primary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN8_PRIMARY PWM Generator 8 primary trigger selected ADC_CONVERSION_TRIGGER_TMR1_PERIOD_MATCH Timer1 period match ADC_CONVERSION_TRIGGER_PWM_SECONDARY_SPECIAL_EVENT PWM secondary special event trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN1_SECONDARY PWM Generator 1 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN2_SECONDARY PWM Generator 2 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN3_SECONDARY PWM Generator 3 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN4_SECONDARY PWM Generator 4 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN5_SECONDARY PWM Generator 5 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN6_SECONDARY PWM Generator 6 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN7_SECONDARY PWM Generator 7 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN8_SECONDARY PWM Generator 8 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN9_SECONDARY PWM Generator 9 secondary trigger selected ADC_CONVERSION_TRIGGER_PWM_GEN1_CURRENT_LMT_ADC PWM Generator 1 current-limit ADC trigger 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1425 ADC_CONVERSION_TRIGGER_PWM_GEN2_CURRENT_LMT_ADC PWM Generator 2 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN3_CURRENT_LMT_ADC PWM Generator 3 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN4_CURRENT_LMT_ADC PWM Generator 4 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN5_CURRENT_LMT_ADC PWM Generator 5 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN6_CURRENT_LMT_ADC PWM Generator 6 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN7_CURRENT_LMT_ADC PWM Generator 7 current-limit ADC trigger ADC_CONVERSION_TRIGGER_PWM_GEN8_CURRENT_LMT_ADC PWM Generator 8 current-limit ADC trigger ADC_CONVERSION_TRIGGER_TMR2_PERIOD_MATCH Timer2 period match Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.8 ADC_RESULT_SIZE Enumeration C typedef enum { ADC_RESULT_SIZE_8_BITS, ADC_RESULT_SIZE_10_BITS, ADC_RESULT_SIZE_12_BITS } ADC_RESULT_SIZE; Description ADC Result Size This data type defines the ADC Result Size. Members Members Description ADC_RESULT_SIZE_8_BITS Converter Mode/Result Size is 8-bits ADC_RESULT_SIZE_10_BITS Converter Mode/Result Size is 10-bits ADC_RESULT_SIZE_12_BITS Converter Mode/Result Size is 12-bits Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.9 ADC_BUFFER_MODE Enumeration C typedef enum { ADC_BUFFER_MODE_ONE_16WORD_BUFFER, ADC_BUFFER_MODE_TWO_8WORD_BUFFERS } ADC_BUFFER_MODE; Description ADC Buffer Mode This data type defines the ADC Buffer Mode. Members Members Description ADC_BUFFER_MODE_ONE_16WORD_BUFFER Buffer configured as one 16-word buffer (ADC1BUF0 to ADC1BUFF) ADC_BUFFER_MODE_TWO_8WORD_BUFFERS Buffer configured as two 8-word buffers (ADC1BUF0 to ADC1BUF7 and ADC1BUF8 to ADC1BUFF) 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1426 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.10 ADC_RESULT_BUF_STATUS Enumeration C typedef enum { ADC_FILLING_BUF_0TO7, ADC_FILLING_BUF_8TOF } ADC_RESULT_BUF_STATUS; Description ADC Result Buffer Status This data type defines the elements that specify which group of eight buffers the ADC is currently filling. Members Members Description ADC_FILLING_BUF_0TO7 Buffers 0x0 to 0x7 are getting filled ADC_FILLING_BUF_8TOF Buffers 0x8 to 0xF are getting filled Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.11 ADC_MUX Enumeration C typedef enum { ADC_MUX_A, ADC_MUX_B } ADC_MUX; Description ADC MUX Enumeration This data type defines the different ADC MUX Enumeration. Members Members Description ADC_MUX_A ADC Mux A Selection ADC_MUX_B ADC Mux B Selection Remarks None 5.6.1.6.8.12 ADC_SAMPLING_MODE Enumeration C typedef enum { ADC_SAMPLING_MODE_SIMULTANEOUS, ADC_SAMPLING_MODE_SEQUENTIAL } ADC_SAMPLING_MODE; 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1427 Description ADC Sampling Mode Select This data type defines the ADC Sampling Mode Select. Members Members Description ADC_SAMPLING_MODE_SIMULTANEOUS Simultaneous Sampling Mode ADC_SAMPLING_MODE_SEQUENTIAL Sequential Sampling Mode Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.13 ADC_INPUTS_SCAN Enumeration C typedef enum { ADC_INPUT_SCAN_AN0, ADC_INPUT_SCAN_AN1, ADC_INPUT_SCAN_AN2, ADC_INPUT_SCAN_AN3, ADC_INPUT_SCAN_AN4, ADC_INPUT_SCAN_AN5, ADC_INPUT_SCAN_AN6, ADC_INPUT_SCAN_AN7, ADC_INPUT_SCAN_AN8, ADC_INPUT_SCAN_AN9, ADC_INPUT_SCAN_AN10, ADC_INPUT_SCAN_AN11, ADC_INPUT_SCAN_AN12, ADC_INPUT_SCAN_AN13, ADC_INPUT_SCAN_AN14, ADC_INPUT_SCAN_AN15, ADC_INPUT_SCAN_AN16, ADC_INPUT_SCAN_AN17, ADC_INPUT_SCAN_AN18, ADC_INPUT_SCAN_AN19, ADC_INPUT_SCAN_AN20, ADC_INPUT_SCAN_AN21, ADC_INPUT_SCAN_AN22, ADC_INPUT_SCAN_AN23, ADC_INPUT_SCAN_AN24, ADC_INPUT_SCAN_AN25, ADC_INPUT_SCAN_AN26, ADC_INPUT_SCAN_AN27, ADC_INPUT_SCAN_AN28, ADC_INPUT_SCAN_AN29, ADC_INPUT_SCAN_AN30, ADC_INPUT_SCAN_AN31, ADC_INPUT_SCAN_IVREF, ADC_INPUT_SCAN_CTMU, ADC_INPUT_SCAN_VSS, ADC_INPUT_SCAN_VBG_DIV_BY_6, ADC_INPUT_SCAN_VBG_DIV_BY_2, ADC_INPUT_SCAN_VBG_DIV_BY_1, ADC_INPUT_SCAN_VDDCORE, ADC_INPUT_SCAN_ALL } ADC_INPUTS_SCAN; 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1428 Description ADC Scan Inputs Enumeration This data type defines the ADC Scan inputs. Members Members Description ADC_INPUT_SCAN_AN0 Scan input is AN0 ADC_INPUT_SCAN_AN1 Scan input is AN1 ADC_INPUT_SCAN_AN2 Scan input is AN2 ADC_INPUT_SCAN_AN3 Scan input is AN3 ADC_INPUT_SCAN_AN4 Scan input is AN4 ADC_INPUT_SCAN_AN5 Scan input is AN5 ADC_INPUT_SCAN_AN6 Scan input is AN6 ADC_INPUT_SCAN_AN7 Scan input is AN7 ADC_INPUT_SCAN_AN8 Scan input is AN8 ADC_INPUT_SCAN_AN9 Scan input is AN9 ADC_INPUT_SCAN_AN10 Scan input is AN10 ADC_INPUT_SCAN_AN11 Scan input is AN11 ADC_INPUT_SCAN_AN12 Scan input is AN12 ADC_INPUT_SCAN_AN13 Scan input is AN13 ADC_INPUT_SCAN_AN14 Scan input is AN14 ADC_INPUT_SCAN_AN15 Scan input is AN15 ADC_INPUT_SCAN_AN16 Scan input is AN16 ADC_INPUT_SCAN_AN17 Scan input is AN17 ADC_INPUT_SCAN_AN18 Scan input is AN18 ADC_INPUT_SCAN_AN19 Scan input is AN19 ADC_INPUT_SCAN_AN20 Scan input is AN20 ADC_INPUT_SCAN_AN21 Scan input is AN21 ADC_INPUT_SCAN_AN22 Scan input is AN22 ADC_INPUT_SCAN_AN23 Scan input is AN23 ADC_INPUT_SCAN_AN24 Scan input is AN24 ADC_INPUT_SCAN_AN25 Scan input is AN25 ADC_INPUT_SCAN_AN26 Scan input is AN26 ADC_INPUT_SCAN_AN27 Scan input is AN27 ADC_INPUT_SCAN_AN28 Scan input is AN28 ADC_INPUT_SCAN_AN29 Scan input is AN29 ADC_INPUT_SCAN_AN30 Scan input is AN30 ADC_INPUT_SCAN_AN31 Scan input is AN31 ADC_INPUT_SCAN_IVREF Scan input is IVref ADC_INPUT_SCAN_CTMU Scan input is CTMU input ADC_INPUT_SCAN_VSS Scan input is Vss ADC_INPUT_SCAN_VBG_DIV_BY_6 Scan input is VBG/6 ADC_INPUT_SCAN_VBG_DIV_BY_2 Scan input is VBG/2 ADC_INPUT_SCAN_VBG_DIV_BY_1 Scan input is VBG ADC_INPUT_SCAN_VDDCORE Scan input is VDDCORE 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1429 ADC_INPUT_SCAN_ALL All Inputs Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.14 ADC_REFERENCE_INPUT Enumeration C typedef enum { ADC_REFERENCE_INPUT_VBG_DIV_BY_1, ADC_REFERENCE_INPUT_VBG_DIV_BY_2, ADC_REFERENCE_INPUT_VBG_DIV_BY_6, ADC_REFERENCE_INPUT_VDDCORE } ADC_REFERENCE_INPUT; Description ADC Reference Input Enumeration This data type defines the ADC Reference Input Enumeration. Members Members Description ADC_REFERENCE_INPUT_VBG_DIV_BY_1 Internal Band Gap Reference Channel VBG ADC_REFERENCE_INPUT_VBG_DIV_BY_2 Internal Band Gap Reference Channel VBG/2 ADC_REFERENCE_INPUT_VBG_DIV_BY_6 Internal Band Gap Reference Channel VBG/6 ADC_REFERENCE_INPUT_VDDCORE Internal Reference Channel VDDCORE Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.15 ADC_RESULT_FORMAT Enumeration C typedef enum { ADC_RESULT_FORMAT_LEFT_JUSTIFIED, ADC_RESULT_FORMAT_RIGHT_JUSTIFIED, ADC_RESULT_FORMAT_INTEGER_16BIT, ADC_RESULT_FORMAT_SIGNED_INTEGER_16BIT, ADC_RESULT_FORMAT_FRACTIONAL_16BIT, ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_16BIT, ADC_RESULT_FORMAT_INTEGER_32BIT, ADC_RESULT_FORMAT_SIGNED_INTEGER_32BIT, ADC_RESULT_FORMAT_FRACTIONAL_32BIT, ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_32BIT } ADC_RESULT_FORMAT; Description ADC Result Format This data type defines the ADC Result Format. Members Members Description ADC_RESULT_FORMAT_LEFT_JUSTIFIED Result Left justified ADC_RESULT_FORMAT_RIGHT_JUSTIFIED Result Right justified 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1430 ADC_RESULT_FORMAT_INTEGER_16BIT Integer 16-bit ADC_RESULT_FORMAT_SIGNED_INTEGER_16BIT Signed Integer 16-bit ADC_RESULT_FORMAT_FRACTIONAL_16BIT Fractional 16-bit ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_16BIT Signed Fractional 16-bit ADC_RESULT_FORMAT_INTEGER_32BIT Integer 32-bit ADC_RESULT_FORMAT_SIGNED_INTEGER_32BIT Signed Integer 32-bit ADC_RESULT_FORMAT_FRACTIONAL_32BIT Fractional 32-bit ADC_RESULT_FORMAT_SIGNED_FRACTIONAL_32BIT Signed Fractional 32-bit Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.16 ADC_DMA_BUFFER_MODE Enumeration C typedef enum { ADC_DMA_BUFFER_MODE_SCATTER_GATHER, ADC_DMA_BUFFER_MODE_ORDER_OF_CONV } ADC_DMA_BUFFER_MODE; Description ADC DMA Buffer Mode This data type defines the ADC Buffer Mode. Members Members Description ADC_DMA_BUFFER_MODE_SCATTER_GATHER DMA buffers are written in Scatter/Gather mode ADC_DMA_BUFFER_MODE_ORDER_OF_CONV DMA buffers are written in the order of conversion Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.17 ADC_PAIR Enumeration C typedef enum { ADC_PAIR_AN0_AN1, ADC_PAIR_AN2_AN3, ADC_PAIR_AN4_AN5, ADC_PAIR_AN6_AN7, ADC_PAIR_AN8_AN9, ADC_PAIR_AN10_AN11, ADC_PAIR_AN12_AN13, ADC_PAIR_AN14_AN15, ADC_PAIR_AN16_AN17, ADC_PAIR_AN18_AN19, ADC_PAIR_AN20_AN21, ADC_PAIR_AN22_AN23, ADC_PAIR_AN24_AN25 } ADC_PAIR; Description ADC Pair This data type defines the ADC Pair. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1431 Members Members Description ADC_PAIR_AN0_AN1 Pair 0 - AN0, AN1 ADC_PAIR_AN2_AN3 Pair 1 - AN2, AN3 ADC_PAIR_AN4_AN5 Pair 2 - AN4, AN5 ADC_PAIR_AN6_AN7 Pair 3 - AN6, AN7 ADC_PAIR_AN8_AN9 Pair 4 - AN8, AN9 ADC_PAIR_AN10_AN11 Pair 5 - AN10, AN11 ADC_PAIR_AN12_AN13 Pair 6 - AN12, AN13 ADC_PAIR_AN14_AN15 Pair 7 - AN14, AN15 ADC_PAIR_AN16_AN17 Pair 8 - AN16, AN17 ADC_PAIR_AN18_AN19 Pair 9 - AN18, AN19 ADC_PAIR_AN20_AN21 Pair 10 - AN20, AN21 ADC_PAIR_AN22_AN23 Pair 11 - AN22, AN23 ADC_PAIR_AN24_AN25 Pair 12 - AN24, AN25 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.18 ADC_CHANNEL123_INPUTS_NEG Enumeration C typedef enum { ADC_CHANNEL123_INPUT_NEG_CH123_VREF_MINUS, ADC_CHANNEL123_INPUT_NEG_CH1_AN6_CH2_AN7_CH3_NC, ADC_CHANNEL123_INPUT_NEG_CH1_AN6_CH2_AN7_CH3_AN8, ADC_CHANNEL123_INPUT_NEG_CH1_AN9_CH2_AN10_CH3_AN11, ADC_CHANNEL123_INPUT_NEG_CH1_AN9_CH2_CH3_NC } ADC_CHANNEL123_INPUTS_NEG; Description ADC Channel 123 Negative Input Select This data type defines the ADC Channel 123 Negative Input Select. Members Members Description ADC_CHANNEL123_INPUT_NEG_CH123_VREF_MINUS CH1, CH2, CH3 negative input is VREF ADC_CHANNEL123_INPUT_NEG_CH1_AN6_CH2_AN7_CH3_NC CH1 negative input is AN6, CH2 negative input is AN7, CH3 negative input is not connected ADC_CHANNEL123_INPUT_NEG_CH1_AN6_CH2_AN7_CH3_AN8 CH1 negative input is AN6, CH2 negative input is AN7, CH3 negative input is AN8 ADC_CHANNEL123_INPUT_NEG_CH1_AN9_CH2_AN10_CH3_AN11 CH1 negative input is AN9, CH2 negative input is AN10, CH3 negative input is AN11 ADC_CHANNEL123_INPUT_NEG_CH1_AN9_CH2_CH3_NC CH1 negative input is AN9, CH2 and CH3 negative inputs are not connected Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1432 5.6.1.6.8.19 ADC_CHANNEL123_INPUTS_POS Enumeration C typedef enum { ADC_CHANNEL123_INPUT_POS_CH1_AN3_CH2_CH3_NC, ADC_CHANNEL123_INPUT_POS_CH1_AN0_CH2_AN1_CH3_AN2, ADC_CHANNEL123_INPUT_POS_CH1_AN3_CH2_AN4_CH3_AN5 } ADC_CHANNEL123_INPUTS_POS; Description ADC Channel 123 Positive Input Select This data type defines the ADC Channel 123 Positive Input Select. Members Members Description ADC_CHANNEL123_INPUT_POS_CH1_AN3_CH2_CH3_NC CH1 positive input is AN3, CH2 and CH3 positive inputs are not connected ADC_CHANNEL123_INPUT_POS_CH1_AN0_CH2_AN1_CH3_AN2 CH1 positive input is AN0, CH2 positive input is AN1, CH3 positive input is AN2 ADC_CHANNEL123_INPUT_POS_CH1_AN3_CH2_AN4_CH3_AN5 CH1 positive input is AN3, CH2 positive input is AN4, CH3 positive input is AN5 Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.20 ADC_INPUTS_POSITIVE Enumeration C typedef enum { ADC_INPUT_POSITIVE_AN0, ADC_INPUT_POSITIVE_AN1, ADC_INPUT_POSITIVE_AN2, ADC_INPUT_POSITIVE_AN3, ADC_INPUT_POSITIVE_AN4, ADC_INPUT_POSITIVE_AN5, ADC_INPUT_POSITIVE_AN6, ADC_INPUT_POSITIVE_AN7, ADC_INPUT_POSITIVE_AN8, ADC_INPUT_POSITIVE_AN9, ADC_INPUT_POSITIVE_AN10, ADC_INPUT_POSITIVE_AN11, ADC_INPUT_POSITIVE_AN12, ADC_INPUT_POSITIVE_AN13, ADC_INPUT_POSITIVE_AN14, ADC_INPUT_POSITIVE_AN15, ADC_INPUT_POSITIVE_AN16, ADC_INPUT_POSITIVE_AN17, ADC_INPUT_POSITIVE_AN18, ADC_INPUT_POSITIVE_AN19, ADC_INPUT_POSITIVE_AN20, ADC_INPUT_POSITIVE_AN21, ADC_INPUT_POSITIVE_AN22, ADC_INPUT_POSITIVE_AN23, ADC_INPUT_POSITIVE_AN24, ADC_INPUT_POSITIVE_AN25, ADC_INPUT_POSITIVE_AN26, ADC_INPUT_POSITIVE_AN27, ADC_INPUT_POSITIVE_AN28, 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1433 ADC_INPUT_POSITIVE_AN29, ADC_INPUT_POSITIVE_AN30, ADC_INPUT_POSITIVE_AN31, ADC_INPUT_POSITIVE_ABS_VOLTAGE_REF, ADC_INPUT_POSITIVE_MUX_DISCONNECT, ADC_INPUT_POSITIVE_TEMP_INDICATOR, ADC_INPUT_POSITIVE_DAC_OUTPUT, ADC_INPUT_POSITIVE_FVR_BUFFER1_OUTPUT, ADC_INPUT_POSITIVE_VBG_DIV_BY_6, ADC_INPUT_POSITIVE_VBG_DIV_BY_2, ADC_INPUT_POSITIVE_VBG_DIV_BY_1, ADC_INPUT_POSITIVE_VDDCORE, ADC_INPUT_POSITIVE_MAX, ADC_INPUT_POSITIVE_CTMU, ADC_INPUT_POSITIVE_IVREF, ADC_INPUT_POSITIVE_OPEN } ADC_INPUTS_POSITIVE; Description ADC Inputs Enumeration This data type defines the ADC inputs. Members Members Description ADC_INPUT_POSITIVE_AN0 Positive input is AN0 ADC_INPUT_POSITIVE_AN1 Positive input is AN1 ADC_INPUT_POSITIVE_AN2 Positive input is AN2 ADC_INPUT_POSITIVE_AN3 Positive input is AN3 ADC_INPUT_POSITIVE_AN4 Positive input is AN4 ADC_INPUT_POSITIVE_AN5 Positive input is AN5 ADC_INPUT_POSITIVE_AN6 Positive input is AN6 ADC_INPUT_POSITIVE_AN7 Positive input is AN7 ADC_INPUT_POSITIVE_AN8 Positive input is AN8 ADC_INPUT_POSITIVE_AN9 Positive input is AN9 ADC_INPUT_POSITIVE_AN10 Positive input is AN10 ADC_INPUT_POSITIVE_AN11 Positive input is AN11 ADC_INPUT_POSITIVE_AN12 Positive input is AN12 ADC_INPUT_POSITIVE_AN13 Positive input is AN13 ADC_INPUT_POSITIVE_AN14 Positive input is AN14 ADC_INPUT_POSITIVE_AN15 Positive input is AN15 ADC_INPUT_POSITIVE_AN16 Positive input is AN16 ADC_INPUT_POSITIVE_AN17 Positive input is AN17 ADC_INPUT_POSITIVE_AN18 Positive input is AN18 ADC_INPUT_POSITIVE_AN19 Positive input is AN19 ADC_INPUT_POSITIVE_AN20 Positive input is AN20 ADC_INPUT_POSITIVE_AN21 Positive input is AN21 ADC_INPUT_POSITIVE_AN22 Positive input is AN22 ADC_INPUT_POSITIVE_AN23 Positive input is AN23 ADC_INPUT_POSITIVE_AN24 Positive input is AN24 ADC_INPUT_POSITIVE_AN25 Positive input is AN25 ADC_INPUT_POSITIVE_AN26 Positive input is AN26 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1434 ADC_INPUT_POSITIVE_AN27 Positive input is AN27 ADC_INPUT_POSITIVE_AN28 Positive input is AN28 ADC_INPUT_POSITIVE_AN29 Positive input is AN29 ADC_INPUT_POSITIVE_AN30 Positive input is AN30 ADC_INPUT_POSITIVE_AN31 Positive input is AN31 ADC_INPUT_POSITIVE_ABS_VOLTAGE_REF ADC Channel 0.6V Absolute Voltage Reference ADC_INPUT_POSITIVE_MUX_DISCONNECT ADC Channel MUX Disconnect ADC_INPUT_POSITIVE_TEMP_INDICATOR ADC Channel Temparature Diode/Indicator ADC_INPUT_POSITIVE_DAC_OUTPUT ADC Channel DAC Output ADC_INPUT_POSITIVE_FVR_BUFFER1_OUTPUT ADC Channel Fixed Voltage Reference Buffer1 Output ADC_INPUT_POSITIVE_VBG_DIV_BY_6 Positive input is VBG/6 ADC_INPUT_POSITIVE_VBG_DIV_BY_2 Positive input is VBG/2 ADC_INPUT_POSITIVE_VBG_DIV_BY_1 Positive input is VBG ADC_INPUT_POSITIVE_VDDCORE Positive input is VDDCORE ADC_INPUT_POSITIVE_MAX Maximum Inputs ADC_INPUT_POSITIVE_CTMU Positive input is from CTMU ADC_INPUT_POSITIVE_IVREF Positive input is IVref ADC_INPUT_POSITIVE_OPEN Positive input is Open Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.21 ADC_CONVERSION_ORDER Enumeration C typedef enum { ADC_CONVERSION_ORDER_ODD_FIRST, ADC_CONVERSION_ORDER_EVEN_FIRST } ADC_CONVERSION_ORDER; Description ADC Conversion Order This data type defines the ADC Conversion Order. Members Members Description ADC_CONVERSION_ORDER_ODD_FIRST Odd numbered analog input is converted first, followed by conversion of even numbered input ADC_CONVERSION_ORDER_EVEN_FIRST Even numbered analog input is converted first, followed by conversion of odd numbered input Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.22 ADC_DMA_ADDRESS_INCREMENT Enumeration C typedef enum { ADC_DMA_ADDRESS_INCREMENT_EVERY_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_2ND_SAMPLE, 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1435 ADC_DMA_ADDRESS_INCREMENT_EVERY_3RD_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_4TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_5TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_6TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_7TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_8TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_9TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_10TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_11TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_12TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_13TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_14TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_15TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_16TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_17TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_18TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_19TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_20TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_21ST_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_22ND_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_23RD_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_24TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_25TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_26TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_27TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_28TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_29TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_30TH_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_31ST_SAMPLE, ADC_DMA_ADDRESS_INCREMENT_EVERY_32ND_SAMPLE } ADC_DMA_ADDRESS_INCREMENT; Description ADC DMA Increment Rate This data type defines the ADC DMA Increment Rate. Members Members Description ADC_DMA_ADDRESS_INCREMENT_EVERY_SAMPLE Increments the DMA address after completion of every sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_2ND_SAMPLE Increments the DMA address after completion of every 2nd sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_3RD_SAMPLE Increments the DMA address after completion of every 3rd sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_4TH_SAMPLE Increments the DMA address after completion of every 4th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_5TH_SAMPLE Increments the DMA address after completion of every 5th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_6TH_SAMPLE Increments the DMA address after completion of every 6th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_7TH_SAMPLE Increments the DMA address after completion of every 7th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_8TH_SAMPLE Increments the DMA address after completion of every 8th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_9TH_SAMPLE Increments the DMA address after completion of every 9th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_10TH_SAMPLE Increments the DMA address after completion of every 10th sample/conversion operation 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1436 ADC_DMA_ADDRESS_INCREMENT_EVERY_11TH_SAMPLE Increments the DMA address after completion of every 11th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_12TH_SAMPLE Increments the DMA address after completion of every 12th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_13TH_SAMPLE Increments the DMA address after completion of every 13th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_14TH_SAMPLE Increments the DMA address after completion of every 14th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_15TH_SAMPLE Increments the DMA address after completion of every 15th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_16TH_SAMPLE Increments the DMA address after completion of every 16th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_17TH_SAMPLE Increments the DMA address after completion of every 17th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_18TH_SAMPLE Increments the DMA address after completion of every 18th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_19TH_SAMPLE Increments the DMA address after completion of every 19th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_20TH_SAMPLE Increments the DMA address after completion of every 20th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_21ST_SAMPLE Increments the DMA address after completion of every 21st sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_22ND_SAMPLE Increments the DMA address after completion of every 22nd sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_23RD_SAMPLE Increments the DMA address after completion of every 23rd sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_24TH_SAMPLE Increments the DMA address after completion of every 24th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_25TH_SAMPLE Increments the DMA address after completion of every 25th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_26TH_SAMPLE Increments the DMA address after completion of every 26th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_27TH_SAMPLE Increments the DMA address after completion of every 27th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_28TH_SAMPLE Increments the DMA address after completion of every 28th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_29TH_SAMPLE Increments the DMA address after completion of every 29th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_30TH_SAMPLE Increments the DMA address after completion of every 30th sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_31ST_SAMPLE Increments the DMA address after completion of every 31st sample/conversion operation ADC_DMA_ADDRESS_INCREMENT_EVERY_32ND_SAMPLE Increments the DMA address after completion of every 32nd sample/conversion operation Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.23 ADC_DMA_INPUT_BUFFER Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1437 ADC_DMA_INPUT_BUFFER_1WORD, ADC_DMA_INPUT_BUFFER_2WORDS, ADC_DMA_INPUT_BUFFER_4WORDS, ADC_DMA_INPUT_BUFFER_8WORDS, ADC_DMA_INPUT_BUFFER_16WORDS, ADC_DMA_INPUT_BUFFER_32WORDS, ADC_DMA_INPUT_BUFFER_64WORDS, ADC_DMA_INPUT_BUFFER_128WORDS } ADC_DMA_INPUT_BUFFER; Description ADC DMA Buffer Per Input This data type defines the ADC DMA Buffer Per Input. Members Members Description ADC_DMA_INPUT_BUFFER_1WORD Allocates 1 word of buffer to each analog input ADC_DMA_INPUT_BUFFER_2WORDS Allocates 2 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_4WORDS Allocates 4 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_8WORDS Allocates 8 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_16WORDS Allocates 16 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_32WORDS Allocates 32 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_64WORDS Allocates 64 words of buffer to each analog input ADC_DMA_INPUT_BUFFER_128WORDS Allocates 128 words of buffer to each analog input Remarks These are the super set enumerations provided for documentation, not all constants are available on all devices. 5.6.1.6.8.24 ADC_ACQUISITION_TIME Type C typedef unsigned int ADC_ACQUISITION_TIME; Description ADC Acquisition Time Selection Data Type This data type defines the different ADC acquisition times by which the ADC can be configured. Remarks None 5.6.1.6.8.25 ADC_CONVERSION_CLOCK Type C typedef unsigned int ADC_CONVERSION_CLOCK; Description ADC Conversion Clock Selection Data Type This data type defines the different ADC Conversion clock Remarks None 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1438 5.6.1.6.8.26 ADC_SAMPLE Type C typedef unsigned int ADC_SAMPLE; Description ADC Sample size This data type defines the size of the adc sample register. Remarks None 5.6.1.6.9 Feature Existence 5.6.1.6.9.1 PLIB_ADC_ExistsAsynchronousDedicatedSampling Function C bool PLIB_ADC_ExistsAsynchronousDedicatedSampling( ADC_MODULE_ID index ); Description This function identifies whether the AsynchronousDedicatedSampling feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_AsynchronousDedicatedSamplingEnable • PLIB_ADC_AsynchronousDedicatedSamplingDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The AsynchronousDedicatedSampling feature is supported on the device • false = The AsynchronousDedicatedSampling feature is not supported on the device Remarks None. 5.6.1.6.9.2 PLIB_ADC_ExistsCalibrationControl Function C bool PLIB_ADC_ExistsCalibrationControl( ADC_MODULE_ID index ); Description This function identifies whether the CalibrationControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1439 • PLIB_ADC_CalibrationEnable • PLIB_ADC_CalibrationDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CalibrationControl feature is supported on the device • false = The CalibrationControl feature is not supported on the device Remarks None. 5.6.1.6.9.3 PLIB_ADC_ExistsChannelGroup Function C bool PLIB_ADC_ExistsChannelGroup( ADC_MODULE_ID index ); Description This function identifies whether the ChannelGroup feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ChannelGroupSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelGroup feature is supported on the device • false = The ChannelGroup feature is not supported on the device Remarks None. 5.6.1.6.9.4 PLIB_ADC_ExistsConversionClock Function C bool PLIB_ADC_ExistsConversionClock( ADC_MODULE_ID index ); Description This function identifies whether the ConversionClock feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1440 • PLIB_ADC_ConversionClockSet • PLIB_ADC_ConversionClockGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionClock feature is supported on the device • false = The ConversionClock feature is not supported on the device Remarks None. 5.6.1.6.9.5 PLIB_ADC_ExistsConversionClockSource Function C bool PLIB_ADC_ExistsConversionClockSource( ADC_MODULE_ID index ); Description This function identifies whether the ConversionClockSource feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionClockSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionClockSource feature is supported on the device • false = The ConversionClockSource feature is not supported on the device Remarks None. 5.6.1.6.9.6 PLIB_ADC_ExistsConversionControl Function C bool PLIB_ADC_ExistsConversionControl( ADC_MODULE_ID index ); Description This function identifies whether the ConversionControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1441 • PLIB_ADC_ConversionStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = When ConversionControl feature is supported on the device • false = When ConversionControl feature is not supported on the device Remarks None. 5.6.1.6.9.7 PLIB_ADC_ExistsConversionOrder Function C bool PLIB_ADC_ExistsConversionOrder( ADC_MODULE_ID index ); Description This function identifies whether the ConversionOrder feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionOrderSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionOrder feature is supported on the device • false = The ConversionOrder feature is not supported on the device Remarks None. 5.6.1.6.9.8 PLIB_ADC_ExistsConversionStatus Function C bool PLIB_ADC_ExistsConversionStatus( ADC_MODULE_ID index ); Description This function identifies whether the ConversionStatus feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionHasCompleted 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1442 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionStatus feature is supported on the device • false = The ConversionStatus feature is not supported on the device Remarks None. 5.6.1.6.9.9 PLIB_ADC_ExistsConversionStopSequenceControl Function C bool PLIB_ADC_ExistsConversionStopSequenceControl( ADC_MODULE_ID index ); Description This function identifies whether the ConversionStopSequenceControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionStopSequenceEnable • PLIB_ADC_ConversionStopSequenceDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionStopSequenceControl feature is supported on the device • false = The ConversionStopSequenceControl feature is not supported on the device Remarks None. 5.6.1.6.9.10 PLIB_ADC_ExistsConversionTriggerGroup Function C bool PLIB_ADC_ExistsConversionTriggerGroup( ADC_MODULE_ID index ); Description This function identifies whether the ConversionTriggerGroup feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1443 • PLIB_ADC_ConversionTriggerGroupSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionTriggerGroup feature is supported on the device • false = The ConversionTriggerGroup feature is not supported on the device Remarks None. 5.6.1.6.9.11 PLIB_ADC_ExistsConversionTriggerSource Function C bool PLIB_ADC_ExistsConversionTriggerSource( ADC_MODULE_ID index ); Description This function identifies whether the ConversionTriggerSource feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ConversionTriggerSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ConversionTriggerSource feature is supported on the device • false = The ConversionTriggerSource feature is not supported on the device Remarks None. 5.6.1.6.9.12 PLIB_ADC_ExistsDMAAddressIncrement Function C bool PLIB_ADC_ExistsDMAAddressIncrement( ADC_MODULE_ID index ); Description This function identifies whether the DMAAddressIncrement feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_DMAAddressIncrementSelect 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1444 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DMAAddressIncrement feature is supported on the device • false = The DMAAddressIncrement feature is not supported on the device Remarks None. 5.6.1.6.9.13 PLIB_ADC_ExistsDMABufferMode Function C bool PLIB_ADC_ExistsDMABufferMode( ADC_MODULE_ID index ); Description This function identifies whether the DMABufferMode feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_DMABufferModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DMABufferMode feature is supported on the device • false = The DMABufferMode feature is not supported on the device Remarks None. 5.6.1.6.9.14 PLIB_ADC_ExistsDMABuffersPerAnalogInput Function C bool PLIB_ADC_ExistsDMABuffersPerAnalogInput( ADC_MODULE_ID index ); Description This function identifies whether the DMABuffersPerInput feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_DMAInputBufferSelect 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1445 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DMABuffersPerInput feature is supported on the device • false = The DMABuffersPerInput feature is not supported on the device Remarks None. 5.6.1.6.9.15 PLIB_ADC_ExistsDMAControl Function C bool PLIB_ADC_ExistsDMAControl( ADC_MODULE_ID index ); Description This function identifies whether the DMAControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_DMAEnable • PLIB_ADC_DMADisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DMAControl feature is supported on the device • false = The DMAControl feature is not supported on the device Remarks None. 5.6.1.6.9.16 PLIB_ADC_ExistsEnableControl Function C bool PLIB_ADC_ExistsEnableControl( ADC_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1446 • PLIB_ADC_Enable • PLIB_ADC_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The EnableControl feature is supported on the device • false = The EnableControl feature is not supported on the device Remarks None. 5.6.1.6.9.17 PLIB_ADC_ExistsGlobalSoftwareTrigger Function C bool PLIB_ADC_ExistsGlobalSoftwareTrigger( ADC_MODULE_ID index ); Description This function identifies whether the GlobalSoftwareTrigger feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_GlobalSoftwareTriggerSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The GlobalSoftwareTrigger feature is supported on the device • false = The GlobalSoftwareTrigger feature is not supported on the device Remarks None. 5.6.1.6.9.18 PLIB_ADC_ExistsInputSelect Function C bool PLIB_ADC_ExistsInputSelect( ADC_MODULE_ID index ); Description This function identifies whether the InputSelect feature is available on the ADC module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1447 • PLIB_ADC_InputSelectPositive • PLIB_ADC_InputSelectNegative Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The InputSelect feature is supported on the device • false = The InputSelect feature is not supported on the device Remarks None. 5.6.1.6.9.19 PLIB_ADC_ExistsInternalReferenceChannelControl Function C bool PLIB_ADC_ExistsInternalReferenceChannelControl( ADC_MODULE_ID index ); Description This function identifies whether the InternalReferenceChannelControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_InternalReferenceChannelEnable • PLIB_ADC_InternalReferenceChannelDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The InternalReferenceChannelControl feature is supported on the device • false = The InternalReferenceChannelControl feature is not supported on the device Remarks None. 5.6.1.6.9.20 PLIB_ADC_ExistsISRJumpTableBaseAddress Function C bool PLIB_ADC_ExistsISRJumpTableBaseAddress( ADC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1448 Description This function identifies whether the ISRJumpTableBaseAddress feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_IsrJumpTableBaseAddressSet • PLIB_ADC_IsrJumpTableBaseAddressGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ISRJumpTableBaseAddress feature is supported on the device • false = The ISRJumpTableBaseAddress feature is not supported on the device Remarks None. 5.6.1.6.9.21 PLIB_ADC_ExistsMuxChannel0NegativeInput Function C bool PLIB_ADC_ExistsMuxChannel0NegativeInput( ADC_MODULE_ID index ); Description This function identifies whether the MuxChannel0NegativeInput feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxChannel0InputNegativeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxChannel0NegativeInput feature is supported on the device • false = The MuxChannel0NegativeInput feature is not supported on the device Remarks None. 5.6.1.6.9.22 PLIB_ADC_ExistsMuxChannel0PositiveInput Function C bool PLIB_ADC_ExistsMuxChannel0PositiveInput( ADC_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1449 ); Description This function identifies whether the MuxChannel0PositiveInput feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxChannel0InputPositiveSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxChannel0PositiveInput feature is supported on the device • false = The MuxChannel0PositiveInput feature is not supported on the device Remarks None. 5.6.1.6.9.23 PLIB_ADC_ExistsMuxChannel123NegativeInput Function C bool PLIB_ADC_ExistsMuxChannel123NegativeInput( ADC_MODULE_ID index ); Description This function identifies whether the MuxChannel123NegativeInput feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxChannel123InputNegativeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxChannel123NegativeInput feature is supported on the device • false = The MuxChannel123NegativeInput feature is not supported on the device Remarks None. 5.6.1.6.9.24 PLIB_ADC_ExistsMuxChannel123PositiveInput Function C bool PLIB_ADC_ExistsMuxChannel123PositiveInput( ADC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1450 Description This function identifies whether the MuxChannel123PositiveInput feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxChannel123InputPositiveSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxChannel123PositiveInput feature is supported on the device • false = The MuxChannel123PositiveInput feature is not supported on the device Remarks None. 5.6.1.6.9.25 PLIB_ADC_ExistsMuxInputScanControl Function C bool PLIB_ADC_ExistsMuxInputScanControl( ADC_MODULE_ID index ); Description This function identifies whether the MuxInputScanControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_MuxAInputScanEnable • PLIB_ADC_MuxAInputScanDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxInputScanControl feature is supported on the device • false = The MuxInputScanControl feature is not supported on the device Remarks None. 5.6.1.6.9.26 PLIB_ADC_ExistsMuxInputScanSelect Function C bool PLIB_ADC_ExistsMuxInputScanSelect( ADC_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1451 ); Description This function identifies whether the MuxInputScanSelect feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_InputScanMaskAdd • PLIB_ADC_InputScanMaskRemove Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MuxInputScanSelect feature is supported on the device • false = The MuxInputScanSelect feature is not supported on the device Remarks None. 5.6.1.6.9.27 PLIB_ADC_ExistsPairConversionControl Function C bool PLIB_ADC_ExistsPairConversionControl( ADC_MODULE_ID index ); Description This function identifies whether the PairConversionControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_PairConversionStart • PLIB_ADC_PairConversionIsPending Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PairConversionControl feature is supported on the device • false = The PairConversionControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1452 5.6.1.6.9.28 PLIB_ADC_ExistsPairInterruptOnConversion Function C bool PLIB_ADC_ExistsPairInterruptOnConversion( ADC_MODULE_ID index ); Description This function identifies whether the PairInterruptOnConversion feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_PairInterruptAfterFirstConversion • PLIB_ADC_PairInterruptAfterSecondConversion Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PairInterruptOnConversion feature is supported on the device • false = The PairInterruptOnConversion feature is not supported on the device Remarks None. 5.6.1.6.9.29 PLIB_ADC_ExistsPairInterruptRequest Function C bool PLIB_ADC_ExistsPairInterruptRequest( ADC_MODULE_ID index ); Description This function identifies whether the PairInterruptRequest feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_PairInterruptRequestEnable • PLIB_ADC_PairInterruptRequestDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PairInterruptRequest feature is supported on the device • false = The PairInterruptRequest feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1453 Remarks None. 5.6.1.6.9.30 PLIB_ADC_ExistsPairSampleStatus Function C bool PLIB_ADC_ExistsPairSampleStatus( ADC_MODULE_ID index ); Description This function identifies whether the PairSampleStatus feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_PairSampleStatusClear • PLIB_ADC_PairSampleIsAvailable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PairSampleStatus feature is supported on the device • false = The PairSampleStatus feature is not supported on the device Remarks None. 5.6.1.6.9.31 PLIB_ADC_ExistsPairTriggerSource Function C bool PLIB_ADC_ExistsPairTriggerSource( ADC_MODULE_ID index ); Description This function identifies whether the PairTriggerSource feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_PairTriggerSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PairTriggerSource feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1454 • false = The PairTriggerSource feature is not supported on the device Remarks None. 5.6.1.6.9.32 PLIB_ADC_ExistsResultBufferFillStatus Function C bool PLIB_ADC_ExistsResultBufferFillStatus( ADC_MODULE_ID index ); Description This function identifies whether the ResultBufferFillStatus feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultBufferStatusGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultBufferFillStatus feature is supported on the device • false = The ResultBufferFillStatus feature is not supported on the device Remarks None. 5.6.1.6.9.33 PLIB_ADC_ExistsResultBufferMode Function C bool PLIB_ADC_ExistsResultBufferMode( ADC_MODULE_ID index ); Description This function identifies whether the ResultBufferMode feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultBufferModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultBufferMode feature is supported on the device • false = The ResultBufferMode feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1455 Remarks None. 5.6.1.6.9.34 PLIB_ADC_ExistsResultFormat Function C bool PLIB_ADC_ExistsResultFormat( ADC_MODULE_ID index ); Description This function identifies whether the ResultFormat feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultFormatSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultFormat feature is supported on the device • false = The ResultFormat feature is not supported on the device Remarks None. 5.6.1.6.9.35 PLIB_ADC_ExistsResultGet Function C bool PLIB_ADC_ExistsResultGet( ADC_MODULE_ID index ); Description This function identifies whether the ResultGet feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultGet feature is supported on the device • false = The ResultGet feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1456 Remarks None. 5.6.1.6.9.36 PLIB_ADC_ExistsResultGetByIndex Function C bool PLIB_ADC_ExistsResultGetByIndex( ADC_MODULE_ID index ); Description This function identifies whether the ResultGetByIndex feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultGetByIndex Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultGetByIndex feature is supported on the device • false = The ResultGetByIndex feature is not supported on the device Remarks None. 5.6.1.6.9.37 PLIB_ADC_ExistsResultSign Function C bool PLIB_ADC_ExistsResultSign( ADC_MODULE_ID index ); Description This function identifies whether the ResultSign feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultSignGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultSign feature is supported on the device • false = The ResultSign feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1457 Remarks None. 5.6.1.6.9.38 PLIB_ADC_ExistsResultSize Function C bool PLIB_ADC_ExistsResultSize( ADC_MODULE_ID index ); Description This function identifies whether the ResultSize feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_ResultSizeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ResultSize feature is supported on the device • false = The ResultSize feature is not supported on the device Remarks None. 5.6.1.6.9.39 PLIB_ADC_ExistsSampleResolution Function C bool PLIB_ADC_ExistsSampleResolution( ADC_MODULE_ID index ); Description This function identifies whether the SampleResolution feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SampleMaxGet • PLIB_ADC_SampleMinGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SampleResolution feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1458 • false = The SampleResolution feature is not supported on the device Remarks None. 5.6.1.6.9.40 PLIB_ADC_ExistsSamplesPerInterruptSelect Function C bool PLIB_ADC_ExistsSamplesPerInterruptSelect( ADC_MODULE_ID index ); Description This function identifies whether the SamplesPerInterruptSelect feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SamplesPerInterruptSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SamplesPerInterruptSelect feature is supported on the device • false = The SamplesPerInterruptSelect feature is not supported on the device Remarks None. 5.6.1.6.9.41 PLIB_ADC_ExistsSamplingAcquisitionTime Function C bool PLIB_ADC_ExistsSamplingAcquisitionTime( ADC_MODULE_ID index ); Description This function identifies whether the SamplingAcquisitionTime feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SampleAcqusitionTimeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SamplingAcquisitionTime feature is supported on the device • false = The SamplingAcquisitionTime feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1459 Remarks None. 5.6.1.6.9.42 PLIB_ADC_ExistsSamplingAutoStart Function C bool PLIB_ADC_ExistsSamplingAutoStart( ADC_MODULE_ID index ); Description This function identifies whether the SamplingAutoStart feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SampleAutoStartEnable • PLIB_ADC_SampleAutoStartDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SamplingAutoStart feature is supported on the device • false = The SamplingAutoStart feature is not supported on the device Remarks None. 5.6.1.6.9.43 PLIB_ADC_ExistsSamplingControl Function C bool PLIB_ADC_ExistsSamplingControl( ADC_MODULE_ID index ); Description This function identifies whether the SamplingControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SamplingStart • PLIB_ADC_SamplingStop Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1460 Returns • true = The SamplingControl feature is supported on the device • false = The SamplingControl feature is not supported on the device Remarks None. 5.6.1.6.9.44 PLIB_ADC_ExistsSamplingModeControl Function C bool PLIB_ADC_ExistsSamplingModeControl( ADC_MODULE_ID index ); Description This function identifies whether the SamplingModeControl feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SamplingModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SamplingModeControl feature is supported on the device • false = The SamplingModeControl feature is not supported on the device Remarks None. 5.6.1.6.9.45 PLIB_ADC_ExistsSamplingStatus Function C bool PLIB_ADC_ExistsSamplingStatus( ADC_MODULE_ID index ); Description This function identifies whether the SamplingStatus feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_SamplingIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1461 Returns • true = The SamplingStatus feature is supported on the device • false = The SamplingStatus feature is not supported on the device Remarks None. 5.6.1.6.9.46 PLIB_ADC_ExistsStopInIdleControl Function C bool PLIB_ADC_ExistsStopInIdleControl( ADC_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_StopInIdleEnable • PLIB_ADC_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The StopInIdle feature is supported on the device • false = The StopInIdle feature is not supported on the device Remarks None. 5.6.1.6.9.47 PLIB_ADC_ExistsVoltageReference Function C bool PLIB_ADC_ExistsVoltageReference( ADC_MODULE_ID index ); Description This function identifies whether the VoltageReference feature is available on the ADC module. When this function returns true, these functions are supported on the device: • PLIB_ADC_VoltageReferenceSelect Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1462 Parameters Parameters Description index Identifier for the device instance Returns • true = The VoltageReference feature is supported on the device • false = The VoltageReference feature is not supported on the device Remarks None. 5.6.1.6.10 Mux Selection and Channel Scan 5.6.1.6.10.1 PLIB_ADC_MuxAInputScanDisable Function C void PLIB_ADC_MuxAInputScanDisable( ADC_MODULE_ID index ); Description This function disables scan input for CH0+ of MUX A. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxAInputScanDisable(MY_ADC_INSTANCE); 5.6.1.6.10.2 PLIB_ADC_MuxAInputScanEnable Function C void PLIB_ADC_MuxAInputScanEnable( ADC_MODULE_ID index ); Description This function enables scan input for CH0+ of MUX A. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1463 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxInputScanControl in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxAInputScanEnable(MY_ADC_INSTANCE); 5.6.1.6.10.3 PLIB_ADC_MuxChannel0InputNegativeSelect Function C void PLIB_ADC_MuxChannel0InputNegativeSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_NEGATIVE input ); Description This function selects the negative input for channel 0 of MUX A or MUX B. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel0NegativeInput in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxChannel0InputNegativeSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_INPUT_NEGATIVE_VREF_MINUS); 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1464 5.6.1.6.10.4 PLIB_ADC_MuxChannel0InputPositiveSelect Function C void PLIB_ADC_MuxChannel0InputPositiveSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_INPUTS_POSITIVE input ); Description This function selects the positive input for channel 0 of MUX A or MUX B. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel0PositiveInput in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxChannel0InputPositiveSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_INPUT_POSITIVE_AN2); 5.6.1.6.10.5 PLIB_ADC_MuxChannel123InputNegativeSelect Function C void PLIB_ADC_MuxChannel123InputNegativeSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_CHANNEL123_INPUTS_NEG input ); Description This function selects the negative input for channels 1, 2, and 3 of MUX A or MUX B. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1465 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel123NegativeInput in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxChannel123InputNegativeSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_CHANNEL123_INPUT_NEG_CH123_VREF_MINUS); 5.6.1.6.10.6 PLIB_ADC_MuxChannel123InputPositiveSelect Function C void PLIB_ADC_MuxChannel123InputPositiveSelect( ADC_MODULE_ID index, ADC_MUX muxType, ADC_CHANNEL123_INPUTS_POS input ); Description This function selects the positive input for channels 1, 2, and 3 of MUX A or MUX B. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured muxType One of the possible values from ADC_MUX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_ADC_ExistsMuxChannel123PositiveInput in your application to determine whether this feature is available. Example // Where MY_ADC_INSTANCE, is the ADC instance selected for use by the // application developer. PLIB_ADC_MuxChannel123InputPositiveSelect(MY_ADC_INSTANCE, ADC_MUX_A, ADC_CHANNEL123_INPUT_POS_CH1_AN0_CH2_AN1_CH3_AN2); 5.6.1.7 Files Files Name Description plib_adc.h ADC PLIB interface header for definitions common to the ADC peripheral. Description 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1466 5.6.1.7.1 plib_adc.h ADC Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the ADC PLIB for all families of Microchip microcontrollers. The definitions in this file are common to the ADC peripheral. Functions Name Description PLIB_ADC_AsynchronousDedicatedSamplingDisable Disables asynchronous dedicated S&H sampling. PLIB_ADC_AsynchronousDedicatedSamplingEnable Enables asynchronous dedicated S&H sampling. PLIB_ADC_CalibrationDisable Normal ADC module operation (no calibration is performed). PLIB_ADC_CalibrationEnable Calibration is performed on the next ADC conversion. PLIB_ADC_ChannelGroupSelect Selects channels to be utilized. PLIB_ADC_ConversionClockGet Obtains the conversion clock. PLIB_ADC_ConversionClockSet Sets the ADC module conversion clock. PLIB_ADC_ConversionClockSourceSelect Selects the ADC module conversion clock source. PLIB_ADC_ConversionHasCompleted Provides the conversion completion status of the ADC. PLIB_ADC_ConversionOrderSelect Selects the conversion order. PLIB_ADC_ConversionStart Starts ADC module manual conversion process. PLIB_ADC_ConversionStopSequenceDisable Normal conversion sequence. PLIB_ADC_ConversionStopSequenceEnable Stop conversion sequence (when the first ADC module interrupt is generated). PLIB_ADC_ConversionTriggerGroupSelect Selects the conversion trigger source group. PLIB_ADC_ConversionTriggerSourceSelect Selects the conversion trigger source. PLIB_ADC_Disable ADC module is disabled (turned OFF). PLIB_ADC_DMAAddressIncrementSelect Selects the increment rate for the DMA address. PLIB_ADC_DMABufferModeSelect DMA Buffer Build mode. PLIB_ADC_DMADisable Disables the ADC Direct Memory Access (DMA). PLIB_ADC_DMAEnable Enables the ADC Direct Memory Access (DMA). PLIB_ADC_DMAInputBufferSelect Selects the number of DMA buffer locations per analog input. PLIB_ADC_Enable ADC module is enabled (turned ON). PLIB_ADC_ExistsAsynchronousDedicatedSampling Identifies whether the AsynchronousDedicatedSampling feature exists on the ADC module PLIB_ADC_ExistsCalibrationControl Identifies whether the CalibrationControl feature exists on the ADC module PLIB_ADC_ExistsChannelGroup Identifies whether the ChannelGroup feature exists on the ADC module PLIB_ADC_ExistsConversionClock Identifies whether the ConversionClock feature exists on the ADC module PLIB_ADC_ExistsConversionClockSource Identifies whether the ConversionClockSource feature exists on the ADC module PLIB_ADC_ExistsConversionControl Identifies whether the ConversionControl feature exists on the ADC module PLIB_ADC_ExistsConversionOrder Identifies whether the ConversionOrder feature exists on the ADC module PLIB_ADC_ExistsConversionStatus Identifies whether the ConversionStatus feature exists on the ADC module 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1467 PLIB_ADC_ExistsConversionStopSequenceControl Identifies whether the ConversionStopSequenceControl feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerGroup Identifies whether the ConversionTriggerGroup feature exists on the ADC module PLIB_ADC_ExistsConversionTriggerSource Identifies whether the ConversionTriggerSource feature exists on the ADC module PLIB_ADC_ExistsDMAAddressIncrement Identifies whether the DMAAddressIncrement feature exists on the ADC module PLIB_ADC_ExistsDMABufferMode Identifies whether the DMABufferMode feature exists on the ADC module PLIB_ADC_ExistsDMABuffersPerAnalogInput Identifies whether the DMABuffersPerInput feature exists on the ADC module PLIB_ADC_ExistsDMAControl Identifies whether the DMAControl feature exists on the ADC module PLIB_ADC_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADC module. PLIB_ADC_ExistsGlobalSoftwareTrigger Identifies whether the GlobalSoftwareTrigger feature exists on the ADC module PLIB_ADC_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADC module PLIB_ADC_ExistsInternalReferenceChannelControl Identifies whether the InternalReferenceChannelControl feature exists on the ADC module PLIB_ADC_ExistsISRJumpTableBaseAddress Identifies whether the ISRJumpTableBaseAddress feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0NegativeInput Identifies whether the MuxChannel0NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel0PositiveInput Identifies whether the MuxChannel0PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel123NegativeInput Identifies whether the MuxChannel123NegativeInput feature exists on the ADC module PLIB_ADC_ExistsMuxChannel123PositiveInput Identifies whether the MuxChannel123PositiveInput feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanControl Identifies whether the MuxInputScanControl feature exists on the ADC module PLIB_ADC_ExistsMuxInputScanSelect Identifies whether the MuxInputScanSelect feature exists on the ADC module PLIB_ADC_ExistsPairConversionControl Identifies whether the PairConversionControl feature exists on the ADC module PLIB_ADC_ExistsPairInterruptOnConversion Identifies whether the PairInterruptOnConversion feature exists on the ADC module PLIB_ADC_ExistsPairInterruptRequest Identifies whether the PairInterruptRequest feature exists on the ADC module PLIB_ADC_ExistsPairSampleStatus Identifies whether the PairSampleStatus feature exists on the ADC module PLIB_ADC_ExistsPairTriggerSource Identifies whether the PairTriggerSource feature exists on the ADC module PLIB_ADC_ExistsResultBufferFillStatus Identifies whether the ResultBufferFillStatus feature exists on the ADC module PLIB_ADC_ExistsResultBufferMode Identifies whether the ResultBufferMode feature exists on the ADC module PLIB_ADC_ExistsResultFormat Identifies whether the ResultFormat feature exists on the ADC module 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1468 PLIB_ADC_ExistsResultGet Identifies whether the ResultGet feature exists on the ADC module PLIB_ADC_ExistsResultGetByIndex Identifies whether the ResultGetByIndex feature exists on the ADC module PLIB_ADC_ExistsResultSign Identifies whether the ResultSign feature exists on the ADC module PLIB_ADC_ExistsResultSize Identifies whether the ResultSize feature exists on the ADC module PLIB_ADC_ExistsSampleResolution Identifies whether the SampleResolution feature exists on the ADC module PLIB_ADC_ExistsSamplesPerInterruptSelect Identifies whether the SamplesPerInterruptSelect feature exists on the ADC module PLIB_ADC_ExistsSamplingAcquisitionTime Identifies whether the SamplingAcquisitionTime feature exists on the ADC module PLIB_ADC_ExistsSamplingAutoStart Identifies whether the SamplingAutoStart feature exists on the ADC module PLIB_ADC_ExistsSamplingControl Identifies whether the SamplingControl feature exists on the ADC module PLIB_ADC_ExistsSamplingModeControl Identifies whether the SamplingModeControl feature exists on the ADC module PLIB_ADC_ExistsSamplingStatus Identifies whether the SamplingStatus feature exists on the ADC module PLIB_ADC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the ADC module PLIB_ADC_ExistsVoltageReference Identifies whether the VoltageReference feature exists on the ADC module PLIB_ADC_GlobalSoftwareTriggerSet Global software trigger enable/set control. PLIB_ADC_InputScanMaskAdd Select ADC analog channel for input scan. PLIB_ADC_InputScanMaskRemove Omits ADC analog channel for input scan. PLIB_ADC_InputSelectNegative Analog negative channel selection. PLIB_ADC_InputSelectPositive Positive analog input channel selection. PLIB_ADC_InternalReferenceChannelDisable Internal reference input is disabled. PLIB_ADC_InternalReferenceChannelEnable Internal reference input is enabled. PLIB_ADC_IsrJumpTableBaseAddressGet Gets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. PLIB_ADC_IsrJumpTableBaseAddressSet Sets the base address of the user's ADC Interrupt Service Routine (ISR) jump table. PLIB_ADC_MuxAInputScanDisable Do not scan input selections for CH0+ of MUX A. PLIB_ADC_MuxAInputScanEnable Scan input selections for CH0+ of MUX A. PLIB_ADC_MuxChannel0InputNegativeSelect Channel 0 negative input select for multiplexer setting. PLIB_ADC_MuxChannel0InputPositiveSelect Channel 0 positive input select for multiplexer setting. PLIB_ADC_MuxChannel123InputNegativeSelect Channel 1, 2, and 3 negative input select. PLIB_ADC_MuxChannel123InputPositiveSelect Channel 1, 2, and 3 positive input select. PLIB_ADC_PairConversionIsPending Informs whether conversion is pending or complete. PLIB_ADC_PairConversionStart Start conversion of the requested ADC pair. PLIB_ADC_PairInterruptAfterFirstConversion ADC pair conversion interrupt is generated after the first conversion. PLIB_ADC_PairInterruptAfterSecondConversion ADC pair conversion interrupt is generated after the second conversion. 5.6 Peripheral Library Help MPLAB Harmony Help ADC Peripheral Library 5-1469 PLIB_ADC_PairInterruptRequestDisable Disable IRQ generation for the ADC pair. PLIB_ADC_PairInterruptRequestEnable Enable IRQ generation for the ADC pair. PLIB_ADC_PairSampleIsAvailable Provides status of the ADC pair sample availability in the buffer. PLIB_ADC_PairSampleStatusClear Clears the ADC pair ready status flag. PLIB_ADC_PairTriggerSourceSelect Selects trigger source for the requested ADC pair. PLIB_ADC_ResultBufferModeSelect Selects the result buffer mode. PLIB_ADC_ResultBufferStatusGet Provides the buffer fill status. PLIB_ADC_ResultFormatSelect Selects the result format. PLIB_ADC_ResultGet Obtains the ADC sample/result value. PLIB_ADC_ResultGetByIndex Provides the ADC conversion result based on the buffer index. PLIB_ADC_ResultSignGet Obtains the ADC result sign. PLIB_ADC_ResultSizeSelect Selects the ADC module mode/result size. PLIB_ADC_SampleAcqusitionTimeSet Sets the ADC acquisition/auto-sample time in TADs. PLIB_ADC_SampleAutoStartDisable Sampling auto-start is disabled. PLIB_ADC_SampleAutoStartEnable Sampling auto-start is enabled. PLIB_ADC_SampleMaxGet Provides the maximum sample value. PLIB_ADC_SampleMinGet Provides the minimum sample value. PLIB_ADC_SamplesPerInterruptSelect Interrupts at the completion of conversion for each nth sample. PLIB_ADC_SamplingIsActive Provides the ADC sampling status. PLIB_ADC_SamplingModeSelect Enable the selected sampling mode. PLIB_ADC_SamplingStart Sampling is enabled. PLIB_ADC_SamplingStop Holding is enabled. PLIB_ADC_StopInIdleDisable Continue ADC module operation when the device is in Idle mode. PLIB_ADC_StopInIdleEnable Discontinue ADC module operation when device enters Idle mode. PLIB_ADC_VoltageReferenceSelect Voltage reference configuration. Types Name Description ADC_ACQUISITION_TIME Data type defining the different ADC acquisition times by which the ADC can be configured. ADC_CONVERSION_CLOCK Data type defines the different ADC Conversion clock ADC_SAMPLE Data type defining the size of the adc sample register. File Name plib_adc.h Company Microchip Technology Inc. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1470 5.6.2 ADCP Peripheral Library This topic describes the Pipelined Analog-to-Digital Converter peripheral library interface. Description This section contains the list of topics. 5.6.2.1 Introduction Pipelined Analog-to-Digital Converter Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Pipelined Analog-to-Digital Converter (ADCP) peripheral is used to convert an analog input into a digital number that represents that input voltage. When the input is periodically converted, the result is a sequence of digital values that have converted a continuous-time and continuous-amplitude analog signal to a discrete-time and discrete-amplitude digital signal. This particular ADC architecture is pipelined allowing it to simultaneously convert up to 6 samples, each at a different stage of conversion resulting in a low overall latency of multiple sampled inputs. The structure of the ADCP is shown in the diagram below. 1. Analog input pins connect to the sample and hold (S&H) circuits. These circuits capture the analog signal so that it can be passed to the pipeline converter. 2. The S&H circuits are controlled by predefined trigger sources. These trigger sources switch the sample and hold circuit to hold and queue the conversion of the sample. 3. Channel scan is available which allows a single trigger to start a sample/conversion sequence of multiple analog inputs using a predefined scan list. 4. A conversion clock is required for the pipeline converter. This clock determines the conversion speed and latency and effects power consumption. 5. A voltage reference is required for the pipeline converter. This voltage reference determines allowable input range of the analog signal. 6. Result registers store the conversion results and can be read by the software application. Software is notified of ready results by either polling or through the use of interrupts. 7. Optional Oversampling Digital Filters can be used to provide increased measurement accuracy at the sacrifice of sample rate. Software is notified of ready oversampling results by either polling or through the use of interrupts. 8. Optional digital comparators can be used to test conversion results independent of software and generate interrupts based on predefined conditions. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1471 5.6.2.2 Release Notes MPLAB Harmony Version: v0.70b ADCP Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.2.4 Using the Library This topic describes the basic architecture of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_adcp.h 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1472 The interface to the ADCP Peripheral library is defined in the "plib_adcp.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the Pipelined Analog to Digital Converter (ADCP) Peripheral library should include "peripheral.h". Library File: The ADCP Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.2.4.1 Hardware Abstraction Model The interface provided is a super set of all the functionality of the available Pipelined Analog-to-Digital Converter (ADCP) on the device. Refer to the specific device data sheet or related family reference manual section to determine the set of functions that are supported for each ADCP module on the device. This library provides the low-level abstraction of the ADCP module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Pipelined Analog-to-Digital Converter (ADCP) Software Abstraction Block Diagram 5.6.2.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the ADCP module. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1473 Library Interface Section Description Interface Routines - Configuration These library functions are used to configure the ADC, enable and disable it, initiate a calibration and manage low power states. Interface Routines - Status These library functions return status information related to the ADC. Interface Routines - Input Selection These library functions select and configure the ANx inputs to the ADC. Interface Routines - Channel Scan These library functions are used to configure the channel scan feature. Interface Routines - Triggering These library functions are used to configure and initiate conversion triggers. Interface Routines - Analog Input Conversion Results These library function are used to retrieve individual conversion results for ANx pins. Interface Routines - Digital Comparator These library functions are used to configure and query the digital comparators. Interface Routines - Oversampling Digital Filter These library functions are used to configure the Oversampling Digital Filter and fetch results from it. 5.6.2.4.3 How the Library Works Core Functionality Name Description Example - Simultaneous Sampling Three Class 1 Inputs Simultaneous sampling is used when the application requires capture of more than one signal at the same instance of time. Simultaneous sampling requires the use of multiple Class 1 inputs where each is assigned the same trigger source. The following example illustrates simultaneous sampling of AN0, AN1 and AN2 using the global software trigger as the trigger source. The dedicated sample and holds (S&Hs) are configured for single-ended input and a unipolar (unsigned) output. No interrupts are used so the results are polled for ready status. Example - Channel Scanning Channel scanning is used in applications where precise timing of the sample to an external source is not needed. Channel scanning allows a large number of analog inputs to be sampled and converted in sequence each time a single trigger occurs. The following example illustrates how to configure channel scanning of multiple Class 2 and Class 3 inputs using the shared S&H. This example uses inputs AN5, AN11 - AN14. AN5 and AN11 are Class 2 inputs. AN13 and AN 14 are Class 3 inputs. The global software trigger is used to initiate the scan. A 4 TAD sample time... more Other Functionality Name Description Example - Digital Oversampling Filter The Digital Oversampling filter can be used to increase resolution of the conversion result at the expense of throughput. The example below shows how two extra bits of resolution can be obtained using 16X oversampling (sixteen samples are used to create one higher resolution result). AN0 is used for the input. The sampling time for the retriggers is set to 3.5 TAD. Example: Example - Digital Comparator The Digital Comparator is used to automatically evaluate results as they are output by the converter. The following example illustrates an automated test of AN5 for values >= 80% of full scale or < 20% of full scale. A count is incremented each time an event occurs. Example: 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1474 Description Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.6.2.4.3.1 Core Functionality 5.6.2.4.3.1.1 Example - Simultaneous Sampling Three Class 1 Inputs Simultaneous sampling is used when the application requires capture of more than one signal at the same instance of time. Simultaneous sampling requires the use of multiple Class 1 inputs where each is assigned the same trigger source. The following example illustrates simultaneous sampling of AN0, AN1 and AN2 using the global software trigger as the trigger source. The dedicated sample and holds (S&Hs) are configured for single-ended input and a unipolar (unsigned) output. No interrupts are used so the results are polled for ready status. Example: int32_t results[3] ; // storage for results // This structure is used to simplify testing for a ready channel AN_READY anReady ; // Configure the ADC // AVdd/AVss reference, ADC clock is system clock (SYSCLK) divided by 8 // No need to specify sample time for class 2/3 inputs or oversampling // sample time as Class 2/3 inputs and oversampling is not used. PLIB_ADCP_Configure ( ADCP_ID_1 , ADCP_VREF_AVDD_AVSS , // AVdd and AVss as reference FALSE , // No VREF boost FALSE , // Do not use fractional format FALSE , // Do not stop in idle ADCP_CLK_SRC_SYSCLK , // SYSCLK is the clock source 4 , // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 0 , // Oversampling is not used. 0 , // No early interrupt. 0 ); // No class 2 or 3 channels are used // Set up the triggers // Configure AN0 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , ADCP_CLASS12_AN0 , ADCP_TRG_SRC_SOFTWARE ) ; // Configure AN1 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , ADCP_CLASS12_AN1 , ADCP_TRG_SRC_SOFTWARE ) ; // Configure AN2 for triggering from software. PLIB_ADCP_Class12TriggerConfigure ( ADCP_ID_1 , ADCP_CLASS12_AN2 , ADCP_TRG_SRC_SOFTWARE ) ; // Set S&H modes PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH0 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH1 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH2 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; // Enable the ADC Module PLIB_ADCP_Enable ( ADCP_ID_1 ) ; // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady ( ADCP_ID_1 )) ; while (1) 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1475 { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger ( ADCP_ID_1 ) ; // Wait for a data results to be ready // if lowest priority channel is done then all are done. do { anReady = PLIB_ADCP_ResultReady ( ADCP_ID_1 ) ; } while (anReady.AN2 == 0) ; // fetch AN0 if (anReady.AN0 == 1) results[0] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN0 ) ; // fetch AN1 if (anReady.AN1 == 1) results[1] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN1 ) ; // fetch AN2 if (anReady.AN2 == 1) results[2] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN2 ) ; } 5.6.2.4.3.1.2 Example - Channel Scanning Channel scanning is used in applications where precise timing of the sample to an external source is not needed. Channel scanning allows a large number of analog inputs to be sampled and converted in sequence each time a single trigger occurs. The following example illustrates how to configure channel scanning of multiple Class 2 and Class 3 inputs using the shared S&H. This example uses inputs AN5, AN11 - AN14. AN5 and AN11 are Class 2 inputs. AN13 and AN 14 are Class 3 inputs. The global software trigger is used to initiate the scan. A 4 TAD sample time is specified for the shared S&H. The shared S&H is configured for single-ended operation and a unipolar output. No interrupts are used so the results are polled for ready status. Example: int32_t results[5] ; // storage for results // This structure is used to simplify testing of the ready status AN_READY anReady ; // This structure is used to simplify specifying channels for scan // AN5, AN11, AN12, AN13 and AN14 are selected for scanning. AN_SELECT anSelect ; anSelect.highWord = 0 ; anSelect.lowWord = 0 ; anSelect.AN5 = 1 ; anSelect.AN11 = 1 ; anSelect.AN12 = 1 ; anSelect.AN13 = 1 ; anSelect.AN14 = 1 ; // Configure the ADC // AVdd/AVss reference, ADC clock is system clock (SYSCLK) divided by 8 // The sample for the shared S&H must be adequate for all inputs. // In this example it is set to 4 TAD. // No need to specify sample time for oversampling as it is not used. PLIB_ADCP_Configure ( ADCP_ID_1 , ADCP_VREF_AVDD_AVSS , // AVdd and AVss as reference FALSE , // No VREF boost FALSE , // Do not use fractional format FALSE , // Do not stop in idle ADCP_CLK_SRC_SYSCLK , // SYSCLK is the clock source 4 , // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1476 0 , // Oversampling is not used. 0 , // No early interrupt. 3 ) ; // 3 + 1 = 4 TAD for Class 2 and 3 // Sample Time. // Specify the inputs to include in the Channel Scan using the selections made when // initializing anSelect. Use the software trigger to initiate the scan. PLIB_ADCP_ChannelScanConfigure ( ADCP_ID_1 , anSelect.lowWord , anSelect.highWord , ADCP_SCAN_TRG_SRC_SOFTWARE ) ; // Set S&H 5 (shared S&H) to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect ( ADCP_ID_1 , ADCP_SH5 , ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR ) ; // Enable the ADC Module PLIB_ADCP_Enable ( ADCP_ID_1 ) ; // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady ( ADCP_ID_1 )) ; while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger ( ADCP_ID_1 ) ; // Wait for a data results to be ready // if lowest priority channel is done then all are done. do { anReady = PLIB_ADCP_ResultReady ( ADCP_ID_1 ) ; } while (anReady.AN14 == 0) ; // fetch AN5 if (anReady.AN5 == 1) results[0] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN5 ) ; // fetch AN11 if (anReady.AN11 == 1) results[1] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN11 ) ; // fetch AN12 if (anReady.AN12 == 1) results[2] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN12 ) ; // fetch AN13 if (anReady.AN13 == 1) results[3] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN13 ) ; // fetch AN14 if (anReady.AN14 == 1) results[4] = PLIB_ADCP_ResultGet ( ADCP_ID_1 , ADCP_AN14 ) ; } 5.6.2.4.3.2 Other Functionality 5.6.2.4.3.2.1 Example - Digital Oversampling Filter The Digital Oversampling filter can be used to increase resolution of the conversion result at the expense of throughput. The example below shows how two extra bits of resolution can be obtained using 16X oversampling (sixteen samples are used to create one higher resolution result). AN0 is used for the input. The sampling time for the retriggers is set to 3.5 TAD. Example: int32_t result; // storage for result 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1477 // Configure the ADC // AVdd/AVss reference, ADC clock is system clock (SYSCLK) divided by 8 // No need to specify sample time for Class 2/3 inputs as they are not used. // Oversampling sample time is set to 3.5 TAD. PLIB_ADCP_Configure(ADCP_ID_1, ADCP_VREF_AVDD_AVSS, // AVdd and AVss as reference FALSE, // No VREF boost FALSE, // Do not use fractional format FALSE, // Do not stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 4, // TAD = 1/SYSCLK * 2 * 4 // or ADC Clock = SYSCLK / (2 * 4) 2, // 2 + 1.5 = 3.5 TAD between // oversampling triggers 0, // No early interrupt. 0); // No Class 2 and 3 are used. // Set up the triggers // Configure AN0 for triggering from software. PLIB_ADCP_Class12TriggerConfigure(ADCP_ID_1, ADCP_CLASS12_AN0, ADCP_TRG_SRC_SOFTWARE); // Set S&H modes // Set S&H 0 to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect(ADCP_ID_1, ADCP_SH0, ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR); // Configure the Oversampling Filter PLIB_ADCP_OsampDigFilterConfig(ADCP_ID_1, // ADCP module ID ADCP_ODFLTR1, // Filter ID ADCP_AN0, // Oversample AN0 ADCP_ODFLTR_16X, // 16 x oversampling FALSE); // No Global Int Enable // Enable ODFLTR0 PLIB_ADCP_OsampDigFilterEnable(ADCP_ID_1, ADCP_ODFLTR1); // Enable the ADC Module PLIB_ADCP_Enable(ADCP_ID_1); // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady(ADCP_ID_1)); while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger(ADCP_ID_1); // Wait for data to be ready while (PLIB_ADCP_OsampDigFilterDataRdy(ADCP_ID_1, ADCP_ODFLTR1) == FALSE); // get the result result = PLIB_ADCP_OsampDigFilterDataGet(ADCP_ID_1, ADCP_ODFLTR1); } 5.6.2.4.3.2.2 Example - Digital Comparator The Digital Comparator is used to automatically evaluate results as they are output by the converter. The following example illustrates an automated test of AN5 for values >= 80% of full scale or < 20% of full scale. A count is incremented each time an event occurs. Example: int32_t result; // storage for result int32_t count = 0; 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1478 /* This structure is used to simplify testing for a ready channel */ AN_READY anReady; // Configure the ADC // AVdd/AVss reference, ADC clock is system clock (SYSCLK) divided by 8 // The sample for the shared S&H must be adequate for all inputs. // In this example it is set to 4 TAD. // No need to specify sample time for oversampling as it is not used. PLIB_ADCP_Configure(ADCP_ID_1, ADCP_VREF_AVDD_AVSS, // AVdd and AVss as reference FALSE, // No VREF boost FALSE, // Do not use fractional format FALSE, // Do not stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 4, // TAD = 1/SYSCLK * 2 * 4 or // ADC Clock = SYSCLK / (2 * 4) 0, // no oversampling 0, // No early interrupt. 3); // 3 + 1 = 4 TAD for Class 2 and 3 Sample Time. // Set up the triggers // Configure AN5 for triggering from software. PLIB_ADCP_Class12TriggerConfigure(ADCP_ID_1, ADCP_CLASS12_AN5, ADCP_TRG_SRC_SOFTWARE); // Set S&H modes // Set S&H 5 to use the single ended, unipolar mode PLIB_ADCP_SHModeSelect(ADCP_ID_1, ADCP_SH5, ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR); // Configure the Digital Comparator // Creates an event when the reading of AN5 is less than 20% or // greater than or equal to 80% of the full scale 12-bit output. PLIB_ADCP_DigCmpConfig(ADCP_ID_1, // ADCP module ID ADCP_DCMP1, // Comparator ID FALSE, // No Global Int Enable FALSE, // no test for between low and high TRUE, // test for greater than or equal to high FALSE, // no test for less than high FALSE, // no test for greater than or equal to low TRUE, // test for less than low 1 << 5, // enable AN5 for comparison 0xFFF - (0xFFF / 5), // high limit is 80% of full scale 0xFFF / 5); // low limit is 20% of full scale // Enable DigCmp1 PLIB_ADCP_DigCmpEnable(ADCP_ID_1, ADCP_DCMP1); // Enable the ADC Module PLIB_ADCP_Enable(ADCP_ID_1); // Wait for a ready status while (!PLIB_ADCP_ModuleIsReady(ADCP_ID_1)); while (1) { // Initiate a trigger PLIB_ADCP_GlobalSoftwareTrigger(ADCP_ID_1); // wait for conversion to complete do { anReady = PLIB_ADCP_ResultReady(ADCP_ID_1); } while (anReady.AN5 == 0); // Check result and increment count if an out of range event // occurred on digital comparator 1 for AN5 if (PLIB_ADCP_DigCmpAIdGet(ADCP_ID_1, ADCP_DCMP1) == 5) { count++; 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1479 } } 5.6.2.4.4 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.2.5 Library Interface Data Types Name Description ADCP_MODULE_ID Identifies the number of ADC Modules Supported. ADCP_VREF_SOURCE Data type defines the ADCP VREF Source Select ADCP_CLOCK_SOURCE Data type defines the ADCP Clock Source Select ADCP_CLASS12_INPUT_ID Type for identifying the Class 1 and Class 2 ADC Inputs ADCP_SH_ID Identifies the S&Hs supported regardless of type. ADCP_DSH_ID Identifies the Dedicated S&Hs supported ADCP_SH_MODE Data type defines the available modes for the S&H ADCP_INPUT_ID Type for identifying the available ADC Inputs ADCP_DCMP_ID Identifies the Digital Comparators supported. ADCP_ODFLTR_ID Identifies the Oversampling Digital Filter supported. ADCP_ODFLTR_OSR Identifies the Oversampling Digital Filter oversampling ratios supported. ADCP_SCAN_TRG_SRC Data type defines the ADCP Channel Scan Trigger Source Selections ADCP_TRG_SRC Data type defines the ADCP Trigger Source Selections AN_SELECT This union of structures is provided to simply selection of analog inputs for inclusion in a particular function. AN_READY This union (identical to the AN_SELECT union) is used as the return value by the PLIB_ADCP_Result_Ready() function. Interface Routines - Channel Scan Name Description PLIB_ADCP_ChannelScanConfigure Selects input to include in Channel Scan Mode PLIB_ADCP_ExistsChannelScan Identifies whether the ChannelScan feature exists on the ADCP module Interface Routines - Configuration Name Description PLIB_ADCP_Configure Configures the Pipelined ADC converter including the ADC calibration registers. PLIB_ADCP_Enable Enables the Pipelined ADC module PLIB_ADCP_Disable Pipelined ADC module is disabled (turned OFF). PLIB_ADCP_CalibrationStart Initiates Pipelined ADC Calibration. PLIB_ADCP_LowPowerStateEnter Places the Pipelined ADC module in a low power state. PLIB_ADCP_LowPowerStateExit Takes the Pipelined ADC module out of low power state and puts it into an operational mode. PLIB_ADCP_LowPowerStateGet Returns the state of the low power setting. PLIB_ADCP_ExistsCalibration Identifies whether the Calibration feature exists on the ADCP module PLIB_ADCP_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCP module 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1480 PLIB_ADCP_ExistsLowPowerControl Identifies whether the LowPowerControl feature exists on the ADCP module PLIB_ADCP_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCP module Interface Routines - Digital Comparator Name Description PLIB_ADCP_DigCmpEnable Enables the Digital Comparator in the Pipelined ADC module PLIB_ADCP_DigCmpDisable Disables the Digital Comparator in the Pipelined ADC module PLIB_ADCP_DigCmpAIdGet Returns the Analog Input ID of for the Comparator Event PLIB_ADCP_DigCmpConfig Configures the Digital Comparator on the Pipelined ADC converter. PLIB_ADCP_ExistsDigCmp Identifies whether the DigitalComparator feature exists on the ADCP module Interface Routines - Individual Analog Input Conversion Results Name Description PLIB_ADCP_ResultReady Returns the ADC conversion result ready bits for the module. PLIB_ADCP_ResultGet Returns a Pipelined ADC conversion result. PLIB_ADCP_ResultReadyGrpIntConfigure Selects input to include in global interrupt. PLIB_ADCP_ExistsConversionResults Identifies whether the ConversionResults feature exists on the ADCP module Interface Routines - Input Selection Name Description PLIB_ADCP_AlternateInputSelect Selects the alternate physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_DefaultInputSelect Selects the default physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADCP module PLIB_ADCP_ExistsModeSelect Identifies whether the ModeSelect feature exists on the ADCP module PLIB_ADCP_SHModeSelect Selects the mode for the specified S&H. Interface Routines - Oversampling Digital Filter Name Description PLIB_ADCP_OsampDigFilterEnable Enables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_OsampDigFilterDisable Disables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_OsampDigFilterDataRdy Used to determine if the Oversampling Digital Filter has data ready. PLIB_ADCP_OsampDigFilterDataGet Used to fetch the data result from the Oversampling Digital Filter. PLIB_ADCP_ExistsOsampDigFilter Identifies whether the OsampDigitalFilter feature exists on the ADCP module PLIB_ADCP_OsampDigFilterConfig Configures the Oversampling Digital Filter on the Pipelined ADC converter. Interface Routines - Status Name Description PLIB_ADCP_ModuleIsReady Returns the overall ready status of the module. PLIB_ADCP_ExistsReadyStatus Identifies whether the ReadyStatus feature exists on the ADCP module Interface Routines - Triggering Name Description PLIB_ADCP_GlobalSoftwareTrigger Initiate a Global Software Trigger on the specified module. PLIB_ADCP_IndividualTrigger Triggers an individual channel independent of the configured trigger source PLIB_ADCP_Class12TriggerConfigure Configures a Class 1 or Class 2 Trigger Source. PLIB_ADCP_ExistsTriggering Identifies whether the Triggering feature exists on the ADCP module 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1481 Description This section describes the Application Programming Interface (API) functions of the Pipelined Analog-to-Digital Converter (ADCP) Peripheral. Refer to each section for a detailed description. 5.6.2.5.1 Interface Routines - Configuration 5.6.2.5.1.1 PLIB_ADCP_Configure Function C void PLIB_ADCP_Configure( ADCP_MODULE_ID index, ADCP_VREF_SOURCE voltageRefSelect, bool boostVref, bool fractionalOutputOn, bool stopInIdle, ADCP_CLOCK_SOURCE adcClockSource, int8_t adcClockDivider, int8_t oversampleDigFilterSamTime, int8_t earlyIntEnable, int8_t class2and3SampleTime ); Description Configures all ADC parameters common to all inputs. This configuration must occur prior to enabling the ADC and therefore must be called when the ADC is disabled. Preconditions The module is disabled when calling this function. Parameters Parameters Description index Identifier for the ADCP instance voltageRefSelect VREF Source Selection boostVref Enables the VREF boost if TRUE. Use when VREFH VREFL < .64 (AVDD - AVSS) fractionalOutputOn sets output to a fractional format if TRUE stopInIdle sets ADC to stop when device is in idle mode if TRUE adcClockSource Clock source selection adcClockDivider Clock source divider. Values range from 0 to 254. oversampleDigFilterSamTime Sets the delay (sample time) between automatically generated oversampling filter triggers. Values range from 0 to 31 for 1.5 TAD to 32.5 TAD respectively. earlyIntEnable Sets the number of clocks prior to the actual arrival of data that the ADRDY bit is set. Range is 0 to 7. Used to generate an early interrupt. class2and3SampleTime Set the sample time for Class 2 and Class 3 inputs. Range is 0 to 255 for a sample time of 1 to 256 respectivley. Returns none 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1482 Remarks This function must be called when the ADC is disabled. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the ADC PLIB_ADCP_Configure( MY_ADCP_INSTANCE, ADCP_VREF_VREFP_VREFN, // VREF+ and VREF- as reference FALSE, // No VREF boost TRUE, // Use fractionl format TRUE, // Do stop in idle ADCP_CLK_SRC_SYSCLK, // SYSCLK is the clock source 3, // TAD = 1/SYSCLK * 2 * 3 // or ADC Clock = SYSCLK / (2 * 3) 2, // 2 + 1.5 = 3.5 TAD between // oversampling triggers 0, // No early interrupt. 3 ); // 3 + 1 = 4 TAD for Class 2 and 3 // Sample Time. // Enable the ADC PLIB_ADCP_Enable(MY_ADCP_INSTANCE); 5.6.2.5.1.2 PLIB_ADCP_Enable Function C void PLIB_ADCP_Enable( ADCP_MODULE_ID index ); Description This function enables (turns ON) the selected Pipelined ADC module. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance to be configured Returns None. Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_Enable(MY_ADCP_INSTANCE); 5.6.2.5.1.3 PLIB_ADCP_Disable Function C void PLIB_ADCP_Disable( ADCP_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1483 ); Description This function disables (turns OFF) the selected Pipelined ADC module. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance to be configured Returns None. Remarks Not all functionality is available on all devices. Please refer to the specific device data sheet for the list of available features. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_Disable(MY_ADCP_INSTANCE); 5.6.2.5.1.4 PLIB_ADCP_CalibrationStart Function C void PLIB_ADCP_CalibrationStart( ADCP_MODULE_ID index ); Description This function initiates calibration of the module. During calibration the module cannot perform conversion. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance to be configured Returns None. Remarks Calibration is complete when PLIB_ADCP_ModuleIsReady() returns a TRUE result. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. PLIB_ADCP_CalibrationStart(MY_ADCP_INSTANCE); while (!PLIB_ADCP_ModuleIsRead(MY_ADCP_INSTANCE)); 5.6.2.5.1.5 PLIB_ADCP_LowPowerStateEnter Function C void PLIB_ADCP_LowPowerStateEnter( 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1484 ADCP_MODULE_ID index ); Description Places the Pipelined ADC module in a low power state. The feature is used in lieu of disabling the ADC when power reduction is needed. The Pipelined ADC can come out of low power state and be operational much faster since recalibration is not required. Preconditions The Pipelined ADC must be enabled. Parameters Parameters Description index Identifier for the ADCP instance Returns None. Remarks None. Example PLIB_ADCP_LowPowerStateEnter(MY_ADCP_INSTANCE); 5.6.2.5.1.6 PLIB_ADCP_LowPowerStateExit Function C void PLIB_ADCP_LowPowerStateExit( ADCP_MODULE_ID index ); Description Takes the Pipelined ADC module out of low power state and puts it into an operational mode. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance Returns None. Remarks The first five conversions following the exit from ADC Low-power mode may be subject to lower accuracy than specified in the device data sheet. Example PLIB_ADCP_LowPowerStateExit(MY_ADCP_INSTANCE); 5.6.2.5.1.7 PLIB_ADCP_LowPowerStateGet Function C bool PLIB_ADCP_LowPowerStateGet( ADCP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1485 Description Returns the state of the low power setting. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance Returns A Boolean indicating the state of the low power setting. Remarks None. Example bool lowPowerSate = PLIB_ADCP_LowPowerStateGet(MY_ADCP_INSTANCE); 5.6.2.5.1.8 PLIB_ADCP_ExistsCalibration Function C bool PLIB_ADCP_ExistsCalibration( ADCP_MODULE_ID index ); Description This function identifies whether the Calibration feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_CalibrationStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the Calibration feature: • true - When Calibration feature is supported on the device • false - When Calibration feature is not supported on the device Remarks None. 5.6.2.5.1.9 PLIB_ADCP_ExistsEnableControl Function C bool PLIB_ADCP_ExistsEnableControl( ADCP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1486 Description This function identifies whether the EnableControl feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_Enable • PLIB_ADCP_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the EnableControl feature: • true - When EnableControl feature is supported on the device • false - When EnableControl feature is not supported on the device Remarks None. 5.6.2.5.1.10 PLIB_ADCP_ExistsLowPowerControl Function C bool PLIB_ADCP_ExistsLowPowerControl( ADCP_MODULE_ID index ); Description This function identifies whether the LowPowerControl feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_LowPowerStateEnter • PLIB_ADCP_LowPowerStateExit • PLIB_ADCP_LowPowerStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the LowPowerControl feature: • true - When LowPowerControl feature is supported on the device • false - When LowPowerControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1487 5.6.2.5.1.11 PLIB_ADCP_ExistsConfiguration Function C bool PLIB_ADCP_ExistsConfiguration( ADCP_MODULE_ID index ); Description This function identifies whether the Configuration feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_Configure Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the Configuration feature: • true - When Configuration feature is supported on the device • false - When Configuration feature is not supported on the device Remarks None. 5.6.2.5.2 Interface Routines - Status 5.6.2.5.2.1 PLIB_ADCP_ModuleIsReady Function C bool PLIB_ADCP_ModuleIsReady( ADCP_MODULE_ID index ); Description Returns the ready status of the Pipelined ADC. The ADC must be ready before operation. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance Returns boolean indicating ready status. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1488 Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable the module PLIB_ADCP_Enable(MY_ADCP_INSTANCE); // wait for calibration to complete while (!PLIB_ADCP_ModuleIsReady(MY_ADCP_INSTANCE)); // begin sampling ... 5.6.2.5.2.2 PLIB_ADCP_ExistsReadyStatus Function C bool PLIB_ADCP_ExistsReadyStatus( ADCP_MODULE_ID index ); Description This function identifies whether the ReadyStatus feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_ModuleIsReady Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the ReadyStatus feature: • true - When ReadyStatus feature is supported on the device • false - When ReadyStatus feature is not supported on the device Remarks None. 5.6.2.5.3 Interface Routines - Input Selection 5.6.2.5.3.1 PLIB_ADCP_AlternateInputSelect Function C void PLIB_ADCP_AlternateInputSelect( ADCP_MODULE_ID index, ADCP_DSH_ID id ); Description Selects the alternate physical input for the specified S&H. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1489 Preconditions The function only applies to dedicated S&Hs (Class 1 Inputs). Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated Class 1 S&H to configure for its alternate input source. Returns none. Remarks None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the alternate input. PLIB_ADCP_AlternateInputSelect(MY_ADCP_INSTANCE, ADCP_DSH1) 5.6.2.5.3.2 PLIB_ADCP_DefaultInputSelect Function C void PLIB_ADCP_DefaultInputSelect( ADCP_MODULE_ID index, ADCP_DSH_ID id ); Description Selects the default physical input for the specified S&H. Preconditions The function only applies to dedicated S&Hs (Class 1 Inputs). Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated Class 1 S&H to configure for its alternate input source. Returns none. Remarks None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the default input. PLIB_ADCP_DefaultInputSelect(MY_ADCP_INSTANCE, ADCP_DSH1) 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1490 5.6.2.5.3.3 PLIB_ADCP_ExistsInputSelect Function C bool PLIB_ADCP_ExistsInputSelect( ADCP_MODULE_ID index ); Description This function identifies whether the InputSelect feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_DedicatedSHInputSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the InputSelect feature: • true - When InputSelect feature is supported on the device • false - When InputSelect feature is not supported on the device Remarks None. 5.6.2.5.3.4 PLIB_ADCP_ExistsModeSelect Function C bool PLIB_ADCP_ExistsModeSelect( ADCP_MODULE_ID index ); Description This function identifies whether the ModeSelect feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_SHModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the ModeSelect feature: • true - When ModeSelect feature is supported on the device • false - When ModeSelect feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1491 Remarks None. 5.6.2.5.3.5 PLIB_ADCP_SHModeSelect Function C void PLIB_ADCP_SHModeSelect( ADCP_MODULE_ID index, ADCP_DSH_ID id, ADCP_SH_MODE mode ); Description Selects the mode (single ended or differential) and encoding (unipolar or two's compliment) for the specified S&H. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance id An ADCP_DSH_ID type indicating which dedicated S&H to configure to use its alternate source. mode An ADCP_SH_MODE type indicating the mode selection. Returns none. Remarks None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Set S&H 1 to use the single ended, two's complement mode // selection. PLIB_ADCP_SHModeSelect(MY_ADCP_INSTANCE, ADCP_SH1, ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP) 5.6.2.5.4 Interface Routines - Channel Scan 5.6.2.5.4.1 PLIB_ADCP_ChannelScanConfigure Function C void PLIB_ADCP_ChannelScanConfigure( ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable, ADCP_SCAN_TRG_SRC triggerSource ); Description Selects inputs, as determined by the low and high enable scan list for inclusion in the channel scan sequence. If the input is a 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1492 Class 1 or Class 2 type, it will also select the trigger source for that input to be the scan trigger, which is required if included in channel scanning. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance lowEnable bit mask for selecting low order scan channels highEnable bit mask for selecting high order scan channels triggerSource Trigger source used to initiate channel scan. Returns none. Remarks The type def AN_SELECT can be used to create a variable to simplify selection of the inputs to include in the channel scan. This typedef creates bit field structures for each ANx input that are joined with unions for the low and high 32-bit words. See the code example for Channel scan in the ADCP PLIB help documentation for deatils on its use. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure Channel Scanning // Channels 10 through 13 // Trigger on Timer 1 match. PLIB_ADCP_ChannelScanConfigure(MY_ADCP_INSTANCE, 0XF000, // AN12 - AN15 0X0F00, // AN24 - AN27 ADCP_SCAN_TRG_SRC_TMR1_MATCH) 5.6.2.5.4.2 PLIB_ADCP_ExistsChannelScan Function C bool PLIB_ADCP_ExistsChannelScan( ADCP_MODULE_ID index ); Description This function identifies whether the ChannelScan feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_ChannelScanConfigure Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the ChannelScan feature: 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1493 • true - When ChannelScan feature is supported on the device • false - When ChannelScan feature is not supported on the device Remarks None. 5.6.2.5.5 Interface Routines - Triggering 5.6.2.5.5.1 PLIB_ADCP_GlobalSoftwareTrigger Function C void PLIB_ADCP_GlobalSoftwareTrigger( ADCP_MODULE_ID index ); Description All inputs or scan list that is configured to trigger on the global software trigger are triggered. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance Returns None. Remarks None. Example PLIB_ADCP_GlobalSoftwareTrigger(MY_ADCP_INSTANCE); 5.6.2.5.5.2 PLIB_ADCP_IndividualTrigger Function C void PLIB_ADCP_IndividualTrigger( ADCP_MODULE_ID index, ADCP_INPUT_ID inputId ); Description Forces a trigger of an individual Class 1 or Class 2 channel independent of its configured trigger source. Preconditions The function only applies to Class 1 and Class 2 inputs. Parameters Parameters Description index Identifier for the ADCP instance inputId An ADCP_INPUT_ID type indicating which input to trigger. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1494 Returns none. Remarks None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Force a trigger of AN5 PLIB_ADCP_IndividualTrigger(MY_ADCP_INSTANCE, ADCP_CLASS12_AN5) 5.6.2.5.5.3 PLIB_ADCP_Class12TriggerConfigure Function C void PLIB_ADCP_Class12TriggerConfigure( ADCP_MODULE_ID index, ADCP_CLASS12_INPUT_ID inputId, ADCP_TRG_SRC triggerSource ); Description Configures the trigger source for Class 1 or Class 2 inputs. A call to this function is not required when the input is being used as part of a channel scan as the channel scan configure function also configures all trigger sources. Preconditions The function only applies to Class 1 and Class 2 inputs. Parameters Parameters Description index Identifier for the ADCP instance inputId Class 1 or Class 2 input to configure the trigger for. triggerSource Trigger source to use for this input. Returns none. Remarks None. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure AN0 for triggering from INT0. PLIB_ADCP_Class12TriggerConfigure(MY_ADCP_INSTANCE, ADCP_CLASS12_AN0, ADCP_TRG_SRC_INT0); 5.6.2.5.5.4 PLIB_ADCP_ExistsTriggering Function C bool PLIB_ADCP_ExistsTriggering( ADCP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1495 Description This function identifies whether the Triggering feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_Class12TriggerConfigure • PLIB_ADCP_GlobalSoftwareTrigger • PLIB_ADCP_IndividualTrigger Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the Triggering feature: • true - When Triggering feature is supported on the device • false - When Triggering feature is not supported on the device Remarks None. 5.6.2.5.6 Interface Routines - Individual Analog Input Conversion Results 5.6.2.5.6.1 PLIB_ADCP_ResultReady Function C AN_READY PLIB_ADCP_ResultReady( ADCP_MODULE_ID index ); Description Returns a result indicating which analog inputs have conversion results ready. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance Returns A AN_READY type indicating conversion result status. Remarks This function returns individual conversion results. It does not return results from the module. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1496 AN_READY MyRdyStatus; // check for data and process it if ((MyRdyStatus = PLIB_ADCP_ResultReady(MY_ADCP_INSTANCE)) != 0) { // fetch the results and process } 5.6.2.5.6.2 PLIB_ADCP_ResultGet Function C int32_t PLIB_ADCP_ResultGet( ADCP_MODULE_ID index, ADCP_INPUT_ID inputId ); Description Returns the specified Pipelined ADC analog input conversion result. Preconditions A valid conversion is ready to be fetched. Parameters Parameters Description index Identifier for the ADCP instance inputId Identifier for the input Returns The conversion result expressed as a 32 bit integer. Remarks None. Example int32_t result; ... // fetch result for AN31 result = PLIB_ADCP_ResultGet( MY_ADCP_INSTANCE, ADCP_AN31 ); 5.6.2.5.6.3 PLIB_ADCP_ResultReadyGrpIntConfigure Function C void PLIB_ADCP_ResultReadyGrpIntConfigure( ADCP_MODULE_ID index, uint32_t lowEnable, uint32_t highEnable ); Description Selects inputs, as determined by the input mask channel scan list for inclusion in the global or global interrupt. Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance lowEnable bit mask for selecting low order scan channels 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1497 highEnable bit mask for selecting high order scan channels Returns none. Remarks The type def AN_SELECT can be used to create a variable to simplify selection of the inputs to include in the global interrupt. This typedef creates bit field structures for each ANx input that are joined with unions for the low and high 32-bit words. See the code example for Channel scan in the ADCP PLIB help documentation for deatils on its use. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure Global Interrupts // Analog inputs 10 through 13 are included in the global interrupt. PLIB_ADCP_ResultReadyGrpIntConfigure(MY_ADCP_INSTANCE, 0x0F00, // inputs AN8 - AN11 0x000F ); // inputs AN16 - AN19 5.6.2.5.6.4 PLIB_ADCP_ExistsConversionResults Function C bool PLIB_ADCP_ExistsConversionResults( ADCP_MODULE_ID index ); Description This function identifies whether the ConversionResults feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_ResultReady • PLIB_ADCP_ResultGet • PLIB_ADCP_ResultReadyGrpIntConfigure Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the ConversionResults feature: • true - When ConversionResults feature is supported on the device • false - When ConversionResults feature is not supported on the device Remarks None. 5.6.2.5.7 Interface Routines - Digital Comparator 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1498 5.6.2.5.7.1 PLIB_ADCP_DigCmpEnable Function C void PLIB_ADCP_DigCmpEnable( ADCP_MODULE_ID index, ADCP_DCMP_ID id ); Description This function enables (turns ON) the selected Digital Comparator in the specified Pipelined ADC module. Preconditions The digital comparator should be configured using the PLIB_ADCP_Configure() function prior to enabling. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module. Returns None. Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable Digital Comparator 1 PLIB_ADCP_DigCmpEnable(MY_ADCP_INSTANCE, ADCP_DCMP1); 5.6.2.5.7.2 PLIB_ADCP_DigCmpDisable Function C void PLIB_ADCP_DigCmpDisable( ADCP_MODULE_ID index, ADCP_DCMP_ID id ); Description This function Disables (turns OFF) the selected Digital Comparator in the specified Pipelined ADC module. Preconditions none. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module. Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1499 Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Disable Digital Comparator 1 PLIB_ADCP_DigCmpDisable(MY_ADCP_INSTANCE, ADCP_DCMP1); 5.6.2.5.7.3 PLIB_ADCP_DigCmpAIdGet Function C int16_t PLIB_ADCP_DigCmpAIdGet( ADCP_MODULE_ID index, ADCP_DCMP_ID id ); Description This function tests the DigCmp Event Flag and if true, returns the ANx Identifier for the input which caused the event or -1 if there was no pending DigCmp event. The ID value returned corresponds to numeric portion of the analog input ID, ANx. Preconditions none. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in the ADCP module. Returns Value x of type int16_t where x is the index to the analog input ANx which caused the event or -1 if no event has occured. Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. int16_t DigCmpResult; // Get Digital Comparator 1 result. DigCmpResult = PLIB_ADCP_DigCmpAIdGet(MY_ADCP_INSTANCE, ADCP_DCMP1); if (DigCmpResult != -1) { // process event } 5.6.2.5.7.4 PLIB_ADCP_DigCmpConfig Function C void PLIB_ADCP_DigCmpConfig( ADCP_MODULE_ID index, ADCP_DCMP_ID id, bool globalIntEnable, bool inBetweenOrEqual, bool greaterEqualHi, bool lessThanHi, bool greaterEqualLo, 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1500 bool lessThanLo, uint32_t inputEnable, int32_t hiLimit, int32_t loLimit ); Description Configures all parameters for the Digital Comparator module of the pipelined ADC. Preconditions The module is disabled when calling this function. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital comparator in this device globalIntEnable When set, comparator events are included in the Global Interrupt inBetweenOrEqual Event is generated when result is greater than or equal to loLimit and less than hiLimit greaterEqualHi Event is generated when result is greater than or equal to hiLimit lessThanHi Event is generated when result is less than hiLimit greaterEqualLo Event is generated when result is greater than or equal to loLimit lessThanLo Event is generated when result is less than loLimit inputEnable Bit field which determines which analog inputs are tested by this comparator module. Bit 0 applies to AN0 and bit 31 to AN31. hiLimit High limit in the same format as the conversion result. loLimit Low limit in the same format as the conversion result. Returns none Remarks This function must be called when the ADC is disabled. The format of hiLimit and loLimit must match the output format of the channel(s) specified in inputEnable. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the Digital Comparator // Creates an event when the reading of AN0 is between 20% to 80% of the // full scale 12-bit output. PLIB_ADCP_DigCmpConfig( MY_ADCP_INSTANCE, // ADCP module ID ADCP_DCMP1, // Comparator ID FALSE, // Global Int Enable TRUE, // test for between low and high FALSE, // no test for greater then equal to high FALSE, // no test for less than high FALSE, // no test for greater then equal to low FALSE, // no test for less than low 1 << 3, // enable AN3 0x0CCD, // high limit, 80% of full scale 0x0333); // low limit, 20% of full scale // Enable Digital Comparator 1 PLIB_ADCP_DigCmpEnable(MY_ADCP_INSTANCE, ADCP_DCMP1); 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1501 5.6.2.5.7.5 PLIB_ADCP_ExistsDigCmp Function C bool PLIB_ADCP_ExistsDigCmp( ADCP_MODULE_ID index ); Description This function identifies whether the DigitalComparator feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_DigCmpConfig • PLIB_ADCP_DigCmpEnable • PLIB_ADCP_DigCmpDisable • PLIB_ADCP_DigCmpAIdGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the DigitalComparator feature: • true - When DigitalComparator feature is supported on the device • false - When DigitalComparator feature is not supported on the device Remarks None. 5.6.2.5.8 Interface Routines - Oversampling Digital Filter 5.6.2.5.8.1 PLIB_ADCP_OsampDigFilterEnable Function C void PLIB_ADCP_OsampDigFilterEnable( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ); Description This function enables (turns ON) the selected Oversampling Digital Filter in the specified Pipelined ADC module. Preconditions The Oversampling Digital Filter should be configured using the PLIB_ADCP_Configure() function prior to enabling. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in the ADCP module. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1502 Returns None. Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Enable OsampDigFilter1 PLIB_ADCP_OsampDigFilterEnable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); 5.6.2.5.8.2 PLIB_ADCP_OsampDigFilterDisable Function C void PLIB_ADCP_OsampDigFilterDisable( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ); Description This function Disables (turns OFF) the selected Oversampling Digital Filter in the specified Pipelined ADC module. Preconditions none. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in the ADCP module. Returns None. Remarks None Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Disable OsampDigFilter1 PLIB_ADCP_OsampDigFilterDisable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); 5.6.2.5.8.3 PLIB_ADCP_OsampDigFilterDataRdy Function C bool PLIB_ADCP_OsampDigFilterDataRdy( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ); Description Used to determine if the ADCP digital filter has data ready. A TRUE is returned when data is available which can be fetched using PLIB_ADCP_OsampDigFilterDataGet() 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1503 Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance id Identifier for the digital Filter in this device Returns A boolean TRUE if data is ready or FALSE if not. . Remarks None. Example if (PLIB_ADCP_OsampDigFilterDataRdy(MY_ADCP_INSTANCE, ADCP_ODFLTR_ID_0)) { // fetch and process data } 5.6.2.5.8.4 PLIB_ADCP_OsampDigFilterDataGet Function C int16_t PLIB_ADCP_OsampDigFilterDataGet( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id ); Description This function is used to fetch data from the Oversampling Digital Filter. The format of the data is determined by the oversampling setting configuration defined in the call of PLIB_ADCP_OsampDigFilterConfig(). Preconditions None. Parameters Parameters Description index Identifier for the ADCP instance dfltrID Identifier for the digital Filter in this device Returns A 16 bit result in the format specified by the filter's oversampling setting Remarks None. Example int16_t myODFLTRResult; if (PLIB_ADCP_OsampDigFilterDataRdy(MY_ADCP_INSTANCE, ADCP_ODFLTR1)) { // fetch data myODFLTRResult = PLIB_ADCP_OsampDigFilterDataGet(MY_ADCP_INSTANCE, ADCP_ODFLTR1); // process result ... } 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1504 5.6.2.5.8.5 PLIB_ADCP_ExistsOsampDigFilter Function C bool PLIB_ADCP_ExistsOsampDigFilter( ADCP_MODULE_ID index ); Description This function identifies whether the OsampDigitalFilter feature is available on the ADCP module. When this function returns true, these functions are supported on the device: • PLIB_ADCP_OsampDigFilterConfig • PLIB_ADCP_OsampDigFilterEnable • PLIB_ADCP_OsampDigFilterDisable • PLIB_ADCP_OsampDigFilterDataRdy • PLIB_ADCP_OsampDigFilterDataGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the OsampDigitalFilter feature: • true - When OsampDigitalFilter feature is supported on the device • false - When OsampDigitalFilter feature is not supported on the device Remarks None. 5.6.2.5.8.6 PLIB_ADCP_OsampDigFilterConfig Function C void PLIB_ADCP_OsampDigFilterConfig( ADCP_MODULE_ID index, ADCP_ODFLTR_ID id, ADCP_INPUT_ID inputId, ADCP_ODFLTR_SAMPLE_RATIO oversampleRatio, bool globalIntEnable ); Description Configures all parameters for the Oversampling Digital Filter module of the pipelined ADC. Preconditions The Oversampling Digital Filter module is disabled when calling this function. Parameters Parameters Description index Identifier for the ADCP instance 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1505 id Identifier for the digital Filter in this device inputId Identifier for the analog input to be oversampled oversampleRatio Enumerator specifying the oversampling ratio globalIntEnable When set, Filter events are included in the Global Interrupt Returns none Remarks This function must be called when the ADC is disabled. Example // Where MY_ADCP_INSTANCE, is the ADCP instance selected for use by the // application developer. // Configure the Oversampling Digital Filter // AN4 is oversampled at a 16X rate. No global interrupt is enabled. PLIB_ADCP_OsampDigFilterConfig( MY_ADCP_INSTANCE, // ADCP module ID ADCP_ODFLTR1, // Filter ID ADCP_AN4, // Oversample AN4 ADCP_ODFLTR_16X, // 16 x oversampling FALSE ); // No Global Int Enable // Enable OsampDigFilter1 PLIB_ADCP_OsampDigFilterEnable(MY_ADCP_INSTANCE, ADCP_ODFLTR1); 5.6.2.5.9 Data Types 5.6.2.5.9.1 ADCP_MODULE_ID Enumeration C typedef enum { ADCP_ID_1, ADC_NUMBER_OF_MODULES } ADCP_MODULE_ID; Description ADC Module ID This enumeration identifies the available ADC modules. Members Members Description ADCP_ID_1 ADC Module 1 ID ADC_NUMBER_OF_MODULES Number of available ADC modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1506 5.6.2.5.9.2 ADCP_VREF_SOURCE Enumeration C typedef enum { ADCP_VREF_AVDD_AVSS, ADCP_VREF_VREFP_AVSS, ADCP_VREF_AVDD_VREFN, ADCP_VREF_VREFP_VREFN } ADCP_VREF_SOURCE; Description ADCP VREF Source Select This data type defines the ADCP Reference Voltage (VREF) Source Select Members Members Description ADCP_VREF_AVDD_AVSS Reference voltage set to AVDD and AVSS ADCP_VREF_VREFP_AVSS Reference voltage set to VREF positive and AVSS ADCP_VREF_AVDD_VREFN Reference voltage set to AVDD and VREF negative ADCP_VREF_VREFP_VREFN Reference voltage set to VREF positive and VREF negative Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.3 ADCP_CLOCK_SOURCE Enumeration C typedef enum { ADCP_CLK_SRC_NONE, ADCP_CLK_SRC_SYSCLK, ADCP_CLK_SRC_RFCLK3, ADCP_CLK_SRC_FRC } ADCP_CLOCK_SOURCE; Description ADCP Clock Source Select This enumeration data type defines the ADCP Clock Source Select Members Members Description ADCP_CLK_SRC_NONE TAD clock disabled ADCP_CLK_SRC_SYSCLK TAD clock set to SYSCLK (TCY) ADCP_CLK_SRC_RFCLK3 TAD clock set to REFCLK3 ADCP_CLK_SRC_FRC TAD clock set to FRC Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.4 ADCP_CLASS12_INPUT_ID Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1507 ADCP_CLASS12_AN0, ADCP_CLASS12_AN1, ADCP_CLASS12_AN2, ADCP_CLASS12_AN3, ADCP_CLASS12_AN4, ADCP_CLASS12_AN5, ADCP_CLASS12_AN6, ADCP_CLASS12_AN7, ADCP_CLASS12_AN8, ADCP_CLASS12_AN9, ADCP_CLASS12_AN10, ADCP_CLASS12_AN11 } ADCP_CLASS12_INPUT_ID; Description ADC Class 1 and Class 2 Input ID Used to identify the Class 1 and Class 2 ADC analog inputs Members Members Description ADCP_CLASS12_AN0 Analog Input AN0 ADCP_CLASS12_AN1 Analog Input AN1 ADCP_CLASS12_AN2 Analog Input AN2 ADCP_CLASS12_AN3 Analog Input AN3 ADCP_CLASS12_AN4 Analog Input AN4 ADCP_CLASS12_AN5 Analog Input AN5 ADCP_CLASS12_AN6 Analog Input AN6 ADCP_CLASS12_AN7 Analog Input AN7 ADCP_CLASS12_AN8 Analog Input AN8 ADCP_CLASS12_AN9 Analog Input AN9 ADCP_CLASS12_AN10 Analog Input AN10 ADCP_CLASS12_AN11 Analog Input AN11 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.5 ADCP_SH_ID Enumeration C typedef enum { ADCP_SH0, ADCP_SH1, ADCP_SH2, ADCP_SH3, ADCP_SH4, ADCP_SH5, ADCP_NUMBER_OF_SH } ADCP_SH_ID; Description ADCP S&H Select This enumeration identifies all supported S&Hs. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1508 Members Members Description ADCP_SH0 S&H 0 ADCP_SH1 S&H 1 ADCP_SH2 S&H 2 ADCP_SH3 S&H 3 ADCP_SH4 S&H 4 ADCP_SH5 S&H 5 ADCP_NUMBER_OF_SH Number of S&Hs Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.6 ADCP_DSH_ID Enumeration C typedef enum { ADCP_DSH0, ADCP_DSH1, ADCP_DSH2, ADCP_DSH3, ADCP_DSH4, ADCP_NUMBER_OF_DSH } ADCP_DSH_ID; Description ADCP Dedicated S&H Select This enumeration identifies the supported Dedicated S&Hs. Members Members Description ADCP_DSH0 Dedicated S&H 0 ADCP_DSH1 Dedicated S&H 1 ADCP_DSH2 Dedicated S&H 2 ADCP_DSH3 Dedicated S&H 3 ADCP_DSH4 Dedicated S&H 4 ADCP_NUMBER_OF_DSH Number of Dedicated S&Hs Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.7 ADCP_SH_MODE Enumeration C typedef enum { ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR, ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP, ADCP_SH_MODE_DIFFERENTIAL_UNIPOLAR, ADCP_SH_MODE_DIFFERENTIAL_TWOS_COMP } ADCP_SH_MODE; 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1509 Description ADCP S&H Mode Data type defines the available modes for the S&H Members Members Description ADCP_SH_MODE_SINGLE_ENDED_UNIPOLAR Sinlge Ended input, Unipolar encoded ADCP_SH_MODE_SINGLE_ENDED_TWOS_COMP Sinlge Ended input, two's compliment encoded ADCP_SH_MODE_DIFFERENTIAL_UNIPOLAR Differential input, Unipolar encoded ADCP_SH_MODE_DIFFERENTIAL_TWOS_COMP Differential input, two's compliment encoded Remarks None 5.6.2.5.9.8 ADCP_INPUT_ID Enumeration C typedef enum { ADCP_AN0, ADCP_AN1, ADCP_AN2, ADCP_AN3, ADCP_AN4, ADCP_AN5, ADCP_AN6, ADCP_AN7, ADCP_AN8, ADCP_AN9, ADCP_AN10, ADCP_AN11, ADCP_AN12, ADCP_AN13, ADCP_AN14, ADCP_AN15, ADCP_AN16, ADCP_AN17, ADCP_AN18, ADCP_AN19, ADCP_AN20, ADCP_AN21, ADCP_AN22, ADCP_AN23, ADCP_AN24, ADCP_AN25, ADCP_AN26, ADCP_AN27, ADCP_AN28, ADCP_AN29, ADCP_AN30, ADCP_AN31, ADCP_AN32, ADCP_AN33, ADCP_AN34, ADCP_AN35, ADCP_AN36, ADCP_AN37, ADCP_AN38, ADCP_AN39, ADCP_AN40, 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1510 ADCP_AN41, ADCP_AN42, ADCP_AN43, ADCP_AN44, ADCP_AN45, ADCP_AN46, ADCP_AN47, ADCP_AN48, ADCP_AN49, ADCP_AN50, ADCP_AN51, ADCP_AN52, ADCP_AN53, ADCP_AN54, ADCP_AN55, ADCP_AN56, ADCP_AN57, ADCP_AN58, ADCP_AN59, ADCP_AN60, ADCP_AN61, ADCP_AN62, ADCP_AN63, ADCP_IVREF, ADCP_IVTEMP } ADCP_INPUT_ID; Description ADC Input ID Type for identifying the available ADC Inputs, regardless of Class. Members Members Description ADCP_AN0 Analog Input AN0 ADCP_AN1 Analog Input AN1 ADCP_AN2 Analog Input AN2 ADCP_AN3 Analog Input AN3 ADCP_AN4 Analog Input AN4 ADCP_AN5 Analog Input AN5 ADCP_AN6 Analog Input AN6 ADCP_AN7 Analog Input AN7 ADCP_AN8 Analog Input AN8 ADCP_AN9 Analog Input AN9 ADCP_AN10 Analog Input AN10 ADCP_AN11 Analog Input AN11 ADCP_AN12 Analog Input AN12 ADCP_AN13 Analog Input AN13 ADCP_AN14 Analog Input AN14 ADCP_AN15 Analog Input AN15 ADCP_AN16 Analog Input AN16 ADCP_AN17 Analog Input AN17 ADCP_AN18 Analog Input AN18 ADCP_AN19 Analog Input AN19 ADCP_AN20 Analog Input AN20 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1511 ADCP_AN21 Analog Input AN21 ADCP_AN22 Analog Input AN22 ADCP_AN23 Analog Input AN23 ADCP_AN24 Analog Input AN24 ADCP_AN25 Analog Input AN25 ADCP_AN26 Analog Input AN26 ADCP_AN27 Analog Input AN27 ADCP_AN28 Analog Input AN28 ADCP_AN29 Analog Input AN29 ADCP_AN30 Analog Input AN30 ADCP_AN31 Analog Input AN31 ADCP_AN32 Analog Input AN32 ADCP_AN33 Analog Input AN33 ADCP_AN34 Analog Input AN34 ADCP_AN35 Analog Input AN35 ADCP_AN36 Analog Input AN36 ADCP_AN37 Analog Input AN37 ADCP_AN38 Analog Input AN38 ADCP_AN39 Analog Input AN39 ADCP_AN40 Analog Input AN40 ADCP_AN41 Analog Input AN41 ADCP_AN42 Analog Input AN42 ADCP_AN43 Analog Input AN43 ADCP_AN44 Analog Input AN44 ADCP_AN45 Analog Input AN45 ADCP_AN46 Analog Input AN46 ADCP_AN47 Analog Input AN47 ADCP_AN48 Analog Input AN48 ADCP_AN49 Analog Input AN49 ADCP_AN50 Analog Input AN50 ADCP_AN51 Analog Input AN51 ADCP_AN52 Analog Input AN52 ADCP_AN53 Analog Input AN53 ADCP_AN54 Analog Input AN54 ADCP_AN55 Analog Input AN55 ADCP_AN56 Analog Input AN56 ADCP_AN57 Analog Input AN57 ADCP_AN58 Analog Input AN58 ADCP_AN59 Analog Input AN59 ADCP_AN60 Analog Input AN60 ADCP_AN61 Analog Input AN61 ADCP_AN62 Analog Input AN62 ADCP_AN63 Analog Input AN63 ADCP_IVREF Analog Input for Internal Voltage Reference ADCP_IVTEMP Analog Input for Internal Temperature Sensor 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1512 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.9 ADCP_DCMP_ID Enumeration C typedef enum { ADCP_DCMP1, ADCP_DCMP2, ADCP_DCMP3, ADCP_DCMP4, ADCP_DCMP5, ADCP_DCMP6, ADCP_NUMBER_OF_DCMP } ADCP_DCMP_ID; Description ADCP Digital Comparator This enumeration identifies all supported digital comparators for this ADCP module. Members Members Description ADCP_DCMP1 DCMP1 ADCP_DCMP2 DCMP2 ADCP_DCMP3 DCMP3 ADCP_DCMP4 DCMP4 ADCP_DCMP5 DCMP5 ADCP_DCMP6 DCMP6 ADCP_NUMBER_OF_DCMP Number of Digital Comparators Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.10 ADCP_ODFLTR_ID Enumeration C typedef enum { ADCP_ODFLTR1, ADCP_ODFLTR2, ADCP_ODFLTR3, ADCP_ODFLTR4, ADCP_ODFLTR5, ADCP_ODFLTR6, ADCP_NUMBER_OF_ODFLTR } ADCP_ODFLTR_ID; Description ADCP Oversampling Digital Filter This enumeration identifies all supported digital Filters for this ADCP module. Members Members Description ADCP_ODFLTR1 ODFLTR1 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1513 ADCP_ODFLTR2 ODFLTR2 ADCP_ODFLTR3 ODFLTR3 ADCP_ODFLTR4 ODFLTR4 ADCP_ODFLTR5 ODFLTR5 ADCP_ODFLTR6 ODFLTR6 ADCP_NUMBER_OF_ODFLTR Number of Oversampling Digital Filters Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.11 ADCP_ODFLTR_OSR Enumeration C typedef enum { ADCP_ODFLTR_4X, ADCP_ODFLTR_16X, ADCP_ODFLTR_64X, ADCP_ODFLTR_256X, ADCP_ODFLTR_2X, ADCP_ODFLTR_8X, ADCP_ODFLTR_32X, ADCP_ODFLTR_128X } ADCP_ODFLTR_OSR; Description ADCP Oversampling Ratio ADCP Oversampling Digital Filter oversampling Ratio This enumeration identifies all supported digital Filter oversampling ratios for this ADCP module. Oversampling ratios determine the number of samples used to generate a single output and the resulting resolution and format. Members Members Description ADCP_ODFLTR_4X 4x oversampling, shift sum 1 bit to right, output data is 13 bits ADCP_ODFLTR_16X 16x oversampling, shift sum 2 bits to right, output data is 14 bits ADCP_ODFLTR_64X 64x oversampling, shift sum 3 bits to right, output data is 15 bits ADCP_ODFLTR_256X 256x oversampling, shift sum 4 bits to right, output data is 16 bits ADCP_ODFLTR_2X 2x oversampling, shift sum 0 bits to right, output data is in 12.1 format ADCP_ODFLTR_8X 8x oversampling, shift sum 1 bit to right, output data is in 13.1 format ADCP_ODFLTR_32X 32x oversampling, shift sum 2 bits to right, output data is in 14.1 format ADCP_ODFLTR_128X 128x oversampling, shift sum 3 bit to right, output data is in 15.1 format Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.12 ADCP_SCAN_TRG_SRC Enumeration C typedef enum { ADCP_SCAN_TRG_SRC_NONE, ADCP_SCAN_TRG_SRC_SOFTWARE, ADCP_SCAN_TRG_SRC_INT0, ADCP_SCAN_TRG_SRC_TMR1_MATCH, 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1514 ADCP_SCAN_TRG_SRC_TMR3_MATCH, ADCP_SCAN_TRG_SRC_TMR5_MATCH, ADCP_SCAN_TRG_SRC_OCMP1, ADCP_SCAN_TRG_SRC_OCMP3, ADCP_SCAN_TRG_SRC_OCMP5, ADCP_SCAN_TRG_SRC_COMP1_COUT, ADCP_SCAN_TRG_SRC_COMP2_COUT } ADCP_SCAN_TRG_SRC; Description ADCP Channel Scan Trigger Source Select This data type defines the ADCP Channel Scan Trigger Source Selections Members Members Description ADCP_SCAN_TRG_SRC_NONE No scan trigger source is selected ADCP_SCAN_TRG_SRC_SOFTWARE Global Software trigger selected as scan trigger source ADCP_SCAN_TRG_SRC_INT0 Interrupt 0 (INT0) selected as scan trigger source ADCP_SCAN_TRG_SRC_TMR1_MATCH Timer 1 Match (TMR1) selected as scan trigger source ADCP_SCAN_TRG_SRC_TMR3_MATCH Timer 3 Match (TMR3) selected as scan trigger source ADCP_SCAN_TRG_SRC_TMR5_MATCH Timer 5 Match (TMR5) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP1 Output Compare 1 (OCMP1) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP3 Output Compare 3 (OCMP3) selected as scan trigger source ADCP_SCAN_TRG_SRC_OCMP5 Output Compare 5 (OCMP5) selected as scan trigger source ADCP_SCAN_TRG_SRC_COMP1_COUT Analog Comparator 1 (COUT) selected as scan trigger source ADCP_SCAN_TRG_SRC_COMP2_COUT Analog Comparator 2 (COUT) selected as scan trigger source Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.13 ADCP_TRG_SRC Enumeration C typedef enum { ADCP_TRG_SRC_NONE, ADCP_TRG_SRC_SOFTWARE, ADCP_TRG_SRC_SCAN_TRG, ADCP_TRG_SRC_INT0, ADCP_TRG_SRC_TMR1_MATCH, ADCP_TRG_SRC_TMR3_MATCH, ADCP_TRG_SRC_TMR5_MATCH, ADCP_TRG_SRC_OCMP1, ADCP_TRG_SRC_OCMP3, ADCP_TRG_SRC_OCMP5, ADCP_TRG_SRC_COMP1_COUT, ADCP_TRG_SRC_COMP2_COUT } ADCP_TRG_SRC; Description ADCP Trigger Source Select This data type defines the ADCP Trigger Source Selections 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1515 Members Members Description ADCP_TRG_SRC_NONE No trigger source is selected ADCP_TRG_SRC_SOFTWARE Global Software trigger selected as the trigger source ADCP_TRG_SRC_SCAN_TRG Use the Channel Scan Trigger as the trigger source (input is part of ch scan) ADCP_TRG_SRC_INT0 Interrupt 0 (INT0) selected as the trigger source ADCP_TRG_SRC_TMR1_MATCH Timer 1 Match (TMR1) selected as the trigger source ADCP_TRG_SRC_TMR3_MATCH Timer 3 Match (TMR3) selected as the trigger source ADCP_TRG_SRC_TMR5_MATCH Timer 5 Match (TMR5) selected as the trigger source ADCP_TRG_SRC_OCMP1 Output Compare 1 (OCMP1) selected as the trigger source ADCP_TRG_SRC_OCMP3 Output Compare 3 (OCMP3) selected as the trigger source ADCP_TRG_SRC_OCMP5 Output Compare 5 (OCMP5) selected as the trigger source ADCP_TRG_SRC_COMP1_COUT Analog Comparator 1 (COUT) selected as the trigger source ADCP_TRG_SRC_COMP2_COUT Analog Comparator 2 (COUT) selected as the trigger source Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.2.5.9.14 AN_SELECT Union C union AN_SELECT { int ret_val; struct { uint32_t lowWord; uint32_t highWord; }; struct { uint32_t AN0 : 1; uint32_t AN1 : 1; uint32_t AN2 : 1; uint32_t AN3 : 1; uint32_t AN4 : 1; uint32_t AN5 : 1; uint32_t AN6 : 1; uint32_t AN7 : 1; uint32_t AN8 : 1; uint32_t AN9 : 1; uint32_t AN10 : 1; uint32_t AN11 : 1; uint32_t AN12 : 1; uint32_t AN13 : 1; uint32_t AN14 : 1; uint32_t AN15 : 1; uint32_t AN16 : 1; uint32_t AN17 : 1; uint32_t AN18 : 1; uint32_t AN19 : 1; uint32_t AN20 : 1; uint32_t AN21 : 1; uint32_t AN22 : 1; uint32_t AN23 : 1; uint32_t AN24 : 1; uint32_t AN25 : 1; uint32_t AN26 : 1; uint32_t AN27 : 1; uint32_t AN28 : 1; 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1516 uint32_t AN29 : 1; uint32_t AN30 : 1; uint32_t AN31 : 1; uint32_t AN32 : 1; uint32_t AN33 : 1; uint32_t AN34 : 1; uint32_t AN35 : 1; uint32_t AN36 : 1; uint32_t AN37 : 1; uint32_t AN38 : 1; uint32_t AN39 : 1; uint32_t AN40 : 1; uint32_t AN41 : 1; uint32_t AN42 : 1; uint32_t AN43 : 1; uint32_t AN44 : 1; uint32_t AN45 : 1; uint32_t AN46 : 1; uint32_t AN47 : 1; uint32_t AN48 : 1; uint32_t AN49 : 1; uint32_t AN50 : 1; uint32_t AN51 : 1; uint32_t AN52 : 1; uint32_t AN53 : 1; uint32_t AN54 : 1; uint32_t AN55 : 1; uint32_t AN56 : 1; uint32_t AN57 : 1; uint32_t AN58 : 1; uint32_t AN59 : 1; uint32_t AN60 : 1; uint32_t AN61 : 1; uint32_t AN62 : 1; uint32_t AN63 : 1; }; }; Description ADCP AN Select Union Structure labels identify the analog inputs associated with each bit when initializing the structure. Unsigned 32 bit integers, lowWord and highWord are used as arguments to the function. Remarks See the Channel Scanning example in the ADCP Help documentation regarding use of this type define. 5.6.2.5.9.15 AN_READY Type C typedef AN_SELECT AN_READY; Description ADCP AN Ready Union Structure labels identify the analog inputs associated with each bit for testing ready status of individual inputs. Unsigned 32 bit integers, lowWord and highWord allow for testing ready status of groups of bits using a mask. Remarks See the Simultaneous Sampling or Channel Scanning examples in the ADCP Help documentation regarding use of this type define. 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1517 5.6.2.6 Files Files Name Description plib_adcp.h ADCP PLIB Interface Header for ADCP common definitions Description 5.6.2.6.1 plib_adcp.h ADCP - Analog to Digital Converter, Pipelined Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the ADCP PLIB for all families of Microchip microcontrollers..The definitions in this file are common to ADCP peripheral. Functions Name Description PLIB_ADCP_AlternateInputSelect Selects the alternate physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_CalibrationStart Initiates Pipelined ADC Calibration. PLIB_ADCP_ChannelScanConfigure Selects input to include in Channel Scan Mode PLIB_ADCP_Class12TriggerConfigure Configures a Class 1 or Class 2 Trigger Source. PLIB_ADCP_Configure Configures the Pipelined ADC converter including the ADC calibration registers. PLIB_ADCP_DefaultInputSelect Selects the default physical input for the specified dedicated (Class 1) S&H. PLIB_ADCP_DigCmpAIdGet Returns the Analog Input ID of for the Comparator Event PLIB_ADCP_DigCmpConfig Configures the Digital Comparator on the Pipelined ADC converter. PLIB_ADCP_DigCmpDisable Disables the Digital Comparator in the Pipelined ADC module PLIB_ADCP_DigCmpEnable Enables the Digital Comparator in the Pipelined ADC module PLIB_ADCP_Disable Pipelined ADC module is disabled (turned OFF). PLIB_ADCP_Enable Enables the Pipelined ADC module PLIB_ADCP_ExistsCalibration Identifies whether the Calibration feature exists on the ADCP module PLIB_ADCP_ExistsChannelScan Identifies whether the ChannelScan feature exists on the ADCP module PLIB_ADCP_ExistsConfiguration Identifies whether the Configuration feature exists on the ADCP module PLIB_ADCP_ExistsConversionResults Identifies whether the ConversionResults feature exists on the ADCP module PLIB_ADCP_ExistsDigCmp Identifies whether the DigitalComparator feature exists on the ADCP module PLIB_ADCP_ExistsEnableControl Identifies whether the EnableControl feature exists on the ADCP module PLIB_ADCP_ExistsInputSelect Identifies whether the InputSelect feature exists on the ADCP module PLIB_ADCP_ExistsLowPowerControl Identifies whether the LowPowerControl feature exists on the ADCP module PLIB_ADCP_ExistsModeSelect Identifies whether the ModeSelect feature exists on the ADCP module PLIB_ADCP_ExistsOsampDigFilter Identifies whether the OsampDigitalFilter feature exists on the ADCP module 5.6 Peripheral Library Help MPLAB Harmony Help ADCP Peripheral Library 5-1518 PLIB_ADCP_ExistsReadyStatus Identifies whether the ReadyStatus feature exists on the ADCP module PLIB_ADCP_ExistsTriggering Identifies whether the Triggering feature exists on the ADCP module PLIB_ADCP_GlobalSoftwareTrigger Initiate a Global Software Trigger on the specified module. PLIB_ADCP_IndividualTrigger Triggers an individual channel independent of the configured trigger source PLIB_ADCP_LowPowerStateEnter Places the Pipelined ADC module in a low power state. PLIB_ADCP_LowPowerStateExit Takes the Pipelined ADC module out of low power state and puts it into an operational mode. PLIB_ADCP_LowPowerStateGet Returns the state of the low power setting. PLIB_ADCP_ModuleIsReady Returns the overall ready status of the module. PLIB_ADCP_OsampDigFilterConfig Configures the Oversampling Digital Filter on the Pipelined ADC converter. PLIB_ADCP_OsampDigFilterDataGet Used to fetch the data result from the Oversampling Digital Filter. PLIB_ADCP_OsampDigFilterDataRdy Used to determine if the Oversampling Digital Filter has data ready. PLIB_ADCP_OsampDigFilterDisable Disables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_OsampDigFilterEnable Enables the Oversampling Digital Filter in the Pipelined ADC module PLIB_ADCP_ResultGet Returns a Pipelined ADC conversion result. PLIB_ADCP_ResultReady Returns the ADC conversion result ready bits for the module. PLIB_ADCP_ResultReadyGrpIntConfigure Selects input to include in global interrupt. PLIB_ADCP_SHModeSelect Selects the mode for the specified S&H. Types Name Description AN_READY This union (identical to the AN_SELECT union) is used as the return value by the PLIB_ADCP_Result_Ready() function. Unions Name Description AN_SELECT This union of structures is provided to simply selection of analog inputs for inclusion in a particular function. File Name plib_ADCP.h Company Microchip Technology Incorporated 5.6.3 BMX Peripheral Library 5.6.3.1 Introduction Bus Matrix (BMX) Peripheral Library for 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1519 Microchip Microcontrollers This library provides a low-level abstraction of the Bus Matrix (BMX) modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Bus Matrix Overview The Bus Matrix is essentially a high-speed switch that establishes connections between devices. Devices can be either master (initiator) or slave (target). The Bus Matrix also performs these other important functions: • Partition memory - The Bus Matrix provides the ability to partition both RAM and flash memory into kernel and user areas. It also controls the type of access, program or data, for each memory area. • Enable/disable program Flash memory cache for Direct Memory Access (DMA) • Enable/disable bus error exceptions - The Bus Matrix provides the ability to disable bus error exceptions for debugging. They are enabled by default. • Set Bus Arbitration mode - The Bus Matrix provides the ability to select between arbitration modes. The arbitration modes control the order and priority of initiator access to peripherals. 5.6.3.2 Release Notes MPLAB Harmony Version: v0.70b BMX Peripheral Library Version : 0.70b Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.3.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1520 5.6.3.4 Using the Library This topic describes the basic architecture of the BMX Peripheral Library and provides information and examples on how to use it. Interface Header File: peripheral.h The interface to the BMX library is defined in the "plib_bmx.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the BMX library must include "peripheral.h". Library File: The BMX Periphera lLlibrary is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6.3.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the BMX module on Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The following figure shows the Bus Matrix hardware abstraction model. Hardware Abstraction Model The BMX Peripheral Library provides interface routines to interact with the blocks shown in the diagram above. The Exception Generator generates a bus error exception for unmapped address accesses from all Bus Matrix initiators: • Initiator Expansion Interface (IXI) shared bus • In-Circuit Debug (ICD) unit • Direct Memory Access (DMA) controller • CPU data bus • CPU instruction bus Each of the above can be individually enabled or disabled with Exception Generator peripheral library routines. All are enabled by default. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1521 The Cache Control simply enables/disables program Flash memory (PFM) data cacheability for DMA accesses. The default setting is disabled. When enabled, the PCACHE module must have data caching enabled. The Bus Arbitrator assigns priority levels to bus initiators following one of three priority schemes: • Fixed, with CPU higher than DMA • Fixed, with DMA higher than CPU (default) • Rotating between four priority sequences The Memory Access Control partitions program Flash memory and RAM into kernel and user areas. The RAM can be further partitioned into data and program segments for both kernel and user areas. By default, the full PFM and RAM are mapped to Kernel mode. 5.6.3.4.2 How the Library Works The Bus Matrix is initialized in the start-up code, before an application is invoked. Most applications will not need to modify the Bus Matrix default settings. The BMX Peripheral Library is available for those applications requiring more complex memory partitioning, including operating systems and applications requiring specialized memory access. The ability to disable exceptions for unmapped memory access may be useful for debugging, but is not recommended for normal use. Changes to the arbitration scheme may improve performance for CPU or DMA intensive applications. 5.6.3.4.2.1 Exception Generator Any unmapped address access by a Bus Matrix initiator will by default generate an exception. These exceptions may be individually enabled or disabled with the peripheral library. Example: Enable CPU instruction exception // Enable CPU instruction exception PLIB_BMX_ISBusExceptionEnable(); 5.6.3.4.2.2 Cache Control This peripheral library function enables program Flash memory (data) cacheability for DMA accesses. Data caching must be enabled in the pcache. Hits are still read from the cache, but misses do not update the cache. This function is disabled by default. Example: Enable PFM Cachebility for DMA access PLIB_BMX_EnablePfmCacheDma() 5.6.3.4.2.3 Bus Arbiter Since there can be more than one initiator attempting to access the same target, an arbitration scheme must be used to control access to the target. The arbitration modes assign priority levels to all the initiators. The initiator with the higher priority level will always win target access over a lower priority initiator. The BMX Bus Arbitrator allows the programmer to select from one of three arbitration modes. PLIB_BMX_ARB_MODE_INST Arbitration mode 0 is a fixed priority scheme, with the CPU given higher priority than DMA. This mode can starve the DMA, so choose this mode when DMA is not being used. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1522 PLIB_BMX_ARB_MODE_DMA Arbitration Mode 1 is a fixed priority scheme like Mode 0, except that the CPU is always the lowest priority. Mode 1 is the default mode. PLIB_BMX_ARB_MODE_ROT Mode 2 arbitration supports rotating priority assignments to all initiators. Instead of a fixed priority assignment, each initiator is assigned the highest priority in a rotating fashion. In this mode, the rotating priority is applied with the following exceptions: 1. CPU data is always selected over CPU instruction. 2. ICD is always the highest priority. 3. When the CPU is processing an exception (EXL = 1) or an error (ERL = 1), the arbitrator temporarily reverts to Mode 0. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1523 Note: Priority Sequence 2 is not selected in the rotation priority scheme if there is a pending CPU data access. In this case, once the data access is complete, Sequence 2 is selected. Example: Set Bus Arbitration Mode to Rotating Priority PLIB_BMX_SetArbitrationMode(PLIB_BMX_ARB_ROT); 5.6.3.4.2.4 Memory Access Control The Bus Matrix allows the programmer to partition program Flash memory into user and kernel partitions. It also allows the programmer to partition data RAM into user and kernel partitions, each of which can be sub-divided into program and data partitions. At reset, the entire program Flash memory is one kernel partition and the entire data RAM is one kernel data partition. Program Flash Memory Partitioning Partitioning of the program Flash memory is accomplished by setting the offset of the user partition within the program Flash memory using the PLIB_BMX_ProgramFlashPartition() function. The size of the program Flash memory varies among devices, but can be retrieved with the PLIB_BMX_ProgramFlashMemorySizeGet() function. The offset must be a multiple of the program Flash memory block size. The program Flash memory block size may vary among devices. If programmed with a value that is not a multiple of the block size, the value will automatically be truncated to a block size boundary. At reset, the entire program Flash memory is mapped to Kernel mode. Example: Create a User Mode Partition of 12K in Program Flash Memory 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1524 size_t pfmSize; size_t userSize = (6 * PLIB_PCACHE_PFM_BLOCK_SIZE); size_t userOffset; // Get size of PFM pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(); userOffset = pfmSize - userSize; if (userOffset > 0) { PLIB_BMX_ProgramFlashPartitionSet(userOffset); } Data RAM Memory Partitioning The Data RAM Can be partitioned into four sections: • Kernel Data • Kernel Program • User Data • User Program Similar to the program Flash memory partitioning, the data RAM partitions are created by setting the base addresses of the various partitions. The BMX Peripheral Library provides a function to set all of the partitions at once. The size of the data RAM varies among devices, but may be retrieved with the PLIB_BMX_DataRAMSizeGet() function. The partitions must be a multiple of the Data RAM memory block size. The data RAM memory block size may vary among devices. If programmed with a value that is not a multiple of the block size, the partition will automatically be truncated to a block size boundary. At reset, the entire data RAM is mapped to Kernel mode. Note: At reset, the entire data RAM is mapped to Kernel mode and all of the offsets are set to zero. To partition the data RAM, all of the offsets must be programmed. If any of the offsets are set to zero, the entire data RAM is allocated to kernel data. Example: RAM Partitioned as Kernel Data, Kernel Program, User Data and User Program //Total Data RAM = 32KB. size_t totalRamSize; size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1525 size_t kernDataRamSize = (3 * PLIB_PCACHE_DRM_BLOCK_SIZE); //Kernel Data RAM = 6KB size_t kernProgRamSize = (2 * PLIB_PCACHE_DRM_BLOCK_SIZE); //Kernel Program RAM = 4KB size_t userDataRamSize = (6 * PLIB_PCACHE_DRM_BLOCK_SIZE); //User Data RAM = 12KB size_t userProgRamSize = (5 * PLIB_PCACHE_DRM_BLOCK_SIZE); //User Program RAM = 10KB //Get Size of Data RAM totalRamSize = PLIB_BMX_DataRAMSizeGet(); //Verify our partition sizes fit our RAM if ((kernDataRamSize + kernProgRamSize + userDataRamSize + userProgRamSize) != totalRamSize) { printf("RAM Partitioning Error\n"); return -1; } kernProgOffset = kernDataRamSize; userDataOffset = kernDataRamSize + kernProgRamSize; userProgOffset = userDataOffset + userDataRamSize; PLIB_BMX_DataRAMPartitionSet(kernProgOffset, userDataOffset, userProgOffset); Example: Determine the size of Data RAM partitions size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; size_t kernDataPart; size_t kernProgPart; size_t userDataPart; size_t userProgPart; size_t totalRamSize; totalRamSize = PLIB_BMX_DataRAMSizeGet(); kernProgOffset = PLIB_BMX_DataRAMKernelProgramOffsetGet(); userDataOffset = PLIB_BMX_DataRAMUserDataOffsetGet(); userProgOffset = PLIB_BMX_DataRAMUserProgramOffsetGet(); kernDataPart = kernProgOffset; kernProgPart = userDataOffset - kernProgOffset; userDataPart = userProgOffset - userDataOffset; userProgPart = totalRamSize - userProgOffset; 5.6.3.4.3 Configuring the Library The library is configured for the supported BMX module when the processor is chosen in the MPLAB IDE. 5.6.3.5 Library Interface Data Types and Constants Name Description BMX_MODULE_ID Lists the possible Module IDs for the bus matrix. PLIB_BMX_ARB_MODE Lists the possible arbitration modes for the bus matrix. PLIB_BMX_DATA_RAM_WAIT_STATES Defines the number of data RAM wait states for address setup. PLIB_BMX_EXCEPTION_SRC Defines which events trigger a bus exception. PLIB_BMX_DRM_BLOCK_SIZE Defines the minimum partition block size in data RAM memory. PLIB_BMX_PFM_BLOCK_SIZE Defines the minimum partition block size in program Flash memory. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1526 Arbiter Routines Name Description PLIB_BMX_ArbitrationModeGet Returns the bus matrix arbitration mode. PLIB_BMX_ArbitrationModeSet Sets the bus matrix arbitration mode. Bus Exception Routines Name Description PLIB_BMX_BusExceptionDataDisable Disables the data bus exception. PLIB_BMX_BusExceptionDataEnable Enables the Data bus exception. PLIB_BMX_BusExceptionDMADisable Disables the DMA bus exception. PLIB_BMX_BusExceptionDMAEnable Enables the DMA bus exception. PLIB_BMX_BusExceptionICDDisable Disables the ICD bus exception. PLIB_BMX_BusExceptionICDEnable Enables the ICD bus exception. PLIB_BMX_BusExceptionInstructionDisable Disables the instruction bus exception. PLIB_BMX_BusExceptionInstructionEnable Enables the instruction bus exception. PLIB_BMX_BusExceptionIXIDisable Disables the IXI bus exception. PLIB_BMX_BusExceptionIXIEnable Enables the IXI bus exception. Feature Existence Routines Name Description PLIB_BMX_ExistsArbitrationMode Identifies that the ArbitrationMode feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionData Identifies that the BusExceptionData feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionDMA Identifies that the BusExceptionDMA feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionICD Identifies that the BusExceptionICD feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionInstruction Identifies that the BusExceptionInstruction feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionIXI Identifies that the BusExceptionIXI feature exists on the BMX module. PLIB_BMX_ExistsDataRAMPartition Identifies that the DataRAMPartition feature exists on the BMX module. PLIB_BMX_ExistsDataRAMSize Identifies that the DataRAMSize feature exists on the BMX module. PLIB_BMX_ExistsDataRamWaitState Identifies that the DataRamWaitState feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashBootSize Identifies that the ProgramFlashBootSize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemoryCacheDma Identifies that the ProgramFlashMemoryCacheDma feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemorySize Identifies that the ProgramFlashMemorySize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashPartition Identifies that the ProgramFlashPartition feature exists on the BMX module. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1527 Memory Access Control Routines Name Description PLIB_BMX_DataRAMKernelProgramOffsetGet Gets the offset (from start of RAM) of the kernel program partition. PLIB_BMX_DataRAMPartitionSet Sets the size of the kernel and user partitions in data RAM memory. PLIB_BMX_DataRAMSizeGet Gets the size of data RAM memory. PLIB_BMX_DataRAMUserDataOffsetGet Gets the offset (from start of RAM) of the user data partition. PLIB_BMX_DataRAMUserProgramOffsetGet Gets the offset (from start of RAM) of the user program partition. PLIB_BMX_DataRamWaitStateGet Returns the number of data RAM Wait states. PLIB_BMX_DataRamWaitStateSet Sets the number of data RAM Wait states. PLIB_BMX_ProgramFlashBootSizeGet Gets the size of boot program Flash memory. PLIB_BMX_ProgramFlashMemorySizeGet Gets the size of program Flash memory. PLIB_BMX_ProgramFlashPartitionGet Gets the size of the kernel partition in program Flash memory. PLIB_BMX_ProgramFlashPartitionSet Sets the size of the kernel and user partitions in program Flash memory. Program Flash Cache Routines Name Description PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Disables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Enables the bus matrix program Flash cacheability for DMA. Description The BMX peripheral library consists of a set of interface routines, data types and constants, and macros provided by the plib_bmx.h header file. This section describes those items. 5.6.3.5.1 Bus Exception Routines 5.6.3.5.1.1 PLIB_BMX_BusExceptionDataDisable Function C void PLIB_BMX_BusExceptionDataDisable( BMX_MODULE_ID index ); Description This function disables the data bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled Returns None. Remarks This function implements an operation of the BusExceptionData feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1528 refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionData in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionDataDisable(BMX_ID_0); 5.6.3.5.1.2 PLIB_BMX_BusExceptionDataEnable Function C void PLIB_BMX_BusExceptionDataEnable( BMX_MODULE_ID index ); Description This function enables the Data bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the BusExceptionData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionData in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionDataEnable(BMX_ID_0); 5.6.3.5.1.3 PLIB_BMX_BusExceptionDMADisable Function C void PLIB_BMX_BusExceptionDMADisable( BMX_MODULE_ID index ); Description This function disables the DMA bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1529 Remarks This function implements an operation of the BusExceptionDMA feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionDMA in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionDMADisable(BMX_ID_0); 5.6.3.5.1.4 PLIB_BMX_BusExceptionDMAEnable Function C void PLIB_BMX_BusExceptionDMAEnable( BMX_MODULE_ID index ); Description This function enables the DMA bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the BusExceptionDMA feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionDMA in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionDMAEnable(BMX_ID_0); 5.6.3.5.1.5 PLIB_BMX_BusExceptionICDDisable Function C void PLIB_BMX_BusExceptionICDDisable( BMX_MODULE_ID index ); Description This function disables the ICD bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1530 Returns None. Remarks This function implements an operation of the BusExceptionICD feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionICD in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionICDDisable(BMX_ID_0); 5.6.3.5.1.6 PLIB_BMX_BusExceptionICDEnable Function C void PLIB_BMX_BusExceptionICDEnable( BMX_MODULE_ID index ); Description This function enables the ICD bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the BusExceptionICD feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionICD in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionICDEnable(BMX_ID_0); 5.6.3.5.1.7 PLIB_BMX_BusExceptionInstructionDisable Function C void PLIB_BMX_BusExceptionInstructionDisable( BMX_MODULE_ID index ); Description This function disables the instruction bus exception. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1531 Parameters Parameters Description index Identifier for the device instance to be disabled Returns None. Remarks This function implements an operation of the BusExceptionInstruction feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionInstruction in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionInstructionDisable(BMX_ID_0); 5.6.3.5.1.8 PLIB_BMX_BusExceptionInstructionEnable Function C void PLIB_BMX_BusExceptionInstructionEnable( BMX_MODULE_ID index ); Description This function enables the instruction bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the BusExceptionInstruction feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionInstruction in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionInstructionEnable(BMX_ID_0); 5.6.3.5.1.9 PLIB_BMX_BusExceptionIXIDisable Function C void PLIB_BMX_BusExceptionIXIDisable( BMX_MODULE_ID index ); Description This function disables the IXI bus exception. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1532 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled Returns None. Remarks This function implements an operation of the BusExceptionIXI feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionIXI in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionIXIDisable(BMX_ID_0); 5.6.3.5.1.10 PLIB_BMX_BusExceptionIXIEnable Function C void PLIB_BMX_BusExceptionIXIEnable( BMX_MODULE_ID index ); Description This function enables the IXI bus exception. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the BusExceptionIXI feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsBusExceptionIXI in your application to to automatically determine whether this feature is available. Example PLIB_BMX_BusExceptionIXIEnable(BMX_ID_0); 5.6.3.5.2 Program Flash Cache Routines 5.6.3.5.2.1 PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Function C void PLIB_BMX_ProgramFlashMemoryCacheDmaDisable( BMX_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1533 ); Description This function disables the program Flash cacheability for DMA. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled Returns None. Remarks This function implements an operation of the ProgramFlashMemoryCacheDma feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemoryCacheDma in your application to to automatically determine whether this feature is available. Example PLIB_BMX_ProgramFlashMemoryCacheDmaDisable(BMX_ID_0); 5.6.3.5.2.2 PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Function C void PLIB_BMX_ProgramFlashMemoryCacheDmaEnable( BMX_MODULE_ID index ); Description This function enables the program Flash cacheability for DMA. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None. Remarks This function implements an operation of the ProgramFlashMemoryCacheDma feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemoryCacheDma in your application to to automatically determine whether this feature is available. Example PLIB_BMX_ProgramFlashMemoryCacheDmaEnable(BMX_ID_0); 5.6.3.5.3 Arbiter Routines 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1534 5.6.3.5.3.1 PLIB_BMX_ArbitrationModeGet Function C PLIB_BMX_ARB_MODE PLIB_BMX_ArbitrationModeGet( BMX_MODULE_ID index ); Description This function returns the bus matrix arbitration mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns PLIB_BMX_ARB_MODE enumerator value representing the arbitration mode. Remarks This function implements an operation of the ArbitrationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsArbitrationMode in your application to to automatically determine whether this feature is available. Example PLIB_BMX_ARB_MODE mode; mode = PLIB_BMX_ArbitrationModeGet(BMX_ID_0); 5.6.3.5.3.2 PLIB_BMX_ArbitrationModeSet Function C void PLIB_BMX_ArbitrationModeSet( BMX_MODULE_ID index, PLIB_BMX_ARB_MODE mode ); Description This function sets the bus matrix arbitration mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode Identifies the desired arbitration mode Returns None. Remarks This function implements an operation of the ArbitrationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsArbitrationMode in your application to to 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1535 automatically determine whether this feature is available. Example PLIB_BMX_ArbitrationModeSet(BMX_ID_0, PLIB_BMX_ARB_MODE_DMA); 5.6.3.5.4 Memory Access Control Routines 5.6.3.5.4.1 PLIB_BMX_DataRAMKernelProgramOffsetGet Function C size_t PLIB_BMX_DataRAMKernelProgramOffsetGet( BMX_MODULE_ID index ); Description This function returns the offset of start address of the kernel program RAM partition. This represents the size of the kernel data RAM partition. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Offset of kernel program partition from base of RAM. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to to automatically determine whether this feature is available. Example size_t kernProgOffset; kernProgOffset = PLIB_BMX_DataRAMKernelProgramOffsetGet(BMX_ID_0); 5.6.3.5.4.2 PLIB_BMX_DataRAMPartitionSet Function C void PLIB_BMX_DataRAMPartitionSet( BMX_MODULE_ID index, size_t kernProgOffset, size_t userDataOffset, size_t userProgOffset ); Description This function sets the size of the kernel and user partitions in the data RAM memory (DRM). By default, the entire data RAM is mapped to Kernel mode and all of the offsets are zero. To partition the data RAM, all of the offsets must be set to a minimum of one DRM block size. If any of the offsets are set to zero, the entire data RAM is allocated to kernel data. The partitions must be a multiple of PLIB_BMX_DRM_BLOCK_SIZE. If programmed with a value that is not a multiple of PLIB_BMX_DRM_BLOCK_SIZE, the value will be automatically truncated to PLIB_BMX_DRM_BLOCK_SIZE. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1536 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured kernProgOffset Size of the offset of the Kernel Program partition userDataOffset Size of the offset of the User Data partition userProgOffset Size of the offset of the User Program partition Returns None. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to to automatically determine whether this feature is available. Example //Total Data RAM = 32 KB. size_t totalRamSize; size_t kernDataRamSize = (3 * PLIB_BMX_DRM_BLOCK_SIZE); size_t kernProgRamSize = (2 * PLIB_BMX_DRM_BLOCK_SIZE); size_t userDataRamSize = (6 * PLIB_BMX_DRM_BLOCK_SIZE); size_t userProgRamSize = (5 * PLIB_BMX_DRM_BLOCK_SIZE); //Get Size of Data RAM totalRamSize = PLIB_BMX_DataRAMSizeGet(BMX_ID_0); //Verify our partition sizes fit our RAM if ((kernDataRamSize + kernProgRamSize + userDataRamSize + userProgRamSize) != totalRamSize) { printf("RAM Partitioning Errorn"); } size_t kernProgOffset; size_t userDataOffset; size_t userProgOffset; kernProgOffset = kernDataRamSize; userDataOffset = kernDataRamSize + kernProgRamSize; userProgOffset = userDataOffset + userDataRamSize; PLIB_BMX_DataRAMPartitionSet(BMX_ID_0, kernProgOffset, userDataOffset, userProgOffset); 5.6.3.5.4.3 PLIB_BMX_DataRAMSizeGet Function C size_t PLIB_BMX_DataRAMSizeGet( BMX_MODULE_ID index ); Description This function returns the size of the data RAM memory. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1537 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Size of data RAM memory. Remarks This function implements an operation of the DataRAMSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMSize in your application to to automatically determine whether this feature is available. Example size_t drmSize; drmSize = PLIB_BMX_DataRAMSizeGet(BMX_ID_0); 5.6.3.5.4.4 PLIB_BMX_DataRAMUserDataOffsetGet Function C size_t PLIB_BMX_DataRAMUserDataOffsetGet( BMX_MODULE_ID index ); Description This function returns the offset of start address of the user data RAM partition. Subtracting the kernel program offset from the user data offset gives the size of the kernel program RAM partition. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Offset of user data partition from base of RAM. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to to automatically determine whether this feature is available. Example size_t userDataOffset; userDataOffset = PLIB_BMX_DataRAMUserDataOffsetGet(BMX_ID_0); 5.6.3.5.4.5 PLIB_BMX_DataRAMUserProgramOffsetGet Function C size_t PLIB_BMX_DataRAMUserProgramOffsetGet( BMX_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1538 ); Description This function returns the offset of start address of the user program RAM partition. Subtracting the user data offset from the user program offset gives the size of the user data RAM partition. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Offset of user data partition from base of RAM. Remarks This function implements an operation of the DataRAMPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRAMPartition in your application to to automatically determine whether this feature is available. Example size_t userProgOffset; userProgOffset = PLIB_BMX_DataRAMUserProgramOffsetGet(BMX_ID_0); 5.6.3.5.4.6 PLIB_BMX_DataRamWaitStateGet Function C PLIB_BMX_DATA_RAM_WAIT_STATES PLIB_BMX_DataRamWaitStateGet( BMX_MODULE_ID index ); Description This function returns the number of data RAM Wait states. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns PLIB_BMX_DATA_RAM_WAIT_STATES enumeration representing the number of wait states. Remarks This function implements an operation of the DataRamWaitState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRamWaitState in your application to to automatically determine whether this feature is available. Example PLIB_BMX_DATA_RAM_WAIT_STATES wait; wait = PLIB_BMX_DataRamWaitStateGet(BMX_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1539 5.6.3.5.4.7 PLIB_BMX_DataRamWaitStateSet Function C void PLIB_BMX_DataRamWaitStateSet( BMX_MODULE_ID index, PLIB_BMX_DATA_RAM_WAIT_STATES wait ); Description This function sets the number of data RAM Wait states. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured PLIB_BMX_DATA_RAM_WAIT_STATES Enumeration representing the number of Wait states Returns None. Remarks This function implements an operation of the DataRamWaitState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsDataRamWaitState in your application to to automatically determine whether this feature is available. Example PLIB_BMX_DataRamWaitStateSet(BMX_ID_0, PLIB_BMX_DATA_RAM_WAIT_ONE); 5.6.3.5.4.8 PLIB_BMX_ProgramFlashBootSizeGet Function C size_t PLIB_BMX_ProgramFlashBootSizeGet( BMX_MODULE_ID index ); Description This function returns the size of the boot program Flash memory. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Size of boot program Flash memory. Remarks This function implements an operation of the ProgramFlashBootSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashBootSize in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1540 Example size_t bootSize; bootSize = PLIB_BMX_ProgramFlashBootSizeGet(BMX_ID_0); 5.6.3.5.4.9 PLIB_BMX_ProgramFlashMemorySizeGet Function C size_t PLIB_BMX_ProgramFlashMemorySizeGet( BMX_MODULE_ID index ); Description This function returns the size of the program Flash memory. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Size of program Flash memory. Remarks This function implements an operation of the ProgramFlashMemorySize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashMemorySize in your application to to automatically determine whether this feature is available. Example size_t pfmSize; pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); 5.6.3.5.4.10 PLIB_BMX_ProgramFlashPartitionGet Function C size_t PLIB_BMX_ProgramFlashPartitionGet( BMX_MODULE_ID index ); Description This function gets the size of the kernel partition in the program Flash memory. The remaining Flash is set to user mode, and may be accessed by user programs. On reset, the entire Flash is mapped to Kernel mode, and this function will return zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Size of the kernel partition in program Flash memory. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1541 Remarks This function implements an operation of the ProgramFlashPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashPartition in your application to to automatically determine whether this feature is available. Example size_t pfmSize; size_t userPfmSize; size_t kernPfmSize; // Get size of PFM pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); kernPfmSize = PLIB_BMX_ProgramFlashPartitionGet(BMX_ID_0); userPfmSize = pfmSize - kernPfmSize; 5.6.3.5.4.11 PLIB_BMX_ProgramFlashPartitionSet Function C void PLIB_BMX_ProgramFlashPartitionSet( BMX_MODULE_ID index, size_t user_size ); Description This function sets the size of the kernel and user partitions in program Flash memory (PFM). Kernel programs may access both partitions, but user programs may not access the kernel partition (including peripheral registers). By default, the entire Flash is mapped to Kernel mode. If called with a non-zero value, a user partition of size user_size is created, and the remaining PFM remains in Kernel mode. The user partition must be a multiple of PLIB_BMX_PFM_BLOCK_SIZE. If programmed with a value that is not a multiple of PLIB_BMX_PFM_BLOCK_SIZE, the value will be truncated to a PLIB_BMX_PFM_BLOCK_SIZE boundary. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured userSize Size of the user partition in PFM Returns None. Remarks This function implements an operation of the ProgramFlashPartition feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_BMX_ExistsProgramFlashPartition in your application to to automatically determine whether this feature is available. Example size_t pfm_size; size_t userSize = (6 * PLIB_BMX_PFM_BLOCK_SIZE); size_t userOffset; // Get size of PFM size_t pfmSize; pfmSize = PLIB_BMX_ProgramFlashMemorySizeGet(BMX_ID_0); userOffset = pfmSize - userSize; 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1542 if (userOffset > 0) { PLIB_BMX_ProgramFlashPartitionSet(BMX_ID_0, userOffset); } 5.6.3.5.5 Data Types and Constants 5.6.3.5.5.1 BMX_MODULE_ID Enumeration C typedef enum { BMX_ID_0, BMX_NUMBER_OF_MODULES } BMX_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the bus matrix. Remarks Refer to the specific device data sheet to obtain the correct number of modules defined for the desired device. 5.6.3.5.5.2 PLIB_BMX_ARB_MODE Enumeration C typedef enum { PLIB_BMX_ARB_MODE_INST, PLIB_BMX_ARB_MODE_DMA, PLIB_BMX_ARB_MODE_ROT } PLIB_BMX_ARB_MODE; Description Arbitration Mode This enumeration lists the possible arbitration modes for the bus matrix. Members Members Description PLIB_BMX_ARB_MODE_INST Arbitration Mode 0 PLIB_BMX_ARB_MODE_DMA Arbitration Mode 1 PLIB_BMX_ARB_MODE_ROT Arbitration Mode 2 5.6.3.5.5.3 PLIB_BMX_DATA_RAM_WAIT_STATES Enumeration C typedef enum { PLIB_BMX_DATA_RAM_WAIT_ZERO, PLIB_BMX_DATA_RAM_WAIT_ONE } PLIB_BMX_DATA_RAM_WAIT_STATES; Description Wait States This definition specifies the number of data RAM wait states for address setup. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1543 Members Members Description PLIB_BMX_DATA_RAM_WAIT_ZERO Zero wait states for address setup PLIB_BMX_DATA_RAM_WAIT_ONE One wait state for address setup 5.6.3.5.5.4 PLIB_BMX_EXCEPTION_SRC Enumeration C typedef enum { PLIB_BMX_ERR_IXI, PLIB_BMX_ERR_ICD, PLIB_BMX_ERR_DMA, PLIB_BMX_ERR_DATA, PLIB_BMX_ERR_INST } PLIB_BMX_EXCEPTION_SRC; Description Exception Bits This definition specifies which events trigger a bus exception. Members Members Description PLIB_BMX_ERR_IXI IXI Shared Bus PLIB_BMX_ERR_ICD In-Circuit Debugger PLIB_BMX_ERR_DMA DMA Controller PLIB_BMX_ERR_DATA CPU Data Bus PLIB_BMX_ERR_INST CPU Instruction Bus 5.6.3.5.5.5 PLIB_BMX_DRM_BLOCK_SIZE Macro C #define PLIB_BMX_DRM_BLOCK_SIZE 2048 Description Program Flash Partition Block Size This definition specifies the minimum partition block size in data RAM memory. 5.6.3.5.5.6 PLIB_BMX_PFM_BLOCK_SIZE Macro C #define PLIB_BMX_PFM_BLOCK_SIZE 2048 Description Program Flash Partition Block Size This definition specifies the minimum partition block size in program Flash memory. 5.6.3.5.6 Feature Existence Routines 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1544 5.6.3.5.6.1 PLIB_BMX_ExistsArbitrationMode Function C bool PLIB_BMX_ExistsArbitrationMode( BMX_MODULE_ID index ); Description This interface identifies that the ArbitrationMode feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ArbitrationModeSet • PLIB_BMX_ArbitrationModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ArbitrationMode feature is supported on the device • false = The ArbitrationMode feature is not supported on the device Remarks None. 5.6.3.5.6.2 PLIB_BMX_ExistsBusExceptionData Function C bool PLIB_BMX_ExistsBusExceptionData( BMX_MODULE_ID index ); Description This interface identifies that the BusExceptionData feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionDataEnable • PLIB_BMX_BusExceptionDataDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The BusExceptionData feature is supported on the device • false = The BusExceptionData feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1545 Remarks None. 5.6.3.5.6.3 PLIB_BMX_ExistsBusExceptionDMA Function C bool PLIB_BMX_ExistsBusExceptionDMA( BMX_MODULE_ID index ); Description This interface identifies that the BusExceptionDMA feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionDMAEnable • PLIB_BMX_BusExceptionDMADisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The BusExceptionDMA feature is supported on the device • false = The BusExceptionDMA feature is not supported on the device Remarks None. 5.6.3.5.6.4 PLIB_BMX_ExistsBusExceptionICD Function C bool PLIB_BMX_ExistsBusExceptionICD( BMX_MODULE_ID index ); Description This interface identifies that the BusExceptionICD feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionICDEnable • PLIB_BMX_BusExceptionICDDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1546 Returns • true = The BusExceptionICD feature is supported on the device • false = TheWhen BusExceptionICD feature is not supported on the device Remarks None. 5.6.3.5.6.5 PLIB_BMX_ExistsBusExceptionInstruction Function C bool PLIB_BMX_ExistsBusExceptionInstruction( BMX_MODULE_ID index ); Description This interface identifies that the BusExceptionInstruction feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionInstructionEnable • PLIB_BMX_BusExceptionInstructionDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The BusExceptionInstruction feature is supported on the device • false = The BusExceptionInstruction feature is not supported on the device Remarks None. 5.6.3.5.6.6 PLIB_BMX_ExistsBusExceptionIXI Function C bool PLIB_BMX_ExistsBusExceptionIXI( BMX_MODULE_ID index ); Description This interface identifies that the BusExceptionIXI feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_BusExceptionIXIEnable • PLIB_BMX_BusExceptionIXIDisable Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1547 Parameters Parameters Description index Identifier for the device instance Returns • true = The BusExceptionIXI feature is supported on the device • false = The BusExceptionIXI feature is not supported on the device Remarks None. 5.6.3.5.6.7 PLIB_BMX_ExistsDataRAMPartition Function C bool PLIB_BMX_ExistsDataRAMPartition( BMX_MODULE_ID index ); Description This interface identifies that the DataRAMPartition feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_DataRAMPartitionSet • PLIB_BMX_DataRAMKernelProgramOffsetGet • PLIB_BMX_DataRAMUserDataOffsetGet • PLIB_BMX_DataRAMUserProgramOffsetGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DataRAMPartition feature is supported on the device • false = The DataRAMPartition feature is not supported on the device Remarks None. 5.6.3.5.6.8 PLIB_BMX_ExistsDataRAMSize Function C bool PLIB_BMX_ExistsDataRAMSize( BMX_MODULE_ID index ); Description This interface identifies that the DataRAMSize feature is available on the BMX module. When this interface returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1548 • PLIB_BMX_DataRAMSizeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DataRAMSize feature is supported on the device • false = The DataRAMSize feature is not supported on the device Remarks None. 5.6.3.5.6.9 PLIB_BMX_ExistsDataRamWaitState Function C bool PLIB_BMX_ExistsDataRamWaitState( BMX_MODULE_ID index ); Description This interface identifies that the DataRamWaitState feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_DataRamWaitStateSet • PLIB_BMX_DataRamWaitStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DataRamWaitState feature is supported on the device • false = The DataRamWaitState feature is not supported on the device Remarks None. 5.6.3.5.6.10 PLIB_BMX_ExistsProgramFlashBootSize Function C bool PLIB_BMX_ExistsProgramFlashBootSize( BMX_MODULE_ID index ); Description This interface identifies that the ProgramFlashBootSize feature is available on the BMX module. When this interface returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1549 • PLIB_BMX_ProgramFlashBootSizeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ProgramFlashBootSize feature is supported on the device • false = The ProgramFlashBootSize feature is not supported on the device Remarks None. 5.6.3.5.6.11 PLIB_BMX_ExistsProgramFlashMemoryCacheDma Function C bool PLIB_BMX_ExistsProgramFlashMemoryCacheDma( BMX_MODULE_ID index ); Description This interface identifies that the ProgramFlashMemoryCacheDma feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ProgramFlashMemoryCacheDmaEnable • PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ProgramFlashMemoryCacheDma feature is supported on the device • false = The ProgramFlashMemoryCacheDma feature is not supported on the device Remarks None. 5.6.3.5.6.12 PLIB_BMX_ExistsProgramFlashMemorySize Function C bool PLIB_BMX_ExistsProgramFlashMemorySize( BMX_MODULE_ID index ); Description This interface identifies that the ProgramFlashMemorySize feature is available on the BMX module. When this interface returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1550 • PLIB_BMX_ProgramFlashMemorySizeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ProgramFlashMemorySize feature is supported on the device • false = The ProgramFlashMemorySize feature is not supported on the device Remarks None. 5.6.3.5.6.13 PLIB_BMX_ExistsProgramFlashPartition Function C bool PLIB_BMX_ExistsProgramFlashPartition( BMX_MODULE_ID index ); Description This interface identifies that the ProgramFlashPartition feature is available on the BMX module. When this interface returns true, these functions are supported on the device: • PLIB_BMX_ProgramFlashPartitionGet • PLIB_BMX_ProgramFlashPartitionSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ProgramFlashPartition feature is supported on the device • false = The ProgramFlashPartition feature is not supported on the device Remarks None. 5.6.3.6 Files Files Name Description plib_bmx.h Defines the Bus Matrix (BMX) Peripheral Library interface Description 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1551 5.6.3.6.1 plib_bmx.h Bus Matrix Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the bus matrix (BMX) peripheral library (PLIB) for Microchip microcontrollers. The definitions in this file are for the bus matrix controller module. Enumerations Name Description PLIB_BMX_ARB_MODE Lists the possible arbitration modes for the bus matrix. PLIB_BMX_DATA_RAM_WAIT_STATES Defines the number of data RAM wait states for address setup. PLIB_BMX_EXCEPTION_SRC Defines which events trigger a bus exception. Functions Name Description PLIB_BMX_ArbitrationModeGet Returns the bus matrix arbitration mode. PLIB_BMX_ArbitrationModeSet Sets the bus matrix arbitration mode. PLIB_BMX_BusExceptionDataDisable Disables the data bus exception. PLIB_BMX_BusExceptionDataEnable Enables the Data bus exception. PLIB_BMX_BusExceptionDMADisable Disables the DMA bus exception. PLIB_BMX_BusExceptionDMAEnable Enables the DMA bus exception. PLIB_BMX_BusExceptionICDDisable Disables the ICD bus exception. PLIB_BMX_BusExceptionICDEnable Enables the ICD bus exception. PLIB_BMX_BusExceptionInstructionDisable Disables the instruction bus exception. PLIB_BMX_BusExceptionInstructionEnable Enables the instruction bus exception. PLIB_BMX_BusExceptionIXIDisable Disables the IXI bus exception. PLIB_BMX_BusExceptionIXIEnable Enables the IXI bus exception. PLIB_BMX_DataRAMKernelProgramOffsetGet Gets the offset (from start of RAM) of the kernel program partition. PLIB_BMX_DataRAMPartitionSet Sets the size of the kernel and user partitions in data RAM memory. PLIB_BMX_DataRAMSizeGet Gets the size of data RAM memory. PLIB_BMX_DataRAMUserDataOffsetGet Gets the offset (from start of RAM) of the user data partition. PLIB_BMX_DataRAMUserProgramOffsetGet Gets the offset (from start of RAM) of the user program partition. PLIB_BMX_DataRamWaitStateGet Returns the number of data RAM Wait states. PLIB_BMX_DataRamWaitStateSet Sets the number of data RAM Wait states. PLIB_BMX_ExistsArbitrationMode Identifies that the ArbitrationMode feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionData Identifies that the BusExceptionData feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionDMA Identifies that the BusExceptionDMA feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionICD Identifies that the BusExceptionICD feature exists on the BMX module. PLIB_BMX_ExistsBusExceptionInstruction Identifies that the BusExceptionInstruction feature exists on the BMX module. 5.6 Peripheral Library Help MPLAB Harmony Help BMX Peripheral Library 5-1552 PLIB_BMX_ExistsBusExceptionIXI Identifies that the BusExceptionIXI feature exists on the BMX module. PLIB_BMX_ExistsDataRAMPartition Identifies that the DataRAMPartition feature exists on the BMX module. PLIB_BMX_ExistsDataRAMSize Identifies that the DataRAMSize feature exists on the BMX module. PLIB_BMX_ExistsDataRamWaitState Identifies that the DataRamWaitState feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashBootSize Identifies that the ProgramFlashBootSize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemoryCacheDma Identifies that the ProgramFlashMemoryCacheDma feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashMemorySize Identifies that the ProgramFlashMemorySize feature exists on the BMX module. PLIB_BMX_ExistsProgramFlashPartition Identifies that the ProgramFlashPartition feature exists on the BMX module. PLIB_BMX_ProgramFlashBootSizeGet Gets the size of boot program Flash memory. PLIB_BMX_ProgramFlashMemoryCacheDmaDisable Disables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemoryCacheDmaEnable Enables the bus matrix program Flash cacheability for DMA. PLIB_BMX_ProgramFlashMemorySizeGet Gets the size of program Flash memory. PLIB_BMX_ProgramFlashPartitionGet Gets the size of the kernel partition in program Flash memory. PLIB_BMX_ProgramFlashPartitionSet Sets the size of the kernel and user partitions in program Flash memory. Macros Name Description PLIB_BMX_DRM_BLOCK_SIZE Defines the minimum partition block size in data RAM memory. PLIB_BMX_PFM_BLOCK_SIZE Defines the minimum partition block size in program Flash memory. File Name plib_bmx.h Company Microchip Technology Inc. 5.6.4 CAN Peripheral Library 5.6.4.1 Introduction CAN Peripheral Library for Microchip Microcontrollers 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1553 The Controller Area Network (CAN) is used primarily in industrial and automotive applications. It is an asynchronous serial data communication protocol that provides reliable communication in an electrically noisy environment. This library provides a low-level abstraction of the CAN module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. 5.6.4.2 Release Notes MPLAB Harmony Version: v0.70b CAN Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1554 5.6.4.4 How the Library Works Note: Not all modes are available on all the devices. Please refer to the specific device data sheet to determine the set of modes that are supported for your device. 5.6.4.4.1 About CAN Protocol The following section briefly discusses the CAN Protocol briefly. For complete details on the CAN protocol, refer to the CAN 2.0 specification available from Bosch. The CAN bus protocol uses asynchronous communication. Information is passed from transmitters to receivers in data frames, which are composed of byte fields that define the contents of the data frame. This is shown in the figure below. Each frame begins with a Start-of-Frame (SOF) bit and terminates with an End-of-Frame (EOF) bit field. The SOF is followed by arbitration and control fields, which identify the message type, format, length and priority. This information allows each node on the CAN bus to respond appropriately to the message. The data field conveys the message content and is of variable length, ranging from 0 to 8 bytes. Error protection is provided by the Cyclic Redundancy Check (CRC) and acknowledgement (ACK) fields. 5.6.4.4.1.1 Standard ID Message Format The Standard ID message begins with a Start-of-Frame bit followed by a 12-bit arbitration field. The arbitration field contains an 11-bit identifier and the Remote Transmit Request (RTR) bit. The identifier defines the type of information contained in the message and is used by each receiving node to determine if the message is of interest. The RTR bit distinguishes a data frame from a remote frame. For a standard data frame, the RTR bit is clear. Following the arbitration field is a 6-bit control field, which provides more information about the contents of the message. The first bit in the control field is an Identifier Extension (IDE) bit, which distinguishes the message as either a standard or extended data frame. A standard data frame is indicated by a dominant state (logic level ‘0’) during transmission of the IDE bit. The second bit in the control field is a reserved (RB0) bit, which is in the dominant state (logic level ‘0’). The last 4 bits in the control field represent the Data Length Code (DLC), which specifies the number of data bytes present in the message. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1555 The data field follows the control field. This field carries the message data – the actual payload of the data frame. This field is of variable length, ranging from 0 to 8 bytes. The number of bytes is user-selectable. The data field is followed by the Cyclic Redundancy Check (CRC) field, which is a 15-bit CRC sequence with one delimiter bit. The acknowledgement (ACK) field is sent as a recessive bit (logic level ‘1’) and is overwritten as a dominant bit by any receiver that has received the data correctly.The message is acknowledged by the receiver regardless of the result of the acceptance filter comparison. The last field is the End-of-Frame field, which consists of 7 recessive bits that indicate the end of message. 5.6.4.4.1.2 Extended ID Message Format The Extended ID Message frame begins with an SOF bit followed by a 31-bit arbitration field. The arbitration field for the extended data frame contains 29 identifier bits in two fields separated by a Substitute Remote Request (SRR) bit and an IDE bit. The SRR bit determines if the message is a remote frame. SRR = 1 for extended data frames. The IDE bit indicates the data frame type. For the extended data frame, IDE = 1. The extended data frame Control field consists of 7 bits. The first bit is the RTR. For the extended data frame, RTR = 0. The next two bits, RB1 and RB0, are reserved bits that are in the dominant state (logic level ‘0’). The last 4 bits in the Control field are the Data Length Code, which specifies the number of data bytes present in the message.The remaining fields in an extended data frame are identical to a standard data frame. 5.6.4.4.1.3 Can Bit Time Quanta The nominal bit rate is the number of bits per second transmitted on the CAN bus. Nominal bit time = 1 ÷ Nominal Bit Rate. There are four time segments in a bit time to compensate for any phase shifts due to oscillator drifts or propagation delays. These time segments do not overlap each other and are represented in terms of Time Quantum (TQ). One TQ is a fixed unit of time derived from the oscillator clock. The total number of time quanta in a nominal bit time must be programmed between 8 and 25 TQ. Each bit transmission time consists of four time segments: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1556 Synchronization Segment – This time segment synchronizes the different nodes connected on the CAN bus. A bit edge is expected to be within this segment. Based on CAN protocol, the Synchronization Segment is assumed to be one Time Quantum. Propagation Segment – This time segment compensates for any time delay that may occur due to the bus line or due to the various transceivers connected on that bus. Phase Segment 1 – This time segment compensates for errors that may occur due to phase shift in the edges. The time segment may be lengthened during resynchronization to compensate for the phase shift. Phase Segment 2 – This time segment compensates for errors that may occur due to phase shift in the edges. The time segment may be shortened during resynchronization to compensate for the phase shift. The Phase Segment 2 time can be configured to be either programmable or specified by the Phase Segment 1 time. Two types of synchronization are used – Hard Synchronization and Resynchronization. A Hard Synchronization occurs once at the start of a frame. Resynchronization occurs inside a frame. Hard synchronization takes place on the recessive-to-dominant transition of the start bit. The bit time is restarted from that edge. Resynchronization takes place when a bit edge does not occur within the Synchronization Segment in a message. One of the Phase Segments is shortened or lengthened by an amount that depends on the phase error in the signal. The maximum amount that can be used is determined by the Synchronization Jump Width parameter. The length of Phase Segment 1 and Phase Segment 2 can be changed depending on oscillator tolerances of the transmitting and receiving node. Resynchronization compensates for any phase shifts that may occur due to the different oscillators used by the transmitting and receiving nodes. Bit Lengthening – If the transmitting node in CAN has a slower oscillator than the receiving node, the next falling edge, and therefore, the sample point, can be delayed by lengthening Phase Segment 1 in the bit time. Bit Shortening – If the transmitting node in CAN has a faster oscillator than the receiving node, then the next falling edge, and therefore, the sample point of the next bit, can be reduced by shortening the Phase Segment 2 in the bit time. Synchronization Jump Width (SJW) – This determines the synchronization jump width by limiting the amount of lengthening or shortening that can be applied to the Phase Segment 1 and Phase Segment 2 time intervals. This segment should not be longer than Phase Segment 2 time. The width can be 1-4 TQ 5.6.4.4.2 Initialization of CAN 5.6.4.4.2.1 Mode Configuration The CAN module must be enabled before configuration. Enabling the CAN module gives it control over the CAN pins of the device. The following code example shows how the PLIB_CAN_Enable function is used to enable the module. /* This code expects the data direction settings to be done from other modules */ /* Switch the CAN module ON */ PLIB_CAN_Enable(CAN_ID_1); The CAN module must be placed in Configuration mode before attempting to configure it. The following features are available in Configuration mode only: • Configuring the CAN module clock and CAN bus speed • Configuring the message acceptance filter mask • Assigning the channel buffer memory • Configuring channel size and Receive Channel Data-only mode. The CAN module operating mode can be changed by using the PLIB_CAN_OperationModeSelect function. The caller should 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1557 wait until the operating mode is set before proceeding. The PLIB_CAN_OperationModeGet function can be used to obtain the current operating mode of the CAN module. /* Switch the CAN module to Configuration mode. Wait until the switch is complete */ PLIB_CAN_Enable(CAN_ID_1); PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_CONFIGURATION_MODE); while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_CONFIGURATION_MODE); The CAN module must be placed in Normal mode in order to be able to send and receive messages. The caller should wait until the Normal operating mode is set before proceeding. The PLIB_CAN_OperationModeSelect function can be used to obtain the current operating mode of the CAN module. /* Switch the CAN module to Normal mode. Wait until the switch is complete */ PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_NORMAL_MODE); while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_NORMAL_MODE); 5.6.4.4.2.2 Setting Bus Speed The bus speed at which the CAN node operates is determined by the CAN module clock and the number of Bit Time Quanta (TQ) assigned to the CAN bit. The following code snippet shows an example of setting the CAN module clock and CAN bus speed. In this example, the number of Bit TQ is 10. /* Configure the CAN Module Clock. The propagation segment, phase segment 1 and phase segment 2 * are configured to have 3TQ. The CANSetSpeed function sets the baud. The CPU * core frequency is 80000000 Hz and the desired CAN bus speed is 250000 bps. */ PLIB_CAN_PhaseSegment2LengthSet(CAN_ID_1, CAN_TIME_SEGMENT_LEN_3TQ); PLIB_CAN_PhaseSegment1LengthSet(CAN_ID_1, CAN_TIME_SEGMENT_LEN_3TQ); PLIB_CAN_PropagationTimeSegmentSet(CAN_ID_1, CAN_TIME_SEGMENT_LEN_3TQ); PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable(CAN_ID_1); PLIB_CAN_BusLine3TimesSamplingEnable(CAN_ID_1); PLIB_CAN_SyncJumpWidthSet(CAN_ID_1, CAN_TIME_SEGMENT_LEN_2TQ); 5.6.4.4.2.3 Assigning Buffer Memory The CAN module requires RAM memory to store received messages and queue message that need to be transmitted. The total amount of memory required depends on the size of each channel. While each channel has a minimum size of one message buffer (16 bytes), to simplify usage issues, channels should be used in a sequentially ascending order starting with channel 0. To better understand the buffer memory requirements of the CAN module, consider the following examples: Example 1: Two transmit channels (each with eight message buffers) and one full receive channel (with 10 message buffers): • Two transmit channels with eight message buffers: 2 * 8 * 16 = 256 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • Total memory required in bytes = 416 bytes Example 2: Four transmit channels (two with eight message buffers and other two with 10 message buffers) and two full receive channels (one with 10 message buffers and one with 20 message buffers): • Two transmit channels with eight message buffers: 2 * 8 * 16 = 256 bytes • Two transmit channels with 10 message buffers: 2 * 10 * 16 = 320 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • One receive channel with 20 message buffers: 1 * 20 * 16 = 320 bytes • Total memory required in bytes = 1056 bytes 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1558 Example 3: One transmit channel (with maximum message buffers) and two receive Channels (one full receive with 10 message buffers and one data-only channel with maximum message buffers): • One transmit channel with maximum (32) message buffers: 1 * 32 * 16 = 512 bytes • One receive channel with 10 message buffers: 1 * 10 * 16 = 160 bytes • One data-only receive channel with 32 message buffers: 1 * 32 * 8 = 256 bytes • Total memory required in bytes = 928 bytes The PLIB_CAN_MemoryBufferAssign function is used to assign a memory buffer to the CAN module, which is shown in the following example. /* Assign the buffer area to the CAN module. * In this case assign enough memory for 2 * channels, each with 8 message buffers.*/ uint8_t MY_CAN_MessageFifoArea[2 * 8 * 16]; PLIB_CAN_MemoryBufferAssign(CAN_ID_1, MY_CAN_MessageFifoArea,(2 * 8 * 16)); 5.6.4.4.2.4 Channel Configuration To transmit and receive CAN messages, the user application must configure channels. The PLIB_CAN_ChannelForTransmitSet function is used to configure a channel for transmit operation. The PLIB_CAN_ChannelForReceiveSet function is used to configure a channel for receive operation. Note: To receive CAN messages, at least one message acceptance filter with a receive channel must be configured. A CAN Transmit channel can be enabled to process a Remote Transmit Request (RTR). In this case, the transmit channel will automatically transmit all queued messages when an RTR message is accepted by the CAN module. The following code shows an example of configuring a CAN Transmit channel. /* Configure CAN1 Channel 0 for Transmit operation. Allocate 8 message buffer, * disable the RTR feature and assign low medium priority for transmissions. */ PLIB_CAN_ChannelForTransmitSet(CAN_ID_1, CAN_CHANNEL0, 8, CAN_TX_RTR_DISABLED, CAN_LOW_MEDIUM_PRIORITY); A CAN receive channel can be enabled to store the data payload portion of an accepted message. This mode is called the Data-only mode. The CAN module otherwise stores both the ID and data payload portion of the accepted message. The following code shows an example of configuring a CAN Receive channel. /* Configure CAN1 Channel 1 for Receive operation. Allocate 8 message buffers, * disable the Data-only feature (specify full receive mode). */ PLIB_CAN_ChannelForReceiveSet(CAN_ID_1, CAN_CHANNEL1, 8, CAN_RX_FULL_RECEIVE); 5.6.4.4.2.5 Filters and Masks Configuration The CAN message acceptance filter allows an application to accept only selected messages from the CAN bus. The CAN module achieves this by comparing the Standard or Extended ID of a message with the configured filter ID. The message is accepted on an ID match. The accepted message is stored in the configured destination channel. The CAN message acceptance filter mask directs the CAN module to ignore specified bits in the filter comparison. This allows the application to accept messages within an ID range. At least one filter and one mask must be configured for the CAN module to be able to receive messages. The destination channel for a filter must be a receive channel unless the channel is a transmit channel with the RTR feature enabled. The PLIB_CAN_FilterConfigure function is used to configure a message acceptance filter. The PLIB_CAN_FilterMaskConfigure function is used to configure a message acceptance filter mask. The filter and mask must be linked together to a channel. This is done using the PLIB_CAN_FilterToChannelLink function. The CAN filter should be enabled to allow messages to be processed. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1559 This is done using the PLIB_CAN_FilterEnable function. To better understand how the filter and masks can be used to implement filtering, consider the following code examples: Example 1: Configure a CAN filter to accept a Standard ID message with ID 0x201 /* Only one message ID is to be accepted. All bits are to be compared * hence the mask value should be 0x7FF. The message type is Standard ID. * Configure CAN1, Filter 0, Mask 0 and set the destination channel as * Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x201, CAN_SID); PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x7FF, CAN_SID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Example 2: Configure a CAN filter to accept an Extended ID message with ID 0x8004001 /* Only one message ID is to be accepted. All bits are to be compared * hence the mask value should be 0x8004001. The message type is Extended ID. * Configure CAN1, Filter 0, Mask 0 and set the destination channel as * Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x8004001, CAN_EID); PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x3FFFFFFF, CAN_EID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Example 3: Configure a CAN filter to accept an Extended ID message within ID range 0x8004000 - 0x8004003 /* A message ID range is to be implemented. The 2 least significant bits can be * ignored. Therefore, the mask value should be 0x3FFFFFFC. The message type is * Extended ID. Configure CAN1, Filter 0, Mask 0 and set the destination channel * as Channel 1. */ PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER0, 0x8004000, CAN_EID); PLIB_CAN_FilterMaskConfigure(CAN_ID_1, CAN_FILTER_MASK0, 0x3FFFFFFC, CAN_EID, CAN_FILTER_MASK_IDE_TYPE); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER0, CAN_FILTER_MASK0, CAN_CHANNEL1); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER0); Note: Refer to About CAN Bus Protocol for more information on Standard and Extended ID addressing. 5.6.4.4.2.6 Enabling Events The CAN module can generate events that indicate the status of the module. Events can be generated at the channel level and at the module level. Enabling a channel event will cause the CAN module to generate a module level event when the channel event occurs. Enabling a module event will cause the CAN module to interrupt the CPU. The following code shows an example of using the PLIB_CAN_ChannelEventEnable and PLIB_CAN_ModuleEventEnable functions to enable channel and module events. /* Enable the Receive channel not empty and Receive channel * full events at the channel level. Enable the Receive event * at the module level. */ PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, (CAN_RX_CHANNEL_NOT_EMPTY|CAN_RX_CHANNEL_FULL)); PLIB_CAN_ModuleEventEnable (CAN_ID_1, CAN_RX_EVENT); Note: The caller must use the Interrupt Peripheral Library to enable the CAN CPU interrupt. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1560 5.6.4.4.3 Transmitting a CAN Message The caller application can transmit a CAN message by queuing the message in a transmit channel, updating the channel, and then flushing it. Flushing a transmit channel will cause the CAN module to transmit all of the CAN messages that are queued in the channel. The PLIB_CAN_TransmitBufferGet function should be used to obtain a CAN_TX_MSG_BUFFER handle type to an empty message buffer. The application should then populate this buffer. The PLIB_CAN_ChannelUpdate function must be called when the buffer has been populated. Finally, the PLIB_CAN_TransmitChannelFlush function is called to flush the channel. The following code shows an example of transmitting an Extended ID message using Channel 0 on the CAN1 module. CAN_TX_MSG_BUFFER * My_Message; /* Get a pointer to the next buffer in the Transmit channel * check if the returned value is null. */ My_Message = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL0); if(My_Message != NULL) { /* Form a Extended ID CAN message. Start by clearing the buffer. Set the IDE bit to 1 to indicate extended ID message. Clear RTR bit as this is not a RTR message. */ My_Message->messageWord[0] = 0; My_Message->messageWord[1] = 0; My_Message->messageWord[2] = 0; My_Message->messageWord[3] = 0; My_Message->msgSID.sid = 0x200; My_Message->msgEID.eid = 0x4002; My_Message->msgEID.ide = 1; My_Message->msgEID.sub_remote_req = 0; My_Message->msgEID.data_length_code = 1; My_Message->data[0] = 0xAA; /* This function lets the CAN module know that the message processing is done.*/ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL0); /* Direct the CAN module to flush the Transmit channel. This will send any pending message in the Transmit channel. */ PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL0); } Note: The PLIB_CAN_TransmitBufferGet function will return NULL if the transmit channel is full. In this occurs, the PLIB_CAN_TransmitChannelFlush function should be called to empty the channel. The following code shows an example of transmitting a Standard ID message using Channel 0 on the CAN1 module. CAN_TX_MSG_BUFFER * myMessage; /* Get a pointer to the next buffer in the channel check if the returned value is null. */ myMessage = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL0); if(myMessage != NULL) { /* Form a Standard ID CAN message. Start by clearing the buffer. Send message to the CAN2 module. IDE = 0 means Standard ID message. Send one byte of data. */ myMessage->messageWord[0] = 0; myMessage->messageWord[1] = 0; 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1561 myMessage->messageWord[2] = 0; myMessage->messageWord[3] = 0; myMessage->msgSID.sid = 0x202; myMessage->msgEID.ide = 0; myMessage->msgEID.data_length_code = 1; myMessage->data[0] = 0x23; /* This function lets the CAN module know that the message processing is done and message is ready to be processed. */ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL0); /* Direct the CAN module to flush the Transmit channel. This will send any pending message in the Transmit channel. */ PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL0); } 5.6.4.4.4 Receiving a CAN Message The caller application can use either the interrupt or polling technique to detect when a message has been received. The following code shows how the PLIB_CAN_ReceivedMessageGet function can be used to read a received message. CAN_RX_MSG_BUFFER * message; message = (CAN_RX_MSG_BUFFER *)PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL1); if(message != NULL) { //Process the message received /* Call the PLIB_CAN_ChannelUpdate function to let the CAN module know that the message processing is done. */ PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL1); } The PLIB_CAN_ReceivedMessageGet() function returns NULL if the channel is empty. 5.6.4.4.5 Handling Events The CAN module can generate events at the channel level and at the module level. An enabled channel event will cause a module event. An enabled module event will cause a CAN CPU interrupt. See Channel Events and Module Events more information on each type of event. 5.6.4.4.5.1 Channel Events Each channel in the module has its own set of events. The type of events are common to all channels. While a specific channel event may be active and can be inspected, it will cause a module event only if the channel event is enabled. The following code shows an example of enabling and disabling channel events using the PLIB_CAN_ChannelEventEnable function. /* CAN 1 Channel 1 and 3 are Transmit channels and Channel 2 and 4 are Receive channels */ /* Enable Channel 1 empty event and channel not full event. Disable Channel 2 full and overflow event */ /* Enable all Transmit events on Channel 2 and disable all RX events on Channel 4 */ PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1562 (CAN_TX_CHANNEL_EMPTY | CAN_TX_CHANNEL_NOT_FULL)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL2, (CAN_RX_CHANNEL_FULL | CAN_RX_CHANNEL_OVERFLOW)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL3, CAN_TX_CHANNEL_ANY_EVENT); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL4, CAN_RX_CHANNEL_ANY_EVENT); The PLIB_CAN_ModuleEventGet function can be used to check if a specific event is active in a specific channel. It is only necessary for the event to be active and not enabled for this to work, as shown in the following code example. // Check if RX Channel 2 of CAN module 1 is not empty or if its full. CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either RX Channel 2 is not empty // or the Channel is full. } If a channel event is enabled and is active, it will set a channel event status flag. This flag indicates that some event in the channel is active. The following code example shows how the PLIB_CAN_AllChannelEventsGet function is used to check if any channel event is active. /* Check if RX Channel 2 of CAN module 1 is not empty or if its full */ CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either RX Channel 2 is not empty // or the Channel is full. } A receive channel overflow condition is special channel event and is available as a module event as well. The PLIB_CAN_AllChannelOverflowStatusGet function returns the status of all channels that have an active overflow event. Only channels with enabled overflow events will be reflected. The following code shows an example of how this function is used. /* Check if Channel 2 or 3 of CAN module 1 have any active events */ CAN_CHANNEL_MASK channelEvents; channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_1); if((channelEvents & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Channel 2 or 3 has an active event. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } 5.6.4.4.5.2 Module Events The CAN module has various sources of events, which includes the channel events. The PLIB_CAN_ModuleEventEnable function can be used to enable and disable module level events. Enabling a module event will cause the CAN module to generate a CPU interrupt, as shown in the following code example. // Enable CAN1 module Transmit Event and Receive Events. // Disable Receive Overflow event and operation // mode change event. PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1563 PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | CAN_RX_OVERFLOW_EVENT)); The PLIB_CAN_ModuleEventGet function can be used to check if any module level events are active. This is shown in the code snippet below. // Check if the CAN Module 1 Receive event // or if Transmit event is active if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & (CAN_RX_EVENT | CAN_TX_EVENT)) != 0) { // Handle the Receive or Transmit module Event here. } The CAN module also provides code to indicate the highest priority pending event in the CAN module. The PLIB_CAN_PendingEventsGet function can be used to read and analyze this code, as shown in the following code example. /* Implement a switch to check and process any active CAN module events */ CAN_EVENT_CODE eventCode; eventCode = PLIB_CAN_PendingEventsGet(CAN_ID_1); switch(eventCode) { case CAN_NO_EVENT: /* Procedure to handle no CAN events */ break; case CAN_WAKEUP_EVENT: /* Procedure to handle device wake-up on CAN bus activity event */ break; default: break; } 5.6.4.4.6 Using the Library This topic describes the basic architecture of the CAN Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_can.h The interface to the CAN Peripheral library is defined in the "plib_can.h" header file. Any C language source (.c) file that uses the CAN Peripheral library should include "peripheral.h". Library File: The CAN Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.4.4.6.1 Hardware Abstraction Model Note: The interface provided is a super set of all of the functionality of the available CAN on the device. Refer to the specific device data sheet or the related family reference manual to determine the set of functions that are supported for each CAN module on the device. This library provides the low-level abstraction of the CAN module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. CAN Software Abstraction Block Diagram 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1564 Software Model: The CAN Peripheral Library provides interface routines to interact with the blocks shown in the diagram above. A channel can be either a transmit channel or a receive channel. The size of a CAN message is typically 16 bytes (8 bytes for data-only receive messages). The size of a channel (the number of messages it can buffer) is configurable. Each channel has a minimum size of one message buffer. The message buffer area for all channels is assigned at configuration time. The CAN Peripheral Library then provides access to these channels and buffers via the library interface. The user code must enable and configure message acceptance filters to receive messages. These filters compare the ID field of the incoming message with configured value and accepts the messages if IDs match. The message is then stored in a selectable receive channel. At least one message acceptance filter and one filter mask should be enabled for the CAN module to receive messages. A filter mask allows specified filter bits to be ignored during the comparison process. This allows the filter to accept a message with an ID range. The CAN Peripheral Library allows the CAN module to generate events. Events can be generated at the channel level and at the module level. Events: The CAN module is capable of notifying the user application when specific events occur in the module. The following diagram shows these events and how they are organized. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1565 There are two types of events in the CAN module: Channel events and Module events. Channel events are generated by transmit and receive channels. Module events are generated by various sources (including channels) within the CAN module. Each event can be enabled or disabled. Enabling a channel event will cause the CAN module to generate a module event. An enabled module level event will cause the CAN module to generate an interrupt to the CPU. The application can also poll channel events to check if these are active. This may be done in cases where a polling scheme (rather than an interrupt scheme) needs to be implemented. In this case, the CAN module provides events status on a channel basis. If a channel event is found active, the application can then use library API calls to inspect which channel condition caused the channel event. 5.6.4.4.6.2 Library Overview The library interface routines are divided into various subsections, each of the sub section addresses one of the blocks or the overall operation of the CAN module. Library Interface Section Description Basic Configuration APIs that are used for basic control of the module, such as enabling and disabling the module. Advanced Configuration Advance configuration, such as selection of the operation mode. Bus Speed Configuration Bus speed configuration. Event Management APIs to manage the events. Message Transmit Functions Transmit APIs. Message Receive Functions APIs that are related to data reception. Error State Tracking Error tracking. Information Functions Information about the module. 5.6.4.4.7 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1566 5.6.4.5 Library Interface Data Types and Constants Name Description CAN_CHANNEL Identifies the supported CAN Channels. CAN_CHANNEL_EVENT Identifies all Layer 3 interrupts. CAN_CHANNEL_MASK Lists the series of useful masks. CAN_DNET_FILTER_SIZE Specifies the size of the DeviceNet filter. CAN_ERROR_STATE Specifies the CAN module error states. CAN_FILTER CAN event code returned by the CAN module. CAN_FILTER_MASK Identifies the available CAN filter masks. CAN_FILTER_MASK_TYPE Specifies the CAN filter mask type. CAN_FUNCTONAL_MODES Lists all possible CAN module functional modes. CAN_ID_TYPE Specifies the CAN ID type. CAN_MODULE_EVENT Specifies the CAN module events CAN_MODULE_ID Enumeration: CAN_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. CAN_MSG_EID Defines the structure of the EID word section of the transmit and receive message. CAN_OPERATION_MODES Lists all possible CAN module operational modes. CAN_RECEIVE_CHANNEL Lists all possible CAN module receive channels. CAN_RECEIVE_MODES Lists all possible CAN module receive modes. CAN_RX_DATA_MODE Enables the Data-only Receive mode or Full Receive mode of a CAN receive channel. CAN_RX_MSG_BUFFER Defines the structure of the CAN receive message buffer CAN_RX_MSG_SID Defines the structure of the SID word section of the receive message. CAN_TIME_SEGMENT_LENGTH All possible values for the assignable number of Time Quanta. CAN_TX_CHANNEL_STATUS Identifies possible transmit channel-specific conditions. CAN_TX_MSG_BUFFER Defines the structure of the CAN transmit message buffer. CAN_TX_MSG_SID Defines the structure of the SID word section of the transmit message. CAN_TX_RTR Specifies the status of the CAN Remote Transmit Request (RTR) feature for a CAN transmit channel. CAN_TXCHANNEL_PRIORITY Specifies the priority of a transmit channel. CAN_RX_DATA_ONLY_SIZE_BYTES Used as the size of the CAN data-only receive message buffer in bytes. CAN_TX_RX_MESSAGE_SIZE_BYTES Used as the array size of the CAN transmit and full receive message buffer. Advanced Configuration Name Description PLIB_CAN_ChannelResetIsComplete Returns 'true' if the specified channel reset is complete. PLIB_CAN_DeviceNetConfigure Configures the CAN module DeviceNet(TM) filter feature. PLIB_CAN_FunctionalModeGet Obtains the functional mode of the CAN module. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1567 PLIB_CAN_MemoryBufferAssign Assigns buffer memory to the CAN module. PLIB_CAN_TimeStampPrescalarSet Sets the CAN receive message time stamp timer prescalar. PLIB_CAN_TimeStampValueGet Returns the current value of the CAN receive message time stamp timer value. PLIB_CAN_TimeStampValueSet Sets the CAN receive message time stamp timer value. PLIB_CAN_FunctionalModeSelect Selects the functional mode of the CAN module. Basic Configuration Name Description PLIB_CAN_BusActivityWakeupDisable Disables the wake-up on bus activity receive line filter. PLIB_CAN_BusActivityWakeupEnable Enables the wake-up on bus activity receive line filter. PLIB_CAN_Disable Disables the specified CAN module. PLIB_CAN_Enable Enables the specified CAN module. PLIB_CAN_IsActive Returns 'true' if the CAN module is active. PLIB_CAN_OperationModeGet Obtains the current CAN operating mode. PLIB_CAN_OperationModeSelect Sets the CAN operating mode. PLIB_CAN_StopInIdleDisable Disables the Stop in Idle feature. PLIB_CAN_StopInIdleEnable Enables the CAN module to stop when the processor enters Idle mode. PLIB_CAN_TimeStampDisable Disables the time stamp feature for the CAN module. PLIB_CAN_TimeStampEnable Enables the time stamp feature for the CAN module. Bus Speed Configuration Name Description PLIB_CAN_BusLine3TimesSamplingDisable Disables the bus line three times sampling. PLIB_CAN_BusLine3TimesSamplingEnable Enables the bus line three times sampling. PLIB_CAN_PhaseSegment1LengthSet Selects the CAN phase buffer segment1 length. PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable Disables the CAN phase buffer segment2 length freely programmable mode. PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable Makes the CAN phase buffer segment2 length freely programmable. PLIB_CAN_PhaseSegment2LengthSet Selects the CAN phase buffer segment2 length. PLIB_CAN_PropagationTimeSegmentSet Selects the propagation time segment. PLIB_CAN_SyncJumpWidthSet Selects the synchronization jump width. Channel Configuration Name Description PLIB_CAN_ChannelForReceiveSet Configures a CAN channel for receive operation. PLIB_CAN_ChannelForTransmitSet Configures a CAN channel for transmission. PLIB_CAN_ChannelReset Resets a CAN channel. PLIB_CAN_ChannelUpdate Updates the CAN Channel internal pointers. PLIB_CAN_ChannelEventDisable Enables channel level events. Error State Tracking Name Description PLIB_CAN_ReceiveErrorCountGet Returns the CAN receive error count. PLIB_CAN_ErrorStateGet Returns the CAN error status word. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1568 Event Management Name Description PLIB_CAN_ModuleEventClear Clears the CAN module level events. PLIB_CAN_ModuleEventDisable Disables the module level events. PLIB_CAN_ModuleEventEnable Enables the module level events. PLIB_CAN_ModuleEventGet Returns the status of the CAN module events. PLIB_CAN_AllChannelEventsGet Returns a value representing the event status of all CAN channels. PLIB_CAN_AllChannelOverflowStatusGet Returns a value representing the receive overflow event status of all CAN channels. PLIB_CAN_ChannelEventClear Clears CAN channel events. PLIB_CAN_ChannelEventEnable Enables channel level events. PLIB_CAN_ChannelEventGet Returns a value representing the event status of a CAN channel. PLIB_CAN_PendingEventsGet Returns a value representing the highest priority active event in the module. Feature Existance Routines Name Description PLIB_CAN_ExistsActiveStatus Identifies whether the ActiveStatus feature exists on the CAN module. PLIB_CAN_ExistsAllChannelEvents Identifies whether the AllChannelEvents feature exists on the CAN module. PLIB_CAN_ExistsAllChannelOverflow Identifies whether the AllChannelOverflow feature exists on the CAN module. PLIB_CAN_ExistsBusActivityWakeup Identifies whether the BusActivityWakeup feature exists on the CAN module. PLIB_CAN_ExistsBusLine3TimesSampling Identifies whether the BusLine3TimesSampling feature exists on the CAN module. PLIB_CAN_ExistsChannelEvent Identifies whether the ChannelEventGet feature exists on the CAN module. PLIB_CAN_ExistsChannelEventEnable Identifies whether the ChannelEventEnable feature exists on the CAN module. PLIB_CAN_ExistsChannelForReceiveSet Identifies whether the ChannelForReceiveSet feature exists on the CAN module. PLIB_CAN_ExistsChannelForTransmitSet Identifies whether the ChannelForTransmitSet feature exists on the CAN module. PLIB_CAN_ExistsChannelReset Identifies whether the ChannelReset feature exists on the CAN module. PLIB_CAN_ExistsChannelUpdate Identifies whether the ChannelUpdate feature exists on the CAN module. PLIB_CAN_ExistsDeviceNet Identifies whether the DeviceNet feature exists on the CAN module. PLIB_CAN_ExistsEnableControl Identifies whether the EnableControl feature exists on the CAN module. PLIB_CAN_ExistsErrorState Identifies whether the ErrorStateGet feature exists on the CAN module. PLIB_CAN_ExistsFilterConfigure Identifies whether the FilterConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterEnable Identifies whether the FilterEnable feature exists on the CAN module. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1569 PLIB_CAN_ExistsFilterMaskConfigure Identifies whether the FilterMaskConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterToChannelLink Identifies whether the FilterToChannelLink feature exists on the CAN module. PLIB_CAN_ExistsFunctionalMode Identifies whether the FunctionalModeSelect feature exists on the CAN module. PLIB_CAN_ExistsLatestFilterMatchGet Identifies whether the LatestFilterMatchGet feature exists on the CAN module. PLIB_CAN_ExistsMemoryBufferAssign Identifies whether the MemoryBufferAssign feature exists on the CAN module. PLIB_CAN_ExistsMessageIsReceived Identifies whether the MessageIsReceived feature exists on the CAN module. PLIB_CAN_ExistsModuleEventClear Identifies whether the ModuleEvents feature exists on the CAN module. PLIB_CAN_ExistsModuleEventEnable Identifies whether the ModuleEventEnable feature exists on the CAN module. PLIB_CAN_ExistsModuleInfo Identifies whether the ModuleInformation feature exists on the CAN module. PLIB_CAN_ExistsOperationModeRead Identifies whether the OperationModeRead feature exists on the CAN module. PLIB_CAN_ExistsOperationModeWrite Identifies whether the OperationModeSet feature exists on the CAN module. PLIB_CAN_ExistsPendingEventsGet Identifies whether the PendingEventsGet feature exists on the CAN module. PLIB_CAN_ExistsPendingTransmissionsAbort Identifies whether the PendingTransmissionsAbort feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment1Length Identifies whether the PhaseSegment1Length feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment2Length Identifies whether the PhaseSegment2Length feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable Identifies whether the PhaseSegment2LengthFreelyProgrammable feature exists on the CAN module. PLIB_CAN_ExistsPropagationTimeSegment Identifies whether the PropagationTimeSegment feature exists on the CAN module. PLIB_CAN_ExistsReceiveBufferClear Identifies whether the ReceiveBufferClear feature exists on the CAN module. PLIB_CAN_ExistsReceiveBufferIsEmpty Identifies whether the ReceiveBufferIsEmpty feature exists on the CAN module. PLIB_CAN_ExistsReceivedMessageGet Identifies whether the ReceivedMessageGet feature exists on the CAN module. PLIB_CAN_ExistsReceiveErrorCount Identifies whether the ReceiveErrorCount feature exists on the CAN module. PLIB_CAN_ExistsReceiveModeSelect Identifies whether the ReceiveModeSelect feature exists on the CAN module. PLIB_CAN_ExistsRemoteTransmitReq Identifies whether the RemoteTransmitReq feature exists on the CAN module. PLIB_CAN_ExistsRxFIFOFourLeftNotify Identifies whether the RxFIFOFourLeftNotify feature exists on the CAN module. PLIB_CAN_ExistsRxFIFOOneLeftNotify Identifies whether the RxFIFOOneLeftNotify feature exists on the CAN module. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1570 PLIB_CAN_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CAN module. PLIB_CAN_ExistsSyncJumpWidthSet Identifies whether the SyncJumpWidth feature exists on the CAN module. PLIB_CAN_ExistsTimeStampEnable Identifies whether the TimeStampEnable feature exists on the CAN module PLIB_CAN_ExistsTimeStampPrescalar Identifies whether the TimeStampPrescalar feature exists on the CAN module. PLIB_CAN_ExistsTimeStampValue Identifies whether the TimeStampValue feature exists on the CAN module. PLIB_CAN_ExistsTransmissionIsAborted Identifies whether the TransmissionAbortStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitBufferGet Identifies whether the TransmitBufferGet feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelFlush Identifies whether the TransmitChannelFlush feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelStatus Identifies whether the TransmitChannelStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitErrorCountGet Identifies whether the TransmitErrorCountGet feature exists on the CAN module. Information Functions Name Description PLIB_CAN_TotalChannelsGet Returns the total number of CAN channels per CAN module. PLIB_CAN_TotalFiltersGet Returns the total number of CAN Filters per CAN module. PLIB_CAN_TotalMasksGet Returns the total number of CAN masks per CAN module. Message Filtering Functions Name Description PLIB_CAN_FilterConfigure Configures a CAN message acceptance filter. PLIB_CAN_FilterDisable Disables a CAN message acceptance filter. PLIB_CAN_FilterEnable Enables a CAN message acceptance filter. PLIB_CAN_FilterIsDisabled Returns 'true' if the specified filter is disabled. PLIB_CAN_FilterMaskConfigure Configures a CAN filter mask. PLIB_CAN_FilterToChannelLink Links a filter to a channel. PLIB_CAN_LatestFilterMatchGet Returns the index of the filter that accepted the latest message. Message Receive Functions Name Description PLIB_CAN_ReceivedMessageGet Returns a pointer to a message to be read from the CAN channel. PLIB_CAN_RxFIFOFourLeftNotify Configures the module to generate an interrupt when the FIFO has four receive buffers left. PLIB_CAN_RxFIFOOneLeftNotify Configures the module to generate an interrupt when the FIFO has only one receive buffer left. PLIB_CAN_ReceiveModeSelect Selects the receive mode of the CAN module. PLIB_CAN_ReceiveModeGet Obtains the receive mode of the CAN module. PLIB_CAN_MessageIsReceived Returns whether a message was received and the receive buffer is not empty. PLIB_CAN_ReceiveBufferIsEmpty Returns whether the receive buffer of the specified channel is empty. PLIB_CAN_ReceiveBufferClear Clears the received message flag. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1571 PLIB_CAN_RemoteTransmitReqIsReceived Returns whether the message received is a remote transmit request. Message Transmit Functions Name Description PLIB_CAN_PendingTransmissionsAbort Aborts any pending transmit operations. PLIB_CAN_TransmissionIsAborted Returns 'true' if the transmit abort operation is complete. PLIB_CAN_TransmitBufferGet Returns a pointer to an empty transmit buffer. PLIB_CAN_TransmitChannelFlush Causes all messages in the specified transmit channel to be transmitted. PLIB_CAN_TransmitChannelStatusGet Returns the condition of the transmit channel. PLIB_CAN_TransmitErrorCountGet Returns the CAN transmit error count Description This section describes the APIs of the CAN Peripheral. Refer to each section for a detailed description. 5.6.4.5.1 Basic Configuration 5.6.4.5.1.1 PLIB_CAN_BusActivityWakeupDisable Function C void PLIB_CAN_BusActivityWakeupDisable( CAN_MODULE_ID index ); Description This function disables the Wake up on bus activity receive line filter. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusActivityWakeup in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_BusActivityWakeupDisable(MY_CAN_ID); 5.6.4.5.1.2 PLIB_CAN_BusActivityWakeupEnable Function C void PLIB_CAN_BusActivityWakeupEnable( 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1572 CAN_MODULE_ID index ); Description This function enables the wake-up on bus activity receive line filter. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusActivityWakeup in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_BusActivityWakeupEnable(MY_CAN_ID); 5.6.4.5.1.3 PLIB_CAN_Disable Function C void PLIB_CAN_Disable( CAN_MODULE_ID index ); Description This function disables the specified CAN module. Preconditions None Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). If the user application clears this bit, it may take a number of cycles before the CAN module completes the current transaction and responds to this request. The user application should check this using the PLIB_CAN_IsActive function to verify that the request has been honored. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1573 This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsEnableControl in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_Disable(MY_CAN_ID); 5.6.4.5.1.4 PLIB_CAN_Enable Function C void PLIB_CAN_Enable( CAN_MODULE_ID index ); Description This function enables the specified CAN module. Preconditions The module should be appropriately configured before being enabled. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). Some of the CAN module settings can be done only when the module is off. Therefore, always call the PLIB_CAN_Enable Function after all other configurations are complete. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsEnableControl in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 //Do all the other configurations before enabling. PLIB_CAN_Enable(MY_CAN_ID); 5.6.4.5.1.5 PLIB_CAN_IsActive Function C bool PLIB_CAN_IsActive( CAN_MODULE_ID index ); Description This function returns 'true' if the CAN module is active. This function is typically called after the CAN module is disabled using the PLIB_CAN_Disable function. The CAN module disable request does not complete immediately when requested and depends on 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1574 the CAN bus status. This function should be called to check whether the module disable is completed. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns • true = The module is still active • false = The module is completely disabled Remarks The CAN module disable operation should not be confused with placing the CAN module in the Disable mode using the PLIB_CAN_OperationModeSelect function. The Disable mode is one of the operating modes of the CAN module. The CAN module is still enabled while in Disable mode. The module disable operation switches the CAN module off. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsActiveStatus in your application to determine whether this feature is available. Example // Disable CAN module 1. Wait until the module is completely disabled. PLIB_CAN_Disable(CAN_ID_1); while(PLIB_CAN_IsActive(CAN_ID_1) == true); 5.6.4.5.1.6 PLIB_CAN_OperationModeGet Function C CAN_OPERATION_MODES PLIB_CAN_OperationModeGet( CAN_MODULE_ID index ); Description This function obtains the current CAN operating mode. This function is typically called after the PLIB_CAN_OperationModeSelect function to check if the requested operation mode change is complete. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns The current CAN_OP_MODE type of operation mode of the CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsOperationModeRead in your application to determine whether this feature is available. Example // Check and wait until the CAN module is in Disable Mode. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1575 while(PLIB_CAN_OperationModeGet(CAN_ID_1) != CAN_DISABLE_MODE); 5.6.4.5.1.7 PLIB_CAN_OperationModeSelect Function C void PLIB_CAN_OperationModeSelect( CAN_MODULE_ID index, CAN_OPERATION_MODES opMode ); Description This function sets the CAN operating mode. The CAN module requires itself to be in certain modes to gain access to module functionality. For example, the module should be in Normal mode to send and receive messages. Note that after this function is called, it should be checked to determine whether the mode was set by using the PLIB_CAN_OperationModeGet function. Preconditions None. Parameters Parameters Description module Identifies the desired CAN module opMode Desired CAN_OP_MODE type of the mode to be set Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsOperationModeWrite in your application to determine whether this feature is available. Example // Set the CAN_ID_1 operating mode to Configuration mode. PLIB_CAN_OperationModeSelect(CAN_ID_1, CAN_CONFIGURATION_MODE); 5.6.4.5.1.8 PLIB_CAN_StopInIdleDisable Function C void PLIB_CAN_StopInIdleDisable( CAN_MODULE_ID index ); Description This function disables the CAN module from stopping operation when the system enters Idle mode. The module continues operation when the system enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1576 Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_StopInIdleDisable(MY_CAN_ID); 5.6.4.5.1.9 PLIB_CAN_StopInIdleEnable Function C void PLIB_CAN_StopInIdleEnable( CAN_MODULE_ID index ); Description This function configures the CAN module to stop operation when the system enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_StopInIdleEnable(MY_CAN_ID); 5.6.4.5.1.10 PLIB_CAN_TimeStampDisable Function C void PLIB_CAN_TimeStampDisable( CAN_MODULE_ID index ); Description This function disables time stamp capture feature for the CAN module. This conserves power by stopping the CAN timer. Preconditions None 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1577 Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampEnable in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_TimeStampDisable(MY_CAN_ID); 5.6.4.5.1.11 PLIB_CAN_TimeStampEnable Function C void PLIB_CAN_TimeStampEnable( CAN_MODULE_ID index ); Description This function enables the time stamp capture feature for the CAN module. The CAN timer value will be stored on valid message reception and is stored with the message. Preconditions None Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampEnable in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 PLIB_CAN_TimeStampEnable(MY_CAN_ID); 5.6.4.5.2 Advanced Configuration 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1578 5.6.4.5.2.1 PLIB_CAN_ChannelResetIsComplete Function C bool PLIB_CAN_ChannelResetIsComplete( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns 'true' if the specified channel reset is complete. This function should preferably be called after calling the PLIB_CAN_ChannelReset function. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the CAN Channel to be inspected for reset Returns • true = Channel reset is complete • false = Channel reset is in progress Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelReset in your application to determine whether this feature is available. Example // Reset channel 4 of CAN_ID_1 module // and wait until the reset is complete PLIB_CAN_ChannelReset(CAN_ID_1,CAN_CHANNEL4); while(PLIB_CAN_ChannelResetIsComplete(CAN_ID_1,CAN_CHANNEL4) != true); 5.6.4.5.2.2 PLIB_CAN_DeviceNetConfigure Function C void PLIB_CAN_DeviceNetConfigure( CAN_MODULE_ID index, CAN_DNET_FILTER_SIZE dncnt ); Description This function configures the CAN module DeviceNet filter feature. DeviceNet filtering allows a portion of the data payload to be used as a filter criteria. This function allows the size of this filter to be configured in bits. The filter can also be disabled. Preconditions The CAN module should preferably be in Configuration mode (using the PLIB_CAN_OperationModeSelect function). Parameters Parameters Description index Identifies the desired CAN module dncnt Specifies the CAN_DNET_FILTER_SIZE size of the DeviceNet filter in bits 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1579 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsDeviceNet in your application to determine whether this feature is available. Example // Disable the CAN_ID_1 DeviceNet filter feature. PLIB_CAN_DeviceNetConfigure(CAN_ID_1, CAN_DNET_FILTER_DISABLE); // Set the CAN_ID_2 Device Net Filter Size to 10 bits. PLIB_CAN_DeviceNetConfigure(CAN_ID_2, CAN_DNET_FILTER_SIZE_10_BIT); 5.6.4.5.2.3 PLIB_CAN_FunctionalModeGet Function C CAN_FUNCTONAL_MODES PLIB_CAN_FunctionalModeGet( CAN_MODULE_ID index ); Description This function obtains the functional mode of the CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFunctionalMode in your application to determine whether this feature is available. Example CAN_FUNCTONAL_MODES funcMode; funcMode = PLIB_CAN_FunctionalModeGet(CAN_ID_1); 5.6.4.5.2.4 PLIB_CAN_MemoryBufferAssign Function C void PLIB_CAN_MemoryBufferAssign( CAN_MODULE_ID index, void * buffer, int sizeInBytes ); Description This function assigns buffer memory to the CAN module. The CAN module uses this buffer memory to store messages to be 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1580 transmitted and received. The size of the memory buffer should be enough to accommodate the required number of message buffers and channels. Preconditions The module should be in Configuration mode (using the PLIB_CAN_OperationModeSelect function). Parameters Parameters Description index Identifies the desired CAN module buffer Pointer to the buffer memory area sizeInBytes Size of the buffer memory is bytes Returns None. Remarks This API is useful only if the CAN module uses device RAM for message buffers and message FIFO location is software configurable. This should not be used if the device message buffer is part of SFR. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsMemoryBufferAssign in your application to determine whether this feature is available. Example // Define and assign a CAN 1 memory buffer for 2 Transmit channels and 1 Receive // channel, each with 4 message buffers uint8_t canMemoryBuffer [3 * 4 * CAN_TX_RX_MESSAGE_SIZE_BYTES]; PLIB_CAN_MemoryBufferAssign(CAN_ID_1, canMemoryBuffer, (3 * 4 * CAN_TX_RX_MESSAGE_SIZE_BYTES)); 5.6.4.5.2.5 PLIB_CAN_TimeStampPrescalarSet Function C void PLIB_CAN_TimeStampPrescalarSet( CAN_MODULE_ID index, unsigned prescalar ); Description This function sets the CAN receive message time stamp timer prescalar. This prescalar determines the rate at the which the time stamp timer is incremented. For example, if the prescalar value is 0xFF, the time stamp timer is incremented by 1 every 255 system clock periods. Preconditions None. Parameters Parameters Description module Identifies the desired CAN module prescalar Prescalar for the CAN receive message time stamp timer. This value should be between 0x0 and 0xFFFF. Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1581 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampPrescalar in your application to determine whether this feature is available. Example // Set the CAN_ID_1 Receive Message Time Stamp Timer prescalar to increment //the Timestamp Timer every 1024 system clock periods. PLIB_CAN_TimeStampPrescalarSet(CAN_ID_1, 1024); 5.6.4.5.2.6 PLIB_CAN_TimeStampValueGet Function C unsigned PLIB_CAN_TimeStampValueGet( CAN_MODULE_ID index ); Description This function gets the current value of the CAN receive message time stamp timer value. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns The current value of the CAN receive message time stamp timer. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampValue in your application to determine whether this feature is available. Example unsigned int timeStampTimerVal; // Get the current time stamp timer value. timeStampTimerVal = PLIB_CAN_TimeStampValueGet(CAN_ID_1); 5.6.4.5.2.7 PLIB_CAN_TimeStampValueSet Function C void PLIB_CAN_TimeStampValueSet( CAN_MODULE_ID index, unsigned value ); Description This function sets the CAN receive message time stamp timer value. The timer will then start counting up from this value. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1582 Parameters Parameters Description index Identifies the desired CAN module value Start value of the receive message yime stamp timer. This value should be between 0x0 and 0xFFFF. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTimeStampValue in your application to determine whether this feature is available. Example // Set start value of CAN_ID_1 Receive Message Time Stamp Timer to 0x100 PLIB_CAN_TimeStampValueSet(CAN_ID_1, 0x0100); 5.6.4.5.2.8 PLIB_CAN_FunctionalModeSelect Function C void PLIB_CAN_FunctionalModeSelect( CAN_MODULE_ID index, CAN_FUNCTONAL_MODES funcMode ); Description This function selects the functional mode of the CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module funcMode Select the functional mode of the CAN module. One of the possible values from CAN_FUNCTIONAL_MODES Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFunctionalMode in your application to determine whether this feature is available. Example PLIB_CAN_FunctionalModeSelect(CAN_ID_1, CAN_LEGACY_MODE0); 5.6.4.5.3 Bus Speed Configuration 5.6.4.5.3.1 PLIB_CAN_BusLine3TimesSamplingDisable Function C void PLIB_CAN_BusLine3TimesSamplingDisable( 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1583 CAN_MODULE_ID index ); Description The bus line will be sampled only once at the sampling point. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusLine3TimesSampling in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_BusLine3TimesSamplingDisable(MY_CAN_ID); } 5.6.4.5.3.2 PLIB_CAN_BusLine3TimesSamplingEnable Function C void PLIB_CAN_BusLine3TimesSamplingEnable( CAN_MODULE_ID index ); Description The bus line will be sampled three times at the sampling point. If this is disabled, the bus line will be sampled only once. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1584 This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This API may not function if the baud rate prescalar value is more than a certain limit. Refer to the specific device data sheet to determine the maximum prescalar that allows three times sampling. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsBusLine3TimesSampling in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_BusLine3TimesSamplingEnable(MY_CAN_ID); } 5.6.4.5.3.3 PLIB_CAN_PhaseSegment1LengthSet Function C void PLIB_CAN_PhaseSegment1LengthSet( CAN_MODULE_ID index, CAN_TIME_SEGMENT_LENGTH length ); Description This function selects the CAN phase buffer segment1 length. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module length Desired segment length Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPhaseSegment1Length in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_PhaseSegment1LengthSet(MY_CAN_ID, CAN_TIME_SEGMENT_LEN_8TQ); } 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1585 5.6.4.5.3.4 PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable Function C void PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable( CAN_MODULE_ID index ); Description This function disables the CAN phase buffer segment2 length freely programmable mode. The segment2 length will be the maximum of the segment1 length or information processing time, whichever is greater. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable(MY_CAN_ID); } 5.6.4.5.3.5 PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable Function C void PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable( CAN_MODULE_ID index ); Description This function makes the CAN phase buffer segment2 length freely programmable. If this mode is not set, the segment2 length will be the maximum of the segment1 length or information processing time, whichever is greater. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1586 Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable(MY_CAN_ID); } 5.6.4.5.3.6 PLIB_CAN_PhaseSegment2LengthSet Function C void PLIB_CAN_PhaseSegment2LengthSet( CAN_MODULE_ID index, CAN_TIME_SEGMENT_LENGTH length ); Description This function selects the CAN phase buffer segment2 length. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module length Desired segment length, select from CAN_TIME_SEGMENT_LENGTH enum Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This function will not work if the freely programmable mode is disabled. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1587 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPhaseSegment2Length in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable(MY_CAN_ID); PLIB_CAN_PhaseSegment2LengthSet(MY_CAN_ID, CAN_TIME_SEGMENT_LEN_8TQ); } 5.6.4.5.3.7 PLIB_CAN_PropagationTimeSegmentSet Function C void PLIB_CAN_PropagationTimeSegmentSet( CAN_MODULE_ID index, CAN_TIME_SEGMENT_LENGTH length ); Description This function selects the propagation time segment. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module. Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in configuration mode. Use PLIB_CAN_OperationModeGet function to get the current mode and PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPropagationTimeSegment in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_PropagationTimeSegmentSet(MY_CAN_ID, CAN_TIME_SEGMENT_LEN_8TQ); } 5.6.4.5.3.8 PLIB_CAN_SyncJumpWidthSet Function C void PLIB_CAN_SyncJumpWidthSet( CAN_MODULE_ID index, CAN_TIME_SEGMENT_LENGTH length 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1588 ); Description This function selects the synchronization jump width. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns None. Remarks The MY_CAN_ID macro in the example above is used as a placeholder for the actual CAN bus ID (as defined by the processor-specific CAN_MODULE_ID enum). This function works only if the CAN module is in Configuration mode. Use the PLIB_CAN_OperationModeGet function to get the current mode and the PLIB_CAN_OperationModeSelect function to change the mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsSyncJumpWidthSet in your application to determine whether this feature is available. Example #define MY_CAN_ID CAN_ID_1 if (CAN_CONFIGURATION_MODE != PLIB_CAN_OperationModeGet(MY_CAN_ID)) { PLIB_CAN_SyncJumpWidthSet(MY_CAN_ID, CAN_TIME_SEGMENT_LEN_8TQ); } 5.6.4.5.4 Channel Configuration 5.6.4.5.4.1 PLIB_CAN_ChannelForReceiveSet Function C void PLIB_CAN_ChannelForReceiveSet( CAN_MODULE_ID index, CAN_CHANNEL channel, uint32_t channelSize, CAN_RX_DATA_MODE dataOnly ); Description This function configures a CAN channel for receive operation. A receive channel can be either a full CAN message receive channel, which receives an entire CAN message (Arbitration field + Data field) or a data-only message channel, which receives only the data payload section of the message. A receive channel can buffer upto 32 messages. The number of messages to buffer (i.e., the size of the channel) is set by the channelSize parameter. Preconditions The CAN module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1589 Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Receive channel channelSize Specifies the number of received messages that the channel can buffer before it overflows. This should be a value between 1 and 32. 5.6.4.5.4.2 PLIB_CAN_ChannelForTransmitSet Function C void PLIB_CAN_ChannelForTransmitSet( CAN_MODULE_ID index, CAN_CHANNEL channel, uint8_t channelSize, CAN_TX_RTR rtren, CAN_TXCHANNEL_PRIORITY priority ); Description This function configures a CAN Channel for transmission. The size of the channel specifies the number of messages that the channel can buffer. The channel is a First In First Out (FIFO) type of buffer. The remote transmit request feature allows the transmit channel to start transmitting when an associated filter has received a message. The transmit channel priority determines the priority as compared to other transmit channels. If two transmit channels have the same priority, the natural channel priority determines which channel transmits first. Preconditions The CAN Module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel channelSize Size of the channel in messages. This value should be between 1 and 32. 5.6.4.5.4.3 PLIB_CAN_ChannelReset Function C void PLIB_CAN_ChannelReset( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function resets a CAN channel. Resetting a CAN channel causes it to discard any unread received messages or any messages that have not been transmitted yet. The reset operation will wait if a message is being currently transmitted or is being received. The PLIB_CAN_ChannelResetIsComplete function can be used to check if the channel reset is complete. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1590 channel Identifies the CAN channel to be reset Returns None. Remarks Attempting to read from a channel that is reset will return messages that may have already been read or may not have been read at all. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelReset in your application to determine whether this feature is available. Example // Reset channel 4 of CAN_ID_1 module // and wait until the reset is complete PLIB_CAN_ChannelReset(CAN_ID_1,CAN_CHANNEL4); while(PLIB_CAN_ChannelResetIsComplete(CAN_ID_1,CAN_CHANNEL4) != true); 5.6.4.5.4.4 PLIB_CAN_ChannelUpdate Function C void PLIB_CAN_ChannelUpdate( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function updates the CAN Channel internal pointers. This function should be called when a message has been read or processed completely from a CAN receive channel (using the PLIB_CAN_ReceivedMessageGet function). It should be called after a new message has been written to a CAN transmit channel (using the PLIB_CAN_TransmitBufferGet function) and before the PLIB_CAN_TransmitChannelFlush function. Trying to read a CAN receive channel that has not been updated will cause the PLIB_CAN_ReceivedMessageGet function to return the same message. Writing to a CAN transmit channel that has not been updated will cause the last written message to be overwritten. Preconditions This function is effective only when the CAN module is not in Configuration mode or Disable mode. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the CAN channel to be updated Returns None. Remarks The PLIB_CAN_ChannelUpdate function should be called on a CAN receive channel only after the message obtained using the PLIB_CAN_ReceivedMessageGet function has been read or processed completely. The CAN module peripheral library does not provide access to older messages once the PLIB_CAN_ChannelUpdate function has been called. When using the PLIB_CAN_TransmitMessageBuffer function to write to a CAN transmit channel the PLIB_CAN_ChannelUpdate function should be called only when a valid message has been written to the channel. Calling the update function without writing 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1591 to the CAN channel will cause an incorrect message to be output on the CAN channel when the transmit channel is flushed. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelUpdate in your application to determine whether this feature is available. Example // CAN_ID_1 Channel 1 is a Receive channel and Channel 2 is a Transmit // channel. Read and update Channel 1. Write a message to Channel 2 and then // update and flush the channel. CAN_TX_MSG_BUFFER * TransmitMessage; CAN_RX_MSG_BUFFER * rxMessage; rxMessage = PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL1); if(rxMessage != NULL) { // Process the received message. PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL1); } TransmitMessage = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL2); if(TransmitMessage != NULL) { // Write a message to buffer PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL2); PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL2); } 5.6.4.5.4.5 PLIB_CAN_ChannelEventDisable Function C void PLIB_CAN_ChannelEventDisable( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags ); Description This function disables channel level events. Any enabled channel event will cause a CAN module event. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel flags Identifies the CAN channel event(s) to be affected. Several events can be controlled by logically ORed combination of events. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEventEnable in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1592 Example PLIB_CAN_ChannelEventDisable(CAN_ID_1, CAN_CHANNEL1, CAN_TX_CHANNEL_EMPTY); 5.6.4.5.5 Event Management 5.6.4.5.5.1 PLIB_CAN_ModuleEventClear Function C void PLIB_CAN_ModuleEventClear( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ); Description This function clears module level events. If the event condition is persistent, clearing the event will have no effect. The event condition itself should be cleared. The CAN_SYSTEM_ERROR_EVENT can only be cleared by disabling the CAN module using the PLIB_CAN_Enable function. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be cleared by specifying a logically ORed combination of events. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventClear in your application to determine whether this feature is available. Example // Clear CAN_ID_1 Transmit Event and Receive Events. PLIB_CAN_ModuleEventClear(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); 5.6.4.5.5.2 PLIB_CAN_ModuleEventDisable Function C void PLIB_CAN_ModuleEventDisable( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ); Description This function disables module level events. Any enabled module event will cause the CAN module to generate a CPU interrupt. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1593 Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be controlled by logically ORed combination of events. Returns None. Remarks An event can be active regardless of it being enabled or disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventEnable in your application to determine whether this feature is available. Example // Enable CAN_ID_1 Transmit Event and Receive Events. // Disable Receive Overflow event and operation // mode change event. PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); PLIB_CAN_ModuleEventDisable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | CAN_RX_OVERFLOW_EVENT)); 5.6.4.5.5.3 PLIB_CAN_ModuleEventEnable Function C void PLIB_CAN_ModuleEventEnable( CAN_MODULE_ID index, CAN_MODULE_EVENT flags ); Description This function enables module level events. Any enabled module event will cause the CAN module to generate a CPU interrupt. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module flags Identifies the CAN module level events to be affected. Several events can be controlled by logically ORed combination of events. Returns None. Remarks An event can be active regardless of it being enabled or disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventEnable in your application to determine whether this feature is available. Example // Enable CAN_ID_1 Transmit Event and Receive Events. // Disable Receive Overflow event and operation 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1594 // mode change event. PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_TX_EVENT | CAN_RX_EVENT)); PLIB_CAN_ModuleEventEnable(CAN_ID_1, (CAN_OPERATION_MODE_CHANGE_EVENT | CAN_RX_OVERFLOW_EVENT)); 5.6.4.5.5.4 PLIB_CAN_ModuleEventGet Function C CAN_MODULE_EVENT PLIB_CAN_ModuleEventGet( CAN_MODULE_ID index ); Description This function returns the status of the CAN module events. The routine returns a status word. This word should be logically ANDed with the desired CAN_MODULE_EVENT event mask. A non-zero result of such an operation would mean that the events specified in the event mask are active. An event mask can contain one event or can be a logical OR combination of multiple events. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns A status word representing the status of the CAN module events. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleEventClear in your application to determine whether this feature is available. Example // Check if the CAN_ID_1 Module Receive event // or if Transmit event is active if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & (CAN_RX_EVENT | CAN_TX_EVENT)) != 0) { // Handle the Receive or Transmit module Event here. } // Check if the CAN_ID_2 System Error Event // is active if((PLIB_CAN_ModuleEventGet(CAN_ID_2) & CAN_SYSTEM_ERROR_EVENT) != 0) { // CAN_ID_2 System error event is active. } 5.6.4.5.5.5 PLIB_CAN_AllChannelEventsGet Function C CAN_CHANNEL_MASK PLIB_CAN_AllChannelEventsGet( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1595 Description This function returns a value representing the event status of all of the CAN channels. The return value can be logically ANDed with a CAN_CHANNEL_MASK type to check whether the channel has any active events. Only an enabled channel event will cause the bit to be updated. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_MASK mask value to check if any event on a channel is active. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsAllChannelEvents in your application to determine whether this feature is available. Example // Check if Channel 2 or 3 of CAN_ID_1 module // have any active events CAN_CHANNEL_MASK channelEvents; channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_1); if((channelEvents & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Channel 2 or 3 has an active event. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } // Check if Channel 31 of CAN_ID_2 module // has an any active events channelEvents = PLIB_CAN_AllChannelEventsGet(CAN_ID_2); if((channelEvents & CAN_CHANNEL31_MASK) != 0) { // Channel 31 of CAN_ID_2 module // has an active event. } 5.6.4.5.5.6 PLIB_CAN_AllChannelOverflowStatusGet Function C CAN_CHANNEL_MASK PLIB_CAN_AllChannelOverflowStatusGet( CAN_MODULE_ID index ); Description This function returns a value representing the Receive overflow event status of all the CAN Channels. The return value can be logically ANDed with a CAN_CHANNEL_MASK type to check whether a channel has any active receive overflow events. The return value will reflect the channel status only if the receive overflow event of the channel is enabled. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1596 Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_MASK mask value to check if a receive channel overflow event is active. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsAllChannelOverflow in your application to determine whether this feature is available. Example // Check if Receive Channel 2 or 3 of CAN_ID_1 module // have overflowed CAN_CHANNEL_MASK channelOverflowEvent; channelOverflowEvent = PLIB_CAN_AllChannelOverflowStatusGet(CAN_ID_1); if((channelOverflowEvent & (CAN_CHANNEL2_MASK | CAN_CHANNEL3_MASK)) != 0) { // Either Receive Channel 2 or 3 has overflowed. // The PLIB_CAN_ChannelEventGet function can be // used to query the channel for more details. } // Check if Receive Channel 31 of CAN_ID_2 module // has overflowed channelOverflowEvent = PLIB_CAN_AllChannelOverflowStatusGet(CAN_ID_2); if((channelOverflowEvent & CAN_CHANNEL31_MASK) != 0) { // Channel 31 of CAN_ID_2 module // has overflowed. } 5.6.4.5.5.7 PLIB_CAN_ChannelEventClear Function C void PLIB_CAN_ChannelEventClear( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT events ); Description This function clears channel events. The events to be cleared are specified as mask. Note that only the receive overflow event is clearable. Attempting to clear other events will have no effect since these events are persistent and clear only when the event condition is cleared. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1597 Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel events Mask specifying the events to be cleared Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEvent in your application to determine whether this feature is available. Example // Clear CAN_ID_2 Receive Channel 3 overflow event PLIB_CAN_ChannelEventClear(CAN_ID_2, CAN_CHANNEL3, CAN_RX_CHANNEL_OVERFLOW); 5.6.4.5.5.8 PLIB_CAN_ChannelEventEnable Function C void PLIB_CAN_ChannelEventEnable( CAN_MODULE_ID index, CAN_CHANNEL channel, CAN_CHANNEL_EVENT flags ); Description This function enables channel level events. Any enabled channel event will cause a CAN module event. An event can be active regardless of it being enabled or disabled. Enabling a transmit type of event for a receive channel will have no any effect. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel flags Identifies the CAN channel event(s) to be affected. Several events can be controlled by logically ORed combination of events. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEventEnable in your application to determine whether this feature is available. Example // CAN_ID_1 Channel 1 and 3 are Transmit channels and Channel 2 and 4 are // Receive channels. Enable Channel 1 empty event and channel not full // event. Disable Channel 2 full and overflow event. // Enable all Transmit events on Channel 2 and disable all Receive events on // on Channel 4. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1598 PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL1, (CAN_TX_CHANNEL_EMPTY | CAN_TX_CHANNEL_NOT_FULL)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL2, (CAN_RX_CHANNEL_FULL | CAN_RX_CHANNEL_OVERFLOW)); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL3, CAN_TX_CHANNEL_ANY_EVENT); PLIB_CAN_ChannelEventEnable(CAN_ID_1, CAN_CHANNEL4, CAN_RX_CHANNEL_ANY_EVENT); 5.6.4.5.5.9 PLIB_CAN_ChannelEventGet Function C CAN_CHANNEL_EVENT PLIB_CAN_ChannelEventGet( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns a value representing the event status of a CAN channel. The return value can be logically ANDed with CAN_CHANNEL_EVENT type to check for a specific event(s). Channels events are affected regardless of whether the event itself is enabled or disabled. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel Returns Returns a value that can be logically ANDed with a CAN_CHANNEL_EVENT type to check if specific CAN channel events are active. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsChannelEvent in your application to determine whether this feature is available. Example // Check if Receive Channel 2 of CAN_ID_1 module // is not empty or if its full. CAN_CHANNEL_EVENT channelEvent; channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_1,CAN_CHANNEL2); if((channelEvent & (CAN_RX_CHANNEL_NOT_EMPTY | CAN_RX_CHANNEL_FULL)) != 0) { // This means that either Receive Channel 2 is not empty // or the Channel is full. } // Check if Transmit Channel 3 of CAN_ID_2 module // has any active events channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_2, CAN_CHANNEL3); if((channelEvent & CAN_TX_CHANNEL_ANY_EVENT) != 0) 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1599 { // This means that some event is active } // Check if Transmit Channel 6 of CAN_ID_2 module is not full channelEvent = PLIB_CAN_ChannelEventGet(CAN_ID_2, CAN_CHANNEL6); if((channelEvent & CAN_TX_CHANNEL_NOT_FULL) != 0) { // This means the Channel is not full. } 5.6.4.5.5.10 PLIB_CAN_PendingEventsGet Function C CAN_EVENT_CODE PLIB_CAN_PendingEventsGet( CAN_MODULE_ID index ); Description This function returns a value representing the highest priority active event in the module. The return value is a CAN_EVENT_CODE type. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns a CAN_EVENT_CODE type representing the highest priority active event in the module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPendingEventsGet in your application to determine whether this feature is available. Example // Implement a switch to check and process // any active CAN module events. CAN_EVENT_CODE eventCode; eventCode = PLIB_CAN_PendingEventsGet(CAN_ID_1); switch(eventCode) { case CAN_NO_EVENT: // Procedure to handle no CAN events break; case CAN_WAKEUP_EVENT: // Procedure to handle device wake-up // on CAN bus activity event break; default: break; 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1600 } 5.6.4.5.6 Message Transmit Functions 5.6.4.5.6.1 PLIB_CAN_PendingTransmissionsAbort Function C void PLIB_CAN_PendingTransmissionsAbort( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function aborts any pending transmit operations. Any messages that are yet to be transmitted will not be transmitted. The messages will still be present in the respective channel. Any message that is in the process of being transmitted will be transmitted completely. Either one channel or all channels can be specified. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel. By specifying CAN_ALL_CHANNELS, transmission on all transmit channels will be aborted. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsPendingTransmissionsAbort in your application to determine whether this feature is available. Example // Abort any pending transmissions on CAN_ID_1 Channel 4 and // Channel 5. PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL4); PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL5); 5.6.4.5.6.2 PLIB_CAN_TransmissionIsAborted Function C bool PLIB_CAN_TransmissionIsAborted( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns 'true' if the transmit abort operation is complete. Either individual channels can be specified or all channels can be specified. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1601 Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel. By specifying CAN_ALL_CHANNELS the status of transmit abort on all transmit channels will be returned. Returns • true = If channel = CAN_ALL_CHANNELS, Transmit Abort is complete = If channel = CAN_CHANNELx, Transmit Abort was successful • false = If channel = CAN_ALL_CHANNELS, Transmit Abort is in progress = If channel = CAN_CHANNELx, Transmit Abort was not successful Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmissionIsAborted in your application to determine whether this feature is available. Example // Abort any pending transmissions on CAN_ID_1 Channel 4 and // check if the current message transmission was aborted. PLIB_CAN_PendingTransmissionsAbort(CAN_ID_1, CAN_CHANNEL4); if(PLIB_CAN_TransmissionIsAborted(CAN_ID_1, CAN_CHANNEL4) == false) { // The message was not aborted. } else { // The message was aborted. } 5.6.4.5.6.3 PLIB_CAN_TransmitBufferGet Function C CAN_TX_MSG_BUFFER * PLIB_CAN_TransmitBufferGet( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns a pointer to an empty transmit buffer. The routine will return a NULL pointer if there aren't any empty transmit buffers. In such a case, the application should flush the channel and wait until the transmit channel has at least one empty buffer. In order to function correctly, it is essential that the PLIB_CAN_ChannelUpdate function is called in the proper sequence for the PLIB_CAN_TransmitBufferGet function to return a pointer to an empty buffer. Preconditions PLIB_CAN_MemoryBufferAssign must be called if the 'transmit buffer' should be in the device RAM. It is not required if the 'transmit buffer' is in SFR space. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN Channel 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1602 Returns Returns a CAN_TX_MSG_BUFFER type pointer to an empty message buffer in the Transmit channel. Returns NULL if the channel is full and there aren't any empty message buffers. Remarks Calling the PLIB_CAN_TransmitBufferGet function on a channel that has not been updated after a message was written to the channel, will cause the function to return a pointer to the written message in case of transmit buffer FIFO. Therefore, a non-transmitted message could get overwritten. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitBufferGet in your application to determine whether this feature is available. Example // Transmit a message through CAN_ID_1 Channel 4 CAN_TX_MSG_BUFFER * msgBuffer; msgBuffer = PLIB_CAN_TransmitBufferGet(CAN_ID_1, CAN_CHANNEL4); if(msgBuffer != NULL) { // Load the message here } else { // No space in the channel // wait until a message // buffer is free. while((PLIB_CAN_ChannelEventGet(CAN_ID_1, CAN_CHANNEL4) & CAN_TX_CHANNEL_NOT_FULL) == 0); } 5.6.4.5.6.4 PLIB_CAN_TransmitChannelFlush Function C void PLIB_CAN_TransmitChannelFlush( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function causes all messages in the specified transmit channel to be transmitted. All messages in the channel at the time of the flush operation will be transmitted. The transmit channel flush operation should preferably be called immediately after the PLIB_CAN_ChannelUpdate function. This will ensure that messages are transmitted promptly. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1603 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitChannelFlush in your application to determine whether this feature is available. Example // Flush CAN_ID_1 Transmit Channel 4. PLIB_CAN_TransmitChannelFlush(CAN_ID_1, CAN_CHANNEL4); 5.6.4.5.6.5 PLIB_CAN_TransmitChannelStatusGet Function C CAN_TX_CHANNEL_STATUS PLIB_CAN_TransmitChannelStatusGet( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns the condition of the transmit channel. The return value can be logically ANDed with CAN_TX_CHANNEL_STATUS type values. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module channel Identifies the desired CAN channel Returns Returns a status word that can be logically ANDed with the CAN_TX_CHANNEL_STATUS type to check whether a condition exists. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitChannelStatus in your application to determine whether this feature is available. Example // Check if CAN_ID_1 Transmit Channel 4 // is still transmitting CAN_TX_CHANNEL_STATUS status; status = PLIB_CAN_TransmitChannelStatusGet(CAN_ID_1, CAN_CHANNEL4); if((status & CAN_TX_CHANNEL_TRANSMITTING) != 0) { // This means that channel is still // transmitting. } // Check if CAN_ID_2 Transmit Channel 5 has lost arbitration // or other Transmit errors. status = PLIB_CAN_TransmitChannelStatusGet(CAN_ID_2, CAN_CHANNEL5); if((status & (CAN_TX_CHANNEL_ARBITRATION_LOST | CAN_TX_CHANNEL_ERROR)) != 0) 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1604 { // This means that the Transmit channel has either // lost arbitration or a Transmit error has occurred. } 5.6.4.5.6.6 PLIB_CAN_TransmitErrorCountGet Function C int PLIB_CAN_TransmitErrorCountGet( CAN_MODULE_ID index ); Description This function returns the CAN transmit error count. Refer to CAN 2.0B specification for more details on the CAN transmit error count and its significance. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns the CAN transmit error count. Remarks There are multiple bus conditions, which could cause the transmit error count to increase. Please refer to the CAN 2.0B specification for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsTransmitErrorCountGet in your application to determine whether this feature is available. Example // Check if the CAN_ID_1 Transmit error count is more than 200 int errorCount; errorCount = PLIB_CAN_TransmitErrorCountGet(CAN_ID_1); if(errorCount > 200) { // This error count is high. // Do some diagnostics. } 5.6.4.5.7 Message Receive Functions 5.6.4.5.7.1 PLIB_CAN_ReceivedMessageGet Function C CAN_RX_MSG_BUFFER * PLIB_CAN_ReceivedMessageGet( CAN_MODULE_ID index, CAN_CHANNEL channel ); Description This function returns a CAN_RX_MSG_BUFFER pointer to a message to be read from the CAN channel. The routine will return 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1605 NULL if there are no new messages to be read. The PLIB_CAN_ChannelUpdate routine should be called after the received message has been processed. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module. channel Identifies the desired CAN Receive channel. Returns Returns NULL if there are no messages in the channel; otherwise returns a CAN_RX_MSG_BUFFER type pointer to a received CAN message. If the receive channel is a full CAN message receive channel, the caller should use the msgSID, msgEID and data members of the CAN_RX_MSG_BUFFER data structure to access the received CAN message. If the receive channel is a data-only channel, the message will only contain 8 payload data bytes (even if the message was placed on the bus with less than 8 bytes). The caller in this case should use the dataOnlyMsgData member of the CAN_RX_MSG_BUFFER data structure to read the data contained in the received CAN message. Remarks The CAN receive channel is configured as a full CAN message receive channel or a data-Only channel while configuring the channel using the PLIB_CAN_ChannelForReceiveSet function. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceivedMessageGet in your application to determine whether this feature is available. Example // Read a message from the CAN_ID_1 Channel 8 // which is configured as full CAN message // receive channel. CAN_RX_MSG_BUFFER * receivedMsg; receivedMsg = (CAN_RX_MSG_BUFFER *)PLIB_CAN_ReceivedMessageGet(CAN_ID_1, CAN_CHANNEL8); if(receivedMsg != NULL) { // rxMsg is pointing to // a CAN message. Process // the message and then update // the CAN channel. PLIB_CAN_ChannelUpdate(CAN_ID_1, CAN_CHANNEL8); } // Read a message from the CAN_ID_2 Channel 9 // which is configured as data only message // receive channel. Access the message // as bytes; CAN_RX_MSG_BUFFER * rxMsg; rxMsg = PLIB_CAN_ReceivedMessageGet(CAN_ID_2, CAN_CHANNEL9); if(rxMsg != NULL) { // rxMsg is pointing to // a CAN message. Process 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1606 // the message and then update // the CAN channel. // rxMsg->dataOnlyMsgData[0] is the first byte of message // data payload. rxMsg->dataOnlyMsgData[0] is the second // byte of message data payload and so on. PLIB_CAN_ChannelUpdate(CAN_ID_2, CAN_CHANNEL9); } 5.6.4.5.7.2 PLIB_CAN_RxFIFOFourLeftNotify Function C void PLIB_CAN_RxFIFOFourLeftNotify( CAN_MODULE_ID index ); Description This function configures the module to generate an interrupt when the FIFO has four receive buffers left. If this API is not called, the module will interrupt if four receive buffers are empty. Preconditions The functional mode of the module should be configured for "CAN_ENHANCED_FIFO_MODE2" using PLIB_CAN_FunctionalModeSelect function. Parameters Parameters Description index Identifies the desired CAN module Returns The total number of CAN Masks per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsRxFIFOFourLeftNotify in your application to determine whether this feature is available. Example PLIB_CAN_RxFIFOFourLeftNotify(CAN_ID_1); 5.6.4.5.7.3 PLIB_CAN_RxFIFOOneLeftNotify Function C void PLIB_CAN_RxFIFOOneLeftNotify( CAN_MODULE_ID index ); Description This function configures the module to generate an interrupt when the FIFO has only one receive buffer left. If this API is not called, the module will interrupt if four receive buffers are empty. Preconditions The functional mode of the module should be configured for "CAN_ENHANCED_FIFO_MODE2" using PLIB_CAN_FunctionalModeSelect function. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1607 Parameters Parameters Description index Identifies the desired CAN module Returns The total number of CAN Masks per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsRxFIFOOneLeftNotify in your application to determine whether this feature is available. Example PLIB_CAN_RxFIFOOneLeftNotify(CAN_ID_1); 5.6.4.5.7.4 PLIB_CAN_ReceiveModeSelect Function C void PLIB_CAN_ReceiveModeSelect( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel, CAN_RECEIVE_MODES recMode ); Description This function selects the receive mode of the CAN module. Preconditions The functional mode should support the 'receive mode' selected. Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL recMode Receive mode, one of the possible values from CAN_RECEIVE_MODES Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveModeSelect in your application to determine whether this feature is available. Example PLIB_CAN_FunctionalModeSelect(CAN_ID_1, CAN_LEGACY_MODE0); PLIB_CAN_ReceiveModeSelect(CAN_ID_1, CAN_RECEIVE_CHANNEL0, CAN_RECEIVE_ALL_MSG_MODE); 5.6.4.5.7.5 PLIB_CAN_ReceiveModeGet Function C CAN_RECEIVE_MODES PLIB_CAN_ReceiveModeGet( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1608 Description This function obtains the receive mode of the CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL Returns Receive mode, one of the possible values from CAN_RECEIVE_MODES. . Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveModeSelect in your application to determine whether this feature is available. Example CAN_RECEIVE_MODES recMode; recMode = PLIB_CAN_ReceiveModeGet(CAN_ID_1, CAN_RECEIVE_CHANNEL0); 5.6.4.5.7.6 PLIB_CAN_MessageIsReceived Function C bool PLIB_CAN_MessageIsReceived( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel ); Description This function returns 'true' if a message was received and the receive buffer is not empty. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL Returns • true = A message was received for the specified channel • false = The receive buffer is not empty for the specified channel Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsMessageIsReceived in your application to determine whether this feature is available. Example if (PLIB_CAN_MessageIsReceived(CAN_ID_1, CAN_RECEIVE_CHANNEL0)) 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1609 { //Read the message //Acknowlege read; otherwise, it will cause the interrupt to //generated again PLIB_CAN_ReceiveBufferClear(CAN_ID_1, CAN_RECEIVE_CHANNEL0); } 5.6.4.5.7.7 PLIB_CAN_ReceiveBufferIsEmpty Function C bool PLIB_CAN_ReceiveBufferIsEmpty( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel ); Description This function returns 'true' if the receive buffer of the specified channel is empty. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL Returns • true = The receive buffer is not empty for the specified channel • false = A message was received for the specified channel Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveBufferIsEmpty in your application to determine whether this feature is available. Example if (PLIB_CAN_ReceiveBufferIsEmpty(CAN_ID_1, CAN_RECEIVE_CHANNEL0)) { //Buffer is empty } 5.6.4.5.7.8 PLIB_CAN_ReceiveBufferClear Function C void PLIB_CAN_ReceiveBufferClear( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel ); Description This function clears the received message flag. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1610 Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveBufferClear in your application to determine whether this feature is available. This API should be called once the receive message buffer is read. This function must be called once the receive message buffer has been read or the interrupt request will still be active and the interrupt may occur again immediately. Example if (PLIB_CAN_MessageIsReceived(CAN_ID_1, CAN_RECEIVE_CHANNEL0)) { //Read the message //Acknowledge read, otherwise it will cause the interrupt to //be generated again PLIB_CAN_ReceiveBufferClear(CAN_ID_1, CAN_RECEIVE_CHANNEL0); } 5.6.4.5.7.9 PLIB_CAN_RemoteTransmitReqIsReceived Function C bool PLIB_CAN_RemoteTransmitReqIsReceived( CAN_MODULE_ID index, CAN_RECEIVE_CHANNEL rcvChannel ); Description This function returns 'true' if the message received is a remote transmit request. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module rcvChannel Receive channel number, one of the possible values from CAN_RECEIVE_CHANNEL Returns • true = Received message is a remote transmission request • false = Received message is not a remote transmission request Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsRemoteTransmitReq in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1611 Example if (PLIB_CAN_RemoteTransmitReqIsReceived(CAN_ID_1, CAN_RECEIVE_CHANNEL0)) { //Request for remote transmit } 5.6.4.5.8 Message Filtering Functions 5.6.4.5.8.1 PLIB_CAN_FilterConfigure Function C void PLIB_CAN_FilterConfigure( CAN_MODULE_ID index, CAN_FILTER filter, uint32_t id, CAN_ID_TYPE filterType ); Description This function configures a CAN message acceptance filter. The ID field of the incoming message must match the filter bits for the CAN module to accept the message. A filter can be a EID type filter, which filters EID messages or a SID filter, which in turn filters SID messages. The filter mask bits (configured using the PLIB_CAN_FilterMaskConfigure function) additionally allow specified message ID bits to be ignored in the filtering process. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN receive filter id A value in the range 0x0 to 0x7FF for SID filter type or 0x0 to 0x1FFFFFFF for EID filter type. 5.6.4.5.8.2 PLIB_CAN_FilterDisable Function C void PLIB_CAN_FilterDisable( CAN_MODULE_ID index, CAN_FILTER filter ); Description This function disables a CAN message acceptance filter. At least one filter must be enabled for the CAN module to receive messages. A receive channel associated with a filter will not receive messages unless the filter is enabled. After a filter is disabled, the PLIB_CAN_FilterIsDisabled function should be called to verify that the filter is disabled. A filter must be disabled before it can be configured. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1612 Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN Message Acceptance Filter Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Example // Enable filter 6 of CAN_ID_2 PLIB_CAN_FilterDisable (CAN_ID_2, CAN_FILTER6); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER4)); 5.6.4.5.8.3 PLIB_CAN_FilterEnable Function C void PLIB_CAN_FilterEnable( CAN_MODULE_ID index, CAN_FILTER filter ); Description This function enables a CAN message acceptance filter. At least one filter must be enabled for the CAN module to receive messages. A receive channel associated with a filter will not receive messages unless the filter is enabled. After a filter is disabled, the PLIB_CAN_FilterIsDisabled function should be called to verify that the filter is disabled. A filter must be disabled before it can be configured. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN message acceptance filter Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Example // Enable filter 6 of CAN_ID_2 PLIB_CAN_FilterEnable (CAN_ID_2, CAN_FILTER6); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1613 while(!PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER4)); 5.6.4.5.8.4 PLIB_CAN_FilterIsDisabled Function C bool PLIB_CAN_FilterIsDisabled( CAN_MODULE_ID index, CAN_FILTER filter ); Description Returns 'true' if the specified filter is disabled. This function should be called to check if the filter is disabled before calling the PLIB_CAN_FilterConfigure function and PLIB_CAN_FilterToChannelLink function. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN filter Returns • true = The filter is disabled • false = The filter is enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterEnable in your application to determine whether this feature is available. Example // Disable CAN_ID_1 filter 3 and wait until the // filter is disabled. PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER3); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER3) == false); 5.6.4.5.8.5 PLIB_CAN_FilterMaskConfigure Function C void PLIB_CAN_FilterMaskConfigure( CAN_MODULE_ID index, CAN_FILTER_MASK mask, uint32_t maskbits, CAN_ID_TYPE idType, CAN_FILTER_MASK_TYPE mide ); Description This function configures a CAN filter mask. The mask bits determine which message ID bits are ignored and compared during the filtering process. Preconditions The CAN module should be in Configuration mode. This is achieved by using the PLIB_CAN_OperationModeSelect function. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1614 Parameters Parameters Description index Identifies the desired CAN module mask Identifies the desired CAN receive filter mask. maskbits A value in the range 0x0 to 0x7FF for SID range or 0x0 to 0x1FFFFFFF for the EID range. Each set bit will mean that the corresponding bit in the filter will be compared to the corresponding bit in the message ID. A clear mask bit means the corresponding bit in the incoming message ID field will be ignored. 5.6.4.5.8.6 PLIB_CAN_FilterToChannelLink Function C void PLIB_CAN_FilterToChannelLink( CAN_MODULE_ID index, CAN_FILTER filter, CAN_FILTER_MASK mask, CAN_CHANNEL channel ); Description This function links a filter to a channel. A filter is typically linked to a receive channel. This allows the channel to receive messages accepted by the filter. A filter can also be linked to a transmit channel if the transmit channel is configured for remote request transmit. In this case, a message accepted by the filter will automatically cause the linked transmit channel to transmit CAN messages that are buffered in the channel. Note that a filter should be enabled using the PLIB_CAN_FilterEnable function after the filter has been linked to the desired channel. Preconditions Filter should have been disabled using the PLIB_CAN_FilterDisable function. Parameters Parameters Description index Identifies the desired CAN module filter Identifies the desired CAN Filter mask Identifies the mask to be used with this filter channel Identifies the channel to be linked to this filter. If a transmit channel is linked, the transmit channel should have it's remote transmit request feature enabled. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsFilterToChannelLink in your application to determine whether this feature is available. Example // Configure CAN_ID_1 filter 3 to accept extended ID messages // with EID 0x1D400 and link the filter to CAN_ID_1 Channel 5. // Note the sequence in which the steps are performed. // Disable the filter and check if its disabled. // Configure the filter. Link it to the Channel and then // enable the filter. PLIB_CAN_FilterDisable(CAN_ID_1, CAN_FILTER3); while(PLIB_CAN_FilterIsDisabled(CAN_ID_1, CAN_FILTER3) == false); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1615 PLIB_CAN_FilterConfigure(CAN_ID_1, CAN_FILTER3, 0x1D400, CAN_EID); PLIB_CAN_FilterToChannelLink(CAN_ID_1, CAN_FILTER3, CAN_FILTER_MASK0, CAN_CHANNEL5); PLIB_CAN_FilterEnable(CAN_ID_1, CAN_FILTER3); 5.6.4.5.8.7 PLIB_CAN_LatestFilterMatchGet Function C CAN_FILTER PLIB_CAN_LatestFilterMatchGet( CAN_MODULE_ID index ); Description This function returns the index of the filter that accepted the latest message. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Index of the filter that accepted the latest message Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsLatestFilterMatchGet in your application to determine whether this feature is available. Example // Check if CAN_ID_2 module Receive Buffer event // is active and if so check which filter // accepted the message. CAN_FILTER filter; if((PLIB_CAN_ModuleEventGet(CAN_ID_1) & CAN_RX_EVENT) != 0) { // Check which filter accepted the message filter = PLIB_CAN_LatestFilterMatchGet(CAN_ID_1); } 5.6.4.5.9 Error State Tracking 5.6.4.5.9.1 PLIB_CAN_ReceiveErrorCountGet Function C int PLIB_CAN_ReceiveErrorCountGet( CAN_MODULE_ID index ); Description This function returns the CAN receive error count. Refer to the CAN 2.0B specification for more details on the CAN receive error 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1616 count and its significance. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns the CAN receive error count. Remarks There are multiple bus conditions, which could cause the receive error count to increase. Please refer to the CAN 2.0b specification for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsReceiveErrorCount in your application to determine whether this feature is available. Example // Check if CAN_ID_1 Receive error count is more than 200. int errCount; errCount = PLIB_CAN_ReceiveErrorCountGet(CAN_ID_1); if(errCount > 200) { // This error count is high. // Do some diagnostics. } 5.6.4.5.9.2 PLIB_CAN_ErrorStateGet Function C CAN_ERROR_STATE PLIB_CAN_ErrorStateGet( CAN_MODULE_ID index ); Description This function returns the CAN error status word. The return word can be logically ANDed with the desired CAN_ERROR_STATE member to check if the CAN module is in a specific error state. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns Returns the CAN_ERROR_STATE word, which can be logically ANDed with the desired CAN_ERROR_STATE member to check whether the CAN module is in a specific error state. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsErrorState in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1617 Example // Check if CAN_ID_1 is in the Transmit or Receive warning state. CAN_ERROR_STATE errorState; errorState = PLIB_CAN_ErrorStateGet(CAN_ID_1); if((errorState & CAN_TX_RX_WARNING_STATE) != 0) { // CAN_ID_1 is in either Transmit or Receive warning state. } // Check if CAN_ID_2 is in the Receive Bus Passive or Transmit Bus passive // state. errorState = PLIB_CAN_ErrorStateGet(CAN_ID_2); if((errorState & (CAN_TX_BUS_PASSIVE_STATE | CAN_RX_BUS_PASSIVE_STATE)) != 0) { // This means that the CAN module is in Transmit Bus Passive // or Receive Bus Passive state. } 5.6.4.5.10 Information Functions 5.6.4.5.10.1 PLIB_CAN_TotalChannelsGet Function C char PLIB_CAN_TotalChannelsGet( CAN_MODULE_ID index ); Description This function returns the total number of CAN channels per CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns The total number of CAN channels per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Example char totalChannels; totalChannels = PLIB_CAN_TotalChannelsGet(CAN_ID_1); 5.6.4.5.10.2 PLIB_CAN_TotalFiltersGet Function C char PLIB_CAN_TotalFiltersGet( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1618 Description This function returns the total number of CAN filters per CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns The total number of CAN Filters per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Example char totalFilters; totalFilters = PLIB_CAN_TotalFiltersGet(CAN_ID_1); 5.6.4.5.10.3 PLIB_CAN_TotalMasksGet Function C char PLIB_CAN_TotalMasksGet( CAN_MODULE_ID index ); Description This function returns the total number of CAN masks per CAN module. Preconditions None. Parameters Parameters Description index Identifies the desired CAN module Returns The total number of CAN Masks per CAN module. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CAN_ExistsModuleInfo in your application to determine whether this feature is available. Example char totalMasks; totalMasks = PLIB_CAN_TotalMasksGet(CAN_ID_1); 5.6.4.5.11 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1619 5.6.4.5.11.1 CAN_CHANNEL Enumeration C typedef enum { CAN_CHANNEL0, CAN_CHANNEL1, CAN_CHANNEL2, CAN_CHANNEL3, CAN_CHANNEL4, CAN_CHANNEL5, CAN_CHANNEL6, CAN_CHANNEL7, CAN_CHANNEL8, CAN_CHANNEL9, CAN_CHANNEL10, CAN_CHANNEL11, CAN_CHANNEL12, CAN_CHANNEL13, CAN_CHANNEL14, CAN_CHANNEL15, CAN_CHANNEL16, CAN_CHANNEL17, CAN_CHANNEL18, CAN_CHANNEL19, CAN_CHANNEL20, CAN_CHANNEL21, CAN_CHANNEL22, CAN_CHANNEL23, CAN_CHANNEL24, CAN_CHANNEL25, CAN_CHANNEL26, CAN_CHANNEL27, CAN_CHANNEL28, CAN_CHANNEL29, CAN_CHANNEL30, CAN_CHANNEL31 } CAN_CHANNEL; Description CAN Channel This enumeration identifies the available CAN channels. Members Members Description CAN_CHANNEL0 Channel 0 ID CAN_CHANNEL1 Channel 1 ID CAN_CHANNEL2 Channel 2 ID CAN_CHANNEL3 Channel 3 ID CAN_CHANNEL4 Channel 4 ID CAN_CHANNEL5 Channel 5 ID CAN_CHANNEL6 Channel 6 ID CAN_CHANNEL7 Channel 7 ID CAN_CHANNEL8 Channel 8 ID CAN_CHANNEL9 Channel 9 ID CAN_CHANNEL10 Channel 10 ID CAN_CHANNEL11 Channel 11 ID 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1620 CAN_CHANNEL12 Channel 12 ID CAN_CHANNEL13 Channel 13 ID CAN_CHANNEL14 Channel 14 ID CAN_CHANNEL15 Channel 15 ID CAN_CHANNEL16 Channel 16 ID CAN_CHANNEL17 Channel 17 ID CAN_CHANNEL18 Channel 18 ID CAN_CHANNEL19 Channel 19 ID CAN_CHANNEL20 Channel 20 ID CAN_CHANNEL21 Channel 21 ID CAN_CHANNEL22 Channel 22 ID CAN_CHANNEL23 Channel 23 ID CAN_CHANNEL24 Channel 24 ID CAN_CHANNEL25 Channel 25 ID CAN_CHANNEL26 Channel 26 ID CAN_CHANNEL27 Channel 27 ID CAN_CHANNEL28 Channel 28 ID CAN_CHANNEL29 Channel 29 ID CAN_CHANNEL30 Channel 30 ID CAN_CHANNEL31 Channel 31 ID 5.6.4.5.11.2 CAN_CHANNEL_EVENT Enumeration C typedef enum { CAN_RX_CHANNEL_NOT_EMPTY, CAN_RX_CHANNEL_HALF_FULL, CAN_RX_CHANNEL_FULL, CAN_RX_CHANNEL_OVERFLOW, CAN_RX_CHANNEL_ANY_EVENT, CAN_TX_CHANNEL_EMPTY, CAN_TX_CHANNEL_HALF_EMPTY, CAN_TX_CHANNEL_NOT_FULL, CAN_TX_CHANNEL_ANY_EVENT } CAN_CHANNEL_EVENT; Description CAN Layer 3 Interrupts This enumerates all the leading interrupts generated due to CAN transmit and receive events. This enumeration can be used to enable or disable channel events and as a mask to check if a channel event is active. A single or a combination of the interrupts can be logically ORed to specify the interrupt(s) to be enabled disabled or events to check. This enumeration is used by PLIB_CAN_ChannelEventEnable, PLIB_CAN_ChannelEventDisable, PLIB_CAN_ChannelEventClear, and PLIB_CAN_ChannelEventGet functions. Members Members Description CAN_RX_CHANNEL_NOT_EMPTY CAN Receive Channel Not Empty Event Mask CAN_RX_CHANNEL_HALF_FULL CAN Receive Channel Half Full Event Mask 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1621 CAN_RX_CHANNEL_FULL CAN Receive Channel Full Event Mask CAN_RX_CHANNEL_OVERFLOW CAN Receive Channel Overflow Event Mask CAN_RX_CHANNEL_ANY_EVENT CAN Receive Channel Any Event Mask CAN_TX_CHANNEL_EMPTY CAN Transmit Channel Empty Event Mask CAN_TX_CHANNEL_HALF_EMPTY CAN Transmit Channel Half Empty Event Mask CAN_TX_CHANNEL_NOT_FULL CAN Transmit Channel Not Full Event Mask CAN_TX_CHANNEL_ANY_EVENT CAN Transmit Channel Any Event Mask 5.6.4.5.11.3 CAN_CHANNEL_MASK Enumeration C typedef enum { CAN_CHANNEL0_MASK, CAN_CHANNEL1_MASK, CAN_CHANNEL2_MASK, CAN_CHANNEL3_MASK, CAN_CHANNEL4_MASK, CAN_CHANNEL5_MASK, CAN_CHANNEL6_MASK, CAN_CHANNEL7_MASK, CAN_CHANNEL8_MASK, CAN_CHANNEL9_MASK, CAN_CHANNEL10_MASK, CAN_CHANNEL11_MASK, CAN_CHANNEL12_MASK, CAN_CHANNEL13_MASK, CAN_CHANNEL14_MASK, CAN_CHANNEL15_MASK, CAN_CHANNEL16_MASK, CAN_CHANNEL17_MASK, CAN_CHANNEL18_MASK, CAN_CHANNEL19_MASK, CAN_CHANNEL20_MASK, CAN_CHANNEL21_MASK, CAN_CHANNEL22_MASK, CAN_CHANNEL23_MASK, CAN_CHANNEL24_MASK, CAN_CHANNEL25_MASK, CAN_CHANNEL26_MASK, CAN_CHANNEL27_MASK, CAN_CHANNEL28_MASK, CAN_CHANNEL29_MASK, CAN_CHANNEL30_MASK, CAN_CHANNEL31_MASK, CAN_ANYCHANNEL_MASK } CAN_CHANNEL_MASK; Description CAN Channel Masks This enumeration identifies a series of useful masks. Each mask represents a CAN channel. These masks are used with the PLIB_CAN_AllChannelEventsGet and PLIB_CAN_AllChannelOverflowStatusGet functions. The value returned by these functions can be logically ANDed with any of these masks to check if an event or overflow event for that channel is active. Members Members Description CAN_CHANNEL0_MASK Channel 0 Mask CAN_CHANNEL1_MASK Channel 1 Mask 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1622 CAN_CHANNEL2_MASK Channel 2 Mask CAN_CHANNEL3_MASK Channel 3 Mask CAN_CHANNEL4_MASK Channel 4 Mask CAN_CHANNEL5_MASK Channel 5 Mask CAN_CHANNEL6_MASK Channel 6 Mask CAN_CHANNEL7_MASK Channel 7 Mask CAN_CHANNEL8_MASK Channel 8 Mask CAN_CHANNEL9_MASK Channel 9 Mask CAN_CHANNEL10_MASK Channel 10 Mask CAN_CHANNEL11_MASK Channel 11 Mask CAN_CHANNEL12_MASK Channel 12 Mask CAN_CHANNEL13_MASK Channel 13 Mask CAN_CHANNEL14_MASK Channel 14 Mask CAN_CHANNEL15_MASK Channel 15 Mask CAN_CHANNEL16_MASK Channel 16 Mask CAN_CHANNEL17_MASK Channel 17 Mask CAN_CHANNEL18_MASK Channel 18 Mask CAN_CHANNEL19_MASK Channel 19 Mask CAN_CHANNEL20_MASK Channel 20 Mask CAN_CHANNEL21_MASK Channel 21 Mask CAN_CHANNEL22_MASK Channel 22 Mask CAN_CHANNEL23_MASK Channel 23 Mask CAN_CHANNEL24_MASK Channel 24 Mask CAN_CHANNEL25_MASK Channel 25 Mask CAN_CHANNEL26_MASK Channel 26 Mask CAN_CHANNEL27_MASK Channel 27 Mask CAN_CHANNEL28_MASK Channel 28 Mask CAN_CHANNEL29_MASK Channel 29 Mask CAN_CHANNEL30_MASK Channel 30 Mask CAN_CHANNEL31_MASK Channel 31 Mask CAN_ANYCHANNEL_MASK Channel any channel Mask 5.6.4.5.11.4 CAN_DNET_FILTER_SIZE Enumeration C typedef enum { CAN_DNET_FILTER_SIZE_18_BIT, CAN_DNET_FILTER_SIZE_17_BIT, CAN_DNET_FILTER_SIZE_16_BIT, CAN_DNET_FILTER_SIZE_15_BIT, CAN_DNET_FILTER_SIZE_14_BIT, CAN_DNET_FILTER_SIZE_13_BIT, CAN_DNET_FILTER_SIZE_12_BIT, CAN_DNET_FILTER_SIZE_11_BIT, CAN_DNET_FILTER_SIZE_10_BIT, CAN_DNET_FILTER_SIZE_9_BIT, CAN_DNET_FILTER_SIZE_8_BIT, CAN_DNET_FILTER_SIZE_7_BIT, CAN_DNET_FILTER_SIZE_6_BIT, CAN_DNET_FILTER_SIZE_5_BIT, CAN_DNET_FILTER_SIZE_4_BIT, 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1623 CAN_DNET_FILTER_SIZE_3_BIT, CAN_DNET_FILTER_SIZE_2_BIT, CAN_DNET_FILTER_SIZE_1_BIT, CAN_DNET_FILTER_DISABLE } CAN_DNET_FILTER_SIZE; Description CAN DeviceNet filter bit numbers. This enumeration identifies the size of the DeviceNet filter in bits. If the size of the DeviceNet filter is "n", the "n" most significant bits of the data payload are compared with the EID field of enabled filters. Members Members Description CAN_DNET_FILTER_SIZE_18_BIT Compare up to data byte 2 bit 6 with filter mask bit 17 CAN_DNET_FILTER_SIZE_17_BIT Compare up to data byte 2 bit 7 with filter mask bit 16 CAN_DNET_FILTER_SIZE_16_BIT Compare up to data byte 1 bit 0 with filter mask bit 15 CAN_DNET_FILTER_SIZE_15_BIT Compare up to data byte 1 bit 1 with filter mask bit 14 CAN_DNET_FILTER_SIZE_14_BIT Compare up to data byte 1 bit 2 with filter mask bit 13 CAN_DNET_FILTER_SIZE_13_BIT Compare up to data byte 1 bit 3 with filter mask bit 12 CAN_DNET_FILTER_SIZE_12_BIT Compare up to data byte 1 bit 4 with filter mask bit 11 CAN_DNET_FILTER_SIZE_11_BIT Compare up to data byte 1 bit 5 with filter mask bit 10 CAN_DNET_FILTER_SIZE_10_BIT Compare up to data byte 1 bit 6 with filter mask bit 9 CAN_DNET_FILTER_SIZE_9_BIT Compare up to data byte 1 bit 7 with filter mask bit 8 CAN_DNET_FILTER_SIZE_8_BIT Compare up to data byte 0 bit 0 with filter mask bit 7 CAN_DNET_FILTER_SIZE_7_BIT Compare up to data byte 0 bit 1 with filter mask bit 6 CAN_DNET_FILTER_SIZE_6_BIT Compare up to data byte 0 bit 2 with filter mask bit 5 CAN_DNET_FILTER_SIZE_5_BIT Compare up to data byte 0 bit 3 with filter mask bit 4 CAN_DNET_FILTER_SIZE_4_BIT Compare up to data byte 0 bit 4 with filter mask bit 3 CAN_DNET_FILTER_SIZE_3_BIT Compare up to data byte 0 bit 5 with filter mask bit 2 CAN_DNET_FILTER_SIZE_2_BIT Compare up to data byte 0 bit 6 with filter mask bit 1 CAN_DNET_FILTER_SIZE_1_BIT Compare up to data byte 0 bit 7 with filter mask bit 0 CAN_DNET_FILTER_DISABLE Do not compare data bytes, Device Net Filtering is disabled 5.6.4.5.11.5 CAN_ERROR_STATE Enumeration C typedef enum { CAN_TX_RX_WARNING_STATE, CAN_RX_WARNING_STATE, CAN_TX_WARNING_STATE, CAN_RX_BUS_PASSIVE_STATE, CAN_TX_BUS_PASSIVE_STATE, CAN_TX_BUS_OFF_STATE } CAN_ERROR_STATE; Description CAN Error States This enumeration identifies all of the CAN module error states events. The CAN module enters or exits an error state as the transmit and receive error counter values change. Refer to the CAN 2.0B specification for more details on the error states. This enumeration is used with the PLIB_CAN_ErrorStateGet function. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1624 Members Members Description CAN_TX_RX_WARNING_STATE CAN Module is in a Transmit or Receive warning state. CAN_RX_WARNING_STATE CAN Module is in a Receive warning state. CAN_TX_WARNING_STATE CAN Module is in a Transmit warning state. CAN_RX_BUS_PASSIVE_STATE CAN Receive is in a Bus Passive state. CAN_TX_BUS_PASSIVE_STATE CAN Transmit is in a Bus Passive state. CAN_TX_BUS_OFF_STATE CAN Transmit is in Bus Off state. 5.6.4.5.11.6 CAN_FILTER Enumeration C typedef enum { CAN_CHANNEL0_EVENT, CAN_CHANNEL1_EVENT, CAN_CHANNEL2_EVENT, CAN_CHANNEL3_EVENT, CAN_CHANNEL4_EVENT, CAN_CHANNEL5_EVENT, CAN_CHANNEL6_EVENT, CAN_CHANNEL7_EVENT, CAN_CHANNEL8_EVENT, CAN_CHANNEL9_EVENT, CAN_CHANNEL10_EVENT, CAN_CHANNEL11_EVENT, CAN_CHANNEL12_EVENT, CAN_CHANNEL13_EVENT, CAN_CHANNEL14_EVENT, CAN_CHANNEL15_EVENT, CAN_CHANNEL16_EVENT, CAN_CHANNEL17_EVENT, CAN_CHANNEL18_EVENT, CAN_CHANNEL19_EVENT, CAN_CHANNEL20_EVENT, CAN_CHANNEL21_EVENT, CAN_CHANNEL22_EVENT, CAN_CHANNEL23_EVENT, CAN_CHANNEL24_EVENT, CAN_CHANNEL25_EVENT, CAN_CHANNEL26_EVENT, CAN_CHANNEL27_EVENT, CAN_CHANNEL28_EVENT, CAN_CHANNEL29_EVENT, CAN_CHANNEL30_EVENT, CAN_CHANNEL31_EVENT, CAN_NO_EVENT, CAN_ERROR_EVENT, CAN_WAKEUP_EVENT, CAN_RX_CHANNEL_OVERFLOW_EVENT, CAN_ADDRESS_ERROR_EVENT, CAN_BUS_BANDWIDTH_ERROR, CAN_TIMESTAMP_TIMER_EVENT, CAN_MODE_CHANGE_EVENT, CAN_FILTER0, CAN_FILTER1, CAN_FILTER2, CAN_FILTER3, CAN_FILTER4, CAN_FILTER5, CAN_FILTER6, CAN_FILTER7, 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1625 CAN_FILTER8, CAN_FILTER9, CAN_FILTER10, CAN_FILTER11, CAN_FILTER12, CAN_FILTER13, CAN_FILTER14, CAN_FILTER15, CAN_FILTER16, CAN_FILTER17, CAN_FILTER18, CAN_FILTER19, CAN_FILTER20, CAN_FILTER21, CAN_FILTER22, CAN_FILTER23, CAN_FILTER24, CAN_FILTER25, CAN_FILTER26, CAN_FILTER27, CAN_FILTER28, CAN_FILTER29, CAN_FILTER30, CAN_FILTER31 } CAN_FILTER; Description CAN Event Code This enumeration identifies all of the event codes returned by the PLIB_CAN_PendingEventsGet function. Members Members Description CAN_CHANNEL0_EVENT An event on Channel 0 is active CAN_CHANNEL1_EVENT An event on Channel 1 is active CAN_CHANNEL2_EVENT An event on Channel 2 is active CAN_CHANNEL3_EVENT An event on Channel 3 is active CAN_CHANNEL4_EVENT An event on Channel 4 is active CAN_CHANNEL5_EVENT An event on Channel 5 is active CAN_CHANNEL6_EVENT An event on Channel 6 is active CAN_CHANNEL7_EVENT An event on Channel 7 is active CAN_CHANNEL8_EVENT An event on Channel 8 is active CAN_CHANNEL9_EVENT An event on Channel 9 is active CAN_CHANNEL10_EVENT An event on Channel 10 is active CAN_CHANNEL11_EVENT An event on Channel 11 is active CAN_CHANNEL12_EVENT An event on Channel 12 is active CAN_CHANNEL13_EVENT An event on Channel 13 is active CAN_CHANNEL14_EVENT An event on Channel 14 is active CAN_CHANNEL15_EVENT An event on Channel 15 is active CAN_CHANNEL16_EVENT An event on Channel 16 is active CAN_CHANNEL17_EVENT An event on Channel 17 is active CAN_CHANNEL18_EVENT An event on Channel 18 is active CAN_CHANNEL19_EVENT An event on Channel 19 is active CAN_CHANNEL20_EVENT An event on Channel 20 is active CAN_CHANNEL21_EVENT An event on Channel 21 is active 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1626 CAN_CHANNEL22_EVENT An event on Channel 22 is active CAN_CHANNEL23_EVENT An event on Channel 23 is active CAN_CHANNEL24_EVENT An event on Channel 24 is active CAN_CHANNEL25_EVENT An event on Channel 25 is active CAN_CHANNEL26_EVENT An event on Channel 26 is active CAN_CHANNEL27_EVENT An event on Channel 27 is active CAN_CHANNEL28_EVENT An event on Channel 28 is active CAN_CHANNEL29_EVENT An event on Channel 29 is active CAN_CHANNEL30_EVENT An event on Channel 30 is active CAN_CHANNEL31_EVENT An event on Channel 31 is active CAN_NO_EVENT No Event is active CAN_ERROR_EVENT CAN Bus Error Event is active CAN_WAKEUP_EVENT CAN Bus Wakeup Event is active CAN_RX_CHANNEL_OVERFLOW_EVENT CAN Receive Channel Overflow Event is active CAN_ADDRESS_ERROR_EVENT CAN Address Error Event is active CAN_BUS_BANDWIDTH_ERROR CAN Bus Bandwidth Error is active CAN_TIMESTAMP_TIMER_EVENT CAN Timestamp Timer Overflow event is active CAN_MODE_CHANGE_EVENT CAN Module Mode Change is active 5.6.4.5.11.7 CAN_FILTER_MASK Enumeration C typedef enum { CAN_FILTER_MASK0, CAN_FILTER_MASK1, CAN_FILTER_MASK2, CAN_FILTER_MASK3, CAN_NUMBER_OF_FILTER_MASKS } CAN_FILTER_MASK; Description CAN Filter Masks This enumeration identifies the available filters masks in each CAN module. Members Members Description CAN_FILTER_MASK0 CAN Filter Mask 0 CAN_FILTER_MASK1 CAN Filter Mask 1 CAN_FILTER_MASK2 CAN Filter Mask 2 CAN_FILTER_MASK3 CAN Filter Mask 3 CAN_NUMBER_OF_FILTER_MASKS Total number of filter masks in the module 5.6.4.5.11.8 CAN_FILTER_MASK_TYPE Enumeration C typedef enum { CAN_FILTER_MASK_IDE_TYPE, CAN_FILTER_MASK_ANY_TYPE } CAN_FILTER_MASK_TYPE; 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1627 Description CAN Filter Mask Type This enumeration specifies the filter mask type. The filter mask can either process messages with any type of ID (extended or standard) or can only process by ID specified in the filter configuration. For example, if the filter associated with the mask only accepts EID type messages and if the mask is configured to process by ID type, then SID messages will not be accepted. If the mask is configured to process any type of message, both SID and EID messages will be accepted on a filter match. Members Members Description CAN_FILTER_MASK_IDE_TYPE Mask processes only Filter type of message CAN_FILTER_MASK_ANY_TYPE Mask processes any type (SID or EID) of message 5.6.4.5.11.9 CAN_FUNCTONAL_MODES Enumeration C typedef enum { CAN_LEGACY_MODE0, CAN_ENHANCED_LEGACY_MODE1, CAN_ENHANCED_FIFO_MODE2 } CAN_FUNCTONAL_MODES; Description CAN Functional Modes This enumerates all operating modes of the CAN module. The application should set the desired mode using the PLIB_CAN_FunctionalModeSelect function, and should then use the PLIB_CAN_FunctionalModeGet function to check if the CAN module has entered the requested mode. Members Members Description CAN_LEGACY_MODE0 CAN Mode 0, Legacy Mode. This mode enabled minimum features. Hides features of Enhanced CAN. This is the default mode of operation on all Reset conditions CAN_ENHANCED_LEGACY_MODE1 CAN Mode 1, Enhanced Legacy Mode. Enables ECAN features. Enables DeviceNet filtering. CAN_ENHANCED_FIFO_MODE2 CAN Mode 2, Enhanced FIFO Mode. In this mode, two or more receive buffers are used to form the receive FIFO buffer. 5.6.4.5.11.10 CAN_ID_TYPE Enumeration C typedef enum { CAN_EID, CAN_SID } CAN_ID_TYPE; Description CAN ID Type This enumeration specifies the two CAN ID types: Standard and Extended. The Standard Type ID is 11 bits long and the Extended ID is 29 bits long. This enumeration then specifies the type of the ID specified while configuring filters and filter masks. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1628 Members Members Description CAN_EID CAN Extended ID CAN_SID CAN Standard ID 5.6.4.5.11.11 CAN_MODULE_EVENT Enumeration C typedef enum { CAN_TX_EVENT, CAN_RX_EVENT, CAN_TIMESTAMP_TIMER_OVERFLOW_EVENT, CAN_OPERATION_MODE_CHANGE_EVENT, CAN_RX_OVERFLOW_EVENT, CAN_SYSTEM_ERROR_EVENT, CAN_BUS_ERROR_EVENT, CAN_BUS_ACTIVITY_WAKEUP_EVENT, CAN_INVALID_RX_MESSAGE_EVENT } CAN_MODULE_EVENT; Description CAN Module Events This enumeration identifies all of the CAN module events. A combination of listed events can be logically ORed to enable or disable module level events. Similarly, a combination of events can be checked if active. This enumeration is used with the PLIB_CAN_ModuleEventEnable function and PLIB_CAN_ModuleEventGet function. Members Members Description CAN_TX_EVENT Transmit channel event. This event will occur if any of the Transmit Channel events are active. CAN_RX_EVENT Receive channel event. This event will occur if any of the Receive Channel events are active. CAN_TIMESTAMP_TIMER_OVERFLOW_EVENT CAN Timer Stamp Timer Overflow event occurs. This event occurs when the Timestamp Timer has overflowed. CAN_OPERATION_MODE_CHANGE_EVENT CAN Operation Mode Change Event. This event occurs when the CAN module has changed it's operating mode successfully. CAN_RX_OVERFLOW_EVENT CAN Receive Channel Overflow Event. This event occurs when any of the Receive Channel has overflowed. CAN_SYSTEM_ERROR_EVENT CAN System Error Event. This event occurs when CAN module tries to access an invalid Device RAM location. CAN_BUS_ERROR_EVENT CAN Bus Error Event. This event occurs when the CAN module cannot access the system bus. CAN_BUS_ACTIVITY_WAKEUP_EVENT CAN Bus Activity Wakeup. This event occurs when the device is in Sleep mode and bus activity is detected on the CAN bus. CAN_INVALID_RX_MESSAGE_EVENT CAN Bus Invalid Receive Message Event. This event occurs when the CAN module receives an Invalid message. 5.6.4.5.11.12 CAN_MODULE_ID Enumeration C typedef enum { CAN_ID_1, CAN_ID_2, 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1629 CAN_ID_3, CAN_NUMBER_OF_MODULES } CAN_MODULE_ID; Description Enumeration: CAN_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. Members Members Description CAN_NUMBER_OF_MODULES The total number of modules available. 5.6.4.5.11.13 CAN_MSG_EID Structure C typedef struct { unsigned data_length_code : 4; unsigned reserved0 : 1; unsigned unimplemented1 : 3; unsigned reserved1 : 1; unsigned remote_request : 1; unsigned eid : 18; unsigned ide : 1; unsigned sub_remote_req : 1; unsigned unimplemented2 : 2; } CAN_MSG_EID; Description CAN Message EID Word This data structure represents the EID section of the CAN transmit and receive message. The data structure is an element of the CAN_TX_MSG_BUFFER and CAN_RX_MSG_BUFFER data structure. Members Members Description unsigned data_length_code : 4; Data Length Control. Specifies the size of the data payload section of the CAN packet. Valid values are 0x0 - 0x8 unsigned reserved0 : 1; Reserved bit. Should be always 0. unsigned unimplemented1 : 3; Unimplemented bit. Should be always 0. unsigned reserved1 : 1; Reserved bit. Should be always 0. unsigned remote_request : 1; Remote Transmit Request bit. Should be set for RTR messages, clear otherwise. unsigned eid : 18; CAN Transmit and Receive Extended ID field. Valid values are in range 0x0 - 0x3FFFF unsigned ide : 1; Identifier bit. If 0 means that message is SID. If 1 means that message is EID type. unsigned sub_remote_req : 1; Substitute Remote request bit. This bit should always be clear for an EID message. It is ignored for an SID message. unsigned unimplemented2 : 2; Unimplemented bit. Should be always 0. 5.6.4.5.11.14 CAN_OPERATION_MODES Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1630 CAN_LISTEN_ALL_MESSAGES_MODE, CAN_CONFIGURATION_MODE, CAN_LISTEN_ONLY_MODE, CAN_LOOPBACK_MODE, CAN_DISABLE_MODE, CAN_NORMAL_MODE } CAN_OPERATION_MODES; Description CAN Operation Modes This enumerates all operating modes of the CAN module. The application should set the desired mode using the PLIB_CAN_OperationModeSelect function, and should then use the PLIB_CAN_OperationModeGet function to check if the CAN module has entered the requested mode. Members Members Description CAN_LISTEN_ALL_MESSAGES_MODE CAN Listen All Message Mode. The CAN module listens to all messages, regardless of errors CAN_CONFIGURATION_MODE CAN Configuration Mode. Various CAN module settings can be configured in this mode CAN_LISTEN_ONLY_MODE CAN Listen Only Mode. In this mode, the CAN module will not acknowledge signal and will not participate in error signaling. All messages are captured CAN_LOOPBACK_MODE CAN Loopback Mode. In this mode, the CAN module Transmit is internally connected to the Receive line. This mode is useful for debugging operation CAN_DISABLE_MODE CAN Disable Mode. The CAN module does not transmit or receive messages in this mode CAN_NORMAL_MODE CAN Normal Operation Mode. The CAN module transmits and receives messages in this mode 5.6.4.5.11.15 CAN_RECEIVE_CHANNEL Enumeration C typedef enum { CAN_RECEIVE_CHANNEL0, CAN_RECEIVE_CHANNEL1 } CAN_RECEIVE_CHANNEL; Description CAN Receive Channels This enumerates all CAN module receive channels(channels that are not allowed to be configured for transmit). Members Members Description CAN_RECEIVE_CHANNEL0 CAN receive channel 0 CAN_RECEIVE_CHANNEL1 CAN receive channel 1 5.6.4.5.11.16 CAN_RECEIVE_MODES Enumeration C typedef enum { CAN_RECEIVE_ALL_MSG_MODE, CAN_RECEIVE_VALID_EID_MODE, CAN_RECEIVE_VALID_STD_MODE, CAN_RECEIVE_VALID_MODE 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1631 } CAN_RECEIVE_MODES; Description CAN Receive Modes This enumerates all operating modes of the CAN module. The application should set the desired mode using the PLIB_CAN_ReceiveModeSelect function, and should then use the PLIB_CAN_ReceiveModeGet function to check if the CAN module has entered the requested mode. Members Members Description CAN_RECEIVE_ALL_MSG_MODE Receive all messages(Including with errors). The message filters will not be considered CAN_RECEIVE_VALID_EID_MODE Receive only valid messages(with error will be discarded, filter will be considered) with extended identifier. This is applicable only for functional mode 0 CAN_RECEIVE_VALID_STD_MODE Receive only valid messages(with error will be discarded, filter will be considered) with standard identifier. This is applicable only for functional mode 0 CAN_RECEIVE_VALID_MODE Receive only valid messages(with error will be discarded, filter will be considered) with extended identifier/standard identifier Based on the configuration 5.6.4.5.11.17 CAN_RX_DATA_MODE Enumeration C typedef enum { CAN_RX_DATA_ONLY, CAN_RX_FULL_RECEIVE } CAN_RX_DATA_MODE; Description CAN Receive Channel Data Only Mode This enumeration specifies the status of the CAN receive channel data-only feature. If the feature is enabled, the CAN module will store only the data payload portion of the received CAN message. If the Full Receive mode is specified, the CAN module stores the entire CAN message (ID field plus data payload). The receive channel can be either in Data-Only mode or Full Receive mode. Members Members Description CAN_RX_DATA_ONLY CAN Receive Channel Data Only Mode is enabled CAN_RX_FULL_RECEIVE CAN Receive Channel Full Receive Mode is enabled 5.6.4.5.11.18 CAN_RX_MSG_BUFFER Union C typedef union { struct { CAN_RX_MSG_SID msgSID; CAN_MSG_EID msgEID; uint8_t data[8]; } uint8_t dataOnlyMsgData[8]; uint32_t messageWord[4]; } CAN_RX_MSG_BUFFER; Description CAN Receive Message Buffer 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1632 This data structure represents the CAN receive message buffer. Received messages could be either full-receive messages or data-only messages. A full-receive message contains the message header and data payload section. For a full-receive CAN receive channel, the caller should use the msgSID, msgEID and data members. A data-only message contains only an 8-byte data payload. While using this data structure with a data-only type of CAN receive channel, the caller should use the dataOnlyMsgData member of the structure and should read only 8 bytes of data. Members Members Description CAN_RX_MSG_SID msgSID; This is SID portion of the CAN Receive message CAN_MSG_EID msgEID; This is EID portion of the CAN Receive message uint8_t data[8]; This is the data payload section of the received message uint8_t dataOnlyMsgData[8]; This can be used if the message buffer is to be read from a Data-Only type of CAN Receive Channel uint32_t messageWord[4]; This is CAN Receive message organized as a set of 32 bit words 5.6.4.5.11.19 CAN_RX_MSG_SID Structure C typedef struct { unsigned sid : 11; unsigned filter_hit : 5; unsigned msg_timestamp : 16; } CAN_RX_MSG_SID; Description CAN Receive Message SID Word This data structure represents the SID section of the CAN receive message. The data structure is an element of the CAN_RX_MSG_BUFFER data structure. Members Members Description unsigned sid : 11; SID of the Received CAN Message unsigned filter_hit : 5; Filter which accepted this message unsigned msg_timestamp : 16; Time stamp of the received message. This is valid only if the Timestamping is enabled 5.6.4.5.11.20 CAN_TIME_SEGMENT_LENGTH Enumeration C typedef enum { CAN_TIME_SEGMENT_LEN_8TQ, CAN_TIME_SEGMENT_LEN_7TQ, CAN_TIME_SEGMENT_LEN_6TQ, CAN_TIME_SEGMENT_LEN_5TQ, CAN_TIME_SEGMENT_LEN_4TQ, CAN_TIME_SEGMENT_LEN_3TQ, CAN_TIME_SEGMENT_LEN_2TQ, CAN_TIME_SEGMENT_LEN_1TQ } CAN_TIME_SEGMENT_LENGTH; Description CAN Segment length This enumeration defines values that can be assigned while defining the number of Time Quanta in a bit. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1633 Members Members Description CAN_TIME_SEGMENT_LEN_8TQ Segment length is 8 x TQ CAN_TIME_SEGMENT_LEN_7TQ Segment length is 7 x TQ CAN_TIME_SEGMENT_LEN_6TQ Segment length is 6 x TQ CAN_TIME_SEGMENT_LEN_5TQ Segment length is 5 x TQ CAN_TIME_SEGMENT_LEN_4TQ Segment length is 4 x TQ CAN_TIME_SEGMENT_LEN_3TQ Segment length is 3 x TQ CAN_TIME_SEGMENT_LEN_2TQ Segment length is 2 x TQ CAN_TIME_SEGMENT_LEN_1TQ Segment length is 1 x TQ 5.6.4.5.11.21 CAN_TX_CHANNEL_STATUS Enumeration C typedef enum { CAN_TX_CHANNEL_TRANSMITTING, CAN_TX_CHANNEL_ERROR, CAN_TX_CHANNEL_ARBITRATION_LOST } CAN_TX_CHANNEL_STATUS; Description CAN Transmit Channel Condition This enumeration identifies the possible transmit channel condition. These masks can be logically ANDed with values returned by the PLIB_CAN_TransmitChannelStatusGet function to check if a condition is active. Members Members Description CAN_TX_CHANNEL_TRANSMITTING CAN Transmit Channel is currently Transmitting. CAN_TX_CHANNEL_ERROR CAN Transmit Channel Error has occurred. CAN_TX_CHANNEL_ARBITRATION_LOST CAN Transmit Channel lost arbitration. 5.6.4.5.11.22 CAN_TX_MSG_BUFFER Union C typedef union { struct { CAN_TX_MSG_SID msgSID; CAN_MSG_EID msgEID; unsigned char data[8]; } uint32_t messageWord[4]; } CAN_TX_MSG_BUFFER; Description CAN Transmit Message Buffer This data structure represents the CAN transmit message buffer. This should be used for writing data to a CAN transmit channel and transmitting data. A pointer to this type of data structure is returned by the PLIB_CAN_TransmitBufferGet function. The data structure allows the transmit message buffer to be accessed as fields of a CAN transmit message and also as an array of four 32-bit words. The latter allows for quick initialization of the message buffer. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1634 Members Members Description CAN_TX_MSG_SID msgSID; This is SID portion of the CAN Transmit message CAN_MSG_EID msgEID; This is EID portion of the CAN Transmit message unsigned char data[8]; This is the data portion of the CAN Transmit message uint32_t messageWord[4]; This is CAN Transmit message organized as a set of 32 bit words 5.6.4.5.11.23 CAN_TX_MSG_SID Structure C typedef struct { unsigned sid : 11; } CAN_TX_MSG_SID; Description CAN Transmit Message SID Word This data structure represents the SID section of the CAN transmit message. The data structure is an element of the CAN_TX_MSG_BUFFER data structure. Members Members Description unsigned sid : 11; CAN Transmit Message Standard ID. This value should be between 0x0 - 0x7FF 5.6.4.5.11.24 CAN_TX_RTR Enumeration C typedef enum { CAN_TX_RTR_ENABLED, CAN_TX_RTR_DISABLED } CAN_TX_RTR; Description CAN Transmit Channel Remote Transmit Request (RTR) This enumeration specifies the status of the CAN RTR feature for a CAN transmit channel. The RTR feature allows a node on the CAN Bus to request a transmission from another node on the bus. The responding node in this case should have a RTR enabled Transmit Channel in order to be able to respond to this request. Members Members Description CAN_TX_RTR_ENABLED CAN Transmit Channel RTR Feature is enabled CAN_TX_RTR_DISABLED CAN Transmit Channel RTR Feature is disabled 5.6.4.5.11.25 CAN_TXCHANNEL_PRIORITY Enumeration C typedef enum { CAN_LOWEST_PRIORITY, CAN_LOW_MEDIUM_PRIORITY, CAN_HIGH_MEDIUM_PRIORITY, CAN_HIGHEST_PRIORITY } CAN_TXCHANNEL_PRIORITY; 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1635 Description CAN Transmit Channel Priority This enumeration identifies the available transmit channel priorities. A transmit channel has its own natural priority order, which determines priority when two or more transmit channels are assigned the same priority level. Channel 1 has higher natural priority than channel 0 and channel 2 has a natural priority than channel 1, and so on. Members Members Description CAN_LOWEST_PRIORITY CAN lowest priority CAN_LOW_MEDIUM_PRIORITY CAN low medium priority CAN_HIGH_MEDIUM_PRIORITY CAN high medium priority CAN_HIGHEST_PRIORITY CAN highest priority 5.6.4.5.11.26 CAN_RX_DATA_ONLY_SIZE_BYTES Macro C #define CAN_RX_DATA_ONLY_SIZE_BYTES 8 Description CAN Data-Only Receive Message Buffer This contant is used as the size of the CAN data-only receive message buffer in bytes. 5.6.4.5.11.27 CAN_TX_RX_MESSAGE_SIZE_BYTES Macro C #define CAN_TX_RX_MESSAGE_SIZE_BYTES 16 Description CAN Transmit and Receive Message Buffer size This contant is used as the array size of the CAN transmit and full receive message buffer. 5.6.4.5.12 Feature Existance Routines 5.6.4.5.12.1 PLIB_CAN_ExistsActiveStatus Function C bool PLIB_CAN_ExistsActiveStatus( CAN_MODULE_ID index ); Description This function identifies whether the ActiveStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_IsActive Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1636 Parameters Parameters Description index Identifier for the device instance Returns • true = The ActiveStatus feature is supported on the device • false = The ActiveStatus feature is not supported on the device Remarks None. 5.6.4.5.12.2 PLIB_CAN_ExistsAllChannelEvents Function C bool PLIB_CAN_ExistsAllChannelEvents( CAN_MODULE_ID index ); Description This function identifies whether the AllChannelEvents feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_AllChannelEventsGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The AllChannelEvents feature is supported on the device • false = The AllChannelEvents feature is not supported on the device Remarks None. 5.6.4.5.12.3 PLIB_CAN_ExistsAllChannelOverflow Function C bool PLIB_CAN_ExistsAllChannelOverflow( CAN_MODULE_ID index ); Description This function identifies whether the AllChannelOverflow feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_AllChannelOverflowStatusGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1637 Parameters Parameters Description index Identifier for the device instance Returns • true = The AllChannelOverflow feature is supported on the device • false = The AllChannelOverflow feature is not supported on the device Remarks None. 5.6.4.5.12.4 PLIB_CAN_ExistsBusActivityWakeup Function C bool PLIB_CAN_ExistsBusActivityWakeup( CAN_MODULE_ID index ); Description This function identifies whether the BusActivityWakeup feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_BusActivityWakeupEnable • PLIB_CAN_BusActivityWakeupDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The BusActivityWakeup feature is supported on the device • false = The BusActivityWakeup feature is not supported on the device Remarks None. 5.6.4.5.12.5 PLIB_CAN_ExistsBusLine3TimesSampling Function C bool PLIB_CAN_ExistsBusLine3TimesSampling( CAN_MODULE_ID index ); Description This function identifies whether the BusLine3TimesSampling feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_BusLine3TimesSamplingEnable • PLIB_CAN_BusLine3TimesSamplingDisable 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1638 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The BusLine3TimesSampling feature is supported on the device • false = The BusLine3TimesSampling feature is not supported on the device Remarks None. 5.6.4.5.12.6 PLIB_CAN_ExistsChannelEvent Function C bool PLIB_CAN_ExistsChannelEvent( CAN_MODULE_ID index ); Description This function identifies whether the ChannelEventGet feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ChannelEventGet • PLIB_CAN_ChannelEventClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelEventGet feature is supported on the device • false = The ChannelEventGet feature is not supported on the device Remarks None. 5.6.4.5.12.7 PLIB_CAN_ExistsChannelEventEnable Function C bool PLIB_CAN_ExistsChannelEventEnable( CAN_MODULE_ID index ); Description This function identifies whether the ChannelEventEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1639 • PLIB_CAN_ChannelEventEnable • PLIB_CAN_ChannelEventDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelEventEnable feature is supported on the device • false = The ChannelEventEnable feature is not supported on the device Remarks None. 5.6.4.5.12.8 PLIB_CAN_ExistsChannelForReceiveSet Function C bool PLIB_CAN_ExistsChannelForReceiveSet( CAN_MODULE_ID index ); Description This function identifies whether the ChannelForReceiveSet feature is available on the CAN module. When this function returns true, this function is are supported on the device: • PLIB_CAN_ChannelForReceiveSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelForReceiveSet feature is supported on the device • false = The ChannelForReceiveSet feature is not supported on the device Remarks None. 5.6.4.5.12.9 PLIB_CAN_ExistsChannelForTransmitSet Function C bool PLIB_CAN_ExistsChannelForTransmitSet( CAN_MODULE_ID index ); Description This function identifies whether the ChannelForTransmitSet feature is available on the CAN module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1640 • PLIB_CAN_ChannelForTransmitSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelForTransmitSet feature is supported on the device • false = The ChannelForTransmitSet feature is not supported on the device Remarks None. 5.6.4.5.12.10 PLIB_CAN_ExistsChannelReset Function C bool PLIB_CAN_ExistsChannelReset( CAN_MODULE_ID index ); Description This function identifies whether the ChannelReset feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ChannelReset • PLIB_CAN_ChannelResetIsComplete Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelReset feature is supported on the device • false = The ChannelReset feature is not supported on the device Remarks None. 5.6.4.5.12.11 PLIB_CAN_ExistsChannelUpdate Function C bool PLIB_CAN_ExistsChannelUpdate( CAN_MODULE_ID index ); Description This function identifies whether the ChannelUpdate feature is available on the CAN module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1641 • PLIB_CAN_ChannelUpdate Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ChannelUpdate feature is supported on the device • false = The ChannelUpdate feature is not supported on the device Remarks None. 5.6.4.5.12.12 PLIB_CAN_ExistsDeviceNet Function C bool PLIB_CAN_ExistsDeviceNet( CAN_MODULE_ID index ); Description This function identifies whether the DeviceNet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_DeviceNetConfigure Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The DeviceNet feature is supported on the device • false = The DeviceNet feature is not supported on the device Remarks None. 5.6.4.5.12.13 PLIB_CAN_ExistsEnableControl Function C bool PLIB_CAN_ExistsEnableControl( CAN_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_Enable 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1642 • PLIB_CAN_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The EnableControl feature is supported on the device • false = The EnableControl feature is not supported on the device Remarks None. 5.6.4.5.12.14 PLIB_CAN_ExistsErrorState Function C bool PLIB_CAN_ExistsErrorState( CAN_MODULE_ID index ); Description This function identifies whether the ErrorStateGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ErrorStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ErrorStateGet feature is supported on the device • false = The ErrorStateGet feature is not supported on the device Remarks None. 5.6.4.5.12.15 PLIB_CAN_ExistsFilterConfigure Function C bool PLIB_CAN_ExistsFilterConfigure( CAN_MODULE_ID index ); Description This function identifies whether the FilterConfigure feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_FilterConfigure 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1643 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The FilterConfigure feature is supported on the device • false = the FilterConfigure feature is not supported on the device Remarks None. 5.6.4.5.12.16 PLIB_CAN_ExistsFilterEnable Function C bool PLIB_CAN_ExistsFilterEnable( CAN_MODULE_ID index ); Description This function identifies whether the FilterEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_FilterEnable • PLIB_CAN_FilterDisable • PLIB_CAN_FilterIsDisabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The FilterEnable feature is supported on the device • false = The FilterEnable feature is not supported on the device Remarks None. 5.6.4.5.12.17 PLIB_CAN_ExistsFilterMaskConfigure Function C bool PLIB_CAN_ExistsFilterMaskConfigure( CAN_MODULE_ID index ); Description This function identifies whether the FilterMaskConfigure feature is available on the CAN module. When this function returns true, 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1644 this function is supported on the device: • PLIB_CAN_FilterMaskConfigure Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The FilterMaskConfigure feature is supported on the device • false = The FilterMaskConfigure feature is not supported on the device Remarks None. 5.6.4.5.12.18 PLIB_CAN_ExistsFilterToChannelLink Function C bool PLIB_CAN_ExistsFilterToChannelLink( CAN_MODULE_ID index ); Description This function identifies whether the FilterToChannelLink feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_FilterToChannelLink Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The FilterToChannelLink feature is supported on the device • false = The FilterToChannelLink feature is not supported on the device Remarks None. 5.6.4.5.12.19 PLIB_CAN_ExistsFunctionalMode Function C bool PLIB_CAN_ExistsFunctionalMode( CAN_MODULE_ID index ); Description This function identifies whether the FunctionalModeSelect feature is available on the CAN module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1645 • PLIB_CAN_FunctionalModeSelect • PLIB_CAN_FunctionalModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The FunctionalModeSelect feature is supported on the device • false = The FunctionalModeSelect feature is not supported on the device Remarks None. 5.6.4.5.12.20 PLIB_CAN_ExistsLatestFilterMatchGet Function C bool PLIB_CAN_ExistsLatestFilterMatchGet( CAN_MODULE_ID index ); Description This function identifies whether the LatestFilterMatchGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_LatestFilterMatchGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The LatestFilterMatchGet feature is supported on the device • false = The LatestFilterMatchGet feature is not supported on the device Remarks None. 5.6.4.5.12.21 PLIB_CAN_ExistsMemoryBufferAssign Function C bool PLIB_CAN_ExistsMemoryBufferAssign( CAN_MODULE_ID index ); Description This function identifies whether the MemoryBufferAssign feature is available on the CAN module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1646 • PLIB_CAN_MemoryBufferAssign Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MemoryBufferAssign feature is supported on the device • false = The MemoryBufferAssign feature is not supported on the device Remarks None. 5.6.4.5.12.22 PLIB_CAN_ExistsMessageIsReceived Function C bool PLIB_CAN_ExistsMessageIsReceived( CAN_MODULE_ID index ); Description This function identifies whether the MessageIsReceived feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_MessageIsReceived Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The MessageIsReceived feature is supported on the device • false = The MessageIsReceived feature is not supported on the device Remarks None. 5.6.4.5.12.23 PLIB_CAN_ExistsModuleEventClear Function C bool PLIB_CAN_ExistsModuleEventClear( CAN_MODULE_ID index ); Description This function identifies whether the ModuleEvents feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ModuleEventClear 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1647 • PLIB_CAN_ModuleEventGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ModuleEvents feature is supported on the device • false = The ModuleEvents feature is not supported on the device Remarks None. 5.6.4.5.12.24 PLIB_CAN_ExistsModuleEventEnable Function C bool PLIB_CAN_ExistsModuleEventEnable( CAN_MODULE_ID index ); Description This function identifies whether the ModuleEventEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ModuleEventEnable • PLIB_CAN_ModuleEventDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ModuleEventEnable feature is supported on the device • false = The ModuleEventEnable feature is not supported on the device Remarks None. 5.6.4.5.12.25 PLIB_CAN_ExistsModuleInfo Function C bool PLIB_CAN_ExistsModuleInfo( CAN_MODULE_ID index ); Description This function identifies whether the ModuleInformation feature is available on the CAN module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1648 • PLIB_CAN_TotalChannelsGet • PLIB_CAN_TotalFiltersGet • PLIB_CAN_TotalMasksGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ModuleInformation feature is supported on the device • false = The ModuleInformation feature is not supported on the device Remarks None. 5.6.4.5.12.26 PLIB_CAN_ExistsOperationModeRead Function C bool PLIB_CAN_ExistsOperationModeRead( CAN_MODULE_ID index ); Description This function identifies whether the OperationModeRead feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_OperationModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The OperationModeRead feature is supported on the device • false = The OperationModeRead feature is not supported on the device Remarks None. 5.6.4.5.12.27 PLIB_CAN_ExistsOperationModeWrite Function C bool PLIB_CAN_ExistsOperationModeWrite( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1649 Description This function identifies whether the OperationModeSet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_OperationModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The OperationModeSet feature is supported on the device • false = The OperationModeSet feature is not supported on the device Remarks None. 5.6.4.5.12.28 PLIB_CAN_ExistsPendingEventsGet Function C bool PLIB_CAN_ExistsPendingEventsGet( CAN_MODULE_ID index ); Description This function identifies whether the PendingEventsGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PendingEventsGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PendingEventsGet feature is supported on the device • false = The PendingEventsGet feature is not supported on the device Remarks None. 5.6.4.5.12.29 PLIB_CAN_ExistsPendingTransmissionsAbort Function C bool PLIB_CAN_ExistsPendingTransmissionsAbort( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1650 Description This function identifies whether the PendingTransmissionsAbort feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PendingTransmissionsAbort Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PendingTransmissionsAbort feature is supported on the device • false = The PendingTransmissionsAbort feature is not supported on the device Remarks None. 5.6.4.5.12.30 PLIB_CAN_ExistsPhaseSegment1Length Function C bool PLIB_CAN_ExistsPhaseSegment1Length( CAN_MODULE_ID index ); Description This function identifies whether the PhaseSegment1Length feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PhaseSegment1LengthSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PhaseSegment1Length feature is supported on the device • false = The PhaseSegment1Length feature is not supported on the device Remarks None. 5.6.4.5.12.31 PLIB_CAN_ExistsPhaseSegment2Length Function C bool PLIB_CAN_ExistsPhaseSegment2Length( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1651 Description This function identifies whether the PhaseSegment2Length feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PhaseSegment2LengthSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PhaseSegment2Length feature is supported on the device • false = The PhaseSegment2Length feature is not supported on the device Remarks None. 5.6.4.5.12.32 PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable Function C bool PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable( CAN_MODULE_ID index ); Description This function identifies whether the PhaseSegment2LengthFreelyProgrammable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable • PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PhaseSegment2LengthFreelyProgrammable feature is supported on the device • false = The PhaseSegment2LengthFreelyProgrammable feature is not supported on the device Remarks None. 5.6.4.5.12.33 PLIB_CAN_ExistsPropagationTimeSegment Function C bool PLIB_CAN_ExistsPropagationTimeSegment( CAN_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1652 ); Description This function identifies whether the PropagationTimeSegment feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_PropagationTimeSegmentSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The PropagationTimeSegment feature is supported on the device • false = The PropagationTimeSegment feature is not supported on the device Remarks None. 5.6.4.5.12.34 PLIB_CAN_ExistsReceiveBufferClear Function C bool PLIB_CAN_ExistsReceiveBufferClear( CAN_MODULE_ID index ); Description This function identifies whether the ReceiveBufferClear feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceiveBufferClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ReceiveBufferClear feature is supported on the device • false = The ReceiveBufferClear feature is not supported on the device Remarks None. 5.6.4.5.12.35 PLIB_CAN_ExistsReceiveBufferIsEmpty Function C bool PLIB_CAN_ExistsReceiveBufferIsEmpty( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1653 Description This function identifies whether the ReceiveBufferIsEmpty feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceiveBufferIsEmpty Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ReceiveBufferIsEmpty feature is supported on the device • false = The ReceiveBufferIsEmpty feature is not supported on the device Remarks None. 5.6.4.5.12.36 PLIB_CAN_ExistsReceivedMessageGet Function C bool PLIB_CAN_ExistsReceivedMessageGet( CAN_MODULE_ID index ); Description This function identifies whether the ReceivedMessageGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceivedMessageGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ReceivedMessageGet feature is supported on the device • false = The ReceivedMessageGet feature is not supported on the device Remarks None. 5.6.4.5.12.37 PLIB_CAN_ExistsReceiveErrorCount Function C bool PLIB_CAN_ExistsReceiveErrorCount( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1654 Description This function identifies whether the ReceiveErrorCount feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_ReceiveErrorCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ReceiveErrorCount feature is supported on the device • false = The ReceiveErrorCount feature is not supported on the device Remarks None. 5.6.4.5.12.38 PLIB_CAN_ExistsReceiveModeSelect Function C bool PLIB_CAN_ExistsReceiveModeSelect( CAN_MODULE_ID index ); Description This function identifies whether the ReceiveModeSelect feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_ReceiveModeSelect • PLIB_CAN_ReceiveModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ReceiveModeSelect feature is supported on the device • false = The ReceiveModeSelect feature is not supported on the device Remarks None. 5.6.4.5.12.39 PLIB_CAN_ExistsRemoteTransmitReq Function C bool PLIB_CAN_ExistsRemoteTransmitReq( CAN_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1655 ); Description This function identifies whether the RemoteTransmitReq feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_RemoteTransmitReqIsReceived Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The RemoteTransmitReq feature is supported on the device • false = The RemoteTransmitReq feature is not supported on the device Remarks None. 5.6.4.5.12.40 PLIB_CAN_ExistsRxFIFOFourLeftNotify Function C bool PLIB_CAN_ExistsRxFIFOFourLeftNotify( CAN_MODULE_ID index ); Description This function identifies whether the RxFIFOFourLeftNotify feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_RxFIFOFourLeftNotify Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The RxFIFOFourLeftNotify feature is supported on the device • false = The RxFIFOFourLeftNotify feature is not supported on the device Remarks None. 5.6.4.5.12.41 PLIB_CAN_ExistsRxFIFOOneLeftNotify Function C bool PLIB_CAN_ExistsRxFIFOOneLeftNotify( CAN_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1656 Description This function identifies whether the RxFIFOOneLeftNotify feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_RxFIFOOneLeftNotify Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The RxFIFOOneLeftNotify feature is supported on the device • false = The RxFIFOOneLeftNotify feature is not supported on the device Remarks None. 5.6.4.5.12.42 PLIB_CAN_ExistsStopInIdle Function C bool PLIB_CAN_ExistsStopInIdle( CAN_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_StopInIdleEnable • PLIB_CAN_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The StopInIdle feature is supported on the device • false = The StopInIdle feature is not supported on the device Remarks None. 5.6.4.5.12.43 PLIB_CAN_ExistsSyncJumpWidthSet Function C bool PLIB_CAN_ExistsSyncJumpWidthSet( CAN_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1657 ); Description This function identifies whether the SyncJumpWidth feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_SyncJumpWidthSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The SyncJumpWidth feature is supported on the device • false = The SyncJumpWidth feature is not supported on the device Remarks None. 5.6.4.5.12.44 PLIB_CAN_ExistsTimeStampEnable Function C bool PLIB_CAN_ExistsTimeStampEnable( CAN_MODULE_ID index ); Description This function identifies whether the TimeStampEnable feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_TimeStampEnable • PLIB_CAN_TimeStampDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TimeStampEnable feature is supported on the device • false = The TimeStampEnable feature is not supported on the device Remarks None. 5.6.4.5.12.45 PLIB_CAN_ExistsTimeStampPrescalar Function C bool PLIB_CAN_ExistsTimeStampPrescalar( 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1658 CAN_MODULE_ID index ); Description This function identifies whether the TimeStampPrescalar feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TimeStampPrescalarSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TimeStampPrescalar feature is supported on the device • false = The TimeStampPrescalar feature is not supported on the device Remarks None. 5.6.4.5.12.46 PLIB_CAN_ExistsTimeStampValue Function C bool PLIB_CAN_ExistsTimeStampValue( CAN_MODULE_ID index ); Description This function identifies whether the TimeStampValue feature is available on the CAN module. When this function returns true, these functions are supported on the device: • PLIB_CAN_TimeStampValueSet • PLIB_CAN_TimeStampValueGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TimeStampValue feature is supported on the device • false = The TimeStampValue feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1659 5.6.4.5.12.47 PLIB_CAN_ExistsTransmissionIsAborted Function C bool PLIB_CAN_ExistsTransmissionIsAborted( CAN_MODULE_ID index ); Description This function identifies whether the TransmissionAbortStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmissionIsAborted Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TransmissionAbortStatus feature is supported on the device • false = The TransmissionAbortStatus feature is not supported on the device Remarks None. 5.6.4.5.12.48 PLIB_CAN_ExistsTransmitBufferGet Function C bool PLIB_CAN_ExistsTransmitBufferGet( CAN_MODULE_ID index ); Description This function identifies whether the TransmitBufferGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitBufferGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TransmitBufferGet feature is supported on the device • false = The TransmitBufferGet feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1660 5.6.4.5.12.49 PLIB_CAN_ExistsTransmitChannelFlush Function C bool PLIB_CAN_ExistsTransmitChannelFlush( CAN_MODULE_ID index ); Description This function identifies whether the TransmitChannelFlush feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitChannelFlush Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TransmitChannelFlush feature is supported on the device • false = The TransmitChannelFlush feature is not supported on the device Remarks None. 5.6.4.5.12.50 PLIB_CAN_ExistsTransmitChannelStatus Function C bool PLIB_CAN_ExistsTransmitChannelStatus( CAN_MODULE_ID index ); Description This function identifies whether the TransmitChannelStatus feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitChannelStatusGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TransmitChannelStatus feature is supported on the device • false = The TransmitChannelStatus feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1661 5.6.4.5.12.51 PLIB_CAN_ExistsTransmitErrorCountGet Function C bool PLIB_CAN_ExistsTransmitErrorCountGet( CAN_MODULE_ID index ); Description This function identifies whether the TransmitErrorCountGet feature is available on the CAN module. When this function returns true, this function is supported on the device: • PLIB_CAN_TransmitErrorCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The TransmitErrorCountGet feature is supported on the device • false = The TransmitErrorCountGet feature is not supported on the device Remarks None. 5.6.4.6 Files Files Name Description plib_can.h This file contains the interface definition for the CAN Peripheral Library. Description 5.6.4.6.1 plib_can.h CAN Peripheral Library Interface Header This library provides a low-level abstraction of the Controller Area Network (CAN) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. Functions Name Description PLIB_CAN_AllChannelEventsGet Returns a value representing the event status of all CAN channels. PLIB_CAN_AllChannelOverflowStatusGet Returns a value representing the receive overflow event status of all CAN channels. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1662 PLIB_CAN_BusActivityWakeupDisable Disables the wake-up on bus activity receive line filter. PLIB_CAN_BusActivityWakeupEnable Enables the wake-up on bus activity receive line filter. PLIB_CAN_BusLine3TimesSamplingDisable Disables the bus line three times sampling. PLIB_CAN_BusLine3TimesSamplingEnable Enables the bus line three times sampling. PLIB_CAN_ChannelEventClear Clears CAN channel events. PLIB_CAN_ChannelEventDisable Enables channel level events. PLIB_CAN_ChannelEventEnable Enables channel level events. PLIB_CAN_ChannelEventGet Returns a value representing the event status of a CAN channel. PLIB_CAN_ChannelForReceiveSet Configures a CAN channel for receive operation. PLIB_CAN_ChannelForTransmitSet Configures a CAN channel for transmission. PLIB_CAN_ChannelReset Resets a CAN channel. PLIB_CAN_ChannelResetIsComplete Returns 'true' if the specified channel reset is complete. PLIB_CAN_ChannelUpdate Updates the CAN Channel internal pointers. PLIB_CAN_DeviceNetConfigure Configures the CAN module DeviceNet(TM) filter feature. PLIB_CAN_Disable Disables the specified CAN module. PLIB_CAN_Enable Enables the specified CAN module. PLIB_CAN_ErrorStateGet Returns the CAN error status word. PLIB_CAN_ExistsActiveStatus Identifies whether the ActiveStatus feature exists on the CAN module. PLIB_CAN_ExistsAllChannelEvents Identifies whether the AllChannelEvents feature exists on the CAN module. PLIB_CAN_ExistsAllChannelOverflow Identifies whether the AllChannelOverflow feature exists on the CAN module. PLIB_CAN_ExistsBusActivityWakeup Identifies whether the BusActivityWakeup feature exists on the CAN module. PLIB_CAN_ExistsBusLine3TimesSampling Identifies whether the BusLine3TimesSampling feature exists on the CAN module. PLIB_CAN_ExistsChannelEvent Identifies whether the ChannelEventGet feature exists on the CAN module. PLIB_CAN_ExistsChannelEventEnable Identifies whether the ChannelEventEnable feature exists on the CAN module. PLIB_CAN_ExistsChannelForReceiveSet Identifies whether the ChannelForReceiveSet feature exists on the CAN module. PLIB_CAN_ExistsChannelForTransmitSet Identifies whether the ChannelForTransmitSet feature exists on the CAN module. PLIB_CAN_ExistsChannelReset Identifies whether the ChannelReset feature exists on the CAN module. PLIB_CAN_ExistsChannelUpdate Identifies whether the ChannelUpdate feature exists on the CAN module. PLIB_CAN_ExistsDeviceNet Identifies whether the DeviceNet feature exists on the CAN module. PLIB_CAN_ExistsEnableControl Identifies whether the EnableControl feature exists on the CAN module. PLIB_CAN_ExistsErrorState Identifies whether the ErrorStateGet feature exists on the CAN module. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1663 PLIB_CAN_ExistsFilterConfigure Identifies whether the FilterConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterEnable Identifies whether the FilterEnable feature exists on the CAN module. PLIB_CAN_ExistsFilterMaskConfigure Identifies whether the FilterMaskConfigure feature exists on the CAN module. PLIB_CAN_ExistsFilterToChannelLink Identifies whether the FilterToChannelLink feature exists on the CAN module. PLIB_CAN_ExistsFunctionalMode Identifies whether the FunctionalModeSelect feature exists on the CAN module. PLIB_CAN_ExistsLatestFilterMatchGet Identifies whether the LatestFilterMatchGet feature exists on the CAN module. PLIB_CAN_ExistsMemoryBufferAssign Identifies whether the MemoryBufferAssign feature exists on the CAN module. PLIB_CAN_ExistsMessageIsReceived Identifies whether the MessageIsReceived feature exists on the CAN module. PLIB_CAN_ExistsModuleEventClear Identifies whether the ModuleEvents feature exists on the CAN module. PLIB_CAN_ExistsModuleEventEnable Identifies whether the ModuleEventEnable feature exists on the CAN module. PLIB_CAN_ExistsModuleInfo Identifies whether the ModuleInformation feature exists on the CAN module. PLIB_CAN_ExistsOperationModeRead Identifies whether the OperationModeRead feature exists on the CAN module. PLIB_CAN_ExistsOperationModeWrite Identifies whether the OperationModeSet feature exists on the CAN module. PLIB_CAN_ExistsPendingEventsGet Identifies whether the PendingEventsGet feature exists on the CAN module. PLIB_CAN_ExistsPendingTransmissionsAbort Identifies whether the PendingTransmissionsAbort feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment1Length Identifies whether the PhaseSegment1Length feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment2Length Identifies whether the PhaseSegment2Length feature exists on the CAN module. PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable Identifies whether the PhaseSegment2LengthFreelyProgrammable feature exists on the CAN module. PLIB_CAN_ExistsPropagationTimeSegment Identifies whether the PropagationTimeSegment feature exists on the CAN module. PLIB_CAN_ExistsReceiveBufferClear Identifies whether the ReceiveBufferClear feature exists on the CAN module. PLIB_CAN_ExistsReceiveBufferIsEmpty Identifies whether the ReceiveBufferIsEmpty feature exists on the CAN module. PLIB_CAN_ExistsReceivedMessageGet Identifies whether the ReceivedMessageGet feature exists on the CAN module. PLIB_CAN_ExistsReceiveErrorCount Identifies whether the ReceiveErrorCount feature exists on the CAN module. PLIB_CAN_ExistsReceiveModeSelect Identifies whether the ReceiveModeSelect feature exists on the CAN module. PLIB_CAN_ExistsRemoteTransmitReq Identifies whether the RemoteTransmitReq feature exists on the CAN module. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1664 PLIB_CAN_ExistsRxFIFOFourLeftNotify Identifies whether the RxFIFOFourLeftNotify feature exists on the CAN module. PLIB_CAN_ExistsRxFIFOOneLeftNotify Identifies whether the RxFIFOOneLeftNotify feature exists on the CAN module. PLIB_CAN_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the CAN module. PLIB_CAN_ExistsSyncJumpWidthSet Identifies whether the SyncJumpWidth feature exists on the CAN module. PLIB_CAN_ExistsTimeStampEnable Identifies whether the TimeStampEnable feature exists on the CAN module PLIB_CAN_ExistsTimeStampPrescalar Identifies whether the TimeStampPrescalar feature exists on the CAN module. PLIB_CAN_ExistsTimeStampValue Identifies whether the TimeStampValue feature exists on the CAN module. PLIB_CAN_ExistsTransmissionIsAborted Identifies whether the TransmissionAbortStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitBufferGet Identifies whether the TransmitBufferGet feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelFlush Identifies whether the TransmitChannelFlush feature exists on the CAN module. PLIB_CAN_ExistsTransmitChannelStatus Identifies whether the TransmitChannelStatus feature exists on the CAN module. PLIB_CAN_ExistsTransmitErrorCountGet Identifies whether the TransmitErrorCountGet feature exists on the CAN module. PLIB_CAN_FilterConfigure Configures a CAN message acceptance filter. PLIB_CAN_FilterDisable Disables a CAN message acceptance filter. PLIB_CAN_FilterEnable Enables a CAN message acceptance filter. PLIB_CAN_FilterIsDisabled Returns 'true' if the specified filter is disabled. PLIB_CAN_FilterMaskConfigure Configures a CAN filter mask. PLIB_CAN_FilterToChannelLink Links a filter to a channel. PLIB_CAN_FunctionalModeGet Obtains the functional mode of the CAN module. PLIB_CAN_FunctionalModeSelect Selects the functional mode of the CAN module. PLIB_CAN_IsActive Returns 'true' if the CAN module is active. PLIB_CAN_LatestFilterMatchGet Returns the index of the filter that accepted the latest message. PLIB_CAN_MemoryBufferAssign Assigns buffer memory to the CAN module. PLIB_CAN_MessageIsReceived Returns whether a message was received and the receive buffer is not empty. PLIB_CAN_ModuleEventClear Clears the CAN module level events. PLIB_CAN_ModuleEventDisable Disables the module level events. PLIB_CAN_ModuleEventEnable Enables the module level events. PLIB_CAN_ModuleEventGet Returns the status of the CAN module events. PLIB_CAN_OperationModeGet Obtains the current CAN operating mode. PLIB_CAN_OperationModeSelect Sets the CAN operating mode. PLIB_CAN_PendingEventsGet Returns a value representing the highest priority active event in the module. PLIB_CAN_PendingTransmissionsAbort Aborts any pending transmit operations. PLIB_CAN_PhaseSegment1LengthSet Selects the CAN phase buffer segment1 length. 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1665 PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable Disables the CAN phase buffer segment2 length freely programmable mode. PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable Makes the CAN phase buffer segment2 length freely programmable. PLIB_CAN_PhaseSegment2LengthSet Selects the CAN phase buffer segment2 length. PLIB_CAN_PropagationTimeSegmentSet Selects the propagation time segment. PLIB_CAN_ReceiveBufferClear Clears the received message flag. PLIB_CAN_ReceiveBufferIsEmpty Returns whether the receive buffer of the specified channel is empty. PLIB_CAN_ReceivedMessageGet Returns a pointer to a message to be read from the CAN channel. PLIB_CAN_ReceiveErrorCountGet Returns the CAN receive error count. PLIB_CAN_ReceiveModeGet Obtains the receive mode of the CAN module. PLIB_CAN_ReceiveModeSelect Selects the receive mode of the CAN module. PLIB_CAN_RemoteTransmitReqIsReceived Returns whether the message received is a remote transmit request. PLIB_CAN_RxFIFOFourLeftNotify Configures the module to generate an interrupt when the FIFO has four receive buffers left. PLIB_CAN_RxFIFOOneLeftNotify Configures the module to generate an interrupt when the FIFO has only one receive buffer left. PLIB_CAN_StopInIdleDisable Disables the Stop in Idle feature. PLIB_CAN_StopInIdleEnable Enables the CAN module to stop when the processor enters Idle mode. PLIB_CAN_SyncJumpWidthSet Selects the synchronization jump width. PLIB_CAN_TimeStampDisable Disables the time stamp feature for the CAN module. PLIB_CAN_TimeStampEnable Enables the time stamp feature for the CAN module. PLIB_CAN_TimeStampPrescalarSet Sets the CAN receive message time stamp timer prescalar. PLIB_CAN_TimeStampValueGet Returns the current value of the CAN receive message time stamp timer value. PLIB_CAN_TimeStampValueSet Sets the CAN receive message time stamp timer value. PLIB_CAN_TotalChannelsGet Returns the total number of CAN channels per CAN module. PLIB_CAN_TotalFiltersGet Returns the total number of CAN Filters per CAN module. PLIB_CAN_TotalMasksGet Returns the total number of CAN masks per CAN module. PLIB_CAN_TransmissionIsAborted Returns 'true' if the transmit abort operation is complete. PLIB_CAN_TransmitBufferGet Returns a pointer to an empty transmit buffer. PLIB_CAN_TransmitChannelFlush Causes all messages in the specified transmit channel to be transmitted. PLIB_CAN_TransmitChannelStatusGet Returns the condition of the transmit channel. PLIB_CAN_TransmitErrorCountGet Returns the CAN transmit error count 5.6 Peripheral Library Help MPLAB Harmony Help CAN Peripheral Library 5-1666 Macros Name Description CAN_RX_DATA_ONLY_SIZE_BYTES Used as the size of the CAN data-only receive message buffer in bytes. CAN_TX_RX_MESSAGE_SIZE_BYTES Used as the array size of the CAN transmit and full receive message buffer. Structures Name Description CAN_MSG_EID Defines the structure of the EID word section of the transmit and receive message. CAN_RX_MSG_SID Defines the structure of the SID word section of the receive message. CAN_TX_MSG_SID Defines the structure of the SID word section of the transmit message. Unions Name Description CAN_RX_MSG_BUFFER Defines the structure of the CAN receive message buffer CAN_TX_MSG_BUFFER Defines the structure of the CAN transmit message buffer. File Name plib_can.h Company Microchip Technology Inc. 5.6.5 Comparator Peripheral Library 5.6.5.1 Introduction Comparator Peripheral Library for Microchip Microcontrollers The Comparator module is comprised of several identical analog comparator blocks, each complete with its own supporting input selectors and output logic. Each Comparator can be configured in a variety of ways, independent of the other comparators. The input voltage to the module can be either fed externally or it can be configured to use the internal voltage. Description This library provides a low-level abstraction of the Comparator module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby abstracting hardware differences from one microcontroller variant to another facilitating future migration. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1667 5.6.5.2 Release Notes MPLAB Harmony Version: v0.70b Comparator Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.5.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1668 . 5.6.5.4 Using the Library This topic describes the basic architecture of the Comparator Peripheral Library and provides information and examples on how to use it. Description Using the Libary Interface Header File: plib_cmp.h The interface to the Comparator Peripheral Library is defined in the "plib_cmp.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Comparator Peripheral Library must include "peripheral.h". Library File: The Comparator Peripheral Library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using the Microchip compilers. Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. The first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). For the Comparator Peripheral Library, the module instance IDs are defined by the Comparator module enumeration. 5.6.5.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Comparator (CMP) module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Diagram 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1669 Hardware Abstraction Model Description The Comparator Peripheral Library provides interface routines to interact with the blocks shown in the diagram above. The Comparator VIN+ and VIN- block selects the Comparator non-inverting and inverting inputs, which can be either external or internal inputs. The Comparator module block compares the voltage level on the inputs and produce an output. If the input VIN+ > VIN-, the output will be high. The output will be low when VIN+ < VIN-. The Comparator Output Polarity block selects the Comparator output polarity. The Comparator Output Control block enables/disables the Comparator output pin. The Comparator Interrupt Logic Control block decide the comparator interrupt generation.The interrupt can happen at Low-to-high, High-to-Low, and for both transitions of the Comparator output. 5.6.5.4.2 Library Usage Model The set of interface routines for the CMP Peripheral Library are: Library Interface Section Description 5.6.5.4.3 How the Library Works The following processes are involved while using a Comparator module: • Initialization • Configuring the Comparator interrupt (optional) • Power-saving modes • Turning on the Comparator module Name Description Initialization Initialize the comparator module. Configuring the Comparator Interrupts Enable the Comparator interrupt (optional) Power-Saving Modes Enable the Comparator power-saving modes (optional) 5.6.5.4.3.1 Initialization This section describes Comparator module initialization. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1670 Description The following steps are involved while using a Comparator module. # Description Function Associated 1 Select the Comparator inverting input. PLIB_CMP_InvertingInputChannelSelect 2 Select the Comparator non-inverting input. PLIB_CMP_NonInvertingInputChannelSelect 3 Select the Comparator output polarity. PLIB_CMP_InvertedOutputSelect PLIB_CMP_NonInvertedOutputSelect 4 Select the Comparator output pin. PLIB_CMP_OutputEnable PLIB_CMP_OutputDisable 5 Turn on the Comparator module. PLIB_CMP_Enable Example #define MY_CMP_ID CMP_ID_1 //Select the comparator inverting input PLIB_CMP_InvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_INVERTING_INPUT_CHANNEL_B); //Select the comparator non-inverting input PLIB_CMP_NonInvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_NON_INVERTING_INPUT_A); //Select the comparator output polarity PLIB_CMP_NonInvertedOutputSelect(MY_CMP_INSTANCE); //Enable the comparator output pin PLIB_CMP_OutputEnable(MY_CMP_INSTANCE); //Turn on the comparator module PLIB_CMP_Enable(MY_CMP_INSTANCE); 5.6.5.4.3.2 Configuring the Comparator Interrupts This section describes the configuration of Comparator module interrupts. Description The following steps are involved while configuring a Comparator interrupt. The comparator interrupt can happen for three events. The user must configure the event-detection logic to report changes to the output state of the Comparator, which can in turn be used for event or interrupt generation. The options include event generation on rising state changes (low-to-high), falling state changes (high-to-low), and all state changes. When a configured event occurs, it is flagged by the event detection flag.The user must clear this flag for the next interrupt generation. # Description Function Associated 1 Comparator event select. PLIB_CMP_InterruptEventSelect 2 Comparator event flag read/clear PLIB_CMP_EventHasOccurred PLIB_CMP_EventStatusClear Example #define MY_CMP_ID CMP_ID_1 //This code expects the comparator interrupt //enabled in the interrupt module //Select the comparator interrupt event 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1671 PLIB_CMP_InterruptEventSelect(MY_CMP_INSTANCE, CMP_LOW_TO_HIGH); //This part of the code should be in ISR if(PLIB_CMP_EventHasOccurred(CMP_ID_1)) { //Do some operations \ //Clear the event flag PLIB_CMP_EventStatusClear(CMP_ID_1); } //Clear the interrupt flag in the interrupt module Note: Not all functionality is available on all devices. Please refer to the specific device data sheet for availability. 5.6.5.4.3.3 Power-Saving Modes This section provides information on the Power-Saving modes for the Comparator module. Description Operation in Sleep mode: If the Comparator interrupt is enabled, the device will wake up from Sleep mode on the Comparator interrupt. If the Comparator interrupt is disabled,the comparator will work, but it will not wake up the device from sleep. Operation in Idle mode: The functions PLIB_CMP_StopInIdleModeEnable and PLIB_CMP_StopInIdleModeDisable determine if the Comparator module stops or continues operation in Idle mode. If the function PLIB_CMP_StopInIdleModeDisable is used, the module will continue operation in the Idle mode. If the Comparator interrupt is enabled, the device will wake up from Idle mode on the Comparator interrupt. If the function PLIB_CMP_StopInIdleModeEnable is used, the module will work in Idle mode but the interrupt will not generate if it is enabled. # Decscription Function Associated 1 Enable Comparator Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable 2 Disable Comparator Stop in Idle mode. PLIB_CMP_StopInIdleModeDisable Example //Select comparator stop in idle mode PLIB_CMP_StopInIdleModeEnable(MY_CMP_INSTANCE); Note: Not all functionality is available on all devices. Please refer to the specific device data sheet for availability. 5.6.5.5 Library Interface Data Types and Constants Name Description CMP_CLOCK_DIVIDE Defines CMP Filter Clock Divide CMP_CVREF_BANDGAP_SELECT Lists the bandgap selection options. CMP_CVREF_REFERENCE_SELECT Lists the reference selection options. CMP_CVREF_VALUE Lists the voltage reference value selection options. CMP_CVREF_VOLTAGE_SOURCE Lists the Voltage source options. CMP_FILTER_CLOCK Defines CMP filter input clock CMP_INTERRUPT_EVENT Defines CMP interrupt events. CMP_INVERTING_INPUT Defines the list of CMP inverting Input CMP_MASK_A Defines CMP Mask A Input. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1672 CMP_MASK_B Defines CMP Mask B Input. CMP_MASK_C Defines CMP Mask C Input. CMP_MODULE_ID Identifies the CMP modules supported CMP_NON_INVERTING_INPUT Defines the list of CMP non inverting Input CMP_SPEED_POWER Defines CMP Speed/Power Comparator AND Gate Configuration Functions Name Description PLIB_CMP_AndGateAInputDisable A input disabled as input to the AND gate PLIB_CMP_AndGateAInputEnable A input enabled as input to the AND gate. PLIB_CMP_AndGateBInputDisable B input disabled as input to the AND gate. PLIB_CMP_AndGateBInputEnable B input enabled as input to the AND gate. PLIB_CMP_AndGateCInputEnable C input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedAInputDisable Inverted A input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedAInputEnable Inverted A input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedBInputDisable Inverted B input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedBInputEnable Inverted B input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedCInputDisable Inverted C input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedCInputEnable Inverted C input enabled as input to the AND gate. PLIB_CMP_NegativeAndGateOutputDisable Negative AND gate output disable. PLIB_CMP_NegativeAndGateOutputEnable Negative AND gate output enable. PLIB_CMP_PositiveAndGateOutputDisable Positive AND gate output disable. PLIB_CMP_PositiveAndGateOutputEnable Positive AND gate output enable. PLIB_CMP_AndGateCInputDisable C input disabled as input to the AND gate. Comparator Feature Configuration Functions Name Description PLIB_CMP_Cmp1OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_Cmp1OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_Cmp2OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_Cmp2OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_HysteresisDisable Comparator hysteresis disable. PLIB_CMP_HysteresisEnable Comparator hysteresis enable. PLIB_CMP_OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_OutputSynchronousWithTimer1Disable Comparator output is asynchronous. PLIB_CMP_OutputSynchronousWithTimer1Enable Comparator Output Synchronous mode select. PLIB_CMP_StopInIdleModeDisable Disables Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable Enables Stop in Idle mode. Comparator Filter Clock Configuration Functions Name Description PLIB_CMP_FilterClockDivideSelect Comparator filter clock divide select. PLIB_CMP_FilterDisable Comparator filter disable. PLIB_CMP_FilterEnable Comparator filter enable. PLIB_CMP_FilterInputClockSelect Comparator filter input clock select. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1673 Comparator Mask Select Configuration Functions Name Description PLIB_CMP_HighLevelMaskSelect High-level masking select. PLIB_CMP_LowLevelMaskSelect Low-level masking select. Comparator Op amp Mode Configuration Functions Name Description PLIB_CMP_OpAmpModeDisable Op amp operation mode disable. PLIB_CMP_OpAmpModeEnable Op amp operation mode enable. PLIB_CMP_OpAmpOutputDisable Op amp output disable. PLIB_CMP_OpAmpOutputEnable Op amp output enable. Comparator OR Gate Configuration Functions Name Description PLIB_CMP_OrGateAInputDisable OR gate A input disable. PLIB_CMP_OrGateAInputEnable A input connected to OR gate. PLIB_CMP_OrGateBInputDisable OR gate B input disable. PLIB_CMP_OrGateBInputEnable B input connected to OR gate. PLIB_CMP_OrGateCInputDisable OR gate C input disable. PLIB_CMP_OrGateCInputEnable C input connected to OR gate. PLIB_CMP_OrGateInvertedAInputDisable OR gate inverted A input disable. PLIB_CMP_OrGateInvertedAInputEnable Inverted A input connected to OR gate. PLIB_CMP_OrGateInvertedBInputDisable OR gate inverted B input disable. PLIB_CMP_OrGateInvertedBInputEnable Inverted B input connected to OR gate PLIB_CMP_OrGateInvertedCInputDisable OR gate inverted C input disable. PLIB_CMP_OrGateInvertedCInputEnable Inverted C input connected to OR gate Feature Existence Functions Name Description PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Identifies whether the CVREFBGRefVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFEnableControl Identifies whether the CVREFEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsCVREFOutputEnableControl Identifies whether the CVREFOutputEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Identifies whether the CVREFRefVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFValueSelect Identifies whether the CVREFValueSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFVoltageRangeSelect Identifies whether the CVREFVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFWideRangeControl Identifies whether the CVREFWideRangeControl feature exists on the Comparator module. PLIB_CMP_ExistsEnableControl Identifies whether the ComparatorEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsInterruptEventSelect Identifies whether the InterruptEventSelect feature exists on the Comparator module. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1674 PLIB_CMP_ExistsInvertingInputSelect Identifies whether the InvertingInputSelect feature exists on the Comparator module. PLIB_CMP_ExistsInvertOutputControl Identifies whether the InvertOutputSelectControl feature exists on the Comparator module. PLIB_CMP_ExistsNonInvertingInputSelect Identifies whether the NonInvertingInputSelect feature exists on the Comparator module. PLIB_CMP_ExistsOutputEnableControl Identifies whether the ComparatorOutputEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsOutputLevelControl Identifies whether the OutputLevelSelectControl feature exists on the Comparator module. PLIB_CMP_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Comparator module. General Configuration Functions Name Description PLIB_CMP_CVREF_BandGapReferenceSourceSelect Selects the band gap reference voltage source. PLIB_CMP_CVREF_Enable Enables the voltage reference of the Comparator module. PLIB_CMP_CVREF_Output2Disable Disables the Vsource/2 voltage output. PLIB_CMP_CVREF_Output2Enable Enables the Vsource/2 voltage output. PLIB_CMP_CVREF_OutputDisable Disables the output voltage. PLIB_CMP_CVREF_OutputEnable Enables the voltage output. PLIB_CMP_CVREF_ReferenceVoltageSelect Selects the voltage reference value. PLIB_CMP_CVREF_SourceNegativeInputSelect Configures the Comparator module to use the selected input as a negative reference. PLIB_CMP_CVREF_SourceVoltageSelect Connects the Comparator module to the selected voltage source. PLIB_CMP_CVREF_ValueGet Returns the voltage setting value. PLIB_CMP_CVREF_ValueSelect Selects the voltage reference value. PLIB_CMP_CVREF_WideRangeDisable Disables the wide range. PLIB_CMP_CVREF_WideRangeEnable Enables the wide range. PLIB_CMP_CVREF_WideRangeIsEnabled Returns whether the wide range is selected for the reference voltage. PLIB_CMP_Disable Disables the Comparator module. PLIB_CMP_Enable Enables the Comparator module. PLIB_CMP_EventHasOccurred Comparator event status. PLIB_CMP_EventStatusClear Comparator event clear. PLIB_CMP_InterruptEventSelect Comparator interrupt event select. PLIB_CMP_InvertedOutputSelect Comparator output is inverted. PLIB_CMP_InvertingInputChannelSelect Comparator inverting input channel select. PLIB_CMP_NonInvertedOutputSelect Comparator output is non-inverted. PLIB_CMP_NonInvertingInputChannelSelect Comparator input channel select. PLIB_CMP_OutputDisable Disables the Comparator output. PLIB_CMP_OutputEnable Enables the Comparator output. PLIB_CMP_OutputStatusGet Comparator output status. PLIB_CMP_CVREF_Disable Disables the voltage reference of the Comparator module. Description This section lists and describes the functions, data types, and constants available in the Comparator Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1675 5.6.5.5.1 General Configuration Functions 5.6.5.5.1.1 PLIB_CMP_CVREF_BandGapReferenceSourceSelect Function C void PLIB_CMP_CVREF_BandGapReferenceSourceSelect( CMP_MODULE_ID index, CMP_CVREF_BANDGAP_SELECT select ); Description This function selects the band gap reference voltage source from the available options from CMP_CVREF_BANDGAP_SELECT. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured select Select a band gap reference source from CMP_CVREF_BANDGAP_SELECT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFBGRefVoltageRangeSelect in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_BandGapReferenceSourceSelect ( CMP_CVREF_ID_1, PLIB_CMP_CVREF_BANDGAP_0_6V ); 5.6.5.5.1.2 PLIB_CMP_CVREF_Enable Function C void PLIB_CMP_CVREF_Enable( CMP_MODULE_ID index ); Description This function enables the voltage reference of the Comparator module. Preconditions The Comparator module should be appropriately configured before being enabled. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1676 PLIB_CMP_CVREF_ExistsCVREFEnableControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_Enable(CMP_CVREF_ID_1); 5.6.5.5.1.3 PLIB_CMP_CVREF_Output2Disable Function C void PLIB_CMP_CVREF_Output2Disable( CMP_MODULE_ID index ); Description This function disables the Vsource/2 voltage output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_CMP_CVREF_Output2Disable(CMP_CVREF_ID_1); 5.6.5.5.1.4 PLIB_CMP_CVREF_Output2Enable Function C void PLIB_CMP_CVREF_Output2Enable( CMP_MODULE_ID index ); Description This function enables the Vsource/2 voltage output. This is independent of voltage output 1. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_CMP_CVREF_Output2Enable(CMP_CVREF_ID_1); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1677 5.6.5.5.1.5 PLIB_CMP_CVREF_OutputDisable Function C void PLIB_CMP_CVREF_OutputDisable( CMP_MODULE_ID index ); Description This function disables the reference voltage output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFOutputEnableControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_VoltageOutputDisable(CMP_CVREF_ID_1); 5.6.5.5.1.6 PLIB_CMP_CVREF_OutputEnable Function C void PLIB_CMP_CVREF_OutputEnable( CMP_MODULE_ID index ); Description This function enables the voltage output Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFOutputEnableControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_OutputEnable(CMP_CVREF_ID_1); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1678 5.6.5.5.1.7 PLIB_CMP_CVREF_ReferenceVoltageSelect Function C void PLIB_CMP_CVREF_ReferenceVoltageSelect( CMP_MODULE_ID index, CMP_CVREF_REFERENCE_SELECT reference ); Description This function selects the voltage reference value. This value decides how many resistance units will be added and thus decides the output voltage. Preconditions Determine the correct value that should be passed. Parameters Parameters Description index Identifier for the device instance to be configured value Select value from CMP_CVREF_VALUE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFRefVoltageRangeSelect in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_ReferenceVoltageSelect ( CMP_CVREF_ID_1, CMP_CVREF_VALUE_13 ); 5.6.5.5.1.8 PLIB_CMP_CVREF_SourceNegativeInputSelect Function C void PLIB_CMP_CVREF_SourceNegativeInputSelect( CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE_NEG_REFERENCE negInput ); Description This function configures the Comparator module to use the selected input as a negative reference for the voltage source. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured. negInput Select the voltage source negative reference from CMP_CVREF_VOLTAGE_SOURCE_NEG_REFERENCE Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1679 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. For such devices, selecting the positive source will automatically select the negative input. Example PLIB_CMP_CVREF_SourceNegativeInputSelect (CMP_CVREF_ID_1, CMP_CVREF_VOLTAGE_SOURCE_NEG_REF_GROUND); 5.6.5.5.1.9 PLIB_CMP_CVREF_SourceVoltageSelect Function C void PLIB_CMP_CVREF_SourceVoltageSelect( CMP_MODULE_ID index, CMP_CVREF_VOLTAGE_SOURCE source ); Description This function connects the Comparator module to the selected voltage source. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source Select the voltage source from CMP_CVREF_VOLTAGE_SOURCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFVoltageRangeSelect in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_SourceVoltageSelect (CMP_CVREF_ID_1, CMP_CVREF_VOLTAGE_SOURCE_INTERNAL); 5.6.5.5.1.10 PLIB_CMP_CVREF_ValueGet Function C CMP_CVREF_VALUE PLIB_CMP_CVREF_ValueGet( CMP_MODULE_ID index ); Description This function returns the configured reference voltage value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1680 Returns CMP_CVREF_VALUE - Reference voltage value Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFValueSelect in your application to determine whether this feature is available. Example CMP_CVREF_VALUE value; value = PLIB_CMP_CVREF_ValueGet ( CMP_CVREF_ID_1 ); 5.6.5.5.1.11 PLIB_CMP_CVREF_ValueSelect Function C void PLIB_CMP_CVREF_ValueSelect( CMP_MODULE_ID index, CMP_CVREF_VALUE value ); Description This function selects the voltage reference value. This value decides how many resistance units will be added and therefore, decides the output voltage. Preconditions Determine the correct value that should be passed. Parameters Parameters Description index Identifier for the device instance to be configured value Select value from CMP_CVREF_VALUE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFValueSelect in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_ValueSelect ( CMP_CVREF_ID_1, CMP_CVREF_VALUE_13 ); 5.6.5.5.1.12 PLIB_CMP_CVREF_WideRangeDisable Function C void PLIB_CMP_CVREF_WideRangeDisable( CMP_MODULE_ID index ); Description This function disables the wide range for reference voltage. The range of possible voltages will become narrower, and finer voltage options can be achieved in this case. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1681 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_WideRangeDisable(CMP_CVREF_ID_1); 5.6.5.5.1.13 PLIB_CMP_CVREF_WideRangeEnable Function C void PLIB_CMP_CVREF_WideRangeEnable( CMP_MODULE_ID index ); Description This function enables the wide range for reference voltage. The voltage range starts from zero if the wide range is selected. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_WideRangeEnable(CMP_CVREF_ID_1); 5.6.5.5.1.14 PLIB_CMP_CVREF_WideRangeIsEnabled Function C bool PLIB_CMP_CVREF_WideRangeIsEnabled( CMP_MODULE_ID index ); Description This function returns whether the wide range is enabled. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1682 Parameters Parameters Description index Identifier for the device instance to be configured Returns • true = The wide range is enabled • false = The wide range is not enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFWideRangeControl in your application to determine whether this feature is available. Example bool range; range = PLIB_CMP_CVREF_WideRangeIsEnabled(MY_CMP_CVREF_ID); 5.6.5.5.1.15 PLIB_CMP_Disable Function C void PLIB_CMP_Disable( CMP_MODULE_ID index ); Description This function disables (i.e., turns OFF) the selected Comparator module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Disable(MY_CMP_INSTANCE); 5.6.5.5.1.16 PLIB_CMP_Enable Function C void PLIB_CMP_Enable( CMP_MODULE_ID index ); Description This function enables (i.e., turns ON) the selected Comparator module. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1683 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Enable(MY_CMP_INSTANCE); 5.6.5.5.1.17 PLIB_CMP_EventHasOccurred Function C bool PLIB_CMP_EventHasOccurred( CMP_MODULE_ID index ); Description This function will return the current event status of the Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true = The event flag is set • false = The event flag is clear Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // bool cmp_event_status = PLIB_CMP_EventHasOccurred(MY_CMP_INSTANCE); 5.6.5.5.1.18 PLIB_CMP_EventStatusClear Function C void PLIB_CMP_EventStatusClear( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1684 Description This function will clear event status bit of the Comparator. Subsequent triggers and interrupts are disabled until the bit is cleared. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_EventStatusClear(MY_CMP_INSTANCE); 5.6.5.5.1.19 PLIB_CMP_InterruptEventSelect Function C void PLIB_CMP_InterruptEventSelect( CMP_MODULE_ID index, CMP_INTERRUPT_EVENT event ); Description This function will select when the Comparator interrupt should occur. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured event One of the possible values from CMP_INTERRUPT_EVENT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsInterruptEventSelect in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // CMP_INTERRUPT_EVENT - CMP_LOW_TO_HIGH PLIB_CMP_InterruptEventSelect(MY_CMP_INSTANCE, CMP_LOW_TO_HIGH); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1685 5.6.5.5.1.20 PLIB_CMP_InvertedOutputSelect Function C void PLIB_CMP_InvertedOutputSelect( CMP_MODULE_ID index ); Description This function will select the inverted comparator output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControlExistsInvertOutputControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_InvertedOutputSelect(MY_CMP_INSTANCE,); 5.6.5.5.1.21 PLIB_CMP_InvertingInputChannelSelect Function C void PLIB_CMP_InvertingInputChannelSelect( CMP_MODULE_ID index, CMP_INVERTING_INPUT channel ); Description This function will select the inverting input channels for the Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel One of the possible values from CMP_INVERTING_INPUT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1686 PLIB_CMP_ExistsInvertingInputSelect in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_InvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_INVERTING_INPUT_CHANNEL_B); 5.6.5.5.1.22 PLIB_CMP_NonInvertedOutputSelect Function C void PLIB_CMP_NonInvertedOutputSelect( CMP_MODULE_ID index ); Description This function will select the non-inverted comparator output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControlExistsInvertOutputControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_NonInvertedOutputSelect(MY_CMP_INSTANCE,); 5.6.5.5.1.23 PLIB_CMP_NonInvertingInputChannelSelect Function C void PLIB_CMP_NonInvertingInputChannelSelect( CMP_MODULE_ID index, CMP_NON_INVERTING_INPUT input ); Description This function will select the non-inverting input channels for the Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel One of the possible values from CMP_NON_INVERTING_INPUT 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1687 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsNonInvertingInputSelect in your application to determine whether this feature is available.s Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_NonInvertingInputChannelSelect(MY_CMP_INSTANCE,CMP_NON_INVERTING_INPUT_A); 5.6.5.5.1.24 PLIB_CMP_OutputDisable Function C void PLIB_CMP_OutputDisable( CMP_MODULE_ID index ); Description This function disables (i.e., turns OFF) the Comparator output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputDisable(MY_CMP_INSTANCE); 5.6.5.5.1.25 PLIB_CMP_OutputEnable Function C void PLIB_CMP_OutputEnable( CMP_MODULE_ID index ); Description This function enables (i.e., turns ON) the Comparator output. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1688 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputEnableControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputEnable(MY_CMP_INSTANCE); 5.6.5.5.1.26 PLIB_CMP_OutputStatusGet Function C bool PLIB_CMP_OutputStatusGet( CMP_MODULE_ID index ); Description This function will return the current status of the Comparator output. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true = The status flag is set • false = The status flag is clear Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // bool cmp_status=PLIB_CMP_OutputStatusGet(MY_CMP_INSTANCE); 5.6.5.5.1.27 PLIB_CMP_CVREF_Disable Function C void PLIB_CMP_CVREF_Disable( CMP_MODULE_ID index ); Description This function disables the voltage reference of the Comparator module. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1689 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_CVREF_ExistsCVREFEnableControl in your application to determine whether this feature is available. Example PLIB_CMP_CVREF_Disable (CMP_CVREF_ID_1); 5.6.5.5.2 Comparator Feature Configuration Functions 5.6.5.5.2.1 PLIB_CMP_Cmp1OutputHighSelect Function C void PLIB_CMP_Cmp1OutputHighSelect( CMP_MODULE_ID index ); Description This function will set the Comparator output bit to '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Cmp1OutputHighSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.2 PLIB_CMP_Cmp1OutputLowSelect Function C void PLIB_CMP_Cmp1OutputLowSelect( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1690 Description This function will set the Comparator output bit to '0'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Cmp1OutputLowSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.3 PLIB_CMP_Cmp2OutputHighSelect Function C void PLIB_CMP_Cmp2OutputHighSelect( CMP_MODULE_ID index ); Description This function will set the Comparator output bit to '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Cmp2OutputHighSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.4 PLIB_CMP_Cmp2OutputLowSelect Function C void PLIB_CMP_Cmp2OutputLowSelect( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1691 Description This function will set the Comparator output bit to '0'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_Cmp2OutputLowSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.5 PLIB_CMP_HysteresisDisable Function C void PLIB_CMP_HysteresisDisable( CMP_MODULE_ID index ); Description This function will disable the hysteresis of the Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_HysteresisDisable(MY_CMP_INSTANCE); 5.6.5.5.2.6 PLIB_CMP_HysteresisEnable Function C void PLIB_CMP_HysteresisEnable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1692 Description This function will enable the hysteresis of the Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_HysteresisEnable(MY_CMP_INSTANCE); 5.6.5.5.2.7 PLIB_CMP_OutputHighSelect Function C void PLIB_CMP_OutputHighSelect( CMP_MODULE_ID index ); Description This function will set the Comparator output bit to '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputLevelControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputHighSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.8 PLIB_CMP_OutputLowSelect Function C void PLIB_CMP_OutputLowSelect( CMP_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1693 ); Description This function will set the Comparator output bit to '0'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsOutputLevelControl in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. PLIB_CMP_OutputLowSelect(MY_CMP_INSTANCE,); 5.6.5.5.2.9 PLIB_CMP_OutputSynchronousWithTimer1Disable Function C void PLIB_CMP_OutputSynchronousWithTimer1Disable( CMP_MODULE_ID index ); Description This function will disable the synchronized comparator output with the Timer1 clock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OutputSynchronousWithTimer1Disable(MY_CMP_INSTANCE); 5.6.5.5.2.10 PLIB_CMP_OutputSynchronousWithTimer1Enable Function C void PLIB_CMP_OutputSynchronousWithTimer1Enable( 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1694 CMP_MODULE_ID index ); Description This function will synchronize comparator output to the rising edge of the Timer1 clock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OutputSynchronousWithTimer1Enable(MY_CMP_INSTANCE); 5.6.5.5.2.11 PLIB_CMP_StopInIdleModeDisable Function C void PLIB_CMP_StopInIdleModeDisable( CMP_MODULE_ID index ); Description This function will continue operation of all enabled comparators when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsStopInIdle in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_StopInIdleModeDisable(MY_CMP_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1695 5.6.5.5.2.12 PLIB_CMP_StopInIdleModeEnable Function C void PLIB_CMP_StopInIdleModeEnable( CMP_MODULE_ID index ); Description This function will discontinue operation of all comparators when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_CMP_ExistsStopInIdle in your application to determine whether this feature is available. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_StopInIdleModeEnable(MY_CMP_INSTANCE); 5.6.5.5.3 Comparator AND Gate Configuration Functions 5.6.5.5.3.1 PLIB_CMP_AndGateAInputDisable Function C void PLIB_CMP_AndGateAInputDisable( CMP_MODULE_ID index ); Description This function will disable the A input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1696 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateAInputDisable(MY_CMP_INSTANCE); 5.6.5.5.3.2 PLIB_CMP_AndGateAInputEnable Function C void PLIB_CMP_AndGateAInputEnable( CMP_MODULE_ID index ); Description This function will select the A input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateAInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.3 PLIB_CMP_AndGateBInputDisable Function C void PLIB_CMP_AndGateBInputDisable( CMP_MODULE_ID index ); Description This function will disable the B input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1697 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateBInputDisable(MY_CMP_INSTANCE); 5.6.5.5.3.4 PLIB_CMP_AndGateBInputEnable Function C void PLIB_CMP_AndGateBInputEnable( CMP_MODULE_ID index ); Description This function will select the B input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateBInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.5 PLIB_CMP_AndGateCInputEnable Function C void PLIB_CMP_AndGateCInputEnable( CMP_MODULE_ID index ); Description This function will select the C input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1698 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateCInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.6 PLIB_CMP_AndGateInvertedAInputDisable Function C void PLIB_CMP_AndGateInvertedAInputDisable( CMP_MODULE_ID index ); Description This function will disable the inverted A input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedAInputDisable(MY_CMP_INSTANCE); 5.6.5.5.3.7 PLIB_CMP_AndGateInvertedAInputEnable Function C void PLIB_CMP_AndGateInvertedAInputEnable( CMP_MODULE_ID index ); Description This function will enable the inverted A input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1699 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedAInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.8 PLIB_CMP_AndGateInvertedBInputDisable Function C void PLIB_CMP_AndGateInvertedBInputDisable( CMP_MODULE_ID index ); Description This function will disable the inverted B input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedBInputDisable(MY_CMP_INSTANCE); 5.6.5.5.3.9 PLIB_CMP_AndGateInvertedBInputEnable Function C void PLIB_CMP_AndGateInvertedBInputEnable( CMP_MODULE_ID index ); Description This function will enable the inverted B input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1700 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedBInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.10 PLIB_CMP_AndGateInvertedCInputDisable Function C void PLIB_CMP_AndGateInvertedCInputDisable( CMP_MODULE_ID index ); Description This function will disable the inverted C input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedCInputDisable(MY_CMP_INSTANCE); 5.6.5.5.3.11 PLIB_CMP_AndGateInvertedCInputEnable Function C void PLIB_CMP_AndGateInvertedCInputEnable( CMP_MODULE_ID index ); Description This function will enable the inverted C input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1701 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateInvertedCInputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.12 PLIB_CMP_NegativeAndGateOutputDisable Function C void PLIB_CMP_NegativeAndGateOutputDisable( CMP_MODULE_ID index ); Description This function will disable the negative AND gate output to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_NegativeAndGateOutputDisable (MY_CMP_INSTANCE); 5.6.5.5.3.13 PLIB_CMP_NegativeAndGateOutputEnable Function C void PLIB_CMP_NegativeAndGateOutputEnable( CMP_MODULE_ID index ); Description This function will enable the negative AND gate output to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1702 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_NegativeAndGateOutputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.14 PLIB_CMP_PositiveAndGateOutputDisable Function C void PLIB_CMP_PositiveAndGateOutputDisable( CMP_MODULE_ID index ); Description This function will disable the positive AND gate output to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_PositiveAndGateOutputDisable (MY_CMP_INSTANCE); 5.6.5.5.3.15 PLIB_CMP_PositiveAndGateOutputEnable Function C void PLIB_CMP_PositiveAndGateOutputEnable( CMP_MODULE_ID index ); Description This function will enable the positive AND gate output to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1703 Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_PositiveAndGateOutputEnable(MY_CMP_INSTANCE); 5.6.5.5.3.16 PLIB_CMP_AndGateCInputDisable Function C void PLIB_CMP_AndGateCInputDisable( CMP_MODULE_ID index ); Description This function will disable the C input as the input to the AND gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_AndGateCInputDisable(MY_CMP_INSTANCE); 5.6.5.5.4 Comparator Filter Clock Configuration Functions 5.6.5.5.4.1 PLIB_CMP_FilterClockDivideSelect Function C void PLIB_CMP_FilterClockDivideSelect( CMP_MODULE_ID index, CMP_CLOCK_DIVIDE scale ); Description This function will select the Comparator filter clock divide. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured scale One of the possible values from CMP_CLOCK_DIVIDE 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1704 Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_FilterClockDivideSelect (MY_CMP_INSTANCE,CMP_FILTER_CLOCK_DIVIDE_1_2); 5.6.5.5.4.2 PLIB_CMP_FilterDisable Function C void PLIB_CMP_FilterDisable( CMP_MODULE_ID index ); Description This function will disable the Comparator digital filter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_FilterDisable (MY_CMP_INSTANCE); 5.6.5.5.4.3 PLIB_CMP_FilterEnable Function C void PLIB_CMP_FilterEnable( CMP_MODULE_ID index ); Description This function will enable the Comparator digital filter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1705 Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_FilterEnable (MY_CMP_INSTANCE); 5.6.5.5.4.4 PLIB_CMP_FilterInputClockSelect Function C void PLIB_CMP_FilterInputClockSelect( CMP_MODULE_ID index, CMP_FILTER_CLOCK inputclock ); Description This function will select the Comparator filter input clock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured inputclock One of the possible values from CMP_FILTER_CLOCK Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_FilterInputClockSelect (MY_CMP_INSTANCE,CMP_FILTER_CLOCK_FP); 5.6.5.5.5 Comparator Op amp Mode Configuration Functions 5.6.5.5.5.1 PLIB_CMP_OpAmpModeDisable Function C void PLIB_CMP_OpAmpModeDisable( CMP_MODULE_ID index ); Description This function will cause the circuit to operate as a Comparator. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1706 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OpAmpModeDisable(MY_CMP_INSTANCE); 5.6.5.5.5.2 PLIB_CMP_OpAmpModeEnable Function C void PLIB_CMP_OpAmpModeEnable( CMP_MODULE_ID index ); Description This function will cause the circuit to operate as an Op amp. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OpAmpModeEnable(MY_CMP_INSTANCE); 5.6.5.5.5.3 PLIB_CMP_OpAmpOutputDisable Function C void PLIB_CMP_OpAmpOutputDisable( CMP_MODULE_ID index ); Description This function will disable the Op amp output pin. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1707 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OpAmpOutputDisable(MY_CMP_INSTANCE); 5.6.5.5.5.4 PLIB_CMP_OpAmpOutputEnable Function C void PLIB_CMP_OpAmpOutputEnable( CMP_MODULE_ID index ); Description This function will enable the Op amp output pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OpAmpOutputEnable(MY_CMP_INSTANCE); 5.6.5.5.6 Comparator OR Gate Configuration Functions 5.6.5.5.6.1 PLIB_CMP_OrGateAInputDisable Function C void PLIB_CMP_OrGateAInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1708 Description This function will disable the A input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateAInputDisable(MY_CMP_INSTANCE); 5.6.5.5.6.2 PLIB_CMP_OrGateAInputEnable Function C void PLIB_CMP_OrGateAInputEnable( CMP_MODULE_ID index ); Description This function will select the A input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateAInputEnable(MY_CMP_INSTANCE); 5.6.5.5.6.3 PLIB_CMP_OrGateBInputDisable Function C void PLIB_CMP_OrGateBInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1709 Description This function will disable the B input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateBInputDisable(MY_CMP_INSTANCE); 5.6.5.5.6.4 PLIB_CMP_OrGateBInputEnable Function C void PLIB_CMP_OrGateBInputEnable( CMP_MODULE_ID index ); Description This function will select the B input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateBInputEnable(MY_CMP_INSTANCE); 5.6.5.5.6.5 PLIB_CMP_OrGateCInputDisable Function C void PLIB_CMP_OrGateCInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1710 Description This function will disable the C input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateCInputDisable(MY_CMP_INSTANCE); 5.6.5.5.6.6 PLIB_CMP_OrGateCInputEnable Function C void PLIB_CMP_OrGateCInputEnable( CMP_MODULE_ID index ); Description This function will select the C input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateCInputEnable(MY_CMP_INSTANCE); 5.6.5.5.6.7 PLIB_CMP_OrGateInvertedAInputDisable Function C void PLIB_CMP_OrGateInvertedAInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1711 Description This function will disable the inverted A input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedAInputDisable (MY_CMP_INSTANCE); 5.6.5.5.6.8 PLIB_CMP_OrGateInvertedAInputEnable Function C void PLIB_CMP_OrGateInvertedAInputEnable( CMP_MODULE_ID index ); Description This function will select the inverted A input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedAInputEnable (MY_CMP_INSTANCE); 5.6.5.5.6.9 PLIB_CMP_OrGateInvertedBInputDisable Function C void PLIB_CMP_OrGateInvertedBInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1712 Description This function will disable the inverted B input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedBInputDisable (MY_CMP_INSTANCE); 5.6.5.5.6.10 PLIB_CMP_OrGateInvertedBInputEnable Function C void PLIB_CMP_OrGateInvertedBInputEnable( CMP_MODULE_ID index ); Description This function will select the inverted B input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedBInputEnable (MY_CMP_INSTANCE); 5.6.5.5.6.11 PLIB_CMP_OrGateInvertedCInputDisable Function C void PLIB_CMP_OrGateInvertedCInputDisable( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1713 Description This function will disable the inverted C input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedCInputDisable (MY_CMP_INSTANCE); 5.6.5.5.6.12 PLIB_CMP_OrGateInvertedCInputEnable Function C void PLIB_CMP_OrGateInvertedCInputEnable( CMP_MODULE_ID index ); Description This function will select the inverted C input as the input to the OR gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_OrGateInvertedCInputEnable (MY_CMP_INSTANCE); 5.6.5.5.7 Comparator Mask Select Configuration Functions 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1714 5.6.5.5.7.1 PLIB_CMP_HighLevelMaskSelect Function C void PLIB_CMP_HighLevelMaskSelect( CMP_MODULE_ID index ); Description This function will select the high-level masking. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_HighLevelMaskSelect(MY_CMP_INSTANCE); 5.6.5.5.7.2 PLIB_CMP_LowLevelMaskSelect Function C void PLIB_CMP_LowLevelMaskSelect( CMP_MODULE_ID index ); Description This function will select the low -evel masking Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_CMP_INSTANCE, is the Comparator instance selected for use by the // application developer. // PLIB_CMP_LowLevelMaskSelect(MY_CMP_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1715 5.6.5.5.8 Data Types and Constants 5.6.5.5.8.1 CMP_CLOCK_DIVIDE Enumeration C typedef enum { CMP_FILTER_CLOCK_DIVIDE_1_1, CMP_FILTER_CLOCK_DIVIDE_1_2, CMP_FILTER_CLOCK_DIVIDE_1_4, CMP_FILTER_CLOCK_DIVIDE_1_8, CMP_FILTER_CLOCK_DIVIDE_1_16, CMP_FILTER_CLOCK_DIVIDE_1_32, CMP_FILTER_CLOCK_DIVIDE_1_64, CMP_FILTER_CLOCK_DIVIDE_1_128 } CMP_CLOCK_DIVIDE; Description CMP Filter Clock Divide Select This macro defines the CMP filter clock divide Members Members Description CMP_FILTER_CLOCK_DIVIDE_1_1 Comparator Filter Clock Division is 1:1 CMP_FILTER_CLOCK_DIVIDE_1_2 Comparator Filter Clock Division is 1:2 CMP_FILTER_CLOCK_DIVIDE_1_4 Comparator Filter Clock Division is 1:4 CMP_FILTER_CLOCK_DIVIDE_1_8 Comparator Filter Clock Division is 1:8 CMP_FILTER_CLOCK_DIVIDE_1_16 Comparator Filter Clock Division is 1:16 CMP_FILTER_CLOCK_DIVIDE_1_32 Comparator Filter Clock Division is 1:32 CMP_FILTER_CLOCK_DIVIDE_1_64 Comparator Filter Clock Division is 1:64 CMP_FILTER_CLOCK_DIVIDE_1_128 Comparator Filter Clock Division is 1:128 5.6.5.5.8.2 CMP_CVREF_BANDGAP_SELECT Enumeration C typedef enum { CMP_CVREF_BANDGAP_1_2V, CMP_CVREF_BANDGAP_0_6V, CMP_CVREF_BANDGAP_VREFPLUS } CMP_CVREF_BANDGAP_SELECT; Description CVREF bandgap select enumeration This enumeration lists the possible Bandgap selection options. Members Members Description CMP_CVREF_BANDGAP_1_2V Select the Band Gap Reference Source as 1.2 V CMP_CVREF_BANDGAP_0_6V Select the Band Gap Reference Source as 0.6 V CMP_CVREF_BANDGAP_VREFPLUS Select the Band Gap Reference Source as VREF 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1716 Remarks None. 5.6.5.5.8.3 CMP_CVREF_REFERENCE_SELECT Enumeration C typedef enum { CMP_CVREF_RESISTOR_LADDER_VOLTAGE, CMP_CVREF_POSITIVE_REFERENCE_VOLTAGE } CMP_CVREF_REFERENCE_SELECT; Description CVREF reference select enumeration This enumeration lists the possible reference selection options. Members Members Description CMP_CVREF_RESISTOR_LADDER_VOLTAGE Select the Band Gap Reference Source as 1.2 V CMP_CVREF_POSITIVE_REFERENCE_VOLTAGE Select the Band Gap Reference Source as 0.6 V Remarks None. 5.6.5.5.8.4 CMP_CVREF_VALUE Enumeration C typedef enum { CMP_CVREF_VALUE_0, CMP_CVREF_VALUE_1, CMP_CVREF_VALUE_2, CMP_CVREF_VALUE_3, CMP_CVREF_VALUE_4, CMP_CVREF_VALUE_5, CMP_CVREF_VALUE_6, CMP_CVREF_VALUE_7, CMP_CVREF_VALUE_8, CMP_CVREF_VALUE_9, CMP_CVREF_VALUE_10, CMP_CVREF_VALUE_11, CMP_CVREF_VALUE_12, CMP_CVREF_VALUE_13, CMP_CVREF_VALUE_14, CMP_CVREF_VALUE_15 } CMP_CVREF_VALUE; Description CVREF voltage reference value selection enumeration This enumeration lists the possible Voltage reference value selection options. Members Members Description CMP_CVREF_VALUE_0 Voltage reference value 0 CMP_CVREF_VALUE_1 Voltage reference value 1 CMP_CVREF_VALUE_2 Voltage reference value 2 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1717 CMP_CVREF_VALUE_3 Voltage reference value 3 CMP_CVREF_VALUE_4 Voltage reference value 4 CMP_CVREF_VALUE_5 Voltage reference value 5 CMP_CVREF_VALUE_6 Voltage reference value 6 CMP_CVREF_VALUE_7 Voltage reference value 7 CMP_CVREF_VALUE_8 Voltage reference value 8 CMP_CVREF_VALUE_9 Voltage reference value 9 CMP_CVREF_VALUE_10 Voltage reference value 10 CMP_CVREF_VALUE_11 Voltage reference value 11 CMP_CVREF_VALUE_12 Voltage reference value 12 CMP_CVREF_VALUE_13 Voltage reference value 13 CMP_CVREF_VALUE_14 Voltage reference value 14 CMP_CVREF_VALUE_15 Voltage reference value 15 Remarks None. 5.6.5.5.8.5 CMP_CVREF_VOLTAGE_SOURCE Enumeration C typedef enum { CMP_CVREF_VOLTAGE_SOURCE_INTERNAL, CMP_CVREF_VOLTAGE_SOURCE_EXTERNAL } CMP_CVREF_VOLTAGE_SOURCE; Description CVREF Voltage source selection enumeration This enumeration lists the possible Voltage source selection options. Members Members Description CMP_CVREF_VOLTAGE_SOURCE_INTERNAL Select vdd/vss source CMP_CVREF_VOLTAGE_SOURCE_EXTERNAL Select external voltage source Remarks None. 5.6.5.5.8.6 CMP_FILTER_CLOCK Enumeration C typedef enum { CMP_FILTER_CLOCK_FP, CMP_FILTER_CLOCK_FOSC, CMP_FILTER_CLOCK_SYNCO1, CMP_FILTER_CLOCK_T2CLK, CMP_FILTER_CLOCK_T3CLK, CMP_FILTER_CLOCK_T4CLK, CMP_FILTER_CLOCK_T5CLK } CMP_FILTER_CLOCK; Description CMP Filter Input Clock Select 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1718 This macro defines the CMP filter input clock Members Members Description CMP_FILTER_CLOCK_FP FP will be the CMP filter input clock CMP_FILTER_CLOCK_FOSC FOSC will be the CMP filter input clock CMP_FILTER_CLOCK_SYNCO1 SYNCO1 will be the CMP filter input clock CMP_FILTER_CLOCK_T2CLK T2CLK will be the CMP filter input clock CMP_FILTER_CLOCK_T3CLK T3CLK will be the CMP filter input clock CMP_FILTER_CLOCK_T4CLK T4CLK will be the CMP filter input clock CMP_FILTER_CLOCK_T5CLK T5CLK will be the CMP filter input clock 5.6.5.5.8.7 CMP_INTERRUPT_EVENT Enumeration C typedef enum { CMP_INTERRUPT_GENERATION_DISABLED } CMP_INTERRUPT_EVENT; Description CMP interrupt event Select This macro defines the CMP interrupt events. Members Members Description CMP_INTERRUPT_GENERATION_DISABLED Select vdd/vss source 5.6.5.5.8.8 CMP_INVERTING_INPUT Enumeration C typedef enum { CMP_INPUT_C2IN_NEGATIVE } CMP_INVERTING_INPUT; Description CMP inverting input channel select This macro defines the list of CMP inverting Input Members Members Description CMP_INPUT_C2IN_NEGATIVE Select vdd/vss source 5.6.5.5.8.9 CMP_MASK_A Enumeration C typedef enum { CMP_MASK_A_PWM1L, CMP_MASK_A_PWM1H, CMP_MASK_A_PWM2L, CMP_MASK_A_PWM2H, CMP_MASK_A_PWM3L, CMP_MASK_A_PWM3H, CMP_MASK_A_PTGO18, 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1719 CMP_MASK_A_PTGO19, CMP_MASK_A_FLT2, CMP_MASK_A_FLT4 } CMP_MASK_A; Description CMP Mask A Input Select This macro defines the CMP Mask A Input. Members Members Description CMP_MASK_A_PWM1L PWM1L will be the CMP mask A input CMP_MASK_A_PWM1H PWM1H will be the CMP mask A input CMP_MASK_A_PWM2L PWM2L will be the CMP mask A input CMP_MASK_A_PWM2H PWM2H will be the CMP mask A input CMP_MASK_A_PWM3L PWM3L will be the CMP mask A input CMP_MASK_A_PWM3H PWM3H will be the CMP mask A input CMP_MASK_A_PTGO18 PTGO18 will be the CMP mask A input CMP_MASK_A_PTGO19 PTGO19 will be the CMP mask A input CMP_MASK_A_FLT2 FLT2 will be the CMP mask A input CMP_MASK_A_FLT4 FLT4 will be the CMP mask A input 5.6.5.5.8.10 CMP_MASK_B Enumeration C typedef enum { CMP_MASK_B_PWM1L, CMP_MASK_B_PWM1H, CMP_MASK_B_PWM2L, CMP_MASK_B_PWM2H, CMP_MASK_B_PWM3L, CMP_MASK_B_PWM3H, CMP_MASK_B_PTGO18, CMP_MASK_B_PTGO19, CMP_MASK_B_FLT2, CMP_MASK_B_FLT4 } CMP_MASK_B; Description CMP Mask B Input Select This macro defines the CMP Mask B Input. Members Members Description CMP_MASK_B_PWM1L PWM1L will be the CMP mask B input CMP_MASK_B_PWM1H PWM1H will be the CMP mask B input CMP_MASK_B_PWM2L PWM2L will be the CMP mask B input CMP_MASK_B_PWM2H PWM2H will be the CMP mask B input CMP_MASK_B_PWM3L PWM3L will be the CMP mask B input CMP_MASK_B_PWM3H PWM3H will be the CMP mask B input CMP_MASK_B_PTGO18 PTGO18 will be the CMP mask B input CMP_MASK_B_PTGO19 PTGO19 will be the CMP mask B input 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1720 CMP_MASK_B_FLT2 FLT2 will be the CMP mask B input CMP_MASK_B_FLT4 FLT4 will be the CMP mask B input 5.6.5.5.8.11 CMP_MASK_C Enumeration C typedef enum { CMP_MASK_C_PWM1L, CMP_MASK_C_PWM1H, CMP_MASK_C_PWM2L, CMP_MASK_C_PWM2H, CMP_MASK_C_PWM3L, CMP_MASK_C_PWM3H, CMP_MASK_C_PTGO18, CMP_MASK_C_PTGO19, CMP_MASK_C_FLT2, CMP_MASK_C_FLT4 } CMP_MASK_C; Description CMP Mask C Input Select This macro defines the CMP Mask C Input. Members Members Description CMP_MASK_C_PWM1L PWM1L will be the CMP mask C input CMP_MASK_C_PWM1H PWM1H will be the CMP mask C input CMP_MASK_C_PWM2L PWM2L will be the CMP mask C input CMP_MASK_C_PWM2H PWM2H will be the CMP mask C input CMP_MASK_C_PWM3L PWM3L will be the CMP mask C input CMP_MASK_C_PWM3H PWM3H will be the CMP mask C input CMP_MASK_C_PTGO18 PTGO18 will be the CMP mask C input CMP_MASK_C_PTGO19 PTGO19 will be the CMP mask C input CMP_MASK_C_FLT2 FLT2 will be the CMP mask C input CMP_MASK_C_FLT4 FLT4 will be the CMP mask C input 5.6.5.5.8.12 CMP_MODULE_ID Enumeration C typedef enum { CMP_ID_1, CMP_ID_2, CMP_ID_3 } CMP_MODULE_ID; Description CMP Module ID This enumeration identifies the CMP modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. Members Members Description CMP_ID_1 CMP Module 1 ID 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1721 CMP_ID_2 CMP Module 2 ID CMP_ID_3 CMP Module 3 ID Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.5.5.8.13 CMP_NON_INVERTING_INPUT Enumeration C typedef enum { CMP_INPUT_C2IN_POSITIVE, CMP_INPUT_INTERNAL_CVREF } CMP_NON_INVERTING_INPUT; Description CMP Non inverting input channel select This macro defines the list of CMP non inverting Input Members Members Description CMP_INPUT_C2IN_POSITIVE Select vdd/vss source CMP_INPUT_INTERNAL_CVREF Select external voltage source 5.6.5.5.8.14 CMP_SPEED_POWER Enumeration C typedef enum { CMP_SPEED_POWER_LOWER, CMP_SPEED_POWER_HIGHER } CMP_SPEED_POWER; Description CMP Speed/Power Select This macro defines the Speed/Power of CMP Members Members Description CMP_SPEED_POWER_LOWER CMP low-power, low-speed CMP_SPEED_POWER_HIGHER CMP normal power, higher speed 5.6.5.5.9 Feature Existence Functions 5.6.5.5.9.1 PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Function C bool PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect( CMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1722 Description This function identifies whether the CVREFBGRefVoltageRangeSelect feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_BandGapReferenceSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFBGRefVoltageRangeSelect feature is supported on the device • false = The CVREFBGRefVoltageRangeSelect feature is not supported on the device Remarks None. 5.6.5.5.9.2 PLIB_CMP_ExistsCVREFEnableControl Function C bool PLIB_CMP_ExistsCVREFEnableControl( CMP_MODULE_ID index ); Description This function identifies whether the CVREFEnableControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_Enable • PLIB_CMP_CVREF_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFEnableControl feature is supported on the device • false = The CVREFEnableControl feature is not supported on the device Remarks None. 5.6.5.5.9.3 PLIB_CMP_ExistsCVREFOutputEnableControl Function C bool PLIB_CMP_ExistsCVREFOutputEnableControl( CMP_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1723 ); Description This function identifies whether the CVREFOutputEnableControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_OutputEnable • PLIB_CMP_CVREF_OutputDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFOutputEnableControl feature is supported on the device • false = The CVREFOutputEnableControl feature is not supported on the device Remarks None. 5.6.5.5.9.4 PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Function C bool PLIB_CMP_ExistsCVREFRefVoltageRangeSelect( CMP_MODULE_ID index ); Description This function identifies whether the CVREFRefVoltageRangeSelect feature is available on the Comparator module. When this function returns true, the following function is supported on the device: • PLIB_CMP_CVREF_ReferenceVoltageSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFRefVoltageRangeSelect feature is supported on the device • false = The CVREFRefVoltageRangeSelect feature is not supported on the device Remarks None. 5.6.5.5.9.5 PLIB_CMP_ExistsCVREFValueSelect Function C bool PLIB_CMP_ExistsCVREFValueSelect( 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1724 CMP_MODULE_ID index ); Description This function identifies whether the CVREFValueSelect feature is available on the Comparator module. When this function returns true, the following function is supported on the device: • PLIB_CMP_CVREF_ValueSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFValueSelect feature is supported on the device • false = The CVREFValueSelect feature is not supported on the device Remarks None. 5.6.5.5.9.6 PLIB_CMP_ExistsCVREFVoltageRangeSelect Function C bool PLIB_CMP_ExistsCVREFVoltageRangeSelect( CMP_MODULE_ID index ); Description This function identifies whether the CVREFVoltageRangeSelect feature is available on the Comparator module. When this function returns true, the following function is supported on the device: • PLIB_CMP_CVREF_SourceVoltageSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFVoltageRangeSelect feature is supported on the device • false = The CVREFVoltageRangeSelect feature is not supported on the device Remarks None. 5.6.5.5.9.7 PLIB_CMP_ExistsCVREFWideRangeControl Function C bool PLIB_CMP_ExistsCVREFWideRangeControl( CMP_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1725 ); Description This function identifies whether the CVREFWideRangeControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_CVREF_WideRangeEnable • PLIB_CMP_CVREF_WideRangeDisable • PLIB_CMP_CVREF_WideRangeIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The CVREFWideRangeControl feature is supported on the device • false = The CVREFWideRangeControl feature is not supported on the device Remarks None. 5.6.5.5.9.8 PLIB_CMP_ExistsEnableControl Function C bool PLIB_CMP_ExistsEnableControl( CMP_MODULE_ID index ); Description This function identifies whether the ComparatorEnableControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_Enable • PLIB_CMP_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ComparatorEnableControl feature is supported on the device • false = The ComparatorEnableControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1726 5.6.5.5.9.9 PLIB_CMP_ExistsInterruptEventSelect Function C bool PLIB_CMP_ExistsInterruptEventSelect( CMP_MODULE_ID index ); Description This function identifies whether the InterruptEventSelect feature is available on the Comparator module. When this function returns true, this function is supported on the device: • PLIB_CMP_InterruptEventSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The InterruptEventSelect feature is supported on the device • false = The InterruptEventSelect feature is not supported on the device Remarks None. 5.6.5.5.9.10 PLIB_CMP_ExistsInvertingInputSelect Function C bool PLIB_CMP_ExistsInvertingInputSelect( CMP_MODULE_ID index ); Description This function identifies whether the InvertingInputSelect feature is available on the Comparator module. When this function returns true, this function is supported on the device: • PLIB_CMP_InvertingInputChannelSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The InvertingInputSelect feature is supported on the device • false = The InvertingInputSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1727 5.6.5.5.9.11 PLIB_CMP_ExistsInvertOutputControl Function C bool PLIB_CMP_ExistsInvertOutputControl( CMP_MODULE_ID index ); Description This function identifies whether the InvertOutputSelectControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_InvertedOutputSelect • PLIB_CMP_NonInvertedOutputSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The InvertOutputSelectControl feature is supported on the device • false = The InvertOutputSelectControl feature is not supported on the device Remarks None. 5.6.5.5.9.12 PLIB_CMP_ExistsNonInvertingInputSelect Function C bool PLIB_CMP_ExistsNonInvertingInputSelect( CMP_MODULE_ID index ); Description This function identifies whether the NonInvertingInputSelect feature is available on the Comparator module. When this function returns true, this function is supported on the device: • PLIB_CMP_adc Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The NonInvertingInputSelect feature is supported on the device • false = The NonInvertingInputSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1728 5.6.5.5.9.13 PLIB_CMP_ExistsOutputEnableControl Function C bool PLIB_CMP_ExistsOutputEnableControl( CMP_MODULE_ID index ); Description This function identifies whether the ComparatorOutputEnableControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputEnable • PLIB_CMP_OutputDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The ComparatorOutputEnableControl feature is supported on the device • false = The ComparatorOutputEnableControl feature is not supported on the device Remarks None. 5.6.5.5.9.14 PLIB_CMP_ExistsOutputLevelControl Function C bool PLIB_CMP_ExistsOutputLevelControl( CMP_MODULE_ID index ); Description This function identifies whether the OutputLevelSelectControl feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_OutputHighSelect • PLIB_CMP_OutputLowSelect • PLIB_CMP_Cmp1OutputHighSelect • PLIB_CMP_Cmp1OutputLowSelect • PLIB_CMP_Cmp2OutputHighSelect • PLIB_CMP_Cmp2OutputLowSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1729 Returns • true = The OutputLevelSelectControl feature is supported on the device • false = The OutputLevelSelectControl feature is not supported on the device Remarks None. 5.6.5.5.9.15 PLIB_CMP_ExistsStopInIdle Function C bool PLIB_CMP_ExistsStopInIdle( CMP_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the Comparator module. When this function returns true, these functions are supported on the device: • PLIB_CMP_StopInIdleModeEnable • PLIB_CMP_StopInIdleModeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true = The StopInIdle feature is supported on the device • false = The StopInIdle feature is not supported on the device Remarks None. 5.6.5.6 Files Files Name Description plib_cmp.h Comparator Peripheral Library Interface Header for Comparator module definitions. Description 5.6.5.6.1 plib_cmp.h Comparator Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Comparator Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1730 Comparator peripheral. Functions Name Description PLIB_CMP_AndGateAInputDisable A input disabled as input to the AND gate PLIB_CMP_AndGateAInputEnable A input enabled as input to the AND gate. PLIB_CMP_AndGateBInputDisable B input disabled as input to the AND gate. PLIB_CMP_AndGateBInputEnable B input enabled as input to the AND gate. PLIB_CMP_AndGateCInputDisable C input disabled as input to the AND gate. PLIB_CMP_AndGateCInputEnable C input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedAInputDisable Inverted A input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedAInputEnable Inverted A input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedBInputDisable Inverted B input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedBInputEnable Inverted B input enabled as input to the AND gate. PLIB_CMP_AndGateInvertedCInputDisable Inverted C input disabled as input to the AND gate. PLIB_CMP_AndGateInvertedCInputEnable Inverted C input enabled as input to the AND gate. PLIB_CMP_Cmp1OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_Cmp1OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_Cmp2OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_Cmp2OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_CVREF_BandGapReferenceSourceSelect Selects the band gap reference voltage source. PLIB_CMP_CVREF_Disable Disables the voltage reference of the Comparator module. PLIB_CMP_CVREF_Enable Enables the voltage reference of the Comparator module. PLIB_CMP_CVREF_Output2Disable Disables the Vsource/2 voltage output. PLIB_CMP_CVREF_Output2Enable Enables the Vsource/2 voltage output. PLIB_CMP_CVREF_OutputDisable Disables the output voltage. PLIB_CMP_CVREF_OutputEnable Enables the voltage output. PLIB_CMP_CVREF_ReferenceVoltageSelect Selects the voltage reference value. PLIB_CMP_CVREF_SourceNegativeInputSelect Configures the Comparator module to use the selected input as a negative reference. PLIB_CMP_CVREF_SourceVoltageSelect Connects the Comparator module to the selected voltage source. PLIB_CMP_CVREF_ValueGet Returns the voltage setting value. PLIB_CMP_CVREF_ValueSelect Selects the voltage reference value. PLIB_CMP_CVREF_WideRangeDisable Disables the wide range. PLIB_CMP_CVREF_WideRangeEnable Enables the wide range. PLIB_CMP_CVREF_WideRangeIsEnabled Returns whether the wide range is selected for the reference voltage. PLIB_CMP_Disable Disables the Comparator module. PLIB_CMP_Enable Enables the Comparator module. PLIB_CMP_EventHasOccurred Comparator event status. PLIB_CMP_EventStatusClear Comparator event clear. PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect Identifies whether the CVREFBGRefVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFEnableControl Identifies whether the CVREFEnableControl feature exists on the Comparator module. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1731 PLIB_CMP_ExistsCVREFOutputEnableControl Identifies whether the CVREFOutputEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsCVREFRefVoltageRangeSelect Identifies whether the CVREFRefVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFValueSelect Identifies whether the CVREFValueSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFVoltageRangeSelect Identifies whether the CVREFVoltageRangeSelect feature exists on the Comparator module. PLIB_CMP_ExistsCVREFWideRangeControl Identifies whether the CVREFWideRangeControl feature exists on the Comparator module. PLIB_CMP_ExistsEnableControl Identifies whether the ComparatorEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsInterruptEventSelect Identifies whether the InterruptEventSelect feature exists on the Comparator module. PLIB_CMP_ExistsInvertingInputSelect Identifies whether the InvertingInputSelect feature exists on the Comparator module. PLIB_CMP_ExistsInvertOutputControl Identifies whether the InvertOutputSelectControl feature exists on the Comparator module. PLIB_CMP_ExistsNonInvertingInputSelect Identifies whether the NonInvertingInputSelect feature exists on the Comparator module. PLIB_CMP_ExistsOutputEnableControl Identifies whether the ComparatorOutputEnableControl feature exists on the Comparator module. PLIB_CMP_ExistsOutputLevelControl Identifies whether the OutputLevelSelectControl feature exists on the Comparator module. PLIB_CMP_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Comparator module. PLIB_CMP_FilterClockDivideSelect Comparator filter clock divide select. PLIB_CMP_FilterDisable Comparator filter disable. PLIB_CMP_FilterEnable Comparator filter enable. PLIB_CMP_FilterInputClockSelect Comparator filter input clock select. PLIB_CMP_HighLevelMaskSelect High-level masking select. PLIB_CMP_HysteresisDisable Comparator hysteresis disable. PLIB_CMP_HysteresisEnable Comparator hysteresis enable. PLIB_CMP_InterruptEventSelect Comparator interrupt event select. PLIB_CMP_InvertedOutputSelect Comparator output is inverted. PLIB_CMP_InvertingInputChannelSelect Comparator inverting input channel select. PLIB_CMP_LowLevelMaskSelect Low-level masking select. PLIB_CMP_NegativeAndGateOutputDisable Negative AND gate output disable. PLIB_CMP_NegativeAndGateOutputEnable Negative AND gate output enable. PLIB_CMP_NonInvertedOutputSelect Comparator output is non-inverted. PLIB_CMP_NonInvertingInputChannelSelect Comparator input channel select. PLIB_CMP_OpAmpModeDisable Op amp operation mode disable. PLIB_CMP_OpAmpModeEnable Op amp operation mode enable. PLIB_CMP_OpAmpOutputDisable Op amp output disable. PLIB_CMP_OpAmpOutputEnable Op amp output enable. PLIB_CMP_OrGateAInputDisable OR gate A input disable. PLIB_CMP_OrGateAInputEnable A input connected to OR gate. PLIB_CMP_OrGateBInputDisable OR gate B input disable. 5.6 Peripheral Library Help MPLAB Harmony Help Comparator Peripheral Library 5-1732 PLIB_CMP_OrGateBInputEnable B input connected to OR gate. PLIB_CMP_OrGateCInputDisable OR gate C input disable. PLIB_CMP_OrGateCInputEnable C input connected to OR gate. PLIB_CMP_OrGateInvertedAInputDisable OR gate inverted A input disable. PLIB_CMP_OrGateInvertedAInputEnable Inverted A input connected to OR gate. PLIB_CMP_OrGateInvertedBInputDisable OR gate inverted B input disable. PLIB_CMP_OrGateInvertedBInputEnable Inverted B input connected to OR gate PLIB_CMP_OrGateInvertedCInputDisable OR gate inverted C input disable. PLIB_CMP_OrGateInvertedCInputEnable Inverted C input connected to OR gate PLIB_CMP_OutputDisable Disables the Comparator output. PLIB_CMP_OutputEnable Enables the Comparator output. PLIB_CMP_OutputHighSelect Comparator output bit is set to '1'. PLIB_CMP_OutputLowSelect Comparator output bit is set to '0'. PLIB_CMP_OutputStatusGet Comparator output status. PLIB_CMP_OutputSynchronousWithTimer1Disable Comparator output is asynchronous. PLIB_CMP_OutputSynchronousWithTimer1Enable Comparator Output Synchronous mode select. PLIB_CMP_PositiveAndGateOutputDisable Positive AND gate output disable. PLIB_CMP_PositiveAndGateOutputEnable Positive AND gate output enable. PLIB_CMP_StopInIdleModeDisable Disables Stop in Idle mode. PLIB_CMP_StopInIdleModeEnable Enables Stop in Idle mode. File Name plib_cmp.h Company Microchip Technology Inc. 5.6.6 DMA Peripheral Library Help 5.6.6.1 Introduction DMA Peripheral Library for Microchip Microcontrollers Direct Memory Access (DMA) is a feature (sub-system) of the microcontroller that allows certain hardware sub-systems within the microcontroller to access the system memory independently of the processor (or the CPU). Description DMA also assists in accessing peripheral memory along with the system memory (data RAM). The DMA sub-system in the PIC family of microcontrollers is optimized for high-performance, real-time, embedded applications where determinism and system latency are priorities. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1733 Figure-1: DMA Hardware Abstraction Model 5.6.6.2 Release Notes MPLAB Harmony Version: v0.70b DMA PLIB Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.6.4 Using the Library This topic describes the basic architecture of the DMA Peripheral Library and provides information and examples on how to use it. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1734 Interface Header File: plib_dma.h The interface to the DMA Peripheral Library is defined in the "plib_dma.h" header file. Any C language source (.c) file that uses the DMA Peripheral library should include "plib_dma.h". Library File: The DMA Peripheral Library (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the peripheral interacts with the framework. 5.6.6.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the DMA module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description The DMA Peripheral Library software is depicted using the following block diagram. Figure-2: DMA Software Abstraction Block Diagram The DMA Peripheral Library takes requests from application software or the DMA device driver and controls the DMA core (the DMA hardware) as per the inputs passed to the library. The major components of the DMA Peripheral Library are: • Source/Destination/Peripheral Address Management • Source/Destination/Peripheral Data Management • DMA Operating/Addressing Mode Management • DMA Channel Management • Interrupt Control and Management The topic Library Overview explains in detail each block of the DMA Peripheral Library software architecture. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1735 Note: The interface provided is a superset of all the functionality of the available DMA module on the device. Refer to the specific device data sheet or related family reference manual to determine the set of functions that are supported for each DMA module on your device. 5.6.6.4.2 Library Usage Model The library interface routines are divided into various topics, each of which addresses one of the blocks or the overall operation of the DMA module. Library Interface Section Description Transfer/Abort (Synchronous) Handles the synchronous DMA transfer start and End. This force request is controlled fully by the software. Transfer/Abort (Asynchronous) Trigger Management Each DMA transaction can be asynchronously initiated or aborted by an interrupt. This feature handles the required configuration. Interrupt Control and Management Each DMA channel can be configured to respond to events such as address error (upper address error, lower address error, etc.), transfer count half done, transfer count done, source data completely transferred, etc. Operating/Addressing Mode Management Before initiating a DMA transaction, the addressing and operating modes of the DMA module need to be configured (per channel basis). As an example, the DMA module can be configured for one shot mode with peripheral indirect addressing mode for a DMA transaction. Channel Management Each DMA channel can be individually configured for a DMA transaction. Priorities can be assigned, a channel can be enabled or disabled, channel chaining can be used, etc. Source/Destination/Peripheral Address Management For each DMA transaction to start, the DMA core needs to know the source and destination addresses. This feature handles this type of configuration. Source/Destination/Peripheral Data Management For each DMA transaction, the amount of data to be transferred, the source and destination size, the transaction type (byte/word), and transaction size can be configured by this feature. Special Function Modules (CRC) Certain high-end controllers support this CRC generator. This feature can be assigned to any of the available DMA channels. This feature handles the configuration of these aspects. Status (Including Channel) This feature specifies the application to access the status information of the DMA and each channel. 5.6.6.4.3 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine which modes are supported. 5.6.6.4.3.1 General Configuration DMA General configuration includes enabling, disabling DMA module globally. It also involves DMA suspend control and behavior in Idle mode. Enable/Disable DMA Enabling and disabling the DMA are the basic routines that may be called during initialization and exit routines of the application. DMA Enable/Disable Example: 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1736 // Enable the DMA controller PLIB_DMA_Enable ( DMA_ID_0 ); // Disable the DMA PLIB_DMA_Disable ( DMA_ID_0 ); // Check the enable status of the DMA controller. if(PLIB_DMA_IsEnabled( DMA_ID_0 )) { // application code } 5.6.6.4.3.2 Transfer/Abort (Synchronous) A DMA transaction can be initiated/aborted asynchronously by configuring an interrupt for a channel. Refer to Transfer/Abort (Asynchronous) Trigger Management for details. In many instances, an application or a device driver needs to initiate a DMA transfer or abort an ongoing DMA transfer for reasons not necessarily known. To handle such cases, the DMA core supports a forceful DMA start and abort. Note: The DMA abort is not supported by all devices. Refer to the specific device data sheet to determine availability of this feature. When a DMA force start request is sent and the channel is already processing/pending to process an interrupt-based DMA transfer, the force transfer request will be ignored. In certain devices, a flag is raised to indicate a collision of DMA requests. Refer to Status (Including Channel) for details. In certain devices, an interrupt is issued to indicate that the active channel may not be able to keep up with the demands from the peripheral module being serviced. For more details refer to Interrupt Control and Management. A DMA force transfer is initiated by the PLIB_DMA_StartTransferSet Function. A DMA force abort is initiated by the PLIB_DMA_AbortTransferSet Function. DMA Transfer/Abort (Synchronous) Configuration A DMA transfer can be initiated or aborted forcefully by the software. Example: // Initiate a forced transfer on channel-3 PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); // Abort a transfer on channel-3 PLIB_DMA_AbortTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); 5.6.6.4.3.3 Transfer/Abort (Asynchronous) Trigger Management DMA Start IRQ Each channel can be configured to initiate a DMA transaction based on the interrupt from a source. This can be enabled/disable per channel basis. To initiate a DMA transfer upon an interrupt trigger, the IRQ number needs to be configured as the start IRQ for this channel. Which source can act as the start IRQ is device-dependent. In certain devices, any of the available IRQs can be configured as the starting IRQ, while in other devices, there is restriction on which interrupt source can act as the start IRQ. Refer to the specific device data sheet to determine feature availability. The starting IRQ is enabled by the PLIB_DMA_ChannelXTriggerEnable Function. A DMA channel can be configured to start a DMA transfer based on the event on an IRQ using the PLIB_DMA_ChannelXStartIRQSet Function. DMA Abort IRQ Each channel can be configured to abort a DMA transaction based on the interrupt from a source. This can be enabled/disabled per channel basis. To abort a DMA transfer upon an interrupt trigger, the IRQ number needs to be configured as the abort IRQ for this channel. The abort IRQ is enabled by the PLIB_DMA_ChannelXTriggerEnable Function. A DMA channel can be configured to abort a 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1737 DMA transfer based on the event on an IRQ using the ChannelXAbortIRQSet Function. DMA Pattern Matching Termination Pattern Match Termination mode allows the user to end a transfer if a byte of data written during a transaction matches a specific pattern. This feature is useful in applications where a variable data size is required and eases the setup of the DMA channel. The UART module is a good example of where this can be effectively used. For details about the pattern data configuration refer to Channel Management. DMA Pattern match mode is enabled using the PLIB_DMA_ChannelXTriggerEnable Function. It can also be disabled using the PLIB_DMA_ChannelXTriggerDisable Function. DMA Transfer/Abort (Asynchronous) Configuration A DMA transfer can also be triggered/aborted asynchronously by using an interrupt event. The interrupt event required to initiate/abort a DMA transfer for a channel needs to be set. Prior to this, the start IRQ and abort IRQ both need to be enabled. Example: // Enable the start IRQ. An interrupt event can trigger a DMA transfer. PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_START ); // Enable the abort IRQ. An interrupt event can abort a DMA transfer on channel-3 PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT ); // Set the start IRQ to UART-2 RX Interrupt PLIB_DMA_ChannelXStartIRQSet ( DMA_ID_0, DMA_CHANNEL_3, DMA_TRIGGER_USART_2_RECEIVE ); // Set the abort IRQ to UART-2 error Interrupt PLIB_DMA_ChannelXAbortIRQSet ( DMA_ID_0, DMA_CHANNEL_3, DMA_TRIGGER_USART_2_ERROR ); In some devices, abort IRQ trigger is not supported. Refer to the specific device data sheet to determine availability. DMA Transfer Pattern Match Abort Configuration The DMA transfer can also be aborted on a pattern match trigger (supported on PIC32 devices). Refer to Transfer/Abort (Asynchronous) Trigger Management for more information on pattern match abort. To use this feature, it must first be enabled. The pattern data needs to be programmed for the required channel. Once this is done, when a DMA transfer is in progress on that particular channel, if the DMA controller comes across the data matching the programmed data the transfer is automatically aborted. Example: // Enable the pattern match abort for channel-3 PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT ); // Set a pattern data to match PLIB_DMA_ChannelXPatternDataSet ( DMA_ID_0, DMA_CHANNEL_3, 0xEE ); 5.6.6.4.3.4 Interrupt Control and Management The DMA module has the ability to generate interrupts reflecting the events that occur during the channel's data transfer. The following are all of the possible interrupts generated during DMA operation. This topic provides information for configuring these interrupts. Error Interrupts This type of event is signalled when an address error has occurred during the channel transfer operation. An address error also can occur if a DMA operation accesses an address beyond configured address limits (low and high). Abort Interrupts This type of event is signalled when a DMA transfer is aborted because of a system event matching the abort IRQ configured for the current channel. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1738 DMA Completion Interrupts (Block Completion Interrupts) This event occurs when a channel transfers a block of configured data. Call Complete Interrupts This event occurs when a channel completes a cell sized data transfer. DMA Midpoint Interrupts This event occurs when the channel is at the midpoint of completing the data transfer. Overrun Interrupts When a DMA channel receives a trigger (software or hardware) while it is servicing another request, an overrun condition occurs. This indicates that the channel is being requested before its current transaction is finished. An overrun condition will not result in termination of the current transaction. Source Address Pointer Activity Interrupts This event occurs when the channel source pointer reached the end of the source or when it reaches the midpoint of the source depending on the way this interrupt is configured. Destination Address Pointer Activity Interrupts This event occurs when the channel destination pointer reached the end of the destination or when it reaches the midpoint of the destination depending on the way this interrupt is configured. This feature helps in configuring the previously listed interrupts. Depending on the device selected, all or some of the interrupts can be individually enabled and disabled. In addition, this feature obtains the status of the interrupts previously mentioned. All of the interrupts belonging to the DMA channel map to the corresponding channel interrupt vector. In general, each channel of the DMA has a dedicated vectored interrupt. Therefore, the ISR for each channel should internally check for the status of the previously mentioned interrupts to respond to the corresponding events. DMA Interrupt Control and Management Each DMA channel has a vectored interrupt. However, each DMA channel internally generates various interrupts, which will invoke the same channel interrupt based on various events. This feature helps to enable/disable them and is also used to obtain the interrupt status. Example: // Enable the channel-3 source done interrupt PLIB_DMA_ChannelXINTSourceEnable ( DMA_ID_0, DMA_CHANNEL_3, DMA_INT_SOURCE_DONE ); // Get the status of address error on channel-3 if(PLIB_DMA_ChannelXINTSourceFlagGet ( DMA_ID_0, DMA_CHANNEL_3, DMA_INT_ADDRESS_ERROR )) { // application code for error handling } // Disable the channel abort interrupt PLIB_DMA_ChannelXINTSourceDisable (DMA_ID_0, DMA_CHANNEL_3, DMA_INT_TRANSFER_ABORT); 5.6.6.4.3.5 Operating/Addressing Mode Management DMA Operating Modes The various operating/transfer modes supported are: • One-Shot mode 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1739 • Repeated One-Shot mode • Continuous mode • Repeated Continuous mode • Ping-Pong mode • Null Data Write mode One-Shot Mode In One-Shot mode, a single transfer is performed for each trigger event. The trigger event can be synchronous (refer to Transfer/Abort (Synchronous) or asynchronous (refer to Transfer/Abort (Asynchronous) Trigger Management). When a single one-shot transfer occurs and the DMA count is decremented to zero, this disables the channel and requires the channel to be re-enabled to perform the next transaction. Repeated One-Shot Mode In Repeated One-Shot mode, single transfers occurs repeatedly so long as triggers are being provided. When the DMA count reaches zero, the channel is not disabled as in One-Shot mode, but the count is reloaded and transfers begin again. Continuous Mode In Continuous mode, a single trigger starts a sequence of back-to-back transfers. These continue with each transfer decrementing the DMA count until it reaches zero. At this point, and like one-shot mode, the channel is disabled. Repeated Continuous Mode This mode can be seen as a combination of Continuous and Repeated One-Shot modes. Data transfers keep occurring so as long as triggers are provided and multiple transfers can occur with each trigger. When the DMA count reaches zero, the address and data registers are reloaded and the process is repeated. Ping-Pong Mode Certain devices support Ping-Pong mode, which allows the CPU to process one buffer while a second buffer operates with the DMA channel. The net result is that the CPU has the entire DMA block transfer time to process the buffer that is currently not being used by the DMA channel. The following figure demonstrates the data flow for four DMA transactions using Ping-Pong mode. Figure: Ping-Pong Mode When the DMA is filling buffer-B, the CPU can process buffer-A and vice-versa. Ping-Pong mode can be combined with One-Shot and Continuous modes (previously discussed) to create other combinations. Null Data Write Mode A DMA transfer operates only in one direction from the source address to the destination address. However, some communication protocols require symmetrical buffer accesses, meaning that for every read operation performed on a buffer, there must be an accompanying write operation. The Null Write mode is designed to satisfy this requirement. This mode works 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1740 by transferring data from the source to the destination like any other DMA operation. Once this is done, the transferred data still with the DMA buffer is written back to the source. DMA Addressing Modes The addressing modes can be broadly classified into the following categories: • Register Indirect with Post Increment Addressing mode • Register Indirect without Post Increment Addressing mode • Source/destination increment based on size • Source/destination decrement based on size • Peripheral Indirect Addressing mode Register Indirect With Post Increment Addressing Mode In this mode, the source data address is incremented by one location after each DMA transaction. The starting address is provided by a start address offset register. Register Indirect Without Post Increment Addressing Mode In this mode, the source data address is not updated after each DMA transaction. Therefore, the next DMA transfer is initiated from the same RAM address. The starting address is provided by a start address offset register. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1741 Figure: Register Indirect Addressing with and without post-increment. Source/Destination Increment Based on Size After each DMA transaction, the source/destination (a separate configuration exist for each) address increments by the size of data (word/byte) configured. Source/Destination Decrement Based on Size After each DMA transaction, the source/destination (a separate configuration exist for each) address decrements by the size of data (word/byte) configured. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1742 Peripheral Indirect Addressing Mode Peripheral Indirect Addressing (PIA) is a special auto-incrementing mode for the transfer of data to and from a multi-level peripheral buffer. This mode is only available for specific peripherals designed with its use in mind. Refer to the specific device data sheet to determine availability of this mode. PIA-capable peripherals - When selected, the PIA-enabled peripheral generates a short Indirect Address (IA) (size defined by the peripheral) to the DMA channel. The IA is logically ORed with either the contents of the source address or the destination address to define a specific address for the peripheral inside the DMA address space. DMA Operating/Transfer Modes: Refer to Operating/Addressing Mode Management for descriptions of the available operating modes. The following code demonstrates usage of Continuous mode. Example: // Enable the DMA PLIB_DMA_Enable ( DMA_ID_0 ); // disable the selected channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3); // program the source and destination addresses // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); // Set the transfer count to 100. PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // set the data transfer mode to one-shot PLIB_DMA_ChannelXOperatingTransferModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_MODE_CONTINUOUS ); // select the source addressing mode PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); // select the destination addressing mode PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE ); // Enable the channel PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Initiate the transfer PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); DMA Addressing Modes: DMA addressing modes can be selected by using following code snippet. DMA Addressing mode Example: // set the source address to increment upon each transfer PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); // Set the destination address to decrement upon each transfer PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE ); 5.6.6.4.3.6 Channel Management Each Channel in the DMA module is can be independently configured for a specific transaction with different properties. The following aspects of the channel can be configured using this feature. DMA Channel Enable/Disable Each channel can be enabled or disabled to control the transactions on the channel. A DMA transfer can only occur when the 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1743 channel is enabled. A DMA channel can be enabled using the PLIB_DMA_ChannelXEnable Function. When a channel is disabled by calling the PLIB_DMA_ChannelXDisable Function function, no data transfers can occur on the channel. DMA Channel Priority The DMA module has a natural priority associated with each of the channels. Channel 0 has the highest priority. Each DMA channel can be assigned priority. This priority scheme changes depending on the device selected. There are three ways in which priorities are assigned in PIC microcontrollers. In the first method, two bits are allocated for each channel for priority. Therefore, priorities 0 to 3 can be assigned to channels. The second is called round-robin. In this method, the module starts by giving Channel 0 preference in any data transfer conflicts. For each successive transfer conflict, the next higher channel receives preference, continuing as a cycle through all the channels. The third method is called fixed scheme, which always gives priority to the lowest requesting channel number. The channel priority can be set using the PLIB_DMA_ChannelPrioritySelect Function or the PLIB_DMA_ChannelXPrioritySelect Function depending on the device selected. DMA Channel Chaining Channel chaining is an enhancement to the DMA channel operation. A channel (slave channel) can be chained to an adjacent channel (master channel). The slave channel will be enabled when a block transfer of the master channel completes. At this point, any event on the slave channel will initiate a DMA transfer. If the channel has an event pending, a DMA transfer will begin immediately. The channel chaining can be enabled or disabled using the PLIB_DMA_ChannelXChainEnable Function and the PLIB_DMA_ChannelXChainDisable Function, respectively. The channel chaining higher/lower channel number can be configured using the PLIB_DMA_ChannelXChainToHigher Function and the PLIB_DMA_ChannelXChainToLower Function. DMA Channel Transfer Direction Each DMA transfer will have a direction. It can be memory to peripheral, peripheral to memory, or memory to memory. This can be set using the PLIB_DMA_ChannelXTransferDirectionSelect Function. DMA Channel Pattern Data On supported devices, a DMA transfer can be aborted by a pattern match (refer to Transfer/Abort (Asynchronous) Trigger Management). The pattern data is per channel basis. It can be set using the PLIB_DMA_ChannelXPatternDataSet Function. Channel Auto Enable This feature can be used to keep the channel active even if a block transfer or pattern match occurs. This mode is useful for applications that do repeated pattern matching. To enable this feature use the PLIB_DMA_ChannelXAutoEnable Function. To disable this feature use the PLIB_DMA_ChannelXAutoDisable Function. DMA Channel Configuration The following example configures DMA Channel 3 by setting its priority to two, enabling the auto-enable feature (refer to Channel Management section), enabling the channel chain feature and chaining Channel 3 and Channel 2, and finally enabling Channel 3. Example: // Disable the channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // set the channel priority to 2 PLIB_DMA_ChannelXPrioritySelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_PRIORITY_2 ); // Configure the channel auto enable feature PLIB_DMA_ChannelXAutoEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Enable the channel chain feature PLIB_DMA_ChannelXChainEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // chain channel 3 to channel 2 PLIB_DMA_ChannelXChainToLower ( DMA_ID_0, DMA_CHANNEL_3 ); // Enable channel-3 PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); In some devices it is required to select the DMA transfer direction before initiating DMA transfer. This can be done using the 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1744 following code. Example: // Disable channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // Set the data transfer direction from memory to peripheral PLIB_DMA_ChannelXTransferDirectionSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL ); // we can also check the current channels transfer direction // check the data transfer direction if ( DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY == PLIB_DMA_ChannelXTransferDirectionGet ( DMA_ID_0, DMA_CHANNEL_3 ) ) { // application code } 5.6.6.4.3.7 Source/Destination/Peripheral Address Management This topic describes configuring the source/destination/peripheral addresses involved in the DMA transfer. Source/Destination Start Address Before initiating a DMA transfer, the channel should be programmed with the source and the destination addresses. In supported devices, this can be done using the PLIB_DMA_ChannelXSourceStartAddressSet Function and the PLIB_DMA_ChannelXDestinationStartAddressSet Function, respectively. At any point, the programmed addresses can be read using the PLIB_DMA_ChannelXSourceStartAddressGet Function and the PLIB_DMA_ChannelXDestinationStartAddressGet Function. Source/Destination Start Address Offset In some devices, a dedicated region of RAM is allocated for DMA transfers typically called DMA RAM. For any DMA transfer, the source or destination address needs to be defined as an offset from the starting of the DMA RAM for such devices. Use the PLIB_DMA_ChannelXStartAddressOffsetSet Function to set the offset addresses of buffers A and B. Buffers A and B are used in Ping-Pong mode. To learn more, refer to Operating/Addressing Mode Management. Peripheral Address When DMA is used for a peripheral to memory or a memory to peripheral transfer, the peripheral address within a register must be set. This register needs to be programmed with the peripheral location where data transfers takes place. For example this can be the I2C buffer Special Function Register (SFR) location or the UART Receive register, etc. To set the peripheral address use the PLIB_DMA_ChannelXPeripheralAddressSet Function. DMA Source/Destination/Peripheral Address Control The first step in initiating a DMA transfer is to set the source and destination addresses. The following example sets the source address and the destination address for Channel 3. Example: // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); On certain devices, the source starting address needs to be given as an offset from the start of the DMA RAM address (in such devices, only memory to peripheral transfers and vice-versa are possible). In such devices, the source start address is set using the PLIB_DMA_ChannelXStartAddressOffsetSet function, as shown in the following code. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1745 Example: // Set the offset-A register to 0x1000 PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000, DMA_ADDRESS_OFFSET_PRIMARY); // If ping-pong mode is enabled we will make use of buffer-B, and in that case // we need to set an address for that also // Set the offset-B to 0x2000 PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000, DMA_ADDRESS_OFFSET_SECONDARY); The following example sets the peripheral address when the DMA needs to be initiated between memory and peripheral. DMA Peripheral Address Set Example: // Set the peripheral address to ADC1 buffer for channel-3 transfers. PLIB_DMA_ChannelXPeripheralAddressSet ( DMA_ID_0, DMA_CHANNEL_3, (volatile uint16_t)(&ADC1BUF0)); There are also equivalent functions available within this library that read the source/destination/peripheral address set. 5.6.6.4.3.8 Source/Destination/Peripheral Data Management This topic describes the data configuration. Source/Destination Transfer Size Configuration In supported devices, each channel can be programmed to read a particular sized data from a source, and write in a particular size to a destination. Both the source and destination sizes are configurable. Use the PLIB_DMA_ChannelXSourceSizeSet Function and the PLIB_DMA_ChannelXDestinationSizeSet Function for read size and write size configuration, respectively. For example, the source size can be 200 bytes and the destination size can be 100 bytes. However, it is logical to have both set to the same value. In some devices, the amount of data that needs to be transferred is independent of the source and destination, and is called transfer count. In such devices use the PLIB_DMA_ChannelXTransferCountSet Function to set the total amount of data (block transfer data). Cell Size Configuration In supported devices, when DMA transfer is initiated, the amount of data configured for a cell transfer will be delivered to the destination per trigger. This can be configured using the PLIB_DMA_ChannelXCellSizeSet Function. Channel Data Size The DMA controller can handle both byte and word (16-bit) transactions. Each DMA channel is individually configurable for the data size using the PLIB_DMA_ChannelXDataSizeSelect Function. Source/Destination Pointer Read In supported devices, the application can read the byte in source/destination to which the DMA core is currently pointing. This can be done using the PLIB_DMA_ChannelXSourcePointer Function and the PLIB_DMA_ChannelXDestinationPointer Function for source and destination, respectively. DMA Source/Destination/Peripheral Data Control After setting the source/destination address the amount of data that needs to be transferred is set in a DMA operation. However, prior to that the data transaction type (byte/word) needs to be configured on certain devices. Example: // Set channel-3 transactions as byte transactions PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_DATA_8 ); // Set channel-3 transactions as 16-bit transactions 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1746 PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_DATA_16 ); // Get the current data size configured if( DMA_CHANNEL_BYTE == PLIB_DMA_ChannelXDataSizeGet ( DMA_ID_0, DMA_CHANNEL_3 )) { // application code } Example: // Set the transfer count to 100. PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); Some high-end microcontrollers (especially PIC32 devices) use the method of cell transfer and block transfer. A cell transfer is the amount of data a DMA channel transfers per an event. In such microcontrollers the application can configure the sizes of the source and destination (per channel basis). A block transfer is defined as the number of bytes transferred when a channel is enabled. A block transfer is comprised of several cell transfers. For example, if the source and destination size is 100 and the cell size is 10, it will take 10 cell transfers to complete the block transfer, which is 100 bytes (larger of source or destination sizes). DMA cell transfer configuration Example: // Set the source size to be 100 PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set the destination size to be 100 PLIB_DMA_ChannelXDestinationSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set the cell size to be 10 PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 10 ); 5.6.6.4.3.9 Special Function Modules (CRC) Selected high-end devices support a special feature called the CRC generator. Depending on the device, the is a highly configurable, 16-bit or 32-bit CRC generator. The CRC can be assigned to any available DMA channel using PLIB_DMA_CRCChannelSelect Function. The CRC is enabled using the PLIB_DMA_CRCEnable Function. Optionally, the data from the source can be subjected to byte reordering using the PLIB_DMA_CRCByteOrderSelect Function. The data is then optionally passed to the Linear Shift Feedback Register (LFSR) CRC or the IP header checksum blocks using the PLIB_DMA_CRCTypeSet Function. The CRC feature is attached to a channel in one of two possible modes, Background or Append. Background Mode The CRC is calculated in the background, with normal DMA behavior maintained. This can be selected by disabling the Append mode. Append Mode Data read from the source is not written to the destination, but the CRC data is accumulated in the CRC data register. The accumulated CRC is written to the location specified by the destination address when a block transfer completes. This mode is enabled by the PLIB_DMA_CRCAppendModeEnable Function. The following code shows DMA CRC calculation in Append mode. Example: // CRC of the Flash block uint32_t blockCRC; bool error = false; // disable the channel 0 interrupts using the Interrupts Peripheral Library // Enable the DMA controller PLIB_DMA_Enable ( DMA_ID_0 ); // disable the selected channel-3 PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_3 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1747 // set the channel priority to 2 PLIB_DMA_ChannelXPrioritySelect ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_PRIORITY_2 ); // Configure the channel auto enable feature PLIB_DMA_ChannelXAutoEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Disable the channel chain feature PLIB_DMA_ChannelXChainDisable ( DMA_ID_0, DMA_CHANNEL_3 ); // Disable the start IRQ. PLIB_DMA_ChannelXTriggerDisable ( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_TRIGGER_TRANSFER_START ); // Seed the CRC generator PLIB_DMA_CRCDataWrite ( DMA_ID_0, 0xFFFF ); // use the standard CCITT CRC 16 polynomial : X^16+X^12+X^5+1 PLIB_DMA_CRCXOREnableSet ( DMA_ID_0, 0x1021 ); // set polynomial length to 16 PLIB_DMA_CRCPolynomialLengthSet (DMA_ID_0, 16); // Enable append mode PLIB_DMA_CRCAppendModeEnable ( DMA_ID_0 ); // Attach CRC to DMA channel-3 PLIB_DMA_CRCChannelSelect (DMA_ID_0, DMA_CHANNEL_3); // Enable the CRC PLIB_DMA_CRCEnable ( DMA_ID_0 ); // Set the source starting address to 0x1000 PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x1000 ); // Set the destination starting address to 0x2000 PLIB_DMA_ChannelXDestinationStartAddressSet ( DMA_ID_0, DMA_CHANNEL_3, 0x2000 ); // set source and destination size to 100 PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); PLIB_DMA_ChannelXDestinationSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); // Set cell size to 100 PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, DMA_CHANNEL_3, 100 ); //Enable channel-3 PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_3 ); // Force initiate a transfer PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_3 ); 5.6.6.4.3.10 Status (including Channel) This module gives application access to various DMA and channel status information. 5.6.6.5 Configuring the Library The library is configured for the supported DMA Peripheral Library. 5.6.6.6 Library Interface Data Types and Constants Name Description DMA_ADDRESS_OFFSET_TYPE Lists the possible DMA address offsets. DMA_CHANNEL Lists the possible DMA channels available. DMA_CHANNEL_ADDRESSING_MODE Lists the possible channel addressing modes. DMA_CHANNEL_COLLISION Lists the possible channel collison types. DMA_CHANNEL_DATA_SIZE Lists the possible data sizes for the DMA channel. DMA_CHANNEL_PRIORITY Lists the possible channel priorities. DMA_CHANNEL_TRANSFER_DIRECTION Lists the possible data transfer directions. DMA_CHANNEL_TRIGGER_TYPE Lists the possible DMA channel triggers. DMA_CRC_BIT_ORDER Lists the possible CRC caluculation bit orders 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1748 DMA_CRC_BYTE_ORDER Lists the possible byte orders. DMA_CRC_TYPE Lists the possible checksums. DMA_DESTINATION_ADDRESSING_MODE Lists the possible destination addressing modes. DMA_INT_TYPE Lists the possible Interrupt types for a particular channel-X DMA_MODULE_ID Possible instances of the DMA module. DMA_PATTERN_LENGTH Gives the DMA pattern length DMA_PING_PONG_MODE Lists the possible ping-pong modes. DMA_SOURCE_ADDRESSING_MODE Lists the possible source addressing modes. DMA_TRANSFER_MODE Lists the possible DMA transfer/operating modes. DMA_TRIGGER_SOURCE Lists the possible DMA trigger sources. DMA Channel Configuration Name Description PLIB_DMA_ChannelPrioritySelect Sets the priority scheme of the DMA channels. PLIB_DMA_ChannelPriorityGet Gets the priority scheme of the DMA channels. PLIB_DMA_ChannelXAutoDisable Channel is disabled after a block transfer is complete. PLIB_DMA_ChannelXAutoEnable Channel is continuously enabled. PLIB_DMA_ChannelXBusyActiveSet Sets the Busy bit to active. PLIB_DMA_ChannelXBusyInActiveSet Sets the Busy bit to inactive. PLIB_DMA_ChannelXChainDisable Disables the channel chaining for the specified DMA channel. PLIB_DMA_ChannelXChainEnable Channel chain feature is enabled. PLIB_DMA_ChannelXChainToHigher Chains the specified channel to a channel higher in natural priority. PLIB_DMA_ChannelXChainToLower Chains the specified channel to a channel lower in natural priority. PLIB_DMA_ChannelXDisable Disable the specified channel. PLIB_DMA_ChannelXEnable Enable the specified channel. PLIB_DMA_ChannelXPriorityGet Gets the priority of the specified channel. PLIB_DMA_ChannelXPrioritySelect Sets the priority of the specified channel. PLIB_DMA_ChannelXTransferDirectionGet Returns the data transfer direction of the specified channel. PLIB_DMA_ChannelXTransferDirectionSelect Selects the data transfer direction of the specified channel. PLIB_DMA_ChannelXDisabledDisablesEvents Channel start/abort events will be ignored even if the channel is disabled. PLIB_DMA_ChannelXDisabledEnablesEvents Channel start/abort events will be registered even if the channel is disabled. PLIB_DMA_ChannelXPatternIgnoreByteDisable Disables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteEnable Enables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Returns the state of the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreGet Returns the pattern match ignore value. PLIB_DMA_ChannelXPatternIgnoreSet Sets the pattern match ignore value. PLIB_DMA_ChannelXPatternLengthGet Returns the pattern match length. PLIB_DMA_ChannelXPatternLengthSet Sets the pattern match length. DMA Channel Status Routines Name Description PLIB_DMA_ChannelXAutoIsEnabled Returns the channel automatic enable status. PLIB_DMA_ChannelXBufferedDataIsWritten Returns the buffered data write status for the specified channel. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1749 PLIB_DMA_ChannelXBusyIsBusy Returns the busy status of the specified channel. PLIB_DMA_ChannelXChainIsEnabled Returns the chain status of the specified channel. PLIB_DMA_ChannelXCollisionStatus Returns the status of the specified collison type for the specified channel. PLIB_DMA_ChannelXEventIsDetected Returns the event status on the specified channel. PLIB_DMA_ChannelXIsEnabled Return the enable status of the specified channel. PLIB_DMA_ChannelXNullWriteModeIsEnabled Returns the enable status of the Null Write mode for the specified channel. PLIB_DMA_ChannelXPingPongModeGet Returns the Ping-Pong mode status for the specified channel. PLIB_DMA_ChannelBitsGet Returns the DMA channel bits. DMA CRC Module Interface Routines Name Description PLIB_DMA_CRCAppendModeDisable Disables the CRC append mode. PLIB_DMA_CRCAppendModeEnable Enables the CRC append mode. PLIB_DMA_CRCAppendModeIsEnabled Gets the enable status of the CRC append mode. PLIB_DMA_CRCBitOrderSelect Selects the bit order for checksum caluculation. PLIB_DMA_CRCByteOrderGet Gets the current byte order selected by the DMA module CRC feature. PLIB_DMA_CRCByteOrderSelect Selects the byte order. PLIB_DMA_CRCChannelGet Returns the current DMA channel to which the CRC is assigned. PLIB_DMA_CRCChannelSelect Assignes the CRC to the specified DMA channel. PLIB_DMA_CRCDataRead Reads the contents of the DMA CRC data register. PLIB_DMA_CRCDataWrite Writes the contents of the DMA CRC data register with the specified data. PLIB_DMA_CRCDisable Disables the DMA module CRC feature. PLIB_DMA_CRCEnable Enables the DMA module CRC feature. PLIB_DMA_CRCPolynomialLengthGet Gets the current polynomial length. PLIB_DMA_CRCPolynomialLengthSet Selects the polynomial length. PLIB_DMA_CRCTypeGet Gets the current DMA module CRC feature type. PLIB_DMA_CRCTypeSet Selects the DMA module CRC feature type. PLIB_DMA_CRCWriteByteOrderAlter The source data is written to the destination reordered as defined by the BYTO<1:0> bits. PLIB_DMA_CRCWriteByteOrderMaintain The source data is written to the destination unaltered. PLIB_DMA_CRCXOREnableGet Reads the CRC XOR register. PLIB_DMA_CRCXOREnableSet Writes to the CRC XOR enable register as per the specified enable mask. DMA General Configuration Routines Name Description PLIB_DMA_BusyActiveReset Resets the BUSY bit of the DMA controller. PLIB_DMA_BusyActiveSet Sets the BUSY bit of the DMA controller. PLIB_DMA_Disable DMA module is disabled. PLIB_DMA_Enable DMA module is enabled. PLIB_DMA_StopInIdleDisable DMA transfers continue during Idle mode. PLIB_DMA_StopInIdleEnable DMA transfers are halted during Idle mode. PLIB_DMA_SuspendDisable DMA suspend is disabled and the DMA module operates normally. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1750 PLIB_DMA_SuspendEnable DMA transfers are suspended to allow uninterrupted access by the CPU to the data bus. DMA Global Status Routines Name Description PLIB_DMA_CRCIsEnabled Gets the enable status of the CRC feature. PLIB_DMA_IsBusy Gets the BUSY bit of the DMA controller. PLIB_DMA_IsEnabled Returns the DMA module enable status. PLIB_DMA_LastBusAccessIsRead Returns true if the last DMA bus access was a read. PLIB_DMA_LastBusAccessIsWrite Returns true if the last DMA bus access was a write. PLIB_DMA_LastChannelActive Returns the last DMA channel that participated in the data transfer. PLIB_DMA_RecentAddressAccessed Returns the address of the most recent DMA access. PLIB_DMA_SuspendIsEnabled Returns the DMA suspend status. DMA Interrupt Control and Management Name Description PLIB_DMA_ChannelXINTSourceDisable Disables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceEnable Enables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagClear Clears the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagGet Returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagSet Sets the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceIsEnabled Returns the enable status of the specified interrupt source for the specified channel. DMA Operating/Addressing Mode Configuration Name Description PLIB_DMA_ChannelXAddressModeGet Gets the channel address mode. PLIB_DMA_ChannelXAddressModeSelect Sets the channel address mode. PLIB_DMA_ChannelXDestinationAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXDestinationAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXNullWriteModeDisable Disables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeEnable Enables the Null Write mode. PLIB_DMA_ChannelXOperatingTransferModeGet Returns the current transfer/operating mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeSelect Selects the transfer/operating mode for the specified channel. PLIB_DMA_ChannelXReloadDisable Disables reloading of the address and count registers. PLIB_DMA_ChannelXReloadEnable Enables reloading of the address and count registers. PLIB_DMA_ChannelXSourceAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXSourceAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXReloadIsEnabled Returns the address and count registers reload enable status. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1751 DMA Source/Destination/Peripheral Address Control Interface Routines Name Description PLIB_DMA_ChannelXDestinationStartAddressGet Reads the destination start address configured for the specified channel. PLIB_DMA_ChannelXDestinationStartAddressSet Writes the specified destination start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXPeripheralAddressGet Gets the peripheral address configured for the specified channel. PLIB_DMA_ChannelXPeripheralAddressSet Sets the peripheral address for the specified channel. PLIB_DMA_ChannelXSourceStartAddressGet Reads the source start address configured for the specified channel. PLIB_DMA_ChannelXSourceStartAddressSet Writes the specified source start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXStartAddressOffsetGet Gets the primary/secondary start address (DPSRAM) offset. PLIB_DMA_ChannelXStartAddressOffsetSet Sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. DMA Source/Destination/Peripheral Data Management Name Description PLIB_DMA_ChannelXCellProgressPointerGet Returns the number of bytes transferred since the last event. PLIB_DMA_ChannelXCellSizeGet Reads the cell size (in bytes) configured for the specified channel. PLIB_DMA_ChannelXCellSizeSet Writes the specified cell size into the register corresponding to the specified channel. PLIB_DMA_ChannelXDataSizeGet Returns the current data size for the specified channel. PLIB_DMA_ChannelXDataSizeSelect Selects the data size for the specified channel. PLIB_DMA_ChannelXDestinationPointerGet Reads the current byte of the destination being pointed to for the specified channel. PLIB_DMA_ChannelXDestinationSizeGet Reads the destination size configured for the specified channel. PLIB_DMA_ChannelXDestinationSizeSet Writes the specified destination size into the register corresponding to the specified channel. PLIB_DMA_ChannelXPatternDataGet Returns the pattern matching (for DMA abort) data programmed for the specified channel. PLIB_DMA_ChannelXPatternDataSet Writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. PLIB_DMA_ChannelXSourcePointerGet Reads the current byte of the source being pointed to for the specified channel. PLIB_DMA_ChannelXSourceSizeGet Reads the source size configured for the specified channel. PLIB_DMA_ChannelXSourceSizeSet Writes the specified source size into the register corresponding to the specified channel. PLIB_DMA_ChannelXTransferCountGet Gets the DMA data transfer count that is programmed for the specified channel. PLIB_DMA_ChannelXTransferCountSet Sets the DMA data transfer count for the specified channel. DMA Transfer/Abort (Asynchronous) Trigger Management Name Description PLIB_DMA_ChannelXAbortIRQSet Sets the IRQ to abort the DMA transfer on the specified channel. PLIB_DMA_ChannelXStartIRQSet Sets the IRQ to initiate the DMA transfer on the specified channel. PLIB_DMA_ChannelXTriggerDisable Disables the DMA transfer abort via a matching interrupt (specified by the IRQ). 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1752 PLIB_DMA_ChannelXTriggerEnable Enables the specified DMA channel trigger. PLIB_DMA_ChannelXTriggerIsEnabled Returns the enable status of the specified DMA transfer/abort trigger. DMA Transfer/Abort (Synchronous) Name Description PLIB_DMA_AbortTransferSet Aborts transfer on the specified channel. PLIB_DMA_StartTransferSet Initiates transfer on the specified channel. Feature Existence Routines Name Description PLIB_DMA_ExistsAbortTransfer Identifies whether the AbortTransfer feature exists on the DMA module. PLIB_DMA_ExistsBusy Identifies whether the Busy feature exists on the DMA module. PLIB_DMA_ExistsChannelBits Identifies whether the ChannelBits feature exists on the DMA module. PLIB_DMA_ExistsChannelX Identifies whether the ChannelX feature exists on the DMA module. PLIB_DMA_ExistsChannelXAbortIRQ Identifies whether the ChannelXAbortIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXAuto Identifies whether the ChannelXAuto feature exists on the DMA module. PLIB_DMA_ExistsChannelXBusy Identifies whether the ChannelXBusy feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellProgressPointer Identifies whether the ChannelXCellProgressPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellSize Identifies whether the ChannelXCellSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXChain Identifies whether the ChannelXChain feature exists on the DMA module. PLIB_DMA_ExistsChannelXChainEnbl Identifies whether the ChannelXChainEnbl feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationPointer Identifies whether the ChannelXDestinationPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationSize Identifies whether the ChannelXDestinationSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationStartAddress Identifies whether the ChannelXDestinationStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXDisabled Identifies whether the ChannelXDisabled feature exists on the DMA module. PLIB_DMA_ExistsChannelXEvent Identifies whether the ChannelXEvent feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSource Identifies whether the ChannelXINTSource feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSourceFlag Identifies whether the ChannelXINTSourceFlag feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternData Identifies whether the ChannelXPatternData feature exists on the DMA module PLIB_DMA_ExistsChannelXPatternIgnore Identifies whether the ChannelXPatternIgnore feature exists on the DMA module. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1753 PLIB_DMA_ExistsChannelXPatternIgnoreByte Identifies whether the ChannelXPatternIgnoreByte feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternLength Identifies whether the ChannelXPatternLength feature exists on the DMA module. PLIB_DMA_ExistsChannelXPriority Identifies whether the ChannelXPriority feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourcePointer Identifies whether the ChannelXSourcePointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceSize Identifies whether the ChannelXSourceSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceStartAddress Identifies whether the ChannelXSourceStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXStartIRQ Identifies whether the ChannelXStartIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXTrigger Identifies whether the ChannelXTrigger feature exists on the DMA module. PLIB_DMA_ExistsCRC Identifies whether the CRC feature exists on the DMA module. PLIB_DMA_ExistsCRCAppendMode Identifies whether the CRCAppendMode feature exists on the DMA module. PLIB_DMA_ExistsCRCBitOrder Identifies whether the CRCBitOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCByteOrder Identifies whether the CRCByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCChannel Identifies whether the CRCChannel feature exists on the DMA module. PLIB_DMA_ExistsCRCData Identifies whether the CRCData feature exists on the DMA module. PLIB_DMA_ExistsCRCPolynomialLength Identifies whether the CRCPolynomialLength feature exists on the DMA module. PLIB_DMA_ExistsCRCType Identifies whether the CRCType feature exists on the DMA module. PLIB_DMA_ExistsCRCWriteByteOrder Identifies whether the CRCWriteByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCXOREnable Identifies whether the CRCXOREnable feature exists on the DMA module. PLIB_DMA_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMA module. PLIB_DMA_ExistsLastBusAccess Identifies whether the LastBusAccess feature exists on the DMA module. PLIB_DMA_ExistsRecentAddress Identifies whether the RecentAddress feature exists on the DMA module. PLIB_DMA_ExistsStartTransfer Identifies whether the StartTransfer feature exists on the DMA module. PLIB_DMA_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the DMA module. PLIB_DMA_ExistsSuspend Identifies whether the Suspend feature exists on the DMA module. Description This topic describes the functions of the DMA Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1754 Refer to each topic for a detailed description. 5.6.6.6.1 DMA General Configuration Routines 5.6.6.6.1.1 PLIB_DMA_BusyActiveReset Function C void PLIB_DMA_BusyActiveReset( DMA_MODULE_ID index ); Description This function resets the BUSY bit of the DMA controller. The DMA module is disabled and is not actively transferring data. Preconditions None. Returns None. Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Example PLIB_DMA_BusyActiveReset( DMA_ID_0 ); 5.6.6.6.1.2 PLIB_DMA_BusyActiveSet Function C void PLIB_DMA_BusyActiveSet( DMA_MODULE_ID index ); Description This function sets the BUSY bit of the DMA controller. The DMA module is active. Preconditions None. Returns None. Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Example PLIB_DMA_BusyActiveSet( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1755 5.6.6.6.1.3 PLIB_DMA_Disable Function C void PLIB_DMA_Disable( DMA_MODULE_ID index ); Description This function disables the DMA module. Preconditions None. Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Example PLIB_DMA_Disable( DMA_ID_0 ); 5.6.6.6.1.4 PLIB_DMA_Enable Function C void PLIB_DMA_Enable( DMA_MODULE_ID index ); Description This function enables the DMA module. Preconditions None. Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Example PLIB_DMA_Enable( DMA_ID_0 ); 5.6.6.6.1.5 PLIB_DMA_StopInIdleDisable Function C void PLIB_DMA_StopInIdleDisable( DMA_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1756 Description This function causes DMA transfers to continue during Idle mode. Preconditions None. Returns None. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStopInIdle function in your application to automatically determine whether this feature is available. Example PLIB_DMA_StopInIdleDisable( DMA_ID_0 ); 5.6.6.6.1.6 PLIB_DMA_StopInIdleEnable Function C void PLIB_DMA_StopInIdleEnable( DMA_MODULE_ID index ); Description This function halts DMA transfers during Idle mode. Preconditions None. Returns None. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStopInIdle function in your application to automatically determine whether this feature is available. Example PLIB_DMA_StopInIdleEnable( DMA_ID_0 ); 5.6.6.6.1.7 PLIB_DMA_SuspendDisable Function C void PLIB_DMA_SuspendDisable( DMA_MODULE_ID index ); Description This function disables the DMA suspend. The DMA module continues to operate normally. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1757 Returns None. Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Example PLIB_DMA_SuspendDisable( DMA_ID_0 ); 5.6.6.6.1.8 PLIB_DMA_SuspendEnable Function C void PLIB_DMA_SuspendEnable( DMA_MODULE_ID index ); Description This function suspends the DMA transfers to allow uninterrupted access by the CPU to the data bus. Preconditions None. Returns None. Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Example PLIB_DMA_SuspendEnable( DMA_ID_0 ); 5.6.6.6.2 DMA Transfer/Abort (Synchronous) 5.6.6.6.2.1 PLIB_DMA_AbortTransferSet Function C void PLIB_DMA_AbortTransferSet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function aborts transfer on the specified channel. This is a forced abort controlled via software. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1758 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the AbortTransfer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsAbortTransfer function in your application to automatically determine whether this feature is available. Example PLIB_DMA_AbortTransferSet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.2.2 PLIB_DMA_StartTransferSet Function C void PLIB_DMA_StartTransferSet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function initiates transfer on the specified channel. This is a forced transfer controlled via software. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the StartTransfer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsStartTransfer function in your application to automatically determine whether this feature is available. Example PLIB_DMA_StartTransferSet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.3 DMA Transfer/Abort (Asynchronous) Trigger Management 5.6.6.6.3.1 PLIB_DMA_ChannelXAbortIRQSet Function C void PLIB_DMA_ChannelXAbortIRQSet( DMA_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1759 DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQ ); Description This function sets the IRQ to abort the DMA transfer on the specified channel. (IRQ to start the channel transfer.) Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL IRQnum The IRQ number of the trigger source of type DMA_TRIGGER_SOURCE Returns None. Remarks This function implements an operation of the ChannelXAbortIRQ feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAbortIRQ function in your application to automatically determine whether this feature is available. Example DMA_TRIGGER_SOURCE irq = DMA_TRIGGER_TIMER_CORE; PLIB_DMA_ChannelXAbortIRQSet ( DMA_ID_0, DMA_CHANNEL_4, irq ); 5.6.6.6.3.2 PLIB_DMA_ChannelXStartIRQSet Function C void PLIB_DMA_ChannelXStartIRQSet( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRIGGER_SOURCE IRQnum ); Description This function sets the IRQ to initiate the DMA transfer on the specified channel. (IRQ to start the channel transfer.) Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL IRQnum The IRQ number of the trigger source of type DMA_TRIGGER_SOURCE Returns None. Remarks This function implements an operation of the ChannelXStartIRQ feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXStartIRQ function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1760 Example //This code is for PIC24F family DMA_TRIGGER_SOURCE irq = DMA_TRIGGER_OUTPUT_COMPARE_1; PLIB_DMA_ChannelXStartIRQSet ( DMA_ID_0, DMA_CHANNEL_4, irq ); 5.6.6.6.3.3 PLIB_DMA_ChannelXTriggerDisable Function C void PLIB_DMA_ChannelXTriggerDisable( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ); Description This function disables the DMA transfer abort via a matching interrupt (specified by the IRQ). The interrupt number IRQ is ignored and does not terminate a transfer. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Returns None. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXTriggerDisable ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT ); 5.6.6.6.3.4 PLIB_DMA_ChannelXTriggerEnable Function C void PLIB_DMA_ChannelXTriggerEnable( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ); Description This function enables the the specified DMA channel trigger. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1761 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Returns None. Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXTriggerEnable ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT ); 5.6.6.6.3.5 PLIB_DMA_ChannelXTriggerIsEnabled Function C bool PLIB_DMA_ChannelXTriggerIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRIGGER_TYPE trigger ); Description This function returns the enable status of the specified DMA transfer/abort trigger. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL trigger Type of trigger (transfer start/abort/pattern match abort) Returns • true - The specified trigger is enabled • false - The specified trigger is disabled Remarks This function implements an operation of the ChannelXTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXTrigger function in your application to automatically determine whether this feature is available. Example bool startTriggerstatus; startTriggerstatus = PLIB_DMA_ChannelXTriggerIsEnabled ( DMA_ID_0, DMA_CHANNEL_4, DMA_CHANNEL_TRIGGER_TRANSFER_START ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1762 5.6.6.6.4 DMA Interrupt Control and Management 5.6.6.6.4.1 PLIB_DMA_ChannelXINTSourceDisable Function C void PLIB_DMA_ChannelXINTSourceDisable( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ); Description This function disables the specified interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns None. Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceDisable ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.4.2 PLIB_DMA_ChannelXINTSourceEnable Function C void PLIB_DMA_ChannelXINTSourceEnable( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ); Description This function enables the specified interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1763 dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns None. Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceEnable ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.4.3 PLIB_DMA_ChannelXINTSourceFlagClear Function C void PLIB_DMA_ChannelXINTSourceFlagClear( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ); Description This function clears the interrupt flag of the specified DMA interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns None. Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceFlagClear ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.4.4 PLIB_DMA_ChannelXINTSourceFlagGet Function C bool PLIB_DMA_ChannelXINTSourceFlagGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1764 DMA_INT_TYPE dmaINTSource ); Description This function returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns • true - The interrupt flag is set • false - The interrupt flag is not set Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; bool AddressErrorINTStatus; AddressErrorINTStatus = PLIB_DMA_ChannelXINTSourceFlagGet ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.4.5 PLIB_DMA_ChannelXINTSourceFlagSet Function C void PLIB_DMA_ChannelXINTSourceFlagSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ); Description This function sets the interrupt flag of the specified DMA interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns None. Remarks This function implements an operation of the ChannelXINTSourceFlag feature. This feature may not be available on all devices. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1765 Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSourceFlag function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXINTSourceFlagSet ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.4.6 PLIB_DMA_ChannelXINTSourceIsEnabled Function C bool PLIB_DMA_ChannelXINTSourceIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_INT_TYPE dmaINTSource ); Description This function returns the enable status of the specified interrupt source for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL dmaINTSource One of the DMA interrupt sources specified by DMA_INT_TYPE Returns • true - The interrupt is enabled • false - The interrupt is not enabled Remarks This function implements an operation of the ChannelXINTSource feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXINTSource function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; bool dmaINTSourceEnableStatus; dmaINTSourceEnableStatus = PLIB_DMA_ChannelXINTSourceIsEnabled ( DMA_ID_0, spiDMAChannel, DMA_INT_ADDRESS_ERROR ); 5.6.6.6.5 DMA Operating/Addressing Mode Configuration 5.6.6.6.5.1 PLIB_DMA_ChannelXAddressModeGet Function C DMA_CHANNEL_ADDRESSING_MODE PLIB_DMA_ChannelXAddressModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1766 Description This function gets the channel address mode. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns channelAddressMode - One of the possible source addressing modes listed by DMA_CHANNEL_ADDRESSING_MODE Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_ADDRESSING_MODE channelAddressMode; channelAddressMode = PLIB_DMA_ChannelXAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.2 PLIB_DMA_ChannelXAddressModeSelect Function C void PLIB_DMA_ChannelXAddressModeSelect( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_ADDRESSING_MODE channelAddressMode ); Description This function sets the channel address mode. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channelAddressMode One of the possible channel addressing modes listed by DMA_CHANNEL_ADDRESSING_MODE Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1767 5.6.6.6.5.3 PLIB_DMA_ChannelXDestinationAddressModeGet Function C DMA_DESTINATION_ADDRESSING_MODE PLIB_DMA_ChannelXDestinationAddressModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function gets the source address mode of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns destinationAddressMode - One of the possible source addressing modes listed by DMA_DESTINATION_ADDRESSING_MODE Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_SOURCE_ADDRESSING_MODE destinationAddressMode; destinationAddressMode = PLIB_DMA_ChannelXDestinationAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.4 PLIB_DMA_ChannelXDestinationAddressModeSelect Function C void PLIB_DMA_ChannelXDestinationAddressModeSelect( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_DESTINATION_ADDRESSING_MODE destinationAddressMode ); Description This function Sets the source address mode of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL destinationAddressMode One of the possible source addressing modes listed by DMA_DESTINATION_ADDRESSING_MODE Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1768 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXDestinationAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE ); 5.6.6.6.5.5 PLIB_DMA_ChannelXNullWriteModeDisable Function C void PLIB_DMA_ChannelXNullWriteModeDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function disables the Null Write mode. No dummy write is initiated. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXNullWriteModeDisable ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.6 PLIB_DMA_ChannelXNullWriteModeEnable Function C void PLIB_DMA_ChannelXNullWriteModeEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function enables the Null Write mode. A dummy write is initiated to the source address for every write to the destination address. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1769 Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXNullWriteModeEnable ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.7 PLIB_DMA_ChannelXOperatingTransferModeGet Function C DMA_TRANSFER_MODE PLIB_DMA_ChannelXOperatingTransferModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the current transfer/operating mode for the specified channel. (Transfer mode and operating mode are used interchangably.) Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns channeltransferMode - One of the possible operating/transfer modes listed by DMA_TRANSFER_MODE Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_TRANSFER_MODE channeltransferMode; channeltransferMode = PLIB_DMA_ChannelXOperatingTransferModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.8 PLIB_DMA_ChannelXOperatingTransferModeSelect Function C void PLIB_DMA_ChannelXOperatingTransferModeSelect( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_TRANSFER_MODE channeltransferMode ); Description This function selects the transfer/operating mode for the specified channel. (Transfer mode and operating mode are used interchangably.) Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1770 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channeltransferMode One of the possible operating/transfer modes listed by DMA_TRANSFER_MODE Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_TRANSFER_MODE channeltransferMode = DMA_MODE_REPEATED_CONTINUOUS; PLIB_DMA_ChannelXOperatingTransferModeSelect ( DMA_ID_0, DMA_CHANNEL_4, channeltransferMode ); 5.6.6.6.5.9 PLIB_DMA_ChannelXReloadDisable Function C void PLIB_DMA_ChannelXReloadDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function disables reloading of the address and count registers. The source, destination address, and the DMA count registers are not reloaded to their previous values upon the start of the next operation. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXReloadDisable ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.10 PLIB_DMA_ChannelXReloadEnable Function C void PLIB_DMA_ChannelXReloadEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1771 Description This function enables reloading of the address and count registers. The source, destination address, and the DMA count registers are reloaded to their previous values upon the start of the next operation. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXReloadEnable ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.11 PLIB_DMA_ChannelXSourceAddressModeGet Function C DMA_SOURCE_ADDRESSING_MODE PLIB_DMA_ChannelXSourceAddressModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function gets the source address mode of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns DMA_SOURCE_ADDRESSING_MODE - One of the possible source addressing modes listed by DMA_SOURCE_ADDRESSING_MODE Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_SOURCE_ADDRESSING_MODE sourceAddressMode; sourceAddressMode = PLIB_DMA_ChannelXSourceAddressModeGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.5.12 PLIB_DMA_ChannelXSourceAddressModeSelect Function C void PLIB_DMA_ChannelXSourceAddressModeSelect( 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1772 DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_SOURCE_ADDRESSING_MODE sourceAddressMode ); Description This function sets the source address mode of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL sourceAddressMode One of the possible source addressing modes listed by DMA_SOURCE_ADDRESSING_MODE Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXSourceAddressModeSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE ); 5.6.6.6.5.13 PLIB_DMA_ChannelXReloadIsEnabled Function C bool PLIB_DMA_ChannelXReloadIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the address and count registers reload enable status. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - The address and count registers reload is enabled • false - The address and count registers reload is disabled Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example bool chAddressCountReloadStatus; 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1773 chAddressCountReloadStatus = PLIB_DMA_ChannelXReloadIsEnabled ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.6 DMA Source/Destination/Peripheral Address Control Interface Routines 5.6.6.6.6.1 PLIB_DMA_ChannelXDestinationStartAddressGet Function C uint32_t PLIB_DMA_ChannelXDestinationStartAddressGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the destination start address configured for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint32_t - The destination start address configured for this channel Remarks This function implements an operation of the ChannelXDestinationStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationStartAddress function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t DestinationStartAddress; DestinationStartAddress = PLIB_DMA_ChannelXDestinationStartAddressGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.6.2 PLIB_DMA_ChannelXDestinationStartAddressSet Function C void PLIB_DMA_ChannelXDestinationStartAddressSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t destinationStartAddress ); Description This function writes the specified destination start address into the register corresponding to the specified channel. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1774 Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL destinationStartAddress The destination start address Returns None. Remarks This function implements an operation of the ChannelXDestinationStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationStartAddress function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t destinationStartAddress = 0x00FDEA00; PLIB_DMA_ChannelXDestinationStartAddressSet( DMA_ID_0, spiDMAChannel, destinationStartAddress ); 5.6.6.6.6.3 PLIB_DMA_ChannelXPeripheralAddressGet Function C uint16_t PLIB_DMA_ChannelXPeripheralAddressGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function gets the peripheral address configured for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The peripheral address configured for the specified channel Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t peripheraladdress; peripheraladdress = PLIB_DMA_ChannelXPeripheralAddressGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.6.4 PLIB_DMA_ChannelXPeripheralAddressSet Function C void PLIB_DMA_ChannelXPeripheralAddressSet( DMA_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1775 DMA_CHANNEL channel, uint16_t peripheraladdress ); Description This function sets the peripheral address for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL peripheraladdress The peripheral address for the specified channel Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t peripheraladdress = 0x100; PLIB_DMA_ChannelXPeripheralAddressSet ( DMA_ID_0, DMA_CHANNEL_4, peripheraladdress ); 5.6.6.6.6.5 PLIB_DMA_ChannelXSourceStartAddressGet Function C uint32_t PLIB_DMA_ChannelXSourceStartAddressGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the source start address configured for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint32_t - The source start address configured for this channel Remarks This function implements an operation of the ChannelXSourceStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceStartAddress function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1776 uint32_t SourceStartAddress; SourceStartAddress = PLIB_DMA_ChannelXSourceStartAddressGet(DMA_ID_0, spiDMAChannel ); 5.6.6.6.6.6 PLIB_DMA_ChannelXSourceStartAddressSet Function C void PLIB_DMA_ChannelXSourceStartAddressSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint32_t sourceStartAddress ); Description This function writes the specified Source start address into the register corresponding to the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL sourceStartAddress The source start address Returns None. Remarks This function implements an operation of the ChannelXSourceStartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceStartAddress function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint32_t sourceStartAddress = 0x00FDEA00; PLIB_DMA_ChannelXSourceStartAddressSet ( DMA_ID_0, spiDMAChannel, sourceStartAddress ); 5.6.6.6.6.7 PLIB_DMA_ChannelXStartAddressOffsetGet Function C uint16_t PLIB_DMA_ChannelXStartAddressOffsetGet( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_ADDRESS_OFFSET_TYPE offset ); Description This function gets the primary/secondary start address (DPSRAM) offset. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1777 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL offset The type of the address offset (primary/secondary) Returns uint16_t - The primary/secondary DPSRAM start address offset Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t addressOffsetA; addressOffsetA = PLIB_DMA_ChannelXStartAddressOffsetGet ( DMA_ID_0, DMA_CHANNEL_4, address, DMA_ADDRESS_OFFSET_PRIMARY ); 5.6.6.6.6.8 PLIB_DMA_ChannelXStartAddressOffsetSet Function C void PLIB_DMA_ChannelXStartAddressOffsetSet( DMA_MODULE_ID index, DMA_CHANNEL channel, uint16_t address, DMA_ADDRESS_OFFSET_TYPE offset ); Description This function sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL address The primary/secondary DPSRAM start address offset offset The type of the address offset (primary/secondary) Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t address = 0x100; PLIB_DMA_ChannelXStartAddressOffsetSet ( DMA_ID_0, DMA_CHANNEL_4, address, DMA_ADDRESS_OFFSET_PRIMARY ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1778 5.6.6.6.7 DMA Source/Destination/Peripheral Data Management 5.6.6.6.7.1 PLIB_DMA_ChannelXCellProgressPointerGet Function C uint16_t PLIB_DMA_ChannelXCellProgressPointerGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function returns the number of bytes transferred since the last event. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The number of bytes transferred since the last event. (The cell progress pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXCellProgressPointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellProgressPointer function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t CellProgress; CellProgress = PLIB_DMA_ChannelXCellProgressPointerGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.2 PLIB_DMA_ChannelXCellSizeGet Function C uint16_t PLIB_DMA_ChannelXCellSizeGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the cell size (in bytes) configured for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1779 Returns uint16_t - The cell size configured (in bytes) for this channel (The cell size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXCellSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t cellSize; cellSize = PLIB_DMA_ChannelXCellSizeGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.3 PLIB_DMA_ChannelXCellSizeSet Function C void PLIB_DMA_ChannelXCellSizeSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t CellSize ); Description This function writes the specified cell size into the register corresponding to the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL cellSize The cell size in bytes (The cell size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the ChannelXCellSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXCellSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t cellSize = 0x10; PLIB_DMA_ChannelXCellSizeSet ( DMA_ID_0, spiDMAChannel, cellSize ); 5.6.6.6.7.4 PLIB_DMA_ChannelXDataSizeGet Function C DMA_CHANNEL_DATA_SIZE PLIB_DMA_ChannelXDataSizeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1780 Description This function returns the current data size for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns channelDataSize - One of the possible data sizes listed by DMA_CHANNEL_DATA_SIZE Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_DATA_SIZE channelDataSize; channelDataSize = PLIB_DMA_ChannelXDataSizeGet( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.7.5 PLIB_DMA_ChannelXDataSizeSelect Function C void PLIB_DMA_ChannelXDataSizeSelect( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_DATA_SIZE channelDataSize ); Description This function selects the data size for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL channelDataSize One of the possible data sizes listed by DMA_CHANNEL_DATA_SIZE Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_DATA_SIZE channelDataSize = DMA_CHANNEL_DATA_8; PLIB_DMA_ChannelXDataSizeSelect ( DMA_ID_0, DMA_CHANNEL_4, channelDataSize ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1781 5.6.6.6.7.6 PLIB_DMA_ChannelXDestinationPointerGet Function C uint16_t PLIB_DMA_ChannelXDestinationPointerGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the current byte of the destination being pointed to for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The destination byte being pointed to for this channel (The destination pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXDestinationPointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationPointer function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t destinationbyte; destinationbyte = PLIB_DMA_ChannelXDestinationPointerGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.7 PLIB_DMA_ChannelXDestinationSizeGet Function C uint16_t PLIB_DMA_ChannelXDestinationSizeGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the destination size configured for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The destination size configured (in bytes) for this channel. (The destination size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1782 Remarks This function implements an operation of the ChannelXDestinationSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t DestinationSize; DestinationSize = PLIB_DMA_ChannelXDestinationSizeGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.8 PLIB_DMA_ChannelXDestinationSizeSet Function C void PLIB_DMA_ChannelXDestinationSizeSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t destinationSize ); Description This function writes the specified destination size into the register corresponding to the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL destinationSize The destination size (The destination size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the ChannelXDestinationSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDestinationSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t destinationSize = 0xA00; PLIB_DMA_ChannelXDestinationSizeSet( DMA_ID_0, spiDMAChannel, destinationSize ); 5.6.6.6.7.9 PLIB_DMA_ChannelXPatternDataGet Function C uint16_t PLIB_DMA_ChannelXPatternDataGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function returns pattern matching (for DMA abort) data programmed for the specified channel. (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1783 Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The pattern matching data programmed for the current channel (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXPatternData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternData function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t patternData; patternData = PLIB_DMA_ChannelXPatternDataGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.10 PLIB_DMA_ChannelXPatternDataSet Function C void PLIB_DMA_ChannelXPatternDataSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t patternData ); Description This function writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL patternData The pattern matching DATA programmed for the current channel (The size of pattern matching data(8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the ChannelXPatternData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternData function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1784 Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t patternData = '0'; PLIB_DMA_ChannelXPatternDataSet ( DMA_ID_0, spiDMAChannel, patternData ); 5.6.6.6.7.11 PLIB_DMA_ChannelXSourcePointerGet Function C uint16_t PLIB_DMA_ChannelXSourcePointerGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the current byte of the source being pointed to for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The source byte being pointed to for this channel. (The source pointer (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXSourcePointer feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourcePointer function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourcebyte; sourcebyte = PLIB_DMA_ChannelXSourcePointerGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.12 PLIB_DMA_ChannelXSourceSizeGet Function C uint16_t PLIB_DMA_ChannelXSourceSizeGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function reads the source size configured for the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1785 Returns uint16_t - The Source size configured (in bytes) for this channel. (The source size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the ChannelXSourceSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourceSize; sourceSize = PLIB_DMA_ChannelXSourceSizeGet ( DMA_ID_0, spiDMAChannel ); 5.6.6.6.7.13 PLIB_DMA_ChannelXSourceSizeSet Function C void PLIB_DMA_ChannelXSourceSizeSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, uint16_t sourceSize ); Description This function writes the specified source size into the register corresponding to the specified channel. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL sourceSize The source size (The source size (8-bit, 16-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the ChannelXSourceSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXSourceSize function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL spiDMAChannel = DMA_CHANNEL_2; uint16_t sourceSize = 0xA00; PLIB_DMA_ChannelXSourceSizeSet ( DMA_ID_0, spiDMAChannel, sourceSize ); 5.6.6.6.7.14 PLIB_DMA_ChannelXTransferCountGet Function C uint16_t PLIB_DMA_ChannelXTransferCountGet( DMA_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1786 DMA_CHANNEL channel ); Description This function gets the DMA data transfer count that is programmed for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns uint16_t - The DMA transfer count for the channel Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t transferCount; transferCount = PLIB_DMA_ChannelXTransferCountGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.7.15 PLIB_DMA_ChannelXTransferCountSet Function C void PLIB_DMA_ChannelXTransferCountSet( DMA_MODULE_ID index, DMA_CHANNEL channel, uint16_t transferCount ); Description This function sets the DMA data transfer count for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL transferCount The DMA transfer count for the channel Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example uint16_t transferCount = 0x10; PLIB_DMA_ChannelXTransferCountSet ( DMA_ID_0, DMA_CHANNEL_4, transferCount ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1787 5.6.6.6.8 DMA Channel Configuration 5.6.6.6.8.1 PLIB_DMA_ChannelPrioritySelect Function C void PLIB_DMA_ChannelPrioritySelect( DMA_MODULE_ID index, DMA_CHANNEL_PRIORITY channelPriority ); Description This function sets the priority scheme of the DMA channels at the global level. This function is used in devices that do not have the per channel priority feature. Preconditions None. Parameters Parameters Description channelPriority One of the supported priorities listed by DMA_CHANNEL_PRIORITY Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_PRIORITY channelPriority = DMA_CHANNEL_ROUND_ROBIN; PLIB_DMA_ChannelPrioritySelect( DMA_ID_0, channelPriority ); 5.6.6.6.8.2 PLIB_DMA_ChannelPriorityGet Function C DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelPriorityGet( DMA_MODULE_ID index ); Description This function gets the priority scheme of the DMA channels at the global level. This function is used in devices that do not have the per channel priority feature. Preconditions None. Returns channelPriority - One of the supported priorities listed by DMA_CHANNEL_PRIORITY Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_PRIORITY channelPriority; channelPriority = PLIB_DMA_ChannelPriorityGet( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1788 5.6.6.6.8.3 PLIB_DMA_ChannelXAutoDisable Function C void PLIB_DMA_ChannelXAutoDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function disables a channel after a block transfer is complete. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. Example PLIB_DMA_ChannelXAutoDisable( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.4 PLIB_DMA_ChannelXAutoEnable Function C void PLIB_DMA_ChannelXAutoEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function enables the channel continuously. The channel is not automatically disabled after a block transfer is complete. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1789 Example PLIB_DMA_ChannelXAutoEnable( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.5 PLIB_DMA_ChannelXBusyActiveSet Function C void PLIB_DMA_ChannelXBusyActiveSet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function sets the busy bit to active, indicating the channel is active or has been enabled. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXBusyActiveSet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.8.6 PLIB_DMA_ChannelXBusyInActiveSet Function C void PLIB_DMA_ChannelXBusyInActiveSet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function sets the busy bit to inactive, indicating the channel is inactive or has been disabled. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1790 refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXBusyInActiveSet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.8.7 PLIB_DMA_ChannelXChainDisable Function C void PLIB_DMA_ChannelXChainDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function disables the channel chaining for the specified DMA channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specfic device data sheet to determine availability or use the the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Example PLIB_DMA_ChannelXChainDisable( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.8 PLIB_DMA_ChannelXChainEnable Function C void PLIB_DMA_ChannelXChainEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function enables the channel chain feature. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1791 Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Example PLIB_DMA_ChannelXChainEnable( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.9 PLIB_DMA_ChannelXChainToHigher Function C void PLIB_DMA_ChannelXChainToHigher( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will Chain the specified channel to a channel higher in natural priority. CH5 will be enabled by a CH4 transfer complete. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXChain feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChain function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXChainToHigher ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.8.10 PLIB_DMA_ChannelXChainToLower Function C void PLIB_DMA_ChannelXChainToLower( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will chain the specified channel to a channel lower in natural priority. CH3 will be enabled by a CH4 transfer complete. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1792 Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXChain feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChain function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXChainToLower ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.8.11 PLIB_DMA_ChannelXDisable Function C void PLIB_DMA_ChannelXDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will disable the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXDisable ( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.12 PLIB_DMA_ChannelXEnable Function C void PLIB_DMA_ChannelXEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will enable the specified channel. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1793 Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXEnable ( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.13 PLIB_DMA_ChannelXPriorityGet Function C DMA_CHANNEL_PRIORITY PLIB_DMA_ChannelXPriorityGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function gets the priority of the specified channel. Preconditions None. Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Returns channelPriority - One of the supported priorities listed by DMA_CHANNEL_PRIORITY Remarks This function implements an operation of the ChannelXPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPriority function in your application to determine whether this feature is available. Example DMA_CHANNEL channel = DMA_CHANNEL_0; DMA_CHANNEL_PRIORITY channelPriority; channelPriority = PLIB_DMA_ChannelXPriorityGet( DMA_ID_0, channel ); 5.6.6.6.8.14 PLIB_DMA_ChannelXPrioritySelect Function C void PLIB_DMA_ChannelXPrioritySelect( DMA_MODULE_ID index, DMA_CHANNEL channel, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1794 DMA_CHANNEL_PRIORITY channelPriority ); Description This function sets the priority of the specified channel. Preconditions None. Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL channelPriority One of the supported priorities listed by DMA_CHANNEL_PRIORITY Returns None. Remarks This function implements an operation of the ChannelXPriority feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPriority function in your application to determine whether this feature is available. Example DMA_CHANNEL channel = DMA_CHANNEL_0; DMA_CHANNEL_PRIORITY channelPriority = DMA_CHANNEL_PRIORITY_3; PLIB_DMA_ChannelXPrioritySelect( DMA_ID_0, channel, channelPriority ); 5.6.6.6.8.15 PLIB_DMA_ChannelXTransferDirectionGet Function C DMA_CHANNEL_TRANSFER_DIRECTION PLIB_DMA_ChannelXTransferDirectionGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the data transfer direction of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns DMA_CHANNEL_TRANSFER_DIRECTION - The transfer direction indicated by the DMA_CHANNEL_TRANSFER_DIRECTION Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL_TRANSFER_DIRECTION chTransferDirection; chTransferDirection = PLIB_DMA_ChannelXTransferDirectionGet ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1795 5.6.6.6.8.16 PLIB_DMA_ChannelXTransferDirectionSelect Function C void PLIB_DMA_ChannelXTransferDirectionSelect( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_TRANSFER_DIRECTION chTransferDirection ); Description This function selects the data transfer direction of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL chTransferDirection The transfer direction indicated by the DMA_CHANNEL_TRANSFER_DIRECTION Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_DMA_ChannelXTransferDirectionSelect ( DMA_ID_0, DMA_CHANNEL_4, DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL ); 5.6.6.6.8.17 PLIB_DMA_ChannelXDisabledDisablesEvents Function C void PLIB_DMA_ChannelXDisabledDisablesEvents( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will allow the channel start/abort events to be ignored even if the channel is disabled. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXDisabled feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1796 refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDisabled function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXDisabledDisablesEvents ( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.18 PLIB_DMA_ChannelXDisabledEnablesEvents Function C void PLIB_DMA_ChannelXDisabledEnablesEvents( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will allow the channel register start/abort events even if the channel is disabled. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXDisabled feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXDisabled function in your application to automatically determine whether this feature is available. Example PLIB_DMA_ChannelXDisabledEnablesEvents ( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.8.19 PLIB_DMA_ChannelXPatternIgnoreByteDisable Function C void PLIB_DMA_ChannelXPatternIgnoreByteDisable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function disables the pattern match ignore byte. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1797 Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreByteDisable(DMA_ID_0, dmaChannel); 5.6.6.6.8.20 PLIB_DMA_ChannelXPatternIgnoreByteEnable Function C void PLIB_DMA_ChannelXPatternIgnoreByteEnable( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function enables the pattern match ignore byte. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreByteEnable(DMA_ID_0, dmaChannel); 5.6.6.6.8.21 PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Function C bool PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the state (enabled or disabled) of the pattern match ignore byte. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1798 Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - The pattern match ignore byte is enabled • false - The pattern match ignore byte is disabled Remarks This function implements an operation of the ChannelXPatternIgnoreByte feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnoreByte function in your application to automatically determine whether this feature is available. Example bool patternIsEnabled; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; patternIsEnabled = PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled(DMA_ID_0, dmaChannel); 5.6.6.6.8.22 PLIB_DMA_ChannelXPatternIgnoreGet Function C uint8_t PLIB_DMA_ChannelXPatternIgnoreGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the value of the pattern match ignore. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns uint8_t - Pattern match ignore value Remarks This function implements an operation of the ChannelXPatternIgnore feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnore function in your application to automatically determine whether this feature is available. Example uint8_t patternMatch; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; patternMatch = PLIB_DMA_ChannelXPatternIgnoreGet ( DMA_ID_0, dmaChannel); 5.6.6.6.8.23 PLIB_DMA_ChannelXPatternIgnoreSet Function C void PLIB_DMA_ChannelXPatternIgnoreSet( 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1799 DMA_MODULE_ID index, DMA_CHANNEL channel, uint8_t pattern ); Description This function sets the value of the pattern match ignore. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL pattern Pattern match ignore value Returns None. Remarks This function implements an operation of the ChannelXPatternIgnore feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternIgnore function in your application to automatically determine whether this feature is available. Example uint8_t patternMatch = 0x8; DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; PLIB_DMA_ChannelXPatternIgnoreSet ( DMA_ID_0, dmaChannel,patternMatch); 5.6.6.6.8.24 PLIB_DMA_ChannelXPatternLengthGet Function C DMA_PATTERN_LENGTH PLIB_DMA_ChannelXPatternLengthGet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel ); Description This function returns the length of the byte matching the CHPIGN bits during a pattern match that may be ignored during the pattern match determination when the CHPIGNEN bit is set. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL Returns patternLen - Length of pattern match (either 1 or 2) Remarks This function implements an operation of the ChannelXPatternLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternLength function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1800 Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; DMA_PATTERN_LENGTH patternLen; patternLen = PLIB_DMA_ChannelXPatternLengthGet(DMA_ID_0, dmaChannel); 5.6.6.6.8.25 PLIB_DMA_ChannelXPatternLengthSet Function C void PLIB_DMA_ChannelXPatternLengthSet( DMA_MODULE_ID index, DMA_CHANNEL dmaChannel, DMA_PATTERN_LENGTH patternLen ); Description This function sets the length of the pattern match ignore to 1 or 2 bytes. Preconditions None. Parameters Parameters Description dmaChannel One of the possible DMA channels listed by DMA_CHANNEL patternLen Length of pattern match (either 1 or 2) Returns None. Remarks This function implements an operation of the ChannelXPatternLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXPatternLength function in your application to automatically determine whether this feature is available. Example DMA_CHANNEL dmaChannel = DMA_CHANNEL_2; DMA_PATTERN_LENGTH patternLen; patternLen = DMA_PATTERN_MATCH_LENGTH_1BYTE; PLIB_DMA_ChannelXPatternLengthSet(DMA_ID_0, dmaChannel, patternLen); 5.6.6.6.9 DMA CRC Module Interface Routines 5.6.6.6.9.1 PLIB_DMA_CRCAppendModeDisable Function C void PLIB_DMA_CRCAppendModeDisable( DMA_MODULE_ID index ); Description This function disables the CRC append mode. The DMA transfers data from the source through the CRC obeying WBO ( DMA_MODULE_ID index, write byte order ) as it writes the data to the destination. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1801 Returns None. Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCAppendModeDisable( DMA_ID_0 ); 5.6.6.6.9.2 PLIB_DMA_CRCAppendModeEnable Function C void PLIB_DMA_CRCAppendModeEnable( DMA_MODULE_ID index ); Description This function enables the CRC append mode. The DMA transfers data from the source into the CRC, but not to the destination. When a block transfer completes, the DMA writes the calculated CRC value to the location specified by the CHxDSA register. Preconditions None. Returns None. Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCAppendModeEnable( DMA_ID_0 ); 5.6.6.6.9.3 PLIB_DMA_CRCAppendModeIsEnabled Function C bool PLIB_DMA_CRCAppendModeIsEnabled( DMA_MODULE_ID index ); Description This function gets the enable status of the CRC append mode. Preconditions None. Returns • true - CRC append mode is enabled • false - CRC append mode is disabled Remarks This function implements an operation of the CRCAppendMode feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1802 refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCAppendMode function in your application to automatically determine whether this feature is available. Example bool DMAcrcAppendMode; DMAcrcAppendMode = PLIB_DMA_CRCAppendModeIsEnabled( DMA_ID_0 ); 5.6.6.6.9.4 PLIB_DMA_CRCBitOrderSelect Function C void PLIB_DMA_CRCBitOrderSelect( DMA_MODULE_ID index, DMA_CRC_BIT_ORDER bitOrder ); Description This function selects the bit order for checksum caluculation. Preconditions None. Parameters Parameters Description bitOrder Specifies the bit order for CRC caluculation Returns None. Remarks This function implements an operation of the CRCBitOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCBitOrder function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCBitOrderSelect ( DMA_ID_0,DMA_CRC_BIT_ORDER_LSB ); 5.6.6.6.9.5 PLIB_DMA_CRCByteOrderGet Function C DMA_CRC_BYTE_ORDER PLIB_DMA_CRCByteOrderGet( DMA_MODULE_ID index ); Description This function gets the current byte order selected by the DMA module CRC feature. Preconditions The WBO bit must be set to use this function. Returns byteOrder - One of the possible byte orders specified by DMA_CRC_BYTE_ORDER Remarks This function implements an operation of the CRCByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCByteOrder function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1803 Example DMA_CRC_BYTE_ORDER byteOrder; byteOrder = PLIB_DMA_CRCByteOrderGet ( DMA_ID_0 ); 5.6.6.6.9.6 PLIB_DMA_CRCByteOrderSelect Function C void PLIB_DMA_CRCByteOrderSelect( DMA_MODULE_ID index, DMA_CRC_BYTE_ORDER byteOrder ); Description This function selects the byte order. Preconditions The WBO bit must be set to use this function. Parameters Parameters Description byteOrder One of the possible byte orders specified by DMA_CRC_BYTE_ORDER Returns None. Remarks This function implements an operation of the CRCByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCByteOrder function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCByteOrderSelect ( DMA_ID_0, DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY ); 5.6.6.6.9.7 PLIB_DMA_CRCChannelGet Function C DMA_CHANNEL PLIB_DMA_CRCChannelGet( DMA_MODULE_ID index ); Description This function returns the current DMA channel to which the CRC is assigned. Preconditions None. Returns crcChannel - One of the possible DMA channels listed by DMA_CHANNEL Remarks This function implements an operation of the CRCChannel feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCChannel function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1804 Example DMA_CHANNEL crcChannel; crcChannel = PLIB_DMA_CRCChannelGet( DMA_ID_0 ); 5.6.6.6.9.8 PLIB_DMA_CRCChannelSelect Function C void PLIB_DMA_CRCChannelSelect( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function assigns the CRC feature to the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns None. Remarks This function implements an operation of the CRCChannel feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCChannel function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCChannelSelect( DMA_ID_0, DMA_CHANNEL_5 ); 5.6.6.6.9.9 PLIB_DMA_CRCDataRead Function C uint32_t PLIB_DMA_CRCDataRead( DMA_MODULE_ID index ); Description This function reads the contents of the DMA CRC data register. Preconditions None. Returns uint32_t - 32-bit CRC data (The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the CRCData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCData function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1805 Example uint32_t DMACRCdata; DMACRCdata = PLIB_DMA_CRCDataRead ( DMA_ID_0 ); 5.6.6.6.9.10 PLIB_DMA_CRCDataWrite Function C void PLIB_DMA_CRCDataWrite( DMA_MODULE_ID index, uint32_t DMACRCdata ); Description This function writes the contents of the DMA CRC data register. Preconditions None. Parameters Parameters Description DMACRCdata 32-bit CRC data (The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the CRCData feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCData function in your application to automatically determine whether this feature is available. Example uint32_t DMACRCdata = 0x0E0E0E; PLIB_DMA_CRCDataWrite ( DMA_ID_0, DMACRCdata ); 5.6.6.6.9.11 PLIB_DMA_CRCDisable Function C void PLIB_DMA_CRCDisable( DMA_MODULE_ID index ); Description This function disables the DMA module CRC feature. The channel transfers proceed normally. Preconditions None. Returns None. Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1806 Example PLIB_DMA_CRCDisable( DMA_ID_0 ); 5.6.6.6.9.12 PLIB_DMA_CRCEnable Function C void PLIB_DMA_CRCEnable( DMA_MODULE_ID index ); Description This function enables the DMA module CRC feature. The channel transfers are routed through the CRC. Preconditions None. Returns None. Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCEnable( DMA_ID_0 ); 5.6.6.6.9.13 PLIB_DMA_CRCPolynomialLengthGet Function C uint8_t PLIB_DMA_CRCPolynomialLengthGet( DMA_MODULE_ID index ); Description This function gets the current polynomial length. Preconditions None. Returns uint8_t - Polynomial length Remarks This function implements an operation of the CRCPolynomialLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCPolynomialLength function in your application to automatically determine whether this feature is available. Example uint8_t polyLength; polyLength = PLIB_DMA_CRCPolynomialLengthGet( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1807 5.6.6.6.9.14 PLIB_DMA_CRCPolynomialLengthSet Function C void PLIB_DMA_CRCPolynomialLengthSet( DMA_MODULE_ID index, uint8_t polyLength ); Description This function Selects the polynomial length. Preconditions None. Parameters Parameters Description polyLength Polynomial length Returns None. Remarks This function implements an operation of the CRCPolynomialLength feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCPolynomialLength function in your application to automatically determine whether this feature is available. Example uint8_t polyLength = 0x2; PLIB_DMA_CRCPolynomialLengthSet( DMA_ID_0, polyLength ); 5.6.6.6.9.15 PLIB_DMA_CRCTypeGet Function C DMA_CRC_TYPE PLIB_DMA_CRCTypeGet( DMA_MODULE_ID index ); Description This function gets the DMA module CRC feature type. The CRC feature will compute either the IP header checksum or the Linear Shift Feedback Register (LFSR) checksum. Preconditions None. Returns CRCType - One of the possible CRC checksums listed by DMA_CRC_TYPE. Remarks This function implements an operation of the CRCType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCType function in your application to automatically determine whether this feature is available. Example DMA_CRC_TYPE CRCType; CRCType = PLIB_DMA_CRCTypeGet( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1808 5.6.6.6.9.16 PLIB_DMA_CRCTypeSet Function C void PLIB_DMA_CRCTypeSet( DMA_MODULE_ID index, DMA_CRC_TYPE CRCType ); Description This function selects the DMA module CRC feature type. The CRC feature will compute either the IP header checksum or the Linear Shift Feedback Register (LFSR) checksum. Preconditions None. Parameters Parameters Description CRCType One of the possible CRC checksums listed by DMA_CRC_TYPE Returns None. Remarks This function implements an operation of the CRCType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCType function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCTypeSet(DMA_ID_0, DMA_CRC_IP_HEADER ); 5.6.6.6.9.17 PLIB_DMA_CRCWriteByteOrderAlter Function C void PLIB_DMA_CRCWriteByteOrderAlter( DMA_MODULE_ID index ); Description This function enables byte order alteration as specified by the BYTO<1:0> bits. The source data is written to the destination reordered as defined by the BYTO<1:0> bits. Preconditions None. Returns None. Remarks This function implements an operation of the CRCWriteByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCWriteByteOrder function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCWriteByteOrderAlter ( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1809 5.6.6.6.9.18 PLIB_DMA_CRCWriteByteOrderMaintain Function C void PLIB_DMA_CRCWriteByteOrderMaintain( DMA_MODULE_ID index ); Description This function disables byte order alteration. The source data is written to the destination unaltered. Preconditions None. Returns None. Remarks This function implements an operation of the CRCWriteByteOrder feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCWriteByteOrder function in your application to automatically determine whether this feature is available. Example PLIB_DMA_CRCWriteByteOrderMaintain ( DMA_ID_0 ); 5.6.6.6.9.19 PLIB_DMA_CRCXOREnableGet Function C uint32_t PLIB_DMA_CRCXOREnableGet( DMA_MODULE_ID index ); Description This function reads the CRC XOR register. Preconditions None. Returns uint32_t - 32-bit CRC XOR enable mask data (The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Remarks This function implements an operation of the CRCXOREnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCXOREnable function in your application to automatically determine whether this feature is available. Example uint32_t DMACRCXORdata; DMACRCXORdata = PLIB_DMA_CRCXOREnableGet ( DMA_ID_0 ); 5.6.6.6.9.20 PLIB_DMA_CRCXOREnableSet Function C void PLIB_DMA_CRCXOREnableSet( DMA_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1810 uint32_t DMACRCXOREnableMask ); Description This function writes to the CRC XOR enable register as per the specified enable mask. Each enabled bit will be taken as input to the shift register. Preconditions None. Parameters Parameters Description DMACRCXOREnableMask 32-bit CRC XOR enable mask data (The CRC data (16-bit, 32-bit) is device-specific. Please refer to the specific device data sheet to determine availability.) Returns None. Remarks This function implements an operation of the CRCXOREnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRCXOREnable function in your application to automatically determine whether this feature is available. Example uint32_t DMACRCXOREnableMask = 0x05EFFFFF; PLIB_DMA_CRCXOREnableSet ( DMA_ID_0, DMACRCXOREnableMask ); 5.6.6.6.10 DMA Global Status Routines 5.6.6.6.10.1 PLIB_DMA_CRCIsEnabled Function C bool PLIB_DMA_CRCIsEnabled( DMA_MODULE_ID index ); Description This function gets the enable status of the CRC feature. Preconditions None. Returns • true - The CRC feature is enabled • false - The CRC feature is disabled Remarks This function implements an operation of the CRC feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsCRC function in your application to automatically determine whether this feature is available. Example bool DMAcrcStatus; 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1811 DMAcrcStatus = PLIB_DMA_CRCIsEnabled( DMA_ID_0 ); 5.6.6.6.10.2 PLIB_DMA_IsBusy Function C bool PLIB_DMA_IsBusy( DMA_MODULE_ID index ); Description This function gets the BUSY bit of the DMA controller. Preconditions None. Returns • true - DMA module is active • false - DMA module is disabled and is not actively transferring data Remarks This function implements an operation of the Busy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsBusy function in your application to automatically determine whether this feature is available. Example bool dmaBusyStatus; dmaBusyStatus = PLIB_DMA_IsBusy( DMA_ID_0 ); 5.6.6.6.10.3 PLIB_DMA_IsEnabled Function C bool PLIB_DMA_IsEnabled( DMA_MODULE_ID index ); Description This function returns the DMA module enable status. Preconditions None. Returns • true - The DMA is enabled • false - The DMA is disabled Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsEnableControl function in your application to automatically determine whether this feature is available. Example PLIB_DMA_IsEnabled( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1812 5.6.6.6.10.4 PLIB_DMA_LastBusAccessIsRead Function C bool PLIB_DMA_LastBusAccessIsRead( DMA_MODULE_ID index ); Description This function returns true if the last DMA bus access was a read. Preconditions None. Returns • true - The last bus access was a read • false - The last bus access was not a read Remarks This function implements an operation of the LastBusAccess feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsLastBusAccess function in your application to automatically determine whether this feature is available. Example bool dmaLastBusAccessType; dmaLastBusAccessType = PLIB_DMA_LastBusAccessIsRead( DMA_ID_0 ); 5.6.6.6.10.5 PLIB_DMA_LastBusAccessIsWrite Function C bool PLIB_DMA_LastBusAccessIsWrite( DMA_MODULE_ID index ); Description This function returns true if the last DMA bus access was a write operation. Preconditions None. Returns • true - The last bus access was a write operation • false - The last bus access was not a write operation Remarks This function implements an operation of the LastBusAccess feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsLastBusAccess function in your application to automatically determine whether this feature is available. Example bool dmaLastBusAccessType; dmaLastBusAccessType = PLIB_DMA_LastBusAccessIsWrite( DMA_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1813 5.6.6.6.10.6 PLIB_DMA_LastChannelActive Function C DMA_CHANNEL PLIB_DMA_LastChannelActive( DMA_MODULE_ID index ); Description This function returns the last DMA channel that participated in the data transfer. Preconditions None. Returns channel - One of the existing DMA channels listed by DMA_CHANNEL Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_CHANNEL lastActiveChannel; lastActiveChannel = PLIB_DMA_LastChannelActive( DMA_ID_0 ); 5.6.6.6.10.7 PLIB_DMA_RecentAddressAccessed Function C uint32_t PLIB_DMA_RecentAddressAccessed( DMA_MODULE_ID index ); Description This function returns the address of the most recent DMA access. Preconditions None. Returns uint32_t - The most recent address accessed by the DMA Remarks This function implements an operation of the RecentAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsRecentAddress function in your application to automatically determine whether this feature is available. Example uint32_t dmaLastAddressAccessed; dmaLastAddressAccessed = PLIB_DMA_RecentAddressAccessed( DMA_ID_0 ); 5.6.6.6.10.8 PLIB_DMA_SuspendIsEnabled Function C bool PLIB_DMA_SuspendIsEnabled( DMA_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1814 Description This function returns the DMA suspend status. Preconditions None. Returns • true - The DMA transfers are suspended • false - The DMA operates normally Remarks This function implements an operation of the Suspend feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsSuspend function in your application to automatically determine whether this feature is available. Example bool dmaSuspendStatus; dmaSuspendStatus = PLIB_DMA_SuspendIsEnabled( DMA_ID_0 ); 5.6.6.6.11 DMA Channel Status Routines 5.6.6.6.11.1 PLIB_DMA_ChannelXAutoIsEnabled Function C bool PLIB_DMA_ChannelXAutoIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the channel automatic enable status. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - Channel automatic enable is on • false - Channel automatic enable is off Remarks This function implements an operation of the ChannelXAuto feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXAuto function in your application to determine whether this feature is available. Example bool ChAutoEnableStatus; ChAutoEnableStatus = PLIB_DMA_ChannelXAutoIsEnabled(DMA_ID_0, DMA_CHANNEL_2 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1815 5.6.6.6.11.2 PLIB_DMA_ChannelXBufferedDataIsWritten Function C bool PLIB_DMA_ChannelXBufferedDataIsWritten( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the buffered data write status for the specified channel. Preconditions None. Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Returns • true - The content of the DMA buffer has not been written to the location specified in the destination/source address or in Null Write mode • false - The content of the DMA buffer has been written to the location specified in the destination/source address or in Null Write mode Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example bool chBuffWriteStatus; chBuffWriteStatus = PLIB_DMA_ChannelXBufferedDataIsWritten( DMA_ID_0, DMA_CHANNEL_3 ); 5.6.6.6.11.3 PLIB_DMA_ChannelXBusyIsBusy Function C bool PLIB_DMA_ChannelXBusyIsBusy( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the busy status of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - The channel is active or has been enabled • false - The channel is inactive or has been disabled 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1816 Remarks This function implements an operation of the ChannelXBusy feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXBusy function in your application to automatically determine whether this feature is available. Example bool chBusyStatus; chBusyStatus = PLIB_DMA_ChannelXBusyIsBusy ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.11.4 PLIB_DMA_ChannelXChainIsEnabled Function C bool PLIB_DMA_ChannelXChainIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the chain status of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - The channel chain is on for this channel • false - The channel chain is off for this channel Remarks This function implements an operation of the ChannelXChainEnbl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelXChainEnbl function in your application to determine whether this feature is available. Example bool ChchainStatus; ChchainStatus = PLIB_DMA_ChannelXChainIsEnabled( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.11.5 PLIB_DMA_ChannelXCollisionStatus Function C bool PLIB_DMA_ChannelXCollisionStatus( DMA_MODULE_ID index, DMA_CHANNEL channel, DMA_CHANNEL_COLLISION collisonType ); Description This function returns the status of the specified collison type for the specified channel. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1817 Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL collisonType Collision type listed by DMA_CHANNEL_COLLISION Returns • true - A collision specified by collisonType was detected • false - No collision of type collisonType was detected Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example bool memWriteCollisionStatus; memWriteCollisionStatus = PLIB_DMA_ChannelXMemoryWriteCollisionStatus( DMA_ID_0, DMA_CHANNEL_3, DMA_CHANNEL_COLLISION_MEMORY ); 5.6.6.6.11.6 PLIB_DMA_ChannelXEventIsDetected Function C bool PLIB_DMA_ChannelXEventIsDetected( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the event status on the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - An event was detected • false - No events were detected Remarks This function implements an operation of the ChannelXEvent feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_DMA_ExistsChannelXEvent function in your application to determine whether this feature is available. Example bool channeleventStatus; channeleventStatus = PLIB_DMA_ChannelXEventIsDetected( DMA_ID_0, DMA_CHANNEL_2 ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1818 5.6.6.6.11.7 PLIB_DMA_ChannelXIsEnabled Function C bool PLIB_DMA_ChannelXIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function will return the enable status of the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - The specified DMA channel is enabled • false - The specified DMA channel is disabled Remarks This function implements an operation of the ChannelX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelX function in your application to automatically determine whether this feature is available. Example bool chEnableStatus; chEnableStatus = PLIB_DMA_ChannelXIsEnabled ( DMA_ID_0, DMA_CHANNEL_2 ); 5.6.6.6.11.8 PLIB_DMA_ChannelXNullWriteModeIsEnabled Function C bool PLIB_DMA_ChannelXNullWriteModeIsEnabled( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the enable status of the Null Write mode for the specified channel. Preconditions None. Parameters Parameters Description channel One of the possible DMA channels listed by DMA_CHANNEL Returns • true - Null write mode is enabled for this channel • false - Null write mode is disabled for this channel 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1819 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example bool chNullWriteStatus; chNullWriteStatus = PLIB_DMA_ChannelXNullWriteModeIsEnabled ( DMA_ID_0, DMA_CHANNEL_4 ); 5.6.6.6.11.9 PLIB_DMA_ChannelXPingPongModeGet Function C DMA_PING_PONG_MODE PLIB_DMA_ChannelXPingPongModeGet( DMA_MODULE_ID index, DMA_CHANNEL channel ); Description This function returns the Ping-Pong mode status for the specified channel. Preconditions None. Parameters Parameters Description channel One of the existing DMA channels listed by DMA_CHANNEL Returns mode - One of the possible Ping-Pong modes Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. Example DMA_PING_PONG_MODE chPingPongStatus; chPingPongStatus = PLIB_DMA_ChannelXPingPongModeGet(DMA_ID_0, DMA_CHANNEL_3 ); if (DMA_PING_PONG_SECONDARY == chPingPongStatus) { \Application } 5.6.6.6.11.10 PLIB_DMA_ChannelBitsGet Function C uint8_t PLIB_DMA_ChannelBitsGet( DMA_MODULE_ID index ); Description This function returns the channel bits. Preconditions None. Returns uint8_t - DMA channel bits 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1820 Remarks This function implements an operation of the ChannelBits feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use the PLIB_DMA_ExistsChannelBits function in your application to automatically determine whether this feature is available. Example uint8_t dmaChBits; dmaChBits = PLIB_DMA_ChannelBitsGet( DMA_ID_0 ); 5.6.6.6.12 Data Types and Constants 5.6.6.6.12.1 DMA_ADDRESS_OFFSET_TYPE Enumeration C typedef enum { DMA_ADDRESS_OFFSET_PRIMARY, DMA_ADDRESS_OFFSET_SECONDARY } DMA_ADDRESS_OFFSET_TYPE; Description DMA address offsets This enumeration lists all the possible DMA address offsets. Members Members Description DMA_ADDRESS_OFFSET_PRIMARY address offset-A DMA_ADDRESS_OFFSET_SECONDARY address offset-B Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.2 DMA_CHANNEL Enumeration C typedef enum { DMA_CHANNEL_0, DMA_CHANNEL_1, DMA_CHANNEL_2, DMA_CHANNEL_3, DMA_CHANNEL_4, DMA_CHANNEL_5, DMA_CHANNEL_6, DMA_CHANNEL_7 } DMA_CHANNEL; Description DMA channel This enumeration lists all the possible DMA channels available. Members Members Description DMA_CHANNEL_0 DMA Channel 0 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1821 DMA_CHANNEL_1 DMA Channel 1 DMA_CHANNEL_2 DMA Channel 2 DMA_CHANNEL_3 DMA Channel 3 DMA_CHANNEL_4 DMA Channel 4 DMA_CHANNEL_5 DMA Channel 5 DMA_CHANNEL_6 DMA Channel 6 DMA_CHANNEL_7 DMA Channel 7 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.3 DMA_CHANNEL_ADDRESSING_MODE Enumeration C typedef enum { DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT, DMA_ADDRESSING_REGISTER_INDIRECT_WITHOUT_POST_INCREMENT, DMA_ADDRESSING_PERIPHERAL_INDIRECT } DMA_CHANNEL_ADDRESSING_MODE; Description DMA channel addressing modes This enumeration lists all the possible channel addressing modes. Members Members Description DMA_ADDRESSING_REGISTER_INDIRECT_WITH_POST_INCREMENT register indirect with post increment DMA_ADDRESSING_REGISTER_INDIRECT_WITHOUT_POST_INCREMENT register indirect without post increment DMA_ADDRESSING_PERIPHERAL_INDIRECT peripheral indirect addressing Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.4 DMA_CHANNEL_COLLISION Enumeration C typedef enum { DMA_CHANNEL_COLLISION_MEMORY, DMA_CHANNEL_COLLISION_PERIPHERAL, DMA_CHANNEL_COLLISION_TRANSFER_REQUEST } DMA_CHANNEL_COLLISION; Description DMA channel collison types This enumeration lists all the possible channel collison types. Members Members Description DMA_CHANNEL_COLLISION_MEMORY Memory Write Collision DMA_CHANNEL_COLLISION_PERIPHERAL Peripheral Write collison DMA_CHANNEL_COLLISION_TRANSFER_REQUEST Transfer request collision 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1822 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.5 DMA_CHANNEL_DATA_SIZE Enumeration C typedef enum { DMA_CHANNEL_DATA_8, DMA_CHANNEL_DATA_16 } DMA_CHANNEL_DATA_SIZE; Description DMA channel data size This enumeration lists all the possible data sizes for the DMA channels. Members Members Description DMA_CHANNEL_DATA_8 8 bit data size DMA_CHANNEL_DATA_16 16 bit data size Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.6 DMA_CHANNEL_PRIORITY Enumeration C typedef enum { DMA_CHANNEL_PRIORITY_0, DMA_CHANNEL_PRIORITY_1, DMA_CHANNEL_PRIORITY_2, DMA_CHANNEL_PRIORITY_3, DMA_CHANNEL_ROUND_ROBIN, DMA_CHANNEL_FIXED_PRIORITY } DMA_CHANNEL_PRIORITY; Description DMA channel priority types This enumeration lists all the possible channel priorities. Members Members Description DMA_CHANNEL_PRIORITY_0 priority 0 DMA_CHANNEL_PRIORITY_1 priority 1 DMA_CHANNEL_PRIORITY_2 priority 2 DMA_CHANNEL_PRIORITY_3 priority 3 DMA_CHANNEL_ROUND_ROBIN round-robin scheme DMA_CHANNEL_FIXED_PRIORITY fixed priority scheme Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1823 5.6.6.6.12.7 DMA_CHANNEL_TRANSFER_DIRECTION Enumeration C typedef enum { DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL, DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY, DMA_READ_FROM_MEMORY_WRITE_TO_MEMORY, DMA_READ_FROM_PERIPHERAL_WRITE_TO_PERIPHERAL } DMA_CHANNEL_TRANSFER_DIRECTION; Description DMA channel data transfer direction This enumeration lists all the possible data transfer directions. Members Members Description DMA_READ_FROM_MEMORY_WRITE_TO_PERIPHERAL DMA transfer happens from the memory to peripheral DMA_READ_FROM_PERIPHERAL_WRITE_TO_MEMORY DMA transfer happens from the peripheral to memory DMA_READ_FROM_MEMORY_WRITE_TO_MEMORY DMA transfer happens from the memory to memory DMA_READ_FROM_PERIPHERAL_WRITE_TO_PERIPHERAL DMA transfer happens from the peripheral to peripheral Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.8 DMA_CHANNEL_TRIGGER_TYPE Enumeration C typedef enum { DMA_CHANNEL_TRIGGER_TRANSFER_START, DMA_CHANNEL_TRIGGER_TRANSFER_ABORT, DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT } DMA_CHANNEL_TRIGGER_TYPE; Description DMA trigger types This enumeration lists all the possible DMA channel triggers. Members Members Description DMA_CHANNEL_TRIGGER_TRANSFER_START Trigger for DMA transfer start DMA_CHANNEL_TRIGGER_TRANSFER_ABORT Trigger for DMA transfer abort DMA_CHANNEL_TRIGGER_PATTERN_MATCH_ABORT Trigger for DMA transfer abort via pattern match Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.9 DMA_CRC_BIT_ORDER Enumeration C typedef enum { DMA_CRC_BIT_ORDER_LSB, DMA_CRC_BIT_ORDER_MSB 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1824 } DMA_CRC_BIT_ORDER; Description DMA CRC caluculation bit order This enumeration lists all the possible CRC caluculation bit orders Members Members Description DMA_CRC_BIT_ORDER_LSB CRC is caluculated least significant bit first DMA_CRC_BIT_ORDER_MSB CRC is caluculated most significant bit first Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.10 DMA_CRC_BYTE_ORDER Enumeration C typedef enum { DMA_CRC_BYTEORDER_NO_SWAPPING, DMA_CRC_SWAP_BYTE_ON_WORD_BOUNDARY, DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY, DMA_CRC_SWAP_BYTE_ON_HALF_WORD_BOUNDARY } DMA_CRC_BYTE_ORDER; Description CRC Byte order type This enumeration lists all the possible byte orders handled by CRC module. Members Members Description DMA_CRC_BYTEORDER_NO_SWAPPING No swapping, Source byte order DMA_CRC_SWAP_BYTE_ON_WORD_BOUNDARY Endian byte swap on word boundaries ( reverse source byte order ) DMA_CRC_SWAP_HALF_WORD_ON_WORD_BOUNDARY Swap half-words on word boundaries ( reverse source half-word order with source byte order per half-word ) DMA_CRC_SWAP_BYTE_ON_HALF_WORD_BOUNDARY Endian byte swap on half-word boundaries ( reverse source half-word order with reverse source byte order per half-word ) Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.11 DMA_CRC_TYPE Enumeration C typedef enum { DMA_CRC_IP_HEADER, DMA_CRC_LFSR } DMA_CRC_TYPE; Description CRC type This enumeration lists all the possible checksums handled by CRC module. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1825 Members Members Description DMA_CRC_IP_HEADER CRC module will caluculate IP header checksum DMA_CRC_LFSR CRC module will caluculate Linear Feedback Shift Registers checksum Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.12 DMA_DESTINATION_ADDRESSING_MODE Enumeration C typedef enum { DMA_ADDRESSING_DESTINATION_UNCHANGED, DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE, DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE, DMA_ADDRESSING_DESTINATION_PERIPHERAL_INDIRECT } DMA_DESTINATION_ADDRESSING_MODE; Description DMA destination addressing modes This enumeration lists all the possible destination addressing modes. Members Members Description DMA_ADDRESSING_DESTINATION_UNCHANGED DMADST remains unchanged after a transfer completion DMA_ADDRESSING_DESTINATION_INCREMENT_BASED_ON_SIZE DMADST is incremented based on SIZE bit after a transfer completion DMA_ADDRESSING_DESTINATION_DECREMENT_BASED_ON_SIZE DMADST is decremented based on SIZE bit after a transfer completion DMA_ADDRESSING_DESTINATION_PERIPHERAL_INDIRECT DMADST is used in peripheral indirect addressing and remains unchanged Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.13 DMA_INT_TYPE Enumeration C typedef enum { DMA_INT_ADDRESS_ERROR, DMA_INT_TRANSFER_ABORT, DMA_INT_CELL_TRANSFER_COMPLETE, DMA_INT_BLOCK_TRANSFER_COMPLETE, DMA_INT_DESTINATION_HALF_FULL, DMA_INT_DESTINATION_DONE, DMA_INT_SOURCE_HALF_EMPTY, DMA_INT_SOURCE_DONE, DMA_INT_COUNT_HALF_DONE, DMA_INT_CHANNEL_OVERRUN, DMA_INT_COMPLETE, DMA_INT_LOW_ADDRESS_LIMIT, DMA_INT_HIGH_ADDRESS_LIMIT } DMA_INT_TYPE; 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1826 Description DMA channel X interrupt types This enumeration lists all the possible interrupt types for a channel. Not to be confused with the DMA trigger/abort interrupt sources (supported only for few parts). Members Members Description DMA_INT_ADDRESS_ERROR Channel address error interrupt DMA_INT_TRANSFER_ABORT channel transfer abort interrupt DMA_INT_CELL_TRANSFER_COMPLETE channel cell transfer complete DMA_INT_BLOCK_TRANSFER_COMPLETE Channel block transfer complete DMA_INT_DESTINATION_HALF_FULL Channel destination half full interrupt DMA_INT_DESTINATION_DONE Channel destination done interrupt DMA_INT_SOURCE_HALF_EMPTY Channel source half empty interrupt DMA_INT_SOURCE_DONE Channel source done interrupt DMA_INT_COUNT_HALF_DONE DMA count has reached its halfway DMA_INT_CHANNEL_OVERRUN channel overrun. channel is triggered while it is still completing the operation based on the previous trigger DMA_INT_COMPLETE DMA complete operation interrupt DMA_INT_LOW_ADDRESS_LIMIT DMA low address limit interrupt DMA_INT_HIGH_ADDRESS_LIMIT DMA high address limit interrupt Remarks Not to be confused with the DMA trigger/abort interrupt sources (supported only for few parts). This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.14 DMA_MODULE_ID Enumeration C typedef enum { DMA_ID_0 } DMA_MODULE_ID; Description DMA module ID This data type defines the possible instances of the DMA module. Members Members Description DMA_ID_0 first instance of the DMA Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.15 DMA_PATTERN_LENGTH Enumeration C typedef enum { DMA_PATTERN_MATCH_LENGTH_1BYTE, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1827 DMA_PATTERN_MATCH_LENGTH_2BYTES } DMA_PATTERN_LENGTH; Description DMA pattern length This enumeration gives the length of the pattern to be matched with CHPIGN<7:0> in DCHxCON<31:24. Members Members Description DMA_PATTERN_MATCH_LENGTH_1BYTE The Length of matching pattern with CHPIGN<7:0> in DCHxCON<31:24> is 1 BYTE DMA_PATTERN_MATCH_LENGTH_2BYTES The Length of matching pattern with CHPIGN<7:0> in DCHxCON<31:24> is 2 BYTES Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.16 DMA_PING_PONG_MODE Enumeration C typedef enum { DMA_PING_PONG_PRIMARY, DMA_PING_PONG_SECONDARY } DMA_PING_PONG_MODE; Description DMA PING-PONG modes This enumeration lists all the possible ping-pong modes. Members Members Description DMA_PING_PONG_PRIMARY DMAxSTA is selected in the ping-pong mode DMA_PING_PONG_SECONDARY DMAxSTB is selected in the ping-pong mode Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.17 DMA_SOURCE_ADDRESSING_MODE Enumeration C typedef enum { DMA_ADDRESSING_SOURCE_UNCHANGED, DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE, DMA_ADDRESSING_SOURCE_DECREMENT_BASED_ON_SIZE, DMA_ADDRESSING_SOURCE_PERIPHERAL_INDIRECT } DMA_SOURCE_ADDRESSING_MODE; Description DMA source addressing modes This enumeration lists all the possible source addressing modes. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1828 Members Members Description DMA_ADDRESSING_SOURCE_UNCHANGED DMASRC remains unchanged after a transfer completion DMA_ADDRESSING_SOURCE_INCREMENT_BASED_ON_SIZE DMASRC is incremented based on SIZE bit after a transfer completion DMA_ADDRESSING_SOURCE_DECREMENT_BASED_ON_SIZE DMASRC is decremented based on SIZE bit after a transfer completion DMA_ADDRESSING_SOURCE_PERIPHERAL_INDIRECT DMASRC is used in peripheral indirect addressing and remains unchanged Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.18 DMA_TRANSFER_MODE Enumeration C typedef enum { DMA_MODE_ONE_SHOT, DMA_MODE_REPEATED_ONE_SHOT, DMA_MODE_CONTINUOUS, DMA_MODE_REPEATED_CONTINUOUS, DMA_MODE_ONE_SHOT_PING_PONG_ENABLED, DMA_MODE_ONE_SHOT_PING_PONG_DISABLED, DMA_MODE_CONTINUOUS_PING_PONG_DISABLED, DMA_MODE_CONTINUOUS_PING_PONG_ENABLED } DMA_TRANSFER_MODE; Description DMA transfer/operating mode This enumeration lists the possible DMA transfer/operating modes. Members Members Description DMA_MODE_ONE_SHOT one-shot transfer DMA_MODE_REPEATED_ONE_SHOT repeated one-shot transfer DMA_MODE_CONTINUOUS continuous transfer DMA_MODE_REPEATED_CONTINUOUS repeated continuous transfer DMA_MODE_ONE_SHOT_PING_PONG_ENABLED one-shot transfer with ping-pong buffers DMA_MODE_ONE_SHOT_PING_PONG_DISABLED one-shot transfer without the ping-pong buffers DMA_MODE_CONTINUOUS_PING_PONG_DISABLED continuous transfer without the ping-pong buffers DMA_MODE_CONTINUOUS_PING_PONG_ENABLED continuous transfer with ping-pong buffers Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.12.19 DMA_TRIGGER_SOURCE Enumeration C typedef enum { DMA_TRIGGER_TIMER_CORE, DMA_TRIGGER_SOFTWARE_0, DMA_TRIGGER_SOFTWARE_1, 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1829 DMA_TRIGGER_EXTERNAL_0 , DMA_TRIGGER_EXTERNAL_1 , DMA_TRIGGER_EXTERNAL_2 , DMA_TRIGGER_EXTERNAL_3 , DMA_TRIGGER_EXTERNAL_4 , DMA_TRIGGER_TIMER_1 , DMA_TRIGGER_TIMER_2 , DMA_TRIGGER_TIMER_3 , DMA_TRIGGER_TIMER_4 , DMA_TRIGGER_TIMER_5 , DMA_TRIGGER_INPUT_CAPTURE_1 , DMA_TRIGGER_INPUT_CAPTURE_2 , DMA_TRIGGER_INPUT_CAPTURE_3 , DMA_TRIGGER_INPUT_CAPTURE_4 , DMA_TRIGGER_INPUT_CAPTURE_5 , DMA_TRIGGER_INPUT_CAPTURE_1_ERROR , DMA_TRIGGER_INPUT_CAPTURE_2_ERROR , DMA_TRIGGER_INPUT_CAPTURE_3_ERROR , DMA_TRIGGER_INPUT_CAPTURE_4_ERROR , DMA_TRIGGER_INPUT_CAPTURE_5_ERROR , DMA_TRIGGER_OUTPUT_COMPARE_1 , DMA_TRIGGER_OUTPUT_COMPARE_2 , DMA_TRIGGER_OUTPUT_COMPARE_3 , DMA_TRIGGER_OUTPUT_COMPARE_4 , DMA_TRIGGER_OUTPUT_COMPARE_5 , DMA_TRIGGER_SPI_1_ERROR , DMA_TRIGGER_SPI_1_RECEIVE , DMA_TRIGGER_SPI_1_TRANSMIT , DMA_TRIGGER_SPI_1A_ERROR , DMA_TRIGGER_SPI_1A_RECEIVE , DMA_TRIGGER_SPI_1A_TRANSMIT , DMA_TRIGGER_SPI_2_ERROR , DMA_TRIGGER_SPI_2_RECEIVE , DMA_TRIGGER_SPI_2_TRANSMIT , DMA_TRIGGER_SPI_2A_ERROR , DMA_TRIGGER_SPI_2A_RECEIVE , DMA_TRIGGER_SPI_2A_TRANSMIT , DMA_TRIGGER_SPI_3_ERROR , DMA_TRIGGER_SPI_3_RECEIVE , DMA_TRIGGER_SPI_3_TRANSMIT , DMA_TRIGGER_SPI_3A_ERROR , DMA_TRIGGER_SPI_3A_RECEIVE , DMA_TRIGGER_SPI_3A_TRANSMIT , DMA_TRIGGER_SPI_4_ERROR , DMA_TRIGGER_SPI_4_RECEIVE , DMA_TRIGGER_SPI_4_TRANSMIT , DMA_TRIGGER_I2C_1_ERROR , DMA_TRIGGER_I2C_1_SLAVE , DMA_TRIGGER_I2C_1_MASTER , DMA_TRIGGER_I2C_1A_ERROR , DMA_TRIGGER_I2C_1A_SLAVE , DMA_TRIGGER_I2C_1A_MASTER , DMA_TRIGGER_I2C_2_ERROR , DMA_TRIGGER_I2C_2_SLAVE , DMA_TRIGGER_I2C_2_MASTER , DMA_TRIGGER_I2C_2A_ERROR , DMA_TRIGGER_I2C_2A_SLAVE , DMA_TRIGGER_I2C_2A_MASTER , DMA_TRIGGER_I2C_3_ERROR , DMA_TRIGGER_I2C_3_SLAVE , DMA_TRIGGER_I2C_3_MASTER , DMA_TRIGGER_I2C_3A_ERROR , DMA_TRIGGER_I2C_3A_SLAVE , DMA_TRIGGER_I2C_3A_MASTER , DMA_TRIGGER_I2C_4_ERROR , DMA_TRIGGER_I2C_4_SLAVE , 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1830 DMA_TRIGGER_I2C_4_MASTER , DMA_TRIGGER_I2C_5_ERROR , DMA_TRIGGER_I2C_5_SLAVE , DMA_TRIGGER_I2C_5_MASTER , DMA_TRIGGER_USART_1_ERROR , DMA_TRIGGER_USART_1_RECEIVE , DMA_TRIGGER_USART_1_TRANSMIT , DMA_TRIGGER_USART_1A_ERROR , DMA_TRIGGER_USART_1A_RECEIVE , DMA_TRIGGER_USART_1A_TRANSMIT , DMA_TRIGGER_USART_1B_ERROR , DMA_TRIGGER_USART_1B_RECEIVE , DMA_TRIGGER_USART_1B_TRANSMIT , DMA_TRIGGER_USART_2_ERROR , DMA_TRIGGER_USART_2_RECEIVE , DMA_TRIGGER_USART_2_TRANSMIT , DMA_TRIGGER_USART_2A_ERROR , DMA_TRIGGER_USART_2A_RECEIVE , DMA_TRIGGER_USART_2A_TRANSMIT , DMA_TRIGGER_USART_2B_ERROR , DMA_TRIGGER_USART_2B_RECEIVE , DMA_TRIGGER_USART_2B_TRANSMIT , DMA_TRIGGER_USART_3_ERROR , DMA_TRIGGER_USART_3_RECEIVE , DMA_TRIGGER_USART_3_TRANSMIT , DMA_TRIGGER_USART_3A_ERROR , DMA_TRIGGER_USART_3A_RECEIVE , DMA_TRIGGER_USART_3A_TRANSMIT , DMA_TRIGGER_USART_3B_ERROR , DMA_TRIGGER_USART_3B_RECEIVE , DMA_TRIGGER_USART_3B_TRANSMIT , DMA_TRIGGER_USART_4_ERROR , DMA_TRIGGER_USART_4_RECEIVE , DMA_TRIGGER_USART_4_TRANSMIT , DMA_TRIGGER_USART_5_ERROR , DMA_TRIGGER_USART_5_RECEIVE , DMA_TRIGGER_USART_5_TRANSMIT , DMA_TRIGGER_USART_6_ERROR , DMA_TRIGGER_USART_6_RECEIVE , DMA_TRIGGER_USART_6_TRANSMIT , DMA_TRIGGER_CHANGE_NOTICE , DMA_TRIGGER_CHANGE_NOTICE_A , DMA_TRIGGER_CHANGE_NOTICE_B , DMA_TRIGGER_CHANGE_NOTICE_C , DMA_TRIGGER_CHANGE_NOTICE_D , DMA_TRIGGER_CHANGE_NOTICE_E , DMA_TRIGGER_CHANGE_NOTICE_F , DMA_TRIGGER_CHANGE_NOTICE_G , DMA_TRIGGER_DMA_0 , DMA_TRIGGER_DMA_1 , DMA_TRIGGER_DMA_2 , DMA_TRIGGER_DMA_3 , DMA_TRIGGER_DMA_4 , DMA_TRIGGER_DMA_5 , DMA_TRIGGER_DMA_6 , DMA_TRIGGER_DMA_7 , DMA_TRIGGER_COMPARATOR_1 , DMA_TRIGGER_COMPARATOR_2 , DMA_TRIGGER_COMPARATOR_3 , DMA_TRIGGER_ADC_1 , DMA_TRIGGER_PARALLEL_PORT , DMA_TRIGGER_CAN_1 , DMA_TRIGGER_CAN_2 , DMA_TRIGGER_CLOCK_MONITOR , DMA_TRIGGER_RTCC , DMA_TRIGGER_FLASH_CONTROL , 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1831 DMA_TRIGGER_USB_1, DMA_TRIGGER_ETH_1, DMA_TRIGGER_PARALLEL_PORT_ERROR, DMA_TRIGGER_CTMU } DMA_TRIGGER_SOURCE; Description DMA trigger sources This enumeration lists all the possible DMA trigger sources. Members Members Description DMA_TRIGGER_TIMER_CORE Core timer DMA_TRIGGER_SOFTWARE_0 Software 0 DMA_TRIGGER_SOFTWARE_1 Software 1 DMA_TRIGGER_EXTERNAL_0 External 0 DMA_TRIGGER_EXTERNAL_1 External 1 DMA_TRIGGER_EXTERNAL_2 External 2 DMA_TRIGGER_EXTERNAL_3 External 3 DMA_TRIGGER_EXTERNAL_4 External 4 DMA_TRIGGER_TIMER_1 Timer 1 DMA_TRIGGER_TIMER_2 Timer 2 DMA_TRIGGER_TIMER_3 Timer 3 DMA_TRIGGER_TIMER_4 Timer 4 DMA_TRIGGER_TIMER_5 Timer 5 DMA_TRIGGER_INPUT_CAPTURE_1 Input Capture 1 DMA_TRIGGER_INPUT_CAPTURE_2 Input Capture 2 DMA_TRIGGER_INPUT_CAPTURE_3 Input Capture 3 DMA_TRIGGER_INPUT_CAPTURE_4 Input Capture 4 DMA_TRIGGER_INPUT_CAPTURE_5 Input Capture 5 DMA_TRIGGER_INPUT_CAPTURE_1_ERROR Input Capture 1 error DMA_TRIGGER_INPUT_CAPTURE_2_ERROR Input Capture 2 error DMA_TRIGGER_INPUT_CAPTURE_3_ERROR Input Capture 3 error DMA_TRIGGER_INPUT_CAPTURE_4_ERROR Input Capture 4 error DMA_TRIGGER_INPUT_CAPTURE_5_ERROR Input Capture 5 error DMA_TRIGGER_OUTPUT_COMPARE_1 Output compare 1 DMA_TRIGGER_OUTPUT_COMPARE_2 Output compare 2 DMA_TRIGGER_OUTPUT_COMPARE_3 Output compare 3 DMA_TRIGGER_OUTPUT_COMPARE_4 Output compare 4 DMA_TRIGGER_OUTPUT_COMPARE_5 Output compare 5 DMA_TRIGGER_SPI_1_ERROR SPI 1 error DMA_TRIGGER_SPI_1_RECEIVE SPI 1 receive DMA_TRIGGER_SPI_1_TRANSMIT SPI 1 transmit DMA_TRIGGER_SPI_1A_ERROR SPI 1A error DMA_TRIGGER_SPI_1A_RECEIVE SPI 1A receive DMA_TRIGGER_SPI_1A_TRANSMIT SPI 1A transmit DMA_TRIGGER_SPI_2_ERROR SPI 2 erro DMA_TRIGGER_SPI_2_RECEIVE SPI 2 receive 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1832 DMA_TRIGGER_SPI_2_TRANSMIT SPI 2 transmit DMA_TRIGGER_SPI_2A_ERROR SPI 2A receive DMA_TRIGGER_SPI_2A_RECEIVE SPI 2A receive DMA_TRIGGER_SPI_2A_TRANSMIT SPI 2A transmit DMA_TRIGGER_SPI_3_ERROR SPI 3 error DMA_TRIGGER_SPI_3_RECEIVE SPI 3 receive DMA_TRIGGER_SPI_3_TRANSMIT SPI 3 transmit DMA_TRIGGER_SPI_3A_ERROR SPI 3A receive DMA_TRIGGER_SPI_3A_RECEIVE SPI 3A receive DMA_TRIGGER_SPI_3A_TRANSMIT SPI 3A receive DMA_TRIGGER_SPI_4_ERROR SPI 4 error DMA_TRIGGER_SPI_4_RECEIVE SPI 4 receive DMA_TRIGGER_SPI_4_TRANSMIT SPI 4 transmit DMA_TRIGGER_I2C_1_ERROR I2C 1 error DMA_TRIGGER_I2C_1_SLAVE I2C 1 slave DMA_TRIGGER_I2C_1_MASTER I2C 1 master DMA_TRIGGER_I2C_1A_ERROR I2C 1A error DMA_TRIGGER_I2C_1A_SLAVE I2C 1A slave DMA_TRIGGER_I2C_1A_MASTER I2C 1A master DMA_TRIGGER_I2C_2_ERROR I2C 2 error DMA_TRIGGER_I2C_2_SLAVE I2C 2 slave DMA_TRIGGER_I2C_2_MASTER I2C 2 master DMA_TRIGGER_I2C_2A_ERROR I2C 2A error DMA_TRIGGER_I2C_2A_SLAVE I2C 2A slave DMA_TRIGGER_I2C_2A_MASTER I2C 2A master DMA_TRIGGER_I2C_3_ERROR I2C 3 error DMA_TRIGGER_I2C_3_SLAVE I2C 3 slave DMA_TRIGGER_I2C_3_MASTER I2C 3 master DMA_TRIGGER_I2C_3A_ERROR I2C 3A error DMA_TRIGGER_I2C_3A_SLAVE I2C 3A slave DMA_TRIGGER_I2C_3A_MASTER I2C 3A master DMA_TRIGGER_I2C_4_ERROR I2C 4 error DMA_TRIGGER_I2C_4_SLAVE I2C 4 slave DMA_TRIGGER_I2C_4_MASTER I2C 4 master DMA_TRIGGER_I2C_5_ERROR I2C 5 error DMA_TRIGGER_I2C_5_SLAVE I2C 5 slave DMA_TRIGGER_I2C_5_MASTER I2C 5 master DMA_TRIGGER_USART_1_ERROR USART 1 error DMA_TRIGGER_USART_1_RECEIVE USART 1 receive DMA_TRIGGER_USART_1_TRANSMIT USART 1 transmit DMA_TRIGGER_USART_1A_ERROR USART 1A error DMA_TRIGGER_USART_1A_RECEIVE USART 1A receive DMA_TRIGGER_USART_1A_TRANSMIT USART 1A transmit DMA_TRIGGER_USART_1B_ERROR USART 1B error DMA_TRIGGER_USART_1B_RECEIVE USART 1B receive 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1833 DMA_TRIGGER_USART_1B_TRANSMIT USART 1B transmit DMA_TRIGGER_USART_2_ERROR USART 2 error DMA_TRIGGER_USART_2_RECEIVE USART 2 receive DMA_TRIGGER_USART_2_TRANSMIT USART 2 transmit DMA_TRIGGER_USART_2A_ERROR USART 2A error DMA_TRIGGER_USART_2A_RECEIVE USART 2A receive DMA_TRIGGER_USART_2A_TRANSMIT USART 2A transmit DMA_TRIGGER_USART_2B_ERROR USART 2B error DMA_TRIGGER_USART_2B_RECEIVE USART 2B receive DMA_TRIGGER_USART_2B_TRANSMIT USART 2B transmit DMA_TRIGGER_USART_3_ERROR USART 3 error DMA_TRIGGER_USART_3_RECEIVE USART 3 receive DMA_TRIGGER_USART_3_TRANSMIT USART 3 transmit DMA_TRIGGER_USART_3A_ERROR USART 3A error DMA_TRIGGER_USART_3A_RECEIVE USART 3A receive DMA_TRIGGER_USART_3A_TRANSMIT USART 3A transmit DMA_TRIGGER_USART_3B_ERROR USART 3B error DMA_TRIGGER_USART_3B_RECEIVE USART 3B receieve DMA_TRIGGER_USART_3B_TRANSMIT USART 3B transmit DMA_TRIGGER_USART_4_ERROR USART 4 error DMA_TRIGGER_USART_4_RECEIVE USART 3B receive DMA_TRIGGER_USART_4_TRANSMIT USART 4 transmit DMA_TRIGGER_USART_5_ERROR USART 5 error DMA_TRIGGER_USART_5_RECEIVE USART 5 receive DMA_TRIGGER_USART_5_TRANSMIT USART 5 transmit DMA_TRIGGER_USART_6_ERROR USART 6 error DMA_TRIGGER_USART_6_RECEIVE USART 6 receive DMA_TRIGGER_USART_6_TRANSMIT USART 6 transmit DMA_TRIGGER_CHANGE_NOTICE Change notice DMA_TRIGGER_CHANGE_NOTICE_A Change notice A DMA_TRIGGER_CHANGE_NOTICE_B Change notice B DMA_TRIGGER_CHANGE_NOTICE_C Change notice C DMA_TRIGGER_CHANGE_NOTICE_D Change notice D DMA_TRIGGER_CHANGE_NOTICE_E Change notice E DMA_TRIGGER_CHANGE_NOTICE_F Change notice F DMA_TRIGGER_CHANGE_NOTICE_G Change notice G DMA_TRIGGER_DMA_0 DMA Channel 0 DMA_TRIGGER_DMA_1 DMA Channel 1 DMA_TRIGGER_DMA_2 DMA Channel 2 DMA_TRIGGER_DMA_3 DMA Channel 3 DMA_TRIGGER_DMA_4 DMA Channel 4 DMA_TRIGGER_DMA_5 DMA Channel 5 DMA_TRIGGER_DMA_6 DMA Channel 6 DMA_TRIGGER_DMA_7 DMA Channel 7 DMA_TRIGGER_COMPARATOR_1 Comparator 1 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1834 DMA_TRIGGER_COMPARATOR_2 DMA Channel 2 DMA_TRIGGER_COMPARATOR_3 DMA Channel 3 DMA_TRIGGER_ADC_1 ADC 1 DMA_TRIGGER_PARALLEL_PORT Parallel port DMA_TRIGGER_CAN_1 CAN 1 DMA_TRIGGER_CAN_2 CAN 2 DMA_TRIGGER_CLOCK_MONITOR Clock monitor DMA_TRIGGER_RTCC RTCC DMA_TRIGGER_FLASH_CONTROL Flash control DMA_TRIGGER_USB_1 USB 1 DMA_TRIGGER_ETH_1 ETH 1 DMA_TRIGGER_PARALLEL_PORT_ERROR Parallel port error DMA_TRIGGER_CTMU CTMU Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.6.6.13 Feature Existence Routines 5.6.6.6.13.1 PLIB_DMA_ExistsAbortTransfer Function C bool PLIB_DMA_ExistsAbortTransfer( DMA_MODULE_ID index ); Description This function identifies whether the AbortTransfer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_AbortTransferSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AbortTransfer feature is supported on the device • false - The AbortTransfer feature is not supported on the device Remarks None. 5.6.6.6.13.2 PLIB_DMA_ExistsBusy Function C bool PLIB_DMA_ExistsBusy( 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1835 DMA_MODULE_ID index ); Description This function identifies whether the Busy feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_BusyActiveSet • PLIB_DMA_BusyActiveReset • PLIB_DMA_IsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Busy feature is supported on the device • false - The Busy feature is not supported on the device Remarks None. 5.6.6.6.13.3 PLIB_DMA_ExistsChannelBits Function C bool PLIB_DMA_ExistsChannelBits( DMA_MODULE_ID index ); Description This function identifies whether the ChannelBits feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelBitsGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelBits feature is supported on the device • false - The ChannelBits feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1836 5.6.6.6.13.4 PLIB_DMA_ExistsChannelX Function C bool PLIB_DMA_ExistsChannelX( DMA_MODULE_ID index ); Description This function identifies whether the ChannelX feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXEnable • PLIB_DMA_ChannelXIsEnabled • PLIB_DMA_ChannelXDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelX feature is supported on the device • false - The ChannelX feature is not supported on the device Remarks None. 5.6.6.6.13.5 PLIB_DMA_ExistsChannelXAbortIRQ Function C bool PLIB_DMA_ExistsChannelXAbortIRQ( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXAbortIRQ feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXAbortIRQSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXAbortIRQ feature is supported on the device • false - The ChannelXAbortIRQ feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1837 Remarks None. 5.6.6.6.13.6 PLIB_DMA_ExistsChannelXAuto Function C bool PLIB_DMA_ExistsChannelXAuto( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXAuto feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXAutoEnable • PLIB_DMA_ChannelXAutoDisable • PLIB_DMA_ChannelXAutoIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXAuto feature is supported on the device • false - The ChannelXAuto feature is not supported on the device Remarks None. 5.6.6.6.13.7 PLIB_DMA_ExistsChannelXBusy Function C bool PLIB_DMA_ExistsChannelXBusy( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXBusy feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXBusyActiveSet • PLIB_DMA_ChannelXBusyInActiveSet • PLIB_DMA_ChannelXBusyIsBusy Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1838 Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXBusy feature is supported on the device • false - The ChannelXBusy feature is not supported on the device Remarks None. 5.6.6.6.13.8 PLIB_DMA_ExistsChannelXCellProgressPointer Function C bool PLIB_DMA_ExistsChannelXCellProgressPointer( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXCellProgressPointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXCellProgressPointerGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXCellProgressPointer feature is supported on the device • false - The ChannelXCellProgressPointer feature is not supported on the device Remarks None. 5.6.6.6.13.9 PLIB_DMA_ExistsChannelXCellSize Function C bool PLIB_DMA_ExistsChannelXCellSize( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXCellSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXCellSizeGet • PLIB_DMA_ChannelXCellSizeSet 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1839 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXCellSize feature is supported on the device • false - The ChannelXCellSize feature is not supported on the device Remarks None. 5.6.6.6.13.10 PLIB_DMA_ExistsChannelXChain Function C bool PLIB_DMA_ExistsChannelXChain( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXChain feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXChainToLower • PLIB_DMA_ChannelXChainToHigher Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXChain feature is supported on the device • false - The ChannelXChain feature is not supported on the device Remarks None. 5.6.6.6.13.11 PLIB_DMA_ExistsChannelXChainEnbl Function C bool PLIB_DMA_ExistsChannelXChainEnbl( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXChainEnbl feature is available on the DMA module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1840 • PLIB_DMA_ChannelXChainEnable • PLIB_DMA_ChannelXChainDisable • PLIB_DMA_ChannelXChainIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXChainEnbl feature is supported on the device • false - The ChannelXChainEnbl feature is not supported on the device Remarks None. 5.6.6.6.13.12 PLIB_DMA_ExistsChannelXDestinationPointer Function C bool PLIB_DMA_ExistsChannelXDestinationPointer( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXDestinationPointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXDestinationPointerGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXDestinationPointer feature is supported on the device • false - The ChannelXDestinationPointer feature is not supported on the device Remarks None. 5.6.6.6.13.13 PLIB_DMA_ExistsChannelXDestinationSize Function C bool PLIB_DMA_ExistsChannelXDestinationSize( DMA_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1841 Description This function identifies whether the ChannelXDestinationSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDestinationSizeGet • PLIB_DMA_ChannelXDestinationSizeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXDestinationSize feature is supported on the device • false - The ChannelXDestinationSize feature is not supported on the device Remarks None. 5.6.6.6.13.14 PLIB_DMA_ExistsChannelXDestinationStartAddress Function C bool PLIB_DMA_ExistsChannelXDestinationStartAddress( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXDestinationStartAddress feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDestinationStartAddressGet • PLIB_DMA_ChannelXDestinationStartAddressSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXDestinationStartAddress feature is supported on the device • false - The ChannelXDestinationStartAddress feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1842 5.6.6.6.13.15 PLIB_DMA_ExistsChannelXDisabled Function C bool PLIB_DMA_ExistsChannelXDisabled( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXDisabled feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXDisabledEnablesEvents • PLIB_DMA_ChannelXDisabledDisablesEvents Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXDisabled feature is supported on the device • false - The ChannelXDisabled feature is not supported on the device Remarks None. 5.6.6.6.13.16 PLIB_DMA_ExistsChannelXEvent Function C bool PLIB_DMA_ExistsChannelXEvent( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXEvent feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXEventIsDetected Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXEvent feature is supported on the device • false - The ChannelXEvent feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1843 5.6.6.6.13.17 PLIB_DMA_ExistsChannelXINTSource Function C bool PLIB_DMA_ExistsChannelXINTSource( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXINTSource feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXINTSourceEnable • PLIB_DMA_ChannelXINTSourceDisable • PLIB_DMA_ChannelXINTSourceIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXINTSource feature is supported on the device • false - The ChannelXINTSource feature is not supported on the device Remarks None. 5.6.6.6.13.18 PLIB_DMA_ExistsChannelXINTSourceFlag Function C bool PLIB_DMA_ExistsChannelXINTSourceFlag( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXINTSourceFlag feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXINTSourceFlagGet • PLIB_DMA_ChannelXINTSourceFlagSet • PLIB_DMA_ChannelXINTSourceFlagClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXINTSourceFlag feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1844 • false - The ChannelXINTSourceFlag feature is not supported on the device Remarks None. 5.6.6.6.13.19 PLIB_DMA_ExistsChannelXPatternData Function C bool PLIB_DMA_ExistsChannelXPatternData( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXPatternData feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternDataGet • PLIB_DMA_ChannelXPatternDataSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXPatternData feature is supported on the device • false - The ChannelXPatternData feature is not supported on the device Remarks None. 5.6.6.6.13.20 PLIB_DMA_ExistsChannelXPatternIgnore Function C bool PLIB_DMA_ExistsChannelXPatternIgnore( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXPatternIgnore feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternIgnoreSet • PLIB_DMA_ChannelXPatternIgnoreGet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1845 Returns • true - The ChannelXPatternIgnore feature is supported on the device • false - The ChannelXPatternIgnore feature is not supported on the device Remarks None. 5.6.6.6.13.21 PLIB_DMA_ExistsChannelXPatternIgnoreByte Function C bool PLIB_DMA_ExistsChannelXPatternIgnoreByte( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXPatternIgnoreByte feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternIgnoreByteEnable • PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled • PLIB_DMA_ChannelXPatternIgnoreByteDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXPatternIgnoreByte feature is supported on the device • false - The ChannelXPatternIgnoreByte feature is not supported on the device Remarks None. 5.6.6.6.13.22 PLIB_DMA_ExistsChannelXPatternLength Function C bool PLIB_DMA_ExistsChannelXPatternLength( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXPatternLength feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPatternLengthSet • PLIB_DMA_ChannelXPatternLengthGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1846 Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXPatternLength feature is supported on the device • false - The ChannelXPatternLength feature is not supported on the device Remarks None. 5.6.6.6.13.23 PLIB_DMA_ExistsChannelXPriority Function C bool PLIB_DMA_ExistsChannelXPriority( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXPriority feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXPrioritySelect • PLIB_DMA_ChannelXPriorityGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXPriority feature is supported on the device • false - The ChannelXPriority feature is not supported on the device Remarks None. 5.6.6.6.13.24 PLIB_DMA_ExistsChannelXSourcePointer Function C bool PLIB_DMA_ExistsChannelXSourcePointer( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXSourcePointer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXSourcePointerGet 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1847 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXSourcePointer feature is supported on the device • false - The ChannelXSourcePointer feature is not supported on the device Remarks None. 5.6.6.6.13.25 PLIB_DMA_ExistsChannelXSourceSize Function C bool PLIB_DMA_ExistsChannelXSourceSize( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXSourceSize feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_ChannelXSourceSizeGet • PLIB_DMA_ChannelXSourceSizeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXSourceSize feature is supported on the device • false - The ChannelXSourceSize feature is not supported on the device Remarks None. 5.6.6.6.13.26 PLIB_DMA_ExistsChannelXSourceStartAddress Function C bool PLIB_DMA_ExistsChannelXSourceStartAddress( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXSourceStartAddress feature is available on the DMA module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1848 • PLIB_DMA_ChannelXSourceStartAddressGet • PLIB_DMA_ChannelXSourceStartAddressSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXSourceStartAddress feature is supported on the device • false - The ChannelXSourceStartAddress feature is not supported on the device Remarks None. 5.6.6.6.13.27 PLIB_DMA_ExistsChannelXStartIRQ Function C bool PLIB_DMA_ExistsChannelXStartIRQ( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXStartIRQ feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_ChannelXStartIRQSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXStartIRQ feature is supported on the device • false - The ChannelXStartIRQ feature is not supported on the device Remarks None. 5.6.6.6.13.28 PLIB_DMA_ExistsChannelXTrigger Function C bool PLIB_DMA_ExistsChannelXTrigger( DMA_MODULE_ID index ); Description This function identifies whether the ChannelXTrigger feature is available on the DMA module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1849 • PLIB_DMA_ChannelXTriggerEnable • PLIB_DMA_ChannelXTriggerIsEnabled • PLIB_DMA_ChannelXTriggerDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChannelXTrigger feature is supported on the device • false - The ChannelXTrigger feature is not supported on the device Remarks None. 5.6.6.6.13.29 PLIB_DMA_ExistsCRC Function C bool PLIB_DMA_ExistsCRC( DMA_MODULE_ID index ); Description This function identifies whether the CRC feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCEnable • PLIB_DMA_CRCDisable • PLIB_DMA_CRCIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRC feature is supported on the device • false - The CRC feature is not supported on the device Remarks None. 5.6.6.6.13.30 PLIB_DMA_ExistsCRCAppendMode Function C bool PLIB_DMA_ExistsCRCAppendMode( DMA_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1850 Description This function identifies whether the CRCAppendMode feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCAppendModeEnable • PLIB_DMA_CRCAppendModeDisable • PLIB_DMA_CRCAppendModeIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCAppendMode feature is supported on the device • false - The CRCAppendMode feature is not supported on the device Remarks None. 5.6.6.6.13.31 PLIB_DMA_ExistsCRCBitOrder Function C bool PLIB_DMA_ExistsCRCBitOrder( DMA_MODULE_ID index ); Description This function identifies whether the CRCBitOrder feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_CRCBitOrderSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCBitOrder feature is supported on the device • false - The CRCBitOrder feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1851 5.6.6.6.13.32 PLIB_DMA_ExistsCRCByteOrder Function C bool PLIB_DMA_ExistsCRCByteOrder( DMA_MODULE_ID index ); Description This function identifies whether the CRCByteOrder feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCByteOrderSelect • PLIB_DMA_CRCByteOrderGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCByteOrder feature is supported on the device • false - The CRCByteOrder feature is not supported on the device Remarks None. 5.6.6.6.13.33 PLIB_DMA_ExistsCRCChannel Function C bool PLIB_DMA_ExistsCRCChannel( DMA_MODULE_ID index ); Description This function identifies whether the CRCChannel feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCChannelSelect • PLIB_DMA_CRCChannelGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCChannel feature is supported on the device • false - The CRCChannel feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1852 Remarks None. 5.6.6.6.13.34 PLIB_DMA_ExistsCRCData Function C bool PLIB_DMA_ExistsCRCData( DMA_MODULE_ID index ); Description This function identifies whether the CRCData feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCDataRead • PLIB_DMA_CRCDataWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCData feature is supported on the device • false - The CRCData feature is not supported on the device Remarks None. 5.6.6.6.13.35 PLIB_DMA_ExistsCRCPolynomialLength Function C bool PLIB_DMA_ExistsCRCPolynomialLength( DMA_MODULE_ID index ); Description This function identifies whether the CRCPolynomialLength feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCPolynomialLengthSet • PLIB_DMA_CRCPolynomialLengthGet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1853 Returns • true - The CRCPolynomialLength feature is supported on the device • false - The CRCPolynomialLength feature is not supported on the device Remarks None. 5.6.6.6.13.36 PLIB_DMA_ExistsCRCType Function C bool PLIB_DMA_ExistsCRCType( DMA_MODULE_ID index ); Description This function identifies whether the CRCType feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCTypeGet • PLIB_DMA_CRCTypeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCType feature is supported on the device • false - The CRCType feature is not supported on the device Remarks None. 5.6.6.6.13.37 PLIB_DMA_ExistsCRCWriteByteOrder Function C bool PLIB_DMA_ExistsCRCWriteByteOrder( DMA_MODULE_ID index ); Description This function identifies whether the CRCWriteByteOrder feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCWriteByteOrderAlter • PLIB_DMA_CRCWriteByteOrderMaintain Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1854 Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCWriteByteOrder feature is supported on the device • false - The CRCWriteByteOrder feature is not supported on the device Remarks None. 5.6.6.6.13.38 PLIB_DMA_ExistsCRCXOREnable Function C bool PLIB_DMA_ExistsCRCXOREnable( DMA_MODULE_ID index ); Description This function identifies whether the CRCXOREnable feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_CRCXOREnableSet • PLIB_DMA_CRCXOREnableGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CRCXOREnable feature is supported on the device • false - The CRCXOREnable feature is not supported on the device Remarks None. 5.6.6.6.13.39 PLIB_DMA_ExistsEnableControl Function C bool PLIB_DMA_ExistsEnableControl( DMA_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_Enable • PLIB_DMA_Disable 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1855 • PLIB_DMA_IsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.6.6.13.40 PLIB_DMA_ExistsLastBusAccess Function C bool PLIB_DMA_ExistsLastBusAccess( DMA_MODULE_ID index ); Description This function identifies whether the LastBusAccess feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_LastBusAccessIsRead • PLIB_DMA_LastBusAccessIsWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LastBusAccess feature is supported on the device • false - The LastBusAccess feature is not supported on the device Remarks None. 5.6.6.6.13.41 PLIB_DMA_ExistsRecentAddress Function C bool PLIB_DMA_ExistsRecentAddress( DMA_MODULE_ID index ); Description This function identifies whether the RecentAddress feature is available on the DMA module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1856 • PLIB_DMA_RecentAddressAccessed Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RecentAddress feature is supported on the device • false - The RecentAddress feature is not supported on the device Remarks None. 5.6.6.6.13.42 PLIB_DMA_ExistsStartTransfer Function C bool PLIB_DMA_ExistsStartTransfer( DMA_MODULE_ID index ); Description This function identifies whether the StartTransfer feature is available on the DMA module. When this function returns true, this function is supported on the device: • PLIB_DMA_StartTransferSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StartTransfer feature is supported on the device • false - The StartTransfer feature is not supported on the device Remarks None. 5.6.6.6.13.43 PLIB_DMA_ExistsStopInIdle Function C bool PLIB_DMA_ExistsStopInIdle( DMA_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_StopInIdleEnable 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1857 • PLIB_DMA_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.6.6.13.44 PLIB_DMA_ExistsSuspend Function C bool PLIB_DMA_ExistsSuspend( DMA_MODULE_ID index ); Description This function identifies whether the Suspend feature is available on the DMA module. When this function returns true, these functions are supported on the device: • PLIB_DMA_SuspendEnable • PLIB_DMA_SuspendDisable • PLIB_DMA_SuspendIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Suspend feature is supported on the device • false - The Suspend feature is not supported on the device Remarks None. 5.6.6.7 Files Files Name Description plib_dma.h Defines the DMA Peripheral Library interface functions. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1858 Description 5.6.6.7.1 plib_dma.h DMA Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Direct Memory Access (DMA) Periheral Library for Microchip microcontrollers. The definitions in this file are for the DMA module. Functions Name Description PLIB_DMA_AbortTransferSet Aborts transfer on the specified channel. PLIB_DMA_BusyActiveReset Resets the BUSY bit of the DMA controller. PLIB_DMA_BusyActiveSet Sets the BUSY bit of the DMA controller. PLIB_DMA_ChannelBitsGet Returns the DMA channel bits. PLIB_DMA_ChannelPriorityGet Gets the priority scheme of the DMA channels. PLIB_DMA_ChannelPrioritySelect Sets the priority scheme of the DMA channels. PLIB_DMA_ChannelXAbortIRQSet Sets the IRQ to abort the DMA transfer on the specified channel. PLIB_DMA_ChannelXAddressModeGet Gets the channel address mode. PLIB_DMA_ChannelXAddressModeSelect Sets the channel address mode. PLIB_DMA_ChannelXAutoDisable Channel is disabled after a block transfer is complete. PLIB_DMA_ChannelXAutoEnable Channel is continuously enabled. PLIB_DMA_ChannelXAutoIsEnabled Returns the channel automatic enable status. PLIB_DMA_ChannelXBufferedDataIsWritten Returns the buffered data write status for the specified channel. PLIB_DMA_ChannelXBusyActiveSet Sets the Busy bit to active. PLIB_DMA_ChannelXBusyInActiveSet Sets the Busy bit to inactive. PLIB_DMA_ChannelXBusyIsBusy Returns the busy status of the specified channel. PLIB_DMA_ChannelXCellProgressPointerGet Returns the number of bytes transferred since the last event. PLIB_DMA_ChannelXCellSizeGet Reads the cell size (in bytes) configured for the specified channel. PLIB_DMA_ChannelXCellSizeSet Writes the specified cell size into the register corresponding to the specified channel. PLIB_DMA_ChannelXChainDisable Disables the channel chaining for the specified DMA channel. PLIB_DMA_ChannelXChainEnable Channel chain feature is enabled. PLIB_DMA_ChannelXChainIsEnabled Returns the chain status of the specified channel. PLIB_DMA_ChannelXChainToHigher Chains the specified channel to a channel higher in natural priority. PLIB_DMA_ChannelXChainToLower Chains the specified channel to a channel lower in natural priority. PLIB_DMA_ChannelXCollisionStatus Returns the status of the specified collison type for the specified channel. PLIB_DMA_ChannelXDataSizeGet Returns the current data size for the specified channel. PLIB_DMA_ChannelXDataSizeSelect Selects the data size for the specified channel. PLIB_DMA_ChannelXDestinationAddressModeGet Gets the source address mode of the specified channel. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1859 PLIB_DMA_ChannelXDestinationAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXDestinationPointerGet Reads the current byte of the destination being pointed to for the specified channel. PLIB_DMA_ChannelXDestinationSizeGet Reads the destination size configured for the specified channel. PLIB_DMA_ChannelXDestinationSizeSet Writes the specified destination size into the register corresponding to the specified channel. PLIB_DMA_ChannelXDestinationStartAddressGet Reads the destination start address configured for the specified channel. PLIB_DMA_ChannelXDestinationStartAddressSet Writes the specified destination start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXDisable Disable the specified channel. PLIB_DMA_ChannelXDisabledDisablesEvents Channel start/abort events will be ignored even if the channel is disabled. PLIB_DMA_ChannelXDisabledEnablesEvents Channel start/abort events will be registered even if the channel is disabled. PLIB_DMA_ChannelXEnable Enable the specified channel. PLIB_DMA_ChannelXEventIsDetected Returns the event status on the specified channel. PLIB_DMA_ChannelXINTSourceDisable Disables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceEnable Enables the specified interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagClear Clears the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagGet Returns the status of the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceFlagSet Sets the interrupt flag of the specified DMA interrupt source for the specified channel. PLIB_DMA_ChannelXINTSourceIsEnabled Returns the enable status of the specified interrupt source for the specified channel. PLIB_DMA_ChannelXIsEnabled Return the enable status of the specified channel. PLIB_DMA_ChannelXNullWriteModeDisable Disables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeEnable Enables the Null Write mode. PLIB_DMA_ChannelXNullWriteModeIsEnabled Returns the enable status of the Null Write mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeGet Returns the current transfer/operating mode for the specified channel. PLIB_DMA_ChannelXOperatingTransferModeSelect Selects the transfer/operating mode for the specified channel. PLIB_DMA_ChannelXPatternDataGet Returns the pattern matching (for DMA abort) data programmed for the specified channel. PLIB_DMA_ChannelXPatternDataSet Writes the specified pattern matching data (for DMA abort) into the register corresponding to the specified channel. PLIB_DMA_ChannelXPatternIgnoreByteDisable Disables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteEnable Enables the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled Returns the state of the pattern match ignore byte. PLIB_DMA_ChannelXPatternIgnoreGet Returns the pattern match ignore value. PLIB_DMA_ChannelXPatternIgnoreSet Sets the pattern match ignore value. PLIB_DMA_ChannelXPatternLengthGet Returns the pattern match length. PLIB_DMA_ChannelXPatternLengthSet Sets the pattern match length. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1860 PLIB_DMA_ChannelXPeripheralAddressGet Gets the peripheral address configured for the specified channel. PLIB_DMA_ChannelXPeripheralAddressSet Sets the peripheral address for the specified channel. PLIB_DMA_ChannelXPingPongModeGet Returns the Ping-Pong mode status for the specified channel. PLIB_DMA_ChannelXPriorityGet Gets the priority of the specified channel. PLIB_DMA_ChannelXPrioritySelect Sets the priority of the specified channel. PLIB_DMA_ChannelXReloadDisable Disables reloading of the address and count registers. PLIB_DMA_ChannelXReloadEnable Enables reloading of the address and count registers. PLIB_DMA_ChannelXReloadIsEnabled Returns the address and count registers reload enable status. PLIB_DMA_ChannelXSourceAddressModeGet Gets the source address mode of the specified channel. PLIB_DMA_ChannelXSourceAddressModeSelect Sets the source address mode of the specified channel. PLIB_DMA_ChannelXSourcePointerGet Reads the current byte of the source being pointed to for the specified channel. PLIB_DMA_ChannelXSourceSizeGet Reads the source size configured for the specified channel. PLIB_DMA_ChannelXSourceSizeSet Writes the specified source size into the register corresponding to the specified channel. PLIB_DMA_ChannelXSourceStartAddressGet Reads the source start address configured for the specified channel. PLIB_DMA_ChannelXSourceStartAddressSet Writes the specified source start address into the register corresponding to the specified channel. PLIB_DMA_ChannelXStartAddressOffsetGet Gets the primary/secondary start address (DPSRAM) offset. PLIB_DMA_ChannelXStartAddressOffsetSet Sets the primary/secondary start address (DPSRAM) offset to the value specified depending on the offset type specified for the specified channel. PLIB_DMA_ChannelXStartIRQSet Sets the IRQ to initiate the DMA transfer on the specified channel. PLIB_DMA_ChannelXTransferCountGet Gets the DMA data transfer count that is programmed for the specified channel. PLIB_DMA_ChannelXTransferCountSet Sets the DMA data transfer count for the specified channel. PLIB_DMA_ChannelXTransferDirectionGet Returns the data transfer direction of the specified channel. PLIB_DMA_ChannelXTransferDirectionSelect Selects the data transfer direction of the specified channel. PLIB_DMA_ChannelXTriggerDisable Disables the DMA transfer abort via a matching interrupt (specified by the IRQ). PLIB_DMA_ChannelXTriggerEnable Enables the specified DMA channel trigger. PLIB_DMA_ChannelXTriggerIsEnabled Returns the enable status of the specified DMA transfer/abort trigger. PLIB_DMA_CRCAppendModeDisable Disables the CRC append mode. PLIB_DMA_CRCAppendModeEnable Enables the CRC append mode. PLIB_DMA_CRCAppendModeIsEnabled Gets the enable status of the CRC append mode. PLIB_DMA_CRCBitOrderSelect Selects the bit order for checksum caluculation. PLIB_DMA_CRCByteOrderGet Gets the current byte order selected by the DMA module CRC feature. PLIB_DMA_CRCByteOrderSelect Selects the byte order. PLIB_DMA_CRCChannelGet Returns the current DMA channel to which the CRC is assigned. PLIB_DMA_CRCChannelSelect Assignes the CRC to the specified DMA channel. PLIB_DMA_CRCDataRead Reads the contents of the DMA CRC data register. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1861 PLIB_DMA_CRCDataWrite Writes the contents of the DMA CRC data register with the specified data. PLIB_DMA_CRCDisable Disables the DMA module CRC feature. PLIB_DMA_CRCEnable Enables the DMA module CRC feature. PLIB_DMA_CRCIsEnabled Gets the enable status of the CRC feature. PLIB_DMA_CRCPolynomialLengthGet Gets the current polynomial length. PLIB_DMA_CRCPolynomialLengthSet Selects the polynomial length. PLIB_DMA_CRCTypeGet Gets the current DMA module CRC feature type. PLIB_DMA_CRCTypeSet Selects the DMA module CRC feature type. PLIB_DMA_CRCWriteByteOrderAlter The source data is written to the destination reordered as defined by the BYTO<1:0> bits. PLIB_DMA_CRCWriteByteOrderMaintain The source data is written to the destination unaltered. PLIB_DMA_CRCXOREnableGet Reads the CRC XOR register. PLIB_DMA_CRCXOREnableSet Writes to the CRC XOR enable register as per the specified enable mask. PLIB_DMA_Disable DMA module is disabled. PLIB_DMA_Enable DMA module is enabled. PLIB_DMA_ExistsAbortTransfer Identifies whether the AbortTransfer feature exists on the DMA module. PLIB_DMA_ExistsBusy Identifies whether the Busy feature exists on the DMA module. PLIB_DMA_ExistsChannelBits Identifies whether the ChannelBits feature exists on the DMA module. PLIB_DMA_ExistsChannelX Identifies whether the ChannelX feature exists on the DMA module. PLIB_DMA_ExistsChannelXAbortIRQ Identifies whether the ChannelXAbortIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXAuto Identifies whether the ChannelXAuto feature exists on the DMA module. PLIB_DMA_ExistsChannelXBusy Identifies whether the ChannelXBusy feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellProgressPointer Identifies whether the ChannelXCellProgressPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXCellSize Identifies whether the ChannelXCellSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXChain Identifies whether the ChannelXChain feature exists on the DMA module. PLIB_DMA_ExistsChannelXChainEnbl Identifies whether the ChannelXChainEnbl feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationPointer Identifies whether the ChannelXDestinationPointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationSize Identifies whether the ChannelXDestinationSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXDestinationStartAddress Identifies whether the ChannelXDestinationStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXDisabled Identifies whether the ChannelXDisabled feature exists on the DMA module. PLIB_DMA_ExistsChannelXEvent Identifies whether the ChannelXEvent feature exists on the DMA module. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1862 PLIB_DMA_ExistsChannelXINTSource Identifies whether the ChannelXINTSource feature exists on the DMA module. PLIB_DMA_ExistsChannelXINTSourceFlag Identifies whether the ChannelXINTSourceFlag feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternData Identifies whether the ChannelXPatternData feature exists on the DMA module PLIB_DMA_ExistsChannelXPatternIgnore Identifies whether the ChannelXPatternIgnore feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternIgnoreByte Identifies whether the ChannelXPatternIgnoreByte feature exists on the DMA module. PLIB_DMA_ExistsChannelXPatternLength Identifies whether the ChannelXPatternLength feature exists on the DMA module. PLIB_DMA_ExistsChannelXPriority Identifies whether the ChannelXPriority feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourcePointer Identifies whether the ChannelXSourcePointer feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceSize Identifies whether the ChannelXSourceSize feature exists on the DMA module. PLIB_DMA_ExistsChannelXSourceStartAddress Identifies whether the ChannelXSourceStartAddress feature exists on the DMA module. PLIB_DMA_ExistsChannelXStartIRQ Identifies whether the ChannelXStartIRQ feature exists on the DMA module. PLIB_DMA_ExistsChannelXTrigger Identifies whether the ChannelXTrigger feature exists on the DMA module. PLIB_DMA_ExistsCRC Identifies whether the CRC feature exists on the DMA module. PLIB_DMA_ExistsCRCAppendMode Identifies whether the CRCAppendMode feature exists on the DMA module. PLIB_DMA_ExistsCRCBitOrder Identifies whether the CRCBitOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCByteOrder Identifies whether the CRCByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCChannel Identifies whether the CRCChannel feature exists on the DMA module. PLIB_DMA_ExistsCRCData Identifies whether the CRCData feature exists on the DMA module. PLIB_DMA_ExistsCRCPolynomialLength Identifies whether the CRCPolynomialLength feature exists on the DMA module. PLIB_DMA_ExistsCRCType Identifies whether the CRCType feature exists on the DMA module. PLIB_DMA_ExistsCRCWriteByteOrder Identifies whether the CRCWriteByteOrder feature exists on the DMA module. PLIB_DMA_ExistsCRCXOREnable Identifies whether the CRCXOREnable feature exists on the DMA module. PLIB_DMA_ExistsEnableControl Identifies whether the EnableControl feature exists on the DMA module. PLIB_DMA_ExistsLastBusAccess Identifies whether the LastBusAccess feature exists on the DMA module. PLIB_DMA_ExistsRecentAddress Identifies whether the RecentAddress feature exists on the DMA module. PLIB_DMA_ExistsStartTransfer Identifies whether the StartTransfer feature exists on the DMA module. 5.6 Peripheral Library Help MPLAB Harmony Help DMA Peripheral Library Help 5-1863 PLIB_DMA_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the DMA module. PLIB_DMA_ExistsSuspend Identifies whether the Suspend feature exists on the DMA module. PLIB_DMA_IsBusy Gets the BUSY bit of the DMA controller. PLIB_DMA_IsEnabled Returns the DMA module enable status. PLIB_DMA_LastBusAccessIsRead Returns true if the last DMA bus access was a read. PLIB_DMA_LastBusAccessIsWrite Returns true if the last DMA bus access was a write. PLIB_DMA_LastChannelActive Returns the last DMA channel that participated in the data transfer. PLIB_DMA_RecentAddressAccessed Returns the address of the most recent DMA access. PLIB_DMA_StartTransferSet Initiates transfer on the specified channel. PLIB_DMA_StopInIdleDisable DMA transfers continue during Idle mode. PLIB_DMA_StopInIdleEnable DMA transfers are halted during Idle mode. PLIB_DMA_SuspendDisable DMA suspend is disabled and the DMA module operates normally. PLIB_DMA_SuspendEnable DMA transfers are suspended to allow uninterrupted access by the CPU to the data bus. PLIB_DMA_SuspendIsEnabled Returns the DMA suspend status. File Name plib_dma.h Company Microchip Technology Inc. 5.6.7 EBI Peripheral Library 5.6.7.1 Introduction EBI Peripheral Library for Microchip Microcontrollers 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1864 This library provides a low-level abstraction of the EBI Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The External Bus Interface (EBI) allows for external physical memory to be mapped into the kernels virtual memory map. The External Bus Interface (EBI) module provides a high-speed, convenient way to interface external parallel memory devices to the PIC32 family device. With the EBI module, it is possible to connect asynchronous SRAM and NOR Flash devices, as well as non-memory devices such as camera sensors. The module also supports Low-Cost Controllerless (LCC) Graphics devices. 5.6.7.2 Release Notes MPLAB Harmony Version: v0.70b EBI Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1865 SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.7.4 Using the Library This topic describes the basic architecture of the EBI Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_ebi.h The interface to the EBI Peripheral library is defined in the "plib_ebi.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the EBI Peripheral library should include "plib_ebi.h". Library File: The EBI Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.7.5 How the Library Works Before using the EBI module, it must be enabled by the application developer(s). To work correctly, the device characteristics of the attached Memory/Flash must be set with the functions in this library. The Characteristics of the Memory/Flash will be found in the specific device data sheet. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.6.7.6 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.7.7 Library Interface Existence Functions Name Description PLIB_EBI_ExistsAddressHoldTime Identifies whether the AddressHoldTime feature exists on the EBI module PLIB_EBI_ExistsAddressPinEnableBits Identifies whether the AddressPinEnableBits feature exists on the EBI module 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1866 PLIB_EBI_ExistsAddressSetupTime Identifies whether the AddressSetupTime feature exists on the EBI module PLIB_EBI_ExistsBaseAddress Identifies whether the Base_Address feature exists on the EBI module PLIB_EBI_ExistsByteSelectPin Identifies whether the ByteSelectPin feature exists on the EBI module PLIB_EBI_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the EBI module PLIB_EBI_ExistsControlEnable Identifies whether the ControlEnable feature exists on the EBI module PLIB_EBI_ExistsDataEnable Identifies whether the DataEnable feature exists on the EBI module PLIB_EBI_ExistsDataTurnAroundTime Identifies whether the DataTurnAroundTime feature exists on the EBI module PLIB_EBI_ExistsFlashPowerDownMode Identifies whether the FlashPowerDownMode feature exists on the EBI module PLIB_EBI_ExistsFlashResetPin Identifies whether the FlashResetPin feature exists on the EBI module PLIB_EBI_ExistsFlashTiming Identifies whether the FlashTiming feature exists on the EBI module PLIB_EBI_ExistsMemoryCharacteristics Identifies whether the MemoryCharacteristics feature exists on the EBI module PLIB_EBI_ExistsMemoryPaging Identifies whether the MemoryPaging feature exists on the EBI module PLIB_EBI_ExistsMemoryTimingConfig Identifies whether the MemoryTimingConfig feature exists on the EBI module PLIB_EBI_ExistsPageMode Identifies whether the PageMode feature exists on the EBI module PLIB_EBI_ExistsPageReadTime Identifies whether the PageReadTime feature exists on the EBI module PLIB_EBI_ExistsReadCycleTime Identifies whether the ReadCycleTime feature exists on the EBI module PLIB_EBI_ExistsReadyMode Identifies whether the ReadyMode feature exists on the EBI module PLIB_EBI_ExistsReadyPin1Config Identifies whether the ReadyPin1Config feature exists on the EBI module PLIB_EBI_ExistsReadyPin2Config Identifies whether the ReadyPin2Config feature exists on the EBI module PLIB_EBI_ExistsReadyPin3Config Identifies whether the ReadyPin3Config feature exists on the EBI module PLIB_EBI_ExistsReadyPinSens Identifies whether the ReadyPinSens feature exists on the EBI module PLIB_EBI_ExistsStaticMemoryWidthRegister Identifies whether the StaticMemoryWidthRegister feature exists on the EBI module PLIB_EBI_ExistsWriteOutputControl Identifies whether the WriteOutputControl feature exists on the EBI module PLIB_EBI_ExistsWritePulseWidth Identifies whether the WritePulseWidth feature exists on the EBI module General Functions Name Description PLIB_EBI_ControlEnableClear This function gets the set power down state. Get Functions Name Description PLIB_EBI_AddressHoldTimeGet This function returns the Address Hold Time 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1867 PLIB_EBI_AddressSetupTimeGet This function is to get the set hold time PLIB_EBI_BaseAddressGet This function returns the Base Address set for each chip select PLIB_EBI_ControlEnableGet This function gets the status of the enable bit for EBI. PLIB_EBI_DataTurnAroundTimeGet This function gets the data turn time set for the EBI Bus. PLIB_EBI_FlashPowerDownModeGet This function gets the set power down state. PLIB_EBI_FlashResetPinGet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_FlashTimingGet This function gets the set flash timing for external flash PLIB_EBI_PageModeGet This function returns Paging mode settings PLIB_EBI_PageReadCycleTimeGet This function returns the cycle time for a page read. PLIB_EBI_PageSizeGet This function returns Paging mode settings PLIB_EBI_ReadCycleTimeGet This function returns the read time in number of clock cycles PLIB_EBI_ReadyModeGet This function returns whether or not the Ready Mode was set. PLIB_EBI_StaticMemoryWidthRegisterGet This function get the width of the set data bus PLIB_EBI_WritePulseWidthGet This function returns the set hold time in clock cycles. Set Functions Name Description PLIB_EBI_AddressPinEnableBitsSet This function sets the address pins used for EBI. PLIB_EBI_BaseAddressSet This function sets the Base address for physical memory at each chip select PLIB_EBI_ByteSelectPinSet This function sets the data Byte Select High [15:8] and Low [7:0] enable pins for use. PLIB_EBI_ChipSelectEnableSet This function sets the Chip Select pins for use with the EBI or GPIO. PLIB_EBI_DataEnableSet This function sets the use of Data Byte Select Pins, High and Low, for control with EBI or GPIO use. PLIB_EBI_FlashPowerDownModeSet This function sets the pin state for flash devices on power down/reset PLIB_EBI_FlashResetPinSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_FlashTimingSet This function sets the timing for hold in reset for external flash PLIB_EBI_MemoryCharacteristicsSet This function set the Memory Characteristics for Memory or attached devices attached to that pin PLIB_EBI_MemoryPagingSet This function sets the size of the memory page if paging is used. PLIB_EBI_MemoryTimingConfigSet This function is to set the cycle time for page reading PLIB_EBI_ReadyPin1ConfigSet This function sets the the control use of Ready pin and the inverts status. PLIB_EBI_ReadyPin2ConfigSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_ReadyPin3ConfigSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_ReadyPinSensSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_StaticMemoryWidthRegisterSet This function set the data width of static memory. PLIB_EBI_WriteOutputControlSet This function sets the Write Enable & Output Enable control pins PLIB_EBI_ControlEnableSet This function sets the enable bit for turning on or off the EBI Bus. PLIB_EBI_ReadyModeSet This function sets the use of ready mode for each pin. The attached device will either pull the ready pin high or low. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1868 Description This section describes the Application Programming Interface (API) functions of the EBI Peripheral. Refer to each section for a detailed description. 5.6.7.7.1 General Functions 5.6.7.7.1.1 PLIB_EBI_ControlEnableClear Function C void PLIB_EBI_ControlEnableClear( EBI_MODULE_ID index ); Description EBIPINEN - in datasheet EBI Pin Enable bit 1 = EBI controls access of pins shared with PMP 0 = Pins shared with EBI are available for general use Parameters Parameters Description index Identifier for the device instance Returns None Remarks None. 5.6.7.7.2 Get Functions 5.6.7.7.2.1 PLIB_EBI_AddressHoldTimeGet Function C int PLIB_EBI_AddressHoldTimeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TWR - in the datasheet. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns Returns a integer, the Address & Data Hold time in number of clocks. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1869 5.6.7.7.2.2 PLIB_EBI_AddressSetupTimeGet Function C int PLIB_EBI_AddressSetupTimeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TAS - in the data sheet Clock cycles for address setup time. A value of ‘0’ is only valid in the case of SSRAM. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns Returns a integer, the address setup time in number of clocks Remarks None. 5.6.7.7.2.3 PLIB_EBI_BaseAddressGet Function C uint32_t PLIB_EBI_BaseAddressGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description CSADDR- in datasheet. This function returns the base address for each chip select pin Parameters Parameters Description index Identifier for the device instance. ChipSelectNumber Identifies what chip select address pin address is being read. Returns Returns a unsigned integer that is the physical address of the attached device Remarks None. 5.6.7.7.2.4 PLIB_EBI_ControlEnableGet Function C bool PLIB_EBI_ControlEnableGet( EBI_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1870 Description EBIPINEN - in datasheet. EBI Pin Enable bit 1 = EBI controls access of pins shared with PMP 0 = Pins shared with EBI are available for general use Parameters Parameters Description index Identifier for the device instance Returns Returns a bool, if EBI is ON or OFF. Remarks None. 5.6.7.7.2.5 PLIB_EBI_DataTurnAroundTimeGet Function C int PLIB_EBI_DataTurnAroundTimeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TBTA - in the datasheet. Returns the clock cycles (0-7) for static memory between read-to-write, write-to-read, and read-to-read when Chip Select changes. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns Returns a integer, the number of clock cycles that is set in the Turn Around Register Remarks None. 5.6.7.7.2.6 PLIB_EBI_FlashPowerDownModeGet Function C bool PLIB_EBI_FlashPowerDownModeGet( EBI_MODULE_ID index ); Description SMRP - in datasheet After a Reset, the controller internally performs a power-down for Flash, and then sets this bit to ‘1’. 1 = Flash is taken out of Power-down mode 0 = Flash is forced into Power-down mode 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1871 Parameters Parameters Description index Identifier for the device instance Returns returns a bool, depending on how FlashPowerDownMode its set Remarks None. 5.6.7.7.2.7 PLIB_EBI_FlashResetPinGet Function C bool PLIB_EBI_FlashResetPinGet( EBI_MODULE_ID index ); Description EBIRPEN - in datasheet. EBIRP Flash Reset pin, 1 = pin is enabled for use by the EBI module 0 = pin is available for general use. Parameters Parameters Description index Identifier for the device instance Returns returns a bool. Remarks None. 5.6.7.7.2.8 PLIB_EBI_FlashTimingGet Function C int PLIB_EBI_FlashTimingGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TRPD -in data sheet The number of clock cycles to hold the external Flash memory in reset. Preconditions MemoryType set to Flash Returns returns a integer, the number of clock cycles Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1872 5.6.7.7.2.9 PLIB_EBI_PageModeGet Function C bool PLIB_EBI_PageModeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description PAGEMODE - in datasheet. This Function returns the state of the register PAGEMODE, If the function returns a 1, Device supports Page mode. If the Function returns a 0,Device does not support Page mode . Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns This function Returns a bool, 1 = Page Mode is used, 0 = Page Mode is not used. Remarks None. 5.6.7.7.2.10 PLIB_EBI_PageReadCycleTimeGet Function C int PLIB_EBI_PageReadCycleTimeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TPRC - in datasheet. Read cycle time = TPRC + 1cycle. The value set and return are the same, the controller performs the read on the next clock, that is why there is a +1. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns Returns a integer, the number of clock cycles used to read a memory page. Remarks None. 5.6.7.7.2.11 PLIB_EBI_PageSizeGet Function C EBI_PAGE_SIZE PLIB_EBI_PageSizeGet( 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1873 EBI_MODULE_ID index, int ChipSelectNumber ); Description PAGESIZE- in datasheet. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns This function Returns the size of the memory page. Remarks None. 5.6.7.7.2.12 PLIB_EBI_ReadCycleTimeGet Function C int PLIB_EBI_ReadCycleTimeGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TRC in datasheet. Read Cycle time = TRC +1 clock cycle, the controller will always take 1 extra clock (the next clock) for a Read Cycle. The return will be the time set by the user. setting a the Read Cycle time to a 0 will return a 0 when read, but the controller will add 1 to that value for the next available clock. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies which chip select number the device is attached to. Returns returns a integer, the read cycle time in system clocks. Remarks None. 5.6.7.7.2.13 PLIB_EBI_ReadyModeGet Function C bool PLIB_EBI_ReadyModeGet( EBI_MODULE_ID index, int ChipSelectNumber ); 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1874 Description RDYMODE - in datasheet. This Function returns the state of the register RDYMODE, If the function returns a 1, Ready input is used. If the Function returns a 0, Ready input is not used. Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns This function Returns a bool, 1 = Ready input is used, 0 = Ready input is not used. Remarks None. 5.6.7.7.2.14 PLIB_EBI_StaticMemoryWidthRegisterGet Function C EBI_STATIC_MEMORY_WIDTH PLIB_EBI_StaticMemoryWidthRegisterGet( EBI_MODULE_ID index, int RegstierNumber ); Description SMDWIDTH - in data sheet 100 = 16 bits 000 = 8 bits Parameters Parameters Description index Identifier for the device instance Returns returns a enum type, which bus mode is used Remarks None. 5.6.7.7.2.15 PLIB_EBI_WritePulseWidthGet Function C int PLIB_EBI_WritePulseWidthGet( EBI_MODULE_ID index, int ChipSelectNumber ); Description TWP in the datasheet. Write Pulse with = TWP + 1 clock cycle 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1875 Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Identifies the specific chip select pin Returns Returns a integer, the number of clock cycles the write pulse width is set to. Remarks None. 5.6.7.7.3 Set Functions 5.6.7.7.3.1 PLIB_EBI_AddressPinEnableBitsSet Function C void PLIB_EBI_AddressPinEnableBitsSet( EBI_MODULE_ID index, EBI_ADDRESS_PORT AddressPort ); Description These pins have to be enabled for the size of the data bus in a contiguous order. EBIA23EN:EBIA0EN - in datasheet. EBI Address Pin Enable bits, 1 = pin is enabled for use by EBI, 0 = pin has is available for general use. Parameters Parameters Description index Identifier for the device instance. AddressPort Identifies how many pins are used for addressing on the EBI bus. Returns None. Remarks None. 5.6.7.7.3.2 PLIB_EBI_BaseAddressSet Function C void PLIB_EBI_BaseAddressSet( EBI_MODULE_ID index, int ChipSelectNumber, uint32_t BaseAddress ); Description CSADDR- in datasheet. This function sets the base address for physical memory at each chip select pin. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1876 Preconditions EBI has to be supported by the microcontroller and has to have a device attached to it. Parameters Parameters Description index Identifier for the device instance. ChipSelectNumber Identifies what chip select address pin is being assigned an address BaseAddress a physical address for memory Returns None. Remarks None. 5.6.7.7.3.3 PLIB_EBI_ByteSelectPinSet Function C void PLIB_EBI_ByteSelectPinSet( EBI_MODULE_ID index, bool ByteSelect0, bool ByteSelect1 ); Description If the system uses Byte Select High/Low pins for the data, the pins must be enabled for use in the EBI controller. EBIBSEN0 - in datasheet. EBIBSEN0, This Controls the pin Enable bit for the Lower Data Byte Select. Lower Data Byte is bits 8:0. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. EBIBSEN1 - in datasheet. EBIBSEN1, This Controls the pin Enable bit for the Upper Data Byte Select. Upper Data Byte is bits 15:8. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. Preconditions Registers EBIDEN0 & EBIDEN1 must be enabled first, this can be done in the function PLIB_EBI_DataEnableSet(). Parameters Parameters Description index Identifier for the device instance ByteSelect0 Identifies Lower Byte Select Pin for enabling. ByteSelect1 Identifies Upper Byte Select Pin for enabling. Returns None. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1877 5.6.7.7.3.4 PLIB_EBI_ChipSelectEnableSet Function C void PLIB_EBI_ChipSelectEnableSet( EBI_MODULE_ID index, bool ChipSelect0, bool ChipSelect1, bool ChipSelect2, bool ChipSelect3 ); Description EBICSEN0 = EBI ChipSelect0 Pin Enable bit. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. EBICSEN1 = EBI ChipSelect1 Pin Enable bit. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. EBICSEN2 = EBI ChipSelect2 Pin Enable bit. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. EBICSEN3 = EBI ChipSelect3 Pin Enable bit. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. Parameters Parameters Description index Identifier for the device instance ChipSelect0 Identifies control of Chip Select 0 for enabling. ChipSelect1 Identifies control of Chip Select 1 for enabling. ChipSelect2 Identifies control of Chip Select 2 for enabling. ChipSelect3 Identifies control of Chip Select 3 for enabling. Returns None. Remarks None. 5.6.7.7.3.5 PLIB_EBI_DataEnableSet Function C void PLIB_EBI_DataEnableSet( EBI_MODULE_ID index, bool DataUpperByte, bool DataLowerByte ); Description EBIDEN1 - in datasheet. EBI Data Upper Byte Pin Enable bit. 1 = [15:8] pins are enabled for use by the EBI module, 0 = [15:8] pins have reverted to general use. EBIDEN0 - in datasheet. EBI Data Upper Byte Pin Enable bit. 1 = [7:0] pins are enabled for use by the EBI module, 0 = [7:0] pins have reverted to general use. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1878 Parameters Parameters Description index Identifier for the device instance DataUpperByte Identifies control of Upper Data Byte for enabling. DataLowerByte Identifies control of Lower Data Byte for enabling. Returns None. Remarks None. 5.6.7.7.3.6 PLIB_EBI_FlashPowerDownModeSet Function C void PLIB_EBI_FlashPowerDownModeSet( EBI_MODULE_ID index, bool FlashPowerDownMode ); Description SMRP- in datasheet. After a Reset, the controller internally performs a power-down for Flash, and then sets this bit to ‘1’. 1 = Flash is taken out of Power-down mode. 0 = Flash is forced into Power-down mode. Parameters Parameters Description index Identifier for the device instance FlashPowerDownMode a bool, sets the power down state for flash memory Returns None. Remarks None. 5.6.7.7.3.7 PLIB_EBI_FlashResetPinSet Function C void PLIB_EBI_FlashResetPinSet( EBI_MODULE_ID index, bool FlashResetPin ); Description EBIRPEN - in datasheet. EBIRP Flash Reset pin, 1 = pin is enabled for use by the EBI module 0 = pin is available for general use. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1879 Parameters Parameters Description index Identifier for the device instance FlashReadPin Flash Rest Pin is Used Returns None. Remarks None. 5.6.7.7.3.8 PLIB_EBI_FlashTimingSet Function C void PLIB_EBI_FlashTimingSet( EBI_MODULE_ID index, int FlashTiming ); Description TRPD - in datasheet. The number of clock cycles to hold the external Flash memory in reset. Preconditions NOR Flash has to be used with EBI instead of SRAM Parameters Parameters Description index Identifier for the device instance FlashTiming an int, the number of clock cycles Returns None. Remarks None. 5.6.7.7.3.9 PLIB_EBI_MemoryCharacteristicsSet Function C void PLIB_EBI_MemoryCharacteristicsSet( EBI_MODULE_ID index, int ChipSelectNumber, EBI_MEMORY_TYPE MemoryType, EBI_MEMORY_SIZE MemorySize, EBI_CS_TIMING TimingReg ); Description EBIMSKx -SRF name index - Identifier for the device instance. ChipSelectNumber - Identifies what chip select address pin is being assigned an address MEMTYPE - in datasheet. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1880 MEMSIZE - in the datasheet. REGSEL - in the datasheet. Preconditions EBI has to be supported by the microcontroller. Parameters Parameters Description index Identifier for the device instance. ChipSelectNumber Identifies which chip select pin MemoryType Identifies which memory is used MemorySize a enum type, sets the size of the attached memory device TimingRegSet Identifies the timing register Returns None. Remarks None. 5.6.7.7.3.10 PLIB_EBI_MemoryPagingSet Function C void PLIB_EBI_MemoryPagingSet( EBI_MODULE_ID index, int ChipSelectNumber, bool PageMode, EBI_PAGE_SIZE MemoryPageSize ); Description PAGESIZE in datasheet. PAGEMODE in datasheet. 1 = Device supports Page mode 0 = Device does not support Page mode Parameters Parameters Description index Identifier for the device instance ChipSelectNumber Sets for that Chip Select pin [0:3] PageMode enable or disable page mode MemoryPageSize size of memory pages Returns none Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1881 5.6.7.7.3.11 PLIB_EBI_MemoryTimingConfigSet Function C void PLIB_EBI_MemoryTimingConfigSet( EBI_MODULE_ID index, int CS_Timing_Reg, int PageReadTime, int DataTurnAroundTime, int WritePulseWidth, int AddressHoldTime, int AddressSetupTime, int ReadCycleTime ); Description SFR = EBISMT[0:2] TPRC - in datasheet. Read cycle time = TPRC + 1cycle. TBTA - in the datasheet. Clock cycles (0-7) for static memory between read-to-write, write-to-read, and read-to-read when Chip Select changes. TWP in the datasheet. Write Pulse with = TWP + 1 clock cycle. TWR - in datasheet. Write Address/Data Hold Time TAS - in datasheet. Clock cycles for address setup time. A value of ‘0’ is only valid in the case of SSRAM. TRC - in datasheet. Read Cycle time = TRC +1 clock cycle. Preconditions EBI has to be supported by the microcontroller. Parameters Parameters Description index Identifier for the device instance CS_Timing_Reg Identifies which chip select Timing register to use EBISMT[0:2] PageReadTime The clock cycle needed for a Memory Page read DataTurnAroundTime Time between read-to-write, write-to-read, and read-to-read when Chip Select changes state. WritePulseWidth The clock cycles needed for a memory write AddressHoldTime The clock time needed for the address bus to hold AddressSetupTime The time needed for the address to settle ReadCycleTime _nt_ Returns None. Remarks None. 5.6.7.7.3.12 PLIB_EBI_ReadyPin1ConfigSet Function C void PLIB_EBI_ReadyPin1ConfigSet( EBI_MODULE_ID index, bool ReadyPin1Enable, bool ReadyPin1Invert 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1882 ); Description EBIRDYEN1 - in datasheet. EBIRDY1 Pin Enable bit, 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use EBIRDYINV1 - in datasheet. EBIRDYx Inversion Control bit 1 = Invert EBIRDYx pin before use 0 = Do not invert EBIRDYx pin before use. Parameters Parameters Description index Identifier for the device instance ReadyPin1Invert Identifies the on/off for invert ReadyPin1Enable Identifies if this pin is used by the control part Returns None. Remarks None. 5.6.7.7.3.13 PLIB_EBI_ReadyPin2ConfigSet Function C void PLIB_EBI_ReadyPin2ConfigSet( EBI_MODULE_ID index, bool ReadyPin2Enable, bool ReadyPin2Invert ); Description EBIRDYEN2 - in datasheet. EBIRDY2 Pin Enable bit, 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use EBIRDYINV2 - in datasheet. EBIRDYx Inversion Control bit 1 = Invert EBIRDYx pin before use 0 = Do not invert EBIRDYx pin before use. Parameters Parameters Description index Identifier for the device instance ReadyPin2Invert Identifies the on/off for invert ReadyPin2Enable Identifies if this pin is used by the control part Returns None. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1883 5.6.7.7.3.14 PLIB_EBI_ReadyPin3ConfigSet Function C void PLIB_EBI_ReadyPin3ConfigSet( EBI_MODULE_ID index, bool ReadyPin3Enable, bool ReadyPin3Invert ); Description EBIRDYEN2 - in datasheet. EBIRDY2 Pin Enable bit, 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use EBIRDYINV2 - in datasheet. EBIRDYx Inversion Control bit 1 = Invert EBIRDYx pin before use 0 = Do not invert EBIRDYx pin before use. Parameters Parameters Description index Identifier for the device instance ReadyPin3Invert Identifies the on/off for invert ReadyPin3Enable Identifies if this pin is used by the control part Returns None. Remarks None. 5.6.7.7.3.15 PLIB_EBI_ReadyPinSensSet Function C void PLIB_EBI_ReadyPinSensSet( EBI_MODULE_ID index, bool SensitivityControl ); Description EBIRDYLVL - in datasheet. EBI Ready Pin trigger detection 1 = Use level detect for EBIRDYx pins, 0 = Use edge detect for EBIRDYx pins Parameters Parameters Description index Identifier for the device instance SensitivityControl for selection edge or level detection Returns None. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1884 5.6.7.7.3.16 PLIB_EBI_StaticMemoryWidthRegisterSet Function C void PLIB_EBI_StaticMemoryWidthRegisterSet( EBI_MODULE_ID index, int RegstierNumber, EBI_STATIC_MEMORY_WIDTH StaticMemoryWidthRegister ); Description SMDWIDTH - in the datasheet. 000 = 16 bits 100 = 8 bits Parameters Parameters Description index Identifier for the device instance RegstierNumber the ID for the register being set StaticMemoryWidthRegister -identifies weither a bus width of 8bit or 16bits Returns None. Remarks None. 5.6.7.7.3.17 PLIB_EBI_WriteOutputControlSet Function C void PLIB_EBI_WriteOutputControlSet( EBI_MODULE_ID index, bool WriteEnable, bool OutputEnable ); Description EBIWEEN - in datasheet. EBIWE, This controls the Enable bit for the Write Enable Pin. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. EBIOEEN - in datasheet. EBIOE, This controls the enable bit for the Output Enable Pin. 1 = pin is enabled for use by the EBI module, 0 = pin is available for general use. Parameters Parameters Description index Identifier for the device instance WriteEnable for enabling Write Enable OutputEnable for enabling Output Enable 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1885 Returns None. Remarks None. 5.6.7.7.3.18 PLIB_EBI_ControlEnableSet Function C void PLIB_EBI_ControlEnableSet( EBI_MODULE_ID index, bool EnableBit ); Description EBIPINEN - in datasheet. EBI Pin Enable bit, 1 = EBI controls access of pins shared with PMP 0 = Pins shared with EBI are available for general use. Parameters Parameters Description index Identifier for the device instance EnableBit Identifes the enable bit Returns None Remarks None. 5.6.7.7.3.19 PLIB_EBI_ReadyModeSet Function C void PLIB_EBI_ReadyModeSet( EBI_MODULE_ID index, bool ReadyPin0, bool ReadyPin1, bool ReadyPin2 ); Description RDYMODE- The device associated with EBI is a data-ready device, and will use the READY pin. 1 = Ready input is used 0 = Ready input is not used Parameters Parameters Description index Identifier for the device instance ReadyPin0 ReadyPin1 ReadyPin2 ReadyPin(x) Identifies the ready pin (1-3) that Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1886 Remarks None. 5.6.7.7.4 Existence Functions 5.6.7.7.4.1 PLIB_EBI_ExistsAddressHoldTime Function C bool PLIB_EBI_ExistsAddressHoldTime( EBI_MODULE_ID index ); Description This function identifies whether the AddressHoldTime feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_AddressHoldTimeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressHoldTime feature is supported on the device • false - The AddressHoldTime feature is not supported on the device Remarks None. 5.6.7.7.4.2 PLIB_EBI_ExistsAddressPinEnableBits Function C bool PLIB_EBI_ExistsAddressPinEnableBits( EBI_MODULE_ID index ); Description This function identifies whether the AddressPinEnableBits feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_AddressPinEnableBitsSet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1887 Returns • true - The AddressPinEnableBits feature is supported on the device • false - The AddressPinEnableBits feature is not supported on the device Remarks None. 5.6.7.7.4.3 PLIB_EBI_ExistsAddressSetupTime Function C bool PLIB_EBI_ExistsAddressSetupTime( EBI_MODULE_ID index ); Description This function identifies whether the AddressSetupTime feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_AddressSetupTimeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressSetupTime feature is supported on the device • false - The AddressSetupTime feature is not supported on the device Remarks None. 5.6.7.7.4.4 PLIB_EBI_ExistsBaseAddress Function C bool PLIB_EBI_ExistsBaseAddress( EBI_MODULE_ID index ); Description This function identifies whether the Base_Address feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_BaseAddressSet • PLIB_EBI_BaseAddressGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1888 Parameters Parameters Description index Identifier for the device instance Returns • true - The Base_Address feature is supported on the device • false - The Base_Address feature is not supported on the device Remarks None. 5.6.7.7.4.5 PLIB_EBI_ExistsByteSelectPin Function C bool PLIB_EBI_ExistsByteSelectPin( EBI_MODULE_ID index ); Description This function identifies whether the ByteSelectPin feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ByteSelectPinSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ByteSelectPin feature is supported on the device • false - The ByteSelectPin feature is not supported on the device Remarks None. 5.6.7.7.4.6 PLIB_EBI_ExistsChipSelectEnable Function C bool PLIB_EBI_ExistsChipSelectEnable( EBI_MODULE_ID index ); Description This function identifies whether the ChipSelectEnable feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ChipSelectEnableSet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1889 Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipSelectEnable feature is supported on the device • false - The ChipSelectEnable feature is not supported on the device Remarks None. 5.6.7.7.4.7 PLIB_EBI_ExistsControlEnable Function C bool PLIB_EBI_ExistsControlEnable( EBI_MODULE_ID index ); Description This function identifies whether the ControlEnable feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ControlEnableSet • PLIB_EBI_ControlEnableGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ControlEnable feature is supported on the device • false - The ControlEnable feature is not supported on the device Remarks None. 5.6.7.7.4.8 PLIB_EBI_ExistsDataEnable Function C bool PLIB_EBI_ExistsDataEnable( EBI_MODULE_ID index ); Description This function identifies whether the DataEnable feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_DataEnableSet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1890 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataEnable feature is supported on the device • false - The DataEnable feature is not supported on the device Remarks None. 5.6.7.7.4.9 PLIB_EBI_ExistsDataTurnAroundTime Function C bool PLIB_EBI_ExistsDataTurnAroundTime( EBI_MODULE_ID index ); Description This function identifies whether the DataTurnAroundTime feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_DataTurnAroundTimeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataTurnAroundTime feature is supported on the device • false - The DataTurnAroundTime feature is not supported on the device Remarks None. 5.6.7.7.4.10 PLIB_EBI_ExistsFlashPowerDownMode Function C bool PLIB_EBI_ExistsFlashPowerDownMode( EBI_MODULE_ID index ); Description This function identifies whether the FlashPowerDownMode feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_FlashPowerDownModeSet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1891 • PLIB_EBI_FlashPowerDownModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashPowerDownMode feature is supported on the device • false - The FlashPowerDownMode feature is not supported on the device Remarks None. 5.6.7.7.4.11 PLIB_EBI_ExistsFlashResetPin Function C bool PLIB_EBI_ExistsFlashResetPin( EBI_MODULE_ID index ); Description This function identifies whether the FlashResetPin feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_FlashResetPinSet • PLIB_EBI_FlashResetPinGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashResetPin feature is supported on the device • false - The FlashResetPin feature is not supported on the device Remarks None. 5.6.7.7.4.12 PLIB_EBI_ExistsFlashTiming Function C bool PLIB_EBI_ExistsFlashTiming( EBI_MODULE_ID index ); Description This function identifies whether the FlashTiming feature is available on the EBI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1892 • PLIB_EBI_FlashTimingSet • PLIB_EBI_FlashTimingGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashTiming feature is supported on the device • false - The FlashTiming feature is not supported on the device Remarks None. 5.6.7.7.4.13 PLIB_EBI_ExistsMemoryCharacteristics Function C bool PLIB_EBI_ExistsMemoryCharacteristics( EBI_MODULE_ID index ); Description This function identifies whether the MemoryCharacteristics feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_MemoryCharacteristicsSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MemoryCharacteristics feature is supported on the device • false - The MemoryCharacteristics feature is not supported on the device Remarks None. 5.6.7.7.4.14 PLIB_EBI_ExistsMemoryPaging Function C bool PLIB_EBI_ExistsMemoryPaging( EBI_MODULE_ID index ); Description This function identifies whether the MemoryPaging feature is available on the EBI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1893 • PLIB_EBI_MemoryPagingSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MemoryPaging feature is supported on the device • false - The MemoryPaging feature is not supported on the device Remarks None. 5.6.7.7.4.15 PLIB_EBI_ExistsMemoryTimingConfig Function C bool PLIB_EBI_ExistsMemoryTimingConfig( EBI_MODULE_ID index ); Description This function identifies whether the MemoryTimingConfig feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_MemoryTimingConfigSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MemoryTimingConfig feature is supported on the device • false - The MemoryTimingConfig feature is not supported on the device Remarks None. 5.6.7.7.4.16 PLIB_EBI_ExistsPageMode Function C bool PLIB_EBI_ExistsPageMode( EBI_MODULE_ID index ); Description This function identifies whether the PageMode feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_PageModeGet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1894 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PageMode feature is supported on the device • false - The PageMode feature is not supported on the device Remarks None. 5.6.7.7.4.17 PLIB_EBI_ExistsPageReadTime Function C bool PLIB_EBI_ExistsPageReadTime( EBI_MODULE_ID index ); Description This function identifies whether the PageReadTime feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_PageReadCycleTimeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PageReadTime feature is supported on the device • false - The PageReadTime feature is not supported on the device Remarks None. 5.6.7.7.4.18 PLIB_EBI_ExistsReadCycleTime Function C bool PLIB_EBI_ExistsReadCycleTime( EBI_MODULE_ID index ); Description This function identifies whether the ReadCycleTime feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadCycleTimeGet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1895 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadCycleTime feature is supported on the device • false - The ReadCycleTime feature is not supported on the device Remarks None. 5.6.7.7.4.19 PLIB_EBI_ExistsReadyMode Function C bool PLIB_EBI_ExistsReadyMode( EBI_MODULE_ID index ); Description This function identifies whether the ReadyMode feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadyModeSet • PLIB_EBI_ReadyModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadyMode feature is supported on the device • false - The ReadyMode feature is not supported on the device Remarks None. 5.6.7.7.4.20 PLIB_EBI_ExistsReadyPin1Config Function C bool PLIB_EBI_ExistsReadyPin1Config( EBI_MODULE_ID index ); Description This function identifies whether the ReadyPin1Config feature is available on the EBI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1896 • PLIB_EBI_ReadyPin1ConfigSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadyPin1Config feature is supported on the device • false - The ReadyPin1Config feature is not supported on the device Remarks None. 5.6.7.7.4.21 PLIB_EBI_ExistsReadyPin2Config Function C bool PLIB_EBI_ExistsReadyPin2Config( EBI_MODULE_ID index ); Description This function identifies whether the ReadyPin2Config feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadyPin2ConfigSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadyPin2Config feature is supported on the device • false - The ReadyPin2Config feature is not supported on the device Remarks None. 5.6.7.7.4.22 PLIB_EBI_ExistsReadyPin3Config Function C bool PLIB_EBI_ExistsReadyPin3Config( EBI_MODULE_ID index ); Description This function identifies whether the ReadyPin3Config feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadyPin3ConfigSet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1897 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadyPin3Config feature is supported on the device • false - The ReadyPin3Config feature is not supported on the device Remarks None. 5.6.7.7.4.23 PLIB_EBI_ExistsReadyPinSens Function C bool PLIB_EBI_ExistsReadyPinSens( EBI_MODULE_ID index ); Description This function identifies whether the ReadyPinSens feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_ReadyPinSensSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadyPinSens feature is supported on the device • false - The ReadyPinSens feature is not supported on the device Remarks None. 5.6.7.7.4.24 PLIB_EBI_ExistsStaticMemoryWidthRegister Function C bool PLIB_EBI_ExistsStaticMemoryWidthRegister( EBI_MODULE_ID index ); Description This function identifies whether the StaticMemoryWidthRegister feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_StaticMemoryWidthRegisterSet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1898 • PLIB_EBI_StaticMemoryWidthRegisterGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StaticMemoryWidthRegister feature is supported on the device • false - The StaticMemoryWidthRegister feature is not supported on the device Remarks None. 5.6.7.7.4.25 PLIB_EBI_ExistsWriteOutputControl Function C bool PLIB_EBI_ExistsWriteOutputControl( EBI_MODULE_ID index ); Description This function identifies whether the WriteOutputControl feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_WriteOutputControlSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteOutputControl feature is supported on the device • false - The WriteOutputControl feature is not supported on the device Remarks None. 5.6.7.7.4.26 PLIB_EBI_ExistsWritePulseWidth Function C bool PLIB_EBI_ExistsWritePulseWidth( EBI_MODULE_ID index ); Description This function identifies whether the WritePulseWidth feature is available on the EBI module. When this function returns true, these functions are supported on the device: • PLIB_EBI_WritePulseWidthGet 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1899 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WritePulseWidth feature is supported on the device • false - The WritePulseWidth feature is not supported on the device Remarks None. 5.6.7.8 Files Files Name Description plib_ebi.h External Bus Interface (EBI) Peripheral Library Interface Header. Description 5.6.7.8.1 plib_ebi.h This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the EBI Peripheral Library. Functions Name Description PLIB_EBI_AddressHoldTimeGet This function returns the Address Hold Time PLIB_EBI_AddressPinEnableBitsSet This function sets the address pins used for EBI. PLIB_EBI_AddressSetupTimeGet This function is to get the set hold time PLIB_EBI_BaseAddressGet This function returns the Base Address set for each chip select PLIB_EBI_BaseAddressSet This function sets the Base address for physical memory at each chip select PLIB_EBI_ByteSelectPinSet This function sets the data Byte Select High [15:8] and Low [7:0] enable pins for use. PLIB_EBI_ChipSelectEnableSet This function sets the Chip Select pins for use with the EBI or GPIO. PLIB_EBI_ControlEnableClear This function gets the set power down state. PLIB_EBI_ControlEnableGet This function gets the status of the enable bit for EBI. PLIB_EBI_ControlEnableSet This function sets the enable bit for turning on or off the EBI Bus. PLIB_EBI_DataEnableSet This function sets the use of Data Byte Select Pins, High and Low, for control with EBI or GPIO use. PLIB_EBI_DataTurnAroundTimeGet This function gets the data turn time set for the EBI Bus. PLIB_EBI_ExistsAddressHoldTime Identifies whether the AddressHoldTime feature exists on the EBI module 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1900 PLIB_EBI_ExistsAddressPinEnableBits Identifies whether the AddressPinEnableBits feature exists on the EBI module PLIB_EBI_ExistsAddressSetupTime Identifies whether the AddressSetupTime feature exists on the EBI module PLIB_EBI_ExistsBaseAddress Identifies whether the Base_Address feature exists on the EBI module PLIB_EBI_ExistsByteSelectPin Identifies whether the ByteSelectPin feature exists on the EBI module PLIB_EBI_ExistsChipSelectEnable Identifies whether the ChipSelectEnable feature exists on the EBI module PLIB_EBI_ExistsControlEnable Identifies whether the ControlEnable feature exists on the EBI module PLIB_EBI_ExistsDataEnable Identifies whether the DataEnable feature exists on the EBI module PLIB_EBI_ExistsDataTurnAroundTime Identifies whether the DataTurnAroundTime feature exists on the EBI module PLIB_EBI_ExistsFlashPowerDownMode Identifies whether the FlashPowerDownMode feature exists on the EBI module PLIB_EBI_ExistsFlashResetPin Identifies whether the FlashResetPin feature exists on the EBI module PLIB_EBI_ExistsFlashTiming Identifies whether the FlashTiming feature exists on the EBI module PLIB_EBI_ExistsMemoryCharacteristics Identifies whether the MemoryCharacteristics feature exists on the EBI module PLIB_EBI_ExistsMemoryPaging Identifies whether the MemoryPaging feature exists on the EBI module PLIB_EBI_ExistsMemoryTimingConfig Identifies whether the MemoryTimingConfig feature exists on the EBI module PLIB_EBI_ExistsPageMode Identifies whether the PageMode feature exists on the EBI module PLIB_EBI_ExistsPageReadTime Identifies whether the PageReadTime feature exists on the EBI module PLIB_EBI_ExistsReadCycleTime Identifies whether the ReadCycleTime feature exists on the EBI module PLIB_EBI_ExistsReadyMode Identifies whether the ReadyMode feature exists on the EBI module PLIB_EBI_ExistsReadyPin1Config Identifies whether the ReadyPin1Config feature exists on the EBI module PLIB_EBI_ExistsReadyPin2Config Identifies whether the ReadyPin2Config feature exists on the EBI module PLIB_EBI_ExistsReadyPin3Config Identifies whether the ReadyPin3Config feature exists on the EBI module PLIB_EBI_ExistsReadyPinSens Identifies whether the ReadyPinSens feature exists on the EBI module PLIB_EBI_ExistsStaticMemoryWidthRegister Identifies whether the StaticMemoryWidthRegister feature exists on the EBI module PLIB_EBI_ExistsWriteOutputControl Identifies whether the WriteOutputControl feature exists on the EBI module PLIB_EBI_ExistsWritePulseWidth Identifies whether the WritePulseWidth feature exists on the EBI module PLIB_EBI_FlashPowerDownModeGet This function gets the set power down state. PLIB_EBI_FlashPowerDownModeSet This function sets the pin state for flash devices on power down/reset PLIB_EBI_FlashResetPinGet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_FlashResetPinSet This function sets the the control use of Ready pin and the inverts status 5.6 Peripheral Library Help MPLAB Harmony Help EBI Peripheral Library 5-1901 PLIB_EBI_FlashTimingGet This function gets the set flash timing for external flash PLIB_EBI_FlashTimingSet This function sets the timing for hold in reset for external flash PLIB_EBI_MemoryCharacteristicsSet This function set the Memory Characteristics for Memory or attached devices attached to that pin PLIB_EBI_MemoryPagingSet This function sets the size of the memory page if paging is used. PLIB_EBI_MemoryTimingConfigSet This function is to set the cycle time for page reading PLIB_EBI_PageModeGet This function returns Paging mode settings PLIB_EBI_PageReadCycleTimeGet This function returns the cycle time for a page read. PLIB_EBI_PageSizeGet This function returns Paging mode settings PLIB_EBI_ReadCycleTimeGet This function returns the read time in number of clock cycles PLIB_EBI_ReadyModeGet This function returns whether or not the Ready Mode was set. PLIB_EBI_ReadyModeSet This function sets the use of ready mode for each pin. The attached device will either pull the ready pin high or low. PLIB_EBI_ReadyPin1ConfigSet This function sets the the control use of Ready pin and the inverts status. PLIB_EBI_ReadyPin2ConfigSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_ReadyPin3ConfigSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_ReadyPinSensSet This function sets the the control use of Ready pin and the inverts status PLIB_EBI_StaticMemoryWidthRegisterGet This function get the width of the set data bus PLIB_EBI_StaticMemoryWidthRegisterSet This function set the data width of static memory. PLIB_EBI_WriteOutputControlSet This function sets the Write Enable & Output Enable control pins PLIB_EBI_WritePulseWidthGet This function returns the set hold time in clock cycles. File Name plib_ebi.h Company Microchip Technology Inc. 5.6.8 Ethernet Peripheral Library 5.6.8.1 Introduction Ethernet Peripheral Library for Microchip Microcontrollers The Ethernet Peripheral Library provides a low-level abstraction of the Ethernet module in the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without interacting directly with the module's registers, thereby hiding the differences in microcontroller variations. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1902 Description Overview Ethernet is the most widely deployed network in offices and homes. Ethernet’s infrastructure, interoperability, and scalability serve to ease development and facilitate communications to the device. Once equipment is connected to an Ethernet network, it can be monitored or controlled through the internet with low latency – “real time” remote delivery. The Ethernet Controller is a bus master module that interfaces with an off-chip PHY in order to implement a complete Ethernet node in a system. Following are some of the key features of this module: • Supports 10/100 Mbps data transfer rates • Supports Full-Duplex and Half-Duplex operation • Supports Reduced Media Independent Interface (RMII) and Media Independent Interface (MII) PHY interface • Supports MII Management (MIIM) PHY Management interface 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1903 • Supports both manual and automatic flow control • Supports Auto-MDIX and enabled PHYs • RAM descriptor based DMA operation for both receive and transmit path • Fully configurable interrupts • Configurable receive packet filtering: • CRC Check • 64-byte Pattern Match • Broadcast, Multicast and Unicast packets • Magic Packet™ • 64-bit Hash Table • Runt Packet • Supports Packet Payload Checksum calculation • Supports various hardware statistics counters 5.6.8.2 Release Notes MPLAB Harmony Version: v0.70b Ethernet Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1904 5.6.8.4 Using the Library This topic describes the basic architecture of the Ethernet Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_eth.h The interface to the Ethernet Peripheral Library is defined in the "plib_eth.h" header file. Any C language source (.c) file that uses the Ethernet Peripheral Library should include "plib_eth.h". Library File: The Ethernet Peripheral Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.8.4.1 Hardware Abstraction Model This section describes how the low-level abstraction is modeled in the software and introduces the library interface. The interface provided is a superset of all the functionality of the available Ethernet on the device. Refer to the specific data sheet or family reference manual to determine the set of functions that are supported for each Ethernet module on your device. Description Hardware Model This library provides the low-level abstraction of the Ethernet module on Microchip family of microcontrollers with a convenient C language interface. Ethernet Controller Block Diagram 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1905 Note: For information on off-chip options to provide Ethernet functionality, refer to the specific device data sheet. 5.6.8.4.2 How the Library Works This section provides information on the operation of the Ethernet Peripheral Library. Description The Peripheral Library is an abstraction of hardware which can be used to control hardware and obtain status. It is intended to allow the programmer access to hardware registers without knowing the exact bit or register names which may vary on individual devices. For example, instead of turning on the Ethernet module using: ETHCON1bits.EON = 1; the programmer can turn on the Ethernet module using: PLIB_ETH_Enable(moduleId);. This allows the programmer to use the same command for any device containing an Ethernet module without having to learn the individual device register names. Basic Overview The Ethernet Controller provides the modules needed to implement a 10/100 Mbps Ethernet node using an external PHY chip. To off-load the CPU from moving packet data to and from the module, internal descriptor-based DMA engines are included in the controller. The Ethernet Controller consists of the following modules: 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1906 • Media Access Control (MAC) block: Responsible for implementing the MAC functions of the Ethernet IEEE 802.3 Specification • Flow Control (FC) block, which provides: • Manual flow control • Automatic flow control • Transmission of PAUSE frames • Reception of PAUSE frame is handled within the MAC • RX Filter (RXF) block: This module performs filtering on every receive packet to determine whether each packet should be accepted or rejected and includes: • CRC Check • 64-byte Pattern Match • Broadcast, Multicast and Unicast packets • Magic Packet™ • 64-bit Hash Table • Runt Packet • TX DMA/TX BM Engine: The TX DMA and TX Buffer Management engines perform data transfers from the memory (using descriptor tables) to the MAC Transmit Interface • RX DMA/RX BM Engine: The RX DMA and RX Buffer Management engines transfer receive packets from the MAC to the memory (using descriptor tables) Basic Ethernet Controller Operation The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. If the Ethernet Controller is disabled, all of the I/O pins used for the MII/RMII and MIIM interfaces operate as port pins and are under the control of the respective PORTx latch bit and TRISx bit. Disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. The Special Function Registers (SFRs) are still accessible and their values are preserved. Clearing the ON bit while the Ethernet Controller is active will abort all pending operations and reset the peripheral as previously defined. Re-enabling the ON bit will restart the Ethernet Controller in its clean reset state while preserving the SFR values. Ethernet Controller Section Block Diagram 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1907 MAC Overview The MAC sub-layer is part of the functionality described in the OSI model for the Data Link Layer. It defines a medium-independent facility, built on the medium-dependent physical facility provided by the Physical Layer, and under the access-layer-independent LLC sub-layer or other MAC client. It is applicable to a general class of local area broadcast media suitable for use with the Carrier Sense Multiple Access with Collision Detection (CSMA/CD). The CSMA/CD MAC sub-layer provides services to the MAC client required for the transmission and reception of frames. The CSMA/CD MAC sub-layer makes a best effort to acquire the medium and transfer a serial stream of bits to the Physical Layer. Although certain errors are reported to the client, error recovery is not provided by the MAC. The following is a summary of the functional capabilities of the CSMA/CD MAC sub-layer as shown in the previous diagram. • For Frame Transmission: • Accepts data from the MAC client and constructs a frame • Presents a bit-serial data stream to the Physical Layer for transmission on the medium • In half-duplex mode, defers transmission of a bit-serial stream whenever the physical medium is busy • It can append proper Frame Check Sequence (FCS) value to outgoing frames and verifies full octet boundary alignment 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1908 • Delays transmission of frame bit stream for specified inter-frame gap period • In half-duplex mode, halts transmission when collision is detected • In half-duplex mode, schedules retransmission after a collision until a specified retry limit is reached • In half-duplex mode, enforces collision to ensure propagation throughout network by sending jam message • Prepends preamble and Start Frame Delimiter and appends FCS to all frame Appends PAD field for frames whose data length is less than a minimum value • For Frame Reception: • Receives a bit-serial data stream from the Physical Layer • Presents the received frames to the MAC client (broadcast, multicast, unicast frames, etc.) • Checks incoming frames for transmission errors by way of FCS and verifies octet boundary alignment • Removes preamble, Start Frame Delimiter and PAD field (if necessary) from received frames • Implements the MII Management block that provides control/status connection to the external MII PHY Note: Not all modes are available on all devices, please refer to the specific device data sheet to determine the set of modes supported for your device. In addition, refer to the "Ethernet" section in the family reference manual or the Ethernet Driver Library for more information. 5.6.8.4.2.1 Ethernet Frame Overview Ethernet Frame Overview IEEE 802.3-compliant Ethernet frames (packets) are between 64 and 1518 bytes long (Preamble and Start -of-Frame Delimiter not included). Frames containing less than 64 bytes are known as “runt” frames, while frames containing more than 1518 bytes are known as “huge” frames. An Ethernet frame is made up of the following fields: • Start-of-Stream/Preamble • Start-of-Frame Delimiter (SFD) • Destination MAC address (DA) • Source MAC address (SA) • Type/Length field • Data Payload • Optional Padding field • Frame Check Sequence (FCS) • Traffic on the actual physical cable Please refer to the IEEE 802.3 Specification for detailed information about the Ethernet protocol. 5.6.8.4.2.2 Ethernet Controller Operation Basic Ethernet Controller Operation The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. If the Ethernet Controller is disabled, all of the I/O pins used for the MII/RMII and MIIM interfaces operate as port pins and are under the control of the respective PORT latch bit and TRIS bit. Disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. The SFRs are still accessible and their values preserved. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1909 Clearing the ON bit while the Ethernet Controller is active will abort all pending operations and reset the peripheral as previously defined. Re-enabling the ON bit will restart the Ethernet Controller in its clean reset state while preserving the SFR values. 5.6.8.4.2.3 Media Independent Interface (MII) This section describes the Media Independent Interface (MII). Description Media Independent Interface (MII) The Media Independent Interface (MII) is a standard interconnection between the MAC and the PHY for communicating TX and RX frame data. This MII has the following important characteristics: • Capable of supporting 10/100 Mbps rates for data transfer, and offers support for management functions • Provides independent four bit wide transmit and receive data paths • Uses TTL signal levels, compatible with common digital CMOS processes • Provides full-duplex operation In 10 Mbps mode, the MII runs at 2.5 MHz; in 100 Mbps mode it runs at 25 MHz. PHYs that provide MII are not required to support both data rates, and may support either one or both. 5.6.8.4.2.4 Reduced Media Independent Interface (RMII) This section describes the Reduced Media Independent Interface (RMII). 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1910 Description Reduced Media Independent Interface (RMII) The management interface (MDIO/MDC) is assumed to be identical to that defined in MII. The RMII has the following characteristics: • Capable of supporting 10 Mbps and 100 Mbps data rates • Single clock reference for both MAC and the PHY (can be sourced from the MAC or from an external source) • Provides independent 2 bit wide transmit and receive data paths • Uses TTL signal levels, compatible with common digital CMOS processes • Provides full-duplex operation • The interface runs at 50 MHz 5.6.8.4.2.5 Flow Control Overview Flow Control Overview Ethernet flow control consists of the ability to send and receive PAUSE frames, which cause the receiving node to stop transmitting for a specific amount of time. On the transmit side, the Flow Control (FC) block handles the hardware handshaking between the MAC and the CPU when the transmit flow control is enabled. Flow control for the received packets is part of the MAC functionality. The PIC32 MAC supports both Symmetric PAUSE and Asymmetric PAUSE as described in Clause 28, Table 28B-2, and Clause 31 and Annex 31B of the IEEE 802.3 Specification. The FC block supports two modes of operation: manual and automatic. In addition, the mode of transmission (Full-Duplex or 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1911 Half-Duplex) programmed into the MAC registers, is used by the FC block. 5.6.8.4.2.6 Receive Filtering Overview Receive Filtering Overview The Receive Filter (RXF) block examines all incoming receive packets and accepts or rejects the packet, based on user-selectable filters. The following RX filters are supported: • CRC Error Acceptance Filter • Runt Error Acceptance Filter • CRC Check Rejection Filter • Runt Rejection Filter • Unicast Acceptance Filter • Not Me Unicast Acceptance Filter • Multicast Acceptance Filter • Broadcast Acceptance Filter • Hash Table Acceptance Filter • Magic Packet Acceptance Filter • Pattern Match Acceptance Filter with logical inversion 5.6.8.4.2.7 Ethernet DMA and Buffer Management Engine Ethernet DMA and Buffer Management Engines To reduce the overhead on the CPU to move the packet data between data memory and the Ethernet controller, internal receive (RX) and transmit (TX) DMA engines are integrated into the module. The DMA engines are responsible for transferring data from system memory to the MAC for transmit packets and for transferring data from the MAC to system memory for receive packets. The DMA engines each have access to the system memory by acting as two different bus masters, one bus master for transmit and one for receive. The DMA engines use separate Ethernet Descriptor Tables (EDTs) for TX and RX operations to determine where the TX/RX packet buffer resides in the system memory. Both transmit and receive descriptors, called Ethernet Descriptors (EDs), used by the DMA engines have a similar format, with only the status word formats being different. Refer to the "Ethernet" section in the family reference manual for more information. 5.6.8.4.3 Sample Code This section provides information for initialization, transmit, and receive using code samples. Description Sample Code The basic functionality of the Ethernet Peripheral Library is grouped into these sections: • Initialization • Transmit • Receive 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1912 For a properly functioning Ethernet port, development of a data queue and use of interrupts will be necessary. For this additional functionality, see the "Ethernet" section in the family reference manual or the Ethernet Driver Library for more information. Initialization Sequence The Ethernet Controller is enabled using PLIB_ETH_Enable and is disabled using PLIB_ETH_Disable. The Ethernet Controller is disabled by default after any Reset. After being Enabled, disabling the controller resets the internal DMA state machines and all transmit and receive operations are aborted. All registers remain accessible and their values are preserved. It is important to reset the PHY and MII Management registers to ensure the PHY is in a known initialized state. Before enabling the module for transmitting or receiving packets, there are several registers that must be initialized. To initialize the Ethernet Controller to receive and transmit, Microchip recommends the following sequence: 1. Begin with the module. • Disable the CPU Ethernet interrupt • Turn the Ethernet Controller off • Disable receive • Disable transmit • Wait until the Ethernet module is no longer busy • Disable all Ethernet Interrupts • Clear the Ethernet Interrupt Pending Flag(s) • Clear the transmit and receive start addresses 2. MAC initialize. • Reset the MAC • A configuration fuse (FETHIO) setting shows which pins will be used for connection to the PHY • A configuration fuse (FMIIEN) settings shows whether MII or RMII will be used 3. PHY Initialize is PHY dependent. Common procedures (which may vary by PHY vender) include the following: • Reset PHY (using Control Register 0) • Set the MII/RMII operation mode • Set the normal, swapped, or auto (preferred)MDIX • Check the PY capabilities (using Status Register 1) • Preferably the auto-negotiation should be selected if the PHY supports it. • Expose the supported capabilities (extended Register 4) • Start the negotiation (using Control Register 0) • wait for the negotiation to complete and get the link partner capabilities (extended Register 5) • negotiation result (vendor-specific register) • If auto-negotiation is not supported (or not selected) • update the PHY Duplex and speed settings (use Control Register 0 or vender-specific register) 4. MAC Configuration • Enable MAC receive and pause both transmit and receive direction control frames. • Select the desired auto-padding, duplex, huge frame, and CRC capabilities. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1913 • Program back-to-back inter-packet gap and non-back-to-back interpacket gap. • Program collision window and maximum retransmissions. • Set Maximum frame length. • Optionally set the station MAC address(es) (or let them default to the factory value). 5. Continue Ethernet Controller initialization: • If planning to turn on flow control, update the Pause Timer Value • If using auto flow control, setup the full/empty watermarks and enable it • Set the receive filters • Set receive buffer size - using packets that are too small impacts performance • Prepare the list/ring of transmit descriptors - refer to the device data sheet for more information • Prepare the list of receive descriptors populated with valid buffers for messages to be received - refer to the device data sheet for more information • Update the transmit buffer start address and the receive buffer start address • Enable the Ethernet Controller and wait until the module is ready • Enable Ethernet Receive. Receive Loop 1. Wait until the receive buffer count has been incremented. 2. Inspect the receive descriptor to see whether it is still owned by the Ethernet Module. 3. If the receive descriptor is still owned by the Ethernet module, nothing has been received. Loop to 1. 4. Otherwise, a message was received and software has control of the memory where it is stored. 5. Extract a message and do something with it. 6. Reinitialize buffer descriptor and return receive buffer to list and decrement the receive packet buffer count. 7. Loop. Transmit Loop 1. Software writes the packet data to packet data memory. A pointer to the packet data is inserted into the transmit buffer descriptor. 2. Update the necessary number of transmit descriptors, starting from the head of the list - setting the data buffer address (large packet fragmentation will impact performance). 3. Update the byte count for each descriptor with the number of bytes contained in each buffer. 4. Set the flag in each transmit descriptor that belongs to the packet to give the descriptor to the Ethernet module for transmission. 5. Enable the transmission. 6. Wait until the Ethernet module returns the transmit buffer descriptor ownership to software. 7. Insect the results of the transmission. 8. Loop. The packet transmit process is as follows: 1. Software writes the packet data to a packet buffer in data memory and programs a buffer descriptor entry to point to the packet data buffer. The buffer descriptor is used to define the Transmission Packet data buffer location and length, and its address is written to the Ethernet Controller. 2. Software then calls the TransmitRequestToSendEnable function, which starts the TX DMA and TXBM logic. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1914 3. After the TX DMA engine reads the DATA_BUFFER_ADDRESS value, the engine will begin reading the packet data from the location read from the descriptor. 4. The TXBM indicates the start-of-frame to the MAC and transmits the entire frame data from the transmit buffer, until the end address is reached. The TXBM simply transmits from the start address until the specified number of bytes has been transmitted to the MAC transmit interface. 5. The MAC can retry a transmission due to an early collision. 6. The MAC can abort a transmission due to a late collision, excessive collisions or excessive defers. This condition is signaled by TXABORT bit (ETHIRQ<2>). 7. Once transmission has completed, the TX DMA engine stores the relevant bits of the TSV into the first descriptor entry of the packet. 8. After the packet has been transmitted, all the descriptors used for the transmission are released to the software via the EOWN bits being cleared. 9. If more valid TX descriptors are available (EOWN = 1), the DMA engine will go back to step 3 to begin the next packet’s transmission. Otherwise, if the next descriptor is still owned by hardware (EOWN = 0), transmission will halt and wait for the software to set the TXRTS bit again. Note that any collision that occurs within the CWINDOW bit (EMAC1CLRT<8:14>) boundary is an early collision and results in a Retry operation. A collision that happens beyond the CWINDOW boundary will be treated as a late collision and will cause an abort. The CWINDOW bit in the EMAC1CLRT register is typically set to 64 bytes. An abort condition can also result from reaching the maximum collision count RETX bit (EMAC1CLRT<0:3>) for a packet trying to be sent. See the "Ethernet" section in the family reference manual or the Ethernet Driver Library for more information. 5.6.8.4.3.1 Initialization #include "plib_eth.h" /******************************************************************************* */ void my_ETH_Initialize(ETH_MODULE_ID id) { //Disable System (CPU) Interrupt associated with Ethernet Peripheral // using the Interrupt Peripheral Library // Example: PLIB_INT_SourceDisable(PLIB_INT_SOURCE_ETH_1); //Disable Ethernet Peripheral in case it was previously enabled PLIB_ETH_Disable(ETH_MODULE_ID1); //Disable any Ethernet Controller interrupt generation: PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID1, ETH_ALL_INTERRUPT_SOURCES); PLIB_ETH_RxDisable(ETH_MODULE_ID1); PLIB_ETH_TxRTSDisable(ETH_MODULE_ID1); while (PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID1)) {/*wait*/ } //Clear the System Interrupt Flag associated with Ethernet Peripheral // using the Interrupt Peripheral Library // Example: PLIB_INT_SourceFlagClear(PLIB_INT_SOURCE_ETH_1); ///////////////////////////////////////////////// //MAC Initialize PLIB_ETH_MIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_MIIResetDisable(ETH_MODULE_ID1); //A configuration fuse (FETHIO) setting shows which digital pins need to be configured if (CONFIGURATION_FUSE_PRIMARY_ETH_PINS==1) { ConfigurePrimaryEthernetPinsAsDigital(); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1915 } else //(CONFIGURATION_FUSE_PRIMARY_ETH_PINS==0) { ConfigureAlternateEthernetPinsAsDigital(); } //A configuration fuse (FMIIEN) settings shows which digital pins need to be configured if (CONFIGURATION_FUSE_MII_STYLE==RMII) { PLIB_ETH_RMIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_RMIIResetDisable(ETH_MODULE_ID1); PLIB_ETH_RMIISpeedSet(ETH_MODULE_ID1, ETH_RMII_100Mps); } PLIB_ETH_MIIResetEnable(ETH_MODULE_ID1); PLIB_ETH_MIIResetDisable(ETH_MODULE_ID1); PLIB_ETH_MIIMClockSet(ETH_MODULE_ID1, ETH_MII_SYSCLK_DIV_BY_10); ///////////////////////////////////////////////// //PHY Initialize is PHY dependent. // Common procedures (which may vary by PHY vender) include the following: // //Reset PHY (using Control Register 0) //Set the MII/RMII operation mode //Set the normal, swapped, or auto (preferred)MDIX //Check the PY capabilities (using Status Register 1) //Preferably the auto-negotiation should be selected if the PHY supports it. //Expose the supported capabilities (extended Register 4) //Start the negotiation (using Control Register 0) //wait for the negotiation to complete and get the link partner capabilities (extended Register 5) //negotiation result (vendor-specific register) //If auto-negotiation is not supported (or not selected) //update the PHY Duplex and speed settings (use Control Register 0 or vender-specific register) ///////////////////////////////////////////////// //MAC Configuration PLIB_ETH_RxEnable(ETH_MODULE_ID1); PLIB_ETH_TxPauseEnable(ETH_MODULE_ID1); PLIB_ETH_RxPauseEnable(ETH_MODULE_ID1); //Select the desired auto-padding, duplex, huge frame, and CRC capabilities PLIB_ETH_AutoDetecPadSet(ETH_MODULE_ID1, ETH_AUTOPAD_BY_PKT_TYPE_ADD_CRC ); PLIB_ETH_FullDuplexEnable(ETH_MODULE_ID1); //or disable for half-duplex PLIB_ETH_CRCEnable(ETH_MODULE_ID1); //or disable if EMAC does not add CRC when no padding is necessary PLIB_ETH_HugeFrameDisable(ETH_MODULE_ID1); //or enable to receive huge frames //Program back-to-back inter-packet gap and non-back-to-back interpacket gap PLIB_ETH_BackToBackIPGpSet(ETH_MODULE_ID1, 0x15 /*backToBackGapValue*/); PLIB_ETH_NonBackToBackIPG1Set(ETH_MODULE_ID1, 0x0C /*nonBackToBackGap1Value*/); PLIB_ETH_NonBackToBackIPG2Set(ETH_MODULE_ID1, 0x12 /*nonBackToBackGap2Value*/); //Set Maximum frame length PLIB_ETH_MaxFrameLengthSet(ETH_MODULE_ID1, 1527 /*maxFrameLenValue*/); //Optionally set the station MAC address(es) (or let them default to the factory value) PLIB_ETH_StationAddressSet(ETH_MODULE_ID1, 1, 0x13 /*stationAddr1Value*/); ///////////////////////////////////////////////// //Continue Ethernet Controller Initialization //Set receive buffer size - using packets that are too small impacts performance PLIB_ETH_ReceiveBufferSizeSet(ETH_MODULE_ID1, 200 /*receiveBufSizeValue*/); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1916 //Prepare the list/ring of transmit descriptors - refer to the device data sheet for more information //Prepare the list of receive descriptors populated with valid buffers for messages to be received - refer //to the device data sheet for more information //Update the transmit buffer start address and the receive buffer start address PLIB_ETH_TxPacketDescAddrSet(ETH_MODULE_ID1, (uint8_t *)0xadd1add0/*txPktDescStartAddrValue*/); PLIB_ETH_RxPacketDescAddrSet(ETH_MODULE_ID1, (uint8_t *)0xadd3add2/*rxPktDescStartAddrValue*/); //If using auto flow control, setup the full/empty watermarks and enable it PLIB_ETH_PauseTimerSet(ETH_MODULE_ID1, 0x64 /*pauseTimerValue*/); PLIB_ETH_RxEmptyWmarkSet(ETH_MODULE_ID1, 0x3F/*emptyRxWatermarkValue*/); PLIB_ETH_RxFullWmarkSet(ETH_MODULE_ID1, 0x10 /*fullRxWatermarkValue*/); PLIB_ETH_AutoFlowControlEnable(ETH_MODULE_ID1); PLIB_ETH_ReceiveFilterEnable(ETH_MODULE_ID1, ETH_MULTICAST_FILT | // enable to accept multicast address packets ETH_BROADCAST_FILTER );// enable to accept all broadcast address packets PLIB_ETH_InterruptSourceDisable(ETH_MODULE_ID1, ETH_ALL_INTERRUPT_SOURCES); //Enable the Ethernet Controller and wait until the module is ready PLIB_ETH_Enable(ETH_MODULE_ID1); while (PLIB_ETH_EthernetIsBusy(ETH_MODULE_ID1)) { //Wait } PLIB_ETH_RxEnable(ETH_MODULE_ID1); return (EXIT_SUCCESS); } 5.6.8.4.3.2 Descriptor Table Example typedef volatile struct { union { //Common to both Receive and Transmit struct { unsigned: 7; unsigned EOWN: 1; //0=Software owns, 1=Ethernet Controller owns unsigned NPV: 1; //0=Next Desc follows this, 1=Next Desc pointed to by NEXT_ED unsigned: 7; unsigned bCount: 11; unsigned: 3; unsigned EOP: 1; unsigned SOP: 1; }; uint32_t w; }; // descriptor header //Common to both Receive and Transmit uint8_t* pEDBuff; // pointer to data buffer union { //This portion differs from Receive to Transmit uint64_t RX_STATUS; //Receive Status struct { 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1917 unsigned RX_PKT_CHECKSUM: 16; unsigned: 8; unsigned RXF_RSV: 8; unsigned RSV: 32; }; uint64_t TX_STATUS; // Transmit Status struct //Transmit Struct { unsigned TSV_TRANSMIT_BYTE_COUNT: 16; unsigned TSV_TX_COLLISION_COUNT: 4; unsigned TSV_TX_CRC_ERROR: 1; unsigned TSV_TX_LENGTH_CHECK_ERROR: 1; unsigned TSV_TX_DONE: 1; unsigned TSV_TX_MULTICAST: 1; unsigned TSV_TX_BROADCAST: 1; unsigned TSV_TX_PACKET_DEFER: 1; unsigned TSV_TX_EXCESSIVE_DEFER: 1; unsigned TSV_TX_MAXIMUM_COLLISION: 1; unsigned TSV_TX_LATE_COLLISION: 1; unsigned TSV_TX_GIANT: 1; unsigned TSV_TX_UNDER_RUN: 1; unsigned TSV_TX_STATUS_VECTOR:1; unsigned TSV_TOTAL_BYTES_TX_ON_WIRE: 16; unsigned TSV_TX_CONTROL_FRAME: 1; unsigned TSV_TX_PAUSE_CONTROL_FRAME: 1; unsigned TSV_TX_BACKPRESSURE_APPLIED: 1; unsigned TSV_TX_VLAN_TAGGED_FRAME: 1; unsigned TSV_IGNORED: 4; unsigned TSV_USER_DEFINED: 8; }; }; // descriptor header //Common to both Receive and Transmit uint8_t* next_ed; // next descriptor (NPV==1); }__attribute__((__packed__)) eth_buffer_descriptor_t; // hardware RX descriptor (linked). For more information on this structure, refer to the "Ethernet" section in the family reference manual. 5.6.8.4.3.3 Transmit C Description #include "plib_eth.h" /*********************************************************************** // */ void my_ETH_Transmit(ETH_MODULE_ID id, eth_buffer_descriptor_t *pArrDcpt, uint8_t *pArrBuff, uint8_t nArrayItems, uint16_t *pArrSize) { //Input Parameters: // *pArrDcpt : pointer to an array that holds free descriptors // *pArrBuff: pointer to an array that holds buffers to be transmitted // *pArrSize: pointer to an array that holds the sizes of the buffers to be transmitted // nArrayItems: number of buffers to be transmitted // // Before attempting to transmit, the data must be placed into a packet // buffer (list) and the point(s) must be placed into transmit descriptor(s) 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1918 // Refer to the DRV_ETH or the device family reference manual for more information extern void* VA_TO_PA(char* pBuff); // extern function that returns the physical // address of the input virtual address parameter uint16_t ix; // loop index eth_buffer_descriptor_t *pEDcpt; // current Ethernet descriptor eth_buffer_descriptor_t *tailDcpt; // last Ethernet descriptor uint8_t *pBuff; // current data buffer to be transmitted uint16_t *pSize; // current data buffer size pEDcpt=pArrDcpt; pBuff=pArrBuff; pSize=pArrSize; tailDcpt=0; for(ix=0; ix< nArrayItems; ix++, pEDcpt++, pBuff++, pSize++) { // pass the descriptor to hw, use linked descriptors, set proper size pEDcpt->pEDBuff = (uint8_t *)VA_TO_PA(pBuff); // set buffer pEDcpt->w=0; // clear all the fields pEDcpt->NPV=1; // set next pointer valid pEDcpt->EOWN=1; // set hw ownership pEDcpt->bCount = *pSize; // set proper size if(tailDcpt) { tailDcpt->next_ed = VA_TO_PA(&pEDcpt); } tailDcpt=pEDcpt; } // at this moment pEDcpt is an extra descriptor we use to end the descriptors list pEDcpt->w=0; // software ownership tailDcpt->next_ed= VA_TO_PA(&pEDcpt); pArrDcpt[0].SOP=1; // start of packet pArrDcpt[nArrayItems-1].EOP=1; // end of packet PLIB_ETH_TransmitPacketDescStartAddrSet(id, VA_TO_PA(pArrDcpt)); // set the transmit address PLIB_ETH_TransmitRequestToSendIsEnabled(id); // set the TXRTS // the ETHC will transmit the buffers we just programmed /* do something else in between */ while (PLIB_ETH_TxRTSIsEnabled(id)) { //Wait until transmit is not busy } // check the ETHSTAT register to see the transfer result } 5.6.8.4.3.4 Receive #include "plib_eth.h" /*********************************************************************** // */ void my_ETH_Receive(ETH_MODULE_ID id, eth_buffer_descriptor_t *pArrDcpt, uint8_t *pArrBuff, uint8_t nArrayItems, uint16_t rxBuffSize) { extern void* VA_TO_PA(char* pBuff); // extern function that returns the physical // address of the input virtual address parameter int ix;// index eth_buffer_descriptor_t *pEDcpt; // current Ethernet descriptor eth_buffer_descriptor_t *tailDcpt; // last Ethernet descriptor char* pBuff;// current data buffer to be transmitted 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1919 pEDcpt=pArrDcpt; pBuff=pArrBuff; tailDcpt=0; //Prepare to receive PLIB_ETH_ReceiveBufferSizeSet(id, (rxBuffSize/16)); for(ix=0; ix< nArrayItems; ix++, pEDcpt++, pBuff++) {// pass the descriptor to hw, use linked descriptors, set proper size pEDcpt->pEDBuff=(unsigned char*)VA_TO_PA(pBuff);// set buffer pEDcpt->w=0;// clear all the fields pEDcpt->NPV= 1;// set next pointer valid pEDcpt->EOWN= 1;// set hw ownership if(tailDcpt) { tailDcpt->next_ed=VA_TO_PA(&pEDcpt); } tailDcpt=pEDcpt; } // at this moment pEDcpt is an extra descriptor we use to end the descriptors list pEDcpt->w=0;// software ownership tailDcpt->next_ed= VA_TO_PA(&pEDcpt); PLIB_ETH_RxPacketDescStartAddrSet(id, VA_TO_PA(pArrDcpt)); // set the address of the first RX descriptor PLIB_ETH_ReceiveEnable(id); // the Ethernet Controller will receive frames and place them in the receive buffers // we just programmed /* do something else in between */ while(PLIB_ETH_RxPacketCountGet(id)==0) { //Wait until something is received. // Packets are received as set by the receive filter } //Receive the packet //doSomethingWithReceivedPacket() // After the received packet has been processed, restore EOWN to 1 and PLIB_ETH_RxBufferCountDecrement(id); } 5.6.8.4.4 Support for Legacy "Ethernet Controller Library" These routines (PLIB_ETH_Legacy*) provide MPLAB Harmony support for applications that use the "Ethernet Controller Library for Microchip PIC32MX Microcontrollers" that is installed with XC32 compilers. (See Microchip\xc32\v1.20\docs\pic32-lib-help\hlpETH.chm for information on this legacy support.) An additional argument, an index value from the ETH_MODULE_ID enumeration, has been added to allow these functions to work from within the context of this MPLAB Harmony Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1920 Legacy Controller Library MPLAB Harmony EthClose EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthInit EthMACGetAddress EthMACOpen EthMACSetAddress EthMACSetMaxFrame EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxGetBuffer EthRxGetPacket EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket DRV_ETHMAC_LegacyClose DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove PLIB_ETH_EventsClr PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet DRV_ETHMAC_LegacyInit PLIB_ETH_MACGetAddress DRV_ETHMAC_LegacyMACOpen PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1921 Ethernet Peripheral Library Legacy Controller Library PLIB_ETH_EventsClr PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet PLIB_ETH_MACGetAddress PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthMACGetAddress EthMACSetAddress EthMACSetMaxFrame EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt 5.6.8.5 Library Interface Data Types and Constants Name Description ETH_AUTOPAD_OPTION Lists the possible automatic padding configurations. ETH_INTERRUPT_SOURCES Lists the possible values of ETH_INTERRUPT_SOURCES. ETH_MIIM_CLK Lists the possible speed selection for the Reduced Media Independent Interface (RMII). ETH_PATTERN_MATCH_MODE Lists the possible pattern match values. ETH_RECEIVE_FILTER Lists the possible values of the receive filter. ETH_RMII_SPEED Lists the possible speed selection for the Reduced Media Independent Interface (RMII). Control Functions Name Description PLIB_ETH_MCSRxResetDisable Disables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetEnable Enables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetIsEnabled Gets the EMAC Control Sub-layer/Receive domain logic reset status. PLIB_ETH_MCSTxResetDisable Disables the reset EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetEnable Enables the reset of EMAC Control Sub-layer/Transmit domain logic. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1922 PLIB_ETH_MCSTxResetIsEnabled Gets the EMAC Control Sub-layer/Transmit domain logic reset status. PLIB_ETH_MIIMReadDataGet Gets EMAC MIIM management read data after a MII read cycle has completed. PLIB_ETH_MIIMReadStart Initiates an MII management read command. PLIB_ETH_MIIMResetDisable Disables EMAC Reset MII Management. PLIB_ETH_MIIMResetEnable Enables EMAC Reset Media Independent Interface (MII) Management. PLIB_ETH_MIIMResetIsEnabled Gets the EMAC Reset MII Management enable status. PLIB_ETH_MIIMScanIncrEnable Enables EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrDisable Disables the EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrIsEnabled Gets the EMAC MIIM scan increment enable status. PLIB_ETH_MIIMScanModeDisable Disables MIIM scan mode. PLIB_ETH_MIIMScanModeEnable Enables MIIM scan mode. PLIB_ETH_MIIMScanModeIsEnabled Gets the MII management scan enable status. PLIB_ETH_MIIMWriteDataSet Sets the EMAC MIIM write data before initiating an MII write cycle. PLIB_ETH_MIIMWriteStart Initiates an MII management write command. PLIB_ETH_MIIResetDisable Disables the EMAC Soft reset. PLIB_ETH_MIIResetEnable Enables the EMAC MIIM Soft reset. PLIB_ETH_MIIResetIsEnabled Gets EMAC MIIM Soft Reset enable status. PLIB_ETH_PHYAddressGet Gets the EMAC MIIM management PHY address. PLIB_ETH_PHYAddressSet Sets the EMAC MIIM PHY address. PLIB_ETH_RegisterAddressGet Gets the EMAC MIIM management register address. PLIB_ETH_RegisterAddressSet Sets EMAC MIIM register address. PLIB_ETH_RMIIResetDisable Disables EMAC Reset RMII. PLIB_ETH_RMIIResetEnable Enables EMAC Reset RMII. PLIB_ETH_RMIIResetIsEnabled Gets the EMAC Reset RMII enable status. PLIB_ETH_RxBufferCountDecrement Causes the Receive Descriptor Buffer Counter to decrement by 1. PLIB_ETH_RxDisable Disables the Ethernet module receive logic. PLIB_ETH_RxEnable Enables the Ethernet receive logic. PLIB_ETH_RxFuncResetDisable Disables the EMAC reset receive funtion logic. PLIB_ETH_RxFuncResetEnable Enables the EMAC reset receive funtion logic. PLIB_ETH_RxFuncResetIsEnabled Gets the EMAC reset receive function status. PLIB_ETH_RxIsEnabled Gets the Ethernet module receive enable status. PLIB_ETH_RxPacketDescAddrGet Gets the address of the next receive descriptor. PLIB_ETH_RxPacketDescAddrSet Sets the Ethernet module receive packet descriptor start address. PLIB_ETH_TestPauseDisable Disables EMAC test pause. PLIB_ETH_TestPauseEnable Enables EMAC test pause. PLIB_ETH_TestPauseIsEnabled Gets the EMAC test pause enable status. PLIB_ETH_TxFuncResetDisable Disables the EMAC Transmit function reset. PLIB_ETH_TxFuncResetEnable Enables the EMAC transmit function reset. PLIB_ETH_TxFuncResetIsEnabled Gets the EMAC Transmit function reset status. PLIB_ETH_TxPacketDescAddrGet Gets the address of the next descriptor to be transmitted. PLIB_ETH_TxPacketDescAddrSet Sets the Ethernet module transmit packet descriptor start address. PLIB_ETH_TxRTSDisable Aborts an Ethernet module transmission. PLIB_ETH_TxRTSEnable Enables the Ethernet transmit request to send. PLIB_ETH_TxRTSIsEnabled Gets the Ethernet module transmit request to send status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1923 PLIB_ETH_CRCDisable Disables EMAC CRC. PLIB_ETH_CRCEnable Enables EMAC CRC. PLIB_ETH_CRCIsEnabled Gets the EMAC CRC enable status. Existence Functions Name Description PLIB_ETH_ExistsAlignmentErrorCount Identifies whether the AlignmentErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsAutoFlowControl Identifies whether the AutoFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionCounts Identifies whether the CollisionCounts feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionWindow Identifies whether the CollisionWindow feature exists on the Ethernet module. PLIB_ETH_ExistsEnable Identifies whether the Enable feature exists on the Ethernet module. PLIB_ETH_ExistsEthernetControllerStatus Identifies whether the EthernetControllerStatus feature exists on the Ethernet module. PLIB_ETH_ExistsFCSErrorCount Identifies whether the FCSErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsFramesTransmittedOK Identifies whether the FramesTransmittedOK feature exists on the Ethernet module. PLIB_ETH_ExistsFramexReceivedOK Identifies whether the FramexReceivedOK feature exists on the Ethernet module. PLIB_ETH_ExistsHashTable Identifies whether the HashTable feature exists on the Ethernet module. PLIB_ETH_ExistsInterPacketGaps Identifies whether the InterPacketGaps feature exists on the Ethernet module. PLIB_ETH_ExistsInterrupt Identifies whether the Interrupt feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Configuration Identifies whether the MAC_Configuration feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Resets Identifies whether the MAC_Resets feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Testing Identifies whether the MAC_Testing feature exists on the Ethernet module. PLIB_ETH_ExistsManualFlowControl Identifies whether the ManualFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsMaxFrameLength Identifies whether the MaxFrameLength feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Config Identifies whether the MIIM_Config feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Indicators Identifies whether the MIIM_Indicators feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMAddresses Identifies whether the MIIMAddresses feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMReadWrite Identifies whether the MIIMReadWrite feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMScanMode Identifies whether the MIIMScanMode feature exists on the Ethernet module. PLIB_ETH_ExistsMIIWriteReadData Identifies whether the MIIWriteReadData feature exists on the Ethernet module. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1924 PLIB_ETH_ExistsPatternMatch Identifies whether the PatternMatch feature exists on the Ethernet module. PLIB_ETH_ExistsPauseTimer Identifies whether the PauseTimer feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveBufferSize Identifies whether the ReceiveBufferSize feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveFilters Identifies whether the ReceiveFilters feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveOverflowCount Identifies whether the ReceiveOverflowCount feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveWmarks Identifies whether the ReceiveWmarks feature exists on the Ethernet module. PLIB_ETH_ExistsRetransmissionMaximum Identifies whether the RetransmissionMaximum feature exists on the Ethernet module. PLIB_ETH_ExistsRMII_Support Identifies whether the RMII_Support feature exists on the Ethernet module. PLIB_ETH_ExistsRxBufferCountDecrement Identifies whether the RxBufferCountDecrement feature exists on the Ethernet module. PLIB_ETH_ExistsRxEnable Identifies whether the ReceiveEnable feature exists on the Ethernet module. PLIB_ETH_ExistsRxPacketDescriptorAddress Identifies whether the RxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStationAddress Identifies whether the StationAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Ethernet module. PLIB_ETH_ExistsTransmitRTS Identifies whether the TransmitRTS feature exists on the Ethernet module. PLIB_ETH_ExistsTxPacketDescriptorAddress Identifies whether the TxPacketDescriptorAddress feature exists on the Ethernet module. Filtering Functions Name Description PLIB_ETH_HashTableGet Gets the value of the Hash table. PLIB_ETH_HashTableSet Sets the Ethernet module Hash table with the new value. PLIB_ETH_PassAllDisable Disables the EMAC PassAll. PLIB_ETH_PassAllEnable Enables the EMAC PassAll. PLIB_ETH_PassAllIsEnabled Gets the EMAC PassAll enable status. PLIB_ETH_PatternMatchChecksumGet Gets the value of the pattern match checksum register. PLIB_ETH_PatternMatchChecksumSet Sets the Ethernet module pattern match checksum register with the new value. PLIB_ETH_PatternMatchGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeSet Sets the Ethernet module pattern match mode. PLIB_ETH_PatternMatchOffsetGet Gets the value of the patter match offset register. PLIB_ETH_PatternMatchOffsetSet Sets the Ethernet module patter match offset register with the new value. PLIB_ETH_PatternMatchSet Sets the Ethernet module pattern match mask register with the new value. PLIB_ETH_PurePreambleDisable Disables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleEnable Enables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleIsEnabled Gets EMAC pure preamble enforcement enable status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1925 PLIB_ETH_ReceiveFilterDisable Disables the specified receive filter. PLIB_ETH_ReceiveFilterEnable Enables the specified receive filter. PLIB_ETH_ReceiveFilterIsEnable Disables the specified receive filter. PLIB_ETH_StationAddressGet Gets the selected EMAC station address. PLIB_ETH_StationAddressSet Sets the selected EMAC Station Address. Flow Control Functions Name Description PLIB_ETH_AutoFlowControlDisable Disables the Ethernet module Automatic Flow Control logic. PLIB_ETH_AutoFlowControlEnable Enables the Ethernet Automatic Flow Control logic. PLIB_ETH_AutoFlowControlIsEnabled Gets the Ethernet module Automatic Flow Control status. PLIB_ETH_BackPresNoBackoffDisable Disables EMAC back pressure/no backo-ff. PLIB_ETH_BackPresNoBackoffEnable Enables EMAC back pressure/no back-off. PLIB_ETH_BackPresNoBackoffIsEnabled Gets the EMAC back pressure/no back-off enable status. PLIB_ETH_ManualFlowControlDisable Disable Ethernet module Manual Flow Control logic. PLIB_ETH_ManualFlowControlEnable Enables the Ethernet Manual Flow Control logic. PLIB_ETH_ManualFlowControlIsEnabled Gets the Ethernet module Manual Flow Control enable status. PLIB_ETH_NoBackoffDisable Disables EMAC no back-offs. PLIB_ETH_NoBackoffEnable Enables EMAC no backoff. PLIB_ETH_NoBackoffIsEnabled Gets the EMAC no back-off enable status. PLIB_ETH_RxEmptyWmarkGet Gets the Ethernet module receive empty watermark. PLIB_ETH_RxEmptyWmarkSet Sets the Ethernet module receive empty water mark. PLIB_ETH_RxFullWmarkGet Gets the Ethernet module receive full watermark. PLIB_ETH_RxFullWmarkSet Sets the Ethernet module receive full water mark. PLIB_ETH_RxPauseDisable Disables the EMAC receive flow control. PLIB_ETH_RxPauseEnable Enables the EMAC receive flow control. PLIB_ETH_RxPauseIsEnabled Gets the EMAC receive flow pause enable status. PLIB_ETH_ShortcutQuantaDisable Disables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaEnable Enables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaIsEnabled Gets EMAC shortcut pause quanta enable status. PLIB_ETH_SimResetDisable Disables the EMAC simulation reset. PLIB_ETH_SimResetEnable Enables the EMAC simulation reset. PLIB_ETH_SimResetIsEnabled Gets the EMAC simulation reset status. PLIB_ETH_TestBackPressDisable Disables EMAC Test backpressure. PLIB_ETH_TestBackPressEnable Enables EMAC Test backpressure. PLIB_ETH_TestBackPressIsEnabled Gets the EMAC test backpressure enable status. PLIB_ETH_TxPauseDisable Disables the transmission of Pause frames. PLIB_ETH_TxPauseEnable Enables the the tansmission Pause frames. PLIB_ETH_TxPauseIsEnabled Gets the Ethernet module enable status. Initialization Functions Name Description PLIB_ETH_AutoDetectPadClear Clears the EMAC Auto-Pad option. PLIB_ETH_AutoDetectPadGet Gets the current EMAC Auto-Pad setting. PLIB_ETH_AutoDetectPadSet Sets the EMAC Auto-Pad option. PLIB_ETH_BackToBackIPGGet Gets the EMAC back-to-back interpacket gap. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1926 PLIB_ETH_BackToBackIPGSet Sets the EMAC back-to-back interpacket gap. PLIB_ETH_CollisionWindowGet Gets the EMAC collision window. PLIB_ETH_CollisionWindowSet Sets the EMAC collision window. PLIB_ETH_DelayedCRCDisable Disables EMAC delayed CRC. PLIB_ETH_DelayedCRCEnable Enables EMAC delayed CRC. PLIB_ETH_DelayedCRCIsEnabled Gets the EMAC delayed CRC enable status. PLIB_ETH_Disable Disables the Ethernet module. PLIB_ETH_Enable Enables the Ethernet module. PLIB_ETH_ExcessDeferDisable Disables EMAC excess defer. PLIB_ETH_ExcessDeferEnable Enables EMAC excess defer. PLIB_ETH_ExcessDeferIsEnabled Gets the EMAC excess defer enable status. PLIB_ETH_FrameLengthCheckDisable Disables the EMAC frame length check. PLIB_ETH_FrameLengthCheckEnable Enables the EMAC frame length check. PLIB_ETH_FrameLengthCheckIsEnabled Gets the EMAC frame length check status. PLIB_ETH_FullDuplexDisable Disables the EMAC full duplex operatio. PLIB_ETH_FullDuplexEnable Enables the EMAC full deuplex operation. PLIB_ETH_FullDuplexIsEnabled Gets the EMAC full duplex enable status. PLIB_ETH_HugeFrameDisable Disables the EMAC from receiving huge frames. PLIB_ETH_HugeFrameEnable Enables the EMAC to receive huge frames. PLIB_ETH_HugeFrameIsEnabled Gets the EMAC huge frame enable status. PLIB_ETH_IsEnabled Gets the Ethernet module enable status. PLIB_ETH_LongPreambleDisable Disables EMAC long preamble enforcement. PLIB_ETH_LongPreambleEnable Enables EMAC long preamble enforcement. PLIB_ETH_LongPreambleIsEnabled Gets the EMAC long preamble enforcement enable status. PLIB_ETH_LoopbackDisable Disables the EMAC loopback logic. PLIB_ETH_LoopbackEnable Enables the EMAC loopback logic. PLIB_ETH_LoopbackIsEnabled Gets the EMAC Loopback interface enable status. PLIB_ETH_MaxFrameLengthGet Gets the EMAC maximum frame length. PLIB_ETH_MaxFrameLengthSet Sets the EMAC maximum frame length. PLIB_ETH_MIIMClockGet Gets the current EMAC MIIM clock selection. PLIB_ETH_MIIMClockSet Sets the EMAC MIM clock selection. PLIB_ETH_MIIMNoPreDisable Disables EMAC No Preamble (allows preamble). PLIB_ETH_MIIMNoPreEnable Enables EMAC MIIM No Preamble (suppresses preamble). PLIB_ETH_MIIMNoPreIsEnabled Gets the EMAC MIIM No Preamble enable status. PLIB_ETH_NonBackToBackIPG1Get Gets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG1Set Sets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG2Get Gets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_NonBackToBackIPG2Set Sets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_PauseTimerGet Gets the Pause Timer value used for flow control. PLIB_ETH_PauseTimerSet Sets the Pause Timer value used for flow control. PLIB_ETH_ReceiveBufferSizeGet Gets the Ethernet module receive buffer size. PLIB_ETH_ReceiveBufferSizeSet Sets the Ethernet module receive buffer size. PLIB_ETH_ReceiveDisable Disables the EMAC from receiving frames. PLIB_ETH_ReceiveEnable Enables the EMAC to receive the frames. PLIB_ETH_ReceiveIsEnabled Gets the Ethernet EMAC receive enable status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1927 PLIB_ETH_ReTxMaxGet Gets the EMAC maximum retransmissions. PLIB_ETH_ReTxMaxSet Sets the EMAC maximum retransmissions. PLIB_ETH_RMIISpeedGet Gets the current EMAC RMII speed. PLIB_ETH_RMIISpeedSet Sets EMAC RMII Speed. PLIB_ETH_StopInIdleDisable Ethernet module operation will continue when the device enters Idle mode. PLIB_ETH_StopInIdleEnable Ethernet module operation will stop when the device enters Idle mode. PLIB_ETH_StopInIdleIsEnabled Gets the Ethernet module Stop in Idle mode enable status. Interrupt Functions Name Description PLIB_ETH_InterruptClear Clears the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptSet Sets the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptsGet Gets the Ethernet module Interrupt Flag register as a group. PLIB_ETH_InterruptSourceDisable Clears the Ethernet module Interrupt Enable register as a group, using a mask. PLIB_ETH_InterruptSourceEnable Sets the Ethernet module Interrupt Enable register in a group, using a mask. PLIB_ETH_InterruptSourceIsEnabled Gets the Ethernet module Interrupt Enable register singularly or as a group. PLIB_ETH_InterruptSourcesGet Returns the entire interrupt enable register. PLIB_ETH_InterruptStatusGet Gets the Ethernet module Interrupt Flag register as a group, using a mask. Statistics Functions Name Description PLIB_ETH_AlignErrorCountClear Sets the count of Ethernet alignment errors to zero. PLIB_ETH_AlignErrorCountGet Gets the count of Ethernet alignment errors. PLIB_ETH_FCSErrorCountClear Sets the value of the Ethernet frame check sequence error to zero. PLIB_ETH_FCSErrorCountGet Gets the count of the frame check sequence error. PLIB_ETH_FramesRxdOkCountClear Sets the value of the Ethernet received frames 'OK' count to zero. PLIB_ETH_FramesRxdOkCountGet Gets the count of the frames frames received successfully. PLIB_ETH_FramesTxdOkCountClear Sets the count of Ethernet Control frames transmitted to zero. PLIB_ETH_FramesTxdOkCountGet Gets the count of Ethernet Control Frames transmitted successfully. PLIB_ETH_MultipleCollisionCountClear Sets the value of the Ethernet multiple collision frame count to zero. PLIB_ETH_MultipleCollisionCountGet Gets the count of the frames transmitted successfully after there was more than one collision. PLIB_ETH_RxOverflowCountClear Sets the value of the Ethernet receive overflow count to zero. PLIB_ETH_RxOverflowCountGet Gets the count of the dropped Ethernet receive frames. PLIB_ETH_RxPacketCountGet Gets the value of the receive packet buffer count. PLIB_ETH_SingleCollisionCountClear Sets the value of the Ethernet single collision frame count to zero. PLIB_ETH_SingleCollisionCountGet Gets the count of the frames transmitted successfully on a second attempt. Status Functions Name Description PLIB_ETH_DataNotValid Gets the MII management read data not valid status. PLIB_ETH_EthernetIsBusy Gets the status value of the Ethernet logic busy. PLIB_ETH_LinkHasFailed Gets the MII management link fail status. PLIB_ETH_MIIMIsBusy Gets the MII management busy status. PLIB_ETH_MIIMIsScanning Gets the MII Management scanning status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1928 PLIB_ETH_ReceiveIsBusy Gets the the Ethernet receive logic busy status. PLIB_ETH_TransmitIsBusy Gets the status value of the Ethernet transmit logic busy status Description This section describes the functions, data types, and constants provided in the Ethernet Peripheral Library. Refer to each section for detailed descriptions. • Initialization Functions • Status Functions • Control Functions • Filtering Functions • Flow Control Functions • Statistics Functions • Interrupt Functions 5.6.8.5.1 Initialization Functions 5.6.8.5.1.1 PLIB_ETH_AutoDetectPadClear Function C void PLIB_ETH_AutoDetectPadClear( ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option ); Description This function sets the EMAC Auto-Pad option. If any auto-pad option other than ETH_AUTOPAD_DISABLED_CHECK_CRC is selected, the CRC must be enabled by PLIB_ETH_CRCEnable. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_AutoDetectPadClear(MY_ETH_INSTANCE, PAD_OPTION); 5.6.8.5.1.2 PLIB_ETH_AutoDetectPadGet Function C ETH_AUTOPAD_OPTION PLIB_ETH_AutoDetectPadGet( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1929 Description This function gets the current EMAC Auto-Pad setting. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns ETH_AUTOPAD_OPTION Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example autoPadOption = PLIB_ETH_AutoDetectPadGet(MY_ETH_INSTANCE); 5.6.8.5.1.3 PLIB_ETH_AutoDetectPadSet Function C void PLIB_ETH_AutoDetectPadSet( ETH_MODULE_ID index, ETH_AUTOPAD_OPTION option ); Description This function sets the EMAC Auto-Pad option. If any auto-pad option other than ETH_AUTOPAD_DISABLED_CHECK_CRC is selected, the CRC must be enabled by PLIB_ETH_CRCEnable. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_AutoDetectPadSet(MY_ETH_INSTANCE, PAD_OPTION); 5.6.8.5.1.4 PLIB_ETH_BackToBackIPGGet Function C uint8_t PLIB_ETH_BackToBackIPGGet( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1930 Description This function gets the EMAC back-to-back interpacket gap. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns backToBackIPGValue - Back-to-back inter-packet gap (7-bits) Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_BackToBackIPGGet(MY_ETH_INSTANCE); 5.6.8.5.1.5 PLIB_ETH_BackToBackIPGSet Function C void PLIB_ETH_BackToBackIPGSet( ETH_MODULE_ID index, uint8_t backToBackIPGValue ); Description This function sets the EMAC back-to-back interpacket gap. Preconditions None. Parameters Parameters Description index Identifier for the device instance backToBackIPGValue Back-to-back inter-packet gap Returns None. Remarks In Full-Duplex mode, the register value should be the desired period in nibble times minus 3. In Full-Duplex, the recommended setting is 0x15. In Half-Duplex mode, the register value should be the desired period in nibble times minus 6. In Half-Duplex, the recommended setting is 0x12. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_BackToBackIPGSet(MY_ETH_INSTANCE, backToBackIPGValue); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1931 5.6.8.5.1.6 PLIB_ETH_CollisionWindowGet Function C uint8_t PLIB_ETH_CollisionWindowGet( ETH_MODULE_ID index ); Description This function gets the EMAC collision window. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns collisionWindowValue - A uint8_t (6-bit) value. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_CollisionWindowGet(MY_ETH_INSTANCE); 5.6.8.5.1.7 PLIB_ETH_CollisionWindowSet Function C void PLIB_ETH_CollisionWindowSet( ETH_MODULE_ID index, uint8_t collisionWindowValue ); Description This function sets the EMAC collision window. Preconditions None. Parameters Parameters Description index Identifier for the device instance collisionWindowValue Collision window Returns None. Remarks This is a programmable field representing the slot time or collision window during which collisions occur in properly configured networks. Since the collision window starts at the beginning of transmission, the preamble and SFD is included. Its default of 0x37 (55d) corresponds to the count of frame bytes at the end of the window. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1932 Example PLIB_ETH_CollisionWindowSet(MY_ETH_INSTANCE, collisionWindowValue); 5.6.8.5.1.8 PLIB_ETH_DelayedCRCDisable Function C void PLIB_ETH_DelayedCRCDisable( ETH_MODULE_ID index ); Description This function disables EMAC delayed CRC. No proprietary header exists. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_DelayedCRCDisable(MY_ETH_INSTANCE); 5.6.8.5.1.9 PLIB_ETH_DelayedCRCEnable Function C void PLIB_ETH_DelayedCRCEnable( ETH_MODULE_ID index ); Description This function enables EMAC delayed CRC. A proprietary packet header exists. Four bytes of the packet header are ignored by the CRC function. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_DelayedCRCEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1933 5.6.8.5.1.10 PLIB_ETH_DelayedCRCIsEnabled Function C bool PLIB_ETH_DelayedCRCIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC delayed CRC enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - A proprietary header exists. Four bytes of packet header are ignored by the CRC function. • false - No proprietary header Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_DelayedCRCIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.11 PLIB_ETH_Disable Function C void PLIB_ETH_Disable( ETH_MODULE_ID index ); Description This function disables the Ethernet module. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_Disable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1934 5.6.8.5.1.12 PLIB_ETH_Enable Function C void PLIB_ETH_Enable( ETH_MODULE_ID index ); Description This function enables the Ethernet module. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_Enable(MY_ETH_INSTANCE); 5.6.8.5.1.13 PLIB_ETH_ExcessDeferDisable Function C void PLIB_ETH_ExcessDeferDisable( ETH_MODULE_ID index ); Description This function disables EMAC excess defer. The EMAC will abort when the excessive deferral limit is reached. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ExcessDeferDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1935 5.6.8.5.1.14 PLIB_ETH_ExcessDeferEnable Function C void PLIB_ETH_ExcessDeferEnable( ETH_MODULE_ID index ); Description This function enables EMAC excess defer. The EMAC will defer to the carrier indefinitely. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ExcessDeferEnable(MY_ETH_INSTANCE); 5.6.8.5.1.15 PLIB_ETH_ExcessDeferIsEnabled Function C bool PLIB_ETH_ExcessDeferIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC excess defer enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC will defer to carrier indefinitely as per the Standard • false - The EMAC will abort when the excessive deferral limit is reached Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ExcessDeferIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1936 5.6.8.5.1.16 PLIB_ETH_FrameLengthCheckDisable Function C void PLIB_ETH_FrameLengthCheckDisable( ETH_MODULE_ID index ); Description This function disables the EMAC frame length check. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FrameLengthCheckDisable(MY_ETH_INSTANCE); 5.6.8.5.1.17 PLIB_ETH_FrameLengthCheckEnable Function C void PLIB_ETH_FrameLengthCheckEnable( ETH_MODULE_ID index ); Description This function enables the EMAC frame length check. Both transmit and receive frame lengths are compared to the Length/Type field. If the Length/Type field represents a length, the check is performed. Mismatches are reported on the transmit/receive statistics vector. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FrameLengthCheckEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1937 5.6.8.5.1.18 PLIB_ETH_FrameLengthCheckIsEnabled Function C bool PLIB_ETH_FrameLengthCheckIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC frame length check status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Both transmit and receive frame lengths are compared to the Length/Type field. If the Length/Type field represents a length then the check is performed. Mismatches are reported on the transmit/receive statistics vector. • false - Length/Type field check is not performed Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_FrameLengthCheckIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.19 PLIB_ETH_FullDuplexDisable Function C void PLIB_ETH_FullDuplexDisable( ETH_MODULE_ID index ); Description This function disables the EMAC full-duplex operation, which results in the EMAC operating in half-duplex. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FullDuplexDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1938 5.6.8.5.1.20 PLIB_ETH_FullDuplexEnable Function C void PLIB_ETH_FullDuplexEnable( ETH_MODULE_ID index ); Description This function enables the EMAC full duplex operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FullDuplexEnable(MY_ETH_INSTANCE); 5.6.8.5.1.21 PLIB_ETH_FullDuplexIsEnabled Function C bool PLIB_ETH_FullDuplexIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC full duplex enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC operates in Full-Duplex mode • false - The EMAC operates in Half-Duplex mode Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_FullDuplexIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1939 5.6.8.5.1.22 PLIB_ETH_HugeFrameDisable Function C void PLIB_ETH_HugeFrameDisable( ETH_MODULE_ID index ); Description This function disables the EMAC from receiving huge frames. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_HugeFrameDisable(MY_ETH_INSTANCE); 5.6.8.5.1.23 PLIB_ETH_HugeFrameEnable Function C void PLIB_ETH_HugeFrameEnable( ETH_MODULE_ID index ); Description This function enables the EMAC receiving the frames of any length. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_HugeFrameEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1940 5.6.8.5.1.24 PLIB_ETH_HugeFrameIsEnabled Function C bool PLIB_ETH_HugeFrameIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC huge frame enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Frames of any length are transmitted and received • false - Huge frames are not allowed for receive or transmit Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_HugeFrameIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.25 PLIB_ETH_IsEnabled Function C bool PLIB_ETH_IsEnabled( ETH_MODULE_ID index ); Description This function returns the Ethernet module enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module is enabled • false - Ethernet module is disabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_IsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1941 5.6.8.5.1.26 PLIB_ETH_LongPreambleDisable Function C void PLIB_ETH_LongPreambleDisable( ETH_MODULE_ID index ); Description This function disables EMAC long preamble enforcement. The EMAC allows any length preamble. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_LongPreambleDisable(MY_ETH_INSTANCE); 5.6.8.5.1.27 PLIB_ETH_LongPreambleEnable Function C void PLIB_ETH_LongPreambleEnable( ETH_MODULE_ID index ); Description This function enables EMAC long preamble enforcement. The EMAC only allows receive packets which contain preamble fields less than 12 bytes in length. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_LongPreambleEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1942 5.6.8.5.1.28 PLIB_ETH_LongPreambleIsEnabled Function C bool PLIB_ETH_LongPreambleIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC long preamble enforcement enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC only allows receive packets, which contain preamble fields less than 12 bytes in length • false - The EMAC allows any length preamble Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_LongPreambleIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.29 PLIB_ETH_LoopbackDisable Function C void PLIB_ETH_LoopbackDisable( ETH_MODULE_ID index ); Description This function disables the EMAC loopback. EMAC resumes normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_LoopbackDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1943 5.6.8.5.1.30 PLIB_ETH_LoopbackEnable Function C void PLIB_ETH_LoopbackEnable( ETH_MODULE_ID index ); Description This function enables the EMAC loopback logic. The EMAC transmit interface is looped back to the EMAC receive interface. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_LoopbackEnable(MY_ETH_INSTANCE); 5.6.8.5.1.31 PLIB_ETH_LoopbackIsEnabled Function C bool PLIB_ETH_LoopbackIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC Loopback interface enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - EMAC transmit interface is looped back to the EMAC receive interface • false - EMAC normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_LoopbackIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1944 5.6.8.5.1.32 PLIB_ETH_MaxFrameLengthGet Function C uint16_t PLIB_ETH_MaxFrameLengthGet( ETH_MODULE_ID index ); Description This function gets the EMAC maximum frame length. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns MaxFrameLength - Maximum frame length Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_MaxFrameLengthGet(MY_ETH_INSTANCE); 5.6.8.5.1.33 PLIB_ETH_MaxFrameLengthSet Function C void PLIB_ETH_MaxFrameLengthSet( ETH_MODULE_ID index, uint16_t MaxFrameLength ); Description This function sets the EMAC maximum frame length. Preconditions None. Parameters Parameters Description index Identifier for the device instance MaxFrameLength Maximum frame length Returns None. Remarks This field resets to 0x05EE, which represents a maximum receive frame of 1518 bytes. An untagged maximum size Ethernet frame is 1518 bytes. A tagged frame adds four octets for a total of 1522 bytes. If a shorter/longer maximum length restriction is desired, program this 16-bit field. If a proprietary header is allowed, this field should be adjusted accordingly. For example, if 4-byte headers are prepended to 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1945 frames, MACMAXF could be set to 1527 bytes. This would allow the maximum VLAN tagged frame plus the 4-byte header. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MaxFrameLengthSet(MY_ETH_INSTANCE, MaxFrameLength); 5.6.8.5.1.34 PLIB_ETH_MIIMClockGet Function C ETH_MIIM_CLK PLIB_ETH_MIIMClockGet( ETH_MODULE_ID index ); Description This function returns the current EMAC MIIM clock selection. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns MIIMClock - of type PLIB_ETH_MIIM_CLK Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example clkstat = PLIB_ETH_MIIMClockGet(MY_ETH_INSTANCE); 5.6.8.5.1.35 PLIB_ETH_MIIMClockSet Function C void PLIB_ETH_MIIMClockSet( ETH_MODULE_ID index, ETH_MIIM_CLK MIIMClock ); Description This function sets the EMAC MIIM clock selection. Preconditions None. Parameters Parameters Description index Identifier for the device instance MIIMClock of type ETH_MIIM_CLK - the system clock divisor for MII Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1946 Remarks This field is used by the clock divide logic in creating the MII Management Clock (MDC), which the IEEE 802.3 Specification defines to be no faster than 2.5 MHz. Some PHYs support clock rates up to 12.5 MHz. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMClockSet(MY_ETH_INSTANCE, MIIMClock); 5.6.8.5.1.36 PLIB_ETH_MIIMNoPreDisable Function C void PLIB_ETH_MIIMNoPreDisable( ETH_MODULE_ID index ); Description This function disables EMAC No preamble (allows preamble). Normal read/write cycles are performed. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMNoPreDisable(MY_ETH_INSTANCE); 5.6.8.5.1.37 PLIB_ETH_MIIMNoPreEnable Function C void PLIB_ETH_MIIMNoPreEnable( ETH_MODULE_ID index ); Description This function enables EMAC MIIM No Preamble (suppresses preamble). The MII Management will perform read/write cycles without the 32-bit preamble field. Some PHYs support suppressed preamble. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1947 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMNoPreEnable(MY_ETH_INSTANCE); 5.6.8.5.1.38 PLIB_ETH_MIIMNoPreIsEnabled Function C bool PLIB_ETH_MIIMNoPreIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC MIIM No Preamble enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management will perform read/write cycles without the 32-bit preamble field. Some PHYs support suppressed preamble. • false - Normal read/write cycles are performed Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIMNoPreIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.39 PLIB_ETH_NonBackToBackIPG1Get Function C uint8_t PLIB_ETH_NonBackToBackIPG1Get( ETH_MODULE_ID index ); Description This function gets the EMAC non-back-to-back interpacket gap register 1. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns nonBackToBackIPGValue - Non-back-to-back inter-packet gap (7-bits) 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1948 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_NonBackToBackIPG1Get(MY_ETH_INSTANCE); 5.6.8.5.1.40 PLIB_ETH_NonBackToBackIPG1Set Function C void PLIB_ETH_NonBackToBackIPG1Set( ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue ); Description This function sets the EMAC non-back-to-back interpacket gap register 1. A value of 0x0C is recommended. Preconditions None. Parameters Parameters Description index Identifier for the device instance nonBackToBackIPGValue Non-back-to-back inter-packet gap Returns None. Remarks This is a programmable field representing the optional carrierSense window referenced in the IEEE 802.3 Specification. If a carrier is detected during the timing of IPGR1, the MAC defers to the carrier. If, however, the carrier comes after IPGR1, the MAC continues timing IPGR2 and transmits, knowingly causing a collision, thereby ensuring fair access to the medium. Its range of values is 0x0 to IPGR2. Its recommended value is 0xC (12d). This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_NonBackToBackIPG1Set(MY_ETH_INSTANCE, nonBackToBackIPGValue); 5.6.8.5.1.41 PLIB_ETH_NonBackToBackIPG2Get Function C uint8_t PLIB_ETH_NonBackToBackIPG2Get( ETH_MODULE_ID index ); Description This function gets the EMAC non-back-to-back interpacket gap register 2. Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1949 Returns nonBackToBackIPGValue - Non-back-to-back inter-packet gap (7-bits) Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_NonBackToBackIPG2Get(MY_ETH_INSTANCE); 5.6.8.5.1.42 PLIB_ETH_NonBackToBackIPG2Set Function C void PLIB_ETH_NonBackToBackIPG2Set( ETH_MODULE_ID index, uint8_t nonBackToBackIPGValue ); Description This function sets the EMAC non-back-to-back interpacket gap register 2. A value of 0x12 is recommended. Preconditions None. Parameters Parameters Description index Identifier for the device instance nonBackToBackIPGValue Non-back-to-back inter-packet gap Returns None. Remarks This is a programmable field representing the non-back-to-back Inter-Packet-Gap. Its recommended value is 0x12 (18d), which represents the minimum IPG of 0.96 us (in 100 Mbps) or 9.6 us (in 10 Mbps). This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_NonBackToBackIPG2Set(MY_ETH_INSTANCE, nonBackToBackIPGValue); 5.6.8.5.1.43 PLIB_ETH_PauseTimerGet Function C uint16_t PLIB_ETH_PauseTimerGet( ETH_MODULE_ID index ); Description This function gets the Pause Timer value used for flow control. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1950 Parameters Parameters Description index Identifier for the device instance Returns PauseTimerValue - Pause Timer Value Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PauseTimerValue = PLIB_ETH_PauseTimerGet(MY_ETH_INSTANCE); 5.6.8.5.1.44 PLIB_ETH_PauseTimerSet Function C void PLIB_ETH_PauseTimerSet( ETH_MODULE_ID index, uint16_t PauseTimerValue ); Description This function sets the Pause Timer value used for flow control. Preconditions Write to the Pause Timer register before enabling the receiver. Call this function before calling PLIB_ETH_ReceiveEnable() Parameters Parameters Description index Identifier for the device instance PauseTimerValue used for Flow Control Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PauseTimerSet(MY_ETH_INSTANCE, PauseTimerValue); 5.6.8.5.1.45 PLIB_ETH_ReceiveBufferSizeGet Function C uint8_t PLIB_ETH_ReceiveBufferSizeGet( ETH_MODULE_ID index ); Description This function gets the Ethernet receive buffer size. The buffer size is set from 16 bytes up to 2032 bytes in increments of 16 bytes each. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1951 Parameters Parameters Description index Identifier for the device instance Returns ReceiveBufferSize - receive buffer size divided by 16 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example size = PLIB_ETH_ReceiveBufferSizeGet(MY_ETH_INSTANCE); 5.6.8.5.1.46 PLIB_ETH_ReceiveBufferSizeSet Function C void PLIB_ETH_ReceiveBufferSizeSet( ETH_MODULE_ID index, uint8_t ReceiveBufferSize ); Description This function sets the Ethernet receive buffer size. The buffer size is set from 16 bytes up to 2032 bytes in increments of 16 bytes each. Preconditions None. Parameters Parameters Description index Identifier for the device instance ReceiveBufferSize In units of 16 bytes, must be a value of 0x01 to 0x7F, 0x00 is invalid Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReceiveBufferSizeSet(MY_ETH_INSTANCE, ReceiveBufferSize/16 ); 5.6.8.5.1.47 PLIB_ETH_ReceiveDisable Function C void PLIB_ETH_ReceiveDisable( ETH_MODULE_ID index ); Description This function disables the EMAC from receiving frames. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1952 Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReceiveDisable(MY_ETH_INSTANCE); 5.6.8.5.1.48 PLIB_ETH_ReceiveEnable Function C void PLIB_ETH_ReceiveEnable( ETH_MODULE_ID index ); Description This function enables the EMAC to receive the frames. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReceiveEnable(MY_ETH_INSTANCE); 5.6.8.5.1.49 PLIB_ETH_ReceiveIsEnabled Function C bool PLIB_ETH_ReceiveIsEnabled( ETH_MODULE_ID index ); Description This function gets the Ethernet EMAC receive enable status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1953 Parameters Parameters Description index Identifier for the device instance Returns • true - Enable the EMAC to receive frames • false - Disable the EMAC to receive frames Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ReceiveIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.1.50 PLIB_ETH_ReTxMaxGet Function C uint8_t PLIB_ETH_ReTxMaxGet( ETH_MODULE_ID index ); Description This function gets the EMAC maximum retransmissions. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns retransmitMax - Maximum number of retransmissions Remarks The maximum number of attempts is limited to 0x0F. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_ReTxMaxGet(MY_ETH_INSTANCE); 5.6.8.5.1.51 PLIB_ETH_ReTxMaxSet Function C void PLIB_ETH_ReTxMaxSet( ETH_MODULE_ID index, uint16_t retransmitMax ); Description This function sets the EMAC maximum retransmissions. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1954 Parameters Parameters Description index Identifier for the device instance retransmitMax Maximum number of retransmissions Returns None. Remarks This is a programmable field specifying the number of retransmission attempts following a collision before aborting the packet due to excessive collisions. The IEEE 802.3 Specification standard specifies the maximum number of attempts (attemptLimit) to be 0xF (15d). Its default is 000. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReTxMaxSet(retransmitMax); 5.6.8.5.1.52 PLIB_ETH_RMIISpeedGet Function C ETH_RMII_SPEED PLIB_ETH_RMIISpeedGet( ETH_MODULE_ID index ); Description This function gets the current EMAC RMII speed. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns RMII_100Mbps - RMII running at 100Mbps RMII_10Mbps - RMII running at 10Mbps Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RMIISpeedGet(MY_ETH_INSTANCE); 5.6.8.5.1.53 PLIB_ETH_RMIISpeedSet Function C void PLIB_ETH_RMIISpeedSet( ETH_MODULE_ID index, ETH_RMII_SPEED RMIISpeed ); Description This function sets EMAC RMII speed. RMII speed can be either RMII_100Mbps or RMII_10Mbps. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1955 Preconditions None. Parameters Parameters Description index Identifier for the device instance RMIISpeed RMII_100Mbps or RMII_10Mbps of type ETH_RMII_SPEED Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RMIISpeedSet(MY_ETH_INSTANCE, ETH_RMII_SPEED RMIISpeed); 5.6.8.5.1.54 PLIB_ETH_StopInIdleDisable Function C void PLIB_ETH_StopInIdleDisable( ETH_MODULE_ID index ); Description This function directs the Ethernet module to continue operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_StopInIdleDisable(MY_ETH_INSTANCE); 5.6.8.5.1.55 PLIB_ETH_StopInIdleEnable Function C void PLIB_ETH_StopInIdleEnable( ETH_MODULE_ID index ); Description This function directs the Ethernet module to stop operation when the device enters Idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1956 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_StopInIdleEnable(MY_ETH_INSTANCE); 5.6.8.5.1.56 PLIB_ETH_StopInIdleIsEnabled Function C bool PLIB_ETH_StopInIdleIsEnabled( ETH_MODULE_ID index ); Description This function returns the Ethernet module Stop in Idle mode enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module transfers stop during Idle mode • false - Ethernet module transfers continue to run during Idle mode Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_StopInIdleIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2 Control Functions 5.6.8.5.2.1 PLIB_ETH_MCSRxResetDisable Function C void PLIB_ETH_MCSRxResetDisable( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1957 Description This function disables the reset EMAC Control Sub-layer/Receive domain logic. The MCS/Receive domain logic is released from reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MCSRxResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.2 PLIB_ETH_MCSRxResetEnable Function C void PLIB_ETH_MCSRxResetEnable( ETH_MODULE_ID index ); Description This function enables the reset EMAC Control Sub-layer/Receive domain logic. The MCS/Receive domain logic is held in reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MCSRxResetEnable(MY_ETH_INSTANCE); 5.6.8.5.2.3 PLIB_ETH_MCSRxResetIsEnabled Function C bool PLIB_ETH_MCSRxResetIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC Control Sub-layer/Receive domain logic reset status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1958 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - EMAC Control Sub-layer/Receive domain logic is in reset • false - EMAC Control Sub-layer/Receive domain logic is not in reset Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MCSRxResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.4 PLIB_ETH_MCSTxResetDisable Function C void PLIB_ETH_MCSTxResetDisable( ETH_MODULE_ID index ); Description This function disables the reset EMAC Control Sub-layer/Transmit domain logic. The MCS/Transmit domain logic is released from reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MCSTxResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.5 PLIB_ETH_MCSTxResetEnable Function C void PLIB_ETH_MCSTxResetEnable( ETH_MODULE_ID index ); Description This function resets the EMAC Control Sub-layer/Transmit domain logic. The MCS/Transmit domain logic is held in reset. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1959 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MCSTxResetEnable(MY_ETH_INSTANCE); 5.6.8.5.2.6 PLIB_ETH_MCSTxResetIsEnabled Function C bool PLIB_ETH_MCSTxResetIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC Control Sub-layer/Transmit domain logic reset status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - EMAC Control Sub-layer/Transmit domain logic is held in reset • false - EMAC Control Sub-layer/Transmit domain logic is not in reset Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MCSTxResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.7 PLIB_ETH_MIIMReadDataGet Function C uint16_t PLIB_ETH_MIIMReadDataGet( ETH_MODULE_ID index ); Description This function gets EMAC MIIM management read data after a MII read cycle has completed. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1960 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns readData - MII read data Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example readData = PLIB_ETH_MIIMReadDataGet(MY_ETH_INSTANCE); 5.6.8.5.2.8 PLIB_ETH_MIIMReadStart Function C void PLIB_ETH_MIIMReadStart( ETH_MODULE_ID index ); Description This function initiates an MII read command. The MII Management module will perform a single read cycle. To get data, use PLIB_ETH_MIIReadDataGet. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example while (PLIB_ETH_MIIMIsBusy(MY_ETH_INSTANCE)) { //Wait until MII Link is not busy } PLIB_ETH_MIIReadStart(MY_ETH_INSTANCE); while (PLIB_ETH_MIIReadIsDataNotValid(MY_ETH_INSTANCE)) { //Wait until read is complete } data = PLIB_ETH_MIIReadDataGet(MY_ETH_INSTANCE); 5.6.8.5.2.9 PLIB_ETH_MIIMResetDisable Function C void PLIB_ETH_MIIMResetDisable( 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1961 ETH_MODULE_ID index ); Description This function disables EMAC Reset MII Management. EMAC will resume normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.10 PLIB_ETH_MIIMResetEnable Function C void PLIB_ETH_MIIMResetEnable( ETH_MODULE_ID index ); Description This function enables EMAC Reset MII Management and holds the MII Management module in reset while enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks MII Management held in Reset after This function is called. Disable ResetMIIanagement to return to normal operation. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMResetEnable(MY_ETH_INSTANCE); 5.6.8.5.2.11 PLIB_ETH_MIIMResetIsEnabled Function C bool PLIB_ETH_MIIMResetIsEnabled( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1962 Description This function gets the EMAC Reset MII Management enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Reset the MII Management module • false - Normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIMResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.12 PLIB_ETH_MIIMScanIncrEnable Function C void PLIB_ETH_MIIMScanIncrEnable( ETH_MODULE_ID index ); Description This function enables EMAC MIIM Scan Increment. The MII Management module will perform read cycles across a range of PHYs. The read cycles will start from address 1 through the value set in the PHY address register. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks The read cycles will start at PHY address 1 and continue through the value set for as the PHY address register. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMScanIncrEnable(MY_ETH_INSTANCE); 5.6.8.5.2.13 PLIB_ETH_MIIMScanIncrDisable Function C void PLIB_ETH_MIIMScanIncrDisable( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1963 Description This function disables the EMAC MIIM Scan Increment. Allows continuous reads of the same PHY. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMScanIncrDisable(MY_ETH_INSTANCE); 5.6.8.5.2.14 PLIB_ETH_MIIMScanIncrIsEnabled Function C bool PLIB_ETH_MIIMScanIncrIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC MIIM scan increment enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management module will perform read cycles across a range of PHYs. The read cycles will start from address 1 through the value set in the PHY address register. • false - Continuous reads of the same PHY Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example ScanIncrement = PLIB_ETH_MIIMScanIncrIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.15 PLIB_ETH_MIIMScanModeDisable Function C void PLIB_ETH_MIIMScanModeDisable( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1964 Description This function disables MIIM scan mode. Scan is disabled for Normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMScanModeDisable(MY_ETH_INSTANCE); 5.6.8.5.2.16 PLIB_ETH_MIIMScanModeEnable Function C void PLIB_ETH_MIIMScanModeEnable( ETH_MODULE_ID index ); Description This function enables MIIM scan mode. The MII Management module will perform read cycles continuously. (Useful for monitoring the Link Fail.) Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMScanModeEnable(MY_ETH_INSTANCE); 5.6.8.5.2.17 PLIB_ETH_MIIMScanModeIsEnabled Function C bool PLIB_ETH_MIIMScanModeIsEnabled( ETH_MODULE_ID index ); Description This function returns the MII management scan enable status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1965 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management module will perform read cycles continuously (for example, useful for monitoring the Link Fail) • false - Normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIMScanModeIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.18 PLIB_ETH_MIIMWriteDataSet Function C void PLIB_ETH_MIIMWriteDataSet( ETH_MODULE_ID index, uint16_t writeData ); Description This function sets the EMAC MIIM write data before initiating write cycle. Preconditions Prior to a call to this routine, the PHY and Register addresses should be set using PLIB_ETH_MIIPHYAddressSet and PLIB_ETH_MIIRegisterAddressSet. Parameters Parameters Description index Identifier for the device instance writeData MII write data Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, WriteData); 5.6.8.5.2.19 PLIB_ETH_MIIMWriteStart Function C void PLIB_ETH_MIIMWriteStart( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1966 Description This function initiates an MII management read command. The MII Management module will perform a write cycle. Preconditions The PHY address and MII register address must be configured before a write using PLIB_ETH_MIIPHYAddressSet(MY_ETH_INSTANCE, phyAddr) and PLIB_ETH_MIIRegisterAddressSet(MY_ETH_INSTANCE, regAddr) Data to be written must be first loaded into the MII write register using PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, writeData) Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIMWriteDataSet(MY_ETH_INSTANCE, dataToWrite); PLIB_ETH_MIIMWriteStart(MY_ETH_INSTANCE); 5.6.8.5.2.20 PLIB_ETH_MIIResetDisable Function C void PLIB_ETH_MIIResetDisable( ETH_MODULE_ID index ); Description This function disables the EMAC MIIM Soft reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIResetDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1967 5.6.8.5.2.21 PLIB_ETH_MIIResetEnable Function C void PLIB_ETH_MIIResetEnable( ETH_MODULE_ID index ); Description This function enables the EMAC MIIM soft reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MIIResetEnable(MY_ETH_INSTANCE); 5.6.8.5.2.22 PLIB_ETH_MIIResetIsEnabled Function C bool PLIB_ETH_MIIResetIsEnabled( ETH_MODULE_ID index ); Description This function gets EMAC MIIM Soft reset enable status. By default this bit is set to '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - MAC MII is in reset • false - MAC MII is not in reset Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIResetIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1968 5.6.8.5.2.23 PLIB_ETH_PHYAddressGet Function C uint8_t PLIB_ETH_PHYAddressGet( ETH_MODULE_ID index ); Description This function gets the EMAC MIIM management PHY address. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns phyAddr - A 5-bit address of the PHY Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example phyAddr = PLIB_ETH_PHYAddressGet(MY_ETH_INSTANCE); 5.6.8.5.2.24 PLIB_ETH_PHYAddressSet Function C void PLIB_ETH_PHYAddressSet( ETH_MODULE_ID index, uint8_t phyAddr ); Description This function sets the EMAC MIIM PHY address. This field represents the 5-bit PHY Address field of Management cycles. Up to 31 PHYs can be addressed (0 is reserved). Preconditions None. Parameters Parameters Description index Identifier for the device instance phyAddr A 5-bit address of the PHY Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PHYAddressSet(MY_ETH_INSTANCE, PhyAddr); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1969 5.6.8.5.2.25 PLIB_ETH_RegisterAddressGet Function C uint8_t PLIB_ETH_RegisterAddressGet( ETH_MODULE_ID index ); Description This function gets the EMAC MIIM management register address. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns regAddr - The (5-bit) address of the MII Registers Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example regAddr = PLIB_ETH_RegisterAddressGet(MY_ETH_INSTANCE); 5.6.8.5.2.26 PLIB_ETH_RegisterAddressSet Function C void PLIB_ETH_RegisterAddressSet( ETH_MODULE_ID index, uint8_t regAddr ); Description This function sets the EMAC MIIM register address. Up to 32 registers may be accessed. Preconditions None. Parameters Parameters Description index Identifier for the device instance regAddr The (5-bit) address of the MII Registers. Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RegisterAddressSet(MY_ETH_INSTANCE, regAddr); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1970 5.6.8.5.2.27 PLIB_ETH_RMIIResetDisable Function C void PLIB_ETH_RMIIResetDisable( ETH_MODULE_ID index ); Description This function disables EMAC Reset RMII for normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RMIIResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.28 PLIB_ETH_RMIIResetEnable Function C void PLIB_ETH_RMIIResetEnable( ETH_MODULE_ID index ); Description This function enables EMAC Reset RMII. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RMIIResetEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1971 5.6.8.5.2.29 PLIB_ETH_RMIIResetIsEnabled Function C bool PLIB_ETH_RMIIResetIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC Reset RMII enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Reset the EMAC RMII module • false - Normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_RMIIResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.30 PLIB_ETH_RxBufferCountDecrement Function C void PLIB_ETH_RxBufferCountDecrement( ETH_MODULE_ID index ); Description This function causes the Receive Descriptor Buffer Counter to decrement by 1. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks Hardware increments the receive buffer counter and software decrements it. If the receive buffer counter is incremented by the receive logic at the same time, the receive buffer counter will appear unchanged. Always reads as '0', so there is no get value routine. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1972 Example PLIB_ETH_RxBufferCountDecrement(MY_ETH_INSTANCE); 5.6.8.5.2.31 PLIB_ETH_RxDisable Function C void PLIB_ETH_RxDisable( ETH_MODULE_ID index ); Description This function disables the Ethernet receive logic. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks Disabling Ethernet receive is not recommended for making changes to any receive-related registers. After the receiver has been enabled, the Ethernet module must be reinitialized to implement changes. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxDisable(MY_ETH_INSTANCE); 5.6.8.5.2.32 PLIB_ETH_RxEnable Function C void PLIB_ETH_RxEnable( ETH_MODULE_ID index ); Description This function enables the Ethernet receive logic. Packets are received and stored in the receive buffer as controlled by the filter configuration. Preconditions All receive registers must be configured before calling this function. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1973 Example PLIB_ETH_RxEnable(MY_ETH_INSTANCE); 5.6.8.5.2.33 PLIB_ETH_RxFuncResetDisable Function C void PLIB_ETH_RxFuncResetDisable( ETH_MODULE_ID index ); Description This function disables the EMAC reset receive funtion logic. The reset receive function logic is released from reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxFuncResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.34 PLIB_ETH_RxFuncResetEnable Function C void PLIB_ETH_RxFuncResetEnable( ETH_MODULE_ID index ); Description This function enables the EMAC reset receive function logic. The receive function logic is held in reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxFuncResetEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1974 5.6.8.5.2.35 PLIB_ETH_RxFuncResetIsEnabled Function C bool PLIB_ETH_RxFuncResetIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC reset receive function status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - EMAC Receive function logic is held in reset • false - EMAC Receive function logic is not in reset Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_RxFuncResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.36 PLIB_ETH_RxIsEnabled Function C bool PLIB_ETH_RxIsEnabled( ETH_MODULE_ID index ); Description This function returns the Ethernet module receive enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module receive is enabled • false - Ethernet module receive is disabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ReceiveIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1975 5.6.8.5.2.37 PLIB_ETH_RxPacketDescAddrGet Function C uint8_t * PLIB_ETH_RxPacketDescAddrGet( ETH_MODULE_ID index ); Description This function gets the address of the next receive descriptor to be used. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns ReceivePacketDescriptorAddress - receive packet descriptor address Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example RxPacketDescAddr = PLIB_ETH_RxPacketDescAddrGet(MY_ETH_INSTANCE); 5.6.8.5.2.38 PLIB_ETH_RxPacketDescAddrSet Function C void PLIB_ETH_RxPacketDescAddrSet( ETH_MODULE_ID index, uint8_t * rxPacketDescStartAddr ); Description This function sets the Ethernet receive packet descriptor start address. Preconditions No transmit, receive, or DMA operations should be in progress when this function is called. Call this function before enabling transmit and receive. Parameters Parameters Description index Identifier for the device instance rxPacketDescStartAddr This address must be 4-byte aligned. (The least significant 2 bits must be '00'.) Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxPacketDescAddrSet(MY_ETH_INSTANCE, rxPacketDescStartAddr) 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1976 5.6.8.5.2.39 PLIB_ETH_TestPauseDisable Function C void PLIB_ETH_TestPauseDisable( ETH_MODULE_ID index ); Description This function disables EMAC Test Pause. The EMAC will resume normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TestPauseDisable(MY_ETH_INSTANCE); 5.6.8.5.2.40 PLIB_ETH_TestPauseEnable Function C void PLIB_ETH_TestPauseEnable( ETH_MODULE_ID index ); Description This function enables EMAC test pause. The EMAC Control sub-layer will inhibit transmissions, just as if a Pause Receive Control frame with a non-zero pause time parameter was received. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1977 Example PLIB_ETH_TestPauseEnable(MY_ETH_INSTANCE); 5.6.8.5.2.41 PLIB_ETH_TestPauseIsEnabled Function C bool PLIB_ETH_TestPauseIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC test pause enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC Control sub-layer will inhibit transmissions, just as if a Pause Receive Control frame with a non-zero pause time parameter was received • false - Normal operation Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_TestPauseIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.42 PLIB_ETH_TxFuncResetDisable Function C void PLIB_ETH_TxFuncResetDisable( ETH_MODULE_ID index ); Description This function disables the EMAC Transmit function reset. The EMAC transmit function is released from reset for normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1978 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxFuncResetDisable(MY_ETH_INSTANCE); 5.6.8.5.2.43 PLIB_ETH_TxFuncResetEnable Function C void PLIB_ETH_TxFuncResetEnable( ETH_MODULE_ID index ); Description This function enables the EMAC transmit function reset. The transmit function is held in reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxFuncResetEnable(MY_ETH_INSTANCE); 5.6.8.5.2.44 PLIB_ETH_TxFuncResetIsEnabled Function C bool PLIB_ETH_TxFuncResetIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC Transmit function reset status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - EMAC transmit function logic is held in reset • false - EMAC transmit function logic is not in reset 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1979 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxFuncResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.45 PLIB_ETH_TxPacketDescAddrGet Function C uint8_t * PLIB_ETH_TxPacketDescAddrGet( ETH_MODULE_ID index ); Description This function gets the address of the next transmit descriptor. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Transmit Packet Descriptor Start Address. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example txPacketDescAddr = PLIB_ETH_TxPacketDescAddrGet(MY_ETH_INSTANCE); 5.6.8.5.2.46 PLIB_ETH_TxPacketDescAddrSet Function C void PLIB_ETH_TxPacketDescAddrSet( ETH_MODULE_ID index, uint8_t * txPacketDescStartAddr ); Description This function sets the Ethernet transmit packet descriptor start address. Preconditions No transmit, receive, or DMA operations should be in progress when this function is called. Call this function before enabling transmit and receive. Parameters Parameters Description index Identifier for the device instance txPacketDescStartAddr This address must be 4-byte aligned. (The least significant 2 bits must be '00'.) Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1980 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxPacketDescAddrSet(MY_ETH_INSTANCE, txPacketDescStartAddr) 5.6.8.5.2.47 PLIB_ETH_TxRTSDisable Function C void PLIB_ETH_TxRTSDisable( ETH_MODULE_ID index ); Description This function aborts an Ethernet module transmission and disables the transmitter after the current packet has completed. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks When disabled by software, transmission stops after the current packet has been completed. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxRTSDisable(MY_ETH_INSTANCE); 5.6.8.5.2.48 PLIB_ETH_TxRTSEnable Function C void PLIB_ETH_TxRTSEnable( ETH_MODULE_ID index ); Description This function enables the Ethernet request to send. Transmit logic is activated and packet(s) defined in the Ethernet descriptor table are transmitted. Preconditions The TX descriptor list and TX DMA must be initialized using PLIB_ETH_TransmitPacketDescStartAddrSet. Parameters Parameters Description index Identifier for the device instance Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1981 Remarks This status is cleared by hardware when the transmission is complete. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxRTSEnable(MY_ETH_INSTANCE); 5.6.8.5.2.49 PLIB_ETH_TxRTSIsEnabled Function C bool PLIB_ETH_TxRTSIsEnabled( ETH_MODULE_ID index ); Description This function returns the Ethernet module transmit request to send status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module transmit is active • false - Ethernet module transmission has stopped or has completed Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_TransmitRTSIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.2.50 PLIB_ETH_CRCDisable Function C void PLIB_ETH_CRCDisable( ETH_MODULE_ID index ); Description This function disables EMAC CRC. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1982 Remarks The frames presented to the EMAC have a valid CRC This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_CRCDisable(MY_ETH_INSTANCE); 5.6.8.5.2.51 PLIB_ETH_CRCEnable Function C void PLIB_ETH_CRCEnable( ETH_MODULE_ID index ); Description This function enables EMAC CRC. The EMAC will append CRC whether padding is required or not. This must be enabled if auto-padding is enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_CRCEnable(MY_ETH_INSTANCE); 5.6.8.5.2.52 PLIB_ETH_CRCIsEnabled Function C bool PLIB_ETH_CRCIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC CRC enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC will append a CRC to every frame whether or not padding was required. Must be set if auto-padding is enabled. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1983 • false - The frames presented to the EMAC have a valid CRC Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_CRCIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.3 Status Functions 5.6.8.5.3.1 PLIB_ETH_DataNotValid Function C bool PLIB_ETH_DataNotValid( ETH_MODULE_ID index ); Description This function gets the MII management read data not valid status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management read cycle has not completed and the read data is not yet valid • false - The MII Management read cycle is complete and the read data is valid Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_DataNotValid(MY_ETH_INSTANCE); Also see the example for function: PLIB_ETH_MIIReadStart(). 5.6.8.5.3.2 PLIB_ETH_EthernetIsBusy Function C bool PLIB_ETH_EthernetIsBusy( ETH_MODULE_ID index ); Description This function sets the value of the Ethernet logic busy. A request indicates that the module has just been turned ON or is completing a transaction after being turned OFF. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1984 Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet logic has been turned ON or is completing a transaction • false - Ethernet logic is idle Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_EthernetIsBusy(MY_ETH_INSTANCE); 5.6.8.5.3.3 PLIB_ETH_LinkHasFailed Function C bool PLIB_ETH_LinkHasFailed( ETH_MODULE_ID index ); Description This function returns the MII management link fail status. This value reflects the last read from the PHY status register. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management module link fail has occurred • false - The MII Management module link fail has not occured Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_LinkHasFailed(MY_ETH_INSTANCE); 5.6.8.5.3.4 PLIB_ETH_MIIMIsBusy Function C bool PLIB_ETH_MIIMIsBusy( ETH_MODULE_ID index ); Description This function returns the MII management busy status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1985 Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management module is currently performing an MII Management read or write cycle • false - The MII Management is free Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIMIsBusy(MY_ETH_INSTANCE); 5.6.8.5.3.5 PLIB_ETH_MIIMIsScanning Function C bool PLIB_ETH_MIIMIsScanning( ETH_MODULE_ID index ); Description This function gets the MII Management scanning status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MII Management module scan operation (continuous MII Management Read cycles) is in progress • false - The MII Management scan operation is not in progress Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_MIIMIsScanning(MY_ETH_INSTANCE); 5.6.8.5.3.6 PLIB_ETH_ReceiveIsBusy Function C bool PLIB_ETH_ReceiveIsBusy( ETH_MODULE_ID index ); Description This function gets the Ethernet receive logic busy status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1986 Parameters Parameters Description index Identifier for the device instance Returns • true - Receive logic is receiving data • false - Receive logic is idle Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ReceiveIsBusy(MY_ETH_INSTANCE); 5.6.8.5.3.7 PLIB_ETH_TransmitIsBusy Function C bool PLIB_ETH_TransmitIsBusy( ETH_MODULE_ID index ); Description This function gets the value of the Ethernet transmit logic busy status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Transmit logic is sending data • false - Transmit logic is idle Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_TransmitIsBusy(MY_ETH_INSTANCE); 5.6.8.5.4 Filtering Functions 5.6.8.5.4.1 PLIB_ETH_HashTableGet Function C uint32_t PLIB_ETH_HashTableGet( ETH_MODULE_ID index ); Description This function gets the value of the Hash table. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1987 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns hashTable - Hash table value (64-bits) Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_HashTableGet(MY_ETH_INSTANCE); 5.6.8.5.4.2 PLIB_ETH_HashTableSet Function C void PLIB_ETH_HashTableSet( ETH_MODULE_ID index, uint64_t hashTableValue ); Description This function sets the Hash table with the new value. Preconditions Call PLIB_ETH_HashTableFilterDisable to disable the Hash table filter before changing the hash table, or set the Hash Table prior to calling PLIB_ETH_ReceiveEnable. Parameters Parameters Description index Identifier for the device instance hashTableValue hash table value (64-bits) Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_HashTableSet(MY_ETH_INSTANCE, hashTableValue); 5.6.8.5.4.3 PLIB_ETH_PassAllDisable Function C void PLIB_ETH_PassAllDisable( ETH_MODULE_ID index ); Description This function disables the EMAC PassAll. Control frames are ignored. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1988 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PassAllDisable(MY_ETH_INSTANCE); 5.6.8.5.4.4 PLIB_ETH_PassAllEnable Function C void PLIB_ETH_PassAllEnable( ETH_MODULE_ID index ); Description This function enables the EMAC PassAll, which enables both the normal and the control frames to be passed. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PassAllEnable(MY_ETH_INSTANCE); 5.6.8.5.4.5 PLIB_ETH_PassAllIsEnabled Function C bool PLIB_ETH_PassAllIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC PassAll enable status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1989 Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC will accept all frames regardless of type (normal vs. Control) • false - The received Control frames are ignored Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_PassAllIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.4.6 PLIB_ETH_PatternMatchChecksumGet Function C uint16_t PLIB_ETH_PatternMatchChecksumGet( ETH_MODULE_ID index ); Description This function gets the value of the patter match checksum register. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns The pattern match checksum. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_PatternMatchChecksumGet(MY_ETH_INSTANCE); 5.6.8.5.4.7 PLIB_ETH_PatternMatchChecksumSet Function C void PLIB_ETH_PatternMatchChecksumSet( ETH_MODULE_ID index, uint16_t PatternMatchChecksumValue ); Description This function sets the pattern match checksum register with the new value. Preconditions Call PLIB_ETH_PatternMatchModeSet(ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1990 Parameters Parameters Description index Identifier for the device instance to be configured PatternMatchChecksumValue Pattern match checksum value Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PatternMatchChecksumSet(MY_ETH_INSTANCE, PatternMatchChecksumValue); 5.6.8.5.4.8 PLIB_ETH_PatternMatchGet Function C uint64_t PLIB_ETH_PatternMatchGet( ETH_MODULE_ID index ); Description This function gets the selected value of the patter match mask register. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns patternMatchMaskValue - Pattern Match Mask Values Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_PatternMatchGet(MY_ETH_INSTANCE); 5.6.8.5.4.9 PLIB_ETH_PatternMatchModeGet Function C ETH_PATTERN_MATCH_MODE PLIB_ETH_PatternMatchModeGet( ETH_MODULE_ID index ); Description This function gets the selected value of the patter match mask register. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1991 Parameters Parameters Description index Identifier for the device instance Returns modeSel - The method of pattern matching from ETH_PATTERN_MATCH_DISABLED Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_PatternMatchModeGet(MY_ETH_INSTANCE); 5.6.8.5.4.10 PLIB_ETH_PatternMatchModeSet Function C void PLIB_ETH_PatternMatchModeSet( ETH_MODULE_ID index, ETH_PATTERN_MATCH_MODE modeSel ); Description This function sets the pattern match mode. Preconditions Set the value before calling PLIB_ETH_ReceiveEnable(). Parameters Parameters Description index Identifier for the device instance modeSel The method of pattern matching from ETH_PATTERN_MATCH_DISABLED Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PatternMatchModeSet(MY_ETH_INSTANCE, ETH_PATTERN_MATCH_DISABLED); 5.6.8.5.4.11 PLIB_ETH_PatternMatchOffsetGet Function C uint16_t PLIB_ETH_PatternMatchOffsetGet( ETH_MODULE_ID index ); Description This function gets the value of the patter match offset register. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1992 Parameters Parameters Description index Identifier for the device instance Returns PatternMatchOffsetValue - Pattern match offset value Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example value = PLIB_ETH_PatternMatchOffsetGet(MY_ETH_INSTANCE); 5.6.8.5.4.12 PLIB_ETH_PatternMatchOffsetSet Function C void PLIB_ETH_PatternMatchOffsetSet( ETH_MODULE_ID index, uint16_t PatternMatchOffsetValue ); Description This function sets the pattern match offset register with the new value. Preconditions Call PLIB_ETH_PatternMatchModeSet(ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable(). Parameters Parameters Description index Identifier for the device instance PatternMatchOffsetValue Pattern match offset value Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PatternMatchOffsetSet(MY_ETH_INSTANCE, PatternMatchOffsetValue); 5.6.8.5.4.13 PLIB_ETH_PatternMatchSet Function C void PLIB_ETH_PatternMatchSet( ETH_MODULE_ID index, uint64_t patternMatchMaskValue ); Description This function sets the pattern match mask register with the new value. Preconditions Call PLIB_ETH_PatternMatchModeSet(index,ETH_PATTERN_MATCH_DISABLED) to disable PatternMatch before changing 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1993 the pattern match mask, or set the value before calling PLIB_ETH_ReceiveEnable. Parameters Parameters Description index Identifier for the device instance patternMatchMaskValue Pattern Match Mask Values (64-bits) Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PatternMatchSet(MY_ETH_INSTANCE, patternMatchMaskValue); 5.6.8.5.4.14 PLIB_ETH_PurePreambleDisable Function C void PLIB_ETH_PurePreambleDisable( ETH_MODULE_ID index ); Description This function disables the EMAC pure preamble enforcement. The EMAC does not perform any preamble checking. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Example PLIB_ETH_PurePreambleDisable(MY_ETH_INSTANCE); Rsemarks: This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6.8.5.4.15 PLIB_ETH_PurePreambleEnable Function C void PLIB_ETH_PurePreambleEnable( ETH_MODULE_ID index ); Description This function enables EMAC pure preamble enforcement. The EMAC will verify the contents of the preamble and discard packets with errors in the preamble. sPrecondition: None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1994 Parameters Parameters Description index Identifier for the device instance Returns None. Remarks The EMAC will verify the content of the preamble to ensure it contains 0x55 and is error-free. A packet with errors in its preamble is discarded. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_PurePreambleEnable(MY_ETH_INSTANCE); 5.6.8.5.4.16 PLIB_ETH_PurePreambleIsEnabled Function C bool PLIB_ETH_PurePreambleIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC pure preamble enforcement enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC will verify the content of the preamble to ensure it contains 0x55 and is error-free. A packet with errors in its preamble is discarded. • false - The EMAC does not perform any preamble checking Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_PurePreambleIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.4.17 PLIB_ETH_ReceiveFilterDisable Function C void PLIB_ETH_ReceiveFilterDisable( ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter ); Description This function disables the specified receive filter. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1995 Preconditions None. Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be disabled from the enumerated selection ETH_RECEIVE_FILTER Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReceiveFilterDisable(index, ETH_CRC_OK_FILTER | ETH_RUNT_ENABLE_FILTER | ETH_UNICAST_FILTER ); 5.6.8.5.4.18 PLIB_ETH_ReceiveFilterEnable Function C void PLIB_ETH_ReceiveFilterEnable( ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter ); Description This function enables the specified receive filter. Preconditions None. Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be enabled from the enumerated selection ETH_RECEIVE_FILTER Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ReceiveFilterEnable(index, ETH_CRC_OK_FILTER | ETH_RUNT_ENABLE_FILTER | ETH_UNICAST_FILTER ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1996 5.6.8.5.4.19 PLIB_ETH_ReceiveFilterIsEnable Function C bool PLIB_ETH_ReceiveFilterIsEnable( ETH_MODULE_ID index, ETH_RECEIVE_FILTER filter ); Description This function disables the specified receive filter. Preconditions None. Parameters Parameters Description index Identifier for the device instance filter The selection of receive filters to be disabled from the enumerated selection ETH_RECEIVE_FILTER Returns • true - If at least one of the specified filters is enabled • false - If no specified filter is enabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example if (PLIB_ETH_ReceiveFilterIsEnable(index, ETH_UNICAST_FILTER)) { PLIB_ETH_ReceiveFilterDisable(MY_MODULE_ID, ETH_UNICAST_FILTER); } 5.6.8.5.4.20 PLIB_ETH_StationAddressGet Function C uint8_t PLIB_ETH_StationAddressGet( ETH_MODULE_ID index, uint8_t which ); Description This function gets the selected EMAC station address. Preconditions None. Parameters Parameters Description index Identifier for the device instance which Select station address to change. Valid values are 1,2,3,4,5,6. Returns stationAddress1 - Station address 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1997 Remarks On a reset, this register is loaded with the factory preprogrammed station address. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stationAddr1 = PLIB_ETH_StationAddress1Get(MY_ETH_INSTANCE, which); 5.6.8.5.4.21 PLIB_ETH_StationAddressSet Function C void PLIB_ETH_StationAddressSet( ETH_MODULE_ID index, uint8_t which, uint8_t stationAddress ); Description This function sets the selected EMAC Station Address. Preconditions None. Parameters Parameters Description index Identifier for the device instance which Select station address to change. Valid values are 1,2,3,4,5,6. stationAddress Station Address. Returns None. Remarks On a reset, this register is loaded with the factory preprogrammed station address. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_StationAddressSet(MY_ETH_INSTANCE, which, stationAddress); 5.6.8.5.5 Flow Control Functions 5.6.8.5.5.1 PLIB_ETH_AutoFlowControlDisable Function C void PLIB_ETH_AutoFlowControlDisable( ETH_MODULE_ID index ); Description This function disables the Ethernet Automatic Flow Control logic. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1998 Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_AutoFlowControlDisable(MY_ETH_INSTANCE); 5.6.8.5.5.2 PLIB_ETH_AutoFlowControlEnable Function C void PLIB_ETH_AutoFlowControlEnable( ETH_MODULE_ID index ); Description This function enables Ethernet Automatic Flow Control logic. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks The full and empty watermarks are used to automatically enable and disable flow control, respectively. When the number of received buffers rises to the full watermark, flow control is automatically enabled. When the receive buffer count falls to the empty watermark, flow control is automatically disabled. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_AutoFlowControlEnable(MY_ETH_INSTANCE); 5.6.8.5.5.3 PLIB_ETH_AutoFlowControlIsEnabled Function C bool PLIB_ETH_AutoFlowControlIsEnabled( ETH_MODULE_ID index ); Description This function gets the Ethernet Automatic Flow Control enable status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-1999 Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module Automatic Flow Control is enabled • false - Ethernet module Autmoatic Flow Control is disabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_AutoFlowControlIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.4 PLIB_ETH_BackPresNoBackoffDisable Function C void PLIB_ETH_BackPresNoBackoffDisable( ETH_MODULE_ID index ); Description This function disables EMAC back pressure/no back-off. The EMAC will back-off when there is backpressure and collisions occur. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_BackPresNoBackoffDisable(MY_ETH_INSTANCE); 5.6.8.5.5.5 PLIB_ETH_BackPresNoBackoffEnable Function C void PLIB_ETH_BackPresNoBackoffEnable( ETH_MODULE_ID index ); Description This function enables EMAC backpressure/no back-off. The EMAC will not back-off when there is backpressure and collisions occur. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2000 Parameters Parameters Description index Identifier for the device instance Returns None. Remarks The EMAC after incidentally causing a collision during backpressure will immediately retransmit without back-off reducing the chance of further collisions and ensuring transmit packets get sent. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_BackPresNoBackoffEnable(MY_ETH_INSTANCE); 5.6.8.5.5.6 PLIB_ETH_BackPresNoBackoffIsEnabled Function C bool PLIB_ETH_BackPresNoBackoffIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC back pressure/no back-off enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC after incidentally causing a collision during backpressure will immediately retransmit without back-off reducing the chance of further collisions and ensuring transmit packets get sent • false - The EMAC will not remove the back-off Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_BackPresNoBackoffIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.7 PLIB_ETH_ManualFlowControlDisable Function C void PLIB_ETH_ManualFlowControlDisable( ETH_MODULE_ID index ); Description This function disables the Ethernet Manual Flow Control logic and automatically sends a Pause frame with a 0x0000 Pause Timer value. This function affects both transmit and receive operations. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2001 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks Disabling Manual Flow Control will automatically send a Pause frame with a 0x0000 Pause Timer value to disable flow control. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ManualFlowControlDisable(MY_ETH_INSTANCE); 5.6.8.5.5.8 PLIB_ETH_ManualFlowControlEnable Function C void PLIB_ETH_ManualFlowControlEnable( ETH_MODULE_ID index ); Description This function enables the Ethernet Manual Flow Control logic. Enabling Manual Flow Control will send a Pause frame using the Pause Timer value. While enabled, a Pause frame is repeated every 128 x (Pause timer value)/2 transmit clock cycles. Affects both transmit and receive operations. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ManualFlowControlEnable(MY_ETH_INSTANCE); 5.6.8.5.5.9 PLIB_ETH_ManualFlowControlIsEnabled Function C bool PLIB_ETH_ManualFlowControlIsEnabled( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2002 Description This function returns the Ethernet module Manual Flow Control enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Ethernet module Manual Flow Control is enabled • false - Ethernet module Manual Flow Control is disabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ManualFlowControlIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.10 PLIB_ETH_NoBackoffDisable Function C void PLIB_ETH_NoBackoffDisable( ETH_MODULE_ID index ); Description This function disables EMAC no back-off. The EMAC will back-off when a collision occurs. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_NoBackoffDisable(MY_ETH_INSTANCE); 5.6.8.5.5.11 PLIB_ETH_NoBackoffEnable Function C void PLIB_ETH_NoBackoffEnable( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2003 Description This function enables EMAC no back-off. The EMAC will not back-off when a collision occurs. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks Following a collision, the EMAC will immediately retransmit rather than using the Binary Exponential Back-off algorithm as specified in the Standard. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_NoBackoffEnable(MY_ETH_INSTANCE); 5.6.8.5.5.12 PLIB_ETH_NoBackoffIsEnabled Function C bool PLIB_ETH_NoBackoffIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC no back-off enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Following a collision, the EMAC will immediately retransmit • false - Following a collision, the EMAC will use the Binary Exponential Back-off algorithm Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_NoBackoffIsEnabled(MY_ETsH_INSTANCE); 5.6.8.5.5.13 PLIB_ETH_RxEmptyWmarkGet Function C uint8_t PLIB_ETH_RxEmptyWmarkGet( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2004 Description This function gets the Ethernet receive empty watermark. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns receiveEmptyWmark - Empty watermark value Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example watermarkValue = PLIB_ETH_RxEmptyWmarkGet(MY_ETH_INSTANCE); 5.6.8.5.5.14 PLIB_ETH_RxEmptyWmarkSet Function C void PLIB_ETH_RxEmptyWmarkSet( ETH_MODULE_ID index, uint8_t watermarkValue ); Description This function sets the Ethernet receive empty water mark with a new value. The software controlled Receive Buffer Empty Wmark is compared against the receive buffer count to determine the empty watermark condition for the empty watermark interrupt and for disabling flow control if Auto Flow Control is enabled. The Full Wmark value should always be greater than the Empty Wmark value. Preconditions None. Parameters Parameters Description index Identifier for the device instance watermarkValue Empty watermark value Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxEmptyWmarkSet(MY_ETH_INSTANCE, watermarkValue); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2005 5.6.8.5.5.15 PLIB_ETH_RxFullWmarkGet Function C uint8_t PLIB_ETH_RxFullWmarkGet( ETH_MODULE_ID index ); Description This function gets the Ethernet receive full watermark. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns receiveFullWmark - Full watermark value Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example watermarkValue = PLIB_ETH_RxFullWmarkGet(MY_ETH_INSTANCE); 5.6.8.5.5.16 PLIB_ETH_RxFullWmarkSet Function C void PLIB_ETH_RxFullWmarkSet( ETH_MODULE_ID index, uint8_t watermarkValue ); Description This function sets the Ethernet receive full water mark with a new value. The software controlled RX Buffer Full Wmark Pointer is compared against the receive buffer count to determine the full watermark condition for the full watermark interrupt and for enabling flow control if Auto Flow Control is enabled. The Full Wmark value should always be greater than the Empty Wmark value. Preconditions None. Parameters Parameters Description index Identifier for the device instance watermarkValue Full watermark value Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2006 Example PLIB_ETH_RxFullWmarkSet(MY_ETH_INSTANCE, watermarkValue); 5.6.8.5.5.17 PLIB_ETH_RxPauseDisable Function C void PLIB_ETH_RxPauseDisable( ETH_MODULE_ID index ); Description This function disables the EMAC receive flow control. The received Pause Flow control frames are ignored. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxPauseDisable(MY_ETH_INSTANCE); 5.6.8.5.5.18 PLIB_ETH_RxPauseEnable Function C void PLIB_ETH_RxPauseEnable( ETH_MODULE_ID index ); Description This function enables the EMAC receive flow control. The EMAC will act upon the received Pause frames. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxPauseEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2007 5.6.8.5.5.19 PLIB_ETH_RxPauseIsEnabled Function C bool PLIB_ETH_RxPauseIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC receive flow pause enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC acts upon received Pause Flow Control frames • false - Received Pause Flow Control frames are ignored Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example status = PLIB_ETH_RxPauseIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.20 PLIB_ETH_ShortcutQuantaDisable Function C void PLIB_ETH_ShortcutQuantaDisable( ETH_MODULE_ID index ); Description This function disables EMAC shortcut pause quanta. The EMAC will resume normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ShortcutQuantaDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2008 5.6.8.5.5.21 PLIB_ETH_ShortcutQuantaEnable Function C void PLIB_ETH_ShortcutQuantaEnable( ETH_MODULE_ID index ); Description This function enables EMAC shortcut pause quanta. The EMAC reduces the effective pause auanta from 64 byte-times to 1 byte-time. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_ShortcutQuantaEnable(MY_ETH_INSTANCE); 5.6.8.5.5.22 PLIB_ETH_ShortcutQuantaIsEnabled Function C bool PLIB_ETH_ShortcutQuantaIsEnabled( ETH_MODULE_ID index ); Description This function returns EMAC shortcut pause quanta enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC reduces the effective Pause Quanta from 64 byte-times to 1 byte-time • false - Normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_ShortcutQuantaIsEnabled(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2009 5.6.8.5.5.23 PLIB_ETH_SimResetDisable Function C void PLIB_ETH_SimResetDisable( ETH_MODULE_ID index ); Description This function disables the EMAC simulation reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_SimResetDisable(MY_ETH_INSTANCE); 5.6.8.5.5.24 PLIB_ETH_SimResetEnable Function C void PLIB_ETH_SimResetEnable( ETH_MODULE_ID index ); Description This function enables the EMAC simulation reset and resets the random number generator within the transmit (TX) function. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_SimResetEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2010 5.6.8.5.5.25 PLIB_ETH_SimResetIsEnabled Function C bool PLIB_ETH_SimResetIsEnabled( ETH_MODULE_ID index ); Description This function returns the EMAC simulation reset status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Simulation Reset is enabled • false - Simulation Reset is disabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example stat = PLIB_ETH_SimResetIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.26 PLIB_ETH_TestBackPressDisable Function C void PLIB_ETH_TestBackPressDisable( ETH_MODULE_ID index ); Description This function disables EMAC Test backpressure. The EMAC will resume normal operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TestBackPressDisable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2011 5.6.8.5.5.27 PLIB_ETH_TestBackPressEnable Function C void PLIB_ETH_TestBackPressEnable( ETH_MODULE_ID index ); Description This function enables EMAC Test backpressure. The EMAC will assert backpressure on the link. Backpressure causes preamble to be transmitted, raising carrier sense. A transmit packet from the system will be sent during backpressure. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is intended for testing only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TestBackPressEnable(MY_ETH_INSTANCE); 5.6.8.5.5.28 PLIB_ETH_TestBackPressIsEnabled Function C bool PLIB_ETH_TestBackPressIsEnabled( ETH_MODULE_ID index ); Description This function gets the EMAC test backpressure enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EMAC will assert backpressure on the link. Backpressure causes the preamble to be transmitted, raising the carrier sense. A transmit packet from the system will be sent during backpressure. • false - Normal operation Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2012 Example PLIB_ETH_TestBackPressIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.5.29 PLIB_ETH_TxPauseDisable Function C void PLIB_ETH_TxPauseDisable( ETH_MODULE_ID index ); Description This function disables the transmit Pause frames. The Pause frames are blocked from being transmitted. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxPauseDisable(MY_ETH_INSTANCE); 5.6.8.5.5.30 PLIB_ETH_TxPauseEnable Function C void PLIB_ETH_TxPauseEnable( ETH_MODULE_ID index ); Description This function enables the tansmission Pause frames. The Pause frames are allowed for transmission. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_TxPauseEnable(MY_ETH_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2013 5.6.8.5.5.31 PLIB_ETH_TxPauseIsEnabled Function C bool PLIB_ETH_TxPauseIsEnabled( ETH_MODULE_ID index ); Description This function gets the Ethernet module enable status. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - Pause Flow Control frames are allowed to be transmitted • false - Pause Flow Control frames are blocked Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example status = PLIB_ETH_TxPauseIsEnabled(MY_ETH_INSTANCE); 5.6.8.5.6 Interrupt Functions 5.6.8.5.6.1 PLIB_ETH_InterruptClear Function C void PLIB_ETH_InterruptClear( ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function clears the Ethernet module interrupt source status using a mask. Logically 'OR' the masks together. Any masks not ORed with the others will be disabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2014 Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example // To clear several interrupts with one command, execute the following: PLIB_ETH_InterruptClear(MY_ETH_INSTANCE, ETH_EMPTY_WATERMARK_INTERRUPT | ETH_FULL_WATERMARK_INTERRUPT | ETH_RX_FIFO_OVERFLOW_ERROR_INTERRUPT ); 5.6.8.5.6.2 PLIB_ETH_InterruptSet Function C void PLIB_ETH_InterruptSet( ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function sets the Ethernet module interrupt source status using a mask. Logically 'OR' the masks together. Any masks not OR'd with the others will be disabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example // To set several interrupt flags with one command, execute the following: PLIB_ETH_InterruptSet(MY_ETH_INSTANCE, ETH_EMPTY_WATERMARK_INTERRUPT | ETH_FULL_WATERMARK_INTERRUPT | ETH_RX_FIFO_OVERFLOW_ERROR_INTERRUPT ); 5.6.8.5.6.3 PLIB_ETH_InterruptsGet Function C ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptsGet( ETH_MODULE_ID index ); Description Gets the Ethernet module Interrupt Flag register as a group. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2015 Parameters Parameters Description index Identifier for the device instance Returns Interrupt bit map, as defined in ETH_INTERRUPT_SOURCES, showing which interrupts have fired. Remarks none. Example 5.6.8.5.6.4 PLIB_ETH_InterruptSourceDisable Function C void PLIB_ETH_InterruptSourceDisable( ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function disables the Ethernet module interrupts by using a mask to select one or multiple interrupts to disable. Logically 'OR' elements of ETH_INTERRUPT_SOURCES together. Preconditions None. Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example // To disable some interrupts with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT | ETH_TRANSMIT_ABORT_INTERRUPT | ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT | ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT ); // Or to disable one interrupt with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT); // Or to disable all interrupts with one command, execute the following: PLIB_ETH_InterruptSourceDisble(MY_ETH_INSTANCE, ETH_ALL_ETH_INTERRUPTS); 5.6.8.5.6.5 PLIB_ETH_InterruptSourceEnable Function C void PLIB_ETH_InterruptSourceEnable( 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2016 ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function enables the Ethernet module interrupts by using a mask to enable one or multiple interrupt enables. Logically 'OR' elements of ETH_INTERRUPT_SOURCES together. Preconditions None. Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example // To enable some interrupts with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT | ETH_TRANSMIT_ABORT_INTERRUPT | ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT | ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT); // Or to enable one interrupt with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_TRANSMIT_DONE_INTERRUPT); // Or to enable all interrupts with one command, execute the following: PLIB_ETH_InterruptSourceEnable(MY_ETH_INSTANCE, ETH_ALL_ETH_INTERRUPTS); 5.6.8.5.6.6 PLIB_ETH_InterruptSourceIsEnabled Function C bool PLIB_ETH_InterruptSourceIsEnabled( ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function returns a true if any of the specified interupt sources are enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance mask The interrupt mask(s) to be checked Returns • true - If any of the specified sources are enabled 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2017 • false - If none of the specified sources are enabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example if ( PLIB_ETH_InterruptSourceIsEnabled(index, ETH_TRANSMIT_DONE_INTERRUPT)) { //If the interrupt is enabled, disable it... PLIB_ETH_InterruptSourceDisable(index, ETH_TRANSMIT_DONE_INTERRUPT); } 5.6.8.5.6.7 PLIB_ETH_InterruptSourcesGet Function C ETH_INTERRUPT_SOURCES PLIB_ETH_InterruptSourcesGet( ETH_MODULE_ID index ); Description This function returns the entire interrupt enable register. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Bit map of interrupt sources, all ORed together, as defined by ETH_INTERRUPT_SOURCES. Remarks None. Example 5.6.8.5.6.8 PLIB_ETH_InterruptStatusGet Function C bool PLIB_ETH_InterruptStatusGet( ETH_MODULE_ID index, ETH_INTERRUPT_SOURCES intmask ); Description This function gets the Ethernet module Interrupt Flag register using a mask. Preconditions None. Parameters Parameters Description index Identifier for the device instance intmask Members of ETH_INTERRUPT_SOURCES logically ORed together 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2018 Returns • true - If any of the specified source statuses are enabled • false - If none of the specified source statuses are enabled Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example if (PLIB_ETH_InterruptStatusGet(index, ETH_TRANSMIT_DONE_INTERRUPT)) { PLIB_ETH_InterruptClear(index, ETH_TRANSMIT_DONE_INTERRUPT); } 5.6.8.5.7 Statistics Functions 5.6.8.5.7.1 PLIB_ETH_AlignErrorCountClear Function C void PLIB_ETH_AlignErrorCountClear( ETH_MODULE_ID index ); Description This function sets the count of Ethernet alignment errors to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value count of alignment errors Returns None. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_AlignErrorCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.2 PLIB_ETH_AlignErrorCountGet Function C uint16_t PLIB_ETH_AlignErrorCountGet( ETH_MODULE_ID index ); Description This function gets the count of Ethernet alignment errors. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2019 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns value - Count of alignment errors Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_AlignErrorCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.3 PLIB_ETH_FCSErrorCountClear Function C void PLIB_ETH_FCSErrorCountClear( ETH_MODULE_ID index ); Description This function sets the value of the Ethernet frame check sequence error to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Count of FCS Errors Returns None. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FCSErrorCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.4 PLIB_ETH_FCSErrorCountGet Function C uint16_t PLIB_ETH_FCSErrorCountGet( ETH_MODULE_ID index ); Description This function gets the count of the frame check sequence error. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2020 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns value - Count of FCS Errors Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_FCSErrorCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.5 PLIB_ETH_FramesRxdOkCountClear Function C void PLIB_ETH_FramesRxdOkCountClear( ETH_MODULE_ID index ); Description This function sets the value of the Ethernet frames 'OK' count to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Count of frames received correctly Returns None. Remarks Changing the value of this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FramesRxdOkCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.6 PLIB_ETH_FramesRxdOkCountGet Function C uint16_t PLIB_ETH_FramesRxdOkCountGet( ETH_MODULE_ID index ); Description This function gets the count of the frames received successfully. Increment count for frames received successfully by the RX Filter. This count will not be incremented if there is a Frame Check Sequence (FCS) or Alignment error. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2021 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns value - Count of frames received correctly Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_FramesRxdOkCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.7 PLIB_ETH_FramesTxdOkCountClear Function C void PLIB_ETH_FramesTxdOkCountClear( ETH_MODULE_ID index ); Description This function sets the count of Ethernet Control frames transmitted to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Count of control frames transmitted correctly Returns None. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_FramesTxdOkCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.8 PLIB_ETH_FramesTxdOkCountGet Function C uint16_t PLIB_ETH_FramesTxdOkCountGet( ETH_MODULE_ID index ); Description This function gets the count of Ethernet Control Frames transmitted successfully. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2022 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns count - count of control frames transmitted correctly Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_FramesTxdOkCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.9 PLIB_ETH_MultipleCollisionCountClear Function C void PLIB_ETH_MultipleCollisionCountClear( ETH_MODULE_ID index ); Description This function sets the value of the Ethernet multiple collision frame count to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Count of multiple collision frames Returns None. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_MultipleCollisionCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.10 PLIB_ETH_MultipleCollisionCountGet Function C uint16_t PLIB_ETH_MultipleCollisionCountGet( ETH_MODULE_ID index ); Description This function gets the count of the frames transmitted successfully after there was more than one collision. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2023 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns count - Count of multiple collision frames Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_MultipleCollisionCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.11 PLIB_ETH_RxOverflowCountClear Function C void PLIB_ETH_RxOverflowCountClear( ETH_MODULE_ID index ); Description This function sets the value of the Ethernet receive overflow count to zero. Increment counter for frames accepted by the RX filter and subsequently dropped due to internal receive error. This event also sets the receive overflow interrupt flag. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns None. Remarks Setting or clearing any bits in this register should be done for debug/test purposes only. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_RxOverflowCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.12 PLIB_ETH_RxOverflowCountGet Function C uint16_t PLIB_ETH_RxOverflowCountGet( ETH_MODULE_ID index ); Description This function gets the count of the dropped Ethernet receive frames. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2024 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns count - uint16_t receiver overflow counts Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_RxOverflowCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.13 PLIB_ETH_RxPacketCountGet Function C uint8_t PLIB_ETH_RxPacketCountGet( ETH_MODULE_ID index ); Description This function gets the value of the the receive packet buffer count. When a packet has been successfully received, this value is incremented by hardware. Software decrements the counter after a packet has been read. Call PLIB_ETH_ReceiveBufferCountDecrement(ETH_MODULE_ID index) to decrement. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns RxPacketCount - Number of received packets in memory Remarks Receive Packet Buffer Counter cannot be decremented below 0x00 Cleared when the Ethernet module is reset. The Receive Packet Buffer Count is not set to '0' when the Ethernet module is turned OFF. This allows software to continue to utilize and decrement the count. This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_RxPacketCountGet(MY_ETH_INSTANCE); 5.6.8.5.7.14 PLIB_ETH_SingleCollisionCountClear Function C void PLIB_ETH_SingleCollisionCountClear( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2025 Description This function sets the value of the Ethernet single collision frame count to zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance value Count of single collision frames Returns None. Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_ETH_SingleCollisionCountClear(MY_ETH_INSTANCE); 5.6.8.5.7.15 PLIB_ETH_SingleCollisionCountGet Function C uint16_t PLIB_ETH_SingleCollisionCountGet( ETH_MODULE_ID index ); Description This function gets the count of the frames transmitted successfully on a second attempt. Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns count - Count of frames transmitted successfully on second attempt Remarks This functionality is not available on all devices. Please refer to the specific device data sheet to determine availability. Example count = PLIB_ETH_SingleCollisionCountGet(MY_ETH_INSTANCE); 5.6.8.5.8 Existence Functions 5.6.8.5.8.1 PLIB_ETH_ExistsAlignmentErrorCount Function C bool PLIB_ETH_ExistsAlignmentErrorCount( ETH_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2026 ); Description This function identifies whether the AlignmentErrorCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_AlignErrorCountClear • PLIB_ETH_AlignErrorCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlignmentErrorCount feature is supported on the device • false - The AlignmentErrorCount feature is not supported on the device Remarks None. 5.6.8.5.8.2 PLIB_ETH_ExistsAutoFlowControl Function C bool PLIB_ETH_ExistsAutoFlowControl( ETH_MODULE_ID index ); Description This function identifies whether the AutoFlowControl feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_AutoFlowControlEnable • PLIB_ETH_AutoFlowControlDisable • PLIB_ETH_AutoFlowControlIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AutoFlowControl feature is supported on the device • false - The AutoFlowControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2027 5.6.8.5.8.3 PLIB_ETH_ExistsCollisionCounts Function C bool PLIB_ETH_ExistsCollisionCounts( ETH_MODULE_ID index ); Description This function identifies whether the CollisionCounts feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_SingleCollisionCountClear • PLIB_ETH_SingleCollisionCountGet • PLIB_ETH_MultipleCollisionCountClear • PLIB_ETH_MultipleCollisionCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CollisionCounts feature is supported on the device • false - The CollisionCounts feature is not supported on the device Remarks None. 5.6.8.5.8.4 PLIB_ETH_ExistsCollisionWindow Function C bool PLIB_ETH_ExistsCollisionWindow( ETH_MODULE_ID index ); Description This function identifies whether the CollisionWindow feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_CollisionWindowGet • PLIB_ETH_CollisionWindowSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CollisionWindow feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2028 • false - The CollisionWindow feature is not supported on the device Remarks None. 5.6.8.5.8.5 PLIB_ETH_ExistsEnable Function C bool PLIB_ETH_ExistsEnable( ETH_MODULE_ID index ); Description This function identifies whether the Enable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_Enable • PLIB_ETH_Disable • PLIB_ETH_IsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Enable feature is supported on the device • false - The Enable feature is not supported on the device Remarks None. 5.6.8.5.8.6 PLIB_ETH_ExistsEthernetControllerStatus Function C bool PLIB_ETH_ExistsEthernetControllerStatus( ETH_MODULE_ID index ); Description This function identifies whether the EthernetControllerStatus feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxPacketCountGet • PLIB_ETH_EthernetIsBus • PLIB_ETH_TransmitIsBusy • PLIB_ETH_ReceiveIsBusy Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2029 Parameters Parameters Description index Identifier for the device instance Returns • true - The EthernetControllerStatus feature is supported on the device • false - The EthernetControllerStatus feature is not supported on the device Remarks None. 5.6.8.5.8.7 PLIB_ETH_ExistsFCSErrorCount Function C bool PLIB_ETH_ExistsFCSErrorCount( ETH_MODULE_ID index ); Description This function identifies whether the FCSErrorCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FCSErrorCountClear • PLIB_ETH_FCSErrorCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FCSErrorCount feature is supported on the device • false - The FCSErrorCount feature is not supported on the device Remarks None. 5.6.8.5.8.8 PLIB_ETH_ExistsFramesTransmittedOK Function C bool PLIB_ETH_ExistsFramesTransmittedOK( ETH_MODULE_ID index ); Description This function identifies whether the FramesTransmittedOK feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FramesTxdOkCountClear • PLIB_ETH_FramesTxdOkCountGet 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2030 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FramesTransmittedOK feature is supported on the device • false - The FramesTransmittedOK feature is not supported on the device Remarks None. 5.6.8.5.8.9 PLIB_ETH_ExistsFramexReceivedOK Function C bool PLIB_ETH_ExistsFramexReceivedOK( ETH_MODULE_ID index ); Description This function identifies whether the FramexReceivedOK feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_FramesRxdOkCountClear • PLIB_ETH_FramesRxdOkCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FramexReceivedOK feature is supported on the device • false - The FramexReceivedOK feature is not supported on the device Remarks None. 5.6.8.5.8.10 PLIB_ETH_ExistsHashTable Function C bool PLIB_ETH_ExistsHashTable( ETH_MODULE_ID index ); Description This function identifies whether the HashTable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2031 • PLIB_ETH_HashTableSet • PLIB_ETH_HashTableGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HashTable feature is supported on the device • false - The HashTable feature is not supported on the device Remarks None. 5.6.8.5.8.11 PLIB_ETH_ExistsInterPacketGaps Function C bool PLIB_ETH_ExistsInterPacketGaps( ETH_MODULE_ID index ); Description This function identifies whether the InterPacketGaps feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_BackToBackIPGGet • PLIB_ETH_BackToBackIPGSet • PLIB_ETH_NonBackToBackIPG1Get • PLIB_ETH_NonBackToBackIPG1Set • PLIB_ETH_NonBackToBackIPG2Get • PLIB_ETH_NonBackToBackIPG2Set Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InterPacketGaps feature is supported on the device • false - The InterPacketGaps feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2032 5.6.8.5.8.12 PLIB_ETH_ExistsInterrupt Function C bool PLIB_ETH_ExistsInterrupt( ETH_MODULE_ID index ); Description This function identifies whether the Interrupt feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_InterruptSourceEnable • PLIB_ETH_InterruptSourceDisable • PLIB_ETH_InterruptSourceIsEnabled • PLIB_ETH_InterruptSet • PLIB_ETH_InterruptClear • PLIB_ETH_InterruptStatusGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Interrupt feature is supported on the device • false - The Interrupt feature is not supported on the device Remarks None. 5.6.8.5.8.13 PLIB_ETH_ExistsMAC_Configuration Function C bool PLIB_ETH_ExistsMAC_Configuration( ETH_MODULE_ID index ); Description This function identifies whether the MAC_Configuration feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_LoopbackEnable • PLIB_ETH_LoopbackDisable • PLIB_ETH_LoopbackIsEnabled • PLIB_ETH_TxPauseEnable • PLIB_ETH_TxPauseDisable • PLIB_ETH_TxPauseIsEnabled • PLIB_ETH_RxPauseEnable 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2033 • PLIB_ETH_RxPauseDisable • PLIB_ETH_RxPauseIsEnabled • PLIB_ETH_PassAllEnable • PLIB_ETH_PassAllDisable • PLIB_ETH_PassAllIsEnabled • PLIB_ETH_ReceiveEnable • PLIB_ETH_ReceiveDisable • PLIB_ETH_ReceiveIsEnabled • PLIB_ETH_ExcessDeferEnable • PLIB_ETH_ExcessDeferDisable • PLIB_ETH_ExcessDeferIsEnabled • PLIB_ETH_BackPresNoBackoffEnable • PLIB_ETH_BackPresNoBackoffDisable • PLIB_ETH_BackPresNoBackoffIsEnabled • PLIB_ETH_NoBackoffEnable • PLIB_ETH_NoBackoffDisable • PLIB_ETH_NoBackoffIsEnabled • PLIB_ETH_LongPreambleEnable • PLIB_ETH_LongPreambleDisable • PLIB_ETH_LongPreambleIsEnabled • PLIB_ETH_PurePreambleEnable • PLIB_ETH_PurePreambleDisable • PLIB_ETH_PurePreambleIsEnabled • PLIB_ETH_AutoDetectPadGet • PLIB_ETH_AutoDetectPadSet • PLIB_ETH_AutoDetectPadClear • PLIB_ETH_CRCEnable • PLIB_ETH_CRCDisable • PLIB_ETH_CRCIsEnabled • PLIB_ETH_DelayedCRCEnable • PLIB_ETH_DelayedCRCDisable • PLIB_ETH_DelayedCRCIsEnabled • PLIB_ETH_HugeFrameEnable • PLIB_ETH_HugeFrameDisable • PLIB_ETH_HugeFrameIsEnabled • PLIB_ETH_FrameLengthCheckEnable • PLIB_ETH_FrameLengthCheckDisable • PLIB_ETH_FrameLengthCheckIsEnabled • PLIB_ETH_FullDuplexEnable 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2034 • PLIB_ETH_FullDuplexDisable • PLIB_ETH_FullDuplexIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MAC_Configuration feature is supported on the device • false - The MAC_Configuration feature is not supported on the device Remarks None. 5.6.8.5.8.14 PLIB_ETH_ExistsMAC_Resets Function C bool PLIB_ETH_ExistsMAC_Resets( ETH_MODULE_ID index ); Description This function identifies whether the MAC_Resets feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIResetEnable • PLIB_ETH_MIIResetDisable • PLIB_ETH_MIIResetIsEnabled • PLIB_ETH_SimResetEnable • PLIB_ETH_SimResetDisable • PLIB_ETH_SimResetIsEnabled • PLIB_ETH_MCSRxResetEnable • PLIB_ETH_MCSRxResetDisable • PLIB_ETH_MCSRxResetIsEnabled • PLIB_ETH_RxFuncResetEnable • PLIB_ETH_RxFuncResetDisable • PLIB_ETH_RxFuncResetIsEnabled • PLIB_ETH_MCSTxResetEnable • PLIB_ETH_MCSTxResetDisable • PLIB_ETH_MCSTxResetIsEnabled • PLIB_ETH_TxFuncResetEnable • PLIB_ETH_TxFuncResetDisable • PLIB_ETH_TxFuncResetIsEnabled 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2035 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MAC_Resets feature is supported on the device • false - The MAC_Resets feature is not supported on the device Remarks None. 5.6.8.5.8.15 PLIB_ETH_ExistsMAC_Testing Function C bool PLIB_ETH_ExistsMAC_Testing( ETH_MODULE_ID index ); Description This function identifies whether the MAC_Testing feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_TestBackPressEnable • PLIB_ETH_TestBackPressDisable • PLIB_ETH_TestBackPressIsEnabled • PLIB_ETH_TestPauseEnable • PLIB_ETH_TestPauseDisable • PLIB_ETH_TestPauseIsEnabled • PLIB_ETH_ShortcutQuantaEnable • PLIB_ETH_ShortcutQuantaDisable • PLIB_ETH_ShortcutQuantaIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MAC_Testing feature is supported on the device • false - The MAC_Testing feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2036 5.6.8.5.8.16 PLIB_ETH_ExistsManualFlowControl Function C bool PLIB_ETH_ExistsManualFlowControl( ETH_MODULE_ID index ); Description This function identifies whether the ManualFlowControl feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ManualFlowControlEnable • PLIB_ETH_ManualFlowControlDisable • PLIB_ETH_ManualFlowControlIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ManualFlowControl feature is supported on the device • false - The ManualFlowControl feature is not supported on the device Remarks None. 5.6.8.5.8.17 PLIB_ETH_ExistsMaxFrameLength Function C bool PLIB_ETH_ExistsMaxFrameLength( ETH_MODULE_ID index ); Description This function identifies whether the MaxFrameLength feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MaxFrameLengthGet • PLIB_ETH_MaxFrameLengthSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MaxFrameLength feature is supported on the device • false - The MaxFrameLength feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2037 Remarks None. 5.6.8.5.8.18 PLIB_ETH_ExistsMIIM_Config Function C bool PLIB_ETH_ExistsMIIM_Config( ETH_MODULE_ID index ); Description This function identifies whether the MIIM_Config feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMResetEnable • PLIB_ETH_MIIMResetDisable • PLIB_ETH_MIIMResetIsEnabled • PLIB_ETH_MIIMClockGet • PLIB_ETH_MIIMClockSet • PLIB_ETH_MIIMNoPreEnable • PLIB_ETH_MIIMNoPreDisable • PLIB_ETH_MIIMNoPreIsEnabled • PLIB_ETH_MIIMScanIncrEnable • PLIB_ETH_MIIMScanIncrDisable • PLIB_ETH_MIIMScanIncrIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIM_Config feature is supported on the device • false - The MIIM_Config feature is not supported on the device Remarks None. 5.6.8.5.8.19 PLIB_ETH_ExistsMIIM_Indicators Function C bool PLIB_ETH_ExistsMIIM_Indicators( ETH_MODULE_ID index ); Description This function identifies whether the MIIM_Indicators feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2038 • PLIB_ETH_LinkHasFailed • PLIB_ETH_DataNotValid • PLIB_ETH_MIIMIsScanning • PLIB_ETH_MIIMIsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIM_Indicators feature is supported on the device • false - The MIIM_Indicators feature is not supported on the device Remarks None. 5.6.8.5.8.20 PLIB_ETH_ExistsMIIMAddresses Function C bool PLIB_ETH_ExistsMIIMAddresses( ETH_MODULE_ID index ); Description This function identifies whether the MIIMAddresses feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PHYAddressGet • PLIB_ETH_PHYAddressSet • PLIB_ETH_RegisterAddressGet • PLIB_ETH_RegisterAddressSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIMAddresses feature is supported on the device • false - The MIIMAddresses feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2039 5.6.8.5.8.21 PLIB_ETH_ExistsMIIMReadWrite Function C bool PLIB_ETH_ExistsMIIMReadWrite( ETH_MODULE_ID index ); Description This function identifies whether the MIIMReadWrite feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMReadStart • PLIB_ETH_MIIMWriteStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIMReadWrite feature is supported on the device • false - The MIIMReadWrite feature is not supported on the device Remarks None. 5.6.8.5.8.22 PLIB_ETH_ExistsMIIMScanMode Function C bool PLIB_ETH_ExistsMIIMScanMode( ETH_MODULE_ID index ); Description This function identifies whether the MIIMScanMode feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMScanModeEnable • PLIB_ETH_MIIMScanModeDisable • PLIB_ETH_MIIMScanModeIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIMScanMode feature is supported on the device • false - The MIIMScanMode feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2040 Remarks None. 5.6.8.5.8.23 PLIB_ETH_ExistsMIIWriteReadData Function C bool PLIB_ETH_ExistsMIIWriteReadData( ETH_MODULE_ID index ); Description This function identifies whether the MIIWriteReadData feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_MIIMWriteDataSet • PLIB_ETH_MIIMReadDataGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MIIWriteReadData feature is supported on the device • false - The MIIWriteReadData feature is not supported on the device Remarks None. 5.6.8.5.8.24 PLIB_ETH_ExistsPatternMatch Function C bool PLIB_ETH_ExistsPatternMatch( ETH_MODULE_ID index ); Description This function identifies whether the PatternMatch feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PatternMatchSet • PLIB_ETH_PatternMatchGet • PLIB_ETH_PatternMatchChecksumSet • PLIB_ETH_PatternMatchChecksumGet • PLIB_ETH_PatternMatchOffsetSet • PLIB_ETH_PatternMatchOffsetGet • PLIB_ETH_PatternMatchModeSet • PLIB_ETH_PatternMatchModeGet 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2041 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PatternMatch feature is supported on the device • false - The PatternMatch feature is not supported on the device Remarks None. 5.6.8.5.8.25 PLIB_ETH_ExistsPauseTimer Function C bool PLIB_ETH_ExistsPauseTimer( ETH_MODULE_ID index ); Description This function identifies whether the PauseTimer feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_PauseTimerSet • PLIB_ETH_PauseTimerGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PauseTimer feature is supported on the device • false - The PauseTimer feature is not supported on the device Remarks None. 5.6.8.5.8.26 PLIB_ETH_ExistsReceiveBufferSize Function C bool PLIB_ETH_ExistsReceiveBufferSize( ETH_MODULE_ID index ); Description This function identifies whether the ReceiveBufferSize feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2042 • PLIB_ETH_ReceiveBufferSizeGet • PLIB_ETH_ReceiveBufferSizeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveBufferSize feature is supported on the device • false - The ReceiveBufferSize feature is not supported on the device Remarks None. 5.6.8.5.8.27 PLIB_ETH_ExistsReceiveFilters Function C bool PLIB_ETH_ExistsReceiveFilters( ETH_MODULE_ID index ); Description This function identifies whether the ReceiveFilters feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ReceiveFilterEnable • PLIB_ETH_ReceiveFilterDisable • PLIB_ETH_ReceiveFilterIsEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveFilters feature is supported on the device • false - The ReceiveFilters feature is not supported on the device Remarks None. 5.6.8.5.8.28 PLIB_ETH_ExistsReceiveOverflowCount Function C bool PLIB_ETH_ExistsReceiveOverflowCount( ETH_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2043 Description This function identifies whether the ReceiveOverflowCount feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxOverflowCountClear • PLIB_ETH_RxOverflowCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveOverflowCount feature is supported on the device • false - The ReceiveOverflowCount feature is not supported on the device Remarks None. 5.6.8.5.8.29 PLIB_ETH_ExistsReceiveWmarks Function C bool PLIB_ETH_ExistsReceiveWmarks( ETH_MODULE_ID index ); Description This function identifies whether the ReceiveWmarks feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxFullWmarkSet • PLIB_ETH_RxFullWmarkGet • PLIB_ETH_RxEmptyWmarkSet • PLIB_ETH_RxEmptyWmarkGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveWmarks feature is supported on the device • false - The ReceiveWmarks feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2044 5.6.8.5.8.30 PLIB_ETH_ExistsRetransmissionMaximum Function C bool PLIB_ETH_ExistsRetransmissionMaximum( ETH_MODULE_ID index ); Description This function identifies whether the RetransmissionMaximum feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_ReTxMaxGet • PLIB_ETH_ReTxMaxSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RetransmissionMaximum feature is supported on the device • false - The RetransmissionMaximum feature is not supported on the device Remarks None. 5.6.8.5.8.31 PLIB_ETH_ExistsRMII_Support Function C bool PLIB_ETH_ExistsRMII_Support( ETH_MODULE_ID index ); Description This function identifies whether the RMII_Support feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RMIIResetEnable • PLIB_ETH_RMIIResetDisable • PLIB_ETH_RMIIResetIsEnabled • PLIB_ETH_RMIISpeedGet • PLIB_ETH_RMIISpeedSet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2045 Returns • true - The RMII_Support feature is supported on the device • false - The RMII_Support feature is not supported on the device Remarks None. 5.6.8.5.8.32 PLIB_ETH_ExistsRxBufferCountDecrement Function C bool PLIB_ETH_ExistsRxBufferCountDecrement( ETH_MODULE_ID index ); Description This function identifies whether the RxBufferCountDecrement feature is available on the Ethernet module. When this function returns true, this function is supported on the device: • PLIB_ETH_RxBufferCountDecrement Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxBufferCountDecrement feature is supported on the device • false - The RxBufferCountDecrement feature is not supported on the device Remarks None. 5.6.8.5.8.33 PLIB_ETH_ExistsRxEnable Function C bool PLIB_ETH_ExistsRxEnable( ETH_MODULE_ID index ); Description This function identifies whether the ReceiveEnable feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxEnable • PLIB_ETH_RxDisable • PLIB_ETH_RxIsEnabled Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2046 Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveEnable feature is supported on the device • false - The ReceiveEnable feature is not supported on the device Remarks None. 5.6.8.5.8.34 PLIB_ETH_ExistsRxPacketDescriptorAddress Function C bool PLIB_ETH_ExistsRxPacketDescriptorAddress( ETH_MODULE_ID index ); Description This function identifies whether the RxPacketDescriptorAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_RxPacketDescAddrSet • PLIB_ETH_RxPacketDescAddrGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxPacketDescriptorAddress feature is supported on the device • false - The RxPacketDescriptorAddress feature is not supported on the device Remarks None. 5.6.8.5.8.35 PLIB_ETH_ExistsStationAddress Function C bool PLIB_ETH_ExistsStationAddress( ETH_MODULE_ID index ); Description This function identifies whether the StationAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_StationAddressGet • PLIB_ETH_StationAddressSet 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2047 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StationAddress feature is supported on the device • false - The StationAddress feature is not supported on the device Remarks None. 5.6.8.5.8.36 PLIB_ETH_ExistsStopInIdle Function C bool PLIB_ETH_ExistsStopInIdle( ETH_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_StopInIdleEnable • PLIB_ETH_StopInIdleDisable • PLIB_ETH_StopInIdleIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.8.5.8.37 PLIB_ETH_ExistsTransmitRTS Function C bool PLIB_ETH_ExistsTransmitRTS( ETH_MODULE_ID index ); Description This function identifies whether the TransmitRTS feature is available on the Ethernet module. When this function returns true, 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2048 these functions are supported on the device: • PLIB_ETH_TxRTSEnable • PLIB_ETH_TxRTSDisable • PLIB_ETH_TxRTSIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitRTS feature is supported on the device • false - The TransmitRTS feature is not supported on the device Remarks None. 5.6.8.5.8.38 PLIB_ETH_ExistsTxPacketDescriptorAddress Function C bool PLIB_ETH_ExistsTxPacketDescriptorAddress( ETH_MODULE_ID index ); Description This function identifies whether the TxPacketDescriptorAddress feature is available on the Ethernet module. When this function returns true, these functions are supported on the device: • PLIB_ETH_TxPacketDescAddrSet • PLIB_ETH_TxPacketDescAddrGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TxPacketDescriptorAddress feature is supported on the device • false - The TxPacketDescriptorAddress feature is not supported on the device Remarks None. 5.6.8.5.9 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2049 5.6.8.5.9.1 ETH_AUTOPAD_OPTION Enumeration C typedef enum { ETH_AUTOPAD_DISABLED_CHECK_CRC, ETH_AUTOPAD_TO_60BYTES_ADD_CRC, ETH_AUTOPAD_TO_64BYTES_ADD_CRC, ETH_AUTOPAD_BY_PKT_TYPE_ADD_CRC } ETH_AUTOPAD_OPTION; Description AutoDetectPad Selection This enumeration lists the possible automatic padding configurations. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.8.5.9.2 ETH_INTERRUPT_SOURCES Enumeration C typedef enum { ETH_TRANSMIT_BVCI_BUS_ERROR_INTERRUPT, ETH_RECEIVE_BVCI_BUS_ERROR_INTERRUPT, ETH_EMPTY_WATERMARK_INTERRUPT, ETH_FULL_WATERMARK_INTERRUPT, ETH_RECEIVE_DONE_INTERRUPT, ETH_PACKET_PENDING_INTERRUPT, ETH_RECEIVE_ACTIVITY_INTERRUPT, ETH_TRANSMIT_DONE_INTERRUPT, ETH_TRANSMIT_ABORT_INTERRUPT, ETH_RECEIVE_BUFFER_NOT_AVAILABLE_INTERRUPT, ETH_RECEIVE_FIFO_OVERFLOW_ERROR_INTERRUPT, ETH_ALL_INTERRUPT_SOURCES } ETH_INTERRUPT_SOURCES; Description ETH Module Interrupt Mask This enumeration lists the possible values of ETH_INTERRUPT_SOURCES. Remarks See also ETH_LEGACY_EVENTS in plib_eth_legacy.h. 5.6.8.5.9.3 ETH_MIIM_CLK Enumeration C typedef enum { ETH_MIIM_SYSCLK_DIV_BY_4, ETH_MIIM_SYSCLK_DIV_RSVD, ETH_MIIM_SYSCLK_DIV_BY_6, ETH_MIIM_SYSCLK_DIV_BY_8, ETH_MIIM_SYSCLK_DIV_BY_10, ETH_MIIM_SYSCLK_DIV_BY_14, ETH_MIIM_SYSCLK_DIV_BY_20, ETH_MIIM_SYSCLK_DIV_BY_28, ETH_MIIM_SYSCLK_DIV_BY_40 } ETH_MIIM_CLK; 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2050 Description MII Clock Selection This enumeration lists the possible speed selection for RMII. The body contains only two states: RMII_10Mbps or RMII_100Mbps. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.8.5.9.4 ETH_PATTERN_MATCH_MODE Type C typedef enum _ETH_PATTERN_MATCH_MODE_ ETH_PATTERN_MATCH_MODE; Description Pattern Match Modes This enumeration lists the pattern match mode values. Remarks In all pattern match enabled cases, it is the pattern match inversion XOR pattern match checksum AND . Some states were omitted from the enumeration since they were duplicates. This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.8.5.9.5 ETH_RECEIVE_FILTER Enumeration C typedef enum { ETH_HASH_FILTER, ETH_MAGIC_PACKET_FILTER, ETH_PATTERN_MATCH_INVERSION, ETH_CRC_ERROR_FILTER, ETH_CRC_OK_FILTER, ETH_RUNT_ERROR_FILTER, ETH_RUNT_ENABLE_FILTER, ETH_UNICAST_FILTER, ETH_NOT_ME_UNICAST_FILTER, ETH_MULTICAST_FILTER, ETH_BROADCAST_FILTER, ETH_ENABLE_ALL_FILTER } ETH_RECEIVE_FILTER; Description ETH Module Receive Filter Mask This enumeration lists the possible values of the receive filter. Members Members Description ETH_HASH_FILTER Enable: Hash Table Filtering. ETH_MAGIC_PACKET_FILTER Enable: Magic Packet Filtering. ETH_PATTERN_MATCH_INVERSION Enable: Pattern Match Checksum must not match to be accepted. ETH_CRC_ERROR_FILTER Enable: Received packet CRC must be invalid to be accepted. ETH_CRC_OK_FILTER Enable: Received packet CRC must be valid to be accepted. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2051 ETH_RUNT_ERROR_FILTER Enable: Received packet must be runt packet to be accepted. ETH_RUNT_ENABLE_FILTER Enable: Received packet must not be a runt packet to be accepted. ETH_UNICAST_FILTER Enable: Unicast Packets whose destination address matches the station address are accepted. ETH_NOT_ME_UNICAST_FILTER Enable: Unicast Packets whose destination address do NOT match the station address are accepted. ETH_MULTICAST_FILTER Enable: Multicast Address Packets are accepted. ETH_BROADCAST_FILTER Enable: Broadcast Address Packets are accepted. ETH_ENABLE_ALL_FILTER Enable: All of the above packets are accepted. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.8.5.9.6 ETH_RMII_SPEED Enumeration C typedef enum { ETH_RMII_10Mbps, ETH_RMII_100Mps } ETH_RMII_SPEED; Description RMII Speed Selection This enumeration lists the possible speed selection for RMII. The body contains only two states: RMII_10Mbps or RMII_100Mbps. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.8.6 Files Files Name Description plib_eth.h Defines the Ethernet Peripheral Library Interface. Description 5.6.8.6.1 plib_eth.h Ethernet Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Ethernet Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Ethernet module. Enumerations Name Description ETH_AUTOPAD_OPTION Lists the possible automatic padding configurations. ETH_INTERRUPT_SOURCES Lists the possible values of ETH_INTERRUPT_SOURCES. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2052 ETH_MIIM_CLK Lists the possible speed selection for the Reduced Media Independent Interface (RMII). ETH_RECEIVE_FILTER Lists the possible values of the receive filter. ETH_RMII_SPEED Lists the possible speed selection for the Reduced Media Independent Interface (RMII). Functions Name Description PLIB_ETH_AlignErrorCountClear Sets the count of Ethernet alignment errors to zero. PLIB_ETH_AlignErrorCountGet Gets the count of Ethernet alignment errors. PLIB_ETH_AutoDetectPadClear Clears the EMAC Auto-Pad option. PLIB_ETH_AutoDetectPadGet Gets the current EMAC Auto-Pad setting. PLIB_ETH_AutoDetectPadSet Sets the EMAC Auto-Pad option. PLIB_ETH_AutoFlowControlDisable Disables the Ethernet module Automatic Flow Control logic. PLIB_ETH_AutoFlowControlEnable Enables the Ethernet Automatic Flow Control logic. PLIB_ETH_AutoFlowControlIsEnabled Gets the Ethernet module Automatic Flow Control status. PLIB_ETH_BackPresNoBackoffDisable Disables EMAC back pressure/no backo-ff. PLIB_ETH_BackPresNoBackoffEnable Enables EMAC back pressure/no back-off. PLIB_ETH_BackPresNoBackoffIsEnabled Gets the EMAC back pressure/no back-off enable status. PLIB_ETH_BackToBackIPGGet Gets the EMAC back-to-back interpacket gap. PLIB_ETH_BackToBackIPGSet Sets the EMAC back-to-back interpacket gap. PLIB_ETH_CollisionWindowGet Gets the EMAC collision window. PLIB_ETH_CollisionWindowSet Sets the EMAC collision window. PLIB_ETH_CRCDisable Disables EMAC CRC. PLIB_ETH_CRCEnable Enables EMAC CRC. PLIB_ETH_CRCIsEnabled Gets the EMAC CRC enable status. PLIB_ETH_DataNotValid Gets the MII management read data not valid status. PLIB_ETH_DelayedCRCDisable Disables EMAC delayed CRC. PLIB_ETH_DelayedCRCEnable Enables EMAC delayed CRC. PLIB_ETH_DelayedCRCIsEnabled Gets the EMAC delayed CRC enable status. PLIB_ETH_Disable Disables the Ethernet module. PLIB_ETH_Enable Enables the Ethernet module. PLIB_ETH_EthernetIsBusy Gets the status value of the Ethernet logic busy. PLIB_ETH_ExcessDeferDisable Disables EMAC excess defer. PLIB_ETH_ExcessDeferEnable Enables EMAC excess defer. PLIB_ETH_ExcessDeferIsEnabled Gets the EMAC excess defer enable status. PLIB_ETH_ExistsAlignmentErrorCount Identifies whether the AlignmentErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsAutoFlowControl Identifies whether the AutoFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionCounts Identifies whether the CollisionCounts feature exists on the Ethernet module. PLIB_ETH_ExistsCollisionWindow Identifies whether the CollisionWindow feature exists on the Ethernet module. PLIB_ETH_ExistsEnable Identifies whether the Enable feature exists on the Ethernet module. PLIB_ETH_ExistsEthernetControllerStatus Identifies whether the EthernetControllerStatus feature exists on the Ethernet module. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2053 PLIB_ETH_ExistsFCSErrorCount Identifies whether the FCSErrorCount feature exists on the Ethernet module. PLIB_ETH_ExistsFramesTransmittedOK Identifies whether the FramesTransmittedOK feature exists on the Ethernet module. PLIB_ETH_ExistsFramexReceivedOK Identifies whether the FramexReceivedOK feature exists on the Ethernet module. PLIB_ETH_ExistsHashTable Identifies whether the HashTable feature exists on the Ethernet module. PLIB_ETH_ExistsInterPacketGaps Identifies whether the InterPacketGaps feature exists on the Ethernet module. PLIB_ETH_ExistsInterrupt Identifies whether the Interrupt feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Configuration Identifies whether the MAC_Configuration feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Resets Identifies whether the MAC_Resets feature exists on the Ethernet module. PLIB_ETH_ExistsMAC_Testing Identifies whether the MAC_Testing feature exists on the Ethernet module. PLIB_ETH_ExistsManualFlowControl Identifies whether the ManualFlowControl feature exists on the Ethernet module. PLIB_ETH_ExistsMaxFrameLength Identifies whether the MaxFrameLength feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Config Identifies whether the MIIM_Config feature exists on the Ethernet module. PLIB_ETH_ExistsMIIM_Indicators Identifies whether the MIIM_Indicators feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMAddresses Identifies whether the MIIMAddresses feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMReadWrite Identifies whether the MIIMReadWrite feature exists on the Ethernet module. PLIB_ETH_ExistsMIIMScanMode Identifies whether the MIIMScanMode feature exists on the Ethernet module. PLIB_ETH_ExistsMIIWriteReadData Identifies whether the MIIWriteReadData feature exists on the Ethernet module. PLIB_ETH_ExistsPatternMatch Identifies whether the PatternMatch feature exists on the Ethernet module. PLIB_ETH_ExistsPauseTimer Identifies whether the PauseTimer feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveBufferSize Identifies whether the ReceiveBufferSize feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveFilters Identifies whether the ReceiveFilters feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveOverflowCount Identifies whether the ReceiveOverflowCount feature exists on the Ethernet module. PLIB_ETH_ExistsReceiveWmarks Identifies whether the ReceiveWmarks feature exists on the Ethernet module. PLIB_ETH_ExistsRetransmissionMaximum Identifies whether the RetransmissionMaximum feature exists on the Ethernet module. PLIB_ETH_ExistsRMII_Support Identifies whether the RMII_Support feature exists on the Ethernet module. PLIB_ETH_ExistsRxBufferCountDecrement Identifies whether the RxBufferCountDecrement feature exists on the Ethernet module. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2054 PLIB_ETH_ExistsRxEnable Identifies whether the ReceiveEnable feature exists on the Ethernet module. PLIB_ETH_ExistsRxPacketDescriptorAddress Identifies whether the RxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStationAddress Identifies whether the StationAddress feature exists on the Ethernet module. PLIB_ETH_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the Ethernet module. PLIB_ETH_ExistsTransmitRTS Identifies whether the TransmitRTS feature exists on the Ethernet module. PLIB_ETH_ExistsTxPacketDescriptorAddress Identifies whether the TxPacketDescriptorAddress feature exists on the Ethernet module. PLIB_ETH_FCSErrorCountClear Sets the value of the Ethernet frame check sequence error to zero. PLIB_ETH_FCSErrorCountGet Gets the count of the frame check sequence error. PLIB_ETH_FrameLengthCheckDisable Disables the EMAC frame length check. PLIB_ETH_FrameLengthCheckEnable Enables the EMAC frame length check. PLIB_ETH_FrameLengthCheckIsEnabled Gets the EMAC frame length check status. PLIB_ETH_FramesRxdOkCountClear Sets the value of the Ethernet received frames 'OK' count to zero. PLIB_ETH_FramesRxdOkCountGet Gets the count of the frames frames received successfully. PLIB_ETH_FramesTxdOkCountClear Sets the count of Ethernet Control frames transmitted to zero. PLIB_ETH_FramesTxdOkCountGet Gets the count of Ethernet Control Frames transmitted successfully. PLIB_ETH_FullDuplexDisable Disables the EMAC full duplex operatio. PLIB_ETH_FullDuplexEnable Enables the EMAC full deuplex operation. PLIB_ETH_FullDuplexIsEnabled Gets the EMAC full duplex enable status. PLIB_ETH_HashTableGet Gets the value of the Hash table. PLIB_ETH_HashTableSet Sets the Ethernet module Hash table with the new value. PLIB_ETH_HugeFrameDisable Disables the EMAC from receiving huge frames. PLIB_ETH_HugeFrameEnable Enables the EMAC to receive huge frames. PLIB_ETH_HugeFrameIsEnabled Gets the EMAC huge frame enable status. PLIB_ETH_InterruptClear Clears the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptSet Sets the Ethernet module interrupt source status as a group, using a mask. PLIB_ETH_InterruptsGet Gets the Ethernet module Interrupt Flag register as a group. PLIB_ETH_InterruptSourceDisable Clears the Ethernet module Interrupt Enable register as a group, using a mask. PLIB_ETH_InterruptSourceEnable Sets the Ethernet module Interrupt Enable register in a group, using a mask. PLIB_ETH_InterruptSourceIsEnabled Gets the Ethernet module Interrupt Enable register singularly or as a group. PLIB_ETH_InterruptSourcesGet Returns the entire interrupt enable register. PLIB_ETH_InterruptStatusGet Gets the Ethernet module Interrupt Flag register as a group, using a mask. PLIB_ETH_IsEnabled Gets the Ethernet module enable status. PLIB_ETH_LinkHasFailed Gets the MII management link fail status. PLIB_ETH_LongPreambleDisable Disables EMAC long preamble enforcement. PLIB_ETH_LongPreambleEnable Enables EMAC long preamble enforcement. PLIB_ETH_LongPreambleIsEnabled Gets the EMAC long preamble enforcement enable status. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2055 PLIB_ETH_LoopbackDisable Disables the EMAC loopback logic. PLIB_ETH_LoopbackEnable Enables the EMAC loopback logic. PLIB_ETH_LoopbackIsEnabled Gets the EMAC Loopback interface enable status. PLIB_ETH_ManualFlowControlDisable Disable Ethernet module Manual Flow Control logic. PLIB_ETH_ManualFlowControlEnable Enables the Ethernet Manual Flow Control logic. PLIB_ETH_ManualFlowControlIsEnabled Gets the Ethernet module Manual Flow Control enable status. PLIB_ETH_MaxFrameLengthGet Gets the EMAC maximum frame length. PLIB_ETH_MaxFrameLengthSet Sets the EMAC maximum frame length. PLIB_ETH_MCSRxResetDisable Disables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetEnable Enables the reset EMAC Control Sub-layer/Receive domain logic. PLIB_ETH_MCSRxResetIsEnabled Gets the EMAC Control Sub-layer/Receive domain logic reset status. PLIB_ETH_MCSTxResetDisable Disables the reset EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetEnable Enables the reset of EMAC Control Sub-layer/Transmit domain logic. PLIB_ETH_MCSTxResetIsEnabled Gets the EMAC Control Sub-layer/Transmit domain logic reset status. PLIB_ETH_MIIMClockGet Gets the current EMAC MIIM clock selection. PLIB_ETH_MIIMClockSet Sets the EMAC MIM clock selection. PLIB_ETH_MIIMIsBusy Gets the MII management busy status. PLIB_ETH_MIIMIsScanning Gets the MII Management scanning status. PLIB_ETH_MIIMNoPreDisable Disables EMAC No Preamble (allows preamble). PLIB_ETH_MIIMNoPreEnable Enables EMAC MIIM No Preamble (suppresses preamble). PLIB_ETH_MIIMNoPreIsEnabled Gets the EMAC MIIM No Preamble enable status. PLIB_ETH_MIIMReadDataGet Gets EMAC MIIM management read data after a MII read cycle has completed. PLIB_ETH_MIIMReadStart Initiates an MII management read command. PLIB_ETH_MIIMResetDisable Disables EMAC Reset MII Management. PLIB_ETH_MIIMResetEnable Enables EMAC Reset Media Independent Interface (MII) Management. PLIB_ETH_MIIMResetIsEnabled Gets the EMAC Reset MII Management enable status. PLIB_ETH_MIIMScanIncrDisable Disables the EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrEnable Enables EMAC MIIM Scan Increment. PLIB_ETH_MIIMScanIncrIsEnabled Gets the EMAC MIIM scan increment enable status. PLIB_ETH_MIIMScanModeDisable Disables MIIM scan mode. PLIB_ETH_MIIMScanModeEnable Enables MIIM scan mode. PLIB_ETH_MIIMScanModeIsEnabled Gets the MII management scan enable status. PLIB_ETH_MIIMWriteDataSet Sets the EMAC MIIM write data before initiating an MII write cycle. PLIB_ETH_MIIMWriteStart Initiates an MII management write command. PLIB_ETH_MIIResetDisable Disables the EMAC Soft reset. PLIB_ETH_MIIResetEnable Enables the EMAC MIIM Soft reset. PLIB_ETH_MIIResetIsEnabled Gets EMAC MIIM Soft Reset enable status. PLIB_ETH_MultipleCollisionCountClear Sets the value of the Ethernet multiple collision frame count to zero. PLIB_ETH_MultipleCollisionCountGet Gets the count of the frames transmitted successfully after there was more than one collision. PLIB_ETH_NoBackoffDisable Disables EMAC no back-offs. PLIB_ETH_NoBackoffEnable Enables EMAC no backoff. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2056 PLIB_ETH_NoBackoffIsEnabled Gets the EMAC no back-off enable status. PLIB_ETH_NonBackToBackIPG1Get Gets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG1Set Sets the EMAC non-back-to-back interpacket gap register 1. PLIB_ETH_NonBackToBackIPG2Get Gets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_NonBackToBackIPG2Set Sets the EMAC non-back-to-back interpacket gap register 2. PLIB_ETH_PassAllDisable Disables the EMAC PassAll. PLIB_ETH_PassAllEnable Enables the EMAC PassAll. PLIB_ETH_PassAllIsEnabled Gets the EMAC PassAll enable status. PLIB_ETH_PatternMatchChecksumGet Gets the value of the pattern match checksum register. PLIB_ETH_PatternMatchChecksumSet Sets the Ethernet module pattern match checksum register with the new value. PLIB_ETH_PatternMatchGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeGet Gets the value of the selected pattern match mask register. PLIB_ETH_PatternMatchModeSet Sets the Ethernet module pattern match mode. PLIB_ETH_PatternMatchOffsetGet Gets the value of the patter match offset register. PLIB_ETH_PatternMatchOffsetSet Sets the Ethernet module patter match offset register with the new value. PLIB_ETH_PatternMatchSet Sets the Ethernet module pattern match mask register with the new value. PLIB_ETH_PauseTimerGet Gets the Pause Timer value used for flow control. PLIB_ETH_PauseTimerSet Sets the Pause Timer value used for flow control. PLIB_ETH_PHYAddressGet Gets the EMAC MIIM management PHY address. PLIB_ETH_PHYAddressSet Sets the EMAC MIIM PHY address. PLIB_ETH_PurePreambleDisable Disables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleEnable Enables EMAC pure preamble enforcement. PLIB_ETH_PurePreambleIsEnabled Gets EMAC pure preamble enforcement enable status. PLIB_ETH_ReceiveBufferSizeGet Gets the Ethernet module receive buffer size. PLIB_ETH_ReceiveBufferSizeSet Sets the Ethernet module receive buffer size. PLIB_ETH_ReceiveDisable Disables the EMAC from receiving frames. PLIB_ETH_ReceiveEnable Enables the EMAC to receive the frames. PLIB_ETH_ReceiveFilterDisable Disables the specified receive filter. PLIB_ETH_ReceiveFilterEnable Enables the specified receive filter. PLIB_ETH_ReceiveFilterIsEnable Disables the specified receive filter. PLIB_ETH_ReceiveIsBusy Gets the the Ethernet receive logic busy status. PLIB_ETH_ReceiveIsEnabled Gets the Ethernet EMAC receive enable status. PLIB_ETH_RegisterAddressGet Gets the EMAC MIIM management register address. PLIB_ETH_RegisterAddressSet Sets EMAC MIIM register address. PLIB_ETH_ReTxMaxGet Gets the EMAC maximum retransmissions. PLIB_ETH_ReTxMaxSet Sets the EMAC maximum retransmissions. PLIB_ETH_RMIIResetDisable Disables EMAC Reset RMII. PLIB_ETH_RMIIResetEnable Enables EMAC Reset RMII. PLIB_ETH_RMIIResetIsEnabled Gets the EMAC Reset RMII enable status. PLIB_ETH_RMIISpeedGet Gets the current EMAC RMII speed. PLIB_ETH_RMIISpeedSet Sets EMAC RMII Speed. PLIB_ETH_RxBufferCountDecrement Causes the Receive Descriptor Buffer Counter to decrement by 1. PLIB_ETH_RxDisable Disables the Ethernet module receive logic. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2057 PLIB_ETH_RxEmptyWmarkGet Gets the Ethernet module receive empty watermark. PLIB_ETH_RxEmptyWmarkSet Sets the Ethernet module receive empty water mark. PLIB_ETH_RxEnable Enables the Ethernet receive logic. PLIB_ETH_RxFullWmarkGet Gets the Ethernet module receive full watermark. PLIB_ETH_RxFullWmarkSet Sets the Ethernet module receive full water mark. PLIB_ETH_RxFuncResetDisable Disables the EMAC reset receive funtion logic. PLIB_ETH_RxFuncResetEnable Enables the EMAC reset receive funtion logic. PLIB_ETH_RxFuncResetIsEnabled Gets the EMAC reset receive function status. PLIB_ETH_RxIsEnabled Gets the Ethernet module receive enable status. PLIB_ETH_RxOverflowCountClear Sets the value of the Ethernet receive overflow count to zero. PLIB_ETH_RxOverflowCountGet Gets the count of the dropped Ethernet receive frames. PLIB_ETH_RxPacketCountGet Gets the value of the receive packet buffer count. PLIB_ETH_RxPacketDescAddrGet Gets the address of the next receive descriptor. PLIB_ETH_RxPacketDescAddrSet Sets the Ethernet module receive packet descriptor start address. PLIB_ETH_RxPauseDisable Disables the EMAC receive flow control. PLIB_ETH_RxPauseEnable Enables the EMAC receive flow control. PLIB_ETH_RxPauseIsEnabled Gets the EMAC receive flow pause enable status. PLIB_ETH_ShortcutQuantaDisable Disables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaEnable Enables EMAC shortcut pause quanta. PLIB_ETH_ShortcutQuantaIsEnabled Gets EMAC shortcut pause quanta enable status. PLIB_ETH_SimResetDisable Disables the EMAC simulation reset. PLIB_ETH_SimResetEnable Enables the EMAC simulation reset. PLIB_ETH_SimResetIsEnabled Gets the EMAC simulation reset status. PLIB_ETH_SingleCollisionCountClear Sets the value of the Ethernet single collision frame count to zero. PLIB_ETH_SingleCollisionCountGet Gets the count of the frames transmitted successfully on a second attempt. PLIB_ETH_StationAddressGet Gets the selected EMAC station address. PLIB_ETH_StationAddressSet Sets the selected EMAC Station Address. PLIB_ETH_StopInIdleDisable Ethernet module operation will continue when the device enters Idle mode. PLIB_ETH_StopInIdleEnable Ethernet module operation will stop when the device enters Idle mode. PLIB_ETH_StopInIdleIsEnabled Gets the Ethernet module Stop in Idle mode enable status. PLIB_ETH_TestBackPressDisable Disables EMAC Test backpressure. PLIB_ETH_TestBackPressEnable Enables EMAC Test backpressure. PLIB_ETH_TestBackPressIsEnabled Gets the EMAC test backpressure enable status. PLIB_ETH_TestPauseDisable Disables EMAC test pause. PLIB_ETH_TestPauseEnable Enables EMAC test pause. PLIB_ETH_TestPauseIsEnabled Gets the EMAC test pause enable status. PLIB_ETH_TransmitIsBusy Gets the status value of the Ethernet transmit logic busy status PLIB_ETH_TxFuncResetDisable Disables the EMAC Transmit function reset. PLIB_ETH_TxFuncResetEnable Enables the EMAC transmit function reset. PLIB_ETH_TxFuncResetIsEnabled Gets the EMAC Transmit function reset status. PLIB_ETH_TxPacketDescAddrGet Gets the address of the next descriptor to be transmitted. PLIB_ETH_TxPacketDescAddrSet Sets the Ethernet module transmit packet descriptor start address. PLIB_ETH_TxPauseDisable Disables the transmission of Pause frames. 5.6 Peripheral Library Help MPLAB Harmony Help Ethernet Peripheral Library 5-2058 PLIB_ETH_TxPauseEnable Enables the the tansmission Pause frames. PLIB_ETH_TxPauseIsEnabled Gets the Ethernet module enable status. PLIB_ETH_TxRTSDisable Aborts an Ethernet module transmission. PLIB_ETH_TxRTSEnable Enables the Ethernet transmit request to send. PLIB_ETH_TxRTSIsEnabled Gets the Ethernet module transmit request to send status. Types Name Description ETH_PATTERN_MATCH_MODE Lists the possible pattern match values. File Name plib_eth.h Company Microchip Technology Inc. 5.6.9 I2C Peripheral Library 5.6.9.1 Introduction This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip microcontrollers. Description I 2C Peripheral Library for Microchip Microcontrollers 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2059 This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Please refer to the I2C-Bus Specification (v2.1), available from Philips Semiconductor (see the Note below) for complete details on the operation and requirements for the I2C bus. Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. 5.6.9.2 Release Notes MPLAB Harmony Version: v0.70b I 2C Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.9.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2060 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.9.4 How the Library Works How the Library Works Before enabling the I2C module the caller must initialize basic configuration, clock frequency, and Slave address recognition features (see Initializing the I2C). After the module has been enabled, it can begin monitoring the bus as a slave device waiting to be addressed by an external master (see Operating as a Slave Receiver). A slave device only transfers data on the bus when it has been addressed by a master (see Operating as a Slave Transmitter). If the module is used to start a transfer, then it is operating as a master. A master addresses a slave and controls the transfer of data by providing the clock (see Operating as a Master Transmitter and Operating as a Master Receiver). Some operations in the I2C library initiate actions on the I2C bus that require time to complete. Also, some events occur asynchronously on the bus. In each of these cases, the module causes either a "master", "slave", or "error" interrupt. Interrupt State Machine describes the different states that can cause an interrupt and show what causes the transition from one state to another. Handling Errors describes the various errors that can occur and how to deal with them. Data transfers on the I2C bus must follow specific formats defined by the I2C bus protocol. (Refer to Forming Transfers for details) Note: The I2C peripheral library does not directly respond to interrupts. The client software (usually a driver, middleware layer, or application) should implement the Interrupt Service Routine (ISR) and call the I2C library's interface routines from that ISR to manage the state of the I2C module. 5.6.9.4.1 Initializing the I2C To initialize the I2C module, perform the following sequence: 1. Select the desired general configuration options using General Initialization Functions to select the desired operation of the following features: • Slave Clock Stretching • General Call Address Recognition • System Management Bus (SMBus) Support • High Frequency Operation • Reserved Address Protection • Stop-in-Idle Operation 2. Program the Baud Rate Generator to set the desired baud rate using the PLIB_I2C_BaudRateSet function. 3. If operating in slave mode, set the desired slave address using the PLIB_I2C_SlaveAddress7BitSet function (for 7-bit mode operation) or PLIB_I2C_SlaveAddress10BitSet function (for 10-bit mode operation). 4. If running in an interrupt-driven environment, clear any pending interrupts and enable the appropriate (master, slave, and error) I2C interrupts. Refer to the "Interrupt Controller" section in the related family reference manual section for information. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2061 5. Enable the module for operation using the PLIB_I2C_Enable function. Example #define MY_I2C_ID I2C_ID_1 uint32_t actualClock; // Configure General I2C Options PLIB_I2C_SlaveClockStretchingEnable(MY_I2C_ID); PLIB_I2C_GeneralCallEnable(MY_I2C_ID); PLIB_I2C_SMBDisable(MY_I2C_ID); PLIB_I2C_HighFrequencyDisable(MY_I2C_ID); PLIB_I2C_ReservedAddressProtectEnable(MY_I2C_ID); PLIB_I2C_StopInIdleEnable(MY_I2C_ID); // Set Desired baud rate PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_PERIPHEAL_CLOCK_FREQ, MY_I2C_BAUD_RATE); // Set the appropriate slave address (slave only) PLIB_I2C_SlaveAddress7BitSet(MY_I2C_ID, MY_SLAVE_ADDRESS); // Optional: Clear and enable interrupts before enabling the I2C module. // Enable the module PLIB_I2C_Enable(MY_I2C_ID); Note: Refer to the "Interrupt Controller" section in the related family reference manual section for details on how to clear and enable the I2C module interrupts. The previous example uses the following constants: Symbol Description I2C_ID_1 Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 MY_I2C_PERIPHERAL_CLOCK Defined as the peripheral clock frequency (in Hz) of the I2C module. Example: #define MY_I2C_PERIPHERAL_CLOCK 80000000 MY_I2C_BAUD_RATE Defined as desired I2C baud rate. Example: #define MY_I2C_BAUD_RATE 100000 MY_SLAVE_ADDRESS Defined as the desired 7-bit I2C slave address. Example #define 0x1A // Slave address 0011010 in binary Note: If 0 is passed in as the mask value, the I2C module will only respond to single slave address passed in the second parameter. 5.6.9.4.2 Operating as a Slave Receiver Before enabling the module, the module's "local" slave address and mask should be programmed using the PLIB_I2C_SlaveAddress7BitSet function or the PLIB_I2C_SlaveAddress10BitSet function, depending on the desired address width. If slave address masking is supported on the chosen processor the "don't care bits" mask can be set using the PLIB_I2C_SlaveMask7BitSet function or the PLIB_I2C_SlaveMask10BitSet function, also depending on the desired address width. Once the I2C module has been enabled, it will begin waiting for an I2C master to address it. When the programmed local slave address is recognized (ignoring any bits in the programmed mask value, if supported), the module will ACK the address and notify software that it has received an address byte. If the R/W bit of the address is 0, the module enters receive mode automatically. As additional bytes are received, the module will automatically ACK them if the previous byte has been read from the RX buffer before the new byte has been completely received and notify software of the newly available byte. Both address and data bytes received must be read from the RX buffer by software. Preconditions 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2062 1. The module must have had it's basic options and clock frequency initialized and have been enabled (see Initializing the I2C). 2. An external master must have started a transfer. 3. The address address of the transfer must have matched with the address (ignoring any bits in the mask) programmed into the module by software. Process Software must follow this sequence: 1. Ensure that a byte has been received either by polling the PLIB_I2C_ReceivedByteIsAvailable function or by waiting for a slave interrupt (at which time, this function should still be checked). 2. Identify if the byte is a data byte or an address byte using the PLIB_I2C_SlaveAddressIsDetected function. 3. If the byte is an address byte, software must identify if it is starting a read or write operation using the PLIB_I2C_SlaveReadIsRequested function. 4. Software must read the byte from the RX buffer using the PLIB_I2C_ReceivedByteGet function, even if it was an address byte. 5. If clock stretching was enabled during initialization, then software must call the PLIB_I2C_SlaveClockRelease function to release the SCL line. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; if ( PLIB_I2C_ReceivedByteIsAvailable(MY_I2C_ID) ) { // Check to see if the byte is data or an address if (PLIB_I2C_SlaveAddressWasDetected(MY_I2C_ID)) { if ( PLIB_I2C_SlaveReadWasRequested(MY_I2C_ID) ) { // Beginning a slave receive sequence } else { // Beginning a slave transmit sequence } } else { // Data Byte Received } // Read the data or address from the RX buffer data = PLIB_I2C_ReceivedByteGet(MY_I2C_ID); // Free the SCL line (only if clock stretching was enabled) PLIB_I2C_SlaveClockRelease(MY_I2C_ID); } The above example uses the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the variable used to hold the byte received. 5.6.9.4.3 Operating as a Slave Transmitter Once an an external master has addressed the the I2C module (see Operating as a Slave Receiver) with the read-write bit set 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2063 (as determined by calling the PLIB_I2C_SlaveReadIsRequested function), software can begin transmitting data to the master. Pre-Conditions 1. The module must have had it's basic options and clock frequency initialized and have been enabled(see Initializing the I2C) 2. An external master must have started a transfer. 3. The address address of the transfer must have matched with the address slave programmed into the I2C module (see Managing Slave Addresses). 4. A slave read must have been requested (as described above). Note: When the address has been received and matched the programmed local slave address, a slave interrupt will occur if it has been enabled. Transmitting a Byte When operating as a slave transmitter on the I2C bus, the software must use the following sequence to transmit data bytes. 1. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 2. Write the byte to be transmitted to the TX buffer using the PLIB_I2C_TransmitterByteSend function. 3. If clock stretching was enabled (using the PLIB_I2C_SlaveClockStretchingEnable function) and the previous byte was ACKed, the PLIB_I2C_SlaveClockRelease function must be called to release the SCL line (it is safe to call this even if the previous byte was NAKed.) Example #define MY_I2C_ID I2C_ID_1 uint8_t data; // Assign the desired byte value into the "data" variable if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { // Write the byte to the TX buffer PLIB_I2C_TransmitterByteSend(MY_I2C_ID, data); // Free the SCL line (only if clock stretching was enabled) PLIB_I2C_SlaveClockRelease(MY_I2C_ID); } Checking Acknowledgement After a byte has been transmitted, the module latches the ACK/NAK response from the master so that software may use the following sequence to verify it and causes another slave interrupt (if it has been enabled). 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by responding to the slave interrupt). 2. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2064 } The above examples use the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the buffer containing byte of data to transmit. 5.6.9.4.4 Operating as a Master Transmitter Whenever the I2C module initiates a transfer on the bus, it is acting as master. A transfer can be initiated any time the bus is idle. If two masters attempt to initiate transfers at nearly the same time, one of them will lose arbitration at some point during the transfer and must retry the transfer later when the bus becomes idle. The winner of arbitration can continue, without any data loss. An I2C bus transfer always begins with a Start condition, followed by one or two properly formatted bytes containing the 7-bit or 10-bit target slave address (address of the slave device that is the target of the transfer). The direction of the remainder of transfers (after the address has been sent) is indicated by bit 0 of the address (0 = write/transmitting, 1 = read/receiving, from the point of view of the master). After that, any amount of data may be transferred and a repeated Start condition (followed by another properly formatted address) can occur to change the direction of the transfer or even the target slave device. See Forming Transfers for details of the possible transfer formats. When the master is finished, an I2C bus transfer always ends with a Stop condition. These steps are summarized below. Summary of Steps 1. Send a Start condition. 2. Send a 7-bit or 10-bit address (one or two bytes with a write transfer indication in bit 0). 3. Send data bytes. 4. Send a Stop condition. Each of these steps making up a transfer will take some time to complete. The completion of each step will cause an I2C master interrupt. The software must always keep track of which state it was in, check the I2C status, and respond to the interrupt by performing the next appropriate step. Note 1: Arbitration loss can occur after each step has completed. Software should check for arbitration loss by calling the PLIB_I2C_ArbitrationLossHasOccurred function. If arbitration loss occurs, it must be cleared by calling the PLIB_I2C_ArbitrationLossClear function. Note 2: After any step completes, but before sending the Stop condition (see step 4), the master may send a repeated Start condition and start over at step 2 to change slave targets and/or transfer direction. Sending a Start Condition To start a master transfer, the software must do the following: Preconditions The module must have had its basic options and clock frequency initialized and have been enabled (see Initializing the I2C). Process 1. Verify that the bus is idle using the PLIB_I2C_BusIsIdle function. 2. Send the start signal using the PLIB_I2C_MasterStart function. 3. Check for arbitration loss after the start condition has completed using the PLIB_I2C_ArbitrationLossHasOccurred function. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2065 Example: Sending a Start Condition #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_BusIsIdle(MY_I2C_ID)) { PLIB_I2C_MasterStart(MY_I2C_ID); } The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. Even if the bus is verified to be idle before sending the start condition, a bus collision can still occur while the Start condition is being transmitted. To verify that arbitration has not been lost during transmission of the Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } Sending a 7-bit Address To send a 7-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 2. Format the address byte correctly with the 7-bit address and the read/write bit appropriately set (for a read transfer) or cleared (for a write transfer). This can be done easily using the PLIB_I2C_ADDRESS_7_BIT_FORMAT macro and the I2C_READ or I2C_WRITE constants. 3. Write the address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function (the address byte can be easily accessed using the PLIB_I2C_ADDRESS_7_BIT_BYTE_ACCESS macro) Note: A master interrupt will occur once the address byte has been transmitted and ACKed or NAKed by the targeted slave device. (If the slave device doesn't answer, an implicit NAK will occur.) 4. Once the address byte has been ACKed or NAKed by the slave target, software must verify the result and respond appropriately. The Acknowledgement and Arbitration process is described in a subsequent section, just before the description of how to send a Stop condition.) Example: Sending a 7-bit Address #define MY_I2C_ID I2C_ID_1 #deifne SLAVE_TARGET_7BIT_ADDRESS 23 I2C_7_BIT_ADDRESS slaveTargetAddress7Bit; // Format the 7-bit address byte with the read or write indication in bit 0 I2C_ADDRESS_7_BIT_FORMAT(slaveTargetAddress7Bit, SLAVE_TARGET_7BIT_ADDRESS, I2C_WRITE); // Send the address byte if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2066 I2C_ADDRESS_7_BIT_BYTE_ACCESS(slaveTargetAddress7Bit)); } Note: Bits 7-1 contain the 7-bit target slave address. Bit 0 indicates read or write direction for the remainder of the transfer. Sending a 10-bit Target Slave Address To send a 10-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Format the two address bytes correctly with the 10-bit address and the read/write bit appropriately set (for a read transfer) or cleared (for a write transfer). This can be done using the I2C_ADDRESS_10_BIT_FORMAT macro and the I2C_READ or I2C_WRITE constants. 2. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 3. Write the first address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function (the first address byte can be easily accessed using the PLIB_I2C_ADDRESS_10_BIT_1ST_BYTE_ACCESS macro) Note: After the first byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 4. Ensure that the first address byte was ACKed by the slave target (to do this, follow the Acknowledgement process described further below) 5. Write the second address byte to the TX buffer using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function (the second address byte can be easily accessed using the PLIB_I2C_ADDRESS_10_BIT_2ND_BYTE_ACCESS macro). Note: After the second byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 6. Ensure that the second address byte was ACKed by the slave target (to do this, follow the process in the Acknowledgement and Arbitration, which is described later in this section). Example: Formatting the 10-bit Address in Two Bytes #define MY_I2C_ID I2C_ID_1 #define SLAVE_TARGET_10BIT_ADDRESS 0x23 I2C_10_BIT_ADDRESS slaveAddress10Bit; I2C_ADDRESS_10_BIT_FORMAT(slaveAddress10Bit, SLAVE_TARGET_10BIT_ADDRESS, I2C_WRITE); Note: The slaveAddress10Bit variable is used in the following two examples. Example: Sending the First Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, I2C_ADDRESS_10_BIT_1ST_BYTE_ACCESS(slaveAddress10Bit)); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Example: Sending the Second Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2067 { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, I2C_ADDRESS_10_BIT_2ND_BYTE_ACCESS(slaveAddress10Bit)); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Sending a Data Byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions • The Start condition must have been sent and completed as previously described • The target slave address has been fully transmitted (with the write indication in bit 0) and ACKed by the targeted slave device Process 1. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady Function. 2. Write the byte to be transmitted to the TX buffer using the PLIB_I2C_TransmitterByteSend Function. Note: After the byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or poll the PLIB_I2C_TransmitterByteHasCompleted function). 3. Check for arbitration loss or an ACK or NAK from the slave as described in the next section, Acknowledgement and Arbitration. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; // Assign the data value into the "data" variable if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, data); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Acknowledgement and Arbitration After sending a data or address byte (as described above), the master transmitter must check to see if arbitration was lost and if the byte was ACK'd or NAK'd. If the byte was ACK'd, the slave receiver is ready to receive more bytes. If the byte was NAKed, the slave receiver cannot accept any more bytes at this time. Preconditions • The start condition must have been sent and completed as previously described • A byte (address or data) must have been transmitted, using one of the the previous processes Process 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by waiting for the master interrupt) 2. Determine if arbitration loss has occurred using the PLIB_I2C_ArbitrationLossHasOccurred function. 3. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2068 { if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Handle arbitration loss PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } else { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } } } To handle arbitration loss, the master transmitter must stop the transfer process and retry the entire transfer again at a later time when the bus is not busy. Sending a Repeated Start Condition If the master wants to change slave targets or transfer directions, it can send a repeated Start condition followed by a new address at any time after the previous target slave address has been acknowledged (and before the Stop condition has been sent). Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed • Zero or more data bytes may also have been sent and ACKed Process Send the repeated Start condition using the PLIB_I2C_MasterStartRepeat function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat(MY_I2C_ID); The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. The repeated Start must be followed by another target slave address (either 7-bit or 10-bit, as appropriate). Sending a Stop Condition When the master transmitter has finished sending data, it must end the transfer with a stop condition. Preonditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed • Zero or more data bytes may also have been sent and ACKed Note: At least one address byte must be transmitted between the Start and Stop conditions. Following a Start condition immediately with a Stop condition is a protocol error and can cause some slave devices to lock up and stop responding to the bus. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2069 Process Send a stop condition using the PLIB_I2C_MasterStop function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop(MY_I2C_ID); The Stop condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Stop condition has been initiated. After a Stop condition, the bus should be idle unless a master immediately starts a new transfer. Strictly speaking, a bus collision can still occur while the Stop condition is being transmitted. Although the transfer is already completed when the Stop condition has been sent, software does not have to abort the transfer; however, it should still check for and clear the arbitration loss condition if it occurs. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } The previous examples use the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the buffer containing byte of data to transmit. slaveTargetAddress7Bit This variable is used to demonstrate how to properly format and access a 7-bit target slave address SLAVE_TARGET_7BIT_ADDRESS This constant is used as a placeholder for the actual 7-bit target slave address that must be defined by the client code. slaveAddress10Bit This variable is used to demonstrate how to properly format and access a 10-bit slave address. SLAVE_TARGET_10BIT_ADDRESS This constant is used as a placeholder for the actual 10-bit slave address that must be defined by the client code. 5.6.9.4.5 Operating as a Master Receiver Any time the I2C module initiates a transfer on the bus, it is acting as a master. A transfer can be initiated any time the bus is idle. If two masters attempt to initiate transfers at nearly the same time, one of them will lose arbitration and must retry the transfer later when the bus becomes idle. The winner of arbitration can continue, without any data loss. An I2C bus transfer always begins with a Start condition, followed by a 7-bit or 10-bit (1-byte or 2-byte) target slave address. Therefore, every master transfer starts off transmitting at least one byte. The direction of transfer of subsequent bytes (after the first byte has been sent) is indicated by bit 0 of the first address byte (0 = write/transmitting, 1 = read/receiving, from the point of view of the master). If 10-bit addressing is used or additional data (such as an internal address) is to be transmitted after the first address byte, the first address byte must indicate a write transfer. To change the direction after transmitting more than just a single address byte, a repeated Start condition (followed by another single address byte) must be sent (see Forming Transfers for details of the possible transfer formats). When the master is finished, an I2C bus transfer always ends with a Stop condition. This results in two basic formats for receiving data as a master, as summarized below. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2070 Summary of Steps: Read Only 1. Send a Start condition. 2. Send a 7-bit address with a read transfer indication in bit 0. 3. Receive data bytes. 4. Send a Stop condition. Summary of Steps: Combined Read-Write 1. Send a Start condition. 2. Send a 7-bit address (or the first byte of a 10-bit address) with a write transfer indication in bit 0. 3. Send the second byte of a 10-bit address (and/or any additional data to be transmitted). 4. Send a repeated Start condition. 5. Resend the first byte of the 10-bit address (or a 7-bit address) with a read indication in bit 0. 6. Receive data bytes. 7. Send a Stop condition. Each of these steps making up a transfer will take some time to complete. The completion of each step will cause an I2C master interrupt. The software must always keep track of which state it was in and respond to the interrupt by performing the next appropriate step. Sending a Start Condition To start a master transfer, the software must do the following: Preconditions The module must have had its basic options and clock frequency initialized and have been enabled (see Initializing the I2C). Process 1. Verify that the bus is idle using the PLIB_I2C_BusIsIdle function. 2. Send the start signal using the PLIB_I2C_MasterStart function. Example #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_BusIsIdle(MY_I2C_ID)) { PLIB_I2C_MasterStart(MY_I2C_ID); } The Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. Even if the bus is verified to be idle before sending the Start condition, a bus collision can still occur while the Start condition is being transmitted. To verify that arbitration has not been lost during transmission of the Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } Sending a 7-bit Address To send a 7-bit address (or the first byte of a 10-bit address), the software must do the following: 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2071 Preconditions The Start condition must have been sent and completed as previously described. Process 1. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 2. Format the address byte correctly with the 7-bit address and the read/write bit appropriately set (for a read transfer) or cleared (for a write transfer). This can be done easily using the PLIB_I2C_ADDRESS_7_BIT_FORMAT macro. and the I2C_READ or I2C_WRITE constants. 3. Write the address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function (the address byte can be easily accessed using theI2C_ADDRESS_7_BIT_BYTE_ACCESS macro). Note: A master interrupt will occur once the address byte has been transmitted and ACKed or NAKed by the targeted slave device (or if arbitration was lost). If the slave device does not answer, an implicit NAK will occur. 4. Once the address byte has been ACKed or NAKed by the slave target (or if arbitration was lost), software must verify the result and respond appropriately. The Acknowledgement and Arbitration process is described in a subsequent section, just before the description of how to send a Stop condition.) Example: Sending a 7-bit Address #define MY_I2C_ID I2C_ID_1 I2C_7_BIT_ADDRESS slaveTargetAddress7Bit; // Format the 7-bit address byte with the read or write indication in bit 0 I2C_ADDRESS_7_BIT_FORMAT(slaveTargetAddress7Bit, SLAVE_TARGET_7BIT_ADDRESS, I2C_WRITE); // Send the address byte if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, I2C_ADDRESS_7_BIT_BYTE_ACCESS(slaveTargetAddress7Bit)); } Note: Bits 7-1 contain the 7-bit target slave address. Bit 0 indicates read or write direction for the remainder of the transfer. Sending a 10-bit Target Slave Address To send a 10-bit address, the software must do the following: Preconditions The Start condition must have been sent and completed as previously described. Process 1. Format the two address bytes correctly with the 10-bit address and the read/write bit cleared, indicating a write transfer. This can be done easily using the PLIB_I2C_ADDRESS_10_BIT_FORMAT macro and the I2C_WRITE constant. 2. Ensure that the TX buffer is currently ready to accept a byte to be transmitted using the PLIB_I2C_TransmitterIsReady function. 3. Write the first address byte to the TX buffer using the PLIB_I2C_TransmitterByteSend function (the first address byte can be easily accessed using the I2C_ADDRESS_10_BIT_1ST_BYTE_ACCESS Macro) Note: After the first byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or poll the PLIB_I2C_TransmitterByteHasCompleted function). 4. Ensure that the first address byte was ACKed by the slave target and check for arbitration loss. To do this, use the Acknowledgement and Arbitration process, which described in the next section. 5. Write the second address byte to the TX buffer using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function (the second address byte can be easily accessed using the I2C_ADDRESS_10_BIT_2ND_BYTE_ACCESS macro). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2072 Note: After the second byte has been sent and ACKed or NAKed by the slave, a master interrupt will occur (or you can poll the PLIB_I2C_TransmitterByteHasCompleted function). 6. Ensure that the second address byte was ACKed by the slave target and that arbitration was not lost. To do this, use the Acknowledgement and Arbitration process, which described in the next section. Example: Formatting the 10-bit Address in Two Bytes #define MY_I2C_ID I2C_ID_1 #define SLAVE_TARGET_10BIT_ADDRESS 0x23 I2C_10_BIT_ADDRESS slaveAddress10Bit; I2C_ADDRESS_10_BIT_FORMAT(slaveAddress10Bit, SLAVE_TARGET_10BIT_ADDRESS, I2C_WRITE); Note: The slaveAddress10Bit variable is used in the following two examples. Example: Sending the First Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, I2C_ADDRESS_10_BIT_1ST_BYTE_ACCESS(slaveAddress10Bit)); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Example: Sending the Second Byte of a 10-bit Address #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterIsReady(MY_I2C_ID)) { PLIB_I2C_TransmitterByteSend(MY_I2C_ID, I2C_ADDRESS_10_BIT_2ND_BYTE_ACCESS(slaveAddress10Bit)); } Wait for transmission to complete and check for acknowledgement and/or arbitration loss. Acknowledgement and Arbitration After sending a data or address byte (as described above), the master transmitter must check to see if arbitration was lost and if the byte was ACKed or NAKed. If the byte was ACKed, the slave receiver is ready to receive more bytes. If the byte was NAKed, the slave receiver cannot accept any more bytes at this time. Preconditions • The Start condition must have been sent and completed as previously described • A byte (address or data) must have been transmitted, using one of the the previous processes Process 1. Ensure that the byte has been completely transmitted using the PLIB_I2C_TransmitterByteHasCompleted function (and/or by waiting for the master interrupt). 2. Determine if arbitration loss has occurred using the PLIB_I2C_ArbitrationLossHasOccurred function. 3. Determine if the byte was ACKed or NAKed using the PLIB_I2C_TransmitterByteWasAcknowledged function. #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_TransmitterByteHasCompleted(MY_I2C_ID)) { if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Handle arbitration loss PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } else 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2073 { if (PLIB_I2C_TransmitterByteWasAcknowledged(MY_I2C_ID)) { // Transmission successful } else { // Transmission was not successful } } } To handle arbitration loss, the master must stop the transfer process and retry the entire transfer again at a later time when the bus is not busy. Sending a Repeated Start Condition If the master wants to change slave targets or transfer directions, it must send a repeated Start condition followed by a new address at any time after the previous target slave address has been acknowledged (and before the Stop condition has been sent). Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed. • Zero or more data bytes may also have been sent or received and ACKed as appropriate. Process Send the repeated Start condition using the PLIB_I2C_MasterStartRepeat function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat(MY_I2C_ID); The repeated Start condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Start condition has been initiated. It must then be followed by another target slave address (either 7-bit or 10-bit, as appropriate). Strictly speaking, a bus collision can still occur while the repeated start condition is being transmitted. To verify that arbitration has not been lost during transmission of the repeated Start condition, the software should check the PLIB_I2C_ArbitrationLossHasOccurred function after the repeated Start condition has completed. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { // Abort transfer, retry later PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } Receiving a Data Byte The following sequence can be used to receive a data byte and repeated to receive an arbitrary number of data bytes. Preconditions • The Start condition must have been sent and completed as previously described • The target slave address must have been fully transmitted (with the read indication in bit 0) and ACKed by the targeted slave device 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2074 Process 1. Start the I2C module cycling the clock line to receive one byte by calling the PLIB_I2C_MasterReceiverClock1Byte function. The I2C module will generate a master interrupt once the eighth clock cycle has completed, but before the ninth cycle has started. 2. Ensure that a byte was received and is available in the RX buffer using the PLIB_I2C_ReceivedByteIsAvailable function. 3. If a byte is available, get it from the RX buffer using the PLIB_I2C_ReceivedByteGet function. 4. ACK or NAK the byte (as determined by software) using the PLIB_I2C_ReceivedByteAcknowledge function. The master receiver indicates to the slave transmitter that it wishes to terminate the transfer by NAKing the last byte. All other bytes should be ACKed after reception. 5. Ensure that the ACK/NAK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function or by waiting for the master interrupt Note: Arbitration loss cannot occur during a master reception (only during transmission). Example: Enabling the Receiver #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterReceiverClock1Byte(MY_I2C_ID); Wait for reception to complete before attempting to get the byte from the receiver. Example: Reading a Byte from the RX Buffer #define MY_I2C_ID I2C_ID_1 #define MY_MAX_COUNT 10 uint8_t data; int count; if ( PLIB_I2C_ReceivedByteIsAvailable(MY_I2C_ID) ) { data = PLIB_I2C_ReceivedByteGet(MY_I2C_ID); count++; // Determine if the data should be ACK'd or NAK'd if (count < MY_MAX_COUNT) { PLIB_I2C_ReceivedByteAcknowledge(MY_I2C_ID, true); } else { PLIB_I2C_ReceivedByteAcknowledge(MY_I2C_ID, false); } } Wait for the ACK/NAK to complete by waiting for the next master interrupt. Example: Verifying ACK/NAK Signal is Complete #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ReceiverByteAcknowledgeHasCompleted(MY_I2C_ID)) { // Byte reception sequence complete } Sending a Stop Condition When the master transmitter has finished sending data, it must end the transfer with a Stop condition. Preconditions • The Start condition must have been sent and completed as previously described • A target slave address must have been transmitted and ACKed. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2075 • Zero or more data bytes may also have been sent or received and ACKed as appropriate Note: At least one address byte must be transmitted between the Start and Stop conditions. Following a Start condition immediately with a Stop condition is a protocol error and can cause some slave devices to lock up and stop responding to the bus. Process Send a Stop condition using the PLIB_I2C_MasterStop function. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop(MY_I2C_ID); The Stop condition must be allowed to complete before any additional steps can be taken. The only way to determine this is to wait for a master interrupt to occur after the Stop condition has been initiated. After a Stop condition, the bus should be idle unless a master immediately starts a new transfer. Strictly speaking, a bus collision can still occur while the stop condition is being transmitted. Although the transfer is already completed when the Stop condition has been sent, software does not have to abort the transfer; however, it should still check for and clear the arbitration loss condition if it occurs. Example: Checking for Arbitration Loss #define MY_I2C_ID I2C_ID_1 if (PLIB_I2C_ArbitrationLossHasOccurred(MY_I2C_ID)) { PLIB_I2C_ArbitrationLossClear(MY_I2C_ID); } The previous example uses the following constants and variables: Symbol Description MY_I2C_ID Defined as the selected I2C module value from the I2C Module enumeration. Example: #define MY_I2C_ID I2C_ID_1 data This is the buffer to hold byte of data received. slaveTargetAddress7Bit This variable is used to demonstrate how to properly format and access a 7-bit target slave address SLAVE_TARGET_7BIT_ADDRESS This constant is used as a place holder for the actual 7-bit target slave address that must be defined by the client code. slaveAddress10Bit This variable is used to demonstrate how to properly format and access a 10-bit target slave address SLAVE_TARGET_10BIT_ADDRESS This constant is used as a place holder for the actual 10-bit target slave address that must be defined by the client code. 5.6.9.4.6 Interrupt State Machine The I2C state machine can be used in either a polled or an interrupt-driven manner. However, even when polled, software must check the state of the master, slave, and error interrupt flags to identify when a state transition occurs. The I2C module can cause three different interrupts: • Slave Interrupt - A byte was sent or received in Slave mode • Master Interrupt - A bus action has completed in Master mode 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2076 • Error Interrupt - An error has occurred in any mode (see Handling Errors) Note: Refer to the "Interrupt Controller" section in the related family reference manual for directions on how to enable, detect, and respond to interrupts. The I2C module will not start generating interrupts (setting the I2C interrupt flags, even if interrupts are disabled) until it is properly configured and enabled. After that, interrupts are generated as described below. Software has to respond appropriately once the interrupt has occurred (the flag has been set) to allow the state machine to advance to the next state. These actions are described below the state machine diagram to which they refer. Notes: 1. These state machine diagrams show the normal operations. Error and exception cases are explained in the Handling Errors section and are not shown in the diagrams. 2. The transition labels sometimes represent hardware interrupts (or the setting of an interrupt flag) and sometimes represent software actions. Refer to the transition tables to understand the transitions. 3. The Wait state is shared between all state machines (i.e., while in the Wait state, the I2C module can start a new master-mode transfer or be addressed by an external master). 4. The Start state is shared between both read and write master transfer state machines (i.e., when starting a new transfer, software can choose start either a read or a write transfer). Slave Mode State Machine Slave Mode State Transitions In Slave mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the module continues to operate correctly. Transition From State To State Software Actions Enable Initialize Wait Enable the module, using the PLIB_I2C_Enable function Slave Interrupt, 7-bit Address Match, Write Wait Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and the PLIB_I2C_SlaveAddressWasDetected function to verify that a 7-bit address (or the first byte of a 10-bit address) has been received. Then, software must get the address byte from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Software must also release the clock by calling PLIB_I2C_SlaveClockRelease function to allow reception of the next byte. Note: This transition occurs on a write transfer with either a 7-bit or 10-bit address (for the first of two address bytes). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2077 Slave Interrupt, Byte Received Receive mode Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and, if one has, get the byte from the receiver buffer by calling PLIB_I2C_ReceivedByteGet function. Then, software must release the clock by calling PLIB_I2C_SlaveClockRelease function to allow reception of the next byte. Slave Interrupt, 10-bit Address Match Receive mode Receive mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and (if 10-bit addressing is being used) call the PLIB_I2C_SlaveAddress10BitWasDetected function to verify that the second byte of the 10-bit address matched the low-order 8-bits of the local-slave 10-bit address. Next, software must get the address byte received from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Note: This transition occurs on write transfer when using 10-bit (2-byte) addressing when the second address byte is received. End Receive Receive mode Wait None. Software is not aware of this transition. A receive transfer can end with a stop condition, a repeated start, or if the second-half of a 10-bit slave address does not match the programmed local slave address (and possibly the optional mask). Slave Interrupt, 7-bit Address Match, Read Wait Transmit mode Software should call the PLIB_I2C_ReceivedByteIsAvailable function to verify that a byte has been received and the PLIB_I2C_SlaveAddressWasDetected function to verify that an address has been received. Then, software must get the address byte from the receiver buffer (the byte is automatically ACKed), using the PLIB_I2C_ReceivedByteGet function. Notes: This transition occurs on a read transfer with a 7-bit (1-byte) address or after a repeated-start with a 10-bit slave address. The second byte of a 10-bit address is not sent after a repeated-start condition, only the first byte. The 10-bit slave device must remember if it was addressed at the beginning of this transfer. After handling the address byte received, software should call the PLIB_I2C_TransmitterIsReady function to make sure that the transmitter buffer is able to accept a byte and, if it is, call the PLIB_I2C_TransmitterByteSend function to send the requested byte. Slave Interrupt, Byte Completed Transmit mode Transmit mode Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function to check to see if the byte was ACKed or NAKed. If the byte was ACKed, software must send the next byte by calling the PLIB_I2C_TransmitterIsReady function to make sure that the transmitter buffer is able to accept a byte and, if it is, call the PLIB_I2C_TransmitterByteSend function to send the next byte. NAK Transmit mode Wait Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function to check to see if the byte was ACKed or NAKed. The master will NAK the last byte it wishes to receive. At that point, the transfer is effectively over and software must not attempt to send any more bytes. The module automatically transitions back to the Wait state when the Stop condition occurs, but software does not receive an interrupt at that point. Master Mode Write Transfer State Machine 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2078 Master-Mode Write-Transfer State Transitions Transition From State To State Software Actions Begin Master Transfer Wait Start This state transition occurs when software initiates transmission of the start condition. Software should call the PLIB_I2C_BusIsIdle function to verify that the bus is not currently in use by another master. Then it must call the PLIB_I2C_MasterStart function (or PLIB_I2C_MasterStartRepeat function) to send the start (or repeated start) condition. Master Interrupt, Start Completed Start 7-Bit Address, Write After the start condition has completed, software should check for a possible collision by calling the PLIB_I2C_ArbitrationLossHasOccurred function. Then, it must send an appropriately formatted 7-bit address byte (or the first byte of the 10-bit address) to the I2C bus to address a slave target. To do this, it should first call the PLIB_I2C_TransmitterIsReady function to verify that the transmitter buffer is ready to accept a byte and then call the PLIB_I2C_TransmitterByteSend function to send the byte. Master Interrupt, Byte Completed 7-bit Address, Write Transmit When the master interrupt occurs (or the PLIB_I2C_TransmitterByteHasCompleted function returns true) to indicate that the last byte sent has completed, software must check to ensure that the slave device ACKed the byte by calling the PLIB_I2C_TransmitterByteWasAcknowledged function. Software should also call the PLIB_I2C_ArbitrationLossHasOccurred function to determine if a collision occurred. If all is well, software may then send another byte to the slave using the PLIB_I2C_TransmitterIsReady function and the PLIB_I2C_TransmitterByteSend function. If 10-bit addressing is being used for this transfer, then the start condition and first byte of the 10-bit address must be followed by the second byte of the 10-bit address. Multiple slaves may respond to the first byte of the 10-bit address. It requires the second byte to uniquely identify the 10-bit slave. However, this is sent using the same process as if it were a data byte. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2079 Master Interrupt, Byte Completed Transmit Transmit Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function check to ensure that the slave device ACKed the byte and the PLIB_I2C_ArbitrationLossHasOccurred function to determine if a collision occurred. If all is well, software may call the PLIB_I2C_TransmitterIsReady function and PLIB_I2C_TransmitterByteSend function to send another byte to the slave and remain in the Transmit state. If not, software should abort the transfer by sending a Stop condition and transition to the Stop, repeated Start state. Master Interrupt, Byte Completed 7-bit Address, Write Stop, repeated Start If the slave NAKed any byte sent or if software wishes to end or re-start the transfer (perhaps to change direction) it can do so by sending a stop condition (using the PLIB_I2C_MasterStop function) or repeated Start condition (using the PLIB_I2C_MasterStartRepeat function). Master Interrupt, Byte Completed Transmit Stop, repeated Start Software must call the PLIB_I2C_TransmitterByteWasAcknowledged function check to check to see if the slave ACKed or NAKed the byte. If the slave NAKed the byte or if software wishes to end or re-start the transfer (perhaps to change direction) it can do so by sending a Stop condition (using the PLIB_I2C_MasterStop function) or repeated Start condition (using the PLIB_I2C_MasterStartRepeat function). Restart Stop, repeated Start Start Immediately after initiating the repeated Start condition, software transitions back to the Start state where it must decide what sort of transfer it will start next. Note: Read transfers will transition to the Start state in the Master Mode Read Transfer state machine. Master Interrupt, Stop Completed Stop, repeated Start Wait When the master interrupt occurs, indicating that the Stop condition has completed, software transitions back to the Wait state (which is actually part of the Slave Mode state machine). Master-Mode Read-Transfer State Machine 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2080 Master Mode Read Transfer State Transitions In Master mode, transitions are initiated under software control and interrupts occur (the master interrupt flag is set, even when interrupts are disabled) when the action initiated has completed. If at any point, an address or data byte is NAKed by the slave or an error occurs, usually the safest thing for the master to do is to end the transfer with a Stop condition and release the bus. Transition From State To State Software Actions Begin Master Transfer Wait Start This state transition occurs when software initiates transmission of the start condition. Software should call the PLIB_I2C_BusIsIdle function to verify that the bus is not currently in use by another master. Then it must call the PLIB_I2C_MasterStart function (or PLIB_I2C_MasterStartRepeat function) to send the start (or repeated Start) condition. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2081 Master Interrupt, Start Completed Start 7-Bit Address, Read After the start condition has completed, software should check for a possible collision by calling the PLIB_I2C_ArbitrationLossHasOccurred function. Then, it must send an appropriately formatted 7-bit address byte (or the first byte of the 10-bit address) to the I2C bus to address a slave target. To do this, it should first call the PLIB_I2C_TransmitterIsReady function to verify that the transmitter buffer is ready to accept a byte and then call the PLIB_I2C_TransmitterByteSend function to send the byte. Note: If using 10-bit addressing, this is a repeated transmission of the first byte of the 10-bit address since all 10-bit transfers must start off as write transfers (so both address bytes can be sent) then be re-started to become read transfers. Master Interrupt, Byte Completed 7-Bit Address, Read Receive Software must initiate the "Clock1Byte" operation (using the PLIB_I2C_MasterReceiverClock1Byte function) so that the I2C module will cycle the SCL line eight times causing the slave to send the requested byte of data. Master Interrupt, Byte Available Receive ACK NAK When a byte has been received (which software can verify using the PLIB_I2C_ReceivedByteIsAvailable function), software must get the received byte from the RX buffer (using the PLIB_I2C_ReceivedByteGet function) and initiate transmission of the ACK/NAK bit (using the PLIB_I2C_ReceivedByteAcknowledge function). If it intends to receive another byte, software must ACK the byte just received. If it does not intend to receive another byte, software must NAK the byte just received. Master Interrupt, ACK Completed ACK, NAK Receive Software can verify that the ACK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function. If software ACKed the previously received byte, it must initiate the "Clock1Byte" operation (using the PLIB_I2C_MasterReceiverClock1Byte function) so that the I2C module will cycle the SCL line eight times so that the slave can send the requested byte. Otherwise, software must have NAKed the previous byte to end the transfer. Master Interrupt, NAK Completed ACK, NAK Stop, Restart Software can verify that the NAK signal has completed using the PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function. If software intends to continue the transfer without allowing the bus to go idle, it must initiate a repeated-start (using the PLIB_I2C_MasterStartRepeat function) and transition immediately to the Start state. If software intends to end the transfer and allow the bus to go idle, it must initiate a Stop condition using the PLIB_I2C_MasterStop function. Restart Stop, repeated Start Start Immediately after initiating the repeated Start condition, software automatically transitions back to the "Start" state where it must decide if it will restart with a read or write transfer. Note: Write transfers will transition to the Start state in the Master Mode Write Transfer state machine. Master Interrupt, Stop Completed Stop, repeated Start Wait When the master interrupt occurs, indicating that the Stop condition has completed, software transitions back to the waiting state (which is actually part of the Slave Mode state machine). 5.6.9.4.7 Managing Slave Addresses An I2C address identifies which slave device is being targeted by a master device on a transfer-by-transfer basis. I2C addresses can be either 7-bits or 10-bits, as shown in the following sections, 7-Bit Slave Addresses and 10-Bit Slave Addresses. Addresses that are 7-bits long are sent in a single byte where bit 0 identifies the direction of the remaining data in the transfer. Addresses that are 10-bits long are sent in two bytes using a reserved range in the 7-bit address space (addresses 0x78 through 0x7C) to encode the two high-order bits (bits A9 and A8) in the first byte. The second byte encodes the eight low-order bites (A7 through A0). These formats are in the following two sections. 7-Bit Slave Addresses When using 7-bit slave addressing, the address byte is the first byte sent by any I2C master device immediately following a 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2082 "Start" condition. The 7-bit address is shifted left by 1 bit to fill bits 7-to-1 in the address byte. Bit 0 in the 7-bit address byte indicates the transfer direction, as follows. Bits Usage A6:A0 Bits 7 through 1 of the address byte contain the 7-bit slave address. R/W Bit 0 of the address byte is the read/write bit (0 = Read, 1 = Write). The I2C_ADDRESS_7_BIT_FORMAT macro can be used to correctly format a 7-bit slave address. The I2C_ADDRESS_7_BIT_BYTE_ACCESS macro can be used to access the byte-format of the address (including the read/write bit). See Operating as a Master Transmitter and Operating as a Master Receiver for examples. 10-Bit Slave Addresses When using 10-bit slave addresses, the first address byte must be sent immediately following a start or repeated Start condition. The second byte must immediately follow the first byte when performing a write transfer. Read transfers must begin as write transfers so that both bytes may be sent. Immediately after sending the second address byte, the master will issue a repeated Start condition and resend the first address byte only (with the read/write bit cleared, indicating a read transfer. The second byte is not retransmitted. Since the transfer has been restarted, all listening 10-bit slave devices know that they will not be address again until the transfer has been ended with a Stop condition. However, devices that respond to 7-bit addresses might respond, so the first byte of the 10-bit address must be repeated to prevent that. The format of the 10-bit address is shown as follows. Bits Usage 11110 Bits 7 through 3 of the first byte are constants. This guarantees that the first byte of the 10-bit address will fall within the reserved range of the 7-bit addresses. A9:A8 Bits 2 through 1 of the first byte are the two high-order bits of the 10-bit address. R/W Bit 0 of the first byte is the Read/Write bit (0 = Read, 1 = Write). A7:A0 The second byte contains the 8 low-order bits of the 10-bit address. The I2C_ADDRESS_10_BIT_FORMAT macro can be used to correctly format a 10-bit slave address. The I2C_ADDRESS_10_BIT_1ST_BYTE_ACCESS macro can be used to access the first byte of the 10-bit address and the I2C_ADDRESS_10_BIT_2ND_BYTE_ACCESS macro can be used to access the second byte of the 10-bit address. See Operating as a Master Transmitter and Operating as a Master Receiver for examples. Operating in Slave Mode In Slave mode, the "slave address" refers to the address (and optional mask) programmed into the I2C module to determine to which address or addresses the module will respond when addressed by an external master. The "raw" (unformatted) address is passed to or returned from the Managing Slave Addresses routines (without being formatted as shown above). Likewise, the mask passed to or returned from the Slave Mask Control Functions is unformatted. Operating in Master Mode In Master mode, the "slave address" refers to the address transmitted on the I2C bus to identify the slave target of the transfer. In these cases, the slave address must be correctly formatted (as shown above) and sent on the bus one byte at a time. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2083 5.6.9.4.8 Forming Transfers Forming Transfers Transfers are formed by chaining the basic "building blocks" shown in the following transfer format legend. The following are all valid I2C transfer formats: • This format allows a master to transmit n bytes of data to an I2C slave supporting a 7-bit address. • This format allows a master to receive n+1 bytes of data from a "streaming" slave. Such a slave has no internal addressing capability. That is, it has no internal registers or addresses. It can only "stream" data to a master that reads from it. • This format allows a master to write n bytes of data to a slave, followed immediately by reading n+1 bytes of data from a slave by sending a repeated Start condition after the first transfer. This format is useful for specifying an internal address to a device, and then reading data from that address. A repeated Start condition can also be used to chain transfers together without letting the bus go idle and potentially losing arbitration. • The following format allows a master to send n bytes of data to a target supporting a 10-bit address. • This format is used to receive n+1 bytes of data from a slave supporting a 10-bit address. The repeated Start condition must be used because the second byte of the 10-bit address must be sent after the first byte of the 10-bit address. Then, the direction of the transfer must be switched to a "read". To do this, after the repeated Start, the master repeats the first byte of 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2084 the 10-bit address with a "read" indication in the low-order bit and 10-bit slave devices must "remember" if they were being addressed once the transfer has started. • This format allows a master to send n bytes of data to a slave device supporting a 10-bit address and immediately read n+1 bytes of data from the same device using the repeated Start and resending the first byte of the 10-bit address technique as shown in the previous format. This format is useful when the master needs to read data from a specific address within a device and it needs to send that address before performing the read. • This format allows a master to chain writes to multiple slaves supporting 10-bit addresses. • This format allows a master to chain multiple writes to different slaves. Note that only the first write can be to a slave supporting a 7-bit address. The second (and any subsequent) writes must be to slaves with 10-bit addresses once any 10-bit device has been addressed. • This format can be used by a "hardware" master that does not have a programmable address. This allows the hardware master to broadcast to all slaves on the bus using the "General Call" address, followed by the master's address. (The master address is generally the same as the device's slave address if it can also act as a slave device.) This format is not normally used by a microcontroller acting as a master. However, it may be received by a microcontroller if such a hardware master exists on the bus. 5.6.9.4.9 Handling Errors There are three basic types of errors that can occur during various I2C operations: • Transmitter Overflow • Receiver Overflow • Arbitration Loss Handling Transmitter Overflow Errors A transmitter overflow error occurs when the software attempts to write to the TX buffer (by calling the PLIB_I2C_TransmitterByteSend function) while the transmitter is busy. When this occurs, the write is not allowed and the transmitter overflow status bit is set. This can be identified by calling the PLIB_I2C_TransmitterOverflowHasOccurred function. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2085 Additional attempts to write to the TX buffer will not be allowed until the transmitter overflow error is cleared by calling the PLIB_I2C_TransmitterOverflowClear function. This sort of error should be either avoided by checking the PLIB_I2C_TransmitterIsReady function before attempting to send a byte or by checking for the error after attempting to send a byte. Interrupts: The transmitter overflow error does not trigger an interrupt. Handling Receiver Overflow Errors A receiver overflow error occurs when an incoming byte has been completely received and is ready to be transferred to the RX buffer, but software has not yet gotten the previous byte from the RX buffer. When this happens the receiver overflow status bit is set and the incoming byte will be lost. This can happen when software does not respond quickly enough to a slave or master interrupt when receiving data. Software should check for this error before calling the PLIB_I2C_ReceivedByteGet function to get a byte from the RX buffer to determine if any data has been lost. This error can be identified by calling the PLIB_I2C_ReceiverOverflowHasOccurred function. This error must be cleared by calling the PLIB_I2C_ReceiverOverflowClear function or no additional data will be received. Interrupts: The receiver overflow error does not trigger an interrupt (although the incoming data byte does, even though it is lost.) Handling Arbitration Loss Errors Strictly speaking, arbitration loss is not an error. Rather it is a normal part of bus operation in a multi-master environment. Arbitration loss occurs when more than one master attempts to transmit on the bus at the same (or nearly the same) time. When this happens, at some point one of the masters will attempt to transmit a binary one ('1') when the other attempts to transmit a binary zero ('0'). At that point, the master transmitting the zero will win the transmission, because the zero transmission will dominate on the bus. The master detecting that the bus signals a zero when it attempted to transmit a one will loose arbitration and must immediately stop transmitting on the bus (which happens automatically). Arbitration loss can be detected during any of the following actions: • Transmission of a Start condition • Transmission of a repeated Start condition • Transmission of an address or data byte • Transmission of an acknowledge bit • Transmission of a Stop condition Arbitration loss can be identified by calling the PLIB_I2C_ArbitrationLossHasOccurred function. The arbitration loss condition can be cleared by calling the PLIB_I2C_ArbitrationLossClear function. Once arbitration loss occurs, the loosing master must wait until the bus is once again idle (at which time a master interrupt will occur if arbitration loss has occurred) and retransmit the transfer from the beginning. Interrupts: The I2C module will trigger an error interrupt when arbitration loss occurs. 5.6.9.4.10 Other Features Other Features Note: The following features are not available on all devices. Please refer to the specific device data sheet to determine which features are supported by your device. General Call Address Support The I2C General Call address (reserved address 0) allows a master to address all slave devices on the bus. During slave operation the module can be made to respond to or ignore the general call address using the PLIB_I2C_GeneralCallEnable function or the PLIB_I2C_GeneralCallDisable function. When a slave address byte is received, software can identify if it was was the general call address using the PLIB_I2C_SlaveAddressIsGeneralCall function (or by checking the value of the address byte 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2086 received). Note: The general call address is always 7-bits. SMBus Support The I2C module can support communication on a System Management Bus (SMBus) by calling the PLIB_I2C_SMBEnable function to adjust the electrical characteristics of the SMBus. Operation During Sleep Mode When the device enters Sleep mode, all clock sources supplied to the I2C modules are shut down. If the device enters Sleep mode in the middle of an I2C master transmission or reception operation, the operation is aborted. If the device enters Sleep mode when the module is operating in slave mode, the external master's clock will continue run the slave state machine. If a slave address match occurs, an interrupt will be provided to wake up the device. Note: Indeterminate results can occur if an error occurs during Sleep mode. Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. I 2C operation during Idle mode can be controlled using the PLIB_I2C_StopInIdleEnable function or the PLIB_I2C_StopInIdleDisable function. By default, the I2C module continues to operate in Idle mode and provide full functionality. Operation with DMA Software activity must occur between the transfer of each byte, making DMA inappropriate for use with the I2C module. 5.6.9.4.11 Using the Library Using the Libary This section describes the basic architecture of the I2C Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_i2c.h The interface to the I2C library is defined in the "plib_i2c.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the I2C library must include "peripheral.h". Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). For the I2C Peripheral Library, the module instance IDs are defined by the I2C Module enumeration. Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the specific device data sheet for more information. 5.6.9.4.11.1 Hardware Abstraction Model This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Hardware Abstraction Model Diagram 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2087 Hardware Abstraction Model Description The I2C Peripheral Library provides interface routines to interact with the blocks shown in the previous diagram. The TX Buffer and RX Buffer are 1-byte (8-bit) buffers for data transmitted (TX) or received (RX) by the Serial Interface to the I 2C bus over the SDA line synchronized with the SCL line by the Clock Control logic. The desired baud rate frequency can be programmed in the Clock Control logic (within I2C bus specifications of 0-100 kHz for Low-to-Fast I2C mode and up to 3.4 MHz for High-Speed I2C mode) by setting the Buad Rate value. However, the nature of the I 2C bus allows slower targets to stretch the clock to slower rates as required, in real time. The I2C bus is a transfer-based multi-master bus, allowing multiple masters to initiate transfers at any time the bus is not currently busy. The Master Arbiter logic monitors transfers and determines if arbitration has been lost. There is no loss of data for the winning master. However, the losing master must retry the entire transfer again later, when the bus is idle. Slave devices are identified by either 7- or-10 bit addresses. The I2C module can act as either a bus master that can initiate transfers or as a slave, responding to transfers initiated by other masters on the bus. The Slave Address Detect logic monitors transfers initiated by other masters to recognize when other masters have addressed this module when it is acting as a slave. The Slave Address is programmed into the I2C module by the software along with an (optional) address Mask, specifying bits in the address that can be ignored. This ability to "mask off" certain bits in the address allows the I2C module to identify multiple addresses and respond as if it were more than one slave device. 5.6.9.4.11.2 Library Usage Model Usage Model 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2088 The items in the diagram correspond to the groupings in the Library Interface section. Library Interface Section Description 5.6.9.4.12 Configuring the Library This library is appropriate for microcontrollers with a dedicated I2C module (not an SSP or MSSP module). 5.6.9.5 Library Interface Data Types and Constants Name Description I2C_MODULE_ID Identifies the supported I2C modules. Baud Rate Generator Control Functions Name Description PLIB_I2C_BaudRateGet Calculates the I2C module's current SCL clock frequency. PLIB_I2C_BaudRateSet Sets the desired baud rate. Existence Functions Name Description PLIB_I2C_ExistsAcksequenceProgress Identifies whether the AcksequenceIsInProgress feature exists on the I2C module PLIB_I2C_ExistsArbitrationLoss Identifies whether the ArbitrationLoss feature exists on the I2C module PLIB_I2C_ExistsBaudRate Identifies whether the BaudRate feature exists on the I2C module PLIB_I2C_ExistsBusIsIdle Identifies whether the BusIdle feature exists on the I2C module PLIB_I2C_ExistsClockStretching Identifies whether the ClockStretching feature exists on the I2C module PLIB_I2C_ExistsDataLineHoldTime Identifies whether the DataLineHoldTime feature exists on the I2C module PLIB_I2C_ExistsGeneralCall Identifies whether the GeneralCall feature exists on the I2C module PLIB_I2C_ExistsGeneralCallAddressDetect Identifies whether the GeneralCallAddressDetect feature exists on the I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2089 PLIB_I2C_ExistsHighFrequency Identifies whether the HighFrequency feature exists on the I2C module PLIB_I2C_ExistsIPMI Identifies whether the IPMI feature exists on the I2C module PLIB_I2C_ExistsMasterReceiverClock1Byte Identifies whether the MasterReceiverClock1Byte feature exists on the I2C module PLIB_I2C_ExistsMasterStart Identifies whether the MasterStart feature exists on the I2C module PLIB_I2C_ExistsMasterStartRepeat Identifies whether the MasterStartRepeat feature exists on the I2C module PLIB_I2C_ExistsMasterStop Identifies whether the MasterStop feature exists on the I2C module PLIB_I2C_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteAcknowledge Identifies whether the ReceivedByteAcknowledge feature exists on the I2C module PLIB_I2C_ExistsReceivedByteAvailable Identifies whether the ReceivedByteAvailable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteGet Identifies whether the ReceivedByteGet feature exists on the I2C module PLIB_I2C_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the I2C module PLIB_I2C_ExistsReservedAddressProtect Identifies whether the ReservedAddressProtect feature exists on the I2C module PLIB_I2C_ExistsSlaveAddress10Bit Identifies whether the SlaveAddress10Bit feature exists on the I2C module PLIB_I2C_ExistsSlaveAddress7Bit Identifies whether the SlaveAddress7Bit feature exists on the I2C module PLIB_I2C_ExistsSlaveAddressDetect Identifies whether the SlaveAddressDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveAddressHoldEnable Identifies whether the SlaveAddressHoldEnable feature exists on the I2C module PLIB_I2C_ExistsSlaveBufferOverwrite Identifies whether the SlaveBufferOverwrite feature exists on the I2C module PLIB_I2C_ExistsSlaveBusCollisionDetect Identifies whether the SlaveBusCollisionDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveClockHold Identifies whether the SlaveClockHold feature exists on the I2C module PLIB_I2C_ExistsSlaveDataDetect Identifies whether the SlaveDataDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveInterruptOnStart Identifies whether the SlaveInterruptOnStart feature exists on the I2C module PLIB_I2C_ExistsSlaveInterruptOnStop Identifies whether the SlaveInterruptOnStop feature exists on the I2C module PLIB_I2C_ExistsSlaveMask Identifies whether the SlaveMask feature exists on the I2C module PLIB_I2C_ExistsSlaveReadRequest Identifies whether the SlaveReadRequest feature exists on the I2C module PLIB_I2C_ExistsSMBus Identifies whether the SMBus feature exists on the I2C module PLIB_I2C_ExistsStartDetect Identifies whether the StartDetect feature exists on the I2C module PLIB_I2C_ExistsStopDetect Identifies whether the StopDetect feature exists on the I2C module PLIB_I2C_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the I2C module PLIB_I2C_ExistsTransmitterByteAcknowledge Identifies whether the TransmitterByteAcknowledge feature exists on the I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2090 PLIB_I2C_ExistsTransmitterByteComplete Identifies whether the TransmitterByteComplete feature exists on the I2C module PLIB_I2C_ExistsTransmitterByteSend Identifies whether the TransmitterByteSend feature exists on the I2C module PLIB_I2C_ExistsTransmitterIsBusy Identifies whether the TransmitterBusy feature exists on the I2C module PLIB_I2C_ExistsTransmitterOverflow Identifies whether the TransmitterOverflow feature exists on the I2C module General Initialization Functions Name Description PLIB_I2C_Disable Disables the specified I2C module. PLIB_I2C_Enable Enables the specified I2C module. PLIB_I2C_GeneralCallDisable Disables the I2C module from recognizing the general call address. PLIB_I2C_GeneralCallEnable Enables the I2C module to recognize the general call address. PLIB_I2C_HighFrequencyDisable Disables the I2C module from using high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_HighFrequencyEnable Enables the I2C module to use high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_IPMIDisable Disables the I2C module's support for the IPMI specification PLIB_I2C_IPMIEnable Enables the I2C module to support the Intelligent Platform Management Interface (IPMI) specification (see Remarks). PLIB_I2C_ReservedAddressProtectDisable Disables the I2C module from protecting reserved addresses, allowing it to respond to them. PLIB_I2C_ReservedAddressProtectEnable Enables the I2C module to protect (not respond to) reserved addresses. PLIB_I2C_SlaveClockStretchingDisable Disables the I2C module from stretching the slave clock. PLIB_I2C_SlaveClockStretchingEnable Enables the I2C module to stretch the slave clock. PLIB_I2C_SMBDisable Disable the I2C module support for SMBus electrical signaling levels. PLIB_I2C_SMBEnable Enables the I2C module to support System Management Bus (SMBus) electrical signaling levels. PLIB_I2C_StopInIdleDisable Disables the Stop-in-Idle feature. PLIB_I2C_StopInIdleEnable Enables the I2C module to stop when the processor enters Idle mode General Status Functions Name Description PLIB_I2C_ArbitrationLossClear Clears the arbitration loss status flag PLIB_I2C_ArbitrationLossHasOccurred Identifies if bus arbitration has been lost. PLIB_I2C_BusIsIdle Determines whether the I2C bus is idle or busy. PLIB_I2C_StartClear Clears the start status flag PLIB_I2C_StartWasDetected Identifies when a Start condition has been detected. PLIB_I2C_StopClear Clears the stop status flag PLIB_I2C_StopWasDetected Identifies when a Stop condition has been detected Master Control Functions Name Description PLIB_I2C_MasterReceiverClock1Byte Drives the bus clock to receive 1 byte of data from a slave device. PLIB_I2C_MasterStart Sends an I2C Start condition on the I2C bus in Master mode. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2091 PLIB_I2C_MasterStartRepeat Sends a repeated Start condition during an ongoing transfer in Master mode. PLIB_I2C_MasterStop Sends an I2C Stop condition to terminate a transfer in Master mode. Receiver Control Functions Name Description PLIB_I2C_ReceivedByteAcknowledge Allows a receiver to acknowledge a that a byte of data has been received. PLIB_I2C_ReceivedByteGet Gets a byte of data received from the I2C bus interface. PLIB_I2C_ReceivedByteIsAvailable Detects whether the receiver has data available. PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Determines if the previous acknowledge has completed. PLIB_I2C_ReceiverOverflowClear Clears the receiver overflow status flag. PLIB_I2C_ReceiverOverflowHasOccurred Identifies if a receiver overflow error has occurred. PLIB_I2C_MasterReceiverReadyToAcknowledge Checks whether the hardware is ready to acknowledge. Slave Address Control Functions Name Description PLIB_I2C_SlaveAddress10BitGet Identifies the current 10-bit Slave mode address. PLIB_I2C_SlaveAddress10BitSet Selects 10-bit Slave mode addressing and sets the address value. PLIB_I2C_SlaveAddress10BitWasDetected Detects reception of the second byte of a 10-bit slave address. PLIB_I2C_SlaveAddress7BitGet Identifies the current 7-bit Slave mode address. PLIB_I2C_SlaveAddress7BitSet Selects 7-bit Slave mode addressing and sets the slave address value. PLIB_I2C_SlaveAddressHoldDisable Disables Address holding. PLIB_I2C_SlaveAddressHoldEnable Enables address holding. PLIB_I2C_SlaveAddressIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveAddressIsGeneralCall Identifies if the current slave address received is the general call address. PLIB_I2C_SlaveAddressModeIs10Bits Identifies if the current slave address mode is 7-bits or 10-bits. PLIB_I2C_SlaveDataIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveReadIsRequested Detects if the request from the master was a read or write. Slave Control Functions Name Description PLIB_I2C_AcksequenceIsInProgress Checks whether the acknowledge sequence is in progress or it is completed. PLIB_I2C_DataLineHoldTimeSet Sets the data line hold time. PLIB_I2C_SlaveBufferOverwriteDisable Disables buffer overwrite. PLIB_I2C_SlaveBufferOverwriteEnable Enables buffer overwrite. PLIB_I2C_SlaveBusCollisionDetectDisable Disables bus collision detect interrupts. PLIB_I2C_SlaveBusCollisionDetectEnable Enables slave bus collision interrupts. PLIB_I2C_SlaveClockHold Holds the SCL clock line low after receiving a byte. PLIB_I2C_SlaveClockRelease Releases a previously held SCL clock line. PLIB_I2C_SlaveDataHoldDisable Disables data holding. PLIB_I2C_SlaveDataHoldEnable Enables data holding. PLIB_I2C_SlaveInterruptOnStartDisable Disables the featue of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStartEnable Enables the featue of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStopDisable Disables the featue of generating interrupt on stop condition. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2092 PLIB_I2C_SlaveInterruptOnStopEnable Enables the featue of generating interrupt on stop condition. Slave Mask Control Functions Name Description PLIB_I2C_SlaveMask10BitGet Identifies the current 10-bit Slave mode address mask. PLIB_I2C_SlaveMask10BitSet Sets the 10-bit mask for Slave mode addressing. PLIB_I2C_SlaveMask7BitGet Identifies the current 7-bit Slave mode address mask. PLIB_I2C_SlaveMask7BitSet Sets the 7-bit mask for Slave mode addressing . Transmitter Control Functions Name Description PLIB_I2C_TransmitterByteHasCompleted Detects whether the module has finished transmitting the most recent byte. PLIB_I2C_TransmitterByteSend Sends a byte of data on the I2C bus. PLIB_I2C_TransmitterByteWasAcknowledged Determines whether the most recently sent byte was acknowledged. PLIB_I2C_TransmitterIsBusy Identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). PLIB_I2C_TransmitterIsReady Detects if the transmitter is ready to accept data to transmit. PLIB_I2C_TransmitterOverflowClear Clears the transmitter overflow status flag. PLIB_I2C_TransmitterOverflowHasOccurred Identifies if a transmitter overflow error has occurred. Description The I2C peripheral library consists of a set of interface routines, data types and constants, and macros provided by the plib_i2c.h header file. This section describes those items. 5.6.9.5.1 General Initialization Functions 5.6.9.5.1.1 PLIB_I2C_Disable Function C void PLIB_I2C_Disable( I2C_MODULE_ID index ); Description This function disables the specified I2C module. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2093 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsModuleEnable in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_Disable( MY_I2C_ID ); 5.6.9.5.1.2 PLIB_I2C_Enable Function C void PLIB_I2C_Enable( I2C_MODULE_ID index ); Description This function enables the specified I2C module. Preconditions The module should be appropriately configured before being enabled. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsModuleEnable in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQUENCY 80000000 #define MY_BAUD_RATE 10000 #define MY_SLAVE_ADDRESS 0x23 PLIB_I2C_SlaveClockStretchingEnable ( MY_I2C_ID ); PLIB_I2C_SMBDisable ( MY_I2C_ID ); PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); PLIB_I2C_ReservedAddressProtectEnable ( MY_I2C_ID ); PLIB_I2C_StopInIdleDisable ( MY_I2C_ID ); PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_CLOCK_FREQUENCY, MY_BAUD_RATE ); PLIB_I2C_SlaveAddress7BitSet( MY_I2C_ID, MY_SLAVE_ADDRESS ); PLIB_I2C_Enable ( MY_I2C_ID ); 5.6.9.5.1.3 PLIB_I2C_GeneralCallDisable Function C void PLIB_I2C_GeneralCallDisable( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2094 Description This function disables the I2C module from recognizing the general call address when operating as a slave receiver. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The General-call feature can be re-enabled by calling the PLIB_I2C_GeneralCallEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCall in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_GeneralCallDisable(MY_I2C_ID); 5.6.9.5.1.4 PLIB_I2C_GeneralCallEnable Function C void PLIB_I2C_GeneralCallEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to recognize the general call address when operating as a slave receiver. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The General-call feature can be disabled by calling the PLIB_I2C_GeneralCallDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCall in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2095 Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_GeneralCallEnable ( MY_I2C_ID ); 5.6.9.5.1.5 PLIB_I2C_HighFrequencyDisable Function C void PLIB_I2C_HighFrequencyDisable( I2C_MODULE_ID index ); Description This function disables the I2C module from using high-frequency signaling, preventing it from using the 400 kHz and 1 MHz signaling rates. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The high-frequency feature can be re-enabled by calling the PLIB_I2C_HighFrequencyEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsHighFrequency in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); 5.6.9.5.1.6 PLIB_I2C_HighFrequencyEnable Function C void PLIB_I2C_HighFrequencyEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to use high-frequency signaling, allowing it to use the 400 kHz and 1 MHz signaling rates. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2096 Returns None. Remarks The high-speed feature can be disabled by calling the PLIB_I2C_HighSpeedEnable function. This feature must be enabled if frequencies higher than 100 kHz programmed using the PLIB_I2C_BaudRateSet function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsHighFrequency in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_HighFrequencyEnable ( MY_I2C_ID ); 5.6.9.5.1.7 PLIB_I2C_IPMIDisable Function C void PLIB_I2C_IPMIDisable( I2C_MODULE_ID index ); Description This function disables the I2C module's support for the IPMI specification. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Please refer to the IPMI specification for details of the Intelligent Platform Management Interface. The IPMI specification is the property of Intel Corporation, Hewlett-Packard Company, NEC Corporation, and Dell Inc. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsIPMI in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_IPMIDisable ( MY_I2C_ID ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2097 5.6.9.5.1.8 PLIB_I2C_IPMIEnable Function C void PLIB_I2C_IPMIEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to support the IPMI specification. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Please refer to the IPMI specification for details of the Intelligent Platform Management Interface. The IPMI specification is the property of Intel Corporation, Hewlett-Packard Company, NEC Corporation, and Dell Inc. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsIPMI in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_IPMIEnable ( MY_I2C_ID ); 5.6.9.5.1.9 PLIB_I2C_ReservedAddressProtectDisable Function C void PLIB_I2C_ReservedAddressProtectDisable( I2C_MODULE_ID index ); Description This function disables the I2C module from protecting reserved addresses, allowing it to respond to them when they match the module's slave address and mask. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2098 Remarks The reserved-address-protect feature can be re-enabled by calling the PLIB_I2C_ReservedAddressProtectEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReservedAddressProtect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_ReservedAddressProtectDisable ( MY_I2C_ID ); 5.6.9.5.1.10 PLIB_I2C_ReservedAddressProtectEnable Function C void PLIB_I2C_ReservedAddressProtectEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to protect reserved addresses by not responding to them, even if they match the module's slave address and mask. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The reserved-address-protect feature can be disabled by calling the PLIB_I2C_ReservedAddressProtectDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReservedAddressProtect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_ReservedAddressProtectEnable(MY_I2C_ID); 5.6.9.5.1.11 PLIB_I2C_SlaveClockStretchingDisable Function C void PLIB_I2C_SlaveClockStretchingDisable( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2099 Description This function disables the I2C module from stretching the slave clock to allow time for software to respond to bytes received from the master. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The clock stretching feature can be re-enabled by calling the PLIB_I2C_SlaveClockStretchingEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsClockStretching in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockStretchingDisable ( MY_I2C_ID ); 5.6.9.5.1.12 PLIB_I2C_SlaveClockStretchingEnable Function C void PLIB_I2C_SlaveClockStretchingEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to stretch the slave clock to allow time for software to respond to bytes received from the master. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The clock stretching feature can be disabled by calling the PLIB_I2C_SlaveClockStretchingDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2100 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsClockStretching in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockStretchingEnable ( MY_I2C_ID ); 5.6.9.5.1.13 PLIB_I2C_SMBDisable Function C void PLIB_I2C_SMBDisable( I2C_MODULE_ID index ); Description This function disables the I2C module support for SMBus electrical signaling levels. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The SMB feature can be re-enabled by calling the PLIB_I2C_SMBEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSMBus in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SMBDisable ( MY_I2C_ID ); 5.6.9.5.1.14 PLIB_I2C_SMBEnable Function C void PLIB_I2C_SMBEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to support SMBus electrical signaling levels. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2101 Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The SMB feature can be disabled by calling the PLIB_I2C_SMBDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSMBus in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SMBEnable ( MY_I2C_ID ); 5.6.9.5.1.15 PLIB_I2C_StopInIdleDisable Function C void PLIB_I2C_StopInIdleDisable( I2C_MODULE_ID index ); Description This function disables the Stop-in-Idle feature, preventing the I2C module from stopping when the processor enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The Stop-in-Idle feature can be re-enabled by calling the PLIB_I2C_StopInIdleEnable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_StopInIdleDisable ( MY_I2C_ID ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2102 5.6.9.5.1.16 PLIB_I2C_StopInIdleEnable Function C void PLIB_I2C_StopInIdleEnable( I2C_MODULE_ID index ); Description This function enables the I2C module to stop when the processor enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The Stop-in-Idle feature can be disabled by calling the PLIB_I2C_StopInIdleDisable function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_StopInIdleEnable ( MY_I2C_ID ); 5.6.9.5.2 General Status Functions 5.6.9.5.2.1 PLIB_I2C_ArbitrationLossClear Function C void PLIB_I2C_ArbitrationLossClear( I2C_MODULE_ID index ); Description This function clears the arbitration loss status flag. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2103 Returns None. Remarks This flag is set by hardware when bus arbitration loss occurs. Its status can be tested using the PLIB_I2C_ArbitrationLossHasOccurred function. This flag should be cleared by software after the arbitration loss has been handled. To handle the error, the entire transmission (from the Start condition to the Stop or restart condition) must be retried later when the bus becomes idle. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsArbitrationLoss in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ArbitrationLossHasOccurred ( MY_I2C_ID ) ) { // Handle bus collision PLIB_I2C_ArbitrationLossClear ( MY_I2C_ID ); } 5.6.9.5.2.2 PLIB_I2C_ArbitrationLossHasOccurred Function C bool PLIB_I2C_ArbitrationLossHasOccurred( I2C_MODULE_ID index ); Description This function identifies if bus arbitration has been lost. Preconditions Bus collisions can occur during any master-mode transmission including: • Sending a Start condition • Sending a repeated Start condition • Sending an address or data byte • sending an ACK/NAK bit • Sending a Stop condition Parameters Parameters Description index Identifies the desired I2C module Returns • true - If software if a bus collision occurred, resulting in loss of bus arbitration • false - If no bus collision occurred 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2104 Remarks The arbitration status should be checked after any Master mode transmission or if an error interrupt occurs. If a bus collision occurs, the entire transmission (from the Start condition to the Stop or restart condition) must be retried later when the bus becomes idle. This flag should be cleared by software using the PLIB_I2C_ArbitrationLossClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsArbitrationLoss in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ArbitrationLossHasOccurred ( MY_I2C_ID ) ) { // Handle bus collision PLIB_I2C_ArbitrationLossClear( MY_I2C_ID ); } 5.6.9.5.2.3 PLIB_I2C_BusIsIdle Function C bool PLIB_I2C_BusIsIdle( I2C_MODULE_ID index ); Description This function checks to see if the I2C bus is currently idle or if there is some activity currently taking place. Preconditions The module must be configured appropriately and enabled. Parameters Parameters Description index Identifies the desired I2C module Returns • true - The bus is currently idle. It is safe to start a master transfer. • false - The bus is currently busy. Do not start a master transfer. Remarks When this function returns true it does not guarantee that a bus arbitration loss cannot occur. Two or more masters can start a transfer within the minimum start signal hold time. (Refer to the I2C specification for a definition of the minimum Start condition hold time.) The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBusIsIdle in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2105 if (PLIB_I2C_BusIsIdle ( MY_I2C_ID )) { PLIB_I2C_MasterStart ( MY_I2C_ID ); } 5.6.9.5.2.4 PLIB_I2C_StartClear Function C void PLIB_I2C_StartClear( I2C_MODULE_ID index ); Description This function clears the start status flag. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks This flag is cleared automatically by the hardware when a Stop condition is detected, but it can also be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStartDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StartWasDetected( MY_I2C_ID ) ) { // Handle Start condition PLIB_I2C_StartClear(MY_I2C_ID); } 5.6.9.5.2.5 PLIB_I2C_StartWasDetected Function C bool PLIB_I2C_StartWasDetected( I2C_MODULE_ID index ); Description This function identifies when a Start condition has been detected. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2106 Parameters Parameters Description index Identifies the desired I2C module Returns • true - A Start Condition has been detected • false - No Start condition has been detected since the last time a Stop condition was detected (or the module was initialized) Remarks This flag is cleared automatically by the hardware when a stop condition is detected, but it can also be cleared by software using PLIB_I2C_StartClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStartDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StartWasDetected ( MY_I2C_ID ) ) { // Handle Start condition } 5.6.9.5.2.6 PLIB_I2C_StopClear Function C void PLIB_I2C_StopClear( I2C_MODULE_ID index ); Description This function clears the stop status flag. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks This flag is cleared automatically by the hardware when a Start condition is detected, but it can also be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopDetect in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2107 Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StopWasDetected ( MY_I2C_ID ) ) { // Handle stop condition PLIB_I2C_StopClear ( MY_I2C_ID ); } 5.6.9.5.2.7 PLIB_I2C_StopWasDetected Function C bool PLIB_I2C_StopWasDetected( I2C_MODULE_ID index ); Description This function identifies when a Stop condition has been detected. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns • true - A Stop condition has been detected • false - No Stop condition has been detected since the last time a Start condition was detected (or the module was initialized) Remarks This flag is cleared automatically by the hardware when a Start condition is detected, but it can also be cleared by software using the PLIB_I2C_StopClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsStopDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_StopWasDetected ( MY_I2C_ID ) ) { // Handle stop condition } 5.6.9.5.3 Baud Rate Generator Control Functions 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2108 5.6.9.5.3.1 PLIB_I2C_BaudRateGet Function C I2C_BAUD_RATE PLIB_I2C_BaudRateGet( I2C_MODULE_ID index, uint32_t clockFrequencyHz ); Description This function calculates the I2C module's current SCL clock frequency. Preconditions The returned value may not be valid if PLIB_I2C_BaudRateSet has not been previously called to set the SCL clock frequency. Parameters Parameters Description index Identifies the desired I2C module clockFrequencyHz Clock Frequency (Hz) provided for the I2C module Returns SCL frequency currently used Remarks The actual frequency provided may be slightly different than the frequency requested due to truncation errors. The actual frequency observed on the SCL line may be lower due to clock stretching. The MY_CLOCK_FREQUENCY macro in the example is used as placeholder for the actual clock frequency. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBaudRate in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQ_INPUT 80000000 uint32_t myBaudRate; myBaudRate = PLIB_I2C_BaudRateGet ( MY_I2C_ID, MY_CLOCK_FREQ_INPUT ); 5.6.9.5.3.2 PLIB_I2C_BaudRateSet Function C void PLIB_I2C_BaudRateSet( I2C_MODULE_ID index, uint32_t clockFrequencyHz, I2C_BAUD_RATE baudRate ); Description This function sets the desired baud rate so that the I2C module will operate at the desired clock frequency (on the SCL line of the bus.) Preconditions The source clock, being sent to the I2C module (internal to the microcontroller) must be operating at the frequency passed. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2109 Parameters Parameters Description index Identifies the desired I2C module clockFrequencyHz Clock Frequency (Hz) baudRate The desired baud rate value. This should be an appropriate value for the frequency and microcontroller in use. Returns None. Remarks IMPORTANT: The I2C module's high-frequency mode must be enabled for frequencies higher than 100 kHz using the PLIB_I2C_HighFrequencyEnable function. Otherwise, the high-frequency mode must be disabled using the PLIB_I2C_HighFrequencyDisable function. The actual frequency selected may be slightly different than the frequency requested due to truncation errors. Use the PLIB_I2C_BaudRateGet function to obtain the actual baud rate value that has been programmed. The actual frequency observed on the SCL line may be lower due to clock stretching. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue, verify that no receptions are in progress before changing the system clock. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsBaudRate in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 #define MY_CLOCK_FREQUENCY_INPUT 80000000 PLIB_I2C_HighFrequencyDisable ( MY_I2C_ID ); PLIB_I2C_BaudRateSet ( MY_I2C_ID, MY_CLOCK_FREQUENCY_INPUT, 40000 ); 5.6.9.5.4 Slave Address Control Functions 5.6.9.5.4.1 PLIB_I2C_SlaveAddress10BitGet Function C uint16_t PLIB_I2C_SlaveAddress10BitGet( I2C_MODULE_ID index ); Description This function identifies the 10-bit slave address to which the module will currently respond. Preconditions The address provided may not be valid if it has not been previously set. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2110 Returns The 10-bit slave address to which the mocule is currently set to respond. Remarks The 16-bit address will be right-aligned in the 16-bit return value. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint16_t slaveAddress; if (PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slaveAddress = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); } 5.6.9.5.4.2 PLIB_I2C_SlaveAddress10BitSet Function C void PLIB_I2C_SlaveAddress10BitSet( I2C_MODULE_ID index, uint16_t address ); Description This function selects 10-bit Slave mode addressing sets the slave address to which the module will respond when operating in Slave mode. Preconditions None Parameters Parameters Description index Identifies the desired I2C module address The 10-bit slave address to which the module will respond (The address should be right-aligned in the 16-bit parameter, without any read/write bit in the 0 position) Returns None. Remarks I2C modules on some microcontroller families may also support an address mask (to allow the module to respond to multiple addresses. When using these microcontrollers, the PLIB_I2C_SlaveAddress10BitSetMasked may be used to support the mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_10_BIT macro in the example is used as a placeholder for the actual desired slave address. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2111 Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_10_BIT 0x23 PLIB_I2C_SlaveAddress10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_10_BIT ); 5.6.9.5.4.3 PLIB_I2C_SlaveAddress10BitWasDetected Function C bool PLIB_I2C_SlaveAddress10BitWasDetected( I2C_MODULE_ID index ); Description This function detects if the second byte of a 10-bit slave address (containing the low-order 8 bits) matching the local address has been received. Preconditions The module must have been configured for 10-bit addressing in Slave mode, enabled, and the first byte of the 10-bit local slave address must have already been received and matched. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the second byte of the local 10-bit address has been received • false - If the second byte of the local 10-bit address has not been received Remarks This function should only be used by slave receivers. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddressDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t i2cReadData; if ( PLIB_I2C_SlaveAddress10BitWasDetected ( MY_I2C_ID ) ) { i2cReadData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } 5.6.9.5.4.4 PLIB_I2C_SlaveAddress7BitGet Function C uint8_t PLIB_I2C_SlaveAddress7BitGet( I2C_MODULE_ID index ); Description This function identifies the 7-bit slave address to which the module will currently respond. Preconditions The address provided may not be valid if it has not been previously set. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2112 Parameters Parameters Description index Identifies the desired I2C module Returns The 7-bit slave address to which the module is currently set to respond. Remarks The 7-bit address will be right-aligned in the 8-bit return value. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress7Bit in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t slave_address7bit; if (!PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address7bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); } 5.6.9.5.4.5 PLIB_I2C_SlaveAddress7BitSet Function C void PLIB_I2C_SlaveAddress7BitSet( I2C_MODULE_ID index, uint8_t address ); Description This function selects 7-bit Slave mode addressing sets the address to which the module will respond when operating in Slave mode. Preconditions None Parameters Parameters Description index Identifies the desired I2C module address The 7-bit slave address to which the module will respond (The address should be right-aligned in the 8-bit parameter, without any read/write bit in the 0 position) Returns None. Remarks I2C modules on some microcontroller families may also support an address mask (to allow the module to respond to multiple addresses. When using these microcontrollers, the PLIB_I2C_SlaveAddress7BitSetMasked may be used to support the mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_7_BIT macro in the example is used as a placeholder for the actual desired slave address. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2113 The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress7Bit in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddress7BitSet ( MY_I2C_ID, MY_SLAVE_ADDRESS_7_BIT ); 5.6.9.5.4.6 PLIB_I2C_SlaveAddressHoldDisable Function C void PLIB_I2C_SlaveAddressHoldDisable( I2C_MODULE_ID index ); Description This function disables address holding. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveAddressHoldEnable in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldDisable ( MY_I2C_ID ); 5.6.9.5.4.7 PLIB_I2C_SlaveAddressHoldEnable Function C void PLIB_I2C_SlaveAddressHoldEnable( I2C_MODULE_ID index ); Description This function enables address holding. If address byte is received, following the 8th falling edge of clock for a clock line will be held low. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2114 Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveAddressHoldEnable in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldEnable ( MY_I2C_ID ); 5.6.9.5.4.8 PLIB_I2C_SlaveAddressIsDetected Function C bool PLIB_I2C_SlaveAddressIsDetected( I2C_MODULE_ID index ); Description This function identifies if the most recent byte received was a data byte or an address byte. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the byte received is an address byte • false - If the byte received is a data byte Remarks This function should only be used by slave receivers. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveReadRequest in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t getData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveAddressIsDetected ( MY_I2C_ID ) ) { 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2115 if ( PLIB_I2C_SlaveReadIsRequested ( MY_I2C_ID ) ) { // Begin slave transamit mode } else { // Begin slave receive mode } } // Read the data and release the bus getData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); } 5.6.9.5.4.9 PLIB_I2C_SlaveAddressIsGeneralCall Function C bool PLIB_I2C_SlaveAddressIsGeneralCall( I2C_MODULE_ID index ); Description This function identifies if the current slave address received is the general call address. Preconditions A slave address must have been received. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the slave address received is the general call address • false - if the slave address received is not the general call address Remarks This bit is set when the general call address has been received. This bit is automatically cleared by hardware when a Stop condition occurs and cannot be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsGeneralCallAddressDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t slaveAddress7Bit; if ( !PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveAddressIsGeneralCall( MY_I2C_ID ) ) { // Handle general call address } slaveAddress7Bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2116 } 5.6.9.5.4.10 PLIB_I2C_SlaveAddressModeIs10Bits Function C bool PLIB_I2C_SlaveAddressModeIs10Bits( I2C_MODULE_ID index ); Description This function identifies if the current slave addressing mode is 7-bits or 10-bits. Preconditions The mode provided may not be valid if the address mode has not been previously set. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the current slave addressing mode is 10-bits • false - if the current slave addressing mode is 7-bits Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveAddress10Bit in your application to determine whether this feature is available. Example uint8_t slave_address7Bit; uint16_t slave_address10Bit; if ( PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address10Bit = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); } else { slave_address7Bit = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); } 5.6.9.5.4.11 PLIB_I2C_SlaveDataIsDetected Function C bool PLIB_I2C_SlaveDataIsDetected( I2C_MODULE_ID index ); Description This function identifies if the most recent byte received was a data byte or an address byte. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2117 Parameters Parameters Description index Identifies the desired I2C module. Returns • true - If the byte received is a data byte • false - If the byte received is an address byte Remarks This function should only be used by slave receivers. This function returns the opposite of the PLIB_I2C_SlaveAddressIsDetected function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveDataDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t dataReceived; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_SlaveDataIsDetected( MY_I2C_ID ) ) { // Read the data and release the bus dataReceived = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); } } 5.6.9.5.4.12 PLIB_I2C_SlaveReadIsRequested Function C bool PLIB_I2C_SlaveReadIsRequested( I2C_MODULE_ID index ); Description This function identifies if a slave read (transmit) or a slave write (receive) was requested by the master that addressed the module. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If an external master is requesting data (slave read/transmit) • false - If an external master is sending data (slave write/receive) 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2118 Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveReadRequest in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t slaveTxData; uint8_t slaveRxData; if ( PLIB_I2C_SlaveReadIsRequested ( MY_I2C_ID ) ) { if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, slaveTxData ); } } else { slaveRxData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } 5.6.9.5.5 Slave Mask Control Functions 5.6.9.5.5.1 PLIB_I2C_SlaveMask10BitGet Function C uint16_t PLIB_I2C_SlaveMask10BitGet( I2C_MODULE_ID index ); Description This function identifies the 10-bit slave address mask that is currently being used to determine which slave addresses the module will respond. Preconditions The address mask provided may not be valid if it has not been previously been set. Parameters Parameters Description index Identifies the desired I2C module Returns The 10-bit slave address mask that the module is currenty using to determine to which addresses the module will respond. Remarks The 10-bit address mask will be Right-aligned in the 16-bit return value. This function is not supported on microcontrollers with I2C modules that do not support the slave address mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2119 PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint16_t slave_address; uint16_t slave_addressMask; if ( PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slave_address = PLIB_I2C_SlaveAddress10BitGet ( MY_I2C_ID ); slave_addressMask = PLIB_I2C_SlaveMask10BitGet ( MY_I2C_ID ); } 5.6.9.5.5.2 PLIB_I2C_SlaveMask10BitSet Function C void PLIB_I2C_SlaveMask10BitSet( I2C_MODULE_ID index, uint16_t mask ); Description This function sets the 10-bit mask for Slave mode addressing. The address mask (if supported) is used, along with the slave address to identify to which addresses the module will respond when operating in Slave mode. It acts as an "ignore" mask, allowing the module to ignore bits within the slave address and thus respond to multiple slave addresses on microcontrollers with I2C modules that support the mask feature. Preconditions None Parameters Parameters Description index Identifies the desired I2C module mask This parameter identifies bits in the address that are "don't care" bits. These bits will be ignored when attempting to match the address, effectively allowing the module to recognize multiple slave addresses. (To match an address exactly, this value must be zero (0).) (This value must also be right aligned in the 16-bit parameter.) Returns None. Remarks I2C modules on some microcontroller families may not support the mask feature, in which case the PLIB_I2C_SlaveMask10BitSet function will not be supported. Refer to the specific device data sheet to determine whether his feature is supported for your device. The MY_SLAVE_ADDRESS_10_BIT and MY_SLAVE_ADDRESS_MASK_10_BIT macros in the example code are used as placeholders for the actual desired slave address and mask that must be filled in by the caller. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2120 Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_10_BIT 0x23 #define MY_SLAVE_ADDR_MASK_10_BIT 0x12 PLIB_I2C_SlaveAddress10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_10_BIT ); PLIB_I2C_SlaveMask10BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_MASK_10_BIT ); 5.6.9.5.5.3 PLIB_I2C_SlaveMask7BitGet Function C uint8_t PLIB_I2C_SlaveMask7BitGet( I2C_MODULE_ID index ); Description This function identifies the 7-bit Slave mode address mask that is currently being used to determine which slave addresses the module will respond. Preconditions The address mask provided may not be valid if it has not been previously been set. Parameters Parameters Description index Identifies the desired I2C module Returns The 7-bit Slave mode address mask that the module is currenty using to determine to which addresses the module will respond. Remarks The 7-bit address mask will be right-aligned in the 8-bit return value. This function is not supported on microcontrollers with I2C modules that do not support the slave address mask feature. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t slaveAddr; uint8_t slaveAddressMsk; if ( !PLIB_I2C_SlaveAddressModeIs10Bits ( MY_I2C_ID ) ) { slaveAddr = PLIB_I2C_SlaveAddress7BitGet ( MY_I2C_ID ); slaveAddressMsk = PLIB_I2C_SlaveMask7BitGet ( MY_I2C_ID ); } 5.6.9.5.5.4 PLIB_I2C_SlaveMask7BitSet Function C void PLIB_I2C_SlaveMask7BitSet( I2C_MODULE_ID index, uint8_t mask 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2121 ); Description This function sets the 7-bit mask for Slave mode addressing. The address mask (if supported) is used, along with the slave address to identify to which addresses the module will respond when operating in Slave mode. It acts as an "ignore" mask, allowing the module to ignore bits within the slave address and will respond to multiple slave addresses on microcontrollers with I2C modules that support the mask feature. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module mask This parameter identifies bits in the address that are "don't care" bits. These bits will be ignored when attempting to match the address, effectively allowing the module to recognize multiple slave addresses. (To match an address exactly, this parameter must be zero (0).) Returns None. Remarks I2C modules on some microcontroller families may not support the mask feature, in which case the PLIB_I2C_SlaveMask7BitSet function will not be supported. Refer to the specific device data sheet to determine whether this feature is supported for your device. The MY_SLAVE_ADDRESS_7_BIT and MY_SLAVE_ADDRESS_MASK_7_BIT macros in the example code are used as placeholders for the actual desired slave address and mask that must be filled in by the caller. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveMask in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 #define MY_SLAVE_ADDR_7_BIT 0x23 #define MY_SLAVE_ADDR_MASK_7_BIT 0x12 PLIB_I2C_SlaveAddress7BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_7_BIT ); PLIB_I2C_SlaveMask7BitSet ( MY_I2C_ID, MY_SLAVE_ADDR_MASK_7_BIT ); 5.6.9.5.6 Slave Control Functions 5.6.9.5.6.1 PLIB_I2C_AcksequenceIsInProgress Function C bool PLIB_I2C_AcksequenceIsInProgress( I2C_MODULE_ID index ); Description This function checks whether the acknowledge sequence is in progress or it is completed. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2122 Preconditions The module must have been configured appropriately and enabled. Parameters Parameters Description index Identifies the desired I2C module Returns true - Acknowledge sequence is in progress. false - Acknowledge sequence is not started or completed. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsAcksequenceProgress in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_AcksequenceIsInProgress ( MY_I2C_ID ) ) { //Transmission completed } 5.6.9.5.6.2 PLIB_I2C_DataLineHoldTimeSet Function C void PLIB_I2C_DataLineHoldTimeSet( I2C_MODULE_ID index, I2C_SDA_MIN_HOLD_TIME sdaHoldTimeNs ); Description This function sets the data line hold time. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module. sdaHoldTimeNs SDA hold time in nano secconds. Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsDataLineHoldTime in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2123 Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_PLIB_I2C_DataLineHoldTimeSet ( MY_I2C_ID, I2C_SDA_MIN_HOLD_TIME_300NS ); 5.6.9.5.6.3 PLIB_I2C_SlaveBufferOverwriteDisable Function C void PLIB_I2C_SlaveBufferOverwriteDisable( I2C_MODULE_ID index ); Description This function disables buffer overwrite. If the buffer overwrite is disabled, on data receive, when the previous data is not read, the buffer will not be overwritten. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveBufferOverwrite in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBufferOverwriteDisable ( MY_I2C_ID ); 5.6.9.5.6.4 PLIB_I2C_SlaveBufferOverwriteEnable Function C void PLIB_I2C_SlaveBufferOverwriteEnable( I2C_MODULE_ID index ); Description This function enables buffer overwrite. If the buffer overwrite is enabled, on data receive, even if the previous data is not read, the buffer will be filled with new data and acknowledge will be generated. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2124 Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveBufferOverwrite in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBufferOverwriteEnable ( MY_I2C_ID ); 5.6.9.5.6.5 PLIB_I2C_SlaveBusCollisionDetectDisable Function C void PLIB_I2C_SlaveBusCollisionDetectDisable( I2C_MODULE_ID index ); Description This function disables bus collision detect interrupts. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveBusCollisionDetect in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveBusCollisionDetectDisable ( MY_I2C_ID ); 5.6.9.5.6.6 PLIB_I2C_SlaveBusCollisionDetectEnable Function C void PLIB_I2C_SlaveBusCollisionDetectEnable( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2125 Description This function enables bus collision interrupts. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveBusCollisionDetect in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveAddressHoldEnable ( MY_I2C_ID ); 5.6.9.5.6.7 PLIB_I2C_SlaveClockHold Function C void PLIB_I2C_SlaveClockHold( I2C_MODULE_ID index ); Description This function allows an I2C slave to stretch the SCL clock line, holding it low to throttle data transfer from a master transmitter. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started by an external master. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks This function will cause the SCL line to be forced low, after the current byte has been fully received. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2126 PLIB_I2C_ExistsSlaveClockHold in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockHold ( MY_I2C_ID ); 5.6.9.5.6.8 PLIB_I2C_SlaveClockRelease Function C void PLIB_I2C_SlaveClockRelease( I2C_MODULE_ID index ); Description This function allows a slave receiver to release a previously held SCL clock line, allowing it to go high and allowing data transfer to continue. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started by an external master, and the SCL clock line should have been previously held (forced low) by the I2C module. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Calling this function when the clock has not been held will not cause any problems. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveClockHold in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveClockRelease ( MY_I2C_ID ); 5.6.9.5.6.9 PLIB_I2C_SlaveDataHoldDisable Function C void PLIB_I2C_SlaveDataHoldDisable( I2C_MODULE_ID index ); Description This function disables data holding. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2127 Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveDataHoldEnable in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveDataHoldDisable ( MY_I2C_ID ); 5.6.9.5.6.10 PLIB_I2C_SlaveDataHoldEnable Function C void PLIB_I2C_SlaveDataHoldEnable( I2C_MODULE_ID index ); Description This function enables data holding. If a data byte is received, following the 8th falling edge of clock for a clock line will be held low. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_SlaveDataHoldEnable in your application to determine whether this feature is available. This API is supported only for the slave mode of I2C. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveDataHoldEnable ( MY_I2C_ID ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2128 5.6.9.5.6.11 PLIB_I2C_SlaveInterruptOnStartDisable Function C void PLIB_I2C_SlaveInterruptOnStartDisable( I2C_MODULE_ID index ); Description This function disables the featue of generating interrupt on start condition. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStart in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStartDisable ( MY_I2C_ID ); 5.6.9.5.6.12 PLIB_I2C_SlaveInterruptOnStartEnable Function C void PLIB_I2C_SlaveInterruptOnStartEnable( I2C_MODULE_ID index ); Description This function enables the featue of generating interrupt on start condition. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2129 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStart in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStartEnable ( MY_I2C_ID ); 5.6.9.5.6.13 PLIB_I2C_SlaveInterruptOnStopDisable Function C void PLIB_I2C_SlaveInterruptOnStopDisable( I2C_MODULE_ID index ); Description This function disables the featue of generating interrupt on stop condition. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStop in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStopDisable ( MY_I2C_ID ); 5.6.9.5.6.14 PLIB_I2C_SlaveInterruptOnStopEnable Function C void PLIB_I2C_SlaveInterruptOnStopEnable( I2C_MODULE_ID index ); Description This function enables the featue of generating interrupt on stop condition. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2130 Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsSlaveInterruptOnStop in your application to determine whether this feature is available. This API is applicable only in I2C slave mode. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_SlaveInterruptOnStopEnable ( MY_I2C_ID ); 5.6.9.5.7 Master Control Functions 5.6.9.5.7.1 PLIB_I2C_MasterReceiverClock1Byte Function C void PLIB_I2C_MasterReceiverClock1Byte( I2C_MODULE_ID index ); Description This function drives the bus clock to receive 1 byte of data from a slave device. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and the module must be the intended receiver of the next byte of data. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks The module stops driving the bus clock after the reception of a single byte of data and this function must be called again to receive another byte. After the module has finished receiving a data byte (determined by responding to an I2C master interrupt and/or by checking the PLIB_I2C_ReceivedByteIsAvailable function), software should check the PLIB_I2C_ReceiverOverflowHasOccurred function to ensure that no data was lost because the receiver buffer was full when the byte was completely received and ready to be placed into the receiver buffer. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2131 processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterReceiverClock1Byte in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterReceiverClock1Byte ( MY_I2C_ID ); 5.6.9.5.7.2 PLIB_I2C_MasterStart Function C void PLIB_I2C_MasterStart( I2C_MODULE_ID index ); Description This function sends the start signal (a falling edge on SDA while SCL is high) to start a transfer on the I2C bus when acting in Master mode. Preconditions The module must have been configured appropriately and enabled and the I2C bus must currently be idle. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Only an I2C master can start a transfer on the bus. The bus is considered to be busy after a Start condition. After the Start condition has completed (detected by responding to the I2C master interrupt), software should check for arbitration loss by calling the PLIB_I2C_ArbitrationLossHasOccurred function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStart in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_BusIsIdle ( MY_I2C_ID ) ) { PLIB_I2C_MasterStart ( MY_I2C_ID ); } 5.6.9.5.7.3 PLIB_I2C_MasterStartRepeat Function C void PLIB_I2C_MasterStartRepeat( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2132 Description This function supports sending a repeated Start condition to change slave targets or transfer direction to support certain I2C transfer formats in Master mode. Preconditions The module must have been configured appropriately and enabled, and a transfer must have been previously started. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Only an I2C master that has already started a transfer can send a repeated Start condition. After the repeated-start condition has completed (detected by responding to the I2C master interrupt), software should check for arbitration loss by the PLIB_I2C_ArbitrationLossHasOccurred function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStartRepeat in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStartRepeat ( MY_I2C_ID ); 5.6.9.5.7.4 PLIB_I2C_MasterStop Function C void PLIB_I2C_MasterStop( I2C_MODULE_ID index ); Description This function sends the stop signal (a rising edge on SDA while SCL is high) on the I2C bus, to end a transfer on the I2C bus when in Master mode. Preconditions The module must have been configured appropriately, enabled, and a previously started transfer must be completed. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks Only an I2C master that has already started a transfer can send a Stop condition. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2133 The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsMasterStop in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 PLIB_I2C_MasterStop ( MY_I2C_ID ); 5.6.9.5.8 Transmitter Control Functions 5.6.9.5.8.1 PLIB_I2C_TransmitterByteHasCompleted Function C bool PLIB_I2C_TransmitterByteHasCompleted( I2C_MODULE_ID index ); Description This function determines if the transmitter has finished sending the most recently sent byte on the I2C bus. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a data or address byte must have been sent. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the transmitter has completed sending the data byte • false - If the transmitter is still busy sending the data byte Remarks This function should be used by both master and slave transmitters. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteComplete in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_TransmitterByteHasCompleted ( MY_I2C_ID ) ) { //Transmission completed } 5.6.9.5.8.2 PLIB_I2C_TransmitterByteSend Function C void PLIB_I2C_TransmitterByteSend( 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2134 I2C_MODULE_ID index, uint8_t data ); Description This function allows the caller to send a byte of data on the I2C bus. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and the I2C module's transmitter must be ready to accept a byte of data to send. Parameters Parameters Description index Identifies the desired I2C module data Data byte to send on the I2C bus Returns None. Remarks This function should be used by both master and slave transmitters. The caller must either first call the PLIB_I2C_TransmitterIsReady function before calling this function to ensure that the transmitter is ready to receive a new byte to transmit or call the PLIB_I2C_TransmitterOverflowHasOccurred function immediately after calling this function to ensure that a transmitter write collision did not occur. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteSend in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t transmitData; //set 'transmitData' variable if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, transmitData ); } 5.6.9.5.8.3 PLIB_I2C_TransmitterByteWasAcknowledged Function C bool PLIB_I2C_TransmitterByteWasAcknowledged( I2C_MODULE_ID index ); Description This function allows a transmitter to determine if the byte just sent was positively acknowledged (ACKed) or negatively acknowledged (NAKed) by the receiver. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, a byte of data must have been sent on the I2C bus, and the transmission must have completed. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2135 Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the receiver ACKed the byte • false - If the receiver NAKed the byte Remarks This function can be used by both master or slave transmitters. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterByteAcknowledge in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_TransmitterByteHasCompleted ( MY_I2C_ID ) ) { if ( PLIB_I2C_TransmitterByteWasAcknowledged ( MY_I2C_ID ) ) { // transmission successful } } 5.6.9.5.8.4 PLIB_I2C_TransmitterIsBusy Function C bool PLIB_I2C_TransmitterIsBusy( I2C_MODULE_ID index ); Description This function identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns true - The transmitter is busy (unable to accept new data) false - The transmitter is ready (able to accept new data) Remarks This function returns the inverse of the PLIB_I2C_TransmitterIsReady function. This flag is cleared automatically by the hardware when the transmitter is ready. It cannot be cleared by software. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2136 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterIsBusy in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t transData; //set 'transData' variable if ( !PLIB_I2C_TransmitterIsBusy( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend( MY_I2C_ID, transData ); } 5.6.9.5.8.5 PLIB_I2C_TransmitterIsReady Function C bool PLIB_I2C_TransmitterIsReady( I2C_MODULE_ID index ); Description This function determines if the transmitter is ready to accept more data to be transmitted on the I2C bus. Preconditions The module must have been configured appropriately, enabled, and a transfer must have been previously started. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the transmitter is ready to accept more data • false - If the transmitter is not ready to accept more data Remarks This function should be used by both master and slave transmitters. This function returns the inverse of the PLIB_I2C_TransmitterIsBusy function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterIsBusy in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t sendData; //set 'sendData' variable if ( PLIB_I2C_TransmitterIsReady ( MY_I2C_ID ) ) { PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, sendData ); } 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2137 5.6.9.5.8.6 PLIB_I2C_TransmitterOverflowClear Function C void PLIB_I2C_TransmitterOverflowClear( I2C_MODULE_ID index ); Description This function clears the transmitter overflow status flag. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks This flag is set by hardware when an overflow error occurs. It's status can be tested using the PLIB_I2C_TransmitterOverflowHasOccurred function. This flag must be cleared be cleared by software after the overflow error has been handled. To handle the error, software must retry the write later after the PLIB_I2C_TransmitterByteSend function returns TRUE. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterOverflow in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t my_data; //set 'my_data' variable PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, my_data ); if ( PLIB_I2C_TransmitterOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_TransmitterOverflowClear ( MY_I2C_ID ); } 5.6.9.5.8.7 PLIB_I2C_TransmitterOverflowHasOccurred Function C bool PLIB_I2C_TransmitterOverflowHasOccurred( I2C_MODULE_ID index ); Description This function identifies if a transmitter overflow error has occurred. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2138 Parameters Parameters Description index Identifies the desired I2C module Returns true - If software attempted to write a byte to the transmitter buffer while the transmitter was busy and unable to accept a new byte (i.e., the write will not occur) false - If no transmitter overflow occurred when software attempted to write a byte to the transmitter buffer (i.e., the write occurred successfully) Remarks This flag must be cleared be cleared by software using the PLIB_I2C_TransmitterOverflowClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsTransmitterOverflow in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t txData; //set 'txData' variable PLIB_I2C_TransmitterByteSend ( MY_I2C_ID, txData ); if ( PLIB_I2C_TransmitterOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_TransmitterOverflowClear ( MY_I2C_ID ); } 5.6.9.5.9 Receiver Control Functions 5.6.9.5.9.1 PLIB_I2C_ReceivedByteAcknowledge Function C void PLIB_I2C_ReceivedByteAcknowledge( I2C_MODULE_ID index, bool ack ); Description This function allows a receiver to positively acknowledge (ACK) or negatively acknowledge (NAK) a byte of data that has been received from the I2C bus. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a byte of data must have been received from the I2C bus. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2139 5.6.9.5.9.2 PLIB_I2C_ReceivedByteGet Function C uint8_t PLIB_I2C_ReceivedByteGet( I2C_MODULE_ID index ); Description This function allows the caller to read a byte of data received from the I2C bus. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, and a byte of data must have been received from the I2C bus. Parameters Parameters Description index Identifies the desired I2C module Returns A byte of data received from the I2C bus. Remarks This function should be used by both master and slave receivers. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteGet in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t receivedData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); receivedData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } 5.6.9.5.9.3 PLIB_I2C_ReceivedByteIsAvailable Function C bool PLIB_I2C_ReceivedByteIsAvailable( I2C_MODULE_ID index ); Description This function determines if the receiver has data available to be read by software. Preconditions The I2C module must have been configured appropriately and enabled, and a transfer must have been previously started. Parameters Parameters Description index Identifies the desired I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2140 Returns • true - If the receiver has data available • false - If the receiver does not have data available Remarks This function should be used by both master and slave receivers. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAvailable in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t readData; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { readData = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } 5.6.9.5.9.4 PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Function C bool PLIB_I2C_ReceiverByteAcknowledgeHasCompleted( I2C_MODULE_ID index ); Description This function allows the receiver to determine if the acknowledgment signal has completed. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started, a byte of data must have been received on the I2C bus, and the acknowledgement must have been started (by calling the PLIB_I2C_ReceivedByteAcknowledge function). Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the acknowledgment has completed • false - If the acknowledgment has not completed Remarks This function can only be used by master receivers. Slave receivers automatically ACK or NAK bytes. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAcknowledge in your application to determine whether this feature is available. Example PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2141 if ( PLIB_I2C_ReceiverByteAcknowledgeHasCompleted ( MY_I2C_ID ) ) { // acknowledgment completed } 5.6.9.5.9.5 PLIB_I2C_ReceiverOverflowClear Function C void PLIB_I2C_ReceiverOverflowClear( I2C_MODULE_ID index ); Description This function clears the receiver overflow status flag. Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns None. Remarks This flag is set by hardware when an overflow error occurs. It's status can be tested using the PLIB_I2C_ReceiverOverflowHasOccurred function. This flag should be cleared be cleared by software after the overflow error has been handled by reading the byte in the receiver buffer. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceiverOverflow in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ReceiverOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_ReceiverOverflowClear ( MY_I2C_ID ); } 5.6.9.5.9.6 PLIB_I2C_ReceiverOverflowHasOccurred Function C bool PLIB_I2C_ReceiverOverflowHasOccurred( I2C_MODULE_ID index ); Description This function identifies if a receiver overflow error has occurred. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2142 Preconditions None. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If a byte was received while the receiver buffer still held a previously received byte (The new byte will be lost) • false - If no receiver overflow occurred when a byte has been received Remarks This flag should be cleared be cleared by software using the PLIB_I2C_ReceiverOverflowClear function. The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceiverOverflow in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 if ( PLIB_I2C_ReceiverOverflowHasOccurred ( MY_I2C_ID ) ) { // Handle overflow error PLIB_I2C_ReceiverOverflowClear ( MY_I2C_ID ); } 5.6.9.5.9.7 PLIB_I2C_MasterReceiverReadyToAcknowledge Function C bool PLIB_I2C_MasterReceiverReadyToAcknowledge( I2C_MODULE_ID index ); Description This function checks for preconditions before acknowledging a slave. Preconditions The module must have been configured appropriately and enabled, a transfer must have been previously started and a byte of data must have been received from the I2C bus. Parameters Parameters Description index Identifies the desired I2C module Returns • true - If the hardware status is ready to acknowledge • false - If the hardware is not ready to acknowledge Remarks This function can only be used by master receivers. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2143 The MY_I2C_ID macro in the example above is used as a placeholder for the actual I2C bus ID (as defined by the processor-specific I2C_MODULE_ID enum). This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_I2C_ExistsReceivedByteAcknowledge in your application to determine whether this feature is available. Example #define MY_I2C_ID I2C_ID_1 uint8_t data; if ( PLIB_I2C_ReceivedByteIsAvailable ( MY_I2C_ID ) ) { if ( PLIB_I2C_MasterReceiverReadyToAcknowledge ( MY_I2C_ID ) ) { PLIB_I2C_ReceivedByteAcknowledge ( MY_I2C_ID, true ); data = PLIB_I2C_ReceivedByteGet ( MY_I2C_ID ); } } 5.6.9.5.10 Existence Functions 5.6.9.5.10.1 PLIB_I2C_ExistsAcksequenceProgress Function C bool PLIB_I2C_ExistsAcksequenceProgress( I2C_MODULE_ID index ); Description This function identifies whether the AcksequenceIsInProgress feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_AcksequenceIsInProgress Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the AcksequenceIsInProgress feature is supported on the device • false - If the AcksequenceIsInProgress feature is not supported on the device Remarks None. 5.6.9.5.10.2 PLIB_I2C_ExistsArbitrationLoss Function C bool PLIB_I2C_ExistsArbitrationLoss( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2144 Description This function identifies whether the ArbitrationLoss feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ArbitrationLossHasOccurred • PLIB_I2C_ArbitrationLossClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ArbitrationLoss feature is supported on the device • false - If the ArbitrationLoss feature is not supported on the device Remarks None. 5.6.9.5.10.3 PLIB_I2C_ExistsBaudRate Function C bool PLIB_I2C_ExistsBaudRate( I2C_MODULE_ID index ); Description This function identifies whether the BaudRate feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_BaudRateSet • PLIB_I2C_BaudRateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the BaudRate feature is supported on the device • false - If the BaudRate feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2145 5.6.9.5.10.4 PLIB_I2C_ExistsBusIsIdle Function C bool PLIB_I2C_ExistsBusIsIdle( I2C_MODULE_ID index ); Description This function identifies whether the BusIdle feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_BusIsIdle Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the BusIdle feature is supported on the device • false - If the BusIdle feature is not supported on the device Remarks None. 5.6.9.5.10.5 PLIB_I2C_ExistsClockStretching Function C bool PLIB_I2C_ExistsClockStretching( I2C_MODULE_ID index ); Description This function identifies whether the ClockStretching feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveClockStretchingEnable • PLIB_I2C_SlaveClockStretchingDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ClockStretching feature is supported on the device • false - If the ClockStretching feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2146 5.6.9.5.10.6 PLIB_I2C_ExistsDataLineHoldTime Function C bool PLIB_I2C_ExistsDataLineHoldTime( I2C_MODULE_ID index ); Description This function identifies whether the DataLineHoldTime feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_DataLineHoldTimeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the DataLineHoldTime feature is supported on the device • false - If the DataLineHoldTime feature is not supported on the device Remarks None. 5.6.9.5.10.7 PLIB_I2C_ExistsGeneralCall Function C bool PLIB_I2C_ExistsGeneralCall( I2C_MODULE_ID index ); Description This function identifies whether the GeneralCall feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_GeneralCallEnable • PLIB_I2C_GeneralCallDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the GeneralCall feature is supported on the device • false - If the GeneralCall feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2147 5.6.9.5.10.8 PLIB_I2C_ExistsGeneralCallAddressDetect Function C bool PLIB_I2C_ExistsGeneralCallAddressDetect( I2C_MODULE_ID index ); Description This function identifies whether the GeneralCallAddressDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddressIsGeneralCall Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the GeneralCallAddressDetect feature is supported on the device • false - If the GeneralCallAddressDetect feature is not supported on the device Remarks None. 5.6.9.5.10.9 PLIB_I2C_ExistsHighFrequency Function C bool PLIB_I2C_ExistsHighFrequency( I2C_MODULE_ID index ); Description This function identifies whether the HighFrequency feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_HighFrequencyEnable • PLIB_I2C_HighFrequencyDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the HighFrequency feature is supported on the device • false - If the HighFrequency feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2148 5.6.9.5.10.10 PLIB_I2C_ExistsIPMI Function C bool PLIB_I2C_ExistsIPMI( I2C_MODULE_ID index ); Description This function identifies whether the IPMI feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_IPMIEnable • PLIB_I2C_IPMIDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the IPMI feature is supported on the device • false - If the IPMI feature is not supported on the device Remarks None. 5.6.9.5.10.11 PLIB_I2C_ExistsMasterReceiverClock1Byte Function C bool PLIB_I2C_ExistsMasterReceiverClock1Byte( I2C_MODULE_ID index ); Description This function identifies whether the MasterReceiverClock1Byte feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_MasterReceiverClock1Byte Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the MasterReceiverClock1Byte feature is supported on the device • false - If the MasterReceiverClock1Byte feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2149 5.6.9.5.10.12 PLIB_I2C_ExistsMasterStart Function C bool PLIB_I2C_ExistsMasterStart( I2C_MODULE_ID index ); Description This function identifies whether the MasterStart feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_MasterStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the MasterStart feature is supported on the device • false - If the MasterStart feature is not supported on the device Remarks None. 5.6.9.5.10.13 PLIB_I2C_ExistsMasterStartRepeat Function C bool PLIB_I2C_ExistsMasterStartRepeat( I2C_MODULE_ID index ); Description This function identifies whether the MasterStartRepeat feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_MasterStartRepeat Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the MasterStartRepeat feature is supported on the device • false - If the MasterStartRepeat feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2150 5.6.9.5.10.14 PLIB_I2C_ExistsMasterStop Function C bool PLIB_I2C_ExistsMasterStop( I2C_MODULE_ID index ); Description This function identifies whether the MasterStop feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_MasterStop Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the MasterStop feature is supported on the device • false - If the MasterStop feature is not supported on the device Remarks None. 5.6.9.5.10.15 PLIB_I2C_ExistsModuleEnable Function C bool PLIB_I2C_ExistsModuleEnable( I2C_MODULE_ID index ); Description This function identifies whether the ModuleEnable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_Enable • PLIB_I2C_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ModuleEnable feature is supported on the device • false - If the ModuleEnable feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2151 5.6.9.5.10.16 PLIB_I2C_ExistsReceivedByteAcknowledge Function C bool PLIB_I2C_ExistsReceivedByteAcknowledge( I2C_MODULE_ID index ); Description This function identifies whether the ReceivedByteAcknowledge feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceivedByteAcknowledge • PLIB_I2C_ReceiverByteAcknowledgeHasCompleted • PLIB_I2C_MasterReceiverReadyToAcknowledge Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReceivedByteAcknowledge feature is supported on the device • false - If the ReceivedByteAcknowledge feature is not supported on the device Remarks None. 5.6.9.5.10.17 PLIB_I2C_ExistsReceivedByteAvailable Function C bool PLIB_I2C_ExistsReceivedByteAvailable( I2C_MODULE_ID index ); Description This function identifies whether the ReceivedByteAvailable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceivedByteIsAvailable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReceivedByteAvailable feature is supported on the device • false - If the ReceivedByteAvailable feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2152 Remarks None. 5.6.9.5.10.18 PLIB_I2C_ExistsReceivedByteGet Function C bool PLIB_I2C_ExistsReceivedByteGet( I2C_MODULE_ID index ); Description This function identifies whether the ReceivedByteGet feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceivedByteGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReceivedByteGet feature is supported on the device • false - If the ReceivedByteGet feature is not supported on the device Remarks None. 5.6.9.5.10.19 PLIB_I2C_ExistsReceiverOverflow Function C bool PLIB_I2C_ExistsReceiverOverflow( I2C_MODULE_ID index ); Description This function identifies whether the ReceiverOverflow feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReceiverOverflowHasOccurred • PLIB_I2C_ReceiverOverflowClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReceiverOverflow feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2153 • false - If the ReceiverOverflow feature is not supported on the device Remarks None. 5.6.9.5.10.20 PLIB_I2C_ExistsReservedAddressProtect Function C bool PLIB_I2C_ExistsReservedAddressProtect( I2C_MODULE_ID index ); Description This function identifies whether the ReservedAddressProtect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_ReservedAddressProtectEnable • PLIB_I2C_ReservedAddressProtectDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReservedAddressProtect feature is supported on the device • false - If the ReservedAddressProtect feature is not supported on the device Remarks None. 5.6.9.5.10.21 PLIB_I2C_ExistsSlaveAddress10Bit Function C bool PLIB_I2C_ExistsSlaveAddress10Bit( I2C_MODULE_ID index ); Description This function identifies whether the SlaveAddress10Bit feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddress10BitSet • PLIB_I2C_SlaveAddress10BitGet • PLIB_I2C_SlaveAddressModeIs10Bits Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2154 Returns • true - If the SlaveAddress10Bit feature is supported on the device • false - If the SlaveAddress10Bit feature is not supported on the device Remarks None. 5.6.9.5.10.22 PLIB_I2C_ExistsSlaveAddress7Bit Function C bool PLIB_I2C_ExistsSlaveAddress7Bit( I2C_MODULE_ID index ); Description This function identifies whether the SlaveAddress7Bit feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddress7BitSet • PLIB_I2C_SlaveAddress7BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveAddress7Bit feature is supported on the device • false - If the SlaveAddress7Bit feature is not supported on the device Remarks None. 5.6.9.5.10.23 PLIB_I2C_ExistsSlaveAddressDetect Function C bool PLIB_I2C_ExistsSlaveAddressDetect( I2C_MODULE_ID index ); Description This function identifies whether the SlaveAddressDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddress10BitWasDetected Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2155 Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveAddressDetect feature is supported on the device • false - If the SlaveAddressDetect feature is not supported on the device Remarks None. 5.6.9.5.10.24 PLIB_I2C_ExistsSlaveAddressHoldEnable Function C bool PLIB_I2C_ExistsSlaveAddressHoldEnable( I2C_MODULE_ID index ); Description This function identifies whether the SlaveAddressHoldEnable feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveAddressHoldEnable • PLIB_I2C_SlaveAddressHoldDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveAddressHoldEnable feature is supported on the device • false - If the SlaveAddressHoldEnable feature is not supported on the device Remarks None. 5.6.9.5.10.25 PLIB_I2C_ExistsSlaveBufferOverwrite Function C bool PLIB_I2C_ExistsSlaveBufferOverwrite( I2C_MODULE_ID index ); Description This function identifies whether the SlaveBufferOverwrite feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveBufferOverwriteEnable • PLIB_I2C_SlaveBufferOverwriteDisable 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2156 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveBufferOverwrite feature is supported on the device • false - If the SlaveBufferOverwrite feature is not supported on the device Remarks None. 5.6.9.5.10.26 PLIB_I2C_ExistsSlaveBusCollisionDetect Function C bool PLIB_I2C_ExistsSlaveBusCollisionDetect( I2C_MODULE_ID index ); Description This function identifies whether the SlaveBusCollisionDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveBusCollisionDetectEnable • PLIB_I2C_SlaveBusCollisionDetectDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveBusCollisionDetect feature is supported on the device • false - If the SlaveBusCollisionDetect feature is not supported on the device Remarks None. 5.6.9.5.10.27 PLIB_I2C_ExistsSlaveClockHold Function C bool PLIB_I2C_ExistsSlaveClockHold( I2C_MODULE_ID index ); Description This function identifies whether the SlaveClockHold feature is available on the I2C module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2157 • PLIB_I2C_SlaveClockHold • PLIB_I2C_SlaveClockRelease Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveClockHold feature is supported on the device • false - If the SlaveClockHold feature is not supported on the device Remarks None. 5.6.9.5.10.28 PLIB_I2C_ExistsSlaveDataDetect Function C bool PLIB_I2C_ExistsSlaveDataDetect( I2C_MODULE_ID index ); Description This function identifies whether the SlaveDataDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveDataIsDetected • PLIB_I2C_SlaveAddressIsDetected Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveDataDetect feature is supported on the device • false - If the SlaveDataDetect feature is not supported on the device Remarks None. 5.6.9.5.10.29 PLIB_I2C_ExistsSlaveInterruptOnStart Function C bool PLIB_I2C_ExistsSlaveInterruptOnStart( I2C_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2158 Description This function identifies whether the SlaveInterruptOnStart feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveInterruptOnStartEnable • PLIB_I2C_SlaveInterruptOnStartDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveInterruptOnStart feature is supported on the device • false - If the SlaveInterruptOnStart feature is not supported on the device Remarks None. 5.6.9.5.10.30 PLIB_I2C_ExistsSlaveInterruptOnStop Function C bool PLIB_I2C_ExistsSlaveInterruptOnStop( I2C_MODULE_ID index ); Description This function identifies whether the SlaveInterruptOnStop feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveInterruptOnStopEnable • PLIB_I2C_SlaveInterruptOnStopDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveInterruptOnStop feature is supported on the device • false - If the SlaveInterruptOnStop feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2159 5.6.9.5.10.31 PLIB_I2C_ExistsSlaveMask Function C bool PLIB_I2C_ExistsSlaveMask( I2C_MODULE_ID index ); Description This function identifies whether the SlaveMask feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveMask7BitSet • PLIB_I2C_SlaveMask7BitGet • PLIB_I2C_SlaveMask10BitSet • PLIB_I2C_SlaveMask10BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveMask feature is supported on the device • false - If the SlaveMask feature is not supported on the device Remarks None. 5.6.9.5.10.32 PLIB_I2C_ExistsSlaveReadRequest Function C bool PLIB_I2C_ExistsSlaveReadRequest( I2C_MODULE_ID index ); Description This function identifies whether the SlaveReadRequest feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SlaveReadIsRequested Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SlaveReadRequest feature is supported on the device • false - If the SlaveReadRequest feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2160 Remarks None. 5.6.9.5.10.33 PLIB_I2C_ExistsSMBus Function C bool PLIB_I2C_ExistsSMBus( I2C_MODULE_ID index ); Description This function identifies whether the SMBus feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_SMBEnable • PLIB_I2C_SMBDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SMBus feature is supported on the device • false - If the SMBus feature is not supported on the device Remarks None. 5.6.9.5.10.34 PLIB_I2C_ExistsStartDetect Function C bool PLIB_I2C_ExistsStartDetect( I2C_MODULE_ID index ); Description This function identifies whether the StartDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StartWasDetected • PLIB_I2C_StartClear Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2161 Returns • true - If the StartDetect feature is supported on the device • false - If the StartDetect feature is not supported on the device Remarks None. 5.6.9.5.10.35 PLIB_I2C_ExistsStopDetect Function C bool PLIB_I2C_ExistsStopDetect( I2C_MODULE_ID index ); Description This function identifies whether the StopDetect feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StopWasDetected • PLIB_I2C_StopClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the StopDetect feature is supported on the device • false - If the StopDetect feature is not supported on the device Remarks None. 5.6.9.5.10.36 PLIB_I2C_ExistsStopInIdle Function C bool PLIB_I2C_ExistsStopInIdle( I2C_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_StopInIdleEnable • PLIB_I2C_StopInIdleDisable Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2162 Parameters Parameters Description index Identifier for the device instance Returns • true - If the StopInIdle feature is supported on the device • false - If the StopInIdle feature is not supported on the device Remarks None. 5.6.9.5.10.37 PLIB_I2C_ExistsTransmitterByteAcknowledge Function C bool PLIB_I2C_ExistsTransmitterByteAcknowledge( I2C_MODULE_ID index ); Description This function identifies whether the TransmitterByteAcknowledge feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterByteWasAcknowledged Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TransmitterByteAcknowledge feature is supported on the device • false - If the TransmitterByteAcknowledge feature is not supported on the device Remarks None. 5.6.9.5.10.38 PLIB_I2C_ExistsTransmitterByteComplete Function C bool PLIB_I2C_ExistsTransmitterByteComplete( I2C_MODULE_ID index ); Description This function identifies whether the TransmitterByteComplete feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterByteHasCompleted Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2163 Parameters Parameters Description index Identifier for the device instance Returns • true - If the TransmitterByteComplete feature is supported on the device • false - If the TransmitterByteComplete feature is not supported on the device Remarks None. 5.6.9.5.10.39 PLIB_I2C_ExistsTransmitterByteSend Function C bool PLIB_I2C_ExistsTransmitterByteSend( I2C_MODULE_ID index ); Description This function identifies whether the TransmitterByteSend feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterByteSend Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TransmitterByteSend feature is supported on the device • false - If the TransmitterByteSend feature is not supported on the device Remarks None. 5.6.9.5.10.40 PLIB_I2C_ExistsTransmitterIsBusy Function C bool PLIB_I2C_ExistsTransmitterIsBusy( I2C_MODULE_ID index ); Description This function identifies whether the TransmitterBusy feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterIsBusy • PLIB_I2C_TransmitterIsReady 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2164 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TransmitterBusy feature is supported on the device • false - If the TransmitterBusy feature is not supported on the device Remarks None. 5.6.9.5.10.41 PLIB_I2C_ExistsTransmitterOverflow Function C bool PLIB_I2C_ExistsTransmitterOverflow( I2C_MODULE_ID index ); Description This function identifies whether the TransmitterOverflow feature is available on the I2C module. When this function returns true, these functions are supported on the device: • PLIB_I2C_TransmitterOverflowHasOccurred • PLIB_I2C_TransmitterOverflowClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TransmitterOverflow feature is supported on the device • false - If the TransmitterOverflow feature is not supported on the device Remarks None. 5.6.9.5.11 Data Types and Constants 5.6.9.5.11.1 I2C_MODULE_ID Enumeration C typedef enum { I2C_ID_1, I2C_ID_2, I2C_ID_3, I2C_ID_4, 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2165 I2C_ID_5, I2C_NUMBER_OF_MODULES } I2C_MODULE_ID; Description I2C Module ID This enumeration identifies the available I2C modules. Members Members Description I2C_ID_1 I2C Module 1 ID I2C_ID_2 I2C Module 2 ID I2C_ID_3 I2C Module 3 ID I2C_ID_4 I2C Module 4 ID I2C_ID_5 I2C Module 5 ID I2C_NUMBER_OF_MODULES Number of available I2C modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers specified in the data sheet. 5.6.9.6 Files Files Name Description plib_i2c.h This file contains the interface definition for the I2C Peripheral Library. Description 5.6.9.6.1 plib_i2c.h I2C Peripheral Library Interface Header This library provides a low-level abstraction of the Inter-Integrated Circuit (I2C) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. Functions Name Description PLIB_I2C_AcksequenceIsInProgress Checks whether the acknowledge sequence is in progress or it is completed. PLIB_I2C_ArbitrationLossClear Clears the arbitration loss status flag PLIB_I2C_ArbitrationLossHasOccurred Identifies if bus arbitration has been lost. PLIB_I2C_BaudRateGet Calculates the I2C module's current SCL clock frequency. PLIB_I2C_BaudRateSet Sets the desired baud rate. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2166 PLIB_I2C_BusIsIdle Determines whether the I2C bus is idle or busy. PLIB_I2C_DataLineHoldTimeSet Sets the data line hold time. PLIB_I2C_Disable Disables the specified I2C module. PLIB_I2C_Enable Enables the specified I2C module. PLIB_I2C_ExistsAcksequenceProgress Identifies whether the AcksequenceIsInProgress feature exists on the I2C module PLIB_I2C_ExistsArbitrationLoss Identifies whether the ArbitrationLoss feature exists on the I2C module PLIB_I2C_ExistsBaudRate Identifies whether the BaudRate feature exists on the I2C module PLIB_I2C_ExistsBusIsIdle Identifies whether the BusIdle feature exists on the I2C module PLIB_I2C_ExistsClockStretching Identifies whether the ClockStretching feature exists on the I2C module PLIB_I2C_ExistsDataLineHoldTime Identifies whether the DataLineHoldTime feature exists on the I2C module PLIB_I2C_ExistsGeneralCall Identifies whether the GeneralCall feature exists on the I2C module PLIB_I2C_ExistsGeneralCallAddressDetect Identifies whether the GeneralCallAddressDetect feature exists on the I2C module PLIB_I2C_ExistsHighFrequency Identifies whether the HighFrequency feature exists on the I2C module PLIB_I2C_ExistsIPMI Identifies whether the IPMI feature exists on the I2C module PLIB_I2C_ExistsMasterReceiverClock1Byte Identifies whether the MasterReceiverClock1Byte feature exists on the I2C module PLIB_I2C_ExistsMasterStart Identifies whether the MasterStart feature exists on the I2C module PLIB_I2C_ExistsMasterStartRepeat Identifies whether the MasterStartRepeat feature exists on the I2C module PLIB_I2C_ExistsMasterStop Identifies whether the MasterStop feature exists on the I2C module PLIB_I2C_ExistsModuleEnable Identifies whether the ModuleEnable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteAcknowledge Identifies whether the ReceivedByteAcknowledge feature exists on the I2C module PLIB_I2C_ExistsReceivedByteAvailable Identifies whether the ReceivedByteAvailable feature exists on the I2C module PLIB_I2C_ExistsReceivedByteGet Identifies whether the ReceivedByteGet feature exists on the I2C module PLIB_I2C_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the I2C module PLIB_I2C_ExistsReservedAddressProtect Identifies whether the ReservedAddressProtect feature exists on the I2C module PLIB_I2C_ExistsSlaveAddress10Bit Identifies whether the SlaveAddress10Bit feature exists on the I2C module PLIB_I2C_ExistsSlaveAddress7Bit Identifies whether the SlaveAddress7Bit feature exists on the I2C module PLIB_I2C_ExistsSlaveAddressDetect Identifies whether the SlaveAddressDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveAddressHoldEnable Identifies whether the SlaveAddressHoldEnable feature exists on the I2C module 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2167 PLIB_I2C_ExistsSlaveBufferOverwrite Identifies whether the SlaveBufferOverwrite feature exists on the I2C module PLIB_I2C_ExistsSlaveBusCollisionDetect Identifies whether the SlaveBusCollisionDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveClockHold Identifies whether the SlaveClockHold feature exists on the I2C module PLIB_I2C_ExistsSlaveDataDetect Identifies whether the SlaveDataDetect feature exists on the I2C module PLIB_I2C_ExistsSlaveInterruptOnStart Identifies whether the SlaveInterruptOnStart feature exists on the I2C module PLIB_I2C_ExistsSlaveInterruptOnStop Identifies whether the SlaveInterruptOnStop feature exists on the I2C module PLIB_I2C_ExistsSlaveMask Identifies whether the SlaveMask feature exists on the I2C module PLIB_I2C_ExistsSlaveReadRequest Identifies whether the SlaveReadRequest feature exists on the I2C module PLIB_I2C_ExistsSMBus Identifies whether the SMBus feature exists on the I2C module PLIB_I2C_ExistsStartDetect Identifies whether the StartDetect feature exists on the I2C module PLIB_I2C_ExistsStopDetect Identifies whether the StopDetect feature exists on the I2C module PLIB_I2C_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the I2C module PLIB_I2C_ExistsTransmitterByteAcknowledge Identifies whether the TransmitterByteAcknowledge feature exists on the I2C module PLIB_I2C_ExistsTransmitterByteComplete Identifies whether the TransmitterByteComplete feature exists on the I2C module PLIB_I2C_ExistsTransmitterByteSend Identifies whether the TransmitterByteSend feature exists on the I2C module PLIB_I2C_ExistsTransmitterIsBusy Identifies whether the TransmitterBusy feature exists on the I2C module PLIB_I2C_ExistsTransmitterOverflow Identifies whether the TransmitterOverflow feature exists on the I2C module PLIB_I2C_GeneralCallDisable Disables the I2C module from recognizing the general call address. PLIB_I2C_GeneralCallEnable Enables the I2C module to recognize the general call address. PLIB_I2C_HighFrequencyDisable Disables the I2C module from using high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_HighFrequencyEnable Enables the I2C module to use high frequency (400 kHz or 1 MHz) signaling. PLIB_I2C_IPMIDisable Disables the I2C module's support for the IPMI specification PLIB_I2C_IPMIEnable Enables the I2C module to support the Intelligent Platform Management Interface (IPMI) specification (see Remarks). PLIB_I2C_MasterReceiverClock1Byte Drives the bus clock to receive 1 byte of data from a slave device. PLIB_I2C_MasterReceiverReadyToAcknowledge Checks whether the hardware is ready to acknowledge. PLIB_I2C_MasterStart Sends an I2C Start condition on the I2C bus in Master mode. PLIB_I2C_MasterStartRepeat Sends a repeated Start condition during an ongoing transfer in Master mode. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2168 PLIB_I2C_MasterStop Sends an I2C Stop condition to terminate a transfer in Master mode. PLIB_I2C_ReceivedByteAcknowledge Allows a receiver to acknowledge a that a byte of data has been received. PLIB_I2C_ReceivedByteGet Gets a byte of data received from the I2C bus interface. PLIB_I2C_ReceivedByteIsAvailable Detects whether the receiver has data available. PLIB_I2C_ReceiverByteAcknowledgeHasCompleted Determines if the previous acknowledge has completed. PLIB_I2C_ReceiverOverflowClear Clears the receiver overflow status flag. PLIB_I2C_ReceiverOverflowHasOccurred Identifies if a receiver overflow error has occurred. PLIB_I2C_ReservedAddressProtectDisable Disables the I2C module from protecting reserved addresses, allowing it to respond to them. PLIB_I2C_ReservedAddressProtectEnable Enables the I2C module to protect (not respond to) reserved addresses. PLIB_I2C_SlaveAddress10BitGet Identifies the current 10-bit Slave mode address. PLIB_I2C_SlaveAddress10BitSet Selects 10-bit Slave mode addressing and sets the address value. PLIB_I2C_SlaveAddress10BitWasDetected Detects reception of the second byte of a 10-bit slave address. PLIB_I2C_SlaveAddress7BitGet Identifies the current 7-bit Slave mode address. PLIB_I2C_SlaveAddress7BitSet Selects 7-bit Slave mode addressing and sets the slave address value. PLIB_I2C_SlaveAddressHoldDisable Disables Address holding. PLIB_I2C_SlaveAddressHoldEnable Enables address holding. PLIB_I2C_SlaveAddressIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveAddressIsGeneralCall Identifies if the current slave address received is the general call address. PLIB_I2C_SlaveAddressModeIs10Bits Identifies if the current slave address mode is 7-bits or 10-bits. PLIB_I2C_SlaveBufferOverwriteDisable Disables buffer overwrite. PLIB_I2C_SlaveBufferOverwriteEnable Enables buffer overwrite. PLIB_I2C_SlaveBusCollisionDetectDisable Disables bus collision detect interrupts. PLIB_I2C_SlaveBusCollisionDetectEnable Enables slave bus collision interrupts. PLIB_I2C_SlaveClockHold Holds the SCL clock line low after receiving a byte. PLIB_I2C_SlaveClockRelease Releases a previously held SCL clock line. PLIB_I2C_SlaveClockStretchingDisable Disables the I2C module from stretching the slave clock. PLIB_I2C_SlaveClockStretchingEnable Enables the I2C module to stretch the slave clock. PLIB_I2C_SlaveDataHoldDisable Disables data holding. PLIB_I2C_SlaveDataHoldEnable Enables data holding. PLIB_I2C_SlaveDataIsDetected Detects if the most recent byte received is a data or an address byte. PLIB_I2C_SlaveInterruptOnStartDisable Disables the featue of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStartEnable Enables the featue of generating interrupt on start condition. PLIB_I2C_SlaveInterruptOnStopDisable Disables the featue of generating interrupt on stop condition. PLIB_I2C_SlaveInterruptOnStopEnable Enables the featue of generating interrupt on stop condition. PLIB_I2C_SlaveMask10BitGet Identifies the current 10-bit Slave mode address mask. PLIB_I2C_SlaveMask10BitSet Sets the 10-bit mask for Slave mode addressing. PLIB_I2C_SlaveMask7BitGet Identifies the current 7-bit Slave mode address mask. 5.6 Peripheral Library Help MPLAB Harmony Help I2C Peripheral Library 5-2169 PLIB_I2C_SlaveMask7BitSet Sets the 7-bit mask for Slave mode addressing . PLIB_I2C_SlaveReadIsRequested Detects if the request from the master was a read or write. PLIB_I2C_SMBDisable Disable the I2C module support for SMBus electrical signaling levels. PLIB_I2C_SMBEnable Enables the I2C module to support System Management Bus (SMBus) electrical signaling levels. PLIB_I2C_StartClear Clears the start status flag PLIB_I2C_StartWasDetected Identifies when a Start condition has been detected. PLIB_I2C_StopClear Clears the stop status flag PLIB_I2C_StopInIdleDisable Disables the Stop-in-Idle feature. PLIB_I2C_StopInIdleEnable Enables the I2C module to stop when the processor enters Idle mode PLIB_I2C_StopWasDetected Identifies when a Stop condition has been detected PLIB_I2C_TransmitterByteHasCompleted Detects whether the module has finished transmitting the most recent byte. PLIB_I2C_TransmitterByteSend Sends a byte of data on the I2C bus. PLIB_I2C_TransmitterByteWasAcknowledged Determines whether the most recently sent byte was acknowledged. PLIB_I2C_TransmitterIsBusy Identifies if the transmitter of the specified I2C module is currently busy (unable to accept more data). PLIB_I2C_TransmitterIsReady Detects if the transmitter is ready to accept data to transmit. PLIB_I2C_TransmitterOverflowClear Clears the transmitter overflow status flag. PLIB_I2C_TransmitterOverflowHasOccurred Identifies if a transmitter overflow error has occurred. File Name plib_i2c.h Company Microchip Technology Inc. 5.6.10 Input Capture Peripheral Library 5.6.10.1 Introduction Input Capture Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Input Capture (IC) Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Input Capture (IC) module is used to capture a timer value on the occurrence of an event on an input pin. The IC module plays a major role in applications requiring frequency measurement. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2170 Figure 1: Input Capture Module Figure 1 shows the functionality of an Input Capture module. An input signal is provided to the input of this module. The input may be prescaled. An edge detection block detects if the input is undergoing a rising or falling transition. Control logic undertakes the capture of the timer value depending upon the operating mode selected. Some devices have Input Capture modules with dedicated timers that can be used to synchronize multiple IC modules together or cascade 16-bit timers to obtain a 32-bit timer. The timer may be triggered by an external, asynchronous input to start counting as well. The IC module has multiple modes of operation which can be used for different applications. Operating modes include the following: • Timer value capture at falling edge of input signal • Timer value capture at rising edge of input signal • Timer value capture at both edges of input signal • Timer value capture on a specified edge of the input signal and every edge thereafter • Timer value capture on every fourth or sixteenth rising edge of the input signal • Interrupt-only mode in which Input Capture module acts as a source of external interrupt. This mode is functional only in device sleep and idle modes. The IC module also incorporates a First In First Out (FIFO) buffer, which temporarily holds the captured value until it is read by the user application. The IC module is capable of generating interrupts when a set number of captures have taken place. 5.6.10.2 Release Notes MPLAB Harmony Version: v0.70b IC Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2171 Nothing to report in this release. 5.6.10.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.10.4 Using the Library This topic describes the basic architecture of the IC Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_ic.h The interface to the IC Peripheral library is defined in the "plib_ic.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the IC Peripheral library should include "peripheral.h". Library File: The IC Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.10.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the Input Capture (IC) module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all of the functionality of the available IC module on the device. Refer to the specific device data sheet or related family reference manual section to determine the set of functions that are supported for each IC module on your device. Description The IC Peripheral Library is used to simplify low-level access to the IC module without having the need to directly interact with the module registers. The names of the functions are generic and lead to easier access to the IC module on different device variants. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2172 Figure 2: Input Capture module Software Abstraction Block Diagram The IC module can be described from a software standpoint as having functions to configure the module itself and select an intended mode of operation. Separate functions exist to select the timer whose value is captured by the IC module. When an external input event occurs, the IC module captures the timer value and stores it in a First In First Out (FIFO) buffer. The captured value can be read from the FIFO buffer by performing an input buffer read by calling the respective function. 5.6.10.4.2 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. All of the interface functions in this library are classified according to: • General setup functions: These functions deal with general setup of the IC module • Timer functions: These routines are used to select the timer, input for the timer, and configure synchronous or triggered operation for the timer • Operation Modes routine: The PLIB_IC_ModeSelect function is used to select an operation mode of IC module • Input capture buffer routines: These routines deal with reading the capture value stored in the IC buffer and performing status checks on the IC buffer • Power-Saving modes: • In Sleep mode, the IC module can function only as an external interrupt source. A rising edge input wakes the device from sleep. An interrupt will be generated if it is enabled for that module. • In Idle mode, the IC module can be configured to either stop its operation or continue its operation • Exists functions: These functions determine whether or not a particular feature is present on a device Subsequent sections provide examples that depict the use of interface routines to perform general tasks such as IC module setup and reading captured values. 5.6.10.4.2.1 Input Capture Module Setup This section shows the steps required to initialize and configure the IC module. The IC module is configured such that a capture event occurs at the first falling edge of the input signal, and then at every subsequent edge of the input signal. Example: 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2173 /* This example shows how to initialize and configure IC module */ /* Disable IC module */ PLIB_IC_Disable(MY_IC_ID); /* Disable any peripherals multiplexed with Input Capture pin */ /* Configure I/O pin as input pin. Refer PORTS Peripheral Library */ /* Stop in Idle mode is disabled for IC module. IC mode functions even in Idle mode */ PLIB_IC_StopInIdleDisable(MY_IC_ID); /* Every Edge Capture mode of operation is selected for IC module */ PLIB_IC_ModeSelect(MY_IC_ID, IC_INPUT_CAPTURE_EVERY_EDGE_MODE); /* Falling edge capture is set for IC module. IC module captures the timer value at the first falling edge of input signal and subsequently at every edge */ PLIB_IC_FirstEdgeCaptureSet(MY_IC_ID,IC_EDGE_FALLING); /* 32-bit timer is selected*/ PLIB_IC_BufferSizeSelect(MY_IC_ID, IC_BUFFER_SIZE_32BIT); /* IC module is enabled */ PLIB_IC_Enable(MY_IC_ID); 5.6.10.4.2.2 Reading a Capture Value This section shows how to read a capture value from the input capture buffer. Example: /* This example shows how to read a Capture value */ uint32_t bufferVal; /* Reading a value from an empty Capture Buffer leads to indeterminate data*/ /* Read value from a non-empty buffer */ if(!PLIB_IC_BufferIsEmpty(MY_IC_ID)) { /* Read the buffer value */ bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); } /* Buffer Overflow condition */ while(PLIB_IC_BufferOverflowHasOccurred) { /*Read buffer values till buffer is empty and overflow condition ceases*/ bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); } 5.6.10.4.2.3 Synchronizing Timer This section shows how to enable synchronous IC timer operation for the input capture buffer. The timer of IC2 is used as the synchronization source for the IC1 module. Example: /* This example shows how to enable synchronous timer operation. Timer of IC1 is operated in synchronism with timer of IC2 */ #define MY_IC_ID1 IC_ID_1 #define MY_IC_ID2 IC_ID_2 /* Disable IC2 module */ PLIB_IC_Disable(MY_IC_ID2); /* Disable IC1 module */ 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2174 PLIB_IC_Disable(MY_IC_ID1); /* Select synchronous mode of operation for IC1 */ PLIB_IC_SyncModeSelect(MY_IC_ID1,IC_MODE_SYNC); /* Timer of IC2 is selected as synchronizing input */ PLIB_IC_SyncModeInputSelect(MY_IC_ID1,IC_SYNC_MODE_INPUT_ICAP2); /*Timer-2 is selected as clock source for IC1 timer. It is important that clock source should match with the clock source of synchronizing input*/ PLIB_IC_ClockSourceSelect(MY_IC_ID1,IC_CLOCK_SOURCE_TIMER2); /* Select synchronous mode of operation for IC2 */ PLIB_IC_SyncModeSelect(MY_IC_ID2,IC_MODE_SYNC); /*Timer-2 is selected as clock source for IC2 timer*/ PLIB_IC_ClockSourceSelect(MY_IC_ID2,IC_CLOCK_SOURCE_TIMER2); /* Disable any peripherals multiplexed with IC1 pin */ /* Disable any peripherals multiplexed with IC2 pin */ /* Configure I/O pin as input pin for IC1. Refer PORTS Peripheral Library */ /* Configure I/O pin as input pin for IC2. Refer PORTS Peripheral Library */ /* IC1 module is enabled. It is important that IC2 in enabled last as IC2 timer is being used as the source of synchronization */ PLIB_IC_Enable(MY_IC_ID1); /* IC2 module is enabled.It is important that IC2 in enabled last as IC2 timer is being used as the source of synchronization */ PLIB_IC_Enable(MY_IC_ID2); 5.6.10.4.3 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.10.5 Library Interface Data Types and Constants Name Description IC_BUFFER_SIZE Selects the IC Buffer size. IC_CLOCK_SOURCES Lists all of the input capture modes for the IC module. IC_EDGE_TYPES Lists the options to select a rising or falling edge for input capture. IC_EVENTS_PER_INTERRUPT Lists the number of input capture events for an interrupt to occur. IC_INPUT_CAPTURE_MODES Lists all of the input capture modes for the IC module. IC_MODULE_ID IC_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Refer to the specific device data sheet to determine the correct number of modules defined for the device. IC_SYNC_MODE_INPUTS Lists the input sources for synchronous and asynchronous operation of the IC module. IC_SYNC_MODES Lists the synchronization modes for the IC module. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2175 IC_TIMERS Lists the different 16-bit timers for the IC module. Feature Existence Functions Name Description PLIB_IC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the IC module PLIB_IC_ExistsBufferIsEmptyStatus Identifies whether the BufferIsEmptyStatus feature exists on the IC module PLIB_IC_ExistsBufferOverflowStatus Identifies whether the BufferOverflowStatus feature exists on the IC module. PLIB_IC_ExistsBufferSize Identifies whether the BufferSize feature exists on the IC module. PLIB_IC_ExistsBufferValue Identifies whether the BufferValue feature exists on the IC module. PLIB_IC_ExistsCaptureMode Identifies whether the CaptureMode feature exists on the IC module. PLIB_IC_ExistsClockSource Identifies whether the ClockSource feature exists on the IC module. PLIB_IC_ExistsEdgeCapture Identifies whether the EdgeCapture feature exists on the IC module. PLIB_IC_ExistsEnable Identifies whether the EnableControl feature exists on the IC module PLIB_IC_ExistsEventsPerInterruptSelect Identifies whether the EventsPerInterruptSelect feature exists on the IC module. PLIB_IC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the IC module. PLIB_IC_ExistsSyncMode Identifies whether the SyncMode feature exists on the IC module. PLIB_IC_ExistsSyncModeInput Identifies whether the SyncModeInput feature exists on the IC module. PLIB_IC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the IC module. PLIB_IC_ExistsTimerTriggered Identifies whether the TimerTriggered feature exists on the IC module. General Setup Functions Name Description PLIB_IC_Disable Disables the IC module. PLIB_IC_Enable Enables the IC module. PLIB_IC_EventsPerInterruptSelect Selects the number of capture events before an interrupt is issued. PLIB_IC_FirstCaptureEdgeSelect Captures the timer count value at the first selected edge of input signal. Input Capture Buffer Functions Name Description PLIB_IC_Buffer16BitGet Obtains the 16-bit input capture buffer value. PLIB_IC_Buffer32BitGet Obtains the 32-bit input capture buffer value. PLIB_IC_BufferIsEmpty Checks whether the input capture buffer is empty. PLIB_IC_BufferOverflowHasOccurred Checks whether an input capture buffer overflow has occurred. PLIB_IC_BufferSizeSelect Sets the input capture buffer size. Operation Modes Functions Name Description PLIB_IC_ModeSelect Selects the input capture mode for IC module. Power-Saving Modes Functions Name Description PLIB_IC_StopInIdleDisable Continues module operation when the device enters Idle mode PLIB_IC_StopInIdleEnable Discontinues IC module operation when the device enters Idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2176 Timer Functions Name Description PLIB_IC_ClockSourceSelect Selects the clock source for the IC module. PLIB_IC_SyncModeInputSelect Selects the input source for synchronous or asynchronous (triggered) operation of the IC module. PLIB_IC_SyncModeSelect Selects the synchronization mode for Input Capture module. PLIB_IC_TimerIsTriggered Checks whether or not the input capture timer has been triggered. PLIB_IC_TimerSelect Selects the 16-bit timer source for the IC module. PLIB_IC_AlternateClockDisable Selects Timer 2/3.instead of the alternate clock source. PLIB_IC_AlternateClockEnable Selects the alternate clock source. Description This section describes the Application Programming Interface (API) functions of the Input Capture Peripheral. Refer to each section for a detailed description. 5.6.10.5.1 General Setup Functions 5.6.10.5.1.1 PLIB_IC_Disable Function C void PLIB_IC_Disable( IC_MODULE_ID index ); Description This function disables the IC module. Preconditions None. Parameters Parameters Description index Identifies the IC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEnable in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 PLIB_IC_Disable(MY_IC_ID); 5.6.10.5.1.2 PLIB_IC_Enable Function C void PLIB_IC_Enable( IC_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2177 ); Description This function enables the IC module. Preconditions The module should be appropriately configured before being enabled. Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEnable in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 //Do all the other configurations before enabling. PLIB_IC_Enable(MY_IC_ID); 5.6.10.5.1.3 PLIB_IC_EventsPerInterruptSelect Function C void PLIB_IC_EventsPerInterruptSelect( IC_MODULE_ID index, IC_EVENTS_PER_INTERRUPT event ); Description The IC module can be configured to generate interrupts depending upon the the occurrence of a certain number of capture events. The number of capture events before an interrupt is generated is set by this function. Preconditions None. Parameters Parameters Description index Identifies the desired IC module event Identifies the interrupt control mode Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEventsPerInterruptSelect in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // IC module is configured to generate interrupt on every capture event 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2178 PLIB_IC_EventsPerInterruptSelect(MY_IC_ID, IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT ); 5.6.10.5.1.4 PLIB_IC_FirstCaptureEdgeSelect Function C void PLIB_IC_FirstCaptureEdgeSelect( IC_MODULE_ID index, IC_EDGE_TYPES edgeType ); Description This function captures the timer count value at the first selected edge of the input signal. Preconditions This setting applies only when the Every Edge Capture mode is set. The capture mode is set by the PLIB_IC_ModeSelect() function. Parameters Parameters Description index Identifies the desired IC module edgeType Identifies the edge type (i.e., whether rising or falling edge) Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsEdgeCapture in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 PLIB_IC_FirstCaptureEdgeSelect(MY_IC_ID,IC_EDGE_FALLING); 5.6.10.5.2 Timer Functions 5.6.10.5.2.1 PLIB_IC_ClockSourceSelect Function C void PLIB_IC_ClockSourceSelect( IC_MODULE_ID index, IC_CLOCK_SOURCES src ); Description This function selects the clock source for the IC module. Preconditions None. Parameters Parameters Description index Identifies the desired IC module src Identifies the clock source 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2179 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsClockSource in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // Clock source of Timer2 is selected as clock source for Input Capture module PLIB_IC_ClockSourceSelect(MY_IC_ID,IC_CLOCK_SOURCE_TIMER2); 5.6.10.5.2.2 PLIB_IC_SyncModeInputSelect Function C void PLIB_IC_SyncModeInputSelect( IC_MODULE_ID index, IC_SYNC_MODE_INPUTS input ); Description This function selects the input source for synchronous or asynchronous (triggered) operation of the IC module. Preconditions None. Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsSyncModeInput in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // PLIB_IC_SyncModeInputSelect(MY_IC_ID,IC_SYNC_MODE_INPUT_OC1); 5.6.10.5.2.3 PLIB_IC_SyncModeSelect Function C void PLIB_IC_SyncModeSelect( IC_MODULE_ID index, IC_SYNC_MODES syncMode ); Description This function selects the synchronization mode for the IC module. The Synchronous or Asynchronous mode of operation can be selected for the IC module timer. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2180 Parameters Parameters Description index Identifies the desired IC module syncMode Identifies the mode (Synchronous or Asynchronous) Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsSyncMode in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // External input triggers Input Capture module asynchronously PLIB_IC_SyncModeSelect(MY_IC_ID,IC_MODE_ASYNC); 5.6.10.5.2.4 PLIB_IC_TimerIsTriggered Function C bool PLIB_IC_TimerIsTriggered( IC_MODULE_ID index ); Description This function checks whether or not the input capture timer has been triggered. This function returns 'true' if the IC timer is triggered and running and returns 'false' if the IC timer is cleared and stopped. Preconditions None. Parameters Parameters Description index Identifies the desired IC module Returns bool - true - The IC timer is triggered and running • false - The IC timer is stopped and held in clear Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsTimerTriggered in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 if(!PLIB_IC_TimerIsTriggered(MY_IC_ID)) { // Do some operation }; 5.6.10.5.2.5 PLIB_IC_TimerSelect Function C void PLIB_IC_TimerSelect( 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2181 IC_MODULE_ID index, IC_TIMERS tmr ); Description This function selects the 16-bit timer source for the IC module. Preconditions None. Parameters Parameters Description index Identifies the desired IC module tmr Identifies the 16-bit timer Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsTimerSelect in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // 16-bit Timer-2 is selected PLIB_IC_TimerSelect(MY_IC_ID, IC_TIMER_TMR2); 5.6.10.5.2.6 PLIB_IC_AlternateClockDisable Function C void PLIB_IC_AlternateClockDisable( IC_MODULE_ID index ); Description Selects Timer 2/3.instead of the alternate clock source. Preconditions None. Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks The feature is not supported on all devices. Check your device's data sheet. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the IC_MODULE_ID passed in the call. Example // Call system service to unlock oscillator #define MY_IC_ID IC_ID_1 PLIB_IC_AlternateClockDisable( MY_IC_ID ); 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2182 5.6.10.5.2.7 PLIB_IC_AlternateClockEnable Function C void PLIB_IC_AlternateClockEnable( IC_MODULE_ID index ); Description Selects the alternate clock source instead of Timer 2/3. Preconditions None. Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks The feature is not supported on all devices. Check your device's data sheet. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the IC_MODULE_ID passed in the call. Example // Call system service to unlock oscillator #define MY_IC_ID IC_ID_1 PLIB_IC_AlternateClockEnable( MY_IC_ID ); 5.6.10.5.3 Input Capture Buffer Functions 5.6.10.5.3.1 PLIB_IC_Buffer16BitGet Function C uint16_t PLIB_IC_Buffer16BitGet( IC_MODULE_ID index ); Description This function reads the 16-bit value of the IC buffer to obtain the captured timer value. This function is used when the buffer size is set to 16-bits. Preconditions The buffer size should be set to 16 bits (i.e., PLIB_IC_BufferSizeSet(MY_IC_ID, IC_BUFFER_SIZE_16BIT). Parameters Parameters Description index Identifies the desired IC module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2183 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferValue in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 uint16_t bufferVal; // Read input capture buffer value and store it in 'bufferVal' bufferVal = PLIB_IC_Buffer16BitGet(MY_IC_ID); 5.6.10.5.3.2 PLIB_IC_Buffer32BitGet Function C uint32_t PLIB_IC_Buffer32BitGet( IC_MODULE_ID index ); Description This function reads the 32-bit value of the IC buffer to obtain the captured timer value. This function is used when the buffer size is set to 32-bits. Preconditions The buffer size should be set to 32 bits (i.e., PLIB_IC_BufferSizeSet(MY_IC_ID, IC_BUFFER_SIZE_32BIT). Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferValue in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 uint32_t bufferVal; // Read input capture buffer value and store it in 'bufferVal' bufferVal = PLIB_IC_Buffer32BitGet(MY_IC_ID); 5.6.10.5.3.3 PLIB_IC_BufferIsEmpty Function C bool PLIB_IC_BufferIsEmpty( IC_MODULE_ID index ); Description This function returns 'true' if the input capture buffer is empty and 'false' if the buffer is not empty. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2184 Parameters Parameters Description index Identifies the desired IC module Returns bool - true - The input capture buffer is empty • false - The input capture buffer is not empty Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferIsEmptyStatus in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 if(!PLIB_IC_BufferIsEmpty(MY_IC_ID)) { // Do some operation }; 5.6.10.5.3.4 PLIB_IC_BufferOverflowHasOccurred Function C bool PLIB_IC_BufferOverflowHasOccurred( IC_MODULE_ID index ); Description This function returns 'true' if an input capture buffer has overflowed and 'false' if the buffer has not overflowed. Preconditions This function only applies when not in Edge Detect mode. Parameters Parameters Description index Identifies the desired IC module Returns bool - true - An overflow of the input capture buffer has occurred • false - An overflow of the input capture buffer has not occurred Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferOverflowStatus in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 if(!PLIB_IC_BufferOverflowHasOccurred(MY_IC_ID)) { // Do some operation }; 5.6.10.5.3.5 PLIB_IC_BufferSizeSelect Function C void PLIB_IC_BufferSizeSelect( 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2185 IC_MODULE_ID index, IC_BUFFER_SIZE bufSize ); Description This function sets the input capture buffer size for IC module. The buffer size can be set to 16 bits or 32 bits. The buffer size should be consistent with the timer selected. A 32-bit timer requires a 32-bit buffer and a 16-bit timer requires a 16-bit buffer. Preconditions The buffer size should be consistent with the timer selected. Parameters Parameters Description index Identifies the desired IC module bufSize Sets the buffer size to 16 bits or 32 bits Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsBufferSize in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // 32-bit timer resource is selected PLIB_IC_BufferSizeSelect(MY_IC_ID, IC_BUFFER_SIZE_32BIT); 5.6.10.5.4 Operation Modes Functions 5.6.10.5.4.1 PLIB_IC_ModeSelect Function C void PLIB_IC_ModeSelect( IC_MODULE_ID index, IC_INPUT_CAPTURE_MODES modeSel ); Description This function selects the input capture mode for the IC module. Preconditions None. Parameters Parameters Description index Identifies the desired IC module modeSel Identifies the timer type required Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2186 PLIB_IC_ExistsCaptureMode in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 // Every Edge Mode is selected PLIB_IC_ModeSelect(MY_IC_ID, IC_INPUT_CAPTURE_EVERY_EDGE_MODE); 5.6.10.5.5 Power-Saving Modes Functions 5.6.10.5.5.1 PLIB_IC_StopInIdleDisable Function C void PLIB_IC_StopInIdleDisable( IC_MODULE_ID index ); Description The function continues operation of the IC module when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired IC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 PLIB_IC_StopInIdleDisable(MY_IC_ID); 5.6.10.5.5.2 PLIB_IC_StopInIdleEnable Function C void PLIB_IC_StopInIdleEnable( IC_MODULE_ID index ); Description This function discontinues IC module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired IC module 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2187 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_IC_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_IC_ID IC_ID_1 PLIB_IC_StopInIdleEnable(MY_IC_ID); 5.6.10.5.6 Data Types and Constants 5.6.10.5.6.1 IC_BUFFER_SIZE Enumeration C typedef enum { IC_BUFFER_SIZE_32BIT, IC_BUFFER_SIZE_16BIT } IC_BUFFER_SIZE; Description IC Buffer Size The IC buffer can be set to 16 bits or 32 bits. The buffer size is set by the PLIB_IC_BufferSizeSelect() function. Members Members Description IC_BUFFER_SIZE_32BIT 32-bit timer source select IC_BUFFER_SIZE_16BIT 16-bit timer source select 5.6.10.5.6.2 IC_CLOCK_SOURCES Enumeration C typedef enum { IC_CLOCK_SOURCE_TIMER1, IC_CLOCK_SOURCE_TIMER2, IC_CLOCK_SOURCE_TIMER3, IC_CLOCK_SOURCE_TIMER4, IC_CLOCK_SOURCE_TIMER5, IC_CLOCK_SOURCE_SYSTEM } IC_CLOCK_SOURCES; Description IC Clock Sources Select This enumeration lists all of the input capture modes for IC module. The capture mode is set via the PLIB_IC_ClockSourceSelect() function. Members Members Description IC_CLOCK_SOURCE_TIMER1 Clock source of Timer1 is the clock source of the capture counter IC_CLOCK_SOURCE_TIMER2 Clock source of Timer2 is the clock source of the capture counter 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2188 IC_CLOCK_SOURCE_TIMER3 Clock source of Timer3 is the clock source of the capture counter IC_CLOCK_SOURCE_TIMER4 Clock source of Timer4 is the clock source of the capture counter IC_CLOCK_SOURCE_TIMER5 Clock source of Timer5 is the clock source of the capture counter IC_CLOCK_SOURCE_SYSTEM System Clock is the clock source of the capture counter 5.6.10.5.6.3 IC_EDGE_TYPES Enumeration C typedef enum { IC_EDGE_FALLING, IC_EDGE_RISING } IC_EDGE_TYPES; Description IC Edge Types Select This enumeration lists the options to select a rising edge input capture or a falling edge input capture. The selection is made by the PLIB_IC_FirstCaptureEdgeSelect() function. Members Members Description IC_EDGE_FALLING Select Falling Edge IC_EDGE_RISING Select Rising Edge 5.6.10.5.6.4 IC_EVENTS_PER_INTERRUPT Enumeration C typedef enum { IC_INTERRUPT_ON_EVERY_4TH_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_3RD_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_2ND_CAPTURE_EVENT, IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT } IC_EVENTS_PER_INTERRUPT; Description IC Capture Events Per Interrupt Select This enumeration lists the number of events that should occur before an interrupt is generated. An interrupt can occur on every capture event, every second, every third, or every fourth capture event. Members Members Description IC_INTERRUPT_ON_EVERY_4TH_CAPTURE_EVENT Interrupt on every 4th capture event IC_INTERRUPT_ON_EVERY_3RD_CAPTURE_EVENT Interrupt on every 3rd capture event IC_INTERRUPT_ON_EVERY_2ND_CAPTURE_EVENT Interrupt on every 2nd capture event IC_INTERRUPT_ON_EVERY_CAPTURE_EVENT Interrupt on every capture event 5.6.10.5.6.5 IC_INPUT_CAPTURE_MODES Enumeration C typedef enum { IC_INPUT_CAPTURE_INTERRUPT_MODE, IC_INPUT_CAPTURE_EVERY_EDGE_MODE, IC_INPUT_CAPTURE_EVERY_16TH_EDGE_MODE, IC_INPUT_CAPTURE_EVERY_4TH_EDGE_MODE, 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2189 IC_INPUT_CAPTURE_RISING_EDGE_MODE, IC_INPUT_CAPTURE_FALLING_EDGE_MODE, IC_INPUT_CAPTURE_EDGE_DETECT_MODE, IC_INPUT_CAPTURE_DISABLE_MODE } IC_INPUT_CAPTURE_MODES; Description IC Input Capture Mode Select This enumeration lists all of the input capture modes for IC module. The capture mode is set via the PLIB_IC_ModeSelect() function. Members Members Description IC_INPUT_CAPTURE_INTERRUPT_MODE Interrupt only mode: Rising edge on input triggers an interrupt. This mode is used only when device is in Sleep/Idle mode IC_INPUT_CAPTURE_EVERY_EDGE_MODE Every Edge Capture mode: The first edge of the input signal is specified via PLIB_IC_RisingEdgeCaptureSet() or PLIB_IC_FallingEdgeCaptureSet() routines. Subsequently, timer count value is captured on every rising and falling of the input signal IC_INPUT_CAPTURE_EVERY_16TH_EDGE_MODE Prescaled Capture mode: Timer count value is captured every 16th rising edge of input signal IC_INPUT_CAPTURE_EVERY_4TH_EDGE_MODE Prescaled Capture mode: Timer count value is captured every 4th rising edge of input signal IC_INPUT_CAPTURE_RISING_EDGE_MODE Rising Edge mode: Timer count value is captured on every rising edge of input signal IC_INPUT_CAPTURE_FALLING_EDGE_MODE Falling Edge mode: Timer count value is captured on every falling edge of input signal IC_INPUT_CAPTURE_EDGE_DETECT_MODE Edge Detect mode: Timer count value is captured on every rising and falling of the input signal Interrupt control bits are ignored and an interrupt event is generated for every capture. Overflow status is not updated. IC_INPUT_CAPTURE_DISABLE_MODE Capture module is disabled.Input signal is ignored and no capture events or interrupts are generated 5.6.10.5.6.6 IC_MODULE_ID Enumeration C typedef enum { IC_ID_1, IC_ID_2, IC_ID_3, IC_ID_4, IC_ID_5, IC_ID_6, IC_ID_7, IC_ID_8, IC_ID_9, IC_NUMBER_OF_MODULES } IC_MODULE_ID; Description IC_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on a Microchip microcontroller. Refer to the specific device data sheet to determine the correct number of modules defined for the device. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2190 Members Members Description IC_NUMBER_OF_MODULES The total number of modules available. 5.6.10.5.6.7 IC_SYNC_MODE_INPUTS Enumeration C typedef enum { IC_SYNC_MODE_INPUT_OC1, IC_SYNC_MODE_INPUT_OC2, IC_SYNC_MODE_INPUT_OC3, IC_SYNC_MODE_INPUT_OC4, IC_SYNC_MODE_INPUT_OC5, IC_SYNC_MODE_INPUT_OC6, IC_SYNC_MODE_INPUT_OC7, IC_SYNC_MODE_INPUT_OC8, IC_SYNC_MODE_INPUT_OC9, IC_SYNC_MODE_INPUT_ICAP1, IC_SYNC_MODE_INPUT_ICAP2, IC_SYNC_MODE_INPUT_ICAP3, IC_SYNC_MODE_INPUT_ICAP4, IC_SYNC_MODE_INPUT_ICAP5, IC_SYNC_MODE_INPUT_ICAP6, IC_SYNC_MODE_INPUT_ICAP7, IC_SYNC_MODE_INPUT_ICAP8, IC_SYNC_MODE_INPUT_ICAP9, IC_SYNC_MODE_INPUT_TMR1, IC_SYNC_MODE_INPUT_TMR2, IC_SYNC_MODE_INPUT_TMR3, IC_SYNC_MODE_INPUT_TMR4, IC_SYNC_MODE_INPUT_TMR5, IC_SYNC_MODE_INPUT_PTG, IC_SYNC_MODE_INPUT_CMP1, IC_SYNC_MODE_INPUT_CMP2, IC_SYNC_MODE_INPUT_CMP3, IC_SYNC_MODE_INPUT_AD, IC_SYNC_MODE_INPUT_CTMU, IC_SYNC_MODE_INPUT_NONE } IC_SYNC_MODE_INPUTS; Description IC Synchronization and Trigger input select This enumeration lists all of the input sources for synchronous and asynchronous operation of IC module. The Input source can be selected by the PLIB_IC_SyncModeInputSelect() function. Members Members Description IC_SYNC_MODE_INPUT_OC1 Synchronization and trigger input is Output Compare1 IC_SYNC_MODE_INPUT_OC2 Synchronization and trigger input is Output Compare2 IC_SYNC_MODE_INPUT_OC3 Synchronization and trigger input is Output Compare3 IC_SYNC_MODE_INPUT_OC4 Synchronization and trigger input is Output Compare4 IC_SYNC_MODE_INPUT_OC5 Synchronization and trigger input is Output Compare5 IC_SYNC_MODE_INPUT_OC6 Synchronization and trigger input is Output Compare6 IC_SYNC_MODE_INPUT_OC7 Synchronization and trigger input is Output Compare7 IC_SYNC_MODE_INPUT_OC8 Synchronization and trigger input is Output Compare8 IC_SYNC_MODE_INPUT_OC9 Synchronization and trigger input is Output Compare9 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2191 IC_SYNC_MODE_INPUT_ICAP1 Synchronization and trigger input is Input Capture1 IC_SYNC_MODE_INPUT_ICAP2 Synchronization and trigger input is Input Capture2 IC_SYNC_MODE_INPUT_ICAP3 Synchronization and trigger input is Input Capture3 IC_SYNC_MODE_INPUT_ICAP4 Synchronization and trigger input is Input Capture4 IC_SYNC_MODE_INPUT_ICAP5 Synchronization and trigger input is Input Capture5 IC_SYNC_MODE_INPUT_ICAP6 Synchronization and trigger input is Input Capture6 IC_SYNC_MODE_INPUT_ICAP7 Synchronization and trigger input is Input Capture7 IC_SYNC_MODE_INPUT_ICAP8 Synchronization and trigger input is Input Capture8 IC_SYNC_MODE_INPUT_ICAP9 Synchronization and trigger input is Input Capture9 IC_SYNC_MODE_INPUT_TMR1 Synchronization and trigger input is Timer1 IC_SYNC_MODE_INPUT_TMR2 Synchronization and trigger input is Timer2 IC_SYNC_MODE_INPUT_TMR3 Synchronization and trigger input is Timer3 IC_SYNC_MODE_INPUT_TMR4 Synchronization and trigger input is Timer4 IC_SYNC_MODE_INPUT_TMR5 Synchronization and trigger input is Timer5 IC_SYNC_MODE_INPUT_PTG Synchronization and trigger input is Peripheral Trigger Generator Module IC_SYNC_MODE_INPUT_CMP1 Trigger input is Comparator1. This input is not used for Synchronization IC_SYNC_MODE_INPUT_CMP2 Trigger input is Comparator2. This input is not used for Synchronization IC_SYNC_MODE_INPUT_CMP3 Trigger input is Comparator3. This input is not used for Synchronization IC_SYNC_MODE_INPUT_AD Trigger input is ADC. This input is not used for Synchronization IC_SYNC_MODE_INPUT_CTMU Trigger input is Charge Time Measurement Unit. This input is not used for Synchronization IC_SYNC_MODE_INPUT_NONE No synchronization and trigger input 5.6.10.5.6.8 IC_SYNC_MODES Enumeration C typedef enum { IC_MODE_ASYNC, IC_MODE_SYNC } IC_SYNC_MODES; Description IC Synchronization Mode Select This enumeration lists the synchronization modes for the IC module. The IC module timer can function in synchronism with the input source or triggered asynchronously by an input trigger. Members Members Description IC_MODE_ASYNC Input source acts as an asynchronous trigger to start Input Capture timer. The Input source can be selected by PLIB_IC_SyncModeInputSelect() routine IC_MODE_SYNC Input source synchronizes Input Capture timer to other modules. The Input source can be selected by PLIB_IC_SyncModeInputSelect() routine 5.6.10.5.6.9 IC_TIMERS Enumeration C typedef enum { IC_TIMER_TMR3, IC_TIMER_TMR2 } IC_TIMERS; 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2192 Description IC 16-bit Timer Select This enumeration lists the different 16-bit timers for the IC timebase when the IC module is configured with a 16-bit timer resource. Members Members Description IC_TIMER_TMR3 Timer3 select IC_TIMER_TMR2 Timer2 select 5.6.10.5.7 Feature Existence Functions 5.6.10.5.7.1 PLIB_IC_ExistsAlternateClock Function C bool PLIB_IC_ExistsAlternateClock( IC_MODULE_ID index ); Description This function identifies whether the AlternateClock feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_AlternateClockEnable • PLIB_IC_AlternateClockDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlternateClock feature is supported on the device • false - The AlternateClock feature is not supported on the device Remarks None. 5.6.10.5.7.2 PLIB_IC_ExistsBufferIsEmptyStatus Function C bool PLIB_IC_ExistsBufferIsEmptyStatus( IC_MODULE_ID index ); Description This function identifies whether the BufferIsEmptyStatus feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferIsEmpty 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2193 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferIsEmptyStatus feature is supported on the device • false - The BufferIsEmptyStatus feature is not supported on the device Remarks None. 5.6.10.5.7.3 PLIB_IC_ExistsBufferOverflowStatus Function C bool PLIB_IC_ExistsBufferOverflowStatus( IC_MODULE_ID index ); Description This function identifies whether the BufferOverflowStatus feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferOverflowHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferOverflowStatus feature is supported on the device • false - The BufferOverflowStatus feature is not supported on the device Remarks None. 5.6.10.5.7.4 PLIB_IC_ExistsBufferSize Function C bool PLIB_IC_ExistsBufferSize( IC_MODULE_ID index ); Description This function identifies whether the BufferSize feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_BufferSizeSelect 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2194 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferSize feature is supported on the device • false - The BufferSize feature is not supported on the device Remarks None. 5.6.10.5.7.5 PLIB_IC_ExistsBufferValue Function C bool PLIB_IC_ExistsBufferValue( IC_MODULE_ID index ); Description This function identifies whether the BufferValue feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_Buffer32BitGet • PLIB_IC_Buffer16BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferValue feature is supported on the device • false - The BufferValue feature is not supported on the device Remarks None. 5.6.10.5.7.6 PLIB_IC_ExistsCaptureMode Function C bool PLIB_IC_ExistsCaptureMode( IC_MODULE_ID index ); Description This function identifies whether the CaptureMode feature is available on the IC module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2195 • PLIB_IC_ModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CaptureMode feature is supported on the device • false - The CaptureMode feature is not supported on the device Remarks None. 5.6.10.5.7.7 PLIB_IC_ExistsClockSource Function C bool PLIB_IC_ExistsClockSource( IC_MODULE_ID index ); Description This function identifies whether the ClockSource feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_ClockSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ClockSource feature is supported on the device • false - If the ClockSource feature is not supported on the device Remarks None. 5.6.10.5.7.8 PLIB_IC_ExistsEdgeCapture Function C bool PLIB_IC_ExistsEdgeCapture( IC_MODULE_ID index ); Description This function identifies whether the EdgeCapture feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_FirstCaptureEdgeSelect 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2196 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EdgeCapture feature is supported on the device • false - The EdgeCapture feature is not supported on the device Remarks None. 5.6.10.5.7.9 PLIB_IC_ExistsEnable Function C bool PLIB_IC_ExistsEnable( IC_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_Enable • PLIB_IC_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.10.5.7.10 PLIB_IC_ExistsEventsPerInterruptSelect Function C bool PLIB_IC_ExistsEventsPerInterruptSelect( IC_MODULE_ID index ); Description This function identifies whether the EventsPerInterruptSelect feature is available on the IC module. When this function returns true, this function is are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2197 • PLIB_IC_EventsPerInterruptSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EventsPerInterruptSelect feature is supported on the device • false - The EventsPerInterruptSelect feature is not supported on the device Remarks None. 5.6.10.5.7.11 PLIB_IC_ExistsStopInIdle Function C bool PLIB_IC_ExistsStopInIdle( IC_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the IC module. When this function returns true, these functions are supported on the device: • PLIB_IC_StopInIdleEnable • PLIB_IC_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.10.5.7.12 PLIB_IC_ExistsSyncMode Function C bool PLIB_IC_ExistsSyncMode( IC_MODULE_ID index ); Description This function identifies whether the SyncMode feature is available on the IC module. When this function returns true, tthis function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2198 • PLIB_IC_SyncModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SyncMode feature is supported on the device • false - If the SyncMode feature is not supported on the device Remarks None. 5.6.10.5.7.13 PLIB_IC_ExistsSyncModeInput Function C bool PLIB_IC_ExistsSyncModeInput( IC_MODULE_ID index ); Description This function identifies whether the SyncModeInput feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_SyncModeInputSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SyncModeInput feature is supported on the device • false - If the SyncModeInput feature is not supported on the device Remarks None. 5.6.10.5.7.14 PLIB_IC_ExistsTimerSelect Function C bool PLIB_IC_ExistsTimerSelect( IC_MODULE_ID index ); Description This function identifies whether the TimerSelect feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_TimerSelect 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2199 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TimerSelect feature is supported on the device • false - The TimerSelect feature is not supported on the device Remarks None. 5.6.10.5.7.15 PLIB_IC_ExistsTimerTriggered Function C bool PLIB_IC_ExistsTimerTriggered( IC_MODULE_ID index ); Description This function identifies whether the TimerTriggered feature is available on the IC module. When this function returns true, this function is supported on the device: • PLIB_IC_TimerIsTriggered Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TimerTriggered feature is supported on the device • false - If the TimerTriggered feature is not supported on the device Remarks None. 5.6.10.6 Files Files Name Description plib_ic.h This file contains the interface definition for the Input Capture (IC) peripheral library. Description 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2200 5.6.10.6.1 plib_ic.h IC Module Peripheral Library Interface Header This library provides a low-level abstraction of the Input Capture (IC) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. Functions Name Description PLIB_IC_AlternateClockDisable Selects Timer 2/3.instead of the alternate clock source. PLIB_IC_AlternateClockEnable Selects the alternate clock source. PLIB_IC_Buffer16BitGet Obtains the 16-bit input capture buffer value. PLIB_IC_Buffer32BitGet Obtains the 32-bit input capture buffer value. PLIB_IC_BufferIsEmpty Checks whether the input capture buffer is empty. PLIB_IC_BufferOverflowHasOccurred Checks whether an input capture buffer overflow has occurred. PLIB_IC_BufferSizeSelect Sets the input capture buffer size. PLIB_IC_ClockSourceSelect Selects the clock source for the IC module. PLIB_IC_Disable Disables the IC module. PLIB_IC_Enable Enables the IC module. PLIB_IC_EventsPerInterruptSelect Selects the number of capture events before an interrupt is issued. PLIB_IC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the IC module PLIB_IC_ExistsBufferIsEmptyStatus Identifies whether the BufferIsEmptyStatus feature exists on the IC module PLIB_IC_ExistsBufferOverflowStatus Identifies whether the BufferOverflowStatus feature exists on the IC module. PLIB_IC_ExistsBufferSize Identifies whether the BufferSize feature exists on the IC module. PLIB_IC_ExistsBufferValue Identifies whether the BufferValue feature exists on the IC module. PLIB_IC_ExistsCaptureMode Identifies whether the CaptureMode feature exists on the IC module. PLIB_IC_ExistsClockSource Identifies whether the ClockSource feature exists on the IC module. PLIB_IC_ExistsEdgeCapture Identifies whether the EdgeCapture feature exists on the IC module. PLIB_IC_ExistsEnable Identifies whether the EnableControl feature exists on the IC module PLIB_IC_ExistsEventsPerInterruptSelect Identifies whether the EventsPerInterruptSelect feature exists on the IC module. PLIB_IC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the IC module. PLIB_IC_ExistsSyncMode Identifies whether the SyncMode feature exists on the IC module. PLIB_IC_ExistsSyncModeInput Identifies whether the SyncModeInput feature exists on the IC module. PLIB_IC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the IC module. PLIB_IC_ExistsTimerTriggered Identifies whether the TimerTriggered feature exists on the IC module. PLIB_IC_FirstCaptureEdgeSelect Captures the timer count value at the first selected edge of input signal. PLIB_IC_ModeSelect Selects the input capture mode for IC module. PLIB_IC_StopInIdleDisable Continues module operation when the device enters Idle mode PLIB_IC_StopInIdleEnable Discontinues IC module operation when the device enters Idle mode. PLIB_IC_SyncModeInputSelect Selects the input source for synchronous or asynchronous (triggered) operation of the IC module. PLIB_IC_SyncModeSelect Selects the synchronization mode for Input Capture module. PLIB_IC_TimerIsTriggered Checks whether or not the input capture timer has been triggered. 5.6 Peripheral Library Help MPLAB Harmony Help Input Capture Peripheral Library 5-2201 PLIB_IC_TimerSelect Selects the 16-bit timer source for the IC module. File Name plib_ic.h Company Microchip Technology Inc. 5.6.11 Interrupt Peripheral Library 5.6.11.1 Introduction Interrupt Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Interrupt Controller module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description Interrupt Controller Overview The Interrupt Controller is a key component of a microcontroller. The Interrupt Controller reduces the numerous peripheral interrupt request signals to a single interrupt request signal to the microcontroller core. The key features present on an Interrupt Controller are: • Interrupt source configuration: Provides the ability to enable, disable, and prioritize a source that may interrupt the core • Interrupt status flags: Identify the source of an interrupt request or exception, usually generated by a peripheral The interrupt will be sent to the core, only if the source is enabled to generate an interrupt and interrupts have been enabled (if supported). Sources will be prioritized so that the highest priority interrupt will be sent to the core if multiple sources cause interrupts at the same time. Many interrupt controllers also include, other optional features: • Global enable configuration: Controls the generation of any interrupt to the core from the Interrupt Controller • Choice of edge transition: Controls the edge transition (high-to-low or low-to-high) on which the interrupts are generated • Priority configuration: Associates a programmable priority with the interrupt source Interrupts can be handled inside the core in the following ways: • Vectored: Each interrupt has an associated interrupt handler routine • Non-vectored: All interrupts have a single (shared) interrupt handler routine. The software determines the interrupt source based on the interrupt status-flags register. • Combination of vectored and non-vectored: Interrupts combined in groups. Each group has a single common interrupt vector or handler, but there are multiple groups (i.e., multiple vectors). Within a specific vector group, software determines which one in the group sources caused the interrupt. A microcontroller can support one, or more than one of the these modes. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2202 Note: Please refer to the the specific device data sheet to determine availability of these features for your device. 5.6.11.2 Release Notes MPLAB Harmony Version: v0.70b Interrupt Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.11.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.11.4 Using the Library This topic describes the basic architecture of the Interrupt Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_int.h The interface to the Interrupt Peripheral Library is defined in the "plib_int.h" header file. Any C language source (.c) file that uses the Interrupt Peripheral Library should include "plib_int.h". Library File: The Interrupt Peripheral Library (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the peripheral interacts with the framework. 5.6.11.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Interrupt Controller module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2203 Description Hardware Abstraction Model The Interrupt Controller receives requests from multiple Interrupt Sources. The Interrupt Controller Configuration controls the overall operation of the interrupt controller. Not all microcontrollers support all the features listed below: • Interrupt nesting configuration • Edge selection of the external interrupts • Vector mode selection • Priority level configuration • Current CPU interrupt and priority status information Source Enable Configuration enables or disables a particular source. On some microcontrollers other CPU exceptions or traps can also be controlled. Source Status Flags give the status of the interrupt request from a specific interrupt source. Other optional features include the Vector Priority Configuration, which is available on some micro controllers and the Proximity Timer. Priority configuration allows a priority level to be associated with each interrupt vector. The proximity timer creates a temporal window in which a group of interrupts of the same, or lower, priority will be held off. This provides an opportunity to queue these interrupt requests and process them using tail-chaining of multiple IRQs and allows higher priority interrupts to pass through during the hold-off window. Traps and Exceptions Some of the things that can interrupt the normal flow of instruction execution of the CPU core are not actual interrupt sources. These are things such as a division-by-zero error or attempting to address unimplemented memory. These errors are either internal to the CPU core itself or are so catastrophic that they are non-maskable and are trapped separately. This library refers to them in general as "traps" and there are interface elements provided to allow software to handle them. 5.6.11.4.2 Library Usage Model This section provides library usage model information. Description The following diagram shows the major components of the usage model. Usage Model Each of the blocks in the diagram correspond to the library interface section. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2204 Library Interface Section Description General Configuration Functions Provides setup, configuration, and status interface routines for the overall operation of the Interrupt Controller module. 5.6.11.4.3 How the Library Works This section provides information on initialization and interrupt source setup and handling. Description Initialization The steps that are required to initialize the Interrupt Controller module vary for different microcontrollers. Note: Refer to the specific device data sheet for the correct initialization sequence for your device. Interrupt Source Setup An interrupt Source needs to be enabled in order for it to be able to generate a interrupt to the core. Use the function PLIB_INT_SourceEnable to enable the interrupt source. INT_SOURCE is a list of the possible interrupt sources On some microcontrollers, each interrupt vector can be associated with a priority. Use the function PLIB_INT_VectorPrioritySet to set the interrupt vector priority. INT_VECTOR is a list of the possible interrupt vectors and INT_PRIORITY_LEVEL is the list of possible priority levels. On some microcontrollers, each interrupt vector can be associated with a sub-priority. Use the function PLIB_INT_VectorSubPrioritySet to set the interrupt source sub-priority. INT_SUBPRIORITY_LEVEL is a list of possible sub-priority levels. On most microcontrollers, it will be necessary to enable interrupt generation to the core by calling the PLIB_INT_Enable function. Interrupt Handling The status of the interrupt indicates whether or not the interrupt request was generated by the source. The status of the trap source can be obtained using the function PLIB_INT_TrapSourceFlagGet and the status of the interrupt source can be obtained using the function PLIB_INT_SourceFlagGet. The interrupt status flags can be used to indicate the interrupt status even if the interrupt is not enabled for the source. When the interrupt is not enabled for the source, no interrupt is generated to the core even though the interrupt controller still recognizes that the source requested an interrupt. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. Before the Interrupt Service Routine (ISR) ends, the status of the interrupt needs to be cleared to avoid entering the ISR repeatedly for the same interrupt event. A trap source status can be cleared using the function PLIB_INT_TrapSourceFlagClear, and an interrupt source status can be cleared using the function PLIB_INT_SourceFlagClear. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. 5.6.11.5 Configuring the Library The library is configured for the supported Interrupt Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2205 5.6.11.6 Library Interface Data Types and Constants Name Description INT_EXTERNAL_SOURCES Lists the possible external sources that can cause an interrupt to occur. INT_PRIORITY_LEVEL Lists the possible interrupt priority levels INT_SOURCE Lists the possible sources that can cause an interrupt to occur INT_SUBPRIORITY_LEVEL Lists the possible interrupt sub priority levels INT_TRAP_SOURCE Lists the names of the trap or exception sources INT_VECTOR Lists the possible interrupt vectors. Feature Existence Functions Name Description PLIB_INT_ExistsAlternateVectorTable Identifies whether the AlternateVectorTable feature exists on the Interrupt Controller module. PLIB_INT_ExistsCPUCurrentPriorityLevel Identifies whether the CPUCurrentPriorityLevel feature exists on the Interrupt Controller module. PLIB_INT_ExistsEnableControl Identifies whether the EnableControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsExternalINTEdgeSelect Identifies whether the ExternalINTEdgeSelect feature exists on the Interrupt Controller module. PLIB_INT_ExistsHighPriority Identifies whether the HighPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTCPUPriority Identifies whether the INTCPUPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTCPUVector Identifies whether the INTCPUVector feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTNesting Identifies whether the INTNesting feature exists on the Interrupt Controller module. PLIB_INT_ExistsLowPriority Identifies whether the LowPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsPeripheralControl Identifies whether the PeripheralControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsPriority Identifies whether the Priority feature exists on the Interrupt Controller module. PLIB_INT_ExistsProximityTimerControl Identifies whether the ProximityTimerControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsProximityTimerEnable Identifies whether the ProximityTimerEnable feature exists on the Interrupt Controller module. PLIB_INT_ExistsSingleVectorShadowSet Identifies whether the SingleVectorShadowSet feature exists on the Interrupt Controller module. PLIB_INT_ExistsSourceControl Identifies whether the SourceControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsSourceFlag Identifies whether the SourceFlag feature exists on the Interrupt Controller module. PLIB_INT_ExistsTrapSource Identifies whether the TrapSource feature exists on the Interrupt Controller module. PLIB_INT_ExistsVectorPriority Identifies whether the VectorPriority feature exists on the Interrupt Controller module. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2206 PLIB_INT_ExistsVectorSelect Identifies whether the VectorSelect feature exists on the Interrupt Controller module. General Configuration Functions Name Description PLIB_INT_AlternateVectorTableSelect Enables the use of the alternate vector table. PLIB_INT_Disable Disables the generation of interrupts to the CPU. PLIB_INT_DISIStatusGet Returns the status of the DISI instruction status. PLIB_INT_Enable Enables the generation of interrupts to the CPU. PLIB_INT_ExternalFallingEdgeSelect Selects the falling edge as the edge polarity of the external interrupt. PLIB_INT_ExternalRisingEdgeSelect Selects the rising edge as the edge polarity of the external interrupt. PLIB_INT_IsEnabled Identifies if interrupts are currently enabled or disabled at the top level. PLIB_INT_MultiVectorSelect Configures the Interrupt Controller for Multiple Vector mode. PLIB_INT_NestingDisable Disables interrupt nesting. PLIB_INT_NestingEnable Enables interrupt nesting. PLIB_INT_PeripheralsDisable Disables the generation of interrupts to the CPU by the peripherals. PLIB_INT_PeripheralsEnable Enables the generation of interrupts to the CPU by the peripherals. PLIB_INT_PriorityDisable Disables interrupt priority levels. PLIB_INT_PriorityEnable Enables interrupt priority levels. PLIB_INT_PriorityGet Returns the priority level of the latest interrupt presented to the CPU. PLIB_INT_PriorityHighDisable Disables the generation of high-priority interrupts to the CPU. PLIB_INT_PriorityHighEnable Enables the generation of high-priority interrupts to the CPU. PLIB_INT_PriorityLowDisable Disables the generation of low-priority interrupts to the CPU. PLIB_INT_PriorityLowEnable Enables generation of low-priority interrupts to the CPU. PLIB_INT_ProximityTimerDisable Disables the interrupt temporal-proximity timer. PLIB_INT_ProximityTimerEnable Enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. PLIB_INT_SingleVectorSelect Configures the Interrupt Controller for Single Vector mode. PLIB_INT_SingleVectorShadowSetDisable Disables the Shadow Register Set in Single Vector mode. PLIB_INT_SingleVectorShadowSetEnable Enables the Shadow Register Set in Single Vector mode. PLIB_INT_StandardVectorTableSelect Enables the use of the standard vector table. Interrupt Source Control Functions Name Description PLIB_INT_SourceDisable Disables the interrupt source PLIB_INT_SourceEnable Enables the interrupt source. This section provides information on initialization and interrupt source setup and handling. PLIB_INT_SourceFlagClear Clears the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagGet Returns the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagSet Sets the status of the interrupt flag for the selected source. PLIB_INT_SourceIsEnabled Gets the enable state of the interrupt source. PLIB_INT_VectorPriorityGet Gets the priority of the interrupt vector. PLIB_INT_VectorPrioritySet Sets the priority of the interrupt vector. PLIB_INT_VectorSubPriorityGet Gets the sub-priority of the interrupt vector. PLIB_INT_VectorSubPrioritySet Sets the sub-priority of the interrupt vector. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2207 Other Status and Control Functions Name Description PLIB_INT_CPUCurrentPriorityLevelGet Gets the interrupt priority level at which the CPU is currently operating. PLIB_INT_ProximityTimerGet Returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. PLIB_INT_ProximityTimerSet Sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. PLIB_INT_TrapSourceFlagClear Clears the flag for the selected trap. PLIB_INT_TrapSourceFlagGet Returns the status of the flag for the selected trap. PLIB_INT_VectorGet Returns the interrupt vector that is presented to the CPU. Description This section provides descriptions and examples for the functions provided in the Interrupt Peripheral Library. 5.6.11.6.1 General Configuration Functions 5.6.11.6.1.1 PLIB_INT_AlternateVectorTableSelect Function C void PLIB_INT_AlternateVectorTableSelect( INT_MODULE_ID index ); Description This function enables the processor to use the alternate vector table instead of the default vector table. If the alternate vector table is enabled using this function, all interrupt and exception processing uses the alternate vectors instead of the default vectors. The alternate vectors are organized in the same manner as the default vectors. Alternate vectors support emulation and debugging by providing a means to switch between an application and support environment, without requiring the interrupt vectors to be reprogrammed. This feature can also be used to enable switching between different software algorithms during run time for evaluation. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the AlternateVectorTable feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsAlternateVectorTable API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_AlternateVectorTableSelect( INT_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2208 5.6.11.6.1.2 PLIB_INT_Disable Function C void PLIB_INT_Disable( INT_MODULE_ID index ); Description This function disables the generation of interrupts to the CPU. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsEnableControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_Disable( INT_ID_0 ); 5.6.11.6.1.3 PLIB_INT_DISIStatusGet Function C bool PLIB_INT_DISIStatusGet( INT_MODULE_ID index ); Description This function returns the status of the DISI instruction status. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns • true - If DISI is active • false - If DISI is not active Remarks This function implements an operation of the DISI feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsDISI API to write flexible code to automatically 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2209 determine if this feature is available. Example PLIB_INT_DISIStatusGet( INT_ID_0 ); 5.6.11.6.1.4 PLIB_INT_Enable Function C void PLIB_INT_Enable( INT_MODULE_ID index ); Description This function enables the generation of interrupts to the CPU. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsEnableControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_Enable( INT_ID_0 ); 5.6.11.6.1.5 PLIB_INT_ExternalFallingEdgeSelect Function C void PLIB_INT_ExternalFallingEdgeSelect( INT_MODULE_ID index, INT_EXTERNAL_SOURCES source ); Description This function selects the falling edge as the edge polarity of the external interrupt. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One or more of the values from INT_EXTERNAL_SOURCES. Values can be combined using a bitwise "OR" operation. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2210 Returns None. Remarks This function implements an operation of the ExternalINTEdgeSelect feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsExternalINTEdgeSelect API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_ExternalFallingEdgeSelect( INT_ID_0, (INT_EXTERNAL_INT_SOURCE0 | INT_EXTERNAL_INT_SOURCE1) ); 5.6.11.6.1.6 PLIB_INT_ExternalRisingEdgeSelect Function C void PLIB_INT_ExternalRisingEdgeSelect( INT_MODULE_ID index, INT_EXTERNAL_SOURCES source ); Description This function selects the rising edge as the edge polarity of the external interrupt. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One or more of the values from INT_EXTERNAL_SOURCES. Values can be combined using a bitwise "OR" operation. Returns None. Remarks This function implements an operation of the ExternalINTEdgeSelect feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsExternalINTEdgeSelect API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_ExternalRisingEdgeSelect( INT_ID_0, ( INT_EXTERNAL_INT_SOURCE0 | INT_EXTERNAL_INT_SOURCE1 ) ); 5.6.11.6.1.7 PLIB_INT_IsEnabled Function C bool PLIB_INT_IsEnabled( INT_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2211 Description This function identifies if interrupts are enabled or disabled at the top level. Preconditions None. Returns • true - If the interrupts are currently enabled • false - If the interrupts are currently disabled Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsEnableControl API to write flexible code to automatically determine if this feature is available. Example status = PLIB_INT_IsEnabled( INT_ID_0 ); 5.6.11.6.1.8 PLIB_INT_MultiVectorSelect Function C void PLIB_INT_MultiVectorSelect( INT_MODULE_ID index ); Description This function configures the Interrupt Controller for Multiple Vector mode. Interrupt requests will serviced at the calculated vector addresses. The CPU vectors to the unique address for each vector number. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks While the user can, during run-time, reconfigure the interrupt controller from Single Vector mode to Multiple Vector mode, such action is strongly discouraged, as it may result in undefined behavior. This function implements an operation of the VectorSelect feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorSelect API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_MultiVectorSelect( INT_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2212 5.6.11.6.1.9 PLIB_INT_NestingDisable Function C void PLIB_INT_NestingDisable( INT_MODULE_ID index ); Description This function disables interrupt nesting on processors that support it. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the INTNesting feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsINTNesting API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_NestingDisable( INT_ID_0 ); 5.6.11.6.1.10 PLIB_INT_NestingEnable Function C void PLIB_INT_NestingEnable( INT_MODULE_ID index ); Description This function enables interrupt nesting on processors that support it. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the INTNesting feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsINTNesting API to write flexible code to automatically determine if this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2213 Example PLIB_INT_NestingEnable( INT_ID_0 ); 5.6.11.6.1.11 PLIB_INT_PeripheralsDisable Function C void PLIB_INT_PeripheralsDisable( INT_MODULE_ID index ); Description This function disables the generation of interrupts to the CPU by the peripherals on devices that support this feature. Preconditions None. Returns None. Remarks This function implements an operation of the PeripheralControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsPeripheralControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PeripheralsDisable( INT_ID_0 ); 5.6.11.6.1.12 PLIB_INT_PeripheralsEnable Function C void PLIB_INT_PeripheralsEnable( INT_MODULE_ID index ); Description This function enables the generation of interrupts to the CPU by the peripherals on devices with the ability to disable them. Preconditions None. Returns None. Remarks This function implements an operation of the PeripheralControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsPeripheralControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PeripheralsEnable( INT_ID_0 ); 5.6.11.6.1.13 PLIB_INT_PriorityDisable Function C void PLIB_INT_PriorityDisable( 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2214 INT_MODULE_ID index ); Description This function disables interrupt priority levels on devices that support programmable interrupt priorities. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the Priority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PriorityDisable( INT_ID_0 ); 5.6.11.6.1.14 PLIB_INT_PriorityEnable Function C void PLIB_INT_PriorityEnable( INT_MODULE_ID index ); Description This function enables interrupt priority levels on devices that support programmable interrupt priorities. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the Priority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PriorityEnable( INT_ID_0 ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2215 5.6.11.6.1.15 PLIB_INT_PriorityGet Function C INT_PRIORITY_LEVEL PLIB_INT_PriorityGet( INT_MODULE_ID index ); Description This function returns the priority level of the latest interrupt presented to the CPU. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns One of the possible values from INT_PRIORITY_LEVEL. Remarks This value should only be used when the interrupt controller is configured for single vector mode using the function PLIB_INT_SingleVectorSelect. This function implements an operation of the INTCPUPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsINTCPUPriority API to write flexible code to automatically determine if this feature is available. Example INT_PRIORITY_LEVEL level = PLIB_INT_RequestedPriorityLevelGet( INT_ID_0 ); 5.6.11.6.1.16 PLIB_INT_PriorityHighDisable Function C void PLIB_INT_PriorityHighDisable( INT_MODULE_ID index ); Description This function disables the generation of high-priority interrupts to the CPU on devices that support high-priority interrupts. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the HighPriority feature. This feature may not be available on all parts. Please refer to 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2216 the data sheet to determine if this feature is available or call the PLIB_INT_ExistsHighPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PriorityHighDisable( INT_ID_0 ); 5.6.11.6.1.17 PLIB_INT_PriorityHighEnable Function C void PLIB_INT_PriorityHighEnable( INT_MODULE_ID index ); Description This function enables the generation of high-priority interrupts to the CPU on devices that support this feature. Preconditions None. Returns None. Remarks This function implements an operation of the HighPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsHighPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PriorityHighEnable( INT_ID_0 ); 5.6.11.6.1.18 PLIB_INT_PriorityLowDisable Function C void PLIB_INT_PriorityLowDisable( INT_MODULE_ID index ); Description This function disables the generation of low-priority interrupts to the CPU on devices that support this feature. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the LowPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsLowPriority API to write flexible code to automatically determine if this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2217 Example PLIB_INT_PriorityLowDisable( INT_ID_0 ); 5.6.11.6.1.19 PLIB_INT_PriorityLowEnable Function C void PLIB_INT_PriorityLowEnable( INT_MODULE_ID index ); Description This function enables generation of low-priority interrupts to the CPU on devices that support this feature. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only one interrupt module ). Returns None. Remarks This function implements an operation of the LowPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsLowPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_PriorityLowEnable( INT_ID_0 ); 5.6.11.6.1.20 PLIB_INT_ProximityTimerDisable Function C void PLIB_INT_ProximityTimerDisable( INT_MODULE_ID index ); Description This function disables the interrupt temporal-proximity timer. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the ProximityTimerEnable feature. This feature may not be available on all parts. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2218 Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsProximityTimerEnable API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_ProximityTimerDisable(INT_PRIORITY_LEVEL3); 5.6.11.6.1.21 PLIB_INT_ProximityTimerEnable Function C void PLIB_INT_ProximityTimerEnable( INT_MODULE_ID index, INT_PRIORITY_LEVEL priority ); Description This function enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. One of the possible values from PLIB_INT_PRIORITY_LEVEL can be selected. Interrupts of that priority and lower start the temporal proximity timer. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). priority One of possible values from INT_PRIORITY_LEVEL. Returns None. Remarks This function implements an operation of the ProximityTimerEnable feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsProximityTimerEnable API to write flexible code to automatically determine if this feature is available. Choosing INT_PRIORITY_0 disables the proximity timer (exactly the same as if PLIB_INT_ProximityTimerDisable had been called. Example //Interrupts of group priority 3 or lower start the temporal proximity timer PLIB_INT_ProximityTimerEnable( INT_ID_0, INT_PRIORITY_LEVEL3 ); 5.6.11.6.1.22 PLIB_INT_SingleVectorSelect Function C void PLIB_INT_SingleVectorSelect( INT_MODULE_ID index ); Description The function configures the Interrupt Controller for Single Vector mode. All interrupt requests will serviced at one vector address. The CPU vectors to the same address for all interrupt sources. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2219 Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks While the user can, during run-time, reconfigure the Interrupt Controller from Single Vector mode to Multiple Vector mode, such action is strongly discouraged, as it may result in undefined behavior. This function implements an operation of the VectorSelect feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorSelect API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SingleVectorSelect( INT_ID_0 ); 5.6.11.6.1.23 PLIB_INT_SingleVectorShadowSetDisable Function C void PLIB_INT_SingleVectorShadowSetDisable( INT_MODULE_ID index ); Description This function disables usage of the "shadow" set of processor registers when operating in Single Vector mode. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the SingleVectorShadowSet feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSingleVectorShadowSet API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SingleVectorShadowSetEnable( INT_ID_0 ); 5.6.11.6.1.24 PLIB_INT_SingleVectorShadowSetEnable Function C void PLIB_INT_SingleVectorShadowSetEnable( INT_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2220 Description This function enables usage of the "shadow" set of processor registers when operating in Single Vector mode. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns None. Remarks This function implements an operation of the SingleVectorShadowSet feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSingleVectorShadowSet API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SingleVectorShadowSetEnable( INT_ID_0 ); 5.6.11.6.1.25 PLIB_INT_StandardVectorTableSelect Function C void PLIB_INT_StandardVectorTableSelect( INT_MODULE_ID index ); Description This function enables use of the standard vector table. This is the default. It is only necessary to use this function if the alternate vector table was enabled using the PLIB_INT_AlternateVectorTableSelect function. Preconditions None. Returns None. Remarks This function implements an operation of the AlternateVectorTable feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsAlternateVectorTable API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_StandardVectorTableSelect( INT_ID_0 ); 5.6.11.6.2 Interrupt Source Control Functions 5.6.11.6.2.1 PLIB_INT_SourceDisable Function C void PLIB_INT_SourceDisable( 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2221 INT_MODULE_ID index, INT_SOURCE source ); Description This function disables the given interrupt source. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns None. Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SourceDisable(INT_ID_0,INT_SOURCE_TIMER_1); 5.6.11.6.2.2 PLIB_INT_SourceEnable Function C void PLIB_INT_SourceEnable( INT_MODULE_ID index, INT_SOURCE source ); Description This function enables the interrupt source. The interrupt flag is set when the interrupt request is sampled. The pending interrupt request will not cause further processing if the interrupt is not enabled using this function or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Initialization The steps that are required to initialize the Interrupt Controller module vary for different microcontrollers. Note: Refer to the specific device data sheet for the correct initialization sequence for your device. Interrupt Source Setup <<<<<<< .mine 1. An interrupt Source needs to be enabled in order for it to be able to generate a interrupt to the core. Use the functions PLIB_INT_SourceEnable to enable the interrupt source. INT_SOURCE is a list of possible interrupt sources 2. On some micro controllers, each interrupt can be associated with a priority. Use the function PLIB_INT_SourcePrioritySet to set the interrupt source priority. INT_SOURCES is list of possible interrupt sources and INT_PRIORITY_LEVELS is the list of possible priority levels. 3. On some micro controllers, each interrupt can be associated with a sub priority. Use the function PLIB_INT_SourceSubPrioritySet to set the interrupt source sub priority. INT_SUBPRIORITY_LEVELS is a list of possible sub priority levels. 4. On most microcontrollers, it will be necessary to enable interrupt generation to the core by calling the PLIB_INT_Enable 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2222 routine. ======= An interrupt Source needs to be enabled in order for it to be able to generate a interrupt to the core. Use the function PLIB_INT_SourceEnable to enable the interrupt source. INT_SOURCE is a list of the possible interrupt sources On some microcontrollers, each interrupt can be associated with a priority. Use the function PLIB_INT_VectorPrioritySet to set the interrupt source priority. INT_SOURCE is a list of the possible interrupt sources and INT_PRIORITY_LEVEL is the list of possible priority levels. On some microcontrollers, each interrupt can be associated with a sub-priority. Use the function PLIB_INT_VectorSubPrioritySet to set the interrupt source sub-priority. INT_SUBPRIORITY_LEVEL is a list of possible sub-priority levels. On most microcontrollers, it will be necessary to enable interrupt generation to the core by calling the PLIB_INT_Enable function. >>>>>>> .r21563 Interrupt Handling The status of the interrupt indicates whether or not the interrupt request was generated by the source. The status of the trap source can be obtained using the function PLIB_INT_TrapSourceFlagGet and the status of the interrupt source can be obtained using the function PLIB_INT_SourceFlagGet. The interrupt status flags can be used to indicate the interrupt status even if the interrupt is not enabled for the source. When the interrupt is not enabled for the source, no interrupt is generated to the core even though the interrupt controller still recognizes that the source requested an interrupt. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. Before the Interrupt Service Routine (ISR) ends, the status of the interrupt needs to be cleared to avoid entering the ISR repeatedly for the same interrupt event. A trap source status can be cleared using the function PLIB_INT_TrapSourceFlagClear, and an interrupt source status can be cleared using the function PLIB_INT_SourceFlagClear. INT_TRAP_SOURCE is a list of possible trap events, and INT_SOURCE is a list of possible interrupt sources. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns None. Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SourceEnable(INT_ID_0,INT_SOURCE_TIMER_1); 5.6.11.6.2.3 PLIB_INT_SourceFlagClear Function C void PLIB_INT_SourceFlagClear( INT_MODULE_ID index, INT_SOURCE source ); 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2223 Description This function clears the status of the interrupt flag for the selected source. The flag is set when the interrupt request is identified. The pending interrupt request will not cause further processing if the interrupt is not enabled using the function PLIB_INT_InterruptSourceEnable or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns None. Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceFlag API to write flexible code to automatically determine if this feature is available. Example if(PLIB_INT_SourceFlagGet(INT_ID_0,INT_SOURCE_TIMER_1)) { PLIB_INT_SourceFlagClear(INT_ID_0,INT_SOURCE_TIMER_1); } 5.6.11.6.2.4 PLIB_INT_SourceFlagGet Function C bool PLIB_INT_SourceFlagGet( INT_MODULE_ID index, INT_SOURCE source ); Description This function returns the status of the interrupt flag for the selected source. The flag is set when the interrupt request is recognized. The pending interrupt request will not cause further processing if the interrupt is not enabled using the function PLIB_INT_InterruptSourceEnable or if interrupts are not enabled (on processors that support the PLIB_INT_Enable feature). Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns true - If the interrupt request is recognized for the source false - If the interrupt request is not recognized for the source 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2224 Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceFlag API to write flexible code to automatically determine if this feature is available. Example if(PLIB_INT_SourceFlagGet(INT_ID_0, INT_SOURCE_TIMER_1)) { PLIB_INT_SourceFlagClear(INT_ID_0, INT_SOURCE_TIMER_1); } 5.6.11.6.2.5 PLIB_INT_SourceFlagSet Function C void PLIB_INT_SourceFlagSet( INT_MODULE_ID index, INT_SOURCE source ); Description This function sets the status of the interrupt flag for the selected source. This function will not be used during normal operation of the system. It is used to generate test interrupts for debug and testing purposes. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns None. Remarks This function implements an operation of the SourceFlag feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceFlag API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_SourceFlagSet(INT_ID_0,INT_SOURCE_TIMER_1); 5.6.11.6.2.6 PLIB_INT_SourceIsEnabled Function C bool PLIB_INT_SourceIsEnabled( INT_MODULE_ID index, INT_SOURCE source ); Description This function gets the enable state of the interrupt source. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2225 Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). source One of the possible values from INT_SOURCE. Returns • true - If the interrupt source is enabled • false - If the interrupt source is disabled Remarks This function implements an operation of the SourceControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsSourceControl API to write flexible code to automatically determine if this feature is available. Example if(PLIB_INT_SourceIsEnabled(INT_ID_0,INT_SOURCE_TIMER_1) != true) { PLIB_INT_SourceEnable(INT_ID_0,INT_SOURCE_TIMER_1); } 5.6.11.6.2.7 PLIB_INT_VectorPriorityGet Function C INT_PRIORITY_LEVEL PLIB_INT_VectorPriorityGet( INT_MODULE_ID index, INT_VECTOR vector ); Description Gets the priority of the interrupt vector. The priority is one of the possible values from INT_PRIORITY_LEVEL Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). vector One of the possible values from INT_VECTOR Returns priority - One of the possible values from INT_PRIORITY_LEVEL Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorPriority API to write flexible code to automatically determine if this feature is available. Example INT_PRIORITY_LEVEL level; 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2226 level = PLIB_INT_VectorPriorityGet(INT_ID_0, INT_VECTOR_T1); 5.6.11.6.2.8 PLIB_INT_VectorPrioritySet Function C void PLIB_INT_VectorPrioritySet( INT_MODULE_ID index, INT_VECTOR vector, INT_PRIORITY_LEVEL priority ); Description Sets the priority of the interrupt vector. The priority is one of the possible values from INT_PRIORITY_LEVEL. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). vector One of the possible values from INT_VECTOR priority One of the possible values from INT_PRIORITY_LEVEL Returns None. Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_VectorPrioritySet(INT_ID_0, INT_VECTOR_T1, INT_PRIORITY_LEVEL_4); 5.6.11.6.2.9 PLIB_INT_VectorSubPriorityGet Function C INT_SUBPRIORITY_LEVEL PLIB_INT_VectorSubPriorityGet( INT_MODULE_ID index, INT_VECTOR vector ); Description This function gets the sub-priority of the interrupt vector. The priority is one of the possible values from INT_SUBPRIORITY_LEVEL. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). vector One of the possible values from INT_VECTOR 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2227 Returns priority - One of the possible values from INT_SUBPRIORITY_LEVEL Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorPriority API to write flexible code to automatically determine if this feature is available. Example INT_SUBPRIORITY_LEVEL level; level = PLIB_INT_VectorSubPriorityGet(INT_ID_0, INT_VECTOR_T1); 5.6.11.6.2.10 PLIB_INT_VectorSubPrioritySet Function C void PLIB_INT_VectorSubPrioritySet( INT_MODULE_ID index, INT_VECTOR vector, INT_SUBPRIORITY_LEVEL subPriority ); Description This function sets the sub priority of the interrupt vector. The sub-priority is one of the possible values from INT_SUBPRIORITY_LEVEL. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). vector One of the possible values from INT_VECTOR subPriority One of the possible values from INT_SUBPRIORITY_LEVEL Returns None. Remarks This function implements an operation of the VectorPriority feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsVectorPriority API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_VectorSubPrioritySet(INT_ID_0, INT_VECTOR_T1, INT_SUBPRIORITY_LEVEL_1); 5.6.11.6.3 Other Status and Control Functions 5.6.11.6.3.1 PLIB_INT_CPUCurrentPriorityLevelGet Function C INT_PRIORITY_LEVEL PLIB_INT_CPUCurrentPriorityLevelGet( INT_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2228 ); Description This function gets the interrupt priority level at which the CPU is currently operating. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns priority - The current interrupt priority of the CPU. Range (0 - 15) Remarks User interrupts are disabled when the CPU priority is more than 7. This function implements an operation of the CPUCurrentPriorityLevel feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsCPUCurrentPriorityLevel API to write flexible code to automatically determine if this feature is available. Example INT_PRIORITY_LEVEL currentCPUPriority; currentCPUPriority = PLIB_INT_CPUCurrentPriorityLevelGet( INT_ID_0 ); 5.6.11.6.3.2 PLIB_INT_ProximityTimerGet Function C uint32_t PLIB_INT_ProximityTimerGet( INT_MODULE_ID index ); Description This function returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns Timer reload value. Remarks This function implements an operation of the ProximityTimerControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsProximityTimerControl API to write flexible code to automatically determine if this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2229 Example uint32_t timer; timer = PLIB_INT_ProximityTimerGet( INT_ID_0 ); 5.6.11.6.3.3 PLIB_INT_ProximityTimerSet Function C void PLIB_INT_ProximityTimerSet( INT_MODULE_ID index, uint32_t timerreloadvalue ); Description This function sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). timerReloadValue Timer reload value. Returns None. Remarks This function implements an operation of the ProximityTimerControl feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsProximityTimerControl API to write flexible code to automatically determine if this feature is available. Example PLIB_INT_ProximityTimerSet(INT_ID_0, 0x12345678); 5.6.11.6.3.4 PLIB_INT_TrapSourceFlagClear Function C void PLIB_INT_TrapSourceFlagClear( INT_MODULE_ID index, INT_TRAP_SOURCE trapsource ); Description This function clears the flag for the selected trap. The flag is set when the request is recognized. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2230 trapSource One of the possible values from INT_TRAP_SOURCE Returns None. Remarks Some processor documentation uses the term "Exception" instead of the term "Trap". For purposes of the Interrupt Peripheral Library, these two terms are synonyms. The difference between a trap (or exception) and an interrupt is that a trap cannot be enabled or disabled, whereas an interrupt can be. This function implements an operation of the TrapSource feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsTrapSource API to write flexible code to automatically determine if this feature is available. Example if(PLIB_INT_TrapSourceFlagGet(INT_ID_0,INT_ADDRESS_OVERFLOW_TRAP)) { PLIB_INT_TrapSourceFlagClear(INT_ID_0,INT_ADDRESS_OVERFLOW_TRAP); } 5.6.11.6.3.5 PLIB_INT_TrapSourceFlagGet Function C bool PLIB_INT_TrapSourceFlagGet( INT_MODULE_ID index, INT_TRAP_SOURCE trapSource ); Description This function returns the status of the flag for the selected trap. The flag is set when the trap request is recognized. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). trapSource One of the possible values from INT_TRAP_SOURCE Returns • true - If the request has been recognized for the trap • false - If the request is not recognized for the trap Remarks Some processor documentation uses the term "Exception" instead of the term "Trap". For purposes of the Interrupt Peripheral Library, these two terms are synonyms. The difference between a trap (or exception) and an interrupt is that a trap cannot be enabled or disabled, whereas an interrupt can be. This function implements an operation of the TrapSource feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsTrapSource API to write flexible code to automatically determine if this feature is available. Example if(PLIB_INT_TrapSourceFlagGet(INT_ID_0,INT_ADDRESS_OVERFLOW_TRAP)) { 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2231 PLIB_INT_TrapSourceFlagClear(INT_ID_0,INT_ADDRESS_OVERFLOW_TRAP); } 5.6.11.6.3.6 PLIB_INT_VectorGet Function C INT_VECTOR PLIB_INT_VectorGet( INT_MODULE_ID index ); Description This function returns the interrupt vector that is presented to the CPU. Preconditions None. Parameters Parameters Description index Identifier for the module instance to be configured (it should be INT_ID_0 for all the devices which has only interrupt module ). Returns One of the possible values from INT_VECTOR. Remarks This value should only be used when the interrupt controller is configured for single vector mode using the function PLIB_INT_MultiVectorDisable. This function implements an operation of the INTCPUVector feature. This feature may not be available on all parts. Please refer to the data sheet to determine if this feature is available or call the PLIB_INT_ExistsINTCPUVector API to write flexible code to automatically determine if this feature is available. Example INT_VECTOR level = PLIB_INT_VectorGet( INT_ID_0 ); 5.6.11.6.4 Data Types and Constants 5.6.11.6.4.1 INT_EXTERNAL_SOURCES Enumeration C typedef enum { INT_EXTERNAL_INT_SOURCE0, INT_EXTERNAL_INT_SOURCE1, INT_EXTERNAL_INT_SOURCE2, INT_EXTERNAL_INT_SOURCE3, INT_EXTERNAL_INT_SOURCE4 } INT_EXTERNAL_SOURCES; Description External Interrupt Sources This enumeration lists the possible external sources that can cause an interrupt to occur. Members Members Description INT_EXTERNAL_INT_SOURCE0 External Interrupt Source 0 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2232 INT_EXTERNAL_INT_SOURCE1 External Interrupt Source 1 INT_EXTERNAL_INT_SOURCE2 External Interrupt Source 2 INT_EXTERNAL_INT_SOURCE3 External Interrupt Source 3 INT_EXTERNAL_INT_SOURCE4 External Interrupt Source 4 Remarks This enumeration is processor-specific and is defined in the processor- specific header files (see processor.h). 5.6.11.6.4.2 INT_PRIORITY_LEVEL Enumeration C typedef enum { INT_PRIORITY_LEVEL0, INT_PRIORITY_LEVEL1, INT_PRIORITY_LEVEL2, INT_PRIORITY_LEVEL3, INT_PRIORITY_LEVEL4, INT_PRIORITY_LEVEL5, INT_PRIORITY_LEVEL6, INT_PRIORITY_LEVEL7 } INT_PRIORITY_LEVEL; Description Priority Level This enumeration lists the possible interrupt priority levels that can be selected for each source. Members Members Description INT_PRIORITY_LEVEL0 Disabled INT_PRIORITY_LEVEL1 Priority 1 INT_PRIORITY_LEVEL2 Priority 2 INT_PRIORITY_LEVEL3 Priority 3 INT_PRIORITY_LEVEL4 Priority 4 INT_PRIORITY_LEVEL5 Priority 5 INT_PRIORITY_LEVEL6 Priority 6 INT_PRIORITY_LEVEL7 Priority 7 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.11.6.4.3 INT_SOURCE Enumeration C typedef enum { INT_SOURCE_SOFTWARE_0, INT_SOURCE_SOFTWARE_1, INT_SOURCE_EXTERNAL_0, INT_SOURCE_EXTERNAL_1, INT_SOURCE_EXTERNAL_2, INT_SOURCE_EXTERNAL_3, INT_SOURCE_EXTERNAL_4, INT_SOURCE_TIMER_CORE, INT_SOURCE_TIMER_1, INT_SOURCE_TIMER_2, 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2233 INT_SOURCE_TIMER_3 , INT_SOURCE_TIMER_4 , INT_SOURCE_TIMER_5 , INT_SOURCE_INPUT_CAPTURE_1 , INT_SOURCE_INPUT_CAPTURE_1_ERROR , INT_SOURCE_INPUT_CAPTURE_2 , INT_SOURCE_INPUT_CAPTURE_2_ERROR , INT_SOURCE_INPUT_CAPTURE_3 , INT_SOURCE_INPUT_CAPTURE_3_ERROR , INT_SOURCE_INPUT_CAPTURE_4 , INT_SOURCE_INPUT_CAPTURE_4_ERROR , INT_SOURCE_INPUT_CAPTURE_5 , INT_SOURCE_INPUT_CAPTURE_5_ERROR , INT_SOURCE_OUTPUT_COMPARE_1 , INT_SOURCE_OUTPUT_COMPARE_2 , INT_SOURCE_OUTPUT_COMPARE_3 , INT_SOURCE_OUTPUT_COMPARE_4 , INT_SOURCE_OUTPUT_COMPARE_5 , INT_SOURCE_SPI_1_ERROR , INT_SOURCE_SPI_1_RECEIVE , INT_SOURCE_SPI_1_TRANSMIT , INT_SOURCE_SPI_2_ERROR , INT_SOURCE_SPI_2_RECEIVE , INT_SOURCE_SPI_2_TRANSMIT , INT_SOURCE_SPI_3_ERROR , INT_SOURCE_SPI_3_RECEIVE , INT_SOURCE_SPI_3_TRANSMIT , INT_SOURCE_SPI_4_ERROR , INT_SOURCE_SPI_4_RECEIVE , INT_SOURCE_SPI_4_TRANSMIT , INT_SOURCE_USART_1_ERROR , INT_SOURCE_USART_1_RECEIVE , INT_SOURCE_USART_1_TRANSMIT , INT_SOURCE_USART_2_ERROR , INT_SOURCE_USART_2_RECEIVE , INT_SOURCE_USART_2_TRANSMIT , INT_SOURCE_USART_3_ERROR , INT_SOURCE_USART_3_RECEIVE , INT_SOURCE_USART_3_TRANSMIT , INT_SOURCE_USART_4_ERROR , INT_SOURCE_USART_4_RECEIVE , INT_SOURCE_USART_4_TRANSMIT , INT_SOURCE_USART_5_ERROR , INT_SOURCE_USART_5_RECEIVE , INT_SOURCE_USART_5_TRANSMIT , INT_SOURCE_USART_6_ERROR , INT_SOURCE_USART_6_RECEIVE , INT_SOURCE_USART_6_TRANSMIT , INT_SOURCE_I2C_1_ERROR , INT_SOURCE_I2C_1_SLAVE , INT_SOURCE_I2C_1_MASTER , INT_SOURCE_I2C_2_ERROR , INT_SOURCE_I2C_2_SLAVE , INT_SOURCE_I2C_2_MASTER , INT_SOURCE_I2C_3_ERROR , INT_SOURCE_I2C_3_SLAVE , INT_SOURCE_I2C_3_MASTER , INT_SOURCE_I2C_4_ERROR , INT_SOURCE_I2C_4_SLAVE , INT_SOURCE_I2C_4_MASTER , INT_SOURCE_I2C_5_ERROR , INT_SOURCE_I2C_5_SLAVE , INT_SOURCE_I2C_5_MASTER , INT_SOURCE_CHANGE_NOTICE , INT_SOURCE_ADC_1 , INT_SOURCE_PARALLEL_PORT , 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2234 INT_SOURCE_PARALLEL_PORT_ERROR, INT_SOURCE_COMPARATOR_1, INT_SOURCE_COMPARATOR_2, INT_SOURCE_CLOCK_MONITOR, INT_SOURCE_RTCC, INT_SOURCE_DMA_0, INT_SOURCE_DMA_1, INT_SOURCE_DMA_2, INT_SOURCE_DMA_3, INT_SOURCE_DMA_4, INT_SOURCE_DMA_5, INT_SOURCE_DMA_6, INT_SOURCE_DMA_7, INT_SOURCE_FLASH_CONTROL, INT_SOURCE_USB_1, INT_SOURCE_CAN_1, INT_SOURCE_CAN_2, INT_SOURCE_ETH_1 } INT_SOURCE; Description Interrupt Source This enumeration lists the possible sources that can cause an interrupt to occur. Members Members Description INT_SOURCE_SOFTWARE_0 Software interrupt 0 INT_SOURCE_SOFTWARE_1 Software interrupt 1 INT_SOURCE_EXTERNAL_0 External interrupt 0 INT_SOURCE_EXTERNAL_1 External interrupt 1 INT_SOURCE_EXTERNAL_2 External interrupt 2 INT_SOURCE_EXTERNAL_3 External interrupt 3 INT_SOURCE_EXTERNAL_4 External interrupt 4 INT_SOURCE_TIMER_CORE Core timer interrupt INT_SOURCE_TIMER_1 Timer 1 interrupt INT_SOURCE_TIMER_2 Timer 2 interrupt INT_SOURCE_TIMER_3 Timer 3 interrupt INT_SOURCE_TIMER_4 Timer 4 interrupt INT_SOURCE_TIMER_5 Timer 5 interrupt INT_SOURCE_INPUT_CAPTURE_1 Input Capture 1 interrupt INT_SOURCE_INPUT_CAPTURE_1_ERROR Input Capture 1 Error interrupt INT_SOURCE_INPUT_CAPTURE_2 Input Capture 2 interrupt INT_SOURCE_INPUT_CAPTURE_2_ERROR Input Capture 2 Error interrupt INT_SOURCE_INPUT_CAPTURE_3 Input Capture 3 interrupt INT_SOURCE_INPUT_CAPTURE_3_ERROR Input Capture 3 Error interrupt INT_SOURCE_INPUT_CAPTURE_4 Input Capture 4 interrupt INT_SOURCE_INPUT_CAPTURE_4_ERROR Input Capture 4 Error interrupt INT_SOURCE_INPUT_CAPTURE_5 Input Capture 5 interrupt INT_SOURCE_INPUT_CAPTURE_5_ERROR Input Capture 5 Error interrupt INT_SOURCE_OUTPUT_COMPARE_1 Output Compare 1 interrupt INT_SOURCE_OUTPUT_COMPARE_2 Output Compare 2 interrupt INT_SOURCE_OUTPUT_COMPARE_3 Output Compare 3 interrupt 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2235 INT_SOURCE_OUTPUT_COMPARE_4 Output Compare 4 interrupt INT_SOURCE_OUTPUT_COMPARE_5 Output Compare 5 interrupt INT_SOURCE_SPI_1_ERROR SPI-1 Error interrupt INT_SOURCE_SPI_1_RECEIVE SPI-1 Receive Done interrupt INT_SOURCE_SPI_1_TRANSMIT SPI-1 Transmit Done interrupt INT_SOURCE_SPI_2_ERROR SPI-2 Error interrupt INT_SOURCE_SPI_2_RECEIVE SPI-2 Receive Done interrupt INT_SOURCE_SPI_2_TRANSMIT SPI-2 Transmit Done interrupt INT_SOURCE_SPI_3_ERROR SPI-3 Error interrupt INT_SOURCE_SPI_3_RECEIVE SPI-3 Receive Done interrupt INT_SOURCE_SPI_3_TRANSMIT SPI-3 Transmit Done interrupt INT_SOURCE_SPI_4_ERROR SPI-4 Error interrupt INT_SOURCE_SPI_4_RECEIVE SPI-4 Receive Done interrupt INT_SOURCE_SPI_4_TRANSMIT SPI-4 Transmit Done interrupt INT_SOURCE_USART_1_ERROR UART-1 Error interrupt INT_SOURCE_USART_1_RECEIVE UART-1 Receive interrupt INT_SOURCE_USART_1_TRANSMIT UART-1 Transmit interrupt INT_SOURCE_USART_2_ERROR UART-2 Error interrupt INT_SOURCE_USART_2_RECEIVE UART-2 Receive interrupt INT_SOURCE_USART_2_TRANSMIT UART-2 Transmit interrupt INT_SOURCE_USART_3_ERROR UART-3 Error interrupt INT_SOURCE_USART_3_RECEIVE UART-3 Receive interrupt INT_SOURCE_USART_3_TRANSMIT UART-3 Transmit interrupt INT_SOURCE_USART_4_ERROR UART-4 Error interrupt INT_SOURCE_USART_4_RECEIVE UART-4 Receive interrupt INT_SOURCE_USART_4_TRANSMIT UART-4 Transmit interrupt INT_SOURCE_USART_5_ERROR UART-5 Error interrupt INT_SOURCE_USART_5_RECEIVE UART-5 Receive interrupt INT_SOURCE_USART_5_TRANSMIT UART-5 Transmit interrupt INT_SOURCE_USART_6_ERROR UART-6 Error interrupt INT_SOURCE_USART_6_RECEIVE UART-6 Receive interrupt INT_SOURCE_USART_6_TRANSMIT UART-6 Transmit interrupt INT_SOURCE_I2C_1_ERROR I2C-1 Bus Error Event interrupt INT_SOURCE_I2C_1_SLAVE I2C-1 Slave Event interrupt INT_SOURCE_I2C_1_MASTER I2C-1 Master Event interrupt INT_SOURCE_I2C_2_ERROR I2C-2 Bus Error Event interrupt INT_SOURCE_I2C_2_SLAVE I2C-2 Slave Event interrupt INT_SOURCE_I2C_2_MASTER I2C-2 Master Event interrupt INT_SOURCE_I2C_3_ERROR I2C-3 Bus Error Event interrupt INT_SOURCE_I2C_3_SLAVE I2C-3 Slave Event interrupt INT_SOURCE_I2C_3_MASTER I2C-3 Master Event interrupt INT_SOURCE_I2C_4_ERROR I2C-4 Bus Error Event interrupt INT_SOURCE_I2C_4_SLAVE I2C-4 Slave Event interrupt INT_SOURCE_I2C_4_MASTER I2C-4 Master Event interrupt INT_SOURCE_I2C_5_ERROR I2C-5 Bus Error Event interrupt 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2236 INT_SOURCE_I2C_5_SLAVE I2C-5 Slave Event interrupt INT_SOURCE_I2C_5_MASTER I2C-5 Master Event interrupt INT_SOURCE_CHANGE_NOTICE Input Change Notice interrupt INT_SOURCE_ADC_1 Analog-to-Digital Converter 1 interrupt INT_SOURCE_PARALLEL_PORT Parallel Master Port interrupt INT_SOURCE_PARALLEL_PORT_ERROR Parallel Master Port Error interrupt INT_SOURCE_COMPARATOR_1 Comparator 1 interrupt INT_SOURCE_COMPARATOR_2 Comparator 2 interrupt INT_SOURCE_CLOCK_MONITOR Fail-Safe Clock Monitor interrupt INT_SOURCE_RTCC Real-Time Clock and Calender interrupt INT_SOURCE_DMA_0 Direct Memory Access Channel 0 interrupt INT_SOURCE_DMA_1 Direct Memory Access Channel 1 interrupt INT_SOURCE_DMA_2 Direct Memory Access Channel 2 interrupt INT_SOURCE_DMA_3 Direct Memory Access Channel 3 interrupt INT_SOURCE_DMA_4 Direct Memory Access Channel 4 interrupt INT_SOURCE_DMA_5 Direct Memory Access Channel 5 interrupt INT_SOURCE_DMA_6 Direct Memory Access Channel 6 interrupt INT_SOURCE_DMA_7 Direct Memory Access Channel 7 interrupt INT_SOURCE_FLASH_CONTROL Flash Control Event interrupt INT_SOURCE_USB_1 Universal Serial Bus 1 interrupt INT_SOURCE_CAN_1 Controller Area Network 1 interrupt INT_SOURCE_CAN_2 Controller Area Network 2 interrupt INT_SOURCE_ETH_1 Ethernet interrupt Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.11.6.4.4 INT_SUBPRIORITY_LEVEL Enumeration C typedef enum { INT_SUBPRIORITY_LEVEL0, INT_SUBPRIORITY_LEVEL1, INT_SUBPRIORITY_LEVEL2, INT_SUBPRIORITY_LEVEL3 } INT_SUBPRIORITY_LEVEL; Description Sub Priority Level This enumeration lists the possible interrupt sub priority levels that can be selected for each source. Members Members Description INT_SUBPRIORITY_LEVEL0 Sub Priority 0 INT_SUBPRIORITY_LEVEL1 Sub Priority 1 INT_SUBPRIORITY_LEVEL2 Sub Priority 2 INT_SUBPRIORITY_LEVEL3 Sub Priority 3 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2237 Remarks This enumeration (INT_SUBPRIORITY_LEVEL) is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.11.6.4.5 INT_TRAP_SOURCE Enumeration C typedef enum { INT_TRAP_ADDRESS_ERROR_LOAD, INT_TRAP_ADDRESS_ERROR_STORE, INT_TRAP_BUS_ERROR_INSTRUCTION, INT_TRAP_BUS_ERROR_DATA, INT_TRAP_SYSCALL, INT_TRAP_BREAKPOINT, INT_TRAP_RESERVED_INSTRUCTION, INT_TRAP_UNUSABLE_COPROCESSOR, INT_TRAP_ARITHMETIC_OVERFLOW, INT_TRAP_GENERAL } INT_TRAP_SOURCE; Description Trap Source This enumeration lists the names of the trap or exception sources. Members Members Description INT_TRAP_ADDRESS_ERROR_LOAD Address error exception on a data load or instruction fetch INT_TRAP_ADDRESS_ERROR_STORE Address error exception on a data store INT_TRAP_BUS_ERROR_INSTRUCTION Bus error exception on an instruction fetch INT_TRAP_BUS_ERROR_DATA Bus error exception on a data load or store INT_TRAP_SYSCALL Exception do to a Syscall instruction INT_TRAP_BREAKPOINT Exception do to hitting a debug breakpoint INT_TRAP_RESERVED_INSTRUCTION Exception do to fetching a reserved instruction INT_TRAP_UNUSABLE_COPROCESSOR Exception do to fetching a reference to an unusable coprocessor INT_TRAP_ARITHMETIC_OVERFLOW Arithmetic Overflow exception INT_TRAP_GENERAL General exception trap Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.11.6.4.6 INT_VECTOR Enumeration C typedef enum { INT_VECTOR_CT, INT_VECTOR_CS0, INT_VECTOR_CS1, INT_VECTOR_INT0, INT_VECTOR_T1, INT_VECTOR_IC1, INT_VECTOR_OC1, INT_VECTOR_INT1, INT_VECTOR_T2, INT_VECTOR_IC2, 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2238 INT_VECTOR_OC2, INT_VECTOR_INT2, INT_VECTOR_T3, INT_VECTOR_IC3, INT_VECTOR_OC3, INT_VECTOR_INT3, INT_VECTOR_T4, INT_VECTOR_IC4, INT_VECTOR_OC4, INT_VECTOR_INT4, INT_VECTOR_T5, INT_VECTOR_IC5, INT_VECTOR_OC5, INT_VECTOR_SPI1, INT_VECTOR_UART1, INT_VECTOR_SPI3, INT_VECTOR_I2C3, INT_VECTOR_I2C1, INT_VECTOR_CN, INT_VECTOR_AD1, INT_VECTOR_PMP, INT_VECTOR_CMP1, INT_VECTOR_CMP2, INT_VECTOR_UART3, INT_VECTOR_SPI2, INT_VECTOR_I2C4, INT_VECTOR_UART2, INT_VECTOR_SPI4, INT_VECTOR_I2C5, INT_VECTOR_I2C2, INT_VECTOR_FSCM, INT_VECTOR_RTCC, INT_VECTOR_DMA0, INT_VECTOR_DMA1, INT_VECTOR_DMA2, INT_VECTOR_DMA3, INT_VECTOR_DMA4, INT_VECTOR_DMA5, INT_VECTOR_DMA6, INT_VECTOR_DMA7, INT_VECTOR_FCE, INT_VECTOR_USB, INT_VECTOR_CAN1, INT_VECTOR_CAN2, INT_VECTOR_ETH, INT_VECTOR_UART4, INT_VECTOR_UART6, INT_VECTOR_UART5 } INT_VECTOR; Description Interrupt Vectors This enumeration lists the possible interrupt vectors. Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.11.6.5 Feature Existence Functions 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2239 5.6.11.6.5.1 PLIB_INT_ExistsAlternateVectorTable Function C bool PLIB_INT_ExistsAlternateVectorTable( INT_MODULE_ID index ); Description This function identifies whether the AlternateVectorTable feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_AlternateVectorTableSelect • PLIB_INT_StandardVectorTableSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlternateVectorTable feature is supported on the device • false - The AlternateVectorTable feature is not supported on the device Remarks None. 5.6.11.6.5.2 PLIB_INT_ExistsCPUCurrentPriorityLevel Function C bool PLIB_INT_ExistsCPUCurrentPriorityLevel( INT_MODULE_ID index ); Description This function identifies whether the CPUCurrentPriorityLevel feature is available on the Interrupt Controller module. When this function returns true, this function is supported on the device: • PLIB_INT_CPUCurrentPriorityLevelGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CPUCurrentPriorityLevel feature is supported on the device • false - The CPUCurrentPriorityLevel feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2240 5.6.11.6.5.3 PLIB_INT_ExistsEnableControl Function C bool PLIB_INT_ExistsEnableControl( INT_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_Enable • PLIB_INT_Disable • PLIB_INT_IsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.11.6.5.4 PLIB_INT_ExistsExternalINTEdgeSelect Function C bool PLIB_INT_ExistsExternalINTEdgeSelect( INT_MODULE_ID index ); Description This function identifies whether the ExternalINTEdgeSelect feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_ExternalRisingEdgeSelect • PLIB_INT_ExternalFallingEdgeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the ExternalINTEdgeSelect feature: • true - The ExternalINTEdgeSelect feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2241 • false - The ExternalINTEdgeSelect feature is not supported on the device Remarks None. 5.6.11.6.5.5 PLIB_INT_ExistsHighPriority Function C bool PLIB_INT_ExistsHighPriority( INT_MODULE_ID index ); Description This function identifies whether the HighPriority feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_PriorityHighEnable • PLIB_INT_PriorityHighDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HighPriority feature is supported on the device • false - The HighPriority feature is not supported on the device Remarks None. 5.6.11.6.5.6 PLIB_INT_ExistsINTCPUPriority Function C bool PLIB_INT_ExistsINTCPUPriority( INT_MODULE_ID index ); Description This function identifies whether the INTCPUPriority feature is available on the Interrupt Controller module. When this function returns true, this function is supported on the device: • PLIB_INT_PriorityGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The INTCPUPriority feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2242 • false - The INTCPUPriority feature is not supported on the device Remarks None. 5.6.11.6.5.7 PLIB_INT_ExistsINTCPUVector Function C bool PLIB_INT_ExistsINTCPUVector( INT_MODULE_ID index ); Description This function identifies whether the INTCPUVector feature is available on the Interrupt Controller module. When this function returns true, this function is supported on the device: • PLIB_INT_VectorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The INTCPUVector feature is supported on the device • false - The INTCPUVector feature is not supported on the device Remarks None. 5.6.11.6.5.8 PLIB_INT_ExistsINTNesting Function C bool PLIB_INT_ExistsINTNesting( INT_MODULE_ID index ); Description This function identifies whether the INTNesting feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_NestingEnable • PLIB_INT_NestingDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The INTNesting feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2243 • false - The INTNesting feature is not supported on the device Remarks None. 5.6.11.6.5.9 PLIB_INT_ExistsLowPriority Function C bool PLIB_INT_ExistsLowPriority( INT_MODULE_ID index ); Description This function identifies whether the LowPriority feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_PriorityLowEnable • PLIB_INT_PriorityLowDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LowPriority feature is supported on the device • false - The LowPriority feature is not supported on the device Remarks None. 5.6.11.6.5.10 PLIB_INT_ExistsPeripheralControl Function C bool PLIB_INT_ExistsPeripheralControl( INT_MODULE_ID index ); Description This function identifies whether the PeripheralControl feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_PeripheralsEnable • PLIB_INT_PeripheralsDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2244 Returns Existence of the PeripheralControl feature: • true - The PeripheralControl feature is supported on the device • false - The PeripheralControl feature is not supported on the device Remarks None. 5.6.11.6.5.11 PLIB_INT_ExistsPriority Function C bool PLIB_INT_ExistsPriority( INT_MODULE_ID index ); Description This function identifies whether the Priority feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_PriorityEnable • PLIB_INT_PriorityDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Priority feature is supported on the device • false - The Priority feature is not supported on the device Remarks None. 5.6.11.6.5.12 PLIB_INT_ExistsProximityTimerControl Function C bool PLIB_INT_ExistsProximityTimerControl( INT_MODULE_ID index ); Description This function identifies whether the ProximityTimerControl feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_ProximityTimerSet • PLIB_INT_ProximityTimerGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2245 Parameters Parameters Description index Identifier for the device instance Returns • true - The ProximityTimerControl feature is supported on the device • false - The ProximityTimerControl feature is not supported on the device Remarks None. 5.6.11.6.5.13 PLIB_INT_ExistsProximityTimerEnable Function C bool PLIB_INT_ExistsProximityTimerEnable( INT_MODULE_ID index ); Description This function identifies whether the ProximityTimerEnable feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_ProximityTimerEnable • PLIB_INT_ProximityTimerDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ProximityTimerEnable feature is supported on the device • false - The ProximityTimerEnable feature is not supported on the device Remarks None. 5.6.11.6.5.14 PLIB_INT_ExistsSingleVectorShadowSet Function C bool PLIB_INT_ExistsSingleVectorShadowSet( INT_MODULE_ID index ); Description This function identifies whether the SingleVectorShadowSet feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_SingleVectorShadowSetDisable • PLIB_INT_SingleVectorShadowSetEnable 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2246 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SingleVectorShadowSet feature is supported on the device • false - The SingleVectorShadowSet feature is not supported on the device Remarks None. 5.6.11.6.5.15 PLIB_INT_ExistsSourceControl Function C bool PLIB_INT_ExistsSourceControl( INT_MODULE_ID index ); Description This function identifies whether the SourceControl feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_SourceEnable • PLIB_INT_SourceDisable • PLIB_INT_SourceIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SourceControl feature is supported on the device • false - The SourceControl feature is not supported on the device Remarks None. 5.6.11.6.5.16 PLIB_INT_ExistsSourceFlag Function C bool PLIB_INT_ExistsSourceFlag( INT_MODULE_ID index ); Description This function identifies whether the SourceFlag feature is available on the Interrupt Controller module. When this function returns 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2247 true, these functions are supported on the device: • PLIB_INT_SourceFlagGet • PLIB_INT_SourceFlagSet • PLIB_INT_SourceFlagClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SourceFlag feature is supported on the device • false - The SourceFlag feature is not supported on the device Remarks None. 5.6.11.6.5.17 PLIB_INT_ExistsTrapSource Function C bool PLIB_INT_ExistsTrapSource( INT_MODULE_ID index ); Description This function identifies whether the TrapSource feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_TrapSourceFlagGet • PLIB_INT_TrapSourceFlagClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TrapSource feature is supported on the device • false - The TrapSource feature is not supported on the device Remarks None. 5.6.11.6.5.18 PLIB_INT_ExistsVectorPriority Function C bool PLIB_INT_ExistsVectorPriority( INT_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2248 ); Description This function identifies whether the VectorPriority feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_VectorPrioritySet • PLIB_INT_VectorPriorityGet • PLIB_INT_VectorSubPrioritySet • PLIB_INT_VectorSubPriorityGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The VectorPriority feature is supported on the device • false - The VectorPriority feature is not supported on the device Remarks None. 5.6.11.6.5.19 PLIB_INT_ExistsVectorSelect Function C bool PLIB_INT_ExistsVectorSelect( INT_MODULE_ID index ); Description This function identifies whether the VectorSelect feature is available on the Interrupt Controller module. When this function returns true, these functions are supported on the device: • PLIB_INT_MultiVectorSelect • PLIB_INT_SingleVectorSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The VectorSelect feature is supported on the device • false - The VectorSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2249 5.6.11.7 Files Files Name Description plib_int.h Defines the Interrupt Peripheral Library interface Description 5.6.11.7.1 plib_int.h Interrupt Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Interrupt Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Interrupt Controller module. Functions Name Description PLIB_INT_AlternateVectorTableSelect Enables the use of the alternate vector table. PLIB_INT_CPUCurrentPriorityLevelGet Gets the interrupt priority level at which the CPU is currently operating. PLIB_INT_Disable Disables the generation of interrupts to the CPU. PLIB_INT_DISIStatusGet Returns the status of the DISI instruction status. PLIB_INT_Enable Enables the generation of interrupts to the CPU. PLIB_INT_ExistsAlternateVectorTable Identifies whether the AlternateVectorTable feature exists on the Interrupt Controller module. PLIB_INT_ExistsCPUCurrentPriorityLevel Identifies whether the CPUCurrentPriorityLevel feature exists on the Interrupt Controller module. PLIB_INT_ExistsEnableControl Identifies whether the EnableControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsExternalINTEdgeSelect Identifies whether the ExternalINTEdgeSelect feature exists on the Interrupt Controller module. PLIB_INT_ExistsHighPriority Identifies whether the HighPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTCPUPriority Identifies whether the INTCPUPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTCPUVector Identifies whether the INTCPUVector feature exists on the Interrupt Controller module. PLIB_INT_ExistsINTNesting Identifies whether the INTNesting feature exists on the Interrupt Controller module. PLIB_INT_ExistsLowPriority Identifies whether the LowPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsPeripheralControl Identifies whether the PeripheralControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsPriority Identifies whether the Priority feature exists on the Interrupt Controller module. PLIB_INT_ExistsProximityTimerControl Identifies whether the ProximityTimerControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsProximityTimerEnable Identifies whether the ProximityTimerEnable feature exists on the Interrupt Controller module. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2250 PLIB_INT_ExistsSingleVectorShadowSet Identifies whether the SingleVectorShadowSet feature exists on the Interrupt Controller module. PLIB_INT_ExistsSourceControl Identifies whether the SourceControl feature exists on the Interrupt Controller module. PLIB_INT_ExistsSourceFlag Identifies whether the SourceFlag feature exists on the Interrupt Controller module. PLIB_INT_ExistsTrapSource Identifies whether the TrapSource feature exists on the Interrupt Controller module. PLIB_INT_ExistsVectorPriority Identifies whether the VectorPriority feature exists on the Interrupt Controller module. PLIB_INT_ExistsVectorSelect Identifies whether the VectorSelect feature exists on the Interrupt Controller module. PLIB_INT_ExternalFallingEdgeSelect Selects the falling edge as the edge polarity of the external interrupt. PLIB_INT_ExternalRisingEdgeSelect Selects the rising edge as the edge polarity of the external interrupt. PLIB_INT_IsEnabled Identifies if interrupts are currently enabled or disabled at the top level. PLIB_INT_MultiVectorSelect Configures the Interrupt Controller for Multiple Vector mode. PLIB_INT_NestingDisable Disables interrupt nesting. PLIB_INT_NestingEnable Enables interrupt nesting. PLIB_INT_PeripheralsDisable Disables the generation of interrupts to the CPU by the peripherals. PLIB_INT_PeripheralsEnable Enables the generation of interrupts to the CPU by the peripherals. PLIB_INT_PriorityDisable Disables interrupt priority levels. PLIB_INT_PriorityEnable Enables interrupt priority levels. PLIB_INT_PriorityGet Returns the priority level of the latest interrupt presented to the CPU. PLIB_INT_PriorityHighDisable Disables the generation of high-priority interrupts to the CPU. PLIB_INT_PriorityHighEnable Enables the generation of high-priority interrupts to the CPU. PLIB_INT_PriorityLowDisable Disables the generation of low-priority interrupts to the CPU. PLIB_INT_PriorityLowEnable Enables generation of low-priority interrupts to the CPU. PLIB_INT_ProximityTimerDisable Disables the interrupt temporal-proximity timer. PLIB_INT_ProximityTimerEnable Enables the interrupt temporal-proximity timer and selects the priority levels that start the timer. PLIB_INT_ProximityTimerGet Returns the value used by the temporal proximity timer as a reload value when the temporal proximity timer is triggered by an interrupt event. PLIB_INT_ProximityTimerSet Sets the temporal proximity timer reload value. This value is used to reload the proximity timer after it has been triggered by an interrupt event. PLIB_INT_SingleVectorSelect Configures the Interrupt Controller for Single Vector mode. PLIB_INT_SingleVectorShadowSetDisable Disables the Shadow Register Set in Single Vector mode. PLIB_INT_SingleVectorShadowSetEnable Enables the Shadow Register Set in Single Vector mode. PLIB_INT_SourceDisable Disables the interrupt source PLIB_INT_SourceEnable Enables the interrupt source. This section provides information on initialization and interrupt source setup and handling. PLIB_INT_SourceFlagClear Clears the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagGet Returns the status of the interrupt flag for the selected source. PLIB_INT_SourceFlagSet Sets the status of the interrupt flag for the selected source. PLIB_INT_SourceIsEnabled Gets the enable state of the interrupt source. PLIB_INT_StandardVectorTableSelect Enables the use of the standard vector table. 5.6 Peripheral Library Help MPLAB Harmony Help Interrupt Peripheral Library 5-2251 PLIB_INT_TrapSourceFlagClear Clears the flag for the selected trap. PLIB_INT_TrapSourceFlagGet Returns the status of the flag for the selected trap. PLIB_INT_VectorGet Returns the interrupt vector that is presented to the CPU. PLIB_INT_VectorPriorityGet Gets the priority of the interrupt vector. PLIB_INT_VectorPrioritySet Sets the priority of the interrupt vector. PLIB_INT_VectorSubPriorityGet Gets the sub-priority of the interrupt vector. PLIB_INT_VectorSubPrioritySet Sets the sub-priority of the interrupt vector. File Name plib_int.h Company Microchip Technology Inc. 5.6.12 NVM Peripheral Library 5.6.12.1 Introduction NVM Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Non-Volatile Memory (NVM)component (Flash) on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description Flash Program Memory The Flash program memory is readable, writeable and erasable during normal operation over the entire operating voltage range. A read from program memory is executed at one byte/word at a time depending on the width of the data bus. A write to the program memory is executed in either blocks of specific sizes or a single word depending on the type of processor used. An erase is performed in blocks. A bulk erase may be performed from user code depending on the type of processor supporting the operation. Writing or erasing program memory will cease instruction fetches until the operation is complete thus restricting memory access and therefore preventing code execution. This is controlled by an internal programming timer. There are three processor dependant methods for program memory modification. • Run-Time Self Programming (RTSP) • In-Circuit Serial Programming (ICSP) • EJTAG programming 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2252 Note: This topic covers the RTSP techniques. 5.6.12.2 Release Notes MPLAB Harmony Version: v0.70b NVM Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.12.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.12.4 Using the Library This topic describes the basic architecture of the NVM Peripheral Library and provides information and examples on how to use it. Interface Header File: peripheral.h The interface to the NVM library is defined in the "plib_nvm.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the NVM library must include "peripheral.h". Library File: The NVM peripheral library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6.12.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the NVM module on the Microchip family of microcontrollers with a convenient C 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2253 language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Abstraction Model The NVM Peripheral Library provides interface routines to interact with the blocks shown in the diagram. NVM Software Abstraction Block Diagram The Flash Status and Control logic ensures that the Flash memory is configured appropriately for modification. It also provides the status of the different operations in progress as well as errors, if any. It also decides if the operation is for Flash program memory or the special device Configuration registers. The Flash Read/Write block ensures that the user data is written to/read from the program memory holding latches. It provides a layer of abstraction over the sequence of processor specific instructions which are required to access this data. Depending on the processor type, either block or Word programming options are available. 5.6.12.4.2 Library Usage Model The topic describes the major components of the usage model. Description Each of the blocks in the diagram correspond to the library interface section. Usage Model Library Interface Section Description Flash Configuration Provides setup, configuration and status control interface routines for Flash program memory. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2254 Flash Read/Write Provides bytewise, pagewise and blockwise Memory access along with NVM keysequence interface routines. 5.6.12.4.3 How the Library Works The usage model for this library is explained in the following sections. 5.6.12.4.3.1 State Machine The following state machine is for the NVM Read and Write during the normal operation. This state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. NVM Write and Read State Machine State Associated Function Setup and Initialization Refer to mode of NVM for detailed instructions of setup. Select Type of memory Once the NVM has been appropriately set up and initialized, the state machine waits for the application to select the type of memory to be accessed Flash program memory or configuration registers. Configure and enable write/read Configures the registers and enables the write/read operation. Select Address The application provides the write/read address from which to access memory. Send Data/Read Data When the application is polling it can fill data/ read data into the internal holding registers and initiate write via PLIB_NVM_FlashWriteStart(NVM_ID_0). Read Error/Write Status The error/write status is available to the application via PLIB_NVM_FlashWriteCycleHasCompleted(NVM_ID_0) and other status APIs. Note: Refer to the mode used for the NVM for the setup and initialization steps. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2255 5.6.12.4.3.2 Flash Operations Note: Flash program memory operations vary across microcontrollers. Please refer to the specific device data sheet or related family reference manual section to determine which features are supported by the device in use. Flash Read Operation Setup 1. Provide the Flash program memory from which the data memory has to be read via the API PLIB_NVM_FlashRead(). This address is then updated in the respective address registers or the Table Pointers depending on the device. 2. Ensure the alignment of the address as specified by the specific device data sheet. 3. The size of the data read depends upon the microcontroller in use. For specific details please refer to the Family Reference manual. Example : Program Memory Read // Determine the address from which to read #define MY_FLASH_BASE_ADDRESS 0xA0007862 //Or any address in flash to read uint32_t address = MY_FLASH_BASE_ADDRESS; // The Data Available at the memory location size_t DataToBeRead; // where, MY_NVM_INSTANCE - is a specific instance of the hardware peripheral. // where, address - The address in the memory from which to read. DataToBeRead = PLIB_NVM_FlashRead(NVM_ID_0, address); 5.6.12.4.3.3 Miscellaneous Functions Note: Flash program memory operations vary across microcontrollers. Please refer to the specific device data sheet or related family reference manual to determine which features are supported by the device in use. This section will detail out a few niche and processor specific APIs provided by this library. Stop in Idle Mode The PLIB_NVM_StopInIdleEnable and PLIB_NVM_StopInIdleDisablex functions cater to this functionality.These functions ensure that Flash operations are discontinued in Idle mode. Low Voltage Detection The PLIB_NVM_LowVoltageIsDetected and PLIB_NVM_LowVoltageEventIsActive functions support low-voltage error detection and triggering of a low-voltage event. 5.6.12.4.4 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.12.4.5 Building the Library This section list the files that are available in the \src of the NVM driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2256 5.6.12.5 Library Interface Configuration and Status Functions Name Description PLIB_NVM_LowVoltageEventIsActive Provides low voltage detection status PLIB_NVM_LowVoltageIsDetected Provides low voltage error detection status PLIB_NVM_MemoryModifyEnable Allows write cycles to Flash/EEPROM PLIB_NVM_MemoryModifyInhibit Inhibits write cycles to Flash/EEPROM PLIB_NVM_MemoryOperationSelect Selects the operation to be performed on Flash/EEPROM memory. PLIB_NVM_StopInIdleDisable Continues Flash operation when device enters idle mode. PLIB_NVM_StopInIdleEnable Discontinues Flash operation when device enters idle mode. PLIB_NVM_WriteOperationHasTerminated This routine provides the status of the Flash/EEPROM write operation or sequence. Feature Existence Functions Name Description PLIB_NVM_ExistsAccessEnable Identifies whether the AccessEnableControl feature exists on the NVM module PLIB_NVM_ExistsAddressModifyControl Identifies whether the AddressModifyControl feature exists on the NVM module PLIB_NVM_ExistsBootPageWriteProtect Identifies whether the BootPageWriteProtect feature exists on the NVM module PLIB_NVM_ExistsEEPROMReadInitiate Identifies whether the EEPROMReadInitiate feature exists on the NVM module PLIB_NVM_ExistsFlashBankRegionSelect Identifies whether the FlashBankRegionSelect feature exists on the NVM module PLIB_NVM_ExistsFlashWPMemoryRangeProvide Identifies whether the FlashWPMemoryRangeProvide feature exists on the NVM module PLIB_NVM_ExistsKeySequence Identifies whether the KeySequence feature exists on the NVM module PLIB_NVM_ExistsLockBootSelect Identifies whether the LockBootSelect feature exists on the NVM module PLIB_NVM_ExistsLockPFMSelect Identifies whether the LockPFMSelect feature exists on the NVM module PLIB_NVM_ExistsLowVoltageError Identifies whether the LowVoltageError feature exists on the NVM module PLIB_NVM_ExistsLowVoltageStatus Identifies whether the LowVoltageStatus feature exists on the NVM module PLIB_NVM_ExistsMemoryModificationControl Identifies whether the MemoryModificationControl feature exists on the NVM module PLIB_NVM_ExistsOperationMode Identifies whether the OperationMode feature exists on the NVM module PLIB_NVM_ExistsProgramEraseOperation Identifies whether the ProgramEraseOperation feature exists on the NVM module PLIB_NVM_ExistsProvideData Identifies whether the ProvideData feature exists on the NVM module PLIB_NVM_ExistsProvideQuadData Identifies whether the ProvideQuadData feature exists on the NVM module 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2257 PLIB_NVM_ExistsSourceAddress Identifies whether the SourceAddress feature exists on the NVM module PLIB_NVM_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the NVM module PLIB_NVM_ExistsWriteErrorStatus Identifies whether the WriteErrorStatus feature exists on the NVM module PLIB_NVM_ExistsWriteOperation Identifies whether the WriteOperation feature exists on the NVM module Flash Memory Functions Name Description PLIB_NVM_DataBlockSourceAddress Takes the address parameter in the argument and loads the base address from which data has to be copied into flash. PLIB_NVM_FlashAccessEnable Allows access to the Flash program memory PLIB_NVM_FlashAddressToModify Takes the address parameter in the argument and loads the address which will be modified by the actual write operation to the appropriate pointer registers . PLIB_NVM_FlashEraseOperationSelect For ERASE and FREE PLIB_NVM_FlashEraseStart Initiates a Program memory erase/write cycle PLIB_NVM_FlashProvideData Provides the user data to intermediate registers before written into flash PLIB_NVM_FlashProvideQuadData Provides low voltage detection status PLIB_NVM_FlashRead Takes the address parameter in the argument and loads the read address to the appropriate register and returns the value read. PLIB_NVM_FlashWriteCycleHasCompleted This routine provides the status of the Flash/EEPROM write cycle. PLIB_NVM_FlashWriteKeySequence Copies the mandatory KEY sequence into the respective registers. PLIB_NVM_FlashWriteOperationSelect Performs erase operation on the memory row selected PLIB_NVM_FlashWriteProtectMemoryAreaRange Provides low voltage detection status PLIB_NVM_FlashWriteStart Initiates a Program memory erase/write cycle PLIB_NVM_IsProgramFlashMemoryLocked Provides low voltage detection status PLIB_NVM_ProgramFlashBank1LowerRegion Provides low voltage detection status PLIB_NVM_ProgramFlashBank2LowerRegion Provides low voltage detection status Other Functions Name Description PLIB_NVM_BootPageWriteProtectionDisable Provides low voltage detection status PLIB_NVM_BootPageWriteProtectionEnable Provides low voltage detection status PLIB_NVM_IsBootMemoryLocked Provides low voltage detection status PLIB_NVM_IsBootPageWriteProtected Provides low voltage detection status PLIB_NVM_LockBootMemory Provides low voltage detection status PLIB_NVM_LockProgramFlashMemory Provides low voltage detection status Description This section describes the Application Programming Interface (API) functions of the NVM Peripheral Library. Refer to each section for detailed descriptions. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2258 5.6.12.5.1 Configuration and Status Functions 5.6.12.5.1.1 PLIB_NVM_LowVoltageEventIsActive Function C bool PLIB_NVM_LowVoltageEventIsActive( NVM_MODULE_ID index ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.1.2 PLIB_NVM_LowVoltageIsDetected Function C bool PLIB_NVM_LowVoltageIsDetected( NVM_MODULE_ID index ); Description This routine provides detection of low voltage error status Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage detection and possible data corruption 0 - Voltage Level Acceptable for programming. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2259 Example bool status; status = PLIB_NVM_LowVoltageIsDetected(MY_NVM_INSTANCE); 5.6.12.5.1.3 PLIB_NVM_MemoryModifyEnable Function C void PLIB_NVM_MemoryModifyEnable( NVM_MODULE_ID index ); Description This routine allows write cycles to Flash/EEPROM Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsMemoryModificationControl in your application to determine whether this feature is available. Example PLIB_NVM_MemoryModifyEnable(MY_NVM_INSTANCE); 5.6.12.5.1.4 PLIB_NVM_MemoryModifyInhibit Function C void PLIB_NVM_MemoryModifyInhibit( NVM_MODULE_ID index ); Description This routine Inhibits write cycles to Flash/EEPROM Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsMemoryModificationControl in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2260 Example PLIB_NVM_MemoryModifyInhibit(MY_NVM_INSTANCE); 5.6.12.5.1.5 PLIB_NVM_MemoryOperationSelect Function C void PLIB_NVM_MemoryOperationSelect( NVM_MODULE_ID index, NVM_OPERATION_MODE operationmode ); Description This routine selects the operation to be performed on Flash/EEPROM memory. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsOperationMode in your application to determine whether this feature is available. Example PLIB_NVM_MemoryOperationSelect(MY_NVM_INSTANCE, NVM_MEMORY_ROW_PROGRAM_OPERATION); 5.6.12.5.1.6 PLIB_NVM_StopInIdleDisable Function C void PLIB_NVM_StopInIdleDisable( NVM_MODULE_ID index ); Description This routine continues Flash operation when device enters idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsStopInIdle in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2261 Example PLIB_NVM_StopInIdleDisable(MY_NVM_INSTANCE, DataToWrite); 5.6.12.5.1.7 PLIB_NVM_StopInIdleEnable Function C void PLIB_NVM_StopInIdleEnable( NVM_MODULE_ID index ); Description This routine discontinues Flash operation when device enters idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsStopInIdle in your application to determine whether this feature is available. Example PLIB_NVM_StopInIdleEnable(MY_NVM_INSTANCE, DataToWrite); 5.6.12.5.1.8 PLIB_NVM_WriteOperationHasTerminated Function C bool PLIB_NVM_WriteOperationHasTerminated( NVM_MODULE_ID index ); Description This routine provides the status of the Flash/EEPROM write operation or sequence which was initiated by a write/erase operation. Preconditions The Address row to be erased must be provided earlier using PLIB_NVM_FlashAddressToModify(). The module should be configured to access Flash memory using PLIB_NVM_FlashMemoryAccessEnable(). A Write cycle must have been initiated via PLIB_NVM_EEPROMWriteInitiate(). Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Write operation prematurely terminated. 0 - Write operation completed. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2262 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteErrorStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_WriteOperationHasTerminated(MY_NVM_INSTANCE); 5.6.12.5.2 Flash Memory Functions 5.6.12.5.2.1 PLIB_NVM_DataBlockSourceAddress Function C void PLIB_NVM_DataBlockSourceAddress( NVM_MODULE_ID index, uint32_t address ); Description This routine takes the address parameter in the argument and loads the base address from which data has to be copied into flash. This is to copy a row of data directly into flash in one iteration without handling any intermediate holding registers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured address The starting address in the user date memory from which data will be written Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsSourceAddress in your application to determine whether this feature is available. Example uint32_t address = MY_RAM_BASE_ADDRESS; PLIB_NVM_DataBlockSourceAddress(MY_NVM_INSTANCE, address); 5.6.12.5.2.2 PLIB_NVM_FlashAccessEnable Function C void PLIB_NVM_FlashAccessEnable( NVM_MODULE_ID index ); Description This routine allows access to the Flash program memory Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2263 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsAccessEnable in your application to determine whether this feature is available. Example PLIB_NVM_FlashAccessEnable(MY_NVM_INSTANCE); 5.6.12.5.2.3 PLIB_NVM_FlashAddressToModify Function C void PLIB_NVM_FlashAddressToModify( NVM_MODULE_ID index, uint32_t address ); Description This routine takes the address parameter in the argument and loads the address which will be modified by the actual write operation. The write operation following this will write the user data into the program memory. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured address The starting address in the memory from which data will be written Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsAddressModifyControl in your application to determine whether this feature is available. Example uint32_t address = MY_FLASH_BASE_ADDRESS; PLIB_NVM_FlashAddressToModify(MY_NVM_INSTANCE, address); 5.6.12.5.2.4 PLIB_NVM_FlashEraseOperationSelect Function C void PLIB_NVM_FlashEraseOperationSelect( NVM_MODULE_ID index ); Description For ERASE and FREE 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2264 5.6.12.5.2.5 PLIB_NVM_FlashEraseStart Function C void PLIB_NVM_FlashEraseStart( NVM_MODULE_ID index ); Description This routine initiates the program memory erase or write cycles Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Example PLIB_NVM_FlashEraseStart(MY_NVM_INSTANCE, DataToWrite); 5.6.12.5.2.6 PLIB_NVM_FlashProvideData Function C void PLIB_NVM_FlashProvideData( NVM_MODULE_ID index, uint32_t data ); Description This routine provides the user data to intermediate registers before written into flash. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Data to be written. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsProvideData in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2265 Example uint32_t DataToWrite; PLIB_NVM_FlashProvideData(MY_NVM_INSTANCE, DataToWrite); 5.6.12.5.2.7 PLIB_NVM_FlashProvideQuadData Function C void PLIB_NVM_FlashProvideQuadData( NVM_MODULE_ID index, uint32_t * data ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.2.8 PLIB_NVM_FlashRead Function C uint32_t PLIB_NVM_FlashRead( NVM_MODULE_ID index, uint32_t address ); Description This routine takes the address parameter in the argument and loads the read address to the appropriate register. The read operation provides data from the above address. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured address The address in the memory from which to read Returns Data value read at the memory address. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2266 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Example uint32_t DataToBeRead; DataToBeRead = PLIB_NVM_FlashRead(MY_NVM_INSTANCE); 5.6.12.5.2.9 PLIB_NVM_FlashWriteCycleHasCompleted Function C bool PLIB_NVM_FlashWriteCycleHasCompleted( NVM_MODULE_ID index ); Description This routine provides the status of the Flash/EEPROM write cycle which was initiated by a write/erase operation. Preconditions The Address row to be erased must be provided earlier using PLIB_NVM_FlashAddressToModify(). The module should be configured to access Flash memory using PLIB_NVM_FlashMemoryAccessEnable(). A Write cycle must have been initiated via PLIB_NVM_EEPROMWriteInitiate(). Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Write/Erase Cycle is incomplete. 0 - Write cycle completed Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_FlashWriteCycleHasCompleted(MY_NVM_INSTANCE); 5.6.12.5.2.10 PLIB_NVM_FlashWriteKeySequence Function C void PLIB_NVM_FlashWriteKeySequence( NVM_MODULE_ID index, uint32_t keysequence ); Description This routine copies the mandatory KEY sequence into the respective registers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2267 keysequence Mandatory KEY sequence depending on the controller type Returns None. Remarks Without the KEY sequence write/erase operation will not be executed. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsKeySequence in your application to determine whether this feature is available. Example PLIB_NVM_FlashWriteKeySequence(MY_NVM_INSTANCE, keysequence); 5.6.12.5.2.11 PLIB_NVM_FlashWriteOperationSelect Function C void PLIB_NVM_FlashWriteOperationSelect( NVM_MODULE_ID index ); Description This routine Performs erase operation on the flash memory row selected Preconditions The Address row to be erased must be provided earlier using PLIB_NVM_FlashAddressToModify(). The module should be configured to access Flash memory using PLIB_NVM_FlashMemoryAccessEnable(). Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsProgramEraseOperation in your application to determine whether this feature is available. Example PLIB_NVM_FlashWriteOperationSelect(MY_NVM_INSTANCE); 5.6.12.5.2.12 PLIB_NVM_FlashWriteProtectMemoryAreaRange Function C void PLIB_NVM_FlashWriteProtectMemoryAreaRange( NVM_MODULE_ID index, uint32_t address ); Description This routine provides detection of low voltage event if any. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2268 Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.2.13 PLIB_NVM_FlashWriteStart Function C void PLIB_NVM_FlashWriteStart( NVM_MODULE_ID index ); Description This routine initiates the program memory erase or write cycles Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsWriteOperation in your application to determine whether this feature is available. Example PLIB_NVM_FlashWriteStart(MY_NVM_INSTANCE); 5.6.12.5.2.14 PLIB_NVM_IsProgramFlashMemoryLocked Function C bool PLIB_NVM_IsProgramFlashMemoryLocked( NVM_MODULE_ID index ); Description This routine provides detection of low voltage event if any. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2269 Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.2.15 PLIB_NVM_ProgramFlashBank1LowerRegion Function C void PLIB_NVM_ProgramFlashBank1LowerRegion( NVM_MODULE_ID index ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.2.16 PLIB_NVM_ProgramFlashBank2LowerRegion Function C void PLIB_NVM_ProgramFlashBank2LowerRegion( NVM_MODULE_ID index ); Description This routine provides detection of low voltage event if any. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2270 Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.3 Other Functions 5.6.12.5.3.1 PLIB_NVM_BootPageWriteProtectionDisable Function C void PLIB_NVM_BootPageWriteProtectionDisable( NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.3.2 PLIB_NVM_BootPageWriteProtectionEnable Function C void PLIB_NVM_BootPageWriteProtectionEnable( NVM_MODULE_ID index, NVM_BOOT_MEMORY_PAGE bootPage ); 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2271 Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.3.3 PLIB_NVM_IsBootMemoryLocked Function C bool PLIB_NVM_IsBootMemoryLocked( NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.3.4 PLIB_NVM_IsBootPageWriteProtected Function C bool PLIB_NVM_IsBootPageWriteProtected( NVM_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2272 NVM_BOOT_MEMORY_PAGE bootPage ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.3.5 PLIB_NVM_LockBootMemory Function C void PLIB_NVM_LockBootMemory( NVM_MODULE_ID index, NVM_BOOT_MEMORY_AREA memoryArea ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2273 5.6.12.5.3.6 PLIB_NVM_LockProgramFlashMemory Function C void PLIB_NVM_LockProgramFlashMemory( NVM_MODULE_ID index ); Description This routine provides detection of low voltage event if any. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Low Voltage Event active. 0 - Low Voltage Event not Active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_NVM_ExistsLowVoltageStatus in your application to determine whether this feature is available. Example bool status; status = PLIB_NVM_LowVoltageEventIsActive(MY_NVM_INSTANCE); 5.6.12.5.4 Feature Existence Functions 5.6.12.5.4.1 PLIB_NVM_ExistsAccessEnable Function C bool PLIB_NVM_ExistsAccessEnable( NVM_MODULE_ID index ); Description This function identifies whether the AccessEnableControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashAccessEnable • PLIB_NVM_EEPROMAccessEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AccessEnableControl feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2274 • false - The AccessEnableControl feature is not supported on the device Remarks None. 5.6.12.5.4.2 PLIB_NVM_ExistsAddressModifyControl Function C bool PLIB_NVM_ExistsAddressModifyControl( NVM_MODULE_ID index ); Description This function identifies whether the AddressModifyControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashAddressToModify • PLIB_NVM_EEPROMAddressToModify Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressModifyControl feature is supported on the device • false - The AddressModifyControl feature is not supported on the device Remarks None. 5.6.12.5.4.3 PLIB_NVM_ExistsBootPageWriteProtect Function C bool PLIB_NVM_ExistsBootPageWriteProtect( NVM_MODULE_ID index ); Description This function identifies whether the BootPageWriteProtect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_BootPageWriteProtectionEnable • PLIB_NVM_BootPageWriteProtectionDisable • PLIB_NVM_IsBootPageWriteProtected Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2275 Returns • true - The BootPageWriteProtect feature is supported on the device • false - The BootPageWriteProtect feature is not supported on the device Remarks None. 5.6.12.5.4.4 PLIB_NVM_ExistsEEPROMReadInitiate Function C bool PLIB_NVM_ExistsEEPROMReadInitiate( NVM_MODULE_ID index ); Description This function identifies whether the EEPROMReadInitiate feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_EEPROMReadStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EEPROMReadInitiate feature is supported on the device • false - The EEPROMReadInitiate feature is not supported on the device Remarks None. 5.6.12.5.4.5 PLIB_NVM_ExistsFlashBankRegionSelect Function C bool PLIB_NVM_ExistsFlashBankRegionSelect( NVM_MODULE_ID index ); Description This function identifies whether the FlashBankRegionSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_ProgramFlashBank1LowerRegion • PLIB_NVM_ProgramFlashBank2LowerRegion Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2276 Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashBankRegionSelect feature is supported on the device • false - The FlashBankRegionSelect feature is not supported on the device Remarks None. 5.6.12.5.4.6 PLIB_NVM_ExistsFlashWPMemoryRangeProvide Function C bool PLIB_NVM_ExistsFlashWPMemoryRangeProvide( NVM_MODULE_ID index ); Description This function identifies whether the FlashWPMemoryRangeProvide feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashWriteProtectMemoryAreaRange Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashWPMemoryRangeProvide feature is supported on the device • false - The FlashWPMemoryRangeProvide feature is not supported on the device Remarks None. 5.6.12.5.4.7 PLIB_NVM_ExistsKeySequence Function C bool PLIB_NVM_ExistsKeySequence( NVM_MODULE_ID index ); Description This function identifies whether the KeySequence feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashWriteKeySequence • PLIB_NVM_EEPROMWriteKeySequence 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2277 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The KeySequence feature is supported on the device • false - The KeySequence feature is not supported on the device Remarks None. 5.6.12.5.4.8 PLIB_NVM_ExistsLockBootSelect Function C bool PLIB_NVM_ExistsLockBootSelect( NVM_MODULE_ID index ); Description This function identifies whether the LockBootSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_LockBootMemory • PLIB_NVM_IsBootMemoryLocked Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LockBootSelect feature is supported on the device • false - The LockBootSelect feature is not supported on the device Remarks None. 5.6.12.5.4.9 PLIB_NVM_ExistsLockPFMSelect Function C bool PLIB_NVM_ExistsLockPFMSelect( NVM_MODULE_ID index ); Description This function identifies whether the LockPFMSelect feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2278 • PLIB_NVM_LockProgramFlashMemory • PLIB_NVM_IsProgramFlashMemoryLocked Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LockPFMSelect feature is supported on the device • false - The LockPFMSelect feature is not supported on the device Remarks None. 5.6.12.5.4.10 PLIB_NVM_ExistsLowVoltageError Function C bool PLIB_NVM_ExistsLowVoltageError( NVM_MODULE_ID index ); Description This function identifies whether the LowVoltageStatus feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_LowVoltageIsDetected Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LowVoltageStatus feature is supported on the device • false - The LowVoltageStatus feature is not supported on the device Remarks None. 5.6.12.5.4.11 PLIB_NVM_ExistsLowVoltageStatus Function C bool PLIB_NVM_ExistsLowVoltageStatus( NVM_MODULE_ID index ); Description This function identifies whether the LowVoltageStatus feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2279 • PLIB_NVM_LowVoltageEventIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LowVoltageStatus feature is supported on the device • false - The LowVoltageStatus feature is not supported on the device Remarks None. 5.6.12.5.4.12 PLIB_NVM_ExistsMemoryModificationControl Function C bool PLIB_NVM_ExistsMemoryModificationControl( NVM_MODULE_ID index ); Description This function identifies whether the MemoryModificationControl feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_MemoryModifyEnable • PLIB_NVM_MemoryModifyInhibit Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MemoryModificationControl feature is supported on the device • false - The MemoryModificationControl feature is not supported on the device Remarks None. 5.6.12.5.4.13 PLIB_NVM_ExistsOperationMode Function C bool PLIB_NVM_ExistsOperationMode( NVM_MODULE_ID index ); Description This function identifies whether the OperationMode feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2280 • PLIB_NVM_MemoryOperationSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Remarks None. 5.6.12.5.4.14 PLIB_NVM_ExistsProgramEraseOperation Function C bool PLIB_NVM_ExistsProgramEraseOperation( NVM_MODULE_ID index ); Description This function identifies whether the ProgramEraseOperation feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashEraseOperationSelect • PLIB_NVM_FlashWriteOperationSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ProgramEraseOperation feature is supported on the device • false - The ProgramEraseOperation feature is not supported on the device Remarks None. 5.6.12.5.4.15 PLIB_NVM_ExistsProvideData Function C bool PLIB_NVM_ExistsProvideData( NVM_MODULE_ID index ); Description This function identifies whether the ProvideData feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2281 • PLIB_NVM_FlashProvideData • PLIB_NVM_EEPROMProvideData Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ProvideData feature is supported on the device • false - The ProvideData feature is not supported on the device Remarks None. 5.6.12.5.4.16 PLIB_NVM_ExistsProvideQuadData Function C bool PLIB_NVM_ExistsProvideQuadData( NVM_MODULE_ID index ); Description This function identifies whether the ProvideQuadData feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashProvideQuadData Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ProvideQuadData feature is supported on the device • false - The ProvideQuadData feature is not supported on the device Remarks None. 5.6.12.5.4.17 PLIB_NVM_ExistsSourceAddress Function C bool PLIB_NVM_ExistsSourceAddress( NVM_MODULE_ID index ); Description This function identifies whether the SourceAddress feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2282 • PLIB_NVM_DataBlockSourceAddress Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SourceAddress feature is supported on the device • false - The SourceAddress feature is not supported on the device Remarks None. 5.6.12.5.4.18 PLIB_NVM_ExistsStopInIdle Function C bool PLIB_NVM_ExistsStopInIdle( NVM_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_StopInIdleEnable • PLIB_NVM_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.12.5.4.19 PLIB_NVM_ExistsWriteErrorStatus Function C bool PLIB_NVM_ExistsWriteErrorStatus( NVM_MODULE_ID index ); Description This function identifies whether the WriteErrorStatus feature is available on the NVM module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2283 • PLIB_NVM_WriteOperationHasTerminated Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteErrorStatus feature is supported on the device • false - The WriteErrorStatus feature is not supported on the device Remarks None. 5.6.12.5.4.20 PLIB_NVM_ExistsWriteOperation Function C bool PLIB_NVM_ExistsWriteOperation( NVM_MODULE_ID index ); Description This function identifies whether the WriteOperation feature is available on the NVM module. When this function returns true, these functions are supported on the device: • PLIB_NVM_FlashRead • PLIB_NVM_EEPROMRead • PLIB_NVM_FlashWriteStart • PLIB_NVM_FlashEraseStart • PLIB_NVM_EEPROMWriteStart • PLIB_NVM_EEPROMEraseStart • PLIB_NVM_FlashWriteCycleHasCompleted Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteOperation feature is supported on the device • false - The WriteOperation feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2284 5.6.12.6 Files Files Name Description plib_nvm.h NVM PLIB Interface Header for NVM common definitions Description 5.6.12.6.1 plib_nvm.h NVM Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the NVM PLIB for all families of Microchip microcontrollers..The definitions in this file are common to NVM peripheral. Functions Name Description PLIB_NVM_BootPageWriteProtectionDisable Provides low voltage detection status PLIB_NVM_BootPageWriteProtectionEnable Provides low voltage detection status PLIB_NVM_DataBlockSourceAddress Takes the address parameter in the argument and loads the base address from which data has to be copied into flash. PLIB_NVM_ExistsAccessEnable Identifies whether the AccessEnableControl feature exists on the NVM module PLIB_NVM_ExistsAddressModifyControl Identifies whether the AddressModifyControl feature exists on the NVM module PLIB_NVM_ExistsBootPageWriteProtect Identifies whether the BootPageWriteProtect feature exists on the NVM module PLIB_NVM_ExistsEEPROMReadInitiate Identifies whether the EEPROMReadInitiate feature exists on the NVM module PLIB_NVM_ExistsFlashBankRegionSelect Identifies whether the FlashBankRegionSelect feature exists on the NVM module PLIB_NVM_ExistsFlashWPMemoryRangeProvide Identifies whether the FlashWPMemoryRangeProvide feature exists on the NVM module PLIB_NVM_ExistsKeySequence Identifies whether the KeySequence feature exists on the NVM module PLIB_NVM_ExistsLockBootSelect Identifies whether the LockBootSelect feature exists on the NVM module PLIB_NVM_ExistsLockPFMSelect Identifies whether the LockPFMSelect feature exists on the NVM module PLIB_NVM_ExistsLowVoltageError Identifies whether the LowVoltageError feature exists on the NVM module PLIB_NVM_ExistsLowVoltageStatus Identifies whether the LowVoltageStatus feature exists on the NVM module PLIB_NVM_ExistsMemoryModificationControl Identifies whether the MemoryModificationControl feature exists on the NVM module PLIB_NVM_ExistsOperationMode Identifies whether the OperationMode feature exists on the NVM module 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2285 PLIB_NVM_ExistsProgramEraseOperation Identifies whether the ProgramEraseOperation feature exists on the NVM module PLIB_NVM_ExistsProvideData Identifies whether the ProvideData feature exists on the NVM module PLIB_NVM_ExistsProvideQuadData Identifies whether the ProvideQuadData feature exists on the NVM module PLIB_NVM_ExistsSourceAddress Identifies whether the SourceAddress feature exists on the NVM module PLIB_NVM_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the NVM module PLIB_NVM_ExistsWriteErrorStatus Identifies whether the WriteErrorStatus feature exists on the NVM module PLIB_NVM_ExistsWriteOperation Identifies whether the WriteOperation feature exists on the NVM module PLIB_NVM_FlashAccessEnable Allows access to the Flash program memory PLIB_NVM_FlashAddressToModify Takes the address parameter in the argument and loads the address which will be modified by the actual write operation to the appropriate pointer registers . PLIB_NVM_FlashEraseOperationSelect For ERASE and FREE PLIB_NVM_FlashEraseStart Initiates a Program memory erase/write cycle PLIB_NVM_FlashProvideData Provides the user data to intermediate registers before written into flash PLIB_NVM_FlashProvideQuadData Provides low voltage detection status PLIB_NVM_FlashRead Takes the address parameter in the argument and loads the read address to the appropriate register and returns the value read. PLIB_NVM_FlashWriteCycleHasCompleted This routine provides the status of the Flash/EEPROM write cycle. PLIB_NVM_FlashWriteKeySequence Copies the mandatory KEY sequence into the respective registers. PLIB_NVM_FlashWriteOperationSelect Performs erase operation on the memory row selected PLIB_NVM_FlashWriteProtectMemoryAreaRange Provides low voltage detection status PLIB_NVM_FlashWriteStart Initiates a Program memory erase/write cycle PLIB_NVM_IsBootMemoryLocked Provides low voltage detection status PLIB_NVM_IsBootPageWriteProtected Provides low voltage detection status PLIB_NVM_IsProgramFlashMemoryLocked Provides low voltage detection status PLIB_NVM_LockBootMemory Provides low voltage detection status PLIB_NVM_LockProgramFlashMemory Provides low voltage detection status PLIB_NVM_LowVoltageEventIsActive Provides low voltage detection status PLIB_NVM_LowVoltageIsDetected Provides low voltage error detection status PLIB_NVM_MemoryModifyEnable Allows write cycles to Flash/EEPROM PLIB_NVM_MemoryModifyInhibit Inhibits write cycles to Flash/EEPROM PLIB_NVM_MemoryOperationSelect Selects the operation to be performed on Flash/EEPROM memory. PLIB_NVM_ProgramFlashBank1LowerRegion Provides low voltage detection status PLIB_NVM_ProgramFlashBank2LowerRegion Provides low voltage detection status PLIB_NVM_StopInIdleDisable Continues Flash operation when device enters idle mode. PLIB_NVM_StopInIdleEnable Discontinues Flash operation when device enters idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help NVM Peripheral Library 5-2286 PLIB_NVM_WriteOperationHasTerminated This routine provides the status of the Flash/EEPROM write operation or sequence. 5.6.13 Output Compare Peripheral Library 5.6.13.1 Introduction Output Compare Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Output Compare Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The Output Compare module is primarily used to generate a single pulse or a series of pulses in response to selected time base events. Output Compare module operation essentially requires a timer and one or two compare values. Users have an option to select either a 32-bit timer or a 16-bit timer. The timer can be programmed to count at a desired frequency and count up to a desired period value. Details regarding timer operation and setup can be found in the Timer Peripheral Library. The Output Compare module compares the value of the timer with the compare values depending on the selected operating mode. When a compare match occurs between a timer value and compare values, the Output Compare module outputs a change of state on its output pins in accordance with the chosen Output Compare compare mode logic. Either a single pulse or a sequence of pulses may be generated. Some of the key operating modes of the OC module are: • Single Compare Set High/Low modes: In these compare modes, a compare match between the timer and the buffer (primary compare value) sets the output High/Low. The output remains at the same state after compare match event unless the module is disabled or the mode is changed. • Single Compare Toggle mode: Output toggles state at every compare match event between the timer and the buffer (primary compare value) • Dual compare Single/Continuous Pulse modes: These modes require two compare values. Leading edge of output pulse is generated during compare match of the incrementing timer and the buffer (primary compare value). Trailing edge of output pulse results when a compare match occurs between the incrementing timer and the pulse width value (secondary compare value). The output may be a single pulse or a sequence of pulses. • Pulse-Width Modulation (PWM) modes: In this mode, output goes high when a compare match occurs between timer and the pulse width value (duty cycle). The output is reset back to its initial state when the timer resets after attaining its maximum count. The Output Compare module also provides programmable interrupt generation on a compare match event. In PWM mode, hardware-based Fault detection and automatic output disable features are provided. Figure 1 shows a block diagram of the Output Compare module. A compare match between the timer value and the compare values generates a pulse at the output. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2287 Figure 1: Output Compare Module Block Diagram Figure 2 shows a block diagram of the Output Compare module with dedicated timers, present on some devices. It facilitates the use of multiple Output Compare modules operating synchronously or the use of an asynchronous trigger to generate a pulse. Figure 2: Output Compare Module Block Diagram with Dedicated Timers 5.6.13.2 Release Notes MPLAB Harmony Version: v0.70b Output Compare Peripheral Library Version :0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2288 5.6.13.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.13.4 Using the Library This topic describes the basic architecture of the Output Compare Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_oc.h The interface to the Output Compare Peripheral library is defined in the "plib_oc.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the Output Compare Peripheral Library should include "peripheral.h". Library File: The Output Compare Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the Peripheral interacts with the framework. 5.6.13.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the Output Compare module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all the functionality of the available Output Compare modules on the device. Refer to the specific device data sheet or related family reference manual section to determine the set of functions that are supported for each Output Compare module on your device. Description The Output Compare Peripheral Library is used to simplify low-level access to the Output Compare module without having the need to directly interact the module's registers. The function names are generic and lead to easier access to the Output Compare module on different devices. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2289 Figure 3: Output Compare module Software Abstraction Block Diagram The Output Compare module can be described from a software standpoint as having functions to configure the module itself, to select the timer, set the buffer and pulse width values, and select the mode of operation. The desired nature of the output pulse is thus obtained. A 16-bit or a 32-bit timer can be selected for the output compare time base. In some devices, the Output Compare module can be synchronized to an external input source. The Output Compare module can also operate asynchronously, based on a trigger by an input source. The Output Compare module entails the use of some functions dealing with Timer set up. These details can be found in Timer Peripheral Library. Functions have been provided to set buffer values and pulse-width values. Pulse-width values are used only in Dual compare and PWM modes. In PWM mode, the buffer value provides the initial duty cycle for the first time period, while all later time cycles employ the 'pulse-width' value as the duty cycle value. Compare modes: • Single Compare Level Mode: Sets the output of Output Compare module at either 'High' or 'Low' at a compare match event • Single Compare Toggle Mode: Toggles the output of OC module at each compare match event. This mode will produce continuous pulses. • Dual Compare Mode: Output Compare module output is driven 'High' on compare match with buffer value and driven 'Low' on a compare match with the pulse-width value. The output can be either a single pulse or a continuous stream of pulses. • PWM Mode: In Edge-aligned PWM mode, the Output Compare module output is driven 'High' whenever the timer resets, and is driven 'Low' on a compare match with the pulse-width value. Faults may or may not be enabled. In Center-aligned PWM mode, the Output Compare module output is driven 'High' on a compare match with the buffer value and driven 'Low' on a compare match with the pulse-width value. Note: In PWM mode, it is vital that the user selects the mode of operation before selecting a Fault input. 5.6.13.4.2 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2290 All of the interface functions in this library are classified according to: • General Setup: These routines deal with general setup of Output Compare module • Compare/PWM Mode: These routines facilitate the selection of a Compare/PWM mode and setting up the compare values • Timer: These functions deal with configuring the timer, selection of the clock source, and setting up a synchronous or asynchronous mode of operation for the OC module • Power-Saving Modes: • Sleep Mode: The Output Compare module output is driven to the same state as it was in prior to the device entering Sleep mode. In PWM Fault mode, Fault detection is active. A Fault forces output of the OC module to tri-state or to a fixed predetermined state. • Idle Mode: The Output Compare module can be configured to suspend its operations or continue its operations. If the Output Compare module suspends its operations, it has the same behavior as it does in Sleep mode. • Faults: These functions are used to select Fault inputs and identify occurrences of Faults when the Output Compare module functions in PWM mode • Exists: These functions notify whether or not a particular feature is present on a device The following sections provide examples that depict the use of interface functions to perform general tasks such as initialization and set up of the Output Compare module and setting up the Output Compare module in different compare modes. 5.6.13.4.2.1 Single Compare Set High Mode The Single Compare Set High mode sets the output of the Output Compare module 'High' at a compare match event. This section illustrates the steps required to configure the Output Compare module in Single Compare Set High mode. Example: /* This example illustrates setting up Output Compare Module in Single Compare Set High mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as timebase */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_SET_HIGH_SINGLE_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set buffer value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /* Configure interrupts associated with Output Compare module. Refer to Timer Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable the Output Compare module */ PLIB_OC_Enable(MY_OC_ID); 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2291 5.6.13.4.2.2 Single Compare Toggle Mode The Single Compare Toggle mode toggles the output of the Output Compare module at each compare match event. This section illustrates the steps required to configure the Output Compare module in Single Compare Toggle mode. Example: /* This example illustrates setting up Output Compare Module in Single Compare Toggle mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as timebase */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_TOGGLE_CONTINOUS_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set Buffer Value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable Output Compare module */ PLIB_OC_Enable(MY_OC_ID); 5.6.13.4.2.3 Dual Compare Continuous Mode In this mode, the Output Compare module output is driven 'High' on a compare match with the buffer value and driven 'Low' on a compare match with the pulse-width value. A continuous stream of pulses is generated. This section illustrates the steps required to configure the Output Compare module in Dual Compare Continuous Pulse mode. Example: /* This example illustrates setting up Output Compare Module in Dual Compare Continuous Pulse mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as timebase */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode */ PLIB_OC_ModeSelect(MY_OC_ID, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE); /* Set buffer size to 16-bits */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2292 /* Set buffer(primary compare) value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /*Set pulse width(secondary compare) value */ PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable the Output Compare module */ PLIB_OC_Enable(MY_OC_ID); 5.6.13.4.2.4 PWM Mode with Enabled Faults This section illustrates the steps required to configure the Output Compare module in PWM mode. Note: In PWM mode, it is vital that the user selects the mode of operation before selecting a Fault input. Example: /* This example illustrates setting up Output Compare Module in Dual Compare Continuous Pulse mode */ /* Configure Timer2 in 16-bit mode. Refer to Timer Peripheral Library for the API */ /* Disable OC module */ PLIB_OC_Disable(MY_OC_ID); /* Select Timer2 as timebase */ PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); /* Set period of time base. Refer to Timer Peripheral Library for the API */ /* Select compare mode. PWM Edge aligned mode is selected */ PLIB_OC_ModeSelect(MY_OC_ID, OC_COMPARE_PWM_EDGE_ALIGNED_MODE ); /* Select Fault input. In Output Compare modules that do not have dedicated timers, fault selection is preset in hardware */ PLIB_OC_FaultInputSelect(MY_OC_ID, OC_FAULT_PRESET); /* Set buffer size to 16-bits. Refer to Timer Peripheral Library for the API */ PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_16BIT); /* Set buffer (initial duty cycle) Value */ PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); /*Set pulse width (Duty cycle) value */ PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); /* Configure interrupts associated with Output Compare module. Refer to Interrupts Peripheral Library for the API */ /* Enable Timer2. Refer to Timer Peripheral Library for the API */ /* Enable OC module */ PLIB_OC_Enable(MY_OC_ID); /* Check for PWM Fault */ while(!PLIB_OC_FaultHasOccurred) { /* If no PWM fault, continue normal operation*/ } 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2293 5.6.13.4.3 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.13.5 Library Interface Data Types and Constants Name Description OC_16BIT_TIMERS Lists different 16 bit time bases for OC module OC_BUFFER_SIZE Lists different buffer sizes for compare value OC_CLOCK_RESOLUTION Lists different PWM resolutions for PWM mode and OC output falling edge delay for compare modes OC_COMPARE_MODES Lists different compare modes for OC module OC_FAULT_MODES Lists modes to clear fault mode OC_FAULT_OUT Provides state of OC output pin when a fault occurs OC_FAULT_TRISTATE Lists modes to clear fault mode OC_FAULTS Lists different fault sources for OC module OC_MODULE_ID OC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. OC_SYNC_MODES Lists different synchronization modes for OC module OC_SYNC_SOURCES Lists different synchronization sources for OC module OC_TRIGGER_STATUS_MODES Lists different trigger status reset modes for OC module Compare Mode Functions Name Description PLIB_OC_Buffer16BitSet Sets a 16-bit primary compare value for compare operations. PLIB_OC_Buffer32BitSet Sets a 32-bit primary compare value for compare operations. PLIB_OC_BufferSizeSelect Sets the buffer size and pulse width to 16-bits or 32-bits. PLIB_OC_PulseWidth16BitSet Sets a 16-bit pulse width for OC module output. PLIB_OC_PulseWidth32BitSet Sets a 32-bit pulse width for OC module output. PLIB_OC_PWMDutyCycleResolutionSet Sets the PWM duty cycle resolution and delays the falling edge of OC output in compare modes. Faults Functions Name Description PLIB_OC_FaultHasOccurred Checks if a PWM fault has occurred. PLIB_OC_FaultInputSelect Selects a Fault input for the OC module. PLIB_OC_FaultModeSelect Selects an automatic or software-based mode to clear the Fault. PLIB_OC_FaultOutSelect OC output pin is driven to a known state on a Fault. PLIB_OC_FaultTristateSelect The OC module output can be tristated or driven to a known state when a Fault occurs. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2294 Feature Existence Functions Name Description PLIB_OC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the OC module PLIB_OC_ExistsBufferSize Identifies whether the BufferSize feature exists on the OC module. PLIB_OC_ExistsBufferValue Identifies whether the BufferValue feature exists on the OC module. PLIB_OC_ExistsCompareModeSelect Identifies whether the CompareModeSelect feature exists on the OC module. PLIB_OC_ExistsEnableControl Identifies whether the EnableControl feature exists on the OC module. PLIB_OC_ExistsFaultInput Identifies whether the FaultInput feature exists on the OC module. PLIB_OC_ExistsFaultModeSelect Identifies whether the FaultModeSelect feature exists on the OC module. PLIB_OC_ExistsFaultOutSelect Identifies whether the FaultOut feature exists on the OC module. PLIB_OC_ExistsFaultStatus Identifies whether the FaultStatus feature exists on the OC module. PLIB_OC_ExistsFaultTristateSelect Identifies whether the FaultTristateSelect feature exists on the OC module. PLIB_OC_ExistsPolarityInvert Identifies whether the PolarityInvert feature exists on the OC module. PLIB_OC_ExistsPulseWidth Identifies whether the PulseWidth feature exists on the OC module. PLIB_OC_ExistsPWMDutyCycleResolutionControl Identifies whether the PWMDutyCycleResolution feature exists on the OC module. PLIB_OC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the OC module. PLIB_OC_ExistsSyncModeSelect Identifies whether the SyncModeSelect feature exists on the OC module. PLIB_OC_ExistsSyncSourceSelect Identifies whether the SyncSourceSelect feature exists on the OC module. PLIB_OC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the OC module. PLIB_OC_ExistsTimerTriggered Identifies whether the TimerTriggered feature exists on the OC module. PLIB_OC_ExistsTriggerControl Identifies whether the TriggerControl feature exists on the OC module. PLIB_OC_ExistsTriggerStatusModeSelect Identifies whether the TriggerStatusModeSelect feature exists on the OC module. General Setup Functions Name Description PLIB_OC_Disable Disable the OC module PLIB_OC_Enable Enables the OC module. PLIB_OC_ModeSelect Selects the compare mode for the OC module. PLIB_OC_PolarityInvertedDisable Disables OC module output inversion polarity. PLIB_OC_PolarityInvertedEnable Output compare polarity is inverted. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2295 Power-Saving Modes Functions Name Description PLIB_OC_StopInIdleDisable OC module continues operating when the device enters Idle mode PLIB_OC_StopInIdleEnable Discontinues OC module operation when the device enters Idle mode Timer Functions Name Description PLIB_OC_IsTriggered Checks whether or not a timer source has been triggered. PLIB_OC_SyncModeSelect Selects the synchronization mode for the OC module. PLIB_OC_SyncSourceSelect Selects the input source for synchronous or asynchronous (triggered) operation of the OC module. PLIB_OC_TimerSelect Selects a clock source for the OC module. PLIB_OC_TriggerClear Clears the trigger status for the OC module. PLIB_OC_TriggerSet Sets the trigger status for the OC module. PLIB_OC_TriggerStatusModeSelect Selects the trigger status reset mode. PLIB_OC_AlternateClockDisable Selects Timer 2/3.instead of the alternate clock source. PLIB_OC_AlternateClockEnable Selects the alternate clock source. Description 5.6.13.5.1 General Setup Functions 5.6.13.5.1.1 PLIB_OC_Disable Function C void PLIB_OC_Disable( OC_MODULE_ID index ); Description This function disables the OC module. Preconditions None. Parameters Parameters Description index Identifies the OC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsEnableControl in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2296 PLIB_OC_Disable(MY_OC_ID); 5.6.13.5.1.2 PLIB_OC_Enable Function C void PLIB_OC_Enable( OC_MODULE_ID index ); Description This function enables the OC module. Preconditions The module should be appropriately configured before being enabled. Parameters Parameters Description index Identifies the desired OC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsEnableControl in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 //Do all the other configurations before enabling. PLIB_OC_Enable(MY_OC_ID); 5.6.13.5.1.3 PLIB_OC_ModeSelect Function C void PLIB_OC_ModeSelect( OC_MODULE_ID index, OC_COMPARE_MODES cmpMode ); Description This function selects the compare mode for the OC module. Preconditions The OC module must be turned off before a new mode is selected. The OC module is turned off via PLIB_OC_ModeSelect(MY_OC_ID,OC_COMPARE_TURN_OFF_MODE) Parameters Parameters Description index Identifies the desired OC module cmpMode Identifies the compare mode for OC module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2297 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsCompareModeSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Dual compare continuous pulse mode is selected PLIB_OC_ModeSelect(MY_OC_ID, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE ); 5.6.13.5.1.4 PLIB_OC_PolarityInvertedDisable Function C void PLIB_OC_PolarityInvertedDisable( OC_MODULE_ID index ); Description This function disables polarity inversion of OC module output. Preconditions None. Parameters Parameters Description index Identifies the desired OC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPolarityInvert in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Polarity of OC module output is Non-inverted PLIB_OC_PolarityInvertedDisable(OC_MODULE_ID index); 5.6.13.5.1.5 PLIB_OC_PolarityInvertedEnable Function C void PLIB_OC_PolarityInvertedEnable( OC_MODULE_ID index ); Description This function inverts the polarity of the OC module output. Preconditions None. Parameters Parameters Description index Identifies the desired OC module 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2298 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPolarityInvert in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Invert polarity of OC module output PLIB_OC_PolarityInvertedEnable(MY_OC_ID); 5.6.13.5.2 Compare Mode Functions 5.6.13.5.2.1 PLIB_OC_Buffer16BitSet Function C void PLIB_OC_Buffer16BitSet( OC_MODULE_ID index, uint16_t val16Bit ); Description This function sets a 16-bit primary compare value for compare operations in all modes except PWM modes. Preconditions The PWM mode of operation should not be selected. The buffer size should be set to 16-bits by the PLIB_OC_BufferSizeSelect() function. Parameters Parameters Description index Identifies the desired OC module val16Bit Sets a 16-bit primary compare value Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferValue in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_Buffer16BitSet(MY_OC_ID, 0x00FF); 5.6.13.5.2.2 PLIB_OC_Buffer32BitSet Function C void PLIB_OC_Buffer32BitSet( OC_MODULE_ID index, uint32_t val32Bit ); 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2299 Description This function sets a 32-bit primary compare value for compare operations in all modes except PWM modes. Preconditions The PWM mode of operation should not be selected. The buffer size should be set to 32-bits by the PLIB_OC_BufferSizeSelect() function. Parameters Parameters Description index Identifies the desired OC module val32Bit Sets a 32-bit primary compare value Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferValue in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_Buffer32BitSet(MY_OC_ID, 0x000000FF); 5.6.13.5.2.3 PLIB_OC_BufferSizeSelect Function C void PLIB_OC_BufferSizeSelect( OC_MODULE_ID index, OC_BUFFER_SIZE size ); Description This function sets the size of the buffer and pulse width to 16-bits or 32-bits. The choice is made based on whether a 16-bit timer or a 32-bit timer is selected. Preconditions None. Parameters Parameters Description index Identifies the desired OC module size Identifies the size of compare value Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsBufferSize in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Buffer size and pulse width size are set to 32-bits 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2300 PLIB_OC_BufferSizeSelect(MY_OC_ID, OC_BUFFER_SIZE_32BIT); 5.6.13.5.2.4 PLIB_OC_PulseWidth16BitSet Function C void PLIB_OC_PulseWidth16BitSet( OC_MODULE_ID index, uint16_t pulseWidth ); Description This function sets a 16-bit pulse width for the OC module in dual compare modes. A dual compare mode can be selected using the PLIB_OC_ModeSelect() function. Secondary compare match event (pulse width) decides the trailing (falling) edge of the OC module output. Preconditions Dual compare operation should be selected. The buffer size should be set to 16-bits by the PLIB_OC_BufferSizeSelect() function. Parameters Parameters Description index Identifies the desired OC module pulseWidth Pulse width value Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPulseWidth in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_PulseWidth16BitSet(MY_OC_ID, 0x0FFF); 5.6.13.5.2.5 PLIB_OC_PulseWidth32BitSet Function C void PLIB_OC_PulseWidth32BitSet( OC_MODULE_ID index, uint32_t pulseWidth ); Description This function sets a 32-bit pulse width for OC module in dual compare modes. A dual compare mode can be selected using PLIB_OC_ModeSelect() routine. Secondary compare match event (pulse width) decides the trailing(falling) edge of OC module output. Preconditions Dual compare operation should be selected. The buffer size should be set to 32-bits by the PLIB_OC_BufferSizeSelect() function. Parameters Parameters Description index Identifies the desired OC module pulseWidth Pulse width value 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2301 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPulseWidth in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_PulseWidth32BitSet(MY_OC_ID, 0x00000FFF); 5.6.13.5.2.6 PLIB_OC_PWMDutyCycleResolutionSet Function C void PLIB_OC_PWMDutyCycleResolutionSet( OC_MODULE_ID index, OC_CLOCK_RESOLUTION clkResolution ); Description This function sets the PWM duty cycle resolution in PWM mode and delays the falling edge of OC output in compare modes. Preconditions Dual compare mode must be selected for this function. Parameters Parameters Description index Identifies the desired OC module clkResolution Select clock resolution Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsPWMDutyCycleResolutionControl in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_PWMDutyCycleResolutionSet(MY_OC_ID,OC_CLOCK_P1); 5.6.13.5.3 Timer Functions 5.6.13.5.3.1 PLIB_OC_IsTriggered Function C bool PLIB_OC_IsTriggered( OC_MODULE_ID index ); Description This function checks whether Output Compare timer has been triggered or not. This function returns 'true' if OC timer is triggered 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2302 and running and 'false' if the OC timer is cleared and stopped. Preconditions None. Parameters Parameters Description index Identifies the desired OC module Returns bool - true - OC timer is triggered and running • false - OC timer is stopped and held in clear Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTimerTriggered in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 if(!PLIB_OC_IsTriggered(MY_OC_ID)) { // Do some operation }; 5.6.13.5.3.2 PLIB_OC_SyncModeSelect Function C void PLIB_OC_SyncModeSelect( OC_MODULE_ID index, OC_SYNC_MODES mode ); Description This function selects the synchronization mode for Othe OC module. The Synchronous or Asynchronous mode of operation can be selected. Preconditions If Asynchronous mode is selected and an OC trigger is selected, that OC module must be disabled first before enabling the trigger functionality. Parameters Parameters Description index Identifies the desired OC module mode Identifies the mode (Synchronous or Asynchronous) Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsSyncModeSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Synchronous mode of operation is selected. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2303 PLIB_OC_SyncModeSelect(MY_OC_ID, OC_MODE_SYNC); 5.6.13.5.3.3 PLIB_OC_SyncSourceSelect Function C void PLIB_OC_SyncSourceSelect( OC_MODULE_ID index, OC_SYNC_SOURCES src ); Description This function selects the input source for synchronous or asynchronous (triggered) operation of the OC module. Preconditions If an OC trigger is selected, that OC module must be disabled before it is configured to be used as a trigger to the next OC module. Parameters Parameters Description index Identifies the desired OC module src Identifies the input source Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsSyncSourceSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 //Input Capture is selected as the input source PLIB_OC_SyncSourceSelect(MY_OC_ID, OC_SYNC_SOURCE_IC6); 5.6.13.5.3.4 PLIB_OC_TimerSelect Function C void PLIB_OC_TimerSelect( OC_MODULE_ID index, OC_16BIT_TIMERS tmr ); Description This function selects a clock source for the OC module if the 16-bit time base is set. Preconditions The 16-bit time base needs to be set. Parameters Parameters Description index Identifies the desired OC module tmr Identifies the timer Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2304 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTimerSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // 16-bit Timer2 is selected PLIB_OC_TimerSelect(MY_OC_ID, OC_TIMER_16BIT_TMR2); 5.6.13.5.3.5 PLIB_OC_TriggerClear Function C void PLIB_OC_TriggerClear( OC_MODULE_ID index ); Description This function clears the trigger status for the OC module. Preconditions Dual compare mode must be selected for this function. Parameters Parameters Description index Identifies the desired OC module Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTriggerControl in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_TriggerClear(MY_OC_ID); 5.6.13.5.3.6 PLIB_OC_TriggerSet Function C void PLIB_OC_TriggerSet( OC_MODULE_ID index ); Description This function sets the trigger status for the OC module. Preconditions Dual compare mode must be selected for this function. Parameters Parameters Description index Identifies the desired OC module 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2305 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTriggerControl in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_TriggerSet(MY_OC_ID); 5.6.13.5.3.7 PLIB_OC_TriggerStatusModeSelect Function C void PLIB_OC_TriggerStatusModeSelect( OC_MODULE_ID index, OC_TRIGGER_STATUS_MODES modes ); Description This function lets the user to reset the trigger status via software or a compare match. Preconditions None. Parameters Parameters Description index Identifies the desired OC module modes Identifies the trigger status reset mode Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsTriggerStatusModeSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 //Trigger status is reset by compare match PLIB_OC_TriggerStatusModeSelect(MY_OC_ID, OC_TRIGGER_STATUS_MATCH); 5.6.13.5.3.8 PLIB_OC_AlternateClockDisable Function C void PLIB_OC_AlternateClockDisable( OC_MODULE_ID index ); Description Selects Timer 2/3.instead of the alternate clock source. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2306 Parameters Parameters Description index Identifies the desired OC module Returns None. Remarks The feature is not supported on all devices. Check your device's data sheet. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the OC_MODULE_ID passed in the call. Example // Call system service to unlock oscillator #define MY_OC_ID OC_ID_1 PLIB_OC_AlternateClockDisable( MY_OC_ID ); 5.6.13.5.3.9 PLIB_OC_AlternateClockEnable Function C void PLIB_OC_AlternateClockEnable( OC_MODULE_ID index ); Description Selects the alternate clock source instead of Timer 2/3. Preconditions None. Parameters Parameters Description index Identifies the desired OC module Returns None. Remarks The feature is not supported on all devices. Check your device's data sheet. A system unlock must be performed before this function can be executed. This function applies to all input capture modules, regardless of the OC_MODULE_ID passed in the call. Example // Call system service to unlock oscillator #define MY_OC_ID OC_ID_1 PLIB_OC_AlternateClockEnable( MY_OC_ID ); 5.6.13.5.4 Power-Saving Modes Functions 5.6.13.5.4.1 PLIB_OC_StopInIdleDisable Function C void PLIB_OC_StopInIdleDisable( 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2307 OC_MODULE_ID index ); Description The function continues OC module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired OC module Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_StopInIdleDisable(MY_OC_ID); 5.6.13.5.4.2 PLIB_OC_StopInIdleEnable Function C void PLIB_OC_StopInIdleEnable( OC_MODULE_ID index ); Description This function discontinues OC module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired OC module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 PLIB_OC_StopInIdleEnable(MY_OC_ID); 5.6.13.5.5 Faults Functions 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2308 5.6.13.5.5.1 PLIB_OC_FaultHasOccurred Function C bool PLIB_OC_FaultHasOccurred( OC_MODULE_ID index ); Description This function returns 'true' if a PWM Fault has occurred and 'false' if no Fault condition exists. Preconditions This function should be used only in Edge or Center-Aligned PWM mode set by the PLIB_OC_ModeSelect() function. Parameters Parameters Description index Identifies the desired OC module Returns bool - true - PWM Fault has occurred • false - No PWM fault Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultStatus in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 if(!PLIB_OC_FaultHasOccurred(MY_OC_ID)) { // Do some operation }; 5.6.13.5.5.2 PLIB_OC_FaultInputSelect Function C void PLIB_OC_FaultInputSelect( OC_MODULE_ID index, OC_FAULTS flt ); Description This function selects a Fault input for the OC module. Preconditions Set the operation mode using PLIB_OC_ModeSelect() before selecting the Fault input. Parameters Parameters Description index Identifies the desired OC module flt Identifies the OC fault input Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2309 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultInput in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Fault B is enabled for Output Compare Module PLIB_OC_FaultInputSelect(MY_OC_ID, OC_FAULT_B); 5.6.13.5.5.3 PLIB_OC_FaultModeSelect Function C void PLIB_OC_FaultModeSelect( OC_MODULE_ID index, OC_FAULT_MODES modes ); Description This function selects a mode to clear the Fault mode. The Fault mode can be reset automatically or by software once the Fault source ceases to exist. Preconditions Set the operation mode using PLIB_OC_ModeSelect() routine before selecting the fault input. Parameters Parameters Description index Identifies the desired OC module modes Identifies the mode to reset Fault status Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultModeSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 // Fault mode is maintained even after fault ceases. Fault mode is reset in software. PLIB_OC_FaultModeSelect(MY_OC_ID, OC_SOFTWARE_CLEAR); 5.6.13.5.5.4 PLIB_OC_FaultOutSelect Function C void PLIB_OC_FaultOutSelect( OC_MODULE_ID index, OC_FAULT_OUT fltState ); Description This function sets OC output to a known state on occurrence of a Fault in Edge or Center-Aligned PWM modes. Preconditions Edge or Center-Aligned PWM mode with Faults enabled should be selected. OC module output tristate should be disabled on occurrence of a Fault via PLIB_OC_TriStateDisable(). 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2310 Parameters Parameters Description index Identifies the desired OC module fltState Identifies the high or low state to which the output is driven on a fault Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultOutSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 //PWM output is set to High on occurrence of fault PLIB_OC_FaultOutSelect(MY_OC_ID,OC_HIGH); 5.6.13.5.5.5 PLIB_OC_FaultTristateSelect Function C void PLIB_OC_FaultTristateSelect( OC_MODULE_ID index, OC_FAULT_TRISTATE tristateSel ); Description This function is used to enable or disable tristating of OC module outputs when a Fault occurs. Preconditions None. Parameters Parameters Description index Identifies the desired OC module tristateSel Enable/Disable Tristate Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OC_ExistsFaultTristateSelect in your application to determine whether this feature is available. Example #define MY_OC_ID OC_ID_1 //Tristate OC module output PLIB_OC_FaultTristateSelect(MY_OC_ID,OC_ENABLE_TRISTATE); 5.6.13.5.6 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2311 5.6.13.5.6.1 OC_16BIT_TIMERS Enumeration C typedef enum { OC_TIMER_16BIT_TMR2, OC_TIMER_16BIT_TMR3, OC_TIMER_16BIT_TMR4, OC_TIMER_16BIT_TMR5, OC_TIMER_16BIT_TMR1, OC_TIMER_PTG, OC_TIMER_PERIPHERAL_CLK } OC_16BIT_TIMERS; Description OC 16 bit Timer Select This enumeration lists different 16 bit time bases for OC module. The time base is set by PLIB_OC_TimerSelect() routine. Members Members Description OC_TIMER_16BIT_TMR2 Clock source of Timer2 is the clock source of OC module OC_TIMER_16BIT_TMR3 Clock source of Timer3 is the clock source of OC module OC_TIMER_16BIT_TMR4 Clock source of Timer4 is the clock source of OC module OC_TIMER_16BIT_TMR5 Clock source of Timer5 is the clock source of OC module OC_TIMER_16BIT_TMR1 Clock source of Timer1 is the clock source of OC module OC_TIMER_PTG Peripheral Trigger Generator output is the clock source for OC module OC_TIMER_PERIPHERAL_CLK Peripheral clock is the clock source for OC module 5.6.13.5.6.2 OC_BUFFER_SIZE Enumeration C typedef enum { OC_BUFFER_SIZE_16BIT, OC_BUFFER_SIZE_32BIT } OC_BUFFER_SIZE; Description OC Buffer Size This enumeration lists different buffer sizes for compare value. and duty cycle value. Members Members Description OC_BUFFER_SIZE_16BIT Buffer size is 16-bits. Duty cycle and compare values will have 16-bit values. OC_BUFFER_SIZE_32BIT Buffer size is 32-bits. Duty cycle and compare values will have 32-bit values. 5.6.13.5.6.3 OC_CLOCK_RESOLUTION Enumeration C typedef enum { OC_CLOCK_P1, OC_CLOCK_P2, OC_CLOCK_P3, OC_CLOCK_P4 } OC_CLOCK_RESOLUTION; 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2312 Description OC PWM Clock Resolution Lists different PWM resolutions in PWM mode and falling edge delay of Output Compare module output in compare modes. Members Members Description OC_CLOCK_P1 OC output falling edge transitionson rising edge of P1 clock OC_CLOCK_P2 OC output falling edge transitionson rising edge of P2 clock OC_CLOCK_P3 OC output falling edge transitionson rising edge of P3 clock OC_CLOCK_P4 OC output falling edge transitionson rising edge of P4 clock 5.6.13.5.6.4 OC_COMPARE_MODES Enumeration C typedef enum { OC_COMPARE_PWM_CENTER_ALIGNED_MODE, OC_COMPARE_PWM_EDGE_ALIGNED_MODE, OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE, OC_DUAL_COMPARE_SINGLE_PULSE_MODE, OC_TOGGLE_CONTINUOUS_PULSE_MODE, OC_SET_LOW_SINGLE_PULSE_MODE, OC_SET_HIGH_SINGLE_PULSE_MODE, OC_COMPARE_TURN_OFF_MODE } OC_COMPARE_MODES; Description OC Compare Modes This enumeration lists different compare modes for OC module. The compare mode is set by PLIB_OC_ModeSelect() routine. Members Members Description OC_COMPARE_PWM_CENTER_ALIGNED_MODE PWM center aligned mode: OC module output is a center aligned PWM signal OC_COMPARE_PWM_EDGE_ALIGNED_MODE PWM edge aligned mode: OC module output is an edge aligned PWM signal OC_DUAL_COMPARE_CONTINUOUS_PULSE_MODE Dual Compare, Continuous Pulse mode: OC module output is driven high on compare match with primary compare value and driven low on compare match with secondary compare value. A continuous stream of pulses is generated unless the compare mode is changed or the module is disabled. If the secondary compare value is greater than time base period value, secondary compare match does not occur. As a consequence, OC module output stays high. OC_DUAL_COMPARE_SINGLE_PULSE_MODE Dual Compare, Single Pulse mode: OC module output is driven high on compare match with primary compare value and driven low on compare match with secondary compare value. If the secondary compare value is greater than time base period value, secondary compare match does not occur. As a consequence, OC module output stays high until a mode change is made or module is disabled OC_TOGGLE_CONTINUOUS_PULSE_MODE Single Compare Toggle mode: OC module output is initialized to Low. OC module output toggles at every compare match event with primary compare value with a single peripheral bus clock cycle delay. This scheme generates a square wave with 50% duty cycle. An interrupt is generated each time the ouput toggles. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2313 OC_SET_LOW_SINGLE_PULSE_MODE Single Compare Set Low mode: A compare match event with primary compare value will set the output of OC module 'Low' with a single peripheral bus clock cycle delay. Output stays Low unless OC module is disabled or a new compare mode is chosen. An interrupt is generated at compare match event. OC module output is initially forced High. OC_SET_HIGH_SINGLE_PULSE_MODE Single Compare Set High mode: A compare match event with primary compare value will set the output of OC module 'High' with a single peripheral bus clock cycle delay. Output stays High unless OC module is disabled or a new compare mode is chosen. An interrupt is generated at compare match event. OC module output is initially forced Low. OC_COMPARE_TURN_OFF_MODE Turn OFF mode: OC module is disabled but still draws current. This mode is used to temporarily turn OFF the OC module before a new compare mode is selected 5.6.13.5.6.5 OC_FAULT_MODES Enumeration C typedef enum { OC_SOFTWARE_CLEAR, OC_AUTOMATIC_CLEAR } OC_FAULT_MODES; Description OC Fault Clear Modes This enumeration lists modes to clear fault mode after the fault source is removed. Members Members Description OC_SOFTWARE_CLEAR Fault mode needs to be cleared in software after the fault source is removed. OC_AUTOMATIC_CLEAR Fault mode is is cleared automatically once fault source is removed. 5.6.13.5.6.6 OC_FAULT_OUT Enumeration C typedef enum { OC_FAULT_LOW, OC_FAULT_HIGH } OC_FAULT_OUT; Description OC Fault Output State This enumeration lists different states of OC output pin when a fault occurs. Members Members Description OC_FAULT_LOW OC output is driven low when fault occurs. OC_FAULT_HIGH OC output is driven high when fault occurs. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2314 5.6.13.5.6.7 OC_FAULT_TRISTATE Enumeration C typedef enum { OC_DISABLE_TRISTATE, OC_ENABLE_TRISTATE } OC_FAULT_TRISTATE; Description OC Fault Output Tristate select This enumeration lists modes to clear fault mode after the fault source is removed. Members Members Description OC_DISABLE_TRISTATE OC module outputs are set in a known state on the occurrence of a fault OC_ENABLE_TRISTATE OC module outputs are tristated on the occurrence of a fault 5.6.13.5.6.8 OC_FAULTS Enumeration C typedef enum { OC_FAULT_A, OC_FAULT_B, OC_FAULT_C, OC_FAULT_PRESET, OC_FAULT_DISABLE } OC_FAULTS; Description OC Fault Select This enumeration lists different fault sources for OC module. The fault source is selected by PLIB_OC_CompareClockSelect() routine. Members Members Description OC_FAULT_A Fault A input OC_FAULT_B Fault B input OC_FAULT_C Fault C input OC_FAULT_PRESET Preset hardware fault input. This value is used for OC modules that have a preset hardware configured fault input selection. OC_FAULT_DISABLE Faults are disabled. PWM operation without faults. 5.6.13.5.6.9 OC_MODULE_ID Enumeration C typedef enum { OC_ID_1, OC_ID_2, OC_ID_3, OC_NUMBER_OF_MODULES } OC_MODULE_ID; 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2315 Description OC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on Microchip microcontrollers. Refer to the specific device data sheet to get the correct number of modules defined for the desired microcontroller. Members Members Description OC_NUMBER_OF_MODULES The total number of modules available. 5.6.13.5.6.10 OC_SYNC_MODES Enumeration C typedef enum { OC_MODE_TRIGGER, OC_MODE_SYNC } OC_SYNC_MODES; Description OC Synchronization modes Status This enumeration lists different synchronization modes for OC module timer. The timer can be made to operate synchronously with an external input or asynchronously on receiving an input trigger. Members Members Description OC_MODE_TRIGGER OC module is asynchronously triggered by a chosen trigger input source OC_MODE_SYNC OC module is synchronized to the input source 5.6.13.5.6.11 OC_SYNC_SOURCES Enumeration C typedef enum { OC_SYNC_SOURCE_NONE, OC_SYNC_SOURCE_OC1, OC_SYNC_SOURCE_OC2, OC_SYNC_SOURCE_OC3, OC_SYNC_SOURCE_OC4, OC_SYNC_SOURCE_OC5, OC_SYNC_SOURCE_OC6, OC_SYNC_SOURCE_OC7, OC_SYNC_SOURCE_OC8, OC_SYNC_SOURCE_OC9, OC_SYNC_SOURCE_PTG, OC_SYNC_SOURCE_TMR1, OC_SYNC_SOURCE_TMR2, OC_SYNC_SOURCE_TMR3, OC_SYNC_SOURCE_TMR4, OC_SYNC_SOURCE_TMR5, OC_SYNC_SOURCE_IC1, OC_SYNC_SOURCE_IC2, OC_SYNC_SOURCE_IC3, OC_SYNC_SOURCE_IC4, OC_SYNC_SOURCE_IC5, OC_SYNC_SOURCE_IC6, OC_SYNC_SOURCE_IC7, 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2316 OC_SYNC_SOURCE_IC8, OC_SYNC_SOURCE_CMP1, OC_SYNC_SOURCE_CMP2, OC_SYNC_SOURCE_CMP3, OC_SYNC_SOURCE_AD, OC_SYNC_SOURCE_CTMU, OC_SYNC_SOURCE_INT1, OC_SYNC_SOURCE_INT2 } OC_SYNC_SOURCES; Description OC Synchronization Sources This enumeration lists all the input sources for synchronous and asynchronously triggered operation. OC module timer can be synchronized to an input source or operate asynchronously on the receipt on an input trigger. The Input source can be selected by PLIB_OC_SyncSourceSelect() routine. Members Members Description OC_SYNC_SOURCE_NONE No synchronization and trigger input OC_SYNC_SOURCE_OC1 Synchronization and trigger input is Output Compare1 OC_SYNC_SOURCE_OC2 Synchronization and trigger input is Output Compare2 OC_SYNC_SOURCE_OC3 Synchronization and trigger input is Output Compare3 OC_SYNC_SOURCE_OC4 Synchronization and trigger input is Output Compare4 OC_SYNC_SOURCE_OC5 Synchronization and trigger input is Output Compare5 OC_SYNC_SOURCE_OC6 Synchronization and trigger input is Output Compare6 OC_SYNC_SOURCE_OC7 Synchronization and trigger input is Output Compare7 OC_SYNC_SOURCE_OC8 Synchronization and trigger input is Output Compare8 OC_SYNC_SOURCE_OC9 Synchronization and trigger input is Output Compare9 OC_SYNC_SOURCE_PTG Synchronization and trigger input is Peripheral Trigger Generator Module OC_SYNC_SOURCE_TMR1 Synchronization and trigger input is Timer1 OC_SYNC_SOURCE_TMR2 Synchronization and trigger input is Timer2 OC_SYNC_SOURCE_TMR3 Synchronization and trigger input is Timer3 OC_SYNC_SOURCE_TMR4 Synchronization and trigger input is Timer4 OC_SYNC_SOURCE_TMR5 Synchronization and trigger input is Timer5 OC_SYNC_SOURCE_IC1 Synchronization and trigger input is Input Capture1 OC_SYNC_SOURCE_IC2 Synchronization and trigger input is Input Capture2 OC_SYNC_SOURCE_IC3 Synchronization and trigger input is Input Capture3 OC_SYNC_SOURCE_IC4 Synchronization and trigger input is Input Capture4 OC_SYNC_SOURCE_IC5 Synchronization and trigger input is Input Capture5 OC_SYNC_SOURCE_IC6 Synchronization and trigger input is Input Capture6 OC_SYNC_SOURCE_IC7 Synchronization and trigger input is Input Capture7 OC_SYNC_SOURCE_IC8 Synchronization and trigger input is Input Capture8 OC_SYNC_SOURCE_CMP1 Trigger input is Comparator1. This input is not used for Synchronization OC_SYNC_SOURCE_CMP2 Trigger input is Comparator2. This input is not used for Synchronization OC_SYNC_SOURCE_CMP3 Trigger input is Comparator3. This input is not used for Synchronization OC_SYNC_SOURCE_AD Trigger input is ADC. This input is not used for Synchronization OC_SYNC_SOURCE_CTMU Trigger input is Charge Time Measurement Unit. This input is not used for Synchronization OC_SYNC_SOURCE_INT1 Synchronization and trigger input is External Interrupt1 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2317 OC_SYNC_SOURCE_INT2 Synchronization and trigger input is External Interrupt2 5.6.13.5.6.12 OC_TRIGGER_STATUS_MODES Enumeration C typedef enum { OC_TRIGGER_STATUS_MATCH, OC_TRIGGER_STATUS_SOFTWARE } OC_TRIGGER_STATUS_MODES; Description OC Trigger Status This enumeration lists different trigger status reset modes. Trigger status can be reset in software or by a compare match between timer value and pulse width value. Members Members Description OC_TRIGGER_STATUS_MATCH Trigger status is cleared on compare match between timer value and pulse width value OC_TRIGGER_STATUS_SOFTWARE Trigger status is cleared in software 5.6.13.5.7 Feature Existence Functions 5.6.13.5.7.1 PLIB_OC_ExistsAlternateClock Function C bool PLIB_OC_ExistsAlternateClock( OC_MODULE_ID index ); Description This function identifies whether the AlternateClock feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_AlternateClockEnable • PLIB_OC_AlternateClockDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlternateClock feature is supported on the device • false - The AlternateClock feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2318 5.6.13.5.7.2 PLIB_OC_ExistsBufferSize Function C bool PLIB_OC_ExistsBufferSize( OC_MODULE_ID index ); Description This function identifies whether the BufferSize feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_BufferSizeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the BufferSize feature is supported on the device • false - If the BufferSize feature is not supported on the device Remarks None. 5.6.13.5.7.3 PLIB_OC_ExistsBufferValue Function C bool PLIB_OC_ExistsBufferValue( OC_MODULE_ID index ); Description This function identifies whether the BufferValue feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_Buffer32BitSet • PLIB_OC_Buffer16BitSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the BufferValue feature is supported on the device • false - If the BufferValue feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2319 5.6.13.5.7.4 PLIB_OC_ExistsCompareModeSelect Function C bool PLIB_OC_ExistsCompareModeSelect( OC_MODULE_ID index ); Description This function identifies whether the CompareModeSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_ModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the CompareModeSelect feature is supported on the device • false - If the CompareModeSelect feature is not supported on the device Remarks None. 5.6.13.5.7.5 PLIB_OC_ExistsEnableControl Function C bool PLIB_OC_ExistsEnableControl( OC_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_Enable • PLIB_OC_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the EnableControl feature is supported on the device • false - If the EnableControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2320 5.6.13.5.7.6 PLIB_OC_ExistsFaultInput Function C bool PLIB_OC_ExistsFaultInput( OC_MODULE_ID index ); Description This function identifies whether the FaultInput feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultInputSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FaultInput feature is supported on the device • false - If the FaultInput feature is not supported on the device Remarks None. 5.6.13.5.7.7 PLIB_OC_ExistsFaultModeSelect Function C bool PLIB_OC_ExistsFaultModeSelect( OC_MODULE_ID index ); Description This function identifies whether the FaultModeSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FaultModeSelect feature is supported on the device • false - If the FaultModeSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2321 5.6.13.5.7.8 PLIB_OC_ExistsFaultOutSelect Function C bool PLIB_OC_ExistsFaultOutSelect( OC_MODULE_ID index ); Description This function identifies whether the FaultOut feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultOutSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FaultOut feature is supported on the device • false - If the FaultOut feature is not supported on the device Remarks None. 5.6.13.5.7.9 PLIB_OC_ExistsFaultStatus Function C bool PLIB_OC_ExistsFaultStatus( OC_MODULE_ID index ); Description This function identifies whether the FaultStatus feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FaultStatus feature is supported on the device • false - If the FaultStatus feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2322 5.6.13.5.7.10 PLIB_OC_ExistsFaultTristateSelect Function C bool PLIB_OC_ExistsFaultTristateSelect( OC_MODULE_ID index ); Description This function identifies whether the FaultTristateSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_FaultTristateSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FaultTristateSelect feature is supported on the device • false - If the FaultTristateSelect feature is not supported on the device Remarks None. 5.6.13.5.7.11 PLIB_OC_ExistsPolarityInvert Function C bool PLIB_OC_ExistsPolarityInvert( OC_MODULE_ID index ); Description This function identifies whether the PolarityInvert feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_PolarityInvertedEnable • PLIB_OC_PolarityInvertedDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PolarityInvert feature is supported on the device • false - If the PolarityInvert feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2323 5.6.13.5.7.12 PLIB_OC_ExistsPulseWidth Function C bool PLIB_OC_ExistsPulseWidth( OC_MODULE_ID index ); Description This function identifies whether the PulseWidth feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_PulseWidth32BitSet • PLIB_OC_PulseWidth16BitSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PulseWidth feature is supported on the device • false - If the PulseWidth feature is not supported on the device Remarks None. 5.6.13.5.7.13 PLIB_OC_ExistsPWMDutyCycleResolutionControl Function C bool PLIB_OC_ExistsPWMDutyCycleResolutionControl( OC_MODULE_ID index ); Description This function identifies whether the PWMDutyCycleResolution feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_PWMDutyCycleResolutionSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PWMDutyCycleResolution feature is supported on the device • false - If the PWMDutyCycleResolution feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2324 5.6.13.5.7.14 PLIB_OC_ExistsStopInIdle Function C bool PLIB_OC_ExistsStopInIdle( OC_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the OC module. When this function returns true, these functions are supported on the device: • PLIB_OC_StopInIdleEnable • PLIB_OC_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the StopInIdle feature is supported on the device • false - If the StopInIdle feature is not supported on the device Remarks None. 5.6.13.5.7.15 PLIB_OC_ExistsSyncModeSelect Function C bool PLIB_OC_ExistsSyncModeSelect( OC_MODULE_ID index ); Description This function identifies whether the SyncModeSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_SyncModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SyncModeSelect feature is supported on the device • false - If the SyncModeSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2325 5.6.13.5.7.16 PLIB_OC_ExistsSyncSourceSelect Function C bool PLIB_OC_ExistsSyncSourceSelect( OC_MODULE_ID index ); Description This function identifies whether the SyncSourceSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_SyncSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SyncSourceSelect feature is supported on the device • false - If the SyncSourceSelect feature is not supported on the device Remarks None. 5.6.13.5.7.17 PLIB_OC_ExistsTimerSelect Function C bool PLIB_OC_ExistsTimerSelect( OC_MODULE_ID index ); Description This function identifies whether the TimerSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_TimerSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TimerSelect feature is supported on the device • false - If the TimerSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2326 5.6.13.5.7.18 PLIB_OC_ExistsTimerTriggered Function C bool PLIB_OC_ExistsTimerTriggered( OC_MODULE_ID index ); Description This function identifies whether the TimerTriggered feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_IsTriggered Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TimerTriggered feature is supported on the device • false - If the TimerTriggered feature is not supported on the device Remarks None. 5.6.13.5.7.19 PLIB_OC_ExistsTriggerControl Function C bool PLIB_OC_ExistsTriggerControl( OC_MODULE_ID index ); Description This function identifies whether the TriggerControl feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_TriggerSet • PLIB_OC_TriggerClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TriggerControl feature is supported on the device • false - If the TriggerControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2327 5.6.13.5.7.20 PLIB_OC_ExistsTriggerStatusModeSelect Function C bool PLIB_OC_ExistsTriggerStatusModeSelect( OC_MODULE_ID index ); Description This function identifies whether the TriggerStatusModeSelect feature is available on the OC module. When this function returns true, this function is supported on the device: • PLIB_OC_TriggerStatusModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the TriggerStatusModeSelect feature is supported on the device • false - If the TriggerStatusModeSelect feature is not supported on the device Remarks None. 5.6.13.6 Files Files Name Description plib_oc.h This file contains the interface definition for the Output Compare (OC) peripheral library. Description 5.6.13.6.1 plib_oc.h Output Compare Module Peripheral Library Interface Header This library provides a low-level abstraction of the Output Compare module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences between one microcontroller variant and another. Functions Name Description PLIB_OC_AlternateClockDisable Selects Timer 2/3.instead of the alternate clock source. PLIB_OC_AlternateClockEnable Selects the alternate clock source. PLIB_OC_Buffer16BitSet Sets a 16-bit primary compare value for compare operations. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2328 PLIB_OC_Buffer32BitSet Sets a 32-bit primary compare value for compare operations. PLIB_OC_BufferSizeSelect Sets the buffer size and pulse width to 16-bits or 32-bits. PLIB_OC_Disable Disable the OC module PLIB_OC_Enable Enables the OC module. PLIB_OC_ExistsAlternateClock Identifies whether the AlternateClock feature exists on the OC module PLIB_OC_ExistsBufferSize Identifies whether the BufferSize feature exists on the OC module. PLIB_OC_ExistsBufferValue Identifies whether the BufferValue feature exists on the OC module. PLIB_OC_ExistsCompareModeSelect Identifies whether the CompareModeSelect feature exists on the OC module. PLIB_OC_ExistsEnableControl Identifies whether the EnableControl feature exists on the OC module. PLIB_OC_ExistsFaultInput Identifies whether the FaultInput feature exists on the OC module. PLIB_OC_ExistsFaultModeSelect Identifies whether the FaultModeSelect feature exists on the OC module. PLIB_OC_ExistsFaultOutSelect Identifies whether the FaultOut feature exists on the OC module. PLIB_OC_ExistsFaultStatus Identifies whether the FaultStatus feature exists on the OC module. PLIB_OC_ExistsFaultTristateSelect Identifies whether the FaultTristateSelect feature exists on the OC module. PLIB_OC_ExistsPolarityInvert Identifies whether the PolarityInvert feature exists on the OC module. PLIB_OC_ExistsPulseWidth Identifies whether the PulseWidth feature exists on the OC module. PLIB_OC_ExistsPWMDutyCycleResolutionControl Identifies whether the PWMDutyCycleResolution feature exists on the OC module. PLIB_OC_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the OC module. PLIB_OC_ExistsSyncModeSelect Identifies whether the SyncModeSelect feature exists on the OC module. PLIB_OC_ExistsSyncSourceSelect Identifies whether the SyncSourceSelect feature exists on the OC module. PLIB_OC_ExistsTimerSelect Identifies whether the TimerSelect feature exists on the OC module. PLIB_OC_ExistsTimerTriggered Identifies whether the TimerTriggered feature exists on the OC module. PLIB_OC_ExistsTriggerControl Identifies whether the TriggerControl feature exists on the OC module. PLIB_OC_ExistsTriggerStatusModeSelect Identifies whether the TriggerStatusModeSelect feature exists on the OC module. PLIB_OC_FaultHasOccurred Checks if a PWM fault has occurred. PLIB_OC_FaultInputSelect Selects a Fault input for the OC module. PLIB_OC_FaultModeSelect Selects an automatic or software-based mode to clear the Fault. PLIB_OC_FaultOutSelect OC output pin is driven to a known state on a Fault. PLIB_OC_FaultTristateSelect The OC module output can be tristated or driven to a known state when a Fault occurs. 5.6 Peripheral Library Help MPLAB Harmony Help Output Compare Peripheral Library 5-2329 PLIB_OC_IsTriggered Checks whether or not a timer source has been triggered. PLIB_OC_ModeSelect Selects the compare mode for the OC module. PLIB_OC_PolarityInvertedDisable Disables OC module output inversion polarity. PLIB_OC_PolarityInvertedEnable Output compare polarity is inverted. PLIB_OC_PulseWidth16BitSet Sets a 16-bit pulse width for OC module output. PLIB_OC_PulseWidth32BitSet Sets a 32-bit pulse width for OC module output. PLIB_OC_PWMDutyCycleResolutionSet Sets the PWM duty cycle resolution and delays the falling edge of OC output in compare modes. PLIB_OC_StopInIdleDisable OC module continues operating when the device enters Idle mode PLIB_OC_StopInIdleEnable Discontinues OC module operation when the device enters Idle mode PLIB_OC_SyncModeSelect Selects the synchronization mode for the OC module. PLIB_OC_SyncSourceSelect Selects the input source for synchronous or asynchronous (triggered) operation of the OC module. PLIB_OC_TimerSelect Selects a clock source for the OC module. PLIB_OC_TriggerClear Clears the trigger status for the OC module. PLIB_OC_TriggerSet Sets the trigger status for the OC module. PLIB_OC_TriggerStatusModeSelect Selects the trigger status reset mode. File Name plib_oc.h Company Microchip Technology Inc. 5.6.14 Oscillator Peripheral Library 5.6.14.1 Introduction Oscillator Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Oscillator module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Oscillator Overview The Oscillator is the heart of the microcontroller and provides the clock on which the core and the peripherals run. For all of the oscillators present on a Microchip microcontroller, two kinds of configurations exist: • Through Configuration bits • At execution time 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2330 The first is through 'Configuration bits', which is a one-time configuration done during the programming of the device. These one-time configurations are programmed in the code memory. The other is 'Execution time' configuration, which deals with features that are allowed to be changed during run-time. This peripheral library provides functions which deal only with the 'execution time' configurable features of the Oscillator module. Certain Oscillator module features can only be selected through 'Configuration bits'. However, most of the features can be altered during run-time by using the functions provided in this library. 5.6.14.2 Release Notes MPLAB Harmony Version: v0.70b Oscillator Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.14.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.14.4 Using the Library Using the Library This topic describes the basic architecture of the Oscillator Peripheral Library and provides information and examples on its use. Interface Header File: plib_osc.h The interface to the Oscillator Peripheral Library is defined in the "plib_osc.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Oscillator Peripheral Library must include "peripheral.h". 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2331 5.6.14.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Oscillator module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model The Oscillator hardware model is shown in the following figure. The blocks represented in dashed lines may not be present in all microcontrollers. Refer to the "Oscillator" chapter in the specific device data sheet to determine availability. To understand the Oscillator module and how each feature is mapped in this library, it is important to understand the following terminology. Clock Source A clock source is hardware that generates oscillations, which may be internal or external. Divisor and Multiplier/PLL These are hardware modules that can scale the clock. The rate at which the scaling is done may be fixed or configurable. Clock Outputs Clock outputs means output lines from the Oscillator module, which may route to different modules of the device or to the CPU (i.e., the system clock). The following diagram provides a simplified explanation and the relationship between the previously mentioned terms. In most cases, there are multiple clock source options available for each of the clock outputs. However, not all the clock sources are 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2332 available for all the output clocks. Scaling is an optional feature in most of the cases. 5.6.14.4.2 Library Usage Model The usage model for the Oscillator Peripheral Library is described in this section. Description The following diagram shows the major components of the usage model: Each of the blocks in the diagram above correspond to the library interface section. Library Interface Section Description 5.6.14.4.3 How the Library Works The library can be used to control the Oscillator module. The usage model is explained in this section. 5.6.14.4.3.1 Oscillator Selection and Switching Note: The device Configuration options change with the microcontroller family. Refer to the "Oscillator" chapter in the specific device data sheet for possible device configurations. On devices that allow it, the oscillator selection can be overridden at run-time using the Oscillator Peripheral Library, as shown in the following code example: //Do the configuration bit settings OSC_SYS_TYPE currOsc; OSC_SYS_TYPE newOsc=OSC_PRIMARY; //get the current oscillator currOsc = PLIB_OSC_CurrentSysClockGet(OSC_ID_0); //check if the current oscillator is same as new oscillator if(currOsc != newOsc) { //set the new oscillator request to Fast RC oscillator PLIB_OSC_SysClockSelect ( OSC_ID_0, newOsc ); } Example: Oscillator Selection Change During Run-time In the event the clock switch did not complete, the clock switch logic can be reset by calling the following API: bool oscSwitch_st; oscSwitch_st = PLIB_OSC_ClockSwitchingIsComplete(OSC_ID_0); if(!oscSwitch_st) { 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2333 PLIB_OSC_ClockSwitchingAbort(OSC_ID_0); } Note: This function takes care of the register unlock, which is required as per the device data sheet. Therefore, the user does not need to explicitly perform the unlock sequence. Example: Oscillator Switch Abort This will abandon the clock switch process, stop and reset the oscillator start-up timer (if applicable), and stop the PLL (if applicable). The clock switch process can be aborted at any time. A clock switch that is already in progress can also be aborted by performing a second clock switch. 5.6.14.4.3.2 Clock Sources This section explains the available clock sources and their setup. The following clock sources are available in Microchip microcontrollers: • Primary Oscillator (Posc) • Secondary Oscillator (Sosc) • Internal Fast RC (FRC) Oscillator • Internal Low-Power RC (LPRC) Oscillator Primary Oscillator (Posc) The Primary Oscillator has several operating modes (refer to the "Oscillator" chapter in the specific device data sheet for exact operating modes). The selection of the operating mode is done using the device Configuration registers during device programming. During run-time this can be changed using the oscillator switch option. However, changing the operating mode from High Gain (HC) to External Clock (EC) or External Resonator(XT) is not possible. If a PLL is available, the PLL input divider can only be programmed during device programming. However, the PLL output divider and the PLL multiplier can be changed during run-time using the PLL functions described in the PLL section. Secondary Oscillator (Sosc) The optional Secondary Oscillator is designed specifically for low-power operation with an external crystal. The Secondary Oscillator is enabled in hardware by the device Configuration bits. Once it is enabled in hardware, it can be switched on during software run-time. bool oscSecondary_st; oscSecondary_st = PLIB_OSC_SecondaryIsEnabled(OSC_ID_0); if(oscSecondary_st) { PLIB_OSC_SecondaryEnable(OSC_ID_0); } //Do something PLIB_OSC_SecondaryDisable(OSC_ID_0); Internal Fast RC (FRC) Oscillator The FRC Oscillator is a fast user-trimmable internal RC oscillator with a user-selectable input divider, PLL multiplier, and output divider. See the "Oscillator" chapter in the specific device data sheet for more information on the FRC oscillator. Once the FRC oscillator is selected using the device Configuration registers or an oscillator switch is initiated selecting the FRC as a new oscillator, the FRC Oscillator PLL divider can be changed during run-time. OSC_FRC_DIV FRCDivisor; //Get the current divider value for FRC 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2334 FRCDivisor = PLIB_OSC_FRCDivisorGet(OSC_ID_0); if(FRCDivisor != OSC_FRC_DIV_4) { PLIB_OSC_FRCDivisorSelect ( OSC_ID_0, OSC_FRC_DIV_4 ); } Internal Low-Power RC (LPRC) Oscillator The LPRC Oscillator is separate from the FRC Oscillator. It oscillates at a nominal frequency of 31.25 kHz (this value is device-dependent). The LPRC Oscillator can act as the clock source for the Power-up Timer (PWRT), Watchdog Timer (WDT), Fail-Safe Clock Monitor (FSCM), and PLL reference circuits. It can also be used to provide a low-frequency clock source option for the device in those applications where power consumption is critical and timing accuracy is not required. The LPRC remains enabled after power on in the following conditions: • Fail-safe clock monitoring is enabled • Watchdog Timer is enabled • LPRC is selected as the system clock PLL Configuration OSC_SYSPLL_OUT_DIV PLLOutDiv; OSC_SYSPLL_MULTIPLIER pll_multiply; pll_multiply = PLIB_OSC_SysPLLMultiplierGet(OSC_ID_0); if(pll_multiply != 15) { PLIB_OSC_SysPLLMultiplierSelect(OSC_ID_0, 15); } PLLOutDiv = PLIB_OSC_SysPLLOutputDivisorGet(OSC_ID_0); if(PLLOutDiv != OSC_SYSPLL_OUT_DIV_8) { PLIB_OSC_SysPLLOutputDivisorSelect(OSC_ID_0, OSC_SYSPLL_OUT_DIV_8); } 5.6.14.4.3.3 Fail-Safe Clock Monitor Fail-Safe Clock Monitor (FSCM) The Fail-Safe Clock Monitor (FSCM) is designed to allow continued device operation if the current oscillator fails. It is intended for use with the Primary Oscillator (Posc) and automatically switches to the FRC oscillator if a Posc failure is detected. The switch to the FRC oscillator allows continued device operation and the ability to retry the Posc or to execute the appropriate for a clock failure. The FSCM can be enabled in the device configuration during the programming of the device. During run-time, the clock failure status can be obtained as follows: bool clockFail; //Returns true if clock failure is detected. clockFail = PLIB_OSC_ClockHasFailed(OSC_ID_0); 5.6.14.4.3.4 Internal FRC Oscillator Tuning Tuning the Oscillator Oscillator tuning will help compensate for temperature effects on the FRC frequency over a wide range of temperatures. The tuning step size is an approximation, the application is supposed to try different values to achieve the best result. In some of the devices there are different tuning modes available. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2335 Direct Number Method FRC tuning is based on the number specified by the PLIB_OSC_FRCTuningSelect function. PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_USING_NUMBER); PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x11); Sequential Dithering To get the sequential dithering working, the client needs to set eight sequencer values. Value 0 is set using the PLIB_OSC_FRCTuningSelect function. The other seven values (values 1 through 7) are set using the PLIB_OSC_FRCTuningSequenceValueSet function. PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_SEQ_DITHER); PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x11); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_1, OSC_FRC_TUNE_MINUS_2_25_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_2, OSC_FRC_TUNE_MINUS_1_5_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_3, OSC_FRC_TUNE_MINUS_0_375_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_4, OSC_FRC_TUNE_PLUS_0_43_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_5, OSC_FRC_TUNE_PLUS_1_29_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_6, OSC_FRC_TUNE_PLUS_2_54_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_7, OSC_FRC_TUNE_MINUS_3_PERCENT); //Configure PWM (period, pulse width and turn on the module) Pseudo-Random Number Select the tuning mode. Then, configure the PWM module and set the period and pulse width. The Oscillator system generates a 4-bit number based on a pseudo-random number generation algorithm. It then uses this value to tune the FRC oscillator. The module will generate different frequencies corresponding to the generated pseudo-random numbers every eighth PWM cycle. PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_PSEUDO_RANDOM); //15 bit Linear Feedback shift register value PLIB_OSC_LinearFeedbackShiftRegSet(OSC_ID_0, 0x7FFF); //Configure PWM (period, pulse width and turn on the module) Note: This function takes care of the register unlock, which is required as per the device data sheet. Therefore, the user does not need to explicitly perform the unlock sequence. 5.6.14.5 Configuring the Library The library is configured for the supported oscillator modules when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2336 5.6.14.6 Library Interface Data Types and Constants Name Description OSC_PB_CLOCK_DIV_TYPE Type of the oscillator PB Clock divisor value. OSC_REF_DIVISOR_TYPE Reference oscillator divisor type. OSC_REFERENCE_MAX_DIV Defines the reference clock output divisor maximum value. OSC_SYSPLL_MULTIPLIER_TYPE Type of the oscillator system PLL multiplier value. OSC_AUX_CLOCK_SOURCE Lists the possible Auxiliary PLL input divider values. OSC_AUX_MODE Lists the possible Auxiliary Oscillator mode values. OSC_AUXPLL_IN_DIV Lists the possible Auxiliary PLL input divider values. OSC_AUXPLL_MULTIPLIER Lists the possible Auxiliary PLL multiplier OSC_AUXPLL_OUT_DIV Lists the possible Auxiliary PLL output divider values. OSC_DOZE_RATIO Lists the possible doze values. OSC_FRC_DIV Lists the possible Fast RC (FRC) Oscillator divider values. OSC_FRC_TUNE Lists the oscillator tuning values. OSC_GFX_CLOCK Lists the possible Graphics (display) module clock values. OSC_LFSR_TYPE Lists the possible Auxiliary PLL input divider values. OSC_MODULE_ID Possible instances of the OSC module. OSC_OPERATION_ON_WAIT Lists the possible status on a WAIT instruction. OSC_PERIPHERAL_BUS Lists the possible Peripheral buses OSC_PLL_SELECT Lists the PLLs in the Oscillator module. OSC_PLLAUX_CLOCK_SOURCE Lists the possible Auxiliary PLL clock source. OSC_REF_BASECLOCK Lists the possible base clock values for the reference oscillator. OSC_REF_DIV Lists the possible reference oscillator divisor values. OSC_REFERENCE Lists the possible reference oscillator OSC_SYS_CLOCK_DIV Lists the possible system clock divisor bits. OSC_SYS_TYPE Lists the possible oscillator type values. OSC_SYSPLL_FREQ_RANGE Lists the possible PLL frequency range OSC_SYSPLL_IN_CLK_SOURCE Lists the possible input clock source for PLL module OSC_SYSPLL_IN_DIV Lists the possible PLL input divider values. OSC_SYSPLL_OUT_DIV Lists the possible PLL output divider values. OSC_TUNING_MODE Lists the oscillator tuning modes. OSC_TUNING_SEQUENCERS Lists the oscillator sequencer entries. OSC_USBCLOCK_SOURCE Lists the possible USB clock sources. Auxiliary Oscillator Setup Functions Name Description PLIB_OSC_AuxClockSourceGet Gets the clock source for the auxiliary clock. PLIB_OSC_AuxClockSourceSet Sets the clock source for the auxiliary clock divisor. PLIB_OSC_AuxModeGet Gets the selected Auxiliary Oscillator mode. PLIB_OSC_AuxModeSelect Selects the Auxiliary Oscillator mode. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2337 Clock Fail Monitoring Functions Name Description PLIB_OSC_ClockHasFailed Returns 'true' if the clock fails. Doze Setup Functions Name Description PLIB_OSC_DozeModeDisable Disables Doze mode. PLIB_OSC_DozeModeEnable Enables Doze mode. PLIB_OSC_DozeRatioGet Gets the ratio of the processor clock to the peripheral clock. PLIB_OSC_DozeRatioSelect Selects the Doze ratio of the processor clock to the peripheral clock. PLIB_OSC_DozeRecoverOnInterruptDisable Disables the recovery from Doze mode upon an interrupt. PLIB_OSC_DozeRecoverOnInterruptEnable Enables recovery from Doze mode upon an interrupt. PLIB_OSC_DozeRecoverOnInterruptIsEnabled Returns 'true' if recover from Doze mode on interrupt is enabled. Fast RC Oscillator Setup Functions Name Description PLIB_OSC_FRCDitherEnable Enables the FRC Oscillator clock dithering. PLIB_OSC_FRCDivisorGet Gets the FRC clock divisor. PLIB_OSC_FRCDivisorSelect Sets the FRC clock divisor to the specified value. PLIB_OSC_FRCTuningModeGet Gets the FRC oscillator tuning mode. PLIB_OSC_FRCTuningModeSet Selects the FRC oscillator tuning mode. PLIB_OSC_FRCTuningSelect Sets the FRC tuning value. PLIB_OSC_FRCTuningSequenceValueGet Gets the value set in the FRC tune sequencer. PLIB_OSC_FRCTuningSequenceValueSet Sets the value in the FRC tune sequencer. PLIB_OSC_LinearFeedbackShiftRegGet Gets the value from linear feedback shift register. PLIB_OSC_LinearFeedbackShiftRegSet Sets the linear feedback shift register. Feature Existence Functions Name Description PLIB_OSC_ExistsClockFail Identifies whether the ClockFail feature exists on the OSC module PLIB_OSC_ExistsFRCDivisor Identifies whether the FRCDivisor feature exists on the OSC module PLIB_OSC_ExistsFRCTuning Identifies whether the FRCTuning feature exists on the OSC module PLIB_OSC_ExistsOnWaitAction Identifies whether the OnWaitAction feature exists on the OSC module PLIB_OSC_ExistsOscCurrentGet Identifies whether the OscCurrentGet feature exists on the OSC module PLIB_OSC_ExistsOscSelect Identifies whether the OscSelect feature exists on the OSC module PLIB_OSC_ExistsOscSwitchInit Identifies whether the OscSwitchInit feature exists on the OSC module PLIB_OSC_ExistsPBClockDivisor Identifies whether the PBClockDivisor feature exists on the OSC module PLIB_OSC_ExistsPBClockOutputEnable Identifies whether the PBClockOutputEnable feature exists on the OSC module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2338 PLIB_OSC_ExistsPBClockReady Identifies whether the PBClockReady feature exists on the OSC module PLIB_OSC_ExistsPLLClockLock Identifies whether the PLLClockLock feature exists on the OSC module PLIB_OSC_ExistsPLLLockStatus Identifies whether the PLLLockStatus feature exists on the OSC module PLIB_OSC_ExistsReferenceOscBaseClock Identifies whether the ReferenceOscBaseClock feature exists on the OSC module PLIB_OSC_ExistsReferenceOscChange Identifies whether the ReferenceOscChange feature exists on the OSC module PLIB_OSC_ExistsReferenceOscChangeActive Identifies whether the ReferenceOscChangeActive feature exists on the OSC module PLIB_OSC_ExistsReferenceOscDivisor Identifies whether the ReferenceOscDivisor feature exists on the OSC module PLIB_OSC_ExistsReferenceOscEnable Identifies whether the ReferenceOscEnable feature exists on the OSC module PLIB_OSC_ExistsReferenceOscStopInIdleEnable Identifies whether the ReferenceOscStopInIdleEnable feature exists on the OSC module PLIB_OSC_ExistsReferenceOscStopInSleep Identifies whether the ReferenceOscStopInSleep feature exists on the OSC module PLIB_OSC_ExistsReferenceOscTrim Identifies whether the ReferenceOscTrim feature exists on the OSC module PLIB_OSC_ExistsReferenceOutputEnable Identifies whether the ReferenceOutputEnable feature exists on the OSC module PLIB_OSC_ExistsSecondaryEnable Identifies whether the SecondaryEnable feature exists on the OSC module PLIB_OSC_ExistsSecondaryReady Identifies whether the SecondaryReady feature exists on the OSC module PLIB_OSC_ExistsSysPLLFrequencyRange Identifies whether the PLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsSysPLLInputClockSource Identifies whether the PLLInputClockSource feature exists on the OSC module PLIB_OSC_ExistsSysPLLInputDivisor Identifies whether the PLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsSysPLLMultiplier Identifies whether the PLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsSysPLLOutputDivisor Identifies whether the PLLOutputDivisor feature exists on the OSC module PLIB_OSC_ExistsUsbClockSource Identifies whether the UsbClockSource feature exists on the OSC module General Setup Functions Name Description PLIB_OSC_OnWaitActionGet Gets the configured operation to be performed when a WAIT instruction is executed. PLIB_OSC_OnWaitActionSet Selects the operation to be performed when a WAIT instruction is executed. PLIB_OSC_StartupTimerHasExpired Returns 'true' if the oscillator start-up time-out timer has expired. Oscillator Switch Setup Functions Name Description PLIB_OSC_ClockSwitchingAbort Aborts an oscillator switch. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2339 PLIB_OSC_ClockSwitchingIsComplete Gets the oscillator switch progress status. PLIB_OSC_CurrentSysClockGet Gets the current oscillator selected. PLIB_OSC_SysClockSelect Selects the new oscillator. Peripheral Clock Setup Functions Name Description PLIB_OSC_PBClockDivisorGet Gets the peripheral bus clock divisor. PLIB_OSC_PBClockDivisorIsReady Checks whether the peripheral bus clock divisor is ready to be written. PLIB_OSC_PBClockDivisorSet Sets the peripheral bus clock divisor to the specified value. PLIB_OSC_PBOutputClockDisable Disables the peripheral bus output clock PLIB_OSC_PBOutputClockEnable Enables the peripheral bus output clock PLIB_OSC_PBOutputClockIsEnabled Checks whether the peripheral bus clock output is enabled or not PLL Setup Functions Name Description PLIB_OSC_PLLAuxClockSourceGet Returns the clock source selected for the Auxiliary PLL. PLIB_OSC_PLLAuxClockSourceSelect Sets the Auxiliary PLL clock source. PLIB_OSC_PLLAuxInputDivisorGet Gets the input divisor for the Auxiliary PLL. PLIB_OSC_PLLAuxInputDivisorSelect Sets the input divisor for the Auxiliary PLL to the specified value. PLIB_OSC_PLLAuxIsLocked Returns whether the Auxiliary PLL is locked. PLIB_OSC_PLLAuxMultiplierGet Gets the Auxiliary PLL multiplier. PLIB_OSC_PLLAuxMultiplierSelect Sets the Auxiliary PLL multiplier to the specified value. PLIB_OSC_PLLAuxOutputDivisorGet Gets the output divisor for the Auxiliary PLL. PLIB_OSC_PLLAuxOutputDivisorSet Sets the output divisor for the Auxiliary PLL to the specified value. PLIB_OSC_PLLClockIsLocked Gets the lock status for the clock and PLL selections. PLIB_OSC_PLLClockLock Locks the clock and PLL selections. PLIB_OSC_PLLClockUnlock Unlocks the clock and PLL selections. PLIB_OSC_PLLDisable Disables the specified PLL. PLIB_OSC_PLLEnable Enables the specified PLL. PLIB_OSC_PLLIsEnabled Returns 'true' if the specified PLL is enabled. PLIB_OSC_PLLIsLocked Returns 'true' if the selected PLL is locked. PLIB_OSC_SysPLLFrequencyRangeGet Returns the frequence range for PLL PLIB_OSC_SysPLLFrequencyRangeSet Sets the frequence range for PLL PLIB_OSC_SysPLLInputClockSourceGet Returns the input clock source for the PLL module PLIB_OSC_SysPLLInputClockSourceSet Sets the input clock source for the PLL module PLIB_OSC_SysPLLInputDivisorGet Gets the input divisor for the PLL. PLIB_OSC_SysPLLInputDivisorSet Sets the input divider for the PLL to the specified value. PLIB_OSC_SysPLLMultiplierGet Gets the PLL multiplier. PLIB_OSC_SysPLLMultiplierSelect Sets the PLL multiplier to the specified value. PLIB_OSC_SysPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_SysPLLOutputDivisorSet Sets the output divider for the PLL to the specified value. Primary Oscillator Setup Functions Name Description PLIB_OSC_PrimaryOscInSleepModeDisable The Primary Oscillator is disabled during Sleep mode. PLIB_OSC_PrimaryOscInSleepModeEnable The Primary Oscillator continues to operate during Sleep mode. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2340 PLIB_OSC_PrimaryOscInSleepModeIsEnabled Returns 'true' if the Primary Oscillator is disabled during Sleep mode. Reference Oscillator Setup Functions Name Description PLIB_OSC_ReferenceOscBaseClockSelect Sets the base clock for the reference oscillator. PLIB_OSC_ReferenceOscDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOscDivisorValueSet Selects the reference oscillator divisor value. PLIB_OSC_ReferenceOscEnable Enables the reference oscillator. PLIB_OSC_ReferenceOscIsEnabled Gets the enable status of the reference oscillator output. PLIB_OSC_ReferenceOscSourceChangeIsActive Returns 'true' if a reference oscillator source change request is active. PLIB_OSC_ReferenceOscStopInIdleDisable Enables the reference oscillator in Idle mode. PLIB_OSC_ReferenceOscStopInIdleEnable Configures the reference oscillator to stop operating in Idle mode. PLIB_OSC_ReferenceOscStopInIdleIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_ReferenceOscStopInSleepDisable Enables the reference oscillator in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepEnable Configures the reference oscillator to stop operating in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepIsEnabled Returns 'true' if the reference oscillator is disabled in Sleep mode. PLIB_OSC_ReferenceOscSwitchIsComplete Returns 'true' if the reference oscillator base clock switching is complete. PLIB_OSC_ReferenceOscTrimSet Sets the reference oscillator divisor trim value. PLIB_OSC_ReferenceOutputDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOutputEnable Enables the reference oscillator output. PLIB_OSC_ReferenceOutputIsEnabled Returns 'true' if the reference oscillator output is enabled. Secondary Oscillator Setup Functions Name Description PLIB_OSC_SecondaryDisable Disables the Secondary Oscillator. PLIB_OSC_SecondaryEnable Enables the Secondary Oscillator. PLIB_OSC_SecondaryIsEnabled Returns 'true' if the Secondary Oscillator is enabled. PLIB_OSC_SecondaryIsReady Returns 'true' if the Secondary Oscillator is ready. USB and Display Clock Setup Functions Name Description PLIB_OSC_GraphicsClockDivisorGet Gets the Graphics module clock divisor. PLIB_OSC_GraphicsClockDivisorSet Sets the Graphics module clock divisor. PLIB_OSC_GraphicsClockSourceGet Gets the Graphics Controller module clock frequency value. PLIB_OSC_GraphicsClockSourceSelect Sets the Graphics Controller module clock. PLIB_OSC_UsbClockSourceGet Gets the USB module clock source. PLIB_OSC_UsbClockSourceSelect Sets the USB module clock source. Description This section lists and describes the functions, data types, and constants provided in the Oscillator Peripheral Library. 5.6.14.6.1 General Setup Functions 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2341 5.6.14.6.1.1 PLIB_OSC_OnWaitActionGet Function C OSC_OPERATION_ON_WAIT PLIB_OSC_OnWaitActionGet( OSC_MODULE_ID index ); Description This function gets the configured operation that is to be performed when a WAIT instruction is executed. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns On a WAIT action, one of the possible values of OSC_OPERATION_ON_WAIT. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOnWaitAction in your application to determine whether this feature is available. Example if (PLIB_OSC_OnWaitActionGet(OSC_ID_0) == OSC_ON_WAIT_SLEEP) { //Do some action } 5.6.14.6.1.2 PLIB_OSC_OnWaitActionSet Function C void PLIB_OSC_OnWaitActionSet( OSC_MODULE_ID index, OSC_OPERATION_ON_WAIT onWait ); Description This function selects the operation to be performed when a WAIT instruction is executed. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module onWait Operation to be performed when a WAIT instruction is executed. One of the possible values of OSC_OPERATION_ON_WAIT. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2342 PLIB_OSC_ExistsOnWaitAction in your application to determine whether this feature is available. If this API is not called, the device will enter Idle mode on execution of a WAIT instruction. Example PLIB_OSC_OnWaitActionSet(OSC_ID_0, OSC_ON_WAIT_SLEEP); 5.6.14.6.1.3 PLIB_OSC_StartupTimerHasExpired Function C bool PLIB_OSC_StartupTimerHasExpired( OSC_MODULE_ID index ); Description This function returns 'true' if the oscillator start-up time-out timer has expired. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Oscillator start-up time-out timer has expired • false - Oscillator start-up time-out timer is running Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example bool startUpTImer; startUpTImer = PLIB_OSC_StartupTimerHasExpired(OSC_ID_0); 5.6.14.6.2 Primary Oscillator Setup Functions 5.6.14.6.2.1 PLIB_OSC_PrimaryOscInSleepModeDisable Function C void PLIB_OSC_PrimaryOscInSleepModeDisable( OSC_MODULE_ID index ); Description This function disables the Primary Oscillator during Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2343 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PrimaryOscInSleepModeDisable(OSC_ID_0); 5.6.14.6.2.2 PLIB_OSC_PrimaryOscInSleepModeEnable Function C void PLIB_OSC_PrimaryOscInSleepModeEnable( OSC_MODULE_ID index ); Description This function enables the Primary Oscillator during Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PrimaryOscInSleepModeEnable(OSC_ID_0); 5.6.14.6.2.3 PLIB_OSC_PrimaryOscInSleepModeIsEnabled Function C bool PLIB_OSC_PrimaryOscInSleepModeIsEnabled( OSC_MODULE_ID index ); Description This function gets the enable status of the Primary Oscillator during Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Primary Oscillator is enabled during Sleep mode 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2344 • false - Primary Oscillator is disabled during Sleep mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example bool priOscStatus; priOscStatus = PLIB_OSC_PrimaryOscInSleepModeIsEnabled(OSC_ID_0); 5.6.14.6.3 Secondary Oscillator Setup Functions 5.6.14.6.3.1 PLIB_OSC_SecondaryDisable Function C void PLIB_OSC_SecondaryDisable( OSC_MODULE_ID index ); Description This function disables the Secondary Oscillator. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Example PLIB_OSC_SecondaryDisable(OSC_ID_0); 5.6.14.6.3.2 PLIB_OSC_SecondaryEnable Function C void PLIB_OSC_SecondaryEnable( OSC_MODULE_ID index ); Description This function enables the Secondary Oscillator. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2345 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Example PLIB_OSC_SecondaryEnable(OSC_ID_0); 5.6.14.6.3.3 PLIB_OSC_SecondaryIsEnabled Function C bool PLIB_OSC_SecondaryIsEnabled( OSC_MODULE_ID index ); Description This function returns 'true' if the Secondary Oscillator is enabled. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Secondary Oscillator is enabled • false - Secondary Oscillator is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryEnable in your application to determine whether this feature is available. Example bool secOscEnable; secOscEnable = PLIB_OSC_SecondaryIsEnabled(OSC_ID_0); 5.6.14.6.3.4 PLIB_OSC_SecondaryIsReady Function C bool PLIB_OSC_SecondaryIsReady( OSC_MODULE_ID index ); Description This function returns the ready status of the Secondary Oscillator. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2346 Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Indicates that the Secondary Oscillator is running and is stable • false - Secondary Oscillator is either turned off or is still warming up Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSecondaryReady in your application to determine whether this feature is available. Example bool secOscReady; secOscReady = PLIB_OSC_SecondaryIsReady(OSC_ID_0); 5.6.14.6.4 Auxiliary Oscillator Setup Functions 5.6.14.6.4.1 PLIB_OSC_AuxClockSourceGet Function C OSC_AUX_CLOCK_SOURCE PLIB_OSC_AuxClockSourceGet( OSC_MODULE_ID index ); Description This function gets the clock source for the auxiliary clock. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_AUX_CLOCK_SOURCE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_AUX_CLOCK_SOURCE auxClockSource; auxClockSource = PLIB_OSC_AuxClockSourceGet(OSC_ID_0); 5.6.14.6.4.2 PLIB_OSC_AuxClockSourceSet Function C void PLIB_OSC_AuxClockSourceSet( OSC_MODULE_ID index, OSC_AUX_CLOCK_SOURCE auxClockSource ); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2347 Description This function sets the clock source for the auxiliary clock divisor. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxClockSource Clock source for the auxiliary clock divisor. One of the possible values from OSC_AUX_CLOCK_SOURCE. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_AuxClockSourceSet(OSC_ID_0, OSC_AUX_CLOCK_PRIMARY); 5.6.14.6.4.3 PLIB_OSC_AuxModeGet Function C OSC_AUX_MODE PLIB_OSC_AuxModeGet( OSC_MODULE_ID index ); Description This function gets the Auxiliary Oscillator mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values of OSC_AUX_MODE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_AUX_MODE auxOscMode; auxOscMode = PLIB_OSC_AuxModeGet(OSC_ID_0); 5.6.14.6.4.4 PLIB_OSC_AuxModeSelect Function C void PLIB_OSC_AuxModeSelect( OSC_MODULE_ID index, OSC_AUX_MODE AuxOscMode 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2348 ); Description This function selects the Auxiliary Oscillator mode based on the input. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxOscMode One of the possible values of OSC_AUX_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_AuxModeSelect(OSC_ID_0, OSC_AUX_MODE_HS); 5.6.14.6.5 Reference Oscillator Setup Functions 5.6.14.6.5.1 PLIB_OSC_ReferenceOscBaseClockSelect Function C void PLIB_OSC_ReferenceOscBaseClockSelect( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_BASECLOCK refOscBaseClock ); Description This function sets the base clock for the reference oscillator. There are multiple clock sources by which the user can configure the module to output to the pin. Users can check the accuracy of the clock by probing the pin. Use the PLIB_OSC_ReferenceOscDivisorValueSet function to divide the clock if it is a very high value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator refOscBaseClk One of the possible values of OSC_REF_BASECLOCK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscBaseClock in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2349 Example PLIB_OSC_ReferenceOscBaseClockSelect(OSC_ID_0, OSC_REFERENCE_1, OSC_REF_BASECLOCK_PBCLK); 5.6.14.6.5.2 PLIB_OSC_ReferenceOscDisable Function C void PLIB_OSC_ReferenceOscDisable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function disables output from the reference oscillator. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. Example PLIB_OSC_ReferenceOscDisable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.3 PLIB_OSC_ReferenceOscDivisorValueSet Function C void PLIB_OSC_ReferenceOscDivisorValueSet( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_DIVISOR_TYPE refOscValue ); Description This function selects the reference oscillator divisor value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator refOscDiv One of the possible values of OSC_REF_DIV 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2350 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscDivisor in your application to determine whether this feature is available. The value entered may not be the actual divisor. Please refer to the specific device data sheet to determine the actual divisor corresponding to the value entered. Example // Select the clock source. PLIB_OSC_ReferenceOscBaseClockSelect(OSC_ID_0, OSC_REFERENCE_1, OSC_REF_BASECLOCK_PBCLK); PLIB_OSC_ReferenceOscDivisorValueSet(OSC_ID_0, OSC_REFERENCE_1, 128); PLIB_OSC_ReferenceOscEnable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.4 PLIB_OSC_ReferenceOscEnable Function C void PLIB_OSC_ReferenceOscEnable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function enables the reference oscillator. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. If the device has a reference clock output enable control, calling this function may not give the reference clock output. Use the PLIB_OSC_ReferenceOutputEnable function to enable the output. Example PLIB_OSC_ReferenceOscEnable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.5 PLIB_OSC_ReferenceOscIsEnabled Function C bool PLIB_OSC_ReferenceOscIsEnabled( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2351 ); Description This function gets the enable status of the reference oscillator output. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns • true - Reference oscillator is enabled • false - Reference oscillator is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscEnable in your application to determine whether this feature is available. Example if(PLIB_OSC_ReferenceOscIsEnabled(OSC_ID_0, OSC_REFERENCE_1)) { //Do some action } 5.6.14.6.5.6 PLIB_OSC_ReferenceOscSourceChangeIsActive Function C bool PLIB_OSC_ReferenceOscSourceChangeIsActive( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function returns 'true' if the reference oscillator source change is in progress. The software is not allowed to give a new source change request. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns • true - Reference oscillator change request is active • false - Reference oscillator change request is not active Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscChangeActive in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2352 Example if (!PLIB_OSC_ReferenceOscSourceChangeIsActive(OSC_ID_0, OSC_REFERENCE_1)) { //Allowed to change the reference clock source } 5.6.14.6.5.7 PLIB_OSC_ReferenceOscStopInIdleDisable Function C void PLIB_OSC_ReferenceOscStopInIdleDisable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function enables the reference oscillator in Idle mode. The reference oscillator continues to run in Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. The default state of the device is the reference oscillator is enabled in Idle mode. Example PLIB_OSC_ReferenceOsctopInSleepDisable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.8 PLIB_OSC_ReferenceOscStopInIdleEnable Function C void PLIB_OSC_ReferenceOscStopInIdleEnable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function configures the reference oscillator to stop operating in Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2353 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator enabled in Idle mode. Therefore, calling this function is necessary only if the PLIB_OSC_ReferenceOscStopInIdleDisable function was previously called, and the software wants to enable oscillator operation in Sleep mode. Example PLIB_OSC_ReferenceOscStopInIdleEnable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.9 PLIB_OSC_ReferenceOscStopInIdleIsEnabled Function C bool PLIB_OSC_ReferenceOscStopInIdleIsEnabled( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function returns 'true' if the reference oscillator is disabled in Idle mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns • true - Reference oscillator is disabled in Idle mode • false - Reference oscillator is enabled in Idle mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInIdleEnable in your application to determine whether this feature is available. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOscStopInIdleIsEnabled(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.10 PLIB_OSC_ReferenceOscStopInSleepDisable Function C void PLIB_OSC_ReferenceOscStopInSleepDisable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2354 Description This function enables the reference oscillator in Sleep mode. The reference oscillator continues to run in Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. The reference clock output will be stopped in Sleep mode if the base clock selected is 'System Clock' or 'Peripheral Clock' regardless of this function. The default state of the device is for the reference oscillator to be enabled in Sleep mode. Therefore, calling this function is necessary only if the PLIB_OSC_ReferenceOscStopInSleepEnable function was previously called, and the software wants to enable oscillator operation in Sleep mode. Example PLIB_OSC_ReferenceOsctopInSleepDisable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.11 PLIB_OSC_ReferenceOscStopInSleepEnable Function C void PLIB_OSC_ReferenceOscStopInSleepEnable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function configures the reference oscillator to stop operating in Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2355 The default state of the device is for the reference oscillator to be enabled in Sleep mode. Example PLIB_OSC_ReferenceOscStopInSleepEnable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.12 PLIB_OSC_ReferenceOscStopInSleepIsEnabled Function C bool PLIB_OSC_ReferenceOscStopInSleepIsEnabled( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function returns 'true' if the reference oscillator is disabled in Sleep mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns • true - Reference oscillator is disabled in Sleep mode • false - Reference oscillator is enabled in Sleep mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscStopInSleep in your application to determine whether this feature is available. Example bool refOscSleep; refOscSleep = PLIB_OSC_ReferenceOscStopInSleepIsEnabled(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.13 PLIB_OSC_ReferenceOscSwitchIsComplete Function C bool PLIB_OSC_ReferenceOscSwitchIsComplete( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function returns 'true' if the reference oscillator base clock switching is complete. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2356 Returns • true - Reference clock base clock switching is complete • false - Reference clock base clock switching is not complete; switching is not started Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscChange in your application to determine whether this feature is available. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOscSwitchIsComplete(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.14 PLIB_OSC_ReferenceOscTrimSet Function C void PLIB_OSC_ReferenceOscTrimSet( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc, OSC_REF_TRIM_TYPE trimValue ); Description This function selects the reference oscillator divisor trim value. The value selected divided by OSC_REF_TRIM_MAX_VALUE will be added to the oscillator divisor value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator trimValue Reference oscillator trim value Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOscTrim in your application to determine whether this feature is available. Example PLIB_OSC_ReferenceOscTrimSet(OSC_ID_0, OSC_REFERENCE_1, 50); 5.6.14.6.5.15 PLIB_OSC_ReferenceOutputDisable Function C void PLIB_OSC_ReferenceOutputDisable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function disables the reference oscillator output. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2357 Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator output disabled. Example PLIB_OSC_ReferenceOutputDisable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.16 PLIB_OSC_ReferenceOutputEnable Function C void PLIB_OSC_ReferenceOutputEnable( OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function enables the reference oscillator output. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. The default state of the device is reference oscillator output disabled. Example PLIB_OSC_ReferenceOutputEnable(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.5.17 PLIB_OSC_ReferenceOutputIsEnabled Function C bool PLIB_OSC_ReferenceOutputIsEnabled( 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2358 OSC_MODULE_ID index, OSC_REFERENCE referenceOsc ); Description This function returns 'true' if the reference oscillator output is enabled. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module referenceOsc Identifies the desired reference oscillator Returns • true - Reference oscillator output is enabled • false - Reference oscillator output is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsReferenceOutputEnable in your application to determine whether this feature is available. Example bool refOscIdle; refOscIdle = PLIB_OSC_ReferenceOutputIsEnabled(OSC_ID_0, OSC_REFERENCE_1); 5.6.14.6.6 Fast RC Oscillator Setup Functions 5.6.14.6.6.1 PLIB_OSC_FRCDitherEnable Function C void PLIB_OSC_FRCDitherEnable( OSC_MODULE_ID index ); Description This function enables the FRC Oscillator clock dithering. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2359 Example PLIB_OSC_FRCDitherEnable(OSC_ID_0); 5.6.14.6.6.2 PLIB_OSC_FRCDivisorGet Function C OSC_FRC_DIV PLIB_OSC_FRCDivisorGet( OSC_MODULE_ID index ); Description This function gets the FRC clock divisor. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_FRC_DIV. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCDivisor in your application to determine whether this feature is available. Example OSC_FRC_DIV divisorFRC; divisorFRC = PLIB_OSC_FRCDivisorGet(OSC_ID_0); 5.6.14.6.6.3 PLIB_OSC_FRCDivisorSelect Function C void PLIB_OSC_FRCDivisorSelect( OSC_MODULE_ID index, OSC_FRC_DIV divisorFRC ); Description This function sets the FRC clock divisor to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module divisorFRC One of the possible values from OSC_FRC_DIV Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2360 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCDivisor in your application to determine whether this feature is available. Example PLIB_OSC_FRCDivisorSelect ( OSC_ID_0, OSC_FRC_DIV_4 ); 5.6.14.6.6.4 PLIB_OSC_FRCTuningModeGet Function C OSC_TUNING_MODE PLIB_OSC_FRCTuningModeGet( OSC_MODULE_ID index ); Description This function gets the FRC oscillator tuning mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible value from OSC_TUNING_MODE enum. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example if (OSC_TUNING_USING_NUMBER == PLIB_OSC_FRCTuningModeGet(OSC_ID_0)) { //Do some action } 5.6.14.6.6.5 PLIB_OSC_FRCTuningModeSet Function C void PLIB_OSC_FRCTuningModeSet( OSC_MODULE_ID index, OSC_TUNING_MODE tuningMode ); Description This function selects the FRC oscillator tuning mode. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module tuningMode One of the possible value from OSC_TUNING_MODE. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2361 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCTuning in your application to determine whether this feature is available. This function takes care of the register unlock, which is required per the device data sheet. Therefore, the user need not explicity perform the unlock sequence. Example PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_USING_NUMBER); 5.6.14.6.6.6 PLIB_OSC_FRCTuningSelect Function C void PLIB_OSC_FRCTuningSelect( OSC_MODULE_ID index, OSC_FRC_TUNE_TYPE tuningValue ); Description This function tunes the FRC oscillator to the value specified. The application is supposed to try different values and find the best one. If the device has different tuning modes, this function will be used differently. See the example provided for the PLIB_OSC_FRCTuningSequenceValueSet function for details. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module tuningValue Tuning value. One of the possible values from OSC_FRC_TUNE_TYPE. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsFRCTuning in your application to determine whether this feature is available. This function takes care of the register unlock, which is required per the device data sheet. Therefore, the user need not explicitly perform the unlock sequence. Example PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x05); 5.6.14.6.6.7 PLIB_OSC_FRCTuningSequenceValueGet Function C OSC_FRC_TUNE_TYPE PLIB_OSC_FRCTuningSequenceValueGet( OSC_MODULE_ID index, OSC_TUNING_SEQUENCERS oscSeqencer ); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2362 Description This function gets the value set in the selected FRC tune sequencer. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module oscSeqencer Value to be set in the sequencer Returns Value in the sequencer specified. One of the possible value from OSC_FRC_TUNE_TYPE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. This API takes care of the register unlock, which is required per the device datasheet. Therefore, the need not explicity perform the unlock sequence. Example OSC_FRC_TUNE_TYPE seqValue; seqValue = PLIB_OSC_FRCTuningSequenceValueGet(OSC_ID_0, OSC_TUNING_SEQUENCER_1); 5.6.14.6.6.8 PLIB_OSC_FRCTuningSequenceValueSet Function C void PLIB_OSC_FRCTuningSequenceValueSet( OSC_MODULE_ID index, OSC_TUNING_SEQUENCERS oscSeqencer, OSC_FRC_TUNE_TYPE seqValue ); Description This function sets the value in the FRC tune sequencer. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module oscSeqencer Select the sequencer seqValue Value to be set in the sequencer. One of the possible values from OSC_FRC_TUNE_TYPE. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2363 Example PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_SEQ_DITHER); PLIB_OSC_FRCTuningSelect(OSC_ID_0, 0x01); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_1, OSC_FRC_TUNE_MINUS_2_25_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_2, OSC_FRC_TUNE_MINUS_1_5_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_3, OSC_FRC_TUNE_MINUS_0_375_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_4, OSC_FRC_TUNE_PLUS_0_43_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_5, OSC_FRC_TUNE_PLUS_1_29_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_6, OSC_FRC_TUNE_PLUS_2_54_PERCENT); PLIB_OSC_FRCTuningSequenceValueSet(OSC_ID_0, OSC_TUNING_SEQUENCER_7, OSC_FRC_TUNE_MINUS_3_PERCENT); //Configure PWM (period, pulse width and turn on the module) 5.6.14.6.6.9 PLIB_OSC_LinearFeedbackShiftRegGet Function C OSC_LFSR_TYPE PLIB_OSC_LinearFeedbackShiftRegGet( OSC_MODULE_ID index ); Description This function gets the value from the linear feedback shift register. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns OSC_LFSR_TYPE - Linear Feedback shift register Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_LFSR_TYPE linearFbValue; linearFbValue = PLIB_OSC_LinearFeedbackShiftRegGet(OSC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2364 5.6.14.6.6.10 PLIB_OSC_LinearFeedbackShiftRegSet Function C void PLIB_OSC_LinearFeedbackShiftRegSet( OSC_MODULE_ID index, OSC_LFSR_TYPE linearFbValue ); Description This function sets the linear feedback shift register. When the FRC oscillator tuning mode is configured for pseudo-random number-based dithering, this function is used to provide the seed number for the pseudo-random number generation algorithm. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module linearFbValue The pseudo-random FRC trim value Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. This function takes care of the register unlock, which is required per the device data sheet. Therefore, the user need not explicity perform the unlock sequence. Example PLIB_OSC_FRCTuningModeSet(OSC_ID_0, OSC_TUNING_PSEUDO_RANDOM); //15 bit Linear Feedback shift register value PLIB_OSC_LinearFeedbackShiftRegSet(OSC_ID_0, 0x7F); 5.6.14.6.7 Oscillator Switch Setup Functions 5.6.14.6.7.1 PLIB_OSC_ClockSwitchingAbort Function C void PLIB_OSC_ClockSwitchingAbort( OSC_MODULE_ID index ); Description This function aborts the oscillator switch to the selection specified by the new oscillator selection bits. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2365 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSwitchInit in your application to determine whether this feature is available. Example PLIB_OSC_ClockSwitchingAbort(OSC_ID_0); 5.6.14.6.7.2 PLIB_OSC_ClockSwitchingIsComplete Function C bool PLIB_OSC_ClockSwitchingIsComplete( OSC_MODULE_ID index ); Description This function gets the status of the oscillator switch progress. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns true - Oscillator switch is complete false - Oscillator switch is in progress Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSwitchInit in your application to determine whether this feature is available. This function takes care of the register unlock, which is required per the device datasheet. Therefore, the user need not explicity perform the unlock sequence. Example PLIB_OSC_SysClockSelect(OSC_ID_0, OSC_PRIMARY); while(!PLIB_OSC_ClockSwitchingIsComplete(OSC_ID_0)); 5.6.14.6.7.3 PLIB_OSC_CurrentSysClockGet Function C OSC_SYS_TYPE PLIB_OSC_CurrentSysClockGet( OSC_MODULE_ID index ); Description This function gets the current oscillater. If the application hasn't changed the oscillator selection, this will be same as the oscillator selected through the Configuration bits. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2366 Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_SYS_TYPE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscCurrentGet in your application to determine whether this feature is available. Example OSC_SYS_TYPE oscCurrent; oscCurrent = PLIB_OSC_CurrentSysClockGet(OSC_ID_0); 5.6.14.6.7.4 PLIB_OSC_SysClockSelect Function C void PLIB_OSC_SysClockSelect( OSC_MODULE_ID index, OSC_SYS_TYPE newOsc ); Description This function selects the new oscillator. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module newOsc One of the possible values from OSC_SYS_TYPE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsOscSelect in your application to determine whether this feature is available. This function takes care of the register unlock, which is required per the device datasheet. Therefore, the user need not explicitly perform the unlock sequence. This function adds the necessary delay (NOP instructions) after switching the oscillator. Therefore, the user need not add any delay as specified in the device data sheet. Example PLIB_OSC_SysClockSelect(OSC_ID_0, OSC_PRIMARY); 5.6.14.6.8 Doze Setup Functions 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2367 5.6.14.6.8.1 PLIB_OSC_DozeModeDisable Function C void PLIB_OSC_DozeModeDisable( OSC_MODULE_ID index ); Description This function disables Doze mode. The CPU peripheral clock ratio is set to 1:1. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. This function adds the necessary delay (NOP instructions), which must be added immediately before entering Doze mode and immediately after exiting Doze mode. Example PLIB_OSC_DozeModeDisable(OSC_ID_0); 5.6.14.6.8.2 PLIB_OSC_DozeModeEnable Function C void PLIB_OSC_DozeModeEnable( OSC_MODULE_ID index ); Description This function enables Doze mode. This is a method to reduce power consumption By reducing the processor clock. Use the PLIB_OSC_DozeRatioSelect function to specify the CPU peripheral clock ratio. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. This function adds the necessary delay (NOP instructions), which must be added immediately before entering Doze mode and immediately after exiting Doze mode. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2368 Example PLIB_OSC_DozeModeEnable(OSC_ID_0); 5.6.14.6.8.3 PLIB_OSC_DozeRatioGet Function C OSC_DOZE_RATIO PLIB_OSC_DozeRatioGet( OSC_MODULE_ID index ); Description This function gets the Doze ratio, which is the ratio between the processor clock and the peripheral clock. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values of OSC_DOZE_RATIO. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_DOZE_RATIO dozeRatio; dozeRatio = PLIB_OSC_DozeRatioGet(OSC_ID_0); 5.6.14.6.8.4 PLIB_OSC_DozeRatioSelect Function C void PLIB_OSC_DozeRatioSelect( OSC_MODULE_ID index, OSC_DOZE_RATIO dozeRatio ); Description This function selects the Doze ratio, which is the ratio between the processor clock and the peripheral clock. By default, the ratio between the processor clock and the peripheral clock is 1:1. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module dozeRatio One of the possible values of OSC_DOZE_RATIO Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2369 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_DozeRatioSelect(OSC_ID_0, OSC_DOZE_RATIO_4); 5.6.14.6.8.5 PLIB_OSC_DozeRecoverOnInterruptDisable Function C void PLIB_OSC_DozeRecoverOnInterruptDisable( OSC_MODULE_ID index ); Description This function disables feature of recovering from Doze mode upon an interrupt. Interrupts will not affect the power-saving Doze mode enable. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_DozeRecoverOnInterruptDisable(OSC_ID_0); 5.6.14.6.8.6 PLIB_OSC_DozeRecoverOnInterruptEnable Function C void PLIB_OSC_DozeRecoverOnInterruptEnable( OSC_MODULE_ID index ); Description This function enables the feature of recovering from Doze mode upon an interrupt. Interrupts clear the power-saving Doze mode enable and reset the CPU peripheral clock ratio to 1:1. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2370 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_DozeRecoverOnInterruptEnable(OSC_ID_0); 5.6.14.6.8.7 PLIB_OSC_DozeRecoverOnInterruptIsEnabled Function C bool PLIB_OSC_DozeRecoverOnInterruptIsEnabled( OSC_MODULE_ID index ); Description This function returns 'true' if recover from Doze mode on interrupt is enabled. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Recover from Doze mode on interrupt is enabled • false - Recover from Doze mode on interrupt is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example bool recoverOnInt; recoverOnInt = PLIB_OSC_DozeRecoverOnInterruptIsEnabled(OSC_ID_0); 5.6.14.6.9 USB and Display Clock Setup Functions 5.6.14.6.9.1 PLIB_OSC_GraphicsClockDivisorGet Function C uint8_t PLIB_OSC_GraphicsClockDivisorGet( OSC_MODULE_ID index ); Description This function gets the Graphics module clock divisor. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2371 Returns Graphics module clock divisor. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example uint8_t displayClockDiv; displayClockDiv = PLIB_OSC_GraphicsClockDivisorGet(OSC_ID_0); 5.6.14.6.9.2 PLIB_OSC_GraphicsClockDivisorSet Function C void PLIB_OSC_GraphicsClockDivisorSet( OSC_MODULE_ID index, uint8_t clockDivisor ); Description This function sets the Graphics module clock divisor. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module clockDivisor Graphics module clock divisor Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_GraphicsClockDivisorSet(OSC_ID_0, 127); 5.6.14.6.9.3 PLIB_OSC_GraphicsClockSourceGet Function C OSC_GFX_CLOCK PLIB_OSC_GraphicsClockSourceGet( OSC_MODULE_ID index ); Description This function gets the clock frequency used for the Graphics Controller module. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2372 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_GFX_CLOCK gfxClock; gfxClock = PLIB_OSC_GraphicsClockSourceGet (OSC_ID_0); 5.6.14.6.9.4 PLIB_OSC_GraphicsClockSourceSelect Function C void PLIB_OSC_GraphicsClockSourceSelect( OSC_MODULE_ID index, OSC_GFX_CLOCK gfxClock ); Description This function sets the clock frequency for the Graphics Controller module. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module gfxClock One of the possible values of OSC_GFX_CLOCK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_GraphicsClockSourceSelect (OSC_ID_0, OSC_GFX_CLOCK_96M); 5.6.14.6.9.5 PLIB_OSC_UsbClockSourceGet Function C OSC_USBCLOCK_SOURCE PLIB_OSC_UsbClockSourceGet( OSC_MODULE_ID index ); Description This function gets the USB module clock source. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2373 Returns USB module clock source. One of the possible values from OSC_USBCLOCK_SOURCE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUsbClockSource in your application to determine whether this feature is available. Example if (SYS_OSC_USBCLK_FRC == PLIB_OSC_UsbClockSourceGet(OSC_ID_0)) { //Do some action } 5.6.14.6.9.6 PLIB_OSC_UsbClockSourceSelect Function C void PLIB_OSC_UsbClockSourceSelect( OSC_MODULE_ID index, OSC_USBCLOCK_SOURCE usbClock ); Description This function sets the USB module clock source. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module usbClock Select the USB module clock source. One of the possible values from OSC_USBCLOCK_SOURCE. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsUsbClockSource in your application to determine whether this feature is available. Before placing the USB module in Suspend mode, use this function to enable the FRC clock. Example PLIB_OSC_UsbClockSourceSelect(OSC_ID_0, SYS_OSC_USBCLK_FRC); 5.6.14.6.10 PLL Setup Functions 5.6.14.6.10.1 PLIB_OSC_PLLAuxClockSourceGet Function C OSC_PLLAUX_CLOCK_SOURCE PLIB_OSC_PLLAuxClockSourceGet( OSC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2374 Description This function returns the clock source selected for the Auxiliary PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns The source for the auxiliary clock. One of the possible values from OSC_PLLAUX_CLOCK_SOURCE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example if(OSC_PLLAUX_CLOCK == PLIB_OSC_PLLAuxClockSourceGet(OSC_ID_0)) { //Take some action } 5.6.14.6.10.2 PLIB_OSC_PLLAuxClockSourceSelect Function C void PLIB_OSC_PLLAuxClockSourceSelect( OSC_MODULE_ID index, OSC_PLLAUX_CLOCK_SOURCE auxPLLClkSrc ); Description This function sets the Auxiliary PLL clock source to either the Primary oscillator or the Auxiliary oscillator depending on the input. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxPLLClkSrc The source for the auxiliary clock. One of the possible values from OSC_PLLAUX_CLOCK_SOURCE. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLAuxClockSourceSelect(OSC_ID_0, OSC_PLLAUX_CLOCK); 5.6.14.6.10.3 PLIB_OSC_PLLAuxInputDivisorGet Function C OSC_AUXPLL_IN_DIV PLIB_OSC_PLLAuxInputDivisorGet( 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2375 OSC_MODULE_ID index ); Description This function gets the input divisor for the Auxiliary PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_AUXPLL_IN_DIV. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_AUXPLL_IN_DIV auxPLLInDiv; auxPLLInDiv = PLIB_OSC_PLLAuxInputDivisorGet(OSC_ID_0); 5.6.14.6.10.4 PLIB_OSC_PLLAuxInputDivisorSelect Function C void PLIB_OSC_PLLAuxInputDivisorSelect( OSC_MODULE_ID index, OSC_AUXPLL_IN_DIV auxPLLInDiv ); Description This function sets the input divisor for the Auxiliary PLL to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxPLLInDiv One of the possible values from OSC_AUXPLL_IN_DIV Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLAuxInputDivisorSelect(OSC_ID_0, OSC_AUXPLL_IN_DIV_2); 5.6.14.6.10.5 PLIB_OSC_PLLAuxIsLocked Function C bool PLIB_OSC_PLLAuxIsLocked( 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2376 OSC_MODULE_ID index ); Description This function returns 'true' if the Auxiliary PLL is locked. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Auxiliary PLL is in lock • false - Auxiliary PLL is not in lock Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example bool lockAuxPLL; lockAuxPLL = PLIB_OSC_PLLAuxIsLocked(OSC_ID_0); 5.6.14.6.10.6 PLIB_OSC_PLLAuxMultiplierGet Function C OSC_AUXPLL_MULTIPLIER PLIB_OSC_PLLAuxMultiplierGet( OSC_MODULE_ID index ); Description This function gets the Auxiliary PLL multiplier. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_PLL_MUL. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_AUXPLL_MULTIPLIER auxpllMultiply; auxpllMultiply = PLIB_OSC_PLLAuxMultiplierGet(OSC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2377 5.6.14.6.10.7 PLIB_OSC_PLLAuxMultiplierSelect Function C void PLIB_OSC_PLLAuxMultiplierSelect( OSC_MODULE_ID index, OSC_AUXPLL_MULTIPLIER auxPllMultiplier ); Description This function sets the Auxiliary PLL multiplier to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxPllMultiplier One of the possible values from OSC_AUXPLL_MULTIPLIER Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLAuxMultiplierSelect (OSC_ID_0, OSC_AUXPLL_MULTIPLIER_4); 5.6.14.6.10.8 PLIB_OSC_PLLAuxOutputDivisorGet Function C OSC_AUXPLL_OUT_DIV PLIB_OSC_PLLAuxOutputDivisorGet( OSC_MODULE_ID index ); Description This function gets the output divisor for the Auxiliary PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_AUXPLL_OUT_DIV. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example OSC_AUXPLL_OUT_DIV auxOutputDiv; auxOutputDiv = PLIB_OSC_PLLAuxOutputDivisorGet(OSC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2378 5.6.14.6.10.9 PLIB_OSC_PLLAuxOutputDivisorSet Function C void PLIB_OSC_PLLAuxOutputDivisorSet( OSC_MODULE_ID index, OSC_AUXPLL_OUT_DIV auxOutputDiv ); Description This function sets the output divisor for the Auxiliary PLL to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module auxOutputDiv One of the possible values from OSC_AUXPLL_OUT_DIV Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLAuxOutputDivisorSet(OSC_ID_0, OSC_AUXPLL_OUT_DIV_2); 5.6.14.6.10.10 PLIB_OSC_PLLClockIsLocked Function C bool PLIB_OSC_PLLClockIsLocked( OSC_MODULE_ID index ); Description This function gets the lock status for the clock and PLL selections. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - clock and PLL selections are locked • false - clock and PLL selections are not locked Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. If the PLL does not stabilize properly during start-up, this function may not reflect the actual status of PLL lock, nor does it detect 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2379 when the PLL loses lock during normal operation. Example bool clockPLL_st; clockPLL_st = PLIB_OSC_PLLClockIsLocked(OSC_ID_0); 5.6.14.6.10.11 PLIB_OSC_PLLClockLock Function C void PLIB_OSC_PLLClockLock( OSC_MODULE_ID index ); Description This function locks the clock and PLL selections. Preconditions The Fail-Safe Clock Monitor (FSCM) should be enabled. Parameters Parameters Description index Identifies the desired oscillator module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. The data given by this API is valid only if clock switching and monitoring is enabled. Otherwise Clock and PLL selections are never locked and may be modified. Example PLIB_OSC_PLLClockLock(OSC_ID_0); 5.6.14.6.10.12 PLIB_OSC_PLLClockUnlock Function C void PLIB_OSC_PLLClockUnlock( OSC_MODULE_ID index ); Description This function unlocks the clock and PLL selection so that the clock and PLL may be modified. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2380 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLClockLock in your application to determine whether this feature is available. This function takes care of the register unlock, which is required per the device data sheet. Therefore, the user need not explicity perform the unlock sequence. Example PLIB_OSC_PLLClockUnlock(OSC_ID_0); 5.6.14.6.10.13 PLIB_OSC_PLLDisable Function C void PLIB_OSC_PLLDisable( OSC_MODULE_ID index, OSC_PLL_SELECT selectPLL ); Description This function disables the the specified PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module selectPLL PLL to be enabled. One of the possible values from OSC_PLL_SELECT. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLDisable(OSC_ID_0, OSC_PLL_SYSTEM); 5.6.14.6.10.14 PLIB_OSC_PLLEnable Function C void PLIB_OSC_PLLEnable( OSC_MODULE_ID index, OSC_PLL_SELECT selectPLL ); Description This function enables the the specified PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2381 selectPLL PLL to be enabled. One of the possible values from OSC_PLL_SELECT. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example PLIB_OSC_PLLEnable(OSC_ID_0, OSC_PLL_SYSTEM); 5.6.14.6.10.15 PLIB_OSC_PLLIsEnabled Function C bool PLIB_OSC_PLLIsEnabled( OSC_MODULE_ID index, OSC_PLL_SELECT selectPLL ); Description This function returns 'true' if the specified PLL is enabled. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module selectPLL PLL to be enabled. One of the possible values from OSC_PLL_SELECT. Returns • true - The specified PLL is enabled • false - The specified PLL is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability. Example if (PLIB_OSC_PLLIsEnabled(OSC_ID_0, OSC_PLL_SYSTEM)) { //Do some action } 5.6.14.6.10.16 PLIB_OSC_PLLIsLocked Function C bool PLIB_OSC_PLLIsLocked( OSC_MODULE_ID index, OSC_PLL_SELECT pllselect ); Description This function returns the status of the PLL lock. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2382 Parameters Parameters Description index Identifies the desired oscillator module pllselect Selects the PLL. Returns • true - PLL module is in lock or PLL module start-up timer is satisfied • false - PLL module is out of lock, PLL start-up timer is running, or PLL is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPLLLockStatus in your application to determine whether this feature is available. If the PLL does not stabilize properly during start-up, this function may not reflect the actual status of PLL lock, nor does it detect when the PLL loses lock during normal operation. Example bool lockPLL_status; lockPLL_status = PLIB_OSC_PLLIsLocked(OSC_ID_0, OSC_PLL_SYSTEM); 5.6.14.6.10.17 PLIB_OSC_SysPLLFrequencyRangeGet Function C OSC_SYSPLL_FREQ_RANGE PLIB_OSC_SysPLLFrequencyRangeGet( OSC_MODULE_ID index ); Description This function returns the frequence range set for PLL Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns PLLFrequencyRange - One of the possible values from OSC_SYSPLL_FREQ_RANGE Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLFrequencyRange in your application to determine whether this feature is available. Example OSC_SYSPLL_FREQ_RANGE PLLFrequencyRange; PLLFrequencyRange = PLIB_OSC_SysPLLFrequencyRangeGet(OSC_ID_0); 5.6.14.6.10.18 PLIB_OSC_SysPLLFrequencyRangeSet Function C void PLIB_OSC_SysPLLFrequencyRangeSet( OSC_MODULE_ID index, OSC_SYSPLL_FREQ_RANGE PLLFrequencyRange 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2383 ); Description This function sets the frequence range for PLL Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module PLLFrequencyRange One of the possible values from OSC_SYSPLL_FREQ_RANGE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLFrequencyRange in your application to determine whether this feature is available. Example PLIB_OSC_SysPLLFrequencyRangeSet(OSC_ID_0, OSC_SYSPLL_FREQ_RANGE_5M_TO_10M); 5.6.14.6.10.19 PLIB_OSC_SysPLLInputClockSourceGet Function C OSC_SYSPLL_IN_CLK_SOURCE PLIB_OSC_SysPLLInputClockSourceGet( OSC_MODULE_ID index ); Description This function returns the input clock source for the PLL module Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns PLLInClockSource - One of the possible values from OSC_SYSPLL_IN_CLK_SOURCE Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputClockSource in your application to determine whether this feature is available. Example OSC_SYSPLL_IN_CLK_SOURCE PLLInClockSource; PLLInClockSource = PLIB_OSC_SysPLLInputClockSourceGet(OSC_ID_0); 5.6.14.6.10.20 PLIB_OSC_SysPLLInputClockSourceSet Function C void PLIB_OSC_SysPLLInputClockSourceSet( 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2384 OSC_MODULE_ID index, OSC_SYSPLL_IN_CLK_SOURCE PLLInClockSource ); Description This function sets the input clock source for the PLL module Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module PLLInClockSource One of the possible values from OSC_SYSPLL_IN_CLK_SOURCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputClockSource in your application to determine whether this feature is available. Example PLIB_OSC_SysPLLInputClockSourceSet(OSC_ID_0, OSC_SYSPLL_IN_CLK_SOURCE_FRC); 5.6.14.6.10.21 PLIB_OSC_SysPLLInputDivisorGet Function C OSC_SYSPLL_IN_DIV PLIB_OSC_SysPLLInputDivisorGet( OSC_MODULE_ID index ); Description This function gets the input divisor for the PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values from OSC_SYSPLL_IN_DIV. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputDivisor in your application to determine whether this feature is available. Example OSC_SYSPLL_IN_DIV PLLInDiv; PLLInDiv = PLIB_OSC_SysPLLInputDivisorGet(OSC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2385 5.6.14.6.10.22 PLIB_OSC_SysPLLInputDivisorSet Function C void PLIB_OSC_SysPLLInputDivisorSet( OSC_MODULE_ID index, OSC_SYSPLL_IN_DIV PLLInDiv ); Description This function sets the input divider for the PLL to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module PLLInDiv One of the possible values from OSC_SYSPLL_In_DIV Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLInputDivisor in your application to determine whether this feature is available. Example PLIB_OSC_SysPLLInputDivisorSet(OSC_ID_0, OSC_SYSPLL_IN_DIV_1); 5.6.14.6.10.23 PLIB_OSC_SysPLLMultiplierGet Function C OSC_SYSPLL_MULTIPLIER_TYPE PLIB_OSC_SysPLLMultiplierGet( OSC_MODULE_ID index ); Description This function gets the PLL multiplier. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns One of the possible values of PB clock divisor of type OSC_SYSPLL_MULTIPLIER_TYPE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLMultiplier in your application to determine whether this feature is available. Actual Multipler value will be returned, NOT the 'PLLMULT' field value. Refer the data sheet of the device for the detail. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2386 Example OSC_SYSPLL_MULTIPLIER_TYPE pll_multiply; pll_multiply = PLIB_OSC_SysPLLMultiplierGet(OSC_ID_0); 5.6.14.6.10.24 PLIB_OSC_SysPLLMultiplierSelect Function C void PLIB_OSC_SysPLLMultiplierSelect( OSC_MODULE_ID index, OSC_SYSPLL_MULTIPLIER_TYPE pll_multiplier ); Description This function sets the PLL multiplier to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module pll_multiplier One of the possible values of PB clock divisor of type OSC_PLL_MUL_TYPE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLMultiplier in your application to determine whether this feature is available. Use PLL Multiplier value directly for the parameter 'pll_multiplier', NOT the value of the 'PLLMULT' field. Library behaviour is undefined in case of used PLL Multiplier value is not supported by the selected device. Refer the data sheet of the device for the detail. Example PLIB_OSC_SysPLLMultiplierSelect (OSC_ID_0, 0x08); 5.6.14.6.10.25 PLIB_OSC_SysPLLOutputDivisorGet Function C OSC_SYSPLL_OUT_DIV PLIB_OSC_SysPLLOutputDivisorGet( OSC_MODULE_ID index ); Description This function gets the output divisor for the PLL. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2387 Returns One of the possible values from OSC_SYSPLL_OUT_DIV. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLOutputDivisor in your application to determine whether this feature is available. Example OSC_SYSPLL_OUT_DIV PLLOutDiv; PLLOutDiv = PLIB_OSC_SysPLLOutputDivisorGet(OSC_ID_0); 5.6.14.6.10.26 PLIB_OSC_SysPLLOutputDivisorSet Function C void PLIB_OSC_SysPLLOutputDivisorSet( OSC_MODULE_ID index, OSC_SYSPLL_OUT_DIV PLLOutDiv ); Description This function sets the output divider for the PLL to the specified value. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module PLLOutDiv One of the possible values from OSC_SYSPLL_OUT_DIV Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsSysPLLOutputDivisor in your application to determine whether this feature is available. Example PLIB_OSC_SysPLLOutputDivisorSelect(OSC_ID_0, OSC_SYSPLL_OUT_DIV_1); 5.6.14.6.11 Peripheral Clock Setup Functions 5.6.14.6.11.1 PLIB_OSC_PBClockDivisorGet Function C OSC_PB_CLOCK_DIV_TYPE PLIB_OSC_PBClockDivisorGet( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ); Description This function gets the peripheral bus clock divisor. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2388 Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Returns One of the possible values of PB clock divisor of type OSC_PB_CLOCK_DIV_TYPE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockDivisor in your application to determine whether this feature is available. Actual Divisor value will be returned, NOT the 'PBDIV' field value. Refer the data sheet of the device for the detail. Example OSC_PB_CLOCK_DIV_TYPE peripheralBusClkDiv; peripheralBusClkDiv = PLIB_OSC_PBClockDivisorGet(OSC_ID_0, OSC_PERIPHERAL_BUS_1); 5.6.14.6.11.2 PLIB_OSC_PBClockDivisorIsReady Function C bool PLIB_OSC_PBClockDivisorIsReady( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ); Description This function checks whether the peripheral bus clock divisor is ready to be written. Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Returns • true - Peripheral bus clock divisor can be written • false - Peripheral bus clock divisor cannot be written Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockReady in your application to determine whether this feature is available. Example if (PLIB_OSC_PBClockDivisorIsReady(OSC_ID_0, OSC_PERIPHERAL_BUS_1)) { PLIB_OSC_PBClockDivisorSet (OSC_ID_0, OSC_PERIPHERAL_BUS_1, 0x01); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2389 } 5.6.14.6.11.3 PLIB_OSC_PBClockDivisorSet Function C void PLIB_OSC_PBClockDivisorSet( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber, OSC_PB_CLOCK_DIV_TYPE peripheralBusClkDiv ); Description This function sets the peripheral bus clock divisor to the specified value. Preconditions Peripheral bus clock divisor should be ready to be written. Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus peripheralBusClkDiv One of the possible values of PB clock divisor of type OSC_PB_CLOCK_DIV_TYPE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockDivisor in your application to determine whether this feature is available. Use PB Divider value directly for the parameter 'peripheralBusClkDiv', NOT the value of the 'PBDIV' field. Library behaviour is undefined in case of used PB Divider value is not supported by the selected device. Refer the data sheet of the device for the detail. Example PLIB_OSC_PBClockDivisorSet (OSC_ID_0, OSC_PERIPHERAL_BUS_1, 0x01); 5.6.14.6.11.4 PLIB_OSC_PBOutputClockDisable Function C void PLIB_OSC_PBOutputClockDisable( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ); Description This function disables the peripheral bus output clock Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2390 Returns None Remarks The clock for peripheral bus 1 cannot be turned off. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Example PLIB_OSC_PBOutputClockDisable (OSC_ID_0, OSC_PERIPHERAL_BUS_2); 5.6.14.6.11.5 PLIB_OSC_PBOutputClockEnable Function C void PLIB_OSC_PBOutputClockEnable( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ); Description This function enables the peripheral bus output clock Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Example PLIB_OSC_PBOutputClockEnable (OSC_ID_0, OSC_PERIPHERAL_BUS_2); 5.6.14.6.11.6 PLIB_OSC_PBOutputClockIsEnabled Function C bool PLIB_OSC_PBOutputClockIsEnabled( OSC_MODULE_ID index, OSC_PERIPHERAL_BUS peripheralBusNumber ); Description This function checks whether the peripheral bus clock output is enabled or not Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2391 Parameters Parameters Description index Identifies the desired oscillator module peripheralBusNumber Identifies the desired peripheral bus Returns • true - Peripheral bus clock output is enabled • false - Peripheral bus clock output is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsPBClockOutputEnable in your application to determine whether this feature is available. Example if (PLIB_OSC_PBOutputClockIsEnabled(OSC_ID_0, OSC_PERIPHERAL_BUS_2)) { PLIB_OSC_PBOutputClockDisable(OSC_ID_0, OSC_PERIPHERAL_BUS_2); } 5.6.14.6.12 Clock Fail Monitoring Functions 5.6.14.6.12.1 PLIB_OSC_ClockHasFailed Function C bool PLIB_OSC_ClockHasFailed( OSC_MODULE_ID index ); Description This function returns 'true' if the clock fails. Monitors the Fail-Safe Clock Monitor (FSCM). Preconditions None. Parameters Parameters Description index Identifies the desired oscillator module Returns • true - Fail-Safe Clock Monitor (FSCM) detected a clock failure • false - No clock failure has been detected Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_OSC_ExistsClockFail in your application to determine whether this feature is available. Example bool clockStatus; clockStatus = PLIB_OSC_ClockHasFailed(OSC_ID_0); 5.6.14.6.13 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2392 5.6.14.6.13.1 OSC_PB_CLOCK_DIV_TYPE Macro C #define OSC_PB_CLOCK_DIV_TYPE SFR_TYPE Description Oscillator Peripheral Bus Clock Divisor Value Type This macro defines the type of the oscillator PB Clock divisor value. Remarks None 5.6.14.6.13.2 OSC_REF_DIVISOR_TYPE Macro C #define OSC_REF_DIVISOR_TYPE SFR_TYPE Description Reference oscillator divisor type This macro defines the reference oscillator divisor type. Please refer to the specific device data sheet to determine the possible values of this type. Remarks None. 5.6.14.6.13.3 OSC_REFERENCE_MAX_DIV Macro C #define OSC_REFERENCE_MAX_DIV 65534 Description Reference clock output divisor maximum This macro defines the reference clock output divisor maximum value. Remarks None 5.6.14.6.13.4 OSC_SYSPLL_MULTIPLIER_TYPE Macro C #define OSC_SYSPLL_MULTIPLIER_TYPE SFR_TYPE Description Oscillator System PLL Multiplier Value Type This macro defines the type of the oscillator system PLL multiplier value. Remarks None 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2393 5.6.14.6.13.5 OSC_AUX_CLOCK_SOURCE Enumeration C typedef enum { OSC_AUX_CLOCK_PRIMARY } OSC_AUX_CLOCK_SOURCE; Description AUX PLL Input divider. This enumeration lists the possible Auxiliary PLL input divider values. Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.6 OSC_AUX_MODE Enumeration C typedef enum { OSC_AUX_MODE_EC, OSC_AUX_MODE_XT, OSC_AUX_MODE_HS, OSC_AUX_DISABLE } OSC_AUX_MODE; Description AUX Oscillator modes. This enumeration lists the possible Auxiliary Oscillator mode values. Members Members Description OSC_AUX_MODE_EC External clock Input OSC_AUX_MODE_XT Crystal/resonator OSC_AUX_MODE_HS High speed crystal OSC_AUX_DISABLE AUX Oscillator disabled Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.7 OSC_AUXPLL_IN_DIV Enumeration C typedef enum { OSC_AUXPLL_IN_DIV_1, OSC_AUXPLL_IN_DIV_2, OSC_AUXPLL_IN_DIV_3, OSC_AUXPLL_IN_DIV_4, OSC_AUXPLL_IN_DIV_5, OSC_AUXPLL_IN_DIV_6, OSC_AUXPLL_IN_DIV_10, OSC_AUXPLL_IN_DIV_12 } OSC_AUXPLL_IN_DIV; Description AUX PLL Input divider. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2394 This enumeration lists the possible Auxiliary PLL input divider values. Members Members Description OSC_AUXPLL_IN_DIV_1 Input divided by 1 OSC_AUXPLL_IN_DIV_2 Input divided by 2 OSC_AUXPLL_IN_DIV_3 Input divided by 3 OSC_AUXPLL_IN_DIV_4 Input divided by 4 OSC_AUXPLL_IN_DIV_5 Input divided by 5 OSC_AUXPLL_IN_DIV_6 Input divided by 6 OSC_AUXPLL_IN_DIV_10 Input divided by 10 OSC_AUXPLL_IN_DIV_12 Input divided by 12 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.8 OSC_AUXPLL_MULTIPLIER Enumeration C typedef enum { OSC_AUXPLL_MULTIPLIER_4 } OSC_AUXPLL_MULTIPLIER; Description Aux PLL Multiplier This enumeration lists the possible Auxiliary PLL multiplier Members Members Description OSC_AUXPLL_MULTIPLIER_4 Auxiliary PLL multiplier value is 1:4 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.9 OSC_AUXPLL_OUT_DIV Enumeration C typedef enum { OSC_AUXPLL_OUT_DIV_1, OSC_AUXPLL_OUT_DIV_2, OSC_AUXPLL_OUT_DIV_4, OSC_AUXPLL_OUT_DIV_8, OSC_AUXPLL_OUT_DIV_16, OSC_AUXPLL_OUT_DIV_32, OSC_AUXPLL_OUT_DIV_64, OSC_AUXPLL_OUT_DIV_256 } OSC_AUXPLL_OUT_DIV; Description AUX PLL Output divider. This enumeration lists the possible Auxiliary PLL output divider values. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2395 Members Members Description OSC_AUXPLL_OUT_DIV_1 output divided by 1 OSC_AUXPLL_OUT_DIV_2 output divided by 2 OSC_AUXPLL_OUT_DIV_4 output divided by 4 OSC_AUXPLL_OUT_DIV_8 output divided by 8 OSC_AUXPLL_OUT_DIV_16 output divided by 16 OSC_AUXPLL_OUT_DIV_32 output divided by 32 OSC_AUXPLL_OUT_DIV_64 output divided by 64 OSC_AUXPLL_OUT_DIV_256 output divided by 256 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.10 OSC_DOZE_RATIO Enumeration C typedef enum { OSC_DOZE_RATIO_1, OSC_DOZE_RATIO_2, OSC_DOZE_RATIO_4, OSC_DOZE_RATIO_8, OSC_DOZE_RATIO_16, OSC_DOZE_RATIO_32, OSC_DOZE_RATIO_64, OSC_DOZE_RATIO_128 } OSC_DOZE_RATIO; Description DOZE bits(CPU peripheral clock ratio selection). This enumeration lists the possible doze values(CPU clock to peripheral clock ratio). Members Members Description OSC_DOZE_RATIO_1 CPU peripheral clock ratio 1:1 OSC_DOZE_RATIO_2 CPU peripheral clock ratio 1:2 OSC_DOZE_RATIO_4 CPU peripheral clock ratio 1:4 OSC_DOZE_RATIO_8 CPU peripheral clock ratio 1:8 OSC_DOZE_RATIO_16 CPU peripheral clock ratio 1:16 OSC_DOZE_RATIO_32 CPU peripheral clock ratio 1:32 OSC_DOZE_RATIO_64 CPU peripheral clock ratio 1:64 OSC_DOZE_RATIO_128 CPU peripheral clock ratio 1:128 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.11 OSC_FRC_DIV Enumeration C typedef enum { OSC_FRC_DIV_1, 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2396 OSC_FRC_DIV_2, OSC_FRC_DIV_4, OSC_FRC_DIV_8, OSC_FRC_DIV_16, OSC_FRC_DIV_32, OSC_FRC_DIV_64, OSC_FRC_DIV_256 } OSC_FRC_DIV; Description FRC divider. This enumeration lists the possible FRC Oscillator divider values. Members Members Description OSC_FRC_DIV_1 Fast RC Oscillator output Divide by 1 OSC_FRC_DIV_2 Fast RC Oscillator output Divide by 2 OSC_FRC_DIV_4 Fast RC Oscillator output Divide by 4 OSC_FRC_DIV_8 Fast RC Oscillator output Divide by 8 OSC_FRC_DIV_16 Fast RC Oscillator output Divide by 16 OSC_FRC_DIV_32 Fast RC Oscillator output Divide by 32 OSC_FRC_DIV_64 Fast RC Oscillator output Divide by 64 OSC_FRC_DIV_256 Fast RC Oscillator output Divide by 256 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.12 OSC_FRC_TUNE Enumeration C typedef enum { OSC_FRC_TUNE_PLUS_3_PERCENT, OSC_FRC_TUNE_PLUS_2_57_PERCENT, OSC_FRC_TUNE_PLUS_2_54_PERCENT, OSC_FRC_TUNE_PLUS_1_71_PERCENT, OSC_FRC_TUNE_PLUS_1_29_PERCENT, OSC_FRC_TUNE_PLUS_0_86_PERCENT, OSC_FRC_TUNE_PLUS_0_43_PERCENT, OSC_FRC_TUNE_CENTRAL_FREQ, OSC_FRC_TUNE_MINUS_0_375_PERCENT, OSC_FRC_TUNE_MINUS_0_75_PERCENT, OSC_FRC_TUNE_MINUS_1_125_PERCENT, OSC_FRC_TUNE_MINUS_1_5_PERCENT, OSC_FRC_TUNE_MINUS_1_875_PERCENT, OSC_FRC_TUNE_MINUS_2_25_PERCENT, OSC_FRC_TUNE_MINUS_2_625_PERCENT, OSC_FRC_TUNE_MINUS_3_PERCENT } OSC_FRC_TUNE; Description Oscillator tuning value enumeration This enumeration lists the possible oscillator tuning values, and is used by the PLIB_OSC_FRCTuningSequenceValueSet and PLIB_OSC_FRCTuningSequenceValueGet functions. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2397 Members Members Description OSC_FRC_TUNE_PLUS_3_PERCENT OSC tune to Central frequency + 3 OSC_FRC_TUNE_PLUS_2_57_PERCENT OSC tune to Central frequency + 2.57 OSC_FRC_TUNE_PLUS_2_54_PERCENT OSC tune to Central frequency + 2.54 OSC_FRC_TUNE_PLUS_1_71_PERCENT OSC tune to Central frequency + 1.71 OSC_FRC_TUNE_PLUS_1_29_PERCENT OSC tune to Central frequency + 1.29 OSC_FRC_TUNE_PLUS_0_86_PERCENT OSC tune to Central frequency + 0.86 OSC_FRC_TUNE_PLUS_0_43_PERCENT OSC tune to Central frequency + 0.43 OSC_FRC_TUNE_CENTRAL_FREQ OSC tune to Central frequency OSC_FRC_TUNE_MINUS_0_375_PERCENT OSC tune to Central frequency - 0.375 OSC_FRC_TUNE_MINUS_0_75_PERCENT OSC tune to Central frequency - 0.75 OSC_FRC_TUNE_MINUS_1_125_PERCENT OSC tune to Central frequency - 1.125 OSC_FRC_TUNE_MINUS_1_5_PERCENT OSC tune to Central frequency - 1.5 OSC_FRC_TUNE_MINUS_1_875_PERCENT OSC tune to Central frequency - 1.875 OSC_FRC_TUNE_MINUS_2_25_PERCENT OSC tune to Central frequency - 2.25 OSC_FRC_TUNE_MINUS_2_625_PERCENT OSC tune to Central frequency - 2.625 OSC_FRC_TUNE_MINUS_3_PERCENT OSC tune to Central frequency - 3 Remarks None. 5.6.14.6.13.13 OSC_GFX_CLOCK Enumeration C typedef enum { OSC_GFX_CLOCK_96M, OSC_GFX_CLOCK_48M } OSC_GFX_CLOCK; Description Graphics module clock values. This enumeration lists the possible Graphics (display) module clock values. Members Members Description OSC_GFX_CLOCK_96M Graphics module clock is 96 MHz OSC_GFX_CLOCK_48M Graphics module clock is 48 MHz Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.14 OSC_LFSR_TYPE Enumeration C typedef enum { OSC_LFSR } OSC_LFSR_TYPE; 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2398 Description AUX PLL Input divider. This enumeration lists the possible Auxiliary PLL input divider values. Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.15 OSC_MODULE_ID Enumeration C typedef enum { OSC_ID_0 } OSC_MODULE_ID; Description OSC module ID This data type defines the possible instances of the OSC module. Members Members Description OSC_ID_0 first instance of the OSC Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.16 OSC_OPERATION_ON_WAIT Enumeration C typedef enum { OSC_ON_WAIT_IDLE, OSC_ON_WAIT_SLEEP } OSC_OPERATION_ON_WAIT; Description Oscillator Operation on wait. This enumeration lists the possible device status when a WAIT instruction is executed. Members Members Description OSC_ON_WAIT_IDLE Idle on Wait Instruction OSC_ON_WAIT_SLEEP Idle on Sleep Instruction Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.17 OSC_PERIPHERAL_BUS Enumeration C typedef enum { OSC_PERIPHERAL_BUS_1, OSC_PERIPHERAL_BUS_2, 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2399 OSC_PERIPHERAL_BUS_3, OSC_PERIPHERAL_BUS_4, OSC_PERIPHERAL_BUS_5, OSC_PERIPHERAL_BUS_6, OSC_PERIPHERAL_BUS_7, OSC_PERIPHERAL_BUS_8 } OSC_PERIPHERAL_BUS; Description Peripheral Buses This enumeration lists the possible peripheral buses available in the device Members Members Description OSC_PERIPHERAL_BUS_1 Peripheral bus 1 OSC_PERIPHERAL_BUS_2 Peripheral bus 2 OSC_PERIPHERAL_BUS_3 Peripheral bus 3 OSC_PERIPHERAL_BUS_4 Peripheral bus 4 OSC_PERIPHERAL_BUS_5 Peripheral bus 5 OSC_PERIPHERAL_BUS_6 Peripheral bus 6 OSC_PERIPHERAL_BUS_7 Peripheral bus 7 OSC_PERIPHERAL_BUS_8 Peripheral bus 8 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.18 OSC_PLL_SELECT Enumeration C typedef enum { OSC_PLL_SYSTEM, OSC_PLL_USB } OSC_PLL_SELECT; Description Oscillator PLL selection. This enumeration lists the available PLLs in the Oscillator module. Members Members Description OSC_PLL_SYSTEM Select system PLL OSC_PLL_USB Select USB PLL Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.19 OSC_PLLAUX_CLOCK_SOURCE Enumeration C typedef enum { OSC_PLLAUX_CLOCK } OSC_PLLAUX_CLOCK_SOURCE; 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2400 Description Auxiliary PLL Clock Source This enumeration lists the possible Auxiliary PLL clock source. Members Members Description OSC_PLLAUX_CLOCK PLL Auxiliary clock Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.20 OSC_REF_BASECLOCK Enumeration C typedef enum { OSC_REF_BASECLOCK_SYSCLK, OSC_REF_BASECLOCK_PBCLK, OSC_REF_BASECLOCK_PRIMARY, OSC_REF_BASECLOCK_FRC, OSC_REF_BASECLOCK_LPRC, OSC_REF_BASECLOCK_SOSC, OSC_REF_BASECLOCK_USBCLK, OSC_REF_BASECLOCK_SYSPLLOUT, OSC_REF_BASECLOCK_EXT } OSC_REF_BASECLOCK; Description Base clock for reference oscillator. This enumeration lists the possible base clock values for the reference oscillator. Members Members Description OSC_REF_BASECLOCK_SYSCLK The base clock for reference clock is System clock OSC_REF_BASECLOCK_PBCLK The base clock for reference clock is Peripheral clock OSC_REF_BASECLOCK_PRIMARY The base clock for reference clock is Primary oscillator OSC_REF_BASECLOCK_FRC The base clock for reference clock is FRC oscillator OSC_REF_BASECLOCK_LPRC The base clock for reference clock is internal low power RC OSC_REF_BASECLOCK_SOSC The base clock for reference clock is Secondary oscillator OSC_REF_BASECLOCK_USBCLK The base clock for reference clock is USB clock OSC_REF_BASECLOCK_SYSPLLOUT The base clock for reference clock is System PLL output OSC_REF_BASECLOCK_EXT The base clock for reference clock is clock from external pin Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.21 OSC_REF_DIV Enumeration C typedef enum { OSC_REF_DIV_1, OSC_REF_DIV_2, OSC_REF_DIV_4, 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2401 OSC_REF_DIV_8, OSC_REF_DIV_16, OSC_REF_DIV_32, OSC_REF_DIV_64, OSC_REF_DIV_128, OSC_REF_DIV_256, OSC_REF_DIV_512, OSC_REF_DIV_1024, OSC_REF_DIV_2048, OSC_REF_DIV_4096, OSC_REF_DIV_8192, OSC_REF_DIV_16384, OSC_REF_DIV_32768 } OSC_REF_DIV; Description Reference Oscillator divisor. This enumeration lists the possible reference oscillator divisor values. Members Members Description OSC_REF_DIV_1 Reference clock is same as base clock OSC_REF_DIV_2 Reference clock is base clock divided by 2 OSC_REF_DIV_4 Reference clock is base clock divided by 4 OSC_REF_DIV_8 Reference clock is base clock divided by 8 OSC_REF_DIV_16 Reference clock is base clock divided by 16 OSC_REF_DIV_32 Reference clock is base clock divided by 32 OSC_REF_DIV_64 Reference clock is base clock divided by 64 OSC_REF_DIV_128 Reference clock is base clock divided by 128 OSC_REF_DIV_256 Reference clock is base clock divided by 256 OSC_REF_DIV_512 Reference clock is base clock divided by 512 OSC_REF_DIV_1024 Reference clock is base clock divided by 1024 OSC_REF_DIV_2048 Reference clock is base clock divided by 2048 OSC_REF_DIV_4096 Reference clock is base clock divided by 4096 OSC_REF_DIV_8192 Reference clock is base clock divided by 8192 OSC_REF_DIV_16384 Reference clock is base clock divided by 16384 OSC_REF_DIV_32768 Reference clock is base clock divided by 32768 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.22 OSC_REFERENCE Enumeration C typedef enum { OSC_REFERENCE_1, OSC_REFERENCE_2, OSC_REFERENCE_3, OSC_REFERENCE_4 } OSC_REFERENCE; Description Reference Oscillators 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2402 This enumeration lists the possible reference oscillator instances available in the device Members Members Description OSC_REFERENCE_1 Reference Oscillator 1 OSC_REFERENCE_2 Reference Oscillator 2 OSC_REFERENCE_3 Reference Oscillator 3 OSC_REFERENCE_4 Reference Oscillator 4 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.23 OSC_SYS_CLOCK_DIV Enumeration C typedef enum { OSC_SYS_CLOCK_DIV_1, OSC_SYS_CLOCK_DIV_2, OSC_SYS_CLOCK_DIV_4, OSC_SYS_CLOCK_DIV_8 } OSC_SYS_CLOCK_DIV; Description System Clock selection. This enumeration lists the possible system clock divisor. Members Members Description OSC_SYS_CLOCK_DIV_1 System clock divide by 1 OSC_SYS_CLOCK_DIV_2 System clock divide by 2 OSC_SYS_CLOCK_DIV_4 System clock divide by 4 OSC_SYS_CLOCK_DIV_8 System clock divide by 8 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.24 OSC_SYS_TYPE Enumeration C typedef enum { OSC_FRC, OSC_FRC_WITH_PLL, OSC_PRIMARY, OSC_PRIMARY_WITH_PLL, OSC_SECONDARY, OSC_LPRC, OSC_FRC_DIV_BY_16, OSC_FRC_BY_FRCDIV } OSC_SYS_TYPE; Description Oscillator type. This enumeration lists the possible oscillator type values. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2403 Members Members Description OSC_FRC Fast RC Oscillator. This includes the 8MHz oscillator OSC_FRC_WITH_PLL Fast RC Oscillator with PLL OSC_PRIMARY Primary Oscillator OSC_PRIMARY_WITH_PLL Fast RC Oscillator with PLL and PostScaler. Includes the 8MHz oscillator OSC_SECONDARY Secondary Oscillator OSC_LPRC Low Power RC Oscillator OSC_FRC_DIV_BY_16 Low-Power Fast RC Oscillator with PostScaler OSC_FRC_BY_FRCDIV Fast RC Oscillator divided by FRCDIV bits Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.25 OSC_SYSPLL_FREQ_RANGE Enumeration C typedef enum { OSC_SYSPLL_FREQ_RANGE_BYPASS, OSC_SYSPLL_FREQ_RANGE_5M_TO_10M, OSC_SYSPLL_FREQ_RANGE_8M_TO_16M, OSC_SYSPLL_FREQ_RANGE_13M_TO_26M, OSC_SYSPLL_FREQ_RANGE_21M_TO_42M, OSC_SYSPLL_FREQ_RANGE_34M_TO_68M } OSC_SYSPLL_FREQ_RANGE; Description System PLL Frequency Range This enumeration lists the possible frequency range for PLL module available in the device Members Members Description OSC_SYSPLL_FREQ_RANGE_BYPASS PLL freq range bypass OSC_SYSPLL_FREQ_RANGE_5M_TO_10M PLL frequencey range is 5MHz to 10MHz OSC_SYSPLL_FREQ_RANGE_8M_TO_16M PLL frequencey range is 8MHz to 16MHz OSC_SYSPLL_FREQ_RANGE_13M_TO_26M PLL frequencey range is 13MHz to 26MHz OSC_SYSPLL_FREQ_RANGE_21M_TO_42M PLL frequencey range is 21MHz to 42MHz OSC_SYSPLL_FREQ_RANGE_34M_TO_68M PLL frequencey range is 34MHz to 68MHz Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.26 OSC_SYSPLL_IN_CLK_SOURCE Enumeration C typedef enum { OSC_SYSPLL_IN_CLK_SOURCE_FRC, OSC_SYSPLL_IN_CLK_SOURCE_PRIMARY } OSC_SYSPLL_IN_CLK_SOURCE; 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2404 Description System PLL Input Clock Source This enumeration lists the possible input clock source for PLL module available in the device Members Members Description OSC_SYSPLL_IN_CLK_SOURCE_FRC FRC is input clock source for PLL module OSC_SYSPLL_IN_CLK_SOURCE_PRIMARY Primary clock is the input clock source for PLL module Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.27 OSC_SYSPLL_IN_DIV Enumeration C typedef enum { OSC_SYSPLL_IN_DIV_1, OSC_SYSPLL_IN_DIV_2, OSC_SYSPLL_IN_DIV_3, OSC_SYSPLL_IN_DIV_4, OSC_SYSPLL_IN_DIV_5, OSC_SYSPLL_IN_DIV_6, OSC_SYSPLL_IN_DIV_7, OSC_SYSPLL_IN_DIV_8 } OSC_SYSPLL_IN_DIV; Description PLL Input divider. This enumeration lists the possible PLL input divider values. Members Members Description OSC_SYSPLL_IN_DIV_1 Divide by 1 OSC_SYSPLL_IN_DIV_2 Divide by 2 OSC_SYSPLL_IN_DIV_3 Divide by 4 OSC_SYSPLL_IN_DIV_4 Divide by 8 OSC_SYSPLL_IN_DIV_5 Divide by 16 OSC_SYSPLL_IN_DIV_6 Divide by 32 OSC_SYSPLL_IN_DIV_7 Divide by 64 OSC_SYSPLL_IN_DIV_8 Divide by 256 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.28 OSC_SYSPLL_OUT_DIV Enumeration C typedef enum { OSC_SYSPLL_OUT_DIV_1, OSC_SYSPLL_OUT_DIV_2, OSC_SYSPLL_OUT_DIV_4, OSC_SYSPLL_OUT_DIV_8, 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2405 OSC_SYSPLL_OUT_DIV_16, OSC_SYSPLL_OUT_DIV_32, OSC_SYSPLL_OUT_DIV_64, OSC_SYSPLL_OUT_DIV_256 } OSC_SYSPLL_OUT_DIV; Description PLL Output divider. This enumeration lists the possible PLL output divider values. Members Members Description OSC_SYSPLL_OUT_DIV_1 Divide by 1 OSC_SYSPLL_OUT_DIV_2 Divide by 2 OSC_SYSPLL_OUT_DIV_4 Divide by 4 OSC_SYSPLL_OUT_DIV_8 Divide by 8 OSC_SYSPLL_OUT_DIV_16 Divide by 16 OSC_SYSPLL_OUT_DIV_32 Divide by 32 OSC_SYSPLL_OUT_DIV_64 Divide by 64 OSC_SYSPLL_OUT_DIV_256 Divide by 256 Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.13.29 OSC_TUNING_MODE Enumeration C typedef enum { OSC_TUNING_USING_NUMBER, OSC_TUNING_SEQ_DITHER, OSC_TUNING_PSEUDO_RANDOM } OSC_TUNING_MODE; Description Oscillator Tuning modes enumeration This enumeration lists the possible oscillator tuning modes, and is used by the PLIB_OSC_FRCTuningModeSet and PLIB_OSC_FRCTuningModeGet functions. Members Members Description OSC_TUNING_USING_NUMBER FRC tuning is based on the number specified by the software. Set the number using PLIB_OSC_FRCTuningModeSet function OSC_TUNING_SEQ_DITHER FRC tuning is based on PWM OSC_TUNING_PSEUDO_RANDOM FRC tuning is Pseudo-Random number generation. Remarks None. 5.6.14.6.13.30 OSC_TUNING_SEQUENCERS Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2406 OSC_TUNING_SEQUENCER_1, OSC_TUNING_SEQUENCER_2, OSC_TUNING_SEQUENCER_3, OSC_TUNING_SEQUENCER_4, OSC_TUNING_SEQUENCER_5, OSC_TUNING_SEQUENCER_6, OSC_TUNING_SEQUENCER_7 } OSC_TUNING_SEQUENCERS; Description Oscillator sequencer entries This enumeration lists the possible oscillator sequencers that are used by the PLIB_OSC_FRCTuningSequenceValueSet and PLIB_OSC_FRCTuningSequenceValueGet functions to tune the FRC Oscillator. Members Members Description OSC_TUNING_SEQUENCER_1 OSC tuning sequencer 1 OSC_TUNING_SEQUENCER_2 OSC tuning sequencer 2 OSC_TUNING_SEQUENCER_3 OSC tuning sequencer 3 OSC_TUNING_SEQUENCER_4 OSC tuning sequencer 4 OSC_TUNING_SEQUENCER_5 OSC tuning sequencer 5 OSC_TUNING_SEQUENCER_6 OSC tuning sequencer 6 OSC_TUNING_SEQUENCER_7 OSC tuning sequencer 7 Remarks None. 5.6.14.6.13.31 OSC_USBCLOCK_SOURCE Enumeration C typedef enum { SYS_OSC_USBCLK_PRIMARY, SYS_OSC_USBCLK_FRC } OSC_USBCLOCK_SOURCE; Description USB clock sources. This enumeration lists the the possible USB clock sources. Members Members Description SYS_OSC_USBCLK_PRIMARY USB clock source is primary oscillator SYS_OSC_USBCLK_FRC USB clock source isFRC oscillator Remarks This enumeration is processor specific and is defined in the processor- specific header files. 5.6.14.6.14 Feature Existence Functions 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2407 5.6.14.6.14.1 PLIB_OSC_ExistsClockFail Function C bool PLIB_OSC_ExistsClockFail( OSC_MODULE_ID index ); Description This function identifies whether the ClockFail feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockHasFailed Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ClockFail feature is supported on the device • false - If the ClockFail feature is not supported on the device Remarks None. 5.6.14.6.14.2 PLIB_OSC_ExistsFRCDivisor Function C bool PLIB_OSC_ExistsFRCDivisor( OSC_MODULE_ID index ); Description This function identifies whether the FRCDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_FRCDivisorSelect • PLIB_OSC_FRCDivisorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FRCDivisor feature is supported on the device • false - If the FRCDivisor feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2408 5.6.14.6.14.3 PLIB_OSC_ExistsFRCTuning Function C bool PLIB_OSC_ExistsFRCTuning( OSC_MODULE_ID index ); Description This function identifies whether the FRCTuning feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_FRCTuningSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the FRCTuning feature is supported on the device • false - If the FRCTuning feature is not supported on the device Remarks None. 5.6.14.6.14.4 PLIB_OSC_ExistsOnWaitAction Function C bool PLIB_OSC_ExistsOnWaitAction( OSC_MODULE_ID index ); Description This function identifies whether the OnWaitAction feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_OnWaitActionSet • PLIB_OSC_OnWaitActionGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the OnWaitAction feature is supported on the device • false - If the OnWaitAction feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2409 5.6.14.6.14.5 PLIB_OSC_ExistsOscCurrentGet Function C bool PLIB_OSC_ExistsOscCurrentGet( OSC_MODULE_ID index ); Description This function identifies whether the OscCurrentGet feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_CurrentSysClockGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the OscCurrentGet feature is supported on the device • false - If the OscCurrentGet feature is not supported on the device Remarks None. 5.6.14.6.14.6 PLIB_OSC_ExistsOscSelect Function C bool PLIB_OSC_ExistsOscSelect( OSC_MODULE_ID index ); Description This function identifies whether the OscSelect feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysClockSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the OscSelect feature is supported on the device • false - If the OscSelect feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2410 5.6.14.6.14.7 PLIB_OSC_ExistsOscSwitchInit Function C bool PLIB_OSC_ExistsOscSwitchInit( OSC_MODULE_ID index ); Description This function identifies whether the OscSwitchInit feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ClockSwitchingAbort • PLIB_OSC_ClockSwitchingIsComplete Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the OscSwitchInit feature is supported on the device • false - If the OscSwitchInit feature is not supported on the device Remarks None. 5.6.14.6.14.8 PLIB_OSC_ExistsPBClockDivisor Function C bool PLIB_OSC_ExistsPBClockDivisor( OSC_MODULE_ID index ); Description This function identifies whether the PBClockDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBClockDivisorGet • PLIB_OSC_PBClockDivisorSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PBClockDivisor feature is supported on the device • false - If the PBClockDivisor feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2411 Remarks None. 5.6.14.6.14.9 PLIB_OSC_ExistsPBClockOutputEnable Function C bool PLIB_OSC_ExistsPBClockOutputEnable( OSC_MODULE_ID index ); Description This function identifies whether the PBClockOutputEnable feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBOutputClockEnable • PLIB_OSC_PBOutputClockDisable • PLIB_OSC_PBOutputClockIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PBClockOutputEnable feature is supported on the device • false - If the PBClockOutputEnable feature is not supported on the device Remarks None. 5.6.14.6.14.10 PLIB_OSC_ExistsPBClockReady Function C bool PLIB_OSC_ExistsPBClockReady( OSC_MODULE_ID index ); Description This function identifies whether the PBClockReady feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PBClockDivisorIsReady Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2412 Returns • true - If the PBClockReady feature is supported on the device • false - If the PBClockReady feature is not supported on the device Remarks None. 5.6.14.6.14.11 PLIB_OSC_ExistsPLLClockLock Function C bool PLIB_OSC_ExistsPLLClockLock( OSC_MODULE_ID index ); Description This function identifies whether the PLLClockLock feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PLLClockLock • PLIB_OSC_PLLClockUnlock • PLIB_OSC_PLLClockIsLocked Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLClockLock feature is supported on the device • false - If the PLLClockLock feature is not supported on the device Remarks None. 5.6.14.6.14.12 PLIB_OSC_ExistsPLLLockStatus Function C bool PLIB_OSC_ExistsPLLLockStatus( OSC_MODULE_ID index ); Description This function identifies whether the PLLLockStatus feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_PLLIsLocked Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2413 Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLLockStatus feature is supported on the device • false - If the PLLLockStatus feature is not supported on the device Remarks None. 5.6.14.6.14.13 PLIB_OSC_ExistsReferenceOscBaseClock Function C bool PLIB_OSC_ExistsReferenceOscBaseClock( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscBaseClock feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscBaseClockSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscBaseClock feature is supported on the device • false - If the ReferenceOscBaseClock feature is not supported on the device Remarks None. 5.6.14.6.14.14 PLIB_OSC_ExistsReferenceOscChange Function C bool PLIB_OSC_ExistsReferenceOscChange( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscChange feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscSwitchIsComplete Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2414 Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscChange feature is supported on the device • false - If the ReferenceOscChange feature is not supported on the device Remarks None. 5.6.14.6.14.15 PLIB_OSC_ExistsReferenceOscChangeActive Function C bool PLIB_OSC_ExistsReferenceOscChangeActive( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscChangeActive feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscSourceChangeIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscChangeActive feature is supported on the device • false - If the ReferenceOscChangeActive feature is not supported on the device Remarks None. 5.6.14.6.14.16 PLIB_OSC_ExistsReferenceOscDivisor Function C bool PLIB_OSC_ExistsReferenceOscDivisor( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscDivisorValueSet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2415 Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscDivisor feature is supported on the device • false - If the ReferenceOscDivisor feature is not supported on the device Remarks None. 5.6.14.6.14.17 PLIB_OSC_ExistsReferenceOscEnable Function C bool PLIB_OSC_ExistsReferenceOscEnable( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscEnable feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscEnable • PLIB_OSC_ReferenceOscDisable • PLIB_OSC_ReferenceOscIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscEnable feature is supported on the device • false - If the ReferenceOscEnable feature is not supported on the device Remarks None. 5.6.14.6.14.18 PLIB_OSC_ExistsReferenceOscStopInIdleEnable Function C bool PLIB_OSC_ExistsReferenceOscStopInIdleEnable( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscStopInIdleEnable feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscStopInIdleEnable 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2416 • PLIB_OSC_ReferenceOscStopInIdleDisable • PLIB_OSC_ReferenceOscStopInIdleIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscStopInIdleEnable feature is supported on the device • false - If the ReferenceOscStopInIdleEnable feature is not supported on the device Remarks None. 5.6.14.6.14.19 PLIB_OSC_ExistsReferenceOscStopInSleep Function C bool PLIB_OSC_ExistsReferenceOscStopInSleep( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOscStopInSleep feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscStopInSleepEnable • PLIB_OSC_ReferenceOscStopInSleepDisable • PLIB_OSC_ReferenceOscStopInSleepIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscStopInSleep feature is supported on the device • false - If the ReferenceOscStopInSleep feature is not supported on the device Remarks None. 5.6.14.6.14.20 PLIB_OSC_ExistsReferenceOscTrim Function C bool PLIB_OSC_ExistsReferenceOscTrim( OSC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2417 Description This function identifies whether the ReferenceOscTrim feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOscTrimSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOscTrim feature is supported on the device • false - If the ReferenceOscTrim feature is not supported on the device Remarks None. 5.6.14.6.14.21 PLIB_OSC_ExistsReferenceOutputEnable Function C bool PLIB_OSC_ExistsReferenceOutputEnable( OSC_MODULE_ID index ); Description This function identifies whether the ReferenceOutputEnable feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_ReferenceOutputEnable • PLIB_OSC_ReferenceOutputDisable • PLIB_OSC_ReferenceOutputIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the ReferenceOutputEnable feature is supported on the device • false - If the ReferenceOutputEnable feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2418 5.6.14.6.14.22 PLIB_OSC_ExistsSecondaryEnable Function C bool PLIB_OSC_ExistsSecondaryEnable( OSC_MODULE_ID index ); Description This function identifies whether the SecondaryEnable feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SecondaryEnable • PLIB_OSC_SecondaryDisable • PLIB_OSC_SecondaryIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SecondaryEnable feature is supported on the device • false - If the SecondaryEnable feature is not supported on the device Remarks None. 5.6.14.6.14.23 PLIB_OSC_ExistsSecondaryReady Function C bool PLIB_OSC_ExistsSecondaryReady( OSC_MODULE_ID index ); Description This function identifies whether the SecondaryReady feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SecondaryIsReady Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the SecondaryReady feature is supported on the device • false - If the SecondaryReady feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2419 Remarks None. 5.6.14.6.14.24 PLIB_OSC_ExistsSysPLLFrequencyRange Function C bool PLIB_OSC_ExistsSysPLLFrequencyRange( OSC_MODULE_ID index ); Description This function identifies whether the PLLFrequencyRange feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLFrequencyRangeSet • PLIB_OSC_SysPLLFrequencyRangeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLFrequencyRange feature is supported on the device • false - If the PLLFrequencyRange feature is not supported on the device Remarks None. 5.6.14.6.14.25 PLIB_OSC_ExistsSysPLLInputClockSource Function C bool PLIB_OSC_ExistsSysPLLInputClockSource( OSC_MODULE_ID index ); Description This function identifies whether the PLLInputClockSource feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLInputClockSourceSet • PLIB_OSC_SysPLLInputClockSourceGet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2420 Returns • true - If the PLLInputClockSource feature is supported on the device • false - If the PLLInputClockSource feature is not supported on the device Remarks None. 5.6.14.6.14.26 PLIB_OSC_ExistsSysPLLInputDivisor Function C bool PLIB_OSC_ExistsSysPLLInputDivisor( OSC_MODULE_ID index ); Description This function identifies whether the PLLInputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLInputDivisorSet • PLIB_OSC_SysPLLInputDivisorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLInputDivisor feature is supported on the device • false - If the PLLInputDivisor feature is not supported on the device Remarks None. 5.6.14.6.14.27 PLIB_OSC_ExistsSysPLLMultiplier Function C bool PLIB_OSC_ExistsSysPLLMultiplier( OSC_MODULE_ID index ); Description This function identifies whether the PLLMultiplier feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLMultiplierSelect • PLIB_OSC_SysPLLMultiplierGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2421 Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLMultiplier feature is supported on the device • false - If the PLLMultiplier feature is not supported on the device Remarks None. 5.6.14.6.14.28 PLIB_OSC_ExistsSysPLLOutputDivisor Function C bool PLIB_OSC_ExistsSysPLLOutputDivisor( OSC_MODULE_ID index ); Description This function identifies whether the PLLOutputDivisor feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_SysPLLOutputDivisorSet • PLIB_OSC_SysPLLOutputDivisorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the PLLOutputDivisor feature is supported on the device • false - If the PLLOutputDivisor feature is not supported on the device Remarks None. 5.6.14.6.14.29 PLIB_OSC_ExistsUsbClockSource Function C bool PLIB_OSC_ExistsUsbClockSource( OSC_MODULE_ID index ); Description This function identifies whether the UsbClockSource feature is available on the OSC module. When this function returns true, these functions are supported on the device: • PLIB_OSC_UsbClockSourceSelect • PLIB_OSC_UsbClockSourceGet 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2422 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - If the UsbClockSource feature is supported on the device • false - If the UsbClockSource feature is not supported on the device Remarks None. 5.6.14.7 Files Files Name Description plib_osc.h Defines the Oscillator (OSC) Peripheral Library interface. Description 5.6.14.7.1 plib_osc.h Oscillator Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Oscillator (OSC) Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Oscillator module. Functions Name Description PLIB_OSC_AuxClockSourceGet Gets the clock source for the auxiliary clock. PLIB_OSC_AuxClockSourceSet Sets the clock source for the auxiliary clock divisor. PLIB_OSC_AuxModeGet Gets the selected Auxiliary Oscillator mode. PLIB_OSC_AuxModeSelect Selects the Auxiliary Oscillator mode. PLIB_OSC_ClockHasFailed Returns 'true' if the clock fails. PLIB_OSC_ClockSwitchingAbort Aborts an oscillator switch. PLIB_OSC_ClockSwitchingIsComplete Gets the oscillator switch progress status. PLIB_OSC_CurrentSysClockGet Gets the current oscillator selected. PLIB_OSC_DozeModeDisable Disables Doze mode. PLIB_OSC_DozeModeEnable Enables Doze mode. PLIB_OSC_DozeRatioGet Gets the ratio of the processor clock to the peripheral clock. PLIB_OSC_DozeRatioSelect Selects the Doze ratio of the processor clock to the peripheral clock. PLIB_OSC_DozeRecoverOnInterruptDisable Disables the recovery from Doze mode upon an interrupt. PLIB_OSC_DozeRecoverOnInterruptEnable Enables recovery from Doze mode upon an interrupt. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2423 PLIB_OSC_DozeRecoverOnInterruptIsEnabled Returns 'true' if recover from Doze mode on interrupt is enabled. PLIB_OSC_ExistsClockFail Identifies whether the ClockFail feature exists on the OSC module PLIB_OSC_ExistsFRCDivisor Identifies whether the FRCDivisor feature exists on the OSC module PLIB_OSC_ExistsFRCTuning Identifies whether the FRCTuning feature exists on the OSC module PLIB_OSC_ExistsOnWaitAction Identifies whether the OnWaitAction feature exists on the OSC module PLIB_OSC_ExistsOscCurrentGet Identifies whether the OscCurrentGet feature exists on the OSC module PLIB_OSC_ExistsOscSelect Identifies whether the OscSelect feature exists on the OSC module PLIB_OSC_ExistsOscSwitchInit Identifies whether the OscSwitchInit feature exists on the OSC module PLIB_OSC_ExistsPBClockDivisor Identifies whether the PBClockDivisor feature exists on the OSC module PLIB_OSC_ExistsPBClockOutputEnable Identifies whether the PBClockOutputEnable feature exists on the OSC module PLIB_OSC_ExistsPBClockReady Identifies whether the PBClockReady feature exists on the OSC module PLIB_OSC_ExistsPLLClockLock Identifies whether the PLLClockLock feature exists on the OSC module PLIB_OSC_ExistsPLLLockStatus Identifies whether the PLLLockStatus feature exists on the OSC module PLIB_OSC_ExistsReferenceOscBaseClock Identifies whether the ReferenceOscBaseClock feature exists on the OSC module PLIB_OSC_ExistsReferenceOscChange Identifies whether the ReferenceOscChange feature exists on the OSC module PLIB_OSC_ExistsReferenceOscChangeActive Identifies whether the ReferenceOscChangeActive feature exists on the OSC module PLIB_OSC_ExistsReferenceOscDivisor Identifies whether the ReferenceOscDivisor feature exists on the OSC module PLIB_OSC_ExistsReferenceOscEnable Identifies whether the ReferenceOscEnable feature exists on the OSC module PLIB_OSC_ExistsReferenceOscStopInIdleEnable Identifies whether the ReferenceOscStopInIdleEnable feature exists on the OSC module PLIB_OSC_ExistsReferenceOscStopInSleep Identifies whether the ReferenceOscStopInSleep feature exists on the OSC module PLIB_OSC_ExistsReferenceOscTrim Identifies whether the ReferenceOscTrim feature exists on the OSC module PLIB_OSC_ExistsReferenceOutputEnable Identifies whether the ReferenceOutputEnable feature exists on the OSC module PLIB_OSC_ExistsSecondaryEnable Identifies whether the SecondaryEnable feature exists on the OSC module PLIB_OSC_ExistsSecondaryReady Identifies whether the SecondaryReady feature exists on the OSC module PLIB_OSC_ExistsSysPLLFrequencyRange Identifies whether the PLLFrequencyRange feature exists on the OSC module PLIB_OSC_ExistsSysPLLInputClockSource Identifies whether the PLLInputClockSource feature exists on the OSC module 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2424 PLIB_OSC_ExistsSysPLLInputDivisor Identifies whether the PLLInputDivisor feature exists on the OSC module PLIB_OSC_ExistsSysPLLMultiplier Identifies whether the PLLMultiplier feature exists on the OSC module PLIB_OSC_ExistsSysPLLOutputDivisor Identifies whether the PLLOutputDivisor feature exists on the OSC module PLIB_OSC_ExistsUsbClockSource Identifies whether the UsbClockSource feature exists on the OSC module PLIB_OSC_FRCDitherEnable Enables the FRC Oscillator clock dithering. PLIB_OSC_FRCDivisorGet Gets the FRC clock divisor. PLIB_OSC_FRCDivisorSelect Sets the FRC clock divisor to the specified value. PLIB_OSC_FRCTuningModeGet Gets the FRC oscillator tuning mode. PLIB_OSC_FRCTuningModeSet Selects the FRC oscillator tuning mode. PLIB_OSC_FRCTuningSelect Sets the FRC tuning value. PLIB_OSC_FRCTuningSequenceValueGet Gets the value set in the FRC tune sequencer. PLIB_OSC_FRCTuningSequenceValueSet Sets the value in the FRC tune sequencer. PLIB_OSC_GraphicsClockDivisorGet Gets the Graphics module clock divisor. PLIB_OSC_GraphicsClockDivisorSet Sets the Graphics module clock divisor. PLIB_OSC_GraphicsClockSourceGet Gets the Graphics Controller module clock frequency value. PLIB_OSC_GraphicsClockSourceSelect Sets the Graphics Controller module clock. PLIB_OSC_LinearFeedbackShiftRegGet Gets the value from linear feedback shift register. PLIB_OSC_LinearFeedbackShiftRegSet Sets the linear feedback shift register. PLIB_OSC_OnWaitActionGet Gets the configured operation to be performed when a WAIT instruction is executed. PLIB_OSC_OnWaitActionSet Selects the operation to be performed when a WAIT instruction is executed. PLIB_OSC_PBClockDivisorGet Gets the peripheral bus clock divisor. PLIB_OSC_PBClockDivisorIsReady Checks whether the peripheral bus clock divisor is ready to be written. PLIB_OSC_PBClockDivisorSet Sets the peripheral bus clock divisor to the specified value. PLIB_OSC_PBOutputClockDisable Disables the peripheral bus output clock PLIB_OSC_PBOutputClockEnable Enables the peripheral bus output clock PLIB_OSC_PBOutputClockIsEnabled Checks whether the peripheral bus clock output is enabled or not PLIB_OSC_PLLAuxClockSourceGet Returns the clock source selected for the Auxiliary PLL. PLIB_OSC_PLLAuxClockSourceSelect Sets the Auxiliary PLL clock source. PLIB_OSC_PLLAuxInputDivisorGet Gets the input divisor for the Auxiliary PLL. PLIB_OSC_PLLAuxInputDivisorSelect Sets the input divisor for the Auxiliary PLL to the specified value. PLIB_OSC_PLLAuxIsLocked Returns whether the Auxiliary PLL is locked. PLIB_OSC_PLLAuxMultiplierGet Gets the Auxiliary PLL multiplier. PLIB_OSC_PLLAuxMultiplierSelect Sets the Auxiliary PLL multiplier to the specified value. PLIB_OSC_PLLAuxOutputDivisorGet Gets the output divisor for the Auxiliary PLL. PLIB_OSC_PLLAuxOutputDivisorSet Sets the output divisor for the Auxiliary PLL to the specified value. PLIB_OSC_PLLClockIsLocked Gets the lock status for the clock and PLL selections. PLIB_OSC_PLLClockLock Locks the clock and PLL selections. PLIB_OSC_PLLClockUnlock Unlocks the clock and PLL selections. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2425 PLIB_OSC_PLLDisable Disables the specified PLL. PLIB_OSC_PLLEnable Enables the specified PLL. PLIB_OSC_PLLIsEnabled Returns 'true' if the specified PLL is enabled. PLIB_OSC_PLLIsLocked Returns 'true' if the selected PLL is locked. PLIB_OSC_PrimaryOscInSleepModeDisable The Primary Oscillator is disabled during Sleep mode. PLIB_OSC_PrimaryOscInSleepModeEnable The Primary Oscillator continues to operate during Sleep mode. PLIB_OSC_PrimaryOscInSleepModeIsEnabled Returns 'true' if the Primary Oscillator is disabled during Sleep mode. PLIB_OSC_ReferenceOscBaseClockSelect Sets the base clock for the reference oscillator. PLIB_OSC_ReferenceOscDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOscDivisorValueSet Selects the reference oscillator divisor value. PLIB_OSC_ReferenceOscEnable Enables the reference oscillator. PLIB_OSC_ReferenceOscIsEnabled Gets the enable status of the reference oscillator output. PLIB_OSC_ReferenceOscSourceChangeIsActive Returns 'true' if a reference oscillator source change request is active. PLIB_OSC_ReferenceOscStopInIdleDisable Enables the reference oscillator in Idle mode. PLIB_OSC_ReferenceOscStopInIdleEnable Configures the reference oscillator to stop operating in Idle mode. PLIB_OSC_ReferenceOscStopInIdleIsEnabled Returns 'true' if the reference oscillator is disabled in Idle mode. PLIB_OSC_ReferenceOscStopInSleepDisable Enables the reference oscillator in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepEnable Configures the reference oscillator to stop operating in Sleep mode. PLIB_OSC_ReferenceOscStopInSleepIsEnabled Returns 'true' if the reference oscillator is disabled in Sleep mode. PLIB_OSC_ReferenceOscSwitchIsComplete Returns 'true' if the reference oscillator base clock switching is complete. PLIB_OSC_ReferenceOscTrimSet Sets the reference oscillator divisor trim value. PLIB_OSC_ReferenceOutputDisable Disables the reference oscillator output. PLIB_OSC_ReferenceOutputEnable Enables the reference oscillator output. PLIB_OSC_ReferenceOutputIsEnabled Returns 'true' if the reference oscillator output is enabled. PLIB_OSC_SecondaryDisable Disables the Secondary Oscillator. PLIB_OSC_SecondaryEnable Enables the Secondary Oscillator. PLIB_OSC_SecondaryIsEnabled Returns 'true' if the Secondary Oscillator is enabled. PLIB_OSC_SecondaryIsReady Returns 'true' if the Secondary Oscillator is ready. PLIB_OSC_StartupTimerHasExpired Returns 'true' if the oscillator start-up time-out timer has expired. PLIB_OSC_SysClockSelect Selects the new oscillator. PLIB_OSC_SysPLLFrequencyRangeGet Returns the frequence range for PLL PLIB_OSC_SysPLLFrequencyRangeSet Sets the frequence range for PLL PLIB_OSC_SysPLLInputClockSourceGet Returns the input clock source for the PLL module PLIB_OSC_SysPLLInputClockSourceSet Sets the input clock source for the PLL module PLIB_OSC_SysPLLInputDivisorGet Gets the input divisor for the PLL. PLIB_OSC_SysPLLInputDivisorSet Sets the input divider for the PLL to the specified value. PLIB_OSC_SysPLLMultiplierGet Gets the PLL multiplier. PLIB_OSC_SysPLLMultiplierSelect Sets the PLL multiplier to the specified value. PLIB_OSC_SysPLLOutputDivisorGet Gets the output divisor for the PLL. PLIB_OSC_SysPLLOutputDivisorSet Sets the output divider for the PLL to the specified value. PLIB_OSC_UsbClockSourceGet Gets the USB module clock source. 5.6 Peripheral Library Help MPLAB Harmony Help Oscillator Peripheral Library 5-2426 PLIB_OSC_UsbClockSourceSelect Sets the USB module clock source. File Name plib_osc.h Company Microchip Technology Inc. 5.6.15 Prefetch Cache Peripheral Library 5.6.15.1 Introduction Prefetch Cache Module Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Prefetch Cache module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Prefetch Cache Module Overview The Prefetch Cache module increases system performance for most applications by: • Predictive prefetching of instructions ahead of the current program counter, hiding the access time of the Flash memory • Instruction and data caching The program Flash memory (PFM) contains a Prefetch module and a number of cache lines, each containing four words. Some of the cache lines may be allocated to data or peripherals. Each cache line has an associated tag. The tag contains the address of the data in the cache line, and a number of status bits. The number of cache lines and number and type of status bits may vary between devices. Refer to your specific device data sheet for details. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2427 5.6.15.2 Release Notes MPLAB Harmony Version: v0.70b Prefetch Cache Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.15.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.15.4 Using the Library This topic describes the basic architecture of the Prefetch Cache Peripheral Library and provides information and examples on how to use it. Interface Header File: peripheral.h The interface to the Prefetch Cache Peripheral Library is defined in the "plib_pcache.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Prefetch Cache Peripheral Library must include "peripheral.h". Library File: The Prefetch Cache Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6.15.4.1 Library Architecture The cache consists of two arrays: tag and data. The data array contains a number of lines of program instructions or data words. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2428 The word size is the same as the processor data width. The tag array contains a number of corresponding fields, each containing: • Mask – address mask value • Tag – tag address to match against • Valid – indicates whether the data in the cache line is valid or not • Lock – indicates the line is locked to hold its contents • Type – instruction, data or peripheral Note: Not all Tag fields are available on all devices. The number of cache lines may vary between devices. Refer to the specific device data sheet for details. Example Cache Line This library allows the programmer to perform various operations on the cache tag and data arrays: • Enable/Disable • Set the Wait state • Read, write, lock, invalidate Note: Not all operations are available on all devices. Refer to the specific device data sheet for details. 5.6.15.4.2 Hardware Abstraction Model This library provides a low-level abstraction of the Prefetch Cache module on Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model The Prefetch Cache module is a performance enhancing module included in some microcontrollers. When running at high clock rates, wait states must be inserted into program Flash memory (PFM) read transactions to meet the access time of the PFM. Wait states can be hidden to the core by prefetching and storing instructions in a temporary holding area that the CPU can access quickly. There are two main functions that the Prefetch Cache module performs: Caching instructions when they are accessed, and prefetching instructions from the PFM before they are needed. The cache holds a subset of the cacheable memory in temporary holding spaces known as cache lines. Each cache line has a tag describing what it is currently holding, and the address where it is mapped. Normally, the cache lines just hold a copy of what is currently in memory to make data available to the CPU without wait states. CPU-requested data may or may not be in the cache. A cache-miss occurs if the CPU requests cacheable data that is not in the cache. In this case, a read is performed to the PFM at the correct address, the data is supplied to the cache and to the CPU. A cache-hit occurs if the cache contains the data that the CPU requests. In the case of a cache-hit, data is supplied to the CPU without wait states. The second main function of the Prefetch Cache module is to prefetch CPU instructions. The module calculates the address of the next cache line and performs a read of the PFM to get the next cache line. This line is placed into a prefetch cache buffer in anticipation of executing straight-line code. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2429 Cache Control This library provides a set of functions to control the behavior of the overall Cache Module. Those functions include: • Setting or reading the number of clock wait cycles • Setting or reading the number of cache lines allocated to data • Controlling which cache lines are invalidated on a PFM write cycle Cache Line Operations This library provides a set of functions to read, write and control the behavior of individual Cache Lines. Operations on individual Cache Lines are performed using a two-step process: 1. Select the individual cache line with PLIB_PCACHE_CacheLineSelect. 2. Perform the required cache line operation using any of the routines in the "Cache Line Operations" section. The operations available are: • Set the cache line to data or instruction type • Mark the cache line as valid or invalid • Lock or unlock the cache line • Read or write the Flash type (boot or program) associated with the cache line • Read or write the address associated with the cache line • Read or write the mask field to force a match between the cache line and multiple physical addresses • Read or write any individual word in the cache line data array Once the operation is performed, the cache line remains selected until PLIB_PCACHE_CacheLineDeselect is performed. Only one cache line can be selected at a time. Cache Status The cache maintains a count of hits and misses for profiling purposes. The cache hit counter increments each time the processor issues an instruction fetch or load that hits the prefetch cache from a cacheable region. Similarly, the cache miss counter increments each time the processor issues an instruction fetch or load that misses the prefetch cache from a cacheable region. Accesses to non-cacheable regions do not affect the counters. These values can be read or written using the Cache Status routines. The cache uses a Least Recently Used (LRU) algorithm to replace cache lines on a miss. The specific algorithm may vary between devices. In some devices, the state of the LRU algorithm encoding bits can be read with 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2430 PLIB_PCACHE_LeastRecentlyUsedStateRead. Prefetch Control Predictive prefetch is controlled by the Prefetch Control routines. Devices with no L1 CPU cache can prefetch from cacheable or non-cacheable regions or both. Devices with L1 CPU cache can prefetch from any address, CPU instructions or CPU instructions and data. Predictive prefetch can be disabled for either type of device. Prefetch Status The Prefetch Cache module maintains a count of prefetch aborts for profiling purposes. The prefetch abort counter is incremented each time a prefetch is aborted due to a non-sequential instruction fetch, load or store. This value can be read or written using the Prefetch Status routines. Flash ECC On some devices, the Flash ECC module has the ability to detect single and double bit errors on PFM reads. When a single bit error is detected, the error is corrected and the Single Error Correction (SEC) counter is decremented. When the SEC counter reaches zero, an interrupt is generated to the CPU. The user has the ability to enable or disable the SEC interrupt. It is disabled by default. The user may set the SEC counter value at any time. The maximum counter value may be device-specific and is defined for each processor by the PLIB_PCACHE_MAX_SEC_COUNT constant. When a double bit error is detected, the device will set the DED status to true and generate a bus exception to the initiator. 5.6.15.4.3 How the Library Works This library can be used to optimize the performance of the processor while executing out of cacheable program Flash memory. This is done by implementing the following: • Instruction caching • Data caching • Cache line control • Predictive prefetching • ECC detection 5.6.15.4.3.1 Cache Control Operations Cache Wait States When operating at high clock rates, the Prefetch Cache module must insert wait states into Program Flash Memory (PFM) read operations to meet PFM access time requirements. One Wait state is equivalent to one clock cycle delay. At reset, the Prefetch Cache Module is set to the maximum number of wait states for the device. The PFM read time can be optimized for the device by selecting the minimum number of wait states for the clock rate used. The number of wait states for a given clock frequency may vary between devices. Note: Refer to the specific device data sheet for details on how to calculate the optimum number of wait states for your device. Example: Setting the Number of PFM wait states based on the System Clock This example assumes one wait state for every 20 MHz of system clock. if (sysclk < 20000000) { PLIB_PCACHE_WaitStateSet(0); } else if (sysclk < 40000000) { PLIB_PCACHE_WaitStateSet(1); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2431 } ... Data Caching Some Prefetch Cache modules allow the user to allocate cache lines to data. This is to provide improved CPU access to constant data stored in PFM. By default, data caching is disabled. The Prefetch Cache Peripheral Library allows the user to set the number of cache lines allocated to data. The number of lines available may vary among devices. The available settings are provided by the device-dependent PLIB_PCACHE_DATA_ENABLE enumeration. Example: Allocating two Cache Lines to Data PLIB_PCACHE_DataCacheEnableSet(PLIB_PCACHE_DATA_2LINE); Cache Line Invalidating on PFM Write It's not possible to execute out of cache while programming the PFM. The PFM controller stalls the cache during the programming sequence. Therefore, user code that initiates a programming sequence should not be located in a cacheable address region. During program operation, the Prefetch Cache is flushed by invalidating some or all of the cache lines. To invalidate all of the cache lines on a PFM write operation, the function PLIB_PCACHE_InvalidateOnPFMProgramAll should be called prior to the PFM write. This will invalidate and unlock every cache line during the write operation. The cache tags and masks are also cleared for all lines. If PLIB_PCACHE_InvalidateOnPFMProgramUnlocked is called before the PFM write, only lines that are not locked will be forced invalid. By default, only unlocked cache lines are invalidated during a PFM write. 5.6.15.4.3.2 Cache Line Operations Performing a cache line operation is a two-step process. Before calling a Cache Line operation function, the cache line must be selected and write-enabled. Once selected and write-enabled, any number of cache line operations may be performed on the selected line until the line is cleared or a different line is selected and write-enabled. Cache lines are selected and write-enabled using PLIB_PCACHE_CacheLineSelect. Cache lines are write-disabled using PLIB_PCACHE_CacheLineDeselect. The following example shows operations on two different cache lines. The code comments describe each operation. Example: Cache Line Operations uint32_t cacheLine[4] = {0x01234567, 0x12345678, 0x23456789, 0x34567890}; //Select Cache Line 4 PLIB_PCACHE_CacheLineSelect(4); //Invalidate Cache Line 4 PLIB_PCACHE_CacheLineInvalid(); //Select Cache Line 6 PLIB_PCACHE_CacheLineSelect(6); //Set Cache Line 6 to Data Type PLIB_PCACHE_CacheLineData(); //Write Data to Cache Line 6 for (i=0; i). Remarks This function implements an operation of the CacheLineMask feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineMask in your application to to automatically determine whether this feature is available. Example uint32_t mask; mask = PLIB_PCACHE_CacheLineMaskGet(PCACHE_ID_0); 5.6.15.6.2.15 PLIB_PCACHE_CacheLineMaskSet Function C void PLIB_PCACHE_CacheLineMaskSet( PCACHE_MODULE_ID index, uint32_t mask ); Description This function sets the cache tag mask to force a match on set bits on the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mask Address mask (bits set to '1' will force a match - valid bits: <15:5>) 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2448 Returns None. Remarks This function implements an operation of the CacheLineMask feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineMask in your application to to automatically determine whether this feature is available. Example uint32_t mask = 0x0C0; PLIB_PCACHE_CacheLineMaskSet(PCACHE_ID_0, mask); 5.6.15.6.2.16 PLIB_PCACHE_CacheLineSelect Function C void PLIB_PCACHE_CacheLineSelect( PCACHE_MODULE_ID index, uint32_t cache_line ); Description This function enables write access to the cache line specified by cache_line. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured cache_line Specifies the cache line to enable write access Returns None. Remarks At reset, all cache lines are read-only. This function implements an operation of the CacheLineSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineSelect in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_CacheLineSelect(PCACHE_ID_0, 0); 5.6.15.6.2.17 PLIB_PCACHE_CacheLineUnlock Function C void PLIB_PCACHE_CacheLineUnlock( PCACHE_MODULE_ID index ); Description This function unlocks the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2449 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the CacheLineLock feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineLock in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_CacheLineUnlock(PCACHE_ID_0); 5.6.15.6.2.18 PLIB_PCACHE_CacheLineValid Function C void PLIB_PCACHE_CacheLineValid( PCACHE_MODULE_ID index ); Description This function validates the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the CacheLineValid feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheLineValid in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_CacheLineValid(PCACHE_ID_0); 5.6.15.6.2.19 PLIB_PCACHE_WordRead Function C uint32_t PLIB_PCACHE_WordRead( PCACHE_MODULE_ID index, uint32_t word ); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2450 Description This function reads the word specified by word from the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read word Location of the word in the data array to be read Returns 32-bit unsigned word from cache data array. Remarks This function implements an operation of the Word feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWord in your application to to automatically determine whether this feature is available. Example uint32_t word; word = PLIB_PCACHE_WordRead(PCACHE_ID_0, 0); 5.6.15.6.2.20 PLIB_PCACHE_WordWrite Function C void PLIB_PCACHE_WordWrite( PCACHE_MODULE_ID index, uint32_t word, uint32_t data ); Description This function writes the word (specified by word parameter) with data (specified by data parameter) to the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be written. word Location of the word in the data array to be written data 32-bit unsigned word to write to cache data array Returns None. Remarks This function implements an operation of the Word feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWord in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2451 Example uint32_t word = 0; uint32_t data = 0xDEADBEEF; PLIB_PCACHE_WordWrite(PCACHE_ID_0, word, data); 5.6.15.6.3 Cache Status Functions 5.6.15.6.3.1 PLIB_PCACHE_CacheHitRead Function C uint32_t PLIB_PCACHE_CacheHitRead( PCACHE_MODULE_ID index ); Description This function reads the number of cache hits. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Number of cache hits. Remarks This function implements an operation of the CacheHit feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheHit in your application to to automatically determine whether this feature is available. Example uint32_t cache_hits; cache_hits = PLIB_PCACHE_CacheHitRead(PCACHE_ID_0); 5.6.15.6.3.2 PLIB_PCACHE_CacheHitWrite Function C void PLIB_PCACHE_CacheHitWrite( PCACHE_MODULE_ID index, uint32_t data ); Description This function sets the number of cache hits. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be written data Number of cache hits to write 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2452 Returns None. Remarks This function implements an operation of the CacheHit feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheHit in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_CacheHitWrite(PCACHE_ID_0, 0xF00); 5.6.15.6.3.3 PLIB_PCACHE_CacheMissRead Function C uint32_t PLIB_PCACHE_CacheMissRead( PCACHE_MODULE_ID index ); Description This function reads the number of cache misses. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read. Returns Number of cache misses. Remarks This function implements an operation of the CacheMiss feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheMiss in your application to to automatically determine whether this feature is available. Example uint32_t cache_misses; cache_misses = PLIB_PCACHE_CacheMissRead(PCACHE_ID_0); 5.6.15.6.3.4 PLIB_PCACHE_CacheMissWrite Function C void PLIB_PCACHE_CacheMissWrite( PCACHE_MODULE_ID index, uint32_t data ); Description This function sets the number of cache misses. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2453 Parameters Parameters Description index Identifier for the device instance to be written data Number of cache misses to write Returns None. Remarks This function implements an operation of the CacheMiss feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCacheMiss in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_CacheMissWrite(PCACHE_ID_0, 0xF00); 5.6.15.6.3.5 PLIB_PCACHE_LeastRecentlyUsedStateRead Function C uint32_t PLIB_PCACHE_LeastRecentlyUsedStateRead( PCACHE_MODULE_ID index ); Description This function reads the state of the cache least recently used encoding bits. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read. Returns State of Least Recently Used encoding bits represented as a 25-bit unsigned integer. Remarks This function implements an operation of the LeastRecentlyUsedState feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsLeastRecentlyUsedState in your application to to automatically determine whether this feature is available. Example uint32_t lru_state; lru_state = PLIB_PCACHE_LeastRecentlyUsedStateRead(PCACHE_ID_0); 5.6.15.6.4 Prefetch Control Functions 5.6.15.6.4.1 PLIB_PCACHE_PrefetchEnableGet Function C PLIB_PCACHE_PREFETCH_ENABLE PLIB_PCACHE_PrefetchEnableGet( PCACHE_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2454 Description This function gets the predictive prefetch state for the Prefetch Cache module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns PLIB_PCACHE_PREFETCH_ENABLE Remarks At reset, the Pretch Cache module is disabled and this function will return PLIB_PCACHE_DISABLE. This function implements an operation of the PrefetchEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchEnable in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_PREFETCH_ENABLE region; region = PLIB_PCACHE_PrefetchEnableGet(PCACHE_ID_0); 5.6.15.6.4.2 PLIB_PCACHE_PrefetchEnableSet Function C void PLIB_PCACHE_PrefetchEnableSet( PCACHE_MODULE_ID index, PLIB_PCACHE_PREFETCH_ENABLE region ); Description This function sets the predictive prefetch state for the Prefetch Cache module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured region PLIB_PCACHE_PREFETCH_ENABLE Returns None. Remarks At reset, the Pretch Cache module is disabled. This function implements an operation of the PrefetchEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchEnable in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_PrefetchEnableSet(PCACHE_ID_0, 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2455 PLIB_PCACHE_PREFETCH_ENABLE_ALL); 5.6.15.6.5 Prefetch Status Functions 5.6.15.6.5.1 PLIB_PCACHE_PrefetchAbortRead Function C uint32_t PLIB_PCACHE_PrefetchAbortRead( PCACHE_MODULE_ID index ); Description This function reads the number of prefetch aborts. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns Number of prefetch aborts. Remarks This function implements an operation of the PrefetchAbort feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchAbort in your application to to automatically determine whether this feature is available. Example uint32_t pfabt; pfabt = PLIB_PCACHE_PrefetchAbortRead(PCACHE_ID_0); 5.6.15.6.5.2 PLIB_PCACHE_PrefetchAbortWrite Function C void PLIB_PCACHE_PrefetchAbortWrite( PCACHE_MODULE_ID index, uint32_t data ); Description This function Sets the number of prefetch aborts. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be written data Number of prefetch aborts Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2456 Remarks This function implements an operation of the PrefetchAbort feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsPrefetchAbort in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_PrefetchAbortWrite(PCACHE_ID_0, 0xF00); 5.6.15.6.6 Flash ECC Functions 5.6.15.6.6.1 PLIB_PCACHE_FlashDEDStatusClear Function C void PLIB_PCACHE_FlashDEDStatusClear( PCACHE_MODULE_ID index ); Description This function clears a bus exception caused by a double-bit error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be cleared Returns None Remarks The DED status is set by hardware. This function implements an operation of the FlashDEDStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashDEDStatus in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashDEDStatusClear(PCACHE_ID_0); 5.6.15.6.6.2 PLIB_PCACHE_FlashDEDStatusGet Function C bool PLIB_PCACHE_FlashDEDStatusGet( PCACHE_MODULE_ID index ); Description This function determines if a bus exception was caused by a double-bit error. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2457 Parameters Parameters Description index Identifier for the device instance to be read Returns • true - A double-bit error was detected • false - A double-bit error was not detected Remarks The Double-bit Error Detected (DED) status is set by hardware. This function implements an operation of the FlashDEDStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashDEDStatus in your application to to automatically determine whether this feature is available. Example bool dedStatus; dedStatus = PLIB_PCACHE_FlashDEDStatusGet(PCACHE_ID_0); 5.6.15.6.6.3 PLIB_PCACHE_FlashSECCountGet Function C uint8_t PLIB_PCACHE_FlashSECCountGet( PCACHE_MODULE_ID index ); Description This function returns the current value of the Flash SEC counter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns count - Number of SEC events to occur before the SEC status is set to true Remarks This function implements an operation of the FlashSECCount feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECCount in your application to to automatically determine whether this feature is available. Example uint8_t count; count = PLIB_PCACHE_FlashSECCountGet(PCACHE_ID_0); 5.6.15.6.6.4 PLIB_PCACHE_FlashSECCountSet Function C void PLIB_PCACHE_FlashSECCountSet( PCACHE_MODULE_ID index, uint8_t count ); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2458 Description This function sets the number of single-bit error corrections that must occur before the SEC status is set to true. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured count Number of SEC events to occur before SEC status is set to true Returns None Remarks This function implements an operation of the FlashSECCount feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECCount in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashSECCountSet(PCACHE_ID_0, 255); 5.6.15.6.6.5 PLIB_PCACHE_FlashSECIntDisable Function C void PLIB_PCACHE_FlashSECIntDisable( PCACHE_MODULE_ID index ); Description This function disables an interrupt on SEC. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be disabled Returns None Remarks At reset the SEC interrupt is disabled. This function implements an operation of the FlashSECInt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECInt in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashSECIntDisable(PCACHE_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2459 5.6.15.6.6.6 PLIB_PCACHE_FlashSECIntEnable Function C void PLIB_PCACHE_FlashSECIntEnable( PCACHE_MODULE_ID index ); Description This function enables an interrupt on SEC. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be enabled Returns None Remarks At reset the SEC interrupt is disabled. This function implements an operation of the FlashSECInt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECInt in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashSECIntEnable(PCACHE_ID_0); 5.6.15.6.6.7 PLIB_PCACHE_FlashSECStatusClear Function C void PLIB_PCACHE_FlashSECStatusClear( PCACHE_MODULE_ID index ); Description This function sets the single-bit error corrected status to false. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be cleared Returns None Remarks The SEC status must be cleared in response to a Prefetch Cache SEC interrupt. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2460 to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashSECStatusClear(PCACHE_ID_0); 5.6.15.6.6.8 PLIB_PCACHE_FlashSECStatusGet Function C bool PLIB_PCACHE_FlashSECStatusGet( PCACHE_MODULE_ID index ); Description This function determines if a SEC event triggered a Prefetch Cache interrupt. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be read Returns • true - A single-bit error was corrected • false - A double-bit error was not corrected Remarks The SEC bit is set when a single-bit error is corrected and the SEC counter is zero. If the Flash SEC interrupt is enabled, an error event is reported to the CPU by a Prefetch Cache interrupt event. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to to automatically determine whether this feature is available. Example bool secStatus; secStatus = PLIB_PCACHE_FlashSECStatusGet(PCACHE_ID_0); 5.6.15.6.6.9 PLIB_PCACHE_FlashSECStatusSet Function C void PLIB_PCACHE_FlashSECStatusSet( PCACHE_MODULE_ID index ); Description This function sets the single-bit error corrected status to true. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2461 Returns None Remarks This function is provided for code testing and debug purposes. Setting the SEC status while the SEC count is zero and the SEC interrupt is enabled will trigger a Prefetch Cache interrupt to the CPU. This function implements an operation of the FlashSECStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsFlashSECStatus in your application to to automatically determine whether this feature is available. Example PLIB_PCACHE_FlashSECStatusSet(PCACHE_ID_0); 5.6.15.6.7 Data Types and Constants 5.6.15.6.7.1 PLIB_PCACHE_MAX_SEC_COUNT Macro C #define PLIB_PCACHE_MAX_SEC_COUNT 255 Description Maximum Value for Single Bit Error Counter This definition specifies the maximum value for single bit error counter. Remarks The actual maximum value of the SEC counter is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.15.6.7.2 PLIB_PCACHE_NUM_LINES Macro C #define PLIB_PCACHE_NUM_LINES Description Number of Cache Lines This definition specifies the number of Prefetch Cache Lines available. Remarks The actual number of cache lines is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.15.6.7.3 PLIB_PCACHE_NUM_WORDS_PER_LINE Macro C #define PLIB_PCACHE_NUM_WORDS_PER_LINE Description Number of Words per Cache Line This definition specifies the number of Words per Prefetch Cache Line. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2462 Remarks The actual number of words per cache line is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.15.6.7.4 PCACHE_MODULE_ID Enumeration C typedef enum { PCACHE_ID_1, PCACHE_NUMBER_OF_MODULES } PCACHE_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the pcache. Remarks Refer to the data sheet to get the correct number of modules defined for the desired device. 5.6.15.6.7.5 PLIB_PCACHE_DATA_ENABLE Enumeration C typedef enum { PLIB_PCACHE_DATA_DISABLE, PLIB_PCACHE_DATA_1LINE, PLIB_PCACHE_DATA_2LINE, PLIB_PCACHE_DATA_4LINE } PLIB_PCACHE_DATA_ENABLE; Description Data Cache Enable This enumeration lists the possible predictive prefetch states for the Prefetch Cache. Members Members Description PLIB_PCACHE_DATA_DISABLE Disable data caching PLIB_PCACHE_DATA_1LINE Enable data caching with a size of 1 Line PLIB_PCACHE_DATA_2LINE Enable data caching with a size of 2 Lines PLIB_PCACHE_DATA_4LINE Enable data caching with a size of 4 Lines Remarks Not all settings are available for all devices. See the device-specific data sheet for details. This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.15.6.7.6 PLIB_PCACHE_PREFETCH_ENABLE Enumeration C typedef enum { PLIB_PCACHE_PREFETCH_DISABLE, PLIB_PCACHE_PREFETCH_ENABLE_CACHED_REGIONS, PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST, PLIB_PCACHE_PREFETCH_ENABLE_NONCACHED_REGIONS, PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST_DATA, 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2463 PLIB_PCACHE_PREFETCH_ENABLE_ALL } PLIB_PCACHE_PREFETCH_ENABLE; Description Predictive Prefetch Cache Enable Bits This enumeration lists the possible predictive prefetch states for the Prefetch Cache. Members Members Description PLIB_PCACHE_PREFETCH_DISABLE Disable predictive prefetch enable PLIB_PCACHE_PREFETCH_ENABLE_CACHED_REGIONS Enable predictive prefetch cache for cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST Enable predictive prefetch cache for cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_NONCACHED_REGIONS Enable predictive prefetch cache for non-cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_CPU_INST_DATA Enable predictive prefetch cache for non-cacheable regions only PLIB_PCACHE_PREFETCH_ENABLE_ALL Enable predictive prefetch cache for cacheable and non-cacheable regions Remarks Not all settings are available for all devices. See the device-specific data sheet for details. This enumeration is processor specific and is defined in the processor-specific header files (see processor.h). 5.6.15.6.8 Feature Existence Functions 5.6.15.6.8.1 PLIB_PCACHE_ExistsCacheHit Function C bool PLIB_PCACHE_ExistsCacheHit( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheHit feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheHitRead • PLIB_PCACHE_CacheHitWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheHit feature is supported on the device • false - The CacheHit feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2464 5.6.15.6.8.2 PLIB_PCACHE_ExistsCacheLine Function C bool PLIB_PCACHE_ExistsCacheLine( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineSelect feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineSelect • PLIB_PCACHE_CacheLineDeselect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineSelect feature is supported on the device • false - The CacheLineSelect feature is not supported on the device Remarks None. 5.6.15.6.8.3 PLIB_PCACHE_ExistsCacheLineAddr Function C bool PLIB_PCACHE_ExistsCacheLineAddr( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineAddr feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineAddrSet • PLIB_PCACHE_CacheLineAddrGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineAddr feature is supported on the device • false - The CacheLineAddr feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2465 Remarks None. 5.6.15.6.8.4 PLIB_PCACHE_ExistsCacheLineFlashType Function C bool PLIB_PCACHE_ExistsCacheLineFlashType( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineFlashType feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineFlashTypeBoot • PLIB_PCACHE_CacheLineFlashTypeInst • PLIB_PCACHE_CacheLineFlashTypeIsInst Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineFlashType feature is supported on the device • false - The CacheLineFlashType feature is not supported on the device Remarks None. 5.6.15.6.8.5 PLIB_PCACHE_ExistsCacheLineLock Function C bool PLIB_PCACHE_ExistsCacheLineLock( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineLock feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineLock • PLIB_PCACHE_CacheLineUnlock • PLIB_PCACHE_CacheLineIsLocked Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2466 Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineLock feature is supported on the device • false - The CacheLineLock feature is not supported on the device Remarks None. 5.6.15.6.8.6 PLIB_PCACHE_ExistsCacheLineMask Function C bool PLIB_PCACHE_ExistsCacheLineMask( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineMask feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineMaskSet • PLIB_PCACHE_CacheLineMaskGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineMask feature is supported on the device • false - The CacheLineMask feature is not supported on the device Remarks None. 5.6.15.6.8.7 PLIB_PCACHE_ExistsCacheLineType Function C bool PLIB_PCACHE_ExistsCacheLineType( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineType feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineData • PLIB_PCACHE_CacheLineInst 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2467 • PLIB_PCACHE_CacheLineIsInst Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineType feature is supported on the device • false - The CacheLineType feature is not supported on the device Remarks None. 5.6.15.6.8.8 PLIB_PCACHE_ExistsCacheLineValid Function C bool PLIB_PCACHE_ExistsCacheLineValid( PCACHE_MODULE_ID index ); Description This interface identifies that the CacheLineValid feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheLineValid • PLIB_PCACHE_CacheLineInvalid • PLIB_PCACHE_CacheLineIsValid Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheLineValid feature is supported on the device • false - The CacheLineValid feature is not supported on the device Remarks None. 5.6.15.6.8.9 PLIB_PCACHE_ExistsCacheMiss Function C bool PLIB_PCACHE_ExistsCacheMiss( PCACHE_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2468 Description This interface identifies that the CacheMiss feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_CacheMissRead • PLIB_PCACHE_CacheMissWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CacheMiss feature is supported on the device • false - The CacheMiss feature is not supported on the device Remarks None. 5.6.15.6.8.10 PLIB_PCACHE_ExistsDataCacheEnable Function C bool PLIB_PCACHE_ExistsDataCacheEnable( PCACHE_MODULE_ID index ); Description This interface identifies that the DataCacheEnable feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_DataCacheEnableSet • PLIB_PCACHE_DataCacheEnableGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataCacheEnable feature is supported on the device • false - The DataCacheEnable feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2469 5.6.15.6.8.11 PLIB_PCACHE_ExistsFlashDEDStatus Function C bool PLIB_PCACHE_ExistsFlashDEDStatus( PCACHE_MODULE_ID index ); Description This interface identifies that the FlashDEDStatus feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashDEDStatusGet • PLIB_PCACHE_FlashDEDStatusClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashDEDStatus feature is supported on the device • false - The FlashDEDStatus feature is not supported on the device Remarks None. 5.6.15.6.8.12 PLIB_PCACHE_ExistsFlashSECCount Function C bool PLIB_PCACHE_ExistsFlashSECCount( PCACHE_MODULE_ID index ); Description This interface identifies that the FlashSECCount feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECCountSet • PLIB_PCACHE_FlashSECCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashSECCount feature is supported on the device • false - The FlashSECCount feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2470 Remarks None. 5.6.15.6.8.13 PLIB_PCACHE_ExistsFlashSECInt Function C bool PLIB_PCACHE_ExistsFlashSECInt( PCACHE_MODULE_ID index ); Description This interface identifies that the FlashSECInt feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECIntEnable • PLIB_PCACHE_FlashSECIntDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FlashSECInt feature is supported on the device • false - The FlashSECInt feature is not supported on the device Remarks None. 5.6.15.6.8.14 PLIB_PCACHE_ExistsFlashSECStatus Function C bool PLIB_PCACHE_ExistsFlashSECStatus( PCACHE_MODULE_ID index ); Description This interface identifies that the FlashSECStatus feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_FlashSECStatusGet • PLIB_PCACHE_FlashSECStatusSet • PLIB_PCACHE_FlashSECStatusClear Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2471 Returns • true - The FlashSECStatus feature is supported on the device • false - The FlashSECStatus feature is not supported on the device Remarks None. 5.6.15.6.8.15 PLIB_PCACHE_ExistsInvalidateOnPFMProgram Function C bool PLIB_PCACHE_ExistsInvalidateOnPFMProgram( PCACHE_MODULE_ID index ); Description This interface identifies that the InvalidateOnPFMProgram feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_InvalidateOnPFMProgramAll • PLIB_PCACHE_InvalidateOnPFMProgramUnlocked Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InvalidateOnPFMProgram feature is supported on the device • false - The InvalidateOnPFMProgram feature is not supported on the device Remarks None. 5.6.15.6.8.16 PLIB_PCACHE_ExistsLeastRecentlyUsedState Function C bool PLIB_PCACHE_ExistsLeastRecentlyUsedState( PCACHE_MODULE_ID index ); Description This interface identifies that the LeastRecentlyUsedState feature is available on the Prefetch Cache module. When this interface returns true, this function is supported on the device: • PLIB_PCACHE_LeastRecentlyUsedStateRead Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2472 Parameters Parameters Description index Identifier for the device instance Returns • true - The LeastRecentlyUsedState feature is supported on the device • false - The LeastRecentlyUsedState feature is not supported on the device Remarks None. 5.6.15.6.8.17 PLIB_PCACHE_ExistsPrefetchAbort Function C bool PLIB_PCACHE_ExistsPrefetchAbort( PCACHE_MODULE_ID index ); Description This interface identifies that the PrefetchAbort feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_PrefetchAbortRead • PLIB_PCACHE_PrefetchAbortWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PrefetchAbort feature is supported on the device • false - The PrefetchAbort feature is not supported on the device Remarks None. 5.6.15.6.8.18 PLIB_PCACHE_ExistsPrefetchEnable Function C bool PLIB_PCACHE_ExistsPrefetchEnable( PCACHE_MODULE_ID index ); Description This interface identifies that the PrefetchEnable feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_PrefetchEnableSet • PLIB_PCACHE_PrefetchEnableGet 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2473 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PrefetchEnable feature is supported on the device • false - The PrefetchEnable feature is not supported on the device Remarks None. 5.6.15.6.8.19 PLIB_PCACHE_ExistsWaitState Function C bool PLIB_PCACHE_ExistsWaitState( PCACHE_MODULE_ID index ); Description This interface identifies that the WaitState feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: • PLIB_PCACHE_WaitStateSet • PLIB_PCACHE_WaitStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WaitState feature is supported on the device • false - The WaitState feature is not supported on the device Remarks None. 5.6.15.6.8.20 PLIB_PCACHE_ExistsWord Function C bool PLIB_PCACHE_ExistsWord( PCACHE_MODULE_ID index ); Description This interface identifies that the Word feature is available on the Prefetch Cache module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2474 • PLIB_PCACHE_WordRead • PLIB_PCACHE_WordWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Word feature is supported on the device • false - The Word feature is not supported on the device Remarks None. 5.6.15.7 Files Files Name Description plib_pcache.h Defines the Prefetch Cache (PCACHE) Peripheral Library Interface Description 5.6.15.7.1 plib_pcache.h Prefetch Cache Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Prefetch Cache (PCACHE) Periheral Library for Microchip microcontrollers. The definitions in this file are for the Prefetch Cache module. Functions Name Description PLIB_PCACHE_CacheHitRead Reads the number of cache hits. PLIB_PCACHE_CacheHitWrite Sets the number of cache hits. PLIB_PCACHE_CacheLineAddrGet Gets the TAG address in the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineAddrSet Sets the TAG address in the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineData Sets cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect to data type. PLIB_PCACHE_CacheLineDeselect Disables write access to the cache line specified by cache_line. PLIB_PCACHE_CacheLineFlashTypeBoot Set the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect as residing in boot Flash. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2475 PLIB_PCACHE_CacheLineFlashTypeInst Set the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect as residing in instruction Flash. PLIB_PCACHE_CacheLineFlashTypeIsInst Returns true if the cache line tag for the line previously write-enabled by PLIB_PCACHE_CacheLineSelect shows the line is residing in instruction Flash. PLIB_PCACHE_CacheLineInst Sets cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect to instruction type. PLIB_PCACHE_CacheLineInvalid Invalidates cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineIsInst Returns true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is set to instruction type. PLIB_PCACHE_CacheLineIsLocked Returns true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is locked. PLIB_PCACHE_CacheLineIsValid Returnes true if cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect is valid. PLIB_PCACHE_CacheLineLock Locks cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineMaskGet Returns the current state of the cache tag mask for the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineMaskSet Sets the cache tag mask to force a match on set bits on the cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineSelect Enables write access to the cache line specified by cache_line. PLIB_PCACHE_CacheLineUnlock Unlocks cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheLineValid Validates cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. PLIB_PCACHE_CacheMissRead Reads the number of cache misses. PLIB_PCACHE_CacheMissWrite Sets the number of cache misses. PLIB_PCACHE_DataCacheEnableGet Gets the data cache enable bits. PLIB_PCACHE_DataCacheEnableSet Sets the data cache enable bits. PLIB_PCACHE_ExistsCacheHit Identifies that the CacheHit feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLine Identifies that the CacheLineSelect feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineAddr Identifies that the CacheLineAddr feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineFlashType Identifies that the CacheLineFlashType feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineLock Identifies that the CacheLineLock feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineMask Identifies that the CacheLineMask feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineType Identifies that the CacheLineType feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheLineValid Identifies that the CacheLineValid feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsCacheMiss Identifies that the CacheMiss feature exists on the Prefetch Cache module. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2476 PLIB_PCACHE_ExistsDataCacheEnable Identifies that the DataCacheEnable feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashDEDStatus Identifies that the FlashDEDStatus feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECCount Identifies that the FlashSECCount feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECInt Identifies that the FlashSECInt feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsFlashSECStatus Identifies that the FlashSECStatus feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsInvalidateOnPFMProgram Identifies that the InvalidateOnPFMProgram feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsLeastRecentlyUsedState Identifies that the LeastRecentlyUsedState feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsPrefetchAbort Identifies that the PrefetchAbort feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsPrefetchEnable Identifies that the PrefetchEnable feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsWaitState Identifies that the WaitState feature exists on the Prefetch Cache module. PLIB_PCACHE_ExistsWord Identifies that the Word feature exists on the Prefetch Cache module. PLIB_PCACHE_FlashDEDStatusClear Clears a bus exception caused by a double-bit error. PLIB_PCACHE_FlashDEDStatusGet Determines if a bus exception was caused by a double-bit error. PLIB_PCACHE_FlashSECCountGet Returns the current value of the Flash SEC counter. PLIB_PCACHE_FlashSECCountSet Sets the number of single-bit error corrections that must occur before the SEC status is set to true. PLIB_PCACHE_FlashSECIntDisable Disables an interrupt on SEC. PLIB_PCACHE_FlashSECIntEnable Enables an interrupt on SEC. PLIB_PCACHE_FlashSECStatusClear Sets the single-bit error corrected status to false. PLIB_PCACHE_FlashSECStatusGet Determines if a SEC event triggered a Prefetch Cache interrupt. PLIB_PCACHE_FlashSECStatusSet Sets the single-bit error corrected status to true. PLIB_PCACHE_InvalidateOnPFMProgramAll Sets prefetch cache to invalidate all data and instruction lines on a PFM program cycle. PLIB_PCACHE_InvalidateOnPFMProgramUnlocked Sets prefetch cache to invalidate all unlocked data and instruction lines on a PFM program cycle. PLIB_PCACHE_LeastRecentlyUsedStateRead Reads the state of the cache least recently used encoding bits. PLIB_PCACHE_PrefetchAbortRead Reads the number of prefetch aborts. PLIB_PCACHE_PrefetchAbortWrite Sets the number of prefetch aborts. PLIB_PCACHE_PrefetchEnableGet Gets the predictive prefetch state for the Prefetch Cache module. PLIB_PCACHE_PrefetchEnableSet Sets the predictive prefetch state for the Prefetch Cache module. PLIB_PCACHE_WaitStateGet Gets the prefetch cache access time. PLIB_PCACHE_WaitStateSet Sets the prefetch cache access time. PLIB_PCACHE_WordRead Reads the word specified by word from cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. 5.6 Peripheral Library Help MPLAB Harmony Help Prefetch Cache Peripheral Library 5-2477 PLIB_PCACHE_WordWrite Writes the word (specified by word parameter) with data (specified by data parameter) to cache line previously write-enabled by PLIB_PCACHE_CacheLineSelect. File Name plib_pcache.h Company Microchip Technology Inc. 5.6.16 PMP Peripheral Library 5.6.16.1 Introduction Parallel Master Port (PMP) Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Parallel Master Port (PMP) module on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description The following diagram shows a block diagram of the PMP module and how it interacts with other peripherals. PMP Overview 5.6.16.2 Release Notes MPLAB Harmony Version: v0.70b PMP Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2478 Known Issues: Nothing to report in this release. 5.6.16.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.16.4 Using the Library Using the Library This topic describes the basic architecture of the PMP Peripheral Library and provides information and examples on its use. Interface Header File: plib_pmp.h The interface to the PMP Peripheral library is defined in the "plib_pmp.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the PMP Peripheral Library must include "peripheral.h". 5.6.16.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Parallel Master Port (PMP) module on Microchip's microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Model Description The PMP module provides interface routines to interact with external peripherals such as LCD, EEPROM, Flash memory, etc., as shown in the following diagram. The diagram shows the PMP module acting as a master. The PMP module can be easily configured to act as a slave. The address and data lines can be multiplexed to suit the application. The address and data buffers are up to 2-byte (16-bit) buffers for data transmitted or received by the parallel interface to the PMP bus over the data and address lines synchronized with control logic including the read and write strobe. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2479 PMP Hardware Abstraction Model Diagram The desired timing wait states to suit different peripheral timings can also be programmed using the PMP module. 5.6.16.4.2 Library Usage Model This section describes the library usage model for the PMP Peripheral Library. Description The following diagram shows the high level organization of the PMP PLIB usage model. The items in the diagram correspond to the groupings in the Library Interface section. PMP Library Usage Model Library Interface Section Description 5.6.16.4.3 How the Library Works How the Library Works Before enabling the PMP module, the caller must initialize basic parameters such as wait states timings, and interrupt mode features (see the Initialization section). After the module has been enabled, it can begin monitoring the bus as a slave device waiting to be addressed by an external master (see the Operating as a Slave section). A slave device only transfers data on the bus when it has been addressed by a master. If the module is used to start a transfer, it is operating as a master. A master addresses a slave and controls the transfer 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2480 of data by providing the clock (see the Operating as a Master section). Some operations in the PMP peripheral library initiate actions on the PMP bus that require time to complete. Also, some events occur asynchronously on the bus. In each of these cases, the module causes either a "master", "slave", or "error" interrupt. The State Machine section describes the different states that can cause an interrupt and show what causes the transition from one state to another. The Handling Errors section describes the various errors that can occur and how to deal with them. 5.6.16.4.3.1 Initialization This section describes the general initialization of the PMP module. Description The important configurations to look for are as follows. Operating Mode Depending on the device, the PMP module can function in Master modes 1 or 2, buffered/enhanced slave mode or the legacy slave mode. To set the PMP module in the appropriate mode, use PLIB_PMP_OperationModeSelect. Multiplexing Mode Depending on the application requirement or hardware arrangement, the data lines can be used to multiplex the addressing information. Various multiplexing modes supported are listed by PMP_MUX_MODE. Use PLIB_PMP_MultiplexModeSelect to select the appropriate multiplexing mode. Chip Select Mode As needed, the Chip Select lines can be made to function as Chip Select or as address lines. Use PLIB_PMP_ChipSelectFunctionSelect to select the required functionality of Chip Select lines. Interrupt Mode PMP generates interrupts based on the option selected for the interrupt mode. Interrupts can be enabled, disabled, generated at the end of a read or write cycle, or when other events occur. Use the PLIB_PMP_InterruptModeSelect to select these options. Address Increment Mode After every read/write cycle, the PMP module can be configured to automatically increment or decrement the address it is accessing. Use PLIB_PMP_AddressIncrementModeSelect to select this option. To initialize the PMP module, perform the following sequence: 1. Select the desired initialization options using the General Initialization Functions to select the desired operation of the following features: • Operating mode • Multiplexing mode • Chip Select mode • Interrupt mode • Address Incrementing mode • Stop-in-Idle operation 2. Program the wait states of the PMP module. Refer to Wait States Initialization Functions for an example. 3. If operating in Master mode, set the desired address (8-bit in this case, the size may vary depending on the application) using PLIB_PMP_AddressSet. 4. If running in an interrupt-driven environment, clear any pending interrupts and enable the appropriate (master, slave, and 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2481 error) PMP interrupts. (Note: Refer to the "Interrupt Controller" chapter in the specific device data sheet for details). 5. Enable the module for operation using PLIB_PMP_Enable. Example // Configure General PMP Options // Select the PMP operation mode PLIB_PMP_OperationModeSelect( PMP_ID_0, PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT ); // Set the multiplexing to none. Address and data lines are not multiplexed. PLIB_PMP_MultiplexModeSelect( PMP_ID_0, PMP_MUX_NONE ); // Select the function of chip-select lines PLIB_PMP_ChipSelectFunctionSelect( PMP_ID_0, PMCS1_PMCS2_AS_ADDRESS_LINES ); // Select the interrupt mode PLIB_PMP_InterruptModeSelect( PMP_ID_0, PMP_INTERRUPT_NONE ); // disable the auto increment/decrement of address after each read/write PLIB_PMP_AddressIncrementModeSelect( PMP_ID_0, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE ); // Enable stop in Idle mode. PLIB_PMP_StopInIdleEnable( PMP_ID_0 ); // Set Desired Wait State Values // Set the data wait states PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_FOUR ); // Set the strobe wait states PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_1 ); // Set the data hold wait states. PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_1 ); // Set the appropriate address (MASTER only) PLIB_PMP_AddressSet ( PMP_ID_0, 0x12 ); // Optional: Clear and enable interrupts before enabling the PMP module. // Enable the module PLIB_PMP_Enable( PMP_ID_0 ); Note: Refer to the "Interrupt Controller" chapter in the specific device data sheet for details on how to clear and enable the PMP module interrupts. 5.6.16.4.3.2 Wait States Initialization This section describes set up and initialization of the wait states for the PMP module. Description In Master mode, the user can control the duration of the read, write and address cycles by configuring the module Wait states. One Wait state period is equivalent to one peripheral bus clock cycles. The following figure shows an example of a Master Read operation using Wait states. Wait States Wait states can be added to the beginning, middle and end of any read or write cycle using the corresponding bits in the PMP 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2482 Configuration. The wait states differ depending on which PMP mode you are in, but setting the wait states is the same per mode and device, as shown in the following example. Initializing Wait States The following sequence can be used to set up the wait states for the PMP Master mode. Preconditions: None. Process: 1. Set the data hold time using PLIB_PMP_WaitStatesDataHoldSelect. 2. Set the strobe wait time using PLIB_PMP_WaitStatesStrobeSelect. 3. Set the data wait time using PLIB_PMP_WaitStatesDataSetUpSelect. Example // Set the data wait states PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_ONE ); // Set the strobe wait states PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_1 ); // Set the data hold wait states. PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_1 ); 5.6.16.4.3.3 Operating as a Master This section describes how to set up the PMP module to operate as a master. Description The PMP module, while acting as a master, waits for its input or output buffers to be read or written. Once the buffers have been manipulated, the appropriate action takes place. A PMP bus transfer always begins with reading or writing to the appropriate PMP input/output buffers. A read from a PMP input buffer performs a PMP read. A write to a PMP output buffer performs a PMP write. The address pins associated with the transfer will have the value that is inside the address register of the PMP module. These steps are summarized as follows. Summary of Steps • Set up the proper PMP address • Send or read data bytes Each of these steps making up a transfer will take some time to complete. By monitoring the busy bit of the PMP module, the user application can determine whether the transfer is complete. The completion of each step can cause a PMP interrupt. Sending a Data Byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: • The address of the destination must be configured in the PMP module • The proper control signals are configured for PMP operation • The PMP module is configured for the desired Master mode • The PMP module is enabled Process: 1. Ensure that the PMP module is not busy by using PLIB_PMP_PortIsBusy. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2483 2. Write the output data buffer using PLIB_PMP_MasterSend. Example: uint8_t data = 'a'; // Set the destination address to be written PLIB_PMP_AddressSet(PMP_ID_0, 0x1234 ); // Check to see if the PMP is busy, then send the byte if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // Send the data PLIB_PMP_MasterSend( PMP_ID_0, data ); } Receiving a Data byte The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: • The address of the destination must be configured in the PMP module. • The proper control signal are configured for PMP operation. Process: 1. Ensure that the PMP module is not busy by using PLIB_PMP_PortIsBusy. 2. Write the output data buffer using PLIB_PMP_MasterReceive. Example: uint8_t data; // Set the source address PLIB_PMP_AddressSet(PMP_ID_0, 0x1234 ); // Check to see the PMP is not busy, then read the data if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // receive the data data = PLIB_PMP_MasterReceive( PMP_ID_0 ); } 5.6.16.4.3.4 Operating as a Slave This section describes how to set up the PMP module to operate as a slave. Description The PMP module while acting as a slave, waits for read or write strobes to occur. Once the buffers have been manipulated, the appropriate action takes place. Summary of Steps • Check to see if data is available to be read • Prepare output buffer for slave read Each of these steps making up a transfer will take some time to complete. By monitoring the busy bit of the PMP module, the user application can determine whether the transfer is complete. The completion of each step can cause a PMP interrupt. Reading Available Data The following sequence can be used to receive a data byte and repeated to receive an arbitrary number of data bytes. Preconditions: • The address of the destination must be set in the PMP module • The proper control signals are initialized for PMP operation 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2484 Process: 1. Check to see if data is available using PLIB_PMP_InputBufferXIsFull. 2. Read the available data using PLIB_PMP_InputBufferXByteReceive. Example: uint8_t data; // Check to see if data is available, then receive the byte if(PLIB_PMP_InputBufferXIsFull( PMP_ID_0, 1)) { // Receive the data from buffer one. data = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } Preparing Output Buffer for Slave Write The following sequence can be used to send a data byte and repeated to send an arbitrary number of data bytes. Preconditions: The proper control signals are initialized for PMP operation. Process: 1. Ensure that the output buffer to be written is empty by using PLIB_PMP_OutputBufferXIsEmpty. 2. Write the output data buffer using PLIB_PMP_OutputBufferXByteSend. Example: uint8_t data; // Check to see if output buffer is available, then send the byte if(PLIB_PMP_OutputBufferXIsEmpty( PMP_ID_0, 1)) { // Fill the output buffer-1 with the data to be sent PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, value); } 5.6.16.4.3.5 State Machine The PMP state machine can be used in either a polled or an interrupt-driven manner. However, in both cases, software must check the state of the master, slave, and error interrupt flags to identify when a state transition occurs. Description The PMP module has one basic interrupt that is triggered when data has been written or read. In Buffered Slave mode, this interrupt can be set to wait until an 'X' amount of buffers are written or read. This interrupt must be cleared in software, but can also be used in DMA transactions to trigger the next DMA transfer. The PMP module will not start generating interrupts (setting the PMP interrupt flags, even if interrupts are disabled) until it is properly configured and enabled. After that, interrupts are generated as described in subsequent sections. Software has to respond appropriately once the interrupt has occurred (the flag has been set) to allow the state machine to advance to the next state. These actions are described in the following sections for the state machine diagram to which they refer. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2485 Slave Mode State Machine Slave-Mode State Transitions In Slave mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the PMP module continues to operate correctly. Basically, if a read/write strobe occurs, then the appropriate read/write happens, which in turn sets the interrupt. Master Mode State Machine 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2486 Master-Mode State Transitions In Master mode, state transitions occur under hardware control automatically or in response to an interrupt. Software must respond appropriately to ensure that the PMP module continues to operate correctly. Basically, if an input or output register is manipulated, the appropriate read/write happens, which in turn sets the interrupt. The PMP module can also be configured to have read/write strobes indicating whether a read/write has completed. 5.6.16.4.3.6 Handling Errors There are two basic types of errors that can occur during various slave PMP operations: • Input Buffer Overrun • Output Buffer Underflow This section provides information on handling these types of errors. Description Handling Input Buffer Overrun Errors An input buffer overflow error occurs when the software is not reading or clearing the input buffers fast enough for the master PMP device attached to it. When this occurs, the master write is not allowed and the "input buffer overflow" status bit is set. This can be identified by calling PLIB_PMP_InputOverflowHasOccurred. Additional attempts to write to the input buffer will not be allowed until the overflow error is cleared by calling PLIB_PMP_InputOverflowClear. This type of error should be either avoided by having proper communication techniques with the PMP Master device or checked using PLIB_PMP_InputBuffersAreFull, which informs the controller that no buffers have data in them (overflow) . Interrupts: The input buffer overflow error does not trigger an interrupt. Handling Output Buffer Underflow Errors An output buffer underflow error occurs when the software is not writing to the output buffers fast enough for the master PMP device attached to it. When this occurs, the master read is not allowed and the "output buffer underflow" status bit is set. This can be identified by calling PLIB_PMP_OutputUnderflowHasOccurred. Additional attempts to read from the output buffer will not be allowed until the overflow error is cleared by calling PLIB_PMP_OutputUnderflowClear. This sort of error should be either avoided by having proper communication techniques with the PMP Master device, or checked using PLIB_PMP_OutputBuffersAreEmpty, which informs the controller that buffers have data in them (underflow) . Interrupts: The input buffer overflow error does not trigger an interrupt. 5.6.16.4.3.7 Other Features This section provides information on additional features that may be available. These features are not available on all devices. Please refer to the "Parallel Master Port (PMP)" chapter in the specific device data sheet to determine which features are supported by your device. Description Operation During Sleep Mode When the device enters Sleep mode, the system clock is disabled. The consequences of Sleep mode depend on which mode the PMP module is configured in at the time that Sleep mode is invoked. Master If the device enters Sleep mode while the PMP module is operating in Master mode, PMP operation will be suspended in its current state until clock execution resumes. As this may cause unexpected control pin timings, users should avoid invoking 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2487 Sleep mode when continuous use of the module is needed. Slave While the PMP module is inactive, but enabled for any Slave mode operation, any read or write operations occurring at that time will be able to complete without the use of the microcontroller clock. Once the operation is completed, the module will issue an interrupt. This interrupt may be used to wake the device from Sleep or Idle modes, depending on the configuration and capabilities of the device. Refer to the specific device data sheet or the related peripheral section in the reference manual to determine the capabilities of your device. Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. PMP operation during Idle mode can be controlled using the PLIB_PMP_StopInIdleEnable or the PLIB_PMP_StopInIdleDisable. By default, the PMP module continues to operate in Idle mode and provide full functionality. 5.6.16.5 Configuring the Library The library is configured for the supported PMP Peripheral Library is configured in the MPLAB IDE. 5.6.16.6 Library Interface Data Types and Constants Name Description PMP_ACK_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_ADDRESS_HOLD_LATCH_WAIT_STATES PMP hold after address latch strobe wait states configuration. PMP_ADDRESS_LATCH Address Latch Strobe configuration. PMP_ADDRESS_LATCH_WAIT_STATES PMP address latch strobe wait states configuration. PMP_ADDRESS_PORT Defines the different address lines that are available for configuration. PMP_ALTERNATE_MASTER_WAIT_STATES PMP alternate master wait states. PMP_CHIP_SELECT PMP Chip Select data type. PMP_CHIPSELECT_FUNCTION Defines different functions available for the Chip Select lines multiplexed with address lines. PMP_DATA_HOLD_STATES PMP Data Hold after strobe wait state. PMP_DATA_LENGTH Possible data lengths handled by the PMP module. PMP_DATA_SIZE PMP data size. PMP_DATA_WAIT_STATES PMP data setup time configuration. PMP_INCREMENT_MODE PMP address incrementing configuration. PMP_INPUT_BUFFER_TYPE PMP Input Buffers type. PMP_INTERRUPT_MODE PMP interupt request mode data type. PMP_MASTER_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_MODULE_ID Possible instances of the PMP module. PMP_MUX_MODE Defines the different mode configurations in which the PMP can be enabled. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2488 PMP_OPERATION_MODE Defines the different mode configurations in which the PMP can be enabled. PMP_PMBE_PORT Defines the available Byte Enable ports. PMP_POLARITY_LEVEL Possible polarity levels for the PMP pins. PMP_STROBE_WAIT_STATES PMP strobe signal wait time configuration. Address Handling Functions Name Description PLIB_PMP_AddressGet Gets the current address of the PMP module. PLIB_PMP_AddressLinesA0A1Get Gets the value of the address lines PMA0 and PMA1. PLIB_PMP_AddressLinesA0A1Set Sets the address lines PMA0 and PMA1 with the value specified. PLIB_PMP_AddressSet Sets the current address of the PMP module to the specified address. Data Read and Write Functions Name Description PLIB_PMP_InputBuffersAreFull Gets the state of the input buffers. PLIB_PMP_InputBufferXByteReceive Data to be received in Byte mode. PLIB_PMP_InputBufferXIsFull Gets the state of the identified input buffer. PLIB_PMP_IsDataReceived Checks and returns if the data has been received in the specified buffer in Slave mode. PLIB_PMP_IsDataTransmitted Checks and returns if the data has been transmitted from the specified buffer in Slave mode. PLIB_PMP_MasterReceive Receives the data in the master mode. PLIB_PMP_MasterSend Sends the specified data in Master mode. PLIB_PMP_OutputBuffersAreEmpty Gets the state of the output buffers. PLIB_PMP_OutputBufferXByteSend Data to be transmitted in Byte mode. PLIB_PMP_OutputBufferXIsEmpty Gets the state of the input buffer. PLIB_PMP_SlaveReceive Receives the data in Slave mode. PLIB_PMP_SlaveSend Sends the specified data in Slave mode. Enhanced Address Handling Functions Name Description PLIB_PMP_ChipXBaseAddressSet Sets the base address of the specified device. PLIB_PMP_ReservedAddressSpaceBitsSet Sets the address bits of the reserved address space of the EPMP. The end address of the Chip Select-2 (if present). Enhanced Error/Status Control Functions Name Description PLIB_PMP_TransactionErrorClear Clears the transaction error flag. PLIB_PMP_TransactionErrorHasOccurred Returns the status of a transaction error. PLIB_PMP_TransactionHasTimedOut Returns the time-out status. PLIB_PMP_TransactionTimeoutClear Clears the time-out flag. Enhanced General Initialization Functions Name Description PLIB_PMP_BusKeeperDisable Disables the bus keeper (high-impedance) state. PLIB_PMP_BusKeeperEnable Enables the bus keeper (high-impedance) state. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2489 PLIB_PMP_ChipSelectXEnableStrobeDeSelect Selects the read and write strobes. The enable strobe is not selected (not required). PLIB_PMP_ChipSelectXEnableStrobeSelect Selects the read/write and enable strobes. PLIB_PMP_SmartAddressStrobeDisable Disables "smart" address strobes. PLIB_PMP_SmartAddressStrobeEnable Enables "smart" address strobes. PLIB_PMP_ChipXAckModeSelect Selects the acknowledge mode for the PMP module. PLIB_PMP_ChipXDataSizeSelect Enables data transfer size for the PMP for the specified device. PLIB_PMP_EnhancedMasterModeSelect Selects Master mode for the PMP module. Enhanced General Status Functions Name Description PLIB_PMP_AlternateMasterHasAccess Gets the status of which alternate masters have gained access to the PMP module. PLIB_PMP_AlternateMasterRequestStatus Gets the status of the request from the alternate master. Enhanced Polarity Configuration Functions Name Description PLIB_PMP_ChipSelectXAckPolaritySelect Sets the Chip Select acknowledge polarity. PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect Sets the nibble/byte enable polarity. PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect Sets the read/write strobe polarity. PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect Sets the write/enable strobe polarity. Enhanced Port Configuration Functions Name Description PLIB_PMP_ChipSelectXPortDisable Disables the specified Chip Select's port. PLIB_PMP_ChipSelectXPortEnable Enables the specified Chip Select's port. Enhanced Wait States Initialization Functions Name Description PLIB_PMP_ChipXWaitStatesAlternateMasterSelect Selects the wait states of the alternate master for Chip Select-X. PLIB_PMP_ChipXWaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_ChipXWaitStatesDataSetupSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_ChipXWaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_WaitStatesAddressHoldStrobeSelect Configures the address wait states needed to be used with the PMP module. PLIB_PMP_WaitStatesAddressLatchStrobeSelect Configures the address wait states needed to be used with the PMP module. Error Status/Control Functions Name Description PLIB_PMP_InputOverflowClear Clears a PMP Overflow error. PLIB_PMP_OutputUnderflowClear Clears a PMP output underflow error. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2490 Feature Existence Functions Name Description PLIB_PMP_ExistsAddressControl Identifies that the AddressControl feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchPolarity Identifies that the AddressLatchPolarity feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchStrobePortControl Identifies that the AddressLatchStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsAddressPortPinControl Identifies that the AddressPortPinControl feature exists on the PMP module. PLIB_PMP_ExistsAltMasterRequest Identifies that the AltMasterRequest feature exists on the PMP module. PLIB_PMP_ExistsBufferOverFlow Identifies that the BufferOverFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferRead Identifies that the BufferRead feature exists on the PMP module. PLIB_PMP_ExistsBufferType Identifies that the BufferType feature exists on the PMP module. PLIB_PMP_ExistsBufferUnderFlow Identifies that the BufferUnderFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferWrite Identifies that the BufferWrite feature exists on the PMP module. PLIB_PMP_ExistsBusKeeper Identifies that the BusKeeper feature exists on the PMP module. PLIB_PMP_ExistsBusyStatus Identifies that the BusyStatus feature exists on the PMP module. PLIB_PMP_ExistsByteEnablePolarity Identifies that the ByteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsByteEnablePortControl Identifies that the ByteEnablePortControl feature exists on the PMP module. PLIB_PMP_ExistsChipSelectEnable Identifies that the ChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsChipSelectoperation Identifies that the ChipSelectoperation feature exists on the PMP module. PLIB_PMP_ExistsChipXACKMode Identifies that the ChipXACKMode feature exists on the PMP module. PLIB_PMP_ExistsChipXACKPolarity Identifies that the ChipXACKPolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXAltMasterWaitStates Identifies that the ChipXAltMasterWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXBaseAddress Identifies that the ChipXBaseAddress feature exists on the PMP module. PLIB_PMP_ExistsChipXByteEnablePolarity Identifies that the ChipXByteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXDataHoldWaitStates Identifies that the ChipXDataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXDataSetupWaitStates Identifies that the ChipXDataSetupWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXDataSize Identifies that the ChipXDataSize feature exists on the PMP module. PLIB_PMP_ExistsChipXEnableStorbeSelect Identifies that the ChipXEnableStorbeSelect feature exists on the PMP module. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2491 PLIB_PMP_ExistsChipXPolarity Identifies that the ChipXPolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXReadWritePolarity Identifies that the ChipXReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXStrobeWaitStates Identifies that the ChipXStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXWriteEnablePolarity Identifies that the ChipXWriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsCSXActiveStatus Identifies that the CSXActiveStatus feature exists on the PMP module. PLIB_PMP_ExistsCSXPortControl Identifies that the CSXPortControl feature exists on the PMP module. PLIB_PMP_ExistsCurrentMaster Identifies that the CurrentMaster feature exists on the PMP module. PLIB_PMP_ExistsDataHoldWaitStates Identifies that the DataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataSetUpWaitStates Identifies that the DataSetUpWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataStrobeWaitStates Identifies that the DataStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataTransferSize Identifies that the DataTransferSize feature exists on the PMP module. PLIB_PMP_ExistsEnableControl Identifies that the EnableControl feature exists on the PMP module. PLIB_PMP_ExistsEnhancedMasterMode Identifies that the EnhancedMasterMode feature exists on the PMP module. PLIB_PMP_ExistsIncrementMode Identifies that the IncrementMode feature exists on the PMP module. PLIB_PMP_ExistsInputBufferFull Identifies that the InputBufferFull feature exists on the PMP module. PLIB_PMP_ExistsInputBufferXStatus Identifies that the InputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsInterruptMode Identifies that the InterruptMode feature exists on the PMP module. PLIB_PMP_ExistsMasterRXTX Identifies that the MasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsMUXModeSelect Identifies that the MUXModeSelect feature exists on the PMP module. PLIB_PMP_ExistsOperationMode Identifies that the OperationMode feature exists on the PMP module. PLIB_PMP_ExistsOutPutBufferEmpty Identifies that the OutPutBufferEmpty feature exists on the PMP module. PLIB_PMP_ExistsOutputBufferXStatus Identifies that the OutputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsReadWritePolarity Identifies that the ReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsReadWriteStrobePortControl Identifies that the ReadWriteStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsReservedAddrSpace Identifies that the ReservedAddrSpace feature exists on the PMP module. PLIB_PMP_ExistsSlaveRX Identifies that the SlaveRX feature exists on the PMP module. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2492 PLIB_PMP_ExistsSlaveTX Identifies that the SlaveTX feature exists on the PMP module. PLIB_PMP_ExistsSmartAddress Identifies that the SmartAddress feature exists on the PMP module. PLIB_PMP_ExistsStopInIdleControl Identifies that the StopInIdleControl feature exists on the PMP module. PLIB_PMP_ExistsTransactionError Identifies that the TransactionError feature exists on the PMP module. PLIB_PMP_ExistsTransactionTimeOut Identifies that the TransactionTimeOut feature exists on the PMP module. PLIB_PMP_ExistsWaitStatesAddrHoldStrobe Identifies that the WaitStatesAddrHoldStrobe feature exists on the PMP module. PLIB_PMP_ExistsWaitStatesAddrLatchStrobe Identifies that the WaitStatesAddrLatchStrobe feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePolarity Identifies that the WriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePortControl Identifies that the WriteEnablePortControl feature exists on the PMP module. General Initialization Functions Name Description PLIB_PMP_AddressIncrementModeGet Gets the increment mode being used with the address of the PMP module. PLIB_PMP_AddressIncrementModeSelect Configures the increment mode being used with the address of the PMP module. PLIB_PMP_AddressLatchStrobeDisable Disables the specific address latch strobe. PLIB_PMP_AddressLatchStrobeEnable Enables the specific address latch strobe. PLIB_PMP_ChipSelectFunctionSelect Defines the functionality of the pins intended to be used as Chip Select. PLIB_PMP_ChipSelectXDisable Configures the Chip Select. PLIB_PMP_ChipSelectXEnable Configures the Chip Select. PLIB_PMP_ChipSelectXIsActive Gets the current status of the specified Chip Select. PLIB_PMP_DataSizeSelect Enables data transfer size for the PMP module. PLIB_PMP_Disable Disables the specific PMP module. PLIB_PMP_Enable Enables the specific PMP module. PLIB_PMP_InputBufferTypeSelect Selects the input buffer based on the input passed. PLIB_PMP_InterruptModeGet Gets the current configured interrupt mode being used with the PMP module. PLIB_PMP_InterruptModeSelect Configures the interrupt request mode being used with the PMP module. PLIB_PMP_MultiplexModeGet Gets the current multiplexing mode configured between the address and data of the PMP module. PLIB_PMP_MultiplexModeSelect Configures the multiplexing between the address and data of the PMP module. PLIB_PMP_OperationModeGet Gets the current operation mode of the PMP module. PLIB_PMP_OperationModeSelect Configures the operation mode of the PMP module. PLIB_PMP_StopInIdleDisable Enables the PMP module to continue operation in Idle mode. PLIB_PMP_StopInIdleEnable Discontinues PMP module operation when the device enters Idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2493 General Status Functions Name Description PLIB_PMP_IsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_PortIsBusy Identifies if the (Master mode) PMP port is busy. PLIB_PMP_InputOverflowHasOccurred Identifies if there was a receiver overflow error. PLIB_PMP_OutputUnderflowHasOccurred Identifies if there was an output buffer sent out with no data. Polarity Configuration Functions Name Description PLIB_PMP_AddressLatchPolaritySelect Sets the address latch strobe polarity. PLIB_PMP_ByteEnablePolaritySelect Sets the byte enable polarity. PLIB_PMP_ChipSelectXPolaritySelect Sets the specified Chip Select polarity. PLIB_PMP_ReadWriteStrobePolaritySelect Sets the polarity of the read strobe. PLIB_PMP_WriteEnableStrobePolaritySelect Sets the polarity of the write enable strobe. Port Configuration Functions Name Description PLIB_PMP_AddressPortDisable Disables the port lines specified as PMP address lines. PLIB_PMP_AddressPortEnable Enables the port lines specified as PMP address lines. PLIB_PMP_ByteEnablePortDisable Disables the byte enable port. PLIB_PMP_ByteEnablePortEnable Enables the byte enable port. PLIB_PMP_ReadWriteStrobePortDisable Disables the PMP module read strobe port. PLIB_PMP_ReadWriteStrobePortEnable Enables the PMP module read strobe port. PLIB_PMP_WriteEnableStrobePortDisable Disables the PMP module write strobe port. PLIB_PMP_WriteEnableStrobePortEnable Enables the PMP module write strobe port. Wait States Initialization Functions Name Description PLIB_PMP_WaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesDataSetUpSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module. Description The PMP peripheral library consists of a set of interface routines, data types and constants, and macros provided by the plib_pmp.h header file. This section describes those items. 5.6.16.6.1 General Initialization Functions 5.6.16.6.1.1 PLIB_PMP_AddressIncrementModeGet Function C PMP_INCREMENT_MODE PLIB_PMP_AddressIncrementModeGet( PMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2494 Description This function gets the pins used by the PMP module. Refer to the enumeration PMP_INCREMENT_MODE for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns PMP_INCREMENT_MODE - One of the possible values from PMP_INCREMENT_MODE Remarks This function implements an operation of the IncrementMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsIncrementMode in your application to to automatically determine whether this feature is available. Example PMP_INCREMENT_MODE curAddressIncMode; curAddressIncMode = PLIB_PMP_AddressIncrementModeGet( PMP_ID_0 ); 5.6.16.6.1.2 PLIB_PMP_AddressIncrementModeSelect Function C void PLIB_PMP_AddressIncrementModeSelect( PMP_MODULE_ID index, PMP_INCREMENT_MODE incrementMode ); Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_INCREMENT_MODE for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed incrementMode One of the possible values from PMP_INCREMENT_MODE Returns None. Remarks This function implements an operation of the IncrementMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsIncrementMode in your application to to automatically determine whether this feature is available. Example PLIB_PMP_AddressIncrementModeSelect( PMP_ID_0, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2495 5.6.16.6.1.3 PLIB_PMP_AddressLatchStrobeDisable Function C void PLIB_PMP_AddressLatchStrobeDisable( PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch ); Description This function disables the PMP module with a specific address latch strobe depending on which strobes are not needed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed latch Identifier for the latch to be disabled Returns None. Remarks This function implements an operation of the AddressLatchStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchStrobePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_UPPER ); PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_HIGH ); PLIB_PMP_AddressLatchStrobeDisable( PMP_ID_0, PMP_ADDRESS_LATCH_LOW ); 5.6.16.6.1.4 PLIB_PMP_AddressLatchStrobeEnable Function C void PLIB_PMP_AddressLatchStrobeEnable( PMP_MODULE_ID index, PMP_ADDRESS_LATCH latch ); Description This function enables the PMP module with a specific address latch strobe depending on which strobes are needed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed latch Identifier for the latch to be enabled Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2496 Remarks This function implements an operation of the AddressLatchStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchStrobePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_UPPER ); PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_HIGH ); PLIB_PMP_AddressLatchStrobeEnable( PMP_ID_0, PMP_ADDRESS_LATCH_LOW ); 5.6.16.6.1.5 PLIB_PMP_ChipSelectFunctionSelect Function C void PLIB_PMP_ChipSelectFunctionSelect( PMP_MODULE_ID index, PMP_CHIPSELECT_FUNCTION chipselfunct ); Description This function selects the PMCS1/PMCS2 as either Chip Select or as address lines depending on the way these bits are programmed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipselfunct One of the possible values from PMP_CHIPSELECT_FUNCTION Returns None. Remarks This function implements an operation of the ChipSelectoperation feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectoperation in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectFunctionSelect( PMP_ID_0, PMCS1_PMCS2_AS_ADDRESS_LINES ); 5.6.16.6.1.6 PLIB_PMP_ChipSelectXDisable Function C void PLIB_PMP_ChipSelectXDisable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function configures the Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as the address pin. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2497 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Returns None. Remarks This function implements an operation of the ChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectEnable in your application to to automatically determine whether this feature is available. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXDisable( PMP_ID_0, chipSelect ); 5.6.16.6.1.7 PLIB_PMP_ChipSelectXEnable Function C void PLIB_PMP_ChipSelectXEnable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function configures the Chip Select(s) being used by the PMP module. The specified Chip Select pin functions as ChipSelect. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for which Chip Select to configure Returns None. Remarks This function implements an operation of the ChipSelectEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipSelectEnable in your application to to automatically determine whether this feature is available. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXEnable( PMP_ID_0, chipSelect ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2498 5.6.16.6.1.8 PLIB_PMP_ChipSelectXIsActive Function C bool PLIB_PMP_ChipSelectXIsActive( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function gets the current status of the specified Chip Select. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for the Chip Select to be checked Returns • true - Chip Select is active • false - Chip Select is not active Remarks This function implements an operation of the CSXActiveStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsCSXActiveStatus in your application to to automatically determine whether this feature is available. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; if(PLIB_PMP_ChipSelectXIsActive( PMP_ID_0, chipSelect )) { //Do something useful } 5.6.16.6.1.9 PLIB_PMP_DataSizeSelect Function C void PLIB_PMP_DataSizeSelect( PMP_MODULE_ID index, PMP_DATA_SIZE size ); Description This function enables 4-bit, 8-bit, or 16-bit data transfer for the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed size Identifier for the data size to be used 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2499 Returns None. Remarks This function implements an operation of the DataTransferSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataTransferSize in your application to to automatically determine whether this feature is available. Example PLIB_PMP_DataSizeSelect( PMP_ID_0, PMP_DATA_SIZE_8_BITS ); 5.6.16.6.1.10 PLIB_PMP_Disable Function C void PLIB_PMP_Disable( PMP_MODULE_ID index ); Description This function disables the specific PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks The default state after any reset for a PMP module is the disable state. If the PMP is disabled, all the related pins are in control of the general purpose I/O logic. Disabling the PMP module resets the buffers to empty states. Any data characters in the buffers are lost. All error and status bits are also reset. Disabling the PMP while the PMP is active, will abort all pending transmissions and receptions. Re-enabling the PMP will restart the module in the same configuration. When disabled, the PMP power consumption is minimal. This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_Disable( PMP_ID_0 ); 5.6.16.6.1.11 PLIB_PMP_Enable Function C void PLIB_PMP_Enable( PMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2500 Description This function enables the specific PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to automatically determine whether this feature is available. Example PLIB_PMP_Enable( PMP_ID_0 ); 5.6.16.6.1.12 PLIB_PMP_InputBufferTypeSelect Function C void PLIB_PMP_InputBufferTypeSelect( PMP_MODULE_ID index, PMP_INPUT_BUFFER_TYPE inputBuffer ); Description This function selects the input buffer based on the input passed. Either TTL or Schmitt Trigger input buffers are selected. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed inputBuffer One of the possible input buffer types Returns None. Remarks This function implements an operation of the BufferType feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferType in your application to to automatically determine whether this feature is available. Example PLIB_PMP_InputBufferTypeSelect( PMP_ID_0, PMP_INPUT_BUFFER_TTL ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2501 5.6.16.6.1.13 PLIB_PMP_InterruptModeGet Function C PMP_INTERRUPT_MODE PLIB_PMP_InterruptModeGet( PMP_MODULE_ID index ); Description This function gets the current configured interrupt mode being used with the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns One of the possible values from PMP_INTERRUPT_MODE. Remarks This function implements an operation of the InterruptMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInterruptMode in your application to to automatically determine whether this feature is available. Example PMP_INTERRUPT_MODE currentIntMode; currentIntMode = PLIB_PMP_InterruptModeGet ( PMP_ID_0 ); 5.6.16.6.1.14 PLIB_PMP_InterruptModeSelect Function C void PLIB_PMP_InterruptModeSelect( PMP_MODULE_ID index, PMP_INTERRUPT_MODE interruptMode ); Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_INTERRUPT_MODE for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed interruptMode One of the possible values from PMP_INTERRUPT_MODE Returns None. Remarks This function implements an operation of the InterruptMode feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2502 refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInterruptMode in your application to to automatically determine whether this feature is available. Example PLIB_PMP_InterruptModeSelect( PMP_ID_0, PMP_INTERRUPT_NONE ); 5.6.16.6.1.15 PLIB_PMP_MultiplexModeGet Function C PMP_MUX_MODE PLIB_PMP_MultiplexModeGet( PMP_MODULE_ID index ); Description This function gets the current multiplexing mode configured between the address and data of the PMP module. Preconditions None. Returns index - Identifier for the device instance to be addressed PMP_MUX_MODE - One of the possible values from PMP_MUX_MODE Remarks This function implements an operation of the MUXModeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMUXModeSelect in your application to to automatically determine whether this feature is available. Example PMP_MUX_MODE currentMuxMode; currentMuxMode = PLIB_PMP_MultiplexModeGet( PMP_ID_0 ); 5.6.16.6.1.16 PLIB_PMP_MultiplexModeSelect Function C void PLIB_PMP_MultiplexModeSelect( PMP_MODULE_ID index, PMP_MUX_MODE multiplexMode ); Description This function configures the pins used by the PMP module. Refer to the enumeration PMP_MUX_MODE for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed multiplexMode One of the possible values from the PMP_MUX_MODE Returns None. Remarks This function implements an operation of the MUXModeSelect feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2503 refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMUXModeSelect in your application to to automatically determine whether this feature is available. Example PLIB_PMP_MultiplexModeSelect( PMP_ID_0, PMP_MUX_NONE ); 5.6.16.6.1.17 PLIB_PMP_OperationModeGet Function C PMP_OPERATION_MODE PLIB_PMP_OperationModeGet( PMP_MODULE_ID index ); Description This function gets the current operation mode of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns PMP_OPERATION_MODE - One of the possible values from PMP_OPERATION_MODE Remarks This function implements an operation of the OperationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOperationMode in your application to to automatically determine whether this feature is available. Example PMP_OPERATION_MODE curOpMode; curOpMode = PLIB_PMP_OperationModeGet( PMP_ID_0 ); 5.6.16.6.1.18 PLIB_PMP_OperationModeSelect Function C void PLIB_PMP_OperationModeSelect( PMP_MODULE_ID index, PMP_OPERATION_MODE operationMode ); Description This function configures operation mode of the PMP module. Refer to the enumeration PMP_OPERATION_MODE for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed operationMode One of the possible values from PMP_OPERATION_MODE 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2504 Returns None. Remarks This function implements an operation of the OperationMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOperationMode in your application to to automatically determine whether this feature is available. Example PLIB_PMP_OperationModeSelect( PMP_ID_0, PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED ); 5.6.16.6.1.19 PLIB_PMP_StopInIdleDisable Function C void PLIB_PMP_StopInIdleDisable( PMP_MODULE_ID index ); Description This function disables the stop in idle flag. The PMP module continues operation in Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks By default, the PMP module will continue operation in Idle mode. This function implements an operation of the StopInIdleControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsStopInIdleControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_StopInIdleDisable( PMP_ID_0 ); 5.6.16.6.1.20 PLIB_PMP_StopInIdleEnable Function C void PLIB_PMP_StopInIdleEnable( PMP_MODULE_ID index ); Description This function enables the PMP module to discontinue operation when the device enters Idle mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2505 Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the StopInIdleControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsStopInIdleControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_StopInIdleEnable( PMP_ID_0 ); 5.6.16.6.2 Enhanced General Initialization Functions 5.6.16.6.2.1 PLIB_PMP_BusKeeperDisable Function C void PLIB_PMP_BusKeeperDisable( PMP_MODULE_ID index ); Description The data bus can be kept in a high-impedance state when not actively being driven. This function disables this "bus keeper" state. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the BusKeeper feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBusKeeper in your application to to automatically determine whether this feature is available. Example PLIB_PMP_BusKeeperDisable ( PMP_ID_0 ); 5.6.16.6.2.2 PLIB_PMP_BusKeeperEnable Function C void PLIB_PMP_BusKeeperEnable( PMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2506 Description The data bus can be kept in a high-impedance state when not actively being driven. This function enables this "bus keeper" state. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the BusKeeper feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBusKeeper in your application to to automatically determine whether this feature is available. Example PLIB_PMP_BusKeeperEnable ( PMP_ID_0 ); 5.6.16.6.2.3 PLIB_PMP_ChipSelectXEnableStrobeDeSelect Function C void PLIB_PMP_ChipSelectXEnableStrobeDeSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function selects the read and write strobes. The read and write strobes have independent lines. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXEnableStorbeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXEnableStorbeSelect in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXEnableStrobeDeSelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2507 5.6.16.6.2.4 PLIB_PMP_ChipSelectXEnableStrobeSelect Function C void PLIB_PMP_ChipSelectXEnableStrobeSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function selects the read/write and enable strobes. The read and write strobes share a common line. A separate enable line is provided to differentiate between read and write operations. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXEnableStorbeSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXEnableStorbeSelect in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXEnableStrobeSelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE ); 5.6.16.6.2.5 PLIB_PMP_SmartAddressStrobeDisable Function C void PLIB_PMP_SmartAddressStrobeDisable( PMP_MODULE_ID index ); Description This function disables "smart" address strobes (each address phase is only present if the current access would cause a different address in the latch than the previous address). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the SmartAddress feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2508 refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSmartAddress in your application to to automatically determine whether this feature is available. Example PLIB_PMP_SmartAddressStrobeDisable ( PMP_ID_0 ); 5.6.16.6.2.6 PLIB_PMP_SmartAddressStrobeEnable Function C void PLIB_PMP_SmartAddressStrobeEnable( PMP_MODULE_ID index ); Description This function enables "smart" address strobes (each address phase is only present if the current access would cause a different address in the latch than the previous address). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the SmartAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSmartAddress in your application to to automatically determine whether this feature is available. Example PLIB_PMP_SmartAddressStrobeEnable ( PMP_ID_0 ); 5.6.16.6.2.7 PLIB_PMP_ChipXAckModeSelect Function C void PLIB_PMP_ChipXAckModeSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_ACK_MODE mode ); Description This function sets the acknowledge for the PMP module. Either enables, disables, or enables it with time-out. See the PMP_ACK_MODE enumeration for additional information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed mode Identifier for the acknowledge mode to be selected 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2509 chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXACKMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXACKMode in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipXAckModeSelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_ACK_DISABLED ); 5.6.16.6.2.8 PLIB_PMP_ChipXDataSizeSelect Function C void PLIB_PMP_ChipXDataSizeSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_DATA_SIZE size ); Description This function enables 4-bit, 8-bit, or 16-bit data transfer for the PMP for the specified device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed size Identifier for the data size to be used chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXDataSize feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXDataSize in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipXDataSizeSelect( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_DATA_SIZE_8_BITS ); 5.6.16.6.2.9 PLIB_PMP_EnhancedMasterModeSelect Function C void PLIB_PMP_EnhancedMasterModeSelect( PMP_MODULE_ID index, PMP_MASTER_MODE master ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2510 Description This function sets the PMP module for Master mode (either CPU or alternate master). The alternate master can have direct I/O access. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed master Identifier for the master to be selected Returns None. Remarks This function implements an operation of the EnhancedMasterMode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnhancedMasterMode in your application to to automatically determine whether this feature is available. Example PLIB_PMP_EnhancedMasterModeSelect ( PMP_ID_0, PMP_CPU_MASTER ); 5.6.16.6.3 General Status Functions 5.6.16.6.3.1 PLIB_PMP_IsEnabled Function C bool PLIB_PMP_IsEnabled( PMP_MODULE_ID index ); Description This function checks whether or not the PMP module is enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the PMP module is enabled • false - if the PMP module is disabled Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsEnableControl in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2511 Example bool pmpStatus; pmpStatus = PLIB_PMP_IsEnabled( PMP_ID_0 ); 5.6.16.6.3.2 PLIB_PMP_PortIsBusy Function C bool PLIB_PMP_PortIsBusy( PMP_MODULE_ID index ); Description This function identifies if the PMP port is busy (in Master mode). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the port is busy • false - If the port is not busy Remarks Works only in Master mode. This function implements an operation of the BusyStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBusyStatus in your application to to automatically determine whether this feature is available. Example bool status; status = PLIB_PMP_PortIsBusy( PMP_ID_0 ); 5.6.16.6.3.3 PLIB_PMP_InputOverflowHasOccurred Function C bool PLIB_PMP_InputOverflowHasOccurred( PMP_MODULE_ID index ); Description This function identifies if there was a receiver overflow error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the input buffer has overflowed • false - If the input buffer has not overflowed 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2512 Remarks This function implements an operation of the BufferOverFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferOverFlow in your application to to automatically determine whether this feature is available. Example if(PLIB_PMP_InputOverflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_InputOverflowClear( PMP_ID_0 ); } 5.6.16.6.3.4 PLIB_PMP_OutputUnderflowHasOccurred Function C bool PLIB_PMP_OutputUnderflowHasOccurred( PMP_MODULE_ID index ); Description This function identifies if there was a output buffer was sent out with no data. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the input buffer was empty when data was sent • false - If the output buffer was not empty when data was sent Remarks This function implements an operation of the BufferUnderFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferUnderFlow in your application to to automatically determine whether this feature is available. Example if(PLIB_PMP_OutputUnderflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_OutputUnderflowClear( PMP_ID_0 ); } 5.6.16.6.4 Enhanced General Status Functions 5.6.16.6.4.1 PLIB_PMP_AlternateMasterHasAccess Function C bool PLIB_PMP_AlternateMasterHasAccess( PMP_MODULE_ID index ); Description This function gets the status of the alternate masters that have gained access to the PMP module, whether or not the alternate 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2513 master has access to the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the alternate master has gained access to the PMP module • false - If the CPU has gained access to the PMP module Remarks This function implements an operation of the CurrentMaster feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsCurrentMaster in your application to to automatically determine whether this feature is available. Example status = PLIB_PMP_AlternateMasterHasAccess ( PMP_ID_0 ); 5.6.16.6.4.2 PLIB_PMP_AlternateMasterRequestStatus Function C bool PLIB_PMP_AlternateMasterRequestStatus( PMP_MODULE_ID index ); Description This function gets the status of the request from the alternate master, whether or not the master is requesting use of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the alternate master is requesting use of the PMP module • false - If the alternate master is not a making request for the PMP module Remarks This function implements an operation of the AltMasterRequest feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAltMasterRequest in your application to to automatically determine whether this feature is available. Example status = PLIB_PMP_AlternateMasterRequestStatus ( PMP_ID_0 ); 5.6.16.6.5 Error Status/Control Functions 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2514 5.6.16.6.5.1 PLIB_PMP_InputOverflowClear Function C void PLIB_PMP_InputOverflowClear( PMP_MODULE_ID index ); Description This function clears an overflow error. Clearing the error resets the receive buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the BufferOverFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferOverFlow in your application to to automatically determine whether this feature is available. Example if(PLIB_PMP_InputOverflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_InputOverflowClear( PMP_ID_0 ); } 5.6.16.6.5.2 PLIB_PMP_OutputUnderflowClear Function C void PLIB_PMP_OutputUnderflowClear( PMP_MODULE_ID index ); Description This function clears a PMP output underflow error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the BufferUnderFlow feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferUnderFlow in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2515 Example if(PLIB_PMP_OutputUnderflowHasOccurred( PMP_ID_0 )) { PLIB_PMP_OutputUnderflowClear( PMP_ID_0 ); } 5.6.16.6.6 Enhanced Error/Status Control Functions 5.6.16.6.6.1 PLIB_PMP_TransactionErrorClear Function C void PLIB_PMP_TransactionErrorClear( PMP_MODULE_ID index ); Description This function clears the transaction error flag. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the TransactionError feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsTransactionError in your application to to automatically determine whether this feature is available. Example if(PLIB_PMP_TransactionErrorHasOccurred ( PMP_ID_0 ) ) PLIB_PMP_TransactionErrorClear ( PMP_ID_0 ); 5.6.16.6.6.2 PLIB_PMP_TransactionErrorHasOccurred Function C bool PLIB_PMP_TransactionErrorHasOccurred( PMP_MODULE_ID index ); Description This function returns the status of a transaction error if an illegal transaction was requested. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2516 Returns • true - If illegal transaction was requested • false - Transaction completed successfully Remarks This function implements an operation of the TransactionError feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsTransactionError in your application to to automatically determine whether this feature is available. Example status = PLIB_PMP_TransactionErrorHasOccurred ( PMP_ID_0 ); 5.6.16.6.6.3 PLIB_PMP_TransactionHasTimedOut Function C bool PLIB_PMP_TransactionHasTimedOut( PMP_MODULE_ID index ); Description This function returns the time-out status of the PMP transaction. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If the transaction timed out • false - If the transaction completed successfully Remarks This function implements an operation of the TransactionTimeOut feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsTransactionTimeOut in your application to to automatically determine whether this feature is available. Example status = PLIB_PMP_TransactionHasTimedOut ( PMP_ID_0 ); 5.6.16.6.6.4 PLIB_PMP_TransactionTimeoutClear Function C void PLIB_PMP_TransactionTimeoutClear( PMP_MODULE_ID index ); Description This function clears the time-out flag. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2517 Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the TransactionTimeOut feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsTransactionTimeOut in your application to to automatically determine whether this feature is available. Example if(PLIB_PMP_TransactionHasTimedOut ( PMP_ID_0 )) PLIB_PMP_TransactionTimeoutClear ( PMP_ID_0 ); 5.6.16.6.7 Data Read and Write Functions 5.6.16.6.7.1 PLIB_PMP_InputBuffersAreFull Function C bool PLIB_PMP_InputBuffersAreFull( PMP_MODULE_ID index ); Description This function gets the state of the input buffers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If all input buffers are full • false - If all input buffers are not full Remarks This function implements an operation of the InputBufferFull feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferFull in your application to to automatically determine whether this feature is available. Example uint8_t value; if(PLIB_PMP_InputBuffersAreFull( PMP_ID_0 )) { value = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2518 5.6.16.6.7.2 PLIB_PMP_InputBufferXByteReceive Function C uint8_t PLIB_PMP_InputBufferXByteReceive( PMP_MODULE_ID index, uint8_t buffer ); Description The data to be received in Byte mode from the specified PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible buffers (valid values are 0 to 3) Returns data - Data to be received Remarks This function implements an operation of the BufferRead feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferRead in your application to to automatically determine whether this feature is available. Example uint8_t mydata; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { // get data from buffer-1 mydata = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 1 ); } 5.6.16.6.7.3 PLIB_PMP_InputBufferXIsFull Function C bool PLIB_PMP_InputBufferXIsFull( PMP_MODULE_ID index, uint8_t buffer ); Description This function gets the state of the identified input buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed buffer The input buffer number (valid values are 0 to 3) 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2519 Returns • true - If all input buffers are full • false - If all input buffers are not full Remarks This function implements an operation of the InputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferXStatus in your application to to automatically determine whether this feature is available. Example uint8_t value; // Check the status of buffer-2 if(PLIB_PMP_InputBufferXIsFull( PMP_ID_0, 2 )) { // get data from buffer 2 value = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 2 ); } 5.6.16.6.7.4 PLIB_PMP_IsDataReceived Function C bool PLIB_PMP_IsDataReceived( PMP_MODULE_ID index, uint8_t buffer ); Description This function checks and returns if the data has been received in the specified buffer in Slave mode. Preconditions The PMP module should be configured for Slave mode operation. Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible input buffers (valid values are 0 to 3) Returns • true - Data has been received in the specified buffer • false - Data has not been received in the specified buffer Remarks This function implements an operation of the InputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsInputBufferXStatus in your application to to automatically determine whether this feature is available. Example int8_t data; // Check if data is received on buffer-2 if(PLIB_PMP_IsDataReceived( PMP_ID_0, 2 )) { // get data from buffer-2 data = PLIB_PMP_InputBufferXByteReceive( PMP_ID_0, 2 ); } 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2520 5.6.16.6.7.5 PLIB_PMP_IsDataTransmitted Function C bool PLIB_PMP_IsDataTransmitted( PMP_MODULE_ID index, uint8_t buffer ); Description Checks and returns if data has been transmitted from the specified buffer. Preconditions The PMP module should be configured for Slave mode operation. Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible output buffers (valid range is 0 to 3) Returns • true - If data has been transmitted from the specified buffer • false - If data has not been transmitted from the specified buffer Remarks This function implements an operation of the OutputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutputBufferXStatus in your application to to automatically determine whether this feature is available. Example uint8_t data; if(PLIB_PMP_IsDataTransmitted( PMP_ID_0, 2 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 2, data ); } 5.6.16.6.7.6 PLIB_PMP_MasterReceive Function C uint16_t PLIB_PMP_MasterReceive( PMP_MODULE_ID index ); Description This function receives the data. The dataflow is from slave to master. Preconditions The PMP module is configured as master. Parameters Parameters Description index Identifier for the device instance to be addressed. Returns uint16_t - Data received 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2521 Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the MasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMasterRXTX in your application to to automatically determine whether this feature is available. Example uint16_t data; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { data = PLIB_PMP_MasterReceive( PMP_ID_0 ); } 5.6.16.6.7.7 PLIB_PMP_MasterSend Function C void PLIB_PMP_MasterSend( PMP_MODULE_ID index, uint16_t data ); Description This function sends the specified data. The data flow is from master to slave. Preconditions The PMP module is configured for Master Mode. Parameters Parameters Description index Identifier for the device instance to be addressed data Data to be transmitted Returns None. Remarks This function to be used only when the PMP is acting as master. This function implements an operation of the MasterRXTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsMasterRXTX in your application to to automatically determine whether this feature is available. Example uint16_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_MasterSend( PMP_ID_0, data ); } 5.6.16.6.7.8 PLIB_PMP_OutputBuffersAreEmpty Function C bool PLIB_PMP_OutputBuffersAreEmpty( PMP_MODULE_ID index ); Description This function gets the state of the output buffers. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2522 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns • true - If all output buffers are empty -false - If all output buffers are not empty Remarks This function implements an operation of the OutPutBufferEmpty feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutPutBufferEmpty in your application to to automatically determine whether this feature is available. Example uint8_t value=0xEF; if(PLIB_PMP_OutputBuffersAreEmpty( PMP_ID_0 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, value); } 5.6.16.6.7.9 PLIB_PMP_OutputBufferXByteSend Function C void PLIB_PMP_OutputBufferXByteSend( PMP_MODULE_ID index, uint8_t buffer, uint8_t data ); Description The data is transmitted in Byte mode for the specified PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed buffer One of the possible output buffers (valid range is 0 to 3) data Data to be transmitted Returns None. Remarks This function implements an operation of the BufferWrite feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsBufferWrite in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2523 Example uint8_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0, 1, data ); } 5.6.16.6.7.10 PLIB_PMP_OutputBufferXIsEmpty Function C bool PLIB_PMP_OutputBufferXIsEmpty( PMP_MODULE_ID index, uint8_t buffer ); Description This function gets the state of the input buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed buffer Output buffer number (valid range is 0 to 3) Returns • true - If the identified output buffer is empty • false - If the identified output buffer is not empty Remarks This function implements an operation of the OutputBufferXStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsOutputBufferXStatus in your application to to automatically determine whether this feature is available. Example uint8_t value = 0xEF; if(PLIB_PMP_OutputBufferXIsEmpty( PMP_ID_0, 1 ) ) { PLIB_PMP_OutputBufferXByteSend( PMP_ID_0,1, value); } 5.6.16.6.7.11 PLIB_PMP_SlaveReceive Function C uint16_t PLIB_PMP_SlaveReceive( PMP_MODULE_ID index ); Description This function receives the data. The dataflow is from master to slave. Preconditions The PMP module is configured as slave. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2524 Parameters Parameters Description index Identifier for the device instance to be addressed. Returns uint16_t - Data received Remarks This function to be used only when the PMP is acting as slave. This function implements an operation of the SlaveRX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSlaveRX in your application to to automatically determine whether this feature is available. Example uint16_t data; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { data = PLIB_PMP_SlaveReceive( PMP_ID_0 ); } 5.6.16.6.7.12 PLIB_PMP_SlaveSend Function C void PLIB_PMP_SlaveSend( PMP_MODULE_ID index, uint16_t data ); Description This function sends the specified data. The data flow is from slave to master. Preconditions The PMP module is configured for Slave Mode. Parameters Parameters Description index Identifier for the device instance to be addressed data Data to be transmitted Returns None. Remarks This function to be used only when the PMP is acting as slave. This function implements an operation of the SlaveTX feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsSlaveTX in your application to to automatically determine whether this feature is available. Example uint16_t data = 'a'; if(!PLIB_PMP_PortIsBusy( PMP_ID_0 )) { PLIB_PMP_SlaveSend( PMP_ID_0, data ); } 5.6.16.6.8 Wait States Initialization Functions 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2525 5.6.16.6.8.1 PLIB_PMP_WaitStatesDataHoldSelect Function C void PLIB_PMP_WaitStatesDataHoldSelect( PMP_MODULE_ID index, PMP_DATA_HOLD_STATES dataHoldState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_DATA_HOLD_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed dataHoldState One of the possible values from PMP_DATA_HOLD_STATES Returns None. Remarks This function implements an operation of the DataHoldWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataHoldWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WaitStatesDataHoldSelect( PMP_ID_0, PMP_DATA_HOLD_2 ); 5.6.16.6.8.2 PLIB_PMP_WaitStatesDataSetUpSelect Function C void PLIB_PMP_WaitStatesDataSetUpSelect( PMP_MODULE_ID index, PMP_DATA_WAIT_STATES dataWaitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_DATA_WAIT_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed dataWaitState One of the possible values from PMP_DATA_WAIT_STATES Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2526 Remarks This function implements an operation of the DataSetUpWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataSetUpWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WaitStatesDataSetUpSelect( PMP_ID_0, PMP_DATA_WAIT_TWO ); 5.6.16.6.8.3 PLIB_PMP_WaitStatesStrobeSelect Function C void PLIB_PMP_WaitStatesStrobeSelect( PMP_MODULE_ID index, PMP_STROBE_WAIT_STATES strobeWaitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_STROBE_WAIT_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed strobeWaitState One of the possible values from PMP_STROBE_WAIT_STATES Returns None. Remarks This function implements an operation of the DataStrobeWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsDataStrobeWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WaitStatesStrobeSelect( PMP_ID_0, PMP_STROBE_WAIT_2 ); 5.6.16.6.9 Enhanced Wait States Initialization Functions 5.6.16.6.9.1 PLIB_PMP_ChipXWaitStatesAlternateMasterSelect Function C void PLIB_PMP_ChipXWaitStatesAlternateMasterSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_ALTERNATE_MASTER_WAIT_STATES waitStates ); Description Selects the wait states of the alternate master for Chip Select-X. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2527 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed waitStates Identifier for wait states chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXAltMasterWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXAltMasterWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipXWaitStatesAlternateMasterSelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_ALTERNATE_MASTER_WAIT_THREE ); 5.6.16.6.9.2 PLIB_PMP_ChipXWaitStatesDataHoldSelect Function C void PLIB_PMP_ChipXWaitStatesDataHoldSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipselect, PMP_DATA_HOLD_STATES dataHoldState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_DATA_HOLD_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipselect One of the possible values from PMP_CHIP_SELECT dataHoldState One of the possible values from PMP_DATA_HOLD_STATES Returns None. Remarks This function implements an operation of the ChipXDataHoldWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXDataHoldWaitStates in your application to to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2528 Example PLIB_PMP_ChipXWaitStatesDataHoldSelect( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_DATA_HOLD_2 ); 5.6.16.6.9.3 PLIB_PMP_ChipXWaitStatesDataSetupSelect Function C void PLIB_PMP_ChipXWaitStatesDataSetupSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipselect, PMP_DATA_WAIT_STATES dataWaitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states for the specified device. Refer to the enumeration PMP_DATA_WAIT_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipselect One of the possible values from PMP_CHIP_SELECT dataWaitState One of the possible values from PMP_DATA_WAIT_STATES Returns None. Remarks This function implements an operation of the ChipXDataSetupWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXDataSetupWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipXWaitStatesDataSetupSelect( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_DATA_WAIT_ONE ); 5.6.16.6.9.4 PLIB_PMP_ChipXWaitStatesStrobeSelect Function C void PLIB_PMP_ChipXWaitStatesStrobeSelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipselect, PMP_STROBE_WAIT_STATES strobeWaitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states for the specified device. Refer to the enumeration PMP_STROBE_WAIT_STATES for the possible settings. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2529 Parameters Parameters Description index Identifier for the device instance to be addressed chipselect One of the possible values from PMP_CHIP_SELECT strobeWaitState One of the possible values from PMP_STROBE_WAIT_STATES Returns None. Remarks This function implements an operation of the ChipXStrobeWaitStates feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXStrobeWaitStates in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipXWaitStatesStrobeSelect( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_STROBE_WAIT_3 ); 5.6.16.6.9.5 PLIB_PMP_WaitStatesAddressHoldStrobeSelect Function C void PLIB_PMP_WaitStatesAddressHoldStrobeSelect( PMP_MODULE_ID index, PMP_ADDRESS_HOLD_LATCH_WAIT_STATES waitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_ADDRESS_HOLD_LATCH_WAIT_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed waitState One of the possible values from PMP_ADDRESS_HOLD_LATCH_WAIT_STATES Returns None. Remarks This function implements an operation of the WaitStatesAddrHoldStrobe feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWaitStatesAddrHoldStrobe in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WaitStatesAddressHoldStrobeSelect( PMP_ID_0, PMP_ADDRESS_HOLD_ONE_AND_ONE_QUARTER ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2530 5.6.16.6.9.6 PLIB_PMP_WaitStatesAddressLatchStrobeSelect Function C void PLIB_PMP_WaitStatesAddressLatchStrobeSelect( PMP_MODULE_ID index, PMP_ADDRESS_LATCH_WAIT_STATES waitState ); Description This function configures the number of peripheral bus clock cycles needed for wait states. Refer to the enumeration PMP_ADDRESS_LATCH_WAIT_STATES for the possible settings. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed waitState One of the possible values from PMP_ADDRESS_LATCH_WAIT_STATES Returns None. Remarks This function implements an operation of the WaitStatesAddrLatchStrobe feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWaitStatesAddrLatchStrobe in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WaitStatesAddressLatchStrobeSelect( PMP_ID_0, PMP_ADDRESS_WAIT_ONE_AND_HALF ); 5.6.16.6.10 Address Handling Functions 5.6.16.6.10.1 PLIB_PMP_AddressGet Function C uint32_t PLIB_PMP_AddressGet( PMP_MODULE_ID index ); Description This function gets the current address of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns address - Device address to be set 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2531 Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Example uint32_t address; address = PLIB_PMP_AddressGet( PMP_ID_0 ); 5.6.16.6.10.2 PLIB_PMP_AddressLinesA0A1Get Function C uint8_t PLIB_PMP_AddressLinesA0A1Get( PMP_MODULE_ID index ); Description This function gets the value of the address lines PMA0 and PMA1. This function is used in the addressable parallel slave port mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns uint8_t - The two-bit address Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Example uint8_t bufferAddress; bufferAddress = PLIB_PMP_AddressLinesA0A1Get( PMP_ID_0 ); 5.6.16.6.10.3 PLIB_PMP_AddressLinesA0A1Set Function C void PLIB_PMP_AddressLinesA0A1Set( PMP_MODULE_ID index, uint8_t address ); Description This function sets the address lines PMA0 and PMA1 with the value specified. This function is used in the addressable parallel slave port mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2532 Parameters Parameters Description index Identifier for the device instance to be addressed address The two-bit address Returns None. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Example uint8_t bufferAddress = 0x2; PLIB_PMP_AddressLinesA0A1Set( PMP_ID_0, bufferAddress ); 5.6.16.6.10.4 PLIB_PMP_AddressSet Function C void PLIB_PMP_AddressSet( PMP_MODULE_ID index, uint32_t address ); Description This function sets the current address of the PMP module to the specified value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed address Device address to be set Returns None. Remarks This function implements an operation of the AddressControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressControl in your application to to automatically determine whether this feature is available. Example uint8_t no_of_addressLines = 8; PLIB_PMP_AddressSet( PMP_ID_0, 0xff ); 5.6.16.6.11 Enhanced Address Handling Functions 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2533 5.6.16.6.11.1 PLIB_PMP_ChipXBaseAddressSet Function C void PLIB_PMP_ChipXBaseAddressSet( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, uint16_t baseAddress ); Description This function sets the base address of the specified device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed baseAddress Base address of the chip chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the ChipXBaseAddress feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXBaseAddress in your application to to automatically determine whether this feature is available. Example uint16_t baseAddress = 0x00FF; PLIB_PMP_ChipXBaseAddressSet( PMP_ID_0, PMP_CHIP_SELECT_ONE, baseAddress ); 5.6.16.6.11.2 PLIB_PMP_ReservedAddressSpaceBitsSet Function C void PLIB_PMP_ReservedAddressSpaceBitsSet( PMP_MODULE_ID index, uint8_t reservedAddress ); Description This function sets the address bits of the reserved address space of the EPMP. The reserved address space determines the end address of the Chip Select-2 (if used). If the reserved address space is set to 0, the last EDS address for the Chip Select-2 will be 0xFFFFFF. For the address range to be accessible for the Chip Select-2 set the reserved address space to a value higher than Chip Select-2 base address. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed reservedAddress The reserved address bits 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2534 Returns None. Remarks This function implements an operation of the ReservedAddrSpace feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReservedAddrSpace in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ReservedAddressSpaceBitsSet ( PMP_ID_0, 0xDF ); 5.6.16.6.12 Port Configuration Functions 5.6.16.6.12.1 PLIB_PMP_AddressPortDisable Function C void PLIB_PMP_AddressPortDisable( PMP_MODULE_ID index, PMP_ADDRESS_PORT portfunctions ); Description This function disables the port lines specified as PMP address lines. They function as normal I/O lines. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed portfunctions One of the possible values from PMP_ADDRESS_PORT Returns None. Remarks This function implements an operation of the AddressPortPinControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressPortPinControl in your application to to automatically determine whether this feature is available. Example //Example-1 PMP_ADDRESS_PORT portfunctions = PMP_PMA2_TO_PMA13_PORTS; PLIB_PMP_AddressPortDisable( PMP_ID_0, PMP_PMA2_TO_PMA13_PORTS ); //Example-2 PLIB_PMP_AddressPortDisable( PMP_ID_0, ( PMP_PMA14_PORT | PMP_PMA15_PORT ) ); 5.6.16.6.12.2 PLIB_PMP_AddressPortEnable Function C void PLIB_PMP_AddressPortEnable( PMP_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2535 PMP_ADDRESS_PORT portfunctions ); Description This function enables the port lines specified as PMP address lines. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed portfunctions One of the possible values from PMP_ADDRESS_PORT Returns None. Remarks This function implements an operation of the AddressPortPinControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressPortPinControl in your application to to automatically determine whether this feature is available. Example //Example-1 PMP_ADDRESS_PORT portfunctions = PMP_PMA2_TO_PMA13_PORTS; PLIB_PMP_AddressPortEnable( PMP_ID_0, PMP_PMA2_TO_PMA13_PORTS ); //Example-2 PLIB_PMP_AddressPortEnable( PMP_ID_0, ( PMP_PMA14_PORT | PMP_PMA15_PORT ) ); 5.6.16.6.12.3 PLIB_PMP_ByteEnablePortDisable Function C void PLIB_PMP_ByteEnablePortDisable( PMP_MODULE_ID index, PMP_PMBE_PORT pmbeInstance ); Description This function disables the byte enable port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed pmbeInstance One of the possible values from PMP_PMBE_PORT Returns None. Remarks This function implements an operation of the ExistsByteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2536 PLIB_PMP_ExistsExistsByteEnablePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ByteEnablePortDisable( PMP_ID_0, PMBE_0 ); 5.6.16.6.12.4 PLIB_PMP_ByteEnablePortEnable Function C void PLIB_PMP_ByteEnablePortEnable( PMP_MODULE_ID index, PMP_PMBE_PORT pmbeInstance ); Description This function enables the byte enable port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed pmbeInstance One of the possible values from PMP_PMBE_PORT Returns None. Remarks This function implements an operation of the ExistsByteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsExistsByteEnablePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ByteEnablePortEnable( PMP_ID_0, PMBE_0 ); 5.6.16.6.12.5 PLIB_PMP_ReadWriteStrobePortDisable Function C void PLIB_PMP_ReadWriteStrobePortDisable( PMP_MODULE_ID index ); Description This function disables the read strobe port of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2537 Remarks This function implements an operation of the ReadWriteStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWriteStrobePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ReadWriteStrobePortDisable( PMP_ID_0 ); 5.6.16.6.12.6 PLIB_PMP_ReadWriteStrobePortEnable Function C void PLIB_PMP_ReadWriteStrobePortEnable( PMP_MODULE_ID index ); Description This function enables the read strobe port of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the ReadWriteStrobePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWriteStrobePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ReadWriteStrobePortEnable( PMP_ID_0 ); 5.6.16.6.12.7 PLIB_PMP_WriteEnableStrobePortDisable Function C void PLIB_PMP_WriteEnableStrobePortDisable( PMP_MODULE_ID index ); Description This function disables the write strobe port of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2538 Returns None. Remarks This function implements an operation of the WriteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WriteEnableStrobePortDisable( PMP_ID_0 ); 5.6.16.6.12.8 PLIB_PMP_WriteEnableStrobePortEnable Function C void PLIB_PMP_WriteEnableStrobePortEnable( PMP_MODULE_ID index ); Description This function enables the write strobe port of the PMP module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed Returns None. Remarks This function implements an operation of the WriteEnablePortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WriteEnableStrobePortEnable( PMP_ID_0 ); 5.6.16.6.13 Enhanced Port Configuration Functions 5.6.16.6.13.1 PLIB_PMP_ChipSelectXPortDisable Function C void PLIB_PMP_ChipSelectXPortDisable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function disables the specified Chip Select's port. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2539 Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the CSXPortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsCSXPortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXPortDisable ( PMP_ID_0, PMP_CHIP_SELECT_ONE ); 5.6.16.6.13.2 PLIB_PMP_ChipSelectXPortEnable Function C void PLIB_PMP_ChipSelectXPortEnable( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect ); Description This function enables the specified Chip Select's port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT Returns None. Remarks This function implements an operation of the CSXPortControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsCSXPortControl in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXPortEnable ( PMP_ID_0, PMP_CHIP_SELECT_ONE ); 5.6.16.6.14 Polarity Configuration Functions 5.6.16.6.14.1 PLIB_PMP_AddressLatchPolaritySelect Function C void PLIB_PMP_AddressLatchPolaritySelect( PMP_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2540 PMP_POLARITY_LEVEL polarity ); Description This function sets the address latch polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Returns None. Remarks This function implements an operation of the AddressLatchPolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsAddressLatchPolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_AddressLatchPolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); 5.6.16.6.14.2 PLIB_PMP_ByteEnablePolaritySelect Function C void PLIB_PMP_ByteEnablePolaritySelect( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ); Description This function sets the byte enable polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ByteEnablePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsByteEnablePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ByteEnablePolaritySelect ( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2541 5.6.16.6.14.3 PLIB_PMP_ChipSelectXPolaritySelect Function C void PLIB_PMP_ChipSelectXPolaritySelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ); Description This function sets the specified Chip Select polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for Chip Select polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ChipXPolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXPolarity in your application to to automatically determine whether this feature is available. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXPolaritySelect( PMP_ID_0, chipSelect, PMP_POLARITY_ACTIVE_HIGH ); 5.6.16.6.14.4 PLIB_PMP_ReadWriteStrobePolaritySelect Function C void PLIB_PMP_ReadWriteStrobePolaritySelect( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ); Description This function sets polarity of the read strobe to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2542 Returns None. Remarks This function implements an operation of the ReadWritePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsReadWritePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ReadWriteStrobePolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); 5.6.16.6.14.5 PLIB_PMP_WriteEnableStrobePolaritySelect Function C void PLIB_PMP_WriteEnableStrobePolaritySelect( PMP_MODULE_ID index, PMP_POLARITY_LEVEL polarity ); Description This function sets the polarity of the write enable strobe to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed polarity Possible polarity levels Returns None. Remarks This function implements an operation of the WriteEnablePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsWriteEnablePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_WriteEnableStrobePolaritySelect( PMP_ID_0, PMP_POLARITY_ACTIVE_HIGH ); 5.6.16.6.15 Enhanced Polarity Configuration Functions 5.6.16.6.15.1 PLIB_PMP_ChipSelectXAckPolaritySelect Function C void PLIB_PMP_ChipSelectXAckPolaritySelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ); Description This function sets the Chip Select acknowledge polarity to the level specified. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2543 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect Identifier for the Chip Select polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ChipXACKPolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXACKPolarity in your application to to automatically determine whether this feature is available. Example PMP_CHIP_SELECT chipSelect = PMP_CHIP_SELECT_ONE; PLIB_PMP_ChipSelectXAckPolaritySelect( PMP_ID_0, chipSelect, PMP_POLARITY_ACTIVE_LOW ); 5.6.16.6.15.2 PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect Function C void PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ); Description This function sets the nibble/byte enable polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ChipXByteEnablePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXByteEnablePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect ( PMP_ID_0, 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2544 PMP_CHIP_SELECT_ONE, PMP_POLARITY_ACTIVE_LOW ); 5.6.16.6.15.3 PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect Function C void PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ); Description This function sets the read/write strobe polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ChipXReadWritePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXReadWritePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_POLARITY_ACTIVE_LOW ); 5.6.16.6.15.4 PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect Function C void PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect( PMP_MODULE_ID index, PMP_CHIP_SELECT chipSelect, PMP_POLARITY_LEVEL polarity ); Description This function sets the write/enable strobe polarity to the level specified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be addressed chipSelect One of the possible values from PMP_CHIP_SELECT 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2545 polarity Possible polarity levels Returns None. Remarks This function implements an operation of the ChipXWriteEnablePolarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PMP_ExistsChipXWriteEnablePolarity in your application to to automatically determine whether this feature is available. Example PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect ( PMP_ID_0, PMP_CHIP_SELECT_ONE, PMP_POLARITY_ACTIVE_LOW ); 5.6.16.6.16 Data Types and Constants 5.6.16.6.16.1 PMP_ACK_MODE Enumeration C typedef enum { PMP_USE_ACK_WITH_TIMEOUT, PMP_USE_ACK, PMP_ACK_DISABLED } PMP_ACK_MODE; Description PMP Acknowledge Modes This data type defines the different configurations by which the PMP can be enabled. Members Members Description PMP_USE_ACK_WITH_TIMEOUT Acknowledge used with a timeout PMP_USE_ACK Acknowledge is used PMP_ACK_DISABLED Acknowledge is not used Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.2 PMP_ADDRESS_HOLD_LATCH_WAIT_STATES Enumeration C typedef enum { PMP_ADDRESS_HOLD_ONE_AND_ONE_QUARTER, PMP_ADDRESS_HOLD_ONE_QUARTER } PMP_ADDRESS_HOLD_LATCH_WAIT_STATES; Description PMP Address Latch Strobe Wait States This data type defines the different configurations by which the PMP holds after address latch strobe wait states can be configured. Refer to the specific device data sheet for the exact clock cycle timing. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2546 Members Members Description PMP_ADDRESS_HOLD_ONE_AND_ONE_QUARTER Data Wait of 1 1/4 Peripheral Bus Clock Cycles PMP_ADDRESS_HOLD_ONE_QUARTER Data Wait of 1/4 Peripheral Bus Clock Cycles Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.3 PMP_ADDRESS_LATCH Enumeration C typedef enum { PMP_ADDRESS_LATCH_UPPER, PMP_ADDRESS_LATCH_HIGH, PMP_ADDRESS_LATCH_LOW } PMP_ADDRESS_LATCH; Description PMP Address Latch This data type defines the different configurations by which the PMP address latch strobes can be configured. Members Members Description PMP_ADDRESS_LATCH_UPPER Address latch upper PMP_ADDRESS_LATCH_HIGH Address latch high PMP_ADDRESS_LATCH_LOW Address latch low Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.4 PMP_ADDRESS_LATCH_WAIT_STATES Enumeration C typedef enum { PMP_ADDRESS_WAIT_THREE_AND_HALF, PMP_ADDRESS_WAIT_TWO_AND_HALF, PMP_ADDRESS_WAIT_ONE_AND_HALF, PMP_ADDRESS_WAIT_HALF } PMP_ADDRESS_LATCH_WAIT_STATES; Description PMP Address Latch Strobe Wait States This data type defines the different configurations by which the PMP address latch strobe wait states can be configured. Refer to the specific device data sheet for the exact clock cycle timing. Members Members Description PMP_ADDRESS_WAIT_THREE_AND_HALF Data Wait of 3 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_TWO_AND_HALF Data Wait of 2 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_ONE_AND_HALF Data Wait of 1 1/2 Peripheral Bus Clock Cycles PMP_ADDRESS_WAIT_HALF Data Wait of 1/2 Peripheral Bus Clock Cycles 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2547 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.5 PMP_ADDRESS_PORT Enumeration C typedef enum { PMP_PMA0_PORT, PMP_PMA1_PORT, PMP_PMA2_TO_PMA13_PORTS, PMP_PMA2_PORT, PMP_PMA3_PORT, PMP_PMA4_PORT, PMP_PMA5_PORT, PMP_PMA6_PORT, PMP_PMA7_PORT, PMP_PMA8_PORT, PMP_PMA9_PORT, PMP_PMA10_PORT, PMP_PMA11_PORT, PMP_PMA12_PORT, PMP_PMA13_PORT, PMP_PMA14_PORT, PMP_PMA15_PORT, PMP_PMA16_TO_PMA22_PORTS } PMP_ADDRESS_PORT; Description PMP Address Port Pins This data type defines the different address that can be configured by the PMP module. The user application can make each pin as a general purpose I/O or part of PMP functionality. Members Members Description PMP_PMA0_PORT Address line 0 port (make as general purpose I/O or PMP address line) PMP_PMA1_PORT Address line 1 port (make as general purpose I/O or PMP address line) PMP_PMA2_TO_PMA13_PORTS Address line 2 to 13 ports (make as general purpose I/O or PMP address lines) PMP_PMA2_PORT Address line 2 port (make as general purpose I/O or PMP address line) PMP_PMA3_PORT Address line 3 port (make as general purpose I/O or PMP address line) PMP_PMA4_PORT Address line 4 port (make as general purpose I/O or PMP address line) PMP_PMA5_PORT Address line 5 port (make as general purpose I/O or PMP address line) PMP_PMA6_PORT Address line 6 port (make as general purpose I/O or PMP address line) PMP_PMA7_PORT Address line 7 port (make as general purpose I/O or PMP address line) PMP_PMA8_PORT Address line 8 port (make as general purpose I/O or PMP address line) PMP_PMA9_PORT Address line 9 port (make as general purpose I/O or PMP address line) PMP_PMA10_PORT Address line 10 port (make as general purpose I/O or PMP address line) PMP_PMA11_PORT Address line 11 port (make as general purpose I/O or PMP address line) PMP_PMA12_PORT Address line 12 port (make as general purpose I/O or PMP address line) PMP_PMA13_PORT Address line 13 port (make as general purpose I/O or PMP address line) PMP_PMA14_PORT Address line 14 port (make as general purpose I/O or PMP address line) PMP_PMA15_PORT Address line 15 port (make as general purpose I/O or PMP address line) PMP_PMA16_TO_PMA22_PORTS Address line 16 to 22 ports (make as general purpose I/O or PMP address lines) 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2548 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). These enumerator values can be passed in a bitwise ORed fashion to select multiple ports at a time. 5.6.16.6.16.6 PMP_ALTERNATE_MASTER_WAIT_STATES Enumeration C typedef enum { PMP_ALTERNATE_MASTER_WAIT_10, PMP_ALTERNATE_MASTER_WAIT_9, PMP_ALTERNATE_MASTER_WAIT_8, PMP_ALTERNATE_MASTER_WAIT_7, PMP_ALTERNATE_MASTER_WAIT_6, PMP_ALTERNATE_MASTER_WAIT_5, PMP_ALTERNATE_MASTER_WAIT_4, PMP_ALTERNATE_MASTER_WAIT_3 } PMP_ALTERNATE_MASTER_WAIT_STATES; Description PMP Alternate Master Wait States This data type defines the different configurations by which the PMP alternate master wait states can be configured. Members Members Description PMP_ALTERNATE_MASTER_WAIT_10 Wait of 10 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_9 Wait of 9 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_8 Wait of 8 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_7 Wait of 7 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_6 Wait of 6 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_5 Wait of 5 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_4 Wait of 4 Alternate Master Cycles PMP_ALTERNATE_MASTER_WAIT_3 Wait of 3 Alternate Master Cycles Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.7 PMP_CHIP_SELECT Enumeration C typedef enum { PMP_CHIP_SELECT_ONE, PMP_CHIP_SELECT_TWO } PMP_CHIP_SELECT; Description PMP Chip Select This data type defines the different Chip Select lines of the PMP module. Members Members Description PMP_CHIP_SELECT_ONE chip selct One 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2549 PMP_CHIP_SELECT_TWO chip selct Two Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.8 PMP_CHIPSELECT_FUNCTION Enumeration C typedef enum { PMCS1_AS_CHIP_SELECT, PMCS1_AS_ADDRESS_LINE, PMCS1_PMCS2_AS_ADDRESS_LINES, PMCS1_AS_ADDRESS_LINE_PMCS2_AS_CHIP_SELECT, PMCS1_AND_PMCS2_AS_CHIP_SELECT } PMP_CHIPSELECT_FUNCTION; Description PMP Chip Select pin functions This data type defines different functions of Chip Select pins. Members Members Description PMCS1_AS_CHIP_SELECT CS1 used as Chip Select PMCS1_AS_ADDRESS_LINE CS1 used as address line PMCS1_PMCS2_AS_ADDRESS_LINES CS1 and CS2 used as address lines PMCS1_AS_ADDRESS_LINE_PMCS2_AS_CHIP_SELECT CS1 used as address line and CS2 as Chip Select PMCS1_AND_PMCS2_AS_CHIP_SELECT Both CS1 and CS2 used as Chip Selects Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.9 PMP_DATA_HOLD_STATES Enumeration C typedef enum { PMP_DATA_HOLD_FOUR, PMP_DATA_HOLD_THREE, PMP_DATA_HOLD_TWO, PMP_DATA_HOLD_ONE } PMP_DATA_HOLD_STATES; Description PMP Data Hold after strobe wait state This data type defines the different data Hold after strobe wait states. Members Members Description PMP_DATA_HOLD_FOUR Data Hold of 4 Peripheral Bus Clock Cycles PMP_DATA_HOLD_THREE Data Hold of 3 Peripheral Bus Clock Cycles PMP_DATA_HOLD_TWO Data Hold of 2 Peripheral Bus Clock Cycles PMP_DATA_HOLD_ONE Data Hold of 1 Peripheral Bus Clock Cycles 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2550 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.10 PMP_DATA_LENGTH Enumeration C typedef enum { PMP_DATA_8_BITS, PMP_DATA_16_BITS, PMP_DATA_32_BITS } PMP_DATA_LENGTH; Description PMP data length This data type defines the possible data lengths handled by the PMP module. Members Members Description PMP_DATA_8_BITS 8-bit data length PMP_DATA_16_BITS 16-bit data length PMP_DATA_32_BITS 32-bit data length Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.11 PMP_DATA_SIZE Enumeration C typedef enum { PMP_DATA_SIZE_SIXTEEN_BITS, PMP_DATA_SIZE_EIGHT_BITS, PMP_DATA_SIZE_FOUR_BITS } PMP_DATA_SIZE; Description PMP DATA Size This data type defines the different configurations for the data lengths handled by the PMP module. Members Members Description PMP_DATA_SIZE_SIXTEEN_BITS Data length of 16-bits PMP_DATA_SIZE_EIGHT_BITS Data length of 8-bits PMP_DATA_SIZE_FOUR_BITS Data length of 4-bits Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.12 PMP_DATA_WAIT_STATES Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2551 PMP_DATA_WAIT_FOUR, PMP_DATA_WAIT_THREE, PMP_DATA_WAIT_TWO, PMP_DATA_WAIT_ONE } PMP_DATA_WAIT_STATES; Description PMP Data setup to read/write/address phase wait state configuration This data type defines the different wait state configurations for setup to read/write/address phase. Members Members Description PMP_DATA_WAIT_FOUR Data Wait of 4 Peripheral Bus Clock Cycles PMP_DATA_WAIT_THREE Data Wait of 3 Peripheral Bus Clock Cycles PMP_DATA_WAIT_TWO Data Wait of 2 Peripheral Bus Clock Cycles PMP_DATA_WAIT_ONE Data Wait of 1 Peripheral Bus Clock Cycles Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.13 PMP_INCREMENT_MODE Enumeration C typedef enum { PMP_BUFFERS_AUTO_INCREMENT, PMP_ADDRESS_AUTO_DECREMENT, PMP_ADDRESS_AUTO_INCREMENT, PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE } PMP_INCREMENT_MODE; Description PMP Increment Modes This data type defines the different configurations by which the PMP address incrementing can be configured. Members Members Description PMP_BUFFERS_AUTO_INCREMENT Read and write buffers auto-increment PMP_ADDRESS_AUTO_DECREMENT Decrement PMP Address by one every read/write cycle PMP_ADDRESS_AUTO_INCREMENT Increment PMP Address by one every read/write cycle PMP_ADDRESS_INCREMENT_DECREMENT_DISABLE PMP Address does not change Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.14 PMP_INPUT_BUFFER_TYPE Enumeration C typedef enum { PMP_INPUT_BUFFER_TTL, PMP_INPUT_BUFFER_SCHMITT } PMP_INPUT_BUFFER_TYPE; 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2552 Description PMP Input Buffers type This data type defines the input buffer types. Members Members Description PMP_INPUT_BUFFER_TTL TTL input buffer PMP_INPUT_BUFFER_SCHMITT schmitt trigger input buffer Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.15 PMP_INTERRUPT_MODE Enumeration C typedef enum { PMP_INTERRUPT_BUFFER_3_IS_ACCESSED, PMP_INTERRUPT_EVERY_RW_CYCLE, PMP_INTERRUPT_NONE } PMP_INTERRUPT_MODE; Description PMP Interrupt Mode This data type defines the different configurations by which the PMP can be configured for interrupt requests. Members Members Description PMP_INTERRUPT_BUFFER_3_IS_ACCESSED Interrupt generated when Read/Write Buffer 3 is read/written PMP_INTERRUPT_EVERY_RW_CYCLE Interupt Occurs Every Read/Write Cycle PMP_INTERRUPT_NONE No interrupt generated Remarks None. 5.6.16.6.16.16 PMP_MASTER_MODE Enumeration C typedef enum { PMP_ALTERNATE_MASTER_DIRECT, PMP_ALTERNATE_MASTER, PMP_CPU_MASTER } PMP_MASTER_MODE; Description PMP Master Modes This data type defines the different configurations by which the PMP can be enabled. Members Members Description PMP_ALTERNATE_MASTER_DIRECT Alternate Master has PMP control with Direct I/O access PMP_ALTERNATE_MASTER Alternate Master has PMP control 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2553 PMP_CPU_MASTER CPU has PMP control Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.17 PMP_MODULE_ID Enumeration C typedef enum { PMP_ID_0 } PMP_MODULE_ID; Description PMP module ID This data type defines the possible instances of the PMP module. Members Members Description PMP_ID_0 first instance of the PMP Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.18 PMP_MUX_MODE Enumeration C typedef enum { PMP_MUX_ADDRESS_PHASES_3, PMP_MUX_ADDRESS_PHASES_2, PMP_MUX_ADDRESS_PHASES_1, PMP_MUX_LINES_16_ADDRESS_16_DATA, PMP_MUX_LINES_16_ADDRESS_8_DATA, PMP_MUX_LINES_8_ADDRESS_8_DATA, PMP_MUX_NONE } PMP_MUX_MODE; Description PMP Multiplex Modes This data type defines the different configurations by which the PMP can be enabled. Members Members Description PMP_MUX_ADDRESS_PHASES_3 Lower address bits are multiplexed with data bits using 3 address phase PMP_MUX_ADDRESS_PHASES_2 Lower address bits are multiplexed with data bits using 2 address phases PMP_MUX_ADDRESS_PHASES_1 Lower address bits are multiplexed with data bits using 1 address phase PMP_MUX_LINES_16_ADDRESS_16_DATA 16 address lines are multiplexed on 16 data lines PMP_MUX_LINES_16_ADDRESS_8_DATA 16 address lines multiplexed on 8 data lines PMP_MUX_LINES_8_ADDRESS_8_DATA 8 bits of address is multiplexed on 8 data lines PMP_MUX_NONE No multiplexing of address and data lines Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2554 5.6.16.6.16.19 PMP_OPERATION_MODE Enumeration C typedef enum { PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED, PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT, PMP_BUFFERED_SLAVE, PMP_ENHANCED_SLAVE, PMP_LEGACY_SLAVE } PMP_OPERATION_MODE; Description PMP Operation Modes This data type defines the different configurations by which the PMP can be enabled. Members Members Description PMP_MASTER_READ_WRITE_STROBES_MULTIPLEXED Master mode 1, the read and the write strobes share a single line. The enable strobe is used to decode the info sent on read/write strobe line PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT Master mode 2, the read and write strobes are on independent lines PMP_BUFFERED_SLAVE Buffered Slave mode PMP_ENHANCED_SLAVE Enhanced Slave mode PMP_LEGACY_SLAVE Legacy Parallel Slave mode Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.16.20 PMP_PMBE_PORT Enumeration C typedef enum { PMBE_0, PMBE_1 } PMP_PMBE_PORT; Description PMP Byte Enable port. This data type defines the available Byte Enable ports. Members Members Description PMBE_0 Byte Enable Port-0 PMBE_1 Byte Enable Port-1 Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2555 5.6.16.6.16.21 PMP_POLARITY_LEVEL Enumeration C typedef enum { PMP_POLARITY_ACTIVE_HIGH, PMP_POLARITY_ACTIVE_LOW } PMP_POLARITY_LEVEL; Description PMP Pins Polarity This data type defines the possible polarity levels for the PMP pins. Members Members Description PMP_POLARITY_ACTIVE_HIGH Active high polarity PMP_POLARITY_ACTIVE_LOW Active low polarity Remarks None. 5.6.16.6.16.22 PMP_STROBE_WAIT_STATES Enumeration C typedef enum { PMP_STROBE_WAIT_FIFTEEN, PMP_STROBE_WAIT_FOURTEEN, PMP_STROBE_WAIT_THIRTEEN, PMP_STROBE_WAIT_TWELVE, PMP_STROBE_WAIT_ELEVEN, PMP_STROBE_WAIT_TEN, PMP_STROBE_WAIT_NINE, PMP_STROBE_WAIT_EIGHT, PMP_STROBE_WAIT_SEVEN, PMP_STROBE_WAIT_SIX, PMP_STROBE_WAIT_FIVE, PMP_STROBE_WAIT_FOUR, PMP_STROBE_WAIT_THREE, PMP_STROBE_WAIT_TWO, PMP_STROBE_WAIT_ONE, PMP_STROBE_WAIT_NONE } PMP_STROBE_WAIT_STATES; Description PMP Read to Byte enable strobe configuration This data type defines the different configurations by which the PMP strobe wait signal time can be configured. Members Members Description PMP_STROBE_WAIT_FIFTEEN Strobe Wait of 15 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FOURTEEN Strobe Wait of 14 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_THIRTEEN Strobe Wait of 13 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TWELVE Strobe Wait of 12 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_ELEVEN Strobe Wait of 11 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TEN Strobe Wait of 10 Peripheral Bus Clock Cycles 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2556 PMP_STROBE_WAIT_NINE Strobe Wait of 9 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_EIGHT Strobe Wait of 8 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_SEVEN Strobe Wait of 7 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_SIX Strobe Wait of 6 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FIVE Strobe Wait of 5 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_FOUR Strobe Wait of 4 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_THREE Strobe Wait of 3 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_TWO Strobe Wait of 2 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_ONE Strobe Wait of 1 Peripheral Bus Clock Cycles PMP_STROBE_WAIT_NONE No wait states Remarks This enumeration is processor specific and is defined in the processor- specific header files (see processor.h). 5.6.16.6.17 Feature Existence Functions 5.6.16.6.17.1 PLIB_PMP_ExistsAddressControl Function C bool PLIB_PMP_ExistsAddressControl( PMP_MODULE_ID index ); Description This interface identifies that the AddressControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AddressSet • PLIB_PMP_AddressLinesA0A1Set • PLIB_PMP_AddressLinesA0A1Get Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressControl feature is supported on the device • false - The AddressControl feature is not supported on the device Remarks None. 5.6.16.6.17.2 PLIB_PMP_ExistsAddressLatchPolarity Function C bool PLIB_PMP_ExistsAddressLatchPolarity( PMP_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2557 ); Description This interface identifies that the AddressLatchPolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_AddressLatchPolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressLatchPolarity feature is supported on the device • false - The AddressLatchPolarity feature is not supported on the device Remarks None. 5.6.16.6.17.3 PLIB_PMP_ExistsAddressLatchStrobePortControl Function C bool PLIB_PMP_ExistsAddressLatchStrobePortControl( PMP_MODULE_ID index ); Description This interface identifies that the AddressLatchStrobePortControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AddressLatchStrobeEnable • PLIB_PMP_AddressLatchStrobeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressLatchStrobePortControl feature is supported on the device • false - The AddressLatchStrobePortControl feature is not supported on the device Remarks None. 5.6.16.6.17.4 PLIB_PMP_ExistsAddressPortPinControl Function C bool PLIB_PMP_ExistsAddressPortPinControl( 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2558 PMP_MODULE_ID index ); Description This interface identifies that the AddressPortPinControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AddressPortEnable • PLIB_PMP_AddressPortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AddressPortPinControl feature is supported on the device • false - The AddressPortPinControl feature is not supported on the device Remarks None. 5.6.16.6.17.5 PLIB_PMP_ExistsAltMasterRequest Function C bool PLIB_PMP_ExistsAltMasterRequest( PMP_MODULE_ID index ); Description This interface identifies that the AltMasterRequest feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AlternateMasterRequestStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AltMasterRequest feature is supported on the device • false - The AltMasterRequest feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2559 5.6.16.6.17.6 PLIB_PMP_ExistsBufferOverFlow Function C bool PLIB_PMP_ExistsBufferOverFlow( PMP_MODULE_ID index ); Description This interface identifies that the BufferOverFlow feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_InputOverflowHasOccurred • PLIB_PMP_InputOverflowClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferOverFlow feature is supported on the device • false - The BufferOverFlow feature is not supported on the device Remarks None. 5.6.16.6.17.7 PLIB_PMP_ExistsBufferRead Function C bool PLIB_PMP_ExistsBufferRead( PMP_MODULE_ID index ); Description This interface identifies that the BufferRead feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_InputBufferXByteReceive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferRead feature is supported on the device • false - The BufferRead feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2560 5.6.16.6.17.8 PLIB_PMP_ExistsBufferType Function C bool PLIB_PMP_ExistsBufferType( PMP_MODULE_ID index ); Description This interface identifies that the BufferType feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_InputBufferTypeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferType feature is supported on the device • false - The BufferType feature is not supported on the device Remarks None. 5.6.16.6.17.9 PLIB_PMP_ExistsBufferUnderFlow Function C bool PLIB_PMP_ExistsBufferUnderFlow( PMP_MODULE_ID index ); Description This interface identifies that the BufferUnderFlow feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_OutputUnderflowHasOccurred • PLIB_PMP_OutputUnderflowClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferUnderFlow feature is supported on the device • false - The BufferUnderFlow feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2561 5.6.16.6.17.10 PLIB_PMP_ExistsBufferWrite Function C bool PLIB_PMP_ExistsBufferWrite( PMP_MODULE_ID index ); Description This interface identifies that the BufferWrite feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_OutputBufferXByteSend Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferWrite feature is supported on the device • false - The BufferWrite feature is not supported on the device Remarks None. 5.6.16.6.17.11 PLIB_PMP_ExistsBusKeeper Function C bool PLIB_PMP_ExistsBusKeeper( PMP_MODULE_ID index ); Description This interface identifies that the BusKeeper feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_BusKeeperEnable • PLIB_PMP_BusKeeperDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BusKeeper feature is supported on the device • false - The BusKeeper feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2562 5.6.16.6.17.12 PLIB_PMP_ExistsBusyStatus Function C bool PLIB_PMP_ExistsBusyStatus( PMP_MODULE_ID index ); Description This interface identifies that the BusyStatus feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_PortIsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BusyStatus feature is supported on the device • false - The BusyStatus feature is not supported on the device Remarks None. 5.6.16.6.17.13 PLIB_PMP_ExistsByteEnablePolarity Function C bool PLIB_PMP_ExistsByteEnablePolarity( PMP_MODULE_ID index ); Description This interface identifies that the ByteEnablePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ByteEnablePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ByteEnablePolarity feature is supported on the device • false - The ByteEnablePolarity feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2563 5.6.16.6.17.14 PLIB_PMP_ExistsByteEnablePortControl Function C bool PLIB_PMP_ExistsByteEnablePortControl( PMP_MODULE_ID index ); Description This interface identifies that the ByteEnablePortControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_ByteEnablePortEnable • PLIB_PMP_ByteEnablePortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ByteEnablePortControl feature is supported on the device • false - The ByteEnablePortControl feature is not supported on the device Remarks None. 5.6.16.6.17.15 PLIB_PMP_ExistsChipSelectEnable Function C bool PLIB_PMP_ExistsChipSelectEnable( PMP_MODULE_ID index ); Description This interface identifies that the ChipSelectEnable feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_ChipSelectXEnable • PLIB_PMP_ChipSelectXDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipSelectEnable feature is supported on the device • false - The ChipSelectEnable feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2564 Remarks None. 5.6.16.6.17.16 PLIB_PMP_ExistsChipSelectoperation Function C bool PLIB_PMP_ExistsChipSelectoperation( PMP_MODULE_ID index ); Description This interface identifies that the ChipSelectoperation feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectFunctionSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipSelectoperation feature is supported on the device • false - The ChipSelectoperation feature is not supported on the device Remarks None. 5.6.16.6.17.17 PLIB_PMP_ExistsChipXACKMode Function C bool PLIB_PMP_ExistsChipXACKMode( PMP_MODULE_ID index ); Description This interface identifies that the ChipXACKMode feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXAckModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXACKMode feature is supported on the device • false - The ChipXACKMode feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2565 Remarks None. 5.6.16.6.17.18 PLIB_PMP_ExistsChipXACKPolarity Function C bool PLIB_PMP_ExistsChipXACKPolarity( PMP_MODULE_ID index ); Description This interface identifies that the ChipXACKPolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXAckPolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXACKPolarity feature is supported on the device • false - The ChipXACKPolarity feature is not supported on the device Remarks None. 5.6.16.6.17.19 PLIB_PMP_ExistsChipXAltMasterWaitStates Function C bool PLIB_PMP_ExistsChipXAltMasterWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the ChipXAltMasterWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXWaitStatesAlternateMasterSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXAltMasterWaitStates feature is supported on the device • false - The ChipXAltMasterWaitStates feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2566 Remarks None. 5.6.16.6.17.20 PLIB_PMP_ExistsChipXBaseAddress Function C bool PLIB_PMP_ExistsChipXBaseAddress( PMP_MODULE_ID index ); Description This interface identifies that the ChipXBaseAddress feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXBaseAddressSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXBaseAddress feature is supported on the device • false - The ChipXBaseAddress feature is not supported on the device Remarks None. 5.6.16.6.17.21 PLIB_PMP_ExistsChipXByteEnablePolarity Function C bool PLIB_PMP_ExistsChipXByteEnablePolarity( PMP_MODULE_ID index ); Description This interface identifies that the ChipXByteEnablePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXByteEnablePolarity feature is supported on the device • false - The ChipXByteEnablePolarity feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2567 Remarks None. 5.6.16.6.17.22 PLIB_PMP_ExistsChipXDataHoldWaitStates Function C bool PLIB_PMP_ExistsChipXDataHoldWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the ChipXDataHoldWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXWaitStatesDataHoldSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXDataHoldWaitStates feature is supported on the device • false - The ChipXDataHoldWaitStates feature is not supported on the device Remarks None. 5.6.16.6.17.23 PLIB_PMP_ExistsChipXDataSetupWaitStates Function C bool PLIB_PMP_ExistsChipXDataSetupWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the ChipXDataSetupWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXWaitStatesDataSetupSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXDataSetupWaitStates feature is supported on the device • false - The ChipXDataSetupWaitStates feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2568 Remarks None. 5.6.16.6.17.24 PLIB_PMP_ExistsChipXDataSize Function C bool PLIB_PMP_ExistsChipXDataSize( PMP_MODULE_ID index ); Description This interface identifies that the ChipXDataSize feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXDataSizeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXDataSize feature is supported on the device • false - The ChipXDataSize feature is not supported on the device Remarks None. 5.6.16.6.17.25 PLIB_PMP_ExistsChipXEnableStorbeSelect Function C bool PLIB_PMP_ExistsChipXEnableStorbeSelect( PMP_MODULE_ID index ); Description This interface identifies that the ChipXEnableStorbeSelect feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_ChipSelectXEnableStrobeSelect • PLIB_PMP_ChipSelectXEnableStrobeDeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXEnableStorbeSelect feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2569 • false - The ChipXEnableStorbeSelect feature is not supported on the device Remarks None. 5.6.16.6.17.26 PLIB_PMP_ExistsChipXPolarity Function C bool PLIB_PMP_ExistsChipXPolarity( PMP_MODULE_ID index ); Description This interface identifies that the ChipXPolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXPolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXPolarity feature is supported on the device • false - The ChipXPolarity feature is not supported on the device Remarks None. 5.6.16.6.17.27 PLIB_PMP_ExistsChipXReadWritePolarity Function C bool PLIB_PMP_ExistsChipXReadWritePolarity( PMP_MODULE_ID index ); Description This interface identifies that the ChipXReadWritePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXReadWritePolarity feature is supported on the device • false - The ChipXReadWritePolarity feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2570 Remarks None. 5.6.16.6.17.28 PLIB_PMP_ExistsChipXStrobeWaitStates Function C bool PLIB_PMP_ExistsChipXStrobeWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the ChipXStrobeWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipXWaitStatesStrobeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXStrobeWaitStates feature is supported on the device • false - The ChipXStrobeWaitStates feature is not supported on the device Remarks None. 5.6.16.6.17.29 PLIB_PMP_ExistsChipXWriteEnablePolarity Function C bool PLIB_PMP_ExistsChipXWriteEnablePolarity( PMP_MODULE_ID index ); Description This interface identifies that the ChipXWriteEnablePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipXWriteEnablePolarity feature is supported on the device • false - The ChipXWriteEnablePolarity feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2571 Remarks None. 5.6.16.6.17.30 PLIB_PMP_ExistsCSXActiveStatus Function C bool PLIB_PMP_ExistsCSXActiveStatus( PMP_MODULE_ID index ); Description This interface identifies that the CSXActiveStatus feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ChipSelectXIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CSXActiveStatus feature is supported on the device • false - The CSXActiveStatus feature is not supported on the device Remarks None. 5.6.16.6.17.31 PLIB_PMP_ExistsCSXPortControl Function C bool PLIB_PMP_ExistsCSXPortControl( PMP_MODULE_ID index ); Description This interface identifies that the CSXPortControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_ChipSelectXPortEnable • PLIB_PMP_ChipSelectXPortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CSXPortControl feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2572 • false - The CSXPortControl feature is not supported on the device Remarks None. 5.6.16.6.17.32 PLIB_PMP_ExistsCurrentMaster Function C bool PLIB_PMP_ExistsCurrentMaster( PMP_MODULE_ID index ); Description This interface identifies that the CurrentMaster feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AlternateMasterHasAccess Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CurrentMaster feature is supported on the device • false - The CurrentMaster feature is not supported on the device Remarks None. 5.6.16.6.17.33 PLIB_PMP_ExistsDataHoldWaitStates Function C bool PLIB_PMP_ExistsDataHoldWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the DataHoldWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_WaitStatesDataHoldSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataHoldWaitStates feature is supported on the device • false - The DataHoldWaitStates feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2573 Remarks None. 5.6.16.6.17.34 PLIB_PMP_ExistsDataSetUpWaitStates Function C bool PLIB_PMP_ExistsDataSetUpWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the DataSetUpWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_WaitStatesDataSetUpSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataSetUpWaitStates feature is supported on the device • false - The DataSetUpWaitStates feature is not supported on the device Remarks None. 5.6.16.6.17.35 PLIB_PMP_ExistsDataStrobeWaitStates Function C bool PLIB_PMP_ExistsDataStrobeWaitStates( PMP_MODULE_ID index ); Description This interface identifies that the DataStrobeWaitStates feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_WaitStatesStrobeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataStrobeWaitStates feature is supported on the device • false - The DataStrobeWaitStates feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2574 Remarks None. 5.6.16.6.17.36 PLIB_PMP_ExistsDataTransferSize Function C bool PLIB_PMP_ExistsDataTransferSize( PMP_MODULE_ID index ); Description This interface identifies that the DataTransferSize feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_DataSizeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataTransferSize feature is supported on the device • false - The DataTransferSize feature is not supported on the device Remarks None. 5.6.16.6.17.37 PLIB_PMP_ExistsEnableControl Function C bool PLIB_PMP_ExistsEnableControl( PMP_MODULE_ID index ); Description This interface identifies that the EnableControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_Disable • PLIB_PMP_Enable • PLIB_PMP_IsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2575 Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.16.6.17.38 PLIB_PMP_ExistsEnhancedMasterMode Function C bool PLIB_PMP_ExistsEnhancedMasterMode( PMP_MODULE_ID index ); Description This interface identifies that the EnhancedMasterMode feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_EnhancedMasterModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnhancedMasterMode feature is supported on the device • false - The EnhancedMasterMode feature is not supported on the device Remarks None. 5.6.16.6.17.39 PLIB_PMP_ExistsIncrementMode Function C bool PLIB_PMP_ExistsIncrementMode( PMP_MODULE_ID index ); Description This interface identifies that the IncrementMode feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_AddressIncrementModeSelect • PLIB_PMP_AddressIncrementModeGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2576 Parameters Parameters Description index Identifier for the device instance Returns • true - The IncrementMode feature is supported on the device • false - The IncrementMode feature is not supported on the device Remarks None. 5.6.16.6.17.40 PLIB_PMP_ExistsInputBufferFull Function C bool PLIB_PMP_ExistsInputBufferFull( PMP_MODULE_ID index ); Description This interface identifies that the InputBufferFull feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_InputBuffersAreFull Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InputBufferFull feature is supported on the device • false - The InputBufferFull feature is not supported on the device Remarks None. 5.6.16.6.17.41 PLIB_PMP_ExistsInputBufferXStatus Function C bool PLIB_PMP_ExistsInputBufferXStatus( PMP_MODULE_ID index ); Description This interface identifies that the InputBufferXStatus feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_InputBufferXIsFull • PLIB_PMP_IsDataReceived 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2577 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InputBufferXStatus feature is supported on the device • false - The InputBufferXStatus feature is not supported on the device Remarks None. 5.6.16.6.17.42 PLIB_PMP_ExistsInterruptMode Function C bool PLIB_PMP_ExistsInterruptMode( PMP_MODULE_ID index ); Description This interface identifies that the InterruptMode feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_InterruptModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InterruptMode feature is supported on the device • false - The InterruptMode feature is not supported on the device Remarks None. 5.6.16.6.17.43 PLIB_PMP_ExistsMasterRXTX Function C bool PLIB_PMP_ExistsMasterRXTX( PMP_MODULE_ID index ); Description This interface identifies that the MasterRXTX feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_MasterSend 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2578 • PLIB_PMP_MasterReceive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MasterRXTX feature is supported on the device • false - The MasterRXTX feature is not supported on the device Remarks None. 5.6.16.6.17.44 PLIB_PMP_ExistsMUXModeSelect Function C bool PLIB_PMP_ExistsMUXModeSelect( PMP_MODULE_ID index ); Description This interface identifies that the MUXModeSelect feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_MultiplexModeSelect • PLIB_PMP_MultiplexModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MUXModeSelect feature is supported on the device • false - The MUXModeSelect feature is not supported on the device Remarks None. 5.6.16.6.17.45 PLIB_PMP_ExistsOperationMode Function C bool PLIB_PMP_ExistsOperationMode( PMP_MODULE_ID index ); Description This interface identifies that the OperationMode feature is available on the PMP module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2579 • PLIB_PMP_OperationModeSelect • PLIB_PMP_OperationModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Remarks None. 5.6.16.6.17.46 PLIB_PMP_ExistsOutPutBufferEmpty Function C bool PLIB_PMP_ExistsOutPutBufferEmpty( PMP_MODULE_ID index ); Description This interface identifies that the OutPutBufferEmpty feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_OutputBuffersAreEmpty Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OutPutBufferEmpty feature is supported on the device • false - The OutPutBufferEmpty feature is not supported on the device Remarks None. 5.6.16.6.17.47 PLIB_PMP_ExistsOutputBufferXStatus Function C bool PLIB_PMP_ExistsOutputBufferXStatus( PMP_MODULE_ID index ); Description This interface identifies that the OutputBufferXStatus feature is available on the PMP module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2580 • PLIB_PMP_OutputBufferXIsEmpty • PLIB_PMP_IsDataTransmitted Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OutputBufferXStatus feature is supported on the device • false - The OutputBufferXStatus feature is not supported on the device Remarks None. 5.6.16.6.17.48 PLIB_PMP_ExistsReadWritePolarity Function C bool PLIB_PMP_ExistsReadWritePolarity( PMP_MODULE_ID index ); Description This interface identifies that the ReadWritePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_ReadWriteStrobePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadWritePolarity feature is supported on the device • false - The ReadWritePolarity feature is not supported on the device Remarks None. 5.6.16.6.17.49 PLIB_PMP_ExistsReadWriteStrobePortControl Function C bool PLIB_PMP_ExistsReadWriteStrobePortControl( PMP_MODULE_ID index ); Description This interface identifies that the ReadWriteStrobePortControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2581 • PLIB_PMP_ReadWriteStrobePortEnable • PLIB_PMP_ReadWriteStrobePortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadWriteStrobePortControl feature is supported on the device • false - The ReadWriteStrobePortControl feature is not supported on the device Remarks None. 5.6.16.6.17.50 PLIB_PMP_ExistsReservedAddrSpace Function C bool PLIB_PMP_ExistsReservedAddrSpace( PMP_MODULE_ID index ); Description This interface identifies that the ReservedAddrSpace feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_ReservedAddressSpaceBitsSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReservedAddrSpace feature is supported on the device • false - The ReservedAddrSpace feature is not supported on the device Remarks None. 5.6.16.6.17.51 PLIB_PMP_ExistsSlaveRX Function C bool PLIB_PMP_ExistsSlaveRX( PMP_MODULE_ID index ); Description This interface identifies that the SlaveRX feature is available on the PMP module. When this interface returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2582 • PLIB_PMP_SlaveReceive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SlaveRX feature is supported on the device • false - The SlaveRX feature is not supported on the device Remarks None. 5.6.16.6.17.52 PLIB_PMP_ExistsSlaveTX Function C bool PLIB_PMP_ExistsSlaveTX( PMP_MODULE_ID index ); Description This interface identifies that the SlaveTX feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_SlaveSend Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SlaveTX feature is supported on the device • false - The SlaveTX feature is not supported on the device Remarks None. 5.6.16.6.17.53 PLIB_PMP_ExistsSmartAddress Function C bool PLIB_PMP_ExistsSmartAddress( PMP_MODULE_ID index ); Description This interface identifies that the SmartAddress feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_SmartAddressStrobeEnable 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2583 • PLIB_PMP_SmartAddressStrobeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SmartAddress feature is supported on the device • false - The SmartAddress feature is not supported on the device Remarks None. 5.6.16.6.17.54 PLIB_PMP_ExistsStopInIdleControl Function C bool PLIB_PMP_ExistsStopInIdleControl( PMP_MODULE_ID index ); Description This interface identifies that the StopInIdleControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_StopInIdleEnable • PLIB_PMP_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdleControl feature is supported on the device • false - The StopInIdleControl feature is not supported on the device Remarks None. 5.6.16.6.17.55 PLIB_PMP_ExistsTransactionError Function C bool PLIB_PMP_ExistsTransactionError( PMP_MODULE_ID index ); Description This interface identifies that the TransactionError feature is available on the PMP module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2584 • PLIB_PMP_TransactionErrorHasOccurred • PLIB_PMP_TransactionErrorClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransactionError feature is supported on the device • false - The TransactionError feature is not supported on the device Remarks None. 5.6.16.6.17.56 PLIB_PMP_ExistsTransactionTimeOut Function C bool PLIB_PMP_ExistsTransactionTimeOut( PMP_MODULE_ID index ); Description This interface identifies that the TransactionTimeOut feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_TransactionHasTimedOut • PLIB_PMP_TransactionTimeoutClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransactionTimeOut feature is supported on the device • false - The TransactionTimeOut feature is not supported on the device Remarks None. 5.6.16.6.17.57 PLIB_PMP_ExistsWaitStatesAddrHoldStrobe Function C bool PLIB_PMP_ExistsWaitStatesAddrHoldStrobe( PMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2585 Description This interface identifies that the WaitStatesAddrHoldStrobe feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_WaitStatesAddressHoldStrobeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WaitStatesAddrHoldStrobe feature is supported on the device • false - The WaitStatesAddrHoldStrobe feature is not supported on the device Remarks None. 5.6.16.6.17.58 PLIB_PMP_ExistsWaitStatesAddrLatchStrobe Function C bool PLIB_PMP_ExistsWaitStatesAddrLatchStrobe( PMP_MODULE_ID index ); Description This interface identifies that the WaitStatesAddrLatchStrobe feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_WaitStatesAddressLatchStrobeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WaitStatesAddrLatchStrobe feature is supported on the device • false - The WaitStatesAddrLatchStrobe feature is not supported on the device Remarks None. 5.6.16.6.17.59 PLIB_PMP_ExistsWriteEnablePolarity Function C bool PLIB_PMP_ExistsWriteEnablePolarity( PMP_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2586 Description This interface identifies that the WriteEnablePolarity feature is available on the PMP module. When this interface returns true, this function is supported on the device: • PLIB_PMP_WriteEnableStrobePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteEnablePolarity feature is supported on the device • false - The WriteEnablePolarity feature is not supported on the device Remarks None. 5.6.16.6.17.60 PLIB_PMP_ExistsWriteEnablePortControl Function C bool PLIB_PMP_ExistsWriteEnablePortControl( PMP_MODULE_ID index ); Description This interface identifies that the WriteEnablePortControl feature is available on the PMP module. When this interface returns true, these functions are supported on the device: • PLIB_PMP_WriteEnableStrobePortEnable • PLIB_PMP_WriteEnableStrobePortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteEnablePortControl feature is supported on the device • false - The WriteEnablePortControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2587 5.6.16.7 Files Files Name Description plib_pmp.h Parallel Master Port (PMP) Peripheral Library Interface Header. Description 5.6.16.7.1 plib_pmp.h This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the PMP Peripheral Library. Functions Name Description PLIB_PMP_AddressGet Gets the current address of the PMP module. PLIB_PMP_AddressIncrementModeGet Gets the increment mode being used with the address of the PMP module. PLIB_PMP_AddressIncrementModeSelect Configures the increment mode being used with the address of the PMP module. PLIB_PMP_AddressLatchPolaritySelect Sets the address latch strobe polarity. PLIB_PMP_AddressLatchStrobeDisable Disables the specific address latch strobe. PLIB_PMP_AddressLatchStrobeEnable Enables the specific address latch strobe. PLIB_PMP_AddressLinesA0A1Get Gets the value of the address lines PMA0 and PMA1. PLIB_PMP_AddressLinesA0A1Set Sets the address lines PMA0 and PMA1 with the value specified. PLIB_PMP_AddressPortDisable Disables the port lines specified as PMP address lines. PLIB_PMP_AddressPortEnable Enables the port lines specified as PMP address lines. PLIB_PMP_AddressSet Sets the current address of the PMP module to the specified address. PLIB_PMP_AlternateMasterHasAccess Gets the status of which alternate masters have gained access to the PMP module. PLIB_PMP_AlternateMasterRequestStatus Gets the status of the request from the alternate master. PLIB_PMP_BusKeeperDisable Disables the bus keeper (high-impedance) state. PLIB_PMP_BusKeeperEnable Enables the bus keeper (high-impedance) state. PLIB_PMP_ByteEnablePolaritySelect Sets the byte enable polarity. PLIB_PMP_ByteEnablePortDisable Disables the byte enable port. PLIB_PMP_ByteEnablePortEnable Enables the byte enable port. PLIB_PMP_ChipSelectFunctionSelect Defines the functionality of the pins intended to be used as Chip Select. PLIB_PMP_ChipSelectXAckPolaritySelect Sets the Chip Select acknowledge polarity. PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect Sets the nibble/byte enable polarity. PLIB_PMP_ChipSelectXDisable Configures the Chip Select. PLIB_PMP_ChipSelectXEnable Configures the Chip Select. PLIB_PMP_ChipSelectXEnableStrobeDeSelect Selects the read and write strobes. The enable strobe is not selected (not required). 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2588 PLIB_PMP_ChipSelectXEnableStrobeSelect Selects the read/write and enable strobes. PLIB_PMP_ChipSelectXIsActive Gets the current status of the specified Chip Select. PLIB_PMP_ChipSelectXPolaritySelect Sets the specified Chip Select polarity. PLIB_PMP_ChipSelectXPortDisable Disables the specified Chip Select's port. PLIB_PMP_ChipSelectXPortEnable Enables the specified Chip Select's port. PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect Sets the read/write strobe polarity. PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect Sets the write/enable strobe polarity. PLIB_PMP_ChipXAckModeSelect Selects the acknowledge mode for the PMP module. PLIB_PMP_ChipXBaseAddressSet Sets the base address of the specified device. PLIB_PMP_ChipXDataSizeSelect Enables data transfer size for the PMP for the specified device. PLIB_PMP_ChipXWaitStatesAlternateMasterSelect Selects the wait states of the alternate master for Chip Select-X. PLIB_PMP_ChipXWaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_ChipXWaitStatesDataSetupSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_ChipXWaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module for the specified device. PLIB_PMP_DataSizeSelect Enables data transfer size for the PMP module. PLIB_PMP_Disable Disables the specific PMP module. PLIB_PMP_Enable Enables the specific PMP module. PLIB_PMP_EnhancedMasterModeSelect Selects Master mode for the PMP module. PLIB_PMP_ExistsAddressControl Identifies that the AddressControl feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchPolarity Identifies that the AddressLatchPolarity feature exists on the PMP module. PLIB_PMP_ExistsAddressLatchStrobePortControl Identifies that the AddressLatchStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsAddressPortPinControl Identifies that the AddressPortPinControl feature exists on the PMP module. PLIB_PMP_ExistsAltMasterRequest Identifies that the AltMasterRequest feature exists on the PMP module. PLIB_PMP_ExistsBufferOverFlow Identifies that the BufferOverFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferRead Identifies that the BufferRead feature exists on the PMP module. PLIB_PMP_ExistsBufferType Identifies that the BufferType feature exists on the PMP module. PLIB_PMP_ExistsBufferUnderFlow Identifies that the BufferUnderFlow feature exists on the PMP module. PLIB_PMP_ExistsBufferWrite Identifies that the BufferWrite feature exists on the PMP module. PLIB_PMP_ExistsBusKeeper Identifies that the BusKeeper feature exists on the PMP module. PLIB_PMP_ExistsBusyStatus Identifies that the BusyStatus feature exists on the PMP module. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2589 PLIB_PMP_ExistsByteEnablePolarity Identifies that the ByteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsByteEnablePortControl Identifies that the ByteEnablePortControl feature exists on the PMP module. PLIB_PMP_ExistsChipSelectEnable Identifies that the ChipSelectEnable feature exists on the PMP module. PLIB_PMP_ExistsChipSelectoperation Identifies that the ChipSelectoperation feature exists on the PMP module. PLIB_PMP_ExistsChipXACKMode Identifies that the ChipXACKMode feature exists on the PMP module. PLIB_PMP_ExistsChipXACKPolarity Identifies that the ChipXACKPolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXAltMasterWaitStates Identifies that the ChipXAltMasterWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXBaseAddress Identifies that the ChipXBaseAddress feature exists on the PMP module. PLIB_PMP_ExistsChipXByteEnablePolarity Identifies that the ChipXByteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXDataHoldWaitStates Identifies that the ChipXDataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXDataSetupWaitStates Identifies that the ChipXDataSetupWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXDataSize Identifies that the ChipXDataSize feature exists on the PMP module. PLIB_PMP_ExistsChipXEnableStorbeSelect Identifies that the ChipXEnableStorbeSelect feature exists on the PMP module. PLIB_PMP_ExistsChipXPolarity Identifies that the ChipXPolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXReadWritePolarity Identifies that the ChipXReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsChipXStrobeWaitStates Identifies that the ChipXStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsChipXWriteEnablePolarity Identifies that the ChipXWriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsCSXActiveStatus Identifies that the CSXActiveStatus feature exists on the PMP module. PLIB_PMP_ExistsCSXPortControl Identifies that the CSXPortControl feature exists on the PMP module. PLIB_PMP_ExistsCurrentMaster Identifies that the CurrentMaster feature exists on the PMP module. PLIB_PMP_ExistsDataHoldWaitStates Identifies that the DataHoldWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataSetUpWaitStates Identifies that the DataSetUpWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataStrobeWaitStates Identifies that the DataStrobeWaitStates feature exists on the PMP module. PLIB_PMP_ExistsDataTransferSize Identifies that the DataTransferSize feature exists on the PMP module. PLIB_PMP_ExistsEnableControl Identifies that the EnableControl feature exists on the PMP module. PLIB_PMP_ExistsEnhancedMasterMode Identifies that the EnhancedMasterMode feature exists on the PMP module. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2590 PLIB_PMP_ExistsIncrementMode Identifies that the IncrementMode feature exists on the PMP module. PLIB_PMP_ExistsInputBufferFull Identifies that the InputBufferFull feature exists on the PMP module. PLIB_PMP_ExistsInputBufferXStatus Identifies that the InputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsInterruptMode Identifies that the InterruptMode feature exists on the PMP module. PLIB_PMP_ExistsMasterRXTX Identifies that the MasterRXTX feature exists on the PMP module. PLIB_PMP_ExistsMUXModeSelect Identifies that the MUXModeSelect feature exists on the PMP module. PLIB_PMP_ExistsOperationMode Identifies that the OperationMode feature exists on the PMP module. PLIB_PMP_ExistsOutPutBufferEmpty Identifies that the OutPutBufferEmpty feature exists on the PMP module. PLIB_PMP_ExistsOutputBufferXStatus Identifies that the OutputBufferXStatus feature exists on the PMP module. PLIB_PMP_ExistsReadWritePolarity Identifies that the ReadWritePolarity feature exists on the PMP module. PLIB_PMP_ExistsReadWriteStrobePortControl Identifies that the ReadWriteStrobePortControl feature exists on the PMP module. PLIB_PMP_ExistsReservedAddrSpace Identifies that the ReservedAddrSpace feature exists on the PMP module. PLIB_PMP_ExistsSlaveRX Identifies that the SlaveRX feature exists on the PMP module. PLIB_PMP_ExistsSlaveTX Identifies that the SlaveTX feature exists on the PMP module. PLIB_PMP_ExistsSmartAddress Identifies that the SmartAddress feature exists on the PMP module. PLIB_PMP_ExistsStopInIdleControl Identifies that the StopInIdleControl feature exists on the PMP module. PLIB_PMP_ExistsTransactionError Identifies that the TransactionError feature exists on the PMP module. PLIB_PMP_ExistsTransactionTimeOut Identifies that the TransactionTimeOut feature exists on the PMP module. PLIB_PMP_ExistsWaitStatesAddrHoldStrobe Identifies that the WaitStatesAddrHoldStrobe feature exists on the PMP module. PLIB_PMP_ExistsWaitStatesAddrLatchStrobe Identifies that the WaitStatesAddrLatchStrobe feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePolarity Identifies that the WriteEnablePolarity feature exists on the PMP module. PLIB_PMP_ExistsWriteEnablePortControl Identifies that the WriteEnablePortControl feature exists on the PMP module. PLIB_PMP_InputBuffersAreFull Gets the state of the input buffers. PLIB_PMP_InputBufferTypeSelect Selects the input buffer based on the input passed. PLIB_PMP_InputBufferXByteReceive Data to be received in Byte mode. PLIB_PMP_InputBufferXIsFull Gets the state of the identified input buffer. PLIB_PMP_InputOverflowClear Clears a PMP Overflow error. PLIB_PMP_InputOverflowHasOccurred Identifies if there was a receiver overflow error. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2591 PLIB_PMP_InterruptModeGet Gets the current configured interrupt mode being used with the PMP module. PLIB_PMP_InterruptModeSelect Configures the interrupt request mode being used with the PMP module. PLIB_PMP_IsDataReceived Checks and returns if the data has been received in the specified buffer in Slave mode. PLIB_PMP_IsDataTransmitted Checks and returns if the data has been transmitted from the specified buffer in Slave mode. PLIB_PMP_IsEnabled Checks whether or not the PMP module is enabled. PLIB_PMP_MasterReceive Receives the data in the master mode. PLIB_PMP_MasterSend Sends the specified data in Master mode. PLIB_PMP_MultiplexModeGet Gets the current multiplexing mode configured between the address and data of the PMP module. PLIB_PMP_MultiplexModeSelect Configures the multiplexing between the address and data of the PMP module. PLIB_PMP_OperationModeGet Gets the current operation mode of the PMP module. PLIB_PMP_OperationModeSelect Configures the operation mode of the PMP module. PLIB_PMP_OutputBuffersAreEmpty Gets the state of the output buffers. PLIB_PMP_OutputBufferXByteSend Data to be transmitted in Byte mode. PLIB_PMP_OutputBufferXIsEmpty Gets the state of the input buffer. PLIB_PMP_OutputUnderflowClear Clears a PMP output underflow error. PLIB_PMP_OutputUnderflowHasOccurred Identifies if there was an output buffer sent out with no data. PLIB_PMP_PortIsBusy Identifies if the (Master mode) PMP port is busy. PLIB_PMP_ReadWriteStrobePolaritySelect Sets the polarity of the read strobe. PLIB_PMP_ReadWriteStrobePortDisable Disables the PMP module read strobe port. PLIB_PMP_ReadWriteStrobePortEnable Enables the PMP module read strobe port. PLIB_PMP_ReservedAddressSpaceBitsSet Sets the address bits of the reserved address space of the EPMP. The end address of the Chip Select-2 (if present). PLIB_PMP_SlaveReceive Receives the data in Slave mode. PLIB_PMP_SlaveSend Sends the specified data in Slave mode. PLIB_PMP_SmartAddressStrobeDisable Disables "smart" address strobes. PLIB_PMP_SmartAddressStrobeEnable Enables "smart" address strobes. PLIB_PMP_StopInIdleDisable Enables the PMP module to continue operation in Idle mode. PLIB_PMP_StopInIdleEnable Discontinues PMP module operation when the device enters Idle mode. PLIB_PMP_TransactionErrorClear Clears the transaction error flag. PLIB_PMP_TransactionErrorHasOccurred Returns the status of a transaction error. PLIB_PMP_TransactionHasTimedOut Returns the time-out status. PLIB_PMP_TransactionTimeoutClear Clears the time-out flag. PLIB_PMP_WaitStatesAddressHoldStrobeSelect Configures the address wait states needed to be used with the PMP module. PLIB_PMP_WaitStatesAddressLatchStrobeSelect Configures the address wait states needed to be used with the PMP module. PLIB_PMP_WaitStatesDataHoldSelect Configures the data hold states (after data transfer) needed to be used with the PMP module. 5.6 Peripheral Library Help MPLAB Harmony Help PMP Peripheral Library 5-2592 PLIB_PMP_WaitStatesDataSetUpSelect Configures the data wait states (before the data transfer) needed to be used with the PMP module. PLIB_PMP_WaitStatesStrobeSelect Configures the strobe wait states (during the data transfer) needed to be used with the PMP module. PLIB_PMP_WriteEnableStrobePolaritySelect Sets the polarity of the write enable strobe. PLIB_PMP_WriteEnableStrobePortDisable Disables the PMP module write strobe port. PLIB_PMP_WriteEnableStrobePortEnable Enables the PMP module write strobe port. File Name plib_pmp.h Company Microchip Technology Inc. 5.6.17 Ports Peripheral Library 5.6.17.1 Introduction This library provides a low-level abstraction of the I/O Ports module on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Ports Peripheral Library for Microchip Microcontrollers I/O Ports Overview The general purpose I/O pins can be considered the simplest of peripherals. These I/O pins allow the microcontroller to monitor and control other devices. To add flexibility and functionality to a device, some pins are multiplexed with alternate function(s). These functions depend on which peripheral features are on the device. In general, when a peripheral is functioning, that pin may not be used as a general purpose I/O pin. A major challenge in general purpose devices is providing the largest possible set of peripheral features while minimizing the conflict of features on I/O pins. The Peripheral Pin Select (PPS) feature simplifies this challenge by enabling the user’s peripheral set selection and their placement on a wide range of I/O pins. By increasing the pin out options available on a particular device, users can better tailor the microcontroller to their entire application.The PPS feature operates over a fixed subset of digital I/O 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2593 pins. Users may independently map the input and/or output of any one of many digital peripherals to any one of these I/O pins. PPS is performed in software and generally does not require the device to be reprogrammed. Hardware safeguards are included that prevent accidental or spurious changes to the peripheral mapping once it has been established. Note: Peripheral Pin Select is not available on all devices. Please refer to the specific device data sheet to determine availability of this feature. Following are some of the key features of the I/O Ports module: • Individual output pin/port open-drain control • Individual input pin/port pull-up/down control • Monitor select inputs and generate interrupt on mismatch condition (Change Notification) • Operation during CPU Sleep and Idle modes • Port line analog/digital selection • Port slew rate control • PPS peripheral function remapping 5.6.17.2 Release Notes MPLAB Harmony Version: v0.70b Ports Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: None to report at this time. 5.6.17.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2594 5.6.17.4 Using the Library This topic describes the basic architecture of the Ports Peripheral Library and provides information and examples on how to use it. Description Interface Header File: plib_ports.h The interface to the Ports Peripheral Library is defined in the "plib_ports.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Ports Peripheral Library must include "peripheral.h". Library File: The Ports Peripheral Library is part of the processor-specific peripheral library installed with the compiler. This library is automatically available (in the default search path) for any project built using the Microchip compilers. 5.6.17.4.1 Hardware Abstraction Model This topic provides detailed information for general purpose I/O and pin mapping. Description General Purpose I/O All port pins have three controls directly associated with their operation as digital I/O. The data direction control determines whether the pin is an input or an output. All port pins are defined as inputs after a Reset. Writes to a port are latched and, if programmed as an output, driven by a buffer to the pin. The value of pin can be read directly from an input buffer, (after it has been synchronized to the clock), regardless of whether the pin direction has been selected as input or output. Additionally, the value being driven by the latch before the output buffer, can also be read. Internal pull-up resistors are available on selected port pins to eliminate the need to use external pull-up resistors. These pull-ups can be controlled by this library. The open-drain feature allows the generation of outputs higher than VDD on any desired digital-only pins by using external pull-up resistors. Note: For detailed specifications on the maximum allowed open-drain voltage, refer to the "Electrical Characteristics" chapter in the specific device data sheet. The input change notification feature of the I/O ports allows the microcontrollers to generate interrupt requests to the processor in response to a change of state on selected input pins. This feature is capable of detecting input change of states even in Sleep mode, when the clocks are disabled. The alternate pin function selections are used to steer specific peripheral input and output functions between different pins. The output slew rate of some port pins are programmable to select either the standard transition rate or a reduced transition rate of 'x' times the standard to minimize EMI. Peripheral Pin Select 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2595 In addition to general purpose IO control, this library also provides a low-level abstraction of the PPS module on Microchip microcontrollers with a convenient C language interface. Available Pins The number of available pins is dependent on the particular device and its pin count. Pins that support the PPS feature include the designation 'RPn' or 'RPIn' in their full pin designation, where 'RP' designates a remappable peripheral and 'n' is the remappable pin number. RP is used to designate pins that support both remappable input and output functions, while RPI indicates pins that only support remappable input functions. Available Peripherals The peripherals managed by PPS are all digital-only peripherals. These include general serial communications (UART and SPI), general purpose timer clock inputs, timer-related peripherals (Input Capture and Output Compare), comparator digital output, interrupt-on-change inputs, etc. In comparison, some digital-only peripheral modules are never included in the peripheral pin select feature. This is because the peripheral’s function requires special I/O circuitry on a specific port and cannot be easily connected to multiple pins. These modules include I2C, among others. A similar requirement excludes all modules with analog inputs, such as the Analog-to-Digital Converter (ADC). If multiple peripherals are enabled on the same pin(s), there is an internal priority that decides which function is mapped to the pin. When a remappable peripheral is active on a given I/O pin, it takes priority over all other digital I/O and digital communication peripherals associated with the pin. Priority is given regardless of the type of peripheral that is mapped. Remappable peripherals never take priority over any analog functions associated with the pin. In other words, If an analog function is enabled on the pin, the PPS input will be disabled. Input Mapping The inputs of the peripheral pin select options are mapped on the basis of the peripheral. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2596 Output Mapping In contrast to inputs, the outputs of the peripheral pin select options are mapped on the basis of the pin. In this case, a control associated with a particular pin dictates the peripheral output to be mapped. Mapping Limitations The control schema of the peripheral select pins is not limited to a small range of fixed peripheral configurations. There are no mutual-exclusion or hardware-enforced lockouts between any of the peripheral mapping SFRs. Literally any combination of peripheral mappings across any or all of the RPn pins is possible. This includes both many-to-one and one-to-many mappings of peripheral inputs and outputs to pins. While such mappings may be technically possible from a configuration point of view, they may not be supportable from an electrical point of view and may cause damage to the part. Note 1: For detailed specifications on the mapping limitations, refer to the "I/O Ports" chapter in the specific device data sheet. Note 2: Regrading pin priorities, the priority of the pins are assigned from left to right, left being the highest priority and the right most being the least priority. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2597 5.6.17.4.2 Library Overview The Ports Peripheral Library supports the following set of interface routines: Library Interface Section Description Port Functions Port access read/write/toggle/clear interfaces with 8-/16-/32-bit widths based on the selected device. Port Pin Functions Port bit/pin read/write/toggle/clear interfaces. Change Notification Functions Port change notification. Peripheral Pin Select Functions Interface routines for mapping the digital input/output to a specific the PPS remappable input/output pin. 5.6.17.4.3 How the Library Works How the Library Works The following topics discuss the processes involved while using a Ports module: • Ports Control • Ports Function Remap • Ports Change Notification • Special Considerations 5.6.17.4.3.1 Ports Control Port Functions Usage: • Port Read - Ports can be read at byte/word level using PLIB_PORTS_Read, and at the bit/pin level using PLIB_PORTS_PinGet • Port Write - Ports can be written to at byte/word level using PLIB_PORTS_Write and at the bit/pin level using PLIB_PORTS_PinWrite. The function PLIB_PORTS_PinSet can be used to set a specific bit/pin of a port. A mask-based PORTx write can be accomplished using the function PLIB_PORTS_Set with the appropriate mask as a parameter along with the value. • Port Clear - Ports can be cleared at byte/word level using PLIB_PORTS_Clear with appropriate mask as a parameter and at the bit/pin level using PLIB_PORTS_PinClear • Port Direction - The ports read direction can be set at byte/word level using PLIB_PORTS_DirectionInputSet and at the bit/pin level using PLIB_PORTS_PinDirectionInputSet. Similarly, the ports write direction can be set at the byte/word level using PLIB_PORTS_DirectionOutputSet and at the bit/pin level using PLIB_PORTS_PinDirectionOutputSet. The direction information can be read using PLIB_PORTS_DirectionGet. • Port Toggle - Ports can be toggled at the byte/word level using PLIB_PORTS_Toggle with the appropriate mask as a parameter and at the bit/pin level using PLIB_PORTS_PinToggle • Port Open Drain - Ports can be enabled for open-drain functionality at the byte/word level using the interface PLIB_PORTS_OpenDrainEnable and at the bit/pin level using PLIB_PORTS_PinOpenDrainEnable. Similarly, the ports can be disabled for open-drain functionality at the byte/word level using PLIB_PORTS_OpenDrainDisable and at the bit/pin level using PLIB_PORTS_PinOpenDrainDisable. • Port Pull-up - Ports can be enabled for pull-up functionality at the byte/word level using PLIB_PORTS_PullUpEnable and at the bit/pin level using PLIB_PORTS_PinPullUpEnable. Similarly, the ports can be disabled for pull-up functionality at the byte/word level using the interface PLIB_PORTS_PullUpDisable and at the bit/pin level using PLIB_PORTS_PinPullUpDisable. Example: 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2598 // PORT Direction setting for output PLIB_PORTS_DirectionOutputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // Writing a value into a PORT PLID_PORTS_Write(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_TYPE)0x1234); // PORT Direction setting for input PLIB_PORTS_DirectionInputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // Reading back the previously written value PORTS_DATA_TYPE readData = PLIB_PORTS_Read(MY_PORTS_INSTANCE, MY_CHANNEL); // Clearing the PORT PLIB_PORTS_Clear(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); // Writing the value based on the mask, only 0x34 gets written to the PORT PLIB_PORTS_Set(MY_PORTS_INSTANCE, MY_CHANNEL, 0x1234, (PORTS_DATA_MASK)0x00FF); // Toggling a PORT PLIB_PORTS_Toggle(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); Note: In certain devices, disabling pull-ups will enable the pull-down feature and vice-versa. For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the related family reference manual section. 5.6.17.4.3.2 Ports Function Remap Using the PPS Feature: 1. Ensure that any fixed digital peripherals on the pins to be used are disabled. 2. Ensure that pins with analog functionality are set to Digital mode. 3. Check if the Input/Output lock is active using PLIB_PORTS_IOLockIsActive. 4. Enable writing to the Input/Output control register using PLIB_PORTS_IOLockDisable. 5. Remap the input and/or output pins using the internal PPS module. This can be achieved with the function PLIB_PORTS_RemapInputOutput with the respective parameters defined in the processor specific headers. 6. Lock the Input/Output control register using PLIB_PORTS_IOLockEnable. 7. Configure and enable newly mapped PPS peripherals. Example: // Remapping input function 'Input Capture 1' to the Remappable input pin 'RPI1' PLIB_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, PORTS_REMAP_FUNCTION_IC1, PORTS_REMAP_PIN_RPI1); // Remapping output function 'UART1 Transmit' to the Remappable output pin 'RP3' PLIB_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, PORTS_REMAP_FUNCTION_U1TX, PORTS_REMAP_PIN_RP3); Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the related family reference manual section. 5.6.17.4.3.3 Ports Change Notification Change Notification Feature Usage 1. Ensure that the change notify pin is configured as a digital input by setting the associated bit in the direction register using the PLIB_PORTS_PinDirectionInputSet or PLIB_PORTS_DirectionInputSet functions. 2. Select the desired change notification pin using PLIB_PORTS_PinChangeNoticeEnable. 3. Turn on the weak pull-up devices (if desired) for the selected change notification pins using PLIB_PORTS_ChangeNoticePullUpEnable (weak pull-ups can be disabled using PLIB_PORTS_ChangeNoticePullUpDisable). 4. Clear the selected change notification interrupt flag. 5. Select the desired interrupt priority for change notification pin. 6. Enable change notification interrupts. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2599 7. Change notification can be disabled after the successful usage using PLIB_PORTS_PinChangeNoticeDisable. Certain microcontrollers support the global control over the change notification feature using the following functions: PLIB_PORTS_ChangeNoticeEnable and PLIB_PORTS_ChangeNoticeDisable. If there are any requirements to control the pull-downs, the following two functions could be used: PLIB_PORTS_ChangeNoticePullDownEnable and PLIB_PORTS_ChangeNoticePullDownDisable. Change Notification Operation in Sleep and Idle Modes The change notification feature continues to operate during Sleep or Idle mode. Its operation can be enabled or disabled using PLIB_PORTS_ChangeNoticeInIdleEnable or PLIB_PORTS_ChangeNoticeInIdleDisable. If one of the enabled change notification pins changes states, the respective status bit will be set, which can be monitored using PLIB_PORTS_ChangeNoticeHasOccured. Example: // Enabling the global change notification PLIB_PORTS_ChangeNoticeEnable(MY_PORTS_INSTANCE); // Enabling weak pull-ups for the change notification PIN 10 PLIB_PORTS_ChangeNoticePullUpEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); // Enabling change notification on PIN 10 PLIB_PORTS_GLobalChangeNoticeEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the related family reference manual section. 5.6.17.4.3.4 Special Considerations Considerations on Ports Usage When reading a port register, all pins configured as analog input channels will read as cleared. Pins configured as digital inputs will not operate correctly with analog peripherals. Analog levels on any pin that is defined as a digital input may cause the input buffer of analog peripherals to consume current that exceeds the device specifications. Pull-ups and pull-downs on change notification pins should always be disabled when the port pin is configured as a digital output. One instruction cycle is required between a port direction change or port write operation and a read operation of the same port. Typically, this instruction would be a NOP. Considerations for PPS The ability to control PPS options introduces several considerations into application design that could be overlooked. This is particularly true for several common peripherals that are available only as remappable peripherals. The main consideration is that the peripheral pin selects are not available on default pins in the device’s default (i.e., Reset) state, all PPS inputs are tied to VSS and all PPS outputs are disconnected. This condition requires the user to initialize the device with the proper peripheral configuration before any other application code is executed. For application safety, however, it is best to lock the configuration after writing to the PPS control. The assignment of a peripheral signal to a particular pin does not automatically perform any other configuration of the pin’s I/O circuitry. In theory, this means adding a pin-selectable output to a pin may mean inadvertently driving an existing peripheral input when the output is driven. Users must be familiar with the behavior of other fixed peripherals that share a remappable pin and know when to enable or disable them. To be safe, fixed digital peripherals that share the same pin should be disabled when not in use. In addition, configuring a remappable pin for a specific peripheral does not automatically turn on that feature. The peripheral must be specifically configured for operation and enabled, as if it were tied to a fixed pin. Where this occurs in the application code (immediately following a device Reset and peripheral configuration or inside the main application routine) depends on the peripheral and its use in the application. A final consideration is that PPS functions neither override analog inputs, nor reconfigure pins with analog functions for digital I/O. If a pin is configured as an analog input on a device Reset, it must be explicitly reconfigured as a digital I/O when used with 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2600 PPS. Note: For more information, refer to the "I/O Ports" chapter in the specific device data sheet or the related family reference manual section. 5.6.17.5 Configuring the Library The library is configured for the supported Ports module when the supported processor is chosen in the MPLAB IDE. 5.6.17.6 Library Interface Data Types and Constants Name Description PORTS_ANALOG_PIN Data type defining the different Analog input pins PORTS_BIT_POS Lists the constants whic holds different bit positions of PORTS. PORTS_CHANGE_NOTICE_PIN Data type defining the different Change Notification Pins enumeration PORTS_CHANNEL Identifies the PORT Channels Supported. PORTS_DATA_MASK Data type defining the PORTS data mask PORTS_DATA_TYPE Data type defining the PORTS data type. PORTS_MODULE_ID Identifies the PORT Modules Supported. PORTS_PERIPHERAL_OD Data type defining the different Peripherals available for Open drain Configuration PORTS_PIN Data type defining the different PORTS IO Pins enumeration PORTS_PIN_MODE Identifies the ports pin mode PORTS_REMAP_FUNCTION Data type defining the different remap function enumeration PORTS_REMAP_INPUT_FUNCTION Data type defining the different remap input function enumeration. PORTS_REMAP_INPUT_PIN Data type defining the different Ports I/O input pins enumeration. PORTS_REMAP_OUTPUT_FUNCTION Data type defining the different remap output function enumeration. PORTS_REMAP_OUTPUT_PIN Data type defining the different Ports I/O output pins enumeration. PORTS_REMAP_PIN Data type defining the different remappable input/output enumeration Change Notification Functions Name Description PLIB_PORTS_ChangeNoticeDisable Global Change Notice disable. PLIB_PORTS_ChangeNoticeEnable Global Change Notice enable. PLIB_PORTS_ChangeNoticeInIdleDisable CPU Idle does not affect Change Notice operation. PLIB_PORTS_ChangeNoticeInIdleEnable CPU Idle mode halts Change Notice operation. PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortHasOccured Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortTurnOff Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortTurnOn Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullDownPerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullDownPerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullUpDisable Disable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpEnable Enable pull-up on input change. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2601 PLIB_PORTS_ChangeNoticePullUpPerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullUpPerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_PinChangeNoticeDisable Port pin Change Notice disable. PLIB_PORTS_PinChangeNoticeEnable Port pin Change Notice enable. PLIB_PORTS_PinChangeNoticePerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_PinChangeNoticePerPortEnable Enables the selected pin as analog or digital. Feature Existence Functions Name Description PLIB_PORTS_ExistsChangeNotice Identifies whether the ChangeNotice feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticeInIdle Identifies whether the ChangeNoticeInIdle feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortInIdle Identifies whether the ChangeNoticeInIdlePerPort feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortStatus Identifies whether the ChangeNoticePerPortStatus feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Identifies whether the ChangeNoticePerPortTurnOn feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullDownPerPort Identifies whether the ChangeNoticePullDownPerPort feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullUp Identifies whether the ChangeNoticePullup feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullUpPerPort Identifies whether the ChangeNoticePullUpPerPort feature exists on the PORTS module PLIB_PORTS_ExistsPinChangeNotice Identifies whether the PinChangeNotice feature exists on the PORTS module PLIB_PORTS_ExistsPinChangeNoticePerPort Identifies whether the PinChangeNoticePerPort feature exists on the PORTS module PLIB_PORTS_ExistsPinMode Identifies whether the PinMode feature exists on the PORTS module PLIB_PORTS_ExistsPinModePerPort Identifies whether the PinModePerPort feature exists on the PORTS module PLIB_PORTS_ExistsPortsDirection Identifies whether the PortsDirection feature exists on the PORTS module PLIB_PORTS_ExistsPortsOpenDrain Identifies whether the PortsOpenDrain feature exists on the PORTS module PLIB_PORTS_ExistsPortsRead Identifies whether the PortsRead feature exists on the PORTS module PLIB_PORTS_ExistsPortsWrite Identifies whether the PortsWrite feature exists on the PORTS module PLIB_PORTS_ExistsRemapInput Identifies whether the RemapInput feature exists on the PORTS module PLIB_PORTS_ExistsRemapOutput Identifies whether the RemapOutput feature exists on the PORTS module Peripheral Pin Select Functions Name Description PLIB_PORTS_RemapInput Input/Output (I/O) function remapping. PLIB_PORTS_RemapOutput Input/Output (I/O) function remapping. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2602 Port Functions Name Description PLIB_PORTS_Clear Clears the selected digital port/latch. PLIB_PORTS_DirectionGet Reads the direction of the selected digital port. PLIB_PORTS_DirectionInputSet Enables the read (input) direction for the selected port. PLIB_PORTS_DirectionOutputSet Enables the write (output) direction for the selected port. PLIB_PORTS_PinOpenDrainDisable Disables the open drain functionality for the selected pin. PLIB_PORTS_PinOpenDrainEnable Enables the open drain functionality for the selected pin. PLIB_PORTS_Read Reads the selected digital port. PLIB_PORTS_Set Writes the selected digital port/latch based on the mask. PLIB_PORTS_Toggle Toggles the selected digital port/latch. PLIB_PORTS_Write Writes the selected digital port/latch. PLIB_PORTS_OpenDrainDisable Disables the open drain functionality for the selected port. PLIB_PORTS_OpenDrainEnable Enables the open drain functionality for the selected port. Port Pin Functions Name Description PLIB_PORTS_PinClear Clears the selected digital pin/latch. PLIB_PORTS_PinDirectionInputSet Enables the read (input) direction for the selected pin. PLIB_PORTS_PinDirectionOutputSet Enables the write (output) direction for the selected pin. PLIB_PORTS_PinGet Reads/Gets data from the selected digital pin. PLIB_PORTS_PinModeSelect Enables the selected pin as analog or digital. PLIB_PORTS_PinSet Sets the selected digital pin/latch. PLIB_PORTS_PinToggle Toggles the selected digital pin/latch. PLIB_PORTS_PinWrite Writes the selected digital pin/latch. PLIB_PORTS_PinModePerPortSelect Enables the selected pin as analog or digital. Description This section lists the interface routines, data types, constants, and macros required for the Ports Peripheral Library. 5.6.17.6.1 Port Pin Functions 5.6.17.6.1.1 PLIB_PORTS_PinClear Function C void PLIB_PORTS_PinClear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function clears the selected digital pin/latch. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2603 Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinClear(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.2 PLIB_PORTS_PinDirectionInputSet Function C void PLIB_PORTS_PinDirectionInputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the read (input) direction for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinDirectionInputSet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2604 5.6.17.6.1.3 PLIB_PORTS_PinDirectionOutputSet Function C void PLIB_PORTS_PinDirectionOutputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the write (output) direction for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinDirectionOutputSet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.4 PLIB_PORTS_PinGet Function C bool PLIB_PORTS_PinGet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function reads/gets data from the selected digital pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2605 Returns Port pin read data. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsRead in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 bool bitStatus = PLIB_PORTS_PinGet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.5 PLIB_PORTS_PinModeSelect Function C void PLIB_PORTS_PinModeSelect( PORTS_MODULE_ID index, PORTS_ANALOG_PIN pin, PORTS_PIN_MODE mode ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pin Possible values of PORTS_ANALOG_PIN mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.1.6 PLIB_PORTS_PinSet Function C void PLIB_PORTS_PinSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2606 Description This function sets the selected digital pin/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinSet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.7 PLIB_PORTS_PinToggle Function C void PLIB_PORTS_PinToggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function toggles the selected digital pin/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2607 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinToggle(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.8 PLIB_PORTS_PinWrite Function C void PLIB_PORTS_PinWrite( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, bool value ); Description This function writes to the selected digital pin/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS value Value to be written to the specific pin/latch true sets the bit, false - clears the bit Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinWrite(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.1.9 PLIB_PORTS_PinModePerPortSelect Function C void PLIB_PORTS_PinModePerPortSelect( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, PORTS_PIN_MODE mode ); Description This function enables the selected pin as analog or digital. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2608 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.2 Port Functions 5.6.17.6.2.1 PLIB_PORTS_Clear Function C void PLIB_PORTS_Clear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK clearMask ); Description This function clears the selected digital port/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. clearMask Identifies the bits to be cleared Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2609 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK clearMask = (PORTS_DATA_MASK)0x00FF; PLIB_PORTS_Clear(MY_PORTS_INSTANCE, MY_CHANNEL, clearMask); 5.6.17.6.2.2 PLIB_PORTS_DirectionGet Function C PORTS_DATA_MASK PLIB_PORTS_DirectionGet( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function reads the direction of the selected digital port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. Returns Direction of the selected port of type PORTS_DATA_MASK Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK readDir = PLIB_PORTS_DirectionGet(MY_PORTS_INSTANCE, MY_CHANNEL); 5.6.17.6.2.3 PLIB_PORTS_DirectionInputSet Function C void PLIB_PORTS_DirectionInputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function enables the read (input) direction for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2610 channel Identifier for the PORTS channel A, B, C, etc. mask mask for the direction of width PORTS_DATA_MASK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_DirectionInputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); 5.6.17.6.2.4 PLIB_PORTS_DirectionOutputSet Function C void PLIB_PORTS_DirectionOutputSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function enables the write (output) direction for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. mask mask for the direction of width PORTS_DATA_MASK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsDirection in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_DirectionOutputSet(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); 5.6.17.6.2.5 PLIB_PORTS_PinOpenDrainDisable Function C void PLIB_PORTS_PinOpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2611 Description This function disables the open drain functionality for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinOpenDrainDisable(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.2.6 PLIB_PORTS_PinOpenDrainEnable Function C void PLIB_PORTS_PinOpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the open drain functionality for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2612 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 PLIB_PORTS_PinOpenDrainEnable(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.6.17.6.2.7 PLIB_PORTS_Read Function C PORTS_DATA_TYPE PLIB_PORTS_Read( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function reads from the selected digital port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. Returns data on a port with width PORTS_DATA_TYPE Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsRead in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_TYPE readData = PLIB_PORTS_Read(MY_PORTS_INSTANCE, MY_CHANNEL); 5.6.17.6.2.8 PLIB_PORTS_Set Function C void PLIB_PORTS_Set( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value, PORTS_DATA_MASK mask ); Description This function writes to the selected digital port/latch relative to the mask. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2613 channel Identifier for the PORTS channel A, B, C, etc. value Value to be written into a port of width PORTS_DATA_TYPE mask Identifies the bits to be written to Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_VALUE - 0x1234 PORTS_DATA_MASK myMask = (PORTS_DATA_MASK)0x00FF; PLIB_PORTS_Set(MY_PORTS_INSTANCE, MY_CHANNEL, MY_VALUE, myMask); 5.6.17.6.2.9 PLIB_PORTS_Toggle Function C void PLIB_PORTS_Toggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK toggleMask ); Description This function toggles the selected digital port/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. toggleMask Identifies the bits to be toggled Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK toggleMask = (PORTS_DATA_MASK)0x00FF; PLIB_PORTS_Toggle(MY_PORTS_INSTANCE, MY_CHANNEL, toggleMask); 5.6.17.6.2.10 PLIB_PORTS_Write Function C void PLIB_PORTS_Write( 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2614 PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value ); Description This function writes to the selected digital port/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. value Value to be written into a port of width PORTS_DATA_TYPE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsWrite in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_VALUE - 0x1234 PLID_PORTS_Write(MY_PORTS_INSTANCE, MY_CHANNEL, MY_VALUE); 5.6.17.6.2.11 PLIB_PORTS_OpenDrainDisable Function C void PLIB_PORTS_OpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function disables the open drain functionality for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. mask mask of type PORTS_DATA_MASK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2615 PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_OpenDrainDisable(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); 5.6.17.6.2.12 PLIB_PORTS_OpenDrainEnable Function C void PLIB_PORTS_OpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function enables the open drain functionality for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORTS channel A, B, C, etc. mask mask of type PORTS_DATA_MASK Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPortsOpenDrain in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_OpenDrainEnable(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); 5.6.17.6.3 Peripheral Pin Select Functions 5.6.17.6.3.1 PLIB_PORTS_RemapInput Function C void PLIB_PORTS_RemapInput( PORTS_MODULE_ID index, PORTS_REMAP_INPUT_FUNCTION function, PORTS_REMAP_INPUT_PIN remapPin ); Description This function controls the I/O function remapping. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2616 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // Remapping input function 'Input Capture 1' to the Remappable pin 'RPD2' PLIB_PORTS_RemapInput(MY_PORTS_INSTANCE, INPUT_FUNC_IC1, INPUT_PIN_RPD2 ); 5.6.17.6.3.2 PLIB_PORTS_RemapOutput Function C void PLIB_PORTS_RemapOutput( PORTS_MODULE_ID index, PORTS_REMAP_OUTPUT_FUNCTION function, PORTS_REMAP_OUTPUT_PIN remapPin ); Description This function controls the I/O function remapping. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // Remapping output function 'UART3 Transmit' to the Remappable pin 'RPA14' PLIB_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, OTPUT_FUNC_U3TX, OUTPUT_PIN_RPA14); 5.6.17.6.4 Change Notification Functions 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2617 5.6.17.6.4.1 PLIB_PORTS_ChangeNoticeDisable Function C void PLIB_PORTS_ChangeNoticeDisable( PORTS_MODULE_ID index ); Description This function disables the global Change Notice feature. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNotice in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_ChangeNoticeDisable(MY_PORTS_INSTANCE); 5.6.17.6.4.2 PLIB_PORTS_ChangeNoticeEnable Function C void PLIB_PORTS_ChangeNoticeEnable( PORTS_MODULE_ID index ); Description This function enables the global Change Notice feature. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNotice in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2618 // application developer. PLIB_PORTS_ChangeNoticeEnable(MY_PORTS_INSTANCE); 5.6.17.6.4.3 PLIB_PORTS_ChangeNoticeInIdleDisable Function C void PLIB_PORTS_ChangeNoticeInIdleDisable( PORTS_MODULE_ID index ); Description This function allows change notice operation to continue upon CPU Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeInIdle in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_ChangeNoticeInIdleDisable(MY_PORTS_INSTANCE); 5.6.17.6.4.4 PLIB_PORTS_ChangeNoticeInIdleEnable Function C void PLIB_PORTS_ChangeNoticeInIdleEnable( PORTS_MODULE_ID index ); Description This function halts Change Notice operation on CPU Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticeInIdle in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2619 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PLIB_PORTS_ChangeNoticeInIdleEnable(MY_PORTS_INSTANCE); 5.6.17.6.4.5 PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Function C void PLIB_PORTS_ChangeNoticeInIdlePerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.6 PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Function C void PLIB_PORTS_ChangeNoticeInIdlePerPortEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function enables the selected pin as analog or digital. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2620 Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.7 PLIB_PORTS_ChangeNoticePerPortHasOccured Function C bool PLIB_PORTS_ChangeNoticePerPortHasOccured( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2621 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.8 PLIB_PORTS_ChangeNoticePerPortTurnOff Function C void PLIB_PORTS_ChangeNoticePerPortTurnOff( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.9 PLIB_PORTS_ChangeNoticePerPortTurnOn Function C void PLIB_PORTS_ChangeNoticePerPortTurnOn( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2622 bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.10 PLIB_PORTS_ChangeNoticePullDownPerPortDisable Function C void PLIB_PORTS_ChangeNoticePullDownPerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2623 5.6.17.6.4.11 PLIB_PORTS_ChangeNoticePullDownPerPortEnable Function C void PLIB_PORTS_ChangeNoticePullDownPerPortEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.12 PLIB_PORTS_ChangeNoticePullUpDisable Function C void PLIB_PORTS_ChangeNoticePullUpDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function disables pull-up on input change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2624 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 PLIB_PORTS_ChangeNoticePullUpDisable(MY_PORTS_INSTANCE, MY_PINNUM); 5.6.17.6.4.13 PLIB_PORTS_ChangeNoticePullUpEnable Function C void PLIB_PORTS_ChangeNoticePullUpEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function enables pull-up on input change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsChangeNoticePullUp in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 PLIB_PORTS_ChangeNoticePullUpEnable(MY_PORTS_INSTANCE, MY_PINNUM); 5.6.17.6.4.14 PLIB_PORTS_ChangeNoticePullUpPerPortDisable Function C void PLIB_PORTS_ChangeNoticePullUpPerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2625 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.15 PLIB_PORTS_ChangeNoticePullUpPerPortEnable Function C void PLIB_PORTS_ChangeNoticePullUpPerPortEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2626 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.16 PLIB_PORTS_PinChangeNoticeDisable Function C void PLIB_PORTS_PinChangeNoticeDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function disables the port pin Change Notice feature. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 PLIB_PORTS_PinChangeNoticeDisable(MY_PORTS_INSTANCE, MY_PINNUM); 5.6.17.6.4.17 PLIB_PORTS_PinChangeNoticeEnable Function C void PLIB_PORTS_PinChangeNoticeEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function enables the port pin Change Notice feature. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2627 pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinChangeNotice in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 PLIB_PORTS_PinChangeNoticeEnable(MY_PORTS_INSTANCE, MY_PINNUM); 5.6.17.6.4.18 PLIB_PORTS_PinChangeNoticePerPortDisable Function C void PLIB_PORTS_PinChangeNoticePerPortDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.4.19 PLIB_PORTS_PinChangeNoticePerPortEnable Function C void PLIB_PORTS_PinChangeNoticePerPortEnable( PORTS_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2628 PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Port pin channel bitPos Position in the PORT pins mode Possible values of PORTS_PIN_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_PORTS_ExistsPinMode in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG PLIB_PORTS_PinModeSelect(MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE); 5.6.17.6.5 Data Types and Constants 5.6.17.6.5.1 PORTS_ANALOG_PIN Enumeration C typedef enum { PORTS_ANALOG_PIN_0, PORTS_ANALOG_PIN_1, PORTS_ANALOG_PIN_2, PORTS_ANALOG_PIN_3, PORTS_ANALOG_PIN_4, PORTS_ANALOG_PIN_5, PORTS_ANALOG_PIN_6, PORTS_ANALOG_PIN_7, PORTS_ANALOG_PIN_8, PORTS_ANALOG_PIN_9, PORTS_ANALOG_PIN_10, PORTS_ANALOG_PIN_11, PORTS_ANALOG_PIN_12, PORTS_ANALOG_PIN_13, PORTS_ANALOG_PIN_14, PORTS_ANALOG_PIN_15, PORTS_ANALOG_PIN_16, PORTS_ANALOG_PIN_17, PORTS_ANALOG_PIN_18, PORTS_ANALOG_PIN_19, PORTS_ANALOG_PIN_20, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2629 PORTS_ANALOG_PIN_21, PORTS_ANALOG_PIN_22, PORTS_ANALOG_PIN_23, PORTS_ANALOG_PIN_24, PORTS_ANALOG_PIN_25, PORTS_ANALOG_PIN_26, PORTS_ANALOG_PIN_27, PORTS_ANALOG_PIN_28, PORTS_ANALOG_PIN_29, PORTS_ANALOG_PIN_30, PORTS_ANALOG_PIN_31, PORTS_ANALOG_PINS_ALL } PORTS_ANALOG_PIN; Description PORTS Analog input pins This data type defines the different Analog input pins Members Members Description PORTS_ANALOG_PIN_0 Analog Input Pin 0 PORTS_ANALOG_PIN_1 Analog Input Pin 1 PORTS_ANALOG_PIN_2 Analog Input Pin 2 PORTS_ANALOG_PIN_3 Analog Input Pin 3 PORTS_ANALOG_PIN_4 Analog Input Pin 4 PORTS_ANALOG_PIN_5 Analog Input Pin 5 PORTS_ANALOG_PIN_6 Analog Input Pin 6 PORTS_ANALOG_PIN_7 Analog Input Pin 7 PORTS_ANALOG_PIN_8 Analog Input Pin 8 PORTS_ANALOG_PIN_9 Analog Input Pin 9 PORTS_ANALOG_PIN_10 Analog Input Pin 10 PORTS_ANALOG_PIN_11 Analog Input Pin 11 PORTS_ANALOG_PIN_12 Analog Input Pin 12 PORTS_ANALOG_PIN_13 Analog Input Pin 13 PORTS_ANALOG_PIN_14 Analog Input Pin 14 PORTS_ANALOG_PIN_15 Analog Input Pin 15 PORTS_ANALOG_PIN_16 Analog Input Pin 16 PORTS_ANALOG_PIN_17 Analog Input Pin 17 PORTS_ANALOG_PIN_18 Analog Input Pin 18 PORTS_ANALOG_PIN_19 Analog Input Pin 19 PORTS_ANALOG_PIN_20 Analog Input Pin 20 PORTS_ANALOG_PIN_21 Analog Input Pin 21 PORTS_ANALOG_PIN_22 Analog Input Pin 22 PORTS_ANALOG_PIN_23 Analog Input Pin 23 PORTS_ANALOG_PIN_24 Analog Input Pin 8 PORTS_ANALOG_PIN_25 Analog Input Pin 9 PORTS_ANALOG_PIN_26 Analog Input Pin 10 PORTS_ANALOG_PIN_27 Analog Input Pin 11 PORTS_ANALOG_PIN_28 Analog Input Pin 12 PORTS_ANALOG_PIN_29 Analog Input Pin 13 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2630 PORTS_ANALOG_PIN_30 Analog Input Pin 14 PORTS_ANALOG_PIN_31 Analog Input Pin 15 PORTS_ANALOG_PINS_ALL All Analog Pins Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.17.6.5.2 PORTS_BIT_POS Enumeration C typedef enum { PORTS_BIT_POS_0, PORTS_BIT_POS_1, PORTS_BIT_POS_2, PORTS_BIT_POS_3, PORTS_BIT_POS_4, PORTS_BIT_POS_5, PORTS_BIT_POS_6, PORTS_BIT_POS_7, PORTS_BIT_POS_8, PORTS_BIT_POS_9, PORTS_BIT_POS_10, PORTS_BIT_POS_11, PORTS_BIT_POS_12, PORTS_BIT_POS_13, PORTS_BIT_POS_14, PORTS_BIT_POS_15 } PORTS_BIT_POS; Description PORTS bit positions Lists the constants whic holds different bit positions of PORTS. Members Members Description PORTS_BIT_POS_0 PORT bit position 0 PORTS_BIT_POS_1 PORT bit position 1 PORTS_BIT_POS_2 PORT bit position 2 PORTS_BIT_POS_3 PORT bit position 3 PORTS_BIT_POS_4 PORT bit position 4 PORTS_BIT_POS_5 PORT bit position 5 PORTS_BIT_POS_6 PORT bit position 6 PORTS_BIT_POS_7 PORT bit position 7 PORTS_BIT_POS_8 PORT bit position 8 PORTS_BIT_POS_9 PORT bit position 9 PORTS_BIT_POS_10 PORT bit position 10 PORTS_BIT_POS_11 PORT bit position 11 PORTS_BIT_POS_12 PORT bit position 12 PORTS_BIT_POS_13 PORT bit position 13 PORTS_BIT_POS_14 PORT bit position 14 PORTS_BIT_POS_15 PORT bit position 15 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2631 Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. 5.6.17.6.5.3 PORTS_CHANGE_NOTICE_PIN Enumeration C typedef enum { PORTS_CHANGE_NOTICE_PIN_0, PORTS_CHANGE_NOTICE_PIN_1, PORTS_CHANGE_NOTICE_PIN_2, PORTS_CHANGE_NOTICE_PIN_3, PORTS_CHANGE_NOTICE_PIN_4, PORTS_CHANGE_NOTICE_PIN_5, PORTS_CHANGE_NOTICE_PIN_6, PORTS_CHANGE_NOTICE_PIN_7, PORTS_CHANGE_NOTICE_PIN_8, PORTS_CHANGE_NOTICE_PIN_9, PORTS_CHANGE_NOTICE_PIN_10, PORTS_CHANGE_NOTICE_PIN_11, PORTS_CHANGE_NOTICE_PIN_12, PORTS_CHANGE_NOTICE_PIN_13, PORTS_CHANGE_NOTICE_PIN_14, PORTS_CHANGE_NOTICE_PIN_15, PORTS_CHANGE_NOTICE_PIN_16, PORTS_CHANGE_NOTICE_PIN_17, PORTS_CHANGE_NOTICE_PIN_18, PORTS_CHANGE_NOTICE_PIN_19, PORTS_CHANGE_NOTICE_PIN_20, PORTS_CHANGE_NOTICE_PIN_21, PORTS_CHANGE_NOTICE_PIN_22, PORTS_CHANGE_NOTICE_PIN_23, PORTS_CHANGE_NOTICE_PIN_24, PORTS_CHANGE_NOTICE_PIN_25, PORTS_CHANGE_NOTICE_PIN_26, PORTS_CHANGE_NOTICE_PIN_27, PORTS_CHANGE_NOTICE_PIN_28, PORTS_CHANGE_NOTICE_PIN_29, PORTS_CHANGE_NOTICE_PIN_30, PORTS_CHANGE_NOTICE_PIN_31, PORTS_CHANGE_NOTICE_PIN_32, PORTS_CHANGE_NOTICE_PIN_33, PORTS_CHANGE_NOTICE_PIN_34, PORTS_CHANGE_NOTICE_PIN_35, PORTS_CHANGE_NOTICE_PIN_36, PORTS_CHANGE_NOTICE_PIN_37, PORTS_CHANGE_NOTICE_PIN_38, PORTS_CHANGE_NOTICE_PIN_39, PORTS_CHANGE_NOTICE_PIN_40, PORTS_CHANGE_NOTICE_PIN_41, PORTS_CHANGE_NOTICE_PIN_42, PORTS_CHANGE_NOTICE_PIN_43, PORTS_CHANGE_NOTICE_PIN_44, PORTS_CHANGE_NOTICE_PIN_45, PORTS_CHANGE_NOTICE_PIN_46, PORTS_CHANGE_NOTICE_PIN_47, PORTS_CHANGE_NOTICE_PIN_48, PORTS_CHANGE_NOTICE_PIN_49, PORTS_CHANGE_NOTICE_PIN_50, PORTS_CHANGE_NOTICE_PIN_51, PORTS_CHANGE_NOTICE_PIN_52, PORTS_CHANGE_NOTICE_PIN_53, PORTS_CHANGE_NOTICE_PIN_54, PORTS_CHANGE_NOTICE_PIN_55, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2632 PORTS_CHANGE_NOTICE_PIN_56, PORTS_CHANGE_NOTICE_PIN_57, PORTS_CHANGE_NOTICE_PIN_58, PORTS_CHANGE_NOTICE_PIN_59, PORTS_CHANGE_NOTICE_PIN_60, PORTS_CHANGE_NOTICE_PIN_61, PORTS_CHANGE_NOTICE_PIN_62, PORTS_CHANGE_NOTICE_PIN_63, PORTS_CHANGE_NOTICE_PIN_64, PORTS_CHANGE_NOTICE_PIN_65, PORTS_CHANGE_NOTICE_PIN_66, PORTS_CHANGE_NOTICE_PIN_67, PORTS_CHANGE_NOTICE_PIN_68, PORTS_CHANGE_NOTICE_PIN_69, PORTS_CHANGE_NOTICE_PIN_70, PORTS_CHANGE_NOTICE_PIN_71, PORTS_CHANGE_NOTICE_PIN_72, PORTS_CHANGE_NOTICE_PIN_73, PORTS_CHANGE_NOTICE_PIN_74, PORTS_CHANGE_NOTICE_PIN_75, PORTS_CHANGE_NOTICE_PIN_76, PORTS_CHANGE_NOTICE_PIN_77, PORTS_CHANGE_NOTICE_PIN_78, PORTS_CHANGE_NOTICE_PIN_79, PORTS_CHANGE_NOTICE_PIN_80, PORTS_CHANGE_NOTICE_PIN_81, PORTS_CHANGE_NOTICE_PIN_82, PORTS_CHANGE_NOTICE_PIN_83, PORTS_CHANGE_NOTICE_PIN_84 } PORTS_CHANGE_NOTICE_PIN; Description Change Notification Pins enumeration This data type defines the different Change Notification Pins enumeration Members Members Description PORTS_CHANGE_NOTICE_PIN_0 Change Notification Pin 0 PORTS_CHANGE_NOTICE_PIN_1 Change Notification Pin 1 PORTS_CHANGE_NOTICE_PIN_2 Change Notification Pin 2 PORTS_CHANGE_NOTICE_PIN_3 Change Notification Pin 3 PORTS_CHANGE_NOTICE_PIN_4 Change Notification Pin 4 PORTS_CHANGE_NOTICE_PIN_5 Change Notification Pin 5 PORTS_CHANGE_NOTICE_PIN_6 Change Notification Pin 6 PORTS_CHANGE_NOTICE_PIN_7 Change Notification Pin 7 PORTS_CHANGE_NOTICE_PIN_8 Change Notification Pin 8 PORTS_CHANGE_NOTICE_PIN_9 Change Notification Pin 9 PORTS_CHANGE_NOTICE_PIN_10 Change Notification Pin 10 PORTS_CHANGE_NOTICE_PIN_11 Change Notification Pin 11 PORTS_CHANGE_NOTICE_PIN_12 Change Notification Pin 12 PORTS_CHANGE_NOTICE_PIN_13 Change Notification Pin 13 PORTS_CHANGE_NOTICE_PIN_14 Change Notification Pin 14 PORTS_CHANGE_NOTICE_PIN_15 Change Notification Pin 15 PORTS_CHANGE_NOTICE_PIN_16 Change Notification Pin 16 PORTS_CHANGE_NOTICE_PIN_17 Change Notification Pin 17 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2633 PORTS_CHANGE_NOTICE_PIN_18 Change Notification Pin 18 PORTS_CHANGE_NOTICE_PIN_19 Change Notification Pin 19 PORTS_CHANGE_NOTICE_PIN_20 Change Notification Pin 20 PORTS_CHANGE_NOTICE_PIN_21 Change Notification Pin 21 PORTS_CHANGE_NOTICE_PIN_22 Change Notification Pin 22 PORTS_CHANGE_NOTICE_PIN_23 Change Notification Pin 23 PORTS_CHANGE_NOTICE_PIN_24 Change Notification Pin 24 PORTS_CHANGE_NOTICE_PIN_25 Change Notification Pin 25 PORTS_CHANGE_NOTICE_PIN_26 Change Notification Pin 26 PORTS_CHANGE_NOTICE_PIN_27 Change Notification Pin 27 PORTS_CHANGE_NOTICE_PIN_28 Change Notification Pin 28 PORTS_CHANGE_NOTICE_PIN_29 Change Notification Pin 29 PORTS_CHANGE_NOTICE_PIN_30 Change Notification Pin 30 PORTS_CHANGE_NOTICE_PIN_31 Change Notification Pin 31 PORTS_CHANGE_NOTICE_PIN_32 Change Notification Pin 32 PORTS_CHANGE_NOTICE_PIN_33 Change Notification Pin 33 PORTS_CHANGE_NOTICE_PIN_34 Change Notification Pin 34 PORTS_CHANGE_NOTICE_PIN_35 Change Notification Pin 35 PORTS_CHANGE_NOTICE_PIN_36 Change Notification Pin 36 PORTS_CHANGE_NOTICE_PIN_37 Change Notification Pin 37 PORTS_CHANGE_NOTICE_PIN_38 Change Notification Pin 38 PORTS_CHANGE_NOTICE_PIN_39 Change Notification Pin 39 PORTS_CHANGE_NOTICE_PIN_40 Change Notification Pin 40 PORTS_CHANGE_NOTICE_PIN_41 Change Notification Pin 41 PORTS_CHANGE_NOTICE_PIN_42 Change Notification Pin 42 PORTS_CHANGE_NOTICE_PIN_43 Change Notification Pin 43 PORTS_CHANGE_NOTICE_PIN_44 Change Notification Pin 44 PORTS_CHANGE_NOTICE_PIN_45 Change Notification Pin 45 PORTS_CHANGE_NOTICE_PIN_46 Change Notification Pin 46 PORTS_CHANGE_NOTICE_PIN_47 Change Notification Pin 47 PORTS_CHANGE_NOTICE_PIN_48 Change Notification Pin 48 PORTS_CHANGE_NOTICE_PIN_49 Change Notification Pin 49 PORTS_CHANGE_NOTICE_PIN_50 Change Notification Pin 50 PORTS_CHANGE_NOTICE_PIN_51 Change Notification Pin 51 PORTS_CHANGE_NOTICE_PIN_52 Change Notification Pin 52 PORTS_CHANGE_NOTICE_PIN_53 Change Notification Pin 53 PORTS_CHANGE_NOTICE_PIN_54 Change Notification Pin 54 PORTS_CHANGE_NOTICE_PIN_55 Change Notification Pin 55 PORTS_CHANGE_NOTICE_PIN_56 Change Notification Pin 56 PORTS_CHANGE_NOTICE_PIN_57 Change Notification Pin 57 PORTS_CHANGE_NOTICE_PIN_58 Change Notification Pin 58 PORTS_CHANGE_NOTICE_PIN_59 Change Notification Pin 59 PORTS_CHANGE_NOTICE_PIN_60 Change Notification Pin 60 PORTS_CHANGE_NOTICE_PIN_61 Change Notification Pin 61 PORTS_CHANGE_NOTICE_PIN_62 Change Notification Pin 62 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2634 PORTS_CHANGE_NOTICE_PIN_63 Change Notification Pin 63 PORTS_CHANGE_NOTICE_PIN_64 Change Notification Pin 64 PORTS_CHANGE_NOTICE_PIN_65 Change Notification Pin 65 PORTS_CHANGE_NOTICE_PIN_66 Change Notification Pin 66 PORTS_CHANGE_NOTICE_PIN_67 Change Notification Pin 67 PORTS_CHANGE_NOTICE_PIN_68 Change Notification Pin 68 PORTS_CHANGE_NOTICE_PIN_69 Change Notification Pin 69 PORTS_CHANGE_NOTICE_PIN_70 Change Notification Pin 70 PORTS_CHANGE_NOTICE_PIN_71 Change Notification Pin 71 PORTS_CHANGE_NOTICE_PIN_72 Change Notification Pin 72 PORTS_CHANGE_NOTICE_PIN_73 Change Notification Pin 73 PORTS_CHANGE_NOTICE_PIN_74 Change Notification Pin 74 PORTS_CHANGE_NOTICE_PIN_75 Change Notification Pin 75 PORTS_CHANGE_NOTICE_PIN_76 Change Notification Pin 76 PORTS_CHANGE_NOTICE_PIN_77 Change Notification Pin 77 PORTS_CHANGE_NOTICE_PIN_78 Change Notification Pin 78 PORTS_CHANGE_NOTICE_PIN_79 Change Notification Pin 79 PORTS_CHANGE_NOTICE_PIN_80 Change Notification Pin 8 PORTS_CHANGE_NOTICE_PIN_81 Change Notification Pin 81 PORTS_CHANGE_NOTICE_PIN_82 Change Notification Pin 82 PORTS_CHANGE_NOTICE_PIN_83 Change Notification Pin 83 PORTS_CHANGE_NOTICE_PIN_84 Change Notification Pin 84 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.17.6.5.4 PORTS_CHANNEL Enumeration C typedef enum { PORTS_CHANNEL_A, PORTS_CHANNEL_B, PORTS_CHANNEL_C, PORTS_CHANNEL_D, PORTS_CHANNEL_E, PORTS_CHANNEL_F, PORTS_CHANNEL_G, PORTS_CHANNEL_H, PORTS_CHANNEL_J, PORTS_NUMBER_OF_CHANNELS } PORTS_CHANNEL; Description PORT Channel ID This enumeration identifies the available PORT Channels. Members Members Description PORTS_CHANNEL_A Port A PORTS_CHANNEL_B Port B 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2635 PORTS_CHANNEL_C Port C PORTS_CHANNEL_D Port D PORTS_CHANNEL_E Port E PORTS_CHANNEL_F Port F PORTS_CHANNEL_G Port G PORTS_CHANNEL_H Port H PORTS_CHANNEL_J Port J PORTS_NUMBER_OF_CHANNELS Max number of Ports Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.17.6.5.5 PORTS_DATA_MASK Type C typedef uint16_t PORTS_DATA_MASK; Description PORTS data mask definition This data type defines the PORTS data mask Remarks This data type changes sizes, depending on if it is being used on an 8- 16- or 32-bit part. 5.6.17.6.5.6 PORTS_DATA_TYPE Type C typedef uint32_t PORTS_DATA_TYPE; Description PORTS data type definition This data type defines the PORTS data type. Remarks This data type changes sizes, depending on if it is being used on an 8-, 16-, or 32-bit device. 5.6.17.6.5.7 PORTS_MODULE_ID Enumeration C typedef enum { PORTS_ID_0, PORT_NUMBER_OF_MODULES } PORTS_MODULE_ID; Description PORT Module ID This enumeration identifies the available PORT modules. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2636 Members Members Description PORT_NUMBER_OF_MODULES Max number of Instances Remarks Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.17.6.5.8 PORTS_PERIPHERAL_OD Enumeration C typedef enum { PORTS_PERIPHERAL_OD_MSSP1, PORTS_PERIPHERAL_OD_MSSP2, PORTS_PERIPHERAL_OD_ECCP1, PORTS_PERIPHERAL_OD_ECCP2, PORTS_PERIPHERAL_OD_ECCP3, PORTS_PERIPHERAL_OD_CCP10, PORTS_PERIPHERAL_OD_CCP9, PORTS_PERIPHERAL_OD_CCP8, PORTS_PERIPHERAL_OD_CCP7, PORTS_PERIPHERAL_OD_CCP6, PORTS_PERIPHERAL_OD_CCP5, PORTS_PERIPHERAL_OD_CCP4, PORTS_PERIPHERAL_OD_EUSART2, PORTS_PERIPHERAL_OD_EUSART1 } PORTS_PERIPHERAL_OD; Description Peripherals available for Open drain Configuration This data type defines the different Peripherals available for Open drain Configuration Members Members Description PORTS_PERIPHERAL_OD_MSSP1 Peripheral Open Drain for MSSP1 PORTS_PERIPHERAL_OD_MSSP2 Peripheral Open Drain for MSSP2 PORTS_PERIPHERAL_OD_ECCP1 Peripheral Open Drain for ECCP1 PORTS_PERIPHERAL_OD_ECCP2 Peripheral Open Drain for ECCP2 PORTS_PERIPHERAL_OD_ECCP3 Peripheral Open Drain for ECCP3 PORTS_PERIPHERAL_OD_CCP10 Peripheral Open Drain for CCP10 PORTS_PERIPHERAL_OD_CCP9 Peripheral Open Drain for CCP9 PORTS_PERIPHERAL_OD_CCP8 Peripheral Open Drain for CCP8 PORTS_PERIPHERAL_OD_CCP7 Peripheral Open Drain for CCP7 PORTS_PERIPHERAL_OD_CCP6 Peripheral Open Drain for CCP6 PORTS_PERIPHERAL_OD_CCP5 Peripheral Open Drain for CCP5 PORTS_PERIPHERAL_OD_CCP4 Peripheral Open Drain for CCP4 PORTS_PERIPHERAL_OD_EUSART2 Peripheral Open Drain for EUSART2 PORTS_PERIPHERAL_OD_EUSART1 Peripheral Open Drain for EUSART1 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2637 5.6.17.6.5.9 PORTS_PIN Enumeration C typedef enum { PORTS_PIN_0, PORTS_PIN_1, PORTS_PIN_2, PORTS_PIN_3, PORTS_PIN_4, PORTS_PIN_5, PORTS_PIN_6, PORTS_PIN_7, PORTS_PIN_8, PORTS_PIN_9, PORTS_PIN_10, PORTS_PIN_11, PORTS_PIN_12, PORTS_PIN_13, PORTS_PIN_14, PORTS_PIN_15 } PORTS_PIN; Description PORTS IO Pins enumeration This data type defines the different PORTS IO Pins enumeration Members Members Description PORTS_PIN_0 PORT Bit Position 0 PORTS_PIN_1 PORT Bit Position 1 PORTS_PIN_2 PORT Bit Position 2 PORTS_PIN_3 PORT Bit Position 3 PORTS_PIN_4 PORT Bit Position 4 PORTS_PIN_5 PORT Bit Position 5 PORTS_PIN_6 PORT Bit Position 6 PORTS_PIN_7 PORT Bit Position 7 PORTS_PIN_8 PORT Bit Position 8 PORTS_PIN_9 PORT Bit Position 9 PORTS_PIN_10 PORT Bit Position 10 PORTS_PIN_11 PORT Bit Position 11 PORTS_PIN_12 PORT Bit Position 12 PORTS_PIN_13 PORT Bit Position 13 PORTS_PIN_14 PORT Bit Position 14 PORTS_PIN_15 PORT Bit Position 15 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.17.6.5.10 PORTS_PIN_MODE Enumeration C typedef enum { PORTS_PIN_MODE_ANALOG, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2638 PORTS_PIN_MODE_DIGITAL } PORTS_PIN_MODE; Description PORTs Pin Mode This enumeration identifies the available pin modes. Members Members Description PORTS_PIN_MODE_ANALOG Port Pin is in Analog Mode PORTS_PIN_MODE_DIGITAL Port pin is in Digital Mode Remarks Not all modules are available on all devices. Refer to the specific device data sheet to determine which modules are supported. 5.6.17.6.5.11 PORTS_REMAP_FUNCTION Enumeration C typedef enum { PORTS_REMAP_FUNCTION_EXT_INT1, PORTS_REMAP_FUNCTION_EXT_INT2, PORTS_REMAP_FUNCTION_EXT_INT3, PORTS_REMAP_FUNCTION_EXT_INT4, PORTS_REMAP_FUNCTION_IC1, PORTS_REMAP_FUNCTION_IC2, PORTS_REMAP_FUNCTION_IC3, PORTS_REMAP_FUNCTION_IC4, PORTS_REMAP_FUNCTION_IC5, PORTS_REMAP_FUNCTION_IC6, PORTS_REMAP_FUNCTION_IC7, PORTS_REMAP_FUNCTION_IC8, PORTS_REMAP_FUNCTION_IC9, PORTS_REMAP_FUNCTION_OC_FAULTA, PORTS_REMAP_FUNCTION_OC_FAULTB, PORTS_REMAP_FUNCTION_SPI1_CLOCK, PORTS_REMAP_FUNCTION_SPI1_DATA, PORTS_REMAP_FUNCTION_SPI1_SLAVE_SEL, PORTS_REMAP_FUNCTION_SPI2_CLOCK, PORTS_REMAP_FUNCTION_SPI2_DATA, PORTS_REMAP_FUNCTION_SPI2_SLAVE_SEL, PORTS_REMAP_FUNCTION_SPI3_CLOCK, PORTS_REMAP_FUNCTION_SPI3_DATA, PORTS_REMAP_FUNCTION_SPI3_SLAVE_SEL, PORTS_REMAP_FUNCTION_TMR2_EXT_CLOCK, PORTS_REMAP_FUNCTION_TMR3_EXT_CLOCK, PORTS_REMAP_FUNCTION_TMR4_EXT_CLOCK, PORTS_REMAP_FUNCTION_TMR5_EXT_CLOCK, PORTS_REMAP_FUNCTION_USART1_CTS, PORTS_REMAP_FUNCTION_USART1_RX, PORTS_REMAP_FUNCTION_USART2_CTS, PORTS_REMAP_FUNCTION_USART2_RX, PORTS_REMAP_FUNCTION_USART3_CTS, PORTS_REMAP_FUNCTION_USART3_RX, PORTS_REMAP_FUNCTION_USART4_CTS, PORTS_REMAP_FUNCTION_USART4_RX, PORTS_REMAP_FUNCTION_NULL, PORTS_REMAP_FUNCTION_C1OUT, PORTS_REMAP_FUNCTION_C2OUT, PORTS_REMAP_FUNCTION_U1TX, PORTS_REMAP_FUNCTION_U1RTS, PORTS_REMAP_FUNCTION_U2TX, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2639 PORTS_REMAP_FUNCTION_U2RTS, PORTS_REMAP_FUNCTION_SDO1, PORTS_REMAP_FUNCTION_SCK1OUT, PORTS_REMAP_FUNCTION_SS1OUT, PORTS_REMAP_FUNCTION_SDO2, PORTS_REMAP_FUNCTION_SCK2OUT, PORTS_REMAP_FUNCTION_SS2OUT, PORTS_REMAP_FUNCTION_OC1, PORTS_REMAP_FUNCTION_OC2, PORTS_REMAP_FUNCTION_OC3, PORTS_REMAP_FUNCTION_OC4, PORTS_REMAP_FUNCTION_OC5, PORTS_REMAP_FUNCTION_OC6, PORTS_REMAP_FUNCTION_OC7, PORTS_REMAP_FUNCTION_OC8, PORTS_REMAP_FUNCTION_U3TX, PORTS_REMAP_FUNCTION_U3RTS, PORTS_REMAP_FUNCTION_U4TX, PORTS_REMAP_FUNCTION_U4RTS, PORTS_REMAP_FUNCTION_SDO3, PORTS_REMAP_FUNCTION_SCK3OUT, PORTS_REMAP_FUNCTION_SS3OUT, PORTS_REMAP_FUNCTION_OC9, PORTS_REMAP_FUNCTION_C3OUT } PORTS_REMAP_FUNCTION; Description Remap Function Enumeration This data type defines the different remap function enumeration Members Members Description PORTS_REMAP_FUNCTION_EXT_INT1 Input Function Name - External Interrupt 1 PORTS_REMAP_FUNCTION_EXT_INT2 Input Function Name - External Interrupt 2 PORTS_REMAP_FUNCTION_EXT_INT3 Input Function Name - External Interrupt 3 PORTS_REMAP_FUNCTION_EXT_INT4 Input Function Name - External Interrupt 4 PORTS_REMAP_FUNCTION_IC1 Input Function Name - Input Capture 1 PORTS_REMAP_FUNCTION_IC2 Input Function Name - Input Capture 2 PORTS_REMAP_FUNCTION_IC3 Input Function Name - Input Capture 3 PORTS_REMAP_FUNCTION_IC4 Input Function Name - Input Capture 4 PORTS_REMAP_FUNCTION_IC5 Input Function Name - Input Capture 5 PORTS_REMAP_FUNCTION_IC6 Input Function Name - Input Capture 6 PORTS_REMAP_FUNCTION_IC7 Input Function Name - Input Capture 7 PORTS_REMAP_FUNCTION_IC8 Input Function Name - Input Capture 8 PORTS_REMAP_FUNCTION_IC9 Input Function Name - Input Capture 9 PORTS_REMAP_FUNCTION_OC_FAULTA Input Function Name - Output Compare Fault A PORTS_REMAP_FUNCTION_OC_FAULTB Input Function Name - Output Compare Fault B PORTS_REMAP_FUNCTION_SPI1_CLOCK Input Function Name - SPI 1 Clock PORTS_REMAP_FUNCTION_SPI1_DATA Input Function Name - SPI1 Data PORTS_REMAP_FUNCTION_SPI1_SLAVE_SEL Input Function Name - SPI1 Slave Select PORTS_REMAP_FUNCTION_SPI2_CLOCK Input Function Name - SPI2 Clock PORTS_REMAP_FUNCTION_SPI2_DATA Input Function Name - SPI2 Data PORTS_REMAP_FUNCTION_SPI2_SLAVE_SEL Input Function Name - SPI2 Slave Select PORTS_REMAP_FUNCTION_SPI3_CLOCK Input Function Name - SPI3 Clock 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2640 PORTS_REMAP_FUNCTION_SPI3_DATA Input Function Name - SPI3 Data PORTS_REMAP_FUNCTION_SPI3_SLAVE_SEL Input Function Name - SPI3 Slave Select PORTS_REMAP_FUNCTION_TMR2_EXT_CLOCK Input Function Name - Timer 2 External CLock PORTS_REMAP_FUNCTION_TMR3_EXT_CLOCK Input Function Name - Timer 3 External Clock PORTS_REMAP_FUNCTION_TMR4_EXT_CLOCK Input Function Name - Timer 4 External Clock PORTS_REMAP_FUNCTION_TMR5_EXT_CLOCK Input Function Name - Timer5 External Clock PORTS_REMAP_FUNCTION_USART1_CTS Input Function Name - USART 1 Clear To Send PORTS_REMAP_FUNCTION_USART1_RX Input Function Name - USART 1 Receive PORTS_REMAP_FUNCTION_USART2_CTS Input Function Name - USART 2 Clear To Send PORTS_REMAP_FUNCTION_USART2_RX Input Function Name - USART 2 Receive PORTS_REMAP_FUNCTION_USART3_CTS Input Function Name - USART 3 Clear To Send PORTS_REMAP_FUNCTION_USART3_RX Input Function Name - USART 3 Receive PORTS_REMAP_FUNCTION_USART4_CTS Input Function Name - USART 4 Clear To Send PORTS_REMAP_FUNCTION_USART4_RX Input Function Name - USART 4 Receive PORTS_REMAP_FUNCTION_NULL Output Function Name - Null PORTS_REMAP_FUNCTION_C1OUT Output Function Name - Comparator 1 Output PORTS_REMAP_FUNCTION_C2OUT Output Function Name - Comparator 2 Output PORTS_REMAP_FUNCTION_U1TX Output Function Name - UART1 Transmit PORTS_REMAP_FUNCTION_U1RTS Output Function Name - UART1 Request To Send PORTS_REMAP_FUNCTION_U2TX Output Function Name - UART2 Transmit PORTS_REMAP_FUNCTION_U2RTS Output Function Name - UART2 Request To Send PORTS_REMAP_FUNCTION_SDO1 Output Function Name - SPI1 Data Output PORTS_REMAP_FUNCTION_SCK1OUT Output Function Name - SPI1 Clock Output PORTS_REMAP_FUNCTION_SS1OUT Output Function Name - SPI1 Slave Select Output PORTS_REMAP_FUNCTION_SDO2 Output Function Name - SPI2 Data Output PORTS_REMAP_FUNCTION_SCK2OUT Output Function Name - SPI2 Clock Output PORTS_REMAP_FUNCTION_SS2OUT Output Function Name - SPI2 Slave Select Output PORTS_REMAP_FUNCTION_OC1 Output Function Name - Output Compare 1 PORTS_REMAP_FUNCTION_OC2 Output Function Name - Output Compare 2 PORTS_REMAP_FUNCTION_OC3 Output Function Name - Output Compare 3 PORTS_REMAP_FUNCTION_OC4 Output Function Name - Output Compare 4 PORTS_REMAP_FUNCTION_OC5 Output Function Name - Output Compare 5 PORTS_REMAP_FUNCTION_OC6 Output Function Name - Output Compare 6 PORTS_REMAP_FUNCTION_OC7 Output Function Name - Output Compare 7 PORTS_REMAP_FUNCTION_OC8 Output Function Name - Output Compare 8 PORTS_REMAP_FUNCTION_U3TX Output Function Name - UART3 Transmit PORTS_REMAP_FUNCTION_U3RTS Output Function Name - UART3 Request To Send PORTS_REMAP_FUNCTION_U4TX Output Function Name - UART4 Transmit PORTS_REMAP_FUNCTION_U4RTS Output Function Name - UART4 Request To Send PORTS_REMAP_FUNCTION_SDO3 Output Function Name - SPI3 Data Output PORTS_REMAP_FUNCTION_SCK3OUT Output Function Name - SPI3 Clock Output PORTS_REMAP_FUNCTION_SS3OUT Output Function Name - SPI3 Slave Select Output PORTS_REMAP_FUNCTION_OC9 Output Function Name - Output Compare 9 PORTS_REMAP_FUNCTION_C3OUT Output Function Name - Comparator 3 Output 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2641 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.17.6.5.12 PORTS_REMAP_INPUT_FUNCTION Enumeration C typedef enum { INPUT_FUNC_INT1, INPUT_FUNC_INT2, INPUT_FUNC_INT3, INPUT_FUNC_INT4, INPUT_FUNC_T2CK, INPUT_FUNC_T3CK, INPUT_FUNC_T4CK, INPUT_FUNC_T5CK, INPUT_FUNC_T6CK, INPUT_FUNC_T7CK, INPUT_FUNC_T8CK, INPUT_FUNC_T9CK, INPUT_FUNC_IC1, INPUT_FUNC_IC2, INPUT_FUNC_IC3, INPUT_FUNC_IC4, INPUT_FUNC_IC5, INPUT_FUNC_IC6, INPUT_FUNC_IC7, INPUT_FUNC_IC8, INPUT_FUNC_IC9, INPUT_FUNC_OCFA, INPUT_FUNC_OCFB, INPUT_FUNC_U1RX, INPUT_FUNC_U1CTS, INPUT_FUNC_U2RX, INPUT_FUNC_U2CTS, INPUT_FUNC_U3RX, INPUT_FUNC_U3CTS, INPUT_FUNC_U4RX, INPUT_FUNC_U4CTS, INPUT_FUNC_U5RX, INPUT_FUNC_U5CTS, INPUT_FUNC_U6RX, INPUT_FUNC_U6CTS, INPUT_FUNC_SDI1, INPUT_FUNC_SS1, INPUT_FUNC_SDI2, INPUT_FUNC_SS2, INPUT_FUNC_SDI3, INPUT_FUNC_SS3, INPUT_FUNC_SDI4, INPUT_FUNC_SS4, INPUT_FUNC_SDI5, INPUT_FUNC_SS5, INPUT_FUNC_SDI6, INPUT_FUNC_SS6, INPUT_FUNC_C1RX, INPUT_FUNC_C2RX, INPUT_FUNC_REFCLKI1, INPUT_FUNC_REFCLKI3, INPUT_FUNC_REFCLKI4, REMAP_NOT_SUPPORTED } PORTS_REMAP_INPUT_FUNCTION; 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2642 Description Remap Input Function Enumeration This data type defines the different remap input function enumeration. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. 5.6.17.6.5.13 PORTS_REMAP_INPUT_PIN Enumeration C typedef enum { INPUT_PIN_RPD2, INPUT_PIN_RPG8, INPUT_PIN_RPF4, INPUT_PIN_RPD10, INPUT_PIN_RPF1, INPUT_PIN_RPB9, INPUT_PIN_RPB10, INPUT_PIN_RPC14, INPUT_PIN_RPB5, INPUT_PIN_RPC1, INPUT_PIN_RPD14, INPUT_PIN_RPG1, INPUT_PIN_RPA14, INPUT_PIN_RPD6, INPUT_PIN_RPD3, INPUT_PIN_RPG7, INPUT_PIN_RPF5, INPUT_PIN_RPD11, INPUT_PIN_RPF0, INPUT_PIN_RPB1, INPUT_PIN_RPE5, INPUT_PIN_RPC13, INPUT_PIN_RPB3, INPUT_PIN_RPC4, INPUT_PIN_RPD15, INPUT_PIN_RPG0, INPUT_PIN_RPA15, INPUT_PIN_RPD7, INPUT_PIN_RPD9, INPUT_PIN_RPG6, INPUT_PIN_RPB8, INPUT_PIN_RPB15, INPUT_PIN_RPD4, INPUT_PIN_RPB0, INPUT_PIN_RPE3, INPUT_PIN_RPB7, INPUT_PIN_RPF12, INPUT_PIN_RPD12, INPUT_PIN_RPF8, INPUT_PIN_RPC3, INPUT_PIN_RPE9, INPUT_PIN_RPD1, INPUT_PIN_RPG9, INPUT_PIN_RPB14, INPUT_PIN_RPD0, INPUT_PIN_RPB6, INPUT_PIN_RPD5, INPUT_PIN_RPB2, INPUT_PIN_RPF3, INPUT_PIN_RPF13, INPUT_PIN_NC, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2643 INPUT_PIN_RPF2, INPUT_PIN_RPC2, INPUT_PIN_RPE8, INPUT_PIN_RPF7, INPUT_PIN_RPD8, INPUT_PIN_RPA0, INPUT_PIN_RPB4, INPUT_PIN_RPC7, INPUT_PIN_RPC0, INPUT_PIN_RPC5, INPUT_PIN_RPA1, INPUT_PIN_RPB11, INPUT_PIN_RPA8, INPUT_PIN_RPC8, INPUT_PIN_RPA9, INPUT_PIN_RPA2, INPUT_PIN_RPA4, INPUT_PIN_RPB13, INPUT_PIN_RPC6, INPUT_PIN_RPA3, INPUT_PIN_RPC9, PIN_REMAP_NOT_SUPPORTED } PORTS_REMAP_INPUT_PIN; Description PORTS IO Input Pins enumeration This data type defines the different Ports I/O input pins enumeration. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. 5.6.17.6.5.14 PORTS_REMAP_OUTPUT_FUNCTION Enumeration C typedef enum { OTPUT_FUNC_U3TX, OTPUT_FUNC_U4RTS, OTPUT_FUNC_SDO1, OTPUT_FUNC_SDO2, OTPUT_FUNC_SDO3, OTPUT_FUNC_SDO5, OTPUT_FUNC_SS6, OTPUT_FUNC_OC3, OTPUT_FUNC_OC6, OTPUT_FUNC_REFCLKO4, OTPUT_FUNC_C2OUT, OTPUT_FUNC_C1TX, OTPUT_FUNC_U1TX, OTPUT_FUNC_U2RTS, OTPUT_FUNC_U5TX, OTPUT_FUNC_U6RTS, OTPUT_FUNC_SDO4, OTPUT_FUNC_OC4, OTPUT_FUNC_OC7, OTPUT_FUNC_REFCLKO1, OTPUT_FUNC_U3RTS, OTPUT_FUNC_U4TX, OTPUT_FUNC_U6TX, OTPUT_FUNC_SS1, OTPUT_FUNC_SS3, OTPUT_FUNC_SS4, OTPUT_FUNC_SS5, OTPUT_FUNC_SDO6, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2644 OTPUT_FUNC_OC5, OTPUT_FUNC_OC8, OTPUT_FUNC_C1OUT, OTPUT_FUNC_REFCLKO3, OTPUT_FUNC_U1RTS, OTPUT_FUNC_U2TX, OTPUT_FUNC_U5RTS, OTPUT_FUNC_SS2, OTPUT_FUNC_OC2, OTPUT_FUNC_OC1, OTPUT_FUNC_OC9, OTPUT_FUNC_C2TX, OTPUT_FUNC_C3OUT, OTPUT_FUNC_REFCLKO, OTPUT_FUNC_NO_CONNECT } PORTS_REMAP_OUTPUT_FUNCTION; Description Remap Output Function Enumeration This data type defines the different remap output function enumeration. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. 5.6.17.6.5.15 PORTS_REMAP_OUTPUT_PIN Enumeration C typedef enum { OUTPUT_PIN_RPA0, OUTPUT_PIN_RPA1, OUTPUT_PIN_RPA2, OUTPUT_PIN_RPA3, OUTPUT_PIN_RPA4, OUTPUT_PIN_RPA8, OUTPUT_PIN_RPA9, OUTPUT_PIN_RPA14, OUTPUT_PIN_RPA15, OUTPUT_PIN_RPB0, OUTPUT_PIN_RPB1, OUTPUT_PIN_RPB2, OUTPUT_PIN_RPB3, OUTPUT_PIN_RPB4, OUTPUT_PIN_RPB5, OUTPUT_PIN_RPB6, OUTPUT_PIN_RPB7, OUTPUT_PIN_RPB8, OUTPUT_PIN_RPB9, OUTPUT_PIN_RPB10, OUTPUT_PIN_RPB11, OUTPUT_PIN_RPB13, OUTPUT_PIN_RPB14, OUTPUT_PIN_RPB15, OUTPUT_PIN_RPC0, OUTPUT_PIN_RPC1, OUTPUT_PIN_RPC2, OUTPUT_PIN_RPC3, OUTPUT_PIN_RPC4, OUTPUT_PIN_RPC5, OUTPUT_PIN_RPC6, OUTPUT_PIN_RPC7, OUTPUT_PIN_RPC8, OUTPUT_PIN_RPC9, OUTPUT_PIN_RPC13, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2645 OUTPUT_PIN_RPC14, OUTPUT_PIN_RPD0, OUTPUT_PIN_RPD1, OUTPUT_PIN_RPD2, OUTPUT_PIN_RPD3, OUTPUT_PIN_RPD4, OUTPUT_PIN_RPD5, OUTPUT_PIN_RPD6, OUTPUT_PIN_RPD7, OUTPUT_PIN_RPD8, OUTPUT_PIN_RPD9, OUTPUT_PIN_RPD10, OUTPUT_PIN_RPD11, OUTPUT_PIN_RPD12, OUTPUT_PIN_RPD14, OUTPUT_PIN_RPD15, OUTPUT_PIN_RPE3, OUTPUT_PIN_RPE5, OUTPUT_PIN_RPE8, OUTPUT_PIN_RPE9, OUTPUT_PIN_RPF0, OUTPUT_PIN_RPF1, OUTPUT_PIN_RPF2, OUTPUT_PIN_RPF3, OUTPUT_PIN_RPF4, OUTPUT_PIN_RPF5, OUTPUT_PIN_RPF6, OUTPUT_PIN_RPF7, OUTPUT_PIN_RPF8, OUTPUT_PIN_RPF12, OUTPUT_PIN_RPF13, OUTPUT_PIN_RPG0, OUTPUT_PIN_RPG1, OUTPUT_PIN_RPG6, OUTPUT_PIN_RPG7, OUTPUT_PIN_RPG8, OUTPUT_PIN_RPG9, REMAP_NOT_SUPPORTED } PORTS_REMAP_OUTPUT_PIN; Description PORTS IO Output Pins enumeration This data type defines the different Ports I/O output pins enumeration. Remarks These are the superset enumerations provided for documentation, not all constants are available on all devices. 5.6.17.6.5.16 PORTS_REMAP_PIN Enumeration C typedef enum { PORTS_REMAP_PIN_RPI0, PORTS_REMAP_PIN_RPI1, PORTS_REMAP_PIN_RPI2, PORTS_REMAP_PIN_RPI3, PORTS_REMAP_PIN_RPI4, PORTS_REMAP_PIN_RPI5, PORTS_REMAP_PIN_RPI6, PORTS_REMAP_PIN_RPI7, PORTS_REMAP_PIN_RPI8, PORTS_REMAP_PIN_RPI9, PORTS_REMAP_PIN_RPI10, PORTS_REMAP_PIN_RPI11, 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2646 PORTS_REMAP_PIN_RPI12 , PORTS_REMAP_PIN_RPI13 , PORTS_REMAP_PIN_RPI14 , PORTS_REMAP_PIN_RPI15 , PORTS_REMAP_PIN_RPI16 , PORTS_REMAP_PIN_RPI17 , PORTS_REMAP_PIN_RPI18 , PORTS_REMAP_PIN_RPI19 , PORTS_REMAP_PIN_RPI20 , PORTS_REMAP_PIN_RPI21 , PORTS_REMAP_PIN_RPI22 , PORTS_REMAP_PIN_RPI23 , PORTS_REMAP_PIN_RPI24 , PORTS_REMAP_PIN_RPI25 , PORTS_REMAP_PIN_RPI26 , PORTS_REMAP_PIN_RPI27 , PORTS_REMAP_PIN_RPI28 , PORTS_REMAP_PIN_RPI29 , PORTS_REMAP_PIN_RPI30 , PORTS_REMAP_PIN_RPI31 , PORTS_REMAP_PIN_RPI32 , PORTS_REMAP_PIN_RPI33 , PORTS_REMAP_PIN_RPI34 , PORTS_REMAP_PIN_RPI35 , PORTS_REMAP_PIN_RPI36 , PORTS_REMAP_PIN_RPI37 , PORTS_REMAP_PIN_RPI38 , PORTS_REMAP_PIN_RPI39 , PORTS_REMAP_PIN_RPI40 , PORTS_REMAP_PIN_RPI41 , PORTS_REMAP_PIN_RPI42 , PORTS_REMAP_PIN_RPI43 , PORTS_REMAP_PIN_RPI44 , PORTS_REMAP_PIN_RPI45 , PORTS_REMAP_PIN_RP0 , PORTS_REMAP_PIN_RP1 , PORTS_REMAP_PIN_RP2 , PORTS_REMAP_PIN_RP3 , PORTS_REMAP_PIN_RP4 , PORTS_REMAP_PIN_RP5 , PORTS_REMAP_PIN_RP6 , PORTS_REMAP_PIN_RP7 , PORTS_REMAP_PIN_RP8 , PORTS_REMAP_PIN_RP9 , PORTS_REMAP_PIN_RP10 , PORTS_REMAP_PIN_RP11 , PORTS_REMAP_PIN_RP12 , PORTS_REMAP_PIN_RP13 , PORTS_REMAP_PIN_RP14 , PORTS_REMAP_PIN_RP15 , PORTS_REMAP_PIN_RP16 , PORTS_REMAP_PIN_RP17 , PORTS_REMAP_PIN_RP18 , PORTS_REMAP_PIN_RP19 , PORTS_REMAP_PIN_RP20 , PORTS_REMAP_PIN_RP21 , PORTS_REMAP_PIN_RP22 , PORTS_REMAP_PIN_RP23 , PORTS_REMAP_PIN_RP24 , PORTS_REMAP_PIN_RP25 , PORTS_REMAP_PIN_RP26 , PORTS_REMAP_PIN_RP27 , PORTS_REMAP_PIN_RP28 , PORTS_REMAP_PIN_RP29 , PORTS_REMAP_PIN_RP30 , PORTS_REMAP_PIN_RP31 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2647 } PORTS_REMAP_PIN; Description Remappable input/output Enumeration This data type defines the different remappable input/output enumeration Members Members Description PORTS_REMAP_PIN_RPI0 Remappable input RPI0 PORTS_REMAP_PIN_RPI1 Remappable input RPI1 PORTS_REMAP_PIN_RPI2 Remappable input RPI2 PORTS_REMAP_PIN_RPI3 Remappable input RPI3 PORTS_REMAP_PIN_RPI4 Remappable input RPI4 PORTS_REMAP_PIN_RPI5 Remappable input RPI5 PORTS_REMAP_PIN_RPI6 Remappable input RPI6 PORTS_REMAP_PIN_RPI7 Remappable input RPI7 PORTS_REMAP_PIN_RPI8 Remappable input RPI8 PORTS_REMAP_PIN_RPI9 Remappable input RPI9 PORTS_REMAP_PIN_RPI10 Remappable input RPI10 PORTS_REMAP_PIN_RPI11 Remappable input RPI11 PORTS_REMAP_PIN_RPI12 Remappable input RPI12 PORTS_REMAP_PIN_RPI13 Remappable input RPI13 PORTS_REMAP_PIN_RPI14 Remappable input RPI14 PORTS_REMAP_PIN_RPI15 Remappable input RPI15 PORTS_REMAP_PIN_RPI16 Remappable input RPI16 PORTS_REMAP_PIN_RPI17 Remappable input RPI17 PORTS_REMAP_PIN_RPI18 Remappable input RPI18 PORTS_REMAP_PIN_RPI19 Remappable input RPI19 PORTS_REMAP_PIN_RPI20 Remappable input RPI20 PORTS_REMAP_PIN_RPI21 Remappable input RPI21 PORTS_REMAP_PIN_RPI22 Remappable input RPI22 PORTS_REMAP_PIN_RPI23 Remappable input RPI23 PORTS_REMAP_PIN_RPI24 Remappable input RPI24 PORTS_REMAP_PIN_RPI25 Remappable input RPI25 PORTS_REMAP_PIN_RPI26 Remappable input RPI26 PORTS_REMAP_PIN_RPI27 Remappable input RPI27 PORTS_REMAP_PIN_RPI28 Remappable input RPI28 PORTS_REMAP_PIN_RPI29 Remappable input RPI29 PORTS_REMAP_PIN_RPI30 Remappable input RPI30 PORTS_REMAP_PIN_RPI31 Remappable input RPI31 PORTS_REMAP_PIN_RPI32 Remappable input RPI32 PORTS_REMAP_PIN_RPI33 Remappable input RPI33 PORTS_REMAP_PIN_RPI34 Remappable input RPI34 PORTS_REMAP_PIN_RPI35 Remappable input RPI35 PORTS_REMAP_PIN_RPI36 Remappable input RPI36 PORTS_REMAP_PIN_RPI37 Remappable input RPI37 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2648 PORTS_REMAP_PIN_RPI38 Remappable input RPI38 PORTS_REMAP_PIN_RPI39 Remappable input RPI39 PORTS_REMAP_PIN_RPI40 Remappable input RPI40 PORTS_REMAP_PIN_RPI41 Remappable input RPI41 PORTS_REMAP_PIN_RPI42 Remappable input RPI42 PORTS_REMAP_PIN_RPI43 Remappable input RPI43 PORTS_REMAP_PIN_RPI44 Remappable input RPI44 PORTS_REMAP_PIN_RPI45 Remappable input RPI45 PORTS_REMAP_PIN_RP0 Remappable output RP0 PORTS_REMAP_PIN_RP1 Remappable output RP1 PORTS_REMAP_PIN_RP2 Remappable output RP2 PORTS_REMAP_PIN_RP3 Remappable output RP3 PORTS_REMAP_PIN_RP4 Remappable output RP4 PORTS_REMAP_PIN_RP5 Remappable output RP5 PORTS_REMAP_PIN_RP6 Remappable output RP6 PORTS_REMAP_PIN_RP7 Remappable output RP7 PORTS_REMAP_PIN_RP8 Remappable output RP8 PORTS_REMAP_PIN_RP9 Remappable output RP9 PORTS_REMAP_PIN_RP10 Remappable output RP10 PORTS_REMAP_PIN_RP11 Remappable output RP11 PORTS_REMAP_PIN_RP12 Remappable output RP12 PORTS_REMAP_PIN_RP13 Remappable output RP13 PORTS_REMAP_PIN_RP14 Remappable output RP14 PORTS_REMAP_PIN_RP15 Remappable output RP15 PORTS_REMAP_PIN_RP16 Remappable output RP16 PORTS_REMAP_PIN_RP17 Remappable output RP17 PORTS_REMAP_PIN_RP18 Remappable output RP18 PORTS_REMAP_PIN_RP19 Remappable output RP19 PORTS_REMAP_PIN_RP20 Remappable output RP20 PORTS_REMAP_PIN_RP21 Remappable output RP21 PORTS_REMAP_PIN_RP22 Remappable output RP22 PORTS_REMAP_PIN_RP23 Remappable output RP23 PORTS_REMAP_PIN_RP24 Remappable output RP24 PORTS_REMAP_PIN_RP25 Remappable output RP25 PORTS_REMAP_PIN_RP26 Remappable output RP26 PORTS_REMAP_PIN_RP27 Remappable output RP27 PORTS_REMAP_PIN_RP28 Remappable output RP28 PORTS_REMAP_PIN_RP29 Remappable output RP29 PORTS_REMAP_PIN_RP30 Remappable output RP30 PORTS_REMAP_PIN_RP31 Remappable output RP31 Remarks These are the super set enumerations provided for documentation, not all constants are available on all parts 5.6.17.6.6 Feature Existence Functions 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2649 5.6.17.6.6.1 PLIB_PORTS_ExistsChangeNotice Function C bool PLIB_PORTS_ExistsChangeNotice( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNotice feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeEnable • PLIB_PORTS_ChangeNoticeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNotice feature is supported on the device • false - The ChangeNotice feature is not supported on the device Remarks None. 5.6.17.6.6.2 PLIB_PORTS_ExistsChangeNoticeInIdle Function C bool PLIB_PORTS_ExistsChangeNoticeInIdle( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticeInIdle feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeInIdleEnable • PLIB_PORTS_ChangeNoticeInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticeInIdle feature is supported on the device • false - The ChangeNoticeInIdle feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2650 Remarks None. 5.6.17.6.6.3 PLIB_PORTS_ExistsChangeNoticePerPortInIdle Function C bool PLIB_PORTS_ExistsChangeNoticePerPortInIdle( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticeInIdlePerPort feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticeInIdlePerPortEnable • PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticeInIdlePerPort feature is supported on the device • false - The ChangeNoticeInIdlePerPort feature is not supported on the device Remarks None. 5.6.17.6.6.4 PLIB_PORTS_ExistsChangeNoticePerPortStatus Function C bool PLIB_PORTS_ExistsChangeNoticePerPortStatus( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticePerPortStatus feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePerPortHasOccured Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticePerPortStatus feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2651 • false - The ChangeNoticePerPortStatus feature is not supported on the device Remarks None. 5.6.17.6.6.5 PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Function C bool PLIB_PORTS_ExistsChangeNoticePerPortTurnOn( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticePerPortTurnOn feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePerPortTurnOn • PLIB_PORTS_ChangeNoticePerPortTurnOff Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticePerPortTurnOn feature is supported on the device • false - The ChangeNoticePerPortTurnOn feature is not supported on the device Remarks None. 5.6.17.6.6.6 PLIB_PORTS_ExistsChangeNoticePullDownPerPort Function C bool PLIB_PORTS_ExistsChangeNoticePullDownPerPort( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticePullDownPerPort feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullDownPerPortEnable • PLIB_PORTS_ChangeNoticePullDownPerPortDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2652 Returns • true - The ChangeNoticePullDownPerPort feature is supported on the device • false - The ChangeNoticePullDownPerPort feature is not supported on the device Remarks None. 5.6.17.6.6.7 PLIB_PORTS_ExistsChangeNoticePullUp Function C bool PLIB_PORTS_ExistsChangeNoticePullUp( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticePullup feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullUpEnable • PLIB_PORTS_ChangeNoticePullUpDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticePullup feature is supported on the device • false - The ChangeNoticePullup feature is not supported on the device Remarks None. 5.6.17.6.6.8 PLIB_PORTS_ExistsChangeNoticePullUpPerPort Function C bool PLIB_PORTS_ExistsChangeNoticePullUpPerPort( PORTS_MODULE_ID index ); Description This function identifies whether the ChangeNoticePullUpPerPort feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_ChangeNoticePullUpPerPortEnable • PLIB_PORTS_ChangeNoticePullUpPerPortDisable Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2653 Parameters Parameters Description index Identifier for the device instance Returns • true - The ChangeNoticePullUpPerPort feature is supported on the device • false - The ChangeNoticePullUpPerPort feature is not supported on the device Remarks None. 5.6.17.6.6.9 PLIB_PORTS_ExistsPinChangeNotice Function C bool PLIB_PORTS_ExistsPinChangeNotice( PORTS_MODULE_ID index ); Description This function identifies whether the PinChangeNotice feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinChangeNoticeEnable • PLIB_PORTS_PinChangeNoticeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PinChangeNotice feature is supported on the device • false - The PinChangeNotice feature is not supported on the device Remarks None. 5.6.17.6.6.10 PLIB_PORTS_ExistsPinChangeNoticePerPort Function C bool PLIB_PORTS_ExistsPinChangeNoticePerPort( PORTS_MODULE_ID index ); Description This function identifies whether the PinChangeNoticePerPort feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinChangeNoticePerPortEnable • PLIB_PORTS_PinChangeNoticePerPortDisable 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2654 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PinChangeNoticePerPort feature is supported on the device • false - The PinChangeNoticePerPort feature is not supported on the device Remarks None. 5.6.17.6.6.11 PLIB_PORTS_ExistsPinMode Function C bool PLIB_PORTS_ExistsPinMode( PORTS_MODULE_ID index ); Description This function identifies whether the PinMode feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PinMode feature is supported on the device • false - The PinMode feature is not supported on the device Remarks None. 5.6.17.6.6.12 PLIB_PORTS_ExistsPinModePerPort Function C bool PLIB_PORTS_ExistsPinModePerPort( PORTS_MODULE_ID index ); Description This function identifies whether the PinModePerPort feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinModePerPortSelect 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2655 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PinModePerPort feature is supported on the device • false - The PinModePerPort feature is not supported on the device Remarks None. 5.6.17.6.6.13 PLIB_PORTS_ExistsPortsDirection Function C bool PLIB_PORTS_ExistsPortsDirection( PORTS_MODULE_ID index ); Description This function identifies whether the PortsDirection feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinDirectionInputSet • PLIB_PORTS_PinDirectionOutputSet • PLIB_PORTS_DirectionInputSet • PLIB_PORTS_DirectionOutputSet • PLIB_PORTS_DirectionGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PortsDirection feature is supported on the device • false - The PortsDirection feature is not supported on the device Remarks None. 5.6.17.6.6.14 PLIB_PORTS_ExistsPortsOpenDrain Function C bool PLIB_PORTS_ExistsPortsOpenDrain( PORTS_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2656 Description This function identifies whether the PortsOpenDrain feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinOpenDrainEnable • PLIB_PORTS_PinOpenDrainDisable • PLIB_PORTS_OpenDrainEnable • PLIB_PORTS_OpenDrainDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PortsOpenDrain feature is supported on the device • false - The PortsOpenDrain feature is not supported on the device Remarks None. 5.6.17.6.6.15 PLIB_PORTS_ExistsPortsRead Function C bool PLIB_PORTS_ExistsPortsRead( PORTS_MODULE_ID index ); Description This function identifies whether the PortsRead feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinGet • PLIB_PORTS_Read Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PortsRead feature is supported on the device • false - The PortsRead feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2657 5.6.17.6.6.16 PLIB_PORTS_ExistsPortsWrite Function C bool PLIB_PORTS_ExistsPortsWrite( PORTS_MODULE_ID index ); Description This function identifies whether the PortsWrite feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_PinWrite • PLIB_PORTS_PinSet • PLIB_PORTS_PinClear • PLIB_PORTS_PinToggle • PLIB_PORTS_Write • PLIB_PORTS_Set • PLIB_PORTS_Toggle • PLIB_PORTS_Clear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PortsWrite feature is supported on the device • false - The PortsWrite feature is not supported on the device Remarks None. 5.6.17.6.6.17 PLIB_PORTS_ExistsRemapInput Function C bool PLIB_PORTS_ExistsRemapInput( PORTS_MODULE_ID index ); Description This function identifies whether the RemapInput feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_RemapInput Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2658 Parameters Parameters Description index Identifier for the device instance Returns • true - The RemapInput feature is supported on the device • false - The RemapInput feature is not supported on the device Remarks None. 5.6.17.6.6.18 PLIB_PORTS_ExistsRemapOutput Function C bool PLIB_PORTS_ExistsRemapOutput( PORTS_MODULE_ID index ); Description This function identifies whether the RemapOutput feature is available on the PORTS module. When this function returns true, these functions are supported on the device: • PLIB_PORTS_RemapOutput Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RemapOutput feature is supported on the device • false - The RemapOutput feature is not supported on the device Remarks None. 5.6.17.7 Files Files Name Description plib_ports.h Ports Peripheral Library Interface header for Ports function definitions. Description 5.6.17.7.1 plib_ports.h Ports Peripheral Library Interface Header 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2659 This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Ports Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Ports peripheral. Functions Name Description PLIB_PORTS_ChangeNoticeDisable Global Change Notice disable. PLIB_PORTS_ChangeNoticeEnable Global Change Notice enable. PLIB_PORTS_ChangeNoticeInIdleDisable CPU Idle does not affect Change Notice operation. PLIB_PORTS_ChangeNoticeInIdleEnable CPU Idle mode halts Change Notice operation. PLIB_PORTS_ChangeNoticeInIdlePerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticeInIdlePerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortHasOccured Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortTurnOff Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePerPortTurnOn Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullDownPerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullDownPerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullUpDisable Disable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpEnable Enable pull-up on input change. PLIB_PORTS_ChangeNoticePullUpPerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_ChangeNoticePullUpPerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_Clear Clears the selected digital port/latch. PLIB_PORTS_DirectionGet Reads the direction of the selected digital port. PLIB_PORTS_DirectionInputSet Enables the read (input) direction for the selected port. PLIB_PORTS_DirectionOutputSet Enables the write (output) direction for the selected port. PLIB_PORTS_ExistsChangeNotice Identifies whether the ChangeNotice feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticeInIdle Identifies whether the ChangeNoticeInIdle feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortInIdle Identifies whether the ChangeNoticeInIdlePerPort feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortStatus Identifies whether the ChangeNoticePerPortStatus feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePerPortTurnOn Identifies whether the ChangeNoticePerPortTurnOn feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullDownPerPort Identifies whether the ChangeNoticePullDownPerPort feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullUp Identifies whether the ChangeNoticePullup feature exists on the PORTS module PLIB_PORTS_ExistsChangeNoticePullUpPerPort Identifies whether the ChangeNoticePullUpPerPort feature exists on the PORTS module PLIB_PORTS_ExistsPinChangeNotice Identifies whether the PinChangeNotice feature exists on the PORTS module PLIB_PORTS_ExistsPinChangeNoticePerPort Identifies whether the PinChangeNoticePerPort feature exists on the PORTS module PLIB_PORTS_ExistsPinMode Identifies whether the PinMode feature exists on the PORTS module PLIB_PORTS_ExistsPinModePerPort Identifies whether the PinModePerPort feature exists on the PORTS module 5.6 Peripheral Library Help MPLAB Harmony Help Ports Peripheral Library 5-2660 PLIB_PORTS_ExistsPortsDirection Identifies whether the PortsDirection feature exists on the PORTS module PLIB_PORTS_ExistsPortsOpenDrain Identifies whether the PortsOpenDrain feature exists on the PORTS module PLIB_PORTS_ExistsPortsRead Identifies whether the PortsRead feature exists on the PORTS module PLIB_PORTS_ExistsPortsWrite Identifies whether the PortsWrite feature exists on the PORTS module PLIB_PORTS_ExistsRemapInput Identifies whether the RemapInput feature exists on the PORTS module PLIB_PORTS_ExistsRemapOutput Identifies whether the RemapOutput feature exists on the PORTS module PLIB_PORTS_OpenDrainDisable Disables the open drain functionality for the selected port. PLIB_PORTS_OpenDrainEnable Enables the open drain functionality for the selected port. PLIB_PORTS_PinChangeNoticeDisable Port pin Change Notice disable. PLIB_PORTS_PinChangeNoticeEnable Port pin Change Notice enable. PLIB_PORTS_PinChangeNoticePerPortDisable Enables the selected pin as analog or digital. PLIB_PORTS_PinChangeNoticePerPortEnable Enables the selected pin as analog or digital. PLIB_PORTS_PinClear Clears the selected digital pin/latch. PLIB_PORTS_PinDirectionInputSet Enables the read (input) direction for the selected pin. PLIB_PORTS_PinDirectionOutputSet Enables the write (output) direction for the selected pin. PLIB_PORTS_PinGet Reads/Gets data from the selected digital pin. PLIB_PORTS_PinModePerPortSelect Enables the selected pin as analog or digital. PLIB_PORTS_PinModeSelect Enables the selected pin as analog or digital. PLIB_PORTS_PinOpenDrainDisable Disables the open drain functionality for the selected pin. PLIB_PORTS_PinOpenDrainEnable Enables the open drain functionality for the selected pin. PLIB_PORTS_PinSet Sets the selected digital pin/latch. PLIB_PORTS_PinToggle Toggles the selected digital pin/latch. PLIB_PORTS_PinWrite Writes the selected digital pin/latch. PLIB_PORTS_Read Reads the selected digital port. PLIB_PORTS_RemapInput Input/Output (I/O) function remapping. PLIB_PORTS_RemapOutput Input/Output (I/O) function remapping. PLIB_PORTS_Set Writes the selected digital port/latch based on the mask. PLIB_PORTS_Toggle Toggles the selected digital port/latch. PLIB_PORTS_Write Writes the selected digital port/latch. Types Name Description PORTS_DATA_MASK Data type defining the PORTS data mask PORTS_DATA_TYPE Data type defining the PORTS data type. File Name plib_ports.h Company Microchip Technology Inc. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2661 5.6.18 Power Peripheral Library 5.6.18.1 Introduction Power Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Power Controller modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Power Controller Overview The Power Controller is a key component of a microcontroller. Power control features allow the user to obtain the balance of power consumption and performance that is best suited to their application. The features provided in this library discuss specific software commands that are used dynamically to place the device in low-power (i.e., power-saving) modes, which disable power and clocking of selected features. When implementing a system to achieve the lowest possible power consumption while maintain the needed performance, the oscillator configuration and clocking of all peripherals must also be considered. Oscillator configuration and peripheral clocking are addressed in the Oscillator Peripheral Library. In addition, each peripheral may have its own low-power mode settings that are controlled by the library of that peripheral. The user is advised to refer to the libraries of the peripherals used for their particular application. Key features present on a power controller include (a microcontroller can support one or more of these power features): • Power Source Configuration: Provides the ability to enable and disable a source that may regulate the power consumption in the device • Power Status Flags: Indicate the status of the particular power feature in the device Note: Please refer to the the specific device data sheet to determine the exact set of supported features. 5.6.18.2 Release Notes MPLAB Harmony Version: v0.70b Power Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2662 5.6.18.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.18.4 Using the Library Using the Library This topic describes the basic architecture of the Power Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_power.h The interface to the Power Peripheral Library is defined in the "plib_power.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Power Peripheral Library must include "peripheral.h". Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the specific data sheet to determine availability. 5.6.18.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Power Controller module on Microchip microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description Hardware Abstraction Block Diagram 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2663 This section discusses the various power-saving features implemented in hardware. Combinations of these methods can be used to selectively tailor an application’s power consumption, while still maintaining critical or timing-sensitive application features. Note: Not all devices support all of the features discussed in this section. Please refer to specific device data sheet to determine the supported features for your device. Instruction-based Power-Saving Modes In addition to full-power operation, otherwise known as Run mode, PIC microcontrollers also provide other instruction-based power-saving modes. By powering down to different modes, different functional areas of the microcontroller allow progressive reductions of operating and idle power consumption. In addition, these modes can be tailored for more power reduction, but at a trade-off of some operating features. • Idle Mode: In Idle mode, the CPU is halted, but the System Clock (SYSCLK) source is still enabled. This allows peripherals to continue to operate when the CPU is halted. Peripherals can be individually configured to halt when entering Idle mode by setting their respective SIDL bit. Latency when exiting Idle mode is very low due to the CPU oscillator source remaining active. • Sleep Mode: The CPU, SYSCLK source and any peripherals that operate on the system clock source are disabled • Deep Sleep Mode: The CPU SYSCLK source, and all the peripherals, with the exception of the Real-Time Clock and Calendar (RTCC) and the Deep Sleep Watchdog Timer (DSWDT), are disabled. This is the lowest power mode for the device. The power to RAM and Flash is also disabled. Deep Sleep mode represents the lowest power mode available without removing power from the application. The instruction-based power-saving modes are exited as a result of several different hardware triggers. When the device exits one of these three operating modes, it is said to ‘wake-up’. Hardware-based Power-Saving Mode VBAT mode is a hardware-based power-saving mode that maintains only the most critical operations when a power loss occurs on VDD. The mode does this by powering the systems from a back-up power source connected to the VBAT pin. In this mode, the RTCC can run even when there is no power on VDD. VBAT mode is entered whenever power is removed from VDD. An on-chip power switch detects the power loss from VDD and connects the VBAT pin to the low-voltage regulator. Entering VBAT mode requires that a power source, distinct from the main VDD power source, be available on the VBAT pin and that VDD be completely removed from the VDD pin(s). Removing VDD can be either unintentional, as in a power failure, or as part of a deliberate power reduction strategy. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2664 Note: Not all devices support all of the features discussed in this section. Please refer to specific device data sheet to determine the supported features for your device. Selective Peripheral Power Control Sleep and Idle modes allow users to substantially reduce power consumption by slowing or stopping the CPU clock. Even so, peripheral modules may still remain clocked, and thus, consume some amount of power.There may be cases where the application needs what these modes do not provide: the ability to allocate limited power resources to the CPU while eliminating power consumption from the peripherals. PIC microcontrollers address this requirement by allowing peripheral modules to be selectively enabled or disabled, reducing or eliminating their power consumption. In addition to the selective peripheral power control implemented as part of this library, devices will also include power saving features that are implemented in their specific libraries. These features include the ability to stop (shutdown) automatically when entering idle mode. On some peripherals the ability to continue operation in Sleep mode is available. Always review the libraries for the peripherals used by your application for specific and unique features that will help minimize power consumption. Disabling Peripheral Modules Most of the peripheral modules in the PIC microcontroller family architecture can be selectively disabled, reducing or essentially eliminating their power consumption during all operating modes. All peripheral modules (except for I/O ports) also have a Control bit that can disable their functionality.These bits, known as the Peripheral Module Disable (PMD) bits, are generically named: “xxMD”. These bits are located in the PMDx Special Function Registers (SFRs). In contrast to the module enable bits, the xxMD bit must be set to a '1' to disable the module. While the PMD and module enable bits both disable a peripheral’s functionality, the PMD bit completely shuts down the peripheral, effectively powering down all circuits and removing all clock sources. This has the additional effect of making any of the module’s control and buffer registers, mapped in the SFR space, unavailable for operations. In other words, when the PMD bit is used to disable a module, the peripheral ceases to exist until the PMD bit is cleared. The PMD bit is most useful in highly power-sensitive applications, where even tiny savings in power consumption can determine the ability of an application to function. In these cases, the bits can be set before the main body of the application to remove those peripherals that will not be needed. 5.6.18.4.2 Library Usage Model Note: The interface provided is a superset of all power functionality available on the device. Refer to the "Power-Saving Features" chapter in the specific device data sheet for availability. This library provides the low-level abstraction of the Power Controller module available on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. The library interface routines are divided into various subsections, each of the sub-sections addresses one of the blocks or the 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2665 overall operation of the Power Controller module. Library Interface Section Description Initialization Functions This section provides a set of functions for configuring the Power-Saving features and enabling or disabling the particular power feature. Status Functions This section provides a function to read the status of a particular power feature. Note: Not all modes are available on all devices. Refer to the "Power-Saving Features" chapter in the specific device data sheet for availability. 5.6.18.4.3 How the Library Works Usage of this library is partitioned into two major sections. Initialization The steps that are required to initialize the Power Controller module vary for different microcontrollers. Refer to the specific device data sheet to determine the correct initialization sequence. The following information provides a general overview. Power Source Setup • A module can be disabled for the microcontroller to be able to save power. Use the function PLIB_POWER_ModuleDisable to disable the particular module. POWER_MODULE_DISABLE provides a list of possible modules sources. • On most microcontrollers, the voltage regulator can be controlled during Sleep mode. It can be enabled (turned on) using PLIB_POWER_VoltageRegulatorEnable and disabled (turned off) using PLIB_POWER_VoltageRegulatorDisable. • On some microcontrollers, Deep Sleep mode is enabled using PLIB_POWER_DeepSleepModeEnable and Brown-out Reset in Deep Sleep mode is enabled using PLIB_POWER_DeepSleepBOREnable. The Deep Sleep mode is disabled using PLIB_POWER_DeepSleepModeDisable and Brown-out Reset in Deep Sleep mode is disabled using PLIB_POWER_DeepSleepBORDisable. Power Status Status of the particular power feature indicates the previous status of that feature. This feature can be used to determine whether the device was in Sleep or Idle mode before waking up. It also allows software to clear the previous status of the device. 5.6.18.5 Configuring the Library The library is configured for the supported Power Controller modules when the processor is chosen in the MPLAB IDE. 5.6.18.6 Library Interface Data Types and Constants Name Description POWER_MODULE List of the modules whose power can be controlled. POWER_MODULE_ID Identifies the supported Power modules. Feature Existence Functions Name Description PLIB_POWER_ExistsDeepSleepBOR Identifies whether the DeepSleepBORControl feature exists on the POWER module 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2666 PLIB_POWER_ExistsDeepSleepFaultDetect Identifies whether the DeepSleepFaultDetectStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepInterruptOnChange Identifies whether the DeepSleepIOCStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepMCLREvent Identifies whether the DeepSleepMCLRStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepMode Identifies whether the DeepSleepModeControl feature exists on the POWER module PLIB_POWER_ExistsDeepSleepPowerOnReset Identifies whether the DeepSleepPORStatus feature exists on the POWER module PLIB_POWER_ExistsIdleStatus Identifies whether the IdleStatus feature exists on the POWER module PLIB_POWER_ExistsPeripheralModuleControl Identifies whether the PeripheralModuleControl feature exists on the POWER module PLIB_POWER_ExistsSleepStatus Identifies whether the SleepStatus feature exists on the POWER module PLIB_POWER_ExistsVoltageRegulatorControl Identifies whether the VoltageRegulatorControl feature exists on the POWER module Initialization Functions Name Description PLIB_POWER_DeepSleepBORDisable Disables the Deep Sleep BOR. PLIB_POWER_DeepSleepBOREnable Enables the Deep Sleep BOR mode. PLIB_POWER_DeepSleepModeDisable Disables the Deep Sleep mode. PLIB_POWER_DeepSleepModeEnable Enables the Deep Sleep mode. PLIB_POWER_PeripheralModuleDisable Disable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleEnable Enable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleIsEnabled Check if selected peripheral is enabled or not PLIB_POWER_VoltageRegulatorDisable Disables the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorEnable Enable the voltage regulator during Sleep mode. Status Functions Name Description PLIB_POWER_ClearIdleStatus Clears the Idle mode status of the device. PLIB_POWER_ClearSleepStatus Clear the Sleep mode status bit of the device. PLIB_POWER_DeepSleepFaultDetectStatus Returns the status of Deep Sleep Fault Detect bit. PLIB_POWER_DeepSleepInterruptOnChangeStatus Returns the status of the Deep Sleep Interrupt-on-Change bit. PLIB_POWER_DeepSleepMCLREventStatus Returns the status of the Deep Sleep MCLR Event bit. PLIB_POWER_DeepSleepPowerOnResetStatus Returns the status of Deep Sleep Power-on Reset bit. PLIB_POWER_DeviceWasInIdleMode Returns the Idle mode status of the device. PLIB_POWER_DeviceWasInSleepMode Returns the Sleep mode status of the device. PLIB_POWER_VoltageRegulatorIsEnabled Provides the status of the voltage regulator during Sleep mode. Description This section lists and describes the functions, data types, and constants provided in the Power Peripheral Library. 5.6.18.6.1 Initialization Functions 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2667 5.6.18.6.1.1 PLIB_POWER_DeepSleepBORDisable Function C void PLIB_POWER_DeepSleepBORDisable( POWER_MODULE_ID index ); Description This function disables the Deep Sleep BOR. The Deep Sleep BOR is independent of the standard BOR and a Deep Sleep BOR event will not cause a wake-up from Deep Sleep. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepBOR in your application to determine whether this feature is available. Example PLIB_POWER_DeepSleepBORDisable(POWER_ID_0); 5.6.18.6.1.2 PLIB_POWER_DeepSleepBOREnable Function C void PLIB_POWER_DeepSleepBOREnable( POWER_MODULE_ID index ); Description This function enables the Deep Sleep BOR mode. The Deep Sleep BOR is ndependent of the standard BOR and a Deep Sleep BOR event will not cause a wake-up from Deep Sleep. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepBOR in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2668 Example PLIB_POWER_DeepSleepBOREnable(POWER_ID_0); 5.6.18.6.1.3 PLIB_POWER_DeepSleepModeDisable Function C void PLIB_POWER_DeepSleepModeDisable( POWER_MODULE_ID index ); Description This function disables the Deep Sleep mode. Deep Sleep mode is intended to provide the lowest levels of power consumption available without requiring the use of external switches to completely remove all power from the device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepMode in your application to determine whether this feature is available. Example PLIB_POWER_DeepSleepModeDisable(POWER_ID_0); 5.6.18.6.1.4 PLIB_POWER_DeepSleepModeEnable Function C void PLIB_POWER_DeepSleepModeEnable( POWER_MODULE_ID index ); Description This function enables the Deep Sleep mode. Deep Sleep mode is intended to provide the lowest levels of power consumption available without requiring the use of external switches to completely remove all power from the device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2669 PLIB_POWER_ExistsDeepSleepMode in your application to determine whether this feature is available. Example PLIB_POWER_DeepSleepModeEnable(POWER_ID_0); 5.6.18.6.1.5 PLIB_POWER_PeripheralModuleDisable Function C void PLIB_POWER_PeripheralModuleDisable( POWER_MODULE_ID index, POWER_MODULE source ); Description This function completely shuts down the selected peripheral, effectively powering down all circuits and removing all clock sources. This has the additional effect of making any of the module’s control and buffer registers, which are mapped in the SFR space, unavailable for operations. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be disabled from POWER_MODULE enum Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Example PLIB_POWER_PeripheralModuleDisable (POWER_ID_0, POWER_MODULE_ADC); 5.6.18.6.1.6 PLIB_POWER_PeripheralModuleEnable Function C void PLIB_POWER_PeripheralModuleEnable( POWER_MODULE_ID index, POWER_MODULE source ); Description This function enables the power supply back to the selected module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be enabled from POWER_MODULE enum 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2670 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Example PLIB_POWER_PeripheralModuleEnable (POWER_ID_0, POWER_MODULE_ADC); 5.6.18.6.1.7 PLIB_POWER_PeripheralModuleIsEnabled Function C bool PLIB_POWER_PeripheralModuleIsEnabled( POWER_MODULE_ID index, POWER_MODULE source ); Description This function checks if selected peripheral is enabled or not. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source Select the module to be enabled from POWER_MODULE enum Returns • true - Power of the selected peripheral is enabled • false - Power of the selected peripheral is disabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsPeripheralModuleControl in your application to determine whether this feature is available. Example if (PLIB_POWER_PeripheralModuleIsEnabled ( POWER_MODULE_0, POWER_MODULE_ADC )) { } 5.6.18.6.1.8 PLIB_POWER_VoltageRegulatorDisable Function C void PLIB_POWER_VoltageRegulatorDisable( POWER_MODULE_ID index ); Description This function disables the voltage regulator into during Sleep mode for the selected device. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2671 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Example PLIB_POWER_VoltageRegulatorDisable(POWER_ID_0); 5.6.18.6.1.9 PLIB_POWER_VoltageRegulatorEnable Function C void PLIB_POWER_VoltageRegulatorEnable( POWER_MODULE_ID index ); Description This function enables the voltage regulator during Sleep mode for the selected device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Example PLIB_POWER_VoltageRegulatorEnable(POWER_ID_0); 5.6.18.6.2 Status Functions 5.6.18.6.2.1 PLIB_POWER_ClearIdleStatus Function C void PLIB_POWER_ClearIdleStatus( POWER_MODULE_ID index ); Description This function clears the Idle status bit of the device if it was previously in Idle mode. However, it does not mean that it wakes up the device from Idle. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2672 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsIdleStatus in your application to determine whether this feature is available. Example if(PLIB_POWER_DeviceWasInIdleMode(POWER_ID_0)) { PLIB_POWER_ClearIdleStatus (POWER_ID_0); } 5.6.18.6.2.2 PLIB_POWER_ClearSleepStatus Function C void PLIB_POWER_ClearSleepStatus( POWER_MODULE_ID index ); Description This function clears the Sleep status bit of the device if it was previously in Sleep mode. However, it does not mean that it wakes up the device from sleep. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsSleepStatus in your application to determine whether this feature is available. Example if(PLIB_POWER_DeviceWasInSleepMode(POWER_ID_0)) { PLIB_POWER_ClearSleepStatus (POWER_ID_0); } 5.6.18.6.2.3 PLIB_POWER_DeepSleepFaultDetectStatus Function C bool PLIB_POWER_DeepSleepFaultDetectStatus( 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2673 POWER_MODULE_ID index ); Description This function returns the status of the Deep Sleep Fault Detect bit. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns true - A Fault occurred during Deep Sleep, and some Deep Sleep configuration settings may have been corrupted false - No Fault was detected during Deep Sleep Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepFaultDetect in your application to determine whether this feature is available. Example if(PLIB_POWER_DeepSleepFaultDetectStatus(POWER_ID_0)) { } 5.6.18.6.2.4 PLIB_POWER_DeepSleepInterruptOnChangeStatus Function C bool PLIB_POWER_DeepSleepInterruptOnChangeStatus( POWER_MODULE_ID index ); Description This function returns the status of the Deep Sleep Interrupt-on-Change bit. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Interrupt-on-Change was asserted during Deep Sleep • false - Interrupt-on-Change was not asserted during Deep Sleep Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepInterruptOnChange in your application to determine whether this feature is available. Example if(PLIB_POWER_DeepSleepInterruptOnChangeStatus(POWER_ID_0)) { 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2674 } 5.6.18.6.2.5 PLIB_POWER_DeepSleepMCLREventStatus Function C bool PLIB_POWER_DeepSleepMCLREventStatus( POWER_MODULE_ID index ); Description This function returns the status of the Deep Sleep MCLR Event bit. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The MCLR pin was active and was asserted during Deep Sleep • false - The MCLR pin was not active, or was active, but not asserted during Deep Sleep Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsDeepSleepMCLREvent in your application to determine whether this feature is available. Example if(PLIB_POWER_DeepSleepMCLREventStatus(POWER_ID_0)) { } 5.6.18.6.2.6 PLIB_POWER_DeepSleepPowerOnResetStatus Function C bool PLIB_POWER_DeepSleepPowerOnResetStatus( POWER_MODULE_ID index ); Description This function returns the status of the Deep Sleep Power-on Reset bit. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The VDD supply POR circuit was active and a POR event was detected • false - The VDD supply POR circuit was not active, or was active but did not detect a POR event Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2675 PLIB_POWER_ExistsDeepSleepPowerOnReset in your application to determine whether this feature is available. Example if(PLIB_POWER_DeepSleepPowerOnResetStatus(POWER_ID_0)) { } 5.6.18.6.2.7 PLIB_POWER_DeviceWasInIdleMode Function C bool PLIB_POWER_DeviceWasInIdleMode( POWER_MODULE_ID index ); Description This function returns the Idle mode status of the device. It tells whether or not the device was in Idle mode before waking up. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The device was in Idle mode before waking up • false - The device was not in Idle mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsIdleStatus in your application to determine whether this feature is available. Example if(PLIB_POWER_DeviceWasInIdleMode(POWER_ID_0)) { } 5.6.18.6.2.8 PLIB_POWER_DeviceWasInSleepMode Function C bool PLIB_POWER_DeviceWasInSleepMode( POWER_MODULE_ID index ); Description This function returns the Sleep mode status of the device. It tells whether or not the device was in Sleep mode before waking up. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2676 Returns • true - The device was in Sleep mode before waking up • false - The device was not in Sleep mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsSleepStatus in your application to determine whether this feature is available. Example if(PLIB_POWER_DeviceWasInSleepMode(POWER_ID_0)) { } 5.6.18.6.2.9 PLIB_POWER_VoltageRegulatorIsEnabled Function C bool PLIB_POWER_VoltageRegulatorIsEnabled( POWER_MODULE_ID index ); Description This function provides the status of the voltage regulator during Sleep mode for the selected device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The voltage regulator will be enabled in Sleep mode • false - The voltage regulator will be disabled in Sleep mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_POWER_ExistsVoltageRegulatorControl in your application to determine whether this feature is available. Example if (PLIB_POWER_VoltageRegulatorIsEnabled(POWER_ID_0)) { } 5.6.18.6.3 Data Types and Constants 5.6.18.6.3.1 POWER_MODULE Enumeration C typedef enum { POWER_MODULE_ADC1, POWER_MODULE_CTMU, POWER_MODULE_CVR, 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2677 POWER_MODULE_CMP1 , POWER_MODULE_CMP2 , POWER_MODULE_CMP3 , POWER_MODULE_IC1 , POWER_MODULE_IC2 , POWER_MODULE_IC3 , POWER_MODULE_IC4 , POWER_MODULE_IC5 , POWER_MODULE_IC6 , POWER_MODULE_IC7 , POWER_MODULE_IC8 , POWER_MODULE_IC9 , POWER_MODULE_OC1 , POWER_MODULE_OC2 , POWER_MODULE_OC3 , POWER_MODULE_OC4 , POWER_MODULE_OC5 , POWER_MODULE_OC6 , POWER_MODULE_OC7 , POWER_MODULE_OC8 , POWER_MODULE_OC9 , POWER_MODULE_TMR1 , POWER_MODULE_TMR2 , POWER_MODULE_TMR3 , POWER_MODULE_TMR4 , POWER_MODULE_TMR5 , POWER_MODULE_TMR6 , POWER_MODULE_TMR7 , POWER_MODULE_TMR8 , POWER_MODULE_TMR9 , POWER_MODULE_UART1 , POWER_MODULE_UART2 , POWER_MODULE_UART3 , POWER_MODULE_UART4 , POWER_MODULE_UART5 , POWER_MODULE_UART6 , POWER_MODULE_SPI1 , POWER_MODULE_SPI2 , POWER_MODULE_SPI3 , POWER_MODULE_SPI4 , POWER_MODULE_SPI5 , POWER_MODULE_SPI6 , POWER_MODULE_I2C1 , POWER_MODULE_I2C2 , POWER_MODULE_I2C3 , POWER_MODULE_I2C4 , POWER_MODULE_I2C5 , POWER_MODULE_USB , POWER_MODULE_CAN1 , POWER_MODULE_CAN2 , POWER_MODULE_RTCC , POWER_MODULE_REF_CLK_OUTPUT , POWER_MODULE_REF_CLK_OUTPUT1 , POWER_MODULE_REF_CLK_OUTPUT2 , POWER_MODULE_REF_CLK_OUTPUT3 , POWER_MODULE_REF_CLK_OUTPUT4 , POWER_MODULE_PMP , POWER_MODULE_EBI , POWER_MODULE_SQI , POWER_MODULE_ETHERNET , POWER_MODULE_DMA , POWER_MODULE_RANDOM_NUM_GENERATOR , POWER_MODULE_CRYPTO } POWER_MODULE; 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2678 Description POWER module enumeration This enumeration lists the modules whose power can be controlled by PMD registers Members Members Description POWER_MODULE_ADC1 ADC module POWER_MODULE_CTMU Charge Time Measurement Unit module POWER_MODULE_CVR Comparator Voltage Reference module POWER_MODULE_CMP1 Comparator module 1 POWER_MODULE_CMP2 Comparator module 2 POWER_MODULE_CMP3 Comparator module 3 POWER_MODULE_IC1 Input Capture 1 module POWER_MODULE_IC2 Input Capture 2 module POWER_MODULE_IC3 Input Capture 3 module POWER_MODULE_IC4 Input Capture 4 module POWER_MODULE_IC5 Input Capture 5 module POWER_MODULE_IC6 Input Capture 6 module POWER_MODULE_IC7 Input Capture 7 module POWER_MODULE_IC8 Input Capture 8 module POWER_MODULE_IC9 Input Capture 9 module POWER_MODULE_OC1 Output Compare 1 module POWER_MODULE_OC2 Output Compare 2 module POWER_MODULE_OC3 Output Compare 3 module POWER_MODULE_OC4 Output Compare 4 module POWER_MODULE_OC5 Output Compare 5 module POWER_MODULE_OC6 Output Compare 6 module POWER_MODULE_OC7 Output Compare 7 module POWER_MODULE_OC8 Output Compare 8 module POWER_MODULE_OC9 Output Compare 9 module POWER_MODULE_TMR1 Timer1 module POWER_MODULE_TMR2 Timer2 module POWER_MODULE_TMR3 Timer3 module POWER_MODULE_TMR4 Timer4 module POWER_MODULE_TMR5 Timer5 module POWER_MODULE_TMR6 Timer6 module POWER_MODULE_TMR7 Timer7 module POWER_MODULE_TMR8 Timer8 module POWER_MODULE_TMR9 Timer9 module POWER_MODULE_UART1 UART1 module POWER_MODULE_UART2 UART2 module POWER_MODULE_UART3 UART3 module POWER_MODULE_UART4 UART4 module POWER_MODULE_UART5 UART5 module POWER_MODULE_UART6 UART6 module 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2679 POWER_MODULE_SPI1 SPI1 module POWER_MODULE_SPI2 SPI2 module POWER_MODULE_SPI3 SPI3 module POWER_MODULE_SPI4 SPI4 module POWER_MODULE_SPI5 SPI5 module POWER_MODULE_SPI6 SPI6 module POWER_MODULE_I2C1 I2C1 module POWER_MODULE_I2C2 I2C2 module POWER_MODULE_I2C3 I2C3 module POWER_MODULE_I2C4 I2C4 module POWER_MODULE_I2C5 I2C5 module POWER_MODULE_USB USB module POWER_MODULE_CAN1 CAN1 module POWER_MODULE_CAN2 CAN2 module POWER_MODULE_RTCC RealTime Clock and Calender module POWER_MODULE_REF_CLK_OUTPUT Reference Clock Output module POWER_MODULE_REF_CLK_OUTPUT1 Reference Clock Output module 1 POWER_MODULE_REF_CLK_OUTPUT2 Reference Clock Output module 2 POWER_MODULE_REF_CLK_OUTPUT3 Reference Clock Output module 3 POWER_MODULE_REF_CLK_OUTPUT4 Reference Clock Output module 4 POWER_MODULE_PMP Parallel Master Port module POWER_MODULE_EBI External Bus Interface module POWER_MODULE_SQI Serial Quad Interface module POWER_MODULE_ETHERNET Ethernet module POWER_MODULE_DMA Data Memory Access module POWER_MODULE_RANDOM_NUM_GENERATOR Random Number Generator module POWER_MODULE_CRYPTO Cryptographic module Remarks Not all modules exist in all devices. Please refer to the specific device data sheet for availability. 5.6.18.6.3.2 POWER_MODULE_ID Enumeration C typedef enum { POWER_ID_0, POWER_NUMBER_OF_MODULES } POWER_MODULE_ID; Description Power Module ID This enumeration identifies the Power modules that are available on the microcontroller. This is the superset of all the possible instances that might be available on a Microchip microcontroller. Members Members Description POWER_ID_0 POWER Module ID POWER_NUMBER_OF_MODULES Number of available POWER modules. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2680 Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the "Power-Saving Features" chapter in the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers provided in the data sheet. 5.6.18.6.4 Feature Existence Functions 5.6.18.6.4.1 PLIB_POWER_ExistsDeepSleepBOR Function C bool PLIB_POWER_ExistsDeepSleepBOR( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepBORControl feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepBOREnable • PLIB_POWER_DeepSleepBORDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepBORControl feature is supported on the device • false - The DeepSleepBORControl feature is not supported on the device Remarks None. 5.6.18.6.4.2 PLIB_POWER_ExistsDeepSleepFaultDetect Function C bool PLIB_POWER_ExistsDeepSleepFaultDetect( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepFaultDetectStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepFaultDetectStatus Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2681 Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepFaultDetectStatus feature is supported on the device • false - The DeepSleepFaultDetectStatus feature is not supported on the device Remarks None. 5.6.18.6.4.3 PLIB_POWER_ExistsDeepSleepInterruptOnChange Function C bool PLIB_POWER_ExistsDeepSleepInterruptOnChange( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepIOCStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepInterruptOnChangeStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepIOCStatus feature is supported on the device • false - The DeepSleepIOCStatus feature is not supported on the device Remarks None. 5.6.18.6.4.4 PLIB_POWER_ExistsDeepSleepMCLREvent Function C bool PLIB_POWER_ExistsDeepSleepMCLREvent( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepMCLRStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepMCLREventStatus Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2682 Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepMCLRStatus feature is supported on the device • false - The DeepSleepMCLRStatus feature is not supported on the device Remarks None. 5.6.18.6.4.5 PLIB_POWER_ExistsDeepSleepMode Function C bool PLIB_POWER_ExistsDeepSleepMode( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepModeControl feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepModeEnable • PLIB_POWER_DeepSleepModeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepModeControl feature is supported on the device • false - The DeepSleepModeControl feature is not supported on the device Remarks None. 5.6.18.6.4.6 PLIB_POWER_ExistsDeepSleepPowerOnReset Function C bool PLIB_POWER_ExistsDeepSleepPowerOnReset( POWER_MODULE_ID index ); Description This function identifies whether the DeepSleepPORStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeepSleepPowerOnResetStatus 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2683 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DeepSleepPORStatus feature is supported on the device • false - The DeepSleepPORStatus feature is not supported on the device Remarks None. 5.6.18.6.4.7 PLIB_POWER_ExistsIdleStatus Function C bool PLIB_POWER_ExistsIdleStatus( POWER_MODULE_ID index ); Description This function identifies whether the IdleStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeviceWasInIdleMode • PLIB_POWER_ClearIdleStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The IdleStatus feature is supported on the device • false - The IdleStatus feature is not supported on the device Remarks None. 5.6.18.6.4.8 PLIB_POWER_ExistsPeripheralModuleControl Function C bool PLIB_POWER_ExistsPeripheralModuleControl( POWER_MODULE_ID index ); Description This function identifies whether the PeripheralModuleControl feature is available on the POWER module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2684 • PLIB_POWER_PeripheralModuleDisable • PLIB_POWER_PeripheralModuleEnable • PLIB_POWER_PeripheralModuleIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PeripheralModuleControl feature is supported on the device • false - The PeripheralModuleControl feature is not supported on the device Remarks None. 5.6.18.6.4.9 PLIB_POWER_ExistsSleepStatus Function C bool PLIB_POWER_ExistsSleepStatus( POWER_MODULE_ID index ); Description This function identifies whether the SleepStatus feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_DeviceWasInSleepMode • PLIB_POWER_ClearSleepStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SleepStatus feature is supported on the device • false - The SleepStatus feature is not supported on the device Remarks None. 5.6.18.6.4.10 PLIB_POWER_ExistsVoltageRegulatorControl Function C bool PLIB_POWER_ExistsVoltageRegulatorControl( POWER_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2685 Description This function identifies whether the VoltageRegulatorControl feature is available on the POWER module. When this function returns true, these functions are supported on the device: • PLIB_POWER_VoltageRegulatorEnable • PLIB_POWER_VoltageRegulatorDisable • PLIB_POWER_VoltageRegulatorIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The VoltageRegulatorControl feature is supported on the device • false - The VoltageRegulatorControl feature is not supported on the device Remarks None. 5.6.18.7 Files Files Name Description plib_power.h Defines the Power Peripheral Library interface. Description 5.6.18.7.1 plib_power.h Power Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Power Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Power Controller module. Functions Name Description PLIB_POWER_ClearIdleStatus Clears the Idle mode status of the device. PLIB_POWER_ClearSleepStatus Clear the Sleep mode status bit of the device. PLIB_POWER_DeepSleepBORDisable Disables the Deep Sleep BOR. PLIB_POWER_DeepSleepBOREnable Enables the Deep Sleep BOR mode. PLIB_POWER_DeepSleepFaultDetectStatus Returns the status of Deep Sleep Fault Detect bit. PLIB_POWER_DeepSleepInterruptOnChangeStatus Returns the status of the Deep Sleep Interrupt-on-Change bit. PLIB_POWER_DeepSleepMCLREventStatus Returns the status of the Deep Sleep MCLR Event bit. PLIB_POWER_DeepSleepModeDisable Disables the Deep Sleep mode. 5.6 Peripheral Library Help MPLAB Harmony Help Power Peripheral Library 5-2686 PLIB_POWER_DeepSleepModeEnable Enables the Deep Sleep mode. PLIB_POWER_DeepSleepPowerOnResetStatus Returns the status of Deep Sleep Power-on Reset bit. PLIB_POWER_DeviceWasInIdleMode Returns the Idle mode status of the device. PLIB_POWER_DeviceWasInSleepMode Returns the Sleep mode status of the device. PLIB_POWER_ExistsDeepSleepBOR Identifies whether the DeepSleepBORControl feature exists on the POWER module PLIB_POWER_ExistsDeepSleepFaultDetect Identifies whether the DeepSleepFaultDetectStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepInterruptOnChange Identifies whether the DeepSleepIOCStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepMCLREvent Identifies whether the DeepSleepMCLRStatus feature exists on the POWER module PLIB_POWER_ExistsDeepSleepMode Identifies whether the DeepSleepModeControl feature exists on the POWER module PLIB_POWER_ExistsDeepSleepPowerOnReset Identifies whether the DeepSleepPORStatus feature exists on the POWER module PLIB_POWER_ExistsIdleStatus Identifies whether the IdleStatus feature exists on the POWER module PLIB_POWER_ExistsPeripheralModuleControl Identifies whether the PeripheralModuleControl feature exists on the POWER module PLIB_POWER_ExistsSleepStatus Identifies whether the SleepStatus feature exists on the POWER module PLIB_POWER_ExistsVoltageRegulatorControl Identifies whether the VoltageRegulatorControl feature exists on the POWER module PLIB_POWER_PeripheralModuleDisable Disable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleEnable Enable the power supply for the module selected in the source. PLIB_POWER_PeripheralModuleIsEnabled Check if selected peripheral is enabled or not PLIB_POWER_VoltageRegulatorDisable Disables the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorEnable Enable the voltage regulator during Sleep mode. PLIB_POWER_VoltageRegulatorIsEnabled Provides the status of the voltage regulator during Sleep mode. File Name plib_power.h Company Microchip Technology Inc. 5.6.19 Reset Peripheral Library 5.6.19.1 Introduction Reset Peripheral Library 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2687 for Microchip Microcontrollers This library provides a low-level abstraction of the Reset Controller modules on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Reset Controller Overview The Reset Controller is a key component of a microcontroller. The Reset Controller gives the reset status of the device at any point of time. The following are the key features present on a Reset Controller: • Reset Source Configuration: Provides the ability to enable and disable a source that may reset the device • Reset Status: Identifies the source of a reset and clears it A microcontroller can support one or more of the above reset modes. Please refer to the the "Resets" chapter in the specific device data sheet to determine the exact set of supported features. 5.6.19.2 Release Notes MPLAB Harmony Version: v0.70b Reset Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.19.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2688 5.6.19.4 Using the Library This topic describes the basic architecture of the Reset Peripheral Library and provides information and examples on how to use it. Description Interface Header File: plib_reset.h The interface to the Reset Peripheral Library is defined in the "plib_reset.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the Reset Peripheral Library must include "peripheral.h". Peripheral Module IDs Peripheral libraries are indexed to allow a single library to control any number of instances of a peripheral in a single microcontroller. To support this, the first parameter to each operation in a peripheral library is the module instance ID. The module instance ID is defined by an enumeration that is defined in the processor-specific header files (included by the library's interface header). Not all microcontrollers will have all instances of the module listed in this enumeration. Please refer to the "Resets" chapter in the specific device data sheet for availability. 5.6.19.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the Reset Controller module on Microchip PIC microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The following figure illustrates the hardware abstraction model for the Reset Peripheral Library. Hardware Abstraction Model The Reset Controller receives requests from multiple Reset Sources. The Reset Controller controls the overall operation of the reset controller. Source Enable Configuration enables or disables a particular source of reset. Some of the reset sources such as Traps are not 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2689 controlled by the users, whereas others can be user controlled. Note: Not all features are available on all devices. Refer to the "Resets" chapter in the specific device data sheet for availability 5.6.19.4.2 Library Architecture This library provides the low-level abstraction of the Reset module available on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. The library interface routines are divided into various subsections, each of the subsection addresses one of the blocks or the overall operation of the Reset Controller module. Library Interface Section Description Initialization Functions This section provides a set of functions for configuring and enabling a reset. Status Functions This section provides a function to read the status of a particular reset. Note: Not all modes are available on all devices. Refer to the "Resets" chapter in the specific device data sheet for availability. 5.6.19.4.3 How the Library Works Initialization The steps that are required to initialize the Reset Controller module vary for different microcontrollers. Refer to the "Resets" chapter in the specific device data sheet for the correct initialization sequence. The following information provides a general overview. Description Reset Source Setup Some reset sources need to be enabled for it to be able to Reset the device. Use the function PLIB_RESET_SoftwareResetEnable to enable the reset source. Reset Status The status of the reset indicates which source generated the reset. The status of the reset source can be obtained using the function PLIB_RESET_ReasonGet. The reason for the reset can be cleared using the function PLIB_RESET_ReasonClear. 5.6.19.5 Configuring the Library The library is configured for the supported Reset Controller modules when the processor is chosen in the MPLAB IDE. 5.6.19.6 Library Interface Data Types and Constants Name Description RESET_MODULE_ID Identifies the supported Reset modules. RESET_CONFIG_REG_READ_ERROR Lists the reset sources. RESET_NMI_COUNT_TYPE Defines NMI counter data type RESET_NMI_REASON Lists the NMI reasons. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2690 Feature Existence Functions Name Description PLIB_RESET_ExistsResetReasonStatus Identifies whether the ResetReasonStatus feature exists on the RESET module PLIB_RESET_ExistsSoftwareResetTrigger Identifies whether the SoftwareResetTrigger feature exists on the RESET module PLIB_RESET_ExistsConfigRegReadError Identifies whether the ConfigRegReadError feature exists on the RESET module PLIB_RESET_ExistsNmiControl Identifies whether the NmiControl feature exists on the RESET module PLIB_RESET_ExistsNmiCounter Identifies whether the NmiCounter feature exists on the RESET module PLIB_RESET_ExistsWdtoInSleep Identifies whether the WdtoInSleep feature exists on the RESET module Initialization Functions Name Description PLIB_RESET_SoftwareResetEnable Enables the software reset. Status Functions Name Description PLIB_RESET_ReasonClear Clears the RCON register. PLIB_RESET_ReasonGet Returns the reason for a reset. PLIB_RESET_ConfigRegReadErrorGet Get the Configuration Register Read Error PLIB_RESET_WdtTimeOutHasOccurredInSleep Returns the state of the device when WDT time-out occurred Description This section lists and describes the functions, data types, and constants provided in the Reset Peripheral Library. 5.6.19.6.1 Initialization Functions 5.6.19.6.1.1 PLIB_RESET_SoftwareResetEnable Function C void PLIB_RESET_SoftwareResetEnable( RESET_MODULE_ID index ); Description This function enables the software reset. The system unlock sequence, which must be performed to enable this feature, is done internally in this function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2691 Remarks This function implements an operation of the SoftwareResetTrigger feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsSoftwareResetTrigger function in your application to determine whether this feature is available. Example PLIB_RESET_SoftwareResetEnable( RESET_ID_0 ); 5.6.19.6.2 Status Functions 5.6.19.6.2.1 PLIB_RESET_ReasonClear Function C void PLIB_RESET_ReasonClear( RESET_MODULE_ID index, RESET_REASON reason ); Description This function clears the particular reset bit in the RCON register. Multiple reasons for a reset can be ORed together and given as an input parameter to clear them simultaneously. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured reason Select the reset type from enum RESET_REASON Returns None Remarks This function implements an operation of the ResetReasonStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsResetReasonStatus function in your application to determine whether this feature is available. Example PLIB_RESET_ReasonClear( RESET_ID_0, RESET_REASON_MCLR | RESET_REASON_POWERON ); 5.6.19.6.2.2 PLIB_RESET_ReasonGet Function C RESET_REASON PLIB_RESET_ReasonGet( RESET_MODULE_ID index ); Description This function returns the reason a reset has occurred for the selected device. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2692 Parameters Parameters Description index Identifier for the device instance to be configured Returns RESET_REASON - Type of reset (when there is more than one reason for a reset, this function will logically OR (bitwise) the reasons and return the value. Remarks This function implements an operation of the ResetReasonStatus feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsResetReasonStatus function in your application to determine whether this feature is available. Example RESET_REASON type; type = PLIB_RESET_ReasonGet ( RESET_ID_0 ); 5.6.19.6.2.3 PLIB_RESET_ConfigRegReadErrorGet Function C RESET_CONFIG_REG_READ_ERROR PLIB_RESET_ConfigRegReadErrorGet( RESET_MODULE_ID index ); Description This function gets the Configuration register read error, if any, after the reset Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns RESET_CONFIG_REG_READ_ERROR - Type of Config Register Read Error Remarks This function implements an operation of the ConfigRegReadError feature. This feature may not be available on all devices. Refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsConfigRegReadError function in your application to determine whether this feature is available. Example if (PLIB_RESET_ConfigRegReadErrorGet( RESET_ID_0 )== PRIMARY_CONFIG_REG_READ_ERROR ) { //Do Something } 5.6.19.6.2.4 PLIB_RESET_WdtTimeOutHasOccurredInSleep Function C bool PLIB_RESET_WdtTimeOutHasOccurredInSleep( RESET_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2693 Description This function returns if device was in sleep or not when WDT time-out event occurred. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True - device was in sleep mode when WDT time-out occurred False - device was not in sleep mode when WDT time-out occurred Remarks This function implements an operation of the WdtoInSleep feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsWdtoInSleep function in your application to determine whether this feature is available. Example if (PLIB_RESET_WdtTimeOutHasOccurredInSleep( RESET_ID_0 )) { //Do Something } 5.6.19.6.3 Data Types and Constants 5.6.19.6.3.1 RESET_MODULE_ID Enumeration C typedef enum { RESET_ID_0 } RESET_MODULE_ID; Description Reset Module ID This enumeration identifies the Reset modules that are available on the microcontroller. This is the superset of all the possible instances that might be available on a Microchip microcontroller. Members Members Description RESET_ID_0 RESET Module ID 0 Remarks Caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules are available on all devices. Refer to the "Resets" chapter in the specific device data sheet to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2694 5.6.19.6.3.2 RESET_CONFIG_REG_READ_ERROR Enumeration C typedef enum { RESET_REASON_POWERON, RESET_REASON_BROWNOUT, RESET_REASON_WDT_TIMEOUT, RESET_REASON_SOFTWARE, RESET_REASON_MCLR, RESET_REASON_CONFIG_MISMATCH, RESET_REASON_HIGH_VOLTAGE_DETECT, PRIMARY_CONFIG_REG_READ_ERROR, PRIMARY_AND_ALTERNATIVE_CONFIG_REG_READ_ERROR, NO_CONFIG_REG_READ_ERROR } RESET_CONFIG_REG_READ_ERROR; Description RESET source select enumeration This enumeration lists the possible reset sources. Members Members Description RESET_REASON_POWERON The last reset was a power on reset RESET_REASON_BROWNOUT The last reset was a brown out reset RESET_REASON_WDT_TIMEOUT The last reset was a watch dog timer time-out reset RESET_REASON_SOFTWARE The last reset was a software reset RESET_REASON_MCLR The last reset was a master clear(MCLR) reset RESET_REASON_CONFIG_MISMATCH The last reset was a configuration mismatch reset RESET_REASON_HIGH_VOLTAGE_DETECT The last reset was high voltage detect reset PRIMARY_CONFIG_REG_READ_ERROR An error occurred during the read of primary configuration registers PRIMARY_AND_ALTERNATIVE_CONFIG_REG_READ_ERROR An error occurred during the read of primary and alternate configuration register NO_CONFIG_REG_READ_ERROR No error occurred during the read of configuration registers Remarks Not all reset sources exist on all devices. Please refer to the specific device data sheet for availability. 5.6.19.6.3.3 RESET_NMI_COUNT_TYPE Type C typedef unsigned char RESET_NMI_COUNT_TYPE; Description RESET_NMI_COUNT_TYPE data type It defines NMI counter data type 5.6.19.6.3.4 RESET_NMI_REASON Enumeration C typedef enum { WDTO_NMI, 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2695 DMTO_NMI, SOFTWARE_NMI, CF_NMI, WDTS_NMI } RESET_NMI_REASON; Description NMI Reason enumeration This enumeration lists the possible NMI sources. Members Members Description WDTO_NMI Watch Dog Timer time-out has caused NMI DMTO_NMI Deadman Timer time-out has caused NMI SOFTWARE_NMI Software trigger has caused NMI CF_NMI Clock Failure has caused NMI WDTS_NMI Watch Dog Timer in Sleep has caused NMI Remarks Not all NMI sources exist on all devices. Please refer to the specific device data sheet for availability. 5.6.19.6.4 Feature Existence Functions 5.6.19.6.4.1 PLIB_RESET_ExistsResetReasonStatus Function C bool PLIB_RESET_ExistsResetReasonStatus( RESET_MODULE_ID index ); Description This function identifies whether the ResetReasonStatus feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_ReasonGet • PLIB_RESET_ReasonClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ResetReasonStatus feature is supported on the device • false - The ResetReasonStatus feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2696 5.6.19.6.4.2 PLIB_RESET_ExistsSoftwareResetTrigger Function C bool PLIB_RESET_ExistsSoftwareResetTrigger( RESET_MODULE_ID index ); Description This function identifies whether the SoftwareResetTrigger feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_SoftwareResetEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SoftwareResetTrigger feature is supported on the device • false - The SoftwareResetTrigger feature is not supported on the device Remarks None. 5.6.19.6.4.3 PLIB_RESET_ExistsConfigRegReadError Function C bool PLIB_RESET_ExistsConfigRegReadError( RESET_MODULE_ID index ); Description This function identifies whether the ConfigRegReadError feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_ConfigRegReadErrorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ConfigRegReadError feature is supported on the device • false - The ConfigRegReadError feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2697 5.6.19.6.4.4 PLIB_RESET_ExistsNmiControl Function C bool PLIB_RESET_ExistsNmiControl( RESET_MODULE_ID index ); Description This function identifies whether the NmiControl feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_NmiReasonGet • PLIB_RESET_NmiEventTrigger • PLIB_RESET_NmiEventClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The NmiControl feature is supported on the device • false - The NmiControl feature is not supported on the device Remarks None. 5.6.19.6.4.5 PLIB_RESET_ExistsNmiCounter Function C bool PLIB_RESET_ExistsNmiCounter( RESET_MODULE_ID index ); Description This function identifies whether the NmiCounter feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_NmiCounterValueSet • PLIB_RESET_NmiCounterValueGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The NmiCounter feature is supported on the device • false - The NmiCounter feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2698 Remarks None. 5.6.19.6.4.6 PLIB_RESET_ExistsWdtoInSleep Function C bool PLIB_RESET_ExistsWdtoInSleep( RESET_MODULE_ID index ); Description This function identifies whether the WdtoInSleep feature is available on the RESET module. When this function returns true, these functions are supported on the device: • PLIB_RESET_WdtTimeOutHasOccurredInSleep Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WdtoInSleep feature is supported on the device • false - The WdtoInSleep feature is not supported on the device Remarks None. 5.6.19.6.5 NMI Events Functions Functions Name Description PLIB_RESET_NmiCounterValueGet Gets the NMI counter value PLIB_RESET_NmiCounterValueSet Sets the NMI counter PLIB_RESET_NmiEventClear Clears the NMI event PLIB_RESET_NmiEventTrigger Triggers the NMI event PLIB_RESET_NmiReasonGet Returns the reason for NMI Description 5.6.19.6.5.1 PLIB_RESET_NmiCounterValueGet Function C RESET_NMI_COUNT_TYPE PLIB_RESET_NmiCounterValueGet( RESET_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2699 Description This function returns the NMI Reset counter value Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns nmi_count - NMI counter value Remarks This function implements an operation of the NmiCounter feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiCounter function in your application to determine whether this feature is available. Example RESET_NMI_COUNT_TYPE nmi_count; nmi_count = PLIB_RESET_NmiCounterValueGet( RESET_ID_0); 5.6.19.6.5.2 PLIB_RESET_NmiCounterValueSet Function C void PLIB_RESET_NmiCounterValueSet( RESET_MODULE_ID index, RESET_NMI_COUNT_TYPE nmi_count ); Description This function sets the NMI counter which needs to be expired for WDT or DMT reset Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured nmi_count -NMI counter value Returns None Remarks This function implements an operation of the NmiCounter feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiCounter function in your application to determine whether this feature is available. Example PLIB_RESET_NmiCounterValueSet( RESET_ID_0, 0x54); 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2700 5.6.19.6.5.3 PLIB_RESET_NmiEventClear Function C void PLIB_RESET_NmiEventClear( RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason ); Description This function clears the Non-Maskable-Interrupt (NMI) event. if WDTO or DMTO NMI event is cleared before NMI counter reaches zero, then no device reset is asserted. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured nmi_reason sets of reasons which can cause NMI Returns None Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Example PLIB_RESET_NmiEventClear( RESET_ID_0, WDTO_NMI ); 5.6.19.6.5.4 PLIB_RESET_NmiEventTrigger Function C void PLIB_RESET_NmiEventTrigger( RESET_MODULE_ID index, RESET_NMI_REASON nmi_reason ); Description This function triggers the Non-Maskable-Interrupt (NMI). In case of DMT or WDT NMI event, it will also trigger NMI counter to start the count down. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured nmi_reason sets of reasons which can cause NMI Returns None 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2701 Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Example PLIB_RESET_NmiEventTrigger( RESET_ID_0, WDTO_NMI ); 5.6.19.6.5.5 PLIB_RESET_NmiReasonGet Function C RESET_NMI_REASON PLIB_RESET_NmiReasonGet( RESET_MODULE_ID index ); Description This function returns the reason which caused the Non-Maskable-Interrupt (NMI) Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns RESET_NMI_REASON - sets of reasons which can cause NMI Remarks This function implements an operation of the NmiControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or include the PLIB_RESET_ExistsNmiControl function in your application to determine whether this feature is available. Example if (PLIB_RESET_NmiReasonGet( RESET_ID_0 )== WDTO_NMI ) { //Do Something } 5.6.19.7 Files Files Name Description plib_reset.h Defines the Reset Peripheral Library interface. Description 5.6.19.7.1 plib_reset.h Reset Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the 5.6 Peripheral Library Help MPLAB Harmony Help Reset Peripheral Library 5-2702 Reset Peripheral Library for Microchip microcontrollers. The definitions in this file are for the Reset Controller module. Functions Name Description PLIB_RESET_ConfigRegReadErrorGet Get the Configuration Register Read Error PLIB_RESET_ExistsConfigRegReadError Identifies whether the ConfigRegReadError feature exists on the RESET module PLIB_RESET_ExistsNmiControl Identifies whether the NmiControl feature exists on the RESET module PLIB_RESET_ExistsNmiCounter Identifies whether the NmiCounter feature exists on the RESET module PLIB_RESET_ExistsResetReasonStatus Identifies whether the ResetReasonStatus feature exists on the RESET module PLIB_RESET_ExistsSoftwareResetTrigger Identifies whether the SoftwareResetTrigger feature exists on the RESET module PLIB_RESET_ExistsWdtoInSleep Identifies whether the WdtoInSleep feature exists on the RESET module PLIB_RESET_NmiCounterValueGet Gets the NMI counter value PLIB_RESET_NmiCounterValueSet Sets the NMI counter PLIB_RESET_NmiEventClear Clears the NMI event PLIB_RESET_NmiEventTrigger Triggers the NMI event PLIB_RESET_NmiReasonGet Returns the reason for NMI PLIB_RESET_ReasonClear Clears the RCON register. PLIB_RESET_ReasonGet Returns the reason for a reset. PLIB_RESET_SoftwareResetEnable Enables the software reset. PLIB_RESET_WdtTimeOutHasOccurredInSleep Returns the state of the device when WDT time-out occurred Types Name Description RESET_NMI_COUNT_TYPE Defines NMI counter data type File Name plib_reset.h Company Microchip Technology Inc. 5.6.20 RTCC Peripheral Library 5.6.20.1 Introduction Real-Time Clock and Calendar (RTCC) Peripheral Library for Microchip Microcontrollers 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2703 This module provides real-time clock and calendar functions. The RTCC is intended for applications where accurate time must be maintained for extended periods with minimum to no intervention from the CPU. The module is optimized for low-power usage to provide extended battery life while keeping track of time. Description The RTCC module is a 100-year clock and calendar with automatic leap year detection. The range of the clock is from 00:00:00 (midnight) on January 1, 2000 to 23:59:59 on December 31, 2099. The hours are available in 24-hour (military time) format. The clock provides a granularity of one second with half-second visibility to the user. RTCC Block Diagram Operating Modes RTCC Mode The RTCC module is intended to be clocked by an external real-time clock crystal oscillating at 32.768 kHz. The prescaler divides the crystal oscillator frequency to produce a 1 Hz frequency for the clock and calendar. The current Date and Time are stored in a BCD counter. Please refer to the "RTCC" chapter in the specific device data sheet and the related family reference manual section to learn more about the counter rolls, overflows and carryovers. Alarm Mode The RTCC module provides an alarm function that is configurable from a half-second to one year. After the alarm is enabled, the RTCC module can be configured to repeat the alarm at preconfigured intervals. The indefinite repetition of the alarm is provided through the Chime feature. Note: Not all functionality is available on all devices. Please refer the specific device data sheet to determine availability. 5.6.20.2 Release Notes MPLAB Harmony Version: v0.70b RTCC Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2704 Nothing to report in this release. 5.6.20.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.20.4 Using the Library This topic describes the basic architecture of the RTCC Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_rtcc.h The interface to the RTCC Peripheral Library is defined in the "plib_rtcc.h" header file. Any C language source (.c) file that uses the RTCC Peripheral Library should include "plib_rtcc.h". Library File: The RTCC Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for information on how the peripheral interacts with the framework. 5.6.20.4.1 Hardware Abstraction Model This library provides a low-level abstraction of the RTCC module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The RTCC peripheral library provides interface routines to interact with the blocks shown in the following diagram. Hardware Abstraction Model 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2705 The RTCC Control Logic provides the capability to operate the RTCC module in the RTCC and Alarm modes. The control logic also handles the comparison and the counter increments, which in turn control the alarm generation. This module is also responsible for the generation of a square wave at the RTCC output pin. In addition, the RTCC module provides the RTCC drift calibration. The RTCC Interrupt Logic is primarily used in alarm generation. The various configurations of the alarm and their repetition period may be defined. The RTCC Registers store the actual date and time. Separate registers are present for RTCC and alarm functionality. 5.6.20.4.2 Library Usage Model This section provides an overview of the usage model for the RTCC Peripheral Library. Description The following diagram describes the major components of the usage model. Usage Model Each of the blocks in the diagram correspond to the library interface section. Library Interface Section Description General Functions Provides the setup and configuration of general functionalities in the RTCC module. This section also covers the drift calibration. RTCC Mode Functions Provides configuration of the RTCC-related registers. Updating the Date and Time registers along with reading them accurately is performed. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2706 Alarm Mode Functions Provides configuration of the Alarm-related registers. Updating the Date and Time registers along with reading them accurately is performed. In addition, the rate at which an alarm occurs and the frequency is also configured in this mode. 5.6.20.4.3 How the Library Works The usage model for this library is explained in the following sections. 5.6.20.4.3.1 State Machine This RTCC state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. Description The following state machine diagram is for RTCC mode and Alarm Mode during normal operation. RTCC State Machine 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2707 State Associated Function Setup and Initialization Refer to mode of RTCC for detailed instructions of setup. Enable Write via Key Sequence For RTCC to perform any function, the module has to be enabled via a series of commands in a special sequence. This is abstracted and is achieved using PLIB_RTCC_WriteEnable. Enable Access of RTC These include the functions needed to set up the RTCC/Alarm, which will be explained in detail in the following sections. Wait for Safe Sync Window To update the RTCC on-the-fly, a safe window period is available, corresponding to 32 clock cycles called RTSYNC. Further sections will explain the functionality in greater detail. Write/Read Date and Time The application may read or write the date and time using PLIB_RTCC_WriteRTCDateValueRegister, PLIB_RTCC_ReadRTCDateValueRegister, among other. These functions are device-specific and may not exist for all devices. 5.6.20.4.3.2 RTCC Mode Operations This section describes the RTCC mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the related family reference manual to determine which features are supported by your device. Description Enabling the RTCC Module for Write Operations To perform a write to any of the RTCC timer registers the RTCWREN bit must be set. It is recommended that this bit be reset unless a write operation is specifically required. A sequence of commands, each varying across processor families must be executed to set the RTCWREN. Example: Enabling a Write // Assume Interrupts are disabled. // Assume the DMA controller is suspended PLIB_RTCC_WriteEnable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. // This API performs the writing of the sequence // 0xaa996655 and 0x556699aa to the SYSKET in MCU32 // and 0x55 and 0xaa in case of MCU 16 and MCU 8 // This API then sets the RTCWREN. Updating RTCC Time and Date 1. Turn off the RTCC using the API PLIB_RTCC_Disable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_ValueRegistersReadSyncBit (This operation may not be required on all devices). 3. Update the Date and Time registers using PLIB_RTCC_WriteRTCTimeValueRegister and PLIB_RTCC_WriteRTCDateValueRegister. 4. Turn on the RTCC module using PLIB_RTCC_Enable. Example: Updating RTCC Time and Date // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsinged long date = 0x06102705; // Set date to Friday 27 Oct 2006 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2708 PLIB_RTCC_Disable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_ValueRegistersReadSyncBit(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_WriteRTCTimeValueRegister(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_WriteRTCDateValueRegister(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_Enable(MY_RTCC_INSTANCE); Updating RTCC Time and Date using RTSYNC Window 1. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_ValueRegistersReadSyncBit. 2. Update the RTC Date and Time registers using PLIB_RTCC_WriteRTCDateValueRegister and PLIB_RTCC_WriteRTCTimeValueRegister. Example: Updating RTCC Time and Date Using RTSYNC Window // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsinged long date = 0x06102705; // Set date to Friday 27 Oct 2006 // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. //Disable Critical Interrupts here .... while(PLIB_RTCC_ValueRegistersReadSyncBit(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_WriteRTCTimeValueRegister(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_WriteRTCDateValueRegister(MY_RTCC_INSTANCE, date); // Update the Date //Enable Critical Interrupts here .... Updating RTCC Time and Date Using Register Pointers 1. Turn off the RTCC using PLIB_RTCC_Disable. 2. Update the register pointer to point to the accurate registers using PLIB_RTCC_ValueRegisterPointer. 3. Update the RTC Date and Time registers using PLIB_RTCC_ValueWrite. 4. Turn on the RTCC module using PLIB_RTCC_Enable. Example: Updating RTCC Time and Date Using Register Pointers // Assume Write Enable has been performed correctly PLIB_RTCC_Disable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. PLIB_RTCC_ValueRegisterPointer(MY_RTCC_INSTANCE, RTCC_REG_YEAR); PLIB_RTCC_ValueWrite(MY_RTCC_INSTANCE, 0x0007); // Update the Year PLIB_RTCC_ValueWrite(MY_RTCC_INSTANCE, 0x1028); // Update the Month and Day PLIB_RTCC_ValueWrite(MY_RTCC_INSTANCE, 0x0110); // Update the Weekday and Hour PLIB_RTCC_ValueWrite(MY_RTCC_INSTANCE, 0x0000); // Set the minute and second 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2709 PLIB_RTCC_Enable(MY_RTCC_INSTANCE); 5.6.20.4.3.3 Alarm Mode Operations This section describes the Alarm mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the related family reference manual to determine which features are supported by your device. Description Configuring the One-Time-Per-Day Alarm 1. Turn off the Alarm and also the chime, alarm repeats, and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmValueRegistersReadSyncBit (This operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_WriteAlarmTimeValueRegister and PLIB_RTCC_WriteAlarmDateValueRegister. 4. Set the alarm mask to every half-second and the repeat counter to zero using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable. Example: Configuring the One-Time-Per-Day Alarm // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsinged long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmValueRegistersReadSyncBit(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_WriteAlarmTimeValueRegister(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_WriteAlarmDateValueRegister(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 0 /*No of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); Configuring the Repeat Alarm 1. Turn off the Alarm and also the Chime, alarm repeats, and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmValueRegistersReadSyncBit (This operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_WriteAlarmTimeValueRegister and PLIB_RTCC_WriteAlarmDateValueRegister. 4. Set the alarm mask to every half-second and the repeat counter to 10 using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable. Example: Configuring the Repeat Alarm // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsinged long date = 0x06102705; // Set date to Friday 27 Oct 2006 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2710 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmValueRegistersReadSyncBit(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_WriteAlarmTimeValueRegister(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_WriteAlarmDateValueRegister(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 10 /*No of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); Configuring the Indefinite One-Per-Day Alarm 1. Turn off the Alarm and also the Chime, alarm repeats and masks using PLIB_RTCC_AlarmDisable. 2. Wait for the sync clock to turn off by reading the status of PLIB_RTCC_AlarmValueRegistersReadSyncBit (This operation may not be required on all devices). 3. Update the Alarm Date and Time registers using PLIB_RTCC_WriteAlarmTimeValueRegister and PLIB_RTCC_WriteAlarmDateValueRegister. 4. Set the alarm mask to every half-second and the repeat counter to 0 using PLIB_RTCC_AlarmMaskModeSelect and PLIB_RTCC_AlarmRepeatCountSet, respectively. 5. Turn on the RTCC Alarm module using PLIB_RTCC_AlarmEnable and enable chime using PLIB_RTCC_AlarmChimeEnable. Example: Configuring the Indefinite One-Per-Day Alarm // Assume Write Enable has been performed correctly unsigned long time = 0x04153300; // Set time 04 hrs 15 mins and 33 sec unsinged long date = 0x06102705; // Set date to Friday 27 Oct 2006 PLIB_RTCC_AlarmDisable(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. while(PLIB_RTCC_AlarmValueRegistersReadSyncBit(MY_RTCC_INSTANCE)); // Wait for clock to turn off PLIB_RTCC_WriteAlarmTimeValueRegister(MY_RTCC_INSTANCE, time); // Update the Time PLIB_RTCC_WriteAlarmDateValueRegister(MY_RTCC_INSTANCE, date); // Update the Date PLIB_RTCC_AlarmMaskModeSelect(MY_RTCC_INSTANCE, RTCC_ALARM_EVERY_HALF_SECOND); PLIB_RTCC_AlarmRepeatCountSet(MY_RTCC_INSTANCE, 0 /*No of repetitions*/ ); PLIB_RTCC_AlarmEnable(MY_RTCC_INSTANCE); PLIB_RTCC_AlarmChimeEnable(MY_RTCC_INSTANCE); 5.6.20.4.3.4 Other Functionality This section describes the Drift Calibration mode of operation of the RTCC module. Note: Please refer to the "RTCC" chapter in the specific device data sheet or the related family reference manual to determine which features are supported by your device. Description The real-time crystal input can be calibrated using the periodic auto-adjust feature. When properly calibrated, the RTCC module 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2711 can provide an error of less than 0.66 seconds per month. Calibration has the ability to eliminate an error of up to 260 ppm. The calibration is accomplished by finding the number of error clock pulses and writing this value into the calibration bit fields using PLIB_RTCC_DriftCalibrate. Drift Calibration 1. Using another timer resource, the user must find the error of the 32.768 kHz crystal. 2. Once the error is known, it must be converted to the number of error clock pulses per minute, as shown by (Ideal Frequency(32,758) - Measured Frequency) * 60 = Error Clocks Per Minute. 3. If the error is negative, the input to PLIB_RTCC_DriftCalibrate is negative. Likewise, if the error is positive, the input is positive. The negative and positive values are the actual number of clock pulses to be added or subtracted from the timer counter per minute. Example: Configuring the One-Time-Per-Day Alarm // Assume Write Enable has been performed correctly // Assume steps 1 and 2 are performed and the error is determined. int driftValue = 0x3FD // 10 bits Adjustment, -3 in value int T0,T1; do { T0 = PLIB_RTCC_ReadRTCTimeValueRegister(MY_RTCC_INSTANCE); T1 = PLIB_RTCC_ReadRTCTimeValueRegister(MY_RTCC_INSTANCE); // where, MY_RTCC_INSTANCE - is a specific instance of the hardware peripheral. }while(T0!=T1) //Read Valid Time Value if((T0 & 0XFF) == 0) // we are at seconds exactly 00, wait for auto adjust { while(!PLIB_RTCC_HalfSecondStatusBit(MY_RTCC_INSTANCE));; Wait for the second Half } PLIB_RTCC_DriftCalibrate(MY_RTCC_INSTANCE, 0x00); //Clear the calibration PLIB_RTCC_DriftCalibrate(MY_RTCC_INSTANCE, 0xdriftValue); 5.6.20.4.4 Configuring the Library The library is configured for the supported RTCC modules when the processor is chosen in the MPLAB IDE. 5.6.20.5 Library Interface Data Types and Constants Name Description RTCC_ALARM_MASK_CONFIGURATION Data type defining the different configurations for the alarm mask bits. RTCC_MODULE_ID Enumeration: RTCC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the superset of all of the possible instances that may be available on the Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. RTCC_VALUE_REGISTER_POINTER Data type defining the different configurations by which the RTCC Date and Time Registers can be accessed. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2712 Alarm Mode Functions Name Description PLIB_RTCC_AlarmChimeDisable Disables the specific RTCC module's chime. PLIB_RTCC_AlarmChimeEnable Enables the specific RTCC module's chime. PLIB_RTCC_AlarmDateGet Returns the contents of the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDateSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDayGet Returns the contents of the Day bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDaySet Writes to the specific RTCC module's Alarm Date value register. PLIB_RTCC_AlarmDisable Disables the specific RTCC module's alarm. PLIB_RTCC_AlarmEnable Enables the specific RTCC module's alarm. PLIB_RTCC_AlarmHourGet Returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmHourSet The function returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMaskModeSelect Sets the specific RTCC module's alarm mask Configuration bits. PLIB_RTCC_AlarmMinuteGet Returns the contents of Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMinuteSet Returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMonthGet Returns the contents of the Month bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmMonthSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmPulseInitialGet Returns the state of the initial alarm pulse. PLIB_RTCC_AlarmPulseInitialSet Enables the determination of the initial alarm pulse. PLIB_RTCC_AlarmRepeatCountGet Reads the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmRepeatCountSet Sets the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmSecondGet Returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmSecondSet Returns the contents of Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeGet Returns the contents of the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeSet Writes to the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmValueRegisterPointer Sets the specific RTCC module's Alarm register pointer. PLIB_RTCC_AlarmWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmWeekDaySet Writes to the specific RTCC module's Alarm Date register. Feature Existence Functions Name Description PLIB_RTCC_ExistsAlarmChimeControl Identifies whether the AlarmChimeControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmControl Identifies whether the AlarmControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmDate Identifies whether the AlarmDate feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmMaskControl Identifies whether the AlarmMaskControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmPulseInitial Identifies whether the AlarmPulseInitial feature exists on the RTCC module. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2713 PLIB_RTCC_ExistsAlarmRepeatControl Identifies whether the AlarmRepeatControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmSyncronization Identifies whether the AlarmSynchronization feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmTime Identifies whether the AlarmTime feature exists on the RTCC module. PLIB_RTCC_ExistsCalibration Identifies whether the Calibration feature exists on the RTCC module. PLIB_RTCC_ExistsClockRunning Identifies whether the ClockRunning feature exists on the RTCC module. PLIB_RTCC_ExistsClockSelect Identifies whether the ClockSelect feature exists on the RTCC module. PLIB_RTCC_ExistsEnableControl Identifies whether the EnableControl feature exists on the RTCC module. PLIB_RTCC_ExistsHalfSecond Identifies whether the HalfSecond feature exists on the RTCC module. PLIB_RTCC_ExistsOutputControl Identifies whether the OutputControl feature exists on the RTCC module. PLIB_RTCC_ExistsOutputSelect Identifies whether the OutputSelect feature exists on the RTCC module. PLIB_RTCC_ExistsRTCDate Identifies whether the RTCDateValue feature exists on the RTCC module. PLIB_RTCC_ExistsRTCTime Identifies whether the RTCTimeValue feature exists on the RTCC module. PLIB_RTCC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the RTCC module. PLIB_RTCC_ExistsSynchronization Identifies whether the Synchronization feature exists on the RTCC module. PLIB_RTCC_ExistsWriteEnable Identifies whether the WriteEnable feature exists on the RTCC module. General Functions Name Description PLIB_RTCC_ClockOutputDisable Disables the specific RTCC module's output pin. PLIB_RTCC_ClockOutputEnable Enables the specific RTCC module's output pin. PLIB_RTCC_ClockRunningStatus Provides the status of the RTCC clock. Other Functions Name Description PLIB_RTCC_ClockSourceSelect Selects the clock source for the RTCC module. PLIB_RTCC_DriftCalibrateGet Reads the specific RTCC module's drift calibration bits. PLIB_RTCC_DriftCalibrateSet Sets the specific RTCC module's drift calibration bits. PLIB_RTCC_HalfSecondStatusGet The function returns the half second status bit. PLIB_RTCC_OutputSelect Selects which signal will be presented on the RTCC pin PLIB_RTCC_StopInIdleDisable Continues normal RTCC operation when the device enters Idle mode. PLIB_RTCC_StopInIdleEnable Disables access to the RTCC module by the Peripheral Bus Clock (PBCLK) when the CPU enters Idle mode. RTCC Mode Functions Name Description PLIB_RTCC_Disable Disables the specific RTCC module on the device. PLIB_RTCC_Enable Enables the specific RTCC module on the device. PLIB_RTCC_WriteDisable Disables writing to the specific RTCC module's value registers. PLIB_RTCC_WriteEnable Enables writing to the specific RTCC module's value registers. PLIB_RTCC_RTCDateGet Returns the contents of the specific RTCC module's Date register. PLIB_RTCC_RTCDateSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCDayGet Returns the contents of the Days bits in the specific RTCC module's Date register. PLIB_RTCC_RTCDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCHourGet Returns the contents of the Hours bits in the specific RTCC module's Time register. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2714 PLIB_RTCC_RTCHourSet Writes the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteGet Returns the contents of the Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteSet Writes the contents of Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMonthGet Returns the contents of the Months bits in the specific RTCC module's Date register. PLIB_RTCC_RTCMonthSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCSecondGet The function returns the contents of the Seconds bits in the specific RTCC device's Time register. PLIB_RTCC_RTCSecondSet Writes the contents of Seconds bits in the specific RTCC module's Time register. PLIB_RTCC_RTCTimeGet Returns the contents of the specific RTCC module's Time register. PLIB_RTCC_RTCTimeSet Writes to the specific RTCC module's Time register. PLIB_RTCC_RTCWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Date register. PLIB_RTCC_RTCWeekDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCYearGet Returns the contents of the Year bits in the specific RTCC module's Date register. PLIB_RTCC_RTCYearSet Writes to the specific RTCC module's Date register. Description This section lists and describes the functions, data types, and constants included in the RTCC Peripheral Library. 5.6.20.5.1 General Functions 5.6.20.5.1.1 PLIB_RTCC_ClockOutputDisable Function C void PLIB_RTCC_ClockOutputDisable( RTCC_MODULE_ID index ); Description This function disables the specific RTCC module's output pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the OutputControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_ClockOutputDisable(RTCC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2715 5.6.20.5.1.2 PLIB_RTCC_ClockOutputEnable Function C void PLIB_RTCC_ClockOutputEnable( RTCC_MODULE_ID index ); Description This function enables the specific RTCC module's output and generates a square wave using either the alarm or the 1 Hz clock output on the RTCC pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the OutputControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_ClockOutputEnable(RTCC_ID_0); 5.6.20.5.1.3 PLIB_RTCC_ClockRunningStatus Function C bool PLIB_RTCC_ClockRunningStatus( RTCC_MODULE_ID index ); Description This function provides the status of the RTCC clock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns The status of the RTCC clock. Remarks This function implements an operation of the ClockRunning feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsClockRunning in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2716 Example bool status; status = PLIB_RTCC_ClockRunningStatus(RTCC_ID_0); 5.6.20.5.2 RTCC Mode Functions 5.6.20.5.2.1 PLIB_RTCC_Disable Function C void PLIB_RTCC_Disable( RTCC_MODULE_ID index ); Description This function disables the specific RTCC module on the device. Preconditions The RTCC module should be unlocked for writing using the function PLIB_RTCC_WriteEnable before this function is called. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsEnableControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_Disable(RTCC_ID_0); 5.6.20.5.2.2 PLIB_RTCC_Enable Function C void PLIB_RTCC_Enable( RTCC_MODULE_ID index ); Description This function enables the specific RTCC module on the device. Preconditions The RTCC module should be unlocked for writing using the function PLIB_RTCC_WriteEnable before this function is called. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2717 Remarks By calling this function, the RTCC pins are controlled by the RTCC module. The RTCC module will continue to function when the device is held in reset. This function implements an operation of the EnableControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsEnableControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_Enable(RTCC_ID_0); 5.6.20.5.2.3 PLIB_RTCC_WriteDisable Function C void PLIB_RTCC_WriteDisable( RTCC_MODULE_ID index ); Description This function disables writing to the specific RTCC module's value registers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the WriteEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWriteEnable in your application to automatically determine whether this feature is available. Example PLIB_RTCC_WriteDisable(RTCC_ID_0); 5.6.20.5.2.4 PLIB_RTCC_WriteEnable Function C void PLIB_RTCC_WriteEnable( RTCC_MODULE_ID index ); Description This function enables writing to the specific RTCC module's value registers. Preconditions The SYSLOCK unlock sequence must be executed prior to calling this function by calling the PLIB_CORE_SysUnlock function. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2718 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the WriteEnable feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsWriteEnable in your application to automatically determine whether this feature is available. Example PLIB_RTCC_WriteEnable(RTCC_ID_0); 5.6.20.5.2.5 PLIB_RTCC_RTCDateGet Function C uint32_t PLIB_RTCC_RTCDateGet( RTCC_MODULE_ID index ); Description The function returns the contents of the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact s equence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Date register contents. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Date; Date = PLIB_RTCC_RTCDateGet(RTCC_ID_0); 5.6.20.5.2.6 PLIB_RTCC_RTCDateSet Function C void PLIB_RTCC_RTCDateSet( RTCC_MODULE_ID index, uint32_t data ); Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2719 Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t data = 0x06102705; //Date = 27 Oct 2006 Friday PLIB_RTCC_RTCDateSet(RTCC_ID_0, data); 5.6.20.5.2.7 PLIB_RTCC_RTCDayGet Function C uint32_t PLIB_RTCC_RTCDayGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Days bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Days bits in the Date register. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Day; Day = PLIB_RTCC_RTCDayGet(RTCC_ID_0); 5.6.20.5.2.8 PLIB_RTCC_RTCDaySet Function C void PLIB_RTCC_RTCDaySet( RTCC_MODULE_ID index, uint32_t day ); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2720 Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured day The BCD value of the day to set in the Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Day = 0x27; //Day = 27th of the month PLIB_RTCC_RTCDaySet(RTCC_ID_0, Day); 5.6.20.5.2.9 PLIB_RTCC_RTCHourGet Function C uint32_t PLIB_RTCC_RTCHourGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Hours bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Hours bits in the Time register. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Hour; Hour = PLIB_RTCC_RTCHourGet(RTCC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2721 5.6.20.5.2.10 PLIB_RTCC_RTCHourSet Function C void PLIB_RTCC_RTCHourSet( RTCC_MODULE_ID index, uint32_t hour ); Description The function writes the contents of the Hours bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured hour BCD value to be written to the Hours bits in the Time register Returns None Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Hour = 0x04; PLIB_RTCC_RTCHourSet(RTCC_ID_0, Hour); 5.6.20.5.2.11 PLIB_RTCC_RTCMinuteGet Function C uint32_t PLIB_RTCC_RTCMinuteGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Minutes bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Minutes bits in the Time register. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Minute; 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2722 Minute = PLIB_RTCC_RTCMinuteGet(RTCC_ID_0); 5.6.20.5.2.12 PLIB_RTCC_RTCMinuteSet Function C void PLIB_RTCC_RTCMinuteSet( RTCC_MODULE_ID index, uint32_t minute ); Description The function writes the contents of thes bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured minute BCD value to be written to the Minutes bits in the Time register Returns None Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Minute = 0x15; PLIB_RTCC_RTCMinuteSet(RTCC_ID_0, Minute); 5.6.20.5.2.13 PLIB_RTCC_RTCMonthGet Function C uint32_t PLIB_RTCC_RTCMonthGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Months bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Months bits in the Date register. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2723 Example uint32_t Month; Month = PLIB_RTCC_RTCMonthGet(RTCC_ID_0); 5.6.20.5.2.14 PLIB_RTCC_RTCMonthSet Function C void PLIB_RTCC_RTCMonthSet( RTCC_MODULE_ID index, uint32_t month ); Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured month The BCD value of the month to set in the Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Month = 0x10; //Month = October PLIB_RTCC_RTCMonthSet(RTCC_ID_0, Month); 5.6.20.5.2.15 PLIB_RTCC_RTCSecondGet Function C uint32_t PLIB_RTCC_RTCSecondGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Seconds bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Seconds bits in the Time register. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2724 Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Second; Second = PLIB_RTCC_RTCSecondGet(RTCC_ID_0); 5.6.20.5.2.16 PLIB_RTCC_RTCSecondSet Function C void PLIB_RTCC_RTCSecondSet( RTCC_MODULE_ID index, uint32_t second ); Description The function writes the contents of the Seconds bits in the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured second BCD value to be written to the Seconds bits in the Time register Returns None. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t Second = 0x33; PLIB_RTCC_RTCSecondSet(RTCC_ID_0, Second); 5.6.20.5.2.17 PLIB_RTCC_RTCTimeGet Function C uint32_t PLIB_RTCC_RTCTimeGet( RTCC_MODULE_ID index ); Description The function returns the contents of the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2725 Returns Time register contents. Remarks This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t time; time = PLIB_RTCC_RTCTimeGet(RTCC_ID_0); 5.6.20.5.2.18 PLIB_RTCC_RTCTimeSet Function C void PLIB_RTCC_RTCTimeSet( RTCC_MODULE_ID index, uint32_t data ); Description The function writes to the specific RTCC module's Time register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Time register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCTime in your application to automatically determine whether this feature is available. Example uint32_t data = 0x04153300; //Time = 4 hrs 15 mins 33 sec PLIB_RTCC_RTCTimeSet(RTCC_ID_0, data); 5.6.20.5.2.19 PLIB_RTCC_RTCWeekDayGet Function C uint32_t PLIB_RTCC_RTCWeekDayGet( RTCC_MODULE_ID index ); Description The function returns the contents of the WeekDay bits in the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2726 Parameters Parameters Description index Identifier for the device instance to be configured Returns WeekDay field in the Date register. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t WeekDay; WeekDay = PLIB_RTCC_RTCWeekDayGet(RTCC_ID_0); 5.6.20.5.2.20 PLIB_RTCC_RTCWeekDaySet Function C void PLIB_RTCC_RTCWeekDaySet( RTCC_MODULE_ID index, uint32_t weekday ); Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured weekday The BCD value of the weekday to set in the Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t WeekDay = 0x05; //WeekDay = Friday PLIB_RTCC_RTCWeekDaySet(RTCC_ID_0, WeekDay); 5.6.20.5.2.21 PLIB_RTCC_RTCYearGet Function C uint32_t PLIB_RTCC_RTCYearGet( RTCC_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2727 ); Description The function returns the contents of the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Year bits in the Date register. Remarks This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Year; Year = PLIB_RTCC_RTCYearGet(RTCC_ID_0); 5.6.20.5.2.22 PLIB_RTCC_RTCYearSet Function C void PLIB_RTCC_RTCYearSet( RTCC_MODULE_ID index, uint32_t year ); Description The function writes to the specific RTCC module's Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured year The BCD value of the year to set in the Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the RTCDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsRTCDate in your application to automatically determine whether this feature is available. Example uint32_t Year = 0x06; //Year = 2006 PLIB_RTCC_RTCYearSet(RTCC_ID_0, Year); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2728 5.6.20.5.3 Alarm Mode Functions 5.6.20.5.3.1 PLIB_RTCC_AlarmChimeDisable Function C void PLIB_RTCC_AlarmChimeDisable( RTCC_MODULE_ID index ); Description This function disables the specific RTCC module's chime. The alarm repeat count value bits stop once they reach zero. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the AlarmChimeControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmChimeControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_AlarmChimeDisable(RTCC_ID_0); 5.6.20.5.3.2 PLIB_RTCC_AlarmChimeEnable Function C void PLIB_RTCC_AlarmChimeEnable( RTCC_MODULE_ID index ); Description This function enables the specific RTCC module's chime. The alarm repeat count bits are allowed to rollover. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the AlarmChimeControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmChimeControl in your 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2729 application to automatically determine whether this feature is available. Example PLIB_RTCC_AlarmChimeEnable(RTCC_ID_0); 5.6.20.5.3.3 PLIB_RTCC_AlarmDateGet Function C uint32_t PLIB_RTCC_AlarmDateGet( RTCC_MODULE_ID index ); Description The function returns the contents of the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Value register. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t Date; Date = PLIB_RTCC_AlarmDateGet(RTCC_ID_0); 5.6.20.5.3.4 PLIB_RTCC_AlarmDateSet Function C void PLIB_RTCC_AlarmDateSet( RTCC_MODULE_ID index, uint32_t data ); Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured data The value to set the Alarm Date register to, in BCD format Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2730 Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t data = 0x06102705; //Date = 27 Oct 2006 Friday PLIB_RTCC_AlarmDateSet(RTCC_ID_0, data); 5.6.20.5.3.5 PLIB_RTCC_AlarmDayGet Function C uint32_t PLIB_RTCC_AlarmDayGet( RTCC_MODULE_ID index ); Description The function returns the contents of Day bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Days bits in the Alarm Date register. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t Day; Day = PLIB_RTCC_AlarmDayGet(RTCC_ID_0); 5.6.20.5.3.6 PLIB_RTCC_AlarmDaySet Function C void PLIB_RTCC_AlarmDaySet( RTCC_MODULE_ID index, uint32_t day ); Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2731 Parameters Parameters Description index Identifier for the device instance to be configured day The BCD value of the day to set in the Alarm Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t Day = 0x27; //Day = 27th of the month PLIB_RTCC_AlarmDaySet(RTCC_ID_0, Day); 5.6.20.5.3.7 PLIB_RTCC_AlarmDisable Function C void PLIB_RTCC_AlarmDisable( RTCC_MODULE_ID index ); Description This function disables the specific RTCC module's alarm. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the AlarmControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_AlarmDisable(RTCC_ID_0); 5.6.20.5.3.8 PLIB_RTCC_AlarmEnable Function C void PLIB_RTCC_AlarmEnable( RTCC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2732 Description This function enables the specific RTCC module's alarm. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks The alarm enable bit is cleared automatically after an alarm event whenever the alarm is not set up to repeat, and chime is disabled. This function implements an operation of the AlarmControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmControl in your application to automatically determine whether this feature is available. Example PLIB_RTCC_AlarmEnable(RTCC_ID_0); 5.6.20.5.3.9 PLIB_RTCC_AlarmHourGet Function C uint32_t PLIB_RTCC_AlarmHourGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Hours bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Hours bits in the Alarm Time register. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t Hour; Hour = PLIB_RTCC_AlarmHourGet(RTCC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2733 5.6.20.5.3.10 PLIB_RTCC_AlarmHourSet Function C void PLIB_RTCC_AlarmHourSet( RTCC_MODULE_ID index, uint32_t hour ); Description Returns the contents of the Hours bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured hour BCD value to be written to the Hours bits in the Alarm Time register Returns None Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t Hour = 0x04; PLIB_RTCC_AlarmHourSet(RTCC_ID_0, Hour); 5.6.20.5.3.11 PLIB_RTCC_AlarmMaskModeSelect Function C void PLIB_RTCC_AlarmMaskModeSelect( RTCC_MODULE_ID index, RTCC_ALARM_MASK_CONFIGURATION data ); Description This function sets the specific RTCC module's alarm mask Configuration bits. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Alarm mask Configuration bits Returns None. Remarks The actual definition of this enumeration is device-specific. This function implements an operation of the AlarmMaskControl feature. This feature may not be available on all devices. Please 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2734 refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmMaskControl in your application to automatically determine whether this feature is available. Example uint8_t data = 0; PLIB_RTCC_AlarmMaskModeSelect(RTCC_ID_0, RTCC_ALARM_EVERY_HALF_SECOND); 5.6.20.5.3.12 PLIB_RTCC_AlarmMinuteGet Function C uint32_t PLIB_RTCC_AlarmMinuteGet( RTCC_MODULE_ID index ); Description The function returns the contents of the field in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Minutes bits in the Alarm Time register. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t Minute; Minute = PLIB_RTCC_AlarmMinuteGet(RTCC_ID_0); 5.6.20.5.3.13 PLIB_RTCC_AlarmMinuteSet Function C void PLIB_RTCC_AlarmMinuteSet( RTCC_MODULE_ID index, uint32_t minute ); Description The function returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured minute BCD value to be written to the Minutes bits in the Alarm Time register Returns None 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2735 Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t Minute = 0x15; PLIB_RTCC_AlarmMinuteSet(RTCC_ID_0, Minute); 5.6.20.5.3.14 PLIB_RTCC_AlarmMonthGet Function C uint32_t PLIB_RTCC_AlarmMonthGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Months bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Months bits in the Date register. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t Month; Month = PLIB_RTCC_AlarmMonthGet(RTCC_ID_0); 5.6.20.5.3.15 PLIB_RTCC_AlarmMonthSet Function C void PLIB_RTCC_AlarmMonthSet( RTCC_MODULE_ID index, uint32_t month ); Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2736 month The BCD value of the month to set in the Alarm Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t Month = 0x10; //Month = October PLIB_RTCC_AlarmMonthSet(RTCC_ID_0, Month); 5.6.20.5.3.16 PLIB_RTCC_AlarmPulseInitialGet Function C bool PLIB_RTCC_AlarmPulseInitialGet( RTCC_MODULE_ID index ); Description This function returns the state of the initial alarm pulse. Preconditions The ALRMEN bit should be '1' indicating the PLIB_RTCC_AlarmEnable function was called. Parameters Parameters Description index Identifier for the device instance to be configured Returns 1 - Logical High 0 - Logical Low Remarks This function implements an operation of the AlarmPulseInitial feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmPulseInitial in your application to automatically determine whether this feature is available. Example bool PulseValue; PulseValue = PLIB_RTCC_AlarmPulseInitialGet(RTCC_ID_0); 5.6.20.5.3.17 PLIB_RTCC_AlarmPulseInitialSet Function C void PLIB_RTCC_AlarmPulseInitialSet( RTCC_MODULE_ID index, bool data ); Description This function enables the determination of initial alarm pulse. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2737 Preconditions The ALRMEN bit should be '0' indicating the PLIB_RTCC_AlarmDisable was called. This function must not be called when the RTCC is ON and the Alarm Sync is 1. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the AlarmPulseInitial feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmPulseInitial in your application to automatically determine whether this feature is available. Example bool data = 0; PLIB_RTCC_AlarmPulseInitialSet(RTCC_ID_0, data); 5.6.20.5.3.18 PLIB_RTCC_AlarmRepeatCountGet Function C uint8_t PLIB_RTCC_AlarmRepeatCountGet( RTCC_MODULE_ID index ); Description This function reads the specific RTCC module's alarm repeat counter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns uint8_t - The current value of the alarm repeat counter Remarks The counter decrements on any alarm event. The counter is prevented from rolling over unless chime is enabled. This function implements an operation of the AlarmRepeatControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmRepeatControl in your application to automatically determine whether this feature is available. Example uint8_t currentCount; currentCount = PLIB_RTCC_AlarmRepeatCountGet(RTCC_ID_0); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2738 5.6.20.5.3.19 PLIB_RTCC_AlarmRepeatCountSet Function C void PLIB_RTCC_AlarmRepeatCountSet( RTCC_MODULE_ID index, uint8_t data ); Description This function sets the specific RTCC module's alarm repeat counter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Alarm repeat counter bits Returns None. Remarks The counter decrements on any alarm event. The counter is prevented from rolling over unless chime is enabled. This function implements an operation of the AlarmRepeatControl feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmRepeatControl in your application to automatically determine whether this feature is available. Example uint8_t data = 0xFF; PLIB_RTCC_AlarmRepeatCountSet(RTCC_ID_0, data); 5.6.20.5.3.20 PLIB_RTCC_AlarmSecondGet Function C uint32_t PLIB_RTCC_AlarmSecondGet( RTCC_MODULE_ID index ); Description The function returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns BCD value of the Seconds bits in the Alarm Time register. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2739 determine whether this feature is available. Example uint32_t Second; Second = PLIB_RTCC_AlarmSecondGet(RTCC_ID_0); 5.6.20.5.3.21 PLIB_RTCC_AlarmSecondSet Function C void PLIB_RTCC_AlarmSecondSet( RTCC_MODULE_ID index, uint32_t second ); Description The function returns the contents of the field in the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured second BCD value to be written to the Seconds bits in the Alarm Time register Returns None Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t Second = 0x33; PLIB_RTCC_AlarmSecondSet(RTCC_ID_0, Second); 5.6.20.5.3.22 PLIB_RTCC_AlarmTimeGet Function C uint32_t PLIB_RTCC_AlarmTimeGet( RTCC_MODULE_ID index ); Description The function returns the contents of the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns Value register. Remarks This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2740 the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t time; time = PLIB_RTCC_AlarmTimeGet(RTCC_ID_0); 5.6.20.5.3.23 PLIB_RTCC_AlarmTimeSet Function C void PLIB_RTCC_AlarmTimeSet( RTCC_MODULE_ID index, uint32_t data ); Description The function writes to the specific RTCC module's Alarm Time register. Please refer to the specific device data sheet for the exact sequence of digits. Preconditions Prior to writing to the Alarm Time register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmTime feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmTime in your application to automatically determine whether this feature is available. Example uint32_t data = 0x04153300; //Time = 4 hrs 15 mins 33 sec PLIB_RTCC_AlarmTimeSet(RTCC_ID_0, data); 5.6.20.5.3.24 PLIB_RTCC_AlarmValueRegisterPointer Function C void PLIB_RTCC_AlarmValueRegisterPointer( RTCC_MODULE_ID index, uint8_t data ); Description This function sets the specific RTCC module's Alarm register pointer. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2741 Parameters Parameters Description index Identifier for the device instance to be configured data Alarm register pointer Returns None. Remarks None. Example uint8_t data = 2; PLIB_RTCC_AlarmValueRegisterPointer(RTCC_ID_0, data); 5.6.20.5.3.25 PLIB_RTCC_AlarmWeekDayGet Function C uint32_t PLIB_RTCC_AlarmWeekDayGet( RTCC_MODULE_ID index ); Description The function returns the contents of Weekday bits in the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. Parameters Parameters Description index Identifier for the device instance to be configured Returns WeekDay bits in the Alarm Date register. Remarks This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t WeekDay; WeekDay = PLIB_RTCC_AlarmWeekDayGet(RTCC_ID_0); 5.6.20.5.3.26 PLIB_RTCC_AlarmWeekDaySet Function C void PLIB_RTCC_AlarmWeekDaySet( RTCC_MODULE_ID index, uint32_t weekday ); Description The function writes to the specific RTCC module's Alarm Date register. Please refer to the specific device data sheet for the exact sequence of digits. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2742 Preconditions Prior to writing to the Alarm Date register, an RTCC write must be enabled using the exact sequences required by the device. Parameters Parameters Description index Identifier for the device instance to be configured weekday The BCD value of the weekday to set in the field of the Alarm Date register Returns None. Remarks A write to this register is only allowed when access is allowed by using the PLIB_RTCC_WriteEnable function. This function implements an operation of the AlarmDate feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsAlarmDate in your application to automatically determine whether this feature is available. Example uint32_t WeekDay = 0x05; //WeekDay = Friday PLIB_RTCC_AlarmWeekDaySet(RTCC_ID_0, WeekDay); 5.6.20.5.4 Other Functions 5.6.20.5.4.1 PLIB_RTCC_ClockSourceSelect Function C void PLIB_RTCC_ClockSourceSelect( RTCC_MODULE_ID index, RTCC_CLOCK_SOURCE_SELECT source ); Description This function determines which clock source the RTCC module will use depending on the features of the device. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source Which clock source will be used Returns None. Remarks This function implements an operation of the ClockSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsClockSelect in your application to automatically determine whether this feature is available. Example PLIB_RTCC_ClockSourceSelect(RTCC_ID_0, RTCC_CLOCK_SOURCE_SELECT_NONE); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2743 5.6.20.5.4.2 PLIB_RTCC_DriftCalibrateGet Function C uint16_t PLIB_RTCC_DriftCalibrateGet( RTCC_MODULE_ID index ); Description This function reads the specific RTCC module's drift calibration bits. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns uint16_t - The current drift calibration value Remarks This function implements an operation of the Calibration feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCalibration in your application to automatically determine whether this feature is available. Example uint16_t calibrationbits; calibrationbits = PLIB_RTCC_DriftCalibrateGet(RTCC_ID_0); 5.6.20.5.4.3 PLIB_RTCC_DriftCalibrateSet Function C void PLIB_RTCC_DriftCalibrateSet( RTCC_MODULE_ID index, uint16_t calibrationbits ); Description This function sets the specific RTCC module's drift calibration bits. The error between the system clock and the external clock has to be computed and calibration input must be provided to this function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured calibrationbits Drift calibration bits Returns None. Remarks This function implements an operation of the Calibration feature. This feature may not be available on all devices. Please refer to 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2744 the specific device data sheet to determine availability or use PLIB_RTCC_ExistsCalibration in your application to automatically determine whether this feature is available. Example uint16_t calibrationbits = 3; //Positive 3 adjustment derived from the formula // Error = (Ideal Freq(32758) - Measured)*60; PLIB_RTCC_DriftCalibrateSet(RTCC_ID_0, calibrationbits); 5.6.20.5.4.4 PLIB_RTCC_HalfSecondStatusGet Function C bool PLIB_RTCC_HalfSecondStatusGet( RTCC_MODULE_ID index ); Description The function returns the half second status bit, which is used in the calibration procedure. When the seconds byte is zero, the calibration value must be updated when the half second bit becomes '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Second half period of a second • false - First half period of a second Remarks This bit is read-only. It is cleared to '0' on a write to the seconds value. This function implements an operation of the HalfSecond feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsHalfSecond in your application to automatically determine whether this feature is available. Example // Wait for the half second status bit to be '1'. while(PLIB_RTCC_HalfSecondStatusGet(RTCC_ID_0)); 5.6.20.5.4.5 PLIB_RTCC_OutputSelect Function C void PLIB_RTCC_OutputSelect( RTCC_MODULE_ID index, RTCC_OUTPUT_SELECT data ); Description This function selects which signal will be presented on the RTCC pin. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2745 Parameters Parameters Description index Identifier for the device instance to be configured data Enumerated value of which signal to present Returns None. Remarks The RTCC module's output pin should be enabled using the function PLIB_RTCC_OutputEnable. This function implements an operation of the OutputSelect feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsOutputSelect in your application to automatically determine whether this feature is available. Example PLIB_RTCC_OutputSelect(RTCC_ID_0, RTCC_OUTPUT_SECONDS_CLOCK); 5.6.20.5.4.6 PLIB_RTCC_StopInIdleDisable Function C void PLIB_RTCC_StopInIdleDisable( RTCC_MODULE_ID index ); Description This function continues normal RTCC operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsStopInIdle in your application to automatically determine whether this feature is available. Example PLIB_RTCC_StopInIdleDisable(RTCC_ID_0); 5.6.20.5.4.7 PLIB_RTCC_StopInIdleEnable Function C void PLIB_RTCC_StopInIdleEnable( RTCC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2746 Description This function disables access to the RTCC module by the PBCLK when the CPU is in Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the StopInIdle feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_RTCC_ExistsStopInIdle in your application to automatically determine whether this feature is available. Example PLIB_RTCC_StopInIdleEnable(RTCC_ID_0); 5.6.20.5.5 Data Types and Constants 5.6.20.5.5.1 RTCC_ALARM_MASK_CONFIGURATION Enumeration C typedef enum { RTCC_ALARM_EVERY_HALF_SECOND, RTCC_ALARM_EVERY_SECOND, RTCC_ALARM_EVERY_10_SECONDS, RTCC_ALARM_EVERY_MINUTE, RTCC_ALARM_EVERY_10_MINUTES, RTCC_ALARM_EVERY_HOUR, RTCC_ALARM_ONCE_A_DAY, RTCC_ALARM_ONCE_A_WEEK, RTCC_ALARM_ONCE_A_MONTH, RTCC_ALARM_ONCE_A_YEAR } RTCC_ALARM_MASK_CONFIGURATION; Description Alarm Mask Configuration This data type defines the different configurations for accessing the alarm mask Configuration bits. Members Members Description RTCC_ALARM_EVERY_HALF_SECOND Alarm every half second RTCC_ALARM_EVERY_SECOND Alarm every second RTCC_ALARM_EVERY_10_SECONDS Alarm every 10 seconds RTCC_ALARM_EVERY_MINUTE Alarm every minute RTCC_ALARM_EVERY_10_MINUTES Alarm every 10 minutes RTCC_ALARM_EVERY_HOUR Alarm every hour RTCC_ALARM_ONCE_A_DAY Alarm every day 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2747 RTCC_ALARM_ONCE_A_WEEK Alarm every week RTCC_ALARM_ONCE_A_MONTH Alarm every month RTCC_ALARM_ONCE_A_YEAR Alarm every year Remarks The actual definition of this enumeration is device-specific. 5.6.20.5.5.2 RTCC_MODULE_ID Enumeration C typedef enum { RTCC_ID_1, RTCC_NUMBER_OF_MODULES } RTCC_MODULE_ID; Description Enumeration: RTCC_MODULE_ID This enumeration defines number of modules which are available on the microcontroller. This is the superset of all of the possible instances that may be available on the Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. Members Members Description RTCC_NUMBER_OF_MODULES The total number of modules available. 5.6.20.5.5.3 RTCC_VALUE_REGISTER_POINTER Enumeration C typedef enum { RTCC_REG_YEAR, RTCC_REG_DAY_MONTH, RTCC_REG_HOURS_WEEKDAY, RTCC_REG_MINUTES_SECONDS } RTCC_VALUE_REGISTER_POINTER; Description Value Register Pointer This data type defines the different configurations by which the RTCC Date and Time Registers can be accessed. Members Members Description RTCC_REG_YEAR The year register is being pointed RTCC_REG_DAY_MONTH The day and month register is being pointed RTCC_REG_HOURS_WEEKDAY The hours and weekday register is being pointed RTCC_REG_MINUTES_SECONDS The minutes and seconds register is being pointed Remarks The actual definition of this enumeration is device-specific. 5.6.20.5.6 Feature Existence Functions 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2748 5.6.20.5.6.1 PLIB_RTCC_ExistsAlarmChimeControl Function C bool PLIB_RTCC_ExistsAlarmChimeControl( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmChimeControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmChimeEnable • PLIB_RTCC_AlarmChimeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmChimeControl feature is supported on the device • false - The AlarmChimeControl feature is not supported on the device Remarks None. 5.6.20.5.6.2 PLIB_RTCC_ExistsAlarmControl Function C bool PLIB_RTCC_ExistsAlarmControl( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmEnable • PLIB_RTCC_AlarmDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmControl feature is supported on the device • false - The AlarmControl feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2749 Remarks None. 5.6.20.5.6.3 PLIB_RTCC_ExistsAlarmDate Function C bool PLIB_RTCC_ExistsAlarmDate( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmDate feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmDateGet • PLIB_RTCC_AlarmDateSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmDate feature is supported on the device • false - The AlarmDate feature is not supported on the device Remarks None. 5.6.20.5.6.4 PLIB_RTCC_ExistsAlarmMaskControl Function C bool PLIB_RTCC_ExistsAlarmMaskControl( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmMaskControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmMaskModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmMaskControl feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2750 • false - The AlarmMaskControl feature is not supported on the device Remarks None. 5.6.20.5.6.5 PLIB_RTCC_ExistsAlarmPulseInitial Function C bool PLIB_RTCC_ExistsAlarmPulseInitial( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmPulseInitialValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmPulseInitialSet • PLIB_RTCC_AlarmPulseInitialGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmPulseInitial feature is supported on the device • false - The AlarmPulseInitial feature is not supported on the device Remarks None. 5.6.20.5.6.6 PLIB_RTCC_ExistsAlarmRepeatControl Function C bool PLIB_RTCC_ExistsAlarmRepeatControl( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmRepeatControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmRepeatCountSet • PLIB_RTCC_AlarmRepeatCountRead Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2751 Returns • true - The AlarmRepeatControl feature is supported on the device • false - The AlarmRepeatControl feature is not supported on the device Remarks None. 5.6.20.5.6.7 PLIB_RTCC_ExistsAlarmSyncronization Function C bool PLIB_RTCC_ExistsAlarmSyncronization( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmSynchronization feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmReadSyncBit Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmSynchronization feature is supported on the device • false - The AlarmSynchronization feature is not supported on the device Remarks None. 5.6.20.5.6.8 PLIB_RTCC_ExistsAlarmTime Function C bool PLIB_RTCC_ExistsAlarmTime( RTCC_MODULE_ID index ); Description This function identifies whether the AlarmTime feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_AlarmTimeGet • PLIB_RTCC_AlarmTimeSet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2752 Parameters Parameters Description index Identifier for the device instance Returns • true - The AlarmTime feature is supported on the device • false - The AlarmTime feature is not supported on the device Remarks None. 5.6.20.5.6.9 PLIB_RTCC_ExistsCalibration Function C bool PLIB_RTCC_ExistsCalibration( RTCC_MODULE_ID index ); Description This function identifies whether the Calibration feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_DriftCalibrate Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Calibration feature is supported on the device • false - The Calibration feature is not supported on the device Remarks None. 5.6.20.5.6.10 PLIB_RTCC_ExistsClockRunning Function C bool PLIB_RTCC_ExistsClockRunning( RTCC_MODULE_ID index ); Description This function identifies whether the ClockRunning feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_ClockRunningStatus Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2753 Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockRunning feature is supported on the device • false - The ClockRunning feature is not supported on the device Remarks None. 5.6.20.5.6.11 PLIB_RTCC_ExistsClockSelect Function C bool PLIB_RTCC_ExistsClockSelect( RTCC_MODULE_ID index ); Description This function identifies whether the ClockSelect feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_SourceClockSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockSelect feature is supported on the device • false - The ClockSelect feature is not supported on the device Remarks None. 5.6.20.5.6.12 PLIB_RTCC_ExistsEnableControl Function C bool PLIB_RTCC_ExistsEnableControl( RTCC_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_Enable • PLIB_RTCC_Disable 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2754 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.20.5.6.13 PLIB_RTCC_ExistsHalfSecond Function C bool PLIB_RTCC_ExistsHalfSecond( RTCC_MODULE_ID index ); Description This function identifies whether the HalfSecond feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_HalfSecondStatusBit Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HalfSecond feature is supported on the device • false - The HalfSecond feature is not supported on the device Remarks None. 5.6.20.5.6.14 PLIB_RTCC_ExistsOutputControl Function C bool PLIB_RTCC_ExistsOutputControl( RTCC_MODULE_ID index ); Description This function identifies whether the OutputControl feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_ClockOutputEnable 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2755 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OutputControl feature is supported on the device • false - The OutputControl feature is not supported on the device Remarks None. 5.6.20.5.6.15 PLIB_RTCC_ExistsOutputSelect Function C bool PLIB_RTCC_ExistsOutputSelect( RTCC_MODULE_ID index ); Description This function identifies whether the OutputSelect feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_SecondsClockOutputSelect • PLIB_RTCC_AlarmPulseOutputSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OutputSelect feature is supported on the device • false - The OutputSelect feature is not supported on the device Remarks None. 5.6.20.5.6.16 PLIB_RTCC_ExistsRTCDate Function C bool PLIB_RTCC_ExistsRTCDate( RTCC_MODULE_ID index ); Description This function identifies whether the RTCDateValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2756 • PLIB_RTCC_RTCDateGet • PLIB_RTCC_RTCDateSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RTCDate feature is supported on the device • false - The RTCDate feature is not supported on the device Remarks None. 5.6.20.5.6.17 PLIB_RTCC_ExistsRTCTime Function C bool PLIB_RTCC_ExistsRTCTime( RTCC_MODULE_ID index ); Description This function identifies whether the RTCTimeValue feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_RTCTimeGet • PLIB_RTCC_RTCTimeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RTCTime feature is supported on the device • false - The RTCTime feature is not supported on the device Remarks None. 5.6.20.5.6.18 PLIB_RTCC_ExistsStopInIdleControl Function C bool PLIB_RTCC_ExistsStopInIdleControl( RTCC_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2757 Description This function identifies whether the StopInIdle feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_StopInIdleEnable • PLIB_RTCC_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.20.5.6.19 PLIB_RTCC_ExistsSynchronization Function C bool PLIB_RTCC_ExistsSynchronization( RTCC_MODULE_ID index ); Description This function identifies whether the Synchronization feature is available on the RTCC module. When this interface returns true, this function is supported on the device: • PLIB_RTCC_ValueRegistersReadSyncBit Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Synchronization feature is supported on the device • false - The Synchronization feature is not supported on the device Remarks None. 5.6.20.5.6.20 PLIB_RTCC_ExistsWriteEnable Function C bool PLIB_RTCC_ExistsWriteEnable( RTCC_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2758 ); Description This function identifies whether the WriteEnable feature is available on the RTCC module. When this interface returns true, these functions are supported on the device: • PLIB_RTCC_WriteEnable • PLIB_RTCC_WriteDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WriteEnable feature is supported on the device • false - The WriteEnable feature is not supported on the device Remarks None. 5.6.20.6 Files Files Name Description plib_rtcc.h Real-Time Clock and Calendar (RTCC) Peripheral Libarary interface header for RTCC common definitions. Description 5.6.20.6.1 plib_rtcc.h RTCC Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the RTCC Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the RTCC peripheral. Functions Name Description PLIB_RTCC_AlarmChimeDisable Disables the specific RTCC module's chime. PLIB_RTCC_AlarmChimeEnable Enables the specific RTCC module's chime. PLIB_RTCC_AlarmDateGet Returns the contents of the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDateSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDayGet Returns the contents of the Day bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmDaySet Writes to the specific RTCC module's Alarm Date value register. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2759 PLIB_RTCC_AlarmDisable Disables the specific RTCC module's alarm. PLIB_RTCC_AlarmEnable Enables the specific RTCC module's alarm. PLIB_RTCC_AlarmHourGet Returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmHourSet The function returns the contents of Hours bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMaskModeSelect Sets the specific RTCC module's alarm mask Configuration bits. PLIB_RTCC_AlarmMinuteGet Returns the contents of Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMinuteSet Returns the contents of the Minutes bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmMonthGet Returns the contents of the Month bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmMonthSet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmPulseInitialGet Returns the state of the initial alarm pulse. PLIB_RTCC_AlarmPulseInitialSet Enables the determination of the initial alarm pulse. PLIB_RTCC_AlarmRepeatCountGet Reads the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmRepeatCountSet Sets the specific RTCC module's alarm repeat counter. PLIB_RTCC_AlarmSecondGet Returns the contents of the Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmSecondSet Returns the contents of Seconds bits in the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeGet Returns the contents of the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmTimeSet Writes to the specific RTCC module's Alarm Time register. PLIB_RTCC_AlarmValueRegisterPointer Sets the specific RTCC module's Alarm register pointer. PLIB_RTCC_AlarmWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Alarm Date register. PLIB_RTCC_AlarmWeekDaySet Writes to the specific RTCC module's Alarm Date register. PLIB_RTCC_ClockOutputDisable Disables the specific RTCC module's output pin. PLIB_RTCC_ClockOutputEnable Enables the specific RTCC module's output pin. PLIB_RTCC_ClockRunningStatus Provides the status of the RTCC clock. PLIB_RTCC_ClockSourceSelect Selects the clock source for the RTCC module. PLIB_RTCC_Disable Disables the specific RTCC module on the device. PLIB_RTCC_DriftCalibrateGet Reads the specific RTCC module's drift calibration bits. PLIB_RTCC_DriftCalibrateSet Sets the specific RTCC module's drift calibration bits. PLIB_RTCC_Enable Enables the specific RTCC module on the device. PLIB_RTCC_ExistsAlarmChimeControl Identifies whether the AlarmChimeControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmControl Identifies whether the AlarmControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmDate Identifies whether the AlarmDate feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmMaskControl Identifies whether the AlarmMaskControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmPulseInitial Identifies whether the AlarmPulseInitial feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmRepeatControl Identifies whether the AlarmRepeatControl feature exists on the RTCC module. PLIB_RTCC_ExistsAlarmSyncronization Identifies whether the AlarmSynchronization feature exists on the RTCC module. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2760 PLIB_RTCC_ExistsAlarmTime Identifies whether the AlarmTime feature exists on the RTCC module. PLIB_RTCC_ExistsCalibration Identifies whether the Calibration feature exists on the RTCC module. PLIB_RTCC_ExistsClockRunning Identifies whether the ClockRunning feature exists on the RTCC module. PLIB_RTCC_ExistsClockSelect Identifies whether the ClockSelect feature exists on the RTCC module. PLIB_RTCC_ExistsEnableControl Identifies whether the EnableControl feature exists on the RTCC module. PLIB_RTCC_ExistsHalfSecond Identifies whether the HalfSecond feature exists on the RTCC module. PLIB_RTCC_ExistsOutputControl Identifies whether the OutputControl feature exists on the RTCC module. PLIB_RTCC_ExistsOutputSelect Identifies whether the OutputSelect feature exists on the RTCC module. PLIB_RTCC_ExistsRTCDate Identifies whether the RTCDateValue feature exists on the RTCC module. PLIB_RTCC_ExistsRTCTime Identifies whether the RTCTimeValue feature exists on the RTCC module. PLIB_RTCC_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the RTCC module. PLIB_RTCC_ExistsSynchronization Identifies whether the Synchronization feature exists on the RTCC module. PLIB_RTCC_ExistsWriteEnable Identifies whether the WriteEnable feature exists on the RTCC module. PLIB_RTCC_HalfSecondStatusGet The function returns the half second status bit. PLIB_RTCC_OutputSelect Selects which signal will be presented on the RTCC pin PLIB_RTCC_RTCDateGet Returns the contents of the specific RTCC module's Date register. PLIB_RTCC_RTCDateSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCDayGet Returns the contents of the Days bits in the specific RTCC module's Date register. PLIB_RTCC_RTCDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCHourGet Returns the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCHourSet Writes the contents of the Hours bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteGet Returns the contents of the Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMinuteSet Writes the contents of Minutes bits in the specific RTCC module's Time register. PLIB_RTCC_RTCMonthGet Returns the contents of the Months bits in the specific RTCC module's Date register. PLIB_RTCC_RTCMonthSet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCSecondGet The function returns the contents of the Seconds bits in the specific RTCC device's Time register. PLIB_RTCC_RTCSecondSet Writes the contents of Seconds bits in the specific RTCC module's Time register. PLIB_RTCC_RTCTimeGet Returns the contents of the specific RTCC module's Time register. PLIB_RTCC_RTCTimeSet Writes to the specific RTCC module's Time register. PLIB_RTCC_RTCWeekDayGet Returns the contents of the WeekDay bits in the specific RTCC module's Date register. PLIB_RTCC_RTCWeekDaySet Writes to the specific RTCC module's Date register. PLIB_RTCC_RTCYearGet Returns the contents of the Year bits in the specific RTCC module's Date register. PLIB_RTCC_RTCYearSet Writes to the specific RTCC module's Date register. PLIB_RTCC_StopInIdleDisable Continues normal RTCC operation when the device enters Idle mode. PLIB_RTCC_StopInIdleEnable Disables access to the RTCC module by the Peripheral Bus Clock (PBCLK) when the CPU enters Idle mode. 5.6 Peripheral Library Help MPLAB Harmony Help RTCC Peripheral Library 5-2761 PLIB_RTCC_WriteDisable Disables writing to the specific RTCC module's value registers. PLIB_RTCC_WriteEnable Enables writing to the specific RTCC module's value registers. Company Microchip Technology Inc. 5.6.21 System Bus Peripheral Library 5.6.21.1 Introduction System Bus Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the System Bus on Microchip microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description The System Bus is a multi-layer crossbar switching matrix that connects initiators to targets. An initiator is a device or peripheral that initiates a data transfer to or from a target. Examples of initiators include the CPU, DMA and Ethernet controller. A target is a memory, bus or peripheral that sends or receives data to/from an initiator. The System Bus allows the system programmer to control which initiators can access each target by defining permission groups for each initiator. Each target has one or more regions (physical address spaces) that can be individually programmed to allow access to different permission groups. By setting initiator permission groups and target region read/write permissions, the system programmer can allow or deny task or program access to system resources. 5.6.21.2 Release Notes MPLAB Harmony Version: v0.70b System Bus Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.21.3 SW License Agreement (c) 2013 Microchip Technology Inc. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2762 Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.21.4 Using the Library This topic describes the basic architecture of the System Bus Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_sb.h The interface to the System Bus Peripheral library is defined in the "plib_sb.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the System Bus Peripheral library should include "peripheral.h". Library File: The System Bus Peripheral library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the peripheral interacts with the framework. 5.6.21.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the System Bus on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description System Bus Software Abstraction Block Diagram 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2763 Hardware Abstraction Model The System Bus Peripheral Library provides interface routines to initialize the bus matrix such that: • Initiator permission groups are assigned • Target regions are defined and given read/write access permissions • Errors are identified, logged and cleared when a permission group violation occurs • CPU and DMA priorities are set 5.6.21.4.2 How the Library Works The System Bus is a crossbar interconnect matrix that provides for simultaneous data transfer between the CPU, memory, and various peripherals on the PIC32 device. In addition, it provides a protection mechanism that allows trusted code to define and restrict access to memory regions and peripherals. A typical application would be a secure bootloader that prevents a third party or untrusted application from accessing regions of Flash memory that contain privileged code or information. The protection mechanism works by dividing the target physical address space into regions, each of which may be accessed by one or more initiators. Individual targets may have one or more regions. Each region can be individually programmed to allow read or write access to one or more permission groups. Each initiator is assigned to a permission group. This library provides interface routines to initialize the System Bus and initiator permission groups. On reset or NMI, the CPU is assigned to permission group 0 (full access). Note: Please refer to the PIC32 Family Reference Manual and specific device data sheet for information on target region mapping and initiator permission groups for a specific device. 5.6.21.4.2.1 Initator Initialization Initializing the initiators for the System Bus is a two-step process: 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2764 • Set CPU and DMA priorities (if needed) • Assign permission groups to each initiator Priority assignments for CPU and DMA By default, the System Bus uses a least-recently-serviced (LRS) priority arbitration scheme for most initiators, including the CPU and DMA. For applications that require low latency, the user may set the CPU and/or DMA arbitration to fixed high priority. For the CPU, fixed high priority means that the CPU gets arbitration preference while servicing an interrupt over all initiators using LRS arbitration. Priority is set using the PLIB_SB_CPUPrioritySet() and PLIB_SB_DMAPrioritySet() library functions. These functions write to a register that must be unlocked first. The PLIB_SB_PriorityUnlock() is provided for this purpose. Initiator permission groups At reset, all initiators default to permission group 0. Each target region can be individually programmed to allow read or write access to any or all permission groups. By assigning permission groups to initiators and restricting target region read/write access based on permission group, it is possible to restrict initiator access to target regions during normal operations. Permission groups are assigned using the library function PLIB_SB_InitPermGrpSet(). 5.6.21.4.2.2 Target Initialization Each System Bus target resides in a physical address space that contains one or more regions. Regions are used to provide separate access permissions for different areas within a target address space. Region 0 for any target is defined as the entire address space for that target. At reset, region 0 for all targets is accessible by any initiator with group 0 permissions. Target regions are defined by base (physical) address and size. Read and write permissions are programmed individually for each region. The number of regions for each target varies, depending on the target. Some regions have fixed addresses, sizes and/or permissions. For example, region 0 for all targets encompasses the entire address space for the target, so the address and size are pre-programmed. Similarly, write permission for PFM is disabled for all initiators except the Flash controller. Target region initialization is a four step process: 1. Set the base address of a region using PLIB_SB_PGRegionAddrSet(). This function takes an enumerated value for the target region. Only valid target regions should be enumerated for any specific device. 2. Set the size of the region using PLIB_SB_PGRegionSizeSet(). 3. Set the read permissions using PLIB_SB_PGRegionReadPermSet(). 4. Set the write permissions using PLIB_SB_PGRegionWritePermSet(). Note: Please refer to the Memory Organization Family Reference Manual section and the specific device data sheet for information on target region mapping and initiator permission groups. 5.6.21.4.2.3 PGV Error Handling A permission group violation (PGV) occurs when an initiator attempts to access a target without the proper permissions. Any permission group violation will trigger an interrupt to the CPU. If enabled, the System Bus will report a PGV to the error log registers in the System Bus. The PGV interrupt handler can then use this library to retrieve information about the violation and act accordingly. By default, error reporting is disabled in the System Bus and must be enabled during the startup or boot code. Errors are divided into two categories: primary and secondary. Primary errors are errors arising from secure accesses, such as trying to access a target region without the proper permissions. Secondary errors are errors arising from non-secure accesses, such as trying to access a memory location outside of a target region. PIC32 devices support logging of primary errors only. Primary error logging is enabled using the library function PLIB_SB_PGVErrorReportPrimaryEnable(). Primary error reporting can be disabled using the library function 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2765 PLIB_SB_PGVErrorReportPrimaryDisable(). Error logging must be enabled or disabled separately for each target. Once a permission group violation error is logged, the user can use this library to retrieve information from the System Bus error log registers. Each target has its own set of error log registers. The error information available and the library API used to retrieve it are shown in the table below. Error Log Data System Bus Peripheral Library Function Has the specified target reported an error? PLIB_SB_PGVErrorStatus() Has the specified target reported more than one error since last cleared? PLIB_SB_PGVErrorMulti() Type of error. PLIB_SB_PGVErrorCode() Initiator ID. PLIB_SB_PGVErrorInitiatorID() OCP command code of the transaction. PLIB_SB_PGVErrorCommandCode() The region number of the specified target accessed during the violation. PLIB_SB_PGVErrorRegion() Permission group of initiator that caused the violation. PLIB_SB_PGVErrorPermissionGroup() Once an error is logged, it needs to be cleared by software before any data for a subsequent violation can be logged (for the same target). This is typically done in the exception handler that reads the data. Which function is used depends on whether a single or multiple error violation occurred. Single violations are cleared with PLIB_SB_PGVErrorClearSingle(), and multiple violations are cleared with PLIB_SB_PGVErrorClearMulti(). 5.6.21.5 Configuring the Library The library is configured for the supported System Bus module when the processor is chosen in the MPLAB IDE. 5.6.21.6 Library Interface Data Types and Constants Name Description PLIB_SB_ARB_POLICY This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. PLIB_SB_ERROR Lists the possible SB Transaction Error Codes PLIB_SB_INIT_ID Lists the possible SB Initiator IDs. PLIB_SB_INIT_PG Lists the possible Initiator permission groups PLIB_SB_OCP_CMD_CODE Lists the possible OCP Command codes. PLIB_SB_PG_INITIATOR Lists the possible permission group Initiators PLIB_SB_REGION_PG This enumeration lists the possible permission groups assigned to a region for read and/or write access. PLIB_SB_TGT_ID Lists the possible SB Target IDs PLIB_SB_TGT_REGION Lists the programmable target regions SB_MODULE_ID Lists the possible Module IDs for the system bus. Feature Existence Functions Name Description PLIB_SB_ExistsCPUPriority Identifies whether the CPUPriority feature exists on the SB module 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2766 PLIB_SB_ExistsDMAPriority Identifies whether the DMAPriority feature exists on the SB module PLIB_SB_ExistsInitPermGrp Identifies whether the InitPermGrp feature exists on the SB module PLIB_SB_ExistsPGRegAddr Identifies whether the PGRegAddr feature exists on the SB module PLIB_SB_ExistsPGRegRdPerm Identifies whether the PGRegRdPerm feature exists on the SB module PLIB_SB_ExistsPGRegSize Identifies whether the PGRegSize feature exists on the SB module PLIB_SB_ExistsPGRegWrPerm Identifies whether the PGRegWrPerm feature exists on the SB module PLIB_SB_ExistsPGVErrClear Identifies whether the PGVErrClear feature exists on the SB module PLIB_SB_ExistsPGVErrClrMulti Identifies whether the PGVErrClrMulti feature exists on the SB module PLIB_SB_ExistsPGVErrClrSingle Identifies whether the PGVErrClrSingle feature exists on the SB module PLIB_SB_ExistsPGVErrCmdCode Identifies whether the PGVErrCmdCode feature exists on the SB module PLIB_SB_ExistsPGVErrInitID Identifies whether the PGVErrInitID feature exists on the SB module PLIB_SB_ExistsPGVErrPG Identifies whether the PGVErrPG feature exists on the SB module PLIB_SB_ExistsPGVErrRegion Identifies whether the PGVErrRegion feature exists on the SB module PLIB_SB_ExistsPGVErrRptPri Identifies whether the PGVErrRptPri feature exists on the SB module PLIB_SB_ExistsPGVErrStatus Identifies whether the PGVErrStatus feature exists on the SB module Other Functions Name Description PLIB_SB_CPUPrioritySet Sets the CPU arbitration policy to SRAM when servicing an interrupt PLIB_SB_DMAPrioritySet Sets the DMA arbitration policy PLIB_SB_InitPermGrpSet Sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. PGV Error Functions Name Description PLIB_SB_PGVErrorClearMulti Clears multiple permission group errors for the specified target. PLIB_SB_PGVErrorClearSingle Clears a single permission group error for the specified target. PLIB_SB_PGVErrorCode Returns a value corresponding to the type of error logged for the specified target. PLIB_SB_PGVErrorCommandCode Returns the OCP command code of the transaction that caused the protection violation for the specified target. PLIB_SB_PGVErrorInitiatorID Returns the ID of the Initiator that caused the protection violation PLIB_SB_PGVErrorLogClearMulti Clears a multiple protection group violations error from the specified target error log register. PLIB_SB_PGVErrorLogClearSingle Clears a single protection group violation error from the specified target error log register. PLIB_SB_PGVErrorMulti Indicates if more than one perimission group violation has occurred since last cleared. PLIB_SB_PGVErrorPermissionGroup Returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. PLIB_SB_PGVErrorRegion Returns the number of the protection region in the specified target address space that caused the protection violation. PLIB_SB_PGVErrorReportPrimaryDisable Disables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorReportPrimaryEnable Enables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorStatus Identifies whether a permission group violation has been reported for the specified target. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2767 Target Initialization Functions Name Description PLIB_SB_PGRegionAddrGet Returns the base address for a permission group region within a target's physical address space. PLIB_SB_PGRegionAddrSet Sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermClear Clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermSet Sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionSizeGet Returns the size for a permission group region within a target's physical address space. PLIB_SB_PGRegionSizeSet Sets the size for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermClear Clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermSet Sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. Description This section describes the Application Programming Interface (API) functions of the System Bus Peripheral Library. Refer to each section for a detailed description. 5.6.21.6.1 Target Initialization Functions 5.6.21.6.1.1 PLIB_SB_PGRegionAddrGet Function C uint32_t PLIB_SB_PGRegionAddrGet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region ); Description This function returns the base address for a permission group region within a target's physical address space. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region for which the address is returned. Returns uint32_t - The base address of the region. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2768 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example uint32_t T1R6BaseAddress; T1R6BaseAddress = PLIB_SB_PGRegionAddrGet(SB_ID_1, PLIB_T1_REGION_6); 5.6.21.6.1.2 PLIB_SB_PGRegionAddrSet Function C void PLIB_SB_PGRegionAddrSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t phys_addr ); Description This function sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region for which the base address is set. phys_addr The base address of the region. Must be aligned to the intended size of the region. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets have a defined start address which may not be changed. Some regions (such as those containing peripheral SFRs) are fixed and may not be changed. Please refer to the specific device data sheet for details. Example // Set up two regions in PFM with full read and write permission #define REGION_5_BASE_ADDR 0x1D000000 #define REGION_6_BASE_ADDR (REGION5_BASE_ADDR + (32*1024)) #define REGION_5_SIZE 0x06 // 32KB #define REGION_6_SIZE 0x05 // 16KB #define FULL_PERM (REGION_PG_0 | REGION_PG_1 | REGION_PG_2 | REGION_PG_3) PLIB_SB_PGRegionAddrSet(SB_ID_1, PLIB_SB_T1_REGION_5, REGION_5_BASE_ADDR); PLIB_SB_PGRegionAddrSet(SB_ID_1, PLIB_SB_T1_REGION_6, REGION_6_BASE_ADDR); PLIB_SB_PGRegionSizeSet(SB_ID_1, PLIB_SB_T1_REGION_5, REGION_5_SIZE); PLIB_SB_PGRegionSizeSet(SB_ID_1, PLIB_SB_T1_REGION_6, REGION_6_SIZE); PLIB_SB_PGRegionReadPermSet(SB_ID_1, PLIB_T1_REGION_5, FULL_PERM); PLIB_SB_PGRegionReadPermSet(SB_ID_1, PLIB_T1_REGION_6, FULL_PERM); PLIB_SB_PGRegionWritePermSet(SB_ID_1, PLIB_T1_REGION_5, FULL_PERM); PLIB_SB_PGRegionWritePermSet(SB_ID_1, PLIB_T1_REGION_6, FULL_PERM); 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2769 5.6.21.6.1.3 PLIB_SB_PGRegionReadPermClear Function C void PLIB_SB_PGRegionReadPermClear( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm ); Description This function clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. readPerm Bitwise OR of the groups given read permission for the region. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is read permission for all groups. Example See code example for PLIB_SB_PGRegionAddrSet(). 5.6.21.6.1.4 PLIB_SB_PGRegionReadPermSet Function C void PLIB_SB_PGRegionReadPermSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG readPerm ); Description This function sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2770 region The region number within the target's address space to be given permissions. Not all regions are programmable. readPerm Bitwise OR of the groups given read permission for the region. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is read permission for all groups. Example See code example for PLIB_SB_PGRegionAddrSet(). 5.6.21.6.1.5 PLIB_SB_PGRegionSizeGet Function C uint32_t PLIB_SB_PGRegionSizeGet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region ); Description This function returns the size for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region for which the size is to be set. Not all regions are programmable. Returns The size of the region. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets encompasses the entire address range of the target, and may not be changed. Some regions (such as those containing peripheral SFRs) may not be changed. Please refer to the specific device data sheet for details. Example uint32_t T1R6Size; T1R6Size = PLIB_SB_PGRegionSizeGet(SB_ID_1, PLIB_T1_REGION_6); 5.6.21.6.1.6 PLIB_SB_PGRegionSizeSet Function C void PLIB_SB_PGRegionSizeSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, uint32_t size ); 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2771 Description This function sets the size for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region for which the size is to be set. Not all regions are programmable. size The actual size of the region being programmed is calculted as follows 2**(size-1)*1024 bytes Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Region 0 of all targets encompasses the entire address range of the target, and may not be changed. Some regions (such as those containing peripheral SFRs) may not be changed. Please refer to the specific device data sheet for details. Example See code example for PLIB_SB_PGRegionAddrSet(). 5.6.21.6.1.7 PLIB_SB_PGRegionWritePermClear Function C void PLIB_SB_PGRegionWritePermClear( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm ); Description This function clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. writePerm Bitwise OR of the groups given read permission for the region. Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2772 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is write permission for all groups. Some regions may not be programmable by all initiators (flash, for example). Please refer to the specific device data sheet for details. Example See code example for PLIB_SB_PGRegionAddrSet(). 5.6.21.6.1.8 PLIB_SB_PGRegionWritePermSet Function C void PLIB_SB_PGRegionWritePermSet( SB_MODULE_ID index, PLIB_SB_TGT_REGION region, PLIB_SB_REGION_PG writePerm ); Description This function sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. Preconditions None. Parameters Parameters Description index Identifier for the device instance. region The region number within the target's address space to be given permissions. Not all regions are programmable. writePerm Bitwise OR of the groups given read permission for the region. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Default reset value for all programmable regions is write permission for all groups. Some regions may not be programmable by all initiators (flash, for example). Please refer to the specific device data sheet for details. Example See code example for PLIB_SB_PGRegionAddrSet(). 5.6.21.6.2 PGV Error Functions 5.6.21.6.2.1 PLIB_SB_PGVErrorClearMulti Function C bool PLIB_SB_PGVErrorClearMulti( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2773 Description This function clears multiple permission group errors for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns mult - Returns the value of the CLEAR bit in the SBTxECLRM register for the specified target. The act of reading this bit clears the error. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example bool mult; mult = PLIB_SB_PGVErrorClearMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.2 PLIB_SB_PGVErrorClearSingle Function C bool PLIB_SB_PGVErrorClearSingle( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function clears a single permission group error for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns sing - Returns the value of the CLEAR bit in the SBTxECLRM register for the specified target. The act of reading this bit clears the error. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example bool sing; sing = PLIB_SB_PGVErrorClearSingle(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2774 5.6.21.6.2.3 PLIB_SB_PGVErrorCode Function C PLIB_SB_ERROR PLIB_SB_PGVErrorCode( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function returns a value corresponding to the type of error logged for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target to be read. Returns PLIB_SB_ERROR enumeration representing the type of SB error logged states. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example PLIB_SB_ERROR error; error = PLIB_SB_ERROR PLIB_SB_PGVErrorCode(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.4 PLIB_SB_PGVErrorCommandCode Function C PLIB_SB_OCP_CMD_CODE PLIB_SB_PGVErrorCommandCode( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function returns the OCP command code of the transaction that caused the protection violation for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns OCP command code Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2775 Example PLIB_SB_OCP_CMD_CODE commandCode; commandCode = PLIB_SB_PGVErrorCommandCode(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.5 PLIB_SB_PGVErrorInitiatorID Function C PLIB_SB_INIT_ID PLIB_SB_PGVErrorInitiatorID( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function returns the ID of the Initiator that caused the protection violation. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns An enumerated value representing the ID of the initiator that caused the protection violation. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example PLIB_SB_INIT_ID id; id = PLIB_SB_PGVErrorInitiatorID(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.6 PLIB_SB_PGVErrorLogClearMulti Function C void PLIB_SB_PGVErrorLogClearMulti( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function clears a multiple protection group violations error from the specified target error log register. Multiple errors are cleared by writing a '1' to both the MULTI and CODE fields of the SBTxELOG1 register for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target to be cleared. Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2776 Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example PLIB_SB_PGVErrorLogClearMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.7 PLIB_SB_PGVErrorLogClearSingle Function C void PLIB_SB_PGVErrorLogClearSingle( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function clears a single protection group violation error from the specified target error log register. Single errors are cleared by writing a '1' to the CODE field of the SBTxELOG1 register for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target to be cleared. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example PLIB_SB_PGVErrorLogClearSingle(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.8 PLIB_SB_PGVErrorMulti Function C bool PLIB_SB_PGVErrorMulti( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function indicates if more than one perimission group violation has occurred since last cleared. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target to be read. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2777 Returns true - Multiple permission group violations. false - Single or no permission group violations. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example bool multiPGV; multiPGV = PLIB_SB_PGVErrorMulti(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.9 PLIB_SB_PGVErrorPermissionGroup Function C int PLIB_SB_PGVErrorPermissionGroup( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example int pg; pg = PLIB_SB_PGVErrorPermissionGroup(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.10 PLIB_SB_PGVErrorRegion Function C int PLIB_SB_PGVErrorRegion( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function returns the number of the protection region in the specified target address space that caused the protection violation. Note that if there are no other region matches, region 0 (the default region that spans the entire target address space) will always match, and this function will return 0. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2778 Parameters Parameters Description index Identifier for the device instance. target The target. Returns Region number in target address space or -1 on unrecognized target. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example int region; region = PLIB_SB_PGVErrorRegion(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.11 PLIB_SB_PGVErrorReportPrimaryDisable Function C void PLIB_SB_PGVErrorReportPrimaryDisable( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function disables primary permission group error reporting for the specified target to the SB flag register. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Reporting of primary errors is disabled at reset. Example PLIB_SB_PGVErrorReportPrimaryDisable(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.12 PLIB_SB_PGVErrorReportPrimaryEnable Function C void PLIB_SB_PGVErrorReportPrimaryEnable( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function enables primary permission group error reporting for the specified target to the SB flag register. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2779 Preconditions None. Parameters Parameters Description index Identifier for the device instance. target The target. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Reporting of primary errors is disabled at reset. Example PLIB_SB_PGVErrorReportPrimaryEnable(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.2.13 PLIB_SB_PGVErrorStatus Function C bool PLIB_SB_PGVErrorStatus( SB_MODULE_ID index, PLIB_SB_TGT_ID target ); Description This function identifies whether a permission group violation has been reported for the specified target. Preconditions None. Parameters Parameters Description index Identifier for the device instance. target Target to be checked. Returns true - Target is reporting a permission group violation. false - Target is not reporting a permission group violation. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. Example bool sbPgv; sbPgv = PLIB_SB_PGVErrorStatus(SB_ID_1, PLIB_SB_TGT_ID_T0); 5.6.21.6.3 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2780 5.6.21.6.3.1 PLIB_SB_ARB_POLICY Enumeration C typedef enum { PRIORITY_LRS, PRIORITY_HI } PLIB_SB_ARB_POLICY; Description SB Arbitration Policy This enumeration lists the possible arbitration policies that can be assigned to the CPU and DMA for SRAM access. Members Members Description PRIORITY_LRS Least Recently Serviced Arbitration PRIORITY_HI High Priority 5.6.21.6.3.2 PLIB_SB_ERROR Enumeration C typedef enum { PLIB_SB_ERROR_NONE, PLIB_SB_ERROR_PGV } PLIB_SB_ERROR; Description PG Error Code This enumeration lists the possible transacton error codes for the SB. Members Members Description PLIB_SB_ERROR_NONE No Error PLIB_SB_ERROR_PGV Permission Group Violation 5.6.21.6.3.3 PLIB_SB_INIT_ID Enumeration C typedef enum { PLIB_SB_INIT_ID_NONE, PLIB_SB_INIT_ID_CPU_LRS, PLIB_SB_INIT_ID_CPU_HI, PLIB_SB_INIT_ID_DMA1_RD_LRS, PLIB_SB_INIT_ID_DMA1_RD_HI, PLIB_SB_INIT_ID_DMA1_WR_LRS, PLIB_SB_INIT_ID_DMA1_WR_HI, PLIB_SB_INIT_ID_USB1, PLIB_SB_INIT_ID_ETH1_RD, PLIB_SB_INIT_ID_ETH1_WR, PLIB_SB_INIT_ID_CAN1, PLIB_SB_INIT_ID_CAN2, PLIB_SB_INIT_ID_SQI1, PLIB_SB_INIT_ID_FLASH_CTL, PLIB_SB_INIT_ID_CRYPTO } PLIB_SB_INIT_ID; 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2781 Description SB Initator ID This enumeration lists the possible SB Initiator IDs. This ID is used for self-reporting and error logging. LRS and HI are SB arbitration schemes set by the soft configuration register CFGCON. 5.6.21.6.3.4 PLIB_SB_INIT_PG Enumeration C typedef enum { PLIB_SB_INIT_PG_0, PLIB_SB_INIT_PG_1, PLIB_SB_INIT_PG_2, PLIB_SB_INIT_PG_3 } PLIB_SB_INIT_PG; Description SB Initiator Permission Groups This enumeration lists the possible initiator permission groups for the SB. Members Members Description PLIB_SB_INIT_PG_0 Privilege Group 0 PLIB_SB_INIT_PG_1 Privilege Group 1 PLIB_SB_INIT_PG_2 Privilege Group 2 PLIB_SB_INIT_PG_3 Privilege Group 3 Remarks These values are used to program the CFGPG soft configuration register, which is not part of the SB. This should be done by the boot code to set up the desired initiator permissions prior to programming the SB. 5.6.21.6.3.5 PLIB_SB_OCP_CMD_CODE Enumeration C typedef enum { PLIB_SB_OCP_CMD_IDLE, PLIB_SB_OCP_CMD_WRITE, PLIB_SB_OCP_CMD_READ, PLIB_SB_OCP_CMD_READEX, PLIB_SB_OCP_CMD_WRITE_NON_POST, PLIB_SB_OCP_CMD_BROADCAST } PLIB_SB_OCP_CMD_CODE; Description OCP Command Codes This enumeration lists the possible OCP command codes. An OCP command code is logged when a transaction violation occurs. The command code of the offending command can then be read. 5.6.21.6.3.6 PLIB_SB_PG_INITIATOR Enumeration C typedef enum { PLIB_SB_PG_INITIATOR_CPU, 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2782 PLIB_SB_PG_INITIATOR_DMA1, PLIB_SB_PG_INITIATOR_USB1, PLIB_SB_PG_INITIATOR_CAN1, PLIB_SB_PG_INITIATOR_CAN2, PLIB_SB_PG_INITIATOR_ETH1, PLIB_SB_PG_INITIATOR_SQI1, PLIB_SB_PG_INITIATOR_FLASH_CTL, PLIB_SB_PG_INITIATOR_CRYPTO } PLIB_SB_PG_INITIATOR; Description SB Initators This enumeration lists the possible permission group Initiators 5.6.21.6.3.7 PLIB_SB_REGION_PG Enumeration C typedef enum { REGION_PG_0, REGION_PG_1, REGION_PG_2, REGION_PG_3 } PLIB_SB_REGION_PG; Description SB Region Permission Groups Lists the possible permission groups assigned to a region for read and/or write access. Members Members Description REGION_PG_0 Privilege Group 0 has read/write permission REGION_PG_1 Privilege Group 1 has read/write permission REGION_PG_2 Privilege Group 2 has read/write permission REGION_PG_3 Privilege Group 3 has read/write permission 5.6.21.6.3.8 PLIB_SB_TGT_ID Enumeration C typedef enum { PLIB_SB_TGT_ID_T0, PLIB_SB_TGT_ID_T1, PLIB_SB_TGT_ID_T2, PLIB_SB_TGT_ID_T3, PLIB_SB_TGT_ID_T4, PLIB_SB_TGT_ID_T5, PLIB_SB_TGT_ID_T6, PLIB_SB_TGT_ID_T7, PLIB_SB_TGT_ID_T8, PLIB_SB_TGT_ID_T9, PLIB_SB_TGT_ID_T10, PLIB_SB_TGT_ID_T11, PLIB_SB_TGT_ID_T12, PLIB_SB_TGT_ID_T13 } PLIB_SB_TGT_ID; Description SB Target ID 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2783 This enumeration lists the possible SB Target IDs Members Members Description PLIB_SB_TGT_ID_T0 System Bus PLIB_SB_TGT_ID_T1 Prefetch Module PLIB_SB_TGT_ID_T2 Data RAM 1 PLIB_SB_TGT_ID_T3 Data RAM 2 PLIB_SB_TGT_ID_T4 External Bus Interface PLIB_SB_TGT_ID_T5 Peripheral Bus 1 PLIB_SB_TGT_ID_T6 Peripheral Bus 2 PLIB_SB_TGT_ID_T7 Peripheral Bus 3 PLIB_SB_TGT_ID_T8 Peripheral Bus 4 PLIB_SB_TGT_ID_T9 Peripheral Bus 5 PLIB_SB_TGT_ID_T10 USB PLIB_SB_TGT_ID_T11 Serial Quad Interface PLIB_SB_TGT_ID_T12 Crypto PLIB_SB_TGT_ID_T13 Random Number Generator 5.6.21.6.3.9 PLIB_SB_TGT_REGION Enumeration C typedef enum { PLIB_SB_T0_REGION_0, PLIB_SB_T0_REGION_1, PLIB_SB_T1_REGION_0, PLIB_SB_T1_REGION_1, PLIB_SB_T1_REGION_2, PLIB_SB_T1_REGION_3, PLIB_SB_T1_REGION_4, PLIB_SB_T1_REGION_5, PLIB_SB_T1_REGION_6, PLIB_SB_T1_REGION_7, PLIB_SB_T1_REGION_8, PLIB_SB_T2_REGION_0, PLIB_SB_T2_REGION_1, PLIB_SB_T2_REGION_2, PLIB_SB_T3_REGION_0, PLIB_SB_T3_REGION_1, PLIB_SB_T3_REGION_2, PLIB_SB_T4_REGION_0, PLIB_SB_T4_REGION_1, PLIB_SB_T4_REGION_2, PLIB_SB_T5_REGION_0, PLIB_SB_T5_REGION_1, PLIB_SB_T5_REGION_2, PLIB_SB_T6_REGION_0, PLIB_SB_T6_REGION_1, PLIB_SB_T7_REGION_0, PLIB_SB_T7_REGION_1, PLIB_SB_T8_REGION_0, PLIB_SB_T8_REGION_1, PLIB_SB_T9_REGION_0, PLIB_SB_T9_REGION_1, PLIB_SB_T10_REGION_0, PLIB_SB_T11_REGION_0, PLIB_SB_T11_REGION_1, PLIB_SB_T12_REGION_0, 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2784 PLIB_SB_T13_REGION_0 } PLIB_SB_TGT_REGION; Description Regions This enumeration lists the programmable SB target regions. Members Members Description PLIB_SB_T0_REGION_0 System Bus Region 0 PLIB_SB_T0_REGION_1 System Bus Region 1 PLIB_SB_T1_REGION_0 Prefetch Module Region 0 PLIB_SB_T1_REGION_1 Prefetch Module Region 1 PLIB_SB_T1_REGION_2 Prefetch Module Region 2 PLIB_SB_T1_REGION_3 Prefetch Module Region 3 PLIB_SB_T1_REGION_4 Prefetch Module Region 4 PLIB_SB_T1_REGION_5 Prefetch Module Region 5 PLIB_SB_T1_REGION_6 Prefetch Module Region 6 PLIB_SB_T1_REGION_7 Prefetch Module Region 7 PLIB_SB_T1_REGION_8 Prefetch Module Region 8 PLIB_SB_T2_REGION_0 Data RAM 1 Region 0 PLIB_SB_T2_REGION_1 Data RAM 1 Region 1 PLIB_SB_T2_REGION_2 Data RAM 1 Region 2 PLIB_SB_T3_REGION_0 Data RAM 2 Region 0 PLIB_SB_T3_REGION_1 Data RAM 2 Region 1 PLIB_SB_T3_REGION_2 Data RAM 2 Region 2 PLIB_SB_T4_REGION_0 External Bus Interface Region 0 PLIB_SB_T4_REGION_1 External Bus Interface Region 1 PLIB_SB_T4_REGION_2 External Bus Interface Region 2 PLIB_SB_T5_REGION_0 Peripheral Bus 1 Region 0 PLIB_SB_T5_REGION_1 Peripheral Bus 1 Region 1 PLIB_SB_T5_REGION_2 Peripheral Bus 1 Region 2 PLIB_SB_T6_REGION_0 Peripheral Bus 2 Region 0 PLIB_SB_T6_REGION_1 Peripheral Bus 2 Region 1 PLIB_SB_T7_REGION_0 Peripheral Bus 3 Region 0 PLIB_SB_T7_REGION_1 Peripheral Bus 3 Region 1 PLIB_SB_T8_REGION_0 Peripheral Bus 4 Region 0 PLIB_SB_T8_REGION_1 Peripheral Bus 4 Region 1 PLIB_SB_T9_REGION_0 Peripheral Bus 5 Region 0 PLIB_SB_T9_REGION_1 Peripheral Bus 5 Region 1 PLIB_SB_T10_REGION_0 USB Region 0 PLIB_SB_T11_REGION_0 Serial Quad Interface Region 0 PLIB_SB_T11_REGION_1 Serial Quad Interface Region 1 PLIB_SB_T12_REGION_0 Crytpo Region 9 PLIB_SB_T13_REGION_0 Random Number Generator 0 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2785 5.6.21.6.3.10 SB_MODULE_ID Enumeration C typedef enum { SB_ID_1, SB_NUMBER_OF_MODULES } SB_MODULE_ID; Description Module ID This enumeration lists the possible Module IDs for the system bus. Remarks Refer to the data sheet to get the correct number of modules defined for the desired device. 5.6.21.6.4 Other Functions 5.6.21.6.4.1 PLIB_SB_CPUPrioritySet Function C void PLIB_SB_CPUPrioritySet( SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority ); Description This function sets the CPU arbitration policy to SRAM when servicing an interrupt. Preconditions System must be unlocked before the priority can be set. Parameters Parameters Description priority Use either high priority or least-recently-serviced algorithm. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGCON, which is not part of the SB. This should be done by the boot code prior to programming the SB. Note that the system must be unlocked before the priority can be set. Default at reset is PRIORITY_LRS. Example PLIB_SB_PriorityUnlock(); PLIB_SB_CPUPrioritySet(SB_ID_1, PRIORITY_HI); 5.6.21.6.4.2 PLIB_SB_DMAPrioritySet Function C void PLIB_SB_DMAPrioritySet( 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2786 SB_MODULE_ID index, PLIB_SB_ARB_POLICY priority ); Description This function sets the DMA arbitration. Preconditions System must be unlocked before the priority can be set. Parameters Parameters Description priority Use either high priority or least-recently-serviced algorithm. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGCON, which is not part of the SB. This should be done by the boot code prior to programming the SB. Note that the system must be unlocked before the priority can be set. Default at reset is PRIORITY_LRS. Example PLIB_SB_PriorityUnlock(); void PLIB_SB_DMAPrioritySet(SB_ID_1, PRIORITY_HI); 5.6.21.6.4.3 PLIB_SB_InitPermGrpSet Function C void PLIB_SB_InitPermGrpSet( SB_MODULE_ID index, PLIB_SB_PG_INITIATOR initiator, PLIB_SB_INIT_PG pg ); Description This function sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. Preconditions None. Parameters Parameters Description initiator The initiator for which permission groups are assigned. pg The permission group(s) to which the initiator is assigned. Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet for availability. This function writes to the soft configuration register CFGPG, which is not part of the SB. Permission groups should be assigned 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2787 by the boot code prior to programming the SB. Default permission group at reset for all initiators is 0. After an NMI, the CPU permission group reverts to 0. All other initiator permission groups remain unchanged. The effective CPU permission group value in debug mode is controlled by boot configuration value DBGPER[2:0]. If DBGPER denies access to the group CPU1PG selects, the effective value selects group 3. Example PLIB_SB_InitPermGrpSet(SB_ID_1, PLIB_SB_PG_INITIATOR_CPU, PLIB_SB_INIT_PG_1); 5.6.21.6.5 Feature Existence Functions 5.6.21.6.5.1 PLIB_SB_ExistsCPUPriority Function C bool PLIB_SB_ExistsCPUPriority( SB_MODULE_ID index ); Description This function identifies whether the CPUPriority feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_CPUPrioritySet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CPUPriority feature is supported on the device • false - The CPUPriority feature is not supported on the device Remarks None. 5.6.21.6.5.2 PLIB_SB_ExistsDMAPriority Function C bool PLIB_SB_ExistsDMAPriority( SB_MODULE_ID index ); Description This function identifies whether the DMAPriority feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_DMAPrioritySet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2788 Parameters Parameters Description index Identifier for the device instance Returns • true - The DMAPriority feature is supported on the device • false - The DMAPriority feature is not supported on the device Remarks None. 5.6.21.6.5.3 PLIB_SB_ExistsInitPermGrp Function C bool PLIB_SB_ExistsInitPermGrp( SB_MODULE_ID index ); Description This function identifies whether the InitPermGrp feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_InitPermGrpSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InitPermGrp feature is supported on the device • false - The InitPermGrp feature is not supported on the device Remarks None. 5.6.21.6.5.4 PLIB_SB_ExistsPGRegAddr Function C bool PLIB_SB_ExistsPGRegAddr( SB_MODULE_ID index ); Description This function identifies whether the PGRegAddr feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionAddrSet • PLIB_SB_PGRegionAddrGet 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2789 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGRegAddr feature is supported on the device • false - The PGRegAddr feature is not supported on the device Remarks None. 5.6.21.6.5.5 PLIB_SB_ExistsPGRegRdPerm Function C bool PLIB_SB_ExistsPGRegRdPerm( SB_MODULE_ID index ); Description This function identifies whether the PGRegRdPerm feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionReadPermSet • PLIB_SB_PGRegionReadPermClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGRegRdPerm feature is supported on the device • false - The PGRegRdPerm feature is not supported on the device Remarks None. 5.6.21.6.5.6 PLIB_SB_ExistsPGRegSize Function C bool PLIB_SB_ExistsPGRegSize( SB_MODULE_ID index ); Description This function identifies whether the PGRegSize feature is available on the SB module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2790 • PLIB_SB_PGRegionSizeSet • PLIB_SB_PGRegionSizeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGRegSize feature is supported on the device • false - The PGRegSize feature is not supported on the device Remarks None. 5.6.21.6.5.7 PLIB_SB_ExistsPGRegWrPerm Function C bool PLIB_SB_ExistsPGRegWrPerm( SB_MODULE_ID index ); Description This function identifies whether the PGRegWrPerm feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGRegionWritePermSet • PLIB_SB_PGRegionWritePermClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGRegWrPerm feature is supported on the device • false - The PGRegWrPerm feature is not supported on the device Remarks None. 5.6.21.6.5.8 PLIB_SB_ExistsPGVErrClear Function C bool PLIB_SB_ExistsPGVErrClear( SB_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2791 Description This function identifies whether the PGVErrClear feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorMulti • PLIB_SB_PGVErrorCode • PLIB_SB_PGVErrorLogClearSingle • PLIB_SB_PGVErrorLogClearMulti Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrClear feature is supported on the device • false - The PGVErrClear feature is not supported on the device Remarks None. 5.6.21.6.5.9 PLIB_SB_ExistsPGVErrClrMulti Function C bool PLIB_SB_ExistsPGVErrClrMulti( SB_MODULE_ID index ); Description This function identifies whether the PGVErrClrMulti feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorClearMulti Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrClrMulti feature is supported on the device • false - The PGVErrClrMulti feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2792 5.6.21.6.5.10 PLIB_SB_ExistsPGVErrClrSingle Function C bool PLIB_SB_ExistsPGVErrClrSingle( SB_MODULE_ID index ); Description This function identifies whether the PGVErrClrSingle feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorClearSingle Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrClrSingle feature is supported on the device • false - The PGVErrClrSingle feature is not supported on the device Remarks None. 5.6.21.6.5.11 PLIB_SB_ExistsPGVErrCmdCode Function C bool PLIB_SB_ExistsPGVErrCmdCode( SB_MODULE_ID index ); Description This function identifies whether the PGVErrCmdCode feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorCommandCode Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrCmdCode feature is supported on the device • false - The PGVErrCmdCode feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2793 5.6.21.6.5.12 PLIB_SB_ExistsPGVErrInitID Function C bool PLIB_SB_ExistsPGVErrInitID( SB_MODULE_ID index ); Description This function identifies whether the PGVErrInitID feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorInitiatorID Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrInitID feature is supported on the device • false - The PGVErrInitID feature is not supported on the device Remarks None. 5.6.21.6.5.13 PLIB_SB_ExistsPGVErrPG Function C bool PLIB_SB_ExistsPGVErrPG( SB_MODULE_ID index ); Description This function identifies whether the PGVErrPG feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorPermissionGroup Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrPG feature is supported on the device • false - The PGVErrPG feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2794 5.6.21.6.5.14 PLIB_SB_ExistsPGVErrRegion Function C bool PLIB_SB_ExistsPGVErrRegion( SB_MODULE_ID index ); Description This function identifies whether the PGVErrRegion feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorRegion Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrRegion feature is supported on the device • false - The PGVErrRegion feature is not supported on the device Remarks None. 5.6.21.6.5.15 PLIB_SB_ExistsPGVErrRptPri Function C bool PLIB_SB_ExistsPGVErrRptPri( SB_MODULE_ID index ); Description This function identifies whether the PGVErrRptPri feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorReportPrimaryEnable • PLIB_SB_PGVErrorReportPrimaryDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrRptPri feature is supported on the device • false - The PGVErrRptPri feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2795 5.6.21.6.5.16 PLIB_SB_ExistsPGVErrStatus Function C bool PLIB_SB_ExistsPGVErrStatus( SB_MODULE_ID index ); Description This function identifies whether the PGVErrStatus feature is available on the SB module. When this function returns true, these functions are supported on the device: • PLIB_SB_PGVErrorStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PGVErrStatus feature is supported on the device • false - The PGVErrStatus feature is not supported on the device Remarks None. 5.6.21.7 Files Files Name Description plib_sb.h Defines the System Bus (SB) Peripheral Library interface Description 5.6.21.7.1 plib_sb.h System Bus Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the system bus (SB) peripheral library (PLIB) for Microchip microcontrollers. The definitions in this file are for the SB controller module. Functions Name Description PLIB_SB_CPUPrioritySet Sets the CPU arbitration policy to SRAM when servicing an interrupt PLIB_SB_DMAPrioritySet Sets the DMA arbitration policy PLIB_SB_ExistsCPUPriority Identifies whether the CPUPriority feature exists on the SB module PLIB_SB_ExistsDMAPriority Identifies whether the DMAPriority feature exists on the SB module 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2796 PLIB_SB_ExistsInitPermGrp Identifies whether the InitPermGrp feature exists on the SB module PLIB_SB_ExistsPGRegAddr Identifies whether the PGRegAddr feature exists on the SB module PLIB_SB_ExistsPGRegRdPerm Identifies whether the PGRegRdPerm feature exists on the SB module PLIB_SB_ExistsPGRegSize Identifies whether the PGRegSize feature exists on the SB module PLIB_SB_ExistsPGRegWrPerm Identifies whether the PGRegWrPerm feature exists on the SB module PLIB_SB_ExistsPGVErrClear Identifies whether the PGVErrClear feature exists on the SB module PLIB_SB_ExistsPGVErrClrMulti Identifies whether the PGVErrClrMulti feature exists on the SB module PLIB_SB_ExistsPGVErrClrSingle Identifies whether the PGVErrClrSingle feature exists on the SB module PLIB_SB_ExistsPGVErrCmdCode Identifies whether the PGVErrCmdCode feature exists on the SB module PLIB_SB_ExistsPGVErrInitID Identifies whether the PGVErrInitID feature exists on the SB module PLIB_SB_ExistsPGVErrPG Identifies whether the PGVErrPG feature exists on the SB module PLIB_SB_ExistsPGVErrRegion Identifies whether the PGVErrRegion feature exists on the SB module PLIB_SB_ExistsPGVErrRptPri Identifies whether the PGVErrRptPri feature exists on the SB module PLIB_SB_ExistsPGVErrStatus Identifies whether the PGVErrStatus feature exists on the SB module PLIB_SB_InitPermGrpSet Sets the read/write permission group(s) for an initiator. The region must also allow read/write access for the permission group for a read/write to occur. PLIB_SB_PGRegionAddrGet Returns the base address for a permission group region within a target's physical address space. PLIB_SB_PGRegionAddrSet Sets the base address for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermClear Clears the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionReadPermSet Sets the permission bit(s) corresponding to the requested read permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionSizeGet Returns the size for a permission group region within a target's physical address space. PLIB_SB_PGRegionSizeSet Sets the size for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermClear Clears the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGRegionWritePermSet Sets the permission bit(s) corresponding to the requested write permissions for a permission group region within a target's physical address space. Not all regions are programmable. PLIB_SB_PGVErrorClearMulti Clears multiple permission group errors for the specified target. PLIB_SB_PGVErrorClearSingle Clears a single permission group error for the specified target. PLIB_SB_PGVErrorCode Returns a value corresponding to the type of error logged for the specified target. PLIB_SB_PGVErrorCommandCode Returns the OCP command code of the transaction that caused the protection violation for the specified target. PLIB_SB_PGVErrorInitiatorID Returns the ID of the Initiator that caused the protection violation PLIB_SB_PGVErrorLogClearMulti Clears a multiple protection group violations error from the specified target error log register. PLIB_SB_PGVErrorLogClearSingle Clears a single protection group violation error from the specified target error log register. 5.6 Peripheral Library Help MPLAB Harmony Help System Bus Peripheral Library 5-2797 PLIB_SB_PGVErrorMulti Indicates if more than one perimission group violation has occurred since last cleared. PLIB_SB_PGVErrorPermissionGroup Returns the permission group of the protection region in a target address space that caused the protection violation for the specified target. PLIB_SB_PGVErrorRegion Returns the number of the protection region in the specified target address space that caused the protection violation. PLIB_SB_PGVErrorReportPrimaryDisable Disables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorReportPrimaryEnable Enables primary permission group error reporting for the specified target to the SB flag register. PLIB_SB_PGVErrorStatus Identifies whether a permission group violation has been reported for the specified target. File Name plib_sb.h Company Microchip Technology Inc. 5.6.22 SPI Peripheral Library 5.6.22.1 Introduction SPI Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Serial Peripheral Interface (SPI) module that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Serial Peripheral Interface (SPI) module is a synchronous serial interface useful for communicating with other peripherals or microcontroller device. These peripheral devices may be serial EEPROMs, shift registers, display drivers, analog-to-digital converters, etc. SPI is a synchronous serial data link operating at full duplex Master/slave relationship. Two data lines: • MOSI – Master Data Output, Slave Data Onput • MISO – Master Data Input, Slave Data Output 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2798 Two control lines: • SCLK – Clock • /SS – Slave Select (no addressing) Devices communicate in Master/Slave mode where the master device initiates the data frame. Multiple slave devices are allowed with individual slave select (Chip Select) lines. The SPI is sometimes referred to as a "four-wire" serial bus, contrasting with three-, two-, and one-wire serial buses. 5.6.22.2 Release Notes MPLAB Harmony Version: v0.70b SPI Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.22.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.22.4 Using the Library This topic describes the basic architecture of the SPI Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_spi.h The interface to the SPI Peripheral Library is defined in the "plib_spi.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the SPI Peripheral library must include "peripheral.h". Library File: The SPI Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2799 5.6.22.4.1 Library Architecture This library provides the low level abstraction of the SPI module available on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all SPI functionality available on the device. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. Description The following diagram shows the general architecture of the SPI Peripheral Library. The library interface routines are divided into various subsections, each of the subsection addresses one of the blocks or the overall operation of the SPI module. Library Interface Section Description General Configuration and Status Functions This section provides a set of functions and data types for configuring the SPI and to read the status of the SPI. Data Transfer Functions This section provides a set of functions and data types for Reading and Writing the SPI buffer values. Transmitter Functions This section provides a set of functions for transmitter. Receiver Functions This section provides a set of functions for receiver. Framed Mode Functions Provides control, status, and data transfer routines for Framed SPI mode. Audio Mode Functions Provides control, status routines to support audio protocol functionality. Note: Not all modes are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2800 5.6.22.4.2 Hardware Abstraction Model This library provides a low-level abstraction of the SPI module on the Microchip family microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The SPI Peripheral Library provides interface routines to interact with the blocks shown in the following diagram. Hardware Abstraction Model The Serial Peripheral Interface (API) module is a synchronous serial interface useful for communicating with external peripherals and other microcontroller devices. The SPI bus specifies four logic signals: • SCLK: serial clock (output from master) • MOSI: master output, slave input (output from master) • MISO: master input, slave output (output from slave) • /SS: slave select (active low, output from master); on certain devices, this pin is implemented using general purpose I/O (GPIO) The SPI bus can operate with a single master device and with one or more slave devices.To begin a communication, the master first configures the clock, using a frequency less than or equal to the maximum frequency the slave device supports.In addition to setting the clock frequency, the master must also configure the clock polarity and phase with respect to the data. The master then transmits the appropriate chip select bit for the desired chip to a logic '0'. A logic '0' is transmitted because the Chip Select line (/SS) is active low, meaning its off state is a logic '1'; the on state is asserted with a logic 0. The master issues the clock cycles. During each SPI clock cycle, a full duplex data transmission occurs: 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2801 • The master sends a bit on the MOSI line; the slave reads it from that same line • The slave sends a bit on the MISO line; the master reads it from that same line Transmissions may involve any number of clock cycles. When there are no more data to be transmitted, the master stops toggling its clock. Normally, it then deselects the slave. The Baud Rate Generator/Prescaler controls the timing, the desired baud rate can be programmed in the baud rate controller. In the Master mode, the clock becomes the serial clock and is provided to external devices via the SCK pin (the clock can be prescaled by the primary prescaler and the secondary prescaler if device supports). The Buffers are for data transmitted or received by the SPI module over the MISO and MOSI line synchronized with the SCK line by the clock control logic. The Status and Control logic, provide the capability to control different ways of enabling or disabling the master and slave. It also can provides status about the transmitter and receiver. Active-Low Slave Select or Frame Synchronization I/O Pulse allows for a Synchronous Slave mode. The SPI module supports the following four SPI modes. • Standard Mode: In this mode of operation, data can be thought of as taking a direct path between the Most Significant bit (MSb) of one module’s shift register and the Least Significant bit (LSb) of the other, and then into the appropriate Transmit or Receive Buffer. The master provides the serial clock and synchronization signals required to the slave device. • Enhanced Buffer Mode: The operation of this mode is very similar to that of Standard mode. The difference is that data can be thought of as moving from the Shift register to a receive FIFO buffer and moving from the transmit FIFO buffer to the Shift register. • Framed Mode: In this mode of operation, the Frame Master controls the generation of the frame synchronization pulse and provides this pulse to other devices at the Slave Select (/SS) pin. The SPI clock is generated by the SPI Master and is continuously running. The SPI slave module uses a frame synchronization pulse received at the SS pin. • Audio Protocol Mode: The SPI module provides support to the audio protocol modes; with this mode, the SPI module can be interfaced to most codec devices available today to provide PIC microcontroller-based audio solutions Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3 How the Library Works The SPI module has the following operating modes: • Standard SPI • Enhanced Buffer SPI • Framed SPI • Audio Protocol Interface Note: Not all modes are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.1 State Machine This state machine is provided to give a general idea of the usage model of the peripheral library. Refer to the usage model for more detailed steps for the scenario that is being used. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2802 Description SPI State Machine The following state machine diagrams shows the transmission and reception during normal operation. SPI Routines State Associated Function Setup and Initialization Initialize the SPI by setting prescalar/baud rate generator, interrupt modes. Enable Master Once the SPI has been appropriately set up and initialized, the state machine enables Master mode (PLIB_SPI_MasterEnable). Select Slave Select slave by pulling the /SSx pin low to transmit the data. Write Data To Transfer Write data to the buffer to transmit using PLIB_SPI_BufferWrite. Wait for Transmit Buffer to Clear Buffer Data will be transmitted to transmit buffer and transmit buffer flag will be full. The state machine waits for transmit buffer to clear. Check for status by calling PLIB_SPI_TransmitBufferIsFull. Wait for Receive Buffer Full to Set Slave sends received data back to master. Upon data received receive buffer flag will set. The state machine waits for Receive buffer to clear. Check for status by calling PLIB_SPI_ReceiveBufferIsFull. Read Buffer Read the buffer using PLIB_SPI_BufferRead. Enable Slave Select Enable slave select by calling PLIB_SPI_PinEnable. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2803 5.6.22.4.3.2 Standard SPI Mode In Standard (legacy) Master and Slave modes, data can be thought of as taking a direct path between the Most Significant bit (MSb) of one module’s shift register and the Least Significant bit (LSb) of the other, and then into the appropriate Transmit or Receive buffer. The module configured as the master module provides the serial clock and synchronization signals (as required) to the slave device. 5.6.22.4.3.2.1 Standard Master Mode In Standard Master mode, the input clock is used as the serial clock. The serial clock is output via the SCK pin to slave devices. Clock pulses are only generated when there is data to be transmitted. Setup 1. Select on which edge of the clock data transmission occurs, using PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect. 2. The clock is prescaled using PLIB_SPI_PrescalePrimarySelect/PLIB_SPI_PrescaleSecondarySelect, if supported by the device. 3. If the module needs to operate as a Master, use PLIB_SPI_MasterEnable. Example: Standard Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. 1. Data to be transmitted is written to the SPI buffer(PLIB_SPI_BufferWrite). 2. When contents of buffer are moved to the shift register, the SPI transmit buffer full flag is cleared (this can be verified using PLIB_SPI_TransmitBufferIsFull). 3. A series of 8/16/32 clock pulses shifts out 8/16/32 bits of transmit data from the shift register to the data out (SDO) pin and simultaneously shifts in the data at the data in (SDI) pin into the shift register. 4. When the transfer is complete, the following events occur: • The SPI interrupt flag is set. Interrupts will occur if SPI interrupts are enabled. The SPI interrupt flag is not cleared automatically by the hardware. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2804 • Also, when the ongoing transmit and receive operation is completed, the contents of the shift register are moved to the SPI receive register. • The SPI receive buffer full flag (PLIB_SPI_ReceiveBufferIsFull) is set by the module, indicating that the receive buffer is full. Once the SPI buffer is read by the user application using PLIB_SPI_BufferRead, the hardware clears the SPI receive buffer full flag. 5. If the SPI receive buffer full flag is set when the SPI module needs to transfer data from SPI shift register to SPI receive buffer, the module will set the SPI receive overflow flag (PLIB_SPI_ReceiverHasOverflowed), indicating an overflow condition. 6. Data to be transmitted can be written to SPI buffer (PLIB_SPI_BufferWrite) by the user software at any time as long as the SPI Transmit buffer full flag is clear (PLIB_SPI_TransmitBufferIsFull). The write can occur while SPI shift register is shifting out the previously written data, allowing continuous transmission. Example: Standard Master Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiveBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.2.2 Standard Slave Mode Slave Select Synchronization The Slave Select pin (/SS) allows for Synchronous Slave mode. If the slave select is enabled (PLIB_SPI_PinEnable), transmission and reception are enabled in Slave mode only if the /SS pin is driven to a low state. The port output or other peripheral outputs must not be driven in order to allow the /SS pin to function as an input. If the slave select is enabled and the /SS pin is driven high, the data output (SDO) pin is no longer driven and will tri-state even if the module is in the middle of a transmission. An aborted transmission will be retried the next time the /SS pin is driven low, using the data held in the SPI Transmit buffer. If slave select is not enabled, the /SS pin does not affect the module operation in Slave mode. SPI Trasmit Buffer Full Status Operation The function of the SPI Trasmit buffer full (PLIB_SPI_TransmitBufferIsFull) is different in the Slave mode of operation. If slave select is disabled (PLIB_SPI_PinDisable), the PLIB_SPI_TransmitBufferIsFull returns a '1' when the SPI buffer is loaded by the user application. It is cleared when the module transfers data from SPI transmit buffer to SPI shift register. This is similar to the SPI Trasmit buffer full function in Master mode. If slave select is enabled (PLIB_SPI_PinEnable), PLIB_SPI_TransmitBufferIsFull returns a '1' when the SPI buffer is loaded by the user application. However,PLIB_SPI_TransmitBufferIsFull returns zero only when the SPI module completes data transmission. A transmission will be aborted when the Slave Select pin goes high and may be retried at a later time. Each data word is held in SPI transmit buffer until all bits are transmitted to the receiver. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2805 Setup In Standard Slave mode, data is transmitted and received as the external clock pulses appear on the SCK pin. The clock polarity and clock edge (PLIB_SPI_ClockPolaritySelect) determine upon which edge of the clock data transmission occurs. Example: Standard Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer (PLIB_SPI_BufferWrite/ PLIB_SPI_BufferRead). The remainder of the operation of the module is identical to that of Standard Master mode. Example: Standard Slave Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2806 } Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.3 Enhanced Buffer SPI Mode The operation of Enhanced Buffer Master and Slave modes is very similar to Standard Master and Slave modes. The difference is that data can be thought of as moving from the Shift register to a receive FIFO buffer and moving from the transmit FIFO buffer to the Shift register. 5.6.22.4.3.3.1 Enhanced Buffer Master Mode In Enhanced Buffer Master mode (referred to as a FIFO), the input clock used as the serial clock. The serial clock is output via the SCK pin to slave devices. Clock pulses are only generated when there is data to be transmitted. Setup 1. Select on which edge of the clock data transmission occurs, using PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect. 2. The clock is prescaled using PLIB_SPI_PrescalePrimarySelect/PLIB_SPI_PrescaleSecondarySelect, or the clock is generated using PLIB_SPI_BaudRateClockSelect, if supported by the device. 3. If the module needs to operate as a Master, use PLIB_SPI_MasterEnable. Example: Enhanced Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_FIFOEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); The CPU loads data to be transmitted into the transmit buffer by writing the SPI buffer (PLIB_SPI_BufferWrite). An SPI transmission begins after the first buffer write. Up to all pending transmissions can be loaded. The number of pending transfers is indicated by the Buffer Element Count bits through PLIB_SPI_FIFOCountGet. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2807 In Master mode, this count reflects the number of transfers pending in the transmit buffer. In Slave mode, it reflects the number of unread receptions in the receive buffer. If the Shift register is empty, the first write will immediately load the Shift register, leaving all transmit buffer locations available. After an SPI transfer completes, the receive buffer location is updated with the received data. The CPU accesses the received data by reading the SPI buffer. After each CPU read, the SPI buffer points to the next buffer location. SPI transfers continue until all pending data transfers have completed. Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. 1. Data to be transmitted is written to the SPI buffer(PLIB_SPI_BufferWrite) and is loaded into the next available transmit buffer location. 2. The SPI transmit buffer full flag (PLIB_SPI_TransmitBufferIsFull) and SPI interrupt flag are set after pending transfers are loaded. 3. The current buffer location’s contents are moved to the Shift register. The SPI transmit buffer is cleared by the module if a buffer location is available for a CPU write. 4. A series of 8/16/32 clock pulses shifts out 8/16/32 bits of transmit data from the shift register to the data out (SDO) pin and simultaneously shifts in the data at the data in (SDI) pin into the shift register. 5. When the transfer is complete, the following events occur: • The contents of the SPI shift register are moved into the next available location in the receive buffer. • If the last unread location is written by the SPI module, the SPI receive buffer full flag (PLIB_SPI_ReceiveBufferIsFull) is set, indicating that all buffer locations are full. Enable the SPI interrupts. The SPI interrupt flag is not cleared automatically by the hardware. • Once the SPI buffer is read (PLIB_SPI_BufferRead) by the user application, the hardware clears the SPI receive buffer full flag (PLIB_SPI_ReceiveBufferIsFull) and the SPI Buffer increments to the next unread receive buffer location. SPI buffer reads beyond the last unread location will not increment the buffer location. 6. When PLIB_SPI_ReceiveBufferIsFull is set, if the SPI module needs to transfer one more data from SPI shift register to the buffer, the module will enable the receive overflow flag (PLIB_SPI_ReceiverHasOverflowed) indicating an overflow condition. 7. Data to be transmitted can be written to the SPI buffer (PLIB_SPI_BufferWrite) by the user application at any time as long as the SPI transmit buffer full flag is clear (PLIB_SPI_TransmitBufferIsFull). Up to all pending transfers can be loaded into the buffer allowing continuous transmission. Example: Enhanced Master Mode communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiveBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2808 data sheet for availability. 5.6.22.4.3.3.2 Enhanced Buffer Slave Mode Slave Select Synchronization The Slave Select pin allows a Synchronous Slave mode. If the slave select enabled (PLIB_SPI_PinEnable), transmission and reception is enabled in Slave mode only if the /SS pin is driven to a low state. The port output or other peripheral outputs must not be driven in order to allow the /SS pin to function as an input. If the slave select is enabled and the /SS pin is driven high, the SDO pin is no longer driven and will tri-state even if the module is in the middle of a transmission. An aborted transmission will be retried the next time the /SS pin is driven low using the data held in the SPI transmit buffer. If the Slave select is disabled (PLIB_SPI_PinDisable), the /SS pin does not affect the module operation in Slave mode. SPI Transmit Buffer Full Operation The function of the SPI transmit buffer full flag (PLIB_SPI_TransmitBufferIsFull) is different in the Slave mode of operation. If Slave select is disabled (PLIB_SPI_PinDisable), the SPI Transmit Buffer Full flag (PLIB_SPI_TransmitBufferIsFull) is set when the last available buffer location is loaded by the user application. It is cleared when the module transfers data from the buffer to SPI status register and a buffer location is available for a CPU write. This is similar to the SPI transmit buffer in Master mode. If Slave select is enabled (PLIB_SPI_PinEnable), the SPI transmit buffer is set when the last available buffer location is loaded by the user application. However, it is cleared only when the SPI module completes data transmission, leaving a buffer location available for a CPU write. A transmission will be aborted when the /SS pin goes high and may be retried at a later time. Each data word is held in the buffer until all bits are transmitted to the receiver. Setup In Slave mode, data is transmitted and received as the external clock pulses appear on the SCK pin. PLIB_SPI_OutputDataPhaseSelect and PLIB_SPI_ClockPolaritySelect determine upon which edge of the clock data transmission occurs. The rest of the operation of the module is identical to that of Enhanced Buffer Master mode. Example: Enhanced Slave Mode communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_INPUT_SAMPLING_PHASE_AT_END);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_FIFOEnable(MY_SPI_ID); // Optional: Enable interrupts. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2809 // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive: Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer (PLIB_SPI_BufferWrite/ PLIB_SPI_BufferRead). The remainder of the operation of the module is identical to that of Enhanced Buffer Master mode. Example: Enhanced Slave Mode communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.4 Framed SPI Modes The SPI module supports a basic framed SPI protocol while operating in either Master or Slave modes. Description The SPI module supports two framed modes of operation. In Frame Master mode, the SPI module generates the frame synchronization pulse and provides this pulse to other devices at the /SS pin. In Frame Slave mode, the SPI module uses a frame synchronization pulse received at the /SS pin. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2810 The framed SPI modes are supported in conjunction with the unframed Master and Slave modes. This makes four framed SPI configurations: • SPI Master mode and Frame Master mode • SPI Master mode and Frame Slave mode • SPI Slave mode and Frame Master mode • SPI Slave mode and Frame Slave mode These modes determine whether or not the SPI module generates the serial clock and the frame synchronization pulse. 5.6.22.4.3.4.1 SPI Master Mode and Frame Master Mode In Master/Frame Master mode, the SPI module generates both the clock and frame synchronization signals, as shown in the following figure. In this mode, the serial clock is output continuously at the SCK pin, regardless of whether the module is transmitting. When the SPI buffer is written (PLIB_SPI_BufferWrite), the /SS pin will be driven to its active state on the appropriate transmit edge of the SCK clock, and remain active for one data frame. If the PLIB_SPI_FrameSyncPulseEdgeSelect function decides whether sync pulse precedes the data transmission or coincides with the beginning of the data transmission. The module starts transmitting data on the next transmit edge of the SCK. Setup The mode is enabled by calling PLIB_SPI_MasterEnable, PLIB_SPI_FramedCommunicationEnable and PLIB_SPI_FrameSyncPulseDirectionSelect (as output). Example: SPI Master Mode and Frame Master Mode Communication Setup 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2811 #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID, SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Master Mode and Frame Master Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using // PLIB_SPI_ReceiveBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.4.2 SPI Master Mode and Frame Slave Mode In Master/Frame Slave mode, the module generates the clock signal but uses the slave module’s frame synchronization signal for data transmission, as shown in the following figure. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2812 In this mode, the /SS pin is an input and it is sampled on the sample edge of the SPI clock.When it is sampled in its active state, data will be transmitted on the subsequent transmit edge of the SPI clock. The SPI interrupt flag is set when the transmission is complete. The user application must make sure that the correct data is loaded into the SPI buffer for transmission before the signal is received at the /SS pin. Setup The mode is enabled by calling PLIB_SPI_MasterEnable, PLIB_SPI_FramedCommunicationEnable, and PLIB_SPI_FrameSyncPulseDirectionSelect. Example: SPI Master Mode and Frame Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_SLAVE_SELECT|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Master Mode and Frame Slave Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // Either Poll for Receiver buffer to be full using 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2813 // PLIB_SPI_ReceiveBufferIsFull or wait for the interrupt // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.4.3 SPI Slave Mode and Frame Master Mode In Slave/Frame Master mode, the module acts as the SPI slave and takes its clock from the other SPI module; however, it produces frame synchronization signals to control data transmission, as shown in the following figure. The input SPI clock will be continuous in Slave mode. The /SS pin will be an output when the Frame sync pulse is output. Therefore, when the SPI buffer is written, the module drives the /SS pin to the active state on the appropriate transmit edge of the SPI clock for one SPI clock cycle. Data will start transmitting on the appropriate SPI clock transmit edge. Setup The mode is enabled by calling PLIB_SPI_SlaveEnable, PLIB_SPI_FramedCommunicationEnable, and PLIB_SPI_FrameSyncPulseDirectionSelect. Example: SPI Slave Mode and Frame Master Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2814 PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Slave Mode and Frame Master Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the"Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.4.4 SPI Slave Mode and Frame Master Mode In Slave/Frame Slave mode, the module obtains both its clock and frame synchronization signal from the master module, as shown in the following figure. In this mode, both the clock and Slave Select pins will be inputs. The /SS pin is sampled on the sample edge of the SPI clock. When /SS is sampled at its active state, data will be transmitted on the appropriate transmit edge of SCK. Setup The mode is enabled by calling PLIB_SPI_SlaveEnable,PLIB_SPI_FramedCommunicationEnable and PLIB_SPI_FrameSyncPulseDirectionSelect (as input). 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2815 Example: SPI Slave Mode and Frame Slave Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_ID,SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER); PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_FramedCommunicationEnable(MY_SPI_ID); PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_ID,SPI_FRAME_PULSE_DIRECTION_INPUT); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: SPI Slave Mode and Frame Slave Mode Communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2816 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.5 Audio Protocol Interface Mode The SPI module can be interfaced to most codec devices available today to provide PIC microcontroller-based audio solutions. Description The SPI module provides support to the audio protocol functionality via four standard I/O pins. The four pins that make up the audio protocol interface modes are: • SDIx: Serial Data Input for receiving sample digital audio data • SDOx: Serial Data Output for transmitting digital audio data • SCKx: Serial Clock (also known as bit clock) • /SSx: Left/Right Channel Clock The SPI module supports four audio protocol modes and can be operated in any one of these modes: Note: Each of the modes can additionally support some or all of the features listed below. Please refer to the"Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for more information. I2S Mode The Inter-IC Sound (I2S) protocol enables transmission of two channels of digital audio data over a single serial interface. The I 2S specification defines a half-duplex interface that supports transmit or receive, but not both at the same time. With both SDO and SDI available, full-duplex operation is supported by this peripheral, as shown in the following figure. Data Transmit and Clocking: • The transmitter shifts the audio sample data’s Most Significant bit (MSb) on the first falling edge of SCK after an LRCK transition • The receiver samples the MSB on the second rising edge of SCK • The left channel data shifts out while LRCK is low and right channel data is shifted out while LRCK is high • The data in the left and right channel consists of a single frame To set the module to I2S mode, the following bits must be set: • Set SPI to I2S Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active low) • Select PLIB_SPI_ClockPolaritySelect (as active low) Setting these bits enables the SDO and LRCK (/SSx) transitions to occur on the falling edge of SCK (BCLK) and sampling of SDI to occur on the rising edge of SCK. Left-Justified Mode The Left-Justified mode is similar to I2S mode; however, in this mode, the SPI shifts the audio data’s MSb on the first SCK edge that is coincident with an LRCK transition. On the receiver side, the SPI module samples the MSb on the next SCK edge. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2817 In general, a codec using justified protocols defaults to transmitting data on the rising edge of SCK and receiving data on the falling edge of SCK. To set the module to Left-Justified mode, the following bits must to be set • Set SPI to Left Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active high) • Select PLIB_SPI_ClockPolaritySelect (as active high) This enables the SDO and LRCK transitions to occur on the rising edge of SCK. Refer to the following sample waveform diagrams for 16-, 24-, and 32-bit audio data transfers. Right-Justified Mode In Right-Justified mode, the SPI module shifts the audio sample data’s MSb after aligning the data to the last clock cycle. The bits preceding the audio sample data can be driven to logic level 0 . To set the module to Right-Justified mode, the following bits must to be set: • Set SPI to Right Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect • Select PLIB_SPI_FrameSyncPulsePolaritySelect (as active high) • Select PLIB_SPI_ClockPolaritySelect (as active high) This enables the SDO and LRCK transitions to occur on the rising edge of SCK after the Least Significant bit (LSb) being aligned to the last clock cycle. Refer to the following sample waveform diagrams for 16-, 24-, and 32-bit audio data transfers. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2818 PCM/DSP Mode This mode modifies the behavior of LRCK and audio data spacing. In PCM/DSP mode, the LRCK can be a single bit wide (i.e., 1 SCK) or as wide as the audio data (16-, 24-, and 32-bits). The audio data is packed in the frame with the left channel data immediately followed by the right channel data. The frame length is still either 32 or 64 clocks when this device is the master. In PCM/DSP mode, the transmitter drives the audio data’s (left channel) MSb on the first or second transmit edge of SCK (after an LRCK transition). Immediately after the (left channel) LSb, the transmitter drives the (right channel) MSb. To set the module to Left-Justified mode, the following bit must to be set: • Set the SPI module to Right-Justified Mode by calling PLIB_SPI_AudioProtocolModeSelect Refer to the following sample waveform for 16-, 24-, and 32-bit audio data transfers. Mono Mode Versus Stereo Mode The SPI module enables the audio data transmission in Mono or Stereo mode by setting PLIB_SPI_AudioTransmitModeSelect. In Stereo mode, the shift register uses each FIFO location once, which gives each channel a unique stream of data for stereo data. In Mono mode, the shift register uses each FIFO location twice, to give each channel the same mono stream of audio data. 5.6.22.4.3.5.1 Master Mode A few characteristics of Master mode are: • This mode enables the device to generate SCK and LRCK pulses as long as the master mode enabled • The SPI module generates LRCK and SCK continuously in all the cases, regardless of the transmit data while in Master mode • The SPI module drives the leading edge of LRCK and SCK within 1 SCK period and the serial data shifts in and out continuously even when the Transmit FIFO is empty The following figure shows a typical interface between the master and slave while in Master mode. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2819 Setup To configure the device in Audio Protocol Master, enable master mode through PLIB_SPI_MasterEnable and enable audio mode through PLIB_SPI_AudioProtocolEnable. Example: Audio Mode Communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear (MY_SPI_ID); // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID, SPI_PIN_DATA_IN|SPI_PIN_DATA_OUT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH); PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); PLIB_SPI_MasterEnable(MY_SPI_ID); PLIB_SPI_AudioProtocolModeSelect(MY_SPI_ID,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_AudioProtocolEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer. Example: Audio Mode Communication Transfer #define MY_SPI_ID SPI_ID_1 uint16_t data; data = 0x00ac; // write to buffer for TX PLIB_SPI_BufferWrite (MY_SPI_ID,data); // wait for transfer to complete while(!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)); // Read the received value data = PLIB_SPI_BufferRead (MY_SPI_ID); Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2820 5.6.22.4.3.5.2 Slave Mode A few characteristics of Slave mode are: • This mode enables the device to receive SCK and LRCK pulses as long as slave mode is enabled • The SPI module drives zeros out of SDO, but does not shift data out or in (SDI) until the module receives the LRCK (i.e., the edge that precedes the left channel) • Once the module receives the leading edge of LRCK, it starts receiving data if PLIB_SPI_PinEnable (enables data in) is selected and the serial data shifts out continuously even when the TX FIFO is empty The following figure shows the interface between a SPI module in Audio Slave Interface mode to a codec master device. Setup The SPI module can be configured in Audio Protocol Slave mode by setting PLIB_SPI_SlaveEnable and enabling the audio protocol through PLIB_SPI_AudioProtocolEnable. Example: Slave Mode communication Setup #define MY_SPI_ID SPI_ID_1 //Diable SPI PLIB_SPI_Disable(MY_SPI_ID); // Optional: Clear SPI interrupts and status flag. //clear SPI buffer PLIB_SPI_BufferClear(MY_SPI_ID); // Configure General SPI Options // Configure General SPI Options PLIB_SPI_StopInIdleDisable(MY_SPI_ID); PLIB_SPI_PinEnable(MY_SPI_ID,SPI_PIN_DATA_OUT|SPI_PIN_SLAVE_SELECT); PLIB_SPI_CommunicationWidthSelect(MY_SPI_ID, SPI_COMMUNICATION_WIDTH_16BITS); // SMP must be cleared when SPI is used in Slave mode PLIB_SPI_InputSamplePhaseSelect(MY_SPI_ID,SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); PLIB_SPI_ClockPolaritySelect(MY_SPI_ID, SPI_CLOCK_POLARITY_IDLE_HIGH);//clock polarity and edge is subject to change ... PLIB_SPI_OutputDataPhaseSelect(MY_SPI_ID, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK);// ... based on your communication mode. PLIB_SPI_SlaveEnable(MY_SPI_ID); PLIB_SPI_AudioProtocolModeSelect(MY_SPI_ID,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); PLIB_SPI_FramedCommunicationDisable(MY_SPI_ID); PLIB_SPI_AudioProtocolEnable(MY_SPI_ID); // Optional: Enable interrupts. // Enable the module PLIB_SPI_Enable(MY_SPI_ID); Transmission and Receive Both data to be transmitted and data that is received are respectively written into, or read from, the SPI buffer 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2821 (PLIB_SPI_BufferWrite/ PLIB_SPI_BufferRead). Example: Slave Mode communication Receive #define MY_SPI_ID SPI_ID_1 uint16_t data; if(PLIB_SPI_ReceiverHasOverflowed(MY_SPI_ID)) { // error PLIB_SPI_ReceiverOverflowClear(MY_SPI_ID);// clear overflow data = PLIB_SPI_BufferRead (MY_SPI_ID); } else if (!PLIB_SPI_ReceiverBufferIsFull(MY_SPI_ID)) { // error } else { data = PLIB_SPI_BufferRead (MY_SPI_ID); // read data while(PLIB_SPI_TransmitBufferIsFull(MY_SPI_ID)); PLIB_SPI_BufferWrite(MY_SPI_ID, data); // send back } Notes: 1. Refer to the "Interrupts" section in the related family reference manual or device data sheet for details on how to clear and enable the SPI module interrupts and flags. 2. MY_SPI_ID is the SPI instance selected for use by the application developer. 3. Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6 Other Features This topic describes the additional features available in the SPI Peripheral Library. 5.6.22.4.3.6.1 Communication Mode The SPI module allows three types of data widths when transmitting and receiving data over a SPI bus. The selection of data width determines the minimum length of the SPI data.The user application should select the appropriate data width to maximize its data throughput. To change the mode of operation on the fly, the SPI module must be idle. If the SPI module is switched off, the new mode will be available when the module is switched on again. The macro, PLIB_SPI_CommunicationWidthSet, allows the module to communicate in either 8-/16-/32-bit modes. The functionality will be the same for each mode, except for the number of bits that are received and transmitted. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6.2 Power-Saving Modes Note: Each of the following modes can additionally support some or all of the features listed below. Please refer to the "Power-Saving Features" chapter in the specific data sheet or the "Power-Saving Modes" family reference manual section for more information. Sleep Mode When the device enters Sleep mode, the device clock source and the entire device is shut down. The consequences of entering Sleep depend upon which mode (Master or Slave) the module is configured in at the time that Sleep mode is invoked. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2822 Idle Mode When the device enters Idle mode, the device clock is operational, but the CPU and selected peripherals are shut down. The SPI module can continue to operate in Idle mode by calling PLIB_SPI_StopInIdleDisable, or can stop operation in Idle mode by calling PLIB_SPI_StopInIdleEnable. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6.3 SPI Receive-only Operation Calling PLIB_SPI_PinDisable (data in pin) disables the transmission at the SDO pin. This allows the SPI module to be configured for a receive-only mode of operation. This function is applicable to all SPI operating modes. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6.4 SPI Error Handling If a new data word has been shifted and the previous buffer contents have not been read, the status can be read by calling PLIB_SPI_ReceiverHasOverflowed. Any received data is not transferred, and further data reception is disabled until the buffer is cleared by calling PLIB_SPI_ReceiverOverflowClear. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6.5 SPI Master Mode Clock Frequency In the SPI Master mode, the clock provided to the SPI module is the system cycle (TCY). This clock will then be prescaled by the primary prescaler (PLIB_SPI_PresclaeSelectPrimary), and the secondary prescaler (PLIB_SPI_PrescaleSelectSecondary). The prescaled instruction clock becomes the serial clock and is provided to external devices via the SCKx pin. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.3.6.6 Interrupts The SPI module has the ability to generate interrupts reflecting the events that occur during the data communication. Interrupts can be enabled or disabled using PLIB_SPI_ErrorInterruptEnable/PLIB_SPI_ErrorInterruptDisable. The following types of interrupts can be generated: • Receive data available interrupts are signalled by SPI receive and transmit flag. This event occurs when there is new data assembled in the SPI receive buffer. • Transmit buffer empty interrupts are signalled by SPI receive and transmit flag. This event occurs when there is space available in the SPI transmit buffer and new data can be written. • Error interrupts are signalled by SPI receive and transmit flag. This event occurs when there is an overflow condition for the receive buffer when there is an underrun of the transmit buffer, or when a frame error event occurs. Note: Not all features are available on all devices. Refer to the "Serial Peripheral Interface (SPI)" chapter in the specific device data sheet for availability. 5.6.22.4.4 Configuring the Library The library is configured for the supported SPI modules when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2823 5.6.22.5 Library Interface Data Types and Constants Name Description SPI_AUDIO_COMMUNICATION_WIDTH Defines the list of SPI audio communication width. SPI_AUDIO_ERROR Defines the list of SPI audio error. SPI_AUDIO_PROTOCOL Data type defining the audio protocol mode. SPI_AUDIO_TRANSMIT_MODE Defines the list of SPI transmit audio mode format. SPI_BAUD_RATE_CLOCK Defines the list of SPI Baud Rate Generator (BRG). SPI_CLOCK_POLARITY Defines the list of SPI clock polarity. SPI_COMMUNICATION_WIDTH Defines the list of SPI communication width. SPI_DATA_TYPE Data type defining the SPI data size. SPI_ERROR_INTERRUPT Defines the list of SPI error interrupts. SPI_FIFO_INTERRUPT Defines the list of SPI Buffer Interrupt mode. SPI_FIFO_TYPE Defines the list of SPI buffer mode. SPI_FRAME_PULSE_DIRECTION Defines the list of SPI frame sync pulse direction. SPI_FRAME_PULSE_EDGE Defines the list of SPI frame sync pulse edge. SPI_FRAME_PULSE_POLARITY Defines the list of SPI frame sync pulse polarity. SPI_FRAME_PULSE_WIDTH Defines the list of SPI frame sync pulse width. SPI_FRAME_SYNC_PULSE Data type defining the frame sync pulse counter values. SPI_INPUT_SAMPLING_PHASE Defines the list of SPI data input sample phase. SPI_MODULE_ID Identifies the supported SPI modules. SPI_OUTPUT_DATA_PHASE Defines the list of SPI serial output data changes. SPI_PIN Data type defining the SPI pin. SPI_PRESCALE_PRIMARY Defines the list of possible primary prescaler values. SPI_PRESCALE_SECONDARY Defines the list of possible seconday prescaler Vvlues. Audio Mode Functions Name Description PLIB_SPI_AudioCommunicationWidthSelect Selects the data width for the SPI audio communication. PLIB_SPI_AudioErrorDisable Disables the SPI error. PLIB_SPI_AudioErrorEnable Enables the SPI error. PLIB_SPI_AudioProtocolDisable Audio protocol is disabled. PLIB_SPI_AudioProtocolEnable Audio protocol is enabled. PLIB_SPI_AudioProtocolModeSelect Selects the Audio Protocol mode. PLIB_SPI_AudioTransmitModeSelect Selects the transmit audio data format. Data Transfer Functions Name Description PLIB_SPI_BufferClear Clears the SPI buffer. PLIB_SPI_BufferRead Returns the SPI buffer value. PLIB_SPI_BufferWrite Write the data to the SPI buffer. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2824 Feature Existence Functions Name Description PLIB_SPI_ExistsAudioCommunicationWidth Identifies whether the AudioCommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsAudioErrorControl Identifies whether the AudioErrorControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolControl Identifies whether the AudioProtocolControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolMode Identifies whether the AudioProtocolMode feature exists on the SPI module. PLIB_SPI_ExistsAudioTransmitMode Identifies whether the AudioTransmitMode feature exists on the SPI module. PLIB_SPI_ExistsBaudRate Identifies whether the BaudRate feature exists on the SPI module. PLIB_SPI_ExistsBaudRateClock Identifies whether the BaudRateClock feature exists on the SPI module. PLIB_SPI_ExistsBuffer Identifies whether the Buffer feature exists on the SPI module. PLIB_SPI_ExistsBusStatus Identifies whether the BusStatus feature exists on the SPI module. PLIB_SPI_ExistsClockPolarity Identifies whether the ClockPolarity feature exists on the SPI module. PLIB_SPI_ExistsCommunicationWidth Identifies whether the CommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SPI module. PLIB_SPI_ExistsErrorInterruptControl Identifies whether the ErrorInterruptControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOControl Identifies whether the FIFOControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOCount Identifies whether the FIFOCount feature exists on the SPI module. PLIB_SPI_ExistsFIFOInterruptMode Identifies whether the FIFOInterruptMode feature exists on the SPI module. PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Identifies whether the FIFOShiftRegisterEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsFramedCommunication Identifies whether the FramedCommunication feature exists on the SPI module. PLIB_SPI_ExistsFrameErrorStatus Identifies whether the FrameErrorStatus feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseCounter Identifies whether the FrameSyncPulseCounter feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseDirection Identifies whether the FrameSyncPulseDirection feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseEdge Identifies whether the FrameSyncPulseEdge feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulsePolarity Identifies whether the FrameSyncPulsePolarity feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseWidth Identifies whether the FrameSyncPulseWidth feature exists on the SPI module. PLIB_SPI_ExistsInputSamplePhase Identifies whether the InputSamplePhase feature exists on the SPI module. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2825 PLIB_SPI_ExistsMasterControl Identifies whether the MasterControl feature exists on the SPI module. PLIB_SPI_ExistsOutputDataPhase Identifies whether the OutputDataPhase feature exists on the SPI module. PLIB_SPI_ExistsPinControl Identifies whether the PinControl feature exists on the SPI module. PLIB_SPI_ExistsPrimaryPrescale Identifies whether the PrimaryPrescale feature exists on the SPI module. PLIB_SPI_ExistsReadDataSignStatus Identifies whether the ReadDataSignStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveBufferStatus Identifies whether the ReceiveBufferStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveFIFOStatus Identifies whether the ReceiveFIFOStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the SPI module. PLIB_SPI_ExistsSecondaryPrescale Identifies whether the SecondaryPrescale feature exists on the SPI module. PLIB_SPI_ExistsSlaveSelectControl Identifies whether the SlaveSelectControl feature exists on the SPI module. PLIB_SPI_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferEmptyStatus Identifies whether the TransmitBufferEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferFullStatus Identifies whether the TransmitBufferFullStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitUnderRunStatus Identifies whether the TransmitUnderRunStatus feature exists on the SPI module. Framed Mode Functions Name Description PLIB_SPI_FramedCommunicationDisable Disables framed SPI support. PLIB_SPI_FramedCommunicationEnable Enables framed SPI support. PLIB_SPI_FrameErrorStatusGet Returns the current status of the SPI frame error. PLIB_SPI_FrameSyncPulseCounterSelect Selects at which character the SPI frame sync pulse is generated. PLIB_SPI_FrameSyncPulseDirectionSelect Selects the frame sync pulse direction. PLIB_SPI_FrameSyncPulseEdgeSelect Selects the frame sync pulse edge. PLIB_SPI_FrameSyncPulsePolaritySelect Selects the frame sync pulse polarity. PLIB_SPI_FrameSyncPulseWidthSelect Sets the frame sync pulse width. General Configuration and Status Functions Name Description PLIB_SPI_BaudRateClockSelect Selects the type of clock is used by the Baud Rate Generator. PLIB_SPI_BaudRateSet Sets the baud rate to the desired value. PLIB_SPI_ClockPolaritySelect Enables clock polarity. PLIB_SPI_CommunicationWidthSelect Selects the data width for the SPI communication. PLIB_SPI_Disable Disables the SPI module. PLIB_SPI_Enable Enables the SPI module. PLIB_SPI_ErrorInterruptDisable Enables SPI error interrupts. PLIB_SPI_ErrorInterruptEnable Enables SPI error interrupts PLIB_SPI_FIFOCountGet Reads the SPI Buffer Element Count bits for either receive or transmit. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2826 PLIB_SPI_FIFODisable Disables the SPI enhanced buffer. PLIB_SPI_FIFOEnable Enables the SPI enhanced buffer. PLIB_SPI_FIFOInterruptModeSelect Selects the SPI buffer interrupt mode. PLIB_SPI_FIFOShiftRegisterIsEmpty Returns the current status of the SPI shift register. PLIB_SPI_InputSamplePhaseSelect Selects the SPI data input sample phase. PLIB_SPI_IsBusy Returns the current SPI module activity status. PLIB_SPI_MasterEnable Enables the SPI in Master mode. PLIB_SPI_OutputDataPhaseSelect Selects serial output data change. PLIB_SPI_PinDisable Enables the selected SPI pins. PLIB_SPI_PinEnable Enables the selected SPI pins. PLIB_SPI_PrescalePrimarySelect Selects the primary prescale for SPI Master mode. PLIB_SPI_PrescaleSecondarySelect Selects the seconday prescale for SPI Master mode. PLIB_SPI_ReadDataIsSignExtended Returns the current status of the receive (RX) FIFO sign-extended data. PLIB_SPI_SlaveEnable Enables the SPI in Slave mode. PLIB_SPI_SlaveSelectDisable Disables Master mode slave select. PLIB_SPI_SlaveSelectEnable Enables Master mode slave select. PLIB_SPI_StopInIdleDisable Continues module operation when the device enters Idle mode. PLIB_SPI_StopInIdleEnable Discontinues module operation when the device enters Idle mode. Receiver Functions Name Description PLIB_SPI_ReceiverBufferIsFull Returns the current status of the SPI receive buffer. PLIB_SPI_ReceiverFIFOIsEmpty Returns the current status of the SPI receive FIFO. PLIB_SPI_ReceiverHasOverflowed Returns the current status of the SPI receiver overflow. PLIB_SPI_ReceiverOverflowClear Clears the SPI receive overflow flag. Transmitter Functions Name Description PLIB_SPI_TransmitBufferIsEmpty Returns the current status of the transmit buffer. PLIB_SPI_TransmitBufferIsFull Returns the current transmit buffer status of the SPI module. PLIB_SPI_TransmitUnderRunStatusGet Returns the current status of the transmit underrun. Description This section lists and describes the functions, data types, and constants provided in the SPI Peripheral Library. 5.6.22.5.1 General Configuration and Status Functions 5.6.22.5.1.1 PLIB_SPI_BaudRateClockSelect Function C void PLIB_SPI_BaudRateClockSelect( SPI_MODULE_ID index, SPI_BAUD_RATE_CLOCK type ); Description This function selects the type of clock is used by the Baud Rate Generator. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2827 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_BAUD_RATE_CLOCK enumeration values as the SPI baud clock Returns None. Remarks This function implements an operation of the baud rate clock control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBaudRateClock" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BaudRateClockSelect (MY_SPI_INSTANCE, SPI_BAUD_RATE_MCLK_CLOCK); 5.6.22.5.1.2 PLIB_SPI_BaudRateSet Function C void PLIB_SPI_BaudRateSet( SPI_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ); Description This function sets the baud rate to the desired value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured clockFrequency Clock frequency baudrate Baud rate value Returns None. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receive error or data loss may result. To avoid this issue, verify that no receptions are in progress before changing the system clock. This function implements an operation of the baud rate set feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBaudRate" in your application to automatically 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2828 determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BaudRateSet(MY_SPI_INSTANCE, MY_CLOCK_FREQUENCY, 9600); 5.6.22.5.1.3 PLIB_SPI_ClockPolaritySelect Function C void PLIB_SPI_ClockPolaritySelect( SPI_MODULE_ID index, SPI_CLOCK_POLARITY polarity ); Description This function enables clock polarity. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured polarity One of the SPI_CLOCK_POLARITY enumeration values as the SPI clock polarity Returns None. Remarks This function implements an operation of the clock polarity feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsClockPolarity" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ClockPolaritySelect(MY_SPI_INSTANCE, SPI_CLOCK_POLARITY_IDLE_HIGH ); 5.6.22.5.1.4 PLIB_SPI_CommunicationWidthSelect Function C void PLIB_SPI_CommunicationWidthSelect( SPI_MODULE_ID index, SPI_COMMUNICATION_WIDTH width ); Description This function selects the data width for the SPI communication. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2829 width One of the SPI_COMMUNICATION_WIDTH enumeration values as the SPI buffer width Returns None. Remarks This function implements an operation of the communication width feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsCommunicationWidth" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_CommunicationWidthSelect(MY_SPI_INSTANCE, SPI_COMMUNICATION_WIDTH_8BITS); 5.6.22.5.1.5 PLIB_SPI_Disable Function C void PLIB_SPI_Disable( SPI_MODULE_ID index ); Description This function disables the SPI module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsEnableControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_Disable(MY_SPI_INSTANCE); 5.6.22.5.1.6 PLIB_SPI_Enable Function C void PLIB_SPI_Enable( SPI_MODULE_ID index ); Description This function enables the SPI module. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2830 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks The SCKx, SDOx, SDIx and SSx pins must be assigned to available RPn pins before use. This function implements an operation of the enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsEnableControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_Enable(MY_SPI_INSTANCE); 5.6.22.5.1.7 PLIB_SPI_ErrorInterruptDisable Function C void PLIB_SPI_ErrorInterruptDisable( SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error ); Description This function enables SPI error interrupts. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured error One of the SPI_ERROR_INTERRUPT enumeration values as the SPI interrupt error Returns None. Remarks This function implements an operation of the error interrupt control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsErrorInterruptControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ErrorInterruptDisable (MY_SPI_INSTANCE, SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2831 5.6.22.5.1.8 PLIB_SPI_ErrorInterruptEnable Function C void PLIB_SPI_ErrorInterruptEnable( SPI_MODULE_ID index, SPI_ERROR_INTERRUPT error ); Description This function enables SPI error interrupts. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_ERROR_INTERRUPT enumeration values as the SPI interrupt error Returns None. Remarks This function implements an operation of the error interrupt control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsErrorInterruptControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ErrorInterruptEnable (MY_SPI_INSTANCE, SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW); 5.6.22.5.1.9 PLIB_SPI_FIFOCountGet Function C uint8_t PLIB_SPI_FIFOCountGet( SPI_MODULE_ID index, SPI_FIFO_TYPE type ); Description This function reads the number of SPI transfers pending for Master mode and the number of unread SPI transfers for Slave mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured type One of the SPI_FIFO_TYPE enumeration values 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2832 Returns CountValue - Buffer element count bits Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOCount" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. uint8_t count = PLIB_SPI_FIFOCountGet(MY_SPI_INSTANCE,SPI_FIFO_TYPE_TRANSMIT); 5.6.22.5.1.10 PLIB_SPI_FIFODisable Function C void PLIB_SPI_FIFODisable( SPI_MODULE_ID index ); Description This function disables the SPI enhanced buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Enables the legacy standard single buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FIFODisable(MY_SPI_INSTANCE); 5.6.22.5.1.11 PLIB_SPI_FIFOEnable Function C void PLIB_SPI_FIFOEnable( SPI_MODULE_ID index ); Description This function enables the SPI enhanced buffer. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2833 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This enables the enhanced buffer mode. This function implements an operation of the FIFO control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FIFOEnable(MY_SPI_INSTANCE); 5.6.22.5.1.12 PLIB_SPI_FIFOInterruptModeSelect Function C void PLIB_SPI_FIFOInterruptModeSelect( SPI_MODULE_ID index, SPI_FIFO_INTERRUPT mode ); Description This function selects the SPI buffer interrupt mode from SPI_FIFO_INTERRUPT. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_FIFO_INTERRUPT enumeration values as the SPI buffer interrupt mode Returns None. Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO interrupt feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOInterruptMode" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2834 PLIB_SPI_FIFOInterruptModeSelect(MY_SPI_INSTANCE, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL); 5.6.22.5.1.13 PLIB_SPI_FIFOShiftRegisterIsEmpty Function C bool PLIB_SPI_FIFOShiftRegisterIsEmpty( SPI_MODULE_ID index ); Description This function returns the current status of the SPI shift register. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - SPI shift register is empty and ready to send or receive • false - SPI shift register is not enpty Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_FIFOShiftRegisterIsEmpty(MY_SPI_INSTANCE); 5.6.22.5.1.14 PLIB_SPI_InputSamplePhaseSelect Function C void PLIB_SPI_InputSamplePhaseSelect( SPI_MODULE_ID index, SPI_INPUT_SAMPLING_PHASE phase ); Description This function selects the input sampling phase in Master mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured phase One of the SPI_INPUT_SAMPLING_PHASE as the SPI input sampling phase 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2835 Returns None. Remarks This function implements an operation of the input sample phase feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsInputSamplePhase" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_InputSamplePhaseSelect(MY_SPI_INSTANCE, SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE); 5.6.22.5.1.15 PLIB_SPI_IsBusy Function C bool PLIB_SPI_IsBusy( SPI_MODULE_ID index ); Description This function returns the current SPI module activity status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - SPI module is currently busy with some transactions • false - SPI module is currently idle Remarks This function implements an operation of the bus status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBusStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool status = PLIB_SPI_IsBusy(MY_SPI_INSTANCE); 5.6.22.5.1.16 PLIB_SPI_MasterEnable Function C void PLIB_SPI_MasterEnable( SPI_MODULE_ID index ); Description This function enables the SPI in Master mode. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2836 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the master enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsMasterControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_MasterEnable(MY_SPI_INSTANCE); 5.6.22.5.1.17 PLIB_SPI_OutputDataPhaseSelect Function C void PLIB_SPI_OutputDataPhaseSelect( SPI_MODULE_ID index, SPI_OUTPUT_DATA_PHASE phase ); Description This function selects serial output data change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data One of the SPI_OUTPUT_DATA_PHASE enumeration values as the SPI serial output data change Returns None. Remarks This function implements an operation of the output data phase feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsOutputDataPhase" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_OutputDataPhaseSelect(MY_SPI_INSTANCE, SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2837 5.6.22.5.1.18 PLIB_SPI_PinDisable Function C void PLIB_SPI_PinDisable( SPI_MODULE_ID index, SPI_PIN pin ); Description This function enables the selected SPI pins. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pin One of the SPI_PIN enumeration values as the SPI pin Returns None. Remarks This function implements an operation of the pin control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsPinControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PinDisable(MY_SPI_INSTANCE, SPI_PIN_SLAVE_SELECT); 5.6.22.5.1.19 PLIB_SPI_PinEnable Function C void PLIB_SPI_PinEnable( SPI_MODULE_ID index, SPI_PIN pin ); Description This function enables the selected SPI pins. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pin One of the SPI_PIN enumeration values as the SPI pin Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2838 Remarks This function implements an operation of the pin control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsPinControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PinEnable(MY_SPI_INSTANCE, SPI_PIN_SLAVE_SELECT); 5.6.22.5.1.20 PLIB_SPI_PrescalePrimarySelect Function C void PLIB_SPI_PrescalePrimarySelect( SPI_MODULE_ID index, SPI_PRESCALE_PRIMARY prescale ); Description This function selects the primary prescale for SPI Master mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the SPI_PRIMARY_PRESCALE enumeration values as the SPI master primary prescale Returns None. Remarks This function implements an operation of the primary prescale select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsPrimaryPrescale" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PrescalePrimarySelect(MY_SPI_INSTANCE, SPI_PRIMARY_PRESCALE_4); 5.6.22.5.1.21 PLIB_SPI_PrescaleSecondarySelect Function C void PLIB_SPI_PrescaleSecondarySelect( SPI_MODULE_ID index, SPI_PRESCALE_SECONDARY prescale ); Description This function selects the seconday prescale for SPI Master mode. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2839 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the SPI_SECONDARY_PRESCALE enumeration values as the SPI master secondary prescale Returns None. Remarks This function implements an operation of the secondary prescale select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsSecondaryPrescale" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_PrescaleSecondarySelect( MY_SPI_INSTANCE, SPI_SECONDARY_PRESCALE_3); 5.6.22.5.1.22 PLIB_SPI_ReadDataIsSignExtended Function C bool PLIB_SPI_ReadDataIsSignExtended( SPI_MODULE_ID index ); Description This function returns the current status of the receive (RX) FIFO sign-extended data. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Data from RX FIFO is sign-extended. • false - Data from RX FIFO is not sign-extended Remarks This function implements an operation of the data sign feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReadDataSignStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_ReadDataIsSignExtended(MY_SPI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2840 5.6.22.5.1.23 PLIB_SPI_SlaveEnable Function C void PLIB_SPI_SlaveEnable( SPI_MODULE_ID index ); Description This function enables the SPI in Slave mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the master enable control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsMasterControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveEnable(MY_SPI_INSTANCE); 5.6.22.5.1.24 PLIB_SPI_SlaveSelectDisable Function C void PLIB_SPI_SlaveSelectDisable( SPI_MODULE_ID index ); Description This function disables Master mode slave select. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature does not support Framed SPI mode. This function implements an operation of the slave select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsSlaveSelectControl" in your application to 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2841 automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveSelectDisable(MY_SPI_INSTANCE); 5.6.22.5.1.25 PLIB_SPI_SlaveSelectEnable Function C void PLIB_SPI_SlaveSelectEnable( SPI_MODULE_ID index ); Description This function enables Master mode slave select. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature does not support Framed SPI mode. This function implements an operation of the slave select feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsSlaveSelectControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_SlaveSelectEnable(MY_SPI_INSTANCE); 5.6.22.5.1.26 PLIB_SPI_StopInIdleDisable Function C void PLIB_SPI_StopInIdleDisable( SPI_MODULE_ID index ); Description This function sets up the SPI module such that module operation is continued when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2842 Returns None. Remarks This function implements an operation of the stop in idle control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsStopInIdleControl" in your application to determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_StopInIdleDisable(MY_SPI_INSTANCE); 5.6.22.5.1.27 PLIB_SPI_StopInIdleEnable Function C void PLIB_SPI_StopInIdleEnable( SPI_MODULE_ID index ); Description This function sets up the SPI module such that module operation is disabled when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the stop in idle control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsStopInIdleControl" in your application to automatically determine if this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_StopInIdleEnable(MY_SPI_INSTANCE); 5.6.22.5.2 Data Transfer Functions 5.6.22.5.2.1 PLIB_SPI_BufferClear Function C void PLIB_SPI_BufferClear( SPI_MODULE_ID index ); Description This function clears the SPI buffer. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2843 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BufferClear(MY_SPI_INSTANCE); 5.6.22.5.2.2 PLIB_SPI_BufferRead Function C SPI_DATA_TYPE PLIB_SPI_BufferRead( SPI_MODULE_ID index ); Description This function returns the SPI buffer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Returns the SPI_DATA_TYPE enumeration value. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. uint8_t bufferValue = PLIB_SPI_BufferRead(MY_SPI_INSTANCE); 5.6.22.5.2.3 PLIB_SPI_BufferWrite Function C void PLIB_SPI_BufferWrite( SPI_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2844 SPI_DATA_TYPE data ); Description This function writes data to the SPI buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Data of the type SPI_DATA_TYPE to written to the SPI buffer Returns None. Remarks This function implements an operation of the buffer control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsBuffer" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_BufferWrite (MY_SPI_INSTANCE, 0xFF); 5.6.22.5.3 Framed Mode Functions 5.6.22.5.3.1 PLIB_SPI_FramedCommunicationDisable Function C void PLIB_SPI_FramedCommunicationDisable( SPI_MODULE_ID index ); Description This function disables framed SPI support. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFramedCommunication" in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2845 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FramedCommunicationDisable(MY_SPI_INSTANCE); 5.6.22.5.3.2 PLIB_SPI_FramedCommunicationEnable Function C void PLIB_SPI_FramedCommunicationEnable( SPI_MODULE_ID index ); Description This function enables framed SPI support. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFramedCommunication" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FramedCommunicationEnable(MY_SPI_INSTANCE); 5.6.22.5.3.3 PLIB_SPI_FrameErrorStatusGet Function C bool PLIB_SPI_FrameErrorStatusGet( SPI_MODULE_ID index ); Description This function returns the current status of the SPI frame error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Frame error detected • false - No frame error detected 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2846 Remarks Valid only if Frame mode is enabled. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameErrorStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool status = PLIB_SPI_FrameErrorStatusGet(MY_SPI_INSTANCE); 5.6.22.5.3.4 PLIB_SPI_FrameSyncPulseCounterSelect Function C void PLIB_SPI_FrameSyncPulseCounterSelect( SPI_MODULE_ID index, SPI_FRAME_SYNC_PULSE pulse ); Description This function selects at which character the SPI frame sync pulse is generated. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pulse One of the SPI_FRAME_SYNC_PULSE enumeration values as the SPI frame sync pulse count Returns None. Remarks This is valid only when PLIB_SPI_FramedCommunicationEnable is enabled. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseCounter" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseCounterSelect(MY_SPI_INSTANCE, SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER ); 5.6.22.5.3.5 PLIB_SPI_FrameSyncPulseDirectionSelect Function C void PLIB_SPI_FrameSyncPulseDirectionSelect( SPI_MODULE_ID index, SPI_FRAME_PULSE_DIRECTION direction ); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2847 Description This function selects the frame sync pulse direction. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured direction One of the SPI_FRAME_PULSE_DIRECTION enumeration values as the SPI frame sync pulse polarity Returns None. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseDirection" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseDirectionSelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_DIRECTION_INPUT ); 5.6.22.5.3.6 PLIB_SPI_FrameSyncPulseEdgeSelect Function C void PLIB_SPI_FrameSyncPulseEdgeSelect( SPI_MODULE_ID index, SPI_FRAME_PULSE_EDGE edge ); Description This function selects the frame sync pulse edge. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured edge One of the SPI_FRAME_PULSE_EDGE enumeration values as the SPI frame sync pulse edge Returns None. Remarks This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseEdge" in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2848 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseEdgeSelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK); 5.6.22.5.3.7 PLIB_SPI_FrameSyncPulsePolaritySelect Function C void PLIB_SPI_FrameSyncPulsePolaritySelect( SPI_MODULE_ID index, SPI_FRAME_PULSE_POLARITY polarity ); Description This function selects the frame sync pulse polarity. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured polarity One of the SPI_FRAME_PULSE_POLARITY enumeration values as the SPI frame sync pulse polarity Returns None. Remarks Available only for Frame mode. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulsePolarity" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulsePolaritySelect(MY_SPI_INSTANCE, SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH ); 5.6.22.5.3.8 PLIB_SPI_FrameSyncPulseWidthSelect Function C void PLIB_SPI_FrameSyncPulseWidthSelect( SPI_MODULE_ID index, SPI_FRAME_PULSE_WIDTH width ); Description This function sets the frame sync pulse width. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2849 Parameters Parameters Description index Identifier for the device instance to be configured edge One of the SPI_FRAME_PULSE_WIDTH enumeration values as the SPI frame sync pulse width. Returns None. Remarks Length of the word is dependent on the communication mode. This function implements an operation of the framed communication feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsFrameSyncPulseWidth" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_FrameSyncPulseWidthSelect (MY_SPI_INSTANCE,SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH); 5.6.22.5.4 Audio Mode Functions 5.6.22.5.4.1 PLIB_SPI_AudioCommunicationWidthSelect Function C void PLIB_SPI_AudioCommunicationWidthSelect( SPI_MODULE_ID index, SPI_AUDIO_COMMUNICATION_WIDTH mode ); Description This function selects the data width for the SPI audio communication. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured width One of the SPI_AUDIO_COMMUNICATION_WIDTH enumeration values as the SPI buffer width Returns None. Remarks This mode is available only when PLIB_SPI_AudioProtocolEnable is enabled. This function implements an operation of the audio communication width feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioCommunicationWidth" in your application to automatically determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2850 Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioCommunicationWidthSelect(MY_SPI_INSTANCE, SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL); 5.6.22.5.4.2 PLIB_SPI_AudioErrorDisable Function C void PLIB_SPI_AudioErrorDisable( SPI_MODULE_ID index, SPI_AUDIO_ERROR error ); Description This function disables the SPI error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured error One of the SPI_AUDIO_ERROR enumeration values as the SPI error Returns None. Remarks This function implements an operation of the audio error control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioErrorControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioErrorDisable (MY_SPI_INSTANCE, SPI_AUDIO_ERROR_RECEIVE_OVERFLOW); 5.6.22.5.4.3 PLIB_SPI_AudioErrorEnable Function C void PLIB_SPI_AudioErrorEnable( SPI_MODULE_ID index, SPI_AUDIO_ERROR error ); Description This function enables the SPI error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2851 error One of the SPI_AUDIO_ERROR enumeration values as the SPI error Returns None. Remarks This function implements an operation of the audio error control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioErrorControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioErrorEnable (MY_SPI_INSTANCE, SPI_AUDIO_ERROR_RECEIVE_OVERFLOW); 5.6.22.5.4.4 PLIB_SPI_AudioProtocolDisable Function C void PLIB_SPI_AudioProtocolDisable( SPI_MODULE_ID index ); Description This function disables the audio protocol. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the audio protocol control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolDisable(MY_SPI_INSTANCE); 5.6.22.5.4.5 PLIB_SPI_AudioProtocolEnable Function C void PLIB_SPI_AudioProtocolEnable( SPI_MODULE_ID index ); Description This function enables the audio protocol. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2852 Preconditions Disable the SPI module by calling PLIB_SPI_Disable. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the audio protocol control feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolControl" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolEnable(MY_SPI_INSTANCE); 5.6.22.5.4.6 PLIB_SPI_AudioProtocolModeSelect Function C void PLIB_SPI_AudioProtocolModeSelect( SPI_MODULE_ID index, SPI_AUDIO_PROTOCOL mode ); Description This function selects the Audio Protocol mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_AUDIO_PROTOCOL enumeration values as the audio protocol Returns None. Remarks This function implements an operation of the audio protocol mode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioProtocolMode" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioProtocolModeSelect(MY_SPI_INSTANCE,SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED ); 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2853 5.6.22.5.4.7 PLIB_SPI_AudioTransmitModeSelect Function C void PLIB_SPI_AudioTransmitModeSelect( SPI_MODULE_ID index, SPI_AUDIO_TRANSMIT_MODE mode ); Description This function selects the transmit audio data format. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode One of the SPI_TRANSMIT_AUDIO_MODE enumeration values as the transmit audio format Returns None. Remarks This function implements an operation of the audio transmit mode feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsAudioTransmitMode" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_AudioTransmitModeSelect (MY_SPI_INSTANCE, SPI_AUDIO_TRANSMIT_MONO); 5.6.22.5.5 Transmitter Functions 5.6.22.5.5.1 PLIB_SPI_TransmitBufferIsEmpty Function C bool PLIB_SPI_TransmitBufferIsEmpty( SPI_MODULE_ID index ); Description This function returns the current status of the transmit buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2854 Returns • true - Transmit buffer is empty • false - Transmit buffer is not empty Remarks This function implements an operation of the transmit buffer empty status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitBufferEmptyStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_TransmitBufferIsEmpty(MY_SPI_INSTANCE); 5.6.22.5.5.2 PLIB_SPI_TransmitBufferIsFull Function C bool PLIB_SPI_TransmitBufferIsFull( SPI_MODULE_ID index ); Description This function returns the current transmit buffer status of the SPI module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Transmit not yet started, transmit buffer is full • false - Transmit started, transmit buffer is empty/not full Remarks In Standard Buffer mode - automatically set in hardware when SPI buffer writes occur, loading the transmit buffer. Automatically cleared in hardware when the SPI module transfers data from the transmit buffer to the shift register. In Enhanced Buffer mode - automatically set in hardware when SPI buffer writes occur, loading the last available buffer. Automatically cleared in hardware when the buffer is available for writing. This function implements an operation of the transmit buffer status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitBufferFullStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool buffullstate = PLIB_SPI_TransmitBufferIsFull (MY_SPI_INSTANCE); 5.6.22.5.5.3 PLIB_SPI_TransmitUnderRunStatusGet Function C bool PLIB_SPI_TransmitUnderRunStatusGet( 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2855 SPI_MODULE_ID index ); Description This function returns the current status of the transmit underrun. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Transmit buffer has encountered an underrun condition • false - Transmit buffer run has not encountered an underrun condition Remarks Valid in Framed Sync mode. This function implements an operation of the transmit underrun status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsTransmitUnderRunStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool Status = PLIB_SPI_TransmitUnderRunStatusGet(MY_SPI_INSTANCE); 5.6.22.5.6 Receiver Functions 5.6.22.5.6.1 PLIB_SPI_ReceiverBufferIsFull Function C bool PLIB_SPI_ReceiverBufferIsFull( SPI_MODULE_ID index ); Description This function returns the current status of the SPI receive buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Status - Receiver Buffer Full Status true - Receive complete, receive buffer is full false - Receive is not complete, receive buffer is empty Remarks In Standard Buffer mode - automatically set in hardware when the SPI module transfers data from the shift register to the receive 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2856 buffer. Automatically cleared in hardware when the core reads the SPI buffer, read in the receive buffer. In Enhanced Buffer mode - automatically set in hardware when the SPI module transfers data from the shift register to the receive buffer, filling the last unread buffer. Automatically cleared in hardware when a buffer is available for a transfer from the shift register. This function implements an operation of the receiver buffer status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiveBufferStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool receivefullstate = PLIB_SPI_ReceiverBufferIsFull (MY_SPI_INSTANCE); 5.6.22.5.6.2 PLIB_SPI_ReceiverFIFOIsEmpty Function C bool PLIB_SPI_ReceiverFIFOIsEmpty( SPI_MODULE_ID index ); Description This function returns the current status of the SPI receive FIFO. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Receive FIFO is empty • false - Receive FIFO is not empty Remarks Valid in Enhanced Buffer mode. This function implements an operation of the FIFO status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiveFIFOStatus" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool fifostate = PLIB_SPI_ReceiverFIFOIsEmpty (MY_SPI_INSTANCE); 5.6.22.5.6.3 PLIB_SPI_ReceiverHasOverflowed Function C bool PLIB_SPI_ReceiverHasOverflowed( SPI_MODULE_ID index ); Description This function returns the current status of the SPI receiver overflow. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2857 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Status - SPI receiver overflow status true - A new byte/word is completely received and discarded. The user software has not read the previous data in the SPI buffer register. false - No Overflow has occurred Remarks This function implements an operation of the receiver overflow status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiverOverflow" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. bool overflowstate = PLIB_SPI_ReceiverHasOverflowed(MY_SPI_INSTANCE); 5.6.22.5.6.4 PLIB_SPI_ReceiverOverflowClear Function C void PLIB_SPI_ReceiverOverflowClear( SPI_MODULE_ID index ); Description This function clears the SPI receive overflow flag. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function implements an operation of the receiver overflow status feature. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use "PLIB_SPI_ExistsReceiverOverflow" in your application to automatically determine whether this feature is available. Example // Where MY_SPI_INSTANCE, is the SPI instance selected for use by the // application developer. PLIB_SPI_ReceiverOverflowClear(MY_SPI_INSTANCE); 5.6.22.5.7 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2858 5.6.22.5.7.1 SPI_AUDIO_COMMUNICATION_WIDTH Enumeration C typedef enum { SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_32CHANNEL, SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_16CHANNEL } SPI_AUDIO_COMMUNICATION_WIDTH; Description SPI Audio Communication Width This macro defines the list of SPI audio communication width. Members Members Description SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL Communication is 24-bit Data,32-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_32DATA_32FIFO_32CHANNEL Communication is 32-bit Data,32-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_32CHANNEL Communication is 16-bit Data,16-bit FIFO,32-bit Channel/64-bit Frame SPI_AUDIO_COMMUNICATION_16DATA_16FIFO_16CHANNEL Communication is 16-bit Data,16-bit FIFO,16-bit Channel/64-bit Frame 5.6.22.5.7.2 SPI_AUDIO_ERROR Enumeration C typedef enum { SPI_AUDIO_ERROR_RECEIVE_OVERFLOW, SPI_AUDIO_ERROR_TRANSMIT_UNDERRUN } SPI_AUDIO_ERROR; Description SPI Audio Error This macro defines the list of SPI audio error. Members Members Description SPI_AUDIO_ERROR_RECEIVE_OVERFLOW SPI error for receive overflow SPI_AUDIO_ERROR_TRANSMIT_UNDERRUN SPI error for transmit underrun 5.6.22.5.7.3 SPI_AUDIO_PROTOCOL Enumeration C typedef enum { SPI_AUDIO_PROTOCOL_PCM_DSP, SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED, SPI_AUDIO_PROTOCOL_LEFT_JUSTIFIED, SPI_AUDIO_PROTOCOL_I2S } SPI_AUDIO_PROTOCOL; Description Audio Protocol Mode enumeration 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2859 This data type defining the audio protocol mode. Members Members Description SPI_AUDIO_PROTOCOL_PCM_DSP Audio protocol set to PCM/DSP mode SPI_AUDIO_PROTOCOL_RIGHT_JUSTIFIED Audio protocol set to Right-Justified mode SPI_AUDIO_PROTOCOL_LEFT_JUSTIFIED Audio protocol set to Left-Justified mode SPI_AUDIO_PROTOCOL_I2S Audio protocol set to I2C mode Remarks This enumeration is processor specific. 5.6.22.5.7.4 SPI_AUDIO_TRANSMIT_MODE Enumeration C typedef enum { SPI_AUDIO_TRANSMIT_MONO, SPI_AUDIO_TRANSMIT_STEREO } SPI_AUDIO_TRANSMIT_MODE; Description Audio Transmit mode format This macro defines the list of SPI transmit audio mode format. Members Members Description SPI_AUDIO_TRANSMIT_MONO SPI Trasmit Audio Data Format is Mono SPI_AUDIO_TRANSMIT_STEREO SPI Trasmit Audio Data Format is Stereo 5.6.22.5.7.5 SPI_BAUD_RATE_CLOCK Enumeration C typedef enum { SPI_BAUD_RATE_MCLK_CLOCK, SPI_BAUD_RATE_PBCLK_CLOCK } SPI_BAUD_RATE_CLOCK; Description SPI Baudrate generator This macro defines the list of the SPI Baud Rate Generator. Members Members Description SPI_BAUD_RATE_MCLK_CLOCK MCLK is used by the Baud Rate Generator SPI_BAUD_RATE_PBCLK_CLOCK Peripheral bus clock is used by the Baud Rate Generator 5.6.22.5.7.6 SPI_CLOCK_POLARITY Enumeration C typedef enum { SPI_CLOCK_POLARITY_IDLE_HIGH, SPI_CLOCK_POLARITY_IDLE_LOW 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2860 } SPI_CLOCK_POLARITY; Description SPI Clock polarity This macro defines the list of SPI clock polarity. Members Members Description SPI_CLOCK_POLARITY_IDLE_HIGH Idle state for clock is a high level;active state is a low level SPI_CLOCK_POLARITY_IDLE_LOW Idle state for clock is a low level;active state is a high level 5.6.22.5.7.7 SPI_COMMUNICATION_WIDTH Enumeration C typedef enum { SPI_COMMUNICATION_WIDTH_32BITS, SPI_COMMUNICATION_WIDTH_16BITS, SPI_COMMUNICATION_WIDTH_8BITS } SPI_COMMUNICATION_WIDTH; Description SPI Communication Width This macro defines the list of SPI communication width. Members Members Description SPI_COMMUNICATION_WIDTH_32BITS Communication is 32-bit-wide SPI_COMMUNICATION_WIDTH_16BITS Communication is word-wide SPI_COMMUNICATION_WIDTH_8BITS Communication is byte-wide 5.6.22.5.7.8 SPI_DATA_TYPE Type C typedef unsigned char SPI_DATA_TYPE; Description SPI Data Type definition This data type defines the SPI data size. Remarks None 5.6.22.5.7.9 SPI_ERROR_INTERRUPT Enumeration C typedef enum { SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW, SPI_ERROR_INTERRUPT_RECEIVE_OVERFLOW, SPI_ERROR_INTERRUPT_TRANSMIT_UNDERRUN } SPI_ERROR_INTERRUPT; Description SPI Error Interrupt 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2861 This macro defines the list of SPI error interrupts. Members Members Description SPI_ERROR_INTERRUPT_FRAME_ERROR_OVERFLOW SPI interrupt for fram error SPI_ERROR_INTERRUPT_RECEIVE_OVERFLOW SPI interrupt for receive overflow error SPI_ERROR_INTERRUPT_TRANSMIT_UNDERRUN SPI interrupt for transmit underrun error 5.6.22.5.7.10 SPI_FIFO_INTERRUPT Enumeration C typedef enum { SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_1HALF_EMPTY_OR_MORE, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_COMPLETELY_EMPTY, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_1HALF_FULL_OR_MORE, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_NOT_EMPTY, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_FULL, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_FIFO_IS_EMPTY, SPI_FIFO_INTERRUPT_WHEN_TRANSMISSION_IS_COMPLETE, SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_FIFO_HAS_ONE_SLOT, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_FULL, SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_3FOURTH_OR_MORE_FULL, SPI_FIFO_INTERRUPT_WHEN_DATA_IS_IN_RECEIVE_BUFFER, SPI_FIFO_INTERRUPT_WHEN_BUFFER_IS_EMPTY } SPI_FIFO_INTERRUPT; Description SPI Buffer Interrupt Mode This macro defines the list of SPI Buffer Interrupt mode. Members Members Description SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_NOT_FULL Interrupt when the transmit buffer is not full SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_1HALF_EMPTY_OR_MORE Interrupt when the transmit buffer is half empty SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_COMPLETELY_EMPTY Interrupt when the transmit buffer is empty SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_1HALF_FULL_OR_MORE Interrupt when the receive buffer half full or more SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_NOT_EMPTY Interrupt when the receive buffer is not empty SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_BUFFER_IS_FULL Interrupt when transmit buffer is full SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_FIFO_IS_EMPTY Interrupt when transmit buffer is empty SPI_FIFO_INTERRUPT_WHEN_TRANSMISSION_IS_COMPLETE Interrupt when transmission is complete SPI_FIFO_INTERRUPT_WHEN_TRANSMIT_FIFO_HAS_ONE_SLOT Interrupt when one slot is left in transmit buffer SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_FULL Interrupt when receive buffer is full SPI_FIFO_INTERRUPT_WHEN_RECEIVE_BUFFER_IS_3FOURTH_OR_MORE_FULL Interrupt when receive buffer is 3/4 or more full SPI_FIFO_INTERRUPT_WHEN_DATA_IS_IN_RECEIVE_BUFFER Interrupt when data is available in receive buffer 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2862 SPI_FIFO_INTERRUPT_WHEN_BUFFER_IS_EMPTY Interrupt when the receive buffer is empty 5.6.22.5.7.11 SPI_FIFO_TYPE Enumeration C typedef enum { SPI_FIFO_TYPE_COMMON, SPI_FIFO_TYPE_TRNSMIT, SPI_FIFO_TYPE_RECEIVE } SPI_FIFO_TYPE; Description SPI Buffer Mode This macro defines the list of SPI buffer mode. Members Members Description SPI_FIFO_TYPE_COMMON Buffer type is common type SPI_FIFO_TYPE_TRNSMIT Buffer type is transmit SPI_FIFO_TYPE_RECEIVE Buffer type is receive 5.6.22.5.7.12 SPI_FRAME_PULSE_DIRECTION Enumeration C typedef enum { SPI_FRAME_PULSE_DIRECTION_OUTPUT, SPI_FRAME_PULSE_DIRECTION_INPUT } SPI_FRAME_PULSE_DIRECTION; Description SPI Frame sync pulse direction This macro defines the list of SPI frame sync pulse direction. Members Members Description SPI_FRAME_PULSE_DIRECTION_OUTPUT Frame sync pulse direction is output SPI_FRAME_PULSE_DIRECTION_INPUT Frame sync pulse direction is input 5.6.22.5.7.13 SPI_FRAME_PULSE_EDGE Enumeration C typedef enum { SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK, SPI_FRAME_PULSE_EDGE_PRECEDES_FIRST_BIT_CLOCK } SPI_FRAME_PULSE_EDGE; Description SPI Frame sync pulse edge This macro defines the list of SPI frame sync pulse edge. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2863 Members Members Description SPI_FRAME_PULSE_EDGE_COINCIDES_FIRST_BIT_CLOCK Frame sync pulse coincides with first bit clock SPI_FRAME_PULSE_EDGE_PRECEDES_FIRST_BIT_CLOCK Frame sync pulse precedes first bit clock 5.6.22.5.7.14 SPI_FRAME_PULSE_POLARITY Enumeration C typedef enum { SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH, SPI_FRAME_PULSE_POLARITY_ACTIVE_LOW } SPI_FRAME_PULSE_POLARITY; Description SPI Frame sync pulse polarity This macro defines the list of SPI frame sync pulse polarity. Members Members Description SPI_FRAME_PULSE_POLARITY_ACTIVE_HIGH Frame sync pulse is active high SPI_FRAME_PULSE_POLARITY_ACTIVE_LOW Frame sync pulse is active low 5.6.22.5.7.15 SPI_FRAME_PULSE_WIDTH Enumeration C typedef enum { SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH, SPI_FRAME_PULSE_WIDTH_ONE_CLOCK_WIDE } SPI_FRAME_PULSE_WIDTH; Description SPI Frame sync pulse width This macro defines the list of SPI frame sync pulse width. Members Members Description SPI_FRAME_PULSE_WIDTH_ONE_WORD_LENGTH Frame sync Pulse width as one word length wide SPI_FRAME_PULSE_WIDTH_ONE_CLOCK_WIDE Frame sync Pulse width as one clock wide 5.6.22.5.7.16 SPI_FRAME_SYNC_PULSE Enumeration C typedef enum { SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_16_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_4_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_2_DATA_CHARACTER, SPI_FRAME_SYNC_PULSE_ON_EVERY_DATA_CHARACTER } SPI_FRAME_SYNC_PULSE; Description Frame Sync Pulse Counter enumeration 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2864 This data type defining the frame sync pulse counter values. Members Members Description SPI_FRAME_SYNC_PULSE_ON_EVERY_32_DATA_CHARACTER Generate a fram sync pulse on every 32 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_16_DATA_CHARACTER Generate a fram sync pulse on every 16 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_8_DATA_CHARACTER Generate a fram sync pulse on every 8 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_4_DATA_CHARACTER Generate a fram sync pulse on every 4 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_2_DATA_CHARACTER Generate a fram sync pulse on every 2 data character SPI_FRAME_SYNC_PULSE_ON_EVERY_DATA_CHARACTER Generate a fram sync pulse on every data character 5.6.22.5.7.17 SPI_INPUT_SAMPLING_PHASE Enumeration C typedef enum { SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE, SPI_INPUT_SAMPLING_PHASE_AT_END } SPI_INPUT_SAMPLING_PHASE; Description SPI Data Input Sample Phase This macro defines the list of SPI data input sample phase. Members Members Description SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE SPI Data Input Sample phase in middle SPI_INPUT_SAMPLING_PHASE_AT_END SPI Data Input Sample phase at end 5.6.22.5.7.18 SPI_MODULE_ID Enumeration C typedef enum { SPI_ID_1, SPI_ID_2, SPI_ID_3, SPI_ID_4, SPI_NUMBER_OF_MODULES } SPI_MODULE_ID; Description SPI Module ID This enumeration identifies the SPI modules that are available on a microcontroller. This is the superset of all the possible instances that might be available on Microchip microcontrollers. Members Members Description SPI_ID_1 SPI Module 1 ID SPI_ID_2 SPI Module 2 ID SPI_ID_3 SPI Module 3 ID SPI_ID_4 SPI Module 4 ID SPI_NUMBER_OF_MODULES Number of available SPI modules. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2865 Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.22.5.7.19 SPI_OUTPUT_DATA_PHASE Enumeration C typedef enum { SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK, SPI_OUTPUT_DATA_PHASE_ON_IDLE_TO_ACTIVE_CLOCK } SPI_OUTPUT_DATA_PHASE; Description SPI Ouput Data Phase This macro defines the list of SPI serial output data changes. Members Members Description SPI_OUTPUT_DATA_PHASE_ON_ACTIVE_TO_IDLE_CLOCK Serial output data changes on transition from active clock state to idle clock state SPI_OUTPUT_DATA_PHASE_ON_IDLE_TO_ACTIVE_CLOCK Serial output data changes on transition from idle clock state to active clock state. 5.6.22.5.7.20 SPI_PIN Enumeration C typedef enum { SPI_PIN_SERIAL_CLOCK, SPI_PIN_DATA_OUT, SPI_PIN_DATA_IN, SPI_PIN_SLAVE_SELECT } SPI_PIN; Description SPI pin This data type defining the SPI pin. Members Members Description SPI_PIN_SERIAL_CLOCK SPI clock pin SPI_PIN_DATA_OUT SPI data output pin SPI_PIN_DATA_IN SPI data input pin SPI_PIN_SLAVE_SELECT SPI slave select pin Remarks This enumeration is processor specific. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2866 5.6.22.5.7.21 SPI_PRESCALE_PRIMARY Enumeration C typedef enum { SPI_PRESCALE_PRIMARY_1, SPI_PRESCALE_PRIMARY_4, SPI_PRESCALE_PRIMARY_16, SPI_PRESCALE_PRIMARY_64 } SPI_PRESCALE_PRIMARY; Description Primary Prescaler Values This macro defines the list of possible primary prescaler values. Members Members Description SPI_PRESCALE_PRIMARY_1 SPI Primary Prescaler Value 1:1 SPI_PRESCALE_PRIMARY_4 SPI Primary Prescaler Value 4:1 SPI_PRESCALE_PRIMARY_16 SPI Primary Prescaler Value 16:1 SPI_PRESCALE_PRIMARY_64 SPI Primary Prescaler Value 64:1 5.6.22.5.7.22 SPI_PRESCALE_SECONDARY Enumeration C typedef enum { SPI_PRESCALE_SECONDARY_1, SPI_PRESCALE_SECONDARY_2, SPI_PRESCALE_SECONDARY_3, SPI_PRESCALE_SECONDARY_4, SPI_PRESCALE_SECONDARY_5, SPI_PRESCALE_SECONDARY_6, SPI_PRESCALE_SECONDARY_7, SPI_PRESCALE_SECONDARY_8 } SPI_PRESCALE_SECONDARY; Description Secondary Prescaler Values This macro defines the list of possible secondary prescaler values. Members Members Description SPI_PRESCALE_SECONDARY_1 SPI Seconday Prescaler Value 1:1 SPI_PRESCALE_SECONDARY_2 SPI Seconday Prescaler Value 2:1 SPI_PRESCALE_SECONDARY_3 SPI Seconday Prescaler Value 3:1 SPI_PRESCALE_SECONDARY_4 SPI Seconday Prescaler Value 4:1 SPI_PRESCALE_SECONDARY_5 SPI Seconday Prescaler Value 5:1 SPI_PRESCALE_SECONDARY_6 SPI Seconday Prescaler Value 6:1 SPI_PRESCALE_SECONDARY_7 SPI Seconday Prescaler Value 7:1 SPI_PRESCALE_SECONDARY_8 SPI Seconday Prescaler Value 8:1 5.6.22.5.8 Feature Existence Functions 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2867 5.6.22.5.8.1 PLIB_SPI_ExistsAudioCommunicationWidth Function C bool PLIB_SPI_ExistsAudioCommunicationWidth( SPI_MODULE_ID index ); Description This function identifies whether the AudioCommunicationWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioCommunicationWidthSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AudioCommunicationWidth feature is supported on the device • false - The AudioCommunicationWidth feature is not supported on the device Remarks None. 5.6.22.5.8.2 PLIB_SPI_ExistsAudioErrorControl Function C bool PLIB_SPI_ExistsAudioErrorControl( SPI_MODULE_ID index ); Description This function identifies whether the AudioErrorControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_AudioErrorEnable • PLIB_SPI_AudioErrorDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AudioErrorControl feature is supported on the device • false - The AudioErrorControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2868 5.6.22.5.8.3 PLIB_SPI_ExistsAudioProtocolControl Function C bool PLIB_SPI_ExistsAudioProtocolControl( SPI_MODULE_ID index ); Description This function identifies whether the AudioProtocolControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_AudioProtocolEnable • PLIB_SPI_AudioProtocolDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AudioProtocolControl feature is supported on the device • false - The AudioProtocolControl feature is not supported on the device Remarks None. 5.6.22.5.8.4 PLIB_SPI_ExistsAudioProtocolMode Function C bool PLIB_SPI_ExistsAudioProtocolMode( SPI_MODULE_ID index ); Description This function identifies whether the AudioProtocolMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioProtocolModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AudioProtocolMode feature is supported on the device • false - The AudioProtocolMode feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2869 5.6.22.5.8.5 PLIB_SPI_ExistsAudioTransmitMode Function C bool PLIB_SPI_ExistsAudioTransmitMode( SPI_MODULE_ID index ); Description This function identifies whether the AudioTransmitMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_AudioTransmitModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AudioTransmitMode feature is supported on the device • false - The AudioTransmitMode feature is not supported on the device Remarks None. 5.6.22.5.8.6 PLIB_SPI_ExistsBaudRate Function C bool PLIB_SPI_ExistsBaudRate( SPI_MODULE_ID index ); Description This function identifies whether the BaudRate feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_BaudRateSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRate feature is supported on the device • false - The BaudRate feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2870 5.6.22.5.8.7 PLIB_SPI_ExistsBaudRateClock Function C bool PLIB_SPI_ExistsBaudRateClock( SPI_MODULE_ID index ); Description This function identifies whether the BaudRateClock feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_BaudRateClockSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRateClock feature is supported on the device • false - The BaudRateClock feature is not supported on the device Remarks None. 5.6.22.5.8.8 PLIB_SPI_ExistsBuffer Function C bool PLIB_SPI_ExistsBuffer( SPI_MODULE_ID index ); Description This function identifies whether the Buffer feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_BufferClear • PLIB_SPI_BufferRead • PLIB_SPI_BufferWrite Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Buffer feature is supported on the device • false - The Buffer feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2871 Remarks None. 5.6.22.5.8.9 PLIB_SPI_ExistsBusStatus Function C bool PLIB_SPI_ExistsBusStatus( SPI_MODULE_ID index ); Description This function identifies whether the BusStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_IsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BusStatus feature is supported on the device • false - The BusStatus feature is not supported on the device Remarks None. 5.6.22.5.8.10 PLIB_SPI_ExistsClockPolarity Function C bool PLIB_SPI_ExistsClockPolarity( SPI_MODULE_ID index ); Description This function identifies whether the ClockPolarity feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ClockPolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockPolarity feature is supported on the device • false - The ClockPolarity feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2872 Remarks None. 5.6.22.5.8.11 PLIB_SPI_ExistsCommunicationWidth Function C bool PLIB_SPI_ExistsCommunicationWidth( SPI_MODULE_ID index ); Description This function identifies whether the CommunicationWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_CommunicationWidthSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CommunicationWidth feature is supported on the device • false - The CommunicationWidth feature is not supported on the device Remarks None. 5.6.22.5.8.12 PLIB_SPI_ExistsEnableControl Function C bool PLIB_SPI_ExistsEnableControl( SPI_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_Enable • PLIB_SPI_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2873 • false - The EnableControl feature is not supported on the device Remarks None. 5.6.22.5.8.13 PLIB_SPI_ExistsErrorInterruptControl Function C bool PLIB_SPI_ExistsErrorInterruptControl( SPI_MODULE_ID index ); Description This function identifies whether the ErrorInterruptControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_ErrorInterruptEnable • PLIB_SPI_ErrorInterruptDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ErrorInterruptControl feature is supported on the device • false - The ErrorInterruptControl feature is not supported on the device Remarks None. 5.6.22.5.8.14 PLIB_SPI_ExistsFIFOControl Function C bool PLIB_SPI_ExistsFIFOControl( SPI_MODULE_ID index ); Description This function identifies whether the FIFOControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_FIFOEnable • PLIB_SPI_FIFODisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2874 Returns • true - The FIFOControl feature is supported on the device • false - The FIFOControl feature is not supported on the device Remarks None. 5.6.22.5.8.15 PLIB_SPI_ExistsFIFOCount Function C bool PLIB_SPI_ExistsFIFOCount( SPI_MODULE_ID index ); Description This function identifies whether the FIFOCount feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FIFOCount feature is supported on the device • false - The FIFOCount feature is not supported on the device Remarks None. 5.6.22.5.8.16 PLIB_SPI_ExistsFIFOInterruptMode Function C bool PLIB_SPI_ExistsFIFOInterruptMode( SPI_MODULE_ID index ); Description This function identifies whether the FIFOInterruptMode feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOInterruptModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2875 Returns • true - The FIFOInterruptMode feature is supported on the device • false - The FIFOInterruptMode feature is not supported on the device Remarks None. 5.6.22.5.8.17 PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Function C bool PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus( SPI_MODULE_ID index ); Description This function identifies whether the FIFOShiftRegisterEmptyStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FIFOShiftRegisterIsEmpty Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FIFOShiftRegisterEmptyStatus feature is supported on the device • false - The FIFOShiftRegisterEmptyStatus feature is not supported on the device Remarks None. 5.6.22.5.8.18 PLIB_SPI_ExistsFramedCommunication Function C bool PLIB_SPI_ExistsFramedCommunication( SPI_MODULE_ID index ); Description This function identifies whether the FramedCommunication feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_FramedCommunicationEnable • PLIB_SPI_FramedCommunicationDisable Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2876 Parameters Parameters Description index Identifier for the device instance Returns • true - The FramedCommunication feature is supported on the device • false - The FramedCommunication feature is not supported on the device Remarks None. 5.6.22.5.8.19 PLIB_SPI_ExistsFrameErrorStatus Function C bool PLIB_SPI_ExistsFrameErrorStatus( SPI_MODULE_ID index ); Description This function identifies whether the FrameErrorStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameErrorStatusGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameErrorStatus feature is supported on the device • false - The FrameErrorStatus feature is not supported on the device Remarks None. 5.6.22.5.8.20 PLIB_SPI_ExistsFrameSyncPulseCounter Function C bool PLIB_SPI_ExistsFrameSyncPulseCounter( SPI_MODULE_ID index ); Description This function identifies whether the FrameSyncPulseCounter feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseCounterSelect Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2877 Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameSyncPulseCounter feature is supported on the device • false - The FrameSyncPulseCounter feature is not supported on the device Remarks None. 5.6.22.5.8.21 PLIB_SPI_ExistsFrameSyncPulseDirection Function C bool PLIB_SPI_ExistsFrameSyncPulseDirection( SPI_MODULE_ID index ); Description This function identifies whether the FrameSyncPulseDirection feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseDirectionSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameSyncPulseDirection feature is supported on the device • false - The FrameSyncPulseDirection feature is not supported on the device Remarks None. 5.6.22.5.8.22 PLIB_SPI_ExistsFrameSyncPulseEdge Function C bool PLIB_SPI_ExistsFrameSyncPulseEdge( SPI_MODULE_ID index ); Description This function identifies whether the FrameSyncPulseEdge feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseEdgeSelect Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2878 Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameSyncPulseEdge feature is supported on the device • false - The FrameSyncPulseEdge feature is not supported on the device Remarks None. 5.6.22.5.8.23 PLIB_SPI_ExistsFrameSyncPulsePolarity Function C bool PLIB_SPI_ExistsFrameSyncPulsePolarity( SPI_MODULE_ID index ); Description This function identifies whether the FrameSyncPulsePolarity feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulsePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameSyncPulsePolarity feature is supported on the device • false - The FrameSyncPulsePolarity feature is not supported on the device Remarks None. 5.6.22.5.8.24 PLIB_SPI_ExistsFrameSyncPulseWidth Function C bool PLIB_SPI_ExistsFrameSyncPulseWidth( SPI_MODULE_ID index ); Description This function identifies whether the FrameSyncPulseWidth feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_FrameSyncPulseWidthSelect Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2879 Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameSyncPulseWidth feature is supported on the device • false - The FrameSyncPulseWidth feature is not supported on the device Remarks None. 5.6.22.5.8.25 PLIB_SPI_ExistsInputSamplePhase Function C bool PLIB_SPI_ExistsInputSamplePhase( SPI_MODULE_ID index ); Description This function identifies whether the InputSamplePhase feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_InputSamplePhaseSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InputSamplePhase feature is supported on the device • false - The InputSamplePhase feature is not supported on the device Remarks None. 5.6.22.5.8.26 PLIB_SPI_ExistsMasterControl Function C bool PLIB_SPI_ExistsMasterControl( SPI_MODULE_ID index ); Description This function identifies whether the MasterControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_MasterEnable • PLIB_SPI_SlaveEnable 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2880 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The MasterControl feature is supported on the device • false - The MasterControl feature is not supported on the device Remarks None. 5.6.22.5.8.27 PLIB_SPI_ExistsOutputDataPhase Function C bool PLIB_SPI_ExistsOutputDataPhase( SPI_MODULE_ID index ); Description This function identifies whether the OutputDataPhase feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_OutputDataPhaseSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OutputDataPhase feature is supported on the device • false - The OutputDataPhase feature is not supported on the device Remarks None. 5.6.22.5.8.28 PLIB_SPI_ExistsPinControl Function C bool PLIB_SPI_ExistsPinControl( SPI_MODULE_ID index ); Description This function identifies whether the PinControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_PinEnable 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2881 • PLIB_SPI_PinDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PinControl feature is supported on the device • false - The PinControl feature is not supported on the device Remarks None. 5.6.22.5.8.29 PLIB_SPI_ExistsPrimaryPrescale Function C bool PLIB_SPI_ExistsPrimaryPrescale( SPI_MODULE_ID index ); Description This function identifies whether the PrimaryPrescale feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_PrescalePrimarySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PrimaryPrescale feature is supported on the device • false - The PrimaryPrescale feature is not supported on the device Remarks None. 5.6.22.5.8.30 PLIB_SPI_ExistsReadDataSignStatus Function C bool PLIB_SPI_ExistsReadDataSignStatus( SPI_MODULE_ID index ); Description This function identifies whether the ReadDataSignStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ReadDataIsSignExtended 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2882 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReadDataSignStatus feature is supported on the device • false - The ReadDataSignStatus feature is not supported on the device Remarks None. 5.6.22.5.8.31 PLIB_SPI_ExistsReceiveBufferStatus Function C bool PLIB_SPI_ExistsReceiveBufferStatus( SPI_MODULE_ID index ); Description This function identifies whether the ReceiveBufferStatus feature is available on the SPI module. When this function returns true, this function is are supported on the device: • PLIB_SPI_ReceiverBufferIsFull Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveBufferStatus feature is supported on the device • false - The ReceiveBufferStatus feature is not supported on the device Remarks None. 5.6.22.5.8.32 PLIB_SPI_ExistsReceiveFIFOStatus Function C bool PLIB_SPI_ExistsReceiveFIFOStatus( SPI_MODULE_ID index ); Description This function identifies whether the ReceiveFIFOStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_ReceiverFIFOIsEmpty 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2883 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveFIFOStatus feature is supported on the device • false - The ReceiveFIFOStatus feature is not supported on the device Remarks None. 5.6.22.5.8.33 PLIB_SPI_ExistsReceiverOverflow Function C bool PLIB_SPI_ExistsReceiverOverflow( SPI_MODULE_ID index ); Description This function identifies whether the ReceiverOverflow feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_ReceiverHasOverflowed • PLIB_SPI_ReceiverOverflowClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverOverflow feature is supported on the device • false - The ReceiverOverflow feature is not supported on the device Remarks None. 5.6.22.5.8.34 PLIB_SPI_ExistsSecondaryPrescale Function C bool PLIB_SPI_ExistsSecondaryPrescale( SPI_MODULE_ID index ); Description This function identifies whether the SecondaryPrescale feature is available on the SPI module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2884 • PLIB_SPI_PrescaleSecondarySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SecondaryPrescale feature is supported on the device • false - The SecondaryPrescale feature is not supported on the device Remarks None. 5.6.22.5.8.35 PLIB_SPI_ExistsSlaveSelectControl Function C bool PLIB_SPI_ExistsSlaveSelectControl( SPI_MODULE_ID index ); Description This function identifies whether the SlaveSelectControl feature is available on the SPI module. When this function returns true, these functions are supported on the device: • PLIB_SPI_SlaveSelectEnable • PLIB_SPI_SlaveSelectDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SlaveSelectControl feature is supported on the device • false - The SlaveSelectControl feature is not supported on the device Remarks None. 5.6.22.5.8.36 PLIB_SPI_ExistsStopInIdleControl Function C bool PLIB_SPI_ExistsStopInIdleControl( SPI_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the SPI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2885 • PLIB_SPI_StopInIdleEnable • PLIB_SPI_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.22.5.8.37 PLIB_SPI_ExistsTransmitBufferEmptyStatus Function C bool PLIB_SPI_ExistsTransmitBufferEmptyStatus( SPI_MODULE_ID index ); Description This function identifies whether the TransmitBufferEmptyStatus feature is available on the SPI module. When this function returns true, this function is are supported on the device: • PLIB_SPI_TransmitBufferIsEmpty Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitBufferEmptyStatus feature is supported on the device • false - The TransmitBufferEmptyStatus feature is not supported on the device Remarks None. 5.6.22.5.8.38 PLIB_SPI_ExistsTransmitBufferFullStatus Function C bool PLIB_SPI_ExistsTransmitBufferFullStatus( SPI_MODULE_ID index ); Description This function identifies whether the TransmitBufferFullStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2886 • PLIB_SPI_TransmitBufferIsFull Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitBufferFullStatus feature is supported on the device • false - The TransmitBufferFullStatus feature is not supported on the device Remarks None. 5.6.22.5.8.39 PLIB_SPI_ExistsTransmitUnderRunStatus Function C bool PLIB_SPI_ExistsTransmitUnderRunStatus( SPI_MODULE_ID index ); Description This function identifies whether the TransmitUnderRunStatus feature is available on the SPI module. When this function returns true, this function is supported on the device: • PLIB_SPI_TransmitUnderRunStatusGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitUnderRunStatus feature is supported on the device • false - The TransmitUnderRunStatus feature is not supported on the device Remarks None. 5.6.22.6 Files Files Name Description plib_spi.h SPI PLIB Interface Header for common definitions Description 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2887 5.6.22.6.1 plib_spi.h SPI Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the SPI PLIB. Functions Name Description PLIB_SPI_AudioCommunicationWidthSelect Selects the data width for the SPI audio communication. PLIB_SPI_AudioErrorDisable Disables the SPI error. PLIB_SPI_AudioErrorEnable Enables the SPI error. PLIB_SPI_AudioProtocolDisable Audio protocol is disabled. PLIB_SPI_AudioProtocolEnable Audio protocol is enabled. PLIB_SPI_AudioProtocolModeSelect Selects the Audio Protocol mode. PLIB_SPI_AudioTransmitModeSelect Selects the transmit audio data format. PLIB_SPI_BaudRateClockSelect Selects the type of clock is used by the Baud Rate Generator. PLIB_SPI_BaudRateSet Sets the baud rate to the desired value. PLIB_SPI_BufferClear Clears the SPI buffer. PLIB_SPI_BufferRead Returns the SPI buffer value. PLIB_SPI_BufferWrite Write the data to the SPI buffer. PLIB_SPI_ClockPolaritySelect Enables clock polarity. PLIB_SPI_CommunicationWidthSelect Selects the data width for the SPI communication. PLIB_SPI_Disable Disables the SPI module. PLIB_SPI_Enable Enables the SPI module. PLIB_SPI_ErrorInterruptDisable Enables SPI error interrupts. PLIB_SPI_ErrorInterruptEnable Enables SPI error interrupts PLIB_SPI_ExistsAudioCommunicationWidth Identifies whether the AudioCommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsAudioErrorControl Identifies whether the AudioErrorControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolControl Identifies whether the AudioProtocolControl feature exists on the SPI module. PLIB_SPI_ExistsAudioProtocolMode Identifies whether the AudioProtocolMode feature exists on the SPI module. PLIB_SPI_ExistsAudioTransmitMode Identifies whether the AudioTransmitMode feature exists on the SPI module. PLIB_SPI_ExistsBaudRate Identifies whether the BaudRate feature exists on the SPI module. PLIB_SPI_ExistsBaudRateClock Identifies whether the BaudRateClock feature exists on the SPI module. PLIB_SPI_ExistsBuffer Identifies whether the Buffer feature exists on the SPI module. PLIB_SPI_ExistsBusStatus Identifies whether the BusStatus feature exists on the SPI module. PLIB_SPI_ExistsClockPolarity Identifies whether the ClockPolarity feature exists on the SPI module. PLIB_SPI_ExistsCommunicationWidth Identifies whether the CommunicationWidth feature exists on the SPI module. PLIB_SPI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SPI module. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2888 PLIB_SPI_ExistsErrorInterruptControl Identifies whether the ErrorInterruptControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOControl Identifies whether the FIFOControl feature exists on the SPI module. PLIB_SPI_ExistsFIFOCount Identifies whether the FIFOCount feature exists on the SPI module. PLIB_SPI_ExistsFIFOInterruptMode Identifies whether the FIFOInterruptMode feature exists on the SPI module. PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus Identifies whether the FIFOShiftRegisterEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsFramedCommunication Identifies whether the FramedCommunication feature exists on the SPI module. PLIB_SPI_ExistsFrameErrorStatus Identifies whether the FrameErrorStatus feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseCounter Identifies whether the FrameSyncPulseCounter feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseDirection Identifies whether the FrameSyncPulseDirection feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseEdge Identifies whether the FrameSyncPulseEdge feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulsePolarity Identifies whether the FrameSyncPulsePolarity feature exists on the SPI module. PLIB_SPI_ExistsFrameSyncPulseWidth Identifies whether the FrameSyncPulseWidth feature exists on the SPI module. PLIB_SPI_ExistsInputSamplePhase Identifies whether the InputSamplePhase feature exists on the SPI module. PLIB_SPI_ExistsMasterControl Identifies whether the MasterControl feature exists on the SPI module. PLIB_SPI_ExistsOutputDataPhase Identifies whether the OutputDataPhase feature exists on the SPI module. PLIB_SPI_ExistsPinControl Identifies whether the PinControl feature exists on the SPI module. PLIB_SPI_ExistsPrimaryPrescale Identifies whether the PrimaryPrescale feature exists on the SPI module. PLIB_SPI_ExistsReadDataSignStatus Identifies whether the ReadDataSignStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveBufferStatus Identifies whether the ReceiveBufferStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiveFIFOStatus Identifies whether the ReceiveFIFOStatus feature exists on the SPI module. PLIB_SPI_ExistsReceiverOverflow Identifies whether the ReceiverOverflow feature exists on the SPI module. PLIB_SPI_ExistsSecondaryPrescale Identifies whether the SecondaryPrescale feature exists on the SPI module. PLIB_SPI_ExistsSlaveSelectControl Identifies whether the SlaveSelectControl feature exists on the SPI module. PLIB_SPI_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferEmptyStatus Identifies whether the TransmitBufferEmptyStatus feature exists on the SPI module. PLIB_SPI_ExistsTransmitBufferFullStatus Identifies whether the TransmitBufferFullStatus feature exists on the SPI module. 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2889 PLIB_SPI_ExistsTransmitUnderRunStatus Identifies whether the TransmitUnderRunStatus feature exists on the SPI module. PLIB_SPI_FIFOCountGet Reads the SPI Buffer Element Count bits for either receive or transmit. PLIB_SPI_FIFODisable Disables the SPI enhanced buffer. PLIB_SPI_FIFOEnable Enables the SPI enhanced buffer. PLIB_SPI_FIFOInterruptModeSelect Selects the SPI buffer interrupt mode. PLIB_SPI_FIFOShiftRegisterIsEmpty Returns the current status of the SPI shift register. PLIB_SPI_FramedCommunicationDisable Disables framed SPI support. PLIB_SPI_FramedCommunicationEnable Enables framed SPI support. PLIB_SPI_FrameErrorStatusGet Returns the current status of the SPI frame error. PLIB_SPI_FrameSyncPulseCounterSelect Selects at which character the SPI frame sync pulse is generated. PLIB_SPI_FrameSyncPulseDirectionSelect Selects the frame sync pulse direction. PLIB_SPI_FrameSyncPulseEdgeSelect Selects the frame sync pulse edge. PLIB_SPI_FrameSyncPulsePolaritySelect Selects the frame sync pulse polarity. PLIB_SPI_FrameSyncPulseWidthSelect Sets the frame sync pulse width. PLIB_SPI_InputSamplePhaseSelect Selects the SPI data input sample phase. PLIB_SPI_IsBusy Returns the current SPI module activity status. PLIB_SPI_MasterEnable Enables the SPI in Master mode. PLIB_SPI_OutputDataPhaseSelect Selects serial output data change. PLIB_SPI_PinDisable Enables the selected SPI pins. PLIB_SPI_PinEnable Enables the selected SPI pins. PLIB_SPI_PrescalePrimarySelect Selects the primary prescale for SPI Master mode. PLIB_SPI_PrescaleSecondarySelect Selects the seconday prescale for SPI Master mode. PLIB_SPI_ReadDataIsSignExtended Returns the current status of the receive (RX) FIFO sign-extended data. PLIB_SPI_ReceiverBufferIsFull Returns the current status of the SPI receive buffer. PLIB_SPI_ReceiverFIFOIsEmpty Returns the current status of the SPI receive FIFO. PLIB_SPI_ReceiverHasOverflowed Returns the current status of the SPI receiver overflow. PLIB_SPI_ReceiverOverflowClear Clears the SPI receive overflow flag. PLIB_SPI_SlaveEnable Enables the SPI in Slave mode. PLIB_SPI_SlaveSelectDisable Disables Master mode slave select. PLIB_SPI_SlaveSelectEnable Enables Master mode slave select. PLIB_SPI_StopInIdleDisable Continues module operation when the device enters Idle mode. PLIB_SPI_StopInIdleEnable Discontinues module operation when the device enters Idle mode. PLIB_SPI_TransmitBufferIsEmpty Returns the current status of the transmit buffer. PLIB_SPI_TransmitBufferIsFull Returns the current transmit buffer status of the SPI module. PLIB_SPI_TransmitUnderRunStatusGet Returns the current status of the transmit underrun. Types Name Description SPI_DATA_TYPE Data type defining the SPI data size. File Name plib_spi.h 5.6 Peripheral Library Help MPLAB Harmony Help SPI Peripheral Library 5-2890 Company Microchip Technology Inc. 5.6.23 SQI Peripheral Library 5.6.23.1 Introduction SQI Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Serial Quad Interface (SQI) Peripheral that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the SQI module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The SQI module is a synchronous serial interface that provides access to serial Flash memories and other serial devices. The SQI bus interface consists of four data lines (SQID3-SQID0), a clock line (SQICLK), two select lines (SQICS0 and SQICS1) and the module supports single Lane (identical to SPI), dual Lane, and quad Lane interface modes. SQI operates in only master mode. The SQI module has configurable transmit and receive buffers, programmable baud rates through the internal clock divider, clock phase, and clock polarity control for efficient data operations. Transmit and receive buffers can be accessed through SQITXDATA and SQIRXDATA registers. Similarly, the control buffer can be accessed through the SQI1CON register and is mainly used to pipeline the operations. The SQI module operates in three transfer modes: DMA, PIO, and XIP using three data flow modes:SPI Mode 0 and Mode 3, and a high-speed Serial Flash mode . All three modes use the control buffer to pipeline the command/data sequences on the SQI bus. Following diagrams describe typical SQI hardware interface and software flow. Figure 1 shows the typical hardware interface of SQI module: 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2891 Figure 1: Hardware Interface Diagram Refer to SQI Family Reference Manual section, which is available on Microchip website for additional details on control register information and operation. 5.6.23.2 Release Notes MPLAB Harmony Version: v0.70b SQI Peripheral Library Version :0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.23.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip, its subsidiaries and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2892 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.23.4 Using the Library This topic describes the basic architecture of the SQI Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_sqi. h The interface to the SQI peripheral library is defined in the "plib_sqi.h" header file. This file is included by the "peripheral.h" file. Any C language source (.c) file that uses the SQI peripheral library should include "peripheral.h". Library File: The SQI peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.6.23.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the SQI module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Before jumping into the software abstraction, it is important to understand the SQI hardware a little more in detail. Figure 2 provides a glimpse of SQI hardware block diagram. As shown the diagram the features of SQI are divided into multiple logic blocks and the SQI peripheral library provides APIs to configure the various logic block thus the features. The control and status SFRs block contains all the registers that are used to configure the SQI in a specific mode of operation. The PIO mode of operation of SQI requires a set of registers to be configured by the Host processor and writing to/ reading from the TXDATA and RXDATA registers. The XIP logic facilitates the SQI modules eXecute-In-Place mode of operation, where Host processor programs the set of registers that configure the XIP mode and the engine automatically reads the external flash and the read data gets mapped into a direct memory region. Where as DMA mode requires the Host processor to program a set of buffer descriptors and instructs SQI to point to the address of those buffer descriptors for the reads and writes. As mentioned earlier there are 3 buffers; transmit, receive and control that are accessed through SQIxTXDATA, SQIxRXDATA adn SQIxCON registers respectively. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2893 Figure 2: SQI Hardware Block Diagram The SQI Peripheral Library takes requests from application software or the SQI device driver and controls the SQI hardware as per the inputs passed to the Library Interface Figure 3 provides the SQI peripheral library software abstraction layer diagram. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2894 Figure 3: SQI Software Abstraction Model The major components are SQI Peripheral Library are: • Configuration Management • Interrupt Control and Status Management • DMA Mode Management 5.6.23.4.2 Library Usage Model The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SQI module. Library Interface Section Description Mode Configuration Management Functions These functions are used to setup transfer mode (DMA/XIP/PIO), data mode (SPI Mode 0/Mode 3/ Serial Flash), lane mode (single/dual/quad) and XIP control registers. Clock Configuration Management Functions These functions are used to enable the clock, setup a clock divider and check the status of the clock to see if it's stable. XIP Configuration Management Functions These functions are used to setup parameters for XIP mode of operation. PIO Mode Transfer Management Functions These functions are used to setup TXDATA, RXDATA registers and status checks. Interrupt Control and Status Management Functions These functions are used to control the interrupts. SQI supports only status type of interrupts (no error interrupts). DMA Buffer Address Management Functions These functions are used to setup the address of the base descriptor, check the address of the current descriptor 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2895 DMA Buffer Descriptor Management Functions These functions are used to setup and control 4 words (BD_CTRL, BD_STATUS (reserved), BD_BUF_ADDR and BD_NEXT_PTR) DMA Control and Status Management Functions These functions are used to control the buffer descriptor fetch process and check the status during the buffer descriptor fetches. 5.6.23.4.3 How the Library Works Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.6.23.4.3.1 Core Functionality SQI modules core functionality is to transfer data between the serial device (mostly quad flash) attached and the PIC microcontroller. In order to achieve this, SQI module uses 3 transfer modes: DMA, PIO and XIP. Each transfer mode can be configured to use any of the 3 available data flow modes (Mode 0, Mode 3 and Serial Flash Mode) to achieve the transfers. DMA and PIO modes are typically used to transfer data and XIP mode is used for code execution. Each mode of operation requires setting-up the clock, selecting data flow mode and selecting lane mode and other parameters as required by the device driver or application. SQI peripheral library includes complete set of API necessary to perform these operations. The following sections describe the SQI core functionality in each mode of operation. 5.6.23.4.3.1.1 XIP Mode XIP (eXecute-In-Place) mode is mostly used to execute the code out of the attached serial flash device. However, this mode can also be used to transfer data as deemed necessary. In order for SQI to operate in XIP mode, host processor would have to setup the two SFRs dedicated to the XIP mode in addition to SQI configuration and clock control SFRs. Please refer to the specific data sheet and family reference manual for the configuration details. Please note that all the XIP configuration values depend on the parameters of the interfaced serial flash memory device. In XIP mode, reading values of any other SFRs return the contents of the serial flash device, the way it is mapped. Figure 4 provides the XIP mode software flow. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2896 Figure 4: XIP Mode Flow Diagram Example: // Example is written to access SST26VF032 flash device // Example assumes the Flash Device is connected to Chip Select 0 //Global defines #define SST26VF_HS_READ 0x0B #define SST26VF_MODE_CODE 0x0 #define SST26VF_MODE_BYTES 0x0 // Setup SQI Configuration Bits PLIB_SQI_Enable(SQI_ID_1); PLIB_SQI_CSOutputEnableSelect(SQI_ID_1, SQI_CS_OEN_0); PLIB_SQI_DataOutputEnableSelect(SQI_ID_1, SQI_DATA_OEN_QUAD); // Disable All Interrupts PLIB_SQI_InterruptDisable(SQI_ID_1, SQI_ALL_INT); PLIB_SQI_InterruptSignalDisable(SQI_ID_1, SQI_ALL_INT); // Setup SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_1); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); // Configure XIP Control 1 SFR PLIB_SQI_XIPControlWord1Set (SQI_ID_1, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2897 SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SST26VF_HS_READ, ADDR_BYTES_3, DUMMY_BYTES_2 ); // Configure XIP Control 2 SFR PLIB_SQI_XIPControlWord2Set (SQI_ID_1, SST26VF_MODE_CODE, MODE_BYTES_0, SQI_CS_0 ); // Set Transfer Mode to XIP PLIB_SQI_TransferModeSet(SQI_ID_1, SQI_XFER_MODE_XIP); // The SQI is now in XIP mode and should start fetching the code 5.6.23.4.3.1.2 DMA Mode DMA mode is used for higher throughput data transfers. In DMA mode, the SQI DMA engine controls the data transfers off-loading the host processor. However, the host processor would have to configure the buffer descriptor and some SQI control SFRs to initiate the the DMA process. Once the transactions are in progress, the DMA will be in control and the host processor can get the control through the interrupts or by disabling the DMA. Figure 5 provides the DMA mode software flow. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2898 Note 1: Buffer descriptor is a data structure in memory containing 4 words (BD_CTRL, BD_STAT, BD_BUFADDR and BD_NXTPTR). Note 2: Base address register points to first buffer descriptor in the chain. Figure 5: DMA Mode Flow Diagram Example: // Example is written to access SST26VF032 flash device // Example assumes the Flash Device is connected to Chip Select 0 //Global defines #define SST26VF_EQIO 0x38 #define SST26VF_HS_READ 0x0B #define SST26VF_MODE_CODE 0x0 #define SST26VF_MODE_BYTES 0x0 #define NUMBER_OF_BDs 5 #define POLL_CON_VALUE 10 { // Setup the Buffer Descriptors for ( i=0; i <(NUMBER_OF_BDs-1); i++) { // Setup Buffer Descriptors. Handle structures as application 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2899 // needs. // Configure SQI Control Fields PLIB_SQI_Enable(SQI_ID_1); PLIB_SQI_CSOutputEnableSelect(SQI_ID_1,SQI_CS_OEN_0); PLIB_SQI_DataOutputEnableSelect(SQI_ID_1,SQI_DATA_OEN_2); PLIB_SQI_BurstEnable(SQI_ID_1); PLIB_SQI_SerialModeSet(SQI_ID_1); PLIB_SQI_TransferModeSet(SQI_ID_1,SQI_XFER_MODE_PIO); // Configure the SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_4); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); //Enable Buffer Descriptor Done and Packet Done Interrupts PLIB_SQI_InterruptEnable(SQI_ID_1,BDDONE); PLIB_SQI_InterruptSignalEnable(SQI_ID_1,BDDONE); PLIB_SQI_InterruptEnable(SQI_ID_1,PKTCOMP); PLIB_SQI_InterruptSignalEnable(SQI_ID_1,PKTCOMP); // Send EQIO(0x38) Command to SST26VF032 to Enable Quad Lane Mode // Note: These steps are not in the flow as these are specific to // one Flash Device (SST26VF032) PLIB_SQI_ChipSelectSet(SQI_ID_1,SQI_CS_0); PLIB_SQI_LaneModeSet(SQI_ID_1,SQI_SINGLE_LANE); PLIB_SQI_TransferCommandSet(SQI_ID_1,SQI_CMD_TRANSMIT); // Transfers 1 Command Byte, No Address/Dummy Bytes PLIB_SQI_TransferCountSet(SQI_ID_1, 0x1); PLIB_SQI_TransmitterDataSend(SQI_ID_1, SST26VF_EQIO); // Set the SQI in DMA Mode PLIB_SQI_TransferModeSet(SQI_ID_1,SQI_XFER_MODE_DMA); // Setup the Base Buffer Descriptor Address if (!PLIB_SQI_DMAIsActive(SQI_ID_1)) PLIB_SQI_DMABDBaseAddressSet(SQI_ID_1, (void *) (&MY_BASE_BD_STRUCT)); //Setup DMA Control Register PLIB_SQI_DMABDEnable(SQI_ID_1); PLIB_SQI_DMABDPollEnable(SQI_ID_1); // Setup DMA Polling If (PLIB_SQI_DMABDPollIsEnabled(SQI_ID_1)) // Poll DMA every 10 cycles PLIB_SQI_PollControlSet(SQI_ID_1, MY_POLL_CONTROL_VALUE); // Start the DMA Process - DMA Engine is now in Control If (PLIB_SQI_DMAIsEnabled(SQI_ID_1)) { if (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) PLIB_SQI_DMABDFetchStart(SQI_ID_1); } } 5.6.23.4.3.1.3 PIO Mode PIO mode is mostly used for data transfers. In PIO mode, the SQI module is entirely under the control of host processor. For the SQI module to operate in PIO mode, the host processor would have to set up the configuration, control, and clock control SFRs. Once the transactions are in progress, the host processor can use interrupts and status flags to control the operation. Please refer to the specific device data sheet and family reference manual for the configuration details. Figure 6 provides the PIO mode software flow. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2900 b Figure 6: PIO Mode Flow Diagram Example: // Example is written to access SST26VF032 flash device // Example assumes the Flash Device is connected to Chip Select 0 // Example reads the device ID of the SST26VF032 //Global defines #define FALSE 0 #define TRUE 1 #define SST26VF_EQIO 0x38 #define SST26VF_HS_READ 0x0B #define SST26VF_QJEDID_READ 0x9F #define SST26VF_JEDEC_ID 0xBF2602 { int32_t jedecID; // Setup SQI Configuration (SQI1CFG) Register PLIB_SQI_ConfigWordSet(MY_SQI_INSTANCE, 1, SQI_CS_OEN_0, SQI_DATA_OEN_QUAD, 0, 1, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2901 0, 0, 0, SQI_DATA_FORMAT_MSBF, SQI_DATA_MODE_3, SQI_XFER_MODE_PIO ); PLIB_SQI_ControlBufferThresholdSet(SQI_ID_1,4); // Enable Specific Interrupts PLIB_SQI_InterruptEnable(SQI_ID_1,TXEMPTY|RXFULL/TXTHRIE|RXTHRIE); // Setup SQI Transfer Clock PLIB_SQI_ClockDividerSet(SQI_ID_1,CLK_DIV_1); PLIB_SQI_ClockEnable(SQI_ID_1); while (!PLIB_SQI_ClockIsStable(SQI_ID_1)); // Setup SQI Transmit Command Threshold PLIB_SQI_TxCommandThresholdSet(SQI_ID_1,3); // Setup SQI Receive Buffer Threshold PLIB_SQI_TxBufferThresholdIntSet(SQI_ID_1,3); // Configure SQI Control Fields and Send EQIO(0x38) Command to // SST26VF032 to Enable Quad Lane Mode PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 1, SQI_CS_1, SQI_LANE_SINGLE, SQI_CMD_TRANSMIT, 1 ); PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 0, SQI_CS_1, SQI_LANE_QUAD, SQI_CMD_TRANSMIT, 1 ); PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 0, SQI_CS_1, SQI_LANE_QUAD, SQI_CMD_RECIEVE, 3 ); if ( PLIB_SQI_InterruptFlagGet(SQI_ID_1,TXEMPTY) ) PLIB_SQI_TransmitData(SQI_ID_1, SST26VF_EQIO); //Configure SQI to read JEDEC-ID in Quad Mode if ( PLIB_SQI_InterruptFlagGet(SQI_ID_1,TXEMPTY) ) PLIB_SQI_TransmitData(SQI_ID_1, SST26VF_QJEDID_READ); if (PLIB_SQI_InterruptFlagGet(SQI_ID_1,RXFULL)) jedecID = PLIB_SQI_ReceiveData(SQI_ID_1); if (jedecID == SST26VF_JEDEC_ID) return TRUE; else return FALSE; } 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2902 5.6.23.4.4 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.23.5 Library Interface Data Types and Constants Name Description SQI_ADDR_BYTES Defines the list of SQI Address Bytes SQI_BD_CTRL_WORD Defines the list of SQI Buffer Descriptor Control Word SQI_BD_STATE Defines the list of SQI Buffer Descriptor State SQI_CLK_DIV Defines the list of SQI Clock Divider Values SQI_CS_NUM Defines the list of SQI Chip Selects SQI_CS_OEN Defines the list of SQI Chip Selects on which output is enabled SQI_DATA_FORMAT Defines the Data Format Options available (LSBF/MSBF) SQI_DATA_MODE Defines the list of SQI Data Modes SQI_DATA_OEN Defines the list of SQI Data pins on which output is enabled SQI_DATA_TYPE Data type defining the SQI Data size. SQI_DUMMY_BYTES Defines the list of SQI Dummy Bytes SQI_INTERRUPTS Defines the list of SQI Interrupts SQI_LANE_MODE Defines the list of SQI Lane Modes (single/dual/quad) SQI_MODE_BYTES Defines the list of SQI Mode Bytes SQI_MODULE_ID Identifies the SQI modules supported SQI_XFER_CMD Defines the list of SQI Transfer Commands SQI_XFER_MODE Defines the list of SQI Transfer Modes Clock Configuration Management Functions Name Description PLIB_SQI_ClockDividerGet Returns the SQI clock divider value. PLIB_SQI_ClockDividerSet Sets the SQI clock (that drives the SQI protocol) divider value. Divides the base clock to generate the SQI clock. PLIB_SQI_ClockEnable Enables the SQI transfer clock. PLIB_SQI_ClockIsStable Returns SQI transfer clock state. DMA Buffer Address Management Functions Name Description PLIB_SQI_DMABDBaseAddressGet Returns the address of the base buffer descriptor. PLIB_SQI_DMABDBaseAddressSet Sets the address of the base buffer descriptor. PLIB_SQI_DMABDCurrentAddressGet Returns the address of the current buffer descriptor in process. DMA Buffer Descriptor Management Functions Name Description PLIB_SQI_DMABDControlWordGet Returns Current Buffer Descriptor Control Word Information. PLIB_SQI_DMABDReceiveBufferCountGet Returns the receive buffer space in bytes. PLIB_SQI_DMABDReceiveBufferLengthGet Returns the receive length in bytes. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2903 PLIB_SQI_DMABDReceiveStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDTransmitBufferCountGet Returns the transmit buffer space in bytes. PLIB_SQI_DMABDTransmitBufferLengthGet Returns the transmit length in bytes. PLIB_SQI_DMABDTransmitStateGet Returns the current state of the buffer descriptor in progress. DMA Control and Status Management Functions Name Description PLIB_SQI_DMABDFetchStart Start the DMA buffer descriptor fetch process. PLIB_SQI_DMABDIsBusy Returns true if DMA Buffer Descriptor is busy. PLIB_SQI_DMABDPollCounterSet Sets the poll counter value. PLIB_SQI_DMABDPollDisable Disables the buffer descriptor polling. PLIB_SQI_DMABDPollEnable Enables the buffer descriptor polling. PLIB_SQI_DMABDPollIsEnabled Returns true if DAM buffer descriptor poll is eanbled and false if it's disabled. PLIB_SQI_DMABDStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMADisable Disables the built-in DMA logic. PLIB_SQI_DMAEnable Enables the built-in DMA logic. PLIB_SQI_DMAHasStarted Returns true if DMA process has started if not returns false. PLIB_SQI_DMAIsEnabled Returns true if DAM is eanbled and false if it's disabled. Feature Existence Functions Name Description PLIB_SQI_ExistsBDBaseAddress Identifies whether the BDBaseAddress feature exists on the SQI module PLIB_SQI_ExistsBDControlWord Identifies whether the BDControlWord feature exists on the SQI module PLIB_SQI_ExistsBDCurrentAddress Identifies whether the BDCurrentAddress feature exists on the SQI module PLIB_SQI_ExistsBDPollCount Identifies whether the BDPollCount feature exists on the SQI module PLIB_SQI_ExistsBDPollingEnable Identifies whether the BDPollingEnable feature exists on the SQI module PLIB_SQI_ExistsBDProcessState Identifies whether the BDProcessState feature exists on the SQI module PLIB_SQI_ExistsBDRxBufCount Identifies whether the BDRxBufCount feature exists on the SQI module PLIB_SQI_ExistsBDRxLength Identifies whether the BDRxLength feature exists on the SQI module PLIB_SQI_ExistsBDRxState Identifies whether the BDRxState feature exists on the SQI module PLIB_SQI_ExistsBDTxBufCount Identifies whether the BDTxBufCount feature exists on the SQI module PLIB_SQI_ExistsBDTxLength Identifies whether the BDTxLength feature exists on the SQI module PLIB_SQI_ExistsBDTxState Identifies whether the BDTxState feature exists on the SQI module PLIB_SQI_ExistsBurstControl Identifies whether the BurstControl feature exists on the SQI module PLIB_SQI_ExistsChipSelect Identifies whether the ChipSelect feature exists on the SQI module PLIB_SQI_ExistsClockControl Identifies whether the ClockControl feature exists on the SQI module PLIB_SQI_ExistsClockDivider Identifies whether the ClockDivider feature exists on the SQI module PLIB_SQI_ExistsClockReady Identifies whether the ClockReady feature exists on the SQI module PLIB_SQI_ExistsConBufThreshold Identifies whether the ConBufThreshold feature exists on the SQI module PLIB_SQI_ExistsConfigWord Identifies whether the ConfigWord feature exists on the SQI module 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2904 PLIB_SQI_ExistsControlWord Identifies whether the ControlWord feature exists on the SQI module PLIB_SQI_ExistsCSDeassert Identifies whether the CSDeassert feature exists on the SQI module PLIB_SQI_ExistsCSOutputEnable Identifies whether the CSOutputEnable feature exists on the SQI module PLIB_SQI_ExistsDataFormat Identifies whether the DataFormat feature exists on the SQI module PLIB_SQI_ExistsDataModeControl Identifies whether the DataModeControl feature exists on the SQI module PLIB_SQI_ExistsDataOutputEnable Identifies whether the DataOutputEnable feature exists on the SQI module PLIB_SQI_ExistsDataPinStatus Identifies whether the DataPinStatus feature exists on the SQI module PLIB_SQI_ExistsDmaEnable Identifies whether the DMAEnable feature exists on the SQI module PLIB_SQI_ExistsDMAEngineBusy Identifies whether the DMAEngineBusy feature exists on the SQI module PLIB_SQI_ExistsDMAProcessInProgress Identifies whether the DMAProcessInProgress feature exists on the SQI module PLIB_SQI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SQI module PLIB_SQI_ExistsHoldPinControl Identifies whether the HoldPinControl feature exists on the SQI module PLIB_SQI_ExistsInterruptControl Identifies whether the InterruptControl feature exists on the SQI module PLIB_SQI_ExistsInterruptSignalControl Identifies whether the InterruptSignalControl feature exists on the SQI module PLIB_SQI_ExistsInterruptStatus Identifies whether the InterruptStatus feature exists on the SQI module PLIB_SQI_ExistsLaneMode Identifies whether the LaneMode feature exists on the SQI module PLIB_SQI_ExistsReceiveLatch Identifies whether the ReceiveLatch feature exists on the SQI module PLIB_SQI_ExistsRxBufferCount Identifies whether the RxBufferCount feature exists on the SQI module PLIB_SQI_ExistsRxBufIntThreshold Identifies whether the RxBufIntThreshold feature exists on the SQI module PLIB_SQI_ExistsRxBufThreshold Identifies whether the RxBufThreshold feature exists on the SQI module PLIB_SQI_ExistsRxData Identifies whether the RxData feature exists on the SQI module PLIB_SQI_ExistsRxUnderRun Identifies whether the RxUnderRun feature exists on the SQI module PLIB_SQI_ExistsSoftReset Identifies whether the SoftReset feature exists on the SQI module PLIB_SQI_ExistsStartDMA Identifies whether the StartDMA feature exists on the SQI module PLIB_SQI_ExistsTransferCommand Identifies whether the TransferCommand feature exists on the SQI module PLIB_SQI_ExistsTransferCount Identifies whether the TransferCount feature exists on the SQI module PLIB_SQI_ExistsTransferModeControl Identifies whether the TransferModeControl feature exists on the SQI module PLIB_SQI_ExistsTxBufferFree Identifies whether the TxBufferFree feature exists on the SQI module PLIB_SQI_ExistsTxBufIntThreshold Identifies whether the TxBufIntThreshold feature exists on the SQI module PLIB_SQI_ExistsTxBufThreshold Identifies whether the TxBufThreshold feature exists on the SQI module 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2905 PLIB_SQI_ExistsTxData Identifies whether the TxData feature exists on the SQI module PLIB_SQI_ExistsTxOverFlow Identifies whether the TxOverFlow feature exists on the SQI module PLIB_SQI_ExistsWPPinControl Identifies whether the WPPinControl feature exists on the SQI module PLIB_SQI_ExistsXIPChipSelect Identifies whether the XIPChipSelect feature exists on the SQI module PLIB_SQI_ExistsXIPControlWord1 Identifies whether the XIPControlWord1 feature exists on the SQI module PLIB_SQI_ExistsXIPControlWord2 Identifies whether the XIPControlWord2 feature exists on the SQI module PLIB_SQI_ExistsXIPLaneMode Identifies whether the XIPLaneMode feature exists on the SQI module PLIB_SQI_ExistsXIPModeBytes Identifies whether the XIPModeBytes feature exists on the SQI module PLIB_SQI_ExistsXIPModeCode Identifies whether the XIPModeCode feature exists on the SQI module PLIB_SQI_ExistsXIPNumberOfAddressBytes Identifies whether the XIPNumberOfAddressBytes feature exists on the SQI module PLIB_SQI_ExistsXIPNumberOfDummyBytes Identifies whether the XIPNumberOfDummyBytes feature exists on the SQI module PLIB_SQI_ExistsXIPReadOpCode Identifies whether the XIPReadOpCode feature exists on the SQI module Interrupt Control and Status Management Functions Name Description PLIB_SQI_DataLineStatus Returns the logical status of the SQI data lines. PLIB_SQI_InterruptDisable Disables the interrupt source. PLIB_SQI_InterruptEnable Enables the interrupt source passed. PLIB_SQI_InterruptFlagGet Return SQI Interrupt flag status. PLIB_SQI_InterruptIsEnabled Returns the interrupt state (eanbled/disabled). PLIB_SQI_InterruptSignalDisable Disables the interrupt signal source. PLIB_SQI_InterruptSignalEnable Enables the interrupt signal source passed. PLIB_SQI_InterruptSignalIsEnabled Returns the interrupt signal state (eanbled/disabled). Mode Configuration Management Functions Name Description PLIB_SQI_BurstEnable This bit sets the burst enable (BURSTEN) function for higher throughput. This function is artifact of the system bus architecture. PLIB_SQI_ClockDisable Disables the SQI transfer clock. PLIB_SQI_ControlBufferThresholdGet Returns the transmit buffer space in bytes. PLIB_SQI_ControlBufferThresholdSet Sets the control buffer threshold value. PLIB_SQI_ControlWordGet Get the SQI control word. PLIB_SQI_ControlWordSet Sets SQI Control Word. PLIB_SQI_CSOutputEnableSelect Selects the output enables on SQI chip select pins. PLIB_SQI_DataFormatGet Returns the data format to Least Significant Bit First or LITTLE-ENDIAN. PLIB_SQI_DataFormatSet Sets the data format to Least Significant Bit First or LITTLE-ENDIAN. PLIB_SQI_DataModeGet Returns the SQI data mode of operation (SPI Mode0/Mode3). PLIB_SQI_DataModeSet Sets the SQI data mode of operation (SPI Mode0/Mode3/Serial Flash). 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2906 PLIB_SQI_DataOutputEnableSelect Selects the output enables on SQI data outputs. PLIB_SQI_Disable Disables the SQI module. PLIB_SQI_Enable Enables the SQI module. PLIB_SQI_HoldClear This bit clears the hold function to be disabled on SQID3 in single and dual lane modes. PLIB_SQI_HoldGet This bit gets the status of HOLD function on SQID3 pin. PLIB_SQI_HoldSet This bit sets the hold function to be enabled on SQID3 in single or dual lane modes. PLIB_SQI_LaneModeGet Returns the lane mode (single/dual/quad). PLIB_SQI_LaneModeSet Sets the data lane mode (single/dual/quad). PLIB_SQI_NumberOfReceiveBufferReads Returns the number of receive buffer reads. PLIB_SQI_ReceiveData Reads the data from the receive buffer. PLIB_SQI_ReceiveLatchDisable Disables the receive latch so receive data is discarded when in transmit mode. PLIB_SQI_ReceiveLatchEnable Enable the receive latch so receive data is latched during transmit mode. PLIB_SQI_ReceiveLatchGet Returns the receive latch status in transmit mode. PLIB_SQI_SoftReset This bit issues a soft reset to the SQI module. PLIB_SQI_TransferModeGet Returns the SQI transfer mode (PIO/DMA/XIP) of operation. PLIB_SQI_TransferModeSet Sets the SQI transfer mode (PIO/DMA/XIP) of operation. PLIB_SQI_TransmitData Writes data into the SQI transmit buffer. PLIB_SQI_WriteProtectClear This bit clears the Write-Protect function to be disabled on SQID2 in single or dual lane modes. PLIB_SQI_WriteProtectGet This bit gets the Write-Protect state of Write_Protect Feature on SQID2. PLIB_SQI_WriteProtectSet This bit sets the Write-Protect function to be enabled on SQID2 in single or dual Lane modes only. PIO Mode Transfer Management Functions Name Description PLIB_SQI_ByteCountGet Returns the current transmit/receive count. PLIB_SQI_ByteCountSet Sets the transmit/receive count. PLIB_SQI_ChipSelectDeassertDisable Clears the chip select de-assert. PLIB_SQI_ChipSelectDeassertEnable Sets the chip select de-assert. PLIB_SQI_ChipSelectGet Returns the chip select that is currently active. PLIB_SQI_ChipSelectSet Activates the chip select. PLIB_SQI_ConfigWordGet Get the SQI configuration word. PLIB_SQI_ConfigWordSet Sets SQI Configuration Word. PLIB_SQI_ReceiveBufferIsUnderrun Returns the status of receive buffer. PLIB_SQI_RxBufferThresholdGet Returns the receive command threshold. PLIB_SQI_RxBufferThresholdIntGet Sets the receive buffer threshold interrupt. PLIB_SQI_RxBufferThresholdIntSet Sets the receive buffer threshold for interrupt. PLIB_SQI_RxBufferThresholdSet Sets the receive command threshold. PLIB_SQI_TransferDirectionGet Returns the transfer command. PLIB_SQI_TransferDirectionSet Sets the transfer command. PLIB_SQI_TransmitBufferFreeSpaceGet Returns the number of transmit buffer words available. PLIB_SQI_TransmitBufferHasOverflowed Returns the current status of the transmit buffer. PLIB_SQI_TxBufferThresholdGet Returns the transmit command threshold value. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2907 PLIB_SQI_TxBufferThresholdIntGet Returns the value to tigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdIntSet Sets the value to tigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdSet Sets the transmit command threshold. XIP Configuration Management Functions Name Description PLIB_SQI_XIPAddressBytesGet Returns the number of address bytes. PLIB_SQI_XIPAddressBytesSet Sets the number of address bytes. PLIB_SQI_XIPChipSelectGet Returns the current active chip select. PLIB_SQI_XIPChipSelectSet Activates the chip select in XIP mode. PLIB_SQI_XIPControlWord1Get Get the XIP mode control word 1. PLIB_SQI_XIPControlWord1Set Sets the XIP mode control word 1. PLIB_SQI_XIPControlWord2Get Get the XIP mode control word 2. PLIB_SQI_XIPControlWord2Set Sets the XIP mode control word 2. PLIB_SQI_XIPDummyBytesGet Sets the number of dummy bytes. PLIB_SQI_XIPDummyBytesSet Sets the number of dummy bytes. PLIB_SQI_XIPLaneModeGet Returns the lane (single/dual/quad) mode in XIP mode. PLIB_SQI_XIPLaneModeSet Selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. PLIB_SQI_XIPModeBytesGet Returns the number of bytes used for mode code command. PLIB_SQI_XIPModeBytesSet Allocates the bytes for mode code command. PLIB_SQI_XIPModeCodeGet Returns the mode code op-code. PLIB_SQI_XIPModeCodeSet Sets the mode code command. PLIB_SQI_XIPReadOpcodeGet Returns the read opcode in XIP mode. PLIB_SQI_XIPReadOpcodeSet Sets the read opcode in XIP mode. Description This section describes the Application Programming Interface (API) functions of the SQI Peripheral Library. Refer to each section for a detailed description. 5.6.23.5.1 Mode Configuration Management Functions 5.6.23.5.1.1 PLIB_SQI_BurstEnable Function C void PLIB_SQI_BurstEnable( SQI_MODULE_ID index ); Description This routine enables burst mode for higher throughput. Burst mode should always be enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2908 Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_BurstEnable(MY_SQI_INSTANCE); 5.6.23.5.1.2 PLIB_SQI_ClockDisable Function C void PLIB_SQI_ClockDisable( SQI_MODULE_ID index ); Description This routine disables the SQI transfer clock (divided clock). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks SQICLK is disabled. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockDisable(MY_SQI_INSTANCE); 5.6.23.5.1.3 PLIB_SQI_ControlBufferThresholdGet Function C uint8_t PLIB_SQI_ControlBufferThresholdGet( SQI_MODULE_ID index ); Description This routine returns the threshold value for the control buffer in bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2909 Returns Control buffer threshold space. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t conBufThres = PLIB_SQI_ControlBufferThresholdGet(MY_SQI_INSTANCE); 5.6.23.5.1.4 PLIB_SQI_ControlBufferThresholdSet Function C void PLIB_SQI_ControlBufferThresholdSet( SQI_MODULE_ID index, uint8_t threshold ); Description This routine sets the control buffer threshold value in bytes, that is used to signal control buffer threshold interrupts. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured threshold Control buffer threshold Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_CONBUF_THRESHOLD is the threshold value. PLIB_SQI_ControlBufferThresholdSet(MY_SQI_INSTANCE, MY_CONBUF_THRESHOLD); 5.6.23.5.1.5 PLIB_SQI_ControlWordGet Function C uint32_t PLIB_SQI_ControlWordGet( SQI_MODULE_ID index ); Description This routine returns the SQI control word. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2910 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t sqiCon = PLIB_SQI_ControlWordGet (MY_SQI_INSTANCE); 5.6.23.5.1.6 PLIB_SQI_ControlWordSet Function C void PLIB_SQI_ControlWordSet( SQI_MODULE_ID index, bool csDeassert, SQI_CS_NUM csNum, SQI_LANE_MODE laneMode, SQI_XFER_CMD command, uint16_t xferCount ); Description This routine sets SQI Control Word. This API is cumulation of multiple APIs, in case driver plans to write the complete control word. In PIO Mode Control word is before each transfer Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured csDeassert Chip select deassert after transfer csNum Active chip select number (0/1) laneMode SQI lane mode (QUAL/DUAL/SINGLE) command Transfer command (TRANSMIT/RECIEVE/IDLE) xferCount Number of bytes to be transmitted/received Returns None. Remarks Chip select is not actually asserted, only enabled to be asserted. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ControlWordSet(MY_SQI_INSTANCE, 1, SQI_CS_1, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2911 SQI_LANE_QUAD, SQI_CMD_TRANSMIT, 5 ); 5.6.23.5.1.7 PLIB_SQI_CSOutputEnableSelect Function C void PLIB_SQI_CSOutputEnableSelect( SQI_MODULE_ID index, SQI_CS_OEN csPins ); Description This routine enables the selected SQI chip selects as outputs. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured csPins Chip select pins for which outputs are enabled Returns None. Remarks Chip select is not actually asserted, only enabled to be asserted. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_CSOutputEnableSelect(MY_SQI_INSTANCE, SQI_CS_OEN_0); 5.6.23.5.1.8 PLIB_SQI_DataFormatGet Function C SQI_DATA_FORMAT PLIB_SQI_DataFormatGet( SQI_MODULE_ID index ); Description This routine returns the SQI data format (LSBF/MSBF). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if Data Format is LSBF, else flase. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2912 Remarks Typical data format in most of the Systems is LITTLE ENDIAN. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_DATA_FORMAT dataFormat = PLIB_SQI_DataFormatGet(MY_SQI_INSTANCE); 5.6.23.5.1.9 PLIB_SQI_DataFormatSet Function C void PLIB_SQI_DataFormatSet( SQI_MODULE_ID index, SQI_DATA_FORMAT dataformat ); Description This routine sets the SQI data format to LSBF (LITTLE-ENDIAN). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Typical data format in most of the Systems is LITTLE ENDIAN. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DataFormatSet(MY_SQI_INSTANCE, SQI_DATA_FORMAT_LSBF); 5.6.23.5.1.10 PLIB_SQI_DataModeGet Function C SQI_DATA_MODE PLIB_SQI_DataModeGet( SQI_MODULE_ID index ); Description This routine returns the SQI data mode (SPI Mode 0/Mode 3) of operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2913 Returns Data mode (SPI Mode 0/Mode 3). Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_DATA_MODE dataMode = PLIB_SQI_DataModeGet(MY_SQI_INSTANCE); 5.6.23.5.1.11 PLIB_SQI_DataModeSet Function C void PLIB_SQI_DataModeSet( SQI_MODULE_ID index, SQI_DATA_MODE mode ); Description This routine sets the data mode to be SPI Mode 0, SPI Mode 3 or Serial Flash. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode Data mode (Mode 0/ Mode 3) Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_DATA_MODE_3 is an enum element. PLIB_SQI_DataModeSet(MY_SQI_INSTANCE, SQI_DATA_MODE_SF); 5.6.23.5.1.12 PLIB_SQI_DataOutputEnableSelect Function C void PLIB_SQI_DataOutputEnableSelect( SQI_MODULE_ID index, SQI_DATA_OEN dataPins ); Description This routine enables the selected SQI data lines as outputs. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2914 Parameters Parameters Description index Identifier for the device instance to be configured dataPins Data pins for which outputs are enabled Returns None. Remarks Chip select is not actually asserted, only enabled to be asserted. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DataOutputEnableSelect(MY_SQI_INSTANCE, SQI_DATA_OEN_DUAL); 5.6.23.5.1.13 PLIB_SQI_Disable Function C void PLIB_SQI_Disable( SQI_MODULE_ID index ); Description This routine disables the SQI module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_Disable(MY_SQI_INSTANCE); 5.6.23.5.1.14 PLIB_SQI_Enable Function C void PLIB_SQI_Enable( SQI_MODULE_ID index ); Description This routine enables the SQI module. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2915 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks The SQICLK, SQICSx, SQID0, SQID1, SQID2 and SQID3 pins must be assigned to available RPn pins before use. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_Enable(MY_SQI_INSTANCE); 5.6.23.5.1.15 PLIB_SQI_HoldClear Function C void PLIB_SQI_HoldClear( SQI_MODULE_ID index ); Description This routine sets SQID3 to be controlled by SQI for normal data operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_HoldClear(MY_SQI_INSTANCE); 5.6.23.5.1.16 PLIB_SQI_HoldGet Function C void PLIB_SQI_HoldGet( SQI_MODULE_ID index ); Description This routine gets the status of HOLD function on SQID3 pin. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2916 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool holdStatus = PLIB_SQI_HoldGet(MY_SQI_INSTANCE); 5.6.23.5.1.17 PLIB_SQI_HoldSet Function C void PLIB_SQI_HoldSet( SQI_MODULE_ID index ); Description This routine sets the SQID3 pin to HIGH/LOW to be be used for hold function in single and dual lane modes for supported flash memories. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function should be used only when SQI is in single/dual lane modes. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_HoldSet(MY_SQI_INSTANCE); 5.6.23.5.1.18 PLIB_SQI_LaneModeGet Function C SQI_LANE_MODE PLIB_SQI_LaneModeGet( SQI_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2917 Description This routine returns the number of lanes (single/dual/quad) used for tansfers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Lane Mode. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_LANE_MODE laneMode = PLIB_SQI_LaneModeGet(MY_SQI_INSTANCE); 5.6.23.5.1.19 PLIB_SQI_LaneModeSet Function C void PLIB_SQI_LaneModeSet( SQI_MODULE_ID index, SQI_LANE_MODE mode ); Description This routine sets the number of lanes (single/dual/quad) used for tansfers. Preconditions Make sure the output enable is selected on the data lines (PLIB_SQI_DataOutputEnableSelect). The device needs to be programmed to the same mode that the SQI controller is set to (might require special commands). Parameters Parameters Description index Identifier for the device instance to be configured mode Lane mode (single/dual/quad) Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_LaneModeSet(MY_SQI_INSTANCE, SQI_LANE_QUAD); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2918 5.6.23.5.1.20 PLIB_SQI_NumberOfReceiveBufferReads Function C uint8_t PLIB_SQI_NumberOfReceiveBufferReads( SQI_MODULE_ID index ); Description This routine returns the number of receive buffer reads for debug purpose. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Number of Receive Buffer Reads. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufReads = PLIB_SQI_ReceiveBufferReadsGet(MY_SQI_INSTANCE); 5.6.23.5.1.21 PLIB_SQI_ReceiveData Function C uint32_t PLIB_SQI_ReceiveData( SQI_MODULE_ID index ); Description This routine reads the data from the SQI receive buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t receivedData= PLIB_SQI_ReceiveData(MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2919 5.6.23.5.1.22 PLIB_SQI_ReceiveLatchDisable Function C void PLIB_SQI_ReceiveLatchDisable( SQI_MODULE_ID index ); Description This routine disables the receive latch, which disables the receive data to be latched in transmit mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ReceiveLatchDisable(MY_SQI_INSTANCE); 5.6.23.5.1.23 PLIB_SQI_ReceiveLatchEnable Function C void PLIB_SQI_ReceiveLatchEnable( SQI_MODULE_ID index ); Description This routine enables the receive latch, which latches receive data in transmit mode. Otherwise receive data in transmit mode is discarded. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks As most of the SQI communication is half-duplex, enable this function only when it's absolutely required. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2920 PLIB_SQI_ReceiveLatchEnable(MY_SQI_INSTANCE); 5.6.23.5.1.24 PLIB_SQI_ReceiveLatchGet Function C bool PLIB_SQI_ReceiveLatchGet( SQI_MODULE_ID index ); Description This routine returns the receive latch status in transmit mode. Returns true, if latch is set (enabling latching of receive buffer data), false if latch is not set (disabling the latching of the receive buffer data). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if Receive latch is set, false if not. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool rxLatch = PLIB_SQI_ReceiveLatchGet(MY_SQI_INSTANCE); 5.6.23.5.1.25 PLIB_SQI_SoftReset Function C void PLIB_SQI_SoftReset( SQI_MODULE_ID index ); Description This routine issues a software reset to the SQI module clearing all the read/write register, internal state machines and data buffers. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2921 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_SoftReset(MY_SQI_INSTANCE); 5.6.23.5.1.26 PLIB_SQI_TransferModeGet Function C SQI_XFER_MODE PLIB_SQI_TransferModeGet( SQI_MODULE_ID index ); Description This routine returns the SQI transfer mode (PIO/DMA/XIP) of operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured. Returns Transfer mode (PIO/DMA/XIP). Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_XFER_MODE xferMode = PLIB_SQI_TransferModeGet(MY_SQI_INSTANCE); 5.6.23.5.1.27 PLIB_SQI_TransferModeSet Function C void PLIB_SQI_TransferModeSet( SQI_MODULE_ID index, SQI_XFER_MODE mode ); Description This routine sets the SQI transfer mode (PIO/DMA/XIP) of operation. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode Transfer mode (PIO/DMA/XIP) Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2922 Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_XFER_MODE_DMA is an enum element. PLIB_SQI_TransferModeSet(MY_SQI_INSTANCE, SQI_XFER_MODE_DMA); 5.6.23.5.1.28 PLIB_SQI_TransmitData Function C void PLIB_SQI_TransmitData( SQI_MODULE_ID index, uint32_t data ); Description This routine writes the data into the SQI transmit buffer, which will be eventually sent out on SQI bus. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Data to be transmitted Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TRANSMIT_DATA is the data to be sent. PLIB_SQI_TransmitData(MY_SQI_INSTANCE, MY_TRANSMIT_DATA); 5.6.23.5.1.29 PLIB_SQI_WriteProtectClear Function C void PLIB_SQI_WriteProtectClear( SQI_MODULE_ID index ); Description This routine disables the SQID2 pin to be used for write-protect function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2923 Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_WriteProtectClear(MY_SQI_INSTANCE); 5.6.23.5.1.30 PLIB_SQI_WriteProtectGet Function C bool PLIB_SQI_WriteProtectGet( SQI_MODULE_ID index ); Description This routine gets the Write-Protect feature status on SQID2 pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool wpStatus = PLIB_SQI_WriteProtectGet(MY_SQI_INSTANCE); 5.6.23.5.1.31 PLIB_SQI_WriteProtectSet Function C void PLIB_SQI_WriteProtectSet( SQI_MODULE_ID index ); Description This routine enables the SQID2 pin to be used for write-protect in single and dual lane modes for supported flash memories. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2924 Returns None. Remarks This function should be used only when SQI is in single/dual lane modes. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_WriteProtectSet (MY_SQI_INSTANCE); 5.6.23.5.2 Clock Configuration Management Functions 5.6.23.5.2.1 PLIB_SQI_ClockDividerGet Function C SQI_CLK_DIV PLIB_SQI_ClockDividerGet( SQI_MODULE_ID index ); Description This routine returns the SQI clock divider value. The returned value in conjuction with the SQI base clock can be used to get the clock rate of SQI clock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Clock Divider Value. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_CLK_DIV clkDiv = PLIB_SQI_ClockDividerGet(MY_SQI_INSTANCE); 5.6.23.5.2.2 PLIB_SQI_ClockDividerSet Function C void PLIB_SQI_ClockDividerSet( SQI_MODULE_ID index, SQI_CLK_DIV clkDivider ); Description This routine sets the SQI clock divider value. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2925 Parameters Parameters Description index Identifier for the device instance to be configured clkDivider Clock divider value Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockDividerSet(MY_SQI_INSTANCE, CLK_DIV_1); 5.6.23.5.2.3 PLIB_SQI_ClockEnable Function C void PLIB_SQI_ClockEnable( SQI_MODULE_ID index ); Description This routine enables the SQI transfer clock (divided clock). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks SQICLK is enabled. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ClockEnable(MY_SQI_INSTANCE); 5.6.23.5.2.4 PLIB_SQI_ClockIsStable Function C bool PLIB_SQI_ClockIsStable( SQI_MODULE_ID index ); Description This routine returns the SQI transfer clock state. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2926 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if clock is stable and false if it's not. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool clockState = PLIB_SQI_ClockIsStable(MY_SQI_INSTANCE); 5.6.23.5.3 XIP Configuration Management Functions 5.6.23.5.3.1 PLIB_SQI_XIPAddressBytesGet Function C SQI_ADDR_BYTES PLIB_SQI_XIPAddressBytesGet( SQI_MODULE_ID index ); Description This routine returns the number of address bytes to be sent to the flash. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Number of Address Bytes. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t addressBytes = PLIB_SQI_XIPAddressBytesGet(MY_SQI_INSTANCE); 5.6.23.5.3.2 PLIB_SQI_XIPAddressBytesSet Function C void PLIB_SQI_XIPAddressBytesSet( SQI_MODULE_ID index, SQI_ADDR_BYTES bytes 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2927 ); Description This routine sets the number of address bytes to be sent to the flash. Typical flash address bytes are 3 (24-bit address). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of address bytes Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPAddressBytesSet(MY_SQI_INSTANCE, ADDR_BYTES_3); 5.6.23.5.3.3 PLIB_SQI_XIPChipSelectGet Function C SQI_CS_NUM PLIB_SQI_XIPChipSelectGet( SQI_MODULE_ID index ); Description This routine returns the active chip select in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_CS_NUM xipCSActive = (PLIB_SQI_XIPChipSelectGet(MY_SQI_INSTANCE); 5.6.23.5.3.4 PLIB_SQI_XIPChipSelectSet Function C void PLIB_SQI_XIPChipSelectSet( 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2928 SQI_MODULE_ID index, SQI_CS_NUM csNum ); Description This routine sets the chip select that is active in XIP mode. Preconditions Make sure the chip select output enable is selected on the CS lines (PLIB_SQI_CSOutputEnableSelect). Parameters Parameters Description index Identifier for the device instance to be configured csNum Chip select number Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPChipSelectSet(MY_SQI_INSTANCE, SQI_CS_0); 5.6.23.5.3.5 PLIB_SQI_XIPControlWord1Get Function C uint32_t PLIB_SQI_XIPControlWord1Get( SQI_MODULE_ID index ); Description This routine returns the XIP mode control word 1. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t xipCon1 = PLIB_SQI_XIPControlWord1Set (MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2929 5.6.23.5.3.6 PLIB_SQI_XIPControlWord1Set Function C void PLIB_SQI_XIPControlWord1Set( SQI_MODULE_ID index, SQI_DUMMY_BYTES dummyBytes, SQI_ADDR_BYTES addressBytes, uint8_t readOpcode, SQI_LANE_MODE dataLaneMode, SQI_LANE_MODE dummyLaneMode, SQI_LANE_MODE modeCodeLaneMode, SQI_LANE_MODE addressLaneMode, SQI_LANE_MODE cmdLaneMode ); Description This routine sets XIP mode control word 1. This routine combines work of multiple PLIB APIs and can be used by the driver where complete XIP control word 1 is being modified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured dummyBytes Number of dummy bytes (0-7) addressBytes Number of address bytes (0-4) readOpcode Quad flash read opcode (ex: 0x0B) dataLaneMode Number of SQI data lanes used for sending data bytes dummyLaneMode Number of SQI data lanes used for sending dummy bytes modeCodeLaneMode Number of SQI data lanes used for sending mode code addressLaneMode Number of SQI data lanes used for sending address cmdLaneMode Number of SQI data lanes used for sending command Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord1Set (MY_SQI_INSTANCE, DUMMY_BYTES_2, ADDR_BYTES_3, 0x0B, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, SQI_LANE_QUAD, ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2930 5.6.23.5.3.7 PLIB_SQI_XIPControlWord2Get Function C uint32_t PLIB_SQI_XIPControlWord2Get( SQI_MODULE_ID index ); Description This routine returns the XIP mode control word 2. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t xipCon2 = PLIB_SQI_XIPControlWord2Set (MY_SQI_INSTANCE); 5.6.23.5.3.8 PLIB_SQI_XIPControlWord2Set Function C void PLIB_SQI_XIPControlWord2Set( SQI_MODULE_ID index, SQI_CS_NUM devSelect, SQI_MODE_BYTES modeBytes, uint8_t modeCode ); Description This routine sets XIP mode control word 2. This routine combines work of multiple PLIB APIs and can be used by the driver where complete XIP control word 2 is being modified. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured modeCode Mode code used for supported flash devices modeBytes Number of mode code bytes devSelect Chip select for XIP mode Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2931 Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPControlWord2Set (MY_SQI_INSTANCE, SQI_CS_0, MODE_BYTES_0, 0x0 ); 5.6.23.5.3.9 PLIB_SQI_XIPDummyBytesGet Function C SQI_DUMMY_BYTES PLIB_SQI_XIPDummyBytesGet( SQI_MODULE_ID index ); Description This routine returns the number of dummy bytes to be sent to the flash after the address bytes, i.e., before doing a fast read. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t dummyBytes = PLIB_SQI_XIPDummyBytesGet(MY_SQI_INSTANCE); 5.6.23.5.3.10 PLIB_SQI_XIPDummyBytesSet Function C void PLIB_SQI_XIPDummyBytesSet( SQI_MODULE_ID index, SQI_DUMMY_BYTES bytes ); Description This routine sets the number of dummy bytes to be sent to the flash after the address bytes, i.e., before doing a fast read. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2932 Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of dummy bytes Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPDummyBytesSet(MY_SQI_INSTANCE, DUMMY_BYTE_1); 5.6.23.5.3.11 PLIB_SQI_XIPLaneModeGet Function C SQI_LANE_MODE PLIB_SQI_XIPLaneModeGet( SQI_MODULE_ID index ); Description This routine returns the the number of SQI lanes ((single/dual/quad)) used in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Lane Mode (Single/Dual/Quad) that SQI Command uses. Remarks This routine can't be called when in XIP mode. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_LANE_MODE laneMode = PLIB_SQI_XIPCommandTypeGet(MY_SQI_INSTANCE); 5.6.23.5.3.12 PLIB_SQI_XIPLaneModeSet Function C void PLIB_SQI_XIPLaneModeSet( SQI_MODULE_ID index, SQI_LANE_MODE dataLanes, SQI_LANE_MODE dummyLanes, SQI_LANE_MODE modeLanes, SQI_LANE_MODE addrLanes, SQI_LANE_MODE cmdLanes ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2933 Description This routine selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured dataLanes Data lane mode (single/dual/quad) dummyLanes Dummy lane mode (single/dual/quad) modeLanes Mode lane mode (single/dual/quad) addrLanes Address lane mode (single/dual/quad) cmdLanes Command lane mode (single/dual/quad) Returns None. Remarks This routine can't be called when in XIP mode. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPLaneModeSet(MY_SQI_INSTANCE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE, SQI_QUAD_SINGLE ); 5.6.23.5.3.13 PLIB_SQI_XIPModeBytesGet Function C SQI_MODE_BYTES PLIB_SQI_XIPModeBytesGet( SQI_MODULE_ID index ); Description This routine returns the number of bytes for the mode code command in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Number of Bytes used for Mode Code Command. Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2934 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_MODE_BYTES modeCodeBytes = PLIB_SQI_XIPModeBytesGet(MY_SQI_INSTANCE); 5.6.23.5.3.14 PLIB_SQI_XIPModeBytesSet Function C void PLIB_SQI_XIPModeBytesSet( SQI_MODULE_ID index, SQI_MODE_BYTES bytes ); Description This routine sets the number of bytes for the mode code command in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured bytes Number of bytes of Mode code Returns None. Remarks Refer to serial device datasheet for the details on this command. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPModeBytesSet(MY_SQI_INSTANCE, MODE_BYTES_0); 5.6.23.5.3.15 PLIB_SQI_XIPModeCodeGet Function C uint8_t PLIB_SQI_XIPModeCodeGet( SQI_MODULE_ID index ); Description This routine returns the mode code command (opcode) in XIP mode for the devices that support it. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Mode Code Opcode. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2935 Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t modeCode = PLIB_SQI_XIPModeCodeGet(MY_SQI_INSTANCE); 5.6.23.5.3.16 PLIB_SQI_XIPModeCodeSet Function C void PLIB_SQI_XIPModeCodeSet( SQI_MODULE_ID index, uint8_t code ); Description This routine sets the mode code command in XIP mode for the supported flash devices. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured code Mode code (byte) Returns None. Remarks Some of the devices seems to support this command, refer to specific serial device data sheet for op-code and sequence details. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_XIPModeCodeSet(MY_SQI_INSTANCE, MY_MODE_CODE); 5.6.23.5.3.17 PLIB_SQI_XIPReadOpcodeGet Function C uint8_t PLIB_SQI_XIPReadOpcodeGet( SQI_MODULE_ID index ); Description This routine returns the read opcode used in XIP mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2936 Returns Read Opcode. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t readOpcode = PLIB_SQI_XIPReadOpcodeGet(MY_SQI_INSTANCE); 5.6.23.5.3.18 PLIB_SQI_XIPReadOpcodeSet Function C void PLIB_SQI_XIPReadOpcodeSet( SQI_MODULE_ID index, uint8_t opCode ); Description This routine sets the flash read opcode in XIP mode. Value of read opcode depends on the flash device attached. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured opCode Flash read opcode Returns None. Remarks Refer to the flash device datasheet for supported read opcodes. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_READ_OPCODE is the opcode dependant on // attached serial device. PLIB_SQI_XIPReadOpcodeSet(MY_SQI_INSTANCE, MY_READ_OPCODE); 5.6.23.5.4 PIO Mode Transfer Management Functions 5.6.23.5.4.1 PLIB_SQI_ByteCountGet Function C uint16_t PLIB_SQI_ByteCountGet( SQI_MODULE_ID index ); Description This routine returns the transmit/receive count, which is set by software and is actively contrtolled and maintained by hardware. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2937 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured count Transmit/Receive count Returns Transfer Count. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint16_t xferCount = PLIB_SQI_ByteCountGet(MY_SQI_INSTANCE); 5.6.23.5.4.2 PLIB_SQI_ByteCountSet Function C void PLIB_SQI_ByteCountSet( SQI_MODULE_ID index, uint16_t xferCount ); Description This routine sets the number of bytes to transmit or receive, which is set by software and is actively contrtolled and maintained by hardware. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured count Transmit/Receive count Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_XFER_COUNT is the transfer count. PLIB_SQI_ByteCountSet(MY_SQI_INSTANCE, MY_XFER_COUNT); 5.6.23.5.4.3 PLIB_SQI_ChipSelectDeassertDisable Function C void PLIB_SQI_ChipSelectDeassertDisable( SQI_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2938 ); Description This routine disables the chip select de-assert. Chip select stays asserted after transmission or reception of specified number of bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ChipSelectDeassertDisable(MY_SQI_INSTANCE); 5.6.23.5.4.4 PLIB_SQI_ChipSelectDeassertEnable Function C void PLIB_SQI_ChipSelectDeassertEnable( SQI_MODULE_ID index ); Description This routine enables chip select de-assert. Chip select is de-asserted after transmission or reception of the specified number of bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ChipSelectDeassertEnable(MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2939 5.6.23.5.4.5 PLIB_SQI_ChipSelectGet Function C SQI_CS_NUM PLIB_SQI_ChipSelectGet( SQI_MODULE_ID index ); Description This routine returns the chip select that is currently active. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Chip Select (2-bit) - Current chip select active (0/1). Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_CS_NUM csNum = PLIB_SQI_ChipSelectGet(MY_SQI_INSTANCE); 5.6.23.5.4.6 PLIB_SQI_ChipSelectSet Function C void PLIB_SQI_ChipSelectSet( SQI_MODULE_ID index, SQI_CS_NUM csNum ); Description This routine sets the chip select to be activated on the next transaction. Preconditions Make sure the chip select output enable is selected on the CS lines (PLIB_SQI_CSOutputEnableSelect). Parameters Parameters Description index Identifier for the device instance to be configured csNum Chip select number Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2940 // application developer and SQI_CS_NUM_0 is the enum element. PLIB_SQI_ChipSelectSet(MY_SQI_INSTANCE, SQI_CS_NUM_0); 5.6.23.5.4.7 PLIB_SQI_ConfigWordGet Function C uint32_t PLIB_SQI_ConfigWordGet( SQI_MODULE_ID index ); Description This routine returns the SQI configuration word. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t sqiCfg = PLIB_SQI_ConfigWordGet (MY_SQI_INSTANCE); 5.6.23.5.4.8 PLIB_SQI_ConfigWordSet Function C void PLIB_SQI_ConfigWordSet( SQI_MODULE_ID index, bool sqiEnable, SQI_CS_OEN csPins, SQI_DATA_OEN dataPins, bool reset, bool burstEn, bool hold, bool writeProtect, bool rxLatch, SQI_DATA_FORMAT lsbf, SQI_DATA_MODE dataMode, SQI_XFER_MODE xferMode ); Description This routine sets SQI Configuration Word. This API is cumulation of multiple APIs, in case driver plans to write the complete configuration word. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2941 Parameters Parameters Description index Identifier for the device instance to be configured sqiEnable Enables/Disables the SQI module csPins Chip Select Output Enable dataPins Data Output Enable reset Resets control, transmit, receive buffers and state machines burstEn Burst Enable (always set to '1') hold SQID2 to act as HOLD# signal in single and dual lane modes writeProtect SQID3 to act as WP# signal in single and dual lane modes rxLatch Activates receive latch in transmit mode lsbf Sets data endian mode to least significant bit first (LSBF) dataMode Sets data mode to mode 0/mode 1/serial flash mode xferMode Sets transfer mode to XIP/DMA/PIO mode Returns None. Remarks Chip select is not actually asserted, only enabled to be asserted. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_ConfigWordSet(MY_SQI_INSTANCE, 1, SQI_CS_OEN_0, SQI_DATA_OEN_QUAD, 0, 1, 0, 0, 0, SQI_DATA_FORMAT_LSBF, SQI_DATA_MODE_3, SQI_XFER_MODE_PIO ); 5.6.23.5.4.9 PLIB_SQI_ReceiveBufferIsUnderrun Function C bool PLIB_SQI_ReceiveBufferIsUnderrun( SQI_MODULE_ID index ); Description This routine returns the status of the receive buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2942 Returns True if Receive Buffer is Underrun, False if not. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool rxun = PLIB_SQI_ReceiveBufferIsUnderrun(MY_SQI_INSTANCE); 5.6.23.5.4.10 PLIB_SQI_RxBufferThresholdGet Function C uint8_t PLIB_SQI_RxBufferThresholdGet( SQI_MODULE_ID index ); Description This routine returns the receive command threshold that is used to monitor receives based on the receive buffer space availability. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Receive Buffer Threshold value. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufThres = PLIB_SQI_RxCommandThresholdGet(MY_SQI_INSTANCE); 5.6.23.5.4.11 PLIB_SQI_RxBufferThresholdIntGet Function C uint8_t PLIB_SQI_RxBufferThresholdIntGet( SQI_MODULE_ID index ); Description This routine returns the receive buffer threshold used to set an interrupt. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2943 Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive interrupt (buffer) threshold Returns Receive Buffer Threshold value (used to trigger an interrupt). Remarks This is a 5-bit fild and bits 7,6,5 are ignored in the char. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t rxBufIntThres = PLIB_SQI_RxBufferThresholdIntGet(MY_SQI_INSTANCE); 5.6.23.5.4.12 PLIB_SQI_RxBufferThresholdIntSet Function C void PLIB_SQI_RxBufferThresholdIntSet( SQI_MODULE_ID index, uint8_t threshold ); Description This routine sets the receive buffer threshold used to trigger an interrupt. Sets an interrpt condition when receive buffer count is larger than or equal to the receive interrupt threshold bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive buffer threshold for interrupt Returns None. Remarks This is a 5-bit fild and bits 7,6,5 are ignored in the char. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_RX_INT_THRESHOLD is the threshold value. PLIB_SQI_RxBufferThresholdIntSet(MY_SQI_INSTANCE, MY_RX_INT_THRESHOLD); 5.6.23.5.4.13 PLIB_SQI_RxBufferThresholdSet Function C void PLIB_SQI_RxBufferThresholdSet( SQI_MODULE_ID index, uint8_t threshold ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2944 Description This routine sets the receive command threshold that is used to monitor receives based on the receive buffer space availability. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured threshold Receive command (buffer) threshold Returns None. Remarks Valid threshold values are 0-31. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_RECEIVE_THRESHOLD is the receive threshold value. PLIB_SQI_RxCommandThresholdSet(MY_SQI_INSTANCE, MY_RECEIVE_THRESHOLD); 5.6.23.5.4.14 PLIB_SQI_TransferDirectionGet Function C SQI_XFER_CMD PLIB_SQI_TransferDirectionGet( SQI_MODULE_ID index ); Description This routine returns the transfer command that is active currently. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Transfer Command (Idle/Receive/Transmit). Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. SQI_XFER_CMD xferDirection = PLIB_SQI_TransferDirectionGet(MY_SQI_INSTANCE); 5.6.23.5.4.15 PLIB_SQI_TransferDirectionSet Function C void PLIB_SQI_TransferDirectionSet( SQI_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2945 SQI_XFER_CMD command ); Description This routine sets the transfer command to Idle/Transmit/Receive. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured command Transfer command Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and SQI_CMD_TRANSMIT is an enum element. PLIB_SQI_TransferDirectionSet(MY_SQI_INSTANCE, SQI_CMD_TRANSMIT); 5.6.23.5.4.16 PLIB_SQI_TransmitBufferFreeSpaceGet Function C uint8_t PLIB_SQI_TransmitBufferFreeSpaceGet( SQI_MODULE_ID index ); Description This routine returns the number of transmit buffer bytes available. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Amont of transmit buffer space free in bytes. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t txBufFreeSpace = PLIB_SQI_TransmitBufferFreeSpaceGet(MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2946 5.6.23.5.4.17 PLIB_SQI_TransmitBufferHasOverflowed Function C bool PLIB_SQI_TransmitBufferHasOverflowed( SQI_MODULE_ID index ); Description This routine returns the current state of the transmit buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if Transmit Buffer has Overflowed, false if not. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool txOv = PLIB_SQI_TransmitBufferHasOverflowed(MY_SQI_INSTANCE); 5.6.23.5.4.18 PLIB_SQI_TxBufferThresholdGet Function C uint8_t PLIB_SQI_TxBufferThresholdGet( SQI_MODULE_ID index ); Description This routine returns the transmit command threshold value that is used to monitor transmits based on the transmit buffer space availability. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Transmit buffer threshold value. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2947 uint8_t txThreshold = PLIB_SQI_TxBufferThresholdGet(MY_SQI_INSTANCE); 5.6.23.5.4.19 PLIB_SQI_TxBufferThresholdIntGet Function C uint8_t PLIB_SQI_TxBufferThresholdIntGet( SQI_MODULE_ID index ); Description This routine returns the transmit buffer threshold used to set an interrupt. When enabled, interrupt is triggered when transmit buffer has more space than the transmit interrupt threshold bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Transmit buffer threshold for interrupt. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t txBufIntThres = PLIB_SQI_TxBufferThresholdIntGet(MY_SQI_INSTANCE); 5.6.23.5.4.20 PLIB_SQI_TxBufferThresholdIntSet Function C void PLIB_SQI_TxBufferThresholdIntSet( SQI_MODULE_ID index, uint8_t threshold ); Description This routine sets the transmit buffer threshold used for an interrupt. When enabled, interrupt is triggered when transmit buffer has more space than the transmit interrupt threshold bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured threshold Transmit interrupt (buffer) threshold Returns None. Remarks This is a 5-bit fild and bits 7,6,5 are ignored in the char. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2948 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TX_INT_THRESHOLD is the threshold value. PLIB_SQI_TxBufferThresholdIntSet(MY_SQI_INSTANCE, MY_TX_INT_THRESHOLD); 5.6.23.5.4.21 PLIB_SQI_TxBufferThresholdSet Function C void PLIB_SQI_TxBufferThresholdSet( SQI_MODULE_ID index, uint8_t threshold ); Description This routine sets the transmit command threshold, which is used to control transmits based on the transmit buffer space availability. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured threshold Transmit command (buffer) threshold Returns None. Remarks Valid threshold values are 0-31. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and MY_TRANSMIT_THRESHOLD is the threshold value. PLIB_SQI_TxBufferThresholdSet(MY_SQI_INSTANCE, MY_TRANSMIT_THRESHOLD); 5.6.23.5.5 Interrupt Control and Status Management Functions 5.6.23.5.5.1 PLIB_SQI_DataLineStatus Function C bool PLIB_SQI_DataLineStatus( SQI_MODULE_ID index, bool dataPin ); Description This routine returns the logical status of the data lines(0/1). Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2949 Parameters Parameters Description index Identifier for the device instance to be configured dataPin Data pin for which status will be returned (0/1/2/3) Returns SQIDx Status (High/Low). Remarks Parsing values other than 0/1/2/3 returns SQID0 pin status. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool sqiDataLineStatus = PLIB_SQI_DataLineStatus(MY_SQI_INSTANCE, 3); 5.6.23.5.5.2 PLIB_SQI_InterruptDisable Function C void PLIB_SQI_InterruptDisable( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); Description This routine disables the interrupt source passed into the function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be disabled Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer and TXFULL is an enum element. PLIB_SQI_InterruptDisable(MY_SQI_INSTANCE, SQI_TXFULL); 5.6.23.5.5.3 PLIB_SQI_InterruptEnable Function C void PLIB_SQI_InterruptEnable( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2950 Description This routine enables the interrupt source passed into the function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be enabled Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptEnable(MY_SQI_INSTANCE, SQI_TXFULL); 5.6.23.5.5.4 PLIB_SQI_InterruptFlagGet Function C bool PLIB_SQI_InterruptFlagGet( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); Description This routine returns the SQI interrupt source flag status (set/cleared). Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt flag of interest Returns Interrupt status. Remarks None. Example if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_INT_ANY) ) if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_TXFULL) ) { ... } if ( PLIB_SQI_InterruptFlagGet(MY_SQI_INSTANCE,SQI_RXFULL) ) { 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2951 ... } . . . } 5.6.23.5.5.5 PLIB_SQI_InterruptIsEnabled Function C bool PLIB_SQI_InterruptIsEnabled( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); Description This routine returns the interrupt state. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt under check Returns True if Interrupt is Enabled, else false. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (PLIB_SQI_InterruptIsEnabled(MY_SQI_INSTANCE, SQI_TXFULL)) { .. } 5.6.23.5.5.6 PLIB_SQI_InterruptSignalDisable Function C void PLIB_SQI_InterruptSignalDisable( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); Description This routine disables the interrupt signals source passed into the function, thus prohibitting it from reaching to the external interrupt controller. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2952 Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be disabled Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptSignalDisable(MY_SQI_INSTANCE, SQI_TXFULL); 5.6.23.5.5.7 PLIB_SQI_InterruptSignalEnable Function C void PLIB_SQI_InterruptSignalEnable( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); Description This routine enables the interrupt signal source passed into the function, thus letting it go out to the external interrupt controller. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt to be enabled Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_InterruptSignalEnable(MY_SQI_INSTANCE, SQI_TXFULL); 5.6.23.5.5.8 PLIB_SQI_InterruptSignalIsEnabled Function C bool PLIB_SQI_InterruptSignalIsEnabled( SQI_MODULE_ID index, SQI_INTERRUPTS interruptFlag ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2953 Description This routine returns the interrupt signal state. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptFlag Interrupt signal under check Returns Boolean flag - Interrupt state true - Interrupt signal is enabled false - Interrupt signal is disabled Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (PLIB_SQI_InterruptSignalIsEnabled(MY_SQI_INSTANCE, SQI_TXFULL)) { .. } 5.6.23.5.6 DMA Buffer Address Management Functions 5.6.23.5.6.1 PLIB_SQI_DMABDBaseAddressGet Function C void* PLIB_SQI_DMABDBaseAddressGet( SQI_MODULE_ID index ); Description This routine returns the address of the base DMA buffer descriptor. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Base Buffer Descriptor Address. Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. void *baseBDAddress; 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2954 If (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) { baseBDAddress = PLIB_SQI_DMABDBaseAddressGet(MY_SQI_INSTANCE); } 5.6.23.5.6.2 PLIB_SQI_DMABDBaseAddressSet Function C void PLIB_SQI_DMABDBaseAddressSet( SQI_MODULE_ID index, void * baseBDAddress ); Description This routine writes the address of the base (first/only) buffer descriptor into the buffer descriptor base address register. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured baseBDAddress Base buffer descriptor address Returns None. Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (!PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) PLIB_SQI_DMABDBaseAddressSet(MY_SQI_INSTANCE, (void *) (&MY_BD_STRUCT)); 5.6.23.5.6.3 PLIB_SQI_DMABDCurrentAddressGet Function C void* PLIB_SQI_DMABDCurrentAddressGet( SQI_MODULE_ID index ); Description This routine returns the address of the DMA buffer descriptor that is currently in progress. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Current Buffer Descriptor Address. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2955 Remarks Check to make sure if DMA Buffer Descriptor fetch is in progress. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint32_t currentBDAddress; If (PLIB_SQI_DMAIsActive(MY_SQI_INSTANCE)) { void* currentBDAddress = PLIB_SQI_DMABDCurrentAddressGet(MY_SQI_INSTANCE); } 5.6.23.5.7 DMA Buffer Descriptor Management Functions 5.6.23.5.7.1 PLIB_SQI_DMABDControlWordGet Function C uint16_t PLIB_SQI_DMABDControlWordGet( SQI_MODULE_ID index ); Description This routine returns current buffer descriptor control word information excluding buffer length. This information is returned in transmit and receive status functions. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Control Word - DMA Buffer Desciptor Control Word Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint16_t dmabdconword; dmabdconword = PLIB_SQI_DMABDControlWordGet(MY_SQI_INSTANCE); switch (dmabdconword) { case BD_ENABLED: ...; case BD_DISABLED: ...; . . . } 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2956 5.6.23.5.7.2 PLIB_SQI_DMABDReceiveBufferCountGet Function C uint8_t PLIB_SQI_DMABDReceiveBufferCountGet( SQI_MODULE_ID index ); Description This routine returns the current receive buffer space in bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Receive buffer space in bytes. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdRxBufCount = PLIB_SQI_DMABDReceiveBufferCountGet(MY_SQI_INSTANCE); 5.6.23.5.7.3 PLIB_SQI_DMABDReceiveBufferLengthGet Function C uint8_t PLIB_SQI_DMABDReceiveBufferLengthGet( SQI_MODULE_ID index ); Description This routine returns the current receive length in bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Receive buffer space in bytes. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdRxBufLength = PLIB_SQI_DMABDReceiveBufferLengthGet(MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2957 5.6.23.5.7.4 PLIB_SQI_DMABDReceiveStateGet Function C SQI_BD_STATE PLIB_SQI_DMABDReceiveStateGet( SQI_MODULE_ID index ); Description This routine returns the current state of the buffer descriptor in progress. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Status - DMA Buffer Descriptor State Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdrxState = PLIB_SQI_DMABDReceiveStateGet(MY_SQI_INSTANCE); switch (bdRxState) { case BD_IDLE: ...; case BD_STATE_FETCH_REQ_PENDING: ...; . . . } 5.6.23.5.7.5 PLIB_SQI_DMABDTransmitBufferCountGet Function C uint8_t PLIB_SQI_DMABDTransmitBufferCountGet( SQI_MODULE_ID index ); Description This routine returns the current transmit buffer space in bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Transmit buffer space in bytes. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2958 Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdTxBufCount = PLIB_SQI_DMABDTransmitBufferCountGet(MY_SQI_INSTANCE); 5.6.23.5.7.6 PLIB_SQI_DMABDTransmitBufferLengthGet Function C uint8_t PLIB_SQI_DMABDTransmitBufferLengthGet( SQI_MODULE_ID index ); Description This routine returns the current transmit length in bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Transmit buffer space in bytes. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdTxBufLength = PLIB_SQI_DMABDTransmitBufferLengthGet(MY_SQI_INSTANCE); 5.6.23.5.7.7 PLIB_SQI_DMABDTransmitStateGet Function C SQI_BD_STATE PLIB_SQI_DMABDTransmitStateGet( SQI_MODULE_ID index ); Description This routine returns the current state of the buffer descriptor in progress. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Status - DMA Buffer Descriptor State 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2959 Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdTxState = PLIB_SQI_DMABDTransmitStateGet(MY_SQI_INSTANCE); switch (bdTxState) { case BD_IDLE: ...; case BD_FETCH_REQ_PENDING: ...; . . . } 5.6.23.5.8 DMA Control and Status Management Functions 5.6.23.5.8.1 PLIB_SQI_DMABDFetchStart Function C void PLIB_SQI_DMABDFetchStart( SQI_MODULE_ID index ); Description This routine starts the DMA buffer descriptor fetch process. Preconditions Make sure the buffer descreptors are setup and the buffer descriptor base address register is pointing to the first/only buffer descriptor. Also ensure any previous BD processing is fixed. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDFetchStart(MY_SQI_INSTANCE); 5.6.23.5.8.2 PLIB_SQI_DMABDIsBusy Function C bool PLIB_SQI_DMABDIsBusy( SQI_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2960 Description This routine returns true if DMA buffer descriptor process is busy, if not returns false. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if DMA Buffer Desciptor is Busy. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool bdBusy = PLIB_SQI_DMABDIsBusy(MY_SQI_INSTANCE) 5.6.23.5.8.3 PLIB_SQI_DMABDPollCounterSet Function C void PLIB_SQI_DMABDPollCounterSet( SQI_MODULE_ID index, uint16_t pollCount ); Description This routine sets the poll counter value that indicates the number of cycles the DMA would wait before fetching the next descriptor word, if the current descriptor fetched was disabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pollControl Polling value Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. if (PLIB_SQI_DMABDPollIsEnabled(MY_SQI_INSTANCE) { PLIB_SQI_DMABDPollCounterSet(MY_SQI_INSTANCE, MY_POLL_VALUE); } 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2961 5.6.23.5.8.4 PLIB_SQI_DMABDPollDisable Function C void PLIB_SQI_DMABDPollDisable( SQI_MODULE_ID index ); Description This routine disables the buffer descriptor polling. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDPollDisable(MY_SQI_INSTANCE); 5.6.23.5.8.5 PLIB_SQI_DMABDPollEnable Function C void PLIB_SQI_DMABDPollEnable( SQI_MODULE_ID index ); Description This routine enables the buffer descriptor polling and works in tandum with poll control register. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Enable this control bit only when you are planning to have dead descriptors in the linked list. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMABDPollEnable(MY_SQI_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2962 5.6.23.5.8.6 PLIB_SQI_DMABDPollIsEnabled Function C bool PLIB_SQI_DMABDPollIsEnabled( SQI_MODULE_ID index ); Description This routine returns true/false if DMA buffer descriptor poll is enabled/disabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if DMA Poll Control is Enabled, else it's false. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. If (PLIB_SQI_DMABDPollIsEnabled(MY_SQI_INSTANCE)) { PLIB_SQI_PollControlSet(MY_SQI_INSTANCE, MY_POLL_CONTROL_VALUE); } 5.6.23.5.8.7 PLIB_SQI_DMABDStateGet Function C SQI_BD_STATE PLIB_SQI_DMABDStateGet( SQI_MODULE_ID index ); Description This routine returns the current state of the buffer descriptor in progress. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns Status - DMA Buffer Descriptor State Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2963 Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. uint8_t bdState = PLIB_SQI_DMABDStateGet(MY_SQI_INSTANCE); switch (bdState) { case BD_IDLE: ...; case BD_FETCH_REQ_PENDING: ...; . . . } 5.6.23.5.8.8 PLIB_SQI_DMADisable Function C void PLIB_SQI_DMADisable( SQI_MODULE_ID index ); Description This routine disables the built-in DMA logic for data transfer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMADisable(MY_SQI_INSTANCE); 5.6.23.5.8.9 PLIB_SQI_DMAEnable Function C void PLIB_SQI_DMAEnable( SQI_MODULE_ID index ); Description This routine enables the built-in DMA logic for data transfer. Preconditions DMA buffer descriptors need to be setup before enabling the DMA. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2964 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. PLIB_SQI_DMAEnable(MY_SQI_INSTANCE); 5.6.23.5.8.10 PLIB_SQI_DMAHasStarted Function C bool PLIB_SQI_DMAHasStarted( SQI_MODULE_ID index ); Description This routine returns true if DMA process started and false if DMA process has not started. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns True if DMA process has started, false if not. Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. bool dmaStarted = PLIB_SQI_DMAHasStarted (MY_SQI_INSTANCE) 5.6.23.5.8.11 PLIB_SQI_DMAIsEnabled Function C bool PLIB_SQI_DMAIsEnabled( SQI_MODULE_ID index ); Description This routine returns true/false if DMA is enabled/disabled. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2965 Parameters Parameters Description index Identifier for the device instance to be configured Returns Boolean Flag - DMA Enable Status true - DMA is enabled false - DMA is disabled Remarks None. Example // Where MY_SQI_INSTANCE, is the SQI instance selected for use by the // application developer. If (PLIB_SQI_DMAIsEnabled(MY_SQI_INSTANCE)) { ... } 5.6.23.5.9 Data Types and Constants 5.6.23.5.9.1 SQI_ADDR_BYTES Enumeration C typedef enum { ADDR_BYTES_4, ADDR_BYTES_3, ADDR_BYTES_2, ADDR_BYTES_1, ADDR_BYTES_0 } SQI_ADDR_BYTES; Description SQI Number of Address Bytes This macro defines the list of SQI Address Bytes Members Members Description ADDR_BYTES_4 SQI is set to Transmit 4 Address Bytes ADDR_BYTES_3 SQI is set to Transmit 3 Address Bytes ADDR_BYTES_2 SQI is set to Transmit 2 Address Bytes ADDR_BYTES_1 SQI is set to Transmit 1 Address Bytes ADDR_BYTES_0 SQI is set to Transmit No Address Bytes 5.6.23.5.9.2 SQI_BD_CTRL_WORD Enumeration C typedef enum { BD_ENABLE, BD_DISABLE, CS_1_ACTIVE, CS_0_ACTIVE, FLASH_SC_ENABLE, FLASH_SC_DISABLE, SET_LSBF, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2966 SET_MSBF, DMA_LANE_QUAD, DMA_LANE_DUAL, DMA_LANE_SINGLE, DMA_IN_TRANSMIT, DMA_IN_RECEIVE, LAST_BD, NOT_LAST_BD, LAST_PKT, NOT_LAST_PKT, PKT_INT_ENABLE, PKT_INT_DISABLE, BD_DONE_INT_ENABLE, BD_DONE_INT_DISABLE, BD_BUF_LENGTH } SQI_BD_CTRL_WORD; Description SQI Buffer Descriptor Cotrol Words This macro defines the list of SQI Buffer Descriptor Control Word Members Members Description BD_ENABLE Current Buffer Descriptor is Enabled BD_DISABLE Current Buffer Descriptor is Disabled CS_1_ACTIVE Chip Select 1 is Active CS_0_ACTIVE Chip Select 0 is Active FLASH_SC_ENABLE Automatic Status Check Enabled FLASH_SC_DISABLE Automatic Status Check Disabled SET_LSBF Least Significant Bit First SET_MSBF Most Significant Bit First DMA_LANE_QUAD DMA writes/reads in Quad Lane Mode DMA_LANE_DUAL DMA writes/reads in Dual Lane Mode DMA_LANE_SINGLE DMA writes/reads in Single Lane Mode DMA_IN_TRANSMIT DMA is Transmitting DMA_IN_RECEIVE DMA is Receieving LAST_BD Indicates Last Buffer Descriptor in the List NOT_LAST_BD Indicates Non Last Buffer Descriptor in the List LAST_PKT Indicates Last Packet of the Data Chunk NOT_LAST_PKT Indicates Non Last Packet of the Data Chunk PKT_INT_ENABLE Indicates Packet Interrupt is Enabled PKT_INT_DISABLE Indicates Packet Interrupt is Disabled BD_DONE_INT_ENABLE Indicates Buffer Descriptor Done Interrupt is Enabled BD_DONE_INT_DISABLE Indicates Buffer Descriptor Done Interrupt is Disabled BD_BUF_LENGTH Indicates Biuffer Length 5.6.23.5.9.3 SQI_BD_STATE Enumeration C typedef enum { BD_STATE_DISABLED, BD_STATE_DONE, BD_STATE_PROCESSING_DATA, 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2967 BD_STATE_BEING_FETCHED, BD_STATE_FETCH_REQ_PENDING, BD_STATE_IDLE } SQI_BD_STATE; Description SQI Buffer Descriptor (BD) State This macro defines the list of SQI Buffer Descriptor states Members Members Description BD_STATE_DISABLED Fetched Buffer Descriptor is Disabled BD_STATE_DONE Fetched Buffer Descriptor Processed BD_STATE_PROCESSING_DATA Fetched Buffer Descriptor is in Data transfer phase BD_STATE_BEING_FETCHED In the process of Fetching the Buffer Descriptor BD_STATE_FETCH_REQ_PENDING Buffer Descriptor Fetch Request Pending BD_STATE_IDLE Buffer Desciptor process is idle 5.6.23.5.9.4 SQI_CLK_DIV Enumeration C typedef enum { CLK_DIV_256, CLK_DIV_128, CLK_DIV_64, CLK_DIV_32, CLK_DIV_16, CLK_DIV_8, CLK_DIV_4, CLK_DIV_2, CLK_DIV_1 } SQI_CLK_DIV; Description SQI Clock Divider This macro defines the list of SQI Clock Divider Values Members Members Description CLK_DIV_256 SQI Clock is divided by 256 CLK_DIV_128 SQI Clock is divided by 128 CLK_DIV_64 SQI Clock is divided by 64 CLK_DIV_32 SQI Clock is divided by 32 CLK_DIV_16 SQI Clock is divided by 16 CLK_DIV_8 SQI Clock is divided by 8 CLK_DIV_4 SQI Clock is divided by 4 CLK_DIV_2 SQI Clock is divided by 2 CLK_DIV_1 SQI Clock is not divided 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2968 5.6.23.5.9.5 SQI_CS_NUM Enumeration C typedef enum { SQI_CS_1, SQI_CS_0 } SQI_CS_NUM; Description SQI Device Select or Chip Select This macro defines the list of SQI Chip Selects Members Members Description SQI_CS_1 SQI Chip Select 1 SQI_CS_0 SQI Chip Select 0 5.6.23.5.9.6 SQI_CS_OEN Enumeration C typedef enum { SQI_CS_OEN_BOTH, SQI_CS_OEN_1, SQI_CS_OEN_0, SQI_CS_OEN_NONE } SQI_CS_OEN; Description SQI Chip Select Output Enable This macro defines the list of SQI Chip Select Output Enables Members Members Description SQI_CS_OEN_BOTH SQI chip select 0 and 1 are enabled SQI_CS_OEN_1 SQI chip select 1 is enabled but chip select 0 is disabled SQI_CS_OEN_0 SQI chip select 0 is enabled but chip select 1 is disabled SQI_CS_OEN_NONE SQI chip select 0 and 1 are disabled 5.6.23.5.9.7 SQI_DATA_FORMAT Enumeration C typedef enum { SQI_DATA_FORMAT_LSBF, SQI_DATA_FORMAT_MSBF } SQI_DATA_FORMAT; Description SQI Data Mode This macro defines the Data Formats (LSBF/MSBF) 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2969 Members Members Description SQI_DATA_FORMAT_LSBF SQI Data is Least Significant Bit First Formatted SQI_DATA_FORMAT_MSBF SQI Data is Most Significant Bit First Formatted 5.6.23.5.9.8 SQI_DATA_MODE Enumeration C typedef enum { SQI_DATA_MODE_SF, SQI_DATA_MODE_3, SQI_DATA_MODE_0 } SQI_DATA_MODE; Description SQI Data Mode This macro defines the list of SQI Data Modes Members Members Description SQI_DATA_MODE_SF SQI is in Serial Flash Mode SQI_DATA_MODE_3 SQI is in SPI mode 3 SQI_DATA_MODE_0 SQI is in SPI mode 0 5.6.23.5.9.9 SQI_DATA_OEN Enumeration C typedef enum { SQI_DATA_OEN_QUAD, SQI_DATA_OEN_DUAL, SQI_DATA_OEN_SINGLE } SQI_DATA_OEN; Description SQI Data Output Enable This macro defines the list of SQI Data Output Enables Members Members Description SQI_DATA_OEN_QUAD SQI data outputs 3 to 0 are enabled (quad lane mode) SQI_DATA_OEN_DUAL SQI data outputs 1 and 0 are enabled (dual lane mode) SQI_DATA_OEN_SINGLE SQI data output 0 is enabled (single lane mode) 5.6.23.5.9.10 SQI_DATA_TYPE Type C typedef uint32_t SQI_DATA_TYPE; Description SQI Data Type definition This data type defines the SQI Data size 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2970 Remarks None 5.6.23.5.9.11 SQI_DUMMY_BYTES Enumeration C typedef enum { DUMMY_BYTES_7, DUMMY_BYTES_6, DUMMY_BYTES_5, DUMMY_BYTES_4, DUMMY_BYTES_3, DUMMY_BYTES_2, DUMMY_BYTE_1, DUMMY_BYTES_0 } SQI_DUMMY_BYTES; Description SQI Number of Dummy Bytes This macro defines the list of SQI Dummy Bytes after Address Bytes Members Members Description DUMMY_BYTES_7 SQI is set to Transmit 7 Dummy Bytes DUMMY_BYTES_6 SQI is set to Transmit 6 Dummy Bytes DUMMY_BYTES_5 SQI is set to Transmit 5 Dummy Bytes DUMMY_BYTES_4 SQI is set to Transmit 4 Dummy Bytes DUMMY_BYTES_3 SQI is set to Transmit 3 Dummy Bytes DUMMY_BYTES_2 SQI is set to Transmit 2 Dummy Bytes DUMMY_BYTE_1 SQI is set to Transmit 1 Dummy Bytes DUMMY_BYTES_0 SQI is set to Transmit No Dummy Bytes 5.6.23.5.9.12 SQI_INTERRUPTS Enumeration C typedef enum { SQI_PKTCOMP, SQI_BDDONE, SQI_CONTHR, SQI_CONEMPTY, SQI_CONFULL, SQI_RXTHR, SQI_RXEMPTY, SQI_RXFULL, SQI_TXTHR, SQI_TXEMPTY, SQI_TXFULL, SQI_ALL_INT } SQI_INTERRUPTS; Description SQI Interrupt List This macro defines the list of SQI Interrupts 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2971 Members Members Description SQI_PKTCOMP SQI Packet Complete Interrupt (used in DMA mode) SQI_BDDONE SQI Buffer Descriptor Done Interrupt (used in DMA mode) SQI_CONTHR SQI Control Buffer Threshold Interrupt SQI_CONEMPTY SQI Control Buffer Empty Interrupt SQI_CONFULL SQI Control Buffer Full Interrupt SQI_RXTHR SQI Receive Buffer Threshold Interrupt SQI_RXEMPTY SQI Receive Buffer Empty Interrupt SQI_RXFULL SQI Receive Buffer Full Interrupt SQI_TXTHR SQI Transmit Buffer Threshold Interrupt SQI_TXEMPTY SQI Transmit Buffer Empty Interrupt SQI_TXFULL SQI Transmit Buffer Full Interrupt SQI_ALL_INT All or any of the above interrupts 5.6.23.5.9.13 SQI_LANE_MODE Enumeration C typedef enum { SQI_LANE_QUAD, SQI_LANE_DUAL, SQI_LANE_SINGLE } SQI_LANE_MODE; Description SQI Lane Mode This macro defines the list of SQI Lane Modes Members Members Description SQI_LANE_QUAD SQI is set into Quad Lane Mode SQI_LANE_DUAL SQI is set into Dual Lane Mode SQI_LANE_SINGLE SQI is set into Single Lane Mode 5.6.23.5.9.14 SQI_MODE_BYTES Enumeration C typedef enum { MODE_BYTES_3, MODE_BYTES_2, MODE_BYTES_1, MODE_BYTES_0 } SQI_MODE_BYTES; Description SQI Number of Mode Bytes This macro defines the list of SQI Mode Bytes allocated for Mode Code 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2972 Members Members Description MODE_BYTES_3 SQI is set to Transmit 3 Mode Bytes MODE_BYTES_2 SQI is set to Transmit 2 Mode Bytes MODE_BYTES_1 SQI is set to Transmit 1 Mode Bytes MODE_BYTES_0 SQI is set to Transmit No Mode Bytes 5.6.23.5.9.15 SQI_MODULE_ID Enumeration C typedef enum { SQI_ID_1, SQI_NUMBER_OF_MODULES } SQI_MODULE_ID; Description SQI Module ID This enumeration identifies the SQI modules which are available on the microcontroller. This is the super set of all the possible instances that might be available on the Microchip microcontrollers. Members Members Description SQI_ID_1 SQI Module 1 ID SQI_NUMBER_OF_MODULES Number of available SQI modules Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.23.5.9.16 SQI_XFER_CMD Enumeration C typedef enum { SQI_CMD_RECEIVE, SQI_CMD_TRANSMIT, SQI_CMD_IDLE } SQI_XFER_CMD; Description SQI Transfer Command This macro defines the list of SQI Transfer Commands Members Members Description SQI_CMD_RECEIVE SQI issues a Receive Command SQI_CMD_TRANSMIT SQI issues a Transmit Command SQI_CMD_IDLE SQI is Idle 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2973 5.6.23.5.9.17 SQI_XFER_MODE Enumeration C typedef enum { SQI_XFER_MODE_XIP, SQI_XFER_MODE_DMA, SQI_XFER_MODE_PIO } SQI_XFER_MODE; Description SQI Transfer Mode This macro defines the list of SQI Transfer Modes Members Members Description SQI_XFER_MODE_XIP SQI is in XIP mode SQI_XFER_MODE_DMA SQI is in DMA mode SQI_XFER_MODE_PIO SQI is in PIO mode 5.6.23.5.10 Feature Existence Functions 5.6.23.5.10.1 PLIB_SQI_ExistsBDBaseAddress Function C bool PLIB_SQI_ExistsBDBaseAddress( SQI_MODULE_ID index ); Description This function identifies whether the BDBaseAddress feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDBaseAddressSet • PLIB_SQI_DMABDBaseAddressGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDBaseAddress feature is supported on the device • false - The BDBaseAddress feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2974 5.6.23.5.10.2 PLIB_SQI_ExistsBDControlWord Function C bool PLIB_SQI_ExistsBDControlWord( SQI_MODULE_ID index ); Description This function identifies whether the BDControlWord feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDControlWordGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDControlWord feature is supported on the device • false - The BDControlWord feature is not supported on the device Remarks None. 5.6.23.5.10.3 PLIB_SQI_ExistsBDCurrentAddress Function C bool PLIB_SQI_ExistsBDCurrentAddress( SQI_MODULE_ID index ); Description This function identifies whether the BDCurrentAddress feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDCurrentAddressGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDCurrentAddress feature is supported on the device • false - The BDCurrentAddress feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2975 5.6.23.5.10.4 PLIB_SQI_ExistsBDPollCount Function C bool PLIB_SQI_ExistsBDPollCount( SQI_MODULE_ID index ); Description This function identifies whether the BDPollCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDPollCounterSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDPollCount feature is supported on the device • false - The BDPollCount feature is not supported on the device Remarks None. 5.6.23.5.10.5 PLIB_SQI_ExistsBDPollingEnable Function C bool PLIB_SQI_ExistsBDPollingEnable( SQI_MODULE_ID index ); Description This function identifies whether the BDPollingEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDPollEnable • PLIB_SQI_DMABDPollDisable • PLIB_SQI_DMABDPollIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDPollingEnable feature is supported on the device • false - The BDPollingEnable feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2976 Remarks None. 5.6.23.5.10.6 PLIB_SQI_ExistsBDProcessState Function C bool PLIB_SQI_ExistsBDProcessState( SQI_MODULE_ID index ); Description This function identifies whether the BDProcessState feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDProcessState feature is supported on the device • false - The BDProcessState feature is not supported on the device Remarks None. 5.6.23.5.10.7 PLIB_SQI_ExistsBDRxBufCount Function C bool PLIB_SQI_ExistsBDRxBufCount( SQI_MODULE_ID index ); Description This function identifies whether the BDRxBufCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDReceiveBufferCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDRxBufCount feature is supported on the device • false - The BDRxBufCount feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2977 Remarks None. 5.6.23.5.10.8 PLIB_SQI_ExistsBDRxLength Function C bool PLIB_SQI_ExistsBDRxLength( SQI_MODULE_ID index ); Description This function identifies whether the BDRxLength feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDReceiveBufferLengthGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDRxLength feature is supported on the device • false - The BDRxLength feature is not supported on the device Remarks None. 5.6.23.5.10.9 PLIB_SQI_ExistsBDRxState Function C bool PLIB_SQI_ExistsBDRxState( SQI_MODULE_ID index ); Description This function identifies whether the BDRxState feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDReceiveStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDRxState feature is supported on the device • false - The BDRxState feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2978 Remarks None. 5.6.23.5.10.10 PLIB_SQI_ExistsBDTxBufCount Function C bool PLIB_SQI_ExistsBDTxBufCount( SQI_MODULE_ID index ); Description This function identifies whether the BDTxBufCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDTransmitBufferCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDTxBufCount feature is supported on the device • false - The BDTxBufCount feature is not supported on the device Remarks None. 5.6.23.5.10.11 PLIB_SQI_ExistsBDTxLength Function C bool PLIB_SQI_ExistsBDTxLength( SQI_MODULE_ID index ); Description This function identifies whether the BDTxLength feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDTransmitBufferLengthGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDTxLength feature is supported on the device • false - The BDTxLength feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2979 Remarks None. 5.6.23.5.10.12 PLIB_SQI_ExistsBDTxState Function C bool PLIB_SQI_ExistsBDTxState( SQI_MODULE_ID index ); Description This function identifies whether the BDTxState feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDTransmitStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDTxState feature is supported on the device • false - The BDTxState feature is not supported on the device Remarks None. 5.6.23.5.10.13 PLIB_SQI_ExistsBurstControl Function C bool PLIB_SQI_ExistsBurstControl( SQI_MODULE_ID index ); Description This function identifies whether the BurstControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_BurstEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BurstControl feature is supported on the device • false - The BurstControl feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2980 Remarks None. 5.6.23.5.10.14 PLIB_SQI_ExistsChipSelect Function C bool PLIB_SQI_ExistsChipSelect( SQI_MODULE_ID index ); Description This function identifies whether the ChipSelect feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ChipSelectSet • PLIB_SQI_ChipSelectGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ChipSelect feature is supported on the device • false - The ChipSelect feature is not supported on the device Remarks None. 5.6.23.5.10.15 PLIB_SQI_ExistsClockControl Function C bool PLIB_SQI_ExistsClockControl( SQI_MODULE_ID index ); Description This function identifies whether the ClockControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ClockEnable • PLIB_SQI_ClockDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2981 Returns • true - The ClockControl feature is supported on the device • false - The ClockControl feature is not supported on the device Remarks None. 5.6.23.5.10.16 PLIB_SQI_ExistsClockDivider Function C bool PLIB_SQI_ExistsClockDivider( SQI_MODULE_ID index ); Description This function identifies whether the ClockDivider feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ClockDividerSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockDivider feature is supported on the device • false - The ClockDivider feature is not supported on the device Remarks None. 5.6.23.5.10.17 PLIB_SQI_ExistsClockReady Function C bool PLIB_SQI_ExistsClockReady( SQI_MODULE_ID index ); Description This function identifies whether the ClockReady feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ClockIsStable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2982 Returns • true - The ClockReady feature is supported on the device • false - The ClockReady feature is not supported on the device Remarks None. 5.6.23.5.10.18 PLIB_SQI_ExistsConBufThreshold Function C bool PLIB_SQI_ExistsConBufThreshold( SQI_MODULE_ID index ); Description This function identifies whether the ConBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ControlBufferThresholdSet • PLIB_SQI_ControlBufferThresholdGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ConBufThreshold feature is supported on the device • false - The ConBufThreshold feature is not supported on the device Remarks None. 5.6.23.5.10.19 PLIB_SQI_ExistsConfigWord Function C bool PLIB_SQI_ExistsConfigWord( SQI_MODULE_ID index ); Description This function identifies whether the ConfigWord feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ConfigWordSet • PLIB_SQI_ConfigWordGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2983 Parameters Parameters Description index Identifier for the device instance Returns • true - The ConfigWord feature is supported on the device • false - The ConfigWord feature is not supported on the device Remarks None. 5.6.23.5.10.20 PLIB_SQI_ExistsControlWord Function C bool PLIB_SQI_ExistsControlWord( SQI_MODULE_ID index ); Description This function identifies whether the ControlWord feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ControlWordSet • PLIB_SQI_ControlWordGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ControlWord feature is supported on the device • false - The ControlWord feature is not supported on the device Remarks None. 5.6.23.5.10.21 PLIB_SQI_ExistsCSDeassert Function C bool PLIB_SQI_ExistsCSDeassert( SQI_MODULE_ID index ); Description This function identifies whether the CSDeassert feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ChipSelectDeassertEnable • PLIB_SQI_ChipSelectDeassertDisable 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2984 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CSDeassert feature is supported on the device • false - The CSDeassert feature is not supported on the device Remarks None. 5.6.23.5.10.22 PLIB_SQI_ExistsCSOutputEnable Function C bool PLIB_SQI_ExistsCSOutputEnable( SQI_MODULE_ID index ); Description This function identifies whether the CSOutputEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_CSOutputEnableSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CSOutputEnable feature is supported on the device • false - The CSOutputEnable feature is not supported on the device Remarks None. 5.6.23.5.10.23 PLIB_SQI_ExistsDataFormat Function C bool PLIB_SQI_ExistsDataFormat( SQI_MODULE_ID index ); Description This function identifies whether the DataFormat feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DataFormatSet 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2985 • PLIB_SQI_DataFormatGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataFormat feature is supported on the device • false - The DataFormat feature is not supported on the device Remarks None. 5.6.23.5.10.24 PLIB_SQI_ExistsDataModeControl Function C bool PLIB_SQI_ExistsDataModeControl( SQI_MODULE_ID index ); Description This function identifies whether the DataModeControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DataModeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataModeControl feature is supported on the device • false - The DataModeControl feature is not supported on the device Remarks None. 5.6.23.5.10.25 PLIB_SQI_ExistsDataOutputEnable Function C bool PLIB_SQI_ExistsDataOutputEnable( SQI_MODULE_ID index ); Description This function identifies whether the DataOutputEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DataOutputEnableSelect 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2986 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataOutputEnable feature is supported on the device • false - The DataOutputEnable feature is not supported on the device Remarks None. 5.6.23.5.10.26 PLIB_SQI_ExistsDataPinStatus Function C bool PLIB_SQI_ExistsDataPinStatus( SQI_MODULE_ID index ); Description This function identifies whether the DataPinStatus feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DataLineStatus Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DataPinStatus feature is supported on the device • false - The DataPinStatus feature is not supported on the device Remarks None. 5.6.23.5.10.27 PLIB_SQI_ExistsDmaEnable Function C bool PLIB_SQI_ExistsDmaEnable( SQI_MODULE_ID index ); Description This function identifies whether the DMAEnable feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMAEnable 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2987 • PLIB_SQI_DMADisable • PLIB_SQI_DMAIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DMAEnable feature is supported on the device • false - The DMAEnable feature is not supported on the device Remarks None. 5.6.23.5.10.28 PLIB_SQI_ExistsDMAEngineBusy Function C bool PLIB_SQI_ExistsDMAEngineBusy( SQI_MODULE_ID index ); Description This function identifies whether the DMAEngineBusy feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDIsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DMAEngineBusy feature is supported on the device • false - The DMAEngineBusy feature is not supported on the device Remarks None. 5.6.23.5.10.29 PLIB_SQI_ExistsDMAProcessInProgress Function C bool PLIB_SQI_ExistsDMAProcessInProgress( SQI_MODULE_ID index ); Description This function identifies whether the DMAProcessInProgress feature is available on the SQI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2988 • PLIB_SQI_DMAHasStarted Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DMAProcessInProgress feature is supported on the device • false - The DMAProcessInProgress feature is not supported on the device Remarks None. 5.6.23.5.10.30 PLIB_SQI_ExistsEnableControl Function C bool PLIB_SQI_ExistsEnableControl( SQI_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_Enable • PLIB_SQI_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.23.5.10.31 PLIB_SQI_ExistsHoldPinControl Function C bool PLIB_SQI_ExistsHoldPinControl( SQI_MODULE_ID index ); Description This function identifies whether the HoldPinControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2989 • PLIB_SQI_HoldSet • PLIB_SQI_HoldClear • PLIB_SQI_HoldGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HoldPinControl feature is supported on the device • false - The HoldPinControl feature is not supported on the device Remarks None. 5.6.23.5.10.32 PLIB_SQI_ExistsInterruptControl Function C bool PLIB_SQI_ExistsInterruptControl( SQI_MODULE_ID index ); Description This function identifies whether the InterruptControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_InterruptEnable • PLIB_SQI_InterruptDisable • PLIB_SQI_InterruptIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InterruptControl feature is supported on the device • false - The InterruptControl feature is not supported on the device Remarks None. 5.6.23.5.10.33 PLIB_SQI_ExistsInterruptSignalControl Function C bool PLIB_SQI_ExistsInterruptSignalControl( SQI_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2990 Description This function identifies whether the InterruptSignalControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_InterruptSignalEnable • PLIB_SQI_InterruptSignalDisable • PLIB_SQI_InterruptSignalIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InterruptSignalControl feature is supported on the device • false - The InterruptSignalControl feature is not supported on the device Remarks None. 5.6.23.5.10.34 PLIB_SQI_ExistsInterruptStatus Function C bool PLIB_SQI_ExistsInterruptStatus( SQI_MODULE_ID index ); Description This function identifies whether the InterruptStatus feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_InterruptFlagGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The InterruptStatus feature is supported on the device • false - The InterruptStatus feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2991 5.6.23.5.10.35 PLIB_SQI_ExistsLaneMode Function C bool PLIB_SQI_ExistsLaneMode( SQI_MODULE_ID index ); Description This function identifies whether the LaneMode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_LaneModeSet • PLIB_SQI_LaneModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LaneMode feature is supported on the device • false - The LaneMode feature is not supported on the device Remarks None. 5.6.23.5.10.36 PLIB_SQI_ExistsReceiveLatch Function C bool PLIB_SQI_ExistsReceiveLatch( SQI_MODULE_ID index ); Description This function identifies whether the ReceiveLatch feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ReceiveLatchEnable • PLIB_SQI_ReceiveLatchDisable • PLIB_SQI_ReceiveLatchGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiveLatch feature is supported on the device • false - The ReceiveLatch feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2992 Remarks None. 5.6.23.5.10.37 PLIB_SQI_ExistsRxBufferCount Function C bool PLIB_SQI_ExistsRxBufferCount( SQI_MODULE_ID index ); Description This function identifies whether the RxBufferCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_NumberOfReceiveBufferReads Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxBufferCount feature is supported on the device • false - The RxBufferCount feature is not supported on the device Remarks None. 5.6.23.5.10.38 PLIB_SQI_ExistsRxBufIntThreshold Function C bool PLIB_SQI_ExistsRxBufIntThreshold( SQI_MODULE_ID index ); Description This function identifies whether the RxBufIntThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_RxBufferThresholdIntSet • PLIB_SQI_RxBufferThresholdIntGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxBufIntThreshold feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2993 • false - The RxBufIntThreshold feature is not supported on the device Remarks None. 5.6.23.5.10.39 PLIB_SQI_ExistsRxBufThreshold Function C bool PLIB_SQI_ExistsRxBufThreshold( SQI_MODULE_ID index ); Description This function identifies whether the RxBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_RxBufferThresholdSet • PLIB_SQI_RxBufferThresholdGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxBufThreshold feature is supported on the device • false - The RxBufThreshold feature is not supported on the device Remarks None. 5.6.23.5.10.40 PLIB_SQI_ExistsRxData Function C bool PLIB_SQI_ExistsRxData( SQI_MODULE_ID index ); Description This function identifies whether the RxData feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ReceiveData Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxData feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2994 • false - The RxData feature is not supported on the device Remarks None. 5.6.23.5.10.41 PLIB_SQI_ExistsRxUnderRun Function C bool PLIB_SQI_ExistsRxUnderRun( SQI_MODULE_ID index ); Description This function identifies whether the RxUnderRun feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ReceiveBufferIsUnderrun Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The RxUnderRun feature is supported on the device • false - The RxUnderRun feature is not supported on the device Remarks None. 5.6.23.5.10.42 PLIB_SQI_ExistsSoftReset Function C bool PLIB_SQI_ExistsSoftReset( SQI_MODULE_ID index ); Description This function identifies whether the SoftReset feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_SoftReset Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SoftReset feature is supported on the device • false - The SoftReset feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2995 Remarks None. 5.6.23.5.10.43 PLIB_SQI_ExistsStartDMA Function C bool PLIB_SQI_ExistsStartDMA( SQI_MODULE_ID index ); Description This function identifies whether the StartDMA feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_DMABDFetchStart Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StartDMA feature is supported on the device • false - The StartDMA feature is not supported on the device Remarks None. 5.6.23.5.10.44 PLIB_SQI_ExistsTransferCommand Function C bool PLIB_SQI_ExistsTransferCommand( SQI_MODULE_ID index ); Description This function identifies whether the TransferCommand feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransferDirectionSet • PLIB_SQI_TransferDirectionGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransferCommand feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2996 • false - The TransferCommand feature is not supported on the device Remarks None. 5.6.23.5.10.45 PLIB_SQI_ExistsTransferCount Function C bool PLIB_SQI_ExistsTransferCount( SQI_MODULE_ID index ); Description This function identifies whether the TransferCount feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_ByteCountSet • PLIB_SQI_ByteCountGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransferCount feature is supported on the device • false - The TransferCount feature is not supported on the device Remarks None. 5.6.23.5.10.46 PLIB_SQI_ExistsTransferModeControl Function C bool PLIB_SQI_ExistsTransferModeControl( SQI_MODULE_ID index ); Description This function identifies whether the TransferModeControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransferModeSet • PLIB_SQI_TransferModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2997 Returns • true - The TransferModeControl feature is supported on the device • false - The TransferModeControl feature is not supported on the device Remarks None. 5.6.23.5.10.47 PLIB_SQI_ExistsTxBufferFree Function C bool PLIB_SQI_ExistsTxBufferFree( SQI_MODULE_ID index ); Description This function identifies whether the TxBufferFree feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransmitBufferFreeSpaceGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TxBufferFree feature is supported on the device • false - The TxBufferFree feature is not supported on the device Remarks None. 5.6.23.5.10.48 PLIB_SQI_ExistsTxBufIntThreshold Function C bool PLIB_SQI_ExistsTxBufIntThreshold( SQI_MODULE_ID index ); Description This function identifies whether the TxBufIntThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TxBufferThresholdIntSet • PLIB_SQI_TxBufferThresholdIntGet Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2998 Parameters Parameters Description index Identifier for the device instance Returns • true - The TxBufIntThreshold feature is supported on the device • false - The TxBufIntThreshold feature is not supported on the device Remarks None. 5.6.23.5.10.49 PLIB_SQI_ExistsTxBufThreshold Function C bool PLIB_SQI_ExistsTxBufThreshold( SQI_MODULE_ID index ); Description This function identifies whether the TxBufThreshold feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TxBufferThresholdSet • PLIB_SQI_TxBufferThresholdGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TxBufThreshold feature is supported on the device • false - The TxBufThreshold feature is not supported on the device Remarks None. 5.6.23.5.10.50 PLIB_SQI_ExistsTxData Function C bool PLIB_SQI_ExistsTxData( SQI_MODULE_ID index ); Description This function identifies whether the TxData feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransmitData 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-2999 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TxData feature is supported on the device • false - The TxData feature is not supported on the device Remarks None. 5.6.23.5.10.51 PLIB_SQI_ExistsTxOverFlow Function C bool PLIB_SQI_ExistsTxOverFlow( SQI_MODULE_ID index ); Description This function identifies whether the TxOverFlow feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_TransmitBufferHasOverflowed Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TxOverFlow feature is supported on the device • false - The TxOverFlow feature is not supported on the device Remarks None. 5.6.23.5.10.52 PLIB_SQI_ExistsWPPinControl Function C bool PLIB_SQI_ExistsWPPinControl( SQI_MODULE_ID index ); Description This function identifies whether the WPPinControl feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_WriteProtectSet 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3000 • PLIB_SQI_WriteProtectClear • PLIB_SQI_WriteProtectGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WPPinControl feature is supported on the device • false - The WPPinControl feature is not supported on the device Remarks None. 5.6.23.5.10.53 PLIB_SQI_ExistsXIPChipSelect Function C bool PLIB_SQI_ExistsXIPChipSelect( SQI_MODULE_ID index ); Description This function identifies whether the XIPChipSelect feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPChipSelectSet • PLIB_SQI_XIPChipSelectGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPChipSelect feature is supported on the device • false - The XIPChipSelect feature is not supported on the device Remarks None. 5.6.23.5.10.54 PLIB_SQI_ExistsXIPControlWord1 Function C bool PLIB_SQI_ExistsXIPControlWord1( SQI_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3001 Description This function identifies whether the XIPControlWord1 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord1Set • PLIB_SQI_XIPControlWord1Get Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPControlWord1 feature is supported on the device • false - The XIPControlWord1 feature is not supported on the device Remarks None. 5.6.23.5.10.55 PLIB_SQI_ExistsXIPControlWord2 Function C bool PLIB_SQI_ExistsXIPControlWord2( SQI_MODULE_ID index ); Description This function identifies whether the XIPControlWord2 feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPControlWord2Set • PLIB_SQI_XIPControlWord2Get Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPControlWord2 feature is supported on the device • false - The XIPControlWord2 feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3002 5.6.23.5.10.56 PLIB_SQI_ExistsXIPLaneMode Function C bool PLIB_SQI_ExistsXIPLaneMode( SQI_MODULE_ID index ); Description This function identifies whether the XIPLaneMode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPLaneModeSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPLaneMode feature is supported on the device • false - The XIPLaneMode feature is not supported on the device Remarks None. 5.6.23.5.10.57 PLIB_SQI_ExistsXIPModeBytes Function C bool PLIB_SQI_ExistsXIPModeBytes( SQI_MODULE_ID index ); Description This function identifies whether the XIPModeBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPModeBytesSet • PLIB_SQI_XIPModeBytesGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPModeBytes feature is supported on the device • false - The XIPModeBytes feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3003 5.6.23.5.10.58 PLIB_SQI_ExistsXIPModeCode Function C bool PLIB_SQI_ExistsXIPModeCode( SQI_MODULE_ID index ); Description This function identifies whether the XIPModeCode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPModeCodeSet • PLIB_SQI_XIPModeCodeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPModeCode feature is supported on the device • false - The XIPModeCode feature is not supported on the device Remarks None. 5.6.23.5.10.59 PLIB_SQI_ExistsXIPNumberOfAddressBytes Function C bool PLIB_SQI_ExistsXIPNumberOfAddressBytes( SQI_MODULE_ID index ); Description This function identifies whether the XIPNumberOfAddressBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPAddressBytesSet • PLIB_SQI_XIPAddressBytesGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPNumberOfAddressBytes feature is supported on the device • false - The XIPNumberOfAddressBytes feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3004 Remarks None. 5.6.23.5.10.60 PLIB_SQI_ExistsXIPNumberOfDummyBytes Function C bool PLIB_SQI_ExistsXIPNumberOfDummyBytes( SQI_MODULE_ID index ); Description This function identifies whether the XIPNumberOfDummyBytes feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPDummyBytesSet • PLIB_SQI_XIPDummyBytesGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The XIPNumberOfDummyBytes feature is supported on the device • false - The XIPNumberOfDummyBytes feature is not supported on the device Remarks None. 5.6.23.5.10.61 PLIB_SQI_ExistsXIPReadOpCode Function C bool PLIB_SQI_ExistsXIPReadOpCode( SQI_MODULE_ID index ); Description This function identifies whether the XIPReadOpCode feature is available on the SQI module. When this function returns true, these functions are supported on the device: • PLIB_SQI_XIPReadOpcodeSet • PLIB_SQI_XIPReadOpcodeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3005 Returns • true - The XIPReadOpCode feature is supported on the device • false - The XIPReadOpCode feature is not supported on the device Remarks None. 5.6.23.6 Files Files Name Description plib_sqi.h SQI PLIB Interface Header for common definitions Description 5.6.23.6.1 plib_sqi.h SQI Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the SQI PLIB. Functions Name Description PLIB_SQI_BurstEnable This bit sets the burst enable (BURSTEN) function for higher throughput. This function is artifact of the system bus architecture. PLIB_SQI_ByteCountGet Returns the current transmit/receive count. PLIB_SQI_ByteCountSet Sets the transmit/receive count. PLIB_SQI_ChipSelectDeassertDisable Clears the chip select de-assert. PLIB_SQI_ChipSelectDeassertEnable Sets the chip select de-assert. PLIB_SQI_ChipSelectGet Returns the chip select that is currently active. PLIB_SQI_ChipSelectSet Activates the chip select. PLIB_SQI_ClockDisable Disables the SQI transfer clock. PLIB_SQI_ClockDividerGet Returns the SQI clock divider value. PLIB_SQI_ClockDividerSet Sets the SQI clock (that drives the SQI protocol) divider value. Divides the base clock to generate the SQI clock. PLIB_SQI_ClockEnable Enables the SQI transfer clock. PLIB_SQI_ClockIsStable Returns SQI transfer clock state. PLIB_SQI_ConfigWordGet Get the SQI configuration word. PLIB_SQI_ConfigWordSet Sets SQI Configuration Word. PLIB_SQI_ControlBufferThresholdGet Returns the transmit buffer space in bytes. PLIB_SQI_ControlBufferThresholdSet Sets the control buffer threshold value. PLIB_SQI_ControlWordGet Get the SQI control word. PLIB_SQI_ControlWordSet Sets SQI Control Word. PLIB_SQI_CSOutputEnableSelect Selects the output enables on SQI chip select pins. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3006 PLIB_SQI_DataFormatGet Returns the data format to Least Significant Bit First or LITTLE-ENDIAN. PLIB_SQI_DataFormatSet Sets the data format to Least Significant Bit First or LITTLE-ENDIAN. PLIB_SQI_DataLineStatus Returns the logical status of the SQI data lines. PLIB_SQI_DataModeGet Returns the SQI data mode of operation (SPI Mode0/Mode3). PLIB_SQI_DataModeSet Sets the SQI data mode of operation (SPI Mode0/Mode3/Serial Flash). PLIB_SQI_DataOutputEnableSelect Selects the output enables on SQI data outputs. PLIB_SQI_Disable Disables the SQI module. PLIB_SQI_DMABDBaseAddressGet Returns the address of the base buffer descriptor. PLIB_SQI_DMABDBaseAddressSet Sets the address of the base buffer descriptor. PLIB_SQI_DMABDControlWordGet Returns Current Buffer Descriptor Control Word Information. PLIB_SQI_DMABDCurrentAddressGet Returns the address of the current buffer descriptor in process. PLIB_SQI_DMABDFetchStart Start the DMA buffer descriptor fetch process. PLIB_SQI_DMABDIsBusy Returns true if DMA Buffer Descriptor is busy. PLIB_SQI_DMABDPollCounterSet Sets the poll counter value. PLIB_SQI_DMABDPollDisable Disables the buffer descriptor polling. PLIB_SQI_DMABDPollEnable Enables the buffer descriptor polling. PLIB_SQI_DMABDPollIsEnabled Returns true if DAM buffer descriptor poll is eanbled and false if it's disabled. PLIB_SQI_DMABDReceiveBufferCountGet Returns the receive buffer space in bytes. PLIB_SQI_DMABDReceiveBufferLengthGet Returns the receive length in bytes. PLIB_SQI_DMABDReceiveStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMABDTransmitBufferCountGet Returns the transmit buffer space in bytes. PLIB_SQI_DMABDTransmitBufferLengthGet Returns the transmit length in bytes. PLIB_SQI_DMABDTransmitStateGet Returns the current state of the buffer descriptor in progress. PLIB_SQI_DMADisable Disables the built-in DMA logic. PLIB_SQI_DMAEnable Enables the built-in DMA logic. PLIB_SQI_DMAHasStarted Returns true if DMA process has started if not returns false. PLIB_SQI_DMAIsEnabled Returns true if DAM is eanbled and false if it's disabled. PLIB_SQI_Enable Enables the SQI module. PLIB_SQI_ExistsBDBaseAddress Identifies whether the BDBaseAddress feature exists on the SQI module PLIB_SQI_ExistsBDControlWord Identifies whether the BDControlWord feature exists on the SQI module PLIB_SQI_ExistsBDCurrentAddress Identifies whether the BDCurrentAddress feature exists on the SQI module PLIB_SQI_ExistsBDPollCount Identifies whether the BDPollCount feature exists on the SQI module PLIB_SQI_ExistsBDPollingEnable Identifies whether the BDPollingEnable feature exists on the SQI module PLIB_SQI_ExistsBDProcessState Identifies whether the BDProcessState feature exists on the SQI module PLIB_SQI_ExistsBDRxBufCount Identifies whether the BDRxBufCount feature exists on the SQI module PLIB_SQI_ExistsBDRxLength Identifies whether the BDRxLength feature exists on the SQI module PLIB_SQI_ExistsBDRxState Identifies whether the BDRxState feature exists on the SQI module 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3007 PLIB_SQI_ExistsBDTxBufCount Identifies whether the BDTxBufCount feature exists on the SQI module PLIB_SQI_ExistsBDTxLength Identifies whether the BDTxLength feature exists on the SQI module PLIB_SQI_ExistsBDTxState Identifies whether the BDTxState feature exists on the SQI module PLIB_SQI_ExistsBurstControl Identifies whether the BurstControl feature exists on the SQI module PLIB_SQI_ExistsChipSelect Identifies whether the ChipSelect feature exists on the SQI module PLIB_SQI_ExistsClockControl Identifies whether the ClockControl feature exists on the SQI module PLIB_SQI_ExistsClockDivider Identifies whether the ClockDivider feature exists on the SQI module PLIB_SQI_ExistsClockReady Identifies whether the ClockReady feature exists on the SQI module PLIB_SQI_ExistsConBufThreshold Identifies whether the ConBufThreshold feature exists on the SQI module PLIB_SQI_ExistsConfigWord Identifies whether the ConfigWord feature exists on the SQI module PLIB_SQI_ExistsControlWord Identifies whether the ControlWord feature exists on the SQI module PLIB_SQI_ExistsCSDeassert Identifies whether the CSDeassert feature exists on the SQI module PLIB_SQI_ExistsCSOutputEnable Identifies whether the CSOutputEnable feature exists on the SQI module PLIB_SQI_ExistsDataFormat Identifies whether the DataFormat feature exists on the SQI module PLIB_SQI_ExistsDataModeControl Identifies whether the DataModeControl feature exists on the SQI module PLIB_SQI_ExistsDataOutputEnable Identifies whether the DataOutputEnable feature exists on the SQI module PLIB_SQI_ExistsDataPinStatus Identifies whether the DataPinStatus feature exists on the SQI module PLIB_SQI_ExistsDmaEnable Identifies whether the DMAEnable feature exists on the SQI module PLIB_SQI_ExistsDMAEngineBusy Identifies whether the DMAEngineBusy feature exists on the SQI module PLIB_SQI_ExistsDMAProcessInProgress Identifies whether the DMAProcessInProgress feature exists on the SQI module PLIB_SQI_ExistsEnableControl Identifies whether the EnableControl feature exists on the SQI module PLIB_SQI_ExistsHoldPinControl Identifies whether the HoldPinControl feature exists on the SQI module PLIB_SQI_ExistsInterruptControl Identifies whether the InterruptControl feature exists on the SQI module PLIB_SQI_ExistsInterruptSignalControl Identifies whether the InterruptSignalControl feature exists on the SQI module PLIB_SQI_ExistsInterruptStatus Identifies whether the InterruptStatus feature exists on the SQI module PLIB_SQI_ExistsLaneMode Identifies whether the LaneMode feature exists on the SQI module PLIB_SQI_ExistsReceiveLatch Identifies whether the ReceiveLatch feature exists on the SQI module PLIB_SQI_ExistsRxBufferCount Identifies whether the RxBufferCount feature exists on the SQI module PLIB_SQI_ExistsRxBufIntThreshold Identifies whether the RxBufIntThreshold feature exists on the SQI module PLIB_SQI_ExistsRxBufThreshold Identifies whether the RxBufThreshold feature exists on the SQI module PLIB_SQI_ExistsRxData Identifies whether the RxData feature exists on the SQI module PLIB_SQI_ExistsRxUnderRun Identifies whether the RxUnderRun feature exists on the SQI module 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3008 PLIB_SQI_ExistsSoftReset Identifies whether the SoftReset feature exists on the SQI module PLIB_SQI_ExistsStartDMA Identifies whether the StartDMA feature exists on the SQI module PLIB_SQI_ExistsTransferCommand Identifies whether the TransferCommand feature exists on the SQI module PLIB_SQI_ExistsTransferCount Identifies whether the TransferCount feature exists on the SQI module PLIB_SQI_ExistsTransferModeControl Identifies whether the TransferModeControl feature exists on the SQI module PLIB_SQI_ExistsTxBufferFree Identifies whether the TxBufferFree feature exists on the SQI module PLIB_SQI_ExistsTxBufIntThreshold Identifies whether the TxBufIntThreshold feature exists on the SQI module PLIB_SQI_ExistsTxBufThreshold Identifies whether the TxBufThreshold feature exists on the SQI module PLIB_SQI_ExistsTxData Identifies whether the TxData feature exists on the SQI module PLIB_SQI_ExistsTxOverFlow Identifies whether the TxOverFlow feature exists on the SQI module PLIB_SQI_ExistsWPPinControl Identifies whether the WPPinControl feature exists on the SQI module PLIB_SQI_ExistsXIPChipSelect Identifies whether the XIPChipSelect feature exists on the SQI module PLIB_SQI_ExistsXIPControlWord1 Identifies whether the XIPControlWord1 feature exists on the SQI module PLIB_SQI_ExistsXIPControlWord2 Identifies whether the XIPControlWord2 feature exists on the SQI module PLIB_SQI_ExistsXIPLaneMode Identifies whether the XIPLaneMode feature exists on the SQI module PLIB_SQI_ExistsXIPModeBytes Identifies whether the XIPModeBytes feature exists on the SQI module PLIB_SQI_ExistsXIPModeCode Identifies whether the XIPModeCode feature exists on the SQI module PLIB_SQI_ExistsXIPNumberOfAddressBytes Identifies whether the XIPNumberOfAddressBytes feature exists on the SQI module PLIB_SQI_ExistsXIPNumberOfDummyBytes Identifies whether the XIPNumberOfDummyBytes feature exists on the SQI module PLIB_SQI_ExistsXIPReadOpCode Identifies whether the XIPReadOpCode feature exists on the SQI module PLIB_SQI_HoldClear This bit clears the hold function to be disabled on SQID3 in single and dual lane modes. PLIB_SQI_HoldGet This bit gets the status of HOLD function on SQID3 pin. PLIB_SQI_HoldSet This bit sets the hold function to be enabled on SQID3 in single or dual lane modes. PLIB_SQI_InterruptDisable Disables the interrupt source. PLIB_SQI_InterruptEnable Enables the interrupt source passed. PLIB_SQI_InterruptFlagGet Return SQI Interrupt flag status. PLIB_SQI_InterruptIsEnabled Returns the interrupt state (eanbled/disabled). PLIB_SQI_InterruptSignalDisable Disables the interrupt signal source. PLIB_SQI_InterruptSignalEnable Enables the interrupt signal source passed. PLIB_SQI_InterruptSignalIsEnabled Returns the interrupt signal state (eanbled/disabled). PLIB_SQI_LaneModeGet Returns the lane mode (single/dual/quad). PLIB_SQI_LaneModeSet Sets the data lane mode (single/dual/quad). 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3009 PLIB_SQI_NumberOfReceiveBufferReads Returns the number of receive buffer reads. PLIB_SQI_ReceiveBufferIsUnderrun Returns the status of receive buffer. PLIB_SQI_ReceiveData Reads the data from the receive buffer. PLIB_SQI_ReceiveLatchDisable Disables the receive latch so receive data is discarded when in transmit mode. PLIB_SQI_ReceiveLatchEnable Enable the receive latch so receive data is latched during transmit mode. PLIB_SQI_ReceiveLatchGet Returns the receive latch status in transmit mode. PLIB_SQI_RxBufferThresholdGet Returns the receive command threshold. PLIB_SQI_RxBufferThresholdIntGet Sets the receive buffer threshold interrupt. PLIB_SQI_RxBufferThresholdIntSet Sets the receive buffer threshold for interrupt. PLIB_SQI_RxBufferThresholdSet Sets the receive command threshold. PLIB_SQI_SoftReset This bit issues a soft reset to the SQI module. PLIB_SQI_TransferDirectionGet Returns the transfer command. PLIB_SQI_TransferDirectionSet Sets the transfer command. PLIB_SQI_TransferModeGet Returns the SQI transfer mode (PIO/DMA/XIP) of operation. PLIB_SQI_TransferModeSet Sets the SQI transfer mode (PIO/DMA/XIP) of operation. PLIB_SQI_TransmitBufferFreeSpaceGet Returns the number of transmit buffer words available. PLIB_SQI_TransmitBufferHasOverflowed Returns the current status of the transmit buffer. PLIB_SQI_TransmitData Writes data into the SQI transmit buffer. PLIB_SQI_TxBufferThresholdGet Returns the transmit command threshold value. PLIB_SQI_TxBufferThresholdIntGet Returns the value to tigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdIntSet Sets the value to tigger the transmit buffer threshold interrupt. PLIB_SQI_TxBufferThresholdSet Sets the transmit command threshold. PLIB_SQI_WriteProtectClear This bit clears the Write-Protect function to be disabled on SQID2 in single or dual lane modes. PLIB_SQI_WriteProtectGet This bit gets the Write-Protect state of Write_Protect Feature on SQID2. PLIB_SQI_WriteProtectSet This bit sets the Write-Protect function to be enabled on SQID2 in single or dual Lane modes only. PLIB_SQI_XIPAddressBytesGet Returns the number of address bytes. PLIB_SQI_XIPAddressBytesSet Sets the number of address bytes. PLIB_SQI_XIPChipSelectGet Returns the current active chip select. PLIB_SQI_XIPChipSelectSet Activates the chip select in XIP mode. PLIB_SQI_XIPControlWord1Get Get the XIP mode control word 1. PLIB_SQI_XIPControlWord1Set Sets the XIP mode control word 1. PLIB_SQI_XIPControlWord2Get Get the XIP mode control word 2. PLIB_SQI_XIPControlWord2Set Sets the XIP mode control word 2. PLIB_SQI_XIPDummyBytesGet Sets the number of dummy bytes. PLIB_SQI_XIPDummyBytesSet Sets the number of dummy bytes. PLIB_SQI_XIPLaneModeGet Returns the lane (single/dual/quad) mode in XIP mode. PLIB_SQI_XIPLaneModeSet Selects the lane (Single/Dual/Quad) mode for different transaction in XIP mode. PLIB_SQI_XIPModeBytesGet Returns the number of bytes used for mode code command. PLIB_SQI_XIPModeBytesSet Allocates the bytes for mode code command. PLIB_SQI_XIPModeCodeGet Returns the mode code op-code. PLIB_SQI_XIPModeCodeSet Sets the mode code command. 5.6 Peripheral Library Help MPLAB Harmony Help SQI Peripheral Library 5-3010 PLIB_SQI_XIPReadOpcodeGet Returns the read opcode in XIP mode. PLIB_SQI_XIPReadOpcodeSet Sets the read opcode in XIP mode. File Name plib_sqi.h Company Microchip Technology Inc. 5.6.24 Timer Peripheral Library 5.6.24.1 Introduction Timer Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the Timer module on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thereby hiding differences from one microcontroller variant to another. Description Overview of Timers The timer function is one of the basic features of a microcontroller. Timers are useful for generating accurate time-based periodic interrupts for software application or real-time operating systems. Other uses include counting external pulses or accurate timing measurement of external events using the timer's gate functions or producing precise time delays. Some timers can also be used to control timing of other peripherals. 5.6.24.2 Release Notes MPLAB Harmony Version: v0.70b Timer Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3011 Nothing to report in this release. 5.6.24.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.24.4 Using the Library This topic describes the basic architecture of the Timer Peripheral Library and provides information and examples on how to use it. Interface Header File: plib_tmr.h The interface to the Timer Peripheral Library is defined in the "plib_tmr.h" header file. Any C language source (.c) file that uses the Timer Peripheral Library must include "plib_tmr.h". Library File: The Timer Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6.24.4.1 Hardware Abstraction Model This library provides the low-level abstraction of the Timer module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all the functionality of the available timers on the device. Refer to the specific device data sheet or related family reference manual to determine the set of functions that are supported for each Timer module on your device. Description Microchip timers can be classified as: • Overflow-based • Period match-based These timers are essentially counters of a specific size (8-, 16-, or 32-bits wide) that increment based on the clock cycle and the 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3012 timer prescaler. An application can monitor these counters to determine how much time has elapsed. The prescaler determines the timer granularity (resolution). It is a mechanism for generating the clock for the timer by the CPU clock. Every CPU has a clock source and the frequency of this source decides the rate at which instructions are executed by the processor. Most of the timers have the option of providing input clock prescalers, while some have the optional postscalers. The prescaler is used to divide the clock frequency of the Timer module and produce a clock for the timer. Each timer can be configured with a different source (internal or external) meaning, the source of the timer’s input clock is selectable. Both internal and external sources are available, depending on the part in use, with some timers providing a clock synchronization mechanisms with reference to external source. On some timers the clock edge, either the rising or the falling edge, on which the increment occurs, is selectable. Overflow-based Timers Overflow-based timers provide timer outputs or generate interrupts after a rollover from the maximum possible timer count. Overflow Timer Abstraction Diagram An overflow interrupt is triggered whenever the timer register overflows (i.e., reaches its maximum value based on its size as depicted by the following diagram). Period Match-based Timers Period match-based timers provide the timer outputs or generate interrupts upon a match between the counter's count value against the preprogrammed period. Period Match timer Abstraction Diagram 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3013 Gated Time Accumulation/Gated Control Mode The Gated Time Accumulation/Gate control mode allows the internal timer to increment based upon the duration of the high time applied to the timer input pin. In the Gated Time Accumulation mode, the timer clock source is derived from the internal system clock. When the input clock pin state is high, the timer will count up until a period match has occurred, or the input pin state is changed to a low state. A pin state transition from high-to-low will trigger an interrupt. A period/compare match interrupt is issued by a timer whenever the value of the timer becomes equal to a certain predefined value as depicted by the following diagram, 5.6.24.4.2 Library Overview The library interface routines are divided into various subsections, each of the sub-sections addresses one of the blocks or the overall operation of the Timer module. Library Interface Section Description 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3014 5.6.24.4.3 How the Library Works Timer modules can operate in the following modes: • Synchronous Clock Counter • Synchronous External Clock Counter • Asynchronous External Clock Counter • Gated Timer Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine availability. 5.6.24.4.3.1 Synchronous Internal Clock Counter This section provides information and examples for setting up Synchronous Internal Clock Counter operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. Description Synchronous Clock Counter operation provides the following capabilities: • Elapsed time measurements • Time delays • Periodic timer interrupts Setup Use the following steps for synchronous internal clock counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode8BitEnable, PLIB_TMR_Mode16BitEnable, or PLIB_TMR_Mode32BitEnable. 2. Set the start value of the timer using PLIB_TMR_Counter8BitSet and PLIB_TMR_Counter16BitSet and PLIB_TMR_Counter32BitSet. 3. The period register value can be set using PLIB_TMR_Period8BitSet, PLIB_TMR_Period16BitSet or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 4. Clear the timer register using PLIB_TMR_Counter8BitClear, PLIB_TMR_Counter16BitClear, or PLIB_TMR_Counter32BitClear. 5. In this mode, the input clock source for the timer is the internal clock, and is selected using PLIB_TMR_ClockSourceSelect, depending on which clock is used as the internal clock in the timer module of the device. 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Timer count is incremented on the rising timer clock edge. On some microcontrollers, this is can be changed using PLIB_TMR_ClockSourceEdgeSelect. with the appropriate parameter for the falling edge (i.e., increment on high-to-low). 8. On some microcontrollers, the timer output can go through a postscaler. The postscaler can be configured using PLIB_TMR_PostscaleSelect. 9. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Synchronous Counter (Internal Clock) Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3015 // Set the prescaler, and set the clock source as internal PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_TMRX_VALUE_1); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0xFFFF); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); Timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Example: Changing Counter Value During Timer Operation // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. uint16_t timer_value; // Clear the timer timer_value = PLIB_TMR_Counter16BitGet(MY_TIMER_INSTANCE); if(timer_value > 0x0ff0) { PLIB_TMR_Counter16BitSet(MY_TIMER_INSTANCE, 0x000a); } Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. 5.6.24.4.3.2 Synchronous External Clock Counter This section provides information and examples for Synchronous External Clock Clock Counter operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. Description Synchronous external clock counter operation provides the following capabilities: • Counting periodic or non-periodic pulses • Use external clock as time base for timers Setup Use the following steps for synchronous external clock counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode8BitEnable, PLIB_TMR_Mode16BitEnable, or PLIB_TMR_Mode32BitEnable. 2. The period register value can be set using PLIB_TMR_Period8BitSet, PLIB_TMR_Period16BitSet, or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter8BitSet , PLIB_TMR_Counter16BitSet, or PLIB_TMR_Counter32BitSet. 4. Some timer modules, can select an external clock as its input source. Use PLIB_TMR_ClockSourceSelect to select the external clock source. 5. The clock source is synchronized with the internal clock for synchronous operation. Use PLIB_TMR_ClockSourceExternalSyncEnable to synchronize the external clock source. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3016 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Timer count is incremented on the rising timer clock edge. On some microcontrollers, this is can be changed using PLIB_TMR_ClockSourceEdgeSelect, with the appropriate parameter for the falling edge (i.e., increment on high-to-low). 8. On some microcontrollers, the timer output can go through a postscaler. The postscaler can be configured using PLIB_TMR_PostscaleSelect. 9. Clear the timer register using PLIB_TMR_Counter8BitClear, PLIB_TMR_Counter16BitClea, or PLIB_TMR_Counter32BitClear. 10. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Synchronous Counter (External Clock) Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and enable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_256); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); PLIB_TMR_ClockSourceExternalSyncEnable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0xFFFF); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Example: Changing Counter Value During Timer Operation // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. uint16_t timer_value; // read the current timer value timer_value = PLIB_TMR_Counter16BitGet(MY_TIMER_INSTANCE); if(timer_value > 0x0ff0) { PLIB_TMR_Counter16BitSet(MY_TIMER_INSTANCE, 0x000a); } Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. 5.6.24.4.3.3 Asynchronous Counter This section provides information and examples for setting up Asynchronous Counter operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. Description Asynchronous Counter operation provides the following capabilities: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3017 • The timer can operate in Sleep mode and can generate an interrupt on a period match • The processor can wake up from Sleep on the timer interrupt • The timer can be clocked from the Secondary Oscillator for real-time clock applications Setup Use the following steps for Asynchronous Counter setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode8BitEnable, PLIB_TMR_Mode16BitEnable, or PLIB_TMR_Mode32BitEnable. 2. The period register value can be set using PLIB_TMR_Period8BitSet, PLIB_TMR_Period16BitSet, or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter8BitSet, PLIB_TMR_Counter16BitSet, and PLIB_TMR_Counter32BitSet. 4. Some timer modules can select an external clock as its input source. Use PLIB_TMR_ClockSourceSelect to select the external clock source. 5. For Asynchronous mode operation, the clock source is not synchronized with the internal clock. Use PLIB_TMR_ClockSourceExternalSyncDisable to disable the synchronization of the external clock source. 6. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired prescaler into the function from the enumeration TMR_PRESCALE. 7. Timer count is incremented on the rising timer clock edge. On some microcontrollers, this is can be changed using PLIB_TMR_ClockSourceEdgeSelect, with the appropriate parameter for the falling edge (i.e., increment on high-to-low). 8. On some microcontrollers, the timer output can go through a postscaler. The postscaler can be configured using PLIB_TMR_PostscaleSelect. 9. Clear the timer register using PLIB_TMR_Counter8BitClear, PLIB_TMR_Counter16BitClear, or PLIB_TMR_Counter32BitClear. 10. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example: Asynchronous Counter Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and disable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_64); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); PLIB_TMR_ClockSourceExternalSyncDisable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0x7F); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, when the timer count matches the period value if available, or when the counter overflows. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3018 5.6.24.4.3.4 Gated Timer This section provides information and examples for setting up Gated Timer operation. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. Description Gated Timer operation can be used to allow measurement of an external signal. Setup Use the following steps for Gated Timer setup: 1. Some timer modules support multiple resolutions, which can be selected using PLIB_TMR_Mode8BitEnable, PLIB_TMR_Mode16BitEnable, or PLIB_TMR_Mode32BitEnable. 2. The period register value can be set using PLIB_TMR_Period8BitSet, PLIB_TMR_Period16BitSet, or PLIB_TMR_Period32BitSet. Use the appropriate function based on the resolution of the timer. 3. Set the start value of the timer using PLIB_TMR_Counter8BitSet, PLIB_TMR_Counter16BitSet, and PLIB_TMR_Counter32BitSet. 4. In this mode, the input clock source for the timer is the internal clock, and is selected using PLIB_TMR_ClockSourceSelect, depending on which clock is used as the internal clock in the timer module of the device. 5. The prescaler for the clock can be selected using PLIB_TMR_PrescaleSelect. Pass in the desired pre scaler into the function from the enumeration TMR_PRESCALE. 6. Timer count is incremented on the rising timer clock edge. On some microcontrollers, this is can be changed using PLIB_TMR_ClockSourceEdgeSelect, with the appropriate parameter for the falling edge (i.e., increment on high-to-low). 7. On some microcontrollers, the timer output can go through a postscaler. The postscaler can be configured using PLIB_TMR_PostscaleSelect. 8. Clear the timer register using PLIB_TMR_Counter8BitClear, PLIB_TMR_Counter16BitClear, or PLIB_TMR_Counter32BitClear. 9. Gated operation can be enabled using the function PLIB_TMR_GateEnable. 10. On some devices, additional gate functionality can be controlled: • Gate Polarity: To allow the timer to count when the gate signal is high, use PLIB_TMR_GatePolaritySelect with the parameter TMR_GATE_POLARITY_ACTIVE_HIGH. To allow the timer to count when the gate signal is low, use PLIB_TMR_GatePolaritySelect with the parameter TMR_GATE_POLARITY_ACTIVE_LOW. • Gate Toggle mode: To allow the timer to measure the full cycle length of gate signal as opposed to the duration of a single pulse level, use PLIB_TMR_GateToggleModeEnable. To disable this mode, use PLIB_TMR_GateToggleModeDisable. • Gate Single Pulse mode: To allow the timer to capture a single pulse gate event, use PLIB_TMR_GateSinglePulseModeEnable and PLIB_TMR_GateSinglePulseModeDisable. The single pulse acquisition can be started using PLIB_TMR_GateSinglePulseAcquisitionStart, and its status can be read using PLIB_TMR_GateSinglePulseAcquisitionHasCompleted. • Additionally, the current state of the gate can be obtained using PLIB_TMR_GateCurrentStateGet • The gate source can be selected using PLIB_TMR_GateSourceSelect, using one of the possible values from TMR_GATE_SOURCE 11. Start the timer once the setup is complete using PLIB_TMR_Start. The timer operation can be stopped using PLIB_TMR_Stop. Example 1: Gated Timer Setup // Where MY_TMR_INSTANCE, is the timer instance selected for use by the application // developer. // Stop the timer 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3019 PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and disable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_64); PLIB_TMR_ClockSourceSelect(MY_TIMER_INSTANCE, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN); PLIB_TMR_ClockSourceExternalSyncDisable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0x7F00); // Enable the gate timer PLIB_TMR_GateEnable(MY_TIMER_INSTANCE); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); Example 2: Gated Timer Setup // Stop the timer uint8_t pulse_width; PLIB_TMR_Stop(MY_TIMER_INSTANCE); // Set the prescaler, and set the clock source as external and disable synchronization PLIB_TMR_PrescaleSelect(MY_TIMER_INSTANCE, TMR_PRESCALE_VALUE_64); PLIB_TMR_ClockSourceExternalInputClockEnable(MY_TIMER_INSTANCE); PLIB_TMR_ClockSourceExternalSyncDisable(MY_TIMER_INSTANCE); // Clear the timer PLIB_TMR_Counter16BitClear(MY_TIMER_INSTANCE); // Load the period register PLIB_TMR_Period16BitSet(MY_TIMER_INSTANCE, 0x7F00); // Enable the gate timer PLIB_TMR_GateEnable(MY_TIMER_INSTANCE); // Gate source selection PLIB_TMR_GateSourceSelect(MY_TIMER_INSTANCE, TMR_GATE_SOURCE_T1_GATE); // Start the timer PLIB_TMR_Start(MY_TIMER_INSTANCE); // Single pulse acquisition start PLIB_TMR_GateSinglePulseAcquisitionStart(MY_TIMER_INSTANCE); // Counting enabled on the rising edge PLIB_TMR_GatePolaritySelect(MY_TMR_INSTANCE, TMR_GATE_POLARITY_ACTIVE_HIGH); // Gate pulse mode enabled PLIB_TMR_GateSinglePulseModeEnable(MY_TIMER_INSTANCE); A timer interrupt is generated if enabled, on the falling edge of the gate signal. Refer to the specific device data sheet to determine whether this feature is available for your device. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes for your device. 5.6.24.4.3.5 Other Features This section provides information on additional features. Description Each of the following modes can additionally support some or all of the features listed. Please refer to the specific device data sheet or family reference manual for details. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3020 Operation During Sleep Mode When the Timer module is configured to operate in Asynchronous mode (with an external clock source), it will continue to increment each timer clock (or prescale multiple of clocks) during Sleep mode. On some devices, Timer operation during Sleep mode can be disabled using PLIB_TMR_OperateInSleepDisable, and can be enabled using PLIB_TMR_OperateInSleepEnable. Operation During Idle Mode A Timer module can continue to operate in Idle mode by calling PLIB_TMR_StopInIdleDisable, or can stop operation in Idle mode by calling PLIB_TMR_StopInIdleEnable. Event Trigger Reset If the PWM modules are configured to use a Timer module, a special event trigger can be generated in Compare mode. The trigger can reset the the timer modules. If supported by the device, the special event trigger reset can be enabled using PLIB_TMR_TriggerEventResetEnable, or disabled using PLIB_TMR_TriggerEventResetDisable. To be able to use this feature, the Timer module must be configured in one of the synchronous modes. Timer Mode Control • PLIB_TMR_Mode8BitEnable - For PIC18 timers, This interface disables 16-bit mode and enables 8-bit mode • PLIB_TMR_Mode16BitEnable: • For PIC18 timers, This interface disables 8-bit mode and enables 16-bit mode • For PIC24/PIC32 timers, this interface enables 16-bit mode and disables 32-bit mode • PLIB_TMR_Mode32BitEnable - For PIC24/PIC32 timers, this interface enables 32-bit mode and disables 16-bit mode Timer Usage Mode Some timers operate in either Period Match mode or Overflow mode. The mode state can be retrieved from the Timer Peripheral Library using IsPeriodMatchBased. This function returns 'true' Period Match mode and 'false' for Overflow mode. Timer Prescaler Information Prescaler divisor information associated with the respective prescaler value selected through TMR_PRESCALE can be retrieved through PLIB_TMR_PrescaleDivisorGet. The true prescaler value can be obtained by using PLIB_TMR_PrescaleGet. Timer Postscaler Information Postscaler divisor information associated with the respective postscaler value is selected through the enumeration TMR_POSTSCALE, and can be retrieved through PLIB_TMR_PostscaleDivisorGet. The true postscaler value can be obtained by using PLIB_TMR_PostscaleGet. Timer Source Edge Information The TMR source edge information can be retrieved using PLIB_TMR_ClockSourceEdgeGet. 5.6.24.4.4 Configuring the Library The library is configured for the supported Timer modules when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3021 5.6.24.5 Library Interface Data Types and Constants Name Description TMR_ASSIGNMENT Data type defining the Timer assignment to modules. TMR_CLOCK_SOURCE Data type defining the different clock sources. TMR_CLOCK_SOURCE_EDGE Data type defining the different source edges. TMR_GATE_POLARITY Data type defining the different gate polarities. TMR_GATE_SOURCE Data type defining the different gate source selections. TMR_MODULE_ID Identifies the supported Timer modules. TMR_POSTSCALE Defines the list of possible postscaler values. TMR_PRESCALE Defines the list of possible prescaler values. Clock Source Control Functions Name Description PLIB_TMR_ClockSourceEdgeGet Gets the source edge information. PLIB_TMR_ClockSourceEdgeSelect Selects the input clock source edge. PLIB_TMR_ClockSourceExternalSyncDisable Disables the clock synchronization of the external input. PLIB_TMR_ClockSourceExternalSyncEnable Enables the clock synchronization of the external input. PLIB_TMR_ClockSourceSelect Selects the clock source. Counter Control Functions Name Description PLIB_TMR_Counter16BitClear Clears the 16-bit timer value. PLIB_TMR_Counter16BitGet Gets the 16-bit timer value. PLIB_TMR_Counter16BitSet Sets the 16-bit timer value. PLIB_TMR_Counter32BitClear Clears the 32-bit timer value. PLIB_TMR_Counter32BitGet Gets the 32-bit timer value. PLIB_TMR_Counter32BitSet Sets the 32-bit timer value. PLIB_TMR_Counter8BitClear Clears the 8-bit timer value. PLIB_TMR_Counter8BitGet Gets the 8-bit timer value. PLIB_TMR_Counter8BitSet Sets the 8-bit timer value. PLIB_TMR_CounterAsyncWriteDisable Disables the writes to the counter register until the pending write operation completes. PLIB_TMR_CounterAsyncWriteEnable Enables back-to-back writes with legacy asynchronous timer functionality. PLIB_TMR_CounterAsyncWriteInProgress Returns the status of the counter write in Asynchronous mode. Feature Existence Functions Name Description PLIB_TMR_ExistsClockSource Identifies whether the ClockSource feature exists on the Timer module. PLIB_TMR_ExistsClockSourceEdge Identifies whether the ClockSourceEdge feature exists on the Timer module. PLIB_TMR_ExistsClockSourceSync Identifies whether the ClockSourceSync feature exists on the Timer module. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3022 PLIB_TMR_ExistsCounter16Bit Identifies whether the Counter16Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter32Bit Identifies whether the Counter32Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter8Bit Identifies whether the Counter8bit feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteControl Identifies whether the CounterAsyncWriteControl feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteInProgress Identifies whether the CounterAsyncWriteInProgress feature exists on the Timer module. PLIB_TMR_ExistsCountMode Identifies whether the CountMode feature exists on the Timer module. PLIB_TMR_ExistsEnableControl Identifies whether the EnableControl feature exists on the Timer module. PLIB_TMR_ExistsGateCurrentState Identifies whether the GateCurrentState feature exists on the Timer module. PLIB_TMR_ExistsGatedTimeAccumulation Identifies whether the GatedTimeAccumulation feature exists on the Timer module. PLIB_TMR_ExistsGatePolarity Identifies whether the GatePolarity feature exists on the Timer module. PLIB_TMR_ExistsGateSinglePulseAcqusition Identifies whether the GateSinglePulseAcquisition feature exists on the Timer module. PLIB_TMR_ExistsGateSinglePulseMode Identifies whether the GateSinglePulseMode feature exists on the Timer module. PLIB_TMR_ExistsGateSource Identifies whether the GateSource feature exists on the Timer module. PLIB_TMR_ExistsGateToggleMode Identifies whether the GateToggleMode feature exists on the Timer module. PLIB_TMR_ExistsMode16Bit Identifies whether the Mode16Bit feature exists on the Timer module. PLIB_TMR_ExistsMode32Bit Identifies whether the Mode32Bit feature exists on the Timer module. PLIB_TMR_ExistsMode8Bit Identifies whether the Mode8Bit feature exists on the Timer module. PLIB_TMR_ExistsOperationInSleep Identifies whether the OperationInSleep feature exists on the Timer module. PLIB_TMR_ExistsPeriod16Bit Identifies whether the Period16Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod32Bit Identifies whether the Period32Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod8Bit Identifies whether the Period8Bit feature exists on the Timer module. PLIB_TMR_ExistsPostscale Identifies whether the Postscale feature exists on the Timer module. PLIB_TMR_ExistsPrescale Identifies whether the Prescale feature exists on the Timer module. PLIB_TMR_ExistsPrescalerAssignment Identifies whether the PrescalerControl feature exists on the Timer module. PLIB_TMR_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the Timer module. PLIB_TMR_ExistsSystemClockStatus Identifies whether the SystemClockStatus feature exists on the Timer module. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3023 PLIB_TMR_ExistsTimerAssignment Identifies whether the TimerAssignment feature exists on the Timer module. PLIB_TMR_ExistsTimerOperationMode Identifies whether the TimerOperationMode feature exists on the Timer module. PLIB_TMR_ExistsTimerOscillator Identifies whether the TimerOscillator feature exists on the Timer module. PLIB_TMR_ExistsTriggerEventReset Identifies whether the TriggerEventReset feature exists on the Timer module. Gate Control Functions Name Description PLIB_TMR_GateCurrentStateGet Returns the current level of the timer gate. PLIB_TMR_GateDisable Enables counting regardless of the corresponding timer gate function. PLIB_TMR_GateEnable Enables counting controlled by the corresponding gate function. PLIB_TMR_GatePolaritySelect Selects the timer gate polarity. PLIB_TMR_GateSinglePulseAcquisitionHasCompleted Returns the gate single pulse acquisition status. PLIB_TMR_GateSinglePulseAcquisitionStart Starts the gate single pulse acquisition. PLIB_TMR_GateSinglePulseModeDisable Disables Single Pulse mode. PLIB_TMR_GateSinglePulseModeEnable Enables Single pulse mode and the controlling corresponding timer gate. PLIB_TMR_GateSourceSelect Selects the timer gate source. PLIB_TMR_GateToggleModeDisable Disables the Gate Toggle mode. PLIB_TMR_GateToggleModeEnable Enables the Gate Toggle mode. General Setup Functions Name Description PLIB_TMR_AssignmentSelect Assigns the specified Timer(s) to the selected modules. PLIB_TMR_ContinousCountModeEnable Enables Continous Count mode PLIB_TMR_Mode16BitEnable Enables the Timer module for 16-bit operation and disables all other modes. PLIB_TMR_Mode32BitEnable Enables 32-bit operation on the Timer module combination. PLIB_TMR_Mode8BitEnable Enables the Timer module in 8-bit operation mode and disables 16-bit mode. PLIB_TMR_Start Starts/enables the indexed timer. PLIB_TMR_Stop Stops/disables the indexed timer. PLIB_TMR_TimerOscillatorDisable Disables the oscillator associated with the Timer module. PLIB_TMR_TimerOscillatorEnable Enables the oscillator associated with the Timer module. PLIB_TMR_TriggerEventResetDisable Disables the special event trigger reset. PLIB_TMR_TriggerEventResetEnable Enables the special event trigger reset. PLIB_TMR_SingleShotModeEnable Enables Single-shot mode. Miscellaneous Functions Name Description PLIB_TMR_IsPeriodMatchBased Gets the operating mode state of the Timer module based on Period Match or Overflow mode. PLIB_TMR_SystemClockFromTimerIsActive Gets the system clock status. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3024 Period Control Functions Name Description PLIB_TMR_Period16BitGet Gets the 16-bit period value. PLIB_TMR_Period16BitSet Sets the 16-bit period value. PLIB_TMR_Period32BitGet Gets the 32-bit period value. PLIB_TMR_Period32BitSet Sets the 32-bit period value. PLIB_TMR_Period8BitGet Gets the 8-bit period value. PLIB_TMR_Period8BitSet Sets the 8-bit period value. Post-processing Functions Name Description PLIB_TMR_PostscaleDivisorGet Gets the postscaler divisor information. PLIB_TMR_PostscaleGet Gets the postscaler divisor information. PLIB_TMR_PostscaleSelect Selects the output clock postscaler. Power Control Functions Name Description PLIB_TMR_OperateInSleepDisable Disables Timer module operation when the device is in Sleep mode. PLIB_TMR_OperateInSleepEnable Enables Timer module operation when the device is in Sleep mode. PLIB_TMR_StopInIdleDisable Continue module operation when the device enters Idle mode. PLIB_TMR_StopInIdleEnable Discontinues module operation when the device enters Idle mode. Preprocessing Functions Name Description PLIB_TMR_PrescaleDivisorGet Gets the prescaler divisor information. PLIB_TMR_PrescaleGet Gets the prescaler information. PLIB_TMR_PrescalerDisable Disables the prescaler assignment to the indexed Timer module. PLIB_TMR_PrescalerEnable Enables the prescaler assignment to the indexed Timer module. PLIB_TMR_PrescaleSelect Selects the clock prescaler. Description This section lists and describes the functions, data types, and constants available in the Timer Peripheral Library. 5.6.24.5.1 General Setup Functions 5.6.24.5.1.1 PLIB_TMR_AssignmentSelect Function C void PLIB_TMR_AssignmentSelect( TMR_MODULE_ID index, TMR_ASSIGNMENT tmrNums ); Description This function assigns the specified Timer(s) as the clock source for the selected modules. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3025 Parameters Parameters Description index Identifier for the device instance to be configured tmrNums One of the possible values of TMR_ASSIGNMENT Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTimerAssignment in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_AssignmentSelect(MY_TMR_INSTANCE, TMR_ASSIGNMENT_T1_TO_CCP_ALL); 5.6.24.5.1.2 PLIB_TMR_ContinousCountModeEnable Function C void PLIB_TMR_ContinousCountModeEnable( TMR_MODULE_ID index ); Description This function enables Continous Count mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCountMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ContinousCountModeEnable(MY_TMR_INSTANCE); 5.6.24.5.1.3 PLIB_TMR_Mode16BitEnable Function C void PLIB_TMR_Mode16BitEnable( TMR_MODULE_ID index ); Description This function enables the Timer module for 16-bit operation and disables all other modes. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3026 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the operation of the Timer module 8-bit mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsMode16Bit in your application to determine whether this feature is available. For PIC18 Timers, this function disables 8-bit mode and enables 16-bit mode. For PIC24/PIC32 TMRs, this function enables 16-bit mode and disables 32-bit mode. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Mode16BitEnable(MY_TMR_INSTANCE); 5.6.24.5.1.4 PLIB_TMR_Mode32BitEnable Function C void PLIB_TMR_Mode32BitEnable( TMR_MODULE_ID index ); Description This function enables the Timer module and the index +1 Timer module to act as one 32-bit timer module and disables all other modes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsMode32Bit in your application to determine whether this feature is available. For PIC24/PIC32 Timers, this function enables 32-bit mode and disables 16-bit mode. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Mode32BitEnable(MY_TMR_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3027 5.6.24.5.1.5 PLIB_TMR_Mode8BitEnable Function C void PLIB_TMR_Mode8BitEnable( TMR_MODULE_ID index ); Description This function enables the Timer module in 8-bit operation mode and disables 16-bit mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the operation of Timer module in 16-bit mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsMode8Bit in your application to determine whether this feature is available. For PIC18 Timers, this function disables 16-bit mode and enables 8-bit mode. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Mode8BitEnable(MY_TMR_INSTANCE); 5.6.24.5.1.6 PLIB_TMR_Start Function C void PLIB_TMR_Start( TMR_MODULE_ID index ); Description This function starts/enables the indexed timer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3028 PLIB_TMR_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Start(MY_TMR_INSTANCE); 5.6.24.5.1.7 PLIB_TMR_Stop Function C void PLIB_TMR_Stop( TMR_MODULE_ID index ); Description This function stops/disables the indexed timer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsEnableControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Stop(MY_TMR_INSTANCE); 5.6.24.5.1.8 PLIB_TMR_TimerOscillatorDisable Function C void PLIB_TMR_TimerOscillatorDisable( TMR_MODULE_ID index ); Description This function disables the oscillator associated with the Timer module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3029 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTimerOscillator in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_TimerOscillatorDisable(MY_TMR_INSTANCE); 5.6.24.5.1.9 PLIB_TMR_TimerOscillatorEnable Function C void PLIB_TMR_TimerOscillatorEnable( TMR_MODULE_ID index ); Description This function enables the oscillator associated with the Timer module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTimerOscillator in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_TimerOscillatorEnable(MY_TMR_INSTANCE); 5.6.24.5.1.10 PLIB_TMR_TriggerEventResetDisable Function C void PLIB_TMR_TriggerEventResetDisable( TMR_MODULE_ID index ); Description This function disables the special event trigger reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3030 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTriggerEventReset in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_TriggerEventResetDisable(MY_TMR_INSTANCE); 5.6.24.5.1.11 PLIB_TMR_TriggerEventResetEnable Function C void PLIB_TMR_TriggerEventResetEnable( TMR_MODULE_ID index ); Description This function enables the special event trigger reset. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTriggerEventReset in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_TriggerEventResetEnable(MY_TMR_INSTANCE); 5.6.24.5.1.12 PLIB_TMR_SingleShotModeEnable Function C void PLIB_TMR_SingleShotModeEnable( TMR_MODULE_ID index ); Description This function enables Single-shot mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3031 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCountMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_SingleShotModeEnable(MY_TMR_INSTANCE); 5.6.24.5.2 Power Control Functions 5.6.24.5.2.1 PLIB_TMR_OperateInSleepDisable Function C void PLIB_TMR_OperateInSleepDisable( TMR_MODULE_ID index ); Description This function disables Timer module operation when the device is in Sleep mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsOperationInSleep in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_OperateInSleepDisable(MY_TMR_INSTANCE); 5.6.24.5.2.2 PLIB_TMR_OperateInSleepEnable Function C void PLIB_TMR_OperateInSleepEnable( TMR_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3032 Description This function enables Timer module operation when the device is in Sleep mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsOperationInSleep in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_OperateInSleepEnable(MY_TMR_INSTANCE); 5.6.24.5.2.3 PLIB_TMR_StopInIdleDisable Function C void PLIB_TMR_StopInIdleDisable( TMR_MODULE_ID index ); Description This function continues module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsStopInIdleControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_StopInIdleDisable(MY_TMR_INSTANCE); 5.6.24.5.2.4 PLIB_TMR_StopInIdleEnable Function C void PLIB_TMR_StopInIdleEnable( 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3033 TMR_MODULE_ID index ); Description This function discontinues module operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsStopInIdleControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_StopInIdleEnable(MY_TMR_INSTANCE); 5.6.24.5.3 Clock Source Control Functions 5.6.24.5.3.1 PLIB_TMR_ClockSourceEdgeGet Function C TMR_CLOCK_SOURCE_EDGE PLIB_TMR_ClockSourceEdgeGet( TMR_MODULE_ID index ); Description This function gets the input clock source edge information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns One of the possible values of TMR_CLOCK_SOURCE_EDGE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceEdge in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3034 TMR_CLOCK_SOURCE_EDGE source; source = PLIB_TMR_ClockSourceEdgeGet(MY_TMR_INSTANCE); 5.6.24.5.3.2 PLIB_TMR_ClockSourceEdgeSelect Function C void PLIB_TMR_ClockSourceEdgeSelect( TMR_MODULE_ID index, TMR_CLOCK_SOURCE_EDGE source ); Description This function selects the input clock source edge, which could either be high-to-low (falling edge) or low-to-high (rising edge). Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values of TMR_CLOCK_SOURCE_EDGE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceEdge in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceEdgeSelect(MY_TMR_INSTANCE, TMR_CLOCK_SOURCE_EDGE_INCREMENT_ON_LOW_TO_HIGH); 5.6.24.5.3.3 PLIB_TMR_ClockSourceExternalSyncDisable Function C void PLIB_TMR_ClockSourceExternalSyncDisable( TMR_MODULE_ID index ); Description This function disables the clock synchronization of the external input. Preconditions The timer module must be configured to use the external clock using the function PLIB_TMR_ClockSourceSelect with the clock source as TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN. If the function PLIB_TMR_ClockSourceSelect configures the clock with some other enumeration, this function will have no effect. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3035 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceSync in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceExternalSyncDisable(MY_TMR_INSTANCE); 5.6.24.5.3.4 PLIB_TMR_ClockSourceExternalSyncEnable Function C void PLIB_TMR_ClockSourceExternalSyncEnable( TMR_MODULE_ID index ); Description This function enables the clock synchronization of the external input. Preconditions The timer module must be configured to use the external clock using the function PLIB_TMR_ClockSourceSelect with the clock source as TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN. If the function PLIB_TMR_ClockSourceSelect configures the clock with some other enumeration, this function will have no effect. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsClockSourceSync in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceExternalSyncEnable(MY_TMR_INSTANCE); 5.6.24.5.3.5 PLIB_TMR_ClockSourceSelect Function C void PLIB_TMR_ClockSourceSelect( TMR_MODULE_ID index, TMR_CLOCK_SOURCE source ); Description This function selects the clock source. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3036 Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values of TMR_CLOCK_SOURCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSource in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_ClockSourceSelect(MY_TMR_INSTANCE, TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK); 5.6.24.5.4 Gate Control Functions 5.6.24.5.4.1 PLIB_TMR_GateCurrentStateGet Function C bool PLIB_TMR_GateCurrentStateGet( TMR_MODULE_ID index ); Description This function returns the current level of the timer gate. The gate value is set for the entire duration of the clock count whether it is a single pulse or a full clock cycle. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Acquisition has started • false - Acquisition has completed or has not been started Remarks This feature is not affected by PLIB_TMR_GateEnable or PLIB_TMR_GateDisable. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateCurrentState in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool gatestate = PLIB_TMR_GateCurrentStateGet(MY_TMR_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3037 5.6.24.5.4.2 PLIB_TMR_GateDisable Function C void PLIB_TMR_GateDisable( TMR_MODULE_ID index ); Description This function enables counting regardless of the gate function. Preconditions The timer must be enabled for this function to take effect. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGatedTimeAccumulation in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateDisable(MY_TMR_INSTANCE); 5.6.24.5.4.3 PLIB_TMR_GateEnable Function C void PLIB_TMR_GateEnable( TMR_MODULE_ID index ); Description This function enables counting controlled by the gate function. Preconditions The timer must be enabled, for this function to take effect. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGatedTimeAccumulation in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3038 // application developer. PLIB_TMR_GateEnable(MY_TMR_INSTANCE); 5.6.24.5.4.4 PLIB_TMR_GatePolaritySelect Function C void PLIB_TMR_GatePolaritySelect( TMR_MODULE_ID index, TMR_GATE_POLARITY polarity ); Description This function selects the timer gate polarity. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured polarity One of the possible values of TMR_GATE_POLARITY Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGatePolarity in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GatePolaritySelect(MY_TMR_INSTANCE, TMR_GATE_POLARITY_ACTIVE_HIGH); 5.6.24.5.4.5 PLIB_TMR_GateSinglePulseAcquisitionHasCompleted Function C bool PLIB_TMR_GateSinglePulseAcquisitionHasCompleted( TMR_MODULE_ID index ); Description This function returns the gate single pulse acquisition status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Acquisition is waiting for an edge • false - Acquisition has completed or has not been started 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3039 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSinglePulseAcqusition in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool isComplete; isComplete = PLIB_TMR_GateSinglePulseAcquisitionHasCompleted(MY_TMR_INSTANCE); 5.6.24.5.4.6 PLIB_TMR_GateSinglePulseAcquisitionStart Function C void PLIB_TMR_GateSinglePulseAcquisitionStart( TMR_MODULE_ID index ); Description This function starts the gate single pulse acquisition feature. Preconditions PLIB_TMR_GateSinglePulseModeEnable should be called before this function. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSinglePulseAcqusition in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateSinglePulseAcquisitionStart(MY_TMR_INSTANCE); 5.6.24.5.4.7 PLIB_TMR_GateSinglePulseModeDisable Function C void PLIB_TMR_GateSinglePulseModeDisable( TMR_MODULE_ID index ); Description This function disables Single Pulse mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3040 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSinglePulseMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateSinglePulseModeDisable(MY_TMR_INSTANCE); 5.6.24.5.4.8 PLIB_TMR_GateSinglePulseModeEnable Function C void PLIB_TMR_GateSinglePulseModeEnable( TMR_MODULE_ID index ); Description This function enables Single pulse mode and the controlling corresponding timer gate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSinglePulseMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateSinglePulseModeEnable(MY_TMR_INSTANCE); 5.6.24.5.4.9 PLIB_TMR_GateSourceSelect Function C void PLIB_TMR_GateSourceSelect( TMR_MODULE_ID index, TMR_GATE_SOURCE source ); Description This function selects the timer gate source. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3041 Parameters Parameters Description index Identifier for the device instance to be configured source One of the possible values of TMR_GATE_SOURCE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateSource in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateSourceSelect(MY_TMR_INSTANCE, TMR_GATE_SOURCE_CMP1_SYNC_OUTPUT); 5.6.24.5.4.10 PLIB_TMR_GateToggleModeDisable Function C void PLIB_TMR_GateToggleModeDisable( TMR_MODULE_ID index ); Description This function disables Gate Toggle mode and the toggle flip flop is cleared. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateToggleMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateToggleModeDisable(MY_TMR_INSTANCE); 5.6.24.5.4.11 PLIB_TMR_GateToggleModeEnable Function C void PLIB_TMR_GateToggleModeEnable( TMR_MODULE_ID index ); Description This function enables Gate Toggle mode. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3042 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsGateToggleMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_GateToggleModeEnable(MY_TMR_INSTANCE); 5.6.24.5.5 Preprocessing Functions 5.6.24.5.5.1 PLIB_TMR_PrescaleDivisorGet Function C uint16_t PLIB_TMR_PrescaleDivisorGet( TMR_MODULE_ID index, TMR_PRESCALE prescale ); Description This function gets the prescaler divisor information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the possible values of TMR_PRESCALE Returns prescale divisor value Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t div = PLIB_TMR_PrescaleDivisorGet (MY_TMR_INSTANCE, TMR_PRESCALE_VALUE_1); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3043 5.6.24.5.5.2 PLIB_TMR_PrescaleGet Function C TMR_PRESCALE PLIB_TMR_PrescaleGet( TMR_MODULE_ID index ); Description This function gets the prescaler information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns One of the possible values of TMR_PRESCALE Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. TMR_PRESCALE prescale; prescale = PLIB_TMR_PrescaleGet (MY_TMR_INSTANCE); 5.6.24.5.5.3 PLIB_TMR_PrescalerDisable Function C void PLIB_TMR_PrescalerDisable( TMR_MODULE_ID index ); Description This function disables the prescaler assignment to the indexed Timer module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescalerAssignment in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3044 Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_PrescalerDisable(MY_TMR_INSTANCE); 5.6.24.5.5.4 PLIB_TMR_PrescalerEnable Function C void PLIB_TMR_PrescalerEnable( TMR_MODULE_ID index ); Description This function enables the prescaler assignment to the indexed Timer module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescalerAssignment in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_PrescalerEnable(MY_TMR_INSTANCE); 5.6.24.5.5.5 PLIB_TMR_PrescaleSelect Function C void PLIB_TMR_PrescaleSelect( TMR_MODULE_ID index, TMR_PRESCALE prescale ); Description This function selects the clock prescaler. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured prescale One of the possible values of TMR_PRESCALE Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3045 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPrescale in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_PrescaleSelect(MY_TMR_INSTANCE, TMR_PRESCALE_VALUE_8); 5.6.24.5.6 Period Control Functions 5.6.24.5.6.1 PLIB_TMR_Period16BitGet Function C uint16_t PLIB_TMR_Period16BitGet( TMR_MODULE_ID index ); Description This function gets the 16-bit period value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns period - 16-bit period value Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod16Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t period = PLIB_TMR_Period16BitGet(MY_TMR_INSTANCE); 5.6.24.5.6.2 PLIB_TMR_Period16BitSet Function C void PLIB_TMR_Period16BitSet( TMR_MODULE_ID index, uint16_t period ); Description This function sets the 16-bit period value. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3046 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured period 16-bit period register value Returns None. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod16Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. // where, MY_PERIOD_VALUE is the 16-bit value which needs to be stored in the // period register. PLIB_TMR_Period16BitSet(MY_TMR_INSTANCE, MY_PERIOD_VALUE); 5.6.24.5.6.3 PLIB_TMR_Period32BitGet Function C uint32_t PLIB_TMR_Period32BitGet( TMR_MODULE_ID index ); Description This function gets the 32-bit period value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns period - 32-bit period value Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod32Bit in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3047 Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint32_t period = PLIB_TMR_Period32BitGet(MY_TMR_INSTANCE); 5.6.24.5.6.4 PLIB_TMR_Period32BitSet Function C void PLIB_TMR_Period32BitSet( TMR_MODULE_ID index, uint32_t period ); Description This function sets the 32-bit period value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured period 32-bit period register value Returns None. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod32Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. // where, MY_PERIOD_VALUE is the 32-bit value which needs to be stored in the // period register. PLIB_TMR_Period32BitSet(MY_TMR_INSTANCE, MY_PERIOD_VALUE); 5.6.24.5.6.5 PLIB_TMR_Period8BitGet Function C uint8_t PLIB_TMR_Period8BitGet( TMR_MODULE_ID index ); Description This function gets the 8 -it period value. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3048 Parameters Parameters Description index Identifier for the device instance to be configured Returns period - 8-bit period value Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod8Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint8_t period = PLIB_TMR_Period8BitGet(MY_TMR_INSTANCE); 5.6.24.5.6.6 PLIB_TMR_Period8BitSet Function C void PLIB_TMR_Period8BitSet( TMR_MODULE_ID index, uint8_t period ); Description This function sets the 8-bit period value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured period 8-bit period value Returns None. Remarks The timer period register may be written at any time before the timer is started or after the timer is stopped. The timer period register can also be written when servicing the interrupt for the timer. When the timer is in operation, it is not recommended to write to the period register. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPeriod8Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. // where, MY_PERIOD_VALUE is the 8-bit value which needs to be stored in the // period register. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3049 PLIB_TMR_Period8BitSet(MY_TMR_INSTANCE, MY_PERIOD_VALUE); 5.6.24.5.7 Counter Control Functions 5.6.24.5.7.1 PLIB_TMR_Counter16BitClear Function C void PLIB_TMR_Counter16BitClear( TMR_MODULE_ID index ); Description This function clears the 16-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter16BitClear(MY_TMR_INSTANCE); 5.6.24.5.7.2 PLIB_TMR_Counter16BitGet Function C uint16_t PLIB_TMR_Counter16BitGet( TMR_MODULE_ID index ); Description This function gets the 16-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 16-bit timer value. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3050 Remarks PLIB_TMR_Counter16BitGet does not prevent the timer from incrementing during the same instruction cycle. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t timerValue = PLIB_TMR_Counter16BitGet(MY_TMR_INSTANCE); 5.6.24.5.7.3 PLIB_TMR_Counter16BitSet Function C void PLIB_TMR_Counter16BitSet( TMR_MODULE_ID index, uint16_t value ); Description This function sets the 16-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured value 16-bit value to be set Returns None. Remarks When the timer register is written to, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter16Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter16BitSet(MY_TMR_INSTANCE, 0x100); 5.6.24.5.7.4 PLIB_TMR_Counter32BitClear Function C void PLIB_TMR_Counter32BitClear( TMR_MODULE_ID index ); Description This function clears the 32-bit timer value. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3051 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter32BitClear(MY_TMR_INSTANCE); 5.6.24.5.7.5 PLIB_TMR_Counter32BitGet Function C uint32_t PLIB_TMR_Counter32BitGet( TMR_MODULE_ID index ); Description This function gets the 32-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 32 bit timer value. Remarks PLIB_TMR_Counter32BitGet does not prevent the timer from incrementing during the same instruction cycle. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint32_t timerValue = PLIB_TMR_Counter32BitGet(MY_TMR_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3052 5.6.24.5.7.6 PLIB_TMR_Counter32BitSet Function C void PLIB_TMR_Counter32BitSet( TMR_MODULE_ID index, uint32_t value ); Description This function sets the 32-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured value 32-bit value to be set Returns None. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter32Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter32BitSet(MY_TMR_INSTANCE, 0x1000000); 5.6.24.5.7.7 PLIB_TMR_Counter8BitClear Function C void PLIB_TMR_Counter8BitClear( TMR_MODULE_ID index ); Description This function clears the 8-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3053 Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter8Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter8BitClear(MY_TMR_INSTANCE); 5.6.24.5.7.8 PLIB_TMR_Counter8BitGet Function C uint8_t PLIB_TMR_Counter8BitGet( TMR_MODULE_ID index ); Description This function gets the 8-bit timer value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns 8-bit timer value. Remarks PLIB_TMR_Counter8BitGet does not prevent the timer from incrementing during the same instruction cycle. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter8Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint8_t timerValue = PLIB_TMR_Counter8BitGet(MY_TMR_INSTANCE); 5.6.24.5.7.9 PLIB_TMR_Counter8BitSet Function C void PLIB_TMR_Counter8BitSet( TMR_MODULE_ID index, uint8_t value ); Description This function sets the 8-bit timer value. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3054 Parameters Parameters Description index Identifier for the device instance to be configured value 8-bit value to be set Returns None. Remarks When the timer register is written, the timer increment does not occur for that cycle. Writes to the timer register in the asynchronous counter mode should be avoided. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounter8Bit in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_Counter8BitSet(MY_TMR_INSTANCE, 0x10); 5.6.24.5.7.10 PLIB_TMR_CounterAsyncWriteDisable Function C void PLIB_TMR_CounterAsyncWriteDisable( TMR_MODULE_ID index ); Description This function disables the writes to the counter register until the pending write operation completes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounterAsyncWriteControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_CounterAsyncWriteDisable(MY_TMR_INSTANCE); 5.6.24.5.7.11 PLIB_TMR_CounterAsyncWriteEnable Function C void PLIB_TMR_CounterAsyncWriteEnable( TMR_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3055 Description This function enables back-to-back writes with legacy asynchronous timer functionality . Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounterAsyncWriteControl in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_CounterAsyncWriteEnable(MY_TMR_INSTANCE); 5.6.24.5.7.12 PLIB_TMR_CounterAsyncWriteInProgress Function C bool PLIB_TMR_CounterAsyncWriteInProgress( TMR_MODULE_ID index ); Description This function returns the status of the counter write in Asynchronous mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Write is in progress • false - Write is complete Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsCounterAsyncWriteInProgress in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool inProgress = PLIB_TMR_CounterAsyncWriteInProgress(MY_TMR_INSTANCE); 5.6.24.5.8 Post-processing Functions 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3056 5.6.24.5.8.1 PLIB_TMR_PostscaleDivisorGet Function C uint16_t PLIB_TMR_PostscaleDivisorGet( TMR_MODULE_ID index, TMR_POSTSCALE postscale ); Description This function gets the postscaler divisor information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured postscale One of the possible values of TMR_POSTSCALE Returns Postscaler divisor value. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPostscale in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint16_t div = PLIB_TMR_PostscaleDivisorGet (MY_TMR_INSTANCE, TMR_POSTSCALE_1_TO_16); 5.6.24.5.8.2 PLIB_TMR_PostscaleGet Function C TMR_POSTSCALE PLIB_TMR_PostscaleGet( TMR_MODULE_ID index ); Description This function gets the postscaler divisor information. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns One of the possible values of TMR_POSTSCALE. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPostscale in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3057 Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. TMR_POSTSCALE postscale; postscale = PLIB_TMR_PostscaleGet (MY_TMR_INSTANCE); 5.6.24.5.8.3 PLIB_TMR_PostscaleSelect Function C void PLIB_TMR_PostscaleSelect( TMR_MODULE_ID index, TMR_POSTSCALE postscale ); Description This function selects the output clock postscaler. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured postscale One of the possible values of TMR_POSTSCALE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsPostscale in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. PLIB_TMR_PostscaleSelect(MY_TMR_INSTANCE, TMR_POSTSCALE_1_TO_1); 5.6.24.5.9 Miscellaneous Functions 5.6.24.5.9.1 PLIB_TMR_IsPeriodMatchBased Function C bool PLIB_TMR_IsPeriodMatchBased( TMR_MODULE_ID index ); Description This function gets the operating mode state of the Timer module based on Period Match or Overflow mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3058 Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Operation in Period Match mode • false - Operation in Overflow mode Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsTimerOperationMode in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. bool status = PLIB_TMR_IsPeriodMatchBased(MY_TMR_INSTANCE); 5.6.24.5.9.2 PLIB_TMR_SystemClockFromTimerIsActive Function C bool PLIB_TMR_SystemClockFromTimerIsActive( TMR_MODULE_ID index ); Description This function gets the system clock derivation status. When the function returns true, the system and peripheral clocks are sourced from the timer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - System/Device Clock is derived from the timer • false - System/Device Clock is from another source Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_TMR_ExistsSystemClockStatus in your application to determine whether this feature is available. Example // Where MY_TMR_INSTANCE, is the timer instance selected for use by the // application developer. uint8_t status = PLIB_TMR_SystemClockFromTimerIsActive(MY_TMR_INSTANCE); 5.6.24.5.10 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3059 5.6.24.5.10.1 TMR_ASSIGNMENT Enumeration C typedef enum { TMR_ASSIGNMENT_T1_TO_CCP_ALL, TMR_ASSIGNMENT_T3_TO_CCP2_T1_TO_CCP1, TMR_ASSIGNMENT_T3_TO_CCP_ALL } TMR_ASSIGNMENT; Description TMR assignment to modules definition This data type defines the Timer assignment to modules. Members Members Description TMR_ASSIGNMENT_T1_TO_CCP_ALL Timer1 is the capture/compare clock source for the CCP modules TMR_ASSIGNMENT_T3_TO_CCP2_T1_TO_CCP1 Timer3 is the capture/compare clock source for CCP2 & Timer1 is the capture/compare clock source for CCP1 TMR_ASSIGNMENT_T3_TO_CCP_ALL Timer3 is the capture/compare clock source for the CCP modules Remarks None. 5.6.24.5.10.2 TMR_CLOCK_SOURCE Enumeration C typedef enum { TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK, TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN } TMR_CLOCK_SOURCE; Description Clock sources selection enumeration This data type defines the different clock sources. Members Members Description TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK Clock source is the internal clock = FOSC/n (where n, is processor specific) TMR_CLOCK_SOURCE_EXTERNAL_INPUT_PIN Clock source is the external input pin Remarks None. 5.6.24.5.10.3 TMR_CLOCK_SOURCE_EDGE Enumeration C typedef enum { TMR_CLOCK_SOURCE_EDGE_INCREMENT_ON_LOW_TO_HIGH, TMR_CLOCK_SOURCE_EDGE_INCREMENT_ON_HIGH_TO_LOW } TMR_CLOCK_SOURCE_EDGE; Description Source edge selection enumeration 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3060 This data type defines the different source edges. Members Members Description TMR_CLOCK_SOURCE_EDGE_INCREMENT_ON_LOW_TO_HIGH Source edge - increment on low to high edge TMR_CLOCK_SOURCE_EDGE_INCREMENT_ON_HIGH_TO_LOW Source edge - increment on high to low edge Remarks None. 5.6.24.5.10.4 TMR_GATE_POLARITY Enumeration C typedef enum { TMR_GATE_POLARITY_ACTIVE_HIGH, TMR_GATE_POLARITY_ACTIVE_LOW } TMR_GATE_POLARITY; Description Gate polarity selection enumeration This data type defines the different gate polarities. Members Members Description TMR_GATE_POLARITY_ACTIVE_HIGH Gate Polarity - Active High TMR_GATE_POLARITY_ACTIVE_LOW Gate Polarity - Active Low Remarks None. 5.6.24.5.10.5 TMR_GATE_SOURCE Enumeration C typedef enum { TMR_GATE_SOURCE_T1_GATE, TMR_GATE_SOURCE_T0_OVERFLOW, TMR_GATE_SOURCE_CMP1_SYNC_OUTPUT, TMR_GATE_SOURCE_CMP2_SYNC_OUTPUT } TMR_GATE_SOURCE; Description Gate Source selection enumeration This data type defines the different gate source selections. Members Members Description TMR_GATE_SOURCE_T1_GATE Timer1 Gate pin TMR_GATE_SOURCE_T0_OVERFLOW Timer0 overflow output TMR_GATE_SOURCE_CMP1_SYNC_OUTPUT Comparator 1 optionally synchronized output TMR_GATE_SOURCE_CMP2_SYNC_OUTPUT Comparator 2 optionally synchronized output 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3061 Remarks None. 5.6.24.5.10.6 TMR_MODULE_ID Enumeration C typedef enum { TMR_ID_0, TMR_ID_1, TMR_ID_2, TMR_ID_3, TMR_ID_4, TMR_ID_5, TMR_ID_6, TMR_ID_7, TMR_ID_8, TMR_ID_9, TMR_NUMBER_OF_MODULES } TMR_MODULE_ID; Description TMR Module ID This enumeration identifies the available Timer modules. Members Members Description TMR_ID_0 Timer 0 TMR_ID_1 Timer 1 TMR_ID_2 Timer 2 TMR_ID_3 Timer 3 TMR_ID_4 Timer 4 TMR_ID_5 Timer 5 TMR_ID_6 Timer 6 TMR_ID_7 Timer 7 TMR_ID_8 Timer 8 TMR_ID_9 Timer 9 TMR_NUMBER_OF_MODULES Max number of timers Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. Not all modules will be available on all microcontrollers. Refer to the data sheet for the specific controller in use to determine which modules are supported. The numbers used in the enumeration values will match the numbers given in the data sheet. 5.6.24.5.10.7 TMR_POSTSCALE Enumeration C typedef enum { TMR_POSTSCALE_1_TO_1, TMR_POSTSCALE_1_TO_2, TMR_POSTSCALE_1_TO_3, TMR_POSTSCALE_1_TO_4, 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3062 TMR_POSTSCALE_1_TO_5, TMR_POSTSCALE_1_TO_6, TMR_POSTSCALE_1_TO_7, TMR_POSTSCALE_1_TO_8, TMR_POSTSCALE_1_TO_9, TMR_POSTSCALE_1_TO_10, TMR_POSTSCALE_1_TO_11, TMR_POSTSCALE_1_TO_12, TMR_POSTSCALE_1_TO_13, TMR_POSTSCALE_1_TO_14, TMR_POSTSCALE_1_TO_15, TMR_POSTSCALE_1_TO_16 } TMR_POSTSCALE; Description Postscaler Values This macro defines the list of possible postscaler values. Members Members Description TMR_POSTSCALE_1_TO_1 Timer Postscale Value 1:1 TMR_POSTSCALE_1_TO_2 Timer Postscale Value 1:2 TMR_POSTSCALE_1_TO_3 Timer Postscale Value 1:3 TMR_POSTSCALE_1_TO_4 Timer Postscale Value 1:4 TMR_POSTSCALE_1_TO_5 Timer Postscale Value 1:5 TMR_POSTSCALE_1_TO_6 Timer Postscale Value 1:6 TMR_POSTSCALE_1_TO_7 Timer Postscale Value 1:7 TMR_POSTSCALE_1_TO_8 Timer Postscale Value 1:8 TMR_POSTSCALE_1_TO_9 Timer Postscale Value 1:9 TMR_POSTSCALE_1_TO_10 Timer Postscale Value 1:10 TMR_POSTSCALE_1_TO_11 Timer Postscale Value 1:11 TMR_POSTSCALE_1_TO_12 Timer Postscale Value 1:12 TMR_POSTSCALE_1_TO_13 Timer Postscale Value 1:13 TMR_POSTSCALE_1_TO_14 Timer Postscale Value 1:14 TMR_POSTSCALE_1_TO_15 Timer Postscale Value 1:15 TMR_POSTSCALE_1_TO_16 Timer0 Prescaler Value 1:16 5.6.24.5.10.8 TMR_PRESCALE Enumeration C typedef enum { TMR_PRESCALE_1_TO_1, TMR_PRESCALE_1_TO_8, TMR_PRESCALE_1_TO_64, TMR_PRESCALE_1_TO_256, TMR_PRESCALE_VALUE_1, TMR_PRESCALE_VALUE_2, TMR_PRESCALE_VALUE_4, TMR_PRESCALE_VALUE_8, TMR_PRESCALE_VALUE_16, TMR_PRESCALE_VALUE_32, TMR_PRESCALE_VALUE_64, TMR_PRESCALE_VALUE_256 } TMR_PRESCALE; 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3063 Description Prescaler Values This macro defines the list of possible prescaler values. Members Members Description TMR_PRESCALE_1_TO_1 Timer Prescaler Value 1:1 TMR_PRESCALE_1_TO_8 Timer Prescaler Value 1:8 TMR_PRESCALE_1_TO_64 Timer Prescaler Value 1:64 TMR_PRESCALE_1_TO_256 Timer Prescaler Value 1:256 TMR_PRESCALE_VALUE_1 Timer Prescaler Value 1:1 TMR_PRESCALE_VALUE_2 Timer Prescaler Value 1:2 TMR_PRESCALE_VALUE_4 Timer Prescaler Value 1:4 TMR_PRESCALE_VALUE_8 Timer Prescaler Value 1:8 TMR_PRESCALE_VALUE_16 Timer Prescaler Value 1:16 TMR_PRESCALE_VALUE_32 Timer Prescaler Value 1:32 TMR_PRESCALE_VALUE_64 Timer Prescaler Value 1:64 TMR_PRESCALE_VALUE_256 Timer Prescaler Value 1:256 5.6.24.5.11 Feature Existence Functions 5.6.24.5.11.1 PLIB_TMR_ExistsClockSource Function C bool PLIB_TMR_ExistsClockSource( TMR_MODULE_ID index ); Description This function identifies whether the ClockSource feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_ClockSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockSource feature is supported on the device • false - The ClockSource feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3064 5.6.24.5.11.2 PLIB_TMR_ExistsClockSourceEdge Function C bool PLIB_TMR_ExistsClockSourceEdge( TMR_MODULE_ID index ); Description This function identifies whether the ClockSourceEdge feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_ClockSourceEdgeSelect • PLIB_TMR_ClockSourceEdgeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockSourceEdge feature is supported on the device • false - The ClockSourceEdge feature is not supported on the device Remarks None. 5.6.24.5.11.3 PLIB_TMR_ExistsClockSourceSync Function C bool PLIB_TMR_ExistsClockSourceSync( TMR_MODULE_ID index ); Description This function identifies whether the ClockSourceSync feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_ClockSourceExternalSyncEnable • PLIB_TMR_ClockSourceExternalSyncDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ClockSourceSync feature is supported on the device • false - The ClockSourceSync feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3065 Remarks None. 5.6.24.5.11.4 PLIB_TMR_ExistsCounter16Bit Function C bool PLIB_TMR_ExistsCounter16Bit( TMR_MODULE_ID index ); Description This function identifies whether the Counter16Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Counter16BitSet • PLIB_TMR_Counter16BitGet • PLIB_TMR_Counter16BitClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Counter16Bit feature is supported on the device • false - The Counter16Bit feature is not supported on the device Remarks None. 5.6.24.5.11.5 PLIB_TMR_ExistsCounter32Bit Function C bool PLIB_TMR_ExistsCounter32Bit( TMR_MODULE_ID index ); Description This function identifies whether the Counter32Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Counter32BitSet • PLIB_TMR_Counter32BitGet • PLIB_TMR_Counter32BitClear Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3066 Parameters Parameters Description index Identifier for the device instance Returns • true - The Counter32Bit feature is supported on the device • false - The Counter32Bit feature is not supported on the device Remarks None. 5.6.24.5.11.6 PLIB_TMR_ExistsCounter8Bit Function C bool PLIB_TMR_ExistsCounter8Bit( TMR_MODULE_ID index ); Description This function identifies whether the Counter8bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Counter8BitSet • PLIB_TMR_Counter8BitGet • PLIB_TMR_Counter8BitClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Counter8bit feature is supported on the device • false - The Counter8bit feature is not supported on the device Remarks None. 5.6.24.5.11.7 PLIB_TMR_ExistsCounterAsyncWriteControl Function C bool PLIB_TMR_ExistsCounterAsyncWriteControl( TMR_MODULE_ID index ); Description This function identifies whether the CounterAsyncWriteControl feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_CounterAsyncWriteEnable 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3067 • PLIB_TMR_CounterAsyncWriteDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CounterAsyncWriteControl feature is supported on the device • false - The CounterAsyncWriteControl feature is not supported on the device Remarks None. 5.6.24.5.11.8 PLIB_TMR_ExistsCounterAsyncWriteInProgress Function C bool PLIB_TMR_ExistsCounterAsyncWriteInProgress( TMR_MODULE_ID index ); Description This function identifies whether the CounterAsyncWriteInProgress feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_CounterAsyncWriteInProgress Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CounterAsyncWriteInProgress feature is supported on the device • false - The CounterAsyncWriteInProgress feature is not supported on the device Remarks None. 5.6.24.5.11.9 PLIB_TMR_ExistsCountMode Function C bool PLIB_TMR_ExistsCountMode( TMR_MODULE_ID index ); Description This function identifies whether the CountMode feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_ContinousCountModeEnable 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3068 • PLIB_TMR_SingleShotModeEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The CountMode feature is supported on the device • false - The CountMode feature is not supported on the device Remarks None. 5.6.24.5.11.10 PLIB_TMR_ExistsEnableControl Function C bool PLIB_TMR_ExistsEnableControl( TMR_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Start • PLIB_TMR_Stop Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.24.5.11.11 PLIB_TMR_ExistsGateCurrentState Function C bool PLIB_TMR_ExistsGateCurrentState( TMR_MODULE_ID index ); Description This function identifies whether the GateCurrentState feature is available on the Timer module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3069 • PLIB_TMR_GateCurrentStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GateCurrentState feature is supported on the device • false - The GateCurrentState feature is not supported on the device Remarks None. 5.6.24.5.11.12 PLIB_TMR_ExistsGatedTimeAccumulation Function C bool PLIB_TMR_ExistsGatedTimeAccumulation( TMR_MODULE_ID index ); Description This function identifies whether the GatedTimeAccumulation feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_GateEnable • PLIB_TMR_GateDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GatedTimeAccumulation feature is supported on the device • false - The GatedTimeAccumulation feature is not supported on the device Remarks None. 5.6.24.5.11.13 PLIB_TMR_ExistsGatePolarity Function C bool PLIB_TMR_ExistsGatePolarity( TMR_MODULE_ID index ); Description This function identifies whether the GatePolarity feature is available on the Timer module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3070 • PLIB_TMR_GatePolaritySelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GatePolarity feature is supported on the device • false - The GatePolarity feature is not supported on the device Remarks None. 5.6.24.5.11.14 PLIB_TMR_ExistsGateSinglePulseAcqusition Function C bool PLIB_TMR_ExistsGateSinglePulseAcqusition( TMR_MODULE_ID index ); Description This function identifies whether the GateSinglePulseAcquisition feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_GateSinglePulseAcquisitionStart • PLIB_TMR_GateSinglePulseAcquisitionHasCompleted Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GateSinglePulseAcquisition feature is supported on the device • false - The GateSinglePulseAcquisition feature is not supported on the device Remarks None. 5.6.24.5.11.15 PLIB_TMR_ExistsGateSinglePulseMode Function C bool PLIB_TMR_ExistsGateSinglePulseMode( TMR_MODULE_ID index ); Description This function identifies whether the GateSinglePulseMode feature is available on the Timer module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3071 • PLIB_TMR_GateSinglePulseModeEnable • PLIB_TMR_GateSinglePulseModeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GateSinglePulseMode feature is supported on the device • false - The GateSinglePulseMode feature is not supported on the device Remarks None. 5.6.24.5.11.16 PLIB_TMR_ExistsGateSource Function C bool PLIB_TMR_ExistsGateSource( TMR_MODULE_ID index ); Description This function identifies whether the GateSource feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_GateSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GateSource feature is supported on the device • false - The GateSource feature is not supported on the device Remarks None. 5.6.24.5.11.17 PLIB_TMR_ExistsGateToggleMode Function C bool PLIB_TMR_ExistsGateToggleMode( TMR_MODULE_ID index ); Description This function identifies whether the GateToggleMode feature is available on the Timer module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3072 • PLIB_TMR_GateToggleModeEnable • PLIB_TMR_GateToggleModeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GateToggleMode feature is supported on the device • false - The GateToggleMode feature is not supported on the device Remarks None. 5.6.24.5.11.18 PLIB_TMR_ExistsMode16Bit Function C bool PLIB_TMR_ExistsMode16Bit( TMR_MODULE_ID index ); Description This function identifies whether the Mode16Bit feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_Mode16BitEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Mode16Bit feature is supported on the device • false - The Mode16Bit feature is not supported on the device Remarks None. 5.6.24.5.11.19 PLIB_TMR_ExistsMode32Bit Function C bool PLIB_TMR_ExistsMode32Bit( TMR_MODULE_ID index ); Description This function identifies whether the Mode32Bit feature is available on the Timer module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3073 • PLIB_TMR_Mode32BitEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Mode32Bit feature is supported on the device • false - The Mode32Bit feature is not supported on the device Remarks None. 5.6.24.5.11.20 PLIB_TMR_ExistsMode8Bit Function C bool PLIB_TMR_ExistsMode8Bit( TMR_MODULE_ID index ); Description This function identifies whether the Mode8Bit feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_Mode8BitEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Mode8Bit feature is supported on the device • false - The Mode8Bit feature is not supported on the device Remarks None. 5.6.24.5.11.21 PLIB_TMR_ExistsOperationInSleep Function C bool PLIB_TMR_ExistsOperationInSleep( TMR_MODULE_ID index ); Description This function identifies whether the OperationInSleep feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_OperateInSleepEnable 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3074 • PLIB_TMR_OperateInSleepDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OperationInSleep feature is supported on the device • false - The OperationInSleep feature is not supported on the device Remarks None. 5.6.24.5.11.22 PLIB_TMR_ExistsPeriod16Bit Function C bool PLIB_TMR_ExistsPeriod16Bit( TMR_MODULE_ID index ); Description This function identifies whether the Period16Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Period16BitSet • PLIB_TMR_Period16BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Period16Bit feature is supported on the device • false - The Period16Bit feature is not supported on the device Remarks None. 5.6.24.5.11.23 PLIB_TMR_ExistsPeriod32Bit Function C bool PLIB_TMR_ExistsPeriod32Bit( TMR_MODULE_ID index ); Description This function identifies whether the Period32Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3075 • PLIB_TMR_Period32BitSet • PLIB_TMR_Period32BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Period32Bit feature is supported on the device • false - The Period32Bit feature is not supported on the device Remarks None. 5.6.24.5.11.24 PLIB_TMR_ExistsPeriod8Bit Function C bool PLIB_TMR_ExistsPeriod8Bit( TMR_MODULE_ID index ); Description This function identifies whether the Period8Bit feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_Period8BitSet • PLIB_TMR_Period8BitGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Period8Bit feature is supported on the device • false - The Period8Bit feature is not supported on the device Remarks None. 5.6.24.5.11.25 PLIB_TMR_ExistsPostscale Function C bool PLIB_TMR_ExistsPostscale( TMR_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3076 Description This function identifies whether the Postscale feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_PostscaleSelect • PLIB_TMR_PostscaleGet • PLIB_TMR_PostscaleDivisorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Postscale feature is supported on the device • false - The Postscale feature is not supported on the device Remarks None. 5.6.24.5.11.26 PLIB_TMR_ExistsPrescale Function C bool PLIB_TMR_ExistsPrescale( TMR_MODULE_ID index ); Description This function identifies whether the Prescale feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_PrescaleSelect • PLIB_TMR_PrescaleGet • PLIB_TMR_PrescaleDivisorGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Prescale feature is supported on the device • false - The Prescale feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3077 5.6.24.5.11.27 PLIB_TMR_ExistsPrescalerAssignment Function C bool PLIB_TMR_ExistsPrescalerAssignment( TMR_MODULE_ID index ); Description This function identifies whether the PrescalerControl feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_PrescalerEnable • PLIB_TMR_PrescalerDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PrescalerControl feature is supported on the device • false - The PrescalerControl feature is not supported on the device Remarks None. 5.6.24.5.11.28 PLIB_TMR_ExistsStopInIdleControl Function C bool PLIB_TMR_ExistsStopInIdleControl( TMR_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_StopInIdleEnable • PLIB_TMR_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3078 Remarks None. 5.6.24.5.11.29 PLIB_TMR_ExistsSystemClockStatus Function C bool PLIB_TMR_ExistsSystemClockStatus( TMR_MODULE_ID index ); Description This function identifies whether the SystemClockStatus feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_SystemClockFromTimerIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SystemClockStatus feature is supported on the device • false - The SystemClockStatus feature is not supported on the device Remarks None. 5.6.24.5.11.30 PLIB_TMR_ExistsTimerAssignment Function C bool PLIB_TMR_ExistsTimerAssignment( TMR_MODULE_ID index ); Description This function identifies whether the TimerAssignment feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_AssignmentSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TimerAssignment feature is supported on the device • false - The TimerAssignment feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3079 Remarks None. 5.6.24.5.11.31 PLIB_TMR_ExistsTimerOperationMode Function C bool PLIB_TMR_ExistsTimerOperationMode( TMR_MODULE_ID index ); Description This function identifies whether the TimerOperationMode feature is available on the Timer module. When this function returns true, this function is supported on the device: • PLIB_TMR_IsPeriodMatchBased Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TimerOperationMode feature is supported on the device • false - The TimerOperationMode feature is not supported on the device Remarks None. 5.6.24.5.11.32 PLIB_TMR_ExistsTimerOscillator Function C bool PLIB_TMR_ExistsTimerOscillator( TMR_MODULE_ID index ); Description This function identifies whether the TimerOscillator feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_TimerOscillatorEnable • PLIB_TMR_TimerOscillatorDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TimerOscillator feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3080 • false - The TimerOscillator feature is not supported on the device Remarks None. 5.6.24.5.11.33 PLIB_TMR_ExistsTriggerEventReset Function C bool PLIB_TMR_ExistsTriggerEventReset( TMR_MODULE_ID index ); Description This function identifies whether the TriggerEventReset feature is available on the Timer module. When this function returns true, these functions are supported on the device: • PLIB_TMR_TriggerEventResetEnable • PLIB_TMR_TriggerEventResetDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TriggerEventReset feature is supported on the device • false - The TriggerEventReset feature is not supported on the device Remarks None. 5.6.24.6 Files Files Name Description plib_tmr.h Timer Peripheral Library interface header. Description 5.6.24.6.1 plib_tmr.h Timer Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Timer Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3081 Functions Name Description PLIB_TMR_AssignmentSelect Assigns the specified Timer(s) to the selected modules. PLIB_TMR_ClockSourceEdgeGet Gets the source edge information. PLIB_TMR_ClockSourceEdgeSelect Selects the input clock source edge. PLIB_TMR_ClockSourceExternalSyncDisable Disables the clock synchronization of the external input. PLIB_TMR_ClockSourceExternalSyncEnable Enables the clock synchronization of the external input. PLIB_TMR_ClockSourceSelect Selects the clock source. PLIB_TMR_ContinousCountModeEnable Enables Continous Count mode PLIB_TMR_Counter16BitClear Clears the 16-bit timer value. PLIB_TMR_Counter16BitGet Gets the 16-bit timer value. PLIB_TMR_Counter16BitSet Sets the 16-bit timer value. PLIB_TMR_Counter32BitClear Clears the 32-bit timer value. PLIB_TMR_Counter32BitGet Gets the 32-bit timer value. PLIB_TMR_Counter32BitSet Sets the 32-bit timer value. PLIB_TMR_Counter8BitClear Clears the 8-bit timer value. PLIB_TMR_Counter8BitGet Gets the 8-bit timer value. PLIB_TMR_Counter8BitSet Sets the 8-bit timer value. PLIB_TMR_CounterAsyncWriteDisable Disables the writes to the counter register until the pending write operation completes. PLIB_TMR_CounterAsyncWriteEnable Enables back-to-back writes with legacy asynchronous timer functionality. PLIB_TMR_CounterAsyncWriteInProgress Returns the status of the counter write in Asynchronous mode. PLIB_TMR_ExistsClockSource Identifies whether the ClockSource feature exists on the Timer module. PLIB_TMR_ExistsClockSourceEdge Identifies whether the ClockSourceEdge feature exists on the Timer module. PLIB_TMR_ExistsClockSourceSync Identifies whether the ClockSourceSync feature exists on the Timer module. PLIB_TMR_ExistsCounter16Bit Identifies whether the Counter16Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter32Bit Identifies whether the Counter32Bit feature exists on the Timer module. PLIB_TMR_ExistsCounter8Bit Identifies whether the Counter8bit feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteControl Identifies whether the CounterAsyncWriteControl feature exists on the Timer module. PLIB_TMR_ExistsCounterAsyncWriteInProgress Identifies whether the CounterAsyncWriteInProgress feature exists on the Timer module. PLIB_TMR_ExistsCountMode Identifies whether the CountMode feature exists on the Timer module. PLIB_TMR_ExistsEnableControl Identifies whether the EnableControl feature exists on the Timer module. PLIB_TMR_ExistsGateCurrentState Identifies whether the GateCurrentState feature exists on the Timer module. PLIB_TMR_ExistsGatedTimeAccumulation Identifies whether the GatedTimeAccumulation feature exists on the Timer module. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3082 PLIB_TMR_ExistsGatePolarity Identifies whether the GatePolarity feature exists on the Timer module. PLIB_TMR_ExistsGateSinglePulseAcqusition Identifies whether the GateSinglePulseAcquisition feature exists on the Timer module. PLIB_TMR_ExistsGateSinglePulseMode Identifies whether the GateSinglePulseMode feature exists on the Timer module. PLIB_TMR_ExistsGateSource Identifies whether the GateSource feature exists on the Timer module. PLIB_TMR_ExistsGateToggleMode Identifies whether the GateToggleMode feature exists on the Timer module. PLIB_TMR_ExistsMode16Bit Identifies whether the Mode16Bit feature exists on the Timer module. PLIB_TMR_ExistsMode32Bit Identifies whether the Mode32Bit feature exists on the Timer module. PLIB_TMR_ExistsMode8Bit Identifies whether the Mode8Bit feature exists on the Timer module. PLIB_TMR_ExistsOperationInSleep Identifies whether the OperationInSleep feature exists on the Timer module. PLIB_TMR_ExistsPeriod16Bit Identifies whether the Period16Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod32Bit Identifies whether the Period32Bit feature exists on the Timer module. PLIB_TMR_ExistsPeriod8Bit Identifies whether the Period8Bit feature exists on the Timer module. PLIB_TMR_ExistsPostscale Identifies whether the Postscale feature exists on the Timer module. PLIB_TMR_ExistsPrescale Identifies whether the Prescale feature exists on the Timer module. PLIB_TMR_ExistsPrescalerAssignment Identifies whether the PrescalerControl feature exists on the Timer module. PLIB_TMR_ExistsStopInIdleControl Identifies whether the StopInIdle feature exists on the Timer module. PLIB_TMR_ExistsSystemClockStatus Identifies whether the SystemClockStatus feature exists on the Timer module. PLIB_TMR_ExistsTimerAssignment Identifies whether the TimerAssignment feature exists on the Timer module. PLIB_TMR_ExistsTimerOperationMode Identifies whether the TimerOperationMode feature exists on the Timer module. PLIB_TMR_ExistsTimerOscillator Identifies whether the TimerOscillator feature exists on the Timer module. PLIB_TMR_ExistsTriggerEventReset Identifies whether the TriggerEventReset feature exists on the Timer module. PLIB_TMR_GateCurrentStateGet Returns the current level of the timer gate. PLIB_TMR_GateDisable Enables counting regardless of the corresponding timer gate function. PLIB_TMR_GateEnable Enables counting controlled by the corresponding gate function. PLIB_TMR_GatePolaritySelect Selects the timer gate polarity. PLIB_TMR_GateSinglePulseAcquisitionHasCompleted Returns the gate single pulse acquisition status. PLIB_TMR_GateSinglePulseAcquisitionStart Starts the gate single pulse acquisition. PLIB_TMR_GateSinglePulseModeDisable Disables Single Pulse mode. 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3083 PLIB_TMR_GateSinglePulseModeEnable Enables Single pulse mode and the controlling corresponding timer gate. PLIB_TMR_GateSourceSelect Selects the timer gate source. PLIB_TMR_GateToggleModeDisable Disables the Gate Toggle mode. PLIB_TMR_GateToggleModeEnable Enables the Gate Toggle mode. PLIB_TMR_IsPeriodMatchBased Gets the operating mode state of the Timer module based on Period Match or Overflow mode. PLIB_TMR_Mode16BitEnable Enables the Timer module for 16-bit operation and disables all other modes. PLIB_TMR_Mode32BitEnable Enables 32-bit operation on the Timer module combination. PLIB_TMR_Mode8BitEnable Enables the Timer module in 8-bit operation mode and disables 16-bit mode. PLIB_TMR_OperateInSleepDisable Disables Timer module operation when the device is in Sleep mode. PLIB_TMR_OperateInSleepEnable Enables Timer module operation when the device is in Sleep mode. PLIB_TMR_Period16BitGet Gets the 16-bit period value. PLIB_TMR_Period16BitSet Sets the 16-bit period value. PLIB_TMR_Period32BitGet Gets the 32-bit period value. PLIB_TMR_Period32BitSet Sets the 32-bit period value. PLIB_TMR_Period8BitGet Gets the 8-bit period value. PLIB_TMR_Period8BitSet Sets the 8-bit period value. PLIB_TMR_PostscaleDivisorGet Gets the postscaler divisor information. PLIB_TMR_PostscaleGet Gets the postscaler divisor information. PLIB_TMR_PostscaleSelect Selects the output clock postscaler. PLIB_TMR_PrescaleDivisorGet Gets the prescaler divisor information. PLIB_TMR_PrescaleGet Gets the prescaler information. PLIB_TMR_PrescalerDisable Disables the prescaler assignment to the indexed Timer module. PLIB_TMR_PrescalerEnable Enables the prescaler assignment to the indexed Timer module. PLIB_TMR_PrescaleSelect Selects the clock prescaler. PLIB_TMR_SingleShotModeEnable Enables Single-shot mode. PLIB_TMR_Start Starts/enables the indexed timer. PLIB_TMR_Stop Stops/disables the indexed timer. PLIB_TMR_StopInIdleDisable Continue module operation when the device enters Idle mode. PLIB_TMR_StopInIdleEnable Discontinues module operation when the device enters Idle mode. PLIB_TMR_SystemClockFromTimerIsActive Gets the system clock status. PLIB_TMR_TimerOscillatorDisable Disables the oscillator associated with the Timer module. PLIB_TMR_TimerOscillatorEnable Enables the oscillator associated with the Timer module. PLIB_TMR_TriggerEventResetDisable Disables the special event trigger reset. PLIB_TMR_TriggerEventResetEnable Enables the special event trigger reset. File Name plib_tmr.h 5.6 Peripheral Library Help MPLAB Harmony Help Timer Peripheral Library 5-3084 Company Microchip Technology Inc. 5.6.25 USART Peripheral Library 5.6.25.1 Introduction USART Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the USART Peripheral Library on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description Overview The Universal Synchronous/Asynchronous Receiver/Transmitter (USART) module is the key component of the serial communications sub-system of a computer. The USART takes the data and transmits the individual bits in a sequential fashion. While receiving, the USART reassembles the bits into complete bytes. The data can be 8-bit or 9-bit. There are two primary forms of serial transmission: Asynchronous and Synchronous. Asynchronous Asynchronous transmission allows data to be transmitted without the sender having to send a clock signal to the receiver. Instead, the sender and receiver must agree on timing parameters (i.e., baud rate) in advance and special bits are added to each word, which are used to synchronize the sending and receiving units. When a word is given to the USART for asynchronous transmissions, a bit called the "Start" bit is added to the beginning of each word that is to be transmitted. The Start bit is used to alert the receiver that a word of data is about to be sent. After the Start bit, the individual bits of the word of data are sent, with the Least Significant bit (LSb) being sent first. When the entire data word has been sent, the transmitter may add a Parity bit that the transmitter generates. The Parity bit may be used by the receiver to perform simple error checking. Then, at least one Stop bit is sent by the transmitter. The Start bit is always a space and the Stop bits are always marks. Each transmitted bit persists for a period of 1/(Baud Rate). An on-chip dedicated Baud Rate Generator (BRG) is used to derive standard baud rate frequencies. When the receiver has received all of the bits in the data word, it may check for the Parity bits (both sender and receiver must agree on whether a Parity bit is to be used), and then the receiver looks for a Stop bit. If the Stop bit does not appear when it is supposed to, the USART module considers the entire word to be unintelligible and will report a framing error to the host processor when the data word is read. Note: Please refer to the the specific device data sheet or the related family reference manual section for details. Synchronous Synchronous serial transmission requires that the sender and receiver share a clock with one another, or that the sender provide a strobe or other timing signal so that the receiver knows when to “read” the next bit of the data. This mode is not available on all microcontrollers. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3085 It is typically used in systems with a single master and one or more slaves. The master device contains the necessary circuitry for baud rate generation and supplies the clock for all devices in the system. There are two signal lines a bidirectional data line and a clock line. Since the data line is bidirectional, synchronous operation is only half-duplex. Start and Stop bits are not used in synchronous transmissions. 5.6.25.2 Release Notes MPLAB Harmony Version: v0.70b USART Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.25.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6.25.4 Using the Library This topic describes the basic architecture of the USART Peripheral Library and provides information and examples on how to use it. Interface Header File: peripheral.h The interface to the USART Peripheral library is defined in the "plib_usart.h" header file. Any C language source (.c) file that uses the USART Peripheral library should include "peripheral.h". Library File: The USART Peripheral library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3086 5.6.25.4.1 Hardware Abstraction Model This section describes the hardware abstraction model. Description Hardware Abstraction Model Hardware Abstraction Model The USART Peripheral Library provides interface routines to interact with the blocks shown in the diagram. The Baud Rate Controller controls the timing in Asynchronous mode, the desired baud rate can be programmed in the baud rate controller or, the baud rate controller can be configured to determine the baud rate of the transmitting device automatically. The Transmitter and Receiver are capable of handling 8-bit or 9-bit data, which can be programmed in the control logic. The 9th bit is used to transfer the address or the parity. Enable 9-bit mode if the hardware is to be used for address or parity detection. The Status and Control logic, provide the ability to control different ways the transmitter, receiver, and the baud rate controller can function. It also can provides status about the transmitter, receiver, or the baud rate controller. The Hardware Flow Control uses CTS and the RTS lines to perform handshaking. Flow control is the ability to stop, and then restart the flow without any loss of bytes. Flow control is needed for modems and other hardware to allow a jump in instantaneous flow rates. Note: This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. The USART module provides two types of infrared USART support: one is the IrDA clock output to support the external IrDA encoder and decoder, and the other is the full implementation of the IrDA encoder and decoder. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3087 Note: This feature is not available on all devices. Please refer to the specific device data sheet to determine availability. 5.6.25.4.2 Library Usage Model This section describes the library usage model. Description Usage Model Each of the blocks in the diagram correspond to the library interface section. Library Interface Section Description 5.6.25.4.3 How the Library Works This section provides information on using the peripheral library with the USART module. The usage model for different scenarios is also described. 5.6.25.4.3.1 State Machine This section describes the transmission and reception state machine. Description The following state machine is for the transmission and reception during normal operation. This state machine provides a general idea of the usage model of the USART Peripheral Library. Refer to the usage model for more detailed steps for the scenario that is being used. Transmit and Receive State machine 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3088 Notes: 1. The wait states shown in red in the diagram can either be achieved using polled functions or using interrupts. 2. Refer to the specific USART mode in use for the setup and initialization steps. 3. Refer to the following table for the functions that can be used at each state. State Associated Function Setup and initialization Refer to the specific USART mode for detailed setup instructions. Wait for data to send Once the USART module has been appropriately set up and initialized, the state machine waits for the application to issue one of the send data functions. Wait for data to be received When the application is using Polled mode, the application can use the function PLIB_USART_ReceiverDataIsAvailable. When the application is using Interrupt mode, the application should wait for a receive interrupt. Enable transmitter Use the function PLIB_USART_TransmitterEnable to enable the transmitter 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3089 Wait for transmitter to have empty space When the application is using polled mode, the application can use the function PLIB_USART_TransmitterBufferIsFull. When the application is using Interrupt mode, the application should wait for a transmit interrupt. Send data Use the function PLIB_USART_TransmitterByteSend to send data. If an address needs to be transmitted or if a byte needs to be transmitted with a Parity bit use the function PLIB_USART_Transmitter9BitsSend. Disable transmitter Use the function PLIB_USART_TransmitterDisable to disable the transmitter. Get status To get the status of the hardware module, use the set of functions, PLIB_USART_ReceiverFramingErrorHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverOverrunHasOccurred. Read data Use the function PLIB_USART_ReceiverByteReceive to read data. Clear overrun error Clear the overrun error using the function PLIB_USART_ReceiverOverrunErrorClear. 5.6.25.4.3.2 Asynchronous USART Mode This section provides processes for setting up asynchronous transmission and reception. Description Asynchronous Transmission Setup 1. Set the desired baud rate using either PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the transmit interrupt. • Ensure that the interrupts are enabled for the system and the peripherals • Select the interrupt priority • Set up the transmit FIFO interrupt mode using PLIB_USART_TransmitterInterruptModeSelect. Refer to USART_TRANSMIT_INTR_MODE for a list of possible values. 6. Enable the USART module using the function PLIB_USART_Enable Example: Asynchronous Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. PLIB_USART_BaudRateSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the asynchronous serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); /* Select 8 data bits, No parity and one stop bit */ PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3090 // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. Enable Transmission 1. Enable the transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full, before attempting to write into the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8-bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting an address or if transmitting a byte with parity). 4. After the transmission is complete, disable the transmitter. Example: Asynchronous Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO - Either wait for Transmit buffer to be not full or wait for //an transmit interrupt. // Transmit the byte when Transmit buffer is empty. // where, my_byte is the 8 bit data to be transmitted PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_byte); Asynchronous Transmission of Break Characters A break characters consists of a Start Bit followed by twelve bits of "0" and a Stop Bit. Setup and Transmission 1. Configure the desired mode, using the previous steps described. 2. Enable the transmitter using PLIB_USART_TransmitterEnable. 3. Transmit the break character using PLIB_USART_TransmitterBreakSend function. 4. Check if the break transmission is complete using PLIB_USART_TransmitterBreakSendIsComplete. 5. Transmission of the next bytes can start. Example: USART Break and Sync Transmission // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. PLIB_USART_BaudRateSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the asynchronous serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); /* Select 8 data bits, No parity and one stop bit */ PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3091 // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // Start the transmission // Transmit the break character PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // Transmit the byte while(PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, 0x55); Refer to the following steps for setting up asynchronous receptions and how to receive data. Asynchronous Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the receive interrupt. • Ensure that the interrupts are enabled for the system and the peripherals • Select the interrupt priority • Set up the receive FIFO interrupt mode using PLIB_USART_ReceiverInterruptModeSelect. Refer to USART_RECEIVE_INTR_MODE for a list of possible values. 6. Optional: If inverted receive polarity is desired, use PLIB_USART_ReceiverIdleStateLowEnable. 7. If available on the device, enable the reception using PLIB_USART_ReceiverEnable. 8. Enable the USART module using PLIB_USART_Enable. Example: Asynchronous Reception Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being // used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable asynchronous mode if the part supports it PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Start the reception // Enable the continuous reception PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3092 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. Example: Asynchronous Reception // TODO - Either wait for Receive buffer to have data or wait for // a receive interrupt. // read the data my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_byte is the 8 bit data received // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } Asynchronous Reception with Address Detection Mode A typical multi-processor communication protocol will differentiate between data bytes and address/control bytes. A common method is to use a 9th data bit to identify whether a data byte is address or data information. If the 9th bit is set, the data is processed as address or control information. If the 9th bit is cleared, the received data word is processed as data associated with the previous address/control byte. The protocol operates as follows: • The master device transmits a data word with 9th bit set. The data word contains the address of a slave device. • All slave devices in the communication chain receive the address word and check the slave address. • The slave device that was addressed will receive and process subsequent data bytes sent by the master device. All other slave devices will discard subsequent data bytes until a new address word(9th bit set) is received. This mode will typically be used in RS-485 systems. Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 3. If available on the device, enable the asynchronous serial port using PLIB_USART_SyncModeSelect. 4. Set the number of data bits (8 or 9) and other line control modes using PLIB_USART_LineControlModeSelect. 5. Optional (if available on the device): If desired, enable the receive interrupt. • Ensure that the interrupts are enabled for the system and the peripherals. Also select the interrupt priority. • Set up the receive FIFO interrupt mode by using the function PLIB_USART_ReceiverInterruptModeSelect. Refer to USART_RECEIVE_INTR_MODE for a list of possible values. • For Address Detect mode, configure PLIB_USART_ReceiverInterruptModeSelect with the receive FIFO interrupt mode as USART_RECEIVE_FIFO_ONE_CHAR. 6. Optional: If inverted receive polarity is desired, use PLIB_USART_ReceiverIdleStateLowEnable. 7. If available on the device, enable the reception using PLIB_USART_ReceiverEnable. 8. Enable address detection using PLIB_USART_ReceiverAddressDetectEnable. 9. Enable the USART module using PLIB_USART_Enable. Note: This feature is not available on all devices. On devices where automatic address detection is available, configure automatic address detection using PLIB_USART_AutomaticAddressDetectModeSetup. Skip steps 2-6 in the following Reception section during the reception phase. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3093 Example: Asynchronous Reception Setup ( with address detect enable) // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently // being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Set the reception to 9 bits to enable address byte. PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_9N1); // Enable address detection. PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); // Start the reception // Enable the continuous reception PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed or poll using PLIB_USART_ReceiverDataIsAvailable. 2. Read the address using PLIB_USART_ReceiverByteReceive. 3. The application determines if this is the device address. If the device is addressed, disable address detect using PLIB_USART_ReceiverAddressDetectDisable to allow subsequent data bytes to be received; otherwise, discard the received word. 4. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorHasOccurred. 5. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. 6. If the device has been addressed, disable the address detection using PLIB_USART_ReceiverAddressDetectDisable, which will allow all received data into the receive buffer and generate interrupts if desired. 7. Optional (if available on the device): If a long packet is expected, the receive interrupt mode could be changed to buffer more than one data word between interrupts. Use PLIB_USART_ReceiverInterruptModeSelect with USART_RECEIVE_FIFO_HALF_FULL or USART_RECEIVE_FIFO_3B4FULL. 8. When the last data byte has been received, enable the address detect using PLIB_USART_ReceiverAddressDetectEnable, so that only address bytes will be received. 9. Optional (if available on the device): Ensure that the receive interrupt is configured to be triggered after each received word using PLIB_USART_ReceiverInterruptModeSelect with USART_RECEIVE_FIFO_ONE_CHAR. Example: Asynchronous Reception (with Address Detect) // Either wait for Receive buffer to have data or wait for a receive interrupt. int8_t my_address; // Receive the address if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { my_address = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_address is the address received } 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3094 // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } if(my_address == MY_DEVICE_ADDRESS) { // The device has been addressed. PLIB_USART_ReceiverAddressDetectDisable(MY_USART_INSTANCE); } // TODO - Receive the data bytes for the packet. Either wait for RX buffer //to have data or wait for a receive interrupt. // When all the bytes for the packet are received. // Enable address detection mode PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); 5.6.25.4.3.3 Synchronous Master Mode This section provides processes for setting up synchronous master transmission and reception. Note: This feature is not available on all devices. Please refer to the specific device data sheet or related family reference manual to determine which features are supported for your device. Description Synchronous Master Transmission Setup 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Disable receive using PLIB_USART_ReceiverDisable. 5. Optional: If desired set the number of data bits to 9 (to send address byte or to enable parity check) using PLIB_USART_Transmitter9BitModeEnable. 6. Optional: If desired, enable the transmit interrupt, ensuring that the interrupts are enabled for the system and the peripherals. Example: Synchronous Master Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous master serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_MASTER); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO Call the appropriate function. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3095 Transmission 1. Enable transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full before attempting to write onto the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. Note: If using interrupts, make sure that interrupts are also enabled for the system and the peripherals. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8 - bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting address or if transmitting a byte with parity). 4. After the transmission is complete, disable the transmitter. Example: Synchronous Master Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO Either wait for Transmit buffer to be not full or wait for an transmit interrupt. // Transmit the byte when Transmit buffer is empty. // where, my_byte is the 8 bit data to be transmitted PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_byte); Synchronous Master Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate IO direction and corresponding to RX and TX I/O pins. 4. Optional: If desired, enable the receive interrupt, ensuring that the interrupts are enabled for the system and the peripherals. 5. Start the reception using PLIB_USART_ReceiverDisable. Example: Synchronous Master Reception Setup uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); PLIB_USART_HandshakeModeSelect(MY_USART_INSTANCE, USART_HANDSHAKE_MODE_SIMPLEX); // Enable the synchronous master serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_MASTER); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Enable receive mode PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. Note: If using interrupts, ensure that interrupts are also enabled for the system and the peripherals. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3096 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred and PLIB_USART_ReceiverFramingErrorHasOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using the function PLIB_USART_ReceiverOverrunErrorClear. Example: Synchronous Master Reception // Read the byte // where, my_byte is the 8 bit data to be transmitted my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } 5.6.25.4.3.4 Synchronous Slave Mode This section provides processes for setting up synchronous slave transmission and reception. Note: This feature is not available on all devices. Please refer to the specific device data sheet or related family reference manual to determine which features are supported for your device. Description Synchronous Slave Transmission Setup 1. Set the desired baud rate using either PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Enable the synchronous slave serial port using PLIB_USART_SyncModeSelect, PLIB_USART_ClockSourceSlaveSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Disable receive mode using PLIB_USART_ReceiverDisable. 5. Optional: If desired, enable the transmit interrupt,ensuring that the interrupts are enabled for the system and the peripherals. Example: Synchronous Slave Transmission Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware //peripheral MY_CLOCK_FREQUENCY - is hardware clock frequency which is //currently being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable slave clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_SLAVE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Disable receive mode PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); // TODO - If using interrupts Enable the transmit interrupt // TODO - Call the appropriate function for the transmit enable interrupt, 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3097 // TODO - Also, make sure that the interrupts are enabled for system and the peripherals. Transmission 1. Enable transmission using PLIB_USART_TransmitterEnable. 2. Ensure that the transmit buffer is not full before attempting to write into the transmit buffer. Either poll using PLIB_USART_TransmitterBufferIsFull or wait for the transmit interrupt. Note: If using interrupts, ensure that interrupts are also enabled for the system and the peripherals. 3. Start the transmission using PLIB_USART_TransmitterByteSend (if transmitting 8-bit data) or PLIB_USART_Transmitter9BitsSend (if transmitting address if transmitting a byte with parity) 4. After the transmission is complete, disable the transmitter. Example: Synchronous Slave Transmission // Enable the transmission PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); // TODO - Either wait for Transmit buffer to be not full or wait //for an transmit interrupt. // Transmit the byte when Transmit buffer is empty. PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, my_word); // where, my_word is the 9 bit data to be transmitted Synchronous Slave Reception Setup 1. Set the desired baud rate using PLIB_USART_BaudRateHighSet or PLIB_USART_BaudRateSet. 2. Enable the synchronous master serial port using PLIB_USART_SyncModeSelect, PLIB_USART_SyncClockSourceSelect, and PLIB_USART_Enable. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Optional: If desired, enable the receive interrupt, ensuring that the interrupts are enabled for the system and the peripherals. 5. Start the reception using PLIB_USART_ReceiverEnable. Example: Synchronous Slave Reception Setup // Set the desired baud rate uint32_t baudRate = 9600; // where, MY_USART_INSTANCE - is a specific instance of the hardware peripheral. // where, MY_CLOCK_FREQUENCY - is hardware clock frequency which is currently //being used by the system. PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, baudRate, MY_CLOCK_FREQUENCY); // Enable the synchronous slave serial port. // enable sync mode PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_SYNC_MODE); // enable master clock PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_SLAVE); // enable USART PLIB_USART_Enable(MY_USART_INSTANCE); // Set the appropriate IO direction for USART pins // TODO - Call the appropriate function. // Start the reception // Enable the continuous reception PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3098 Reception 1. Either wait for an interrupt, which will be generated when the reception is completed, or poll using PLIB_USART_ReceiverDataIsAvailable. Note: If using interrupts make sure that interrupts are also enabled for the system and the peripherals. 2. Read the status of the device using PLIB_USART_ReceiverOverrunHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred, and PLIB_USART_ReceiverFramingErrorHasOccurred. 3. Read the data using PLIB_USART_ReceiverByteReceive. 4. If an overrun error occurred, clear the error using PLIB_USART_ReceiverOverrunErrorClear. Example: Synchronous Slave Reception // Transmit the data my_byte = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); // where, my_byte is the 8 bit data received // If overrun error clear the error. if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } 5.6.25.4.3.5 Other Features This section describes additional features of the USART Peripheral Library. Note: The features described in this section are not available on all devices. Please refer to the specific device data sheet or the related family reference manual to determine which features are supported by your device. Description IrDA Support Support for IrDA is available in some microcontrollers. 1. Enable IrDA support using PLIB_USART_IrDAEnable. IrDA support can be disabled using PLIB_USART_IrDADisable. 2. Optional: If using the external IrDA encoder and decoder, use the function PLIB_USART_OperationModeSelect with USART_ENABLE_TX_RX_BCLK_USED to output the 16x baud clock. 3. Optional: IrDA Transmit Polarity can be inverted using PLIB_USART_TransmitterIdleIsLowEnable. 4. Optional: IrDA Receive Polarity can be inverted using PLIB_USART_ReceiverIdleStateLowEnable. 5. Enable the USART using PLIB_USART_Enable. Loopback Support This is the mode in which the transmission is internally connected to reception. 1. Set the desired baud rate using PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Set up the line control parameters (data bits, stop bits, parity, flow control) using PLIB_USART_LineControlModeSelect. Refer to USART_LINECONTROL_MODE for a list of possible values. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Optional: If desired, enable the transmit interrupt, also make sure that the interrupts are enabled for the system and the peripherals. 5. Optional: Also select the interrupt priority. 6. Optional: Also, set up the transmit FIFO interrupt mode using PLIB_USART_TransmitterInterruptModeSelect. Refer to USART_TRANSMIT_INTR_MODE for a list of possible values. 7. Enable the USART module using PLIB_USART_Enable and enable the transmission using PLIB_USART_TransmitterEnable. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3099 8. Enable loopback using PLIB_USART_LoopbackEnable. Loopback can be disabled at any time using PLIB_USART_LoopbackDisable 9. Continue with transmission and/or reception using the same steps as for asynchronous transmission/reception. Auto Baud Support 1. Enable the auto baud detection using the function PLIB_USART_BaudRateAutoDetectEnable, which requires a reception of the Sync character (0x55). 2. Optional: Poll PLIB_USART_BaudRateAutoDetectIsComplete to check if the baud rate is detected. 3. Optional: Call PLIB_USART_BaudRateGet to get the baud rate that was detected. 4. Clear the receive interrupt. 5. On some microcontrollers, reading the data using PLIB_USART_ReceiverByteReceive may be required. Flow Control Support The USART can use Simplex or Flow Control modes: • Use PLIB_USART_HandshakeModeSelect to enable flow control (USART_HANDSHAKE_MODE_FLOW_CONTROL) or use simplex mode (USART_HANDSHAKE_MODE_SIMPLEX) selected from USART_HANDSHAKE_MODE. • To configure the USART line control features, use PLIB_USART_LineControlModeSelect selected from USART_LINECONTROL_MODE. • Additionally, the USART pins may need to be configured using PLIB_USART_OperationModeSelect and the appropriate values from USART_OPERATION_MODE. Operation During Sleep Mode When the device enters Sleep mode, all clock sources supplied to the USART modules are shut down. If the device enters Sleep mode in the middle of a USART transmission or reception operation, the operation is aborted and the USART pins are driven to default state. A Start bit, when detected, can wake up the device. • The application needs to enable the wake-up on start bit using PLIB_USART_WakeOnStartEnable just before entering Sleep mode, to wake-up the device • For the device to wake-up from sleep, reception of the Sync character or Wake-up Signal character is required • Optional: If using interrupts, a receive interrupt is generated Operation During Idle Mode When the device enters Idle mode, the system clock sources remain functional and the CPU stops code execution. • USART operation during Idle mode can be stopped using PLIB_USART_StopInIdleEnable. When the device enters Idle mode, the USART module operation is similar to that as in Sleep mode(Refer to Operation in Sleep Mode). • By default, the USART module continues to operate in Idle mode and provide full functionality USART Operation With DMA The DMA module can be used to transfer data between the USART and the CPU, without CPU assistance. 1. Set the desired baud rate using the function PLIB_USART_BaudRateSet or PLIB_USART_BaudRateHighSet. 2. Set up the line control parameters (data bits, stop bits, parity, flow control) using the function PLIB_USART_LineControlModeSelect. Refer to USART_LINECONTROL_MODE for a list of possible values. 3. Set the appropriate I/O direction and corresponding RX and TX I/O pins. 4. Enable the USART module using PLIB_USART_Enable and enable the transmission using PLIB_USART_TransmitterEnable. 5. Enable the Transmit, Receive, and Error interrupts, ensuring that the interrupts are enabled for the system and the peripherals. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3100 6. Select the interrupt priority. 7. Set up the Transmit FIFO Interrupt mode and Receive FIFO Interrupt mode using the PLIB_USART_TransmitterFIFOLevelSelect and PLIB_USART_ReceiverFIFOLevelSelect functions. To generate interrupts for every character received, use USART_RECEIVE_FIFO_ONE_CHAR from USART_RECEIVE_INTR_MODE. 8. Configure the DMA to be used with the USART receiver and transmitter. 5.6.25.4.4 Configuring the Library The library is configured for the supported USART modules when the processor is chosen in the MPLAB IDE. 5.6.25.5 Library Interface Data Types and Constants Name Description USART_BAUD_RATE_MODE Lists the USART baud rate modes. USART_HANDSHAKE_MODE Lists the USART handshake modes. USART_LINECONTROL_MODE Data type defining the different configurations by which the USART data flow can be configured. USART_MODULE_ID Enumeration: USART_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. USART_OPERATION_MODE Data type defining the different configurations by which the USART can be enabled. USART_RECEIVE_INTR_MODE Data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. USART_RECEIVE_MODES Lists the USART receive modes. USART_SYNC_CLOCK_SOURCE Lists the USART clock sources. USART_SYNC_MODES Selection between asynchronous communication and synchronous communication. USART_TRANSMIT_INTR_MODE Data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Baud Rate Generator Functions Name Description PLIB_USART_BaudRateAutoDetectEnable Enables baud rate measurement on the next character, which requires reception of the Sync character. PLIB_USART_BaudRateAutoDetectIsComplete Gets the state of the automatic baud detection. PLIB_USART_BaudRateAutoDetectOverflowHasOccurred Identifies if the automatic baud timer has overflowed. PLIB_USART_BaudRateGet Gets the baud rate current in use. PLIB_USART_BaudRateHighDisable Disables the high baud rate selection. PLIB_USART_BaudRateHighEnable Enables high baud rate selection. PLIB_USART_BaudRateHighSet Sets the baud rate to the desired value. PLIB_USART_BaudRateModeSelect Enables the 16-bit Baud Rate Generator (BRG). PLIB_USART_BaudRateSet Sets the baud rate to the desired value. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3101 Feature Existence Functions Name Description PLIB_USART_ExistsAlternateIO Identifies whether the AlternateIOEnableControl feature exists on the USART module. PLIB_USART_ExistsBaudRate Identifies whether the BaudRate feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetect Identifies whether the BaudRateAutoDetect feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetectOverflow Identifies whether the BaudRateAutoDetectOverflow feature exists on the USART module. PLIB_USART_ExistsBaudRateBitMode Identifies whether the BaudRateMode feature exists on the USART module. PLIB_USART_ExistsBaudRateHigh Identifies whether the BaudRateHigh feature exists on the USART module. PLIB_USART_ExistsEnable Identifies whether the EnableControl feature exists on the USART module. PLIB_USART_ExistsHandshakeMode Identifies whether the HandShakeMode feature exists on the USART module. PLIB_USART_ExistsIrDA Identifies whether the IrDAControl feature exists on the USART module. PLIB_USART_ExistsLineControlMode Identifies whether the LineControlMode feature exists on the USART module. PLIB_USART_ExistsLoopback Identifies whether the Loopback feature exists on the USART module. PLIB_USART_ExistsOperationMode Identifies whether the OperationMode feature exists on the USART module. PLIB_USART_ExistsReceiver Identifies whether the Receiver feature exists on the USART module. PLIB_USART_ExistsReceiverAddressAutoDetect Identifies whether the ReceiverAddressAutoDetect feature exists on the USART module. PLIB_USART_ExistsReceiverAddressDetect Identifies whether the ReceiverAddressDetect feature exists on the USART module. PLIB_USART_ExistsReceiverDataAvailableStatus Identifies whether the ReceiverDataAvailable feature exists on the USART module PLIB_USART_ExistsReceiverEnable Identifies whether the ReceiverEnableControl feature exists on the USART module. PLIB_USART_ExistsReceiverFramingErrorStatus Identifies whether the ReceiverFramingError feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStateLowEnable Identifies whether the ReceiverPolarityInvert feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStatus Identifies whether the ReceiverIdle feature exists on the USART module. PLIB_USART_ExistsReceiverInterruptMode Identifies whether the ReceiverInterruptMode feature exists on the USART module. PLIB_USART_ExistsReceiverMode Identifies whether the ReceiverMode feature exists on the USART module. PLIB_USART_ExistsReceiverOverrunStatus Identifies whether the ReceiverOverrunError feature exists on the USART module. PLIB_USART_ExistsReceiverParityErrorStatus Identifies whether the ReceiverParityError feature exists on the USART module. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3102 PLIB_USART_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USART module. PLIB_USART_ExistsSyncClockPolarity Identifies whether the SyncClockPolarity feature exists on the USART module. PLIB_USART_ExistsSyncClockSource Identifies whether the SyncClockSource feature exists on the USART module. PLIB_USART_ExistsSyncMode Identifies whether the SyncMode feature exists on the USART module. PLIB_USART_ExistsTransmitter Identifies whether the Transmitter feature exists on the USART module. PLIB_USART_ExistsTransmitter9BitsSend Identifies whether the Transmitter9Bits feature exists on the USART module. PLIB_USART_ExistsTransmitterBreak Identifies whether the TransmitterBreak feature exists on the USART module. PLIB_USART_ExistsTransmitterBufferFullStatus Identifies whether the TransmitterBufferFull feature exists on the USART module. PLIB_USART_ExistsTransmitterEmptyStatus Identifies whether the TransmitterEmpty feature exists on the USART module. PLIB_USART_ExistsTransmitterEnable Identifies whether the TransmitterEnableControl feature exists on the USART module PLIB_USART_ExistsTransmitterIdleIsLow Identifies whether the TransmitterIdleIsLow feature exists on the USART module. PLIB_USART_ExistsTransmitterIdleStatus Identifies whether the TransmitterIdle feature exists on the USART module. PLIB_USART_ExistsTransmitterInterruptMode Identifies whether the TransmitterInterruptMode feature exists on the USART module. PLIB_USART_ExistsWakeOnStart Identifies whether the WakeOnStart feature exists on the USART module. General Functions Name Description PLIB_USART_AlternateIODisable Disables the use of alternate I/O pins for the receiver and transmitter. PLIB_USART_AlternateIOEnable Enables the use of alternate I/O pins for the receiver and transmitter. PLIB_USART_Disable Disables the specific USART module PLIB_USART_Enable Enables the specific USART module. PLIB_USART_HandshakeModeSelect Sets the data flow configuration. PLIB_USART_IrDADisable Disables the IrDA encoder and decoder. PLIB_USART_IrDAEnable Enables the IrDA encoder and decoder. PLIB_USART_LineControlModeSelect Sets the data flow configuration. PLIB_USART_LoopbackDisable Disables Loopback mode. PLIB_USART_LoopbackEnable Enables Loopback mode. PLIB_USART_OperationModeSelect Configures the operation mode of the USART module. PLIB_USART_StopInIdleDisable Disables the Stop in Idle mode (the USART module continues operation when the device is in Idle mode). PLIB_USART_StopInIdleEnable Discontinues operation when the device enters Idle mode. PLIB_USART_SyncClockPolarityIdleHighDisable Sets the idle state of the clock to low. PLIB_USART_SyncClockPolarityIdleHighEnable Sets the idle state of the clock to high. PLIB_USART_SyncClockSourceSelect Sets the clock source. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3103 PLIB_USART_SyncModeSelect Selects the USART mode to be asynchronous. PLIB_USART_WakeOnStartDisable Disables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartEnable Enables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartIsEnabled Gets the state of the sync break event completion. Receiver Functions Name Description PLIB_USART_ReceiverAddressAutoDetectDisable Disables the automatic Address Detect mode. PLIB_USART_ReceiverAddressAutoDetectEnable Setup the automatic Address Detect mode. PLIB_USART_ReceiverAddressDetectDisable Enables the Address Detect mode. PLIB_USART_ReceiverAddressDetectEnable Enables the Address Detect mode. PLIB_USART_ReceiverAddressIsReceived Checks and return if the data received is an address. PLIB_USART_ReceiverByteReceive Data to be received in the Byte mode. PLIB_USART_ReceiverDataIsAvailable Identifies if the receive data is available for the specified USART module. PLIB_USART_ReceiverDisable Disables the USART receiver. PLIB_USART_ReceiverEnable Enables the USART receiver. PLIB_USART_ReceiverFramingErrorHasOccurred Gets the framing error status. PLIB_USART_ReceiverIdleStateLowDisable Disables receive polarity inversion. PLIB_USART_ReceiverIdleStateLowEnable Enables receive polarity inversion. PLIB_USART_ReceiverInterruptModeSelect Sets the USART receiver FIFO level. PLIB_USART_ReceiverIsIdle Identifies if the receiver is idle. PLIB_USART_ReceiverModeSelect Disables Single Receive mode. PLIB_USART_ReceiverOverrunErrorClear Clears a USART Overrun error. PLIB_USART_ReceiverOverrunHasOccurred Identifies if there was a receiver overrun error. PLIB_USART_ReceiverParityErrorHasOccurred Gets the parity error status. Transmitter Functions Name Description PLIB_USART_Transmitter9BitsSend Data to be transmitted in the byte mode with the 9th bit. PLIB_USART_TransmitterBreakSend Transmits the break character. PLIB_USART_TransmitterBreakSendIsComplete Returns the status of the break transmission PLIB_USART_TransmitterBufferIsFull Gets the transmit buffer full status. PLIB_USART_TransmitterByteSend Data to be transmitted in the Byte mode. PLIB_USART_TransmitterDisable Disables the specific USART module transmitter. PLIB_USART_TransmitterEnable Enables the specific USART module transmitter. PLIB_USART_TransmitterIdleIsLowDisable Disables the Transmit Idle Low state. PLIB_USART_TransmitterIdleIsLowEnable Enables the Transmit Idle Low state. PLIB_USART_TransmitterInterruptModeSelect Set the USART transmitter interrupt mode. PLIB_USART_TransmitterIsEmpty Gets the transmit shift register empty status. PLIB_USART_TransmitterIsIdle Gets the transmit buffer full status. Description This section describes the functions, data types, and constants available in the USART Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3104 5.6.25.5.1 General Functions 5.6.25.5.1.1 PLIB_USART_AlternateIODisable Function C void PLIB_USART_AlternateIODisable( USART_MODULE_ID index ); Description This function disables the USART module to use the alternate I/O pins for the receiver and transmitter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsAlternateIO in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_AlternateIODisable(MY_USART_INSTANCE); 5.6.25.5.1.2 PLIB_USART_AlternateIOEnable Function C void PLIB_USART_AlternateIOEnable( USART_MODULE_ID index ); Description This function enables the USART module to use the alternate I/O pins for the receiver and transmitter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3105 PLIB_USART_ExistsAlternateIO in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_AlternateIOEnable(MY_USART_INSTANCE); 5.6.25.5.1.3 PLIB_USART_Disable Function C void PLIB_USART_Disable( USART_MODULE_ID index ); Description This function disables the specific USART module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks The default state after any reset for a USART module is the disable state. If the USART is disabled, all of the related pins are in control of the general purpose I/O logic. Disabling the USART module resets the buffers to empty states. Any data characters in the buffers are lost and the baud rate is reset. All error and status bits are also reset. Disabling the USART while the USART is active, will abort all pending transmissions and receptions. Re-enabling the USART will restart the module in the same configuration. When disabled, the USART power consumption is minimal. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_Disable(MY_USART_INSTANCE); 5.6.25.5.1.4 PLIB_USART_Enable Function C void PLIB_USART_Enable( USART_MODULE_ID index ); Description This function enables the specific USART module. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3106 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks By calling this function, the USART pins are controlled by the USART module. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_Enable(MY_USART_INSTANCE); 5.6.25.5.1.5 PLIB_USART_HandshakeModeSelect Function C void PLIB_USART_HandshakeModeSelect( USART_MODULE_ID index, USART_HANDSHAKE_MODE handshakeConfig ); Description This function sets the USART data flow configuration based on the mask provided and the specified baud rate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode For possible data flow configurations, refer to USART_HANDSHAKE_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsHandshakeMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_HandshakeModeSelect(MY_USART_INSTANCE, USART_HANDSHAKE_MODE_SIMPLEX); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3107 5.6.25.5.1.6 PLIB_USART_IrDADisable Function C void PLIB_USART_IrDADisable( USART_MODULE_ID index ); Description This function disables the IrDA encoder and decoder. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks By default, the IrDA Encoder and Decoder are disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsIrDA in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_IrDADisable(MY_USART_INSTANCE); 5.6.25.5.1.7 PLIB_USART_IrDAEnable Function C void PLIB_USART_IrDAEnable( USART_MODULE_ID index ); Description This function enables the IrDA encoder and decoder. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsIrDA in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3108 Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_IrDAEnable(MY_USART_INSTANCE); 5.6.25.5.1.8 PLIB_USART_LineControlModeSelect Function C void PLIB_USART_LineControlModeSelect( USART_MODULE_ID index, USART_LINECONTROL_MODE dataFlowConfig ); Description This function sets the USART data flow configuration based on the mask provided and the specified baud rate. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode For possible data flow configurations, refer to USART_LINECONTROL_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLineControlMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LineControlModeSelect(MY_USART_INSTANCE, USART_8N1); 5.6.25.5.1.9 PLIB_USART_LoopbackDisable Function C void PLIB_USART_LoopbackDisable( USART_MODULE_ID index ); Description This function disables Loopback mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3109 Returns None. Remarks By default, Loopback mode is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLoopback in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LoopbackDisable(MY_USART_INSTANCE); 5.6.25.5.1.10 PLIB_USART_LoopbackEnable Function C void PLIB_USART_LoopbackEnable( USART_MODULE_ID index ); Description This function enables Loopback mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks By default, Loopback mode is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsLoopback in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_LoopbackEnable(MY_USART_INSTANCE); 5.6.25.5.1.11 PLIB_USART_OperationModeSelect Function C void PLIB_USART_OperationModeSelect( USART_MODULE_ID index, USART_OPERATION_MODE operationmode ); Description This function configures the operation mode of the USART (i.e., controls the pins used by the USART module). Refer to USART_OPERATION_MODE for the possible settings. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3110 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured operationmode One of the possible values from USART_OPERATION_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsOperationMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_OperationModeSelect(MY_USART_INSTANCE, USART_ENABLE_TX_RX_BCLK_USED); 5.6.25.5.1.12 PLIB_USART_StopInIdleDisable Function C void PLIB_USART_StopInIdleDisable( USART_MODULE_ID index ); Description This function disables the Stop in Idle mode. The USART module continues operation when the device is in Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks By default, the USART module will continue operation in idle mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_StopInIdleDisable(MY_USART_INSTANCE); 5.6.25.5.1.13 PLIB_USART_StopInIdleEnable Function C void PLIB_USART_StopInIdleEnable( 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3111 USART_MODULE_ID index ); Description This function enables the USART module to discontinue operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsStopInIdle in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_StopInIdleEnable(MY_USART_INSTANCE); 5.6.25.5.1.14 PLIB_USART_SyncClockPolarityIdleHighDisable Function C void PLIB_USART_SyncClockPolarityIdleHighDisable( USART_MODULE_ID index ); Description This function sets the clock idle in the synchronous mode to low. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the clock polarity idle as high. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsSyncClockPolarity in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_SyncClockPolarityIdleHighDisable(MY_USART_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3112 5.6.25.5.1.15 PLIB_USART_SyncClockPolarityIdleHighEnable Function C void PLIB_USART_SyncClockPolarityIdleHighEnable( USART_MODULE_ID index ); Description This function sets the clock idle in the Synchronous mode to high. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the clock polarity idle as low. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsSyncClockPolarity in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_SyncClockPolarityIdleHighEnable(MY_USART_INSTANCE); 5.6.25.5.1.16 PLIB_USART_SyncClockSourceSelect Function C void PLIB_USART_SyncClockSourceSelect( USART_MODULE_ID index, USART_SYNC_CLOCK_SOURCE source ); Description This function sets the clock source to either master or slave, which is only valid in Synchronous mode. The clock is generated from the baud rate generator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the use of the slave as the clock source. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3113 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsSyncClockSource in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_SyncClockSourceSelect(MY_USART_INSTANCE, USART_SYNC_CLOCK_SOURCE_MASTER); 5.6.25.5.1.17 PLIB_USART_SyncModeSelect Function C void PLIB_USART_SyncModeSelect( USART_MODULE_ID index, USART_SYNC_MODES mode ); Description This function enables the Asynchronous mode of the USART module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Calling this function disables the Synchronous mode of the USART module. By default, the module is in Asynchronous mode after a reset. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsSyncMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_SyncModeSelect(MY_USART_INSTANCE, USART_ASYNC_MODE); 5.6.25.5.1.18 PLIB_USART_WakeOnStartDisable Function C void PLIB_USART_WakeOnStartDisable( USART_MODULE_ID index ); Description This function disables the wake-up on start bit detection feature during Sleep mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3114 Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_WakeOnStartDisable(MY_USART_INSTANCE); 5.6.25.5.1.19 PLIB_USART_WakeOnStartEnable Function C void PLIB_USART_WakeOnStartEnable( USART_MODULE_ID index ); Description This function enables the wake-up on start feature during Sleep mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_WakeOnStartEnable(MY_USART_INSTANCE); 5.6.25.5.1.20 PLIB_USART_WakeOnStartIsEnabled Function C bool PLIB_USART_WakeOnStartIsEnabled( USART_MODULE_ID index ); Description This function returns the status of the sync break event, when called after enabling using PLIB_USART_WakeOnStartEnable. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3115 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsWakeOnStart in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 //Call the interface just prior to entering the sleep mode. PLIB_USART_WakeOnStartEnable(MY_USART_INSTANCE); // Check the status if the Sync break event is over. if(PLIB_USART_WakeOnStartIsEnabled(MY_USART_INSTANCE)) { // Do Something } 5.6.25.5.2 Baud Rate Generator Functions 5.6.25.5.2.1 PLIB_USART_BaudRateAutoDetectEnable Function C void PLIB_USART_BaudRateAutoDetectEnable( USART_MODULE_ID index ); Description This function enables the baud rate measurement on the next character, which requires reception of the Sync character. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateAutoDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3116 PLIB_USART_BaudRateAutoDetectEnable(MY_USART_INSTANCE); // Wait till the baud rate is detected. while(!PLIB_USART_BaudRateAutoDetectIsComplete(MY_USART_INSTANCE)); 5.6.25.5.2.2 PLIB_USART_BaudRateAutoDetectIsComplete Function C bool PLIB_USART_BaudRateAutoDetectIsComplete( USART_MODULE_ID index ); Description This function gets the state of the automatic baud detection and returns a '0' if the baud rate auto detection is complete. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Baud rate detection is not complete • false - Baud rate detection is complete Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateAutoDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateAutoDetectEnable(MY_USART_INSTANCE); // Wait till the baud rate is detected. while(!PLIB_USART_BaudRateAutoDetectIsComplete(MY_USART_INSTANCE)); 5.6.25.5.2.3 PLIB_USART_BaudRateAutoDetectOverflowHasOccurred Function C bool PLIB_USART_BaudRateAutoDetectOverflowHasOccurred( USART_MODULE_ID index ); Description This function identifies whether or not the automatic baud timer has overflowed. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3117 Returns • true - An auto-baud overflow has occurred • false - An auto-baud overflow has not occurred Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateAutoDetectOverflow in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_BaudRateAutoDetectOverflowHasOccurred(MY_USART_INSTANCE); 5.6.25.5.2.4 PLIB_USART_BaudRateGet Function C uint32_t PLIB_USART_BaudRateGet( USART_MODULE_ID index, int32_t clockFrequency ); Description This function gets the baud rate that is currently in use. The clock frequency needs to be passed to the function. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured clockFrequency Clock Frequency Returns BaudRate - Baud Rate Value Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRate in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRate ; PLIB_USART_BaudRateSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRate = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); 5.6.25.5.2.5 PLIB_USART_BaudRateHighDisable Function C void PLIB_USART_BaudRateHighDisable( USART_MODULE_ID index ); Description This function disables the high baud rate selection. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3118 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateHighDisable(MY_USART_INSTANCE); 5.6.25.5.2.6 PLIB_USART_BaudRateHighEnable Function C void PLIB_USART_BaudRateHighEnable( USART_MODULE_ID index ); Description This function enables high baud rate selection. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateHighEnable(MY_USART_INSTANCE); 5.6.25.5.2.7 PLIB_USART_BaudRateHighSet Function C void PLIB_USART_BaudRateHighSet( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3119 ); Description This function sets the baud rate to the desired value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured baudRate Baud Rate Value, it is the baud rate value clockFrequency Clock Frequency Returns None. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue verify that no receptions are in progress before changing the system clock. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateHigh in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRateValue ; PLIB_USART_BaudRateHighSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRateValue = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); 5.6.25.5.2.8 PLIB_USART_BaudRateModeSelect Function C void PLIB_USART_BaudRateModeSelect( USART_MODULE_ID index, USART_BAUD_RATE_MODE mode ); Description This function enables the 16-bit Baud Rate Generator. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured mode Baud rate mode Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3120 Remarks Calling this function disables the 8-bit Baud Rate Generator. The 16-bit mode is used to achieve a slow baud rate for fast oscillator frequencies. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRateBitMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_BaudRateModeSelect(MY_USART_INSTANCE, USART_BAUD_RATE_16_BIT_MODE); 5.6.25.5.2.9 PLIB_USART_BaudRateSet Function C void PLIB_USART_BaudRateSet( USART_MODULE_ID index, uint32_t clockFrequency, uint32_t baudRate ); Description This function sets the baud rate to the desired value. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured baudRate Baud Rate Value clockFrequency Clock Frequency Returns None. Remarks Setting a new baud rate value causes the baud rate timer to reset. This ensures that the baud rate timer does not have to overflow before outputting the new baud rate. If the system clock is changed during an active receive operation, a receiver error or data loss may result. To avoid this issue verify that no receptions are in progress before changing the system clock. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsBaudRate in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 uint32_t baudRateValue ; PLIB_USART_BaudRateSet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY, 9600); baudRateValue = PLIB_USART_BaudRateGet(MY_USART_INSTANCE, MY_CLOCK_FREQUENCY); 5.6.25.5.3 Transmitter Functions 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3121 5.6.25.5.3.1 PLIB_USART_Transmitter9BitsSend Function C void PLIB_USART_Transmitter9BitsSend( USART_MODULE_ID index, int8_t data, bool Bit9th ); Description The data is transmitted in the byte mode for the specified USART module, with 9th bit. Preconditions The USART module should be configured to use the 9 data bits. Parameters Parameters Description index Identifier for the device instance to be configured data Data to be transmitted. 9thBit 9th bit of the data to be transmitted. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitter9BitsSend in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t data = 'a'; if(!PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)) { PLIB_USART_Transmitter9BitsSend(MY_USART_INSTANCE, data, false); } 5.6.25.5.3.2 PLIB_USART_TransmitterBreakSend Function C void PLIB_USART_TransmitterBreakSend( USART_MODULE_ID index ); Description This function transmits the break character. Preconditions The application should wait for the transmitter to be idle, before calling this function. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3122 Returns None. Remarks After the break has been transmitted, the application can start transmitting next bytes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBreak in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // wait for the break transmission to complete while(!PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); 5.6.25.5.3.3 PLIB_USART_TransmitterBreakSendIsComplete Function C bool PLIB_USART_TransmitterBreakSendIsComplete( USART_MODULE_ID index ); Description The function returns the status of the break transmission. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - Transmit Break on the next transmission • false - Break Transmission completed or not started Remarks After the break has been transmitted, the application can start transmitting next bytes. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBreak in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); // wait for the break transmission to complete 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3123 while(!PLIB_USART_TransmitterBreakSendIsComplete(MY_USART_INSTANCE)); 5.6.25.5.3.4 PLIB_USART_TransmitterBufferIsFull Function C bool PLIB_USART_TransmitterBufferIsFull( USART_MODULE_ID index ); Description Gets the transmit status of the specified USART module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The transmit buffer is full • false - The transmit buffer is not full, at least one more character can be written. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterBufferFullStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); 5.6.25.5.3.5 PLIB_USART_TransmitterByteSend Function C void PLIB_USART_TransmitterByteSend( USART_MODULE_ID index, int8_t data ); Description The data is transmitted in the Byte mode for the specified USART module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured data Data to be transmitted. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3124 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitter in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 uint8_t data = 'a'; if(!PLIB_USART_TransmitterBufferIsFull(MY_USART_INSTANCE)) { PLIB_USART_TransmitterByteSend(MY_USART_INSTANCE, data); } 5.6.25.5.3.6 PLIB_USART_TransmitterDisable Function C void PLIB_USART_TransmitterDisable( USART_MODULE_ID index ); Description This function disables the specific USART module transmitter. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks Disabling the transmitter during a transmission will cause the transmission to be aborted. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterDisable(MY_USART_INSTANCE); 5.6.25.5.3.7 PLIB_USART_TransmitterEnable Function C void PLIB_USART_TransmitterEnable( USART_MODULE_ID index ); Description This function enables the specific USART module transmitter. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3125 Preconditions The USART module should be enabled using the function PLIB_USART_Enable before this function is called. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks The transmitter should not be enabled until the USART is enabled. The transmissions will not be enabled otherwise. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterEnable(MY_USART_INSTANCE); 5.6.25.5.3.8 PLIB_USART_TransmitterIdleIsLowDisable Function C void PLIB_USART_TransmitterIdleIsLowDisable( USART_MODULE_ID index ); Description This function disables the Transmit Idle Low state. In USART Synchronous mode, this function configures that the TX polarity the idle state is high. When IrDA is enabled, this function sets the IrDA encoded Transmit Idle state to a '0'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterIdleIsLow in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterIdleIsLowDisable(MY_USART_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3126 5.6.25.5.3.9 PLIB_USART_TransmitterIdleIsLowEnable Function C void PLIB_USART_TransmitterIdleIsLowEnable( USART_MODULE_ID index ); Description This function enables the Transmit Idle Low state. In the USART Synchronous mode, this function configures that the TX polarity, the idle state is low. When IrDA(c) is enabled, this function sets that IrDA encoded Transmit Idle state to a '1'. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterIdleIsLow in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterIdleIsLowEnable(MY_USART_INSTANCE); 5.6.25.5.3.10 PLIB_USART_TransmitterInterruptModeSelect Function C void PLIB_USART_TransmitterInterruptModeSelect( USART_MODULE_ID index, USART_TRANSMIT_INTR_MODE fifolevel ); Description This function sets the condition in which the USART module should generate an interrupt. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured interruptMode Interrupt mode; for possible configurations, refer to USART_TRANSMIT_INTR_MODE Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3127 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterInterruptMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_TransmitterInterruptModeSelect(MY_USART_INSTANCE, USART_TRANSMIT_FIFO_EMPTY ); 5.6.25.5.3.11 PLIB_USART_TransmitterIsEmpty Function C bool PLIB_USART_TransmitterIsEmpty( USART_MODULE_ID index ); Description This function gets the transmit shift register empty status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The transmit shift register is empty • false - The transmit shift register is not empty Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterEmptyStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 // Wait for the Transmit buffer to be empty. while(!PLIB_USART_TransmitterIsEmpty(MY_USART_INSTANCE)); // Transmit the break character. PLIB_USART_TransmitterBreakSend(MY_USART_INSTANCE); 5.6.25.5.3.12 PLIB_USART_TransmitterIsIdle Function C bool PLIB_USART_TransmitterIsIdle( USART_MODULE_ID index ); Description This function gets the transmit buffer full status. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3128 Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The transmitter is idle • false - The transmitter is not idle Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsTransmitterIdleStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_TransmitterIsIdle(MY_USART_INSTANCE); 5.6.25.5.4 Receiver Functions 5.6.25.5.4.1 PLIB_USART_ReceiverAddressAutoDetectDisable Function C void PLIB_USART_ReceiverAddressAutoDetectDisable( USART_MODULE_ID index ); Description This function disables the automatic Address Detect mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressAutoDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressAutoDetectDisable(MY_USART_INSTANCE); 5.6.25.5.4.2 PLIB_USART_ReceiverAddressAutoDetectEnable Function C void PLIB_USART_ReceiverAddressAutoDetectEnable( USART_MODULE_ID index, int8_t Mask 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3129 ); Description This function configures the automatic Address Detect mode. Uses the mask as the address character for automatic address detection. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Mask Address character to be used, when enabled Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressAutoDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressAutoDetectEnable(MY_USART_INSTANCE, MY_DEVICE_ADDRESS); 5.6.25.5.4.3 PLIB_USART_ReceiverAddressDetectDisable Function C void PLIB_USART_ReceiverAddressDetectDisable( USART_MODULE_ID index ); Description This function disables the Address Detect mode. If it is enabled, and the device is addressed, disable the Address Detect mode to continue receiving bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks All bytes are received, and the 9th bit can be used as the parity bit. By default, the address detect is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3130 PLIB_USART_ReceiverAddressDetectDisable(MY_USART_INSTANCE); 5.6.25.5.4.4 PLIB_USART_ReceiverAddressDetectEnable Function C void PLIB_USART_ReceiverAddressDetectEnable( USART_MODULE_ID index ); Description This function enables the Address Detect mode. If it is enabled, and the device is addressed, disable the Address Detect mode to continue receiving bytes. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks If 9 data bits are not selected, this bit has no effect. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverAddressDetectEnable(MY_USART_INSTANCE); 5.6.25.5.4.5 PLIB_USART_ReceiverAddressIsReceived Function C bool PLIB_USART_ReceiverAddressIsReceived( USART_MODULE_ID index ); Description Checks and return if the data received is an address. The address has the 9th bit set. If data received, has 9th bit set, function returns true, else returns false. Preconditions The USART module should be configured to use the 9 data bits. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - if the data received has the 9th bit set • false - if the address received has the 9th bit cleared 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3131 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverAddressDetect in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 int8_t address; if(PLIB_USART_ReceiverAddressIsReceived(MY_USART_INSTANCE)) { address = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } 5.6.25.5.4.6 PLIB_USART_ReceiverByteReceive Function C int8_t PLIB_USART_ReceiverByteReceive( USART_MODULE_ID index ); Description The data to be received in Byte mode from the specified USART module. Call the functions PLIB_USART_ReceiverFramingErrorHasOccurred, PLIB_USART_ReceiverParityErrorHasOccurred and PLIB_USART_ReceiverOverrunHasOccurred to get any error that occurred. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns data - Data to be received. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiver in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 bool isError; uint8_t mydata; if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } isError = PLIB_USART_ReceiverFramingErrorHasOccurred(MY_USART_INSTANCE) | PLIB_USART_ReceiverParityErrorHasOccurred(MY_USART_INSTANCE) | PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE); if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3132 } 5.6.25.5.4.7 PLIB_USART_ReceiverDataIsAvailable Function C bool PLIB_USART_ReceiverDataIsAvailable( USART_MODULE_ID index ); Description This function identifies if the receive data is available for the specified USART module. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The data is available • false - The data is not available Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverDataAvailableStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 int8_t mydata; if(PLIB_USART_ReceiverDataIsAvailable(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } 5.6.25.5.4.8 PLIB_USART_ReceiverDisable Function C void PLIB_USART_ReceiverDisable( USART_MODULE_ID index ); Description This function disables the USART receiver. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3133 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverDisable(MY_USART_INSTANCE); 5.6.25.5.4.9 PLIB_USART_ReceiverEnable Function C void PLIB_USART_ReceiverEnable( USART_MODULE_ID index ); Description This function enables the USART receiver. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverEnable(MY_USART_INSTANCE); 5.6.25.5.4.10 PLIB_USART_ReceiverFramingErrorHasOccurred Function C bool PLIB_USART_ReceiverFramingErrorHasOccurred( USART_MODULE_ID index ); Description This function gets the framing error status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3134 Returns • true - The framing error was detected on the current character • false - The framing error was not detected on the current character Remarks Reading the error clears the error. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverFramingErrorStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_ReceiverFramingErrorHasOccurred(MY_USART_INSTANCE); 5.6.25.5.4.11 PLIB_USART_ReceiverIdleStateLowDisable Function C void PLIB_USART_ReceiverIdleStateLowDisable( USART_MODULE_ID index ); Description This function disables receive polarity inversion. In the USART Synchronous mode, this function configures that the data is not inverted. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStateLowEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverIdleStateLowDisable(MY_USART_INSTANCE); 5.6.25.5.4.12 PLIB_USART_ReceiverIdleStateLowEnable Function C void PLIB_USART_ReceiverIdleStateLowEnable( USART_MODULE_ID index ); Description This function enables receive polarity inversion. In the USART Synchronous mode, this function configures that the data is inverted. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3135 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStateLowEnable in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverIdleStateLowEnable(MY_USART_INSTANCE); 5.6.25.5.4.13 PLIB_USART_ReceiverInterruptModeSelect Function C void PLIB_USART_ReceiverInterruptModeSelect( USART_MODULE_ID index, USART_RECEIVE_INTR_MODE interruptMode ); Description This function sets the USART receiver FIFO level. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured fifolevel For possible configurations, refer to USART_RECEIVE_INTR_MODE Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverInterruptMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverInterruptModeSelect(MY_USART_INSTANCE, USART_RECEIVE_FIFO_ONE_CHAR ); 5.6.25.5.4.14 PLIB_USART_ReceiverIsIdle Function C bool PLIB_USART_ReceiverIsIdle( 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3136 USART_MODULE_ID index ); Description This function identifies if the receiver is idle. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The receive buffer is idle • false - The receive buffer is not idle Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverIdleStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 int8_t mydata; if(PLIB_USART_ReceiverIsIdle(MY_USART_INSTANCE)) { mydata = PLIB_USART_ReceiverByteReceive(MY_USART_INSTANCE); } 5.6.25.5.4.15 PLIB_USART_ReceiverModeSelect Function C void PLIB_USART_ReceiverModeSelect( USART_MODULE_ID index, USART_RECEIVE_MODES mode ); Description This function disables Single Receive mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This function has no effect during Asynchronous mode, or in the Synchronous Slave mode. By default, the single receive is disabled after a reset. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3137 PLIB_USART_ExistsReceiverMode in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 PLIB_USART_ReceiverModeSelect(MY_USART_INSTANCE, USART_RECEIVE_MODE_SINGLE); 5.6.25.5.4.16 PLIB_USART_ReceiverOverrunErrorClear Function C void PLIB_USART_ReceiverOverrunErrorClear( USART_MODULE_ID index ); Description Clears an overrun error. Clearing the error, resets the receive buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks WARNING: Calling this API will clear all the previously received data. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverOverrunStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } 5.6.25.5.4.17 PLIB_USART_ReceiverOverrunHasOccurred Function C bool PLIB_USART_ReceiverOverrunHasOccurred( USART_MODULE_ID index ); Description This function identifies if there was a receiver overrun error. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3138 Returns • true - The receive buffer has overflowed • false - The receive buffer has not overflowed Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverOverrunStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 if(PLIB_USART_ReceiverOverrunHasOccurred(MY_USART_INSTANCE)) { PLIB_USART_ReceiverOverrunErrorClear(MY_USART_INSTANCE); } 5.6.25.5.4.18 PLIB_USART_ReceiverParityErrorHasOccurred Function C bool PLIB_USART_ReceiverParityErrorHasOccurred( USART_MODULE_ID index ); Description This function gets the parity error status. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - The parity error was detected on the current character • false - The parity error was not detected on the current character Remarks Reading the error clears the error. A Parity error is irrelevant in case of 9-bit mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USART_ExistsReceiverParityErrorStatus in your application to determine whether this feature is available. Example #define MY_USART_INSTANCE USART_ID_1 status = PLIB_USART_ReceiverParityErrorHasOccurred(MY_USART_INSTANCE); 5.6.25.5.5 Data Types and Constants 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3139 5.6.25.5.5.1 USART_BAUD_RATE_MODE Enumeration C typedef enum { USART_BAUD_RATE_8_BIT_MODE, USART_BAUD_RATE_16_BIT_MODE } USART_BAUD_RATE_MODE; Description /* USART Baud rate mode This enumeration lists the USART baud rate modes. Members Members Description USART_BAUD_RATE_8_BIT_MODE Baud rate register is 8 bit USART_BAUD_RATE_16_BIT_MODE Baud rate register is 16 bit Remarks None. 5.6.25.5.5.2 USART_HANDSHAKE_MODE Enumeration C typedef enum { USART_HANDSHAKE_MODE_FLOW_CONTROL, USART_HANDSHAKE_MODE_SIMPLEX } USART_HANDSHAKE_MODE; Description /* USART Handshake modes This enumeration lists the USART handshake modes. Members Members Description USART_HANDSHAKE_MODE_FLOW_CONTROL Enables flow control USART_HANDSHAKE_MODE_SIMPLEX Enables simplex mode communication, no flow control Remarks None. 5.6.25.5.5.3 USART_LINECONTROL_MODE Enumeration C typedef enum { USART_8N1, USART_8E1, USART_8O1, USART_8N2, USART_8E2, USART_8O2, USART_9N1, USART_9N2 } USART_LINECONTROL_MODE; 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3140 Description Data Flow configuration This data type defines the different configurations by which the USART can be configured for the data flow. Members Members Description USART_8N1 8 Data Bits, No Parity,one Stop Bit USART_8E1 8 Data Bits, Even Parity, 1 stop bit USART_8O1 8 Data Bits, odd Parity, 1 stop bit USART_8N2 8 Data Bits, No Parity,two Stop Bits USART_8E2 8 Data Bits, Even Parity, 2 stop bits USART_8O2 8 Data Bits, odd Parity, 2 stop bits USART_9N1 9 Data Bits, No Parity, 1 stop bit USART_9N2 9 Data Bits, No Parity, 2 stop bits Remarks None. 5.6.25.5.5.4 USART_MODULE_ID Enumeration C typedef enum { USART_ID_1, USART_ID_2, USART_ID_3, USART_ID_4, USART_ID_5, USART_ID_6, USART_NUMBER_OF_MODULES } USART_MODULE_ID; Description Enumeration: USART_MODULE_ID This enumeration defines the number of modules that are available on the microcontroller. This is the superset of all of the possible instances that might be available on Microchip microcontrollers. Refer to the data sheet to get the correct number of modules defined for desired microcontroller. Members Members Description USART_ID_1 USART 1 USART_ID_2 USART 2 USART_ID_3 USART 3 USART_ID_4 USART 4 USART_ID_5 USART 5 USART_ID_6 USART 6 USART_NUMBER_OF_MODULES Total number of USART modules available 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3141 5.6.25.5.5.5 USART_OPERATION_MODE Enumeration C typedef enum { USART_ENABLE_TX_RX_BCLK_USED, USART_ENABLE_TX_RX_CTS_RTS_USED, USART_ENABLE_TX_RX_RTS_USED, USART_ENABLE_TX_RX_USED } USART_OPERATION_MODE; Description Enable configuration This data type defines the different configurations by which the USART can be enabled. Members Members Description USART_ENABLE_TX_RX_BCLK_USED TX, RX and BCLK pins are used by USART module USART_ENABLE_TX_RX_CTS_RTS_USED TX, RX, CTS and RTS pins are used by USART module USART_ENABLE_TX_RX_RTS_USED TX, RX and RTS pins are used by USART module USART_ENABLE_TX_RX_USED TX and RX pins are used by USART module Remarks The actual definition of this enumeration is device-specific. 5.6.25.5.5.6 USART_RECEIVE_INTR_MODE Enumeration C typedef enum { USART_RECEIVE_FIFO_HALF_FULL, USART_RECEIVE_FIFO_3B4FULL, USART_RECEIVE_FIFO_ONE_CHAR } USART_RECEIVE_INTR_MODE; Description Receive Interrupt mode configuration This data type defining the different Receive FIFO levels by which the USART receive interrupt modes can be configured. Members Members Description USART_RECEIVE_FIFO_HALF_FULL Interrupt when receive buffer is half full USART_RECEIVE_FIFO_3B4FULL Interrupt when receive buffer is 3/4 full USART_RECEIVE_FIFO_ONE_CHAR Interrupt when a character is received Remarks None. 5.6.25.5.5.7 USART_RECEIVE_MODES Enumeration C typedef enum { USART_RECEIVE_MODE_CONTINUOUS, USART_RECEIVE_MODE_SINGLE, 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3142 USART_RECEIVE_MODES_NONE } USART_RECEIVE_MODES; Description /* USART Receive modes This enumeration lists the USART receive modes. Members Members Description USART_RECEIVE_MODE_CONTINUOUS Continuous Receive mode USART_RECEIVE_MODE_SINGLE Single Receive mode USART_RECEIVE_MODES_NONE No Receive mode Remarks This enumeration may not exist for all devices. 5.6.25.5.5.8 USART_SYNC_CLOCK_SOURCE Enumeration C typedef enum { USART_SYNC_CLOCK_SOURCE_MASTER, USART_SYNC_CLOCK_SOURCE_SLAVE } USART_SYNC_CLOCK_SOURCE; Description /* USART Clock sources This enumeration lists the USART clock sources. Members Members Description USART_SYNC_CLOCK_SOURCE_MASTER USART clock source is from master USART_SYNC_CLOCK_SOURCE_SLAVE USART clock source is from slave Remarks None. 5.6.25.5.5.9 USART_SYNC_MODES Enumeration C typedef enum { USART_ASYNC_MODE, USART_SYNC_MODE } USART_SYNC_MODES; Description /* USART Synchronisation Modes Lists enumerations selecting asynchronous communication or synchronous communication. Members Members Description USART_ASYNC_MODE Normal UART. Asynchronous USART_SYNC_MODE Synchronous 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3143 Remarks This enumeration is not used for devices which does not have the synchronous communication option (i.e., always asynchronous). 5.6.25.5.5.10 USART_TRANSMIT_INTR_MODE Enumeration C typedef enum { USART_TRANSMIT_FIFO_EMPTY, USART_TRANSMIT_FIFO_FULL, USART_TRANSMIT_FIFO_IDLE, USART_TRANSMIT_FIFO_NOT_FULL } USART_TRANSMIT_INTR_MODE; Description /* Transmit Interrupt mode configuration This data type defining the different transmit FIFO levels by which the USART transmit interrupt modes can be configured. Members Members Description USART_TRANSMIT_FIFO_EMPTY Interrupt when the transmit buffer becomes empty USART_TRANSMIT_FIFO_FULL Interrupt when the last transmission is over and all transmit operations are completed USART_TRANSMIT_FIFO_IDLE Interrupt when all characters are transmitted USART_TRANSMIT_FIFO_NOT_FULL Interrupt when atleast one location is empty in the transmit buffer Remarks None. 5.6.25.5.6 Feature Existence Functions 5.6.25.5.6.1 PLIB_USART_ExistsAlternateIO Function C bool PLIB_USART_ExistsAlternateIO( USART_MODULE_ID index ); Description This function identifies whether the AlternateIOEnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_AlternateIOEnable • PLIB_USART_AlternateIODisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3144 Returns • true - The AlternateIOEnableControl feature is supported on the device • false - The AlternateIOEnableControl feature is not supported on the device Remarks None. 5.6.25.5.6.2 PLIB_USART_ExistsBaudRate Function C bool PLIB_USART_ExistsBaudRate( USART_MODULE_ID index ); Description This function identifies whether the BaudRate feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateSet • PLIB_USART_BaudRateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRate feature is supported on the device • false - The BaudRate feature is not supported on the device Remarks None. 5.6.25.5.6.3 PLIB_USART_ExistsBaudRateAutoDetect Function C bool PLIB_USART_ExistsBaudRateAutoDetect( USART_MODULE_ID index ); Description This function identifies whether the BaudRateAutoDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateAutoDetectEnable • PLIB_USART_BaudRateAutoDetectIsComplete Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3145 Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRateAutoDetect feature is supported on the device • false - The BaudRateAutoDetect feature is not supported on the device Remarks None. 5.6.25.5.6.4 PLIB_USART_ExistsBaudRateAutoDetectOverflow Function C bool PLIB_USART_ExistsBaudRateAutoDetectOverflow( USART_MODULE_ID index ); Description This function identifies whether the BaudRateAutoDetectOverflow feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_BaudRateAutoDetectOverflowHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRateAutoDetectOverflow feature is supported on the device • false - The BaudRateAutoDetectOverflow feature is not supported on the device Remarks None. 5.6.25.5.6.5 PLIB_USART_ExistsBaudRateBitMode Function C bool PLIB_USART_ExistsBaudRateBitMode( USART_MODULE_ID index ); Description This function identifies whether the BaudRateMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_BaudRateModeSelect Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3146 Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRateMode feature is supported on the device • false - The BaudRateMode feature is not supported on the device Remarks None. 5.6.25.5.6.6 PLIB_USART_ExistsBaudRateHigh Function C bool PLIB_USART_ExistsBaudRateHigh( USART_MODULE_ID index ); Description This function identifies whether the BaudRateHigh feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_BaudRateHighSet • PLIB_USART_BaudRateHighDisable • PLIB_USART_BaudRateHighEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BaudRateHigh feature is supported on the device • false - The BaudRateHigh feature is not supported on the device Remarks None. 5.6.25.5.6.7 PLIB_USART_ExistsEnable Function C bool PLIB_USART_ExistsEnable( USART_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_Disable 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3147 • PLIB_USART_Enable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EnableControl feature is supported on the device • false - The EnableControl feature is not supported on the device Remarks None. 5.6.25.5.6.8 PLIB_USART_ExistsHandshakeMode Function C bool PLIB_USART_ExistsHandshakeMode( USART_MODULE_ID index ); Description This function identifies whether the HandShakeMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_HandshakeModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HandShakeMode feature is supported on the device • false - The HandShakeMode feature is not supported on the device Remarks None. 5.6.25.5.6.9 PLIB_USART_ExistsIrDA Function C bool PLIB_USART_ExistsIrDA( USART_MODULE_ID index ); Description This function identifies whether the IrDAControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_IrDADisable 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3148 • PLIB_USART_IrDAEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The IrDAControl feature is supported on the device • false - The IrDAControl feature is not supported on the device Remarks None. 5.6.25.5.6.10 PLIB_USART_ExistsLineControlMode Function C bool PLIB_USART_ExistsLineControlMode( USART_MODULE_ID index ); Description This function identifies whether the LineControlMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_LineControlModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LineControlMode feature is supported on the device • false - The LineControlMode feature is not supported on the device Remarks None. 5.6.25.5.6.11 PLIB_USART_ExistsLoopback Function C bool PLIB_USART_ExistsLoopback( USART_MODULE_ID index ); Description This function identifies whether the Loopback feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_LoopbackEnable 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3149 • PLIB_USART_LoopbackDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Loopback feature is supported on the device • false - The Loopback feature is not supported on the device Remarks None. 5.6.25.5.6.12 PLIB_USART_ExistsOperationMode Function C bool PLIB_USART_ExistsOperationMode( USART_MODULE_ID index ); Description This function identifies whether the OperationMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_OperationModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OperationMode feature is supported on the device • false - The OperationMode feature is not supported on the device Remarks None. 5.6.25.5.6.13 PLIB_USART_ExistsReceiver Function C bool PLIB_USART_ExistsReceiver( USART_MODULE_ID index ); Description This function identifies whether the Receiver feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverByteReceive 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3150 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Receiver feature is supported on the device • false - The Receiver feature is not supported on the device Remarks None. 5.6.25.5.6.14 PLIB_USART_ExistsReceiverAddressAutoDetect Function C bool PLIB_USART_ExistsReceiverAddressAutoDetect( USART_MODULE_ID index ); Description This function identifies whether the ReceiverAddressAutoDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverAddressAutoDetectEnable • PLIB_USART_ReceiverAddressAutoDetectDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverAddressAutoDetect feature is supported on the device • false - The ReceiverAddressAutoDetect feature is not supported on the device Remarks None. 5.6.25.5.6.15 PLIB_USART_ExistsReceiverAddressDetect Function C bool PLIB_USART_ExistsReceiverAddressDetect( USART_MODULE_ID index ); Description This function identifies whether the ReceiverAddressDetect feature is available on the USART module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3151 • PLIB_USART_ReceiverAddressDetectEnable • PLIB_USART_ReceiverAddressDetectDisable • PLIB_USART_ReceiverAddressIsReceived Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverAddressDetect feature is supported on the device • false - The ReceiverAddressDetect feature is not supported on the device Remarks None. 5.6.25.5.6.16 PLIB_USART_ExistsReceiverDataAvailableStatus Function C bool PLIB_USART_ExistsReceiverDataAvailableStatus( USART_MODULE_ID index ); Description This function identifies whether the ReceiverDataAvailable feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverDataIsAvailable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverDataAvailable feature is supported on the device • false - The ReceiverDataAvailable feature is not supported on the device Remarks None. 5.6.25.5.6.17 PLIB_USART_ExistsReceiverEnable Function C bool PLIB_USART_ExistsReceiverEnable( USART_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3152 Description This function identifies whether the ReceiverEnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverEnable • PLIB_USART_ReceiverDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverEnableControl feature is supported on the device • false - The ReceiverEnableControl feature is not supported on the device Remarks None. 5.6.25.5.6.18 PLIB_USART_ExistsReceiverFramingErrorStatus Function C bool PLIB_USART_ExistsReceiverFramingErrorStatus( USART_MODULE_ID index ); Description This function identifies whether the ReceiverFramingError feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverFramingErrorHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverFramingError feature is supported on the device • false - The ReceiverFramingError feature is not supported on the device Remarks None. 5.6.25.5.6.19 PLIB_USART_ExistsReceiverIdleStateLowEnable Function C bool PLIB_USART_ExistsReceiverIdleStateLowEnable( USART_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3153 ); Description This function identifies whether the ReceiverPolarityInvert feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverIdleStateLowEnable • PLIB_USART_ReceiverIdleStateLowDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverPolarityInvert feature is supported on the device • false - The ReceiverPolarityInvert feature is not supported on the device Remarks None. 5.6.25.5.6.20 PLIB_USART_ExistsReceiverIdleStatus Function C bool PLIB_USART_ExistsReceiverIdleStatus( USART_MODULE_ID index ); Description This function identifies whether the ReceiverIdle feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverIsIdle Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverIdle feature is supported on the device • false - The ReceiverIdle feature is not supported on the device Remarks None. 5.6.25.5.6.21 PLIB_USART_ExistsReceiverInterruptMode Function C bool PLIB_USART_ExistsReceiverInterruptMode( 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3154 USART_MODULE_ID index ); Description This function identifies whether the ReceiverInterruptMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverInterruptModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverInterruptMode feature is supported on the device • false - The ReceiverInterruptMode feature is not supported on the device Remarks None. 5.6.25.5.6.22 PLIB_USART_ExistsReceiverMode Function C bool PLIB_USART_ExistsReceiverMode( USART_MODULE_ID index ); Description This function identifies whether the ReceiverMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverMode feature is supported on the device • false - The ReceiverMode feature is not supported on the device Remarks None. 5.6.25.5.6.23 PLIB_USART_ExistsReceiverOverrunStatus Function C bool PLIB_USART_ExistsReceiverOverrunStatus( USART_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3155 ); Description This function identifies whether the ReceiverOverrunError feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_ReceiverOverrunErrorClear • PLIB_USART_ReceiverOverrunHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverOverrunError feature is supported on the device • false - The ReceiverOverrunError feature is not supported on the device Remarks None. 5.6.25.5.6.24 PLIB_USART_ExistsReceiverParityErrorStatus Function C bool PLIB_USART_ExistsReceiverParityErrorStatus( USART_MODULE_ID index ); Description This function identifies whether the ReceiverParityError feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_ReceiverParityErrorHasOccurred Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ReceiverParityError feature is supported on the device • false - The ReceiverParityError feature is not supported on the device Remarks None. 5.6.25.5.6.25 PLIB_USART_ExistsStopInIdle Function C bool PLIB_USART_ExistsStopInIdle( 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3156 USART_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_StopInIdleEnable • PLIB_USART_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.25.5.6.26 PLIB_USART_ExistsSyncClockPolarity Function C bool PLIB_USART_ExistsSyncClockPolarity( USART_MODULE_ID index ); Description This function identifies whether the SyncClockPolarity feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_SyncClockPolarityIdleHighDisable • PLIB_USART_SyncClockPolarityIdleHighEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SyncClockPolarity feature is supported on the device • false - The SyncClockPolarity feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3157 5.6.25.5.6.27 PLIB_USART_ExistsSyncClockSource Function C bool PLIB_USART_ExistsSyncClockSource( USART_MODULE_ID index ); Description This function identifies whether the SyncClockSource feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_SyncClockSourceSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SyncClockSource feature is supported on the device • false - The SyncClockSource feature is not supported on the device Remarks None. 5.6.25.5.6.28 PLIB_USART_ExistsSyncMode Function C bool PLIB_USART_ExistsSyncMode( USART_MODULE_ID index ); Description This function identifies whether the SyncMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_SyncModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SyncMode feature is supported on the device • false - The SyncMode feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3158 5.6.25.5.6.29 PLIB_USART_ExistsTransmitter Function C bool PLIB_USART_ExistsTransmitter( USART_MODULE_ID index ); Description This function identifies whether the Transmitter feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterByteSend Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Transmitter feature is supported on the device • false - The Transmitter feature is not supported on the device Remarks None. 5.6.25.5.6.30 PLIB_USART_ExistsTransmitter9BitsSend Function C bool PLIB_USART_ExistsTransmitter9BitsSend( USART_MODULE_ID index ); Description This function identifies whether the Transmitter9Bits feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_Transmitter9BitsSend Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The Transmitter9Bits feature is supported on the device • false - The Transmitter9Bits feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3159 5.6.25.5.6.31 PLIB_USART_ExistsTransmitterBreak Function C bool PLIB_USART_ExistsTransmitterBreak( USART_MODULE_ID index ); Description This function identifies whether the TransmitterBreak feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterBreakSend • PLIB_USART_TransmitterBreakSendIsComplete Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterBreak feature is supported on the device • false - The TransmitterBreak feature is not supported on the device Remarks None. 5.6.25.5.6.32 PLIB_USART_ExistsTransmitterBufferFullStatus Function C bool PLIB_USART_ExistsTransmitterBufferFullStatus( USART_MODULE_ID index ); Description This function identifies whether the TransmitterBufferFull feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterBufferIsFull Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterBufferFull feature is supported on the device • false - The TransmitterBufferFull feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3160 5.6.25.5.6.33 PLIB_USART_ExistsTransmitterEmptyStatus Function C bool PLIB_USART_ExistsTransmitterEmptyStatus( USART_MODULE_ID index ); Description This function identifies whether the TransmitterEmpty feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterIsEmpty Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterEmpty feature is supported on the device • false - The TransmitterEmpty feature is not supported on the device Remarks None. 5.6.25.5.6.34 PLIB_USART_ExistsTransmitterEnable Function C bool PLIB_USART_ExistsTransmitterEnable( USART_MODULE_ID index ); Description This function identifies whether the TransmitterEnableControl feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterEnable • PLIB_USART_TransmitterDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterEnableControl feature is supported on the device • false - The TransmitterEnableControl feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3161 5.6.25.5.6.35 PLIB_USART_ExistsTransmitterIdleIsLow Function C bool PLIB_USART_ExistsTransmitterIdleIsLow( USART_MODULE_ID index ); Description This function identifies whether the TransmitterIdleIsLow feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_TransmitterIdleIsLowDisable • PLIB_USART_TransmitterIdleIsLowEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterIdleIsLow feature is supported on the device • false - The TransmitterIdleIsLow feature is not supported on the device Remarks None. 5.6.25.5.6.36 PLIB_USART_ExistsTransmitterIdleStatus Function C bool PLIB_USART_ExistsTransmitterIdleStatus( USART_MODULE_ID index ); Description This function identifies whether the TransmitterIdle feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterIsIdle Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterIdle feature is supported on the device • false - The TransmitterIdle feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3162 5.6.25.5.6.37 PLIB_USART_ExistsTransmitterInterruptMode Function C bool PLIB_USART_ExistsTransmitterInterruptMode( USART_MODULE_ID index ); Description This function identifies whether the TransmitterInterruptMode feature is available on the USART module. When this function returns true, this function is supported on the device: • PLIB_USART_TransmitterInterruptModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TransmitterInterruptMode feature is supported on the device • false - The TransmitterInterruptMode feature is not supported on the device Remarks None. 5.6.25.5.6.38 PLIB_USART_ExistsWakeOnStart Function C bool PLIB_USART_ExistsWakeOnStart( USART_MODULE_ID index ); Description This function identifies whether the WakeOnStart feature is available on the USART module. When this function returns true, these functions are supported on the device: • PLIB_USART_WakeOnStartEnable • PLIB_USART_WakeOnStartDisable • PLIB_USART_WakeOnStartIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WakeOnStart feature is supported on the device • false - The WakeOnStart feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3163 Remarks None. 5.6.25.6 Files Files Name Description plib_usart.h Universal Synchronous/Asynchronous Receiver/Transmitter (USART) Peripheral Library interface header for USART functions. Description 5.6.25.6.1 plib_usart.h USART Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USART Peripheral Library for all families of Microchip microcontrollers. The functions in this file are common to the USART module. Functions Name Description PLIB_USART_AlternateIODisable Disables the use of alternate I/O pins for the receiver and transmitter. PLIB_USART_AlternateIOEnable Enables the use of alternate I/O pins for the receiver and transmitter. PLIB_USART_BaudRateAutoDetectEnable Enables baud rate measurement on the next character, which requires reception of the Sync character. PLIB_USART_BaudRateAutoDetectIsComplete Gets the state of the automatic baud detection. PLIB_USART_BaudRateAutoDetectOverflowHasOccurred Identifies if the automatic baud timer has overflowed. PLIB_USART_BaudRateGet Gets the baud rate current in use. PLIB_USART_BaudRateHighDisable Disables the high baud rate selection. PLIB_USART_BaudRateHighEnable Enables high baud rate selection. PLIB_USART_BaudRateHighSet Sets the baud rate to the desired value. PLIB_USART_BaudRateModeSelect Enables the 16-bit Baud Rate Generator (BRG). PLIB_USART_BaudRateSet Sets the baud rate to the desired value. PLIB_USART_Disable Disables the specific USART module PLIB_USART_Enable Enables the specific USART module. PLIB_USART_ExistsAlternateIO Identifies whether the AlternateIOEnableControl feature exists on the USART module. PLIB_USART_ExistsBaudRate Identifies whether the BaudRate feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetect Identifies whether the BaudRateAutoDetect feature exists on the USART module. PLIB_USART_ExistsBaudRateAutoDetectOverflow Identifies whether the BaudRateAutoDetectOverflow feature exists on the USART module. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3164 PLIB_USART_ExistsBaudRateBitMode Identifies whether the BaudRateMode feature exists on the USART module. PLIB_USART_ExistsBaudRateHigh Identifies whether the BaudRateHigh feature exists on the USART module. PLIB_USART_ExistsEnable Identifies whether the EnableControl feature exists on the USART module. PLIB_USART_ExistsHandshakeMode Identifies whether the HandShakeMode feature exists on the USART module. PLIB_USART_ExistsIrDA Identifies whether the IrDAControl feature exists on the USART module. PLIB_USART_ExistsLineControlMode Identifies whether the LineControlMode feature exists on the USART module. PLIB_USART_ExistsLoopback Identifies whether the Loopback feature exists on the USART module. PLIB_USART_ExistsOperationMode Identifies whether the OperationMode feature exists on the USART module. PLIB_USART_ExistsReceiver Identifies whether the Receiver feature exists on the USART module. PLIB_USART_ExistsReceiverAddressAutoDetect Identifies whether the ReceiverAddressAutoDetect feature exists on the USART module. PLIB_USART_ExistsReceiverAddressDetect Identifies whether the ReceiverAddressDetect feature exists on the USART module. PLIB_USART_ExistsReceiverDataAvailableStatus Identifies whether the ReceiverDataAvailable feature exists on the USART module PLIB_USART_ExistsReceiverEnable Identifies whether the ReceiverEnableControl feature exists on the USART module. PLIB_USART_ExistsReceiverFramingErrorStatus Identifies whether the ReceiverFramingError feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStateLowEnable Identifies whether the ReceiverPolarityInvert feature exists on the USART module. PLIB_USART_ExistsReceiverIdleStatus Identifies whether the ReceiverIdle feature exists on the USART module. PLIB_USART_ExistsReceiverInterruptMode Identifies whether the ReceiverInterruptMode feature exists on the USART module. PLIB_USART_ExistsReceiverMode Identifies whether the ReceiverMode feature exists on the USART module. PLIB_USART_ExistsReceiverOverrunStatus Identifies whether the ReceiverOverrunError feature exists on the USART module. PLIB_USART_ExistsReceiverParityErrorStatus Identifies whether the ReceiverParityError feature exists on the USART module. PLIB_USART_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USART module. PLIB_USART_ExistsSyncClockPolarity Identifies whether the SyncClockPolarity feature exists on the USART module. PLIB_USART_ExistsSyncClockSource Identifies whether the SyncClockSource feature exists on the USART module. PLIB_USART_ExistsSyncMode Identifies whether the SyncMode feature exists on the USART module. PLIB_USART_ExistsTransmitter Identifies whether the Transmitter feature exists on the USART module. PLIB_USART_ExistsTransmitter9BitsSend Identifies whether the Transmitter9Bits feature exists on the USART module. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3165 PLIB_USART_ExistsTransmitterBreak Identifies whether the TransmitterBreak feature exists on the USART module. PLIB_USART_ExistsTransmitterBufferFullStatus Identifies whether the TransmitterBufferFull feature exists on the USART module. PLIB_USART_ExistsTransmitterEmptyStatus Identifies whether the TransmitterEmpty feature exists on the USART module. PLIB_USART_ExistsTransmitterEnable Identifies whether the TransmitterEnableControl feature exists on the USART module PLIB_USART_ExistsTransmitterIdleIsLow Identifies whether the TransmitterIdleIsLow feature exists on the USART module. PLIB_USART_ExistsTransmitterIdleStatus Identifies whether the TransmitterIdle feature exists on the USART module. PLIB_USART_ExistsTransmitterInterruptMode Identifies whether the TransmitterInterruptMode feature exists on the USART module. PLIB_USART_ExistsWakeOnStart Identifies whether the WakeOnStart feature exists on the USART module. PLIB_USART_HandshakeModeSelect Sets the data flow configuration. PLIB_USART_IrDADisable Disables the IrDA encoder and decoder. PLIB_USART_IrDAEnable Enables the IrDA encoder and decoder. PLIB_USART_LineControlModeSelect Sets the data flow configuration. PLIB_USART_LoopbackDisable Disables Loopback mode. PLIB_USART_LoopbackEnable Enables Loopback mode. PLIB_USART_OperationModeSelect Configures the operation mode of the USART module. PLIB_USART_ReceiverAddressAutoDetectDisable Disables the automatic Address Detect mode. PLIB_USART_ReceiverAddressAutoDetectEnable Setup the automatic Address Detect mode. PLIB_USART_ReceiverAddressDetectDisable Enables the Address Detect mode. PLIB_USART_ReceiverAddressDetectEnable Enables the Address Detect mode. PLIB_USART_ReceiverAddressIsReceived Checks and return if the data received is an address. PLIB_USART_ReceiverByteReceive Data to be received in the Byte mode. PLIB_USART_ReceiverDataIsAvailable Identifies if the receive data is available for the specified USART module. PLIB_USART_ReceiverDisable Disables the USART receiver. PLIB_USART_ReceiverEnable Enables the USART receiver. PLIB_USART_ReceiverFramingErrorHasOccurred Gets the framing error status. PLIB_USART_ReceiverIdleStateLowDisable Disables receive polarity inversion. PLIB_USART_ReceiverIdleStateLowEnable Enables receive polarity inversion. PLIB_USART_ReceiverInterruptModeSelect Sets the USART receiver FIFO level. PLIB_USART_ReceiverIsIdle Identifies if the receiver is idle. PLIB_USART_ReceiverModeSelect Disables Single Receive mode. PLIB_USART_ReceiverOverrunErrorClear Clears a USART Overrun error. PLIB_USART_ReceiverOverrunHasOccurred Identifies if there was a receiver overrun error. PLIB_USART_ReceiverParityErrorHasOccurred Gets the parity error status. PLIB_USART_StopInIdleDisable Disables the Stop in Idle mode (the USART module continues operation when the device is in Idle mode). PLIB_USART_StopInIdleEnable Discontinues operation when the device enters Idle mode. PLIB_USART_SyncClockPolarityIdleHighDisable Sets the idle state of the clock to low. PLIB_USART_SyncClockPolarityIdleHighEnable Sets the idle state of the clock to high. 5.6 Peripheral Library Help MPLAB Harmony Help USART Peripheral Library 5-3166 PLIB_USART_SyncClockSourceSelect Sets the clock source. PLIB_USART_SyncModeSelect Selects the USART mode to be asynchronous. PLIB_USART_Transmitter9BitsSend Data to be transmitted in the byte mode with the 9th bit. PLIB_USART_TransmitterBreakSend Transmits the break character. PLIB_USART_TransmitterBreakSendIsComplete Returns the status of the break transmission PLIB_USART_TransmitterBufferIsFull Gets the transmit buffer full status. PLIB_USART_TransmitterByteSend Data to be transmitted in the Byte mode. PLIB_USART_TransmitterDisable Disables the specific USART module transmitter. PLIB_USART_TransmitterEnable Enables the specific USART module transmitter. PLIB_USART_TransmitterIdleIsLowDisable Disables the Transmit Idle Low state. PLIB_USART_TransmitterIdleIsLowEnable Enables the Transmit Idle Low state. PLIB_USART_TransmitterInterruptModeSelect Set the USART transmitter interrupt mode. PLIB_USART_TransmitterIsEmpty Gets the transmit shift register empty status. PLIB_USART_TransmitterIsIdle Gets the transmit buffer full status. PLIB_USART_WakeOnStartDisable Disables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartEnable Enables the wake-up on start bit detection feature during Sleep mode. PLIB_USART_WakeOnStartIsEnabled Gets the state of the sync break event completion. File Name plib_usart.h Company Microchip Technology Inc. 5.6.26 USB Peripheral Library 5.6.26.1 Introduction This library provides a low-level abstraction of the USB module on Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, thus hiding differences from one microcontroller variant to another. Description USB Peripheral Library for Microchip Microcontrollers 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3167 USB Overview USB is an asynchronous serial interface with a tiered star configuration. USB is implemented as a master/slave configuration. On a given bus, there can be multiple (up to 127) slaves (devices), but there is only one master (host). There are three possible module implementations: host, device and OTG dual role. The user should have an understanding of the USB documents available on the USB implementers web site (www.usb.org). Device The USB device accepts data from the host and responds to requests for data. It performs some peripheral functions, such as a mouse or data storage device. • Functionality may be class or vendor-specific • Draws 100 mA or less before configuration • Can draw up to 500 mA after successful negotiation with the host • Can support low-speed, full-speed or hi-speed protocol. Hi-speed support requires implementation of full-speed. (Low, Full, and Hi-Speed supported by this module.) • Supports control transfers. Supports data transfers required for implementation • Optionally supports Session Request Protocol (SRP) • Can be bus-powered or self-powered Host The host is the master in a USB system and is responsible for identifying all devices connected to it (enumeration), initiating all transfers, allocating bus bandwidth and supplying power to any bus-powered USB devices connected directly to it. There are two types of hosts. USB Standard Host: • A large variety of devices are supported • This host supports all USB transfer types • USB hubs are supported to allow connection of multiple devices simultaneously • Device drivers can be updated to support new devices • A type ‘A’ receptacle is used for each port • Each port must be able to deliver a minimum of 100 mA for a configured or unconfigured 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3168 • device, and optionally, up to 500 mA for a configured device • Full-Speed and Low-Speed must be supported. Hi-Speed can be supported. • This is a typical personal computer implementation Embedded Host • Only supports a specific list of devices, referred to as a Targeted Peripheral List (TPL) • This type of host is only required to support transfer types required by devices in the TPL • USB hub support is optional (Provided in this module) • Device drivers are not required to be pocketable • A type ‘A’ receptacle is used for each port • Only speeds required by devices in the TLP must be supported. (Low, Full, and Hi-Speed supported by this module.) • Each port must be able to deliver a minimum of 100 mA for a configured or unconfigured device, and optionally, up to 500 mA for a configured device • This is a typical implementation for a microcontroller USB On-the-Go (OTG) The OTG dual role device supports both USB host and device functionality. OTG dual role devices use a micro-AB receptacle. This allows a micro-A or a micro-B plug to be attached. Both the micro-A and micro-B plugs have an additional pin, the ID pin, to signify the connect type. The plug type, micro-A or micro-B, determines the default role of the OTG device, host or USB device. An OTG device will perform the role of a host when a micro-A plug is detected. When a micro-B plug is detected, the role of a USB device is performed. When an OTG device is directly connected to another OTG device using an OTG cable, micro-A to micro-B, Host Negotiation Protocol (HNP) can be used to swap the roles of the host and USB device between the two without disconnecting and reconnecting cabling. To differentiate between the two OTG devices, the term, “A-device”, is used to refer to the device connected to the micro-A plug and “B-device” is used to refer to the OTG device connected to the micro-B plug. OTG dual role operating as a host (A-device): • Only supports a specific list of devices, referred to as a Targeted Peripheral List (TPL). Generic class support is not allowed. • Only required to support transaction types required by devices in the TPL • USB hub support is optional. (Multi-point support provided by this module.) • Device drivers are not required to be pocketable • Only a single micro-AB receptacle is used • Only full speed must be supported. Hi-Speed and/or Low-Speed can be supported. (Low, Full, and Hi-Speed supported by this module.) • The USB port must be able to deliver a minimum of 8 mA for a configured or unconfigured device, and optionally, up to 500 mA for a configured device • Supports Host Negotiation Protocol (HNP) and Session Request Protocol (SRP). The host can switch roles to become a device. The initial role as a host or device is determined by the plug type, micro-A or micro-B, inserted into the micro-AB receptacle • The A-device supplies VBUS power, when the bus is powered, even if the roles are swapped using HNP OTG dual role operating as a USB device (B-device): • Class or vendor-specific functionality • Draws 8 mA or less before configuration • Is typically self-powered due to low-current requirements, but can draw up to 500 mA after successful negotiation with the host 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3169 • Only a single micro-AB receptacle is used • Must support Full-Speed. Support of low speed and/or Hi-Speed is optional • Supports control transactions. Supports data transactions required for implementation. • Supports Session Request Protocol (SRP) and/or Host Negotiation Protocol (HNP). (This module supports both SRP and HNP.) • The A-device supplies VBUS power, when the bus is powered, even if the roles are swapped using HNP Additional Features of the Hi-Speed USB Module • Operates either as a function controller of a Hi-Speed/Full-Speed USB device or as the host/device in a point-to-point or multi-point communications with other USB function • Supports OTG communications with on or more Hi-Speed, Full-Speed, or Low-Speed devices • Provides soft connect/disconnect. • In addition to Endpoint Zero, supports seven transmit and seven receive endpoints • Dynamic FIFO sizing for Endpoints 1-7. (Endpoint Zero FIFO fixed at 64 bytes.) FIFOs use module-internal SRAM. • Module-internal eight channel DMA with access to all FIFOs • All host transaction scheduling supported in hardware • Supports Link Power Management 5.6.26.2 Release Notes MPLAB Harmony Version: v0.70b USB PLIB Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.26.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3170 5.6.26.4 Using the Library This topic describes the basic architecture of the USB Peripheral Library and provides information and examples on how to use it. Interface Header File: peripheral.h The interface to the USB Peripheral Library is defined in the "plib_usb.h" header file, which is included by the "peripheral.h" peripheral library header file. Any C language source (.c) file that uses the USB Peripheral Library must include "peripheral.h". Library File: The USB Peripheral Library is part of the processor-specific peripheral library archive (.a) file installed with the compiler. Libraries in this archive are automatically available to the linker (in the default search path) for any project built using the Microchip compiler. 5.6.26.4.1 Hardware Abstraction Models This section describes the hardware abstraction model for the USB Peripheral Library. Description Hardware Abstraction Model Figure 1. shows the USB Module for the PIC32 family of devices. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3171 Figure 1: PIC32 USB Module The USB OTG module contains analog and digital components to provide a USB 2.0 full-speed and low-speed embedded host, full-speed device, or On-The-Go (OTG) implementation with a minimum of external components. This module in Host mode is intended for use as an embedded host and therefore does not implement a Universal Host Controller Interface (UHCI) or a Open Host Controller Interface (OHCI). The USB OTG module consists of the clock generator, the USB voltage comparators, the transceiver, the Serial Interface Engine (SIE), a dedicated USB Bus Master, pull-up and pull-down resistors and the register interface. The clock generator provides the 48 MHz clock, which is required for USB full-speed and low-speed communication. The voltage comparators monitor the voltage on the VBUS pin to determine the state of the bus. The transceiver provides the analog translation between the USB bus and the digital logic. The SIE is a state machine that transfers data to and from the endpoint buffers, and generates the hardware protocol for data transfers. The USB Bus Master transfers data between the data buffers in RAM and the SIE. The integrated pull-up and pull-down resistors eliminate the need for external signaling components. The register interface allows the CPU to configure and communicate with the module. Figure 2 shows the USB module found in PIC24/dsPIC33 devices. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3172 Figure 2: PIC24/dsPIC33 USB Module The two implementations are nearly identical, but the PIC24/dsPIC33 USB module also supports using an external USB transceiver. Figure 3 provides an example of a USB module on an 8-bit device. Figure 3: PIC18 USB Module 5.6.26.4.2 Library Overview This library provides the low level abstraction of the USB Peripheral on Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Description Figure 4 describes the abstraction model employed by the USB Peripheral Library. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3173 Figure 4: USB Peripheral Library Abstraction Model The peripheral functions are grouped together under different function groups. These application must then use a combination of function from the different function groups to achieve the desired USB peripheral operation. Library Interface Section Description USB Setup Functions This section provides functions to perform general USB peripheral setup such as functions to set USB Speed, control on-chip pull ups, etc. Buffer Descriptor Table Functions This section provides functions that allow the application to setup, configure and access/modify the Buffer Descriptors in the Buffer Descriptor Table. USB Activity Functions This section provides function that allow the application to monitor bus conditions on the USB. USB Bus Signaling Functions This section provides functions that allow the application to generate Reset and Resume Signaling. Last Transaction Status Functions This section provides functions that allow the application to query conditions of the USB peripheral. Endpoints Functions This section provides functions that allow the application to manage endpoints. Interrupts Functions This section provides functions that allow the application to enable, disable and query the status interrupts in the USB peripheral. Host Functions This section provides functions that are required to operate the USB module while in Host mode. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3174 On-The-Go (OTG) Functions This section provides functions that are required to operate the USB module while in OTG mode. External Transceiver Support Functions This section provides function that are required to operate to enable/disable the external transceiver interface. VBus Support Functions This section provides functions that allow VBUS level monitoring and VBUS boost PWM module control. Test Support Functions This section provides functions that enable/disable test signals needed for eye pattern measurement. 5.6.26.4.3 USB Buffers and the Buffer Descriptor Table (BDT) This section describes USB buffers and the Buffer Descriptor Table. Description All USB endpoints are implemented using buffers and control bits in RAM. Both software and the USB module have access to these buffers and control bits. To arbitrate this access a semaphore flag system is used. Each endpoint can be configured for transmit only, receive only or transmit and receive. Transmit and receive functions have separate buffers. For each buffer there is a Buffer Descriptor (BD) in the Buffer Descriptor Table (BDT). On most devices the BDT has room for two transmit and two receive buffers for each endpoint, supporting ping-pong buffering. Buffer descriptors must be aligned on 512 byte boundaries to enable the USB module to correctly read each entry. The starting address of the Buffer Descriptor Table is set by the PLIB_USB_BDTBaseAddressSet. #define USB_MAX_EP_NUMBER 15 #define USB_PING_PONG_MODE_SELECTION USB_PING_PONG__FULL_PING_PONG #if (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__NO_PING_PONG) #define BDT_NUM_ENTRIES ((USB_MAX_EP_NUMBER + 1) * 2) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__EP0_OUT_ONLY) #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 2)+1) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__FULL_PING_PONG) #define BDT_NUM_ENTRIES ((USB_MAX_EP_NUMBER + 1) * 4) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__ALL_BUT_EP0) #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 4)-2) #else #error "No ping pong mode defined." #endif #if defined(__18CXX) #pragma udata gBDT=USB_BDT_ADDRESS #elif defined(__PIC32MX__) volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES] __attribute__ (( aligned (512) )); #else volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES]; #endif//defined(__18CXX)) (For PIC18 devices, this isn't necessary since the BDT always starts at 0x0400 in memory.) Each Buffer Descriptor entry in the BDT has a bufferAddress pointer to the Buffer Descriptor's buffer in memory (RAM or FLASH). Figure 5 shows the structure for most PIC24 and all PIC32 devices. These devices support ping-pong buffering for all endpoints. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3175 Figure 5: Buffer Descriptor Table and Endpoint Buffers With 16 endpoints (Endpoints 0 - 15 ) there are 64 possible entries in the Buffer Descriptor Table: // (Even,Odd) or (Ping,Pong) // (Rx,Tx) | // (EP0 to EPn) | | volatile USB_BDT_ENTRY myBDT[(USB_MAX_EP_NUMBER + 1)][2][2] __attribute__ (( aligned (512) )); On PIC18F and PIC24F devices, ping-pong buffering can be disabled for all of some of the endpoints. Figure 6 shows the buffering options available for PIC24F devices and Figure 7 shows the buffering options available for PIC18F devices. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3176 Figure 6: Buffer Descriptor Table Mapping for Various PIC24F Ping-Pong Configurations 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3177 Figure 7: Buffer Descriptor Table Mapping for Various PIC18F Ping-Pong Configurations Peripheral library functions are provided to support reading each BD while hiding the details of BDT addressing that can change when ping-pong buffering is disabled for one or more endpoints. The format of Buffer Descriptors vary from family to family and it is not important to know the differences, since peripheral library functions hide these details. To understand the information stored in each Buffer Descriptor Table entry it is informative to look at the C language description for one family of devices. (All device families support the same information but with different ways of packing the data into memory.) For most PIC24/dsPIC33 devices and all PIC32 devices each BD is 8 bytes long and is described by this C code: typedef union _USB_BDT_ENTRY __attribute__ ((packed)) { uint64_t dlValue; //Double Long Integer Value uint32_t lValue[2]; //Long Integer Values uint16_t sValue[4]; //Short Integer Values struct __attribute__ ((packed)) { USB_BD_STATUS bufferStatus; //(RW) Buffer Status uint16_t byteCount:10; //(RW) Byte Count uint8_t : 6; //( ) Reserved 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3178 uint32_t bufferAddress; //(RW) Buffer Address in Data Ram or Flash }; } USB_BDT_ENTRY; For transmit buffers byteCount is set to the length of the buffer using PLIB_USB_BufferByteCountSet. For receive buffers PLIB_USB_BufferByteCountSet is used to set the maximum allowable receive data length. PLIB_USB_BufferByteCountGet is used to determine how many bytes were actually transmitted or received. The memory address of each buffer is found in bufferAddress. The functions PLIB_USB_BufferAddressSet and PLIB_USB_BufferAddressGet support this field in the Buffer Descriptor. Buffer status is stored in the 16 least significant bits of each BDT entry: typedef union _USB_BD_STATUS __attribute__ ((packed)) { uint16_t sValue; //Short Integer Value struct __attribute__ ((packed)) { uint8_t :2; //( )Reserved uint8_t stallEnable :1; //( W) Buffer Stall Enable uint8_t dataToggleSyncEnable :1; //( W) Data Toggle Synch Enable uint8_t :1; //( ) Reserved uint8_t :1; //( ) Reserved uint8_t dataToggle :1; //(RW) Data Toggle Synch Value uint8_t uSBOwnsBuffer :1; //(RW) USB Ownership of buffer and BDT entry }; struct __attribute__ ((packed)) { uint8_t :2; //( ) Reserved uint8_t packetID :4; //(R ) Packet Identifier (PID) }; } USB_BD_STATUS; The fields stallEnable and dataToggleSyncEnable in the Buffer Descriptor status structure are writable but not readable. The function PLIB_USB_BufferStallEnable sets the stallEnable bit. (Hardware will clear the bit after receiving a SETUP token from the host.) The functions PLIB_USB_BufferDataToggleSyncEnable and PLIB_USB_BufferDataToggleSyncDisable manipulate dataToggleSyncEnable . On a read from the status structure stallEnable and dataToggleSyncEnable and the next two (reserved) bits are replaced by the Packet Identifier (PID), called packetID in the structure. The function PLIB_USB_BufferPIDGet reads packetID. The rest of the status structure is writable and readable: dataToggle and uSBOwnsBuffer. The dataToggle (DATA0 or DATA1) of a receive buffer is determined by using PLIB_USB_BufferDataToggleGet. For transmit buffers the dataToggle value is set using PLIB_USB_BufferDataToggleSelect . The field uSBOwnsBuffer is used by both software and the USB module as a semaphore. The function PLIB_USB_BufferReleaseToUSB releases the buffer to the USB module and the function PLIB_USB_BufferReleasedToSW returns a boolean true when the buffer is released back to software by the USB module. As long as PLIB_USB_BufferReleasedToSW returns false, software should not change the Buffer Descriptor Table entry or its associated buffer. 5.6.26.4.4 USB Setup Example This section provides example code for setting up the USB module. Description Following is an example of how to set up the USB module: #define USB_MAX_EP_NUMBER 15 #define USB_PING_PONG_MODE_SELECTION USB_PING_PONG__FULL_PING_PONG 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3179 #if (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__NO_PING_PONG) #define BDT_NUM_ENTRIES ((USB_MAX_EP_NUMBER + 1) * 2) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__EP0_OUT_ONLY) #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 2)+1) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__FULL_PING_PONG) #define BDT_NUM_ENTRIES ((USB_MAX_EP_NUMBER + 1) * 4) #elif (USB_PING_PONG_MODE_SELECTION == USB_PING_PONG__ALL_BUT_EP0) #define BDT_NUM_ENTRIES (((USB_MAX_EP_NUMBER + 1) * 4)-2) #else #error "No ping pong mode defined." #endif #if defined(__18CXX) #pragma udata gBDT=USB_BDT_ADDRESS #elif defined(__PIC32MX__) volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES] __attribute__ (( aligned (512) )); #else volatile union USB_BDT_ENTRY_TAG gBDT[BDT_NUM_ENTRIES]; #endif//defined(__18CXX)) unsigned int bufferTransactionCount[BDT_NUM_ENTRIES]; // Turn off USB module PLIB_USB_Disable( usbID ); // Setup the Hardware if ( usbModuleSetup.StopInIdle ) { PLIB_USB_StopInIdleEnable( usbID ); } else { PLIB_USB_StopInIdleDisable( usbID ); } if ( usbModuleSetup.SuspendInSleep ) { PLIB_USB_AutoSuspendEnable( usbID ); } else { PLIB_USB_AutoSuspendDisable( usbID ); } PLIB_USB_OperatingModeSelect( usbID, usbModuleSetup.OpMode ); PLIB_USB_PingPongModeSelect( usbID, usbModuleSetup.ppMode ); // Reset all ping pong buffers to "Even" PLIB_USB_PingPongFreeze( usbID ); PLIB_USB_PingPongUnfreeze( usbID ); // Interrupt flag cleared on the safer side IFS1bits.USBIF = 0; // Enable USB module interrupts PLIB_USB_InterruptEnable( usbID, DRV_USB_GEN_INT_ENABLES ); // Disable all OTG interrupts PLIB_USB_OTG_InterruptDisable( usbID, DRV_USB_OTB_INT_ENABLES ); // Enable all Error interrupts PLIB_USB_ErrorInterruptEnable( usbID, DRV_USB_ERR_INT_ENABLES ); // Enable the interrupt source in case of interrupt mode 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3180 IEC1bits.USBIE = 1; // Setting the Interrupt Prioriry in case of interrupt mode. IPC11bits.USBIP = 4; // Initialize BDT for ( iEntry = 0; iEntry < BDT_NUM_ENTRIES; iEntry++ ) { #if (defined(__18CXX) || defined(__PIC24F__)) gBDT[iEntry].lValue = 0ul; #elif (defined (__dsPIC33E__) || defined (__PIC24E__) || defined(__PIC32MX__)) gBDT[iEntry].lValue[0] = 0ul; gBDT[iEntry].lValue[1] = 0ul; #else #error "Unknown device type" #endif bufferTransactionCount[iEntry] = 0; }//end for ( iEntry = 0; iEntry < BDT_NUM_ENTRIES; iEntry++ ) // Inform USB module of BDT's address in memory #if defined(__PIC32MX__) // For PIC32 PLIB_USB_BDTBaseAddressSet( usbID , (void *)((uint32_t)KVA_TO_PA(gBDT)) ); #else // Everybody else PLIB_USB_BDTBaseAddressSet(MY_USB_INSTANCE, (void *)(&gBDT) ); #endif /***********************/ /* SETUP ENDPOINT ZERO */ /***********************/ PLIB_USB_BufferAddressSet( usbID, (void*)gBDT, PLIB_USB_PingPongModeGet( usbID ), 0, USB_BUFFER_RX, USB_BUFFER_EVEN, pSetupRcvBuffer ); // Configure Endpoint Zero control register PLIB_USB_EP0LSDirectConnectDisable( usbID ); // For Hosts, included for completeness PLIB_USB_EP0NakRetryEnable( usbID ); // For Hosts, included for completeness PLIB_USB_EPnControlTransferEnable( usbID, 0 ); // Enable control transfers PLIB_USB_EPnRxSelect( usbID, 0, USB_EP_RX ); // Enable receive PLIB_USB_EPnHandshakeEnable( usbID, 0 ); // Enable handshaking // Setup Endpoint Zero's receive buffer BDT entries ppMode = PLIB_USB_PingPongModeGet( usbID ); // Ping Pong Mode needed for BDT entry indexing // Clear PID bits PLIB_USB_BufferPIDBitsClear(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); //Rx0 // Disable buffer stall PLIB_USB_BufferStallDisable(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); //Rx0 // Enable Data Toggle Synchronization PLIB_USB_BufferDataToggleSyncEnable(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVE N); //Rx0 // Set Data0/1 to Data0 PLIB_USB_BufferDataToggleSelect(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN,US B_BUFFER_DATA0); //Rx0 // Setup packets have 8 bytes of data payload PLIB_USB_BufferByteCountSet(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN,8); // Release buffers to USB module 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3181 PLIB_USB_BufferReleaseToUSB(usbID,(void*)gBDT,ppMode,0,USB_BUFFER_RX,USB_BUFFER_EVEN); PLIB_USB_Enable( gDrvUSBObj[hDriver].usbID ); // Turn on USB module 5.6.26.5 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6.26.6 Library Interface Data Types and Constants Name Description USB_BUFFER_DATA01 Provides enumeration data toggle for a buffer. USB_BUFFER_DIRECTION Provides enumeration transmit/receive direction for a buffer. USB_BUFFER_PING_PONG Enumerates the ping-pong buffer (Even vs. Odd). USB_BUFFER_SCHEDULE_DATA01 Provides enumeration data toggle for a buffer. USB_EP_TXRX Provides enumeration transmit/receive setup for an endpoint. USB_OPMODES Provides enumeration of operating modes supported by USB. USB_OTG_INTERRUPTS Provides enumeration of interrupts related to the USB On-The-Go (OTG) module. USB_OTG_PULL_UP_PULL_DOWN USB OTG pull-Up and pull-Down resistors for D+ and D- . USB_PID Legal PID values. USB_PING_PONG_MODE Supports the four modes of ping-pong buffering for PIC18 and PIC24F devices. USB_PING_PONG_STATE Decodes which buffer (Even vs. Odd) was used for the last transaction. USB_TOKEN_SPEED Provides enumeration of available token speeds. USB_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). Buffer Descriptor Table Functions Name Description PLIB_USB_BDTBaseAddressGet Returns the base address of the Buffer Descriptor Table. PLIB_USB_BDTBaseAddressSet Sets the base address for the Buffer Descriptor Table for PIC24 and PIC32 devices. PLIB_USB_BufferAddressGet Gets the memory address of an endpoint buffer. PLIB_USB_BufferAddressSet Sets the endpoint buffer address. PLIB_USB_BufferAllCancelReleaseToUSB Cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. PLIB_USB_BufferByteCountGet Returns the endpoint buffer byte count. PLIB_USB_BufferByteCountSet Sets the buffer byte count. PLIB_USB_BufferCancelReleaseToUSB Cancels release of the endpoint buffer by software, allowing software to again access the buffer. PLIB_USB_BufferClearAll Clears (zeros out) entries in the Buffer Descriptor Table. PLIB_USB_BufferClearAllDTSEnable Clears the endpoint descriptor entry and enables data toggle synchronization. PLIB_USB_BufferDataToggleGet Returns data synchronization (DATA0 or DATA1) for the endpoint buffer. PLIB_USB_BufferDataToggleSelect Sets the endpoint buffer to DATA0 or DATA1. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3182 PLIB_USB_BufferDataToggleSyncDisable Disables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferDataToggleSyncEnable Enables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferEP0RxStatusInitialize Initializes the Endpoint 0 RX endpoint buffer descriptors. PLIB_USB_BufferIndexGet Gets the Buffer Descriptor Table index for a buffer. PLIB_USB_BufferPIDBitsClear Clears the Buffer Status bits in the Buffer Descriptor Table. PLIB_USB_BufferPIDGet Returns the token packet ID (PID) from the endpoint buffer status. PLIB_USB_BufferReleasedToSW Returns the boolean flag value of 'true' when the buffer has been released by the USB module. PLIB_USB_BufferReleaseToUSB Releases the endpoint buffer by software, allowing the USB module access to the buffer. PLIB_USB_BufferSchedule Hands over a buffer to the USB module along with the buffer address and byte count. PLIB_USB_BufferStallDisable Disables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallEnable Enables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallGet Returns the buffer stall status for an endpoint/direction/ping-pong. Endpoints Functions Name Description PLIB_USB_EP0HostSetup Sends token to the specified address. PLIB_USB_EP0LSDirectConnectDisable Disables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0LSDirectConnectEnable Enables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0NakRetryDisable Disables retrying of NAKed transactions. PLIB_USB_EP0NakRetryEnable Enables retrying NAK'd transactions for Endpoint 0. PLIB_USB_EPnAttributesClear Clears the set attributes of the specified endpoint. PLIB_USB_EPnAttributesSet Configures attributes of the endpoint such as direction, handshake capability and direction. PLIB_USB_EPnControlTransferDisable Disables endpoint control transfers. PLIB_USB_EPnControlTransferEnable Enables endpoint control transfers. PLIB_USB_EPnDirectionDisable Disables the specified endpoint direction. PLIB_USB_EPnHandshakeDisable Disables endpoint handshaking. PLIB_USB_EPnHandshakeEnable Enables endpoint handshaking. PLIB_USB_EPnIsStalled Tests whether the endpoint epValue is stalled. PLIB_USB_EPnRxDisable Disables an endpoint's abililty to process IN tokens. PLIB_USB_EPnRxEnable Enables an endpoint to process IN tokens. PLIB_USB_EPnRxSelect Selects receive capabilities of an endpoint. PLIB_USB_EPnStallClear Clears an endpoint's stalled flag. PLIB_USB_EPnTxDisable Disables an endpoint's ability to process OUT tokens. PLIB_USB_EPnTxEnable Enables an endpoint to process OUT tokens. PLIB_USB_EPnTxRxSelect Selects transmit and/or receive capabilities of an endpoint. PLIB_USB_EPnTxSelect Selects transmit capabilities of an endpoint. Error Interrupts Functions Name Description PLIB_USB_ErrorInterruptDisable Disables an error interrupt for the USB module. PLIB_USB_ErrorInterruptEnable Enables an error interrupt for the USB module. PLIB_USB_ErrorInterruptFlagAllGet Returns a logically ORed bit map of active error interrupt flags. PLIB_USB_ErrorInterruptFlagClear Clears an error interrupt flag for the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3183 PLIB_USB_ErrorInterruptFlagGet Tests an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagSet Sets an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptIsEnabled Returns true if interrupts are enabled. External Transceiver Support Functions Name Description PLIB_USB_I2CInterfaceForExtModuleDisable Specifies external module(s) are controlled via dedicated pins. PLIB_USB_I2CInterfaceForExtModuleEnable Specifies external module(s) are controlled via the I2C interface. PLIB_USB_TransceiverDisable Disables the on-chip transceiver PLIB_USB_TransceiverEnable Enables the on-chip transceiver. Feature Existence Functions Name Description PLIB_USB_ExistsActivityPending Identifies whether the ActivityPending feature exists on the USB module. PLIB_USB_ExistsALL_Interrupt Identifies whether the ALL_Interrupt feature exists on the USB module. PLIB_USB_ExistsAutomaticSuspend Identifies whether the AutomaticSuspend feature exists on the USB module. PLIB_USB_ExistsBDTBaseAddress Identifies whether the BDTBaseAddress feature exists on the USB module. PLIB_USB_ExistsBDTFunctions Identifies whether the BDTFunctions feature exists on the USB module. PLIB_USB_ExistsBufferFreeze Identifies whether the BufferFreeze feature exists on the USB module. PLIB_USB_ExistsDeviceAddress Identifies whether the DeviceAddress feature exists on the USB module. PLIB_USB_ExistsEP0LowSpeedConnect Identifies whether the EP0LowSpeedConnect feature exists on the USB module. PLIB_USB_ExistsEP0NAKRetry Identifies whether the EP0NAKRetry feature exists on the USB module. PLIB_USB_ExistsEPnRxEnable Identifies whether the EPnRxEnableEnhanced feature exists on the USB module. PLIB_USB_ExistsEPnTxRx Identifies whether the EPnTxRx feature exists on the USB module. PLIB_USB_ExistsERR_Interrupt Identifies whether the ERR_Interrupt feature exists on the USB module. PLIB_USB_ExistsERR_InterruptStatus Identifies whether the ERR_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsEyePattern Identifies whether the EyePattern feature exists on the USB module. PLIB_USB_ExistsFrameNumber Identifies whether the FrameNumber feature exists on the USB module. PLIB_USB_ExistsGEN_Interrupt Identifies whether the GEN_Interrupt feature exists on the USB module. PLIB_USB_ExistsGEN_InterruptStatus Identifies whether the GEN_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsHostBusyWithToken Identifies whether the HostBusyWithToken feature exists on the USB module. PLIB_USB_ExistsHostGeneratesReset Identifies whether the HostGeneratesReset feature exists on the USB module. PLIB_USB_ExistsLastDirection Identifies whether the LastDirection feature exists on the USB module. PLIB_USB_ExistsLastEndpoint Identifies whether the LastEndpoint feature exists on the USB module. PLIB_USB_ExistsLastPingPong Identifies whether the LastPingPong feature exists on the USB module. PLIB_USB_ExistsLastTransactionDetails Identifies whether the LastTransactionDetails feature exists on the USB module. PLIB_USB_ExistsLiveJState Identifies whether the LiveJState feature exists on the USB module. PLIB_USB_ExistsLiveSingleEndedZero Identifies whether the LiveSingleEndedZero feature exists on the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3184 PLIB_USB_ExistsModuleBusy Identifies whether the ModuleBusy feature exists on the USB module. PLIB_USB_ExistsModulePower Identifies whether the ModulePower feature exists on the USB module. PLIB_USB_ExistsNextTokenSpeed Identifies whether the NextTokenSpeed feature exists on the USB module. PLIB_USB_ExistsOnChipPullup Identifies whether the OnChipPullup feature exists on the USB module. PLIB_USB_ExistsOnChipTransceiver Identifies whether the OnChipTransceiver feature exists on the USB module. PLIB_USB_ExistsOpModeSelect Identifies whether the OpModeSelect feature exists on the USB module. PLIB_USB_ExistsOTG_ASessionValid Identifies whether the OTG_ASessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_BSessionEnd Identifies whether the OTG_BSessionEnd feature exists on the USB module. PLIB_USB_ExistsOTG_IDPinState Identifies whether the OTG_IDPinState feature exists on the USB module. PLIB_USB_ExistsOTG_Interrupt Identifies whether the OTG_Interrupt feature exists on the USB module. PLIB_USB_ExistsOTG_InterruptStatus Identifies whether the OTG_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsOTG_LineState Identifies whether the OTG_LineState feature exists on the USB module. PLIB_USB_ExistsOTG_PullUpPullDown Identifies whether the OTG_PullUpPullDown feature exists on the USB module. PLIB_USB_ExistsOTG_SessionValid Identifies whether the OTG_SessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_VbusCharge Identifies whether the OTG_VbusCharge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusDischarge Identifies whether the OTG_VbusDischarge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusPowerOnOff Identifies whether the OTG_VbusPowerOnOff feature exists on the USB module. PLIB_USB_ExistsPacketTransfer Identifies whether the PacketTransfer feature exists on the USB module. PLIB_USB_ExistsPingPongMode Identifies whether the PingPongMode feature exists on the USB module. PLIB_USB_ExistsResumeSignaling Identifies whether the ResumeSignaling feature exists on the USB module. PLIB_USB_ExistsSleepEntryGuard Identifies whether the SleepEntryGuard feature exists on the USB module. PLIB_USB_ExistsSOFThreshold Identifies whether the SOFThreshold feature exists on the USB module. PLIB_USB_ExistsSpeedControl Identifies whether the SpeedControl feature exists on the USB module. PLIB_USB_ExistsStartOfFrames Identifies whether the StartOfFrames feature exists on the USB module. PLIB_USB_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USB module. PLIB_USB_ExistsSuspend Identifies whether the Suspend feature exists on the USB module. PLIB_USB_ExistsTokenEP Identifies whether the TokenEP feature exists on the USB module. PLIB_USB_ExistsTokenPID Identifies whether the TokenPID feature exists on the USB module. PLIB_USB_ExistsUOEMonitor Identifies whether the UOEMonitor feature exists on the USB module. Host Functions Name Description PLIB_USB_IsBusyWithToken Indicates whether there is a token being executed by the USB module as Host. PLIB_USB_SOFDisable Disables the automatic generation of the SOF token. PLIB_USB_SOFEnable Enables the automatic generation of the SOF token every 1 ms. PLIB_USB_SOFThresholdGet Returns the Start-of-Frame (SOF) Count bits. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3185 PLIB_USB_SOFThresholdSet Sets the Start-of-Frame (SOF) threshold value. PLIB_USB_TokenEPGet Returns the specified Endpoint address. PLIB_USB_TokenEPSet Sets the Endpoint address for a host transaction. PLIB_USB_TokenPIDGet Returns the token transaction type. PLIB_USB_TokenPIDSet Sets the token transaction type to pidValue. PLIB_USB_TokenSpeedSelect Selects low speed or full speed for subsequent token executions. Interrupts Functions Name Description PLIB_USB_InterruptDisable Disables a general interrupt for the USB module. PLIB_USB_InterruptEnable Enables a general interrupt for the USB module. PLIB_USB_InterruptEnableGet Returns the enable/disable status of general USB module interrupts PLIB_USB_InterruptFlagAllGet Returns a logically ORed bit map of active general USB interrupt flags. PLIB_USB_InterruptFlagClear Clears a general interrupt flag for the USB module. PLIB_USB_InterruptFlagGet Tests a general interrupt flag for the USB module. PLIB_USB_InterruptFlagSet Sets a general interrupt flag for the USB module. PLIB_USB_InterruptIsEnabled Returns true if interrupts are enabled. Last Transaction Status Functions Name Description PLIB_USB_LastTransactionDetailsGet Returns the details of the last completed transaction. PLIB_USB_LastTransactionDirectionGet Indicates the direction of the last transaction. PLIB_USB_LastTransactionEndPtGet Returns the endpoint number of the last USB transfer. PLIB_USB_LastTransactionPingPongStateGet Indicates whether the last transaction was to an EVEN buffer or an ODD buffer. On-The-Go (OTG) Functions Name Description PLIB_USB_OTG_BSessionHasEnded Returns the status of the B-Session End Indicator bit. PLIB_USB_OTG_IDPinStateIsTypeA Returns the ID Pin state. PLIB_USB_OTG_LineStateIsStable Returns the status of the Line Stable Indicator bit. PLIB_USB_OTG_PullUpPullDownSetup Enables or disables pull-up and pull-down resistors. PLIB_USB_OTG_SessionValid Returns the status of the Session Valid Indicator bit. PLIB_USB_OTG_VBusChargeDisable Disables VBUS line charge. PLIB_USB_OTG_VBusChargeEnable Enables the VBUS line to be charged through a pull-up resistor. PLIB_USB_OTG_VBusChargeTo3V Sets the VBUS line to charge to 3.3V. PLIB_USB_OTG_VBusChargeTo5V Sets the VBUS line to charge to 5V. PLIB_USB_OTG_VBusDischargeDisable Disables VBUS line discharge. PLIB_USB_OTG_VBusDischargeEnable Enables VBUS line to be discharged through a resistor. PLIB_USB_OTG_VBusPowerOff Turns off power on the VBUS Line. PLIB_USB_OTG_VBusPowerOn Turns on power for the VBUS line. PLIB_USB_OTG_VBusValid Returns the status of the A-VBUS valid indicator. OTG Interrupts Functions Name Description PLIB_USB_OTG_InterruptDisable Disables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptEnable Enables a USB On-The-Go (OTG) Interrupt for the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3186 PLIB_USB_OTG_InterruptFlagClear Clears a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagGet Tests a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagSet Sets a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptIsEnabled Returns whether or not interrupts are enabled. Other Functions Name Description PLIB_USB_ModuleIsBusy Indicates if the USB module is not ready to be enabled. PLIB_USB_PingPongFreeze Resets all Ping-Pong buffer pointers to even buffers. PLIB_USB_PingPongReset Resets the USB peripheral internal Ping-Pong indicator to point to even buffers. PLIB_USB_PingPongUnfreeze Enables Ping-Pong buffering. PLIB_USB_TokenSend Sends token to the specified address. Test Support Functions Name Description PLIB_USB_EyePatternDisable Disables the USB eye pattern test. PLIB_USB_EyePatternEnable Enables USB eye pattern test. USB Activity Functions Name Description PLIB_USB_ActivityPending Returns whether or not USB activity is pending. PLIB_USB_FrameNumberGet Returns the USB frame number. PLIB_USB_JStateIsActive Live differential receiver J State flag. PLIB_USB_PacketTransferDisable Disables the Serial Interface Engine (SIE). PLIB_USB_PacketTransferEnable Re-enables the Serial Interface Engine (SIE), allowing token and packet processing. PLIB_USB_PacketTransferIsDisabled Indicates that a setup token has been received from the Host and that token/packet processing is disabled. PLIB_USB_SE0InProgress Returns whether a single-ended zero event is in progress. USB Bus Signaling Functions Name Description PLIB_USB_ResetSignalDisable Disables reset signalling on the USB bus. PLIB_USB_ResetSignalEnable Enables reset signalling on the USB bus. PLIB_USB_ResumeSignalingDisable Disables resume signaling. PLIB_USB_ResumeSignalingEnable Enables resume signaling. USB Setup Functions Name Description PLIB_USB_AllInterruptEnable Configures the USB peripheral general interrupts, error interrupts and OTG interrupts. PLIB_USB_AutoSuspendDisable Disables USB OTG Auto-suspend mode. PLIB_USB_AutoSuspendEnable Enables USB Auto-suspend mode. PLIB_USB_DeviceAddressGet Returns the address of the USB module in Device mode. PLIB_USB_DeviceAddressSet Sets the USB Device's address. PLIB_USB_Disable Disables (powers down) the USB module. PLIB_USB_Enable Enables (powers up) the USB module. PLIB_USB_FullSpeedDisable Forces the USB module to operate at low speed. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3187 PLIB_USB_FullSpeedEnable Enables the USB to operate at full speed. PLIB_USB_OnChipPullUpDisable Disables on-chip pull-ups. PLIB_USB_OnChipPullUpEnable Enables on-chip pull-ups. PLIB_USB_OperatingModeSelect Selects the operating mode of the USB module. PLIB_USB_PingPongModeGet Returns the Ping-Pong Configuration setting. PLIB_USB_PingPongModeSelect Selects the Ping-Pong Configuration setting. PLIB_USB_SleepGuardDisable This function disables Sleep Guard. Entry into Sleep mode is immediate. PLIB_USB_SleepGuardEnable Entry into Sleep mode is blocked if bus activity is detected or if an interrupt is pending. PLIB_USB_StopInIdleDisable Allows the USB module to continue operation when the device enters Idle mode. PLIB_USB_StopInIdleEnable Enables USB module operation to stop when the device enters Idle mode. PLIB_USB_SuspendDisable Disables USB OTG Suspend mode. PLIB_USB_SuspendEnable Enables USB Suspend mode. PLIB_USB_UOEMonitorDisable Disables the OE signal output. PLIB_USB_UOEMonitorEnable Enables the OE signal output. VBus Support Functions Name Description PLIB_USB_ExternalComparatorMode2Pin Sets the 2-pin input configuration for VBUS comparators. PLIB_USB_ExternalComparatorMode3Pin Sets the 3-pin input configuration for VBUS Comparators. PLIB_USB_PWMCounterDisable Disables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMCounterEnable Enables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMDisable Disables the PWM Generator. PLIB_USB_PWMEnable Enables the PWM Generator. PLIB_USB_PWMPolaritiyActiveLow Sets the PWM output to active-high and resets low. PLIB_USB_PWMPolarityActiveHigh Sets the PWM output to active-low and resets high. PLIB_USB_VBoostDisable Disables the On-Chip 5V Boost Regulator Circuit Disabled bit. PLIB_USB_VBoostEnable Enables the On-Chip 5V Boost Regulator Circuit Enabled bit. PLIB_USB_VBUSComparatorDisable Disables the on-chip VBUS Comparator. PLIB_USB_VBUSComparatorEnable Enables the on-chip VBUS Comparator. PLIB_USB_VBUSPullUpDisable Disables the pull-up on the VBUS pin. PLIB_USB_VBUSPullUpEnable Enables the pull-up on the VBUS pin. Description This library provides the low level abstraction of the USB Peripheral on Microchip family of microcontrollers with a convenient C language interface. 5.6.26.6.1 USB Setup Functions 5.6.26.6.1.1 PLIB_USB_AllInterruptEnable Function C void PLIB_USB_AllInterruptEnable( USB_MODULE_ID index, USB_INTERRUPTS usbInterruptsFlag, USB_ERROR_INTERRUPTS usbErrorInterruptsFlag, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3188 USB_OTG_INTERRUPTS otgInterruptFlag ); Description This function configures the USB peripheral general interrupts, error interrupts and OTG interrupts. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest usbInterruptsFlag General interrupts to be configured usbErrorInterruptsFlag USB Error interrupts to be configured otgInterruptFlag OTG interrupts to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsALL_Interrupt in your application to determine whether this feature is available. Example // This code snippet disables all OTG interrupts, disables // the SOF interrupt and enables all error interrupts. USB_OTG_INTERRUPTS otgInterruptEnables = ~USB_OTG_INT_ALL ; USB_INTERRUPTS generalInterruptEnables = USB_INT_ALL & ~USB_INT_SOF ; USB_ERROR_INTERRUPTS errorInterruptEnables = USB_ERR_INT_ALL ; PLIB_USB_AllInterruptEnable(USB_MODULE_ID index, USB_INTERRUPTS usbInterruptsFlag, USB_ERROR_INTERRUPTS usbErrorInterruptsFlag, USB_OTG_INTERRUPTS otgInterruptFlag); 5.6.26.6.1.2 PLIB_USB_AutoSuspendDisable Function C void PLIB_USB_AutoSuspendDisable( USB_MODULE_ID index ); Description This function disables USB OTG Auto-suspend mode. The USB OTG module will operate normally and does not automatically suspend upon entry to Sleep mode. Software must use PLIB_USB_SuspendEnable to suspend the module, including the USB 48 MHz clock Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3189 Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsAutomaticSuspend in your application to determine whether this feature is available. Example PLIB_USB_AutoSuspendDisable(MY_USB_INSTANCE); 5.6.26.6.1.3 PLIB_USB_AutoSuspendEnable Function C void PLIB_USB_AutoSuspendEnable( USB_MODULE_ID index ); Description This function enables USB Auto-suspend mode. The USB module automatically suspends upon entry to Sleep mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsAutomaticSuspend in your application to determine whether this feature is available. Example PLIB_USB_AutoSuspendEnable(MY_USB_INSTANCE); 5.6.26.6.1.4 PLIB_USB_DeviceAddressGet Function C uint8_t PLIB_USB_DeviceAddressGet( USB_MODULE_ID index ); Description This function returns the address of the USB module in Device mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3190 Returns Device Address Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsDeviceAddressin your application to determine whether this feature is available. Example myUSBAddress = PLIB_USB_DeviceAddressGet(MY_USB_INSTANCE); 5.6.26.6.1.5 PLIB_USB_DeviceAddressSet Function C void PLIB_USB_DeviceAddressSet( USB_MODULE_ID index, uint8_t address ); Description This function sets the USB Device's address as part of enumeration. Preconditions USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest address USB address Returns None. Remarks Not applicable for PIC18 devices, since USB Host functionality is not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsDeviceAddressin your application to determine whether this feature is available. Example uint8_t myUSBAddress = ....; PLIB_USB_DeviceAddressSet(MY_USB_INSTANCE, myUSBAddress); 5.6.26.6.1.6 PLIB_USB_Disable Function C void PLIB_USB_Disable( USB_MODULE_ID index ); Description This function disables (powers down) the USB module. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3191 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks For PIC24/dsPIC33 and PIC32 devices, the USB module must be in Device mode before the USB module is powered down. For PIC32 devices, all reads or writes to module registers after powering down the module will be invalid until PLIB_USB_ModuleIsBusy (MY_USB_INSTANCE) == false. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModulePower in your application to determine whether this feature is available. Example #if ( defined(__PIC24E__) || defined(__dsPIC33E__) || defined(__PIC32MX__) ) // Disable Host, Device, or OTG before powering down PLIB_USB_OperatingModeSelect( MY_USB_INSTANCE, USB_OPMODE_NONE ); #endif // Turn off USB PLIB_USB_Disable(MY_USB_INSTANCE); #ifdef (__PIC32MX__) // For PIC32, wait until module is no longer busy before trying to // access any USB module registers. while ( PLIB_USB_ModuleIsBusy (MY_USB_INSTANCE) ) { //wait } #endif // Can now read or modify USB module status 5.6.26.6.1.7 PLIB_USB_Enable Function C void PLIB_USB_Enable( USB_MODULE_ID index ); Description This function enables (powers up) the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not valid on PIC18 devices until a valid clock source is provided to the USB module. See also PLIB_USB_ModuleIsBusy. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3192 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModulePoweryour application to determine whether this feature is available. Example // Complete Needed setup for the module PLIB_USB_Enable(MY_USB_INSTANCE); 5.6.26.6.1.8 PLIB_USB_FullSpeedDisable Function C void PLIB_USB_FullSpeedDisable( USB_MODULE_ID index ); Description This function forces the USB module to operate at low speed. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks For PIC18 devices, use only before the USB module is enabled to select low speed. In addition, an input clock of 6 MHz instead of 48 MHz is required. For all others devices: Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSpeedControl in your application to determine whether this feature is available. Example PLIB_USB_FullSpeedDisable(MY_USB_INSTANCE); 5.6.26.6.1.9 PLIB_USB_FullSpeedEnable Function C void PLIB_USB_FullSpeedEnable( USB_MODULE_ID index ); Description This function enables the USB to operate at full speed. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3193 Returns None. Remarks For PIC18 devices, use only before the USB module is enabled to select low speed. In addition, an input clock of 6 MHz instead of 48 MHz is required. For all others devices: Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSpeedControl in your application to determine whether this feature is available. Example PLIB_USB_FullSpeedEnable(MY_USB_INSTANCE); 5.6.26.6.1.10 PLIB_USB_OnChipPullUpDisable Function C void PLIB_USB_OnChipPullUpDisable( USB_MODULE_ID index ); Description This function disables on-chip pull-ups. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks PIC18 devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipPullup in your application to determine whether this feature is available. Example PLIB_USB_OnChipPullUpDisable(MY_USB_INSTANCE); 5.6.26.6.1.11 PLIB_USB_OnChipPullUpEnable Function C void PLIB_USB_OnChipPullUpEnable( USB_MODULE_ID index ); Description This function enables on-chip pull-ups. Pull-up on D+ in Full-Speed mode. Pull-up on D- in Low-Speed mode. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3194 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks PIC18 devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipPullup in your application to determine whether this feature is available. Example PLIB_USB_OnChipPullUpEnable(MY_USB_INSTANCE); 5.6.26.6.1.12 PLIB_USB_OperatingModeSelect Function C void PLIB_USB_OperatingModeSelect( USB_MODULE_ID index, USB_OPMODES opMode ); Description This function selects the operating mode of the USB module, either Host, Device, or OTG. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest opMode Selected operating mode: USB_OPMODE_DEVICE, USB_OPMODE_HOST, or USB_OPMODE_OTG Returns None. Remarks Not needed on PIC18 devices, since only UPB_OPMODE_DEVICE is supported and there are no other operating modes. Use USB_OPMODE_NONE to disable all possible functions. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOpModeSelect in your application to determine whether this feature is available. Example PLIB_USB_OperatingModeSelect( MY_USB_INSTANCE, USB_OPMODE_DEVICE ); 5.6.26.6.1.13 PLIB_USB_PingPongModeGet Function C USB_PING_PONG_MODE PLIB_USB_PingPongModeGet( USB_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3195 Description This function returns the Ping-Pong Configuration setting. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns Ping-Pong Mode - One of USB_PING_PONG__ALL_BUT_EP0, USB_PING_PONG__FULL_PING_PONG, USB_PING_PONG__EP0_OUT_ONLY, USB_PING_PONG__NO_PING_PONG Remarks For PIC18F and PIC24F devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPingPongMode in your application to determine whether this feature is available. Example ppConfig = PLIB_USB_PingPongModeGet(MY_USB_INSTANCE); 5.6.26.6.1.14 PLIB_USB_PingPongModeSelect Function C void PLIB_USB_PingPongModeSelect( USB_MODULE_ID index, USB_PING_PONG_MODE ppConfig ); Description This function selects the Ping-Pong Configuration setting. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest ppConfig Ping-Pong configuration selection. One of USB_PING_PONG__ALL_BUT_EP0, USB_PING_PONG__FULL_PING_PONG, USB_PING_PONG__EP0_OUT_ONLY, USB_PING_PONG__NO_PING_PONG Returns None. Remarks For PIC18F and PIC24F devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPingPongMode in your application to determine whether this feature is available. Example PLIB_USB_PingPongModeSelect(MY_USB_INSTANCE,USB_PING_PONG__ALL_BUT_EP0); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3196 5.6.26.6.1.15 PLIB_USB_SleepGuardDisable Function C void PLIB_USB_SleepGuardDisable( USB_MODULE_ID index ); Description This function disables Sleep Guard. Entry into Sleep mode is immediate. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18, dsPIC or PIC24 devices. Not available on all PIC32 devices. Refer to the specific device data sheet for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSleepEntryGuard in your application to determine whether this feature is available. Example PLIB_USB_SleepGuardDisable(MY_USB_INSTANCE); 5.6.26.6.1.16 PLIB_USB_SleepGuardEnable Function C void PLIB_USB_SleepGuardEnable( USB_MODULE_ID index ); Description This function block entry into Sleep mode if bus activity is detected or if an interrupt is pending. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18, dsPIC, or PIC24 devices. Not available on all PIC32 devices. Refer to the specific device data sheet for details. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSleepEntryGuard in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3197 Example PLIB_USB_SleepGuardEnable(MY_USB_INSTANCE); 5.6.26.6.1.17 PLIB_USB_StopInIdleDisable Function C void PLIB_USB_StopInIdleDisable( USB_MODULE_ID index ); Description This function allows the USB module to continue operation when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStopInIdle in your application to determine whether this feature is available. Example PLIB_USB_StopInIdleDisable(MY_USB_INSTANCE); 5.6.26.6.1.18 PLIB_USB_StopInIdleEnable Function C void PLIB_USB_StopInIdleEnable( USB_MODULE_ID index ); Description This function enables USB module operation to stop when the device enters Idle mode. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStopInIdle in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3198 Example PLIB_USB_StopInIdleEnable(MY_USB_INSTANCE); 5.6.26.6.1.19 PLIB_USB_SuspendDisable Function C void PLIB_USB_SuspendDisable( USB_MODULE_ID index ); Description This function disables USB OTG Suspend mode. The USB OTG module will operate normally. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSuspend in your application to determine whether this feature is available. Example PLIB_USB_SuspendDisable(MY_USB_INSTANCE); 5.6.26.6.1.20 PLIB_USB_SuspendEnable Function C void PLIB_USB_SuspendEnable( USB_MODULE_ID index ); Description This function enables USB Suspend mode. The 48 MHz USB clock will be gated off. The transceiver is placed in a low-power state. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3199 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSuspend in your application to determine whether this feature is available. Example PLIB_USB_SuspendEnable(MY_USB_INSTANCE); 5.6.26.6.1.21 PLIB_USB_UOEMonitorDisable Function C void PLIB_USB_UOEMonitorDisable( USB_MODULE_ID index ); Description This function disables the OE signal output. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsUOEMonitor in your application to determine whether this feature is available. Example //Disable the OE output. PLIB_USB_UOEMonitorDisable(MY_USB_INSTANCE); 5.6.26.6.1.22 PLIB_USB_UOEMonitorEnable Function C void PLIB_USB_UOEMonitorEnable( USB_MODULE_ID index ); Description This function enables the OE signal output. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3200 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsUOEMonitor in your application to determine whether this feature is available. Example //Enable the OE output. PLIB_USB_UOEMonitorEnable(MY_USB_INSTANCE); 5.6.26.6.2 Buffer Descriptor Table Functions 5.6.26.6.2.1 PLIB_USB_BDTBaseAddressGet Function C void* PLIB_USB_BDTBaseAddressGet( USB_MODULE_ID index ); Description This function returns the base address of the Buffer Descriptor Table. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Always set to 0x400 for PIC18 devices. Must be set for dsPIC33E/PIC24E, PIC24F, and PIC32 devices using PLIB_USB_BDTBaseAddressSet. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTBaseAddress in your application to determine whether this feature is available. Example void * pMyBDT; pMyBDT = PLIB_USB_BDTBaseAddressGet(MY_USB_INSTANCE); 5.6.26.6.2.2 PLIB_USB_BDTBaseAddressSet Function C void PLIB_USB_BDTBaseAddressSet( USB_MODULE_ID index, void* address ); Description This function sets the base address for the Buffer Descriptor Table. This function is only available on PIC24 and PIC32 devices. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3201 Parameters Parameters Description index Identifier for the device instance of interest address Physical memory address in RAM of Buffer Descriptor Table Returns None. Remarks Available on dsPIC33E/PIC24E, PIC24F, and PIC32. For PIC18 devices the address is fixed at 0x400. The address of the Buffer Descriptor Table must be 512 byte-aligned. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTBaseAddress in your application to determine whether this feature is available. Example #if defined(__PIC32MX__) // For PIC32 PLIB_USB_BDTBaseAddressSet(MY_USB_INSTANCE, (void *)((uint32_t)KVA_TO_PA(&myBDT)) ); #else // Everybody else PLIB_USB_BDTBaseAddressSet(MY_USB_INSTANCE, (void *)(&myBDT) ); #endif 5.6.26.6.2.3 PLIB_USB_BufferAddressGet Function C void* PLIB_USB_BufferAddressGet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function gets the memory address of an endpoint buffer. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint Value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns Buffer address in memory. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3202 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.4 PLIB_USB_BufferAddressSet Function C void PLIB_USB_BufferAddressSet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, void* bufferAddress ); Description This function sets the endpoint buffer address. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferAddress address in memory of endpoint transmit or receive buffer Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.5 PLIB_USB_BufferAllCancelReleaseToUSB Function C void PLIB_USB_BufferAllCancelReleaseToUSB( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, int nEndpoints ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3203 Description This function cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest pBDT Pointer to the Buffer Descriptor Table ppMode Buffer Descriptor Table Ping-Pong mode nEndpoints Number of endpoints in the Buffer-Descriptor table Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example //Cancel all buffer releases to USB. //BDT has 3 Endpoints. PLIB_USB_BufferAllCancelReleaseToUSB(MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, 3); 5.6.26.6.2.6 PLIB_USB_BufferByteCountGet Function C uint16_t PLIB_USB_BufferByteCountGet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function returns the endpoint buffer byte count, the actual number of bytes transmitted or received. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3204 Returns Endpoint buffe byte count. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.7 PLIB_USB_BufferByteCountSet Function C void PLIB_USB_BufferByteCountSet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, uint16_t bufferByteCount ); Description This function sets the number of bytes to be transmitted or the maximum number of bytes to be received. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferByteCount number of bytes to be transmitted or the maximum number of bytes to be received Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.8 PLIB_USB_BufferCancelReleaseToUSB Function C void PLIB_USB_BufferCancelReleaseToUSB( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3205 uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function cancels the release of the endpoint buffer by software, allowing software to again access the buffer. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.9 PLIB_USB_BufferClearAll Function C void PLIB_USB_BufferClearAll( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function clears (zeros out) the entries in the Buffer Descriptor Table. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3206 bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.10 PLIB_USB_BufferClearAllDTSEnable Function C void PLIB_USB_BufferClearAllDTSEnable( USB_MODULE_ID index, void * pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection ); Description This function clears the endpoint descriptor entry and enables data toggle synchronization. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest pBDT pointer to Buffer Descriptor Table pingpong Ping-Pong mode. epvalue Endpoint to be be affected bufferDirection Endpoint direction Returns None. Remarks None. Example //Clear endpoint 6 buffer descriptor transmit entry and //enable data toggle synchronization. PLIB_USB_BufferClearAllDTSEnable ( MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, 6, USB_BUFFER_TX); 5.6.26.6.2.11 PLIB_USB_BufferDataToggleGet Function C USB_BUFFER_DATA01 PLIB_USB_BufferDataToggleGet( USB_MODULE_ID index, void* pBDT, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3207 USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function returns data synchronization (DATA0 or DATA1) for the endpoint buffer. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns Data Toggle value, USB_BUFFER_DATA0 or USB_BUFFER_DATA1, for the buffer Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.12 PLIB_USB_BufferDataToggleSelect Function C void PLIB_USB_BufferDataToggleSelect( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, USB_BUFFER_DATA01 bufferData01 ); Description This function sets the endpoint buffer to DATA0 or DATA1. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3208 bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferData01 USB_BUFFER_DATA0 or USB_BUFFER_DATA1 Returns None. Remarks See PLIB_USB_BufferDataToggleGet to determine the received data toggle setting. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.13 PLIB_USB_BufferDataToggleSyncDisable Function C void PLIB_USB_BufferDataToggleSyncDisable( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function disables DATA0/DATA1 synchronization between the device and host. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.14 PLIB_USB_BufferDataToggleSyncEnable Function C void PLIB_USB_BufferDataToggleSyncEnable( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3209 USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function enables DATA0/DATA1 synchronization between the device and host. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.15 PLIB_USB_BufferEP0RxStatusInitialize Function C void PLIB_USB_BufferEP0RxStatusInitialize( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, USB_BUFFER_PING_PONG pingpong, uint16_t bufferByteCount ); Description This function initializes the Endpoint 0 RX endpoint buffer descriptors. This function will clear the Endpoint 0 RX Buffer Descriptor status field, load the endpoint size and release the buffer to the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest pBDT Pointer to Buffer Descriptor Table pingpong Ping-Pong mode 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3210 bufferByteCount size of the EP0 RX buffer in bytes Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example //Initialize EP0 RX even buffer descriptor and release back to //USB. Buffer size is 64 PLIB_USB_BufferEP0RxStatusInitialize ( MY_USB_INSTANCE, pBDT, USB_PING_PONG_NO_PING_PONG, USB_BUFFER_EVEN, 64); 5.6.26.6.2.16 PLIB_USB_BufferIndexGet Function C uint8_t PLIB_USB_BufferIndexGet( USB_MODULE_ID index, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function gets the Buffer Descriptor Table index for a buffer. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns Buffer index into the Buffer Descriptor Table. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.17 PLIB_USB_BufferPIDBitsClear Function C void PLIB_USB_BufferPIDBitsClear( USB_MODULE_ID index, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3211 void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function clears the Buffer Status bits in the Buffer Descriptor Table. Preconditions The associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks Call PLIB_USB_BufferPIDBitsClear before setting buffer control bits. This is equivalent to: PLIB_USB_BufferCancelReleaseToUSB(...) PLIB_USB_BufferDataToggleSelect( ...,USB_BUFFER_DATA0) PLIB_USB_BufferDataToggleSyncDisable(...) PLIB_USB_BufferStallDisable(...) This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.18 PLIB_USB_BufferPIDGet Function C uint8_t PLIB_USB_BufferPIDGet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function returns the token packet ID (PID) from the endpoint buffer status. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3212 pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns Endpoint buffer packet ID (PID). Remarks There is no equivalent "Set" routine, since this field is read-only in the buffer status register within the Buffer Descriptor Table. It is set when the buffer has been transmitted or received by the USB module and the usbOwnsBuffer field has been cleared by the USB module, releasing the buffer for software access. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.19 PLIB_USB_BufferReleasedToSW Function C bool PLIB_USB_BufferReleasedToSW( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function returns the boolean flag value of 'true' when the buffer has been released by the USB module. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns • true - The buffer has been released by hardware • false - The buffer is still controlled by hardware Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3213 Example 5.6.26.6.2.20 PLIB_USB_BufferReleaseToUSB Function C void PLIB_USB_BufferReleaseToUSB( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function releases the endpoint buffer by software, allowing the USB module access to buffer. Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.2.21 PLIB_USB_BufferSchedule Function C void PLIB_USB_BufferSchedule( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong, void * bufferAddress, int16_t bufferByteCount, USB_BUFFER_SCHEDULE_DATA01 bufferData01 ); Description This function sets the endpoint descriptor buffer address, sets the send/receive byte count, and then hands over the buffer to the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3214 Preconditions None. Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD bufferAddress Address of the application buffer bufferByteCount Send or expected receive byte count bufferData01 USB_BUFFER_SET_DATA0, USB_BUFFER_SET_DATA1, or USB_BUFFER_DONTCHANGE (The last choice leaves the existing DATA0/1 value of the buffer alone.) Returns None. Remarks This function does the work of three other functions: PLIB_USB_BufferAddressSet, PLIB_USB_BufferByteCountSet, PLIB_USB_BufferReleaseToUSB This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. 5.6.26.6.2.22 PLIB_USB_BufferStallDisable Function C void PLIB_USB_BufferStallDisable( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function disables STALL handshaking for the associated endpoint buffer. Preconditions The associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'). Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3215 bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks Release of a STALL handshake for the buffer is done by hardware when the host sends a SETUP token to the associated endpoint or resets the USB module This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. . Example 5.6.26.6.2.23 PLIB_USB_BufferStallEnable Function C void PLIB_USB_BufferStallEnable( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function enables STALL handshaking for the associated endpoint buffer. Preconditions The associated buffer must have been released by the USB module (i.e. PLIB_USB_BufferReleasedToSW returns 'true'). Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns None. Remarks Release of a STALL handshake for the buffer is done by hardware when the host sends a SETUP token to the associated endpoint or resets the USB module. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3216 5.6.26.6.2.24 PLIB_USB_BufferStallGet Function C bool PLIB_USB_BufferStallGet( USB_MODULE_ID index, void* pBDT, USB_PING_PONG_MODE ppMode, uint8_t epValue, USB_BUFFER_DIRECTION bufferDirection, USB_BUFFER_PING_PONG bufferPingPong ); Description This function returns the buffer stall status for an endpoint/direction/ping-pong. Preconditions the associated buffer must have been released by the USB module (i.e., PLIB_USB_BufferReleasedToSW returns 'true'). Parameters Parameters Description index Dummy argument, identifier for the device instance of interest pBDT Pointer to start of Buffer Descriptor Table ppMode Ping-Pong buffering mode epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint bufferDirection USB_BUFFER_RX or USB_BUFFER_TX bufferPingPong USB_BUFFER_EVEN or USB_BUFFER_ODD Returns • true - Buffer stall is enabled • false - Buffer stall is not enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBDTFunctions in your application to determine whether this feature is available. Example 5.6.26.6.3 Endpoints Functions 5.6.26.6.3.1 PLIB_USB_EP0HostSetup Function C void PLIB_USB_EP0HostSetup( USB_MODULE_ID index ); Description This function configures endpoint 0 for typical host operation. Control transfers are enable. Transmit and Receive is enabled. Handshaking is enabled. Low Speed connection is disabled. NAK retry is disabled. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3217 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example // Configure endpoint 0 for host operation PLBIB_USB_EP0HostSetup(USB_MODULE_ID index); 5.6.26.6.3.2 PLIB_USB_EP0LSDirectConnectDisable Function C void PLIB_USB_EP0LSDirectConnectDisable( USB_MODULE_ID index ); Description This function disables direct connection to a low-speed device for Endpoint 0. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Host mode and U1EP0 only. Not applicable for PIC18 devices, since USB Host functionality is not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0LowSpeedConnect in your application to determine whether this feature is available. Example PLIB_USB_EP0LSDirectConnectDisable(MY_USB_INSTANCE); 5.6.26.6.3.3 PLIB_USB_EP0LSDirectConnectEnable Function C void PLIB_USB_EP0LSDirectConnectEnable( USB_MODULE_ID index ); Description This function enables direct connection to a low-speed device for Endpoint 0. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3218 Preconditions USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Host Mode and U1EP0 only. Not applicable for PIC18 devices, since USB Host functionality is not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0LowSpeedConnect in your application to determine whether this feature is available. Example PLIB_USB_EP0LSDirectConnectEnable(MY_USB_INSTANCE); 5.6.26.6.3.4 PLIB_USB_EP0NakRetryDisable Function C void PLIB_USB_EP0NakRetryDisable( USB_MODULE_ID index ); Description This function disables retrying of NAKed transactions. Preconditions The USB module must be in Host or OTG modes. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Host/OTG only. Not applicable for PIC18 devices, since USB Host and OTG functionality is not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0NAKRetry in your application to determine whether this feature is available. Example PLIB_USB_EP0NakRetryDisable(MY_USB_INSTANCE); 5.6.26.6.3.5 PLIB_USB_EP0NakRetryEnable Function C void PLIB_USB_EP0NakRetryEnable( USB_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3219 Description This function enables retrying NAK'd transactions for Endpoint 0. Preconditions The USB module must be in Host or OTG modes. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Host/OTG only. Not applicable for PIC18 devices, since USB Host or OTG functionality is not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEP0NAKRetry in your application to determine whether this feature is available. Example PLIB_USB_EP0NakRetryEnable(MY_USB_INSTANCE); 5.6.26.6.3.6 PLIB_USB_EPnAttributesClear Function C void PLIB_USB_EPnAttributesClear( USB_MODULE_ID index, uint8_t epValue ); Description Clears the set attributes of the specified endpoint. The endpoint transmit receive, handshake and setup packet handling capability is disabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks None. Example // This clears up the endpoint 0 atrributes and thus disables // the endpoints PLIB_USB_EPnAttributesClear(MY_USB_INSTANCE, 0); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3220 5.6.26.6.3.7 PLIB_USB_EPnAttributesSet Function C void PLIB_USB_EPnAttributesSet( USB_MODULE_ID index, uint8_t epValue, int direction, bool isControl, bool handshake ); Description Configures attributes of the endpoint such as direction, handshake capability and direction. If the isControl flag is true, then the direction and handshake parameters are ignored and the endpoint is configured for control transfers. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint direction Endpoint direction, if 1 then RX and if 0 then TX. isControl If true endpoint is configured for control transfers. handshake If true, then handshake is enabled on the endpoint else it is disabled. Returns None. Remarks None. Example // This enables endpoint 0 for control transfers. PLIB_USB_EPnAttributesSet(MY_USB_INSTANCE, 0, 0, true, true); // This enables endpoint 2 for non control transfer, direction // is RX and handshake enable. PLIB_USB_EPnAttributesSet(MY_USB_INSTANCE, 2, 1, false, true); 5.6.26.6.3.8 PLIB_USB_EPnControlTransferDisable Function C void PLIB_USB_EPnControlTransferDisable( USB_MODULE_ID index, uint8_t epValue ); Description This function disables endpoint control transfers when endpoint transmit and endpoint receive are both enabled. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3221 Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnControlTransferDisable(MY_USB_INSTANCE, someEP); 5.6.26.6.3.9 PLIB_USB_EPnControlTransferEnable Function C void PLIB_USB_EPnControlTransferEnable( USB_MODULE_ID index, uint8_t epValue ); Description This function enables endpoint control transfers when endpoint transmit and endpoint receive are both enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnControlTransferEnable(MY_USB_INSTANCE, someEP); 5.6.26.6.3.10 PLIB_USB_EPnDirectionDisable Function C void PLIB_USB_EPnDirectionDisable( USB_MODULE_ID index, uint8_t epValue, int direction ); Description Disables the specified endpoint direction. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3222 Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint direction If 1, then TX direction is disabled. If 0 RX direction is disabled. Returns None. Remarks None. Example // This function disbles the TX direction of endpoint 1 PLIB_USB_EPnDirectionDisable(MY_USB_INSTANCE, 1, 1); 5.6.26.6.3.11 PLIB_USB_EPnHandshakeDisable Function C void PLIB_USB_EPnHandshakeDisable( USB_MODULE_ID index, uint8_t epValue ); Description This function disables endpoint handshaking. Typically used for Isochronous endpoints. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnHandshakeDisable(MY_USB_INSTANCE, someEP); 5.6.26.6.3.12 PLIB_USB_EPnHandshakeEnable Function C void PLIB_USB_EPnHandshakeEnable( USB_MODULE_ID index, uint8_t epValue 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3223 ); Description This function enables endpoint handshaking. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnHandshakeEnable(MY_USB_INSTANCE, someEP); 5.6.26.6.3.13 PLIB_USB_EPnIsStalled Function C bool PLIB_USB_EPnIsStalled( USB_MODULE_ID index, uint8_t epValue ); Description This function tests whether the endpoint epValue is stalled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns • true - The endpoint is stalled • false - The endpoint is not stalled Remarks Not valid before an endpoint is enabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example if( PLIB_USB_EPnIsStalled(MY_USB_INSTANCE, someEP) ) { // Handle the stall 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3224 } 5.6.26.6.3.14 PLIB_USB_EPnRxDisable Function C void PLIB_USB_EPnRxDisable( USB_MODULE_ID index, uint8_t endpoint ); Description This function disables an endpoint's ability to process IN tokens. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example //De-provision endpoint 3 to process IN Token PLIB_USB_EPnRxDisable(MY_USB_INSTANCE, 3); 5.6.26.6.3.15 PLIB_USB_EPnRxEnable Function C void PLIB_USB_EPnRxEnable( USB_MODULE_ID index, uint8_t endpoint ); Description This function enables an endpoint to process IN tokens. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3225 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example //Provision endpoint 3 to process IN Token PLIB_USB_EPnRxEnable(MY_USB_INSTANCE, 3); 5.6.26.6.3.16 PLIB_USB_EPnRxSelect Function C void PLIB_USB_EPnRxSelect( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ); Description This function selects receive capabilities of an endpoint. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_RX, USB_EP_NOTXRX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnRxSelect(MY_USB_INSTANCE, someEP, USB_EP_RX); 5.6.26.6.3.17 PLIB_USB_EPnStallClear Function C void PLIB_USB_EPnStallClear( USB_MODULE_ID index, uint8_t epValue ); Description This function clears an endpoint's stalled flag. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3226 Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint Returns None. Remarks Not valid before an endpoint is enabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example if( PLIB_USB_EPnIsStalled(MY_USB_INSTANCE, someEP) ) { // Handle the stall PLIB_USB_EPnStallClear(MY_USB_INSTANCE, someEP); } 5.6.26.6.3.18 PLIB_USB_EPnTxDisable Function C void PLIB_USB_EPnTxDisable( USB_MODULE_ID index, uint8_t endpoint ); Description This function disables an endpoint's ability to process OUT tokens. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example //De-provision endpoint 3 to process OUT Token PLIB_USB_EPnTxDisable(MY_USB_INSTANCE, 3); 5.6.26.6.3.19 PLIB_USB_EPnTxEnable Function C void PLIB_USB_EPnTxEnable( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3227 USB_MODULE_ID index, uint8_t endpoint ); Description This function enables an endpoint to process OUT tokens. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest endpoint Endpoint to be affected Returns None. Remarks None. Example //Provision endpoint 3 to process OUT Token PLIB_USB_EPnTxEnable(MY_USB_INSTANCE, 3); 5.6.26.6.3.20 PLIB_USB_EPnTxRxSelect Function C void PLIB_USB_EPnTxRxSelect( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ); Description This function selects transmit and/or receive capabilities of an endpoint. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_TX, USB_EP_RX, USB_EP_TX_RX, USB_EP_NOTXRX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3228 Example PLIB_USB_EPnTxRxSelect(MY_USB_INSTANCE, someEP, USB_EP_TXRX); 5.6.26.6.3.21 PLIB_USB_EPnTxSelect Function C void PLIB_USB_EPnTxSelect( USB_MODULE_ID index, uint8_t epValue, USB_EP_TXRX epTxRx ); Description This function selects transmit capabilities of an endpoint. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint epTxRx Transmit/Receive setting for endpoint: USB_EP_TX, USB_EP_NOTXRX Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEPnRxEnable in your application to determine whether this feature is available. Example PLIB_USB_EPnTxSelect(MY_USB_INSTANCE, someEP, USB_EP_TX); 5.6.26.6.4 Interrupts Functions 5.6.26.6.4.1 PLIB_USB_InterruptDisable Function C void PLIB_USB_InterruptDisable( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function disables a general interrupt source for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3229 interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_InterruptDisable( MY_USB_INSTANCE, USB_INT_ERROR ); 5.6.26.6.4.2 PLIB_USB_InterruptEnable Function C void PLIB_USB_InterruptEnable( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function enables general interrupt sources of the USB module to trigger a USB interrupt. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_InterruptEnable( MY_USB_INSTANCE, USB_INT_ERROR ); 5.6.26.6.4.3 PLIB_USB_InterruptEnableGet Function C USB_INTERRUPTS PLIB_USB_InterruptEnableGet( USB_MODULE_ID index ); Description Returns the enable/disable status of general USB module interrupts Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3230 Parameters Parameters Description index Identifier for the device instance of interest Returns A bit map containing status of enabled interrupts. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example USB_INTERRUPTS enabledInterrupts; enabledInterrupts = PLIB_USB_InterruptEnableGet( MY_USB_INSTANCE); if(enabledInterrupts|USB_INT_ATTACH) { // This means Attach interrupt is enabled. } 5.6.26.6.4.4 PLIB_USB_InterruptFlagAllGet Function C USB_INTERRUPTS PLIB_USB_InterruptFlagAllGet( USB_MODULE_ID index ); Description This functoin returns a logically ORed bit map of active general USB interrupt flags. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns Returns a logically ORed bit map of active general USB interrupt flags. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Example USB_INTERRUPTS interruptEnables; interruptEnables = PLIB_USB_InterruptFlagAllGet(MY_USB_INSTANCE); if(interruptEnables | USB_INT_DEVICE_RESET) { // Device received reset signalling } 5.6.26.6.4.5 PLIB_USB_InterruptFlagClear Function C void PLIB_USB_InterruptFlagClear( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3231 USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function clears a general interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Example PLIB_USB_InterruptFlagClear( MY_USB_INSTANCE, USB_INT_ERROR ); 5.6.26.6.4.6 PLIB_USB_InterruptFlagGet Function C bool PLIB_USB_InterruptFlagGet( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function tests a general interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Example if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_ANY) ) if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_ERROR) ) { PLIB_USB_InterruptFlagClear(MY_USB_INSTANCE,USB_INT_ERROR); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3232 // Error clean up } if ( PLIB_USB_InterruptFlagGet(MY_USB_INSTANCE,USB_INT_HOST_DETACH) ) { PLIB_USB_InterruptFlagClear(MY_USB_INSTANCE,USB_INT_HOST_DETACH); // Device detached clean up } . . . } 5.6.26.6.4.7 PLIB_USB_InterruptFlagSet Function C void PLIB_USB_InterruptFlagSet( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function sets a general interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_InterruptStatus in your application to determine whether this feature is available. Example PLIB_USB_InterruptFlagSet( MY_USB_INSTANCE, USB_INT_ERROR ); 5.6.26.6.4.8 PLIB_USB_InterruptIsEnabled Function C bool PLIB_USB_InterruptIsEnabled( USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function returns true if interrupts are enabled. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3233 Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns • true - Interrupts are enabled • false - Interrupts are not enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example if ( PLIB_USB_InterruptIsEnabled( MY_USB_INSTANCE, USB_INT_ERROR ) ) { } 5.6.26.6.5 Error Interrupts Functions 5.6.26.6.5.1 PLIB_USB_ErrorInterruptDisable Function C void PLIB_USB_ErrorInterruptDisable( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ); Description This function disables an error interrupt source for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_ErrorInterruptDisable( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3234 5.6.26.6.5.2 PLIB_USB_ErrorInterruptEnable Function C void PLIB_USB_ErrorInterruptEnable( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ); Description This function enables error interrupt sources of the USB module to trigger a USB interrupt. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_ErrorInterruptEnable( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); 5.6.26.6.5.3 PLIB_USB_ErrorInterruptFlagAllGet Function C USB_ERROR_INTERRUPTS PLIB_USB_ErrorInterruptFlagAllGet( USB_MODULE_ID index ); Description This function returns a logically ORed bit map of active error interrupt flags. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns Returns a logically ORed bit map of active error interutp flags. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3235 Example USB_ERROR_INTERRUPTS errorInterruptEnables; errorInterruptEnables = PLIB_USB_ErrorInterruptFlagAllGet(MY_USB_INSTANCE); if(errorInterruptEnables | USB_ERR_INT_DEVICE_EOF_ERROR) { // End of frame error occurred. } 5.6.26.6.5.4 PLIB_USB_ErrorInterruptFlagClear Function C void PLIB_USB_ErrorInterruptFlagClear( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ); Description This function clears an error interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks None. Example PLIB_USB_ErrorInterruptFlagClear( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); 5.6.26.6.5.5 PLIB_USB_ErrorInterruptFlagGet Function C bool PLIB_USB_ErrorInterruptFlagGet( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ); Description This function tests an error interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3236 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Example if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_ANY) ) if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_PID_CHECK_FAILURE) ) { PLIB_USB_ErrorInterruptFlagClear(MY_USB_INSTANCE,USB_ERR_INT_PID_CHECK_FAILURE); // PID Error Check failure cleanup } if ( PLIB_USB_ErrorInterruptFlagGet(MY_USB_INSTANCE,USB_ERR_INT_DEVICE_EOF_ERROR) ) { PLIB_USB_ErrorInterruptFlagClear(MY_USB_INSTANCE,USB_ERR_INT_DEVICE_EOF_ERROR); // EOF error cleanup } . . . } 5.6.26.6.5.6 PLIB_USB_ErrorInterruptFlagSet Function C void PLIB_USB_ErrorInterruptFlagSet( USB_MODULE_ID index, USB_ERROR_INTERRUPTS interruptFlag ); Description This function sets an error interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Example PLIB_USB_ErrorInterruptFlagSet( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ); 5.6.26.6.5.7 PLIB_USB_ErrorInterruptIsEnabled Function C bool PLIB_USB_ErrorInterruptIsEnabled( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3237 USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function determines whether interrupts are enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns • true - Interrupts are enabled • false - Interrupts are not enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsERR_InterruptStatus in your application to determine whether this feature is available. Example if ( PLIB_USB_ErrorInterruptIsEnabled( MY_USB_INSTANCE, USB_ERR_INT_BAD_CRC16 ) ) { } 5.6.26.6.6 Last Transaction Status Functions 5.6.26.6.6.1 PLIB_USB_LastTransactionDetailsGet Function C void PLIB_USB_LastTransactionDetailsGet( USB_MODULE_ID index, USB_BUFFER_DIRECTION * direction, USB_PING_PONG_STATE * pingpong, uint8_t * endpoint ); Description This function returns the details of the last completed transaction. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest direction Return value contains direction of the last transfer pingpong Return value contains Ping-Pong indication of the the last transfer endpoint Return value contains the endpoint which processed the last transfer 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3238 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastTransactionDetails in your application to determine whether this feature is available. Example USB_BUFFER_DIRECTION direction; USB_PING_PONG_STATE pingpong; uint8_t endpoint; interruptEnables = PLIB_USB_InterruptFlagAllGet(MY_USB_INSTANCE); if(interruptEnables | USB_INT_TOKEN_DONE) { // Find out details of the token PLIB_USB_LastTransactionDetailsGet(MY_USB_INSTANCE, &direction, &pingpong, &endpoint); } 5.6.26.6.6.2 PLIB_USB_LastTransactionDirectionGet Function C USB_BUFFER_DIRECTION PLIB_USB_LastTransactionDirectionGet( USB_MODULE_ID index ); Description This function indicates the direction of the last transaction, either transmit or receive. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns USB_LastDirection: USB_RECEIVE_TRANSFER or USB_TRANSMIT_TRANSFER Remarks None. Example See PLIB_USB_LastTransactionEndPtGet. 5.6.26.6.6.3 PLIB_USB_LastTransactionEndPtGet Function C uint8_t PLIB_USB_LastTransactionEndPtGet( USB_MODULE_ID index ); Description This function returns the endpoint number of the last USB transfer, which is actually the index into the Buffer Descriptor Table of the last USB transfer. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3239 Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns endPoint - Endpoint of last completed USB transfer Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastDirection in your application to determine whether this feature is available. Example while ( !PLIB_USB_INT_FlagGet(MY_USB_INSTANCE,USB_INT_GEN,TOKEN_DONE) ) { // Do nothing, wait until completion of next transaction } // Retrieve information relating to the last completed transaction endpoint = PLIB_USB_LastTransactionEndPtGet(MY_USB_INSTANCE); direction = PLIB_USB_LastTransactionDirectionGet(MY_USB_INSTANCE); pingPongState = PLIB_USB_LastTransactionPingPongStateGet(MY_USB_INSTANCE); // Clearing the Token Processing Done flag advances the status FIFO to // oldest transaction in the FIFO. Wait for completion of next transaction // before using PLIB_USB_Last*Get functions again to read status. PLIB_USB_INT_FlagClear(MY_USB_INSTANCE,USB_INT_GEN,TOKEN_DONE); 5.6.26.6.6.4 PLIB_USB_LastTransactionPingPongStateGet Function C USB_PING_PONG_STATE PLIB_USB_LastTransactionPingPongStateGet( USB_MODULE_ID index ); Description This function indicates whether the last transaction was to an Even buffer or an Odd buffer. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns USB_PING_PONG_STATE. Remarks Not valid if PIC18 or PIC24F endpoint does not have ping-pong buffering enabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLastPingPong in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3240 Example See PLIB_USB_LastTransactionEndPtGet. 5.6.26.6.7 Host Functions 5.6.26.6.7.1 PLIB_USB_IsBusyWithToken Function C bool PLIB_USB_IsBusyWithToken( USB_MODULE_ID index ); Description This function indicates whether there is a token being executed by the USB module as Host. Software should check that the previous token is finished before issuing a new token. Preconditions USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not applicable for PIC18 devices since PIC18 devices do not support Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostBusyWithToken in your application to determine whether this feature is available. Example while( PLIB_USB_IsBusyWithToken(MY_USB_INSTANCE) ) { // do nothing } // Issue new token 5.6.26.6.7.2 PLIB_USB_SOFDisable Function C void PLIB_USB_SOFDisable( USB_MODULE_ID index ); Description This function disables the automatic generation of the SOF token. Preconditions USB module must be in Host mode. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3241 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not applicable for PIC18 devices since PIC18 devices do not support Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStartOfFrames in your application to determine whether this feature is available. Example PLIB_USB_SOFDisable(MY_USB_INSTANCE); 5.6.26.6.7.3 PLIB_USB_SOFEnable Function C void PLIB_USB_SOFEnable( USB_MODULE_ID index ); Description This function enables the automatic generation of the SOF token every 1 ms. Preconditions USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not applicable for PIC18 devices since PIC18 devices do not support Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsStartOfFrames in your application to determine whether this feature is available. Example PLIB_USB_SOFEnable(MY_USB_INSTANCE); 5.6.26.6.7.4 PLIB_USB_SOFThresholdGet Function C uint8_t PLIB_USB_SOFThresholdGet( USB_MODULE_ID index ); Description This functin returns the Start-of-Frame (SOF) Count bits. (Value represents 10 + (packet size of n bytes);). 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3242 Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns SOF threshold value. Remarks Host mode only. SOF Threshold Value = packet byte count + 10 = 0b0100_1010 = 0x4A = 74 for 64-byte packet = 0b0010_1010 = 0x2A = 42 for 32-byte packet = 0b0001_1010 = 0x1A = 26 for 16-byte packet = 0x0001_0010 = 0x12 = 18 for 8-byte packet This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSOFThreshold in your application to determine whether this feature is available. Example thresholdSOF = PLIB_USB_SOFThresholdGet(MY_USB_INSTANCE); 5.6.26.6.7.5 PLIB_USB_SOFThresholdSet Function C void PLIB_USB_SOFThresholdSet( USB_MODULE_ID index, uint8_t threshold ); Description This function sets the Start-of-Frame (SOF) threshold value. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest threshold SOF threshold Returns None. Remarks Host mode only. SOF Threshold Value = packet byte count + 10 = 0b0100_1010 = 0x4A = 74 for 64-byte packet = 0b0010_1010 = 0x2A = 42 for 32-byte packet = 0b0001_1010 = 0x1A = 26 for 16-byte packet = 0x0001_0010 = 0x12 = 18 for 8-byte packet 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3243 This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsSOFThreshold in your application to determine whether this feature is available. Example // Set SOF threshold for 64-byte packets PLIB_USB_SOFThresholdSet(MY_USB_INSTANCE,64+10); 5.6.26.6.7.6 PLIB_USB_TokenEPGet Function C uint8_t PLIB_USB_TokenEPGet( USB_MODULE_ID index ); Description This function returns the address of the specified Endpoint. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns Endpoint value - 0 <= epValue <= Module Maximum Endpoint. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenEP in your application to determine whether this feature is available. Example someEP = PLIB_USB_TokenEPGet(MY_USB_INSTANCE); 5.6.26.6.7.7 PLIB_USB_TokenEPSet Function C void PLIB_USB_TokenEPSet( USB_MODULE_ID index, uint8_t epValue ); Description This function sets the Endpoint address for a host transaction. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest epValue Endpoint value, 0 <= epValue <= Module Maximum Endpoint 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3244 Returns None. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenEP in your application to determine whether this feature is available. Example uint8_t someEP = 0x03; PLIB_USB_TokenEPSet(MY_USB_INSTANCE, someEP); 5.6.26.6.7.8 PLIB_USB_TokenPIDGet Function C USB_PID PLIB_USB_TokenPIDGet( USB_MODULE_ID index ); Description This function returns the token transaction type. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns Packet ID of token, USB_PID_SETUP, USB_PID_IN, or USB_PID_OUT Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenPID in your application to determine whether this feature is available. Example somePID = PLIB_USB_TokenPIDGet(MY_USB_INSTANCE); 5.6.26.6.7.9 PLIB_USB_TokenPIDSet Function C void PLIB_USB_TokenPIDSet( USB_MODULE_ID index, USB_PID pidValue ); Description This function sets the token transaction type to pidValue. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3245 pidValue USB_PID_SETUP, USB_PID_IN, or USB_PID_OUT Returns None. Remarks Host mode only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsTokenPID in your application to determine whether this feature is available. Example somePID = USB_PID_SETUP; PLIB_USB_TokenPIDSet (MY_USB_INSTANCE, somePID ); 5.6.26.6.7.10 PLIB_USB_TokenSpeedSelect Function C void PLIB_USB_TokenSpeedSelect( USB_MODULE_ID index, USB_TOKEN_SPEED tokenSpeed ); Description This function selects low speed or full speed for subsequent token executions. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest tokenSpeed Speed for next token execution: USB_LOWSPEED_TOKENS or USB_FULLSPEED_TOKENS Returns None. Remarks Not applicable for PIC18 devices since PIC18 devices do not support Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsNextTokenSpeed in your application to determine whether this feature is available. Example PLIB_USB_TokenSpeedSet(MY_USB_INSTANCE,USB_LOWSPEED_TOKENS); 5.6.26.6.8 USB Bus Signaling Functions 5.6.26.6.8.1 PLIB_USB_ResetSignalDisable Function C void PLIB_USB_ResetSignalDisable( USB_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3246 Description This function disables reset signalling on the USB bus. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not applicable for PIC18, since USB Host functionality is Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostGeneratesReset in your application to determine whether this feature is available. Example See PLIB_USB_ResetSignalEnable. 5.6.26.6.8.2 PLIB_USB_ResetSignalEnable Function C void PLIB_USB_ResetSignalEnable( USB_MODULE_ID index ); Description This function enables reset signalling on the USB bus. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not applicable for PIC18, since USB Host functionality is Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsHostGeneratesReset in your application to determine whether this feature is available. Example // Snippet to perform a software reset: PLIB_USB_ResetSignalEnable(MY_USB_INSTANCE); // ... delay 50ms PLIB_USB_ResetSignalDisable(MY_USB_INSTANCE); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3247 5.6.26.6.8.3 PLIB_USB_ResumeSignalingDisable Function C void PLIB_USB_ResumeSignalingDisable( USB_MODULE_ID index ); Description This function disables resume signaling. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsResumeSignaling in your application to determine whether this feature is available. Example See PLIB_USB_ResumeSignalingEnable. 5.6.26.6.8.4 PLIB_USB_ResumeSignalingEnable Function C void PLIB_USB_ResumeSignalingEnable( USB_MODULE_ID index ); Description This function enables resume signalling. Resume allows the peripheral to perform a remote wake-up by executing resume signaling. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Software must enable resume signaling for 10 ms if the device is in Device mode, or for 25 ms if the device is in Host mode, and then disable resume signaling to enable remote wake-up. In Host mode, the USB module will append a low-speed EOP to the end resume signaling when it is disabled. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsResumeSignaling in your application to determine whether this 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3248 feature is available. Example // Perform resume signaling: PLIB_USB_ResumeSignalingEnable(MY_USB_INSTANCE); // Delay 10ms PLIB_USB_ResumeSignalingDisable(MY_USB_INSTANCE); 5.6.26.6.9 On-The-Go (OTG) Functions 5.6.26.6.9.1 PLIB_USB_OTG_BSessionHasEnded Function C bool PLIB_USB_OTG_BSessionHasEnded( USB_MODULE_ID index ); Description This function returns the status of the B-Session End Indicator bit. Preconditions The USB module must be in OTG mode. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - The VBUS Voltage is below VB_SESS_END on the B-device • false - The VBUS voltage is above VB_SESS_END on the B-device Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_BSessionEnd in your application to determine whether this feature is available. Example if ( !PLIB_USB_OTG_BSessionHasEnded(MY_USB_INSTANCE) ) { // B session valid } else { // B session not valid } 5.6.26.6.9.2 PLIB_USB_OTG_IDPinStateIsTypeA Function C bool PLIB_USB_OTG_IDPinStateIsTypeA( USB_MODULE_ID index ); Description This function returns ID Pin state. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3249 Preconditions The USB module must be in OTG mode. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - Type A Cable attached, • false - No cable is attached or a Type B cable is attached Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_IDPinState in your application to determine whether this feature is available. Example if ( PLIB_USB_OTG_IDPinStateIsTypeA(MY_USB_INSTANCE) ) { // Type A cable attached } else { // No cable or Type B cable attached }; 5.6.26.6.9.3 PLIB_USB_OTG_LineStateIsStable Function C bool PLIB_USB_OTG_LineStateIsStable( USB_MODULE_ID index ); Description This function returns the status of the Line Stable Indicator bit. Preconditions The USB module must be in OTG mode. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - The USB line state has been stable for the previous 1 ms • false - The USB line state has not been stable for the previous 1 ms Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_LineState in your application to determine whether this feature is available. Example if( PLIB_USB_OTG_LineStateIsStable(MY_USB_INSTANCE) ) { // Line has been stable 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3250 // ... rest of code ... } 5.6.26.6.9.4 PLIB_USB_OTG_PullUpPullDownSetup Function C void PLIB_USB_OTG_PullUpPullDownSetup( USB_MODULE_ID index, USB_OTG_PULL_UP_PULL_DOWN resistor, bool enableResistor ); Description This function enables or disables pull-up and pull-down resistors. Preconditions USB On-The-Go (OTG) must be enabled. Parameters Parameters Description index Identifier for the device instance of interest resistor USB_OTG_DPLUS_PULLUP, USB_OTG_DMINUS_PULLUP, USB_OTG_DPLUS_PULLDN, or USB_OTG_DMINUS_PULLDN enableResistor true to enable resistor, false to disable it Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_PullUpPullDown in your application to determine whether this feature is available. Example // Enable pull-up resistor for D+ PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLUP,true); 5.6.26.6.9.5 PLIB_USB_OTG_SessionValid Function C bool PLIB_USB_OTG_SessionValid( USB_MODULE_ID index ); Description This function returns the status of the Session Valid Indicator bit. Preconditions The USB module must be in OTG mode. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - The VBUS voltage is above Session Valid on the A or B device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3251 • false - The VBUS voltage is below Session Valid on the A or B device Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_SessionValid in your application to determine whether this feature is available. Example if ( PLIB_USB_OTG_SessionValid(MY_USB_INSTANCE) ) { // Session valid } else { // Session not valid } 5.6.26.6.9.6 PLIB_USB_OTG_VBusChargeDisable Function C void PLIB_USB_OTG_VBusChargeDisable( USB_MODULE_ID index ); Description This function disables VBUS line charge. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusCharge in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusChargeDisable(MY_USB_INSTANCE); 5.6.26.6.9.7 PLIB_USB_OTG_VBusChargeEnable Function C void PLIB_USB_OTG_VBusChargeEnable( USB_MODULE_ID index ); Description This function enables the VBUS line to be charged through a pull-up resistor. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3252 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusDischarge in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusChargeEnable(MY_USB_INSTANCE); 5.6.26.6.9.8 PLIB_USB_OTG_VBusChargeTo3V Function C void PLIB_USB_OTG_VBusChargeTo3V( USB_MODULE_ID index ); Description This function sets the VBUS line to charge to 3.3V. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. Example PLIB_USB_OTG_VBusChargeTo3V(MY_USB_INSTANCE); 5.6.26.6.9.9 PLIB_USB_OTG_VBusChargeTo5V Function C void PLIB_USB_OTG_VBusChargeTo5V( USB_MODULE_ID index ); Description This function sets the VBUS line to charge to 5V. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3253 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. Example PLIB_USB_OTG_VBusChargeTo5V (MY_USB_INSTANCE); 5.6.26.6.9.10 PLIB_USB_OTG_VBusDischargeDisable Function C void PLIB_USB_OTG_VBusDischargeDisable( USB_MODULE_ID index ); Description This function disables VBUS line discharge. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusDischarge in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusDischargeDisable(MY_USB_INSTANCE); 5.6.26.6.9.11 PLIB_USB_OTG_VBusDischargeEnable Function C void PLIB_USB_OTG_VBusDischargeEnable( USB_MODULE_ID index ); Description This function enables the VBUS line to be discharged through a resistor. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3254 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 or PIC32 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusCharge in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusDischargeEnable(MY_USB_INSTANCE); 5.6.26.6.9.12 PLIB_USB_OTG_VBusPowerOff Function C void PLIB_USB_OTG_VBusPowerOff( USB_MODULE_ID index ); Description This function turns off power on the VBUS Line. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusPowerOnOff in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusPowerOff(MY_USB_INSTANCE); 5.6.26.6.9.13 PLIB_USB_OTG_VBusPowerOn Function C void PLIB_USB_OTG_VBusPowerOn( USB_MODULE_ID index ); Description This function turns on power for the VBUS line. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3255 Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_VbusPowerOnOff in your application to determine whether this feature is available. Example PLIB_USB_OTG_VBusPowerOn(MY_USB_INSTANCE); 5.6.26.6.9.14 PLIB_USB_OTG_VBusValid Function C bool PLIB_USB_OTG_VBusValid( USB_MODULE_ID index ); Description This function returns the status of the A-VBUS valid indicator. Preconditions The USB module must be in OTG mode. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - The VBUS voltage is above VA_VBUS_VLD on the A-device, • false - The VBUS voltage is below VA_VBUS_VLD on the A-device Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_ASessionValid in your application to determine whether this feature is available. Example if ( PLIB_USB_OTG_VBusValid(MY_USB_INSTANCE) ) { // Vbus voltage above session valid for A device } else { // Vbus voltage below session valid for A device } 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3256 5.6.26.6.10 OTG Interrupts Functions 5.6.26.6.10.1 PLIB_USB_OTG_InterruptDisable Function C void PLIB_USB_OTG_InterruptDisable( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ); Description This function disables a USB On-The-Go (OTG) interrupt source for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_OTG_InterruptDisable( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); 5.6.26.6.10.2 PLIB_USB_OTG_InterruptEnable Function C void PLIB_USB_OTG_InterruptEnable( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ); Description This function enables USB On-The-Go (OTG) interrupt sources of the USB module to trigger a USB interrupt. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3257 Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Example PLIB_USB_OTG_InterruptEnable( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); 5.6.26.6.10.3 PLIB_USB_OTG_InterruptFlagClear Function C void PLIB_USB_OTG_InterruptFlagClear( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ); Description This function clears a USB On-The-Go (OTG) interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Example PLIB_USB_OTG_InterruptFlagClear( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); 5.6.26.6.10.4 PLIB_USB_OTG_InterruptFlagGet Function C bool PLIB_USB_OTG_InterruptFlagGet( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ); Description This function tests a USB On-The-Go (OTG) interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3258 Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Example if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_ANY) ) if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END) ) { PLIB_USB_OTG_InterruptFlagClear(MY_USB_INSTANCE,USB_OTG_INT_ADEVICE_VBUS_VALID ); // Device A Vbus Valid Change } if ( PLIB_USB_OTG_InterruptFlagGet(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END) ) { PLIB_USB_OTG_InterruptFlagClear(MY_USB_INSTANCE,USB_OTG_INT_BDEVICE_SESSION_END); // Device B Vbus Valid Change } . . . } 5.6.26.6.10.5 PLIB_USB_OTG_InterruptFlagSet Function C void PLIB_USB_OTG_InterruptFlagSet( USB_MODULE_ID index, USB_OTG_INTERRUPTS interruptFlag ); Description This function sets a USB On-The-Go (OTG) interrupt source flag for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_InterruptStatus in your application to determine whether this feature is available. Example PLIB_USB_OTG_InterruptFlagSet( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ); 5.6.26.6.10.6 PLIB_USB_OTG_InterruptIsEnabled Function C bool PLIB_USB_OTG_InterruptIsEnabled( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3259 USB_MODULE_ID index, USB_INTERRUPTS interruptFlag ); Description This function returns whether or not interrupts are enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest interruptFlag Interrupt Returns • true - Interrupts are enabled • false - Interrupts are not enabled Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOTG_Interrupt in your application to determine whether this feature is available. Example if ( PLIB_USB_OTG_InterruptIsEnabled( MY_USB_INSTANCE, USB_OTG_INT_ID_STATE_CHANGE ) ) { } 5.6.26.6.11 USB Activity Functions 5.6.26.6.11.1 PLIB_USB_ActivityPending Function C bool PLIB_USB_ActivityPending( USB_MODULE_ID index ); Description This function returns whether or not USB bus activity has been detected, an interrupt is pending, or an interrupt is yet to be generated. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - The USB module should not be suspended • false - No interrupts are pending or module may be suspended or powered down 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3260 Remarks Not available on PIC18 devices. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsActivityPending in your application to determine whether this feature is available. Example while ( PLIB_USB_ActivityPending(MY_USB_INSTANCE) ) { // Wait } // Suspend USB module. 5.6.26.6.11.2 PLIB_USB_FrameNumberGet Function C uint16_t PLIB_USB_FrameNumberGet( USB_MODULE_ID index ); Description This function returns the USB frame number in the lower 11 bits. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns Current frame number in lower 11 bits. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsFrameNumber in your application to determine whether this feature is available. Example frameNumber = PLIB_USB_FrameNumberGet(MY_USB_INSTANCE); 5.6.26.6.11.3 PLIB_USB_JStateIsActive Function C bool PLIB_USB_JStateIsActive( USB_MODULE_ID index ); Description This function indicates the live JState (differential '0' in low speed, differential '1' in full speed) on the bus. Preconditions The USB module must be in Host mode. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3261 Returns None. Remarks Not applicable for PIC18 devices since PIC18 devices do not support Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLiveJState in your application to determine whether this feature is available. Example // Enable Host Mode PLIB_USB_OperatingModeSelect(MY_USB_INSTANCE,USB_OPMODE_HOST); // Enable D+ and D- pull-down resistors PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLDN, true); PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DMINUS_PULLDN,true); // Disable D+ and D- pull-up resistors PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DPLUS_PULLUP, false); PLIB_USB_OTG_PullUpPullDownSetup(MY_USB_INSTANCE,USB_OTG_DMINUS_PULLUP,false); // Enable SOF Packet generation PLIB_USB_SOFEnable(MY_USB_INSTANCE); // Enable the device attach interrupt PLIB_USB_INT_Enable(MY_USB_INSTANCE,USB_INT_OTG,ACTIVITY_DETECT); // Wait for the Attach interrupt. while(!PLIB_USB_INT_FlagGet(MY_USB_INSTANCE,USB_INT_OTG,ACTIVITY_DETECT) ) { //Do nothing } // Check JState if( PLIB_USB_JStateIsActive(MY_USB_INSTANCE) ) { // Full Speed PLIB_USB_FullSpeedEnable(MY_USB_INSTANCE); } else { // Low Speed PLIB_USB_FullSpeedDisable(MY_USB_INSTANCE); } 5.6.26.6.11.4 PLIB_USB_PacketTransferDisable Function C void PLIB_USB_PacketTransferDisable( USB_MODULE_ID index ); Description This function disables the Serial Interface Engine (SIE). Preconditions USB module must be in device mode. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3262 Returns None. if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferDisable(MY_USB_INSTANCE); } Remarks Not valid when the USB module is in Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. 5.6.26.6.11.5 PLIB_USB_PacketTransferEnable Function C void PLIB_USB_PacketTransferEnable( USB_MODULE_ID index ); Description This function re-enables the Serial Interface Engine (SIE), allowing token and packet processing. Preconditions USB module must be in device mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferEnable(MY_USB_INSTANCE); } Remarks Not valid when the USB module is in Host mode. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. 5.6.26.6.11.6 PLIB_USB_PacketTransferIsDisabled Function C bool PLIB_USB_PacketTransferIsDisabled( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3263 USB_MODULE_ID index ); Description This function indicates that a setup token has been received from the Host and that the Serial Interface Engine (SIE) has been turned off, disabling token and packet processing. Preconditions USB module must be in device mode. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Not valid when USB is Host. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsPacketTransfer in your application to determine whether this feature is available. Example if( PLIB_USB_PacketTransferIsDisabled(MY_USB_INSTANCE) ) { // SETUP token received, do the needful operations . . . // SETUP handling completed, enable Setup token and packet processing: PLIB_USB_PacketTransferEnable(MY_USB_INSTANCE); } 5.6.26.6.11.7 PLIB_USB_SE0InProgress Function C bool PLIB_USB_SE0InProgress( USB_MODULE_ID index ); Description This function returns whether a single-ended zero event is in progress. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - A single ended zero event (SE0) is occurring • false - A single-ended zero event (SE0) is not occurring Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsLiveSingleEndedZero in your application to determine whether this feature is available. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3264 Example if( PLIB_USB_SE0InProgress(MY_USB_INSTANCE) ) { // handle the SE0 event } 5.6.26.6.12 External Transceiver Support Functions 5.6.26.6.12.1 PLIB_USB_I2CInterfaceForExtModuleDisable Function C void PLIB_USB_I2CInterfaceForExtModuleDisable( USB_MODULE_ID index ); Description Specifies that external module(s) are controlled via dedicated pins. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_I2CInterfaceForExtModuleDisable(MY_USB_INSTANCE); 5.6.26.6.12.2 PLIB_USB_I2CInterfaceForExtModuleEnable Function C void PLIB_USB_I2CInterfaceForExtModuleEnable( USB_MODULE_ID index ); Description This function specifies that external module(s) are controlled via the I2C interface. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3265 Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_I2CInterfaceForExtModuleEnable(MY_USB_INSTANCE); 5.6.26.6.12.3 PLIB_USB_TransceiverDisable Function C void PLIB_USB_TransceiverDisable( USB_MODULE_ID index ); Description This function disables the on-chip transceiver and enables the interface to the off-chip transceiver. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks PIC18 devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipTransceiver in your application to determine whether this feature is available. Example PLIB_USB_TransceiverDisable(MY_USB_INSTANCE); 5.6.26.6.12.4 PLIB_USB_TransceiverEnable Function C void PLIB_USB_TransceiverEnable( USB_MODULE_ID index ); Description This function enables the on-chip transceiver. The interface to the off-chip transceiver is disabled. Preconditions Use only before the USB module is enabled by calling PLIB_USB_Enable. Parameters Parameters Description index Identifier for the device instance of interest Returns None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3266 Remarks PIC18 devices only. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsOnChipTransceiver in your application to determine whether this feature is available. Example PLIB_USB_TransceiverEnable(MY_USB_INSTANCE); 5.6.26.6.13 VBus Support Functions 5.6.26.6.13.1 PLIB_USB_ExternalComparatorMode2Pin Function C void PLIB_USB_ExternalComparatorMode2Pin( USB_MODULE_ID index ); Description This function sets the 2-pin input configuration for VBUS Comparators. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_ExternalComparatorMode2Pin(MY_USB_INSTANCE); 5.6.26.6.13.2 PLIB_USB_ExternalComparatorMode3Pin Function C void PLIB_USB_ExternalComparatorMode3Pin( USB_MODULE_ID index ); Description This function sets the 3-pin input configuration for VBUS comparators. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3267 Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_ExternalComparatorMode3Pin(MY_USB_INSTANCE); 5.6.26.6.13.3 PLIB_USB_PWMCounterDisable Function C void PLIB_USB_PWMCounterDisable( USB_MODULE_ID index ); Description This function disables the PWM counter used to generate the VBUS for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_PWMDisable(MY_USB_INSTANCE); PLIB_USB_PWMCounterDisable(MY_USB_INSTANCE); 5.6.26.6.13.4 PLIB_USB_PWMCounterEnable Function C void PLIB_USB_PWMCounterEnable( USB_MODULE_ID index ); Description This function enables the PWM counter used to generate the VBUS for the USB module. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3268 Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_PWMEnable(MY_USB_INSTANCE); PLIB_USB_PWMCounterEnable(MY_USB_INSTANCE); 5.6.26.6.13.5 PLIB_USB_PWMDisable Function C void PLIB_USB_PWMDisable( USB_MODULE_ID index ); Description This function disables the PWM Generator. PWM output held in a reset state defined by PLIB_USB_PWMPolarityActiveHigh or PLIB_USB_PWMPolarityActiveLow. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_PWMDisable (MY_USB_INSTANCE); 5.6.26.6.13.6 PLIB_USB_PWMEnable Function C void PLIB_USB_PWMEnable( USB_MODULE_ID index ); Description This function enables the PWM Generator. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3269 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_PWMEnable(MY_USB_INSTANCE); 5.6.26.6.13.7 PLIB_USB_PWMPolaritiyActiveLow Function C void PLIB_USB_PWMPolaritiyActiveLow( USB_MODULE_ID index ); Description This function sets the PWM output to active-high and resets low. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. 5.6.26.6.13.8 PLIB_USB_PWMPolarityActiveHigh Function C void PLIB_USB_PWMPolarityActiveHigh( USB_MODULE_ID index ); Description This function sets the PWM output to active-low and resets high. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3270 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_PWMPolaritiy (MY_USB_INSTANCE); 5.6.26.6.13.9 PLIB_USB_VBoostDisable Function C void PLIB_USB_VBoostDisable( USB_MODULE_ID index ); Description This function disables the On-Chip 5V Boost Regulator Circuit Disabled bit. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBoostDisable(MY_USB_INSTANCE); 5.6.26.6.13.10 PLIB_USB_VBoostEnable Function C void PLIB_USB_VBoostEnable( USB_MODULE_ID index ); Description This function enables the On-Chip 5V Boost Regulator Circuit Enabled bit. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3271 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBoostEnable(MY_USB_INSTANCE); 5.6.26.6.13.11 PLIB_USB_VBUSComparatorDisable Function C void PLIB_USB_VBUSComparatorDisable( USB_MODULE_ID index ); Description This function disables the on-chip VBUS Comparator. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBUSComparatorDisable(MY_USB_INSTANCE); 5.6.26.6.13.12 PLIB_USB_VBUSComparatorEnable Function C void PLIB_USB_VBUSComparatorEnable( USB_MODULE_ID index ); Description This function enables the on-chip VBUS Comparator. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3272 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBUSComparatorEnable(MY_USB_INSTANCE); 5.6.26.6.13.13 PLIB_USB_VBUSPullUpDisable Function C void PLIB_USB_VBUSPullUpDisable( USB_MODULE_ID index ); Description This function diables the pull-up on the VBUS pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBUSPullUpDisable(MY_USB_INSTANCE); 5.6.26.6.13.14 PLIB_USB_VBUSPullUpEnable Function C void PLIB_USB_VBUSPullUpEnable( USB_MODULE_ID index ); Description This function enables the pull-up on the VBUS pin. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3273 Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is available on your device. Example PLIB_USB_VBUSPullUpEnable(MY_USB_INSTANCE); 5.6.26.6.14 Test Support Functions 5.6.26.6.14.1 PLIB_USB_EyePatternDisable Function C void PLIB_USB_EyePatternDisable( USB_MODULE_ID index ); Description This function disables the USB eye pattern test. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEyePattern in your application to determine whether this feature is available. Example PLIB_USB_EyePatternDisable(MY_USB_INSTANCE); 5.6.26.6.14.2 PLIB_USB_EyePatternEnable Function C void PLIB_USB_EyePatternEnable( USB_MODULE_ID index ); Description This function enables the USB eye pattern test. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3274 Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsEyePattern in your application to determine whether this feature is available. Example PLIB_USB_EyePatternEnable(MY_USB_INSTANCE); 5.6.26.6.15 Other Functions 5.6.26.6.15.1 PLIB_USB_ModuleIsBusy Function C bool PLIB_USB_ModuleIsBusy( USB_MODULE_ID index ); Description This function indicates if the USB module is not ready to be enabled. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns • true - USB module is active or disabled, but not ready to be enabled • false - USB module is not active and is ready to be enabled Remarks This feature is not available on PIC18, PIC24, and dsPIC33 devices. If PLIB_USB_ModuleIsBusy(MY_USB_INSTANCE) == true and the USB module is disabled, and all status returned for the module, all enables/disables for the module will produce undefined results. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsModuleBusyin your application to determine whether this feature is available. Example #ifdef (__PIC32MX__) while ( PLIB_USB_ModuleIsBusy(MY_USB_INSTANCE) ) { // wait 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3275 } #endif PLIB_USB_Disable(MY_USB_INSTANCE); 5.6.26.6.15.2 PLIB_USB_PingPongFreeze Function C void PLIB_USB_PingPongFreeze( USB_MODULE_ID index ); Description This function resets all Ping-Pong buffer pointers to even buffers. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks Buffers remain "frozen" at "Even" until they are unfrozen using PLIB_USB_PingPongUnfreeze. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Example // Reset all ping-pong buffers to "Even" PLIB_USB_PingPongFreeze(MY_USB_INSTANCE); PLIB_USB_PingPongUnfreeze(MY_USB_INSTANCE); 5.6.26.6.15.3 PLIB_USB_PingPongReset Function C void PLIB_USB_PingPongReset( USB_MODULE_ID index ); Description This function resets the USB peripheral internal Ping-Pong indicator to point to Even buffers. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3276 PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Example PLIB_USB_PingPongReset(MY_USB_INSTANCE); 5.6.26.6.15.4 PLIB_USB_PingPongUnfreeze Function C void PLIB_USB_PingPongUnfreeze( USB_MODULE_ID index ); Description This function enables Ping-Pong buffering. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest Returns None. Remarks See PLIB_USB_PingPongFreeze. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsBufferFreeze in your application to determine whether this feature is available. Example // Reset all Ping-Pong buffers to "Even" PLIB_USB_PingPongFreeze(MY_USB_INSTANCE); PLIB_USB_PingPongUnfreeze(MY_USB_INSTANCE); 5.6.26.6.15.5 PLIB_USB_TokenSend Function C void PLIB_USB_TokenSend( USB_MODULE_ID index, USB_PID pidValue, uint8_t endpoint, uint8_t deviceAddress, bool isLowSpeed ); Description This function sends the specified token to the specified endpoint and address. The token is placed on the bus at the next available time. The token can be executed at low speed. Preconditions None. Parameters Parameters Description index Identifier for the device instance of interest pidValue PID of the token to be placed on the bus. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3277 endpoint Device endpoint to which the token should be sent. isLowSpeed Is true if the token should be executed at low speed. Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_USB_ExistsGEN_Interrupt in your application to determine whether this feature is available. Example // Send an OUT token to endpoint 1 device address 2 at full speed PLIB_USB_SendToken(MY_USB_INSTANCE, USB_PID_OUT, 1, 2, false); 5.6.26.6.16 Data Types and Constants 5.6.26.6.16.1 USB_BUFFER_DATA01 Enumeration C typedef enum { USB_BUFFER_DATA0, USB_BUFFER_DATA1 } USB_BUFFER_DATA01; Description USB Endpoint Buffer Data Toggle Enumeration This data type provides enumeration data toggle for a buffer. Members Members Description USB_BUFFER_DATA0 DATA0/1 = 0 USB_BUFFER_DATA1 DATA0/1 = 1 Remarks None. 5.6.26.6.16.2 USB_BUFFER_DIRECTION Enumeration C typedef enum { USB_BUFFER_RX, USB_BUFFER_TX } USB_BUFFER_DIRECTION; Description USB Endpoint Buffer Direction Enumeration This data type provides enumeration transmit/receive direction for a buffer. Members Members Description USB_BUFFER_RX Receive USB_BUFFER_TX Transmit 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3278 Remarks None. 5.6.26.6.16.3 USB_BUFFER_PING_PONG Enumeration C typedef enum { USB_BUFFER_EVEN, USB_BUFFER_ODD } USB_BUFFER_PING_PONG; Description Enumeration of USB Buffer Ping-Pong This data type enumerates the ping-pong buffer (Even vs. Odd). Members Members Description USB_BUFFER_EVEN Even Buffer USB_BUFFER_ODD Odd Buffer Remarks None. 5.6.26.6.16.4 USB_BUFFER_SCHEDULE_DATA01 Enumeration C typedef enum { USB_BUFFER_DONTCHANGE, USB_BUFFER_SET_DATA0, USB_BUFFER_SET_DATA1 } USB_BUFFER_SCHEDULE_DATA01; Description USB Endpoint Buffer Data Toggle Enumeration for Buffer Schedulint This data type provides enumeration data toggle for a buffer. Members Members Description USB_BUFFER_DONTCHANGE Don't Change DATA0/1 USB_BUFFER_SET_DATA0 DATA0/1 = 0 USB_BUFFER_SET_DATA1 DATA0/1 = 1 Remarks None. 5.6.26.6.16.5 USB_EP_TXRX Enumeration C typedef enum { USB_EP_NOTXRX, USB_EP_RX, USB_EP_TX, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3279 USB_EP_TX_RX } USB_EP_TXRX; Description Enumeration of USB Endpoint Transmit/Receive Setup This data type provides enumeration transmit/receive setup for an endpoint. Members Members Description USB_EP_NOTXRX Nothing enabled for endpoint USB_EP_RX Receive enabled for endpoint USB_EP_TX Transmit enabled for endpoint USB_EP_TX_RX Transmit and Receive enabled for endpoint Remarks None. 5.6.26.6.16.6 USB_OPMODES Enumeration C typedef enum { USB_OPMODE_NONE, USB_OPMODE_DEVICE, USB_OPMODE_HOST, USB_OPMODE_OTG } USB_OPMODES; Description USB Operating Modes Enumeration This data type provides enumeration of the operating modes supported by the USB module. Members Members Description USB_OPMODE_NONE None USB_OPMODE_DEVICE Device USB_OPMODE_HOST Host USB_OPMODE_OTG OTG Remarks PIC18 devices only support USB_OPMODE_DEVICE. 5.6.26.6.16.7 USB_OTG_INTERRUPTS Enumeration C typedef enum { USB_OTG_INT_ADEVICE_VBUS_VALID, USB_OTG_INT_OTG_RESERVED, USB_OTG_INT_BDEVICE_SESSION_END, USB_OTG_INT_SESSION_VALID, USB_OTG_INT_ACTIVITY_DETECT, USB_OTG_INT_STABLE_LINE_STATE, USB_OTG_INT_ONE_MS_TIMEOUT, USB_OTG_INT_ID_STATE_CHANGE, USB_OTG_INT_ANY, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3280 USB_OTG_INT_ALL } USB_OTG_INTERRUPTS; Description USB OTG Interrupts Enumeration This data type provides enumeration of interrupts related to the USB OTG module. Members Members Description USB_OTG_INT_ADEVICE_VBUS_VALID State of (Vbus > Va_vbus_vld) on the A device has changed USB_OTG_INT_OTG_RESERVED Reserved. Don't use. USB_OTG_INT_BDEVICE_SESSION_END State of (Vbus < Vb_sess_end) on the B device has changed USB_OTG_INT_SESSION_VALID State of (Vbus > Va_sess_vld) on the A or B devices has changed USB_OTG_INT_ACTIVITY_DETECT Activity detected on the D+, D-, ID, or Vbus lines USB_OTG_INT_STABLE_LINE_STATE USB line state has been stable for 1 ms, but different from last time USB_OTG_INT_ONE_MS_TIMEOUT One millescond timer has expired USB_OTG_INT_ID_STATE_CHANGE Change in state of ID pin detected. USB_OTG_INT_ANY All or Any of the above USB_OTG_INT_ALL All or Any of the above Remarks Not applicable on PIC18 devices or if the USB OTG module is not enabled. 5.6.26.6.16.8 USB_OTG_PULL_UP_PULL_DOWN Enumeration C typedef enum { USB_OTG_DPLUS_PULLUP, USB_OTG_DMINUS_PULLUP, USB_OTG_DPLUS_PULLDN, USB_OTG_DMINUS_PULLDN } USB_OTG_PULL_UP_PULL_DOWN; Description Enumeration of Pull-Up and Pull-Down Resistors for OTG This data type enumerates the OTG Pull-Up and Pull-Down resistors for D+ and D- . Members Members Description USB_OTG_DPLUS_PULLUP D+ Pull-Up USB_OTG_DMINUS_PULLUP D- Pull-Up USB_OTG_DPLUS_PULLDN D+ Pull-Down USB_OTG_DMINUS_PULLDN D- Pull-Down Remarks Not applicable for PIC18 devices. 5.6.26.6.16.9 USB_PID Enumeration C typedef enum { 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3281 USB_PID_SETUP, USB_PID_IN, USB_PID_OUT } USB_PID; Description Enumeration of Legal Packet IDs (PIDs) This data type enumerates the valid (i.e., legal) PID values. While the PID field is four bits long, only these values are legal and should be used. The use of any other values may cause unpredictable results. Members Members Description USB_PID_SETUP Setup token USB_PID_IN IN token USB_PID_OUT OUT token 5.6.26.6.16.10 USB_PING_PONG_MODE Enumeration C typedef enum { USB_PING_PONG_ALL_BUT_EP0, USB_PING_PONG_FULL_PING_PONG, USB_PING_PONG_EP0_OUT_ONLY, USB_PING_PONG_NO_PING_PONG } USB_PING_PONG_MODE; Description Enumeration of USB Ping-Pong Modes for PIC18 and PIC24F This data type supports the four modes of ping-pong buffering for PIC18 and PIC24F devices. Members Members Description USB_PING_PONG_ALL_BUT_EP0 Ping-Pong buffering on all endpoints except Endpoint Zero USB_PING_PONG_FULL_PING_PONG Ping-Pong buffering on all endpoints USB_PING_PONG_EP0_OUT_ONLY Ping-Pong buffering on just Endpoint Zero transmit USB_PING_PONG_NO_PING_PONG No ping-pong buffering Remarks For PIC18 and PIC24F devices only. 5.6.26.6.16.11 USB_PING_PONG_STATE Enumeration C typedef enum { USB_PING_PONG_EVEN, USB_PING_PONG_ODD } USB_PING_PONG_STATE; Description Enumeration of USB Ping-Pong Indicator This data type decodes which buffer (Even vs. Odd) was used for the last transaction. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3282 Members Members Description USB_PING_PONG_EVEN Last transaction on Even Buffer USB_PING_PONG_ODD Last transaction on Odd Buffer Remarks None. 5.6.26.6.16.12 USB_TOKEN_SPEED Enumeration C typedef enum { USB_LOWSPEED_TOKENS, USB_FULLSPEED_TOKENS } USB_TOKEN_SPEED; Description USB Token Speeds Enumeration This data type provides enumeration of available token speeds. Members Members Description USB_LOWSPEED_TOKENS Low Speed Tokens USB_FULLSPEED_TOKENS Full Speed Tokens Remarks For Host mode only. 5.6.26.6.16.13 USB_MAX_EP_NUMBER Macro C #define USB_MAX_EP_NUMBER 15 Description Maximum number of endpoints This constant defines the maximum number of endpoints supported (not including EP0). It is used in dimensioning the Buffer Descriptor Table (BDT) array. 5.6.26.6.17 Feature Existence Functions 5.6.26.6.17.1 PLIB_USB_ExistsActivityPending Function C bool PLIB_USB_ExistsActivityPending( USB_MODULE_ID index ); Description This function identifies whether the ActivityPending feature is available on the USB module. When this function returns true, this function is supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3283 • PLIB_USB_ActivityPending Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ActivityPending feature is supported on the device • false - The ActivityPending feature is not supported on the device Remarks None. 5.6.26.6.17.2 PLIB_USB_ExistsALL_Interrupt Function C bool PLIB_USB_ExistsALL_Interrupt( USB_MODULE_ID index ); Description This function identifies whether the ALL_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_AllInterruptEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ALL_Interrupt feature is supported on the device • false - The ALL_Interrupt feature is not supported on the device Remarks None. 5.6.26.6.17.3 PLIB_USB_ExistsAutomaticSuspend Function C bool PLIB_USB_ExistsAutomaticSuspend( USB_MODULE_ID index ); Description This function identifies whether the AutomaticSuspend feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_AutoSuspendDisable 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3284 • PLIB_USB_AutoSuspendEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The AutomaticSuspend feature is supported on the device • false - The AutomaticSuspend feature is not supported on the device Remarks None. 5.6.26.6.17.4 PLIB_USB_ExistsBDTBaseAddress Function C bool PLIB_USB_ExistsBDTBaseAddress( USB_MODULE_ID index ); Description This function identifies whether the BDTBaseAddress feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_BDTBaseAddressGet • PLIB_USB_BDTBaseAddressSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDTBaseAddress feature is supported on the device • false - The BDTBaseAddress feature is not supported on the device Remarks None. 5.6.26.6.17.5 PLIB_USB_ExistsBDTFunctions Function C bool PLIB_USB_ExistsBDTFunctions( USB_MODULE_ID index ); Description This function identifies whether the BDTFunctions feature is available on the USB module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3285 • PLIB_USB_BufferAddressGet • PLIB_USB_BufferAddressSet • PLIB_USB_BufferByteCountGet • PLIB_USB_BufferByteCountSet • PLIB_USB_BufferCancelReleaseToUSB • PLIB_USB_BufferAllCancelReleaseToUSB • PLIB_USB_BufferClearAll • PLIB_USB_BufferDataToggleGet • PLIB_USB_BufferDataToggleSelect • PLIB_USB_BufferDataToggleSyncEnable • PLIB_USB_BufferDataToggleSyncDisable • PLIB_USB_BufferIndexGet • PLIB_USB_BufferPIDBitsClear • PLIB_USB_BufferPIDGet • PLIB_USB_BufferReleasedToSW • PLIB_USB_BufferReleaseToUSB • PLIB_USB_BufferSchedule • PLIB_USB_BufferStallDisable • PLIB_USB_BufferStallEnable • PLIB_USB_BufferStallGet • PLIB_USB_BufferEP0RxStatusInitialize • PLIB_USB_BufferClearAllDTSEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BDTFunctions feature is supported on the device • false - The BDTFunctions feature is not supported on the device Remarks None. 5.6.26.6.17.6 PLIB_USB_ExistsBufferFreeze Function C bool PLIB_USB_ExistsBufferFreeze( USB_MODULE_ID index ); Description This function identifies whether the BufferFreeze feature is available on the USB module. When this function returns true, these 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3286 functions are supported on the device: • PLIB_USB_PingPongFreeze • PLIB_USB_PingPongUnfreeze • PLIB_USB_PingPongReset Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The BufferFreeze feature is supported on the device • false - The BufferFreeze feature is not supported on the device Remarks None. 5.6.26.6.17.7 PLIB_USB_ExistsDeviceAddress Function C bool PLIB_USB_ExistsDeviceAddress( USB_MODULE_ID index ); Description This function identifies whether the DeviceAddress feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_DeviceAddressSet • PLIB_USB_DeviceAddressGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The DeviceAddress feature is supported on the device • false - The DeviceAddress feature is not supported on the device Remarks None. 5.6.26.6.17.8 PLIB_USB_ExistsEP0LowSpeedConnect Function C bool PLIB_USB_ExistsEP0LowSpeedConnect( USB_MODULE_ID index 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3287 ); Description This function identifies whether the EP0LowSpeedConnect feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EP0LSDirectConnectEnable • PLIB_USB_EP0LSDirectConnectDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EP0LowSpeedConnect feature is supported on the device • false - The EP0LowSpeedConnect feature is not supported on the device Remarks None. 5.6.26.6.17.9 PLIB_USB_ExistsEP0NAKRetry Function C bool PLIB_USB_ExistsEP0NAKRetry( USB_MODULE_ID index ); Description This function identifies whether the EP0NAKRetry feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EP0NakRetryEnable • PLIB_USB_EP0NakRetryDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EP0NAKRetry feature is supported on the device • false - The EP0NAKRetry feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3288 5.6.26.6.17.10 PLIB_USB_ExistsEPnRxEnable Function C bool PLIB_USB_ExistsEPnRxEnable( USB_MODULE_ID index ); Description This function identifies whether the EPnRxEnableEnhanced feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EPnRxEnable • PLIB_USB_EPnRxDisable • PLIB_USB_EPnTxEnable • PLIB_USB_EPnTxDisable • PLIB_USB_EPnHandshakeEnable • PLIB_USB_EPnHandshakeDisable • PLIB_USB_EPnControlTransferEnable • PLIB_USB_EPnControlTransferDisable • PLIB_USB_EPnIsStalled • PLIB_USB_EPnStallClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EPnRxEnableEnhanced feature is supported on the device • false - The EPnRxEnableEnhanced feature is not supported on the device Remarks None. 5.6.26.6.17.11 PLIB_USB_ExistsEPnTxRx Function C bool PLIB_USB_ExistsEPnTxRx( USB_MODULE_ID index ); Description This function identifies whether the EPnTxRx feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EPnTxSelect • PLIB_USB_EPnRxSelect • PLIB_USB_EPnTxRxSelect 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3289 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EPnTxRx feature is supported on the device • false - The EPnTxRx feature is not supported on the device Remarks None. 5.6.26.6.17.12 PLIB_USB_ExistsERR_Interrupt Function C bool PLIB_USB_ExistsERR_Interrupt( USB_MODULE_ID index ); Description This function identifies whether the ERR_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ErrorInterruptEnable • PLIB_USB_ErrorInterruptDisable • PLIB_USB_ErrorInterruptIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ERR_Interrupt feature is supported on the device • false - The ERR_Interrupt feature is not supported on the device Remarks None. 5.6.26.6.17.13 PLIB_USB_ExistsERR_InterruptStatus Function C bool PLIB_USB_ExistsERR_InterruptStatus( USB_MODULE_ID index ); Description This function identifies whether the ERR_InterruptStatus feature is available on the USB module. When this function returns true, 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3290 these functions are supported on the device: • PLIB_USB_ErrorInterruptFlagSet • PLIB_USB_ErrorInterruptFlagClear • PLIB_USB_ErrorInterruptFlagGet • PLIB_USB_ErrorInterruptFlagAllGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ERR_InterruptStatus feature is supported on the device • false - The ERR_InterruptStatus feature is not supported on the device Remarks None. 5.6.26.6.17.14 PLIB_USB_ExistsEyePattern Function C bool PLIB_USB_ExistsEyePattern( USB_MODULE_ID index ); Description This function identifies whether the EyePattern feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_EyePatternDisable • PLIB_USB_EyePatternEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The EyePattern feature is supported on the device • false - The EyePattern feature is not supported on the device Remarks None. 5.6.26.6.17.15 PLIB_USB_ExistsFrameNumber Function C bool PLIB_USB_ExistsFrameNumber( 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3291 USB_MODULE_ID index ); Description This function identifies whether the FrameNumber feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_FrameNumberGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The FrameNumber feature is supported on the device • false - The FrameNumber feature is not supported on the device Remarks None. 5.6.26.6.17.16 PLIB_USB_ExistsGEN_Interrupt Function C bool PLIB_USB_ExistsGEN_Interrupt( USB_MODULE_ID index ); Description This function identifies whether the GEN_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_InterruptEnable • PLIB_USB_InterruptDisable • PLIB_USB_InterruptIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GEN_Interrupt feature is supported on the device • false - The GEN_Interrupt feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3292 5.6.26.6.17.17 PLIB_USB_ExistsGEN_InterruptStatus Function C bool PLIB_USB_ExistsGEN_InterruptStatus( USB_MODULE_ID index ); Description This function identifies whether the GEN_InterruptStatus feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_InterruptFlagSet • PLIB_USB_InterruptFlagClear • PLIB_USB_InterruptFlagGet • PLIB_USB_InterruptFlagAllGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The GEN_InterruptStatus feature is supported on the device • false - The GEN_InterruptStatus feature is not supported on the device Remarks None. 5.6.26.6.17.18 PLIB_USB_ExistsHostBusyWithToken Function C bool PLIB_USB_ExistsHostBusyWithToken( USB_MODULE_ID index ); Description This function identifies whether the HostBusyWithToken feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_IsBusyWithToken Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HostBusyWithToken feature is supported on the device • false - The HostBusyWithToken feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3293 Remarks None. 5.6.26.6.17.19 PLIB_USB_ExistsHostGeneratesReset Function C bool PLIB_USB_ExistsHostGeneratesReset( USB_MODULE_ID index ); Description This function identifies whether the HostGeneratesReset feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ResetSignalEnable • PLIB_USB_ResetSignalDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The HostGeneratesReset feature is supported on the device • false - The HostGeneratesReset feature is not supported on the device Remarks None. 5.6.26.6.17.20 PLIB_USB_ExistsLastDirection Function C bool PLIB_USB_ExistsLastDirection( USB_MODULE_ID index ); Description This function identifies whether the LastDirection feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionDirectionGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LastDirection feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3294 • false - The LastDirection feature is not supported on the device Remarks None. 5.6.26.6.17.21 PLIB_USB_ExistsLastEndpoint Function C bool PLIB_USB_ExistsLastEndpoint( USB_MODULE_ID index ); Description This function identifies whether the LastEndpoint feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionEndPtGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LastEndpoint feature is supported on the device • false - The LastEndpoint feature is not supported on the device Remarks None. 5.6.26.6.17.22 PLIB_USB_ExistsLastPingPong Function C bool PLIB_USB_ExistsLastPingPong( USB_MODULE_ID index ); Description This function identifies whether the LastPingPong feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionPingPongStateGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LastPingPong feature is supported on the device • false - The LastPingPong feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3295 Remarks None. 5.6.26.6.17.23 PLIB_USB_ExistsLastTransactionDetails Function C bool PLIB_USB_ExistsLastTransactionDetails( USB_MODULE_ID index ); Description This function identifies whether the LastTransactionDetails feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_LastTransactionDetailsGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LastTransactionDetails feature is supported on the device • false - The LastTransactionDetails feature is not supported on the device Remarks None. 5.6.26.6.17.24 PLIB_USB_ExistsLiveJState Function C bool PLIB_USB_ExistsLiveJState( USB_MODULE_ID index ); Description This function identifies whether the LiveJState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_JStateIsActive Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LiveJState feature is supported on the device • false - The LiveJState feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3296 Remarks None. 5.6.26.6.17.25 PLIB_USB_ExistsLiveSingleEndedZero Function C bool PLIB_USB_ExistsLiveSingleEndedZero( USB_MODULE_ID index ); Description This function identifies whether the LiveSingleEndedZero feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_SE0InProgress Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The LiveSingleEndedZero feature is supported on the device • false - The LiveSingleEndedZero feature is not supported on the device Remarks None. 5.6.26.6.17.26 PLIB_USB_ExistsModuleBusy Function C bool PLIB_USB_ExistsModuleBusy( USB_MODULE_ID index ); Description This function identifies whether the ModuleBusy feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ModuleIsBusy Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ModuleBusy feature is supported on the device • false - The ModuleBusy feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3297 Remarks None. 5.6.26.6.17.27 PLIB_USB_ExistsModulePower Function C bool PLIB_USB_ExistsModulePower( USB_MODULE_ID index ); Description This function identifies whether the ModulePower feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_Enable • PLIB_USB_Disable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ModulePower feature is supported on the device • false - The ModulePower feature is not supported on the device Remarks None. 5.6.26.6.17.28 PLIB_USB_ExistsNextTokenSpeed Function C bool PLIB_USB_ExistsNextTokenSpeed( USB_MODULE_ID index ); Description This function identifies whether the NextTokenSpeed feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_TokenSpeedSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The NextTokenSpeed feature is supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3298 • false - The NextTokenSpeed feature is not supported on the device Remarks None. 5.6.26.6.17.29 PLIB_USB_ExistsOnChipPullup Function C bool PLIB_USB_ExistsOnChipPullup( USB_MODULE_ID index ); Description This function identifies whether the OnChipPullup feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OnChipPullUpDisable • PLIB_USB_OnChipPullUpEnable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OnChipPullup feature is supported on the device • false - The OnChipPullup feature is not supported on the device Remarks None. 5.6.26.6.17.30 PLIB_USB_ExistsOnChipTransceiver Function C bool PLIB_USB_ExistsOnChipTransceiver( USB_MODULE_ID index ); Description This function identifies whether the OnChipTransceiver feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TransceiverEnable • PLIB_USB_TransceiverDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3299 Returns • true - The OnChipTransceiver feature is supported on the device • false - The OnChipTransceiver feature is not supported on the device Remarks None. 5.6.26.6.17.31 PLIB_USB_ExistsOpModeSelect Function C bool PLIB_USB_ExistsOpModeSelect( USB_MODULE_ID index ); Description This function identifies whether the OpModeSelect feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OperatingModeSelect Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OpModeSelect feature is supported on the device • false - The OpModeSelect feature is not supported on the device Remarks None. 5.6.26.6.17.32 PLIB_USB_ExistsOTG_ASessionValid Function C bool PLIB_USB_ExistsOTG_ASessionValid( USB_MODULE_ID index ); Description This function identifies whether the OTG_ASessionValid feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_VBusValid Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3300 Returns • true - The OTG_ASessionValid feature is supported on the device • false - The OTG_ASessionValid feature is not supported on the device Remarks None. 5.6.26.6.17.33 PLIB_USB_ExistsOTG_BSessionEnd Function C bool PLIB_USB_ExistsOTG_BSessionEnd( USB_MODULE_ID index ); Description This function identifies whether the OTG_BSessionEnd feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_BSessionHasEnded Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_BSessionEnd feature is supported on the device • false - The OTG_BSessionEnd feature is not supported on the device Remarks None. 5.6.26.6.17.34 PLIB_USB_ExistsOTG_IDPinState Function C bool PLIB_USB_ExistsOTG_IDPinState( USB_MODULE_ID index ); Description This function identifies whether the OTG_IDPinState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_IDPinStateIsTypeA Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3301 Returns • true - The OTG_IDPinState feature is supported on the device • false - The OTG_IDPinState feature is not supported on the device Remarks None. 5.6.26.6.17.35 PLIB_USB_ExistsOTG_Interrupt Function C bool PLIB_USB_ExistsOTG_Interrupt( USB_MODULE_ID index ); Description This function identifies whether the OTG_Interrupt feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_InterruptEnable • PLIB_USB_OTG_InterruptDisable • PLIB_USB_OTG_InterruptIsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_Interrupt feature is supported on the device • false - The OTG_Interrupt feature is not supported on the device Remarks None. 5.6.26.6.17.36 PLIB_USB_ExistsOTG_InterruptStatus Function C bool PLIB_USB_ExistsOTG_InterruptStatus( USB_MODULE_ID index ); Description This function identifies whether the OTG_InterruptStatus feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_InterruptFlagSet • PLIB_USB_OTG_InterruptFlagClear • PLIB_USB_OTG_InterruptFlagGet 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3302 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_InterruptStatus feature is supported on the device • false - The OTG_InterruptStatus feature is not supported on the device Remarks None. 5.6.26.6.17.37 PLIB_USB_ExistsOTG_LineState Function C bool PLIB_USB_ExistsOTG_LineState( USB_MODULE_ID index ); Description This function identifies whether the OTG_LineState feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_LineStateIsStable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_LineState feature is supported on the device • false - The OTG_LineState feature is not supported on the device Remarks None. 5.6.26.6.17.38 PLIB_USB_ExistsOTG_PullUpPullDown Function C bool PLIB_USB_ExistsOTG_PullUpPullDown( USB_MODULE_ID index ); Description This function identifies whether the OTG_PullUpPullDown feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_PullUpPullDownSetup 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3303 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_PullUpPullDown feature is supported on the device • false - The OTG_PullUpPullDown feature is not supported on the device Remarks None. 5.6.26.6.17.39 PLIB_USB_ExistsOTG_SessionValid Function C bool PLIB_USB_ExistsOTG_SessionValid( USB_MODULE_ID index ); Description This function identifies whether the OTG_SessionValid feature is available on the USB module. When this function returns true, this function is supported on the device: • PLIB_USB_OTG_SessionValid Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_SessionValid feature is supported on the device • false - The OTG_SessionValid feature is not supported on the device Remarks None. 5.6.26.6.17.40 PLIB_USB_ExistsOTG_VbusCharge Function C bool PLIB_USB_ExistsOTG_VbusCharge( USB_MODULE_ID index ); Description This function identifies whether the OTG_VbusCharge feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_VBusChargeEnable 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3304 • PLIB_USB_OTG_VBusChargeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_VbusCharge feature is supported on the device • false - The OTG_VbusCharge feature is not supported on the device Remarks None. 5.6.26.6.17.41 PLIB_USB_ExistsOTG_VbusDischarge Function C bool PLIB_USB_ExistsOTG_VbusDischarge( USB_MODULE_ID index ); Description This function identifies whether the OTG_VbusDischarge feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_OTG_VBusDischargeEnable • PLIB_USB_OTG_VBusDischargeDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_VbusDischarge feature is supported on the device • false - The OTG_VbusDischarge feature is not supported on the device Remarks None. 5.6.26.6.17.42 PLIB_USB_ExistsOTG_VbusPowerOnOff Function C bool PLIB_USB_ExistsOTG_VbusPowerOnOff( USB_MODULE_ID index ); Description This function identifies whether the OTG_VbusPowerOnOff feature is available on the USB module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3305 • PLIB_USB_OTG_VBusPowerOff • PLIB_USB_OTG_VBusPowerOn Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The OTG_VbusPowerOnOff feature is supported on the device • false - The OTG_VbusPowerOnOff feature is not supported on the device Remarks None. 5.6.26.6.17.43 PLIB_USB_ExistsPacketTransfer Function C bool PLIB_USB_ExistsPacketTransfer( USB_MODULE_ID index ); Description This function identifies whether the PacketTransfer feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_PacketTransferIsDisabled • PLIB_USB_PacketTransferEnable • PLIB_USB_PacketTransferDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PacketTransfer feature is supported on the device • false - The PacketTransfer feature is not supported on the device Remarks None. 5.6.26.6.17.44 PLIB_USB_ExistsPingPongMode Function C bool PLIB_USB_ExistsPingPongMode( USB_MODULE_ID index ); 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3306 Description This function identifies whether the PingPongMode feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_PingPongModeSelect • PLIB_USB_PingPongModeGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PingPongMode feature is supported on the device • false - The PingPongMode feature is not supported on the device Remarks None. 5.6.26.6.17.45 PLIB_USB_ExistsResumeSignaling Function C bool PLIB_USB_ExistsResumeSignaling( USB_MODULE_ID index ); Description This function identifies whether the ResumeSignaling feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_ResumeSignalingEnable • PLIB_USB_ResumeSignalingDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The ResumeSignaling feature is supported on the device • false - The ResumeSignaling feature is not supported on the device Remarks None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3307 5.6.26.6.17.46 PLIB_USB_ExistsSleepEntryGuard Function C bool PLIB_USB_ExistsSleepEntryGuard( USB_MODULE_ID index ); Description This function identifies whether the SleepEntryGuard feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SleepGuardEnable • PLIB_USB_SleepGuardDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SleepEntryGuard feature is supported on the device • false - The SleepEntryGuard feature is not supported on the device Remarks None. 5.6.26.6.17.47 PLIB_USB_ExistsSOFThreshold Function C bool PLIB_USB_ExistsSOFThreshold( USB_MODULE_ID index ); Description This function identifies whether the SOFThreshold feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SOFThresholdGet • PLIB_USB_SOFThresholdSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SOFThreshold feature is supported on the device • false - The SOFThreshold feature is not supported on the device 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3308 Remarks None. 5.6.26.6.17.48 PLIB_USB_ExistsSpeedControl Function C bool PLIB_USB_ExistsSpeedControl( USB_MODULE_ID index ); Description This function identifies whether the SpeedControl feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_FullSpeedEnable • PLIB_USB_FullSpeedDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The SpeedControl feature is supported on the device • false - The SpeedControl feature is not supported on the device Remarks None. 5.6.26.6.17.49 PLIB_USB_ExistsStartOfFrames Function C bool PLIB_USB_ExistsStartOfFrames( USB_MODULE_ID index ); Description This function identifies whether the StartOfFrames feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SOFEnable • PLIB_USB_SOFDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3309 Returns • true - The StartOfFrames feature is supported on the device • false - The StartOfFrames feature is not supported on the device Remarks None. 5.6.26.6.17.50 PLIB_USB_ExistsStopInIdle Function C bool PLIB_USB_ExistsStopInIdle( USB_MODULE_ID index ); Description This function identifies whether the StopInIdle feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_StopInIdleEnable • PLIB_USB_StopInIdleDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The StopInIdle feature is supported on the device • false - The StopInIdle feature is not supported on the device Remarks None. 5.6.26.6.17.51 PLIB_USB_ExistsSuspend Function C bool PLIB_USB_ExistsSuspend( USB_MODULE_ID index ); Description This function identifies whether the Suspend feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_SuspendEnable • PLIB_USB_SuspendDisable Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3310 Parameters Parameters Description index Identifier for the device instance Returns • true - The Suspend feature is supported on the device • false - The Suspend feature is not supported on the device Remarks None. 5.6.26.6.17.52 PLIB_USB_ExistsTokenEP Function C bool PLIB_USB_ExistsTokenEP( USB_MODULE_ID index ); Description This function identifies whether the TokenEP feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TokenEPGet • PLIB_USB_TokenEPSet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TokenEP feature is supported on the device • false - The TokenEP feature is not supported on the device Remarks None. 5.6.26.6.17.53 PLIB_USB_ExistsTokenPID Function C bool PLIB_USB_ExistsTokenPID( USB_MODULE_ID index ); Description This function identifies whether the TokenPID feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_TokenPIDGet • PLIB_USB_TokenPIDSet 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3311 Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TokenPID feature is supported on the device • false - The TokenPID feature is not supported on the device Remarks None. 5.6.26.6.17.54 PLIB_USB_ExistsUOEMonitor Function C bool PLIB_USB_ExistsUOEMonitor( USB_MODULE_ID index ); Description This function identifies whether the UOEMonitor feature is available on the USB module. When this function returns true, these functions are supported on the device: • PLIB_USB_UOEMonitorEnable • PLIB_USB_UOEMonitorDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The UOEMonitor feature is supported on the device • false - The UOEMonitor feature is not supported on the device Remarks None. 5.6.26.7 Files Files Name Description plib_usb.h USB PLIB Interface Header for common definitions Description 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3312 5.6.26.7.1 plib_usb.h USB Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB Peripheral Library. Enumerations Name Description USB_BUFFER_DATA01 Provides enumeration data toggle for a buffer. USB_BUFFER_DIRECTION Provides enumeration transmit/receive direction for a buffer. USB_BUFFER_PING_PONG Enumerates the ping-pong buffer (Even vs. Odd). USB_BUFFER_SCHEDULE_DATA01 Provides enumeration data toggle for a buffer. USB_EP_TXRX Provides enumeration transmit/receive setup for an endpoint. USB_OPMODES Provides enumeration of operating modes supported by USB. USB_OTG_INTERRUPTS Provides enumeration of interrupts related to the USB On-The-Go (OTG) module. USB_OTG_PULL_UP_PULL_DOWN USB OTG pull-Up and pull-Down resistors for D+ and D- . USB_PID Legal PID values. USB_PING_PONG_MODE Supports the four modes of ping-pong buffering for PIC18 and PIC24F devices. USB_PING_PONG_STATE Decodes which buffer (Even vs. Odd) was used for the last transaction. USB_TOKEN_SPEED Provides enumeration of available token speeds. Functions Name Description PLIB_USB_ActivityPending Returns whether or not USB activity is pending. PLIB_USB_AllInterruptEnable Configures the USB peripheral general interrupts, error interrupts and OTG interrupts. PLIB_USB_AutoSuspendDisable Disables USB OTG Auto-suspend mode. PLIB_USB_AutoSuspendEnable Enables USB Auto-suspend mode. PLIB_USB_BDTBaseAddressGet Returns the base address of the Buffer Descriptor Table. PLIB_USB_BDTBaseAddressSet Sets the base address for the Buffer Descriptor Table for PIC24 and PIC32 devices. PLIB_USB_BufferAddressGet Gets the memory address of an endpoint buffer. PLIB_USB_BufferAddressSet Sets the endpoint buffer address. PLIB_USB_BufferAllCancelReleaseToUSB Cancels all endpoint buffer releases to the USB module and hands over the buffer to the CPU. PLIB_USB_BufferByteCountGet Returns the endpoint buffer byte count. PLIB_USB_BufferByteCountSet Sets the buffer byte count. PLIB_USB_BufferCancelReleaseToUSB Cancels release of the endpoint buffer by software, allowing software to again access the buffer. PLIB_USB_BufferClearAll Clears (zeros out) entries in the Buffer Descriptor Table. PLIB_USB_BufferClearAllDTSEnable Clears the endpoint descriptor entry and enables data toggle synchronization. PLIB_USB_BufferDataToggleGet Returns data synchronization (DATA0 or DATA1) for the endpoint buffer. PLIB_USB_BufferDataToggleSelect Sets the endpoint buffer to DATA0 or DATA1. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3313 PLIB_USB_BufferDataToggleSyncDisable Disables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferDataToggleSyncEnable Enables DATA0/DATA1 synchronization between the device and host. PLIB_USB_BufferEP0RxStatusInitialize Initializes the Endpoint 0 RX endpoint buffer descriptors. PLIB_USB_BufferIndexGet Gets the Buffer Descriptor Table index for a buffer. PLIB_USB_BufferPIDBitsClear Clears the Buffer Status bits in the Buffer Descriptor Table. PLIB_USB_BufferPIDGet Returns the token packet ID (PID) from the endpoint buffer status. PLIB_USB_BufferReleasedToSW Returns the boolean flag value of 'true' when the buffer has been released by the USB module. PLIB_USB_BufferReleaseToUSB Releases the endpoint buffer by software, allowing the USB module access to the buffer. PLIB_USB_BufferSchedule Hands over a buffer to the USB module along with the buffer address and byte count. PLIB_USB_BufferStallDisable Disables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallEnable Enables STALL handshaking for the associated endpoint buffer. PLIB_USB_BufferStallGet Returns the buffer stall status for an endpoint/direction/ping-pong. PLIB_USB_DeviceAddressGet Returns the address of the USB module in Device mode. PLIB_USB_DeviceAddressSet Sets the USB Device's address. PLIB_USB_Disable Disables (powers down) the USB module. PLIB_USB_Enable Enables (powers up) the USB module. PLIB_USB_EP0HostSetup Sends token to the specified address. PLIB_USB_EP0LSDirectConnectDisable Disables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0LSDirectConnectEnable Enables direct connection to a low-speed device for Endpoint 0. PLIB_USB_EP0NakRetryDisable Disables retrying of NAKed transactions. PLIB_USB_EP0NakRetryEnable Enables retrying NAK'd transactions for Endpoint 0. PLIB_USB_EPnAttributesClear Clears the set attributes of the specified endpoint. PLIB_USB_EPnAttributesSet Configures attributes of the endpoint such as direction, handshake capability and direction. PLIB_USB_EPnControlTransferDisable Disables endpoint control transfers. PLIB_USB_EPnControlTransferEnable Enables endpoint control transfers. PLIB_USB_EPnDirectionDisable Disables the specified endpoint direction. PLIB_USB_EPnHandshakeDisable Disables endpoint handshaking. PLIB_USB_EPnHandshakeEnable Enables endpoint handshaking. PLIB_USB_EPnIsStalled Tests whether the endpoint epValue is stalled. PLIB_USB_EPnRxDisable Disables an endpoint's abililty to process IN tokens. PLIB_USB_EPnRxEnable Enables an endpoint to process IN tokens. PLIB_USB_EPnRxSelect Selects receive capabilities of an endpoint. PLIB_USB_EPnStallClear Clears an endpoint's stalled flag. PLIB_USB_EPnTxDisable Disables an endpoint's ability to process OUT tokens. PLIB_USB_EPnTxEnable Enables an endpoint to process OUT tokens. PLIB_USB_EPnTxRxSelect Selects transmit and/or receive capabilities of an endpoint. PLIB_USB_EPnTxSelect Selects transmit capabilities of an endpoint. PLIB_USB_ErrorInterruptDisable Disables an error interrupt for the USB module. PLIB_USB_ErrorInterruptEnable Enables an error interrupt for the USB module. PLIB_USB_ErrorInterruptFlagAllGet Returns a logically ORed bit map of active error interrupt flags. PLIB_USB_ErrorInterruptFlagClear Clears an error interrupt flag for the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3314 PLIB_USB_ErrorInterruptFlagGet Tests an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptFlagSet Sets an error interrupt flag for the USB module. PLIB_USB_ErrorInterruptIsEnabled Returns true if interrupts are enabled. PLIB_USB_ExistsActivityPending Identifies whether the ActivityPending feature exists on the USB module. PLIB_USB_ExistsALL_Interrupt Identifies whether the ALL_Interrupt feature exists on the USB module. PLIB_USB_ExistsAutomaticSuspend Identifies whether the AutomaticSuspend feature exists on the USB module. PLIB_USB_ExistsBDTBaseAddress Identifies whether the BDTBaseAddress feature exists on the USB module. PLIB_USB_ExistsBDTFunctions Identifies whether the BDTFunctions feature exists on the USB module. PLIB_USB_ExistsBufferFreeze Identifies whether the BufferFreeze feature exists on the USB module. PLIB_USB_ExistsDeviceAddress Identifies whether the DeviceAddress feature exists on the USB module. PLIB_USB_ExistsEP0LowSpeedConnect Identifies whether the EP0LowSpeedConnect feature exists on the USB module. PLIB_USB_ExistsEP0NAKRetry Identifies whether the EP0NAKRetry feature exists on the USB module. PLIB_USB_ExistsEPnRxEnable Identifies whether the EPnRxEnableEnhanced feature exists on the USB module. PLIB_USB_ExistsEPnTxRx Identifies whether the EPnTxRx feature exists on the USB module. PLIB_USB_ExistsERR_Interrupt Identifies whether the ERR_Interrupt feature exists on the USB module. PLIB_USB_ExistsERR_InterruptStatus Identifies whether the ERR_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsEyePattern Identifies whether the EyePattern feature exists on the USB module. PLIB_USB_ExistsFrameNumber Identifies whether the FrameNumber feature exists on the USB module. PLIB_USB_ExistsGEN_Interrupt Identifies whether the GEN_Interrupt feature exists on the USB module. PLIB_USB_ExistsGEN_InterruptStatus Identifies whether the GEN_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsHostBusyWithToken Identifies whether the HostBusyWithToken feature exists on the USB module. PLIB_USB_ExistsHostGeneratesReset Identifies whether the HostGeneratesReset feature exists on the USB module. PLIB_USB_ExistsLastDirection Identifies whether the LastDirection feature exists on the USB module. PLIB_USB_ExistsLastEndpoint Identifies whether the LastEndpoint feature exists on the USB module. PLIB_USB_ExistsLastPingPong Identifies whether the LastPingPong feature exists on the USB module. PLIB_USB_ExistsLastTransactionDetails Identifies whether the LastTransactionDetails feature exists on the USB module. PLIB_USB_ExistsLiveJState Identifies whether the LiveJState feature exists on the USB module. PLIB_USB_ExistsLiveSingleEndedZero Identifies whether the LiveSingleEndedZero feature exists on the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3315 PLIB_USB_ExistsModuleBusy Identifies whether the ModuleBusy feature exists on the USB module. PLIB_USB_ExistsModulePower Identifies whether the ModulePower feature exists on the USB module. PLIB_USB_ExistsNextTokenSpeed Identifies whether the NextTokenSpeed feature exists on the USB module. PLIB_USB_ExistsOnChipPullup Identifies whether the OnChipPullup feature exists on the USB module. PLIB_USB_ExistsOnChipTransceiver Identifies whether the OnChipTransceiver feature exists on the USB module. PLIB_USB_ExistsOpModeSelect Identifies whether the OpModeSelect feature exists on the USB module. PLIB_USB_ExistsOTG_ASessionValid Identifies whether the OTG_ASessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_BSessionEnd Identifies whether the OTG_BSessionEnd feature exists on the USB module. PLIB_USB_ExistsOTG_IDPinState Identifies whether the OTG_IDPinState feature exists on the USB module. PLIB_USB_ExistsOTG_Interrupt Identifies whether the OTG_Interrupt feature exists on the USB module. PLIB_USB_ExistsOTG_InterruptStatus Identifies whether the OTG_InterruptStatus feature exists on the USB module. PLIB_USB_ExistsOTG_LineState Identifies whether the OTG_LineState feature exists on the USB module. PLIB_USB_ExistsOTG_PullUpPullDown Identifies whether the OTG_PullUpPullDown feature exists on the USB module. PLIB_USB_ExistsOTG_SessionValid Identifies whether the OTG_SessionValid feature exists on the USB module. PLIB_USB_ExistsOTG_VbusCharge Identifies whether the OTG_VbusCharge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusDischarge Identifies whether the OTG_VbusDischarge feature exists on the USB module. PLIB_USB_ExistsOTG_VbusPowerOnOff Identifies whether the OTG_VbusPowerOnOff feature exists on the USB module. PLIB_USB_ExistsPacketTransfer Identifies whether the PacketTransfer feature exists on the USB module. PLIB_USB_ExistsPingPongMode Identifies whether the PingPongMode feature exists on the USB module. PLIB_USB_ExistsResumeSignaling Identifies whether the ResumeSignaling feature exists on the USB module. PLIB_USB_ExistsSleepEntryGuard Identifies whether the SleepEntryGuard feature exists on the USB module. PLIB_USB_ExistsSOFThreshold Identifies whether the SOFThreshold feature exists on the USB module. PLIB_USB_ExistsSpeedControl Identifies whether the SpeedControl feature exists on the USB module. PLIB_USB_ExistsStartOfFrames Identifies whether the StartOfFrames feature exists on the USB module. PLIB_USB_ExistsStopInIdle Identifies whether the StopInIdle feature exists on the USB module. PLIB_USB_ExistsSuspend Identifies whether the Suspend feature exists on the USB module. PLIB_USB_ExistsTokenEP Identifies whether the TokenEP feature exists on the USB module. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3316 PLIB_USB_ExistsTokenPID Identifies whether the TokenPID feature exists on the USB module. PLIB_USB_ExistsUOEMonitor Identifies whether the UOEMonitor feature exists on the USB module. PLIB_USB_ExternalComparatorMode2Pin Sets the 2-pin input configuration for VBUS comparators. PLIB_USB_ExternalComparatorMode3Pin Sets the 3-pin input configuration for VBUS Comparators. PLIB_USB_EyePatternDisable Disables the USB eye pattern test. PLIB_USB_EyePatternEnable Enables USB eye pattern test. PLIB_USB_FrameNumberGet Returns the USB frame number. PLIB_USB_FullSpeedDisable Forces the USB module to operate at low speed. PLIB_USB_FullSpeedEnable Enables the USB to operate at full speed. PLIB_USB_I2CInterfaceForExtModuleDisable Specifies external module(s) are controlled via dedicated pins. PLIB_USB_I2CInterfaceForExtModuleEnable Specifies external module(s) are controlled via the I2C interface. PLIB_USB_InterruptDisable Disables a general interrupt for the USB module. PLIB_USB_InterruptEnable Enables a general interrupt for the USB module. PLIB_USB_InterruptEnableGet Returns the enable/disable status of general USB module interrupts PLIB_USB_InterruptFlagAllGet Returns a logically ORed bit map of active general USB interrupt flags. PLIB_USB_InterruptFlagClear Clears a general interrupt flag for the USB module. PLIB_USB_InterruptFlagGet Tests a general interrupt flag for the USB module. PLIB_USB_InterruptFlagSet Sets a general interrupt flag for the USB module. PLIB_USB_InterruptIsEnabled Returns true if interrupts are enabled. PLIB_USB_IsBusyWithToken Indicates whether there is a token being executed by the USB module as Host. PLIB_USB_JStateIsActive Live differential receiver J State flag. PLIB_USB_LastTransactionDetailsGet Returns the details of the last completed transaction. PLIB_USB_LastTransactionDirectionGet Indicates the direction of the last transaction. PLIB_USB_LastTransactionEndPtGet Returns the endpoint number of the last USB transfer. PLIB_USB_LastTransactionPingPongStateGet Indicates whether the last transaction was to an EVEN buffer or an ODD buffer. PLIB_USB_ModuleIsBusy Indicates if the USB module is not ready to be enabled. PLIB_USB_OnChipPullUpDisable Disables on-chip pull-ups. PLIB_USB_OnChipPullUpEnable Enables on-chip pull-ups. PLIB_USB_OperatingModeSelect Selects the operating mode of the USB module. PLIB_USB_OTG_BSessionHasEnded Returns the status of the B-Session End Indicator bit. PLIB_USB_OTG_IDPinStateIsTypeA Returns the ID Pin state. PLIB_USB_OTG_InterruptDisable Disables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptEnable Enables a USB On-The-Go (OTG) Interrupt for the USB module. PLIB_USB_OTG_InterruptFlagClear Clears a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagGet Tests a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptFlagSet Sets a USB On-The-Go (OTG) Interrupt flag for the USB module. PLIB_USB_OTG_InterruptIsEnabled Returns whether or not interrupts are enabled. PLIB_USB_OTG_LineStateIsStable Returns the status of the Line Stable Indicator bit. PLIB_USB_OTG_PullUpPullDownSetup Enables or disables pull-up and pull-down resistors. PLIB_USB_OTG_SessionValid Returns the status of the Session Valid Indicator bit. PLIB_USB_OTG_VBusChargeDisable Disables VBUS line charge. PLIB_USB_OTG_VBusChargeEnable Enables the VBUS line to be charged through a pull-up resistor. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3317 PLIB_USB_OTG_VBusChargeTo3V Sets the VBUS line to charge to 3.3V. PLIB_USB_OTG_VBusChargeTo5V Sets the VBUS line to charge to 5V. PLIB_USB_OTG_VBusDischargeDisable Disables VBUS line discharge. PLIB_USB_OTG_VBusDischargeEnable Enables VBUS line to be discharged through a resistor. PLIB_USB_OTG_VBusPowerOff Turns off power on the VBUS Line. PLIB_USB_OTG_VBusPowerOn Turns on power for the VBUS line. PLIB_USB_OTG_VBusValid Returns the status of the A-VBUS valid indicator. PLIB_USB_PacketTransferDisable Disables the Serial Interface Engine (SIE). PLIB_USB_PacketTransferEnable Re-enables the Serial Interface Engine (SIE), allowing token and packet processing. PLIB_USB_PacketTransferIsDisabled Indicates that a setup token has been received from the Host and that token/packet processing is disabled. PLIB_USB_PingPongFreeze Resets all Ping-Pong buffer pointers to even buffers. PLIB_USB_PingPongModeGet Returns the Ping-Pong Configuration setting. PLIB_USB_PingPongModeSelect Selects the Ping-Pong Configuration setting. PLIB_USB_PingPongReset Resets the USB peripheral internal Ping-Pong indicator to point to even buffers. PLIB_USB_PingPongUnfreeze Enables Ping-Pong buffering. PLIB_USB_PWMCounterDisable Disables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMCounterEnable Enables the PWM counter used to generate the VBUS for the USB module. PLIB_USB_PWMDisable Disables the PWM Generator. PLIB_USB_PWMEnable Enables the PWM Generator. PLIB_USB_PWMPolaritiyActiveLow Sets the PWM output to active-high and resets low. PLIB_USB_PWMPolarityActiveHigh Sets the PWM output to active-low and resets high. PLIB_USB_ResetSignalDisable Disables reset signalling on the USB bus. PLIB_USB_ResetSignalEnable Enables reset signalling on the USB bus. PLIB_USB_ResumeSignalingDisable Disables resume signaling. PLIB_USB_ResumeSignalingEnable Enables resume signaling. PLIB_USB_SE0InProgress Returns whether a single-ended zero event is in progress. PLIB_USB_SleepGuardDisable This function disables Sleep Guard. Entry into Sleep mode is immediate. PLIB_USB_SleepGuardEnable Entry into Sleep mode is blocked if bus activity is detected or if an interrupt is pending. PLIB_USB_SOFDisable Disables the automatic generation of the SOF token. PLIB_USB_SOFEnable Enables the automatic generation of the SOF token every 1 ms. PLIB_USB_SOFThresholdGet Returns the Start-of-Frame (SOF) Count bits. PLIB_USB_SOFThresholdSet Sets the Start-of-Frame (SOF) threshold value. PLIB_USB_StopInIdleDisable Allows the USB module to continue operation when the device enters Idle mode. PLIB_USB_StopInIdleEnable Enables USB module operation to stop when the device enters Idle mode. PLIB_USB_SuspendDisable Disables USB OTG Suspend mode. PLIB_USB_SuspendEnable Enables USB Suspend mode. PLIB_USB_TokenEPGet Returns the specified Endpoint address. PLIB_USB_TokenEPSet Sets the Endpoint address for a host transaction. 5.6 Peripheral Library Help MPLAB Harmony Help USB Peripheral Library 5-3318 PLIB_USB_TokenPIDGet Returns the token transaction type. PLIB_USB_TokenPIDSet Sets the token transaction type to pidValue. PLIB_USB_TokenSend Sends token to the specified address. PLIB_USB_TokenSpeedSelect Selects low speed or full speed for subsequent token executions. PLIB_USB_TransceiverDisable Disables the on-chip transceiver PLIB_USB_TransceiverEnable Enables the on-chip transceiver. PLIB_USB_UOEMonitorDisable Disables the OE signal output. PLIB_USB_UOEMonitorEnable Enables the OE signal output. PLIB_USB_VBoostDisable Disables the On-Chip 5V Boost Regulator Circuit Disabled bit. PLIB_USB_VBoostEnable Enables the On-Chip 5V Boost Regulator Circuit Enabled bit. PLIB_USB_VBUSComparatorDisable Disables the on-chip VBUS Comparator. PLIB_USB_VBUSComparatorEnable Enables the on-chip VBUS Comparator. PLIB_USB_VBUSPullUpDisable Disables the pull-up on the VBUS pin. PLIB_USB_VBUSPullUpEnable Enables the pull-up on the VBUS pin. Macros Name Description USB_MAX_EP_NUMBER Maximum number of endpoints supported (not including EP0). File Name plib_usb.h Company Microchip Technology Inc. 5.6.27 Watchdog Timer Peripheral Library 5.6.27.1 Introduction Watchdog Timer (WDT) Peripheral Library for Microchip Microcontrollers This library provides a low-level abstraction of the WDT Peripheral Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3319 Description The primary function of the Watchdog Timer (WDT) is to reset the microcontroller, in the event of a software malfunction, by resetting the device if it has not been cleared by software. To ensure that application doesn't hang, the application is supposed to reset the timer periodically. It can also be used to wake the device from Sleep or Idle mode. The WDT is a free-running timer, which uses the Low-Power RC (LPRC) Oscillator and requires no external components. Therefore, the WDT will continue to operate even if the system’s primary clock source is stopped. 5.6.27.2 Release Notes MPLAB Harmony Version: v0.70b Watchdog Timer Peripheral Library Version : 0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.6.27.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3320 5.6.27.4 How the Library Works This section describes how the WDT Peripheral Library works. Description Initializing the WDT module involves these processes. • Selecting the postscaler • Enabling the WDT using PLIB_WDT_Enable • Selecting the window size if the application wants the WDT in Windowed mode using PLIB_WDT_WindowEnable Note: Selecting the postscaler and window size should be done through the Configuration bits The application should periodically clear the timer once it is enabled; otherwise, a time-out will lead to a device Reset. Use PLIB_WDT_TimerClear to clear the WDT. A timer clear before a time-out may also lead to a reset in Windowed mode. The user application can clear the window only in the allowed window. Refer to the specific device data sheet to determine the allowed window period for your device. Example /************************************************************** * This code fragment assumes the WDT is not enabled through * * device configuration bits. The Postscaler value must be set * * through the device configuration and window size should be * * set if applicable * **************************************************/ /* Initializing the watchdog involves */ PLIB_WDT_Enable(WDT_ID_0); //Application loop while(1) { PLIB_WDT_TimerClear(WDT_ID_0); //user code } Note: Refer to the specific device data sheet for information on the allowed window periods for your device and other Configuration bit settings. 5.6.27.4.1 Using the Library This topic describes the basic architecture of the WDT Peripheral Library and provides information and examples on how to use it. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3321 Interface Header File: plib_wdt.h The interface to the WDT Peripheral Library is defined in the "plib_wdt.h" header file. Any C language source (.c) file that uses the WDT Peripheral Library should include "peripheral.h". Library File: The WDT Peripheral Library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.6.27.4.1.1 Hardware Abstraction Model This library provides the low-level abstraction of the Watchdog timer module on the Microchip family of microcontrollers with a convenient C language interface. This topic describes how that abstraction is modeled in the software and introduces the library interface. Note: The interface provided is a superset of all of the functionality of the available Watchdog Timer modules on the device. Refer to the specific device data sheet or related family reference manual section to determine the set of functions that are supported for each Watchdog Timer module on your device. Description Watchdog Timer Software Abstraction Block Diagram The WDT uses the internal Low-Power RC (LPRC) Oscillator as the clock source. The clock is divided by the configured prescaler value. There may be one more postscaler divisors. The divided clock is then used to increment a counter. The WDT module uses the watchdog register as a timer. If there is no reset signal from the software and if the counter overflows, this results in a reset in normal mode. In the case of Sleep or Idle mode, the overflow will result in a device wake-up. For Windowed mode, resetting the counter when the count is not in the specified window will also lead to a reset. If the device is in Sleep or Idle mode, the reset signal will be used to wake-up the device. 5.6.27.4.1.2 Library Overview Library Interface Section Description General Configuration Functions This includes module enable, module disable, watchdog timer window enable, watchdog timer window disable and the timer reset routines. General Status Functions Status routines for the WDT. 5.6.27.5 Configuring the Library The library is configured for the supported processor when the processor is chosen in the MPLAB IDE. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3322 5.6.27.6 Library Interface Data Types and Constants Name Description WDT_MODULE_ID Identifies the supported WDT modules. Feature Existence Functions Name Description PLIB_WDT_ExistsEnableControl Identifies whether the EnableControl feature exists on the WDT module. PLIB_WDT_ExistsPostscalarValue Identifies whether the PostscalarValue feature exists on the WDT module. PLIB_WDT_ExistsTimerClear Identifies whether the TimerClear feature exists on the WDT module. PLIB_WDT_ExistsWindowEnable Identifies whether the WindowEnable feature exists on the WDT module. General Configuration Functions Name Description PLIB_WDT_Disable Disables the WDT module. PLIB_WDT_Enable Enables the WDT module. PLIB_WDT_WindowDisable Disables the WDT Windowed mode. PLIB_WDT_WindowEnable Enables the WDT Window mode. PLIB_WDT_TimerClear Resets the WDT module. General Status Functions Name Description PLIB_WDT_IsEnabled Returns the watchdog timer on/off(enable/disable) status. PLIB_WDT_PostscalarValueGet Returns the WDT postscalar value. Description This section describes the functions, data types, and constants available in the WDT Peripheral Library. 5.6.27.6.1 General Configuration Functions 5.6.27.6.1.1 PLIB_WDT_Disable Function C void PLIB_WDT_Disable( WDT_MODULE_ID index ); Description This function disables the WDT module if it is enabled in software. Preconditions The WDT module must be enabled through software. Parameters Parameters Description index Identifies the desired WDT module 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3323 Returns None. Remarks This function will not disable the WDT module if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Example PLIB_WDT_Disable ( WDT_ID_0 ); 5.6.27.6.1.2 PLIB_WDT_Enable Function C void PLIB_WDT_Enable( WDT_MODULE_ID index ); Description This function enables the WDT module. If it is already enabled through the Configuration bits, it will keep it enabled. Preconditions None. Parameters Parameters Description index Identifies the desired WDT module Returns None. Remarks Calling this function is not necessary if it is enabled through its Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Example PLIB_WDT_Enable ( WDT_ID_0 ); 5.6.27.6.1.3 PLIB_WDT_WindowDisable Function C void PLIB_WDT_WindowDisable( WDT_MODULE_ID index ); Description This function disables the WDT Windowed mode. Preconditions None. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3324 Parameters Parameters Description index Identifies the desired WDT module Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsWindowEnable in your application to determine whether this feature is available. Example PLIB_WDT_WindowDisable ( WDT_ID_0 ); 5.6.27.6.1.4 PLIB_WDT_WindowEnable Function C void PLIB_WDT_WindowEnable( WDT_MODULE_ID index ); Description This function enables the WDT Windowed mode. Preconditions The window size must be set through the Configuration bits. Parameters Parameters Description index Identifies the desired WDT module Returns None. Remarks The window size must be set through the Configuration bits. The example code doesn't include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsWindowEnable in your application to determine whether this feature is available. Example PLIB_WDT_WindowEnable ( WDT_ID_0 ); PLIB_WDT_Enable ( WDT_ID_0 ); 5.6.27.6.1.5 PLIB_WDT_TimerClear Function C void PLIB_WDT_TimerClear( WDT_MODULE_ID index ); Description This function resets the WDT module. The WDT module should be cleared periodically before the count crosses and forces the 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3325 device to reset. Preconditions None. Parameters Parameters Description index Identifies the desired WDT module Returns None. Remarks Resetting the device before the count reaches the window will cause a reset in Windowed mode. The example code doesn't include the settings that should be done through the Configuration bits. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsTimerClear in your application to determine whether this feature is available. Example PLIB_WDT_Enable ( WDT_ID_0 ); //Application loop while(1) { PLIB_WDT_TimerClear ( WDT_ID_0 ); //user code } 5.6.27.6.2 General Status Functions 5.6.27.6.2.1 PLIB_WDT_IsEnabled Function C bool PLIB_WDT_IsEnabled( WDT_MODULE_ID index ); Description Returns the 'true', if the watchdog timer is already ON. Otherwise returns 'false'. Preconditions None. Parameters Parameters Description index Identifies the desired WDT module Returns true - If the watchdog timer is on false - If the watchdog timer is off Remarks This function returns 'true' if the device is enabled either though the Configuration bits or in the software. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3326 PLIB_WDT_ExistsEnableControl in your application to determine whether this feature is available. Example if (PLIB_WDT_IsEnabled ( WDT_ID_0 ) ) { //Do some action } 5.6.27.6.2.2 PLIB_WDT_PostscalarValueGet Function C char PLIB_WDT_PostscalarValueGet( WDT_MODULE_ID index ); Description This function returns the WDT postscalar value. The value will correspond to a division factor. Preconditions None. Parameters Parameters Description index Identifies the desired WDT module Returns The postscalar value. Remarks The value returned will be right-aligned. Refer the datasheet of the specific device to get the division factor corresponding to the value. This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use PLIB_WDT_ExistsPostscalarValue in your application to determine whether this feature is available. Example uint8_t value; PLIB_WDT_Enable ( WDT_ID_0 ); value = PLIB_WDT_PostscalarValueGet ( WDT_ID_0 ); 5.6.27.6.3 Data Types and Constants 5.6.27.6.3.1 WDT_MODULE_ID Enumeration C typedef enum { WDT_ID, WDT_NUMBER_OF_MODULES } WDT_MODULE_ID; Description WDT Module ID This enumeration identifies the available WDT modules. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3327 Members Members Description WDT_ID WDT Module 1 ID WDT_NUMBER_OF_MODULES Number of available WDT modules. Remarks The caller should not rely on the specific numbers assigned to any of these values as they may change from one processor to the next. 5.6.27.6.4 Feature Existence Functions 5.6.27.6.4.1 PLIB_WDT_ExistsEnableControl Function C bool PLIB_WDT_ExistsEnableControl( WDT_MODULE_ID index ); Description This function identifies whether the EnableControl feature is available on the WDT module. When this function returns true, these functions are supported on the device: • PLIB_WDT_Enable • PLIB_WDT_Disable • PLIB_WDT_IsEnabled Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns Existence of the EnableControl feature: • true - When EnableControl feature is supported on the device • false - When EnableControl feature is not supported on the device Remarks None. 5.6.27.6.4.2 PLIB_WDT_ExistsPostscalarValue Function C bool PLIB_WDT_ExistsPostscalarValue( WDT_MODULE_ID index ); Description This function identifies whether the PostscalarValue feature is available on the WDT module. When this function returns true, this 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3328 function is supported on the device: • PLIB_WDT_PostscalarValueGet Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The PostscalarValue feature is supported on the device • false - The PostscalarValue feature is not supported on the device Remarks None. 5.6.27.6.4.3 PLIB_WDT_ExistsTimerClear Function C bool PLIB_WDT_ExistsTimerClear( WDT_MODULE_ID index ); Description This function identifies whether the TimerClear feature is available on the WDT module. When this function returns true, this function is supported on the device: • PLIB_WDT_TimerClear Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The TimerClear feature is supported on the device • false - The TimerClear feature is not supported on the device Remarks None. 5.6.27.6.4.4 PLIB_WDT_ExistsWindowEnable Function C bool PLIB_WDT_ExistsWindowEnable( WDT_MODULE_ID index ); Description This function identifies whether the WindowEnable feature is available on the WDT module. When this function returns true, these functions are supported on the device: 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3329 • PLIB_WDT_WindowEnable • PLIB_WDT_WindowDisable Preconditions None. Parameters Parameters Description index Identifier for the device instance Returns • true - The WindowEnable feature is supported on the device • false - The WindowEnable feature is not supported on the device Remarks None. 5.6.27.7 Files Files Name Description plib_wdt.h Watchdog Timer (WDT) Peripheral Library interface header for Watchdog Timer common definitions. Description 5.6.27.7.1 plib_wdt.h WDT Peripheral Library Interface Header This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Watchdog Timer Peripheral Library for all families of Microchip microcontrollers. The definitions in this file are common to the Watchdog Timer peripheral. Functions Name Description PLIB_WDT_Disable Disables the WDT module. PLIB_WDT_Enable Enables the WDT module. PLIB_WDT_ExistsEnableControl Identifies whether the EnableControl feature exists on the WDT module. PLIB_WDT_ExistsPostscalarValue Identifies whether the PostscalarValue feature exists on the WDT module. PLIB_WDT_ExistsTimerClear Identifies whether the TimerClear feature exists on the WDT module. PLIB_WDT_ExistsWindowEnable Identifies whether the WindowEnable feature exists on the WDT module. PLIB_WDT_IsEnabled Returns the watchdog timer on/off(enable/disable) status. PLIB_WDT_PostscalarValueGet Returns the WDT postscalar value. PLIB_WDT_TimerClear Resets the WDT module. PLIB_WDT_WindowDisable Disables the WDT Windowed mode. PLIB_WDT_WindowEnable Enables the WDT Window mode. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3330 File Name plib_wdt.h Company Microchip Technology Inc. 5.6 Peripheral Library Help MPLAB Harmony Help Watchdog Timer Peripheral Library 5-3331 5.7 System Service Library Help 5.7.1 System Service Overview System services provide common functionality that would otherwise need to be duplicated or would force other drivers and libraries to interact in complex and difficult to manage ways. System services have two primary types of implementations: • System Service Libraries • Low-Level Support Most system service libraries follow the same basic model as a device driver (directly using a peripheral library to access hardware) or a middleware library (using a device driver to access hardware) as the rest of the system. Some low-level support libraries provide common (cross-micro/cross-board) interfaces, but require system-specific implementation as part of a Board Support Package (BSP) or application configuration (for example, the low-level "raw" interrupt support necessary for interrupt-driven configurations). 5.7.1.1 Library Interface Data Types and Constants Name Description _SYS_TASKS_PRIORITIES Defines system tasks priorities. MAIN_RETURN_CODES Predefined list of return codes for "main". SYS_MODULE_DATA Contains module-interface info used to define a table of system modules SYS_MODULE_DEINITIALIZE_ROUTINE Pointer to a routine that de-initializes a system module (driver, library, or system-maintained application) SYS_MODULE_INDEX Identifies which instance of a system module should be initialized or opened. SYS_MODULE_INIT Initializes a module (including device drivers) in a current power status as requested by the system or power manager. SYS_MODULE_INITIALIZE_ROUTINE Pointer to a routine that initializes a system module (driver, library, or system-maintained application). SYS_MODULE_INTERFACE Structure contains pointers to module-interface routines for a single system module. SYS_MODULE_OBJ Handle to an instance of a system module. SYS_MODULE_REINITIALIZE_ROUTINE Pointer to a routine that reinitializes a system module (driver, library, or system-maintained application) SYS_MODULE_STATUS_ROUTINE Pointer to a routine that gets the current status of a system module (driver, library, or system-maintained application). SYS_MODULE_TASKS_DATA Structure contains pointers to module's tasks routine. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3332 SYS_MODULE_TASKS_ROUTINE Pointer to a routine that performs the tasks necessary to maintain a state machine in a module system module (driver, library, or system-maintained application). SYS_STATUS Identifies the current status/state of a system module (including device drivers). SYS_TASKS_PRIORITY Defines system tasks priorities. MAIN_RETURN Defines the correct return type for the "main" routine. MAIN_RETURN_CODE Provides the correct value for the return code from "main". SYS_MODULE_OBJ_INVALID Object handle value returned if unable to initialize the requested instance of a system module. SYS_MODULE_OBJ_STATIC Object handle value returned by static modules. SYS_MODULE_POWER_IDLE_RUN Module power-state idle-run state code. SYS_MODULE_POWER_IDLE_STOP Module power-state idle-stop state code. SYS_MODULE_POWER_OFF Module power-state power off state code. SYS_MODULE_POWER_RUN_FULL Module power-state run-full state code. SYS_MODULE_POWER_SLEEP Module power-state sleep state code. System Functions Name Description SYS_Tasks Function that performs all polled system tasks. Description 5.7.1.1.1 System Functions 5.7.1.1.1.1 SYS_Tasks Function C void SYS_Tasks(); Description System Tasks Function This function performs all polled system tasks by calling the state machine "tasks" functions for all polled modules in the system, including drivers, services, middleware and applications. Preconditions The SYS_Initialize function must have been called and completed. Returns None. Remarks If the module is interrupt driven, the system will call this routine from an interrupt context. Example SYS_Initialize ( NULL ); while ( true ) { SYS_Tasks ( ); 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3333 } 5.7.1.1.2 Data Types and Constants 5.7.1.1.2.1 MAIN_RETURN_CODES Enumeration C typedef enum { MAIN_RETURN_FAILURE = -1, MAIN_RETURN_SUCCESS = 0 } MAIN_RETURN_CODES; Description Main Routine Codes This enumeration provides a predefined list of return codes for "main". Remarks These codes can be passed into the MAIN_RETURN_CODE macro to convert them to the appropriate type (or discard them if not needed) for the Microchip microcontroller in use. Example MAIN_RETURN main ( void ) { // Initialize the system SYS_Initialize(...); // Main Loop while(true) { SYS_Tasks(); } return MAIN_RETURN_CODE(MAIN_RETURN_SUCCESS); } 5.7.1.1.2.2 SYS_MODULE_DATA Structure C typedef struct { SYS_MODULE_INTERFACE interface; SYS_MODULE_OBJ object; SYS_TASKS_PRIORITY priority; unsigned int count; } SYS_MODULE_DATA; Description System Module Data This structure contains module-interface info used to define a table of system modules. Members Members Description SYS_MODULE_INTERFACE interface; Module interface (function pointers, index, etc) SYS_MODULE_OBJ object; Object handle obtained from initialization call SYS_TASKS_PRIORITY priority; Requested module priority (identifies "Tasks" interval) unsigned int count; Number of intervals (of the module priority) before calling this module's "Tasks" routine. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3334 Remarks Used internally by the system services. Not to be accessed by user code. 5.7.1.1.2.3 SYS_MODULE_DEINITIALIZE_ROUTINE Type C typedef void (* SYS_MODULE_DEINITIALIZE_ROUTINE)(SYS_MODULE_OBJ object); Description System Module De-initialization Routine Pointer This data type is a pointer to a routine that deinitializes a system module (driver, library, or system-maintained application). Preconditions The low-level board initialization must have (and will be) completed and the module's initialization routine will have been called before the system will call the deinitialization routine for any modules. Parameters Parameters Description object Handle to the module instance Returns None. Remarks If the module instance has to be used again, the module's "initalize" function must first be called. Example TBD 5.7.1.1.2.4 SYS_MODULE_INDEX Type C typedef unsigned short int SYS_MODULE_INDEX; Description System Module Index This data type identifies to which instance of a system module a call to that module's "Initialize" and "Open" routines refers. Remarks Each individual module will usually define macro names for the index values it supports (ex. DRV_TMR_INDEX_1, DRV_TMR_INDEX_2, ...). 5.7.1.1.2.5 SYS_MODULE_INIT Union C typedef union { uint8_t value; struct { uint8_t powerState : 4; uint8_t reserved : 4; } sys; } SYS_MODULE_INIT; 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3335 Description System Module Init This structure provides the necessary data to initialize or reinitialize a module (including device drivers) into a requested power state. The structure can be extended in a module specific way as to carry module specific initialization data. Members Members Description uint8_t powerState : 4; Requested power state uint8_t reserved : 4; Module-definable field, module-specific usage Remarks This structure is used in the device driver routines DRV__Initialize and DRV__Reinitialize that are defined by each device driver. The "powerState" member has several pre-defined values (shown below). All other available values (within the 4-bit field) are available for module-specific meaning. Pre-defined powerState Values: 0. SYS_MODULE_POWER_OFF - Module power-state power off state code 1. SYS_MODULE_POWER_SLEEP - Module power-state sleep state code 2. SYS_MODULE_POWER_IDLE_STOP - Module power-state idle-stop state code 3. SYS_MODULE_POWER_IDLE_RUN - Module power-state idle-run state code 4-14. - Module-specific meaning 15. SYS_MODULE_POWER_RUN_FULL - Module power-state run-full state code 5.7.1.1.2.6 SYS_MODULE_INITIALIZE_ROUTINE Type C typedef SYS_MODULE_OBJ (* SYS_MODULE_INITIALIZE_ROUTINE)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Description System Module Initialization Routine Pointer This data type is a pointer to a routine that initializes a system module (driver, library, or system-maintained application). Preconditions The low-level board initialization must have (and will be) completed before the system will call the initialization routine for any modules. Parameters Parameters Description index Identifier for the module instance to be initialized 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3336 init Pointer to the data structure containing any data necessary to initialize the module. This pointer may be null if no data is required and default initialization is to be used. Returns A handle to the instance of the system module that was initialized. This handle is a necessary parameter to all of the other system-module level routines for that module. Remarks This function will only be called once during system initialization. 5.7.1.1.2.7 SYS_MODULE_INTERFACE Structure C typedef struct { SYS_MODULE_INITIALIZE_ROUTINE pModuleInitialize; SYS_MODULE_REINITIALIZE_ROUTINE pModuleReinitialize; SYS_MODULE_DEINITIALIZE_ROUTINE pModuleDeinitialize; SYS_MODULE_STATUS_ROUTINE pModuleStatus; SYS_MODULE_TASKS_DATA * pTasksData; SYS_MODULE_INIT * pModuleInitData; SYS_MODULE_INDEX index; unsigned int tasksNum; } SYS_MODULE_INTERFACE; Description System Module Interface This structure contains pointers to module-interface routines for a single system module. The system will initialize these modules (using their respective initialization routines) and (potentially) monitor and maintain their states using the reinitialize, deinitialize, and status routines. Members Members Description SYS_MODULE_INITIALIZE_ROUTINE pModuleInitialize; Pointer to the module's initialization routine SYS_MODULE_REINITIALIZE_ROUTINE pModuleReinitialize; Pointer to the module's re-initializtion routine SYS_MODULE_DEINITIALIZE_ROUTINE pModuleDeinitialize; Pointer to the module's de-initialization routine SYS_MODULE_STATUS_ROUTINE pModuleStatus; Pointer to the module's status routine SYS_MODULE_TASKS_DATA * pTasksData; Pointer to the module's "Tasks" routine SYS_MODULE_INIT * pModuleInitData; Pointer to the module's init data table SYS_MODULE_INDEX index; Index to the module instance unsigned int tasksNum; Number of tasks supported by this module Remarks A pointer to this structure is passed to the SYS_ModuleRegister routine. Example TBD 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3337 5.7.1.1.2.8 SYS_MODULE_OBJ Type C typedef uintptr_t SYS_MODULE_OBJ; Description System Module Object This data type is a handle to a specific instance of a system module (such as a device driver). Remarks Code outside of a specific module should consider this as an opaque type (much like a void *). Do not make any assumptions about base type as it may change in the future or about the value stored in a variable of this type. 5.7.1.1.2.9 SYS_MODULE_REINITIALIZE_ROUTINE Type C typedef void (* SYS_MODULE_REINITIALIZE_ROUTINE)(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Description System Module Re-initialization Routine Pointer This data type is a pointer to a routine that re-initializes a system module (driver, library, or system-maintained application). Preconditions The low-level board initialization must have (and will be) completed and the module's initialization routine will have been called before the system will call the reinitialization routine for any modules. Parameters Parameters Description object Handle to the module instance init Pointer to the data structure containing any data necessary to initialize the module. This pointer may be null if no data is required and default initialization is to be used. Returns None. Remarks This operation uses the same initialization data structure as the Initialize operation. This operation can be used to change the power state of a module. This operation can also be used to refresh the hardware state as defined by the initialization data, thus it must guarantee that all hardware state has been refreshed. This function can be called multiple times to reinitialize the module. Example TBD 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3338 5.7.1.1.2.10 SYS_MODULE_STATUS_ROUTINE Type C typedef SYS_STATUS (* SYS_MODULE_STATUS_ROUTINE)(SYS_MODULE_OBJ object); Description System Module Status Routine Pointer This data type is a pointer to a routine that gets the current status of a system module (driver, library, or system-maintained application). Preconditions The low-level board initialization must have (and will be) completed and the module's initialization routine will have been called before the system will call the status routine for any modules. Parameters Parameters Description object Handle to the module instance Returns One of the possible status codes from SYS_STATUS Remarks A module's status operation can be used to determine when any of the other module level operations has completed as well as to obtain general status of the module. The value returned by the status routine will be checked after calling any of the module operations to find out when they have completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). A module may define module-specific error values of less or equal SYS_STATUS_ERROR_EXTENDED (-10). The status function must NEVER block. If the status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Example TBD 5.7.1.1.2.11 SYS_MODULE_TASKS_DATA Structure C typedef struct { SYS_MODULE_TASKS_ROUTINE pTasksFunction; bool intModule; } SYS_MODULE_TASKS_DATA; Description System Module Tasks data This structure contains pointers to module's tasks routine. A module can have an array of such structures depending on number of tasks routines it supports. The system will either directly/indirectly call the tasks routine depending on the value of intModule. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3339 Members Members Description SYS_MODULE_TASKS_ROUTINE pTasksFunction; Pointer to the module's "Tasks" routine bool intModule; Tasks type (polled/interrupt) Remarks A pointer to this structure is passed to the SYS_ModuleRegister routine. Example TBD 5.7.1.1.2.12 SYS_MODULE_TASKS_ROUTINE Type C typedef void (* SYS_MODULE_TASKS_ROUTINE)(SYS_MODULE_OBJ object); Description System Module Tasks Routine Pointer This data type is a pointer to a routine that performs the tasks necessary to maintain a state machine in a module system module (driver, library, or system-maintained application). Preconditions The low-level board initialization must have (and will be) completed and the module's initialization routine will have been called before the system will call the deinitialization routine for any modules. Parameters Parameters Description object Handle to the module instance Returns None. Remarks If the module is interrupt driven, the system will call this routine from an interrupt context. Example TBD 5.7.1.1.2.13 SYS_STATUS Enumeration C typedef enum { SYS_STATUS_ERROR_EXTENDED = -10, SYS_STATUS_ERROR = -1, SYS_STATUS_UNINITIALIZED = 0, SYS_STATUS_BUSY = 1, SYS_STATUS_READY = 2, SYS_STATUS_READY_EXTENDED = 10 } SYS_STATUS; Description System Module Status This enumeration identifies the current status/state of a system module (including device drivers). 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3340 Members Members Description SYS_STATUS_ERROR_EXTENDED = -10 Indicates that a non-system defined error has occurred. The caller must call the extended status routine for the module in question to identify the error. SYS_STATUS_ERROR = -1 An un-specified error has occurred. SYS_STATUS_UNINITIALIZED = 0 The module has not yet been initialized SYS_STATUS_BUSY = 1 An operation is currently in progress SYS_STATUS_READY = 2 Any previous operations have succeeded and the module is ready for additional operations SYS_STATUS_READY_EXTENDED = 10 Indicates that the module is in a non-system defined ready/run state. The caller must call the extended status routine for the module in question to identify the state. Remarks This enumeration is the return type for the system-level status routine defined by each device driver or system module (for example, DRV_I2C_Status). 5.7.1.1.2.14 SYS_TASKS_PRIORITY Enumeration C typedef enum _SYS_TASKS_PRIORITIES { SYS_TASKS_PRIORITY_INVALID = 0, SYS_TASKS_PRIORITY_HIGH, SYS_TASKS_PRIORITY_MEDIUM, SYS_TASKS_PRIORITY_LOW } SYS_TASKS_PRIORITY; Description System Tasks Priority This enumeration defines the available system tasks priorities. Members Members Description SYS_TASKS_PRIORITY_INVALID = 0 Invalid priority (can be used as a sentinal value) SYS_TASKS_PRIORITY_HIGH High priority tasks are called every time through the loop SYS_TASKS_PRIORITY_MEDIUM Called at the medium priority interval. SYS_TASKS_PRIORITY_LOW Called at the low priority interval. Remarks To use medium priority tasks, a medium priority interval must be defined by defining SYS_TASKS_CONFIG_MEDIUM_INTERVAL to the desired interval (in milliseconds). To use low priority tasks, a low priority interval must be defined by defining SYS_TASKS_CONFIG_LOW_INTERVAL to the desired interval (in milliseconds). 5.7.1.1.2.15 MAIN_RETURN Macro C #define MAIN_RETURN void Description Main Routine Return Type 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3341 This macro defines the correct return type for the "main" routine for the selected Microchip microcontroller family. Remarks This type changes depending upon which family of Microchip microcontrollers is chosen. Most Microchip microcontrollers do not return any value from "main". Example MAIN_RETURN main ( void ) { // Initialize the system SYS_Initialize(...); // Main Loop while(true) { SYS_Tasks(); } return MAIN_RETURN_CODE(MAIN_RETURN_SUCCESS); } 5.7.1.1.2.16 MAIN_RETURN_CODE Macro C #define MAIN_RETURN_CODE(c) Description Main Routine Code Macro This macro provides the correct value for the return code from "main". Remarks Most Microchip microcontrollers do not provide a return value from "main". Therefore, this macro discards the code it is given unless it is needed. Example MAIN_RETURN main ( void ) { // Initialize the system SYS_Initialize(...); // Main Loop while(true) { SYS_Tasks(); } return MAIN_RETURN_CODE(MAIN_RETURN_SUCCESS); } 5.7.1.1.2.17 SYS_MODULE_OBJ_INVALID Macro C #define SYS_MODULE_OBJ_INVALID ((SYS_MODULE_OBJ) -1 ) Description System Module Object Invalid This is the object handle value returned if unable to initialize the requested instance of a system module. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3342 Remarks Do not rely on the actual value of this constant. It may change in future implementations. 5.7.1.1.2.18 SYS_MODULE_OBJ_STATIC Macro C #define SYS_MODULE_OBJ_STATIC ((SYS_MODULE_OBJ) 0 ) Description System Module Object Static This is the object handle value returned by static system modules. Remarks Do not rely on the actual value of this constant. It may change in future implementations. 5.7.1.1.2.19 SYS_MODULE_POWER_IDLE_RUN Macro C #define SYS_MODULE_POWER_IDLE_RUN 3 Description System Module Power Idle-Run State This value identifies the current power status/state of a system module (including device drivers). It is used to indicate that the module should prepare to enter an idle-run state. Remarks An idle-run state indicates that the core CPU clock may be stopped, but the module's peripheral clock may continue running and peripheral operations may continue as long as no code needs to be executed. If code needs to execute, the module must cause an interrupt. This value is passed in the powerState field of the SYS_MODULE_INIT structure that takes part in all modules initialization and reinitialization. The power state codes between SYS_MODULE_POWER_IDLE_RUN (with a value of 3) and SYS_MODULE_POWER_RUN_FULL (with a value of 15) are available for module-specific definition and usage. 5.7.1.1.2.20 SYS_MODULE_POWER_IDLE_STOP Macro C #define SYS_MODULE_POWER_IDLE_STOP 2 Description System Module Power Idle-Stop State This value identifies the current power status/state of a system module (including device drivers). It is used to indicate that the module should prepare to enter an idle-stop state. Remarks An idle-stop state indicates that the core CPU clock may be stopped, but the module's peripheral clock may continue running. However, the peripheral should prepare to stop operations when the idle state is entered. This value is passed in the powerState field of the SYS_MODULE_INIT structure that takes part in all modules initialization and reinitialization. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3343 The power state codes between SYS_MODULE_POWER_IDLE_RUN (with a value of 3) and SYS_MODULE_POWER_RUN_FULL (with a value of 15) are available for module-specific definition and usage. 5.7.1.1.2.21 SYS_MODULE_POWER_OFF Macro C #define SYS_MODULE_POWER_OFF 0 Description System Module Power Off State This value identifies the current power status/state of a system module (including device drivers). It is used to indicate that the module should prepare to enter a full power-off state. Remarks A power off state indicates that power may be completely removed (0 Volts). This value is passed in the powerState field of the SYS_MODULE_INIT structure that takes part in all modules initialization and reinitialization. The power state codes between SYS_MODULE_POWER_IDLE_RUN (with a value of 3) and SYS_MODULE_POWER_RUN_FULL (with a value of 15) are available for module-specific definition and usage. 5.7.1.1.2.22 SYS_MODULE_POWER_RUN_FULL Macro C #define SYS_MODULE_POWER_RUN_FULL 15 Description System Module Power Run-Full State This value identifies the current power status/state of a system module (including device drivers). It is used to indicate that the module should prepare to enter an run-full state. Remarks An run-full state indicates that the core CPU and pereipheral clocks are operational at their normal configured speed and the module should be ready for normal operation. This value is passed in the powerState field of the SYS_MODULE_INIT structure that takes part in all modules initialization and reinitialization. The power state codes between SYS_MODULE_POWER_IDLE_RUN (with a value of 3) and SYS_MODULE_POWER_RUN_FULL (with a value of 15) are available for module-specific definition and usage. 5.7.1.1.2.23 SYS_MODULE_POWER_SLEEP Macro C #define SYS_MODULE_POWER_SLEEP 1 Description System Module Power Sleep State This value identifies the current power status/state of a system module (including device drivers). It is used to indicate that the module should prepare to enter a sleep state. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3344 Remarks A Sleep state indicates that the core CPU and peripheral clocks may be stopped and no code will execute and any module hardware will be stopped. This value is passed in the powerState field of the SYS_MODULE_INIT structure that takes part in all modules initialization and reinitialization. The power state codes between SYS_MODULE_POWER_IDLE_RUN (with a value of 3) and SYS_MODULE_POWER_RUN_FULL (with a value of 15) are available for module-specific definition and usage. 5.7.1.2 Files Files Name Description sys_common.h Common definitions and declarations required for the system. sys_module.h Defines definitions and declarations related to system modules. system.h Aggregates all of the system services library interface headers. Description 5.7.1.2.1 sys_common.h System Services Common Library Header This file defines the common definitions and declarations required for the system. Remarks This file is included by "system.h". Enumerations Name Description _SYS_TASKS_PRIORITIES Defines system tasks priorities. MAIN_RETURN_CODES Predefined list of return codes for "main". SYS_TASKS_PRIORITY Defines system tasks priorities. Macros Name Description MAIN_RETURN Defines the correct return type for the "main" routine. MAIN_RETURN_CODE Provides the correct value for the return code from "main". File Name sys_common.h Company Microchip Technology Inc. 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3345 5.7.1.2.2 sys_module.h System Module Header This file defines definitions and interfaces related to system modules. Remarks This file is included via "system.h" and does not normally need to be included directly. Enumerations Name Description SYS_STATUS Identifies the current status/state of a system module (including device drivers). Functions Name Description SYS_Initialize Function that initializes all modules in the system. SYS_Tasks Function that performs all polled system tasks. Macros Name Description SYS_MODULE_OBJ_INVALID Object handle value returned if unable to initialize the requested instance of a system module. SYS_MODULE_OBJ_STATIC Object handle value returned by static modules. SYS_MODULE_POWER_IDLE_RUN Module power-state idle-run state code. SYS_MODULE_POWER_IDLE_STOP Module power-state idle-stop state code. SYS_MODULE_POWER_OFF Module power-state power off state code. SYS_MODULE_POWER_RUN_FULL Module power-state run-full state code. SYS_MODULE_POWER_SLEEP Module power-state sleep state code. Structures Name Description SYS_MODULE_DATA Contains module-interface info used to define a table of system modules SYS_MODULE_INTERFACE Structure contains pointers to module-interface routines for a single system module. SYS_MODULE_TASKS_DATA Structure contains pointers to module's tasks routine. Types Name Description SYS_MODULE_DEINITIALIZE_ROUTINE Pointer to a routine that de-initializes a system module (driver, library, or system-maintained application) SYS_MODULE_INDEX Identifies which instance of a system module should be initialized or opened. SYS_MODULE_INITIALIZE_ROUTINE Pointer to a routine that initializes a system module (driver, library, or system-maintained application). SYS_MODULE_OBJ Handle to an instance of a system module. SYS_MODULE_REINITIALIZE_ROUTINE Pointer to a routine that reinitializes a system module (driver, library, or system-maintained application) SYS_MODULE_STATUS_ROUTINE Pointer to a routine that gets the current status of a system module (driver, library, or system-maintained application). 5.7 System Service Library Help MPLAB Harmony Help System Service Overview 5-3346 SYS_MODULE_TASKS_ROUTINE Pointer to a routine that performs the tasks necessary to maintain a state machine in a module system module (driver, library, or system-maintained application). Unions Name Description SYS_MODULE_INIT Initializes a module (including device drivers) in a current power status as requested by the system or power manager. File Name sys_module.h Company Microchip Technology Inc. 5.7.1.2.3 system.h System Services Library Interface Header This file aggregates all of the system services library interface headers so that client code only needs to include this one single header to obtain prototypes and definitions for the interface to all system service libraries. System services provide common functionality that would otherwise need to be duplicated by multiple other modules or would force other drivers and libraries to interact in complex and hard to manage ways. System services eliminate conflicts by controlling access shared resources. Remarks The directory in which this file resides should be added to the compiler's search path for header files. Many Harmony libraries assume that "system.h" is available in the "include" path. File Name system.h Company Microchip Technology Inc. 5.7.2 Clock System Service Library 5.7.2.1 Introduction Clock System Service Library for Microchip Microcontrollers 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3347 This library provides an interface to manage the Oscillator module on Microchip family of micro controllers during different modes of operation. Overview of Oscillator The Oscillator is the heart of the microcontroller which provides the clock on which the core and the peripherals run. For all of the oscillators present on a Microchip microcontroller, two kinds of configurations exist: • Through Configuration bits • At Execution time The first is through 'Configuration bits' which is a one-time configuration and it is done during the programming of the device. These one-time configurations are programmed in the code memory. The other is 'Execution time' configuration, which deals with features that are allowed to change during the code execution. This library provides functions which deals only with the 'Execution time' configurable features of the Oscillator module. Oscillator is a device which supports the CPU and other peripherals by providing clock. So there is more of initialization and a little or no run time operations. The run time operations would be getting the System clock or any other 'output clocks'. If the application want to change any of the initialization, at run time, that can be done. The Oscillator module as a whole is a group of oscillators. These are provided for the application to choose right oscillator for his application. It is important to wisely choose the oscillator and the frequency at which the CPU and the other peripheral should run at in a very power critical environments. 5.7.2.2 Release Notes MPLAB Harmony Version: v0.70b Oscillator System Service Library Version : 0.01a Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3348 FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.2.4 Using the Library This topic describes the basic architecture of the Oscillator System Service and provides information and examples on how to use it. Interface Header File: sys_osc.h The interface to the Oscillator System Service is defined in the "sys_osc.h" header file, which is included by the "sys.h" header file. Any C language source (.c) file that uses the Oscillator system service must include "sys.h". 5.7.2.4.1 Abstraction Model To understand the oscillator module and how each of its feature is mapped in this library, it is important to understand all these terminologies. Oscillators: A clock source is hardware which generates oscillations. This may be internal or external. Divisor and Multiplier/PLL: These are hardware modules which can scale the clock. The rate at which the scaling is done may be fixed or configurable. Clocks: Clock outputs means output lines from the oscillator module which may route to different modules of the device or to the CPU(the system clock). The diagram above gives a simplified explanation and the relationship between the above mentioned terms. In most of the cases, there are multiple clock source options available for each of the clock outputs. But not all the clock sources are available for all the output clocks. Scaling is an optional feature in most of the cases. 5.7.2.4.2 Library Overview The diagram below shows the flow of an application call to Oscillator System service. Refer to the section System Services Overview for how the system services operates in a system. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3349 The library interface routines are divided into various subsections, each of the subsection addresses one of the blocks or the overall operation of the Oscillator System Service module. Library Interface Section Description System Initialization Functions This section provides an initialization routine to configure the module at the startup of the system and Re-initialization if the application want to change any of the initialization settings System Status Functions Provides function to read different clock outputs from the oscillator module. Optional System Functions FRC oscillator tuning and clock fail detection APIs 5.7.2.4.3 How the Library Works 5.7.2.4.3.1 Initialization Oscillator is a module with a little or no run time operations. So the application must do most of the configurations at the time of System initialization even though it is allowed to change the clock frequency at run time. Not all the devices will need all the initialization parameters of the structure. Refer the datasheet of the specific device to know the features available in each device. Call the initialization API by passing the initialization data required. generalInit.auxOscMode = CLK_AUX_HS; generalInit.auxPllEnable = true; generalInit.refOscEnable = true; generalInit.trimValue = 0; generalInit.secondaryOscKeepEnabled = true; generalInit.onWaitOperation = CLK_ON_WAIT_IDLE; generalInit.sysClockSource = SYS_CLK_SYSCLK_PRIMARY_PLL; generalInit.usbClockSource = SYS_CLK_USBCLK_PRIMARY_PLL; generalInit.auxClockSource = CLK_AUX_CLOCK_PRIMARY_PLL; generalInit.refOscBaseClock = CLK_REF_PB_CLOCK; generalInit.pll_multiplier = SYS_CLK_PLL_SYSCLOCK_BY_20; generalInit.frcClockDivisor = CLK_FRC_DIVISOR_4; generalInit.peripheralBusClkDiv = CLK_PB_CLOCK_DIV_8; generalInit.auxPllMultiplier = CLK_PLL_MUL_18; generalInit.refOscDivisor = = 1024; 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3350 generalInit.dozeRatio = CLK_DOZE_RATIO_4; generalInit.dozeRecoverOnInterrupt = true; SYS_CLK_Initialize (&generalInit); Oscillator needs some time to settle. So it is recommended to do the oscillator initialization before initializing other modules. Check for the oscillator status once all the initializations are complete and before application task routine takes control. 5.7.2.4.3.2 Changing the Clock It is allowed to change any of the clock frequency at run time. There is a single API provided to set the clock source and configure it to the clock frequency requested. User is supposed to look at the data sheet ad find out one of the possible value of the output clock. The API, internally adjusts the multipliers/divisors necessary. Setting the System Clock: SYS_CLK_ClockFrequencySet(CLK_SYSTEM, SYS_CLK_SOURCE_FRC, 8000000); Setting the USB Clock: SYS_CLK_ClockFrequencySet(CLK_USB, SYS_CLK_SOURCE_FRCPLL, 48000000); 5.7.2.4.3.3 Using Status Functions Once the the initialization is done, oscillator needs some time to settle down and get into its normal operation. The application can add a delay, do other initialization or wait in the status check routine. To minimize the waiting time it is highly recommended to do the initialization before all other initializations. // Populate the oscillator initialization structure //Call the initialization routines //Do other initializations //Check whether all the oscillators are ready while((!SYS_OSC_IsReady(OSC_OUTPUT_SYSCLOCK)) && (!SYS_OSC_IsReady(OSC_OUTPUT_PBCLOCK)) && (!SYS_OSC_IsReady(OSC_OUTPUT_USBCLOCK))&& (!SYS_OSC_IsReady(OSC_OUTPUT_GFXCLOCK))); while(1) { //Application } The application can read the frequency at which the system is running at any time after the initialization is complete. uint32_t sysClockOutputHz, usbClockOutputHz, pbClockOutputHz, gfxClockOutputHz; //Get the system clock sysClockOutputHz = SYS_OSC_ClockFrequencyGet(OSC_OUTPUT_SYSCLOCK); //Get the peripheral clock pbClockOutputHz = SYS_OSC_ClockFrequencyGet(OSC_OUTPUT_PBCLOCK); //Get the USB clock usbClockOutputHz = SYS_OSC_ClockFrequencyGet(OSC_OUTPUT_USBCLOCK); //Get the graphics clock gfxClockOutputHz = SYS_OSC_ClockFrequencyGet(OSC_OUTPUT_GFXCLOCK); 5.7.2.4.3.4 Oscillator Tuning Tuning the Oscillator: Oscillator Tuning will help compensate for temperature effects on the FRC frequency over a wide range of temperatures. The tuning step size is an approximation, the application is supposed to try different values to achieve the best result. In some of the 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3351 devices there are different tuning modes available. Direct Number method: //Software must unlock before the start of the tuning. SYS_OSC_FRCTUNING_DATA tuningInput; OSC_FRC_TUNING_VALUE tuningValue = OSC_TUNE_TO_CENTRAL_FREQ_PLUS_0_86; tuningInput.tuningMode = OSC_TUNING_USING_NUMBER; tuningInput.tuningData = &tuningValue; SYS_OSC_FRCTuningSet(&tuningInput); Sequential Dithering: To get the Sequential Dithering working, the application is suppose to set the value in 7 sequencers and also in the tuning register. Then configure the PWM module, set the period and pulse width. The Oscillator module generates frequencies corresponding the value specified in these registers in every 8th PWM cycle. //Software must unlock before the start of the tuning. SYS_OSC_FRCTUNING_DATA tuningInput; OSC_FRC_TUNING_VALUE tuningValue[8]; //Initialize with tuning values tuningValue[0] = OSC_TUNE_TO_CENTRAL_MINUS_2_25_PERC; tuningValue[1] = OSC_TUNE_TO_CENTRAL_MINUS_1_5_PERC; tuningValue[2] = OSC_TUNE_TO_CENTRAL_MINUS_0_375_PERC; tuningValue[3] = OSC_TUNE_TO_CENTRAL_PLUS_0_43_PERC; tuningValue[4] = OSC_TUNE_TO_CENTRAL_PLUS_1_29_PERC; tuningValue[5] = OSC_TUNE_TO_CENTRAL_PLUS_2_54_PERC; tuningValue[6] = OSC_TUNE_TO_CENTRAL_MINUS_3_PERC; tuningValue[7] = OSC_TUNE_TO_CENTRAL_MINUS_3_PERC; tuningInput.tuningMode = OSC_TUNING_SEQ_DITHER; tuningInput.tuningData = tuningValue; SYS_OSC_FRCTuningSet(&tuningInput); Pseudo-Random Number: Select the tuning mode. Then configure the PWM module, set the period and pulse width. The Oscillator system generates a 4-bit number based on Pseudo-Random number generation algorithm. It then uses this value to tune the FRC oscillator. The module will generate different frequencies corresponding to the generated Pseudo-Random numbers every 8th PWM cycle. //Software must unlock before the start of the tuning. SYS_OSC_FRCTUNING_DATA tuningInput; OSC_FRC_TUNING_VALUE tuningValue = 0x7FFF; tuningInput.tuningMode = OSC_TUNING_PSEUDO_RANDOM; tuningInput.tuningData = &tuningValue; SYS_OSC_FRCTuningSet(&tuningInput); 5.7.2.5 Configuring the Library The configuration of the Oscillator System Service Library is based on the file sys_config.h This header file contains the configuration selection for the Oscillator System Service Library. Based on the selections made, the Oscillator System Service Library will support or not support selected features. These configuration settings will apply to all instances of the Oscillator System Service Library. This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3352 5.7.2.6 Library Interface Data Types and Constants Name Description SYS_CLK_FRCTUNING_DATA Defines the data required for tuning the FRC Oscillator. SYS_CLK_INIT Defines the data required to initialize the Oscillator for the Clock System Service. SYS_CLK_OUTPUT Lists the available clock outputs. SYS_CLK_SOURCE Lists the available clock outputs. CLK_PERIPH_BUS_MZ Lists the available peripheral clocks. CLK_SOURCE_PERIPHERAL Lists the available clock sources for the peripheral clock. Optional System Functions Name Description SYS_CLK_FRCTuningSet Starts the FRC tuning. System Initialization Functions Name Description SYS_CLK_ClockFailureCallbackRegister Allows registration of a call back function that will be triggered on a clock failure. SYS_CLK_Initialize Initializes hardware and internal data structure of the System Clock. System Status Functions Name Description SYS_CLK_ClockFrequencyGet Gets the selected clock frequency in Hz. SYS_CLK_ClockFrequencySet Configures the clock multiplier and divisor values. SYS_CLK_ClockIsReady Checks whether the selected clock output is stable and ready to use. SYS_CLK_FRCTune This function is used for direct value based FRC oscillator tuning. SYS_CLK_MZPeriphBusFreqGet Gets the selected peripheral clock frequency in Hz (PIC32MZ only). Description 5.7.2.6.1 System Initialization Functions 5.7.2.6.1.1 SYS_CLK_ClockFailureCallbackRegister Function C void SYS_CLK_ClockFailureCallbackRegister( void * callback ); Description This function allows registration of a callback function that will be triggered on a clock failure. In addition, this function monitors the Fail-Safe Clock Monitor (FSCM). Preconditions None. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3353 Parameters Parameters Description index Identifies the desired System Clock Returns None. Remarks This function is not available on all devices. Please refer to the specific device data sheet for availability. Example SYS_CLK_ClockFailureCallbackRegister(&ErrorHandle); void ErrorHandle (void) { //Handle the error. } 5.7.2.6.1.2 SYS_CLK_Initialize Function C void SYS_CLK_Initialize( const SYS_CLK_INIT const * clkInit ); Description This function initializes the hardware and internal data structure of the System Clock. Preconditions None. Parameters Parameters Description clkInit Pointer to a data structure containing any data necessary to initialize the System Clock. This pointer can be NULL if no data is required as static overrides have been provided. Returns None. Example SYS_CLK_INIT generalInit; // Populate the oscillator initialization structure generalInit.systemClockSource = SYS_CLK_SOURCE_FRC_SYSPLL; generalInit.systemClockFrequency = 30000000; generalInit.usbClockEnable = true; generalInit.usbClockSource = SYS_CLK_SOURCE_PRIMARY_USBPLL; generalInit.usbClockFrequency = 48000000; generalInit.peripheralClockEnable = true; generalInit.peripheralClockSource = SYS_CLK_SOURCE_SYSCLK_OUT; generalInit.peripheralClockFrequency = 15000000; generalInit.referenceClockEnable = true; generalInit.referenceClockSource = SYS_CLK_SOURCE_FRC; generalInit.referenceClockFrequency = 8000000; SYS_CLK_Initialize (&generalInit); 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3354 Remarks: This could be called at the time of system initialization to initialize the oscillator or after initialization to change any of the initialization settings. 5.7.2.6.2 System Status Functions 5.7.2.6.2.1 SYS_CLK_ClockFrequencyGet Function C unsigned long SYS_CLK_ClockFrequencyGet( SYS_CLK_OUTPUT clockOutput ); Description This function gets the selected clock frequency in Hz. Preconditions The selected clock output must be configured and enabled. Returns Clock frequency in Hz. Example unsigned long sysClockOutputHz; sysClockOutputHz = SYS_CLK_ClockFrequencyGet(CLK_SYSTEM); 5.7.2.6.2.2 SYS_CLK_ClockFrequencySet Function C unsigned long SYS_CLK_ClockFrequencySet( SYS_CLK_OUTPUT outputClock, SYS_CLK_SOURCE clockSource, unsigned long clockFrequency ); Description This function configures the clock multiplier and divisor values. This function covers all of the configuration for an oscillator clock output. All of the arguments in the API may not be applicable in all cases. The API discards the arguments that are not relevant. Preconditions The SYS_CLK_Initialize function should be called before calling this API. Parameters Parameters Description outputClock Clock for which the source is to be selected clockSource Select the clock source clockFrequency Select the clock clock frequecncy Returns None. Example SYS_CLK_ClockFrequencySet(CLK_SYSTEM, SYS_CLK_SOURCE_FRC, 8000000); Remarks: This API returns a zero if it cannot achieve the value requested. The user 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3355 must recheck the hardware and enter the possible value. 5.7.2.6.2.3 SYS_CLK_ClockIsReady Function C bool SYS_CLK_ClockIsReady( SYS_CLK_OUTPUT clockOutput ); Description This function checks whether the selected clock output is stable. This should be checked at system start-up, after the initialization is complete and also each time when there is a change in the clock setup configuration. This function checks the PLL lock status to determine whether the PLL is enabled. Preconditions None. Returns • true - The selected clock output is stable • false - The selected clock output is not stable Remarks This function should be called at system start-up. This API is non-blocking in nature, so the application must call this API in a loop to wait until the initial settling time of the oscillator expires and the oscillator becomes ready. Example //Wait until the selected clock output is getting stabilized. while(!SYS_CLK_ClockIsReady(CLK_SYSTEM)); 5.7.2.6.2.4 SYS_CLK_FRCTune Function C void SYS_CLK_FRCTune( OSC_FRC_DIV tuningData ); Description This function triggers the FRC tuning based on the selected mode. FRC tuning functionality has been provided to help customers compensate for temperature effects on the FRC frequency over a wide range of temperatures. Preconditions The device selected must support the oscillator tuning feature. Parameters Parameters Description tuningData One of the possible value of OSC_FRC_TUNE enum Returns None. Remarks The tuning step size is an approximation, and is neither characterized, nor tested. This API may can be only used with devices that support direct value based FRC tuning. Refer to the specific device data sheet 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3356 to determine whether this feature exists for your device. Example SYS_CLK_FRCTune( OSC_FRC_TUNE_MINUS_1_875_PERCENT); 5.7.2.6.2.5 SYS_CLK_MZPeriphBusFreqGet Function C unsigned long SYS_CLK_MZPeriphBusFreqGet( CLK_PERIPH_BUS_MZ periphBus ); Description This function gets the selected clock frequency in Hz (PIC32MZ only). Preconditions The selected clock output must be configured and enabled. Returns Clock frequency in Hz. Example unsigned long sysClockOutputHz; sysClockOutputHz = SYS_CLK_ClockFrequencyGet(CLK_PERIPH_BUS_2); 5.7.2.6.3 Optional System Functions 5.7.2.6.3.1 SYS_CLK_FRCTuningSet Function C void SYS_CLK_FRCTuningSet( SYS_CLK_FRCTUNING_DATA * tuningData ); Description This function triggers the FRC tuning based on the selected mode. Preconditions The device selected must support the oscillator tuning feature. Parameters Parameters Description tuningData An instance of the structure SYS_CLK_FRCTUNING_DATA Data used for tuning tuningMode FRC oscillator tuning mode Returns None. Remarks This function is not applicable for devices that do not have an FRC oscillator and devices that do have an FRC oscillator, but not FRC tuning. Refer to the specific device data sheet to determine whether this feature exists for your device. Example SYS_CLK_FRCTUNING_DATA tuningInput; 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3357 CLK_FRC_TUNING_VALUE tuningValue; tuningData.tuningMode = CLK_TUNING_USING_NUMBER; tuningInput.tuningData = &tuningValue; SYS_CLK_FRCTuningSet(&tuningInput); 5.7.2.6.4 Data Types and Constants 5.7.2.6.4.1 SYS_CLK_FRCTUNING_DATA Structure C typedef struct { OSC_TUNING_MODE tuningMode; uint8_t * tuningData; } SYS_CLK_FRCTUNING_DATA; Description Clock module FRC tuning modes This structure defines the necessary data required to tune the FRC Oscillator. Members Members Description OSC_TUNING_MODE tuningMode; Oscillator tuning mode uint8_t * tuningData; The data required may vary depending on the mode. This could be pointed to a variable or an array of data Remarks None. 5.7.2.6.4.2 SYS_CLK_INIT Structure C typedef struct { SYS_CLK_SOURCE systemClockSource; unsigned long systemClockFrequency; bool usbClockEnable; SYS_CLK_SOURCE usbClockSource; unsigned long usbClockFrequency; bool peripheralClockEnable; SYS_CLK_SOURCE peripheralClockSource; unsigned long peripheralClockFrequency; bool referenceClockEnable; SYS_CLK_SOURCE referenceClockSource; unsigned long referenceClockFrequency; bool secondaryOscKeepEnabled; OSC_OPERATION_ON_WAIT onWaitInstruction; bool referenceStopInIdle; bool referenceSuspendInSleep; } SYS_CLK_INIT; Description Clock System Service Reference Oscillator initialization data This structure defines the data required to initialize the Oscillator for the Clock System Service. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3358 Members Members Description SYS_CLK_SOURCE systemClockSource; Initializations for System clock unsigned long systemClockFrequency; Set the System clock frequency bool usbClockEnable; Initializations for USB clock Enable the USB clock. If the device doesn't need USB clock, set this variable to 'false'. In that case, user need not set next two variables. SYS_CLK_SOURCE usbClockSource; Select the USB clock source unsigned long usbClockFrequency; Set the USB clock frequency bool peripheralClockEnable; Initializations for Peripheral clock Enable the Peripheral clock. If the device doesn't need Peripheral clock, set this variable to 'false'. In that case, user need not set next two variables. SYS_CLK_SOURCE peripheralClockSource; Select the Peripheral clock source unsigned long peripheralClockFrequency; Set the Peripheral clock frequency bool referenceClockEnable; Initializations for Reference clock out Set this variable to 'true' to enable the reference clock out. The system service will discard this either if this variable is set to 'false' or if the device doesn't has 'reference clock out' feature. SYS_CLK_SOURCE referenceClockSource; Base clock for the reference clock out. This will be divided and tuned to get the actual Reference clock output unsigned long referenceClockFrequency; Use this to fine tune the divided reference oscillator clock out. bool secondaryOscKeepEnabled; Even though the secondary oscillator is not used, keeping the oscillator running, allows a fast switch to the lower system clock for low-power operation OSC_OPERATION_ON_WAIT onWaitInstruction; System action on a 'Wait' instruction bool referenceStopInIdle; Stop reference clock out in Idle mode bool referenceSuspendInSleep; Stop reference clock out in sleep mode Remarks Calling this API may not be essential in some cases. Some of the elements in this structure are part of the library configuration file. Setting them here will override the configuration file setting. 5.7.2.6.4.3 SYS_CLK_OUTPUT Enumeration C typedef enum { CLK_SYSTEM, CLK_PERIPHERAL, CLK_USB, CLK_REFERENCE, CLK_GRAPHIX, CLK_ADCPWM } SYS_CLK_OUTPUT; Description Clocks enumeration This enumeration lists all of the available clock outputs. This is used by the SYS_CLK_ClockFrequencyGet and SYS_CLK_ClockIsReady functions. Members Members Description CLK_SYSTEM Selects System clock output. This is used by the CPU and some of the peripherals 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3359 CLK_PERIPHERAL Selects peripheral clock output. This is used by most of the peripherals CLK_USB Selects USB clock output. This is used by the USB module CLK_REFERENCE Selects referece clock output. This to check any of the clock or it could be used as a clock source for other devices CLK_GRAPHIX Selects Graphics clock output. This is used by the display module CLK_ADCPWM Selects ADC/PWM clock Remarks 'Clock output' means output from the clock source. 5.7.2.6.4.4 SYS_CLK_SOURCE Enumeration C typedef enum { SYS_CLK_TOTAL_SOURCES, SYS_CLK_SOURCE_EXTERNAL, SYS_CLK_SOURCE_USBPLL_OUT, SYS_CLK_SOURCE_SYSPLL_OUT, SYS_CLK_SOURCE_PBCLK_OUT, SYS_CLK_SOURCE_SYSCLK_OUT, SYS_CLK_SOURCE_AUXILIARY, SYS_CLK_SOURCE_FRC_BY_DIV, SYS_CLK_SOURCE_FRC_BY_16, SYS_CLK_SOURCE_LPRC, SYS_CLK_SOURCE_SECONDARY, SYS_CLK_SOURCE_PRIMARY_USBPLL, SYS_CLK_SOURCE_PRIMARY_SYSPLL, SYS_CLK_SOURCE_PRIMARY, SYS_CLK_SOURCE_FRC_SYSPLL, SYS_CLK_SOURCE_FRC } SYS_CLK_SOURCE; Description Clock clocks enumeration This enumeration lists all the available clock outputs. This is used by the SYS_CLK_ClockFrequencyGet and SYS_CLK_ClockIsReady functions. Members Members Description SYS_CLK_TOTAL_SOURCES This gives the total number of sources present SYS_CLK_SOURCE_EXTERNAL Source of clock is external(from the pin) This is used only for the Reference clock. SYS_CLK_SOURCE_USBPLL_OUT Source of clock is output of USB PLL This is used only for the Reference clock. SYS_CLK_SOURCE_SYSPLL_OUT Source of clock is the output of System PLL. This is used only for the Reference clock. SYS_CLK_SOURCE_PBCLK_OUT Source of clock is peripheral clock. This is used only for the Reference clock. SYS_CLK_SOURCE_SYSCLK_OUT Source of clock is System clock. This is used for Peripheral clock and the Reference clock. SYS_CLK_SOURCE_AUXILIARY Source of clock is Auxiliary clock. SYS_CLK_SOURCE_FRC_BY_DIV Source of clock is internal fast RC divided by the divisor configured in software. This is used only for the System clock. SYS_CLK_SOURCE_FRC_BY_16 Source of clock is internal fast RC divided by 16. This is used only for the System clock. SYS_CLK_SOURCE_LPRC Source of clock is internal low power RC. This is used for System clock and the Reference clock. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3360 SYS_CLK_SOURCE_SECONDARY Source of clock is secondary oscillator. This is used for System clock and the Reference clock. SYS_CLK_SOURCE_PRIMARY_USBPLL Source of clock is primary oscillator multiplied by the USB PLL value and divided by the divisor configured by software. This is used only for the USB clock SYS_CLK_SOURCE_PRIMARY_SYSPLL Source of clock is primary oscillator multiplied by the System PLL value and divided by the divisor configured by software. This is used for System clock and the Reference clock. SYS_CLK_SOURCE_PRIMARY Source of clock is primary oscillator. This is used for System clock, Reference clock and the USB clock SYS_CLK_SOURCE_FRC_SYSPLL Source of clock is internal fast RC multiplied by system PLL. This is used for System clock and the Reference clock. SYS_CLK_SOURCE_FRC Source of clock is internal fast RC This is used for System clock, Reference clock and the USB clock Remarks 'Clock output' means output from the clock source. Not all clock sources are available for all devices. Refer to the specific device data sheet to determine the available clock sources. 5.7.2.6.4.5 CLK_PERIPH_BUS_MZ Enumeration C typedef enum { CLK_PERIPH_BUS_1, CLK_PERIPH_BUS_2, CLK_PERIPH_BUS_3, CLK_PERIPH_BUS_4, CLK_PERIPH_BUS_5, CLK_PERIPH_BUS_6, CLK_PERIPH_BUS_7, CLK_PERIPH_BUS_8 } CLK_PERIPH_BUS_MZ; Description Peripherals Clocks enumeration (PIC32MZ only) This enumeration lists all of the available peripheral clocks. This is used by the SYS_CLK_ClockFrequencyGet function to return the peripheral clock frequency to the caller. Members Members Description CLK_PERIPH_BUS_6 not used Remarks None. 5.7.2.6.4.6 CLK_SOURCE_PERIPHERAL Enumeration C typedef enum { SYS_CLK_SOURCE_SYSTEMCLK } CLK_SOURCE_PERIPHERAL; Description Peripheral clock sources enumeration This enumeration lists all the available peripheral clock sources. This is used by the SYS_CLK_ClockFrequencySet function. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3361 Members Members Description SYS_CLK_SOURCE_SYSTEMCLK Source of clock is system clock Remarks None. 5.7.2.7 Files Files Name Description sys_clk.h API for the Clock System Service. Description 5.7.2.7.1 sys_clk.h Clock System Service Interface Definition This file contains the interface definition for the Clock System Service. It provides a way to interact with the Clock subsystem to manage the timing requests supported by the system. Enumerations Name Description CLK_PERIPH_BUS_MZ Lists the available peripheral clocks. CLK_SOURCE_PERIPHERAL Lists the available clock sources for the peripheral clock. SYS_CLK_OUTPUT Lists the available clock outputs. SYS_CLK_SOURCE Lists the available clock outputs. Functions Name Description SYS_CLK_ClockFailureCallbackRegister Allows registration of a call back function that will be triggered on a clock failure. SYS_CLK_ClockFrequencyGet Gets the selected clock frequency in Hz. SYS_CLK_ClockFrequencySet Configures the clock multiplier and divisor values. SYS_CLK_ClockIsReady Checks whether the selected clock output is stable and ready to use. SYS_CLK_FRCTune This function is used for direct value based FRC oscillator tuning. SYS_CLK_FRCTuningSet Starts the FRC tuning. SYS_CLK_Initialize Initializes hardware and internal data structure of the System Clock. SYS_CLK_MZPeriphBusFreqGet Gets the selected peripheral clock frequency in Hz (PIC32MZ only). Structures Name Description SYS_CLK_FRCTUNING_DATA Defines the data required for tuning the FRC Oscillator. SYS_CLK_INIT Defines the data required to initialize the Oscillator for the Clock System Service. 5.7 System Service Library Help MPLAB Harmony Help Clock System Service Library 5-3362 File Name sys_clk.h Company Microchip Technology Inc. 5.7.3 Device Control System Service Library 5.7.3.1 Introduction Device Control System Service Library for Microchip Microcontrollers This library provides a low-level abstraction of the Device Control System Service Library that is available on the Microchip family of PIC32 microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description The Device Control System Service provides the developer a simple API to configure their device for maximum performance. It does this by minimizing the number of clock cycles required to fetch instructions and data from Program Flash Memory (PFM), and SRAM. For PIC32MX devices, it also sets the peripheral clock bus to the fastest speed available for the current system clock frequency. 5.7.3.2 Release Notes MPLAB Harmony Version: v0.70b Device Control System Service Library Version : 0.1 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3363 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.3.4 Using the Library This topic describes the basic architecture of the Device Control System Service Library and provides information and examples on how to use it. Interface Header File: sys_devcon.h The interface to the Device Control System Service library is defined in the "sys_devcon.h" header file. This file is included by the "system.h" file. Any C language source (.c) file that uses the Device Control System Service library should include "system.h". Library File: The Device Control System Service library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the System Service interacts with the framework. 5.7.3.4.1 Abstraction Model This topic provides a description of the software abstraction for the Device Control System Service. Description Device Control Software Abstraction Block Diagram The Device Control System Service configures the device for maximum performance given the current system clock speed. The system clock is retrieved using the System Clock service when the Device Control service is initialized. For this reason, the System Clock Service must be initialized prior to the Device Control Service. The Device Control Service increases performance by: • Minimizing the number of wait states inserted in an instruction fetch from Program Flash Memory (PFM). • Minimizing the number of wait states inserted in a CPU access to Data RAM Memory (DRM) (PIC32MX only). • Enabling the prefetch logic in the Prefetch Cache module. • Setting the peripheral bus clock to the maximum speed (PIC32MX only). 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3364 5.7.3.4.2 Library Overview Refer to the section System Services Overview for how the system services operates in a system. The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Device Control module. Library Interface Section Description System Interaction Functions Provides system module APIs. Device initialization, de-initialization, re-initialization and status functions. Core Functionality Configures Device based on current system clock 5.7.3.4.3 How the Library Works 5.7.3.4.3.1 System Interaction Initialization and Reinitialization Initialization of the Device Control System Service initializes an internal data structure that stores the current system clock frequency. Any time the system clock is changed, the Device Control system service should be reinitialized. The system clock is read using the Clock System Service. Therefore, the Clock System Service must be initialized prior to initializing the Device Control System Service. The Device Control Status and Tasks routines are provided as stubs for future enhancement. They are not currently required for this system service. 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3365 5.7.3.4.3.2 Core Functionality The Device Control System Service currently provides a single API to configure the device for maximum performance. It uses the current clock frequency stored in an internal data structure to tune the wait states, enable the prefetch buffer and set the peripheral clock (PIC32MX only) for maximum performance. The API takes no arguments and returns void. SYS_DEVCON_PerformanceConfig() 5.7.3.5 Configuring the Library Macros Name Description SYS_DEVCON_PIC32MX_MAX_PB_FREQ This is macro SYS_DEVCON_PIC32MX_MAX_PB_FREQ. SYS_DEVCON_PRIMARY_CLOCK This is macro SYS_DEVCON_PRIMARY_CLOCK. SYS_DEVCON_SYSTEM_CLOCK This is macro SYS_DEVCON_SYSTEM_CLOCK. Description The configuration of the Device Control system service is based on the file sys_config.h This header file contains the configuration selection for the Device Control system service. Based on the selections made, the Device Control system service will support or not support selected features. These configuration settings will apply to all instances of the Device Control system service. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.7.3.5.1 Others Three configuration options exist for the Device Control System Service. SYS_DEVCON_PRIMARY_CLOCK: Primary oscillator frequency. Not currently used. SYS_DEVCON_SYSTEM_CLOCK: System clock frequency. Retrieved using the System Clock Service. Not currently used. SYS_DEVCON_PIC32MX_MAX_PB_FREQ: Maximum peripheral bus clock frequency. Required for PIC32MX devices only. 5.7.3.5.2 Examples - Sample Functionality /* Primary Oscillator clock frequency Summary: Sets up the Primary Oscillator clock frequency. Description: This macro sets up the Primary Oscillator clock frequency. Remarks: None. 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3366 */ #define SYS_DEVCON_PRIMARY_CLOCK 24000000L // ***************************************************************************** /* System Clock frequency Summary: Sets up the System clock frequency. Description: This macro sets up the System clock frequency. Remarks: None. */ #define SYS_DEVCON_SYSTEM_CLOCK 200000000L // ***************************************************************************** /* PIC32MX Max Peripheral Bus Frequency Summary: Defines the maximum peripheral bus clock frequency for PIC32MX. Description: This macro defines the maximum peripheral bus clock frequency for PIC32MX. Remarks: None. */ #define SYS_DEVCON_PIC32MX_MAX_PB_FREQ 80000000L 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3367 5.7.3.5.3 SYS_DEVCON_PIC32MX_MAX_PB_FREQ Macro C #define SYS_DEVCON_PIC32MX_MAX_PB_FREQ 80000000L Description This is macro SYS_DEVCON_PIC32MX_MAX_PB_FREQ. 5.7.3.5.4 SYS_DEVCON_PRIMARY_CLOCK Macro C #define SYS_DEVCON_PRIMARY_CLOCK 24000000L Description This is macro SYS_DEVCON_PRIMARY_CLOCK. 5.7.3.5.5 SYS_DEVCON_SYSTEM_CLOCK Macro C #define SYS_DEVCON_SYSTEM_CLOCK 200000000L Description This is macro SYS_DEVCON_SYSTEM_CLOCK. 5.7.3.6 Building the Library This section list the files that are available in the \src of the Device Control System Service. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. sys_devcon.c 5.7.3.7 Library Interface Data Types and Constants Name Description SYS_DEVCON_HANDLE Identifies a particular registered event instance. SYS_DEVCON_INIT Identifies the system timer initialize structure. SYS_DEVCON_INDEX_0 Device Control System Service index definitions. System Interaction Functions Name Description SYS_DEVCON_Deinitialize Deinitializes the specific module instance of the DEVCON module SYS_DEVCON_Initialize Initializes data for the instance of the Device Control module and opens the specific module instance. SYS_DEVCON_PerformanceConfig Configures the PFM wait states and prefetch (cache) module for maximum performance. 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3368 SYS_DEVCON_Reinitialize Reinitializes and refreshes the hardware for the instance of the Device Control module. SYS_DEVCON_Status Returns status of the specific instance of the Device Control module. SYS_DEVCON_Tasks Maintains the system Device Control state machine. SYS_Initialize Function that initializes all modules in the system. Description 5.7.3.7.1 System Interaction Functions 5.7.3.7.1.1 SYS_DEVCON_Deinitialize Function C void SYS_DEVCON_Deinitialize( SYS_MODULE_OBJ object ); Description This function deinitializes the specific module instance disabling its operation (and any hardware for driver modules). Resets all of the internal data structures and fields for the specified instance to the default settings. Preconditions The SYS_DEVCON_Initialize function should have been called before calling this function. Parameters Parameters Description object SYS DEVCON object handle, returned from SYS_DEVCON_Initialize Returns None. Example SYS_MODULE_OBJ object; // Returned from SYS_DEVCON_Initialize SYS_STATUS status; SYS_DEVCON_Deinitialize (object); status = SYS_DEVCON_Status (object); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the SYS DEVCON is deinitialized. } Remarks: Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. 5.7.3.7.1.2 SYS_DEVCON_Initialize Function C SYS_MODULE_OBJ SYS_DEVCON_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3369 Description This function initializes the instance of the Device Control module, using the specified initialization data. It also initializes any internal data structures. Preconditions None. Parameters Parameters Description index Index for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the Device Control module. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to an object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to SYS_DEVCON_Reinitialize, SYS_DEVCON_Deinitialize, SYS_DEVCON_Tasks and SYS_DEVCON_Status routines. Example SYS_MODULE_OBJ objectHandle; SYS_DEVCON_INIT initConfig; // Populate the devcon initialization structure initConfig.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; initConfig.sysOscFreq = CONFIG_OSC_FREQ; objectHandle = SYS_DEVCON_Initialize (SYS_DEVCON_INDEX_0, (SYS_MODULE_INIT*)&initConfig); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Remarks: This routine should only be called once during system initialization unless SYS_DEVCON_Deinitialize is first called to deinitialize the device instance before reinitializing it. If the system was already initialized it safely returns without causing any disturbance. 5.7.3.7.1.3 SYS_DEVCON_PerformanceConfig Function C void SYS_DEVCON_PerformanceConfig(); Description This function configures the PFM wait states and prefetch (cache) module for maximum performance. Preconditions The SYS_DEVCON_Initialize function should have been called before calling this function. Returns None. Example SYS_DEVCON_PerformanceConfig(); Remarks: None. 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3370 5.7.3.7.1.4 SYS_DEVCON_Reinitialize Function C void SYS_DEVCON_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); Description This function reinitializes the instance of the Device Control module using the supplied data. It modifies the internal data structure. Preconditions The SYS_DEVCON_Initialize function should have been called before calling this function. Parameters Parameters Description object Identifies the SYS DEVCON Object returned by the Initialize interface init Pointer to the data structure containing any data necessary to initialize the hardware Returns None Example SYS_MODULE_OBJ objectHandle; SYS_DEVCON_INIT initConfig; SYS_STATUS devconStatus; // Populate the timer initialization structure initConfig.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; initConfig.sysOscFreq = CONFIG_OSC_FREQ; SYS_DEVCON_Reinitialize (objectHandle, (SYS_MODULE_INIT*)&initConfig); devconStatus = SYS_DEVCON_Status (object); if (SYS_STATUS_ERROR >= devconStatus) { // Handle error } Remarks: This operation uses the same initialization data structure as the SYS_DEVCON_Initialize operation. This operation can be used to change the power state of a DEVCON module. This function can be called multiple times to reinitialize the module. This operation uses the same initialization data structure as the Initialize operation. This operation can also be used to refresh the hardware registers as defined by the initialization data. 5.7.3.7.1.5 SYS_DEVCON_Status Function C SYS_STATUS SYS_DEVCON_Status( SYS_MODULE_OBJ object ); Description This function returns the status of the specific module instance disabling its operation (and any hardware for driver modules). 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3371 Preconditions The SYS_DEVCON_Initialize function should have been called before calling this function. Parameters Parameters Description object SYS DEVCON object handle, returned from SYS_DEVCON_Initialize Returns SYS_STATUS_READY - Indicates that any previous operations have succeeded and the module is ready for additional operations. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR. Example SYS_MODULE_OBJ object; // Returned from SYS_DEVCON_Initialize SYS_STATUS tmrStatus; devconStatus = SYS_DEVCON_Status (object); else if (SYS_STATUS_ERROR >= devconStatus) { // Handle error } Remarks: Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. 5.7.3.7.1.6 SYS_DEVCON_Tasks Function C void SYS_DEVCON_Tasks( SYS_MODULE_OBJ object ); Description This function is used to maintain the system Device Control internal state machine. Preconditions The SYS_DEVCON_Initialize function must have been called for the specified DEVCON driver instance. Parameters Parameters Description object SYS DEVCON object handle, returned from SYS_DEVCON_Initialize Returns None 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3372 Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. Example SYS_MODULE_OBJ object; // Returned from SYS_DEVCON_Initialize while (true) { SYS_DEVCON_Tasks (object); // Do other tasks } 5.7.3.7.1.7 SYS_Initialize Function C void SYS_Initialize( void * data ); Description System Initialization Function This function initializes all modules in the system, including any drivers, services, middleware, and applications. Preconditions None. Parameters Parameters Description data Pointer to the data structure containing any data necessary to initialize the module. This pointer may be null if no data is required and default initialization is to be used. Returns None. Remarks This function will only be called once, after system reset. Example SYS_Initialize ( NULL ); while ( true ) { SYS_Tasks ( ); } 5.7.3.7.2 Data Types and Constants 5.7.3.7.2.1 SYS_DEVCON_HANDLE Type C typedef int8_t SYS_DEVCON_HANDLE; 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3373 Description SYS DEVCON Handle This event handle identifies a registered instance of an event. Every time the application that tries to access the paramateres with respect to a particular event, shall used this event handle to refer to that event. Remarks None. 5.7.3.7.2.2 SYS_DEVCON_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; uint32_t sysOscFreq; } SYS_DEVCON_INIT; Description SYS DEVCON Initialize structure This structure identifies the system timer initialize structure. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization uint32_t sysOscFreq; System Oscillator Frequency in Hertz Remarks None. 5.7.3.7.2.3 SYS_DEVCON_INDEX_0 Macro C #define SYS_DEVCON_INDEX_0 0 Description SYS Device Control Module Index Numbers These constants provide Device Control System Service index definitions. Remarks These constants should be used in place of hard-coded numeric literals. 5.7.3.8 Files Files Name Description sys_devcon.h Device Control System Service interface definition. sys_devcon_config.h Device Control System Service configuration templates. Description 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3374 5.7.3.8.1 sys_devcon.h Device Control System Service Interface Definition This file contains the interface definition for the Device Control System Service. It provides a way to interact with the Device Control subsystem to manage the device control requests supported by the system. Functions Name Description SYS_DEVCON_Deinitialize Deinitializes the specific module instance of the DEVCON module SYS_DEVCON_Initialize Initializes data for the instance of the Device Control module and opens the specific module instance. SYS_DEVCON_PerformanceConfig Configures the PFM wait states and prefetch (cache) module for maximum performance. SYS_DEVCON_Reinitialize Reinitializes and refreshes the hardware for the instance of the Device Control module. SYS_DEVCON_Status Returns status of the specific instance of the Device Control module. SYS_DEVCON_Tasks Maintains the system Device Control state machine. Macros Name Description SYS_DEVCON_INDEX_0 Device Control System Service index definitions. Structures Name Description SYS_DEVCON_INIT Identifies the system timer initialize structure. Types Name Description SYS_DEVCON_HANDLE Identifies a particular registered event instance. File Name sys_devcon.h Company Microchip Technology Inc. 5.7.3.8.2 sys_devcon_config.h Device Control System Service Configuration Templates This file contains constants to configure the Device Control System Service. Macros Name Description SYS_DEVCON_PIC32MX_MAX_PB_FREQ This is macro SYS_DEVCON_PIC32MX_MAX_PB_FREQ. SYS_DEVCON_PRIMARY_CLOCK This is macro SYS_DEVCON_PRIMARY_CLOCK. SYS_DEVCON_SYSTEM_CLOCK This is macro SYS_DEVCON_SYSTEM_CLOCK. File Name sys_devcon_config_template.h 5.7 System Service Library Help MPLAB Harmony Help Device Control System Service Library 5-3375 Company Microchip Technology Inc. 5.7.4 File System Service Library 5.7.4.1 Introduction Introduction to the MPLAB Harmony File System (FS). Description The MPLAB Harmony File System (FS) provides file system services to MPLAB Harmony based applications. Figure 1 shows the architecture of the File System Service. Figure 1: File System Architecture The File System Service provides an application programming interface (API) through which a utility or user program requests services of a file system. Some file system APIs may also include interfaces for maintenance operations, such as creating or initializing a file system and verifying the file system for integrity. The File System service is really a framework designed to support multiple file systems (native file system) and multiple media in the same application. Examples of native file systems are FAT12, FAT32, MPFS, and JFS, among others. Each of these native file systems have a common set of APIs that can be used to access the files of that particular native file system. The File System Service abstracts the native file system calls and provides a common interface to the user/application layer. For example, while the application layer requests for a file read or write from a disk, due to the presence of the this abstraction, the application need not be bothered about the native file system implemented on that disk. Instead, the application can call the 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3376 read/write API of the File System, which in turn translates to the read/write command of the native file system used on the required disk. This simplifies the implementation of the higher application layer and also provides a mechanism to add more native file system to the File System framework in the future. Note: Throughout this document, "File System Service" and "sys_fs" are used interchangeably. 5.7.4.2 Release Notes MPLAB Harmony Version: v0.70b File System Service Library Version : 0.1 Release Date: 18Nov2013 New in This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. • Supports multiple file systems. Presently, FAT FS and MPFS are the two native file systems that are supported. • Supports multiple media. • Supports both static media (SD card, non-volatile memory, etc.) and dynamic media (mass storage device). • Supports long file names for files. • Supports media with multiple partitions. Known Issues: • Does not work in MIPS16 mode. • For some SD cards, reading or writing data of more than 1 sector (512Bytes) causes random junk characters to be inserted in the data. Hence, it is advised to read or write 512Bytes or lesser at a time. • SD cards (size 2 GB or less) do not work with the present version of File system. Only SDHC cards work. • Hardware switch-based write protection feature is not implemented for SD cards. • Since the FS demonstration codes do not have an integrated real-time clock module, the time is set internally to a fixed value of 9th August 2013, 3:06pm (in the file diskio.c). • Not all functions (such as directory related functions) from native FAT FS are supported in the present version of the MPLAB Harmony FS. For the list of implemented functions, please refer to the Library Interface section. • SD cards do not support dynamic card insertion. To use an SD card, the card has to be inserted before running the code execution. • Testing on multi-partitioned media was not carried out extensively. 5.7.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3377 CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.4.4 Getting Started This topic provides an introduction to the MPLAB Harmony File System. Description The MPLAB Harmony File System (FS) provides embedded application developers with a file system framework for retrieving and storing data from various media. The MPLAB Harmony file system is designed to support multiple file systems (native file systems) and multiple media at the same time. Examples of native file systems are FAT12, FAT32, MPFS, and JFS, among others. Each of these native file systems has a common set of APIs that can be used to access the files of that particular native file system. The FS is a part of the MPLAB Harmony installation and is accompanied by demonstration applications that highlight usage. These demonstrations can also be modified or updated to build custom applications. FS features include the following: • Support for multiple file system (FAT, MPFS) • Supports multiple physical media (NVM, SD card) • More physical media can be interfaced with the FS, once the driver is available for the media • Modular and Layered architecture 5.7.4.4.1 Architecture This topic describes the architecture of the MPLAB Harmony File System. Description The FS framework features a modular and layered architecture, as shown in Figure 1. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3378 Figure 1: FS Framework Architecture As seen in Figure 1, the FS Framework consists of the following major blocks: • The Driver for the physical media has to be included as a part of the FS Framework. This layer provides a low-level interface to access the physical media. This layer also enables multiple instances of media. Examples of drivers are: • NVM driver – To access files using NVM (Flash memory) • SPI driver – To access files from SD card, which interfaces using the SPI peripheral • The Media driver provides a mechanism to access the media as “sectors”. Sectors are the smallest storage element accessed by a file system and are contiguous memory locations. Typically, each sector has 512 bytes. Depending on the requirement, in some cases, the driver and media driver could be combined as one layer. • The Media manager implements a disk and sector based media access mechanism. It also performs disk allocated/deallocated on media attach/detach. Due to the implementation of this layer, the FS Framework can support multiple disks. • The Native file system implements support for the media file system format. Examples of native file systems are: FAT12, FAT32, and MPFS, among other. At present, only the FAT and MPFS files systems are supported by the FS framework; however, more native file systems can be included. • The Virtual file system (or SYS_FS ) layer provides a file system independent file system operation interface. This layer translates virtual file systems calls to native file system calls. Due to this layer, applications can now support multiple file systems. Interfaces provided by this layer, but not limited to, include: • SYS_FS_mount • SYS_FS_open • SYS_FS_read • SYS_FS_write • SYS_FS_close 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3379 5.7.4.4.2 Application Interaction This topic describes how an application must interact with the File System. Description The interaction of various layers is shown in Figure 1. Figure 1: Application Interaction with FS Framework In the process of using the FS Framework, the application must first mount the media drive for the FS Framework to access the media. Unless the mounting process returns successfully, the application should continue trying to mount the drive. If the drive is not attached, the mounting process will fail. In such a situation, the application should not proceed further unless the mounting is success. Figure 2: Application Mounts a Drive Once the drive is mounted, the application code can then open the file from the drive with different attributes (such as read-only or write). If the file open returns a valid handle, the application can proceed further. Otherwise, the application will enter an error state. The reason for an invalid handle could be that the application was trying to read a file from the drive that does not exist. Another reason for an invalid handle is when the application tries to write to a drive that is write-protected. Once the file is opened, the valid file handle is further used to read/write data to the file. Once the required operation is performed on the file, the file can then be closed by the application by passing the file handle. Figure 3 illustrates the process. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3380 Figure 3: Further File System Operations 5.7.4.4.3 Using the File System This topic describes how to use the File System. Description Use the Available Library Demonstration Applications The FS framework release package contains a set of demonstration applications that are representative of common scenario (single/multi-media and single/multi-native file systems). These demonstrations can be easily modified to include application-specific initialization and application logic. The application logic must be non-blocking and could be implemented as a state machine. • The application specific initialization can be called in the SYS_Initialize() function (in the sys_init.c file). The SYS_Initialize is called when the device comes out of Power-on Reset (POR). • The application logic can be called in the SYS_Tasks() function (in the sys_tasks.c file). The application logic can interact with the FS layer by using relevant API calls, as provided in the APP_Tasks() (in the app.c file) Building a FS Application from Scratch In a case where the available demonstration applications do not meet the end application requirements, an application to use the FS framework can be created by from scratch. Figure 1 shows a flowchart for the steps that need to be performed. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3381 Figure 1: Steps to create a FS Application Step 1: Create a MPLAB Project and add the required FS framework files to the project. The following files are needed to build the a FS project • system_config.h - This file should contain the compile time configuration macros for the Driver, Media Layer, and FS layer. The file also contains the clock speed setting, which is set for the microcontroller. • system_init.c – This file should contain the initial settings for each driver. It should also call the functions required to initialize different drivers to be used by the FS. • ff.c, diskio.c, mpfs.c, sys_fs.c, sys_fs_media_manager.c – These files are part of the FS, which must be included in the project • sys_int_pic32.c and plib_int_pic32.c - These files implement the system interrupt service that is required by the FS • sys_ports.c – If the FS is using a SD card as media, this file needs to be included (for Chip Select) • Driver – The driver for media to be used by FS should also be included • Application specific files - These file will implement the application logic Step 2: Since the MPLAB Harmony drivers included with the File System operate in interrupt mode, a driver Handler should be defined as follows: /* Use this for PIC32MX */ void __ISR ( _SPI1_VECTOR,ipl4 ) _InterruptHandler_SPI_stub ( void ) { DRV_SPI_Tasks((SYS_MODULE_OBJ)appDrvObjects.drvSPIObject); } /* Use this for PIC32MZ */ void __ISR ( _SPI2_RX_VECTOR,ipl4 ) _InterruptHandler_SPI_RX_stub ( void ) { DRV_SPI_Tasks((SYS_MODULE_OBJ)appDrvObjects.drvSPIObject); } void __ISR ( _SPI2_TX_VECTOR,ipl4 ) _InterruptHandler_SPI_TX_stub ( void ) { DRV_SPI_Tasks((SYS_MODULE_OBJ)appDrvObjects.drvSPIObject); } 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3382 Step 3: The application should create a while(1) loop that continuously updates the driver layer State Machine and the application state machine. This requires the application state machine to be non-blocking. /* This while(1) loop will continuously update the driver layer state machine and the application state machine */ while(1) { /* Task routine for sys_fs */ SYS_FS_Tasks(); /* Call the SDCARD Task */ DRV_SDCARD_Tasks(appDrvObjects.drvSDCARDObject); /* Call the application's tasks routine */ APP_Tasks ( ); } Step 4: If interrupt-based operation is needed, the interrupts need to be enabled first. The application should then initialize the driver layer. Refer to the driver specific documents regarding usage. /* Initialize the interrupt system */ SYS_INT_Initialize(); /* Initialize the global interrupts */ SYS_INT_Enable(); /* set priority for SPI interrupt source */ SYS_INT_VectorPrioritySet(INT_VECTOR_SPI1, INT_PRIORITY_LEVEL3); /* set sub-priority for SPI interrupt source */ SYS_INT_VectorSubprioritySet(INT_VECTOR_SPI1, INT_SUBPRIORITY_LEVEL3); /* Initialize the global interrupts */ SYS_INT_Enable(); /* Initialize the SPI driver */ appDrvObjects.drvSPIObject = DRV_SPI_Initialize(DRV_SPI_INDEX_0, (SYS_MODULE_INIT *)&drvSPIInit); /* Initialize the SDCARD driver*/ appDrvObjects.drvSDCARDObject = DRV_SDCARD_Initialize(DRV_SDCARD_INDEX_0, (SYS_MODULE_INIT *)&drvSDCARDInit); Step 5: The application code can be implemented as a non-blocking state machine inside the APP_TASKS() function, as shown below for an application to read a file and write the content into another newly created file. The input file "TEST.JPG" is not provided with the release package. It could be any arbitrary JPEG file chosen by the user, and then suitably renamed to "TEST.JPG". The reason for choosing a JPEG file for test purposes is that the duplicate file "TEST1.JPG" created by the FS demonstration could be easily verified for correctness by inserting the SD card in the computer and opening the "TEST1.JPG" file. void APP_Tasks ( void ) { /* The application task state machine */ switch(appData.state) { 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3383 case APP_MOUNT_DISK: if(SYS_FS_Mount("/dev/mmcblka1", "/mnt/myDrive", FAT, 0, NULL) != 0) { /* The disk could not be mounted. Try * mounting again untill success. */ appData.state = APP_MOUNT_DISK; } else { /* Mount was successful. Open a file. * Let the switch case fall through. */ appData.state = APP_OPEN_FILE; } break; case APP_OPEN_FILE: appData.fileHandle = SYS_FS_FileOpen("/mnt/myDrive/TEST.JPG", (FA_READ)); if(appData.fileHandle == SYS_FS_HANDLE_INVALID) { /* Could not open the file. Error out*/ appData.state = APP_ERROR; } else { appData.fileHandle1 = SYS_FS_FileOpen("/mnt/myDrive/TEST1.JPG", (FA_WRITE|FA_CREATE_ALWAYS)); if(appData.fileHandle == SYS_FS_HANDLE_INVALID) { /* Could not open the file. Error out*/ appData.state = APP_ERROR; } else { /* Check the file to be read */ appData.state = APP_CHECK_FILE; } } break; case APP_CHECK_FILE: /* check the size of file */ fileSize = SYS_FS_FileSize(appData.fileHandle); /* since, we will read 512 bytes at a time, find the number of times, the read has to be performed */ sectorCounter = integralSector = (fileSize/512); /* find the remaining bytes */ balanceSector = (fileSize%512); appData.state = APP_READ_WRITE_TO_FILE; break; case APP_READ_WRITE_TO_FILE: if(SYS_FS_FileRead((void *)appData.data, 512, appData.fileHandle) == -1) { /* There was an error while reading the file. * Close the file and error out. */ SYS_FS_FileClose(appData.fileHandle); appData.state = APP_ERROR; } 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3384 else if(SYS_FS_FileWrite((const void *)appData.data, 512, appData.fileHandle1) == -1) { /* Write was not successful. Close the file * and error out.*/ SYS_FS_FileClose(appData.fileHandle1); appData.state = APP_ERROR; } else { sectorCounter--; /* if entire integral sectors are written, then write the balance sector*/ if(sectorCounter == 0) { if(SYS_FS_FileRead((void *)appData.data, balanceSector, appData.fileHandle) == -1) { /* There was an error while reading the file. * Close the file and error out. */ SYS_FS_FileClose(appData.fileHandle); appData.state = APP_ERROR; } else if(SYS_FS_FileWrite((const void *)appData.data, balanceSector, appData.fileHandle1) == -1) { /* Write was not successful. Close the file * and error out.*/ SYS_FS_FileClose(appData.fileHandle1); appData.state = APP_ERROR; } else { appData.state = APP_CLOSE_FILE; } } } break; case APP_CLOSE_FILE: /* Close both files */ SYS_FS_FileClose(appData.fileHandle); SYS_FS_FileClose(appData.fileHandle1); /* The test was successful. Lets idle. */ appData.state = APP_IDLE; break; case APP_IDLE: /* The appliction comes here when the demo * has completed successfully. Switch on * green LED. */ BSP_SwitchONLED(LED_2); break; case APP_ERROR: /* The appliction comes here when the demo * has failed. Switch on the red LED.*/ BSP_SwitchONLED(LED_1); break; default: break; } } //End of APP_Tasks 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3385 5.7.4.5 Migration Guide This section provides information for migrating an existing File System (FS) application that uses legacy MLA code to MPLAB Harmony. Description The topics covered include: • Initialization • System Configuration • Mounting a Volume • Opening a File • Reading a File • Writing a File • Closing a File • File EOF • File Tell • File Seek • SYS_FS_Tasks In each topic, differences between the legacy MLA code and MPLAB Harmony are described and examples are provided to assist with the migration. 5.7.4.5.1 Comparison of API Names This topic tabulates the API names for MLA vs. the name for MPLAB Harmony. Description API Name in MLA API Name in MPLAB Harmony N/A SYS_FS_Mount N/A SYS_FS_Unmount N/A SYS_FS_FileError FSInit SYS_FS_Initialize N/A SYS_FS_Tasks Fsfclose SYS_FS_FileClose Fsfeof SYS_FS_FileEOF FSfread SYS_FS_FileRead FSftell SYS_FS_FileTell FSfwrite SYS_FS_FileWrite N/A SYS_FS_FileSize wFSfopen SYS_FS_FileOpen N/A SYS_FS_FileStat FSfseek SYS_FS_FileSeek 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3386 5.7.4.5.2 Initialization This topic describes the differences in initialization. Description MLA Initialization (Legacy code): In legacy MLA code, the initialization involves modification of the header file "HardwareProfile.h". The header file has definitions for the SPI modules used (SPI1 or SPI2), configuration for SPI module, clock frequency, pin mapping for SD card, and pin remapping for SPI (SDI, SDO and SCLK pins). The following two images illustrate these modifications. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3387 Inside the main() function, the initialization of interrupts and the clock occurs in a series of function calls. Then, the media detect function is called for the media used. Later, the FS init function is called, which internally performs the disk mount, and if the mount process and FS initialization is successful, the functions returns as "1". MPLAB Harmony Initialization: In the case of MPLAB Harmony, the initialization is done by the sys_initialize() function, which is called from the main() function. Inside the sys_initialize() function, the BSP, interrupt, clock, port remapping, driver initialization, FS initialization and application-specific initialization is done. All initialization is done by calling specific system function calls, as shown in the following image. For more information, refer to the demonstration code provided as a part of the MPLAB Harmony release 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3388 package. The SPI module selection and configuration of the SPI module is done through the SPI driver initialization structure. Similarly, the selection of pins related to SD card functionality and the selection of the SPI clock frequency is done through the SD card driver initialization structure. The initialization structures are passed as input parameters during driver initialization function calls. There are no #define used, as was done in the case of legacy MLA code. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3389 Since MPLAB Harmony supports multiple file systems, there is a structure which needs to be defined and then passed as an input parameter to the SYS_FS_Init() function. 5.7.4.5.3 System Configuration This topic describes differences in system configuration. Description system_config.h file in MPLAB Harmony: The file "system_config.h" contains the various system configurations required to run an application. Examples of system configurations related to, but not limited to drivers are: • SPI driver configuration: such as DRV_SPI_INSTANCES_NUMBER, DRV_SPI_CLIENTS_NUMBER, 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3390 DRV_SPI_INTERRUPT_MODE, DRV_SPI_BUFFER_SIZE, etc. • SD Card driver configuration: such as DRV_SDCARD_INSTANCES_NUMBER, DRV_SDCARD_CLIENTS_NUMBER, DRV_SDCARD_QUEUE_POOL_SIZE, etc. These configurations are required to configure the drivers used for the FS. Since the driver concept was not present in the legacy MLA code, this is a new addition to MPLAB Harmony. To get detailed information about each of the configuration parameter, please refer to the driver help. Media manager configuration: • SYS_FS_MEDIA_NUMBER - Number of media that will be used in the application. For example, if the application uses SD card and Mass storage device the SYS_FS_MEDIA_NUMBER should be defined as 2. • SYS_FS_VOLUME_NUMBER - Number of volumes that will be used in the application. MPLAB Harmony supports multi-partitioned media. If the application uses a SD card that has three partitions and a Mass storage device, which has one partition, the SYS_FS_VOLUME_NUMBER should be defined as 4. • Clock related configurations are present in the file, which are used to set the clock for the device File system related configuration: • SYS_FS_MAX_FILE_SYSTEM_TYPE - Number of native file system that will be used in the application. MPLAB Harmony supports multiple native file systems. If the application uses two file systems, FAT FS and MPFS2, SYS_FS_MAX_FILE_SYSTEM_TYPE should be defined as 2. • SYS_FS_MAX_FILES - Maximum number of files that will be opened by the application at a time • Other application-specific configuration settings SYS_Tasks() in MPLAB Harmony: In the case of MPLAB Harmony, certain tasks need to be executed periodically. These tasks are executed from a common function called SYS_Tasks(), which is in turn called from the main loop (while(1)) loop. While the concept of running certain functions from the main loop is not new, the legacy MLA demonstration code did not have any functions that had to run from the main loop.However, in case of MPLAB Harmony, it is mandatory that certain tasks should be running periodically from the main loop. In the case of the FS application, tasks that have to run from SYS_Tasks() function are: • SYS_FS_Tasks() - This task maintains the working of the SYS_FS layer and other file system related layers. It is extremely essential that this function runs periodically from the SYS_Tasks() function. • Driver task - Consider a case where the FS application uses a SD card -- there is no hardware module that controls the SD card. In such a case, the task routine for the SD card must run from SYS_Tasks(). This is required so that the internal driver mechanism for the SD card continues working. • Any other application related task 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3391 5.7.4.5.4 Mounting a Volume This topic describes differences when mounting a volume. Description Mounting a Volume in MLA vs. MPLAB Harmony: In case of MLA, the complete mounting of a volume was achieved by calling the two functions, MDD_MediaDetect() and FSInit(), until the function returns success. The features of mounting a volume in MLA were: • There are two functions that completely achieve the mounting process • Both functions were of input type as "void" (no input argument) • Both functions were called in blocking mode In the case of MPLAB Harmony, the mounting of a volume is achieved by calling the SYS_FS_Mount() function, until the function returns success. The features of mounting a volume in MPLAB Harmony are: • SYS_FS_Mount() function includes both media detection and mounting the volume. Please note that, MPLAB Harmony FS still needs the function SYS_FS_Initialize() to be called during system initialization. Though the name SYS_FS_Initialize() seems similar to the MLA function FSInit(), the task achieved by calling these functions are very different. • SYS_FS_Initialize() (MPLAB Harmony function) - Just does the initialization of SYS_FS layer. It does not do any mounting of volumes. • FSInit() (MLA function) - Did the initialization of FS and also did mount the disk. • SYS_FS_Mount() function accepts input parameter such as devName, mntName, fileSystemType etc. To know each of the parameter in detail, pleas refer to the documentation of the SYS_FS_Mount() function. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3392 • SYS_FS_Mount() has to be running in a non-blocking mode. The following image shows an application where SYS_FS_Mount() is called from the state machine implementation. This is required as the implementation of the state machine allows the SYS_Tasks() function to be run periodically. This is quite different from the earlier implementations of MLA. 5.7.4.5.5 Opening a File This topic describes differences when opening a file. Description Opening a file in MLA vs. MPLAB Harmony: Opening a file remains similar for both MLA and MPLAB Harmony. However, a critical difference in MPLAB Harmony is that, while opening the file, the complete path of the file must be specified. In addition, the path must be preceded by the string "/mnt/". The complete path is required because the MPLAB Harmony FS implements a multi-partition media support. Therefore, the file path should include the name of volume (assigned media partition), and from where the file is to be opened. For more details, please refer to the documentation of the SYS_FS_FileOpen() function. The following two figures illustrate opening a file in MLA vs. MPLAB Harmony. In case of MLA, the error in opening a file was indicated by the file open function returning a NULL, while, in MPLAB harmony, the file open returns SYS_FS_HANDLE_INVALID. Figure 1: Opening a File in MLA Figure 2: Opening a File in MPLAB Harmony 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3393 5.7.4.5.6 Reading a File This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while reading a file. Description Reading a file in MLA vs. MPLAB Harmony: Reading a file remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The smaller differences are that, the name of the function to read the file is different, the order of parameters passed are different and MPLAB Harmony only takes 3 parameters. The MPLAB Harmony function only enables byte based access. Though, both MLA and MPLAB harmony file read functions returns the number of bytes read, the MPLAB Harmony functions also returns “-1” if there were any errors while reading the file. Figure: Reading a File in MLA Figure: Reading a File in MPLAB Harmony 5.7.4.5.7 Writing a File This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while writing to a file. Description Writing to a file in MLA vs. MPLAB Harmony: Writing to a file remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The smaller differences are that, the name of the function to write to the file is different, the order of parameters passed are different and MPLAB Harmony only takes 3 parameters. The MPLAB Harmony function only enables byte based access. Though, both MLA and MPLAB harmony file read functions returns the number of bytes written, the MPLAB Harmony functions also returns “-1” if there were any errors while writing to the file. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3394 Figure: Writing to a File in MLA Figure: Writing to a File in MPLAB Harmony 5.7.4.5.8 Closing a File This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while closing a file. Description Closing a file in MLA vs. MPLAB Harmony: Closing a file remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The smaller difference is that, the name of the function is different. Figure: Closing a File in MLA Figure: Closing a File in MPLAB Harmony 5.7.4.5.9 File EOF This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while checking for end of file. Description Checking for EOF in MLA vs. MPLAB Harmony: The EOF function remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The smaller 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3395 difference is that, the name of the function is different. Figure: EOF in MLA Figure: EOF in MPLAB Harmony 5.7.4.5.10 File Tell This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while checking for file pointer (tell). Description Checking for file pointer (tell) in MLA vs. MPLAB Harmony: The function to check for file pointer (tell) remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The smaller difference is that, the name of the function is different. Figure: Tell Function in MLA Figure: Tell Function in MPLAB Harmony 5.7.4.5.11 File Seek This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS, while performing a file seek. Description File seek in MLA vs. MPLAB Harmony: The function to perform file seek remains similar for both MLA and MPLAB Harmony, as depicted in the screen shots below. The 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3396 smaller difference is that, the name of the function is different. Figure: File Seek in MLA Figure: File Seek in MPLAB Harmony 5.7.4.5.12 SYS_FS_Tasks This topic describes the differences between legacy MLA code for FS and MPLAB Harmony FS with respect to SYS_FS_Tasks() function. Description SYS_FS_Tasks() in MLA vs. MPLAB Harmony: The MPLAB Harmony needs the SYS_FS_Tasks() function to be running periodically from the SYS_Tasks() function. The MLA code did not had any such function which had to be running periodically. Figure: Running SYS_FS_Tasks() Function from SYS_Tasks() 5.7.4.6 Library Interface Data Types and Constants Name Description SYS_FS_ERROR Lists the various error cases SYS_FS_FILE_OPEN_ATTRIBUTES Lists the various attributes (modes) in which a file can be opened SYS_FS_FILE_SEEK_CONTROL Lists the various modes of file seek 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3397 SYS_FS_FILE_SYSTEM_TYPE Enumerated data type identifying native file systems supported. SYS_FS_FSTAT The structure to obtain the status of a file. SYS_FS_FUNCTIONS SYS FS Function signature structure for native file systems SYS_FS_HANDLE This type defines the file handle. SYS_FS_REGISTRATION_TABLE The sys_fs layer has to be initialized by passing this structure with suitably initialized members. SYS_FS_RESULT Lists the various results of a file operation FAT_FS_MAX_LFN Lists the maximum length of file name during LFN selection FAT_FS_MAX_SS Lists the definitions for FAT file system sector size. FAT_FS_USE_LFN Lists the definitions for FAT file system LFN selection SYS_FS_HANDLE_INVALID This definitions defines the SYS FS file invalid handle. File Operation Functions Name Description SYS_FS_FileClose Close a file. SYS_FS_FileEOF check handle status SYS_FS_FileOpen Open a file SYS_FS_FileRead Read specified bytes from a file SYS_FS_FileSeek Move the file pointer. SYS_FS_FileSize Returns the size of the file SYS_FS_FileStat Get file status SYS_FS_FileTell Obtains the file pointer position SYS_FS_FileWrite Write on the file SYS_FS_FileNameGet Reads the file name. General Operation Functions Name Description SYS_FS_FileError check the type of error SYS_FS_Initialize Initializes the File system Abstration Layer (sys_fs layer). SYS_FS_Mount Mount filesystems SYS_FS_Tasks Tasks for the sys_fs layer SYS_FS_Unmount unmount filesystems Description This section describes the Application Programming Interface (API) functions of the File System. 5.7.4.6.1 File Operation Functions 5.7.4.6.1.1 SYS_FS_FileClose Function C SYS_FS_RESULT SYS_FS_FileClose( SYS_FS_HANDLE handle ); Description The SYS_FS_FileClose() function closes an opened file 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3398 Preconditions A valid file handle must be obtained before closing a file. Parameters Parameters Description handle A valid handle, which was obtained while opening the file. Returns If Success - SYS_FS_RES_SUCCESS If Failure - SYS_FS_RES_FAILURE The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_HANDLE fileHandle; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... SYS_FS_FileClose(fileHandle); 5.7.4.6.1.2 SYS_FS_FileEOF Function C bool SYS_FS_FileEOF( SYS_FS_HANDLE handle ); Description Checks whether or not the file position indicator is at the end of the file. Preconditions A valid file handle must be obtained before knowing a file eof. Parameters Parameters Description handle file handle obtaind during file Open. Returns If Success - When file pointer has not reached the end of file - false When file pointer has reached the end of file - true If Failure - false The reason for failure could be retrieved with SYS_FS_Error 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3399 Remarks None Example SYS_FS_HANDLE fileHandle; bool eof; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... eof = SYS_FS_FileEOF(fileHandle); if(eof == false) { // could be not EOF or a failure // Check the error state using SYS_FS_FileError } 5.7.4.6.1.3 SYS_FS_FileOpen Function C SYS_FS_HANDLE SYS_FS_FileOpen( const char* fname, SYS_FS_FILE_OPEN_ATTRIBUTES attributes ); Description The SYS_FS_FileOpen opens a requested file in a specific mode (attaribute). Preconditions Prior to opening a file, the name of the volume on which the file resides should be known. Also, that volume should be already mounted. While opening the file, the name of the volume is to be passed along with the file name. Parameters Parameters Description path Path to the file along with the volume name. The string of volume and file name has to be preceeded by "/mnt/". Also, the volume name and file name has to be separated by a slash "/". attributes Access mode of the file, of the type SYS_FS_FILE_OPEN_ATTRIBUTES Returns If Success - Valid handle will be returned If Failure - Returned handle will be SYS_FS_HANDLE_INVALID The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_HANDLE fileHandle; 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3400 fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } 5.7.4.6.1.4 SYS_FS_FileRead Function C size_t SYS_FS_FileRead( void * buf, size_t nbyte, SYS_FS_HANDLE handle ); Description The SYS_FS_FileRead() function shall attempt to read nbyte bytes from the file associated with the file handle into the buffer pointed to by buf. Preconditions A valid file handle must be obtained before reading a file. Parameters Parameters Description handle File handle obtained during file open. buf Pointer to buffer into which data is read. nbyte Number of bytes to be read Returns If Success - The number of bytes successfully read (0 or positive number) If Failure - (-1) The reason for failure could be retrieved with SYS_FS_Error Remarks None Example ... char buf[20]; size_t nbytes; size_t bytes_read; SYS_FS_HANDLE fd; ... nbytes = sizeof(buf); bytes_read = SYS_FS_FileRead(buf, nbytes, fd); ... 5.7.4.6.1.5 SYS_FS_FileSeek Function C int32_t SYS_FS_FileSeek( SYS_FS_HANDLE fildes, int32_t offset, SYS_FS_FILE_SEEK_CONTROL whence 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3401 ); Description The SYS_FS_FileSeek() function shall set the file pointer for a open file associated with the file handle, as follows: If whence is SYS_FS_SEEK_SET, the file offset shall be set to offset bytes from the begining. If whence is SYS_FS_SEEK_CUR, the file offset shall be set to its current location plus offset. If whence is SYS_FS_SEEK_END, the file offset shall be set to the size of the file plus offset. If SYS_FS_SEEK_END is selected, then offset has to be a negative number, inorder for the file pointer to be valid. Trying to move the file pointer using SYS_FS_FileSeek, beyond the range of file will only cause the pointer to be moved to the last location of the file. Preconditions A valid file handle must be obtained before seeking a file. Parameters Parameters Description handle A valid file handle obtained during file open. offset The number of bytes which act as file offset. This value could be a positive or negative value. whence File seek control input of type SYS_FS_FILE_SEEK_CONTROL. Returns If Success - The number of bytes by which file pointer is moved (0 or positive number) If Failure - (-1) If the choosen offset value was (-1), then the success or failure can be ascertained with SYS_FS_Error. The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_HANDLE fileHandle; int status; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... status = SYS_FS_FileSeek(fileHandle, 5, SYS_FS_SEEK_CUR); if((status != -1) && (status == 5)) { // Success } 5.7.4.6.1.6 SYS_FS_FileSize Function C int32_t SYS_FS_FileSize( 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3402 SYS_FS_HANDLE handle ); Description Returns the size of the file as pointed by the handle. Preconditions A valid file handle must be obtained before knowing a file size. Parameters Parameters Description handle File handle obtained during file Open. Returns If Success - file size If Failure - (-1) The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_HANDLE fileHandle; long fileSize; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... fileSize = SYS_FS_FileSize(fileHandle); if(fileSize != -1) { // Success } 5.7.4.6.1.7 SYS_FS_FileStat Function C SYS_FS_RESULT SYS_FS_FileStat( const char* fname, SYS_FS_FSTAT * buf ); Description The SYS_FS_FileStat() function shall obtain information about a file associated with the file name, and shall write it to the structure pointed to by buf. The buf argument is a pointer to a SYS_FS_FSTAT structure,into which information is placed concerning the file. This function can read the status of file irrespective of a file is opened or not. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3403 Preconditions Prior to opening a file, the name of the volume on which the file resides should be known. Also, that volume should be already mounted. While opening the file, the name of the volume is to be passed along with the file name. Parameters Parameters Description path Path to the file along with the volume name. The string of volume and file name has to be preceeded by "/mnt/". Also, the volume name and file name has to be separated by a slash "/". buf pointer to SYS_FS_FSTAT structure. Returns If Success - SYS_FS_RES_SUCCESS If Failure - SYS_FS_RES_FAILURE The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_fStat fileStat; if(SYS_FS_FileStat("/mnt/myDrive/FILE.TXT", &fileStat) == SYS_FS_RES_SUCCESS) { // Successfully read the status of file "FILE.TXT" } 5.7.4.6.1.8 SYS_FS_FileTell Function C int32_t SYS_FS_FileTell( SYS_FS_HANDLE handle ); Description Obtains the current value of the file position indicator for the file, pointed to by handle. Preconditions A valid file handle must be obtained before performing a file tell. Parameters Parameters Description handle File handle obtained during file Open. Returns If Success - current file position If Failure - (-1) The reason for failure could be retrieved with SYS_FS_Error 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3404 Remarks None Example SYS_FS_HANDLE fileHandle; int32_t tell; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... tell = SYS_FS_FileTell(fileHandle); if(tell != -1) { // Success } 5.7.4.6.1.9 SYS_FS_FileWrite Function C size_t SYS_FS_FileWrite( const void * buf, size_t nbyte, SYS_FS_HANDLE handle ); Description The SYS_FS_FileWrite() function shall attempt to write nbyte bytes from the buffer pointed to by buf to the file associated with the file handle. Preconditions A valid file handle must be obtained before writing a file. Parameters Parameters Description handle File handle obtained during file open. buf Pointer to buffer from which data is to be written nbyte Number of bytes to be written Returns If Success - The number of bytes successfully written (0 or positive number) If Failure - (-1) The reason for failure could be retrieved with SYS_FS_Error Remarks None Example ... 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3405 const char *buf = "Hello World"; size_t nbytes; size_t bytes_written; SYS_FS_HANDLE fd; ... bytes_written = SYS_FS_FileWrite((const void *)buf, nbytes, fd); ... 5.7.4.6.1.10 SYS_FS_FileNameGet Function C bool SYS_FS_FileNameGet( SYS_FS_HANDLE handle, uint8_t* cName, uint16_t wLen ); Description Reads the file name of a file that is already open. Preconditions The file handle referenced by handle is already open. Parameters Parameters Description handle file handle obtaind during file Open. cName where to store the name of the file. wLen the maximum length of data to store in cName. Returns If Success - The file name was successfully located - true If Failure The file handle provided is not currently open - false The reason for failure could be retrieved with SYS_FS_Error Remarks None Example SYS_FS_HANDLE fileHandle; bool stat; uint8_t fileName[255]; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle != SYS_FS_HANDLE_INVALID) { // File open is successful } ... ... stat = SYS_FS_FileNameGet(fileHandle, fileName, 8 ); if(stat == false) { 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3406 // file not located based on handle passed // Check the error state using SYS_FS_FileError } 5.7.4.6.2 General Operation Functions 5.7.4.6.2.1 SYS_FS_FileError Function C SYS_FS_ERROR SYS_FS_FileError(); Description When a file system operation fails, the application can know the exact reason of failure by calling the SYS_FS_FileError. Preconditions This function has to be called immediately after a failure is observed while doing a file operation. Any subsequent failure will overwrite the cause of pervious failure. Returns Error code of type SYS_FS_ERROR Remarks None Example SYS_FS_HANDLE fileHandle; SYS_FS_ERROR err; fileHandle = SYS_FS_FileOpen("/mnt/myDrive/FILE.JPG", (SYS_FS_FILE_OPEN_READ)); if(fileHandle == SYS_FS_HANDLE_INVALID) { // If failure, now know the specific reason for failure err = SYS_FS_FileError(); } 5.7.4.6.2.2 SYS_FS_Initialize Function C SYS_FS_RESULT SYS_FS_Initialize( const void* initData ); Description Initializes the abstraction layer (sys_fs layer) and sets up the necessary parameters. Preconditions This is the first function to be called during usage of sys_fs. Calling other functions from sys_fs without initializing the sys_fs will cause un-predictable behavior. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3407 Parameters Parameters Description initData The pointer to array of the type SYS_FS_REGISTRATION_TABLE, but type casted to (const void *). The number of elements of array is decided by the definition SYS_FS_MAX_FILE_SYSTEM_TYPE. If the application uses 1 file system (say only FAT FS), then SYS_FS_MAX_FILE_SYSTEM_TYPE is defined to be 1. Otherwise, if the application uses 2 file systems (say FAT FS and MPFS2), then SYS_FS_MAX_FILE_SYSTEM_TYPE is defined to be 2. The SYS_FS_MAX_FILE_SYSTEM_TYPE has to be defined in system_config.h file. Returns If Success - SYS_FS_RES_SUCCESS If Failure - SYS_FS_RES_FAILURE The reason for failure could be retrieved with SYS_FS_Error Example // This code snippet shows an example of how the // SYS FS is initialized // Only 1 file system is used #define SYS_FS_MAX_FILE_SYSTEM_TYPE 1 // Functions pointer table for FAT FS const SYS_FS_FUNCTIONS FatFsFunctions = { .mount = f_mount, .unmount = f_unmount, .open = f_open, .read = f_read, .write = f_write, .close = f_close, .seek = f_lseek, .tell = f_tell, .eof = f_eof, .size = f_size, .fstat = f_stat, }; const SYS_FS_REGISTRATION_TABLE sysFSInit [ SYS_FS_MAX_FILE_SYSTEM_TYPE ] = { { .nativeFileSystemType = FAT, .nativeFileSystemFunctions = &FatFsFunctions } }; SYS_FS_Initialize( (const void *) sysFSInit ); 5.7.4.6.2.3 SYS_FS_Mount Function C SYS_FS_RESULT SYS_FS_Mount( const char * devName, const char * mountName, SYS_FS_FILE_SYSTEM_TYPE filesystemtype, unsigned long mountflags, const void * data ); 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3408 Description The mount command attaches the filesystem specified to a volume. When a media (say, SD card or USB thumb drive) is attached to the system, the SYS_FS_Tasks() function needs to run atleast 8 times (for each partition), from the SYS_Tasks(), before the volume names are assigned to each partitions. Hence it is mandatory that the SYS_FS_Tasks() is run periodically. Also, it is mandatory that the SYS_FS_Mount() function call from the application code, is not blocking. The application code has to allow the SYS_FS_Tasks() to run periodically while calling the SYS_FS_Mount function. If the SYS_FS_Mount() is called in a blocking mode, then the SYS_Tasks() never gets a chance to run and hence, the media will not be analyzed and finally, the SYS_FS_Mount will never succed. This will result in a dead-lock. There is no mechanism available for the application to know if the specified volume (devName) is really attached or not. The only available possibilty is to keep trying to mount the volume (with the devname), untill success is achieved. It is prudent that the application code implements a time out mechanism while trying to mount a volume (by calling SYS_FS_Mount). The trial for mount should continue atleast 10 times before before assuming that the mount will never succedeed. This has to be done for every new volume to be mounted. The name standard of volume (devName) used in Harmony file system is as below: - For NVM - "nvm" "media number" "volume number" For SD card - "mmcblk" "media number" "volume number" For MSD - "sd" "media number" "volume number" Where, "media number" - a, b, c... depending upon number of media of certain type connected. Where, "volume number" - 1, 2, 3... depending upon number of partitions in that media. The convention for assigning names to volumes is given by an example: - If an SD card (with 4 partitiona) is attached to the system, and assuming all 4 partitions are recognized, then there will be 4 devNames -- mmcblka1, mmcblka2, mmcblka3 and mmcblka4. Subsequently, a NVM media is attached which has only 1 partition, then the devname will be -- nvma1. Later, another SD card is attached to the system which has 1 partition, then the devname will be -- mmcblkb1. Finally, there will be 6 volume names (or devNames), which is available for the application to be mounted and used for file system. Preconditions The "devName" name for the volume has to be known. The file sytem type with which each of the volumes are formatted has to be known. Trying to mount a volume with a file system which is different from what the volume is actually formatted, will cause mounting failure. Parameters Parameters Description devName The device name (name of volume) which needs to be mounted. The devName has to be preceeded by the string "/dev/". mountName Mount name for the device to be mounted. This is a name provided by the user. In future, while accessing the mounted volume (say, during SYS_FS_FileOpen operation), the mountName is used to refer the path for file. The mount name has to be preceeded by the string "/mnt/" filesystemtype native file system of SYS_FS_FILE_SYSTEM_TYPE type. mountflags mounting control flags. This parameter is reserved for future enhancements. Hence, always pass zero. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3409 data The data argument is interpreted by the different file systems. This parameter is reserved for future enhancements. Hence, always pass NULL. Returns If Success - SYS_FS_RES_SUCCESS If Failure - SYS_FS_RES_FAILURE The reason for failure could be retrieved with SYS_FS_Error Example switch(appState) { case TRY_MOUNT: if(SYS_FS_Mount("/dev/mmcblka1", "/mnt/myDrive", FAT, 0, NULL) != SYS_FS_RES_SUCCESS) { // Failure, hence try mouting again } else { // Mount was successful. Do further file operations appState = DO_FURTHER_STUFFS; } break; 5.7.4.6.2.4 SYS_FS_Tasks Function C void SYS_FS_Tasks(); Description This routine is used to run the varioius tasks and functionalities of sys_fs layer. Preconditions The SYS_FS_Initialize routine must have been called before running the tasks. Returns None Remarks This routine is not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Example void SYS_Tasks ( void ) { SYS_FS_Tasks (); // Do other tasks } 5.7.4.6.2.5 SYS_FS_Unmount Function C SYS_FS_RESULT SYS_FS_Unmount( const char * mountName ); 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3410 Description remove the attachment of the volume from the fil system Preconditions The volume name has to be know in order to pass as input to Unmount. The specified volume name to be unmounted should have been already mounted. Parameters Parameters Description mountName Mount name for the volume to be mounted. The mount name has to be preceeded by the string "/mnt/". Returns If Success - SYS_FS_RES_SUCCESS If Failure - SYS_FS_RES_FAILURE The reason for failure could be retrieved with SYS_FS_Error Example if(SYS_FS_Unmount("/mnt/myDrive") != SYS_FS_RES_SUCCESS) { // Failure, hence try unmouting again } else { // Unmount was successful. } 5.7.4.6.3 Data Types and Constants 5.7.4.6.3.1 SYS_FS_ERROR Enumeration C typedef enum { SYS_FS_ERROR_OK = 0, SYS_FS_ERROR_DISK_ERR, SYS_FS_ERROR_INT_ERR, SYS_FS_ERROR_NOT_READY, SYS_FS_ERROR_NO_FILE, SYS_FS_ERROR_NO_PATH, SYS_FS_ERROR_INVALID_NAME, SYS_FS_ERROR_DENIED, SYS_FS_ERROR_EXIST, SYS_FS_ERROR_INVALID_OBJECT, SYS_FS_ERROR_WRITE_PROTECTED, SYS_FS_ERROR_INVALID_DRIVE, SYS_FS_ERROR_NOT_ENABLED, SYS_FS_ERROR_NO_FILESYSTEM, SYS_FS_ERROR_FORMAT_ABORTED, SYS_FS_ERROR_TIMEOUT, SYS_FS_ERROR_LOCKED, SYS_FS_ERROR_NOT_ENOUGH_CORE, SYS_FS_ERROR_TOO_MANY_OPEN_FILES, SYS_FS_ERROR_INVALID_PARAMETER, SYS_FS_ERROR_NOT_ENOUGH_FREE_VOLUME, SYS_FS_ERROR_FS_NOT_SUPPORTED, SYS_FS_ERROR_FS_NOT_MATCH_WITH_VOLUME, SYS_FS_ERROR_NOT_SUPPORTED_IN_NATIVE_FS 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3411 } SYS_FS_ERROR; Description File Error error enumeration This enumeration lists the various error cases. When the application calls for a file system function which has a return type of SYS_FS_RESULT and if the return value is SYS_FS_RES_FAILURE, the application can know the specific reason for failure by calling the SYS_FS_FileError function. The return value of SYS_FS_FileError function will be one of the enumeration of the type SYS_FS_ERROR. Members Members Description SYS_FS_ERROR_OK = 0 Success SYS_FS_ERROR_DISK_ERR (1) A hard error occurred in the low level disk I/O layer SYS_FS_ERROR_INT_ERR (2) Assertion failed SYS_FS_ERROR_NOT_READY (3) The physical drive cannot work SYS_FS_ERROR_NO_FILE (4) Could not find the file SYS_FS_ERROR_NO_PATH (5) Could not find the path SYS_FS_ERROR_INVALID_NAME (6) The path name format is invalid SYS_FS_ERROR_DENIED (7) Access denied due to prohibited access or directory full SYS_FS_ERROR_EXIST (8) Access denied due to prohibited access SYS_FS_ERROR_INVALID_OBJECT (9) The file/directory object is invalid SYS_FS_ERROR_WRITE_PROTECTED (10) The physical drive is write protected SYS_FS_ERROR_INVALID_DRIVE (11) The logical drive number is invalid SYS_FS_ERROR_NOT_ENABLED (12) The volume has no work area SYS_FS_ERROR_NO_FILESYSTEM (13) There is no valid volume SYS_FS_ERROR_FORMAT_ABORTED (14) The Format() aborted due to any parameter error SYS_FS_ERROR_TIMEOUT (15) Could not get a grant to access the volume within defined period SYS_FS_ERROR_LOCKED (16) The operation is rejected according to the file sharing policy SYS_FS_ERROR_NOT_ENOUGH_CORE (17) LFN working buffer could not be allocated SYS_FS_ERROR_TOO_MANY_OPEN_FILES (18) Number of open files SYS_FS_ERROR_INVALID_PARAMETER (19) Given parameter is invalid SYS_FS_ERROR_NOT_ENOUGH_FREE_VOLUME (20) Too many mounts requested. Not enough free volume available SYS_FS_ERROR_FS_NOT_SUPPORTED (21) Requested native file system is not supported SYS_FS_ERROR_FS_NOT_MATCH_WITH_VOLUME (22) Requested native file system does not match the format of volume SYS_FS_ERROR_NOT_SUPPORTED_IN_NATIVE_FS (23) Function not supported in native file system layer 5.7.4.6.3.2 SYS_FS_FILE_OPEN_ATTRIBUTES Enumeration C typedef enum { SYS_FS_FILE_OPEN_READ = 0, SYS_FS_FILE_OPEN_WRITE, SYS_FS_FILE_OPEN_APPEND, SYS_FS_FILE_OPEN_READ_PLUS, SYS_FS_FILE_OPEN_WRITE_PLUS, SYS_FS_FILE_OPEN_APPEND_PLUS } SYS_FS_FILE_OPEN_ATTRIBUTES; Description File open attributes 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3412 Lists the various attributes (modes) in which a file can be opened Members Members Description SYS_FS_FILE_OPEN_READ = 0 reading the file = possible, if file exists. reading the file = file open returns error, if file does not exist. writing to the file = not possible. Write operation returns error SYS_FS_FILE_OPEN_WRITE reading the file = not possble. Read operation returns error writing to the file = possible. If file exists, write happens from the begining of the file, overwriting the existing content of the file. writing to the file = If file does not exist, a new file will be created and data will be written into the newly created file. SYS_FS_FILE_OPEN_APPEND reading the file = not possble. Read operation returns error writing to the file = possible. If file exists, write happens from the end of the file, preserving the existing content of the file. writing to the file = If file does not exist, a new file will be created and data will be written into the newly created file. SYS_FS_FILE_OPEN_READ_PLUS reading the file = possible, if file exists. reading the file = file open returns error, if file does not exist. writing to the file = possible, if file exists, staring from the begining of the file (overwriting). writing to the file = file open returns error, if file does not exist. SYS_FS_FILE_OPEN_WRITE_PLUS reading the file = possible, if file exists. reading the file = If file does not exist, a new file will be created. writing to the file = possible. If file exists, write happens from the begining of the file, overwriting the existing content of the file. writing to the file = If file does not exist, a new file will be created and data will be written into the newly created file. SYS_FS_FILE_OPEN_APPEND_PLUS reading the file = possible, if file exists. reading the file = If file does not exist, a new file will be created. writing to the file = possible. If file exists, write happens from the end of the file, preserving the existing content of the file. writing to the file = If file does not exist, a new file will be created and data will be written into the newly created file. 5.7.4.6.3.3 SYS_FS_FILE_SEEK_CONTROL Enumeration C typedef enum { SYS_FS_SEEK_SET, SYS_FS_SEEK_CUR, SYS_FS_SEEK_END } SYS_FS_FILE_SEEK_CONTROL; Description File Seek control This enumeration lists the various modes of file seek. When the application calls the SYS_FS_FileSeek function, it specifies the kind of seek that needs to be performed. The enumeration lists the various modes of file seek. Members Members Description SYS_FS_SEEK_SET The file offset shall be set to input number of bytes from the start SYS_FS_SEEK_CUR The file offset shall be set to its current location plus input number of bytes 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3413 SYS_FS_SEEK_END The file offset shall be set to the size of the file plus input number of bytes Remarks None. 5.7.4.6.3.4 SYS_FS_FILE_SYSTEM_TYPE Enumeration C typedef enum { FAT, MPFS2 } SYS_FS_FILE_SYSTEM_TYPE; Description File System type These enumerated values are the possible native file system that can be supported by the SYS FS layer. Members Members Description FAT FAT FS native File system MPFS2 MPFS2 native File system Remarks None. 5.7.4.6.3.5 SYS_FS_FSTAT Structure C typedef struct { uint32_t fsize; uint16_t fdate; uint16_t ftime; uint8_t fattrib; char fname[13]; char* lfname; uint32_t lfsize; } SYS_FS_FSTAT; Description SYS FS File status structure This structure holds the various status of a file. The stucture is passed when SYS_FS_Stat function is called and after a successful execution of the function, the members of this structure carries the file status. Members Members Description uint32_t fsize; File size uint16_t fdate; Last modified date uint16_t ftime; Last modified time uint8_t fattrib; Attribute char fname[13]; Short file name (8.3 format) char* lfname; Pointer to the LFN buffer uint32_t lfsize; Size of LFN buffer in TCHAR 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3414 Remarks None. 5.7.4.6.3.6 SYS_FS_FUNCTIONS Structure C typedef struct { int (* mount)(uint8_t vol); int (* unmount)(uint8_t vol); int (* open)(uintptr_t handle, const char* path, uint8_t mode); int (* read)(uintptr_t fp, void* buff, uint32_t btr, uint32_t *br); int (* write)(uintptr_t fp, const void* buff, uint32_t btw, uint32_t* bw); int (* close)(uintptr_t fp); int (* seek)(uintptr_t handle, uint32_t offset); uint32_t (* tell)(uintptr_t handle); bool (* eof)(uintptr_t handle); uint32_t (* size)(uintptr_t handle); int (* fstat)(const char* path, uintptr_t fno); } SYS_FS_FUNCTIONS; Description SYS FS Function signature structure for native file systems The SYS FS layer supports functions from each native file system layer. This structure specifies the signature for each function from native file system (parameter that needs to be passed to each function and return type for each function). If a new native file system is to be integrated with the SYS FS layer, the functions should follow the signature. The structure of function pointer for 2 native file system -- FAT FS and MPFS2 is already provided in the respective source files for the native file system. Hence the following structure is not immediately useful for the user. But the explanation for the structure is still provided for advanced users who would wish to integrate a new native file system to the Harmony File system framework. Members Members Description int (* mount)(uint8_t vol); Function pointer of native file system for mounting a volume int (* unmount)(uint8_t vol); Function pointer of native file system for unmounting a volume int (* open)(uintptr_t handle, const char* path, uint8_t mode); Function pointer of native file system for opening a file int (* read)(uintptr_t fp, void* buff, uint32_t btr, uint32_t *br); Function pointer of native file system for reading a file int (* write)(uintptr_t fp, const void* buff, uint32_t btw, uint32_t* bw); Function pointer of native file system for writing to a file int (* close)(uintptr_t fp); Function pointer of native file system for closing a file int (* seek)(uintptr_t handle, uint32_t offset); Function pointer of native file system for moving the file pointer by a desired offset uint32_t (* tell)(uintptr_t handle); Function pointer of native file system for finding the position of the file pointer bool (* eof)(uintptr_t handle); Function pointer of native file system to check if the end of file is reached uint32_t (* size)(uintptr_t handle); Function pointer of native file system to know the size of file int (* fstat)(const char* path, uintptr_t fno); Function pointer of native file system to know the status of file Remarks None. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3415 5.7.4.6.3.7 SYS_FS_HANDLE Type C typedef uintptr_t SYS_FS_HANDLE; Description SYS FS File Handle While the application code opens a file, a file handle is returned by the open function (on successful open). This type defines the type of file handle. Remarks None. 5.7.4.6.3.8 SYS_FS_REGISTRATION_TABLE Structure C typedef struct { SYS_FS_FILE_SYSTEM_TYPE nativeFileSystemType; const SYS_FS_FUNCTIONS * nativeFileSystemFunctions; } SYS_FS_REGISTRATION_TABLE; Description SYS_FS_REGISTRATION_TABLE structure When the SYS FS layer is initialised, it has to know the type of native file system it has to support and the list of functions for native file system. The members of this structure can be initialized with suitable values and then passed on to SYS_FS_Initialize initialization function. Please refer to the example code provided for SYS_FS_Initialize. Members Members Description SYS_FS_FILE_SYSTEM_TYPE nativeFileSystemType; Native file system of type SYS_FS_FILE_SYSTEM_TYPE const SYS_FS_FUNCTIONS * nativeFileSystemFunctions; Pointer to the structure of type SYS_FS_FUNCTIONS which has the list of Remarks None. 5.7.4.6.3.9 SYS_FS_RESULT Enumeration C typedef enum { SYS_FS_RES_SUCCESS = 0, SYS_FS_RES_FAILURE = -1 } SYS_FS_RESULT; Description File operation result enum This enumeration lists the various results of a file operation. When a file operation function is called from the application, and if the return type of the function is SYS_FS_RESULT, then, the enumration below specifies the value of function return. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3416 Members Members Description SYS_FS_RES_SUCCESS = 0 Operation successful SYS_FS_RES_FAILURE = -1 operation failed 5.7.4.6.3.10 FAT_FS_MAX_LFN Macro C #define FAT_FS_MAX_LFN 255 Description FAT File System LFN (long file name) max length Set the value to 255 5.7.4.6.3.11 FAT_FS_MAX_SS Macro C #define FAT_FS_MAX_SS 512 Description FAT File System Sector size Maximum sector size to be handled. Always set the value of sector size to 512 5.7.4.6.3.12 FAT_FS_USE_LFN Macro C #define FAT_FS_USE_LFN 1 Description FAT File System LFN (long file name) selection The FAT_FS_USE_LFN option switches the LFN support. Set the value to 1 5.7.4.6.3.13 SYS_FS_HANDLE_INVALID Macro C #define SYS_FS_HANDLE_INVALID ((SYS_FS_HANDLE)(-1)) Description SYS FS File Invalid Handle While the application code opens a file, if the file open is unsuccessful, an invalid file handle is returned. This definition defines the type of invalid file handle. Remarks None. 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3417 5.7.4.7 Files Files Name Description sys_fs.h This file contains function and type declarations required to interact with the Harmony File System System Framework. Description 5.7.4.7.1 sys_fs.h File System System-Library Interface Declarations and types. This file contains function and type declarations required to interact with the Harmony File System System Framework. Enumerations Name Description SYS_FS_ERROR Lists the various error cases SYS_FS_FILE_OPEN_ATTRIBUTES Lists the various attributes (modes) in which a file can be opened SYS_FS_FILE_SEEK_CONTROL Lists the various modes of file seek SYS_FS_FILE_SYSTEM_TYPE Enumerated data type identifying native file systems supported. SYS_FS_RESULT Lists the various results of a file operation Functions Name Description SYS_FS_FileClose Close a file. SYS_FS_FileEOF check handle status SYS_FS_FileError check the type of error SYS_FS_FileNameGet Reads the file name. SYS_FS_FileOpen Open a file SYS_FS_FileRead Read specified bytes from a file SYS_FS_FileSeek Move the file pointer. SYS_FS_FileSize Returns the size of the file SYS_FS_FileStat Get file status SYS_FS_FileTell Obtains the file pointer position SYS_FS_FileWrite Write on the file SYS_FS_Initialize Initializes the File system Abstration Layer (sys_fs layer). SYS_FS_Mount Mount filesystems SYS_FS_Tasks Tasks for the sys_fs layer SYS_FS_Unmount unmount filesystems Macros Name Description FAT_FS_MAX_LFN Lists the maximum length of file name during LFN selection FAT_FS_MAX_SS Lists the definitions for FAT file system sector size. FAT_FS_USE_LFN Lists the definitions for FAT file system LFN selection 5.7 System Service Library Help MPLAB Harmony Help File System Service Library 5-3418 SYS_FS_HANDLE_INVALID This definitions defines the SYS FS file invalid handle. Structures Name Description SYS_FS_FSTAT The structure to obtain the status of a file. SYS_FS_FUNCTIONS SYS FS Function signature structure for native file systems SYS_FS_REGISTRATION_TABLE The sys_fs layer has to be initialized by passing this structure with suitably initialized members. Types Name Description SYS_FS_HANDLE This type defines the file handle. File Name sys_fs.h Company Microchip Technology Incorported 5.7.5 Interrupt System Service Library 5.7.5.1 Introduction Interrupt System Service for Microchip Microcontrollers This library implements the Interrupt System Service. It is part of the system services that provides support for processing interrupts. The Interrupt System provides support for initializing the processor's interrupt controller, registering Interrupt Service Routines (ISRs) and managing interrupts. These features enable making efficient and dynamic applications, drivers, and middleware that respond to external events as they occur in real time. 5.7.5.2 Release Notes MPLAB Harmony Version: v0.70b Interrupt System Service Library Version : 1.0 Release Date: 18Nov2013 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3419 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.5.4 Using the Library This topic describes the basic architecture of the Interrupt System Service Library and provides information and examples on how to use it. Interface Header File: sys_int.h The interface to the Interrupt System Service library is defined in the "sys_int.h" header file, which is included by the "sys.h" system service header file. Any C language source (.c) file that uses the Interrupt System Service library should include "sys.h". Library File: The Interrupt System Service library (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the library interacts with the framework. 5.7.5.4.1 Abstraction Model This library provides an abstraction of the interrupt subsystem that is used by device drivers, middleware libraries and applications to receive and control interrupts in real time. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3420 Interrupt System Service The interrupt system services provide support for initializing the processor's interrupt controller, managing Interrupt Service Routines (ISRs) and managing interrupts. Initialization Each software module (device driver, library, or application) that needs to receive an interrupt must enable that interrupt itself. This is normally done in the module's initialization routine which is called by the "SYS_Initialize" service. A module that intends to use an interrupt must first register the "Tasks" function that is to be called when the desired source causes an interrupt. Then, it must enable that source, once it is ready to start receiving interrupts. If the interrupt system service is configured for static usage, then the routine that dynamically registers the "Tasks" function will be nulled out by a macro (generating no run-time code) and, instead, the "Tasks" routine must be called statically from the function that implements the raw ISR vector. How this is done is different for each processor family, as explained below. Interrupt Service Routine (ISR) Each software module (device driver, library, or application) that needs to receive an interrupt must implement a "Tasks" routine to handle that interrupt. In order for the module to operate in an interrupt-driven mode, the "Tasks" routine must be called from within the appropriate "raw" Interrupt Service Routine (ISR). How the raw ISR is implemented is highly dependent upon the specific processor being used. Libraries are available that implement raw ISRs for each processor family in a way that allows dynamic registration and de-registration of "Tasks" routines. These libraries maintain tables that associate the "Tasks" routine registered by the SYS INIT service with each interrupt source in the system. Alternately, in a statically-linked system implementation, the ISR may be implemented by the system designer or integrator (in the configuration-specific "sys_int.c" file). Such "static" ISR implementations must identify the source of the interrupt then directly call the appropriate module's "Tasks" routine. This requires knowledge of the modules that have been included in the system and cannot be implemented in advance as a library. Note: It is also possible, in a highly optimized system (or to support highly resource-restricted parts), to implement the logic of the module's "Tasks" routine directly in the raw ISR. However, this method is not recommended unless absolutely necessary to meet system timing requirements. Board Support Packages (BSPs) If the processor is affixed directly to the board, the BSP may also implement any required "raw" ISRs, eliminating the need for the system designer or integrator to implement the ISR(s) himself. Refer to the documentation for the BSP in use for details on what initialization and ISR support it provides. This support is not implemented by the Interrupt System Services library. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3421 5.7.5.4.2 Library Overview The diagram below describes the major components of the usage model. Library Usage Model Each of the blocks in the diagram above correspond to the library interface section. Library Interface Section Description Interrupt System Setup Functions Provides processor specific initialization of the interrupt system. Global Interrupt Management Functions Provide interface routines to enable/disable all interrupts on the system. 5.7.5.4.3 How the Library Works The Interrupt System Service Library can be used by a device driver, middleware layer, or application to provide access to, and control over, interrupts to the processor. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the modes supported for your device. 5.7.5.4.3.1 Interrupt System Setup The Interrupt System Service library must be initialized by calling the SYS_INT_Initialize routine. If the MPLAB Harmony dynamic initialization service is used, the "SYS_INT_Initialize" routine will be called automatically when the "SYS_Initialize" function is called. In a statically initialized system, the system designer or integrator must implement the "SYS_Initialize" function and that function must call "SYS_INT_Initialize" before initializing any modules that might require use if the interrupt system service. Once the library has been initialized, call the function SYS_INT_Enable to enable interrupts to the processor. However, before enabling the generation of interrupts to the processor, each individual module (driver, library, or application) must have a "Tasks" routine to in place (either registered with SYS_INT_DynamicRegister or statically linked to the raw ISR) to handle the interrupt before it enables it's own interrupt. Example: Initializing the System Interrupt Library SYS_INT_Initialize(); // Initialize all interrupt-aware software modules SYS_INT_Enable(); 5.7.5.4.3.2 Critical Sections Critical Sections Critical sections of code are small sections of code that must execute atomically, with no possibility of being interrupted. To support this, the following technique can be used. Global Interrupt Management provides routines to create a global critical section of code. Global Critical Section If no interrupts of any kind can be allowed within a critical section of code, the following routines can be used to ensure this. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3422 • SYS_INT_Disable: To start a critical section, all interrupts are disabled with the call of this function • SYS_INT_Enable : To end a critical section, interrupts are enabled from the interrupt controller to the core. • SYS_INT_IsEnabled: Status to indicate if interrupts are currently enabled or not. Example: Global Critical Section bool flag; flag = SYS_INT_Disable(); // Do something critical if (flag) { SYS_INT_Enable(); } Source Interrupt Management provides interface routines to create local critical sections Local Critical Sections Normally, it is not necessary to globally disable all possible interrupts. For example, in a driver for a specific device, it is not normally important if an unrelated interrupt occurs in the middle of a critical section of code. However, if the interrupt for the source that the driver manages must not occur within a critical section of code, it can be protected using the following technique. Example: Local Critical Section bool flag; // interrupt source enable status before disable is called flag = SYS_INT_SourceDisable(MY_DRIVER_INTERRUPT_SOURCE); // Do something critical if (flag) { SYS_INT_SourceEnable(MY_DRIVER_INTERRUPT_SOURCE); } Note: These methods of protecting critical sections is usually implemented as part of an Operating System Abstraction Layer (OSAL), so it is not normally necessary to use these examples explicitly. Normally, the OSAL will provide single functions or macros that implement this functionality. So, if available, an OSAL method is preferred over implementing the critical section code as shown in the above examples. 5.7.5.4.3.3 Source Interrupt Management The driver, middleware, or application's interrupt-handling "Tasks" routine must do two things at a minimum, in the following order. 1. Remove the cause of the interrupt 2. Clear the interrupt source by calling the function SYS_INT_SourceStatusClear Exactly what actions are necessary to remove the cause of an interrupt is completely dependent on the source of the interrupt. This is normally the main purpose of the driver itself and is beyond the scope of this section. Refer to the documentation for the peripheral being managed. WARNING! The cause of the interrupt must be removed before clearing the interrupt source or the interrupt may re-occur immediately after the source is cleared potentially causing an infinite loop. An infinite loop may also occur if the source is not cleared before the interrupt-handler returns. Example: Handling Interrupts void DRV_MYDEV_Tasks( SYS_MODULE_OBJ object ) { 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3423 // Remove the cause of the interrupt //... // Clear Interrupt source SYS_INT_SourceStatusClear(myIntSourceID); } Note: The value of "myIntSourceID" is usually either a static or dynamic configuration option. Refer to the documentation for the specific device driver to identify how to define the interrupt source ID. Testing Interrupt Some times it is necessary to cause an interrupt in software, possibly for testing purposes. To support this, the function SYS_INT_SourceStatusSet is provided. Example: Causing an Interrupt in Software SYS_INT_SourceStatusSet(MY_DRIVER_INTERRUPT_SOURCE); Note: This feature is not available for all interrupt sources on all Microchip microcontrollers. Refer to the data sheet for the microcontroller being used to determine if it is possible for software to set a specific interrupt source. 5.7.5.5 Configuring the Library Three things must be correctly configured in order to use the System Interrupt library. 1. Select the Appropriate Processor 2. Initialize the Interrupt System Service 3. Configure the Raw ISR Support Select the Appropriate Processor The following data types are dependent on the processor selection and are actually defined in the interrupt peripheral library for the specific microcontroller being used. • INT_SOURCE • INT_PRIORITY • INT_SUBPRIORITY These are configured by selecting the appropriate processor in MPLAB, which adds the "mprocessor" option to the compiler command line to identify the correct processor and processor-specific implementation of the peripheral library to use. Since the System Interrupt library is part of the Microchip Firmware Framework, it will get built with the correct definition of these data types. Initialize the Interrupt System Service There are two ways to initialize the interrupt system service, depending on whether you're using a static configuration or a dynamic configuration. For a dynamic configuration the constant SYS_INT_DYNAMIC needs to be defined. This makes SYS_INT_DynamicRegister and SYS_INT_DynamicDeregister available. The required driver tasks routines need to be registered using SYS_INT_DynamicRegister function. For a static configuration, the system designer or integrator must implement the SYS_INT_Initialize routine. This routine's purpose is to perform any actions necessary to initialize the interrupt subsystem and interrupt controller on the specific processor and system, usually interacting directly with the Interrupt controller modules Peripheral Library (PLIB) to accomplish these tasks. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3424 Configure the Raw ISR Support In some systems, there may only be a single actual ("raw") ISR to handle all interrupts. In this sort of system, most of the System Interrupt library may be implemented in software, with only the highest level interrupt being supported by hardware. In other systems, all interrupts may be supported by separate ISRs and vector selection and prioritization will be supported by hardware. ISRs may be dynamically linked to specific interrupt sources or they may be statically linked at build time. If a dynamic interrupt library is used(by defining the constant SYS_INT_DYNAMIC) , the calls to SYS_INT_DynamicRegister will register a pointer to the given "Tasks" routine for each registered interrupt source in an internal table. The dynamic library will then determine the source of the interrupt and call the given "Tasks" routine. If a static configuration is desired, the "raw" ISR support must be implemented so that it directly calls (using static, build-time linkage) the appropriate module's "Tasks" routine. This requires the system implementer or integrator to implement the raw ISR, but it reduces the amount of overhead necessary to handle interrupts, reducing both interrupt latency and code size. 5.7.5.5.1 Static Configuration When statically configuring raw ISR support, the system implementer or integrator must directly implement the raw ISRs in an appropriate manner for the selected processor. The Raw ISR, must then call the appropriate "Tasks" routine to properly handle and clear the interrupt source. Description A static configuration of the raw ISR support for MPLAB Harmony requires processor-family-specific knowledge. Or, more accurately, it requires compiler-specific knowledge. The examples below will show a sampling of how to implement a raw ISR for different part families. Refer to the compiler manual for the selected processor family for details of how to implement an interrupt service routine. Raw ISR Responsibilities: 1. Identify the Interrupt Source 2. Call the Appropriate Module's "Tasks" Routine The first thing a raw ISR must do is identify the source of the interrupt. For some processor families, each interrupt source has its own interrupt "vector". This means that the only time a specific ISR is called is when a specific source has caused an interrupt. Thus, the raw ISR can assume that every time it is called it's source has caused an interrupt. Other processor families combine two or more interrupt sources into a single interrupt "vector". In such a case, the raw ISR must verify which source caused the interrupt and it must verify if that source is enabled. In either case, once the raw ISR has identified the interrupt source, it must call the appropriate module's "Tasks" routine to service and clear the interrupt. Example: PIC32 Timer-1 Raw ISR void __ISR ( _TIMER_1_VECTOR ) _InterruptHandler_TMR_1_stub( void ) { /* Call the timer driver's "Tasks" routine */ DRV_TMR_Tasks ( gTMRObject ); } Example: PIC24 Timer-1 Raw ISR void __attribute__ ( ( interrupt, no_auto_psv ) ) _ISR _T1Interrupt( void ) { /* Call the timer driver's "Tasks" routine */ DRV_TMR_Tasks ( gTMRObject ); } 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3425 Example: PIC18 Timer-1 Raw ISR #pragma interrupt_level 0 void interrupt low_priority InterruptHandler_low_priority_stub ( void ) { if ( SYS_INT_SourceIsEnabled( gTMRObject ) && PLIB_INT_SourceFlagGet( gTMRObject ) ) { /* Call the timer driver's "Tasks" routine */ DRV_TMR_Tasks ( gTMRObject ); } // Check other sources... } In all of the above examples, "gTMRObject" holds the return value from the "DRV_TMR_Initialize" routine. The SYS_INT_DynamicRegister and SYS_INT_DynamicDeregister routines are macro switched to compile away to nothing if a static configuration is chosen 5.7.5.5.2 Dynamic Configuration When dynamically configuring raw ISR support, the system implementer or integrator must register each interrupt-driven driver or module's "Tasks" routine with the dynamic system interrupt service for the appropriate interrupt source. The dynamic SYS INT service will then ensure that the appropriate "Tasks" routine is called when an interrupt occurs. Description When using the dynamic system interrupt (SYS INT) service, it is not necessary to implement "raw ISRs" for interrupt-driven modules. The processor-family-specific, dynamic SYS INT implementation provided with MPLAB Harmony implements the "raw ISR(s)" so the system developer or integrator doesn't have to. Instead, the system developer must register the module's "Tasks" routine(s) using the "SYS_ModuleRegister" routine after registering the module in the module registration routine (described in the SYS INIT documentation). The example below shows how a module must register its ISR "Tasks" routine. Example: Dynamic Registration of an Interrupt-Driven Module // Register the TMR driver's "Tasks" routine with the SYS INT service SYS_INT_DynamicRegister(object, DRV_TMR_Tasks, PLIB_INT_SOURCE_TIMER_1); The module init routine must register the module's "Tasks" routine(s) with the SYS INT service instead of the SYS TASKS service. to do this, it calls the "SYS_INT_DynamicRegister" routine, passing in the object(the same object handle returned by the module's initialization routine), along with a pointer to the module's "Tasks" routine and the interrupt source with which it will be associated. 5.7.5.6 Library Interface Data Types and Constants Name Description SYS_INT_TASKS_POINTER Pointer to an interrupt-handlng "Tasks" routine. Global Interrupt Management Functions Name Description SYS_INT_Disable Disables interrupts to the processor. SYS_INT_Enable Enables global interrupts to the processor. SYS_INT_IsEnabled Identifies if interrupts are currently enbled or disabled at the top level. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3426 Interrupt Source Management Functions Name Description SYS_INT_SourceDisable Disables the specified source from generating interrupts to the processor. SYS_INT_SourceEnable Enables the specified source to generate interrupts to the processor. SYS_INT_SourceIsEnabled Identifies if the specified source is enabled or disabled. SYS_INT_SourceStatusClear Clears the interrupt request for the specified interrupt source. SYS_INT_SourceStatusGet Determines the status of the specified interrupt source. SYS_INT_SourceStatusSet Sets the specified interrupt source. SYS_INT_VectorPrioritySet Sets the given interrupt vector to the specified priority. SYS_INT_VectorSubprioritySet Sets the specified interrupt vector to the given sub priority. Interrupt System Setup Functions Name Description SYS_INT_Initialize Configures and initializes the interrupt subsystem. SYS_INT_DynamicDeregister Deregisters the current ISR from the given interrupt source. SYS_INT_DynamicRegister Registers an Interrupt "Tsks" Routine for the specified interrupt source or trap). Description 5.7.5.6.1 Interrupt System Setup Functions 5.7.5.6.1.1 SYS_INT_Initialize Function C void SYS_INT_Initialize(); Description This function configures and initializes the interrupt subsystem appropriately for the current system design. Preconditions None. Returns None. Remarks None. The System Interrupt library must be initialized by calling the SYS_INT_Initialize routine. This is normally done in the "SYS_Initialize" routine before any interrupt support is used. If the dynamic interrupt system service is not used, the "SYS_Initialize" routine must be implemented by the system designer or integrator as required by the system design and is not implemented by the System Interrupt library. The global interrupts are enabled as a part the call to "SYS_INT_Initialize". However, before enabling the generation of interrupts to the processor, each individual module (driver, library, or application) must have a "Tasks" routine to in place ( statically linked to the raw ISR) to handle the interrupt before it enables it's own interrupt. Example: Initializing the System Interrupt Library SYS_INT_Initialize(); 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3427 Example // Initialize the interrupt system. This needs to done in the initialization // code. SYS_INT_Initialize(); 5.7.5.6.1.2 SYS_INT_DynamicDeregister Function C void SYS_INT_DynamicDeregister( INT_SOURCE source ); Description This function deregisters the current Interrupt Service Routine (ISR), if any, from the specified interrupt source. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description source Identifier for the desired interrupt source Returns None. Remarks It is safe to call this routine, even of no ISR has been registered for the given interrupt source. Calling this routine is optional. If the system is designed such that the given ISR is expected to always be available once the system has been initialiazed, this routine does not need to be called. Example SYS_INT_DynamicDeregister(SYS_INT_TIMER_1); 5.7.5.6.1.3 SYS_INT_DynamicRegister Function C void SYS_INT_DynamicRegister( INT_SOURCE source, SYS_INT_TASKS_POINTER tasks, SYS_MODULE_OBJ object ); Description This function registers an Interrupt "Tasks" Routine for the specified interrupt source or trap). Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description source Identifier for the desired interrupt source tasks Pointer to the tasks routine object Handle to the module instance 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3428 Returns None. Remarks This routine only generates executable code when a driver is configured to register dynamically its "Tasks" routine with the system interrupt service. However, it should be called even if the ISR-to-source association is defined statically at compile time to maintain source code compatibility. A device driver normally registers its own ISR from it's initialization routine. In the example code, the macros MY_DRIVER_INTERRUPT_SOURCE would be defined in the appropriate configuration header, which would be included by the driver source file where the "DRV_MYDEV_Tasks" routine and the MyParam data would be defined. It is safe to call this routine without first calling SYS_INT_DynamicDeregister, even if a previous ISR has been registered. The effect will be that the new ISR supplants the old one. The System Interrupt library must be initialized by calling the SYS_INT_Initialize routine. This is normally done in the "SYS_Initialize" routine before any interrupt support is used. If the dynamic interrupt system service is not used, the "SYS_Initialize" routine must be implemented by the system designer or integrator as required by the system design and is not implemented by the System Interrupt library. Once the library has been initialized, call the function SYS_INT_Enable to enable interrupts to the processor. However, before enabling the generation of interrupts to the processor, each individual module (driver, library, or application) must have a "Tasks" routine to in place (either registered with SYS_INT_DynamicRegister or statically linked to the raw ISR) to handle the interrupt before it enables it's own interrupt. Example: Initializing the System Interrupt Library // Initialize the interrupt system. SYS_INT_Initialize(); // Initialize all interrupt-aware software modules SYS_INT_Enable(); Example SYS_INT_Initialize(); SYS_INT_DynamicRegister(MY_DRIVER_INTERRUPT_SOURCE, DRV_MYDEV_Tasks, MyObject); 5.7.5.6.2 Global Interrupt Management Functions 5.7.5.6.2.1 SYS_INT_Disable Function C bool SYS_INT_Disable(); Description This function disables interrupts to the processor at the top level. This function can be called to prevent any source from being able to generate an interrupt. It returns the global interrupt status before disabling the interrupts. Preconditions SYS_INT_Initialize must have been called. Returns true - Global Interrupts are enabled (before the call to disable) false - Global Interrupts are disabled (before the call to disable) 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3429 Remarks None. Example // Interrupt enable status bool flag; // Disable the global interrupts flag = SYS_INT_Disable(); // Do something critical // Check if interrupts were disabled/enabled if (flag) { // enable the global interrupts if they were enabled before the // call to SYS_INT_Disable() SYS_INT_Enable(); } 5.7.5.6.2.2 SYS_INT_Enable Function C void SYS_INT_Enable(); Description This function enables interrupts to the processor at the top level, allowing any currently enabled source to generate an interrupt. This function must be called before any source will be able to generate an interrupt. Preconditions None. Returns None. Remarks SYS_INT_Enable is called from the SYS_INT_Initialize() function. Example // Check if global interrupts are enabled if(!SYS_INT_IsEnabled()) { // Enable the global interrupts. SYS_INT_Enable(); } 5.7.5.6.2.3 SYS_INT_IsEnabled Function C bool SYS_INT_IsEnabled(); Description This function identifies if interrupts are enbled or disabled at the top level. Preconditions SYS_INT_Initialize must have been called. Returns • true - If the interrupts are currently enabled • false - If the interrupts are ccurrentlyl disabled 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3430 Remarks None. Example // Check if global interrupts are enabled if ( SYS_INT_IsEnabled() ) { // Interrupt enable status bool flag; // Disable the global interrupts. flag = SYS_INT_Disable(); } 5.7.5.6.3 Interrupt Source Management Functions 5.7.5.6.3.1 SYS_INT_SourceDisable Function C bool SYS_INT_SourceDisable( INT_SOURCE source ); Description This routine disables the given source from generating interrupts the processor when events occur.It returns the interrupt source enable/disable status before disabling the interrupt source. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description source Identifier for the desired interrupt source. Returns • true - The Interrupt source is enabled (before the call to SYS_INT_SourceDisable) • false - The Interrupt source is disabled (before the call to SYS_INT_SourceDisable) Remarks None. Example // interrupt source enable/disable status. bool flag // Initialize the interrupt system.This needs to done in the initialization // code. SYS_INT_Initialize(); // Disable the interrupt source flag = SYS_INT_SourceDisable(INT_SOURCE_PARALLEL_PORT); // before enabling the source check the enable/disable status if(flag) { SYS_INT_SourceEnable(INT_SOURCE_PARALLEL_PORT); } 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3431 5.7.5.6.3.2 SYS_INT_SourceEnable Function C void SYS_INT_SourceEnable( INT_SOURCE source ); Description This routine enables the specified source to generate interrupts to the processor when events occur. Preconditions SYS_INT_Initialize must have been called and an ISR must have been registered for the source. Parameters Parameters Description source Identifier for the desired interrupt source Returns None. Remarks An Interrupt Service Routine (ISR) for the given interrupt source must be ready to receive the call before the source is enabled. Example // Initialize the interrupt system. This needs to done in the initialization // code. SYS_INT_Initialize(); // Enable the interrupt source SYS_INT_SourceEnable(INT_SOURCE_PARALLEL_PORT); 5.7.5.6.3.3 SYS_INT_SourceIsEnabled Function C bool SYS_INT_SourceIsEnabled( INT_SOURCE source ); Description This function identifies if the specified source is currently enabled or is currently disabled. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description source Identifier for the desired interrupt source. Returns • true - If the given source is currently enabled. • false - If the given source is currently disabled. Remarks None. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3432 Example // Initialize the interrupt system. This needs to done in the initialization // code. SYS_INT_Initialize(); // Check if the required interrupt source is enabled if ( SYS_INT_SourceIsEnabled(INT_SOURCE_PARALLEL_PORT)) { // App code } 5.7.5.6.3.4 SYS_INT_SourceStatusClear Function C void SYS_INT_SourceStatusClear( INT_SOURCE source ); Description This function clears the interrupt request for the specified interrupt source. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description source Identifier for the desired interrupt source Returns None. Remarks None. Example // Initialize the interrupt system. This needs to done in the initialization // code. SYS_INT_Initialize(); // Check if the interrupt source flag is set if ( SYS_INT_SourceStatusGet(INT_SOURCE_PARALLEL_PORT) ) { // Clear the interrupt flag SYS_INT_SourceStatusClear(INT_SOURCE_PARALLEL_PORT); } 5.7.5.6.3.5 SYS_INT_SourceStatusGet Function C bool SYS_INT_SourceStatusGet( INT_SOURCE source ); Description This function determines the current status of the interrupt source. Preconditions SYS_INT_Initialize must have been called. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3433 Parameters Parameters Description source Identifier for the desired interrupt source Returns • true - If the given interrupt source is currently set • false - If the given interrupt source is not currently set Remarks Works even if the interrupt source or interrupts in general have not been enabled, so it can be used for polling implementations. Example // Initialize the interrupt system.This needs to done in the initialization // code. SYS_INT_Initialize(); // Check if the required interrupt source is set if ( SYS_INT_SourceStatusGet(INT_SOURCE_PARALLEL_PORT) ) { // Handle interrupt } 5.7.5.6.3.6 SYS_INT_SourceStatusSet Function C void SYS_INT_SourceStatusSet( INT_SOURCE source ); Description This function sets the specified interrupt source, causing the processor to be interrupted if interrupts are enabled, the source has been enabled, and the priority is higher than the current priority. Preconditions SYS_INT_Initialize must have been called and an ISR must have been registered for the source (if interrupts and the source are enabled). Parameters Parameters Description source Identifier for the desired interrupt source Returns None. Remarks Not supported for all interrupt sources. Check the specific data sheet for software clear only interrupt sources. The driver, middleware, or application's interrupt-handling "Tasks" routine must do two things at a minimum, in the following order. 1. Remove the cause of the interrupt 2. Clear the interrupt source by calling the function SYS_INT_SourceStatusClear Exactly what actions are necessary to remove the cause of an interrupt is completely dependent on the source of the interrupt. This is normally the main purpose of the driver itself and is beyond the scope of this section. Refer to the documentation for the peripheral being managed. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3434 WARNING! The cause of the interrupt must be removed before clearing the interrupt source or the interrupt may re-occur immediately after the source is cleared potentially causing an infinite loop. An infinite loop may also occur if the source is not cleared before the interrupt-handler returns. Example: Handling Interrupts void DRV_MYDEV_Tasks( SYS_MODULE_OBJ object ) { // Remove the cause of the interrupt //... // Clear Interrupt source SYS_INT_SourceStatusClear(myIntSourceID); } Note: the value of "myIntSourceID" is usually either a static or dynamic configuration option. Refer to the documentation for the specific device driver to identify how to define the interrupt source ID. Testing Interrupt Some times it is necessary to cause an interrupt in software, possibly for testing purposes. To support this, the function SYS_INT_SourceStatusSet is provided. Example: Causing an Interrupt in Software SYS_INT_SourceStatusSet(MY_DRIVER_INTERRUPT_SOURCE); Note: This feature is not available for all interrupt sources on all Microchip microcontrollers. Refer to the data sheet for the microcontroller being used to determine if it is possible for software to set a specific interrupt source. Example // Initialize the interrupt system. This needs to done in the initialization // code. SYS_INT_Initialize(); // Check if interrupt source flag is set if ( !SYS_INT_SourceStatusGet(INT_SOURCE_PARALLEL_PORT) ) { // Set the interrupt source flag SYS_INT_SourceStatusSet(INT_SOURCE_PARALLEL_PORT); } 5.7.5.6.3.7 SYS_INT_VectorPrioritySet Function C void SYS_INT_VectorPrioritySet( INT_VECTOR vector, INT_PRIORITY_LEVEL priority ); Description This routine sets the given interrupt vector to the specified priority. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description vector Identifier for the desired interrupt vector priority Priority (if supported) 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3435 Returns None. Remarks This feature is not supported on all devices. Refer to the specific device data sheet or family reference manual to determine whether this feature is supported. In the example code, the macros MY_DRIVER_INTERRUPT_VECTOR, MY_DRIVER_ISR_PRIORITY would be defined appropriately during configuration. Example #define MY_DRIVER_INTERRUPT_VECTOR INT_VECTOR_T1 #define MY_DRIVER_ISR_PRIORITY INT_PRIORITY_LEVEL2 // Initialize the interrupt system.This needs to done in the initialization // code. SYS_INT_Initialize(); // Assign priority to the interrupt vector SYS_INT_VectorPrioritySet(MY_DRIVER_INTERRUPT_VECTOR, MY_DRIVER_ISR_PRIORITY); 5.7.5.6.3.8 SYS_INT_VectorSubprioritySet Function C void SYS_INT_VectorSubprioritySet( INT_VECTOR vector, INT_SUBPRIORITY_LEVEL subpriority ); Description This function sets the specified interrupt vector to the specified sub-priority. Preconditions SYS_INT_Initialize must have been called. Parameters Parameters Description vector Identifier for the desired interrupt vector subpriority Subproirity (if supported) Returns None. Remarks This feature is not supported on all devices. Refer to the specific device data sheet or family reference manual to determine whether this feature is supported. In the example code, the macros MY_DRIVER_INTERRUPT_VECTOR, MY_DRIVER_ISR_SUB_PRIORITY would be defined appropriately during configuration. Example #define MY_DRIVER_INTERRUPT_VECTOR INT_VECTOR_T1 #define MY_DRIVER_ISR_PRIORITY INT_PRIORITY_LEVEL2 #define MY_DRIVER_ISR_SUB_PRIORITY INT_SUBPRIORITY_LEVEL1 // Initialize the interrupt system.This needs to done in the initialization // code. SYS_INT_Initialize(); // Assign priority to the interrupt vector SYS_INT_VectorPrioritySet(MY_DRIVER_INTERRUPT_VECTOR, MY_DRIVER_ISR_PRIORITY); 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3436 // Assign sub-priority to the interrupt vector SYS_INT_VectorSubprioritySet(MY_DRIVER_INTERRUPT_VECTOR, MY_DRIVER_ISR_SUB_PRIORITY); 5.7.5.6.4 Data Types and Constants 5.7.5.6.4.1 SYS_INT_TASKS_POINTER Type C typedef void (* SYS_INT_TASKS_POINTER)(SYS_MODULE_OBJ object); Description Interrupt Tasks Routine Pointer This data type defines a pointer to an interrupt-handling "Tasks" routine. The form of a tasks routine is as follows: void My_Tasks ( SYS_MODULE_OBJ object ); Where "MyTasks" is the name of the tasks routine and object is a Handle to the module instance. Remarks "Tasks" is normally defined by a device driver, middleware, or system layer. The term Interrupt Service Routine (ISR) is used for the "raw" ISR code that is either located directly at the interrupt vector address or whose address is loaded from the interrupt vector. The term "Tasks" routine is used to identify the driver-specific routine that is called by the actual ISR to perform the tasks necessary to handle and clear the interrupt. 5.7.5.7 Files Files Name Description sys_int.h Interrupt System Service. Description 5.7.5.7.1 sys_int.h Interrupt System Service Library Interface Definition This file contains the interface definition for the Interrupt System Service. It provides a way to interact with the interrupt subsystem to manage the occurance of interrupts for sources supported by the system. Functions Name Description SYS_INT_Disable Disables interrupts to the processor. SYS_INT_DynamicDeregister Deregisters the current ISR from the given interrupt source. SYS_INT_DynamicRegister Registers an Interrupt "Tsks" Routine for the specified interrupt source or trap). SYS_INT_Enable Enables global interrupts to the processor. SYS_INT_Initialize Configures and initializes the interrupt subsystem. SYS_INT_IsEnabled Identifies if interrupts are currently enbled or disabled at the top level. SYS_INT_SourceDisable Disables the specified source from generating interrupts to the processor. 5.7 System Service Library Help MPLAB Harmony Help Interrupt System Service Library 5-3437 SYS_INT_SourceEnable Enables the specified source to generate interrupts to the processor. SYS_INT_SourceIsEnabled Identifies if the specified source is enabled or disabled. SYS_INT_SourceStatusClear Clears the interrupt request for the specified interrupt source. SYS_INT_SourceStatusGet Determines the status of the specified interrupt source. SYS_INT_SourceStatusSet Sets the specified interrupt source. SYS_INT_VectorPrioritySet Sets the given interrupt vector to the specified priority. SYS_INT_VectorSubprioritySet Sets the specified interrupt vector to the given sub priority. Types Name Description SYS_INT_TASKS_POINTER Pointer to an interrupt-handlng "Tasks" routine. File Name sys_int.h Company Microchip Technology Inc. 5.7.6 Messaging System Service Library 5.7.6.1 Introduction Messaging System Service Library for Microchip Microcontrollers This library provides intra-process and inter-process communication by the sending and receiving of simple messages. The format of these messages is under developer control, providing flexibility to tune message format for each application. The number and size of message queues is under developer control, with a message priority scheme implemented by multiple queues. Each priority queue has an configurable size. The number of message types and the number of receiving mailboxes is also configurable. Description This library provides intra-process and inter-process communication by the sending and receiving of simple messages. The format of these messages is under developer control, providing flexibility to tune message format for each application. The number and size of message queues is under developer control, with a message priority scheme implemented by multiple queues. Each priority queue has an configurable size. The number of message types and the number of receiving mailboxes is also configurable. Consider an application that combines graphics on a display screen, with a touch overlay on top of the screen, and several buttons. System messages can be used by touch software to alert the graphics part of the application to update the screen as well as alert other parts of the application to perhaps change the audio volume whenever a slider value has changed. This is easily supported by the Messaging System Services Library. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3438 5.7.6.2 Release Notes MPLAB Harmony Version: v0.70b Messaging System Service Library Version : 0.01a Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.6.4 Using the Library Interface Header File: sys_msg.h The interface to the Messaging System Service library is defined in the "sys_msg.h" header file". This library uses calloc to allocate memory for: • Message queues for each priority as part of SYS_MSG_Initialize • Mailbox definition objects • Message type objects If calls to calloc fails to allocate the needed memory then object handles are returned with a value of SYS_OBJ_HANDLE_INVALID. Here is a simple example that can be run on any PIC32 starter kit: #include #include #include "system/common/sys_module.h" #include "system/msg/sys_msg.h" #include "system/msg/src/sys_msg_local.h" 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3439 // Strawman callback functions for three mailboxes void myCallBack0( SYS_MSG_OBJECT *pMessage ) { DBPRINTF("CallBack0:: Message Type: %d, nSource: %d\r\n" " param 0: %d, param1: %d, param2: %d \r\n", pMessage->nMessageTypeID, pMessage->nSource, pMessage->param0, pMessage->param1, pMessage->param2 ); } void myCallBack1( SYS_MSG_OBJECT *pMessage ) { DBPRINTF("CallBack1:: Message Type: %d, nSource: %d\r\n" " param 0: %d, param1: %d, param2: %d \r\n", pMessage->nMessageTypeID, pMessage->nSource, pMessage->param0, pMessage->param1, pMessage->param2 ); } void myCallBack2( SYS_MSG_OBJECT *pMessage ) { DBPRINTF("CallBack2:: Message Type: %d, nSource: %d\r\n" " param 0: %d, param1: %d, param2: %d \r\n", pMessage->nMessageTypeID, pMessage->nSource, pMessage->param0, pMessage->param1, pMessage->param2 ); } int main(void) { SYS_MSG_MESSAGING_OBJECT oSysMsg; SYS_OBJ_HANDLE hSysMsg, hMsgType[5], hMailbox[3]; SYS_MSG_INSTANCE iSysMsg = SYS_MSG_0; SYS_MSG_OBJECT myMessage[5]; {// SYS_MSG_Initialize uint8_t nQSizes[] = SYS_MSG_BUFFER_SIZES; // Initialize the messaging system. This needs to done in the initialization code. hSysMsg = SYS_MSG_Initialize(iSysMsg,SYS_MSG_MAX_PRIORITY+1,nQSizes); SYS_ASSERT( SYS_OBJ_HANDLE_INVALID != hSysMsg,"Bad hSysMsg!" ); } // Create the message types to be used // ID: :Priority hMsgType[0] = SYS_MSG_TypeCreate(iSysMsg,1<<0,0); hMsgType[1] = SYS_MSG_TypeCreate(iSysMsg,1<<1,1); hMsgType[2] = SYS_MSG_TypeCreate(iSysMsg,1<<2,2); hMsgType[3] = SYS_MSG_TypeCreate(iSysMsg,1<<3,3); hMsgType[4] = SYS_MSG_TypeCreate(iSysMsg,1<<4,4); // Create the mailboxes to be used hMailbox[0] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack0 ); hMailbox[1] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack1 ); hMailbox[2] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack2 ); // Identify which messages are of interest for each mailbox. SYS_MSG_MailboxMsgAdd(hMailbox[0],hMsgType[0]); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<1)); 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3440 SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<2)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<3)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<4)); SYS_MSG_MailboxMsgAdd(hMailbox[1],hMsgType[0]); SYS_MSG_MailboxMsgAdd(hMailbox[2],hMsgType[0]); {//Send and receive messages SYS_MSGQ_ELEMENT *pQElement; SYS_MSG_OBJECT *pMessage; SYS_MSG_RESULTS myResult; SYS_MSG_QUEUE_STATUS qStatus[5]; uint16_t iPriority; for (iPriority=0;iPriority<=SYS_MSG_MAX_PRIORITY;iPriority++) { myMessage[iPriority].nSource = SYS_MSG_MAX_PRIORITY-iPriority; myMessage[iPriority].nMessageTypeID = 1<nMessageTypeID, pMessage->nSource, pMessage->param0, pMessage->param1, pMessage->param2 ); } // Deliver messages for all mailboxes. DBPRINTF("\r\nGot Messages: %d\r\n",SYS_MSG_GotMessages(iSysMsg)); for (iPriority=0;iPriority<=SYS_MSG_MAX_PRIORITY;iPriority++) { qStatus[iPriority] = SYS_MSG_QueueStatus((SYS_OBJ_HANDLE)iSysMsg,iPriority); } DBPRINTF("Queue Status (4:-1:0): %d, %d, %d, %d, %d\r\n\r\n", qStatus[4],qStatus[3],qStatus[2],qStatus[1],qStatus[0]); while ( (pQElement = SYS_MSG_MessageReceive(iSysMsg)) != NULL ) { SYS_MSG_MessageDeliver(iSysMsg,pQElement); for (iPriority=0;iPriority<=SYS_MSG_MAX_PRIORITY;iPriority++) { qStatus[iPriority] = SYS_MSG_QueueStatus((SYS_OBJ_HANDLE)iSysMsg,iPriority); } DBPRINTF("Queue Status (4:-1:0): %d, %d, %d, %d, %d\r\n\r\n", qStatus[4],qStatus[3],qStatus[2],qStatus[1],qStatus[0]); } DBPRINTF("Got Messages: %d\r\n",SYS_MSG_GotMessages(iSysMsg)); } return 0; } 5.7.6.4.1 Abstraction Model This library provides an abstraction of the messaging subsystem that is used by device drivers, middleware libraries and applications to receive and control interrupts in real time. and supporting text 5.7.6.4.2 Library Overview The following diagram describes the major components of the usage model. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3442 Library Usage Model Each of the blocks in the diagram correspond to the library interface section. Library Interface Section Description Initialization, Tasks, and Versioning Functions Provides Mailbox Functions Provides Message Type Functions Provides Message Send/Receive Functions Provides Utility Functions Provides Configuration Functions Provides 5.7.6.4.3 How the Library Works The Messaging System Service Library can be used by a device driver, middleware layer, or application to provide access to, and control over, interrupts to the processor. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the modes supported for your device. 5.7.6.5 Configuring the Library The file framework/system/msg/config/sys_msg_config.h provides configuration parameters that the implementer can use to adapt the System Messaging Service library to a particular application. By default, the system message format provides 64 bits of information in a message: typedef union { struct { uint16_t param0; // Message parameter zero uint16_t param1; // Message parameter one uint16_t param2; // Message parameter two uint16_t nMessageTypeID; // Message type identifier }; struct { uint16_t nSource; // Message source identifier uintptr_t * pData; // Pointer to additional message data }; } SYS_MSG_OBJECT; The only required field in the message format definition is nMessageTypeID. But it doesn't need to be 16 bits long. The maximum number of mailboxes is defined by: #define SYS_MSG_MAX_MAILBOXES (32) The minimum number of mailboxes is one. The maximum number of message types is defined by: #define SYS_MSG_MAX_TYPES (32) The minimum number of message types is one. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3443 Message priorities run from zero to SYS_MSG_MAX_PRIORITY, which is defined by: #define SYS_MSG_MAX_PRIORITY (4) For each message priority from 0,1, to SYS_MSG_MAX_PRIORITY a queue is created. The size of each queue is defined by: // Message Priority: 0 1 2 3 4 #define SYS_MSG_BUFFER_SIZES { 64, 32, 16, 8, 4 } In this example there are five priorities, 0,1,..4, and the sizes of each message queue is provided in the definition of SYS_MSB_BUFFER_SIZES. Then this information is used when initializing the System Messaging Service in the application startup code: SYS_OBJ_HANDLE hSysMsg; {//SYS_MSG_Initialize uint16_t nQSizes[] = SYS_MSG_BUFFER_SIZES; hSysMsg = SYS_MSG_Initialize(SYS_MSG_MAX_PRIORITY+1,nQSizes); SYS_ASSERT( SYS_OBJ_HANDLE_INVALID != hSysMsg,"Bad hSysMsg!" ); } 5.7.6.6 Building the Library This section list the files that are available in the \src of the System Message Service Library driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.7.6.7 Library Interface Data Types and Constants Name Description SYS_MSG_INIT Contains all the data necessary to initialize an instance of the System Messaging Service. SYS_MSG_INSTANCE System Messaging instances numbering is from 0,1, to SYS_MSG_MAX_INSTANCE. SYS_MSG_OBJECT This is type SYS_MSG_OBJECT. SYS_MSG_QUEUE_STATUS Messaging queue status enumeration. SYS_MSG_RECEIVE_CALLBACK Pointer to the System Message Received Callback Function SYS_MSG_RESULTS Enumeration of message send results. SYS_MSGQ_ELEMENT Defines queue element for message queue belonging to each priority. _SYS_MSG_H This is macro _SYS_MSG_H. _SYS_MSG_OBJECT Defines the contents of a system message. SYS_MSG_MAILBOXES_ADDONE don't need to round up the number of bitmaps SYS_MSG_NUM_MAILBOX_BITMAPS This is macro SYS_MSG_NUM_MAILBOX_BITMAPS. Configuration Functions Name Description SYS_MSG_BUFFER_SIZES define SYS_MSG_BUFFER_SIZES { 4, 4, 4, 4, 1 SYS_MSG_MAX_MAILBOXES Specifies the maximum number of mailboxes possible. SYS_MSG_MAX_MSGS_DELIVERED Specifies the maximum number of messages delivered per each call to SYS_MSG_Tasks. SYS_MSG_MAX_PRIORITY Specifies the maximum message priority. SYS_MSG_MAX_TYPES Specifies the maximum number of message types possible. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3444 Initialization, Tasks, and Versioning Functions Name Description SYS_MSG_Deinitialize Deinitializes System Messaging Instance. SYS_MSG_Initialize Configures and initializes the messaging subsystem. SYS_MSG_Tasks System Messaging Service Tasks routine. SYS_MSG_VersionGet Gets the System Messaging Service version in numerical format. SYS_MSG_VersionStrGet Gets System Messaging Service version in string format. Mailbox Functions Name Description SYS_MSB_MailboxClose Closes (destroys) a mailbox previously opened with SYS_MSB_MailboxOpen. SYS_MSB_MailboxOpen Opens a system messaging mailbox. SYS_MSB_MailboxReinit Reinitialize previously opened mailbox. SYS_MSG_MailboxMessagesGet Get queued messages for a mailbox. SYS_MSG_MailboxMsgAdd Adds a message type to the list of messages received by a mailbox. SYS_MSG_MailboxMsgRemove Removes a message type from the list of messages received by a mailbox. Message Send/Receive Functions Name Description SYS_MSG_GotMessages Returns true if system messaging has undelivered messages, false otherwise. SYS_MSG_MessageDeliver Deliver message to mailboxes. SYS_MSG_MessageReceive Receive next message in message queues. SYS_MSG_MessageSend Sends a message, as defined by a message structure. Message Type Functions Name Description SYS_MSG_TypeCreate Creates a new message type. SYS_MSG_TypeRemove Removes an existing message type. Utility Functions Name Description SYS_MSG_ID2hMsgType Translates message type identifier into handle of corresponding message type object. SYS_MSG_QueueStatus Returns message queue status for a given message priority. Description 5.7.6.7.1 Initialization, Tasks, and Versioning Functions 5.7.6.7.1.1 SYS_MSG_Deinitialize Function C void SYS_MSG_Deinitialize( SYS_OBJ_HANDLE handleSysMsg ); 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3445 Description Deinitializes System Messaging Instance and frees up allocated memory for it. Preconditions None. Parameters Parameters Description hSysMsg handle to System Messaging Object for instance to be removed. Returns None. Remarks None. Example SYS_OBJ_HANDLE hSysMsg; uint16_t nQSizes[] = SYS_MSG_BUFFER_SIZES; // Initialize the messaging system. This needs to done in the initialization code. // Choose System Messaging instance that supports 8 byte messages hSysMsg = SYS_MSG_Initialize(SYS_MSG_8Bytes,SYS_MSG_MAX_PRIORITY+1,nQSizes); if (SYS_OBJ_HANDLE_INVALID == hSysMsg) { // Handle error } . . . // Remove this instance. SYS_MSG_Deinitialize( hSysMsg ); 5.7.6.7.1.2 SYS_MSG_Initialize Function C SYS_OBJ_HANDLE SYS_MSG_Initialize( const SYS_MSG_INSTANCE iSysMsg, SYS_OBJ_HANDLE pInitializeSysMsg ); Description This routine configures and initializes the messaging subsystem appropriately for the current system design. Preconditions None. Parameters Parameters Description iSysMsg Index of System Messaging Service to be initialized. pInitSysMsg Pointer to System Messaging initialization data structure. If NULL default config values are used. Returns Handle to the System Messaging object created. Returns SYS_OBJ_HANDLE_INVALID if allocation of data structure fails. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3446 Returns SYS_OBJ_HANDLE_INVALID if pointer to initialization data structure is NULL. Remarks None. Example SYS_OBJ_HANDLE hSysMsg; SYS_MSG_INIT sInitSysMsg = { 0, (SYS_MSG_MAX_PRIORITY+1), { SYS_MSG_BUFFER_SIZES } }; //uint16_t nQSizes[] = SYS_MSG_BUFFER_SIZES; // Initialize the messaging system. This needs to done in the initialization code. // Choose System Messaging instance that supports 8 byte messages hSysMsg = SYS_MSG_Initialize(SYS_MSG_8Bytes,&sInitSysMsg); if (SYS_OBJ_HANDLE_INVALID == hSysMsg) { // Handle error } 5.7.6.7.1.3 SYS_MSG_Tasks Function C void SYS_MSG_Tasks( SYS_OBJ_HANDLE handleSysMsg ); Description System Messaging Service Tasks routine. Preconditions hSysMsg must have been returned from a call to SYS_MSG_Initialize. Parameters Parameters Description hSysMsg handle to System Messaging Object. Returns None. Remarks None. Example while ( SYS_MSG_GotMessages(iSysMsg) ) { SYS_MSG_Tasks(hSysMsg); } 5.7.6.7.1.4 SYS_MSG_VersionGet Function C unsigned int SYS_MSG_VersionGet(); Description This routine gets the System Messaging Service version. The version is encoded as major * 10000 + minor * 100 + patch. The stringized version can be obtained using SYS_MSG_VersionStrGet() 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3447 Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for. Returns Current System Messaging Service version in numerical format. Remarks None. Example unsigned int version; version = SYS_MSG_VersionGet(); if(version < 110200) { // Do Something } 5.7.6.7.1.5 SYS_MSG_VersionStrGet Function C char * SYS_MSG_VersionStrGet(); Description This routine gets the System Messaging Service version. The version is returned as major.minor.path[type], where type is optional. The numerical version can be obtained using SYS_MSG_VersionGet() Preconditions None. Parameters Parameters Description drvIndex Identifier for the object instance to get the version for. Returns Current System Messaging Service version in the string format. Remarks None. Example char *version; version = SYS_MSG_VersionStrGet(); printf("%s", version); 5.7.6.7.2 Mailbox Functions 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3448 5.7.6.7.2.1 SYS_MSB_MailboxClose Function C void SYS_MSB_MailboxClose( SYS_OBJ_HANDLE hMailbox ); Description Closes (destroys) a mailbox previously opened with SYS_MSB_MailboxOpen. Preconditions hMailbox provided by call to SYS_MSB_MailboxOpen. Parameters Parameters Description hMailbox Handle to mailbox that is to be closed (destroyed). Returns None. None. Example SYS_OBJ_HANDLE hMyMailbox; hMyMailbox = SYS_MSB_MailboxOpen( iSysMsg, &myCallBackFunction ); SYS_MSB_MailboxClose(hMyMailbox); 5.7.6.7.2.2 SYS_MSB_MailboxOpen Function C SYS_OBJ_HANDLE SYS_MSB_MailboxOpen( const SYS_MSG_INSTANCE iSysMsg, SYS_MSG_RECEIVE_CALLBACK msgCallBackFunction ); Description Opens a system messaging mailbox, providing a message callback function that is called whenever a message is received. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Message callback function will not be called until SYS_MSG_MailboxSignUp has been used to sign up the mailbox for messages of interest. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. msgCallBackFunction pointer to message callback function Returns Handle to new system messaging mailbox. Remarks A null callback function disables messaging callbacks. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3449 Example SYS_OBJ_HANDLE hMyMailbox; hMyMailbox = SYS_MSB_MailboxOpen( iSysMsg, &myCallBackFunction ); if (SYS_OBJ_HANDLE_INVALID == SYS_MSG_TypeRemove) { // Handle error } 5.7.6.7.2.3 SYS_MSB_MailboxReinit Function C void SYS_MSB_MailboxReinit( SYS_OBJ_HANDLE hMailbox, SYS_MSG_RECEIVE_CALLBACK msgCallBackFunction ); Description Reinitialize previously opened mailbox by providing new call back function and clearing all message type assignments. Preconditions hMailbox provided by call to SYS_MSB_MailboxOpen. Parameters Parameters Description hMailbox Object handle to mailbox msgCallBackFunction pointer to new message callback function Remarks A null callback function disables messaging callbacks. Example SYS_OBJ_HANDLE hMyMailbox; hMyMailbox = SYS_MSB_MailboxOpen( iSysMsg, &myCallBackFunction ); SYS_MSB_MailboxReinit(hMyMailbox,&anotherCallBackFunction ); 5.7.6.7.2.4 SYS_MSG_MailboxMessagesGet Function C SYS_MSG_OBJECT * SYS_MSG_MailboxMessagesGet( SYS_OBJ_HANDLE hMailbox ); Description Get queued messages for a mailbox. Messages returned by this function will not be received via the mailbox's callback function. Preconditions hMailbox provided by call to SYS_MSB_MailboxOpen. Parameters Parameters Description hMailbox Object handle to mailbox Returns Pointer to next message in the queue(s) that is of interest to the mailbox. Function returns NULL if no messages are found in the 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3450 queue. Remarks None. Example SYS_MSG_OBJECT *pNextMessage; while ( NULL != (pNextMessage = SYS_MSG_MailboxMessagesGet(hMyMailbox)) ) { // Process message at *pNextMessage. } 5.7.6.7.2.5 SYS_MSG_MailboxMsgAdd Function C void SYS_MSG_MailboxMsgAdd( SYS_OBJ_HANDLE hMailbox, SYS_OBJ_HANDLE hMsgType ); Description Adds a message type to the list of messages received by a mailbox. Preconditions hMailbox provided by call to SYS_MSB_MailboxOpen. Parameters Parameters Description hMailbox Object handle to mailbox hMsgType Handle to message type of interest for this mailbox. Returns None. Remarks When the message type handle is unknown but the message ID is known use SYS_MSG_ID2hMsgType to provide the message type handle. See code example. Example const SYS_MSG_INSTANCE iSysMsg; SYS_OBJ_HANDLE hMsgType[5], hMailbox[3]; // Create three mailboxes hMailbox[0] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack0 ); hMailbox[1] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack1 ); hMailbox[2] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack2 ); // Create five message types // Message ID: :Priority hMsgType[0] = SYS_MSG_TypeCreate(iSysMsg,1<<0,0); hMsgType[1] = SYS_MSG_TypeCreate(iSysMsg,1<<1,1); hMsgType[2] = SYS_MSG_TypeCreate(iSysMsg,1<<2,2); hMsgType[3] = SYS_MSG_TypeCreate(iSysMsg,1<<3,3); hMsgType[4] = SYS_MSG_TypeCreate(iSysMsg,1<<4,4); // Add messages to each mailbox SYS_MSG_MailboxMsgAdd(hMailbox[0],hMsgType[0]); SYS_MSG_MailboxMsgAdd(hMailbox[1],hMsgType[1]); SYS_MSG_MailboxMsgAdd(hMailbox[2],hMsgType[2]); 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3451 SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<1)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<2)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<3)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<4)); 5.7.6.7.2.6 SYS_MSG_MailboxMsgRemove Function C void SYS_MSG_MailboxMsgRemove( SYS_OBJ_HANDLE hMailbox, SYS_OBJ_HANDLE hMsgType ); Description Removes a message type from the list of messages received by a mailbox. Preconditions hMailbox provided by call to SYS_MSB_MailboxOpen. Parameters Parameters Description hMailbox Object handle to mailbox hMsgType Handle to message type to be ignored by this mailbox. Returns None. Remarks When the message type handle is unknown but the message ID is known use SYS_MSG_ID2hMsgType to provide the message type handle. See code example. Example const SYS_MSG_INSTANCE iSysMsg; SYS_OBJ_HANDLE hMsgType[5], hMailbox[3]; // Create three mailboxes hMailbox[0] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack0 ); hMailbox[1] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack1 ); hMailbox[2] = SYS_MSB_MailboxOpen( iSysMsg, &myCallBack2 ); // Create five message types // Message ID: :Priority hMsgType[0] = SYS_MSG_TypeCreate(iSysMsg,1<<0,0); hMsgType[1] = SYS_MSG_TypeCreate(iSysMsg,1<<1,1); hMsgType[2] = SYS_MSG_TypeCreate(iSysMsg,1<<2,2); hMsgType[3] = SYS_MSG_TypeCreate(iSysMsg,1<<3,3); hMsgType[4] = SYS_MSG_TypeCreate(iSysMsg,1<<4,4); // Add messages to each mailbox SYS_MSG_MailboxMsgAdd(hMailbox[0],hMsgType[0]); SYS_MSG_MailboxMsgAdd(hMailbox[1],hMsgType[1]); SYS_MSG_MailboxMsgAdd(hMailbox[2],hMsgType[2]); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<1)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<2)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<3)); SYS_MSG_MailboxMsgAdd(hMailbox[0],SYS_MSG_ID2hMsgType(iSysMsg,1<<4)); 5.7.6.7.3 Message Type Functions 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3452 5.7.6.7.3.1 SYS_MSG_TypeCreate Function C SYS_OBJ_HANDLE SYS_MSG_TypeCreate( const SYS_MSG_INSTANCE iSysMsg, uint8_t nMessageTypeID, uint8_t nMessagePriority ); Description Creates a new message type, defining an integer message type and priority. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. nMessageTypeID Integer message type identifier nMessagePriority Message priority, between 0 and SYS_MSG_MAX_PRIORITIES Returns Handle to new message type definition. Remarks None. Example SYS_OBJ_HANDLE hMsgType; hMsgType = SYS_MSG_TypeCreate( iSysMsg, 1, 3 ); if (SYS_OBJ_HANDLE_INVALID == hMsgType) { // Handle error } 5.7.6.7.3.2 SYS_MSG_TypeRemove Function C void SYS_MSG_TypeRemove( SYS_OBJ_HANDLE hMsgType ); Description Remmoves an existing message type. Preconditions None. Parameters Parameters Description hMsgType Handle to message type that is to be removed Returns None. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3453 Remarks When the message type handle is unknown but the message ID is known use SYS_MSG_ID2hMsgType to provide the message type handle. See code example. Example SYS_OBJ_HANDLE hMsgType; hMsgType = SYS_MSG_TypeCreate( iSysMsg, 1, 3 ); SYS_MSG_TypeRemove( hMsgType ); Alternately: SYS_OBJ_HANDLE hMsgType; hMsgType = SYS_MSG_TypeCreate( iSysMsg, 1, 3 ); SYS_MSG_TypeRemove( SYS_MSG_ID2hMsgType(iSysMsg,1) ); 5.7.6.7.4 Message Send/Receive Functions 5.7.6.7.4.1 SYS_MSG_GotMessages Function C bool SYS_MSG_GotMessages( const SYS_MSG_INSTANCE iSysMsg ); Description Returns true if system messaging has undelivered messages, false otherwise. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. Returns True if there are undelivered system messages, false otherwise. Remarks None. Example DBPRINTF("rnGot Messages: %drn",SYS_MSG_GotMessages(iSysMsg)); while ( (pNextMessage = SYS_MSG_MessageReceive(iSysMsg)) != NULL ) { SYS_MSG_MessageDeliver(iSysMsg,pNextMessage); DBPRINTF("rn"); } DBPRINTF("Got Messages: %drn",SYS_MSG_GotMessages(ihSysMsg)); 5.7.6.7.4.2 SYS_MSG_MessageDeliver Function C void SYS_MSG_MessageDeliver( const SYS_MSG_INSTANCE iSysMsg, SYS_MSGQ_ELEMENT * pQElement ); 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3454 Description Deliver message to mailboxes, remove message from queue when done. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. pQElement pointer to queue element to be delivered. Returns None. Remarks None. Example SYS_MSGQ_ELEMENT *pQElement; SYS_MSG_OBJECT nextMessage; while ( (pQElement = SYS_MSG_MessageReceive(iSysMsg)) != NULL ) { // In case you desire to examine message before delivering it. nextMessage = pQElement->sMessage; // Deliver message to all interested mailboxes SYS_MSG_MessageDeliver(iSysMsg,pQElement); } 5.7.6.7.4.3 SYS_MSG_MessageReceive Function C SYS_MSGQ_ELEMENT * SYS_MSG_MessageReceive( const SYS_MSG_INSTANCE iSysMsg ); Description Receive next message in message queues, returning NULL if queues are empty. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. Returns Pointer to next message, as found in a message queue element, NULL if there are no messages. Remarks None. Example SYS_MSGQ_ELEMENT *pQElement; SYS_MSG_OBJECT nextMessage; while ( (pQElement = SYS_MSG_MessageReceive(iSysMsg)) != NULL ) 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3455 { // In case you desire to examine message before delivering it. nextMessage = pQElement->sMessage; // Deliver message to all interested mailboxes SYS_MSG_MessageDeliver(iSysMsg,pQElement); } 5.7.6.7.4.4 SYS_MSG_MessageSend Function C SYS_MSG_RESULTS SYS_MSG_MessageSend( const SYS_MSG_INSTANCE iSysMsg, SYS_MSG_OBJECT * pMessage ); Description Sends a message, as defined by a message structure. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. pMessage Pointer to message definition. Returns Message result from SYS_MSG_RESULTS enumeration. Remarks None. Example SYS_MSG_OBJECT myMessage; SYS_MSG_RESULTS myMessageStatus; SYS_OBJ_HANDLE hMyMsgType; hMyMsgType = SYS_MSG_TypeCreate( iSysMsg, 1, 3 ); if (SYS_OBJ_HANDLE_INVALID == hMyMsgType) { // Handle error } myMessage.hMsgType = hMyMsgType; myMessage.nSource = myMsgSource; myMessage.param1 = parameterOneValue; myMessage.param1 = parameterTwoValue; myMessageStatus = SYS_MSG_MessageSend(iSysMsg,&myMessage); SYS_ASSERT( myMessageStatus > 0, "Bad message status!" ); 5.7.6.7.5 Utility Functions 5.7.6.7.5.1 SYS_MSG_ID2hMsgType Function C SYS_OBJ_HANDLE SYS_MSG_ID2hMsgType( 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3456 const SYS_MSG_INSTANCE iSysMsg, uint8_t nMessageTypeID ); Description Translates message type identifier into handle of corresponding message type object. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. Parameters Parameters Description iSysMsg Index of System Messaging Service instance. nMessageTypeID Integer message type identifier. Returns Handle to message type definition object corresponding to the message type identifier. Returns NULL if the message type is not defined. Remarks This function is useful in situations where the message type identifier is known but the message type handle is not. This allows applications to statically define message type IDs and use them in code instead of having to wait until message handles are known and then dynamically sharing message handles via global variables. Example #define MY_MESSAGE_TYPE_ID 1; // Create message type SYS_OBJ_HANDLE hMsgType; uint8_t nPriority = 3; hMsgType = SYS_MSG_TypeCreate( iSysMsg, MY_MESSAGE_TYPE_ID, nPriority ); if (SYS_OBJ_HANDLE_INVALID == hMsgType) { // Handle error } . . . // Remove message type without knowing message type handle SYS_MSG_TypeRemove(iSysMsg,SYS_MSG_ID2hMsgType(iSysMsg,MY_MESSAGE_TYPE_ID)); 5.7.6.7.5.2 SYS_MSG_QueueStatus Function C SYS_MSG_QUEUE_STATUS SYS_MSG_QueueStatus( const SYS_MSG_INSTANCE iSysMsg, uint8_t nMessagePriority ); Description Returns message queue status for a given message priority. Preconditions iSysMsg must have been used in a call to SYS_MSG_Initialize. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3457 Parameters Parameters Description iSysMsg Index of System Messaging Service instance. nMessagePriority message priority of interest, from zero to SYS_MSG_MAX_PRIORITIES. Returns Number of messages in queue if not full or SYS_MSG_QUEUE_FULL if full. If message priority is not legal, returns SYS_MSG_QUEUE_BAD. Remarks None. Example 5.7.6.7.6 Configuration Functions 5.7.6.7.6.1 SYS_MSG_BUFFER_SIZES Macro C #define SYS_MSG_BUFFER_SIZES { 16 } Description define SYS_MSG_BUFFER_SIZES { 4, 4, 4, 4, 1 5.7.6.7.6.2 SYS_MSG_MAX_MAILBOXES Macro C #define SYS_MSG_MAX_MAILBOXES (2) Description System Messaging Max Number of Mailboxes Specifies the maximum number of mailboxes possible. Remarks Minimum number is 1 mailbox. 5.7.6.7.6.3 SYS_MSG_MAX_MSGS_DELIVERED Macro C #define SYS_MSG_MAX_MSGS_DELIVERED (1) Description System Messaging Maximum Number of Messages Delivered per call to SYS_MSG_Tasks Specifies the maximum number of messages delivered per each call to SYS_MSG_Tasks. If zero then all message queues are emptied before the tasks routine finishes execution. Remarks 0 implies all queues are empty after SYS_MSG_Tasks is done. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3458 5.7.6.7.6.4 SYS_MSG_MAX_PRIORITY Macro C #define SYS_MSG_MAX_PRIORITY (0) Description System Messaging Maximum Priority Specifies the maximum message priority. Remarks Message priorities run from 0 to SYS_MSG_MAX_PRIORITIES. The number of message queues is SYS_MSG_MAX_PRIORITIES+1. 5.7.6.7.6.5 SYS_MSG_MAX_TYPES Macro C #define SYS_MSG_MAX_TYPES (2) Description System Messaging Max Number of Message Types Specifies the maximum number of message types possible. Remarks Minimum number is 1. 5.7.6.7.7 Data Types and Constants 5.7.6.7.7.1 SYS_MSG_INIT Structure C typedef struct { uint8_t nMaxMsgsDelivered; uint8_t nMessagePriorities; uint16_t * nQSizes; } SYS_MSG_INIT; Description System Messaging Service Initialization Data Contains all the data necessary to initialize an instance of the System Messaging Service. Members Members Description uint8_t nMaxMsgsDelivered; Maximum number of messages delivered per call to SYS_MSG_Tasks uint8_t nMessagePriorities; Number of message priorities desired uint16_t * nQSizes; Array of qukeue sizes for priorities 0,1,...SYS_MSG_MAX_PRIORITY Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the SYS_MSG_Initialize routine. If nMaxMsgsDelivered == 0 then ALL messages in priority queues are delivered each time SYS_MSG_Tasks is called. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3459 5.7.6.7.7.2 SYS_MSG_INSTANCE Enumeration C typedef enum { SYS_MSG_0, SYS_MSG_1, SYS_MSG_2, SYS_MSG_3, SYS_MSG_4, SYS_MSG_NUM_INSTANCES } SYS_MSG_INSTANCE; Description Enumeration of the Allowable of System Messaging Instances System Messaging instances numbering is from 0,1, to SYS_MSG_MAX_INSTANCE. Remarks None. 5.7.6.7.7.3 SYS_MSG_OBJECT Structure C typedef struct { union { struct { uint8_t nMessageTypeID; uint8_t nSource; uint16_t param0; uint16_t param1; uint16_t param2; } struct { uint16_t dummy; uint16_t nSizeData; uintptr_t * pData; } } } SYS_MSG_OBJECT; Description This is type SYS_MSG_OBJECT. Members Members Description uint8_t nMessageTypeID; Message type identifier uint8_t nSource; Message source identifier uint16_t param0; Message parameter zero uint16_t param1; Message parameter one uint16_t param2; Message parameter two uint16_t nSizeData; Size of data that pData identifies uintptr_t * pData; Pointer to additional message data 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3460 5.7.6.7.7.4 SYS_MSG_QUEUE_STATUS Enumeration C typedef enum { SYS_MSG_QUEUE_BAD, SYS_MSG_QUEUE_FULL, SYS_MSG_QUEUE_EMPTY } SYS_MSG_QUEUE_STATUS; Description System Messaging Queue Status Enumeration Messaging queue status enumeration. Positive values indicate number of messages in the queue. Members Members Description SYS_MSG_QUEUE_BAD QUEUE Status: full SYS_MSG_QUEUE_FULL QUEUE Status: full SYS_MSG_QUEUE_EMPTY QUEUE Status: empty Remarks None. 5.7.6.7.7.5 SYS_MSG_RECEIVE_CALLBACK Type C typedef void (* SYS_MSG_RECEIVE_CALLBACK)(SYS_MSG_OBJECT *pMessage); Description Pointer to the System Message Received Callback Function Pointer to the function provided for each system messaging mailbox that is called when a system message is received for each mailbox. 5.7.6.7.7.6 SYS_MSG_RESULTS Enumeration C typedef enum { SYS_MSG_NOT_SENT_QFULL, SYS_MSG_BAD_PRIORITY, SYS_MSG_BAD_MSGTYPE, SYS_MSG_NOT_SENT, SYS_MSG_SENT } SYS_MSG_RESULTS; Description System Messaging Results Enumeration Enumeration of message send results. Members Members Description SYS_MSG_NOT_SENT_QFULL Message could not be sent, no room available in priority queues SYS_MSG_BAD_PRIORITY Message could not be sent, Message Message priority bad SYS_MSG_BAD_MSGTYPE Message could not be sent, Message type bad 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3461 SYS_MSG_NOT_SENT Message could not be sent, no other information available SYS_MSG_SENT Message sent Remarks SYS_MSG_SENT aligns with SYS_MSGQ_Success. SYS_MSG_NOT_SENT aligns with SYS_MSGQ_Failure 5.7.6.7.7.7 SYS_MSGQ_ELEMENT Structure C typedef struct { SYS_MSG_OBJECT sMessage; uint16_t mailboxInterestBitMap[SYS_MSG_NUM_MAILBOX_BITMAPS]; } SYS_MSGQ_ELEMENT; Description System Messaging Queues Element Defines queue element for message queue belonging to each priority. Members Members Description SYS_MSG_OBJECT sMessage; System Message Bit map for mailboxes interested in this message type, modified as each mailbox is notified. Remarks None 5.7.6.7.7.8 _SYS_MSG_H Macro C #define _SYS_MSG_H Description This is macro _SYS_MSG_H. 5.7.6.7.7.9 _SYS_MSG_OBJECT Macro C #define _SYS_MSG_OBJECT Description System Message Format Defines the contents of a system message. This information is copied into an element of the system message queue identified by the message priority. Remarks None 5.7.6.7.7.10 SYS_MSG_MAILBOXES_ADDONE Macro C #define SYS_MSG_MAILBOXES_ADDONE 0 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3462 Description don't need to round up the number of bitmaps 5.7.6.7.7.11 SYS_MSG_NUM_MAILBOX_BITMAPS Macro C #define SYS_MSG_NUM_MAILBOX_BITMAPS (SYS_MSG_MAX_MAILBOXES/16 + SYS_MSG_MAILBOXES_ADDONE) Description This is macro SYS_MSG_NUM_MAILBOX_BITMAPS. 5.7.6.8 Files Files Name Description sys_msg.h System Service for the messaging module. sys_msg_config.h System Messaging Configuration definitions file Description 5.7.6.8.1 sys_msg.h Messaging System-Library Interface Definition This file contains the interface definition for the messaging system service. It provides a way to interact with the messaging subsystem. Enumerations Name Description SYS_MSG_INSTANCE System Messaging instances numbering is from 0,1, to SYS_MSG_MAX_INSTANCE. SYS_MSG_QUEUE_STATUS Messaging queue status enumeration. SYS_MSG_RESULTS Enumeration of message send results. Functions Name Description SYS_MSB_MailboxClose Closes (destroys) a mailbox previously opened with SYS_MSB_MailboxOpen. SYS_MSB_MailboxOpen Opens a system messaging mailbox. SYS_MSB_MailboxReinit Reinitialize previously opened mailbox. SYS_MSG_Deinitialize Deinitializes System Messaging Instance. SYS_MSG_GotMessages Returns true if system messaging has undelivered messages, false otherwise. SYS_MSG_ID2hMsgType Translates message type identifier into handle of corresponding message type object. SYS_MSG_Initialize Configures and initializes the messaging subsystem. SYS_MSG_MailboxMessagesGet Get queued messages for a mailbox. SYS_MSG_MailboxMsgAdd Adds a message type to the list of messages received by a mailbox. SYS_MSG_MailboxMsgRemove Removes a message type from the list of messages received by a mailbox. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3463 SYS_MSG_MessageDeliver Deliver message to mailboxes. SYS_MSG_MessageReceive Receive next message in message queues. SYS_MSG_MessageSend Sends a message, as defined by a message structure. SYS_MSG_QueueStatus Returns message queue status for a given message priority. SYS_MSG_Tasks System Messaging Service Tasks routine. SYS_MSG_TypeCreate Creates a new message type. SYS_MSG_TypeRemove Removes an existing message type. SYS_MSG_VersionGet Gets the System Messaging Service version in numerical format. SYS_MSG_VersionStrGet Gets System Messaging Service version in string format. Macros Name Description _SYS_MSG_H This is macro _SYS_MSG_H. _SYS_MSG_OBJECT Defines the contents of a system message. SYS_MSG_MAILBOXES_ADDONE don't need to round up the number of bitmaps SYS_MSG_NUM_MAILBOX_BITMAPS This is macro SYS_MSG_NUM_MAILBOX_BITMAPS. SYS_OBJ_HANDLE_INVALID This is macro SYS_OBJ_HANDLE_INVALID. SYS_OBJ_HANDLE_STATIC This is macro SYS_OBJ_HANDLE_STATIC. Structures Name Description SYS_MSG_INIT Contains all the data necessary to initialize an instance of the System Messaging Service. SYS_MSG_OBJECT This is type SYS_MSG_OBJECT. SYS_MSGQ_ELEMENT Defines queue element for message queue belonging to each priority. Types Name Description SYS_MSG_RECEIVE_CALLBACK Pointer to the System Message Received Callback Function SYS_OBJ_HANDLE SYS_MODULE_OBJ is badly named. It should be SYS_MODULE_OBJ_HANDLE or something shorter. For brevity, it is renamed to SYS_OBJ_HANDLE. File Name sys_msg.h Company Microchip Technology Incorported 5.7.6.8.2 sys_msg_config.h System Messaging Configuration Definitions These definitions statically define the operation of the System Messaging service. Macros Name Description SYS_MSG_BUFFER_SIZES define SYS_MSG_BUFFER_SIZES { 4, 4, 4, 4, 1 SYS_MSG_MAX_MAILBOXES Specifies the maximum number of mailboxes possible. 5.7 System Service Library Help MPLAB Harmony Help Messaging System Service Library 5-3464 SYS_MSG_MAX_MSGS_DELIVERED Specifies the maximum number of messages delivered per each call to SYS_MSG_Tasks. SYS_MSG_MAX_PRIORITY Specifies the maximum message priority. SYS_MSG_MAX_TYPES Specifies the maximum number of message types possible. File Name sys_msg_config.h Company Microchip Technology Incorported 5.7.7 Ports System Service Library 5.7.7.1 Introduction Ports System Service Library for Microchip Microcontrollers This library provides an interface to manage and control general purpose input or output ports (GPIO) controlled by the PORTx modules on the Microchip families of microcontrollers. Overview One challenge designers of general purpose microcontroller devices face is to provide a large set of available peripheral features on parts with a limited number of I/O pins. To help meet this challenge and to provide flexibilty for board designers, many parts provide an ability to route I/O signals for selected peripherals to different I/O pins. Still, in some cases, general purpose I/O pins must be used to implement the desired functionality under direct software control. The purpose of the ports system service is to provide direct control if general purpose I/O pins and to support the selection of the desired peripheral functionality for supported I/O pins and ports. General purpose I/O pins can be controlled individually, but they are also grouped together in sets and can be controlled together as a unit. These groups of GPIO pins are called "ports" on Microchip microcontrollers and this library provides the ability to read and write data patterns to or from them in sets or as individual pins. In addition peripheral IO routing and pin/port control, this library provides the ability to select and configure several other features of the I/O pins and ports available on Microchip microcontrollers as described below. Other Features • Individual output pin/port open-drain enable/disable • Individual input pin/port pull-up enable/disable • Monitor select inputs and generate interrupt on mismatch condition [Change Notification] • Operate during CPU Sleep and Idle modes • Port line Analog/Digital Selection 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3465 • Port slew rate control Note: Trademarks and Intellectual Property are property of their respective owners. Customers are responsible for obtaining appropriate licensing or rights before using this software. 5.7.7.2 Release Notes MPLAB Harmony Version: v0.70b Ports System Service Library Library Version : 0.01 Release Date: %ReleaseNotes% New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.7.4 Using the Library This topic describes the basic architecture of the Ports System Service Library and provides information and examples on how to use it. Interface Header File: sys_ports.h The interface to the Ports System Service Library is defined in the "sys_ports.h" header file, which is included by the "sys.h" header file. Any C language source (.c) file that uses the Ports System Service must include "sys.h". 5.7.7.4.1 Abstraction Model This model explains how the system interfaces with the Ports System Service and the application as depicted in the below diagram. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3466 General Purpose I/O: All port pins have three registers directly associated with their operation as digital I/O. The Data Direction register determines whether the pin is an input or an output. If the data direction bit is a ‘1’, then the pin is an input. All port pins are defined as inputs after a Reset. Reads from the Output Latch register, read the latch. Writes to the latch, write the latch. Reads from the port, read the port pins, while writes to the port pins, write the latch. The pull-ups act as a current source or sink source connected to the pin, and eliminates the need for external resistors when push-button or keypad devices are connected. These pull-ups prevent floating state of the pins by providing voltage to it. These features are available on some pins and some parts. Please check the data sheet of the specific device for further information. The open-drain feature allows the generation of outputs higher than VDD (e.g., 5V) on any desired digital only pins by using external pull-up resistors. The maximum open-drain voltage allowed is the same as the maximum VIH specification. The input change notification function of the I/O ports allows the microcontrollers to generate interrupt requests to the processor in response to a change of state on selected input pins. This feature is capable of detecting input change of states even in Sleep mode, when the clocks are disabled. The Alternate Pin Function selections are used to steer specific peripheral input and output functions between different pins. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3467 The output slew rate of each port is programmable to select either the standard transition rate or a reduced transition rate of x times the standard to minimize EMI. The reduced transition time is the default slew rate for all ports. Peripheral Pin Select: AVAILABLE PINS: The number of available pins is dependent on the particular device and its pin count. Pins that support the peripheral pin select feature include the designation “RPn” in their full pin designation, where “RP” designates a remappable peripheral and “n” is the remappable port number. AVAILABLE PERIPHERALS: The peripherals managed by the peripheral pin select are all digital-only peripherals. These include general serial communications (UART and SPI), general purpose timer clock inputs, timer-related peripherals (input capture and output compare) and interrupt-on-change inputs. In comparison, some digital-only peripheral modules are never included in the peripheral pin select feature. This is because the peripheral’s function requires special I/O circuitry on a specific port and cannot be easily connected to multiple pins. These modules include I2C among others. A similar requirement excludes all modules with analog inputs, such as the A/D converter. A key difference between remappable and non-remappable peripherals is that remappable peripherals are not associated with a default I/O pin. The peripheral must always be assigned to a specific I/O pin before it can be used. In contrast, non-remappable peripherals are always available on a default pin, assuming that the peripheral is active and not conflicting with another peripheral. When a remappable peripheral is active on a given I/O pin, it takes priority over all other digital I/O and digital communication peripherals associated with the pin. Priority is given regardless of the type of peripheral that is mapped. Remappable peripherals never take priority over any analog functions associated with the pin. INPUT MAPPING: The inputs of the peripheral pin select options are mapped on the basis of the peripheral. That is, a control register associated with a peripheral dictates the pin it will be mapped to. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3468 Note: For input only, peripheral pin select functionality does not have priority over I/Oport settings. Therefore, when configuring Remappable Pin for input,the corresponding bit in the I/O port register must also be configured for input (set to '1'). OUTPUT MAPPING: In contrast to inputs, the outputs of the peripheral pin select options are mapped on the basis of the pin. In this case, a control register associated with a particular pin dictates the peripheral output to be mapped. Mapping Limitations: The control schema of the peripheral select pins is not limited to a small range of fixed peripheral configurations. There are no mutual or hardware-enforced lockouts between any of the peripheral mapping SFRs. Literally any combination of peripheral mappings across any or all of the RPn pins is possible. This includes both many-to-one and one-to-many mappings of peripheral inputs and outputs to pins. While such mappings may be technically possible from a configuration point of view, they may not be supportable from an electrical point of view. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3469 5.7.7.4.2 Library Overview The Ports System Service Library is a MPLAB Harmony system service. Please refer to the system services documentation for a detailed description of MPLAB system services. The library interface routines are divided into various subsections, each subsection addresses one of the blocks or the overall operation of the PORTx module. Library Interface Section Description Pin Control Functions Port bit/pin read/write/toggle/clear/set interfaces. Ports Control Functions Port access read/write/toggle/clear/set interfaces. Change Notification Functions Interface routines for Port line change notification. Peripheral Pin Select Functions Interface routines for mapping the digital input/output to a specific PPS Remappable input/output pin. 5.7.7.4.3 How the Library Works 5.7.7.4.3.1 Pin Control Pins Functions Usage Pin Read: Port pin can be read at bit/pin level using "SYS_PORTS_PinRead" with appropriate parameters. Pin Write: Port pin can be written at bit/pin level using "SYS_PORTS_PinWrite" with appropriate parameters. Pin Clear: Port pin can be cleared at bit/pin level using "SYS_PORTS_PinClear" with appropriate parameters. Pin Set: Port pin can be set at bit/pin level using "SYS_PORTS_PinSet" with appropriate parameters. Pin Direction Control: Port pin direction can be set at bit/pin level using "SYS_PORTS_PinDirectionSelect" with appropriate parameters. The Direction information can be obtained through the interface "SYS_PORTS_DirectionGet". Pin Toggle: Port pin can be toggled at bit/pin level using "SYS_PORTS_PinToggle" with appropriate parameters. Pin Open Drain: Port pin can be enabled open drain functionality at bit/pin level using "SYS_PORTS_PinOpenDrainEnable" with appropriate parameters. Similarly, the Port pin can be disabled open drain functionality at bit/pin level using "SYS_PORTS_PinOpenDrainDisable" with appropriate parameters. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3470 Pin Pull up: Port pin can be enabled pull up functionality at bit/pin level using "SYS_PORTS_PinPullUpEnable" with appropriate parameters. Similarly, the Port pin can be disabled pull up functionality at bit/pin level using "SYS_PORTS_PinPullUpDisable" with appropriate parameters. Example: // PORT Direction setting for output SYS_PORTS_PinDirectionSelect(MY_PORTS_INSTANCE, SYS_PORTS_DIRECTION_OUTPUT, MY_CHANNEL, MY_PINNUM); // PORT Direction setting for input SYS_PORTS_PinDirectionSelect(MY_PORTS_INSTANCE, SYS_PORTS_DIRECTION_INPUT, MY_CHANNEL, MY_PINNUM); // Writing a value into a PORT SYS_PORTS_PinWrite(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM, MY_VALUE); // Reading back the previously written value bool readData = SYS_PORTS_PinRead(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); // Clearing the PORT SYS_PORTS_PinClear(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); // Setting the port SYS_PORTS_PinSet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); // Toggling a PORT SYS_PORTS_PinToggle(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.4.3.2 Ports Control Port Functions Usage Port Read: Ports can be read at byte/word level using the interface "SYS_PORTS_Read" with appropriate parameters. Port Write: Ports can be written to at byte/word level using the interface "SYS_PORTS_Write" appropriate parameters. Port Clear: Ports can be cleared at byte/word level using the interface "SYS_PORTS_Clear" with appropriate parameters. Port Set: Ports can be set at byte/word level using the interface "SYS_PORTS_Set" with appropriate parameters. Port Direction Control: Ports direction can be set at byte/word level using the interface "SYS_PORTS_DirectionSelect" with appropriate parameters. The Direction information can be obtained through the interface "SYS_PORTS_DirectionGet". Port Toggle: Ports can be toggled at byte/word level using the interface "SYS_PORTS_Toggle" with appropriate parameters. Port Open Drain: Ports can be enabled open drain functionality at byte/word level using the interface "SYS_PORTS_OpenDrainEnable" with appropriate parameters. Similarly, the Ports can be disabled open drain functionality at byte/word level using the interface "SYS_PORTS_OpenDrainDisable" with appropriate parameters. Port Pull up: 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3471 Ports can be enabled pull up functionality at byte/word level using the interface "SYS_PORTS_PullUpEnable" with appropriate parameters. Similarly, the Ports can be disabled pull up functionality at byte/word level using the interface "SYS_PORTS_PullUpDisable" with appropriate parameters. Example: // PORT Direction setting for output SYS_PORTS_DirectionSelect(MY_PORTS_INSTANCE, SYS_PORTS_DIRECTION_OUTPUT, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // PORT Direction setting for input SYS_PORTS_DirectionSelect(MY_PORTS_INSTANCE, SYS_PORTS_DIRECTION_INPUT, MY_CHANNEL, (PORTS_DATA_MASK)0xFFFF); // Writing a value into a PORT SYS_PORTS_Write(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_TYPE)0x1234) // Reading back the previously written value PORTS_DATA_TYPE readData = SYS_PORTS_Read(MY_PORTS_INSTANCE, MY_CHANNEL); // Clearing the PORT SYS_PORTS_Clear(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); // Setting the port SYS_PORTS_Set(MY_PORTS_INSTANCE, MY_CHANNEL, 0x1234, (PORTS_DATA_MASK)0x00FF); // Toggling a PORT SYS_PORTS_Toggle(MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF); Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.4.3.3 Change Notification Change Notification Feature Usage The change notification feature can be enabled using "SYS_PORTS_ChangeNotificationEnable". This routine does the following operations. Change notification can be disabled after the successful usage using the interface "SYS_PORTS_ChangeNotificationDisable" Certain microcontrollers support the global control over the change notification feature using the following interfaces "SYS_PORTS_ChangeNotificationGlobalEnable" and "SYS_PORTS_ChangeNotificationGlobalDisable". The status of the change notification pin can be obtained through interface "SYS_PORTS_ChangeNotificationStatus" If there are any requirements to control the pull downs the following interfaces could be used, "SYS_PORTS_ChangeNotificationPullDownEnable" and "SYS_PORTS_ChangeNotificationPullDownDisable" If there are any requirements to control the pull ups the following interfaces could be used, "SYS_PORTS_ChangeNotificationPullUpEnable" and "SYS_PORTS_ChangeNotificationPullUpDisable" Change Notification Operation in Sleep and Idle Modes The change notification module continues to operate during Sleep or Idle mode. Its operation can be enabled /disabled using the interfaces "SYS_PORTS_ChangeNotificationInIdleModeEnable" / "SYS_PORTS_ChangeNotificationInIdleModeDisable" If one of the enabled change notify pins changes states, the respective status bit will be set which can be monitored using the interface "SYS_PORTS_ChangeNotificationStatus". Example: // Enabling the global change notification SYS_PORTS_ChangeNotificationGlobalEnable(MY_PORTS_INSTANCE); // Enabling weak pull-ups for the change notification PIN 10 SYS_PORTS_ChangeNotificationPullUpEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); // Enabling change notification on PIN 10 SYS_PORTS_ChangeNotificationEnable(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10, SYS_PORTS_PULLUP_ENABLE); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3472 // Enabling the change notification in idle mode. SYS_PORTS_ChangeNotificationInIdleModeEnable(MY_PORTS_INSTANCE); //Obtaining the status of the change notification pin. bool status: status = SYS_PORTS_ChangeNotificationStatus(MY_PORTS_INSTANCE, PORTS_CHANGE_NOTICE_PIN_10); Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.4.3.4 Peripheral Pin Select Ports Remapping or Peripheral Pin Select Usage Input/Output Function Remapping: "SYS_PORTS_RemapInputOutput" with appropriate parameters can be used to remap a particular port pin as input.output for a peripheral. Input/Output Lock: "SYS_PORTS_IOLockEnable" and SYS_PORTS_IOLockDisable" with appropriate parameters can be used to lock/unlock a pin. Example: // Remapping input function 'Input Capture 1' to the Remappable input pin 'RPI1' SYS_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, PORTS_REMAP_FUNCTION_IC1, PORTS_REMAP_PIN_RPI1); // Remapping output function 'UART1 Transmit' to the Remappable output pin 'RP3' SYS_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, PORTS_REMAP_FUNCTION_U1TX, PORTS_REMAP_PIN_RP3); Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.4.3.5 Miscellaneous Other Usage Slew Rate: Slew rate of a particular port can be controlled though the interface "SYS_PORTS_SlewRateSetReduced" and "SYS_PORTS_SlewRateSetStandard". Open Drain: Peripheral based open drain can be controlled through the interfaces "SYS_PORTS_PeripheralOpenDrainEnable" and "SYS_PORTS_PeripheralOpenDrainDisable". Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.4.3.6 Special Considerations Note on Ports Usage: 1. Setting a port pin as an analog input also requires that the corresponding direction be set. If the direction is set to output, the digital output level (VOH or VOL) will be outputted. 2. When reading the port register, all pins configured as analog input channels will read as cleared. 3. Pins configured as digital inputs will not output an analog input. Analog levels on any pin that is defined as a digital input may cause the input buffer to consume current that exceeds the device specifications. 4. Pull-ups and pull-downs on change notification pins should always be disabled when the port pin is configured as a digital output. Considerations for the Peripheral Pin Select: 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3473 The ability to control Peripheral Pin Select options introduces several considerations into application design that could be overlooked. This is particularly true for several common peripherals that are available only as remappable peripherals. The main consideration is that the Peripheral Pin Selects are not available on default pins in the device’s default (Reset) state, all Peripheral Pin Select inputs are tied to Vss and all Peripheral Pin Select outputs are disconnected. This situation requires the user to initialize the device with the proper peripheral configuration before any other application code is executed. For application safety, however, it is best to lock the configuration after writing to the control registers. A final consideration is that Peripheral Pin Select functions neither override analog inputs, nor reconfigure pins with analog functions for digital I/O. If a pin is configured as an analog input on device Reset, it must be explicitly reconfigured as digital I/O when used with a Peripheral Pin Select. Note: Not all the features are available on all devices. Please refer to the specific device data sheet to determine availability. 5.7.7.5 Configuring the Library The configuration of the Ports System Service is based on the file sys_config.h This header file contains the configuration selection for the PORTS System Service>. Based on the selections made, the Ports System Service will support or not support selected features. These configuration settings will apply to all instances of the Ports System Service. This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.7.7.6 Building the Library 5.7.7.7 Library Interface Data Types and Constants Name Description SYS_PORTS_PIN_DIRECTION Defines the direction of the port pins. SYS_PORTS_PULLUP_PULLDOWN_STATUS Provides the pull-up and pull-down status. Change Notification Functions Name Description SYS_PORTS_ChangeNotificationDisable Disables the change notification for the selected port. SYS_PORTS_ChangeNotificationEnable Enables the change notification for the selected port. SYS_PORTS_ChangeNotificationGlobalDisable Globally disables the change notification for the selected port. SYS_PORTS_ChangeNotificationGlobalEnable Globally enables the change notification for the selected port. SYS_PORTS_ChangeNotificationInIdleModeDisable Disables the change notification for the selected port in Sleep or Idle mode. SYS_PORTS_ChangeNotificationInIdleModeEnable Enables the change notification for the selected port in Sleep or Idle mode. SYS_PORTS_ChangeNotificationPullDownDisable Disables pull-down on input change. SYS_PORTS_ChangeNotificationPullDownEnable Enables pull-down on input change. SYS_PORTS_ChangeNotificationPullUpDisable Disables pull-up on input change. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3474 SYS_PORTS_ChangeNotificationPullUpEnable Enables a weak pull-up on the change notification pin. SYS_PORTS_ChangeNotificationStatus Gets the status of the corresponding notification pin. Peripheral Pin Select Functions Name Description SYS_PORTS_IOLockDisable Disables the I/O lock. SYS_PORTS_IOLockEnable Enables the I/O lock. SYS_PORTS_IOLockIsActive Returns the status of I/O lock. SYS_PORTS_RemapInput Input/Output (I/O) function remapping. SYS_PORTS_RemapOutput Input/Output (I/O) function remapping. Pin Control Functions Name Description SYS_PORTS_PinModeSelect Enables the selected pin as analog or digital. SYS_PORTS_PinOpenDrainDisable Disables the open-drain functionality for the selected pin. SYS_PORTS_PinOpenDrainEnable Enables the open-drain functionality for the selected pin. SYS_PORTS_PinPullUpDisable Disables the pull-up functionality for the selected pin SYS_PORTS_PinPullUpEnable Enables the pull-up functionality for the selected pin. SYS_PORTS_PinRead Reads the selected digital pin. SYS_PORTS_PinSet Sets the selected digital pin/latch. SYS_PORTS_PinToggle Toggles the selected digital pin. SYS_PORTS_PinWrite Writes the selected digital pin. SYS_PORTS_PinClear Clears the selected digital pin. SYS_PORTS_PinDirectionSelect Enables the direction for the selected pin. Ports Control Functions Name Description SYS_PORTS_Clear Clears the selected digital port. SYS_PORTS_DirectionGet Reads the direction for the selected port. SYS_PORTS_DirectionSelect Enables the direction for the selected port. SYS_PORTS_OpenDrainDisable Disables the open-drain functionality for the selected port. SYS_PORTS_OpenDrainEnable Enables the open-drain functionality for the selected port. SYS_PORTS_PullUpDisable Disables the pull-up for the selected port. SYS_PORTS_PullUpEnable Enables the pull-up for the selected port. SYS_PORTS_Read Reads the data from the I/O port. SYS_PORTS_Set Writes the selected digital port/latch based on the mask. SYS_PORTS_Toggle Toggles the selected digital port pins. SYS_PORTS_Write Writes the data to the I/O port. Description 5.7.7.7.1 Pin Control Functions 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3475 5.7.7.7.1.1 SYS_PORTS_PinModeSelect Function C void SYS_PORTS_PinModeSelect( PORTS_MODULE_ID index, PORTS_ANALOG_PIN pin, PORTS_PIN_MODE mode ); Description This function enables the selected pin as analog or digital. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pin Possible values of PORTS_ANALOG_PIN mode Possible values of PORTS_PIN_MODE Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PIN - PORTS_ANALOG_PIN_AN0 // MY_PIN_MODE - PORTS_PIN_MODE_ANALOG SYS_PORTS_PinModSYS_PORTS_PinModeSelecteSelect( MY_PORTS_INSTANCE, MY_PIN, MY_PIN_MODE ); 5.7.7.7.1.2 SYS_PORTS_PinOpenDrainDisable Function C void SYS_PORTS_PinOpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function disables the open-drain functionality for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3476 Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinOpenDrainDisable(MY_PORTS_INSTANCE, MY_PINNUM); 5.7.7.7.1.3 SYS_PORTS_PinOpenDrainEnable Function C void SYS_PORTS_PinOpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function enables the open-drain functionality for the selected pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinOpenDrainEnable( MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM ); 5.7.7.7.1.4 SYS_PORTS_PinPullUpDisable Function C void SYS_PORTS_PinPullUpDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function disables the pull-up functionality for the selected pin. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3477 Preconditions None Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. On some devices, pull-up disable leads to pull-down enable. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinPullUpDisable( MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM ); 5.7.7.7.1.5 SYS_PORTS_PinPullUpEnable Function C void SYS_PORTS_PinPullUpEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This functin enables the pull-up functionality for the selected pin. Preconditions None Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinPullUpEnable( MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM ); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3478 5.7.7.7.1.6 SYS_PORTS_PinRead Function C bool SYS_PORTS_PinRead( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function reads the selected digital pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns The status of the port pin. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 bool bitStatus = SYS_PORTS_PinRead(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.7.7.7.1.7 SYS_PORTS_PinSet Function C void SYS_PORTS_PinSet( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function sets the selected digital pin/latch. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3479 Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinSet(MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM); 5.7.7.7.1.8 SYS_PORTS_PinToggle Function C void SYS_PORTS_PinToggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function toggles the selected digital pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PinToggle( MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM ); 5.7.7.7.1.9 SYS_PORTS_PinWrite Function C void SYS_PORTS_PinWrite( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos, bool value ); Description This function writes the selected digital pin. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3480 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS 5.7.7.7.1.10 SYS_PORTS_PinClear Function C void SYS_PORTS_PinClear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This function clears the selected digital pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_IO_PIN_10 SYS_PORTS_PinClear( MY_PORTS_INSTANCE, MY_CHANNEL, MY_PINNUM ); 5.7.7.7.1.11 SYS_PORTS_PinDirectionSelect Function C void SYS_PORTS_PinDirectionSelect( PORTS_MODULE_ID index, SYS_PORTS_PIN_DIRECTION pinDir, PORTS_CHANNEL channel, PORTS_BIT_POS bitPos ); Description This functino enables the direction for the selected pin. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3481 Preconditions None Parameters Parameters Description index Identifier for the device instance to be configured pinDir Pin direction channel Identifier for the PORT channel: A, B, C, etc. bitPos Possible values of PORTS_BIT_POS Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_PIN_10 SYS_PORTS_PIN_DIRECTION pinDir; pinDir = SYS_PORTS_DIRECTION_INPUT; SYS_PORTS_PinDirectionSelect(MY_PORTS_INSTANCE, pinDir, MY_CHANNEL, MY_PINNUM); 5.7.7.7.2 Ports Control Functions 5.7.7.7.2.1 SYS_PORTS_Clear Function C void SYS_PORTS_Clear( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK clearMask ); Description This function clears the selected digital port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. clearMask Identifies the bits to be cleared Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3482 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK clearMask = (PORTS_DATA_MASK)0x00FF; SYS_PORTS_Clear( MY_PORTS_INSTANCE, MY_CHANNEL, clearMask ); 5.7.7.7.2.2 SYS_PORTS_DirectionGet Function C PORTS_DATA_MASK SYS_PORTS_DirectionGet( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function reads the direction for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. Returns Direction of the port. Remarks None. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK value; value = SYS_PORTS_DirectionGet( MY_PORTS_INSTANCE, MY_CHANNEL ); 5.7.7.7.2.3 SYS_PORTS_DirectionSelect Function C void SYS_PORTS_DirectionSelect( PORTS_MODULE_ID index, SYS_PORTS_PIN_DIRECTION pinDir, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function enables the direction for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinDir Pin direction 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3483 channel Identifier for the PORT channel: A, B, C, etc. mask Mask for the direction of width PORTS_DATA_MASK Returns None Remarks None. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_PIN_DIRECTION pinDir; pinDir = SYS_PORTS_DIRECTION_INPUT; PORTS_DATA_MASK myMask = (PORTS_DATA_MASK)0x00FF; SYS_PORTS_DirectionSelect(MY_PORTS_INSTANCE, pinDir, MY_CHANNEL, myMask ); 5.7.7.7.2.4 SYS_PORTS_OpenDrainDisable Function C void SYS_PORTS_OpenDrainDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function disables the open-drain functionality for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. mask Mask of type PORTS_DATA_MASK Returns None Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_PeripheralOpenDrainDisable( MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF ); 5.7.7.7.2.5 SYS_PORTS_OpenDrainEnable Function C void SYS_PORTS_OpenDrainEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3484 Description This function enables the open-drain functionality for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. mask Mask of type PORTS_DATA_MASK Returns None Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_OpenDrainEnable( MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF ); 5.7.7.7.2.6 SYS_PORTS_PullUpDisable Function C void SYS_PORTS_PullUpDisable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function disables the pull-up for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. mask Mask of type PORTS_DATA_MASK Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. On some devices, pull-up disable leads to pull-down enable. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3485 SYS_PORTS_PullUpDisable( MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF ); 5.7.7.7.2.7 SYS_PORTS_PullUpEnable Function C void SYS_PORTS_PullUpEnable( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK mask ); Description This function enables the pull-up for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. mask Mask of type PORTS_DATA_MASK Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_PullUpEnable( MY_PORTS_INSTANCE, MY_CHANNEL, (PORTS_DATA_MASK)0x00FF ); 5.7.7.7.2.8 SYS_PORTS_Read Function C PORTS_DATA_TYPE SYS_PORTS_Read( PORTS_MODULE_ID index, PORTS_CHANNEL channel ); Description This function reads the data from the I/O port. Preconditions The direction of the port to be set as input. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. Returns Return the data read from the port. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3486 Remarks None. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_TYPE readData; readData = SYS_PORTS_Read( MY_PORTS_INSTANCE, MY_CHANNEL ); 5.7.7.7.2.9 SYS_PORTS_Set Function C void SYS_PORTS_Set( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value, PORTS_DATA_MASK mask ); Description This function writes to the selected digital port/latch relative to the mask. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. value Value to be written into a port of width PORTS_DATA_TYPE mask Identifies the bits to be written Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_VALUE - 0x1234 PORTS_DATA_MASK myMask = (PORTS_DATA_MASK)0x00FF; SYS_PORTS_Set(MY_PORTS_INSTANCE, MY_CHANNEL, MY_VALUE, myMask); 5.7.7.7.2.10 SYS_PORTS_Toggle Function C void SYS_PORTS_Toggle( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_MASK toggleMask ); Description This function toggles the selected digital port pins. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3487 Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. toggleMask Identifies the bits to be toggled Returns None Remarks None. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_MASK toggleMask = (PORTS_DATA_MASK)0x00FF; SYS_PORTS_Toggle( MY_PORTS_INSTANCE, MY_CHANNEL, toggleMask ); 5.7.7.7.2.11 SYS_PORTS_Write Function C void SYS_PORTS_Write( PORTS_MODULE_ID index, PORTS_CHANNEL channel, PORTS_DATA_TYPE value ); Description This function writes the data to the I/O port. Preconditions The direction of the port to be set as output. Parameters Parameters Description index Identifier for the device instance to be configured channel Identifier for the PORT channel: A, B, C, etc. value Value to be written into a port of width PORTS_DATA_TYPE Returns None. Remarks None. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_DATA_TYPE writeData; SYS_PORTS_Write( MY_PORTS_INSTANCE, MY_CHANNEL, MY_VALUE ); 5.7.7.7.3 Change Notification Functions 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3488 5.7.7.7.3.1 SYS_PORTS_ChangeNotificationDisable Function C void SYS_PORTS_ChangeNotificationDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function disables the change notification for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. PORTS_CHANGE_NOTICE_PIN pinNum; SYS_PORTS_ChangeNotificationDisable( index, pinNum ); 5.7.7.7.3.2 SYS_PORTS_ChangeNotificationEnable Function C void SYS_PORTS_ChangeNotificationEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum, SYS_PORTS_PULLUP_PULLDOWN_STATUS value ); Description This function enables the change notification for the selected port. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured value Pull-up enable or disable value pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3489 Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_PULLUP_PULLDOWN_STATUS value; PORTS_CHANGE_NOTICE_PIN pinNum; SYS_PORTS_ChangeNotificationEnable( index, pinNum, value ); 5.7.7.7.3.3 SYS_PORTS_ChangeNotificationGlobalDisable Function C void SYS_PORTS_ChangeNotificationGlobalDisable( PORTS_MODULE_ID index ); Description This function globally disables the change notification for the selected port. Preconditions None. Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_ChangeNotificationGlobalDisable( MY_PORTS_INSTANCE); 5.7.7.7.3.4 SYS_PORTS_ChangeNotificationGlobalEnable Function C void SYS_PORTS_ChangeNotificationGlobalEnable( PORTS_MODULE_ID index ); Description This function globally enables the change notification for the selected port. Preconditions None. Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_ChangeNotificationGlobalEnable( MY_PORTS_INSTANCE ); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3490 5.7.7.7.3.5 SYS_PORTS_ChangeNotificationInIdleModeDisable Function C void SYS_PORTS_ChangeNotificationInIdleModeDisable( PORTS_MODULE_ID index ); Description This function disables the change notification for the selected port in Sleep or Idle mode. Preconditions None. Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_ChangeNotificationInIdleModeDisable( MY_PORTS_INSTANCE ); 5.7.7.7.3.6 SYS_PORTS_ChangeNotificationInIdleModeEnable Function C void SYS_PORTS_ChangeNotificationInIdleModeEnable( PORTS_MODULE_ID index ); Description This function enables the change notification for the selected port in Sleep or Idle mode. Preconditions None. Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_ChangeNotificationInIdleModeEnable( MY_PORTS_INSTANCE ); 5.7.7.7.3.7 SYS_PORTS_ChangeNotificationPullDownDisable Function C void SYS_PORTS_ChangeNotificationPullDownDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3491 Description This function disables pull-down on input change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 SYS_PORTS_ChangeNotificationPullDownDisable( MY_PORTS_INSTANCE, MY_PINNUM ); 5.7.7.7.3.8 SYS_PORTS_ChangeNotificationPullDownEnable Function C void SYS_PORTS_ChangeNotificationPullDownEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function enables pull-down on input change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 SYS_PORTS_ChangeNotificationPullDownEnable( MY_PORTS_INSTANCE, MY_PINNUM ); 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3492 5.7.7.7.3.9 SYS_PORTS_ChangeNotificationPullUpDisable Function C void SYS_PORTS_ChangeNotificationPullUpDisable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function disables pull-up on input change. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 SYS_PORTS_ChangeNotificationPullUpDisable( MY_PORTS_INSTANCE, MY_PINNUM ); 5.7.7.7.3.10 SYS_PORTS_ChangeNotificationPullUpEnable Function C void SYS_PORTS_ChangeNotificationPullUpEnable( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function enables a weak pull-up on the change notification pin. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns None. Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3493 Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // MY_PINNUM - PORTS_CHANGE_NOTICE_PIN_10 SYS_PORTS_ChangeNotificationPullUpEnable( MY_PORTS_INSTANCE, MY_PINNUM ); 5.7.7.7.3.11 SYS_PORTS_ChangeNotificationStatus Function C bool SYS_PORTS_ChangeNotificationStatus( PORTS_MODULE_ID index, PORTS_CHANGE_NOTICE_PIN pinNum ); Description This function gets the status of the corresponding notification pin.. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured pinNum Possible values of PORTS_CHANGE_NOTICE_PIN Returns • true - Change notice has occurred • false - Change notice has not occurred Remarks Not all features are available on all devices. Refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. //pinNUM is the change notification pin bool status; status = SYS_PORTS_ChangeNotificationStatus( MY_PORTS_INSTANCE, MY_PINNUM ); 5.7.7.7.4 Peripheral Pin Select Functions 5.7.7.7.4.1 SYS_PORTS_IOLockDisable Function C void SYS_PORTS_IOLockDisable( PORTS_MODULE_ID index ); Description This function disables the I/O lock. Preconditions index - Identifier for the device instance to be configured Returns None. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3494 Remarks This feature is available for devices with PPS functionality. If the associated Configuration bit is set and if the I/O lock is enabled, this feature can never be used to disable the I/O lock. The only way to clear the bit and re-enable peripheral remapping is to perform a device Reset. This function is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_IOLockDisable(MY_PORTS_INSTANCE); 5.7.7.7.4.2 SYS_PORTS_IOLockEnable Function C void SYS_PORTS_IOLockEnable( PORTS_MODULE_ID index ); Description This function enables the I/O lock. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature is available for devices with Peripheral Pin Select (PPS) functionality. If the associated Configuration bit is set, this function can only be set once. This function is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. SYS_PORTS_IOLockEnable(MY_PORTS_INSTANCE); 5.7.7.7.4.3 SYS_PORTS_IOLockIsActive Function C bool SYS_PORTS_IOLockIsActive( PORTS_MODULE_ID index ); Description This function returns the status of I/O lock. Preconditions None. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3495 Parameters Parameters Description index Identifier for the device instance to be configured Returns • true - I/O lock is active • false - I/O lock is not active Remarks This feature is available for devices with PPS functionality. This function is not available on all devices. Please refer to the specific device data sheet for availability. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. bool lockStatus; lockStatus = SYS_PORTS_IOLockIsActive(MY_PORTS_INSTANCE); 5.7.7.7.4.4 SYS_PORTS_RemapInput Function C void SYS_PORTS_RemapInput( PORTS_MODULE_ID index, PORTS_REMAP_INPUT_FUNCTION function, PORTS_REMAP_INPUT_PIN remapPin ); Description This function controls the I/O function remapping. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use SYS_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // Remapping input function 'Input Capture 1' to the Remappable pin 'RPD2' SYS_PORTS_RemapInput(MY_PORTS_INSTANCE, INPUT_FUNC_IC1, INPUT_PIN_RPD2 ); 5.7.7.7.4.5 SYS_PORTS_RemapOutput Function C void SYS_PORTS_RemapOutput( PORTS_MODULE_ID index, 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3496 PORTS_REMAP_OUTPUT_FUNCTION function, PORTS_REMAP_OUTPUT_PIN remapPin ); Description This function controls the I/O function remapping. Preconditions None. Parameters Parameters Description index Identifier for the device instance to be configured Returns None. Remarks This feature may not be available on all devices. Please refer to the specific device data sheet to determine availability or use SYS_PORTS_ExistsRemapInputOutput in your application to determine whether this feature is available. Example // Where MY_PORTS_INSTANCE, is the ports instance selected for use by the // application developer. // Remapping output function 'UART3 Transmit' to the Remappable pin 'RPA14' SYS_PORTS_RemapInputOutput(MY_PORTS_INSTANCE, OTPUT_FUNC_U3TX, OUTPUT_PIN_RPA14); 5.7.7.7.5 Data Types and Constants 5.7.7.7.5.1 SYS_PORTS_PIN_DIRECTION Enumeration C typedef enum { SYS_PORTS_DIRECTION_OUTPUT, SYS_PORTS_DIRECTION_INPUT } SYS_PORTS_PIN_DIRECTION; Description SYS PORTS PIN DIRECTION These constants provide the port pin direction definitions. Members Members Description SYS_PORTS_DIRECTION_OUTPUT Direction as output SYS_PORTS_DIRECTION_INPUT Direction as input Remarks None. 5.7.7.7.5.2 SYS_PORTS_PULLUP_PULLDOWN_STATUS Enumeration C typedef enum { SYS_PORTS_PULLUP_DISABLE, 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3497 SYS_PORTS_PULLUP_ENABLE } SYS_PORTS_PULLUP_PULLDOWN_STATUS; Description SYS PORTS PULLUP status These constants provide the pull-up or pull-down status definitions. Members Members Description SYS_PORTS_PULLUP_DISABLE PULLUP Disable SYS_PORTS_PULLUP_ENABLE PULLUP Enable Remarks None. 5.7.7.8 Files Files Name Description help_sys_ports.h This is file help_sys_ports.h. sys_ports.h Ports System Service interface definitions Description 5.7.7.8.1 help_sys_ports.h This is file help_sys_ports.h. Enumerations Name Description PORTS_ANALOG_PIN Data type defining the different Analog input pins PORTS_CHANGE_NOTICE_PIN Data type defining the different Change Notification Pins enumeration PORTS_CHANNEL Identifies the PORT Channels Supported. PORTS_MODULE_ID Identifies the PORT Modules Supported. PORTS_PERIPHERAL_OD Data type defining the different Peripherals available for Open drain Configuration PORTS_PIN Data type defining the different PORTS IO Pins enumeration PORTS_REMAP_FUNCTION Data type defining the different remap function enumeration PORTS_REMAP_PIN Data type defining the different remappable input/output enumeration 5.7.7.8.2 sys_ports.h Ports System Service Interface Definition This file contains the interface definition for the Ports system service. It provides a way to interact with the Ports subsystem to manage the timing requests supported by the system 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3498 Enumerations Name Description SYS_PORTS_PIN_DIRECTION Defines the direction of the port pins. SYS_PORTS_PULLUP_PULLDOWN_STATUS Provides the pull-up and pull-down status. Functions Name Description SYS_PORTS_ChangeNotificationDisable Disables the change notification for the selected port. SYS_PORTS_ChangeNotificationEnable Enables the change notification for the selected port. SYS_PORTS_ChangeNotificationGlobalDisable Globally disables the change notification for the selected port. SYS_PORTS_ChangeNotificationGlobalEnable Globally enables the change notification for the selected port. SYS_PORTS_ChangeNotificationInIdleModeDisable Disables the change notification for the selected port in Sleep or Idle mode. SYS_PORTS_ChangeNotificationInIdleModeEnable Enables the change notification for the selected port in Sleep or Idle mode. SYS_PORTS_ChangeNotificationPullDownDisable Disables pull-down on input change. SYS_PORTS_ChangeNotificationPullDownEnable Enables pull-down on input change. SYS_PORTS_ChangeNotificationPullUpDisable Disables pull-up on input change. SYS_PORTS_ChangeNotificationPullUpEnable Enables a weak pull-up on the change notification pin. SYS_PORTS_ChangeNotificationStatus Gets the status of the corresponding notification pin. SYS_PORTS_Clear Clears the selected digital port. SYS_PORTS_DirectionGet Reads the direction for the selected port. SYS_PORTS_DirectionSelect Enables the direction for the selected port. SYS_PORTS_IOLockDisable Disables the I/O lock. SYS_PORTS_IOLockEnable Enables the I/O lock. SYS_PORTS_IOLockIsActive Returns the status of I/O lock. SYS_PORTS_OpenDrainDisable Disables the open-drain functionality for the selected port. SYS_PORTS_OpenDrainEnable Enables the open-drain functionality for the selected port. SYS_PORTS_PinClear Clears the selected digital pin. SYS_PORTS_PinDirectionSelect Enables the direction for the selected pin. SYS_PORTS_PinModeSelect Enables the selected pin as analog or digital. SYS_PORTS_PinOpenDrainDisable Disables the open-drain functionality for the selected pin. SYS_PORTS_PinOpenDrainEnable Enables the open-drain functionality for the selected pin. SYS_PORTS_PinPullUpDisable Disables the pull-up functionality for the selected pin SYS_PORTS_PinPullUpEnable Enables the pull-up functionality for the selected pin. SYS_PORTS_PinRead Reads the selected digital pin. SYS_PORTS_PinSet Sets the selected digital pin/latch. SYS_PORTS_PinToggle Toggles the selected digital pin. SYS_PORTS_PinWrite Writes the selected digital pin. SYS_PORTS_PullUpDisable Disables the pull-up for the selected port. SYS_PORTS_PullUpEnable Enables the pull-up for the selected port. SYS_PORTS_Read Reads the data from the I/O port. SYS_PORTS_RemapInput Input/Output (I/O) function remapping. SYS_PORTS_RemapOutput Input/Output (I/O) function remapping. SYS_PORTS_Set Writes the selected digital port/latch based on the mask. SYS_PORTS_Toggle Toggles the selected digital port pins. 5.7 System Service Library Help MPLAB Harmony Help Ports System Service Library 5-3499 SYS_PORTS_Write Writes the data to the I/O port. File Name sys_ports.h Company Microchip Technology Inc. 5.7.8 Timer System Service Library 5.7.8.1 Introduction Timer System Service Library for Microchip Microcontrollers This library provides interfaces to manage alarms and/or delays. Overview The Timer System Service Library is capable of providing periodic or one shot alarms, delays to the user. It works as a client for the Timer driver and opens one of the instances of the driver to perform the activities. The periodicity or the delay is an integer multiple of the Timer driver alarm period. 5.7.8.2 Release Notes MPLAB Harmony Version: v0.70b Timer System Service Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3500 5.7.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED AS IS MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.8.4 Using the Library This topic describes the basic architecture of the Timer System Service Library and provides information and examples on how to use it. Interface Header File: sys_tmr.h The interface to the Timer System Service library is defined in the "sys_tmr.h" header file, which is included by the "sys.h" system service header file. Any C language source (.c) file that uses the Timer System Service library should include "sys.h". Library File: The Timer System Service Library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the System Service interacts with the framework. Useful Terminologies: Term Description Tick Heart beats provided by the system timer. Defines the rate at which the callback gets called in a periodicity. One tick corresponds to one alarm period. Alarm Minimum resolution to which the Timer driver is configured, a tick or a callback is a multiple of this time. One Shot callback Callback gets called only once after the time is elapsed. Periodic callback Callback gets called at a periodic rate as defined by the user. Delay Non-blocking delays Pre-requisites: Following modules are necessary for the Timer System Service layer to function, • Timer Peripheral library • Timer Device driver • Interrupt Peripheral library [If Interrupt mode is opted] 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3501 • Interrupt System Service [If Interrupt mode is opted] 5.7.8.4.1 Abstraction Model The Timer System Service module uses the Timer driver abstraction layer to provide the following functionalities, • Periodic Callback • One Shot/Single Callback • Delays [interrupt mode alone] Note: Periodic/One shot modes of the Timer System Service will work in both polling and interrupt driven environments. Simple Timer System Service abstraction model. The following flow diagram depicts Periodic Callback usage model. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3502 The following flow diagram depicts One Shot Callback usage model. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3503 The following flow diagram depicts Delay usage model. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3504 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3505 5.7.8.4.2 Library Overview The library interface routines are divided into various subsections, each of the subsections addresses one of the blocks or the overall operation of the Timer System Service Library. Library Interface Section Description System Level Interaction Functions Provides system module APIs. Device initialization, deinitialization, reinitialization and status functions. Timed Callback Functions Provides interfaces to handle timed periodic or one shot callbacks Timed Delay Functions Provides interfaces to handle timed delays Miscellaneous Functions Provides interfaces for timer tick counts, etc. 5.7.8.4.3 How the Library Works The library provides interfaces to support: • System Interaction • Periodic Callback • One shot/Single Callback • Delays [In Interrupt mode Alone] • Tick count Information The following model gives information on interaction between various modules. Note: The arrows in the above diagram indicates the dependencies or support. Module interaction occurs in the following order: 1. The initialization, reinitialization, deinitialization are handled by the SYS INIT module. 2. The Timer System Service Initialization function initializes the library's internal data structures. 3. After the initialization, Timer System Service Tasks function would be called by the SYS Tasks module to open the Timer Driver and do other configuration activities. Once the Timer driver is ready to be used the Timer System Service Tasks API makes the system ready to be used by setting the status of the Timer System Service module to SYS_MODULE_RUNNING. 4. The application can now enable either periodic callback or one-shot callback or enable delays. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3506 Notes: 1. It is possible to have multiple clients access the system timer service. 2. Multiple client system calls for the configuration of multiple periodic callbacks or one shot and single periodic callback event etc. 3. It is not possible to use one client in polling and the other in the interrupt driven mode. 4. User or the application has to make sure to initialize the interrupt system module and set priorities accordingly. 5.7.8.4.3.1 System Interaction Initialization and Reinitialization: The SYS module performs the initialization and the reinitialization of the Timer System Service. During initialization the following informations are populated into the internal data structures from the init structure 'SYS_TMR_INIT' passed as a parameter: Initialization Member Description moduleInit System module initialization of the power state drvIndex Timer driver module/instance index, the same index used to initialize the timer driver alarmPeriod Alarm period in ms to configure the timer driver. This period will be used as the base time for further calculations of periodic or single callbacks etc. The SYS_TMR_Initialize API returns a dummy handle of the type SYS_MODULE_OBJ. There on, the object handle returned by the Initialize interface would be used by the other system interfaces like SYS_TMR_Reinitialize, SYS_TMR_Deinitialize, SYS_TMR_Status and SYS_TMR_Tasks. Note: Already initialized SYS TMR module if tried to initialize again, will safely return without modifying the behavior of the system. Example for Timer System Service initialization: SYS_MODULE_OBJ objectHandle; SYS_TMR_INIT initConfig; // Populate the SYS TMR initialization structure initConfig.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; initConfig.drvIndex = DRV_TMR_INDEX_0; initConfig.alarmPeriod = 100; objectHandle = SYS_TMR_Initialize( SYS_TMR_INDEX_0, ( SYS_MODULE_INIT * )&initConfig ); if( SYS_MODULE_OBJ_INVALID == objectHandle ) { // Handle error } Sample initialization sequence in polling environment: void SYS_Initialize( SYS_INIT_DATA *data ) { /* Application Initialization */ App_Init(); /* Initialize the Timer driver */ drvTmrObject = DRV_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&tmrInitData ); /* Initialize the SYS TMR Module */ sysTmrObject = SYS_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&sysTmrInitData ); } Sample initialization sequence in an interrupt driven environment:' 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3507 void SYS_Initialize( SYS_INIT_DATA *data ) { /* Application Initialization */ App_Init(); /* Initialize the Timer driver */ drvTmrObject = DRV_TMR_Initialize( DRV_TMR_INDEX_0, ( SYS_MODULE_INIT * )&tmrInitData ); /* Initialize the SYS TMR Module */ sysTmrObject = SYS_TMR_Initialize( DRV_TMR_INDEX_0, ( SYS_MODULE_INIT * )&sysTmrInitData ); /* Set the Timer Interrupt priority, sub-priority if supported by the device */ SYS_INT_PrioritySet( INT_SOURCE_TIMER_1, INT_PRIORITY_LEVEL1 ); SYS_INT_SubprioritySet( INT_SOURCE_TIMER_1, INT_SUBPRIORITY_LEVEL1 ); /* Initialize the interrupt sub system module */ SYS_INT_Initialize(); } Deinitialization: The deinitialize operation (SYS_TMR_Deinitialize) places the module in inactive state. Once the initialize operation has been called, the deinitialize operation must be called before the initialize is called again. If the operation requires time to allow the hardware to complete, this will be reported by the SYS_TMR_Status operation. Status: Status of the system timer module can be checked using SYS_TMR_Status interface. After the initialization, reinitialization or the deinitialization activities the System timer Service status can be retrieved and checked for further actions. Tasks Routine: The system will call SYS_TMR_Tasks from System Task Service no matter whether we are in a polled or an interrupt driven environment. This interface gets the system timer module into running mode. This interface needs to be called after the timer driver is successfully initialized. Sample call order in case of a polling environment: void SYS_Tasks( void ) { /* Call Driver TMR Tasks API */ DRV_TMR_Tasks( drvTmrObject ); /* Call SYS TMR Tasks API */ SYS_TMR_Tasks( sysTmrObject ); /* Call the Application Tasks */ App_Tasks(); } Sample call order in case of an interrupt driven environment: void SYS_Tasks( void ) { /* Call SYS TMR Tasks */ SYS_TMR_Tasks( sysTmrObject ); /* Call the Application Tasks */ App_Tasks(); } void InterruptServiceRoutine( void ) { /* Call the timer driver's "Tasks" routine */ DRV_TMR_Tasks( drvTmrObject ); } 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3508 5.7.8.4.3.2 Periodic Callback This section deals with the periodic callback registration and its usage. The following diagram depicts the interaction across various modules for the periodic callback feature, Steps involved in registering & using the feature: 1. Set the Timer System Service in the running mode (SYS_MODULE_RUNNING). See description to set to running mode. Use the SYS_TMR_STATUS function to verify that the service is in this mode. 2. Register the periodic callback feature using the SYS_TMR_CallbackPeriodic with the period and the pointer to the callback routine. The period parameter should be integral multiple of the Timer driver alarm period. The interface 'SYS_TMR_CallbackPeriodic' returns a valid handle after successful registration. Note: The handle can be later used by the user to stop the periodic callback temporarily by the user using the interface 'SYS_TMR_CallbackStop'. Based on the periodicity set by the user the respective callback would be triggered repetitively after it elapses. Example use case of this feature is described below, void SYS_Initialize ( SYS_INIT_DATA *data ) { /* Initialize the Timer driver */ drvTmrObject = DRV_TMR_Initialize ( SYS_INDEX, (SYS_MODULE_INIT *)&tmrInitData ); /* Initialize the SYS TMR Module */ sysTmrObject = SYS_TMR_Initialize ( SYS_INDEX, (SYS_MODULE_INIT *)&sysTmrInitData ); /* Application Initialization */ App_Initialize (); } void SYS_Tasks(void) 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3509 { /* Call Driver TMR Tasks API */ DRV_TMR_Tasks ( drvTmrObject ); /* Call SYS TMR Tasks API */ SYS_TMR_Tasks ( sysTmrObject ); /* Call the App Tasks */ App_Tasks (); } void App_Tasks ( void ) { switch (testState) { /* Wait in Init state till the SYS TMR Module is in running mode */ case TEST_STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { /* SYS TMR is in running mode */ testState = TEST_STATE_Config_Periodic; } else { testState = TEST_STATE_Init; } break; case TEST_STATE_Config_Periodic: /* Activate periodic callback */ handle = SYS_TMR_CallbackPeriodic (120, &Test_Callback); testState = TEST_STATE_Count_Read; break; case TEST_STATE_Count_Read: testCount1 = SYS_TMR_TickCountGet (); break; } } // Callback which will be called repetitively after the configured // time elapses void Test_Callback ( void ) { PORTA = ~PORTA; } Note: The configuration 'SYS_TMR_INTERRUPT_MODE' has no impact on this feature. Single Periodic Event Feature: The configuration macro/switch 'SYS_TMR_SINGLE_PERIODIC_EVENT', if set true will enables single periodic event feature. After the user creates one periodic callback event, no other periodic callback events are allowed. In the sense, multiple periodic events cannot be registered. Multiple Periodic Event Feature: The configuration macro/switch 'SYS_TMR_SINGLE_PERIODIC_EVENT', if set false will enable multiple periodic event feature. 5.7.8.4.3.3 One Shot Callback This section deals with the one-shot/single callback registration and its usage. The following diagram depicts the interaction across various modules for the one-shot callback feature, 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3510 Steps involved in registering and using the feature: 1. Initial requirement is to have the Timer System Service module in the mode 'SYS_MODULE_RUNNING'. The user can call the function SYS_TMR_Status to get the current status information of the module. 2. One-shot/Single callback feature can be registered by calling the function 'SYS_TMR_CallbackSingle' with the parameters periodicity of the callback & a pointer to the user's callback routine. The period parameter has to be integral multiple of the TMR driver alarm period. Based on the periodicity set by the user the respective callback would be triggered once after it elapses. Note: The handle can be later used by the user to stop the one shot callback temporarily by the user using the interface 'SYS_TMR_CallbackStop'. Example use case of this feature is described below, void SYS_Initialize ( SYS_INIT_DATA *data ) { /* Initialize the Timer driver */ drvTmrObject = DRV_TMR_Initialize ( SYS_INDEX, (SYS_MODULE_INIT *)&tmrInitData ); /* Initialize the SYS TMR Module */ sysTmrObject = SYS_TMR_Initialize ( SYS_INDEX, (SYS_MODULE_INIT *)&sysTmrInitData ); /* Application Initialization */ App_Initialize (); } void SYS_Tasks(void) { /* Call Driver TMR Tasks API */ DRV_TMR_Tasks ( drvTmrObject ); /* Call SYS TMR Tasks API */ SYS_TMR_Tasks ( sysTmrObject ); /* Call the App Tasks */ App_Tasks (); } 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3511 void App_Tasks ( void ) { switch (testState) { /* Wait in Init state till the SYS TMR Module is in running mode */ case TEST_STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { /* SYS TMR is in running mode */ testState = TEST_STATE_Config_Single; } else { testState = TEST_STATE_Init; } break; case TEST_STATE_Config_Single: /* Activate one shot/single callback */ handle = SYS_TMR_CallbackSingle (120, &Test_Callback); testState = TEST_STATE_Count_Read; break; case TEST_STATE_Count_Read: testCount1 = SYS_TMR_TickCountGet (); break; } } // Callback which will be called repetitively after the configured // time elapses void Test_Callback ( void ) { PORTA = ~PORTA; } Note: The configuration 'SYS_TMR_INTERRUPT_MODE' has no impact on this feature. 5.7.8.4.3.4 Delays This section deals with the delay registration and its usage. The mechanism depicted supports only non-blocking delays. The following diagram depicts the interaction across various modules for the delay feature, 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3512 Steps involved in registering and using the feature: 1. Initial requirement is to have the Timer System Service module in the mode 'SYS_MODULE_RUNNING'. The user can call the function SYS_TMR_Status to get the current status information of the module. 2. Delay feature can be registered by calling the function 'SYS_TMR_DelayMS' with the delay parameter. The delay parameter has to be integral multiple of the Timer driver alarm period. Note: The API 'SYS_TMR_DelayMS' returns a valid handle after successful registration. This handle can be later used by the user to check the status of the delay using the API 'SYS_TMR_DelayStatusGet'. The following code fragment gives a typical use case for this feature, case DELAY_START_STATE: handle = SYS_TMR_DelayMS (500); state = DELAY_CHECKSTATE; break; case DELAY_CHECKSTATE: if (SYS_TMR_DELAY_EXPIRED == SYS_TMR_DelayStatusGet(handle)) { state = DELAY_START_STATE; } else { state = DELAY_CHECKSTATE; } break; Note: For the usage of the Delay feature, the configuration switch 'SYS_TMR_INTERRUPT_MODE' needs to be set to 'true'. 5.7.8.4.3.5 Miscellaneous Tick Counts Information: The API 'SYS_TMR_TickCountGet' provides the current tick information. Alarm Period: The previously configured alarm period can be obtained using the interface 'SYS_TMR_AlarmPeriodGet'. Period chosen for the periodic/one shot callback should be a multiple of the driver's alarm period Say if the alarm period is 10ms, then the period should be a multiple of 10. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3513 5.7.8.4.3.6 Examples Sample application tasks: Periodic callback with only one period with 120 ms period: switch (state) { case STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { state = STATE_Config_Periodic; } else { state = STATE_Init; } break; case STATE_Config_Periodic: handle = SYS_TMR_CallbackPeriodic (120, &Test_Callback); state = STATE_Count_Read; break; case STATE_Count_Read: testCount = SYS_TMR_TickCountGet (); state = STATE_Count_Read; break; } Periodic callback with multiple periods 120 ms and 250 ms: switch (state) { case STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { state = STATE_Config_Periodic; } else { state = STATE_Init; } break; case STATE_Config_Periodic: handle1 = SYS_TMR_CallbackPeriodic (120, &Test_Callback1); handle2 = SYS_TMR_CallbackPeriodic (250, &Test_Callback2); state = STATE_Count_Read; break; case STATE_Count_Read: testCount = SYS_TMR_TickCountGet (); state = STATE_Count_Read; break; } void Test_Callback1 ( void ) { /* Assume RA0 is connected to one LED */ PORTAbits.RA0 = ~PORTAbits.RA0; } void Test_Callback2 ( void ) { /* Assume RA1 is connected to another LED */ 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3514 PORTAbits.RA1 = ~PORTAbits.RA1; } One-Shot Callback: switch (state) { case STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { state = STATE_Config_Single; } else { state = STATE_Init; } break; case STATE_Config_Single: SYS_TMR_CallbackSingle (500, &Test_Callback); state = STATE_Count_Read; break; case STATE_Count_Read: testCount = SYS_TMR_TickCountGet (); state = STATE_Count_Read; break; } Delay: switch (state) { case STATE_Init: if (SYS_MODULE_RUNNING == SYS_TMR_Status(sysTmrObject)) { state = STATE_DelayStart; } else { state = STATE_Init; } break; case STATE_DelayStart: dlHandle = SYS_TMR_DelayMS (500); state = STATE_DelayCheck; break; case STATE_DelayCheck: if (SYS_TMR_DELAY_EXPIRED == SYS_TMR_DelayStatusGet(dlHandle)) { state = STATE_DelayStart; } else { state = STATE_DelayCheck; } break; } 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3515 5.7.8.5 Configuring the Library Macros Name Description SYS_TMR_ERROR_TOLERANCE Sets the error tolerance in milliseconds. SYS_TMR_INTERRUPT_MODE Activates the Interrupt mode. SYS_TMR_SINGLE_PERIODIC_EVENT Sets the type of the periodic event. SYS_TMR_MAX_PERIODIC_EVENTS Sets the maximum periodic multi-event callbacks supported. Description The configuration of the Timer System Service is based on the file sys_config.h. This header file contains the configuration selection for the Timer System Service build. Based on the selections made, the Timer System Service will support or not support selected features.These configuration settings will apply to all instances of the Timer System Service. This header can be placed anywhere, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.7.8.5.1 SYS_TMR_ERROR_TOLERANCE Macro C #define SYS_TMR_ERROR_TOLERANCE 0 Description Error Tolerance configuration This macro sets the error tolerance in milliseconds with reference to the configured alarm period of the timer driver. Remarks None. 5.7.8.5.2 SYS_TMR_INTERRUPT_MODE Macro C #define SYS_TMR_INTERRUPT_MODE false Description Interrupt Mode configuration This macro sets up the interrupt mode, which can accept the following values: • true - Interrupt mode • false - No Interrupt mode Remarks The delay feature works only if the Interrupt mode is set to 'true' and the respective Timer has been configured for Interrupt mode. This feature has been designed to provide a non-blocking delay. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3516 5.7.8.5.3 SYS_TMR_SINGLE_PERIODIC_EVENT Macro C #define SYS_TMR_SINGLE_PERIODIC_EVENT true Description Periodic event type configuration This macro sets the type of the periodic event, which can accept the following values: • true - Single periodic event • false - Multiple periodic events Remarks If multiple periodic events are enabled, the switch SYS_TMR_MAX_PERIODIC_EVENTS has to be configured to support the maximum permitted events. 5.7.8.5.4 SYS_TMR_MAX_PERIODIC_EVENTS Macro C #define SYS_TMR_MAX_PERIODIC_EVENTS 5 Description Maximum periodic events configuration This macro sets the maximum periodic multi-event callbacks. Remarks This requires multiple periodic events enabled through the switch SYS_TMR_SINGLE_PERIODIC_EVENT. 5.7.8.6 Building the Library 5.7.8.7 Library Interface Data Types and Constants Name Description SYS_TMR_CALLBACK Defines a pointer to a callback function. SYS_TMR_DELAY_STATUS Defines the callback service type. SYS_TMR_HANDLE Identifies a particular registered event instance. SYS_TMR_INIT Identifies the system timer initialize structure. SYS_TMR_HANDLE_INVALID Identifies the invalid handle of the system timer. SYS_TMR_INDEX_0 Timer System Service index definitions. SYS_TMR_RUNNING Identifies the current status/state of the system timer. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3517 Miscellaneous Functions Name Description SYS_TMR_AlarmPeriodGet Returns the previously configured alarm period. SYS_TMR_TickCountGet Provides the current counter value. System Level Interaction Functions Name Description SYS_TMR_Deinitialize Deinitializes the specific module instance of the TMR module SYS_TMR_Initialize Initializes hardware and data for the instance of the Timer module and opens the specific module instance. SYS_TMR_Reinitialize Reinitializes and refreshes the hardware for the instance of the Timer module. SYS_TMR_Status Returns status of the specific instance of the Timer module. SYS_TMR_Tasks Maintains the system timer's state machine and implements its ISR. Timed Callback Functions Name Description SYS_TMR_CallbackPeriodic The Periodic callback is registered and started using this function. SYS_TMR_CallbackSingle The one-shot/single callback is registered and started using this function. SYS_TMR_CallbackStop Stops the periodic callback service. Timed Delay Functions Name Description SYS_TMR_DelayMS Registers an event for the specified delay. SYS_TMR_DelayStatusGet Intimates if the previously configured delay has elapsed. Description This section describes the APIs of the Timer System Service Library. Refer to each section for a detailed description. 5.7.8.7.1 System Level Interaction Functions 5.7.8.7.1.1 SYS_TMR_Deinitialize Function C void SYS_TMR_Deinitialize( SYS_MODULE_OBJ object ); Description This function deinitializes the specific module instance disabling its operation (and any hardware for driver modules). Resets all of the internal data structures and fields for the specified instance to the default settings. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description object SYS TMR object handle, returned from SYS_TMR_Initialize 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3518 Returns None. Example SYS_MODULE_OBJ object; // Returned from SYS_TMR_Initialize SYS_STATUS status; SYS_TMR_Deinitialize (object); status = SYS_TMR_Status (object); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the SYS TMR is deinitialized. } Remarks: Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. 5.7.8.7.1.2 SYS_TMR_Initialize Function C SYS_MODULE_OBJ SYS_TMR_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Description This function initializes hardware for the instance of the Timer module, using the specified hardware initialization data. It also initializes any internal data structures. Preconditions None. Parameters Parameters Description index Index for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the sys timer. This pointer may be null if no data is required because static overrides have been provided. Returns If successful, returns a valid handle to an object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to SYS_TMR_Reinitialize, SYS_TMR_Deinitialize, SYS_TMR_Tasks and SYS_TMR_Status routines. Example SYS_MODULE_OBJ objectHandle; SYS_TMR_INIT initConfig; // Populate the timer initialization structure initConfig.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; initConfig.drvIndex = DRV_TMR_INDEX_0; initConfig.alarmPeriod = 100; objectHandle = SYS_TMR_Initialize (SYS_TMR_INDEX_0, (SYS_MODULE_INIT*)&initConfig); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3519 Remarks: This routine should only be called once during system initialization unless SYS_TMR_Deinitialize is first called to deinitialize the device instance before reinitializing it. If the system was already initialized it safely returns without causing any disturbance. 5.7.8.7.1.3 SYS_TMR_Reinitialize Function C void SYS_TMR_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); Description This function reinitializes and refreshes the hardware for the instance of the Timer module using the supplied data. It modifies the internal data structure. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description object Identifies the SYS TMR Object returned by the Initialize interface init Pointer to the data structure containing any data necessary to initialize the hardware Returns None Example SYS_MODULE_OBJ objectHandle; SYS_TMR_INIT initConfig; SYS_STATUS tmrStatus; // Populate the timer initialization structure initConfig.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; initConfig.drvIndex = DRV_TMR_INDEX_0; initConfig.alarmPeriod = 100; SYS_TMR_Reinitialize (objectHandle, (SYS_MODULE_INIT*)&initConfig); tmrStatus = SYS_TMR_Status (object); if (SYS_STATUS_BUSY == tmrStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= tmrStatus) { // Handle error } Remarks: This operation uses the same initialization data structure as the SYS_TMR_Initialize operation. This operation can be used to change the power state of a TMR module. This function can be called multiple times to reinitialize the module. This operation uses the same initialization data structure as the Initialize operation. This operation can also be used to refresh the hardware registers as defined by the initialization data. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3520 5.7.8.7.1.4 SYS_TMR_Status Function C SYS_STATUS SYS_TMR_Status( SYS_MODULE_OBJ object ); Description This function returns the status of the specific module instance disabling its operation (and any hardware for driver modules). Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description object SYS TMR object handle, returned from SYS_TMR_Initialize Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been de-initialized This value is less than SYS_STATUS_ERROR. Example SYS_MODULE_OBJ object; // Returned from SYS_TMR_Initialize SYS_STATUS tmrStatus; tmrStatus = SYS_TMR_Status (object); else if (SYS_STATUS_ERROR >= tmrStatus) { // Handle error } Remarks: Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. 5.7.8.7.1.5 SYS_TMR_Tasks Function C void SYS_TMR_Tasks( SYS_MODULE_OBJ object ); Description This function is used to maintain the system timer's internal state machine and implement its ISR for interrupt-driven implementations. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3521 Preconditions The SYS_TMR_Initialize function must have been called for the specified TMR driver instance. Parameters Parameters Description object SYS TMR object handle, returned from SYS_TMR_Initialize Returns None Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the apropriate raw ISR. Example SYS_MODULE_OBJ object; // Returned from SYS_TMR_Initialize while (true) { SYS_TMR_Tasks (object); // Do other tasks } 5.7.8.7.2 Timed Callback Functions 5.7.8.7.2.1 SYS_TMR_CallbackPeriodic Function C SYS_TMR_HANDLE SYS_TMR_CallbackPeriodic( unsigned int period, SYS_TMR_CALLBACK callback ); Description This function registers the periodic callback service corresponding to the configuration paramenters passed by the user. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description period Periodic delay in milliseconds callback Pointer to a callback routine that will be called periodically Returns A valid event handler of type SYS_TMR_HANDLE is returned. Example SYS_TMR_HANDLE handle; unsigned int period = 20; void Test_Callback1 (void); handle = SYS_TMR_CallbackPeriodic (period, &Test_Callback1); 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3522 Remarks: The Period chosen should be a multiple of the driver's alarm period. For example, if the alarm period is 10 ms, the period should be a multiple of 10. 5.7.8.7.2.2 SYS_TMR_CallbackSingle Function C SYS_TMR_HANDLE SYS_TMR_CallbackSingle( unsigned int period, SYS_TMR_CALLBACK callback ); Description This function registers a one-shot/single callback service corresponding to the configuration paramenters passed by the user. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description period Periodic delay in milliseconds callback Pointer to a callback routine which will be called periodically Returns A valid event handler of type SYS_TMR_HANDLE is returned. Example SYS_TMR_HANDLE handle; unsigned int period = 20; void Test_Callback1 (void); handle = SYS_TMR_CallbackSingle (period, &Test_Callback1); Remarks: None. 5.7.8.7.2.3 SYS_TMR_CallbackStop Function C void SYS_TMR_CallbackStop( SYS_TMR_HANDLE handle ); Description This function stops the previously registered periodic callbacks service. Preconditions The SYS_TMR_CallbackPeriodic function should have been called before calling this function. Parameters Parameters Description handle A valid callback service handle, returned from the system API SYS_TMR_CallbackPeriodic Returns None. Example SYS_TMR_HANDLE handle; uint16_t period = 20; 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3523 void Test_Callback1 (void); handle = SYS_TMR_CallbackPeriodic (period, &Test_Callback1); ... ... SYS_TMR_CallbackStop (handle); Remarks: None. 5.7.8.7.3 Timed Delay Functions 5.7.8.7.3.1 SYS_TMR_DelayMS Function C SYS_TMR_HANDLE SYS_TMR_DelayMS( unsigned int delay ); Description This function registers an event for the specified delay. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Parameters Parameters Description delay Indicates the delay required in milliseconds Returns A valid event handler of type SYS_TMR_HANDLE is returned. Example SYS_TMR_DelayStart (50); Remarks: Works only in Interrupt mode. 5.7.8.7.3.2 SYS_TMR_DelayStatusGet Function C SYS_TMR_DELAY_STATUS SYS_TMR_DelayStatusGet( SYS_TMR_HANDLE handle ); Description This function intimates if the previously configured delay has elapsed. Preconditions The SYS_TMR_DelayStart function should have been called before calling this function. Parameters Parameters Description handle A valid callback service handle, returned from the system API SYS_TMR_DelayMS Returns One of the possible values of SYS_TMR_DELAY_STATUS. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3524 Example if (SYS_TMR_DELAY_EXPIRED == SYS_TMR_DelayStatusGet ()) // Do Something Remarks: None. 5.7.8.7.4 Miscellaneous Functions 5.7.8.7.4.1 SYS_TMR_AlarmPeriodGet Function C uint32_t SYS_TMR_AlarmPeriodGet(); Description This function obtains the previously configured alarm period. Preconditions The SYS_TMR_Initialize function should have been called before calling this function. Returns uint32_t - Alarm period in milliseconds Example uint32_t period; period = SYS_TMR_AlarmPeriodGet(); Remarks: None. 5.7.8.7.4.2 SYS_TMR_TickCountGet Function C uint32_t SYS_TMR_TickCountGet(); Description This function provides the current counter value. Preconditions The SYS_TMR_CallbackPeriodic function should have been called before calling this function. Returns uint32_t - Current system timer tick count value Example uint32_t count; count = SYS_TMR_TickCountGet (); Remarks: None. 5.7.8.7.5 Data Types and Constants 5.7.8.7.5.1 SYS_TMR_CALLBACK Type C typedef void (* SYS_TMR_CALLBACK)(void); Description SYS TMR Callback Function 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3525 This data type defines a pointer callback function. Remarks None. 5.7.8.7.5.2 SYS_TMR_DELAY_STATUS Enumeration C typedef enum { SYS_TMR_DELAY_IDLE, SYS_TMR_DELAY_EXPIRED, SYS_TMR_DELAY_NOT_EXPIRED, SYS_TMR_DELAY_ERROR } SYS_TMR_DELAY_STATUS; Description Callback service type enumeration This data type defines the callback service type. Members Members Description SYS_TMR_DELAY_IDLE Delay Idle SYS_TMR_DELAY_EXPIRED Delay Expired SYS_TMR_DELAY_NOT_EXPIRED Delay not yet expired SYS_TMR_DELAY_ERROR delay error Remarks None. 5.7.8.7.5.3 SYS_TMR_HANDLE Type C typedef int8_t SYS_TMR_HANDLE; Description SYS TMR Handle This event handle identifies a registered instance of an event. Every time the application that tries to access the paramateres with respect to a particular event, shall used this event handle to refer to that event. Remarks None. 5.7.8.7.5.4 SYS_TMR_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX drvIndex; uint32_t alarmPeriod; } SYS_TMR_INIT; Description SYS TMR Initialize structure 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3526 This structure identifies the system timer initialize structure. Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX drvIndex; Driver Module index uint32_t alarmPeriod; Alarm period in ms Remarks None. 5.7.8.7.5.5 SYS_TMR_HANDLE_INVALID Macro C #define SYS_TMR_HANDLE_INVALID ((int8_t)-1) Description SYS Timer invalid handle macro definition This enumeration identifies the invalid handle of the system timer. Remarks None. 5.7.8.7.5.6 SYS_TMR_INDEX_0 Macro C #define SYS_TMR_INDEX_0 0 Description SYS Timer Module Index Numbers These constants provide Timer System Service index definitions. Remarks These constants should be used in place of hard-coded numeric literals. 5.7.8.7.5.7 SYS_TMR_RUNNING Macro C #define SYS_TMR_RUNNING (SYS_STATUS_READY + 1) Description SYS Timer Module specific Status This enumeration identifies the current status/state of the system timer. Remarks This enumeration is the return type for the system-level status routine defined by each device driver or system module (for example: SYS_TMR_Status). 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3527 5.7.8.8 Files Files Name Description sys_tmr.h Timer System Service interface definition. sys_tmr_config.h Contains configuration definitions that are common to timer system services and aggregrates the configuration files for the system services. Description 5.7.8.8.1 sys_tmr.h Timer System Service Interface Definition This file contains the interface definition for the Timer System Service. It provides a way to interact with the Timer subsystem to manage the timing requests supported by the system. Enumerations Name Description SYS_TMR_DELAY_STATUS Defines the callback service type. Functions Name Description SYS_TMR_AlarmPeriodGet Returns the previously configured alarm period. SYS_TMR_CallbackPeriodic The Periodic callback is registered and started using this function. SYS_TMR_CallbackSingle The one-shot/single callback is registered and started using this function. SYS_TMR_CallbackStop Stops the periodic callback service. SYS_TMR_Deinitialize Deinitializes the specific module instance of the TMR module SYS_TMR_DelayMS Registers an event for the specified delay. SYS_TMR_DelayStatusGet Intimates if the previously configured delay has elapsed. SYS_TMR_Initialize Initializes hardware and data for the instance of the Timer module and opens the specific module instance. SYS_TMR_Reinitialize Reinitializes and refreshes the hardware for the instance of the Timer module. SYS_TMR_Status Returns status of the specific instance of the Timer module. SYS_TMR_Tasks Maintains the system timer's state machine and implements its ISR. SYS_TMR_TickCountGet Provides the current counter value. Macros Name Description SYS_TMR_HANDLE_INVALID Identifies the invalid handle of the system timer. SYS_TMR_INDEX_0 Timer System Service index definitions. SYS_TMR_RUNNING Identifies the current status/state of the system timer. Structures Name Description SYS_TMR_INIT Identifies the system timer initialize structure. 5.7 System Service Library Help MPLAB Harmony Help Timer System Service Library 5-3528 Types Name Description SYS_TMR_CALLBACK Defines a pointer to a callback function. SYS_TMR_HANDLE Identifies a particular registered event instance. File Name sys_tmr.h Company Microchip Technology Inc. 5.7.8.8.2 sys_tmr_config.h Timer System Service Configuration Definitions for the Template Version This file contains configuration definitions that are common to timer drivers and aggregrates the configuration files for the system services. Macros Name Description SYS_TMR_ERROR_TOLERANCE Sets the error tolerance in milliseconds. SYS_TMR_INTERRUPT_MODE Activates the Interrupt mode. SYS_TMR_MAX_PERIODIC_EVENTS Sets the maximum periodic multi-event callbacks supported. SYS_TMR_SINGLE_PERIODIC_EVENT Sets the type of the periodic event. File Name sys_tmr_config.h Company Microchip Technology Inc. 5.7.9 Watchdog Timer (WDT) System Service Library 5.7.9.1 Introduction Watchdog Timer (WDT) System Service Library for Microchip Microcontrollers The primary function of the Watchdog Timer (WDT) is to reset the microcontroller, in the event of a software malfunction, by resetting the device if it has not been cleared by software. To ensure that application doesn't hang, the application is required to reset the timer periodically. It can also be used to wake the device from Sleep or Idle mode. The WDT is a free-running timer which uses the low-power RC oscillator and requires no external components. Therefore, the WDT will continue to operate even if the system’s primary clock source is stopped. 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3529 This library provides a low-level abstraction of the Watchdog Timer System Service Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by abstracting differences from one microcontroller variant to another. 5.7.9.2 Release Notes MPLAB Harmony Version: v0.70b Watchdog Timer (WDT) System Service Library Version : 0.1 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.7.9.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.7.9.4 Using the Library This topic describes the basic architecture of the Watchdog Timer System Service Library and provides information and examples on how to use it. Interface Header File: sys_wdt.h The interface to the Watchdog Timer System Service library is defined in the "sys_wdt.h" header file. This file is included by the "sys.h" file. Any C language source (.c) file that uses the Watchdog Timer System Service library should include "sys.h". Library File: The Watchdog Timer System Service library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the System Service interacts with the framework. 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3530 5.7.9.4.1 Abstraction Model Watchdog Timer Software Abstraction Block Diagram Watchdog timer uses internal Low Power RC(LPRC) oscillator as the source of clock. The clock is divided by the configured prescalar value. There may be one more postscalar divisors and these should be set through the 'configuration bits'. The divided clock is then used to increment a counter. If the software does not clear the counter in time the counter overflows and that will result in reset in normal mode. In case of Sleep or Idle mode the overflow will result in device wakeup. In case of windowed mode, resetting the counter when the count is not in the window specified will also lead to a reset. 5.7.9.4.2 Library Overview Refer to the System Services Overview section for how the system services operates in a system. The library interface routines are divided into various sub-sections, each sub-section addresses one of the blocks of the overall operation of the Watchdog Timer module. Library Interface Section Description Enable and Disable Functions APIs to enable and disable the Watchdog Timer Clearing the Timer Functions API to clear the Watchdog Timer 5.7.9.4.3 How the Library Works Initialization of Watchdog Timer: In case of devices which has 'Window mode', use the argument to control the window mode. The argument will be discarded in case of devices which doesn't has 'Window mode'. SYS_WDT_Enable(true); //Some code SYS_WDT_Enable(false); //Some code SYS_WDT_Disable(); Note: For all the above code to work, the watchdog timer should not be controlled through configuration bits. Service the Watchdog Timer: To ensure the normal operation of the system, the software must clear the Watchdog timer periodically. SYS_WDT_TimerClear(); 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3531 Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. 5.7.9.5 Configuring the Library Macros Name Description WDT_PLIB_ID Configures the module's ID used by the peripheral library. Description The configuration of the Watchdog Timer System Service is based on the file sys_config.h This header file contains the configuration selection for the Watchdog Timer System Service. Based on the selections made, the Watchdog Timer System Service will support or not support selected features. These configuration settings will apply to all instances of the Watchdog Timer System Service. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.7.9.5.1 WDT_PLIB_ID Macro C #define WDT_PLIB_ID WDT_ID_1 Description Watchdog timer module ID used by the Peripheral Library This macro configures the module's ID used by the peripheral library. Remarks None. 5.7.9.6 Builiding the Library This section list the files that are available in the \src of the Watchdog Timer System Service driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.7.9.7 Library Interface Clearing the Timer Functions Name Description SYS_WDT_TimerClear Reset the WDT. Enable and Disable Functions Name Description SYS_WDT_Disable Disables the WDT if it is enabled in software. SYS_WDT_Enable Enables the WDT. The argument 'windowModeEnable' will be used only for those devices that support 'window mode'. Otherwise, it will be discarded. 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3532 Description This section describes the Application Programming Interface (API) functions of the Watchdog Timer System Service. Refer to each section for a detailed description. 5.7.9.7.1 Enable and Disable Functions 5.7.9.7.1.1 SYS_WDT_Disable Function C void SYS_WDT_Disable(); Description This function disables the WDT if it is enabled in software. If the WDT is enabled through 'configuration bits' it cannot be disabled using this function. Preconditions The WDT should be disabled through 'configuration bits'. Returns None. Remarks The example code doesn't include the settings that should be done through configuration bits. Example SYS_WDT_Disable(); 5.7.9.7.1.2 SYS_WDT_Enable Function C void SYS_WDT_Enable( bool windowModeEnable ); Description This function enables the WDT. The argument 'windowModeEnable' will be used only for those devices that support 'window mode'. Otherwise, the argument will be discarded. This function could be called multiple times to enable/disable the 'window mode'. Preconditions None. Parameters Parameters Description 5.7.9.7.2 Clearing the Timer Functions 5.7.9.7.2.1 SYS_WDT_TimerClear Function C void SYS_WDT_TimerClear(); 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3533 Description This function clears the WDT counter. The WDT should be cleared periodically before the count overflows and forces the device to Reset. Preconditions None. Returns None. Remarks Clearing the WDT before the count reaches the window, will cause a reset in Windowed mode. The example code doesn't include the settings that should be done through Configuration bits. This feature is not available on all devices. Please refer to the specific device data sheet to determine whether this feature is supported. Example //Application loop while(1) { SYS_WDT_TimerClear(); //user code } 5.7.9.8 Files Files Name Description sys_wdt.h Watchdog Timer (WDT) System Service inteface definition. sys_wdt_config.h Watchdog Timer (WDT) System Service interface definition. Description 5.7.9.8.1 sys_wdt.h Watchdog Timer System Service Interface Definition This file contains the interface definition for the WDT System Service. It provides a way to interact with the WDT subsystem to manage the timing requests supported by the system. Functions Name Description SYS_WDT_Disable Disables the WDT if it is enabled in software. SYS_WDT_Enable Enables the WDT. The argument 'windowModeEnable' will be used only for those devices that support 'window mode'. Otherwise, it will be discarded. SYS_WDT_TimerClear Reset the WDT. File Name sys_wdt.h 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3534 Company Microchip Technology Inc. 5.7.9.8.2 sys_wdt_config.h Watchdog Timer System Service Interface Definition This file contains the interface definition for the WDT System Service. It provides a way to interact with the Watchdog timer subsystem to manage the timing requests supported by the system Macros Name Description WDT_PLIB_ID Configures the module's ID used by the peripheral library. File Name sys_wdt.h Company Microchip Technology Inc. 5.7 System Service Library Help MPLAB Harmony Help Watchdog Timer (WDT) System Service 5-3535 5.8 TCP/IP Stack Library Help 5.8.1 TCP/IP Library Overview 5.8.1.1 Introduction This topic provides an overview of the TCP/IP Stack in MPLAB Harmony. Description The MPLAB Harmony TCP/IP Stack provides a foundation for embedded network applications by handling most of the interaction required between the physical network port and your application. It includes modules for several commonly used application layers, including HTTP for serving web pages, SMTP for sending e-mails, SNMP for providing status and control, Telnet, TFTP, Serial-to-Ethernet and much more. In addition, the stack includes light-weight and high-performance implementations of the TCP and UDP transport layers, as well as other supporting modules such as IP, ICMP, DHCP, ARP, and DNS. This help file serves two purposes. The first is to be a guide for first-time users of the TCP/IP Stack. The Getting Started section begins a series of pages to help you become familiar with the stack and configure it for use on a Microchip development board. The second purpose is to serve as a programmer's reference guide to the features and APIs available in the TCP/IP Stack. 5.8.1.2 Release Notes MPLAB Harmony Version: v0.70b TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 This is the first release of the library. The interface can change in the beta and\or 1.0 release. Description Resource Usage and Network Metrics for the PIC32MX Memory and Flash usage Module RAM No Optimization Flash No Optimization RAM Optimize for Size Flash Optimize for Size RAM Optimized for Speed Flash Optimized for Speed Core (arp, tcp manager, tcp helpers, hash functions, etc.) 356 51,380 352 24,772 352 34,812 Berkeley API 116 7,464 116 4,116 116 7,080 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3536 Commands for TCP Configuration 120 18,348 120 13,104 124 14,556 DHCP Client 40 11,328 40 6,036 44 7,676 DHCP Server 76 15,188 76 7,464 76 10,456 DNS Client 66 6,868 62 3,496 68 4,368 DNS Server 86 2,276 86 1,052 88 1,192 FTP Server 40 11,368 40 5,384 40 6,548 HTTP Server 24 19,964 24 10,404 24 13,128 ICMPv4 Server 20 2,472 20 1,112 20 1,264 ICMPv6 Server 20 11,852 20 6,332 20 7,336 IPerf 252 22,344 252 12,136 252 14,240 IPv4 40 4,572 40 2,348 40 2,640 IPv6 224 45,488 224 25,060 224 40,480 Microchip Embedded Ethernet Device Discoverer 36 3,280 36 1,764 36 2,164 NetBIOS Name Resolution 12 2,884 12 1,372 12 2,024 Reboot Server 12 1,048 12 576 12 764 SMTP Client 98 8,252 102 4,324 104 6,052 SNMP Server 72 30,616 68 16,244 72 28,900 SNMPv3 Server 864 32,600 864 15,580 864 27,052 SNTP Client 72 2,796 72 1,572 72 1,780 SSL 72 33,416 72 18,096 72 49,252 TCP Protocol 28 42,268 28 21,604 32 28,556 Telnet Server 28 3,708 28 1,908 28 2,236 UDP Protocol 36 17,052 36 9,308 40 11,884 Zero Config for Local Link 25 22,296 25 10,892 25 13,116 Network Performance measured with iPerf The following commands were used to generate the performance numbers: • UDP/IP Client: • PIC32 Board: iperf -c -u -b 100M -i 5 -t 20 • PC: iperf -s -u -i 5 • UDP/IP Server: • PIC32 Board: iperf -s -u -i 5 • PC: iperf -c mchpboard_e -u -b 100M -i 5 -t 20 • TCP/IP Client • PIC32 Board: iperf -c -t 10 -i 5 -l 1024 -x 100M -M 1460 • PC: iperf -s -i 5 -m -w 10K –N • TCP/IP Server • PIC32 Board: iperf -s -i 5 -x 100M 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3537 • PC: iperf -c mchpboard_e -t 10 -i 5 -l 1024 UDP/IP Client UDP/IP Server TCP/IP Client TCP/IP Server 89.3 MBits/sec 95.7 MBits/sec 50.1 MBits/sec 60.3 MBits/sec Resource Usage and Network Metrics for the PIC32MZ Memory and Flash usage Module RAM No Optimization Flash No Optimization RAM Optimized for Size Flash Optimized for Size RAM Optimized for Speed Flash Optimized for Speed Core (arp, tcp manager, tcp helpers, hash functions, etc.) 356 51,112 352 24,868 352 34,632 Berkeley API 116 7,348 116 4,116 116 7,056 Commands for TCP Configuration 120 18,232 120 13,084 124 14,472 DHCP Client 40 11,276 40 6,040 44 7,660 DHCP Server 76 15,072 76 7,464 76 10,396 DNS Client 66 6,752 62 3,488 68 4,324 DNS Server 86 2,160 86 1,052 88 1,172 FTP Server 40 11,252 40 5,372 40 6,516 HTTP Server 24 19,848 24 10,284 24 12,988 ICMPv4 Server 20 2,356 20 1,112 20 1,240 ICMPv6 Server 20 12,336 20 6,668 20 7,572 IPerf 252 23,132 252 12,508 252 14,396 IPv4 40 4,576 40 2,368 40 2,628 IPv6 224 45,896 224 24,988 224 40,296 Microchip Embedded Ethernet Device Discoverer 36 3,164 36 1,748 36 1,980 NetBIOS Name Resolution 12 2,768 12 1,372 12 2,000 Reboot Server 12 932 12 572 12 744 SMTP Client 98 8,136 102 4,304 104 6,008 SNMP Server 72 30,500 68 16,188 72 28,500 SNMPv3 Server 864 32,368 864 15,396 864 26,804 SNTP Client 72 2,780 72 1,592 72 1,772 SSL 72 33,068 72 18,068 72 49,156 TCP Protocol 28 42,496 28 21,604 32 28,620 Telnet Server 28 3,592 28 1,896 28 2,156 UDP Protocol 36 17,320 36 9,360 40 11,812 Zero Config for Local Link 25 22,488 25 11,000 25 13,156 Network Performance measured with iPerf 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3538 The following commands were used to generate the performance numbers: • UDP/IP Client: • PIC32 Board: iperf -c -u -b 100M -i 5 -t 20 • PC: iperf -s -u -i 5 • UDP/IP Server: • PIC32 Board: iperf -s -u -i 5 • PC: iperf -c mchpboard_e -u -b 100M -i 5 -t 20 • TCP/IP Client • PIC32 Board: iperf -c -t 10 -i 5 -l 1024 -x 100M -M 1460 • PC: iperf -s -i 5 -m -w 10K –N • TCP/IP Server • PIC32 Board: iperf -s -i 5 -x 100M • PC: iperf -c mchpboard_e -t 10 -i 5 -l 1024 UDP/IP Client UDP/IP Server TCP/IP Client TCP/IP Server 71.6 MBits/sec 95.7 MBits/sec 46.6 MBits/sec 44.5 MBits/sec 5.8.1.3 SW License Agreement MICROCHIP IS WILLING TO LICENSE THE ACCOMPANYING SOFTWARE AND DOCUMENTATION TO YOU ONLY ON THE CONDITION THAT YOU ACCEPT ALL OF THE FOLLOWING TERMS. TO ACCEPT THE TERMS OF THIS LICENSE, CLICK "I ACCEPT" AND PROCEED WITH THE DOWNLOAD OR INSTALL. IF YOU DO NOT ACCEPT THESE LICENSE TERMS, CLICK "I DO NOT ACCEPT," AND DO NOT DOWNLOAD OR INSTALL THIS SOFTWARE. NON-EXCLUSIVE SOFTWARE LICENSE AGREEMENT This Nonexclusive Software License Agreement ("Agreement") is a contract between you, your heirs, successors and assigns ("Licensee") and Microchip Technology Incorporated, a Delaware corporation, with a principal place of business at 2355 W. Chandler Blvd., Chandler, AZ 85224-6199, and its subsidiary, Microchip Technology (Barbados) II Incorporated (collectively, "Microchip") for the accompanying Microchip software including, but not limited to, Graphics Library Software, IrDA Stack Software, MCHPFSUSB Stack Software, Memory Disk Drive File System Software, mTouch(TM) Capacitive Library Software, Smart Card Library Software, TCP/IP Stack Software, MiWi(TM) DE Software, Security Package Software, and/or any PC programs and any updates thereto (collectively, the "Software"), and accompanying documentation, including images and any other graphic resources provided by Microchip ("Documentation"). 1. Definitions. As used in this Agreement, the following capitalized terms will have the meanings defined below: a. "Microchip Products" means Microchip microcontrollers and Microchip digital signal controllers. b. "Licensee Products" means Licensee products that use or incorporate Microchip Products. c. "Object Code" means the Software computer programming code that is in binary form (including related documentation, if any), and error corrections, improvements, modifications, and updates. d. "Source Code" means the Software computer programming code that may be printed out or displayed in human readable form (including related programmer comments and documentation, if any), and error corrections, improvements, modifications, and updates. e. "Third Party" means Licensee’s agents, representatives, consultants, clients, customers, or contract manufacturers. f. "Third Party Products" means Third Party products that use or incorporate Microchip Products. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3539 2. Software License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to: a. use the Software in connection with Licensee Products and/or Third Party Products; b. if Source Code is provided, modify the Software; provided that Licensee clearly notifies Third Parties regarding the source of such modifications; c. distribute the Software to Third Parties for use in Third Party Products, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept ( see page 174)") and this Agreement accompanies such distribution; d. sublicense to a Third Party to use the Software, so long as such Third Party agrees to be bound by this Agreement (in writing or by "click to accept ( see page 174)"); e. with respect to the TCP/IP Stack Software, Licensee may port the ENC28J60.c, ENC28J60.h, ENCX24J600.c, and ENCX24J600.h driver source files to a non-Microchip Product used in conjunction with a Microchip ethernet controller; f. with respect to the MiWi (TM) DE Software, Licensee may only exercise its rights when the Software is embedded on a Microchip Product and used with a Microchip radio frequency transceiver or UBEC UZ2400 radio frequency transceiver which are integrated into Licensee Products or Third Party Products. For purposes of clarity, Licensee may NOT embed the Software on a non-Microchip Product, except as described in this Section. 3. Documentation License Grant. Microchip grants strictly to Licensee a non-exclusive, non-transferable, worldwide license to use the Documentation in support of Licensee's authorized use of the Software 4. Third Party Requirements. Licensee acknowledges that it is Licensee’s responsibility to comply with any third party license terms or requirements applicable to the use of such third party software, specifications, systems, or tools. This includes, by way of example but not as a limitation, any standards setting organizations requirements and, particularly with respect to the Security Package Software, local encryption laws and requirements. Microchip is not responsible and will not be held responsible in any manner for Licensee’s failure to comply with such applicable terms or requirements. 5. Open Source Components. Notwithstanding the license grant in Section 1 above, Licensee further acknowledges that certain components of the Software may be covered by so-called "open source" software licenses ("Open Source Components"). Open Source Components means any software licenses approved as open source licenses by the Open Source Initiative or any substantially similar licenses, including without limitation any license that, as a condition of distribution of the software licensed under such license, requires that the distributor make the software available in source code format. To the extent required by the licenses covering Open Source Components, the terms of such license will apply in lieu of the terms of this Agreement. To the extent the terms of the licenses applicable to Open Source Components prohibit any of the restrictions in this Agreement with respect to such Open Source Components, such restrictions will not apply to such Open Source Component. 6. Licensee Obligations. Licensee will not: (a) engage in unauthorized use, modification, disclosure or distribution of Software or Documentation, or its derivatives; (b) use all or any portion of the Software, Documentation, or its derivatives except in conjunction with Microchip Products, Licensee Products or Third Party Products; or (c) reverse engineer (by disassembly, decompilation or otherwise) Software or any portion thereof. Licensee may not remove or alter any Microchip copyright or other proprietary rights notice posted in any portion of the Software or Documentation. Licensee will defend, indemnify and hold Microchip and its subsidiaries harmless from and against any and all claims, costs, damages, expenses (including reasonable attorney's fees), liabilities, and losses, including without limitation: (x) any claims directly or indirectly arising from or related to the use, modification, disclosure or distribution of the Software, Documentation, or any intellectual property rights related thereto; (y) the use, sale and distribution of Licensee Products or Third Party Products; and (z) breach of this Agreement. 7. Confidentiality. Licensee agrees that the Software (including but not limited to the Source Code, Object Code and library files) and its derivatives, Documentation and underlying inventions, algorithms, know-how and ideas relating to the Software and the Documentation are proprietary information belonging to Microchip and its licensors ("Proprietary Information"). Except as expressly and unambiguously allowed herein, Licensee will hold in confidence and not use or disclose any Proprietary Information and will similarly bind its employees and Third Party(ies) in writing. Proprietary Information will not include information that: (i) is in or enters the public domain without breach of this Agreement and through no fault of the receiving party; (ii) the receiving party was legally in possession of prior to receiving it; (iii) the receiving party can demonstrate was developed by 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3540 the receiving party independently and without use of or reference to the disclosing party's Proprietary Information; or (iv) the receiving party receives from a third party without restriction on disclosure. If Licensee is required to disclose Proprietary Information by law, court order, or government agency, License will give Microchip prompt notice of such requirement in order to allow Microchip to object or limit such disclosure. Licensee agrees that the provisions of this Agreement regarding unauthorized use and nondisclosure of the Software, Documentation and related Proprietary Rights are necessary to protect the legitimate business interests of Microchip and its licensors and that monetary damage alone cannot adequately compensate Microchip or its licensors if such provisions are violated. Licensee, therefore, agrees that if Microchip alleges that Licensee or Third Party has breached or violated such provision then Microchip will have the right to injunctive relief, without the requirement for the posting of a bond, in addition to all other remedies at law or in equity. 8. Ownership of Proprietary Rights. Microchip and its licensors retain all right, title and interest in and to the Software and Documentation including, but not limited to all patent, copyright, trade secret and other intellectual property rights in the Software, Documentation, and underlying technology and all copies and derivative works thereof (by whomever produced). Licensee and Third Party use of such modifications and derivatives is limited to the license rights described in this Agreement. 9. Termination of Agreement. Without prejudice to any other rights, this Agreement terminates immediately, without notice by Microchip, upon a failure by Licensee or Third Party to comply with any provision of this Agreement. Upon termination, Licensee and Third Party will immediately stop using the Software, Documentation, and derivatives thereof, and immediately destroy all such copies. 10. Warranty Disclaimers. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. MICROCHIP AND ITS LICENSORS ASSUME NO RESPONSIBILITY FOR THE ACCURACY, RELIABILITY OR APPLICATION OF THE SOFTWARE OR DOCUMENTATION. MICROCHIP AND ITS LICENSORS DO NOT WARRANT THAT THE SOFTWARE WILL MEET REQUIREMENTS OF LICENSEE OR THIRD PARTY, BE UNINTERRUPTED OR ERROR-FREE. MICROCHIP AND ITS LICENSORS HAVE NO OBLIGATION TO CORRECT ANY DEFECTS IN THE SOFTWARE. 11. Limited Liability. IN NO EVENT WILL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER ANY LEGAL OR EQUITABLE THEORY FOR ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. The aggregate and cumulative liability of Microchip and its licensors for damages hereunder will in no event exceed $1000 or the amount Licensee paid Microchip for the Software and Documentation, whichever is greater. Licensee acknowledges that the foregoing limitations are reasonable and an essential part of this Agreement. 12. General. THIS AGREEMENT WILL BE GOVERNED BY AND CONSTRUED UNDER THE LAWS OF THE STATE OF ARIZONA AND THE UNITED STATES WITHOUT REGARD TO CONFLICTS OF LAWS PROVISIONS. Licensee agrees that any disputes arising out of or related to this Agreement, Software or Documentation will be brought exclusively in either the U.S. District Court for the District of Arizona, Phoenix Division, or the Superior Court of Arizona located in Maricopa County, Arizona. This Agreement will constitute the entire agreement between the parties with respect to the subject matter hereof. It will not be modified except by a written agreement signed by an authorized representative of Microchip. If any provision of this Agreement will be held by a court of competent jurisdiction to be illegal, invalid or unenforceable, that provision will be limited or eliminated to the minimum extent necessary so that this Agreement will otherwise remain in full force and effect and enforceable. No waiver of any breach of any provision of this Agreement will constitute a waiver of any prior, concurrent or subsequent breach of the same or any other provisions hereof, and no waiver will be effective unless made in writing and signed by an authorized representative of the waiving party. Licensee agrees to comply with all import and export laws and restrictions and regulations of the Department of Commerce or other United States or foreign agency or authority. The indemnities, obligations of confidentiality, and limitations on liability described herein, and any right of action for breach of this Agreement prior to termination, will survive any termination of this Agreement. Any prohibited assignment will be null and void. Use, duplication or disclosure by the United States Government is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer-Restricted Rights clause of FAR 52.227-19 when applicable, or in subparagraph (c)(1)(ii) of the Rights in 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3541 Technical Data and Computer Software clause at DFARS 252.227-7013, and in similar clauses in the NASA FAR Supplement. Contractor/manufacturer is Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199. If Licensee has any questions about this Agreement, please write to Microchip Technology Inc., 2355 W. Chandler Blvd., Chandler, AZ 85224-6199 USA. ATTN: Marketing. Copyright (c) 2012 Microchip Technology Inc. All rights reserved. License Rev. No. 05-012412 5.8.1.4 Getting Help This topic provides information for requesting support assistance with the TCP/IP Stack. Description The TCP/IP Stack is supported through Microchip's standard support channels. If you encounter difficulties, you may submit ticket requests at http://support.microchip.com. The Microchip forums are also an excellent source of information, with a very lively community dedicated specifically to Ethernet and TCP/IP discussions at http://forum.microchip.com. Microchip also offers embedded network classes through Regional Training Centers. For more information, visit http://www.microchip.com/rtc. 5.8.1.5 Utilities This section discusses the computer software applications included with the TCP/IP Stack. These tools are implemented using the C# or Java programming languages, or both. The C# tools (*.exe) will require the Microsoft® .NET Framework v2.0 to be installed on the local PC. The Java tools (*.jar) require Java Runtime Environment (JRE) 1.6 or later to be installed on the target computer. 5.8.1.5.1 MPFS2 Utility This topic provides a description of the MPFS2 Utility. Description The MPFS2 Utility packages web pages into a format for efficient storage in an embedded system. It is a graphical application for PCs that can generate MPFS2 images for storage in external storage or internal Flash program memory. When used to build MPFS2 images, the MPFS2 Utility also indexes the dynamic variables found. It uses this information to generate HTTPPrint.h, which ensures that the proper callback functions are invoked as necessary. It also stores this index information along with the file in the MPFS2 image, which alleviates the task of searching from the embedded device. Finally, when developing an application that uses external storage, the MPFS2 Utility can upload images to the external storage device using the upload functionality built into the HTTP2 web server or FTP server. The source code for this application is included in the Microchip Applications Libraries installer. 5.8.1.5.1.1 Building MPFS2 Images This topic provides information for building MPFS2 images. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3542 Description The MPFS2 Utility has four steps, which are denoted on the left hand side of the dialog. To build an MPFS image, select Start With: Webpage Directory in step 1 and choose the directory in which the web pages are stored. Step 2 selects the output format. If storing the web pages in external EEPROM or serial Flash, choose the BIN Image output format. If internal program memory will be used, select C18/C32 Image for use with 8-bit and 32-bit parts, or ASM30 Array for 16-bit targets. To store the web pages on a device formatted with the FAT file system without compressing them into an MPFS image, select MDD. Step 3 asks for the MPLAB IDE project directory. The MPFS tool will write the image file to the project directory, and will also update the HTTPPrint.h file there if needed. Select the correct directory so that the right files are modified. Step 4 controls the upload settings. When external EEPROM or serial flash is used for storage, the option to upload the newly created image to the board is available. Check the box next to Upload Image To to enable this feature. The target host name (or IP address), upload protocol, and upload path may need to be changed to the one chosen when the board was first configured. You may also need to modify the user name and password used to access the secured functionality in your application, like web page upload. Use the Settings button to edit these values. If internal program memory is being used, the image will be compiled in with the project and so direct uploads are not available. Make sure to include the output source file indicated in step 3 as part of the project. Once all the correct settings have been chosen, click the Generate button to create the image. If uploads are enabled, this will also attempt to upload the file to the device. 5.8.1.5.1.2 Uploading Pre-built MPFS2 Images This topic provides information on uploading pre-built MPFS2 images. Description There are two ways to upload a pre-built image to external storage. The first is described in the Getting Started ( see page 79) section, and involves uploading from the browser directly. The second is to use the MPFS2 Utility to upload the image. You can select HTTP or FTP uploading to match the protocol that your application uses. To use the MPFS2 Utility to upload an image, begin by selecting Start With: Pre-Build MPFS Image in step 1 at the top. Choose the image file to upload. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3543 Steps 2 and 3 are not required for pre-built images. Proceed directly to step 4 and verify that the upload settings are correct. The target host name (or IP address), upload protocol, and upload path may need to be changed to the one chosen when the board was first configured. You may also need to modify the user name and password used to access the secured functionality in your application, like web page upload. Use the Settings button to edit these values. Once all the settings are correct, click the Upload button. The image will be uploaded to the board. 5.8.1.5.1.3 Advanced MPFS2 Settings This topic provides information on advanced MPFS2 settings. Description The Advanced Settings dialog found in step 2 provides greater control over how files are processed. The Dynamic Files list indicates which file types to parse for dynamic variables. By default, all files with the extensions htm, html, cgi, or xml are parsed. If an application has dynamic variables in other file types, these types must be added to the list. This field must be a comma-separated list of extensions and file names. The Do Not Compress field indicates which file types should never be compressed. Compressing files with GZIP saves both storage space and transmission time. However, this is only suitable for static content such as CSS or JavaScript. Any files with dynamic variables will automatically be excluded. In addition, any file that the PIC may need to process internally should be excluded. Files included via ~inc:filename~ should not be compressed, nor should any BIB file used for the SNMP module (if present). Additional file types can be added to this list if a custom application will be accessing the MPFS. The GZIP compressor will attempt to shrink all files. In some cases, especially with images, little or no compression is achieved. When this occurs the file is stored as-is in the MPFS image. 5.8.1.5.1.4 MPFS2 Command Line Options This topic provides a description of the MPFS2 command line options. Description To facilitate batch files and automation, the MPFS2 Utility also supports execution from the command line. The syntax is as follows: MPFS2.jar [options] 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Library Overview 5-3544 The SourceDir, ProjectDir, and OutputFile options are required and should be enclosed in quotation marks. The OutputFile option will be relative to ProjectDir, and cannot be a full path name. The various option switches are described in the following table. Switch Short Description /BIN /b Output a BIN image (Default) /C18_C32 /c Output a C18 or XC32 image /ASM16 /s Output an ASM16 image /mpfs2 /2 Use the MPFS2 format (Default) /html "..." /h "..." File types to be parsed for dynamic variables (Default: "*.htm, *.html, *.cgi, *.xml") /xgzip "..." /z "..." File types to be excluded from GZIP compression (Default: "*.bib, *.inc") The command-line interface does not support image uploads. For batch or production uploads, use a tool such as wget to upload the generated BIN image. 5.8.1.5.2 TCP/IP Discoverer This topic provides a description of the TCP/IP Discoverer. Description The TCP/IP Discoverer PC project (formerly known as the Embedded Ethernet Device Discoverer) will aid in embedded product device discovery (with the Announce ( see page 160) protocol) and will demonstrate how to write PC applications to communicate to embedded devices. When the "Discover Devices" button is clicked, this application will transmit a broadcast UDP packet containing the message, "Discovery: Who is out there?" on the local network to port 30303. If any embedded devices with the Announce ( see page 160) protocol enabled are connected to the network, they will respond with a UDP packet containing their host name (NBNS ( see page 295)) and MAC address. The Java source code for this application is also included. This source code should provide a rough idea of how to write a PC-based application to communicate with your embedded devices. 5.8.2 TCP/IP Stack Porting Guide 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3545 5.8.2.1 Introduction Porting to the MPLAB Harmony TCP/IP Stack This help file provides information for porting from a previous version of the TCP/IP Stack to the TCP/IP Stack within MPLAB Harmony. 5.8.2.2 Release Notes MPLAB Harmony Version: v0.70b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.2.3 SW License Agreement © 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED “AS IS.” MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.2.4 Upgrading from the V5 TCP/IP Stack to the MPLAB Harmony TCP/IP Stack The MPLAB Harmony TCP/IP Stack is a completely new distribution, which is included as part of the MPLAB Harmony installation. No files need to be maintained from an existing V5 TCP/IP Stack installation. 5.8.2.4.1 MPLAB Harmony TCP/IP Stack Key Features This topic provides a description of the key features of the MPLAB Harmony TCP/IP Stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3546 Description Note: The PIC18 device family is not supported by the MPLAB Harmony TCP/IP Stack. The following are the key features of the MPLAB Harmony TCP/IP Stack: • Multiple interfaces • IPV6 support • Fully dynamic: • Stack initialization/deinitialization • Up/down interface • Resource management • Module configuration • Improved modularity and stack layout • Run-time configuration through the TCP/IP console • Interrupt driven operation • RTOS friendly, with easy RTOS integration 5.8.2.4.2 MPLAB Harmony TCP/IP Stack Structure This topic describes the structure of the MPLAB Harmony TCP/IP Stack. Description The MPLAB Harmony TCP/IP Stack consists of the following structure: • Lowercase file names • Underscores are used (e.g., tcpip_manager.h) • Private headers are no longer exposed and have been moved to the source folder • System services have been removed from the stack, such as: • Interrupts • Drivers • Timer services • File system • Board Support Package (BSP) By default, the TCP/IP Stack is placed into the following location during installation of MPLAB Harmony on a Windows® system: C:\Microchip\harmony\\framework\tcpip The following figure shows the list of files in the tcpip folder. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3547 5.8.2.4.3 MPLAB Harmony TCP/IP Stack Design This topic discusses the design of the MPLAB Harmony TCP/IP Stack. Description The MPLAB Harmony TCP/IP Stack is designed as a part of a system running other applications, middleware, etc. Therefore, it makes use of the system services that are available to other modules in the system or to the application, such as: • File system • System interrupts • System driver services • System timers • System device drivers • System command processor • System console • System debug services Refer to the ./framework/tcpip/src/system folder for the header files that expose the system wide available API. 5.8.2.4.4 MPLAB Harmony TCP/IP Stack API Changes This topic discusses the reasons behind the API changes to the MPLAB Harmony TCP/IP Stack. Description For most modules, the API should be backward compatible to the V5 TCP/IP Stack. The changes in the stack API have been minimized so that the porting process is straightforward. However, new functionality has been added because of new features, such as IPV6 support, multiple network interfaces, and the dynamic configuration of the stack. Other than these new features, the changes to the API were only made when an existing V5 TCP/IP Stack function did not support the required parameters/flexibility, or they were confusing. The API changes are at the TCP, UDP, ARP, HTTP, SMTP, and stack access and initialization level. 5.8.2.4.4.1 TCP Changes This topic discusses the changes made to the tcp.h file. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3548 Description TCP Changes The TCP/IP Stack include header file, tcp.h, has been updated as follows. • DNS Resolution - DNS resolution is no longer performed automatically when opening a TCP socket. The TCP layer takes only an IP address as an input parameter. If you need a DNS resolution, you have to perform it before opening a socket (see dns.h). • IPV6 Support - Support for IPV6 has been added Opening TCP Sockets To open TCP sockets, the required functions are now: TCP_SOCKET TCPIP_TCP_ServerOpen(IP_ADDRESS_TYPE addType, TCP_PORT localPort, IP_MULTI_ADDRESS* localAddress) and TCP_SOCKET TCPIP_TCP_ClientOpen(IP_ADDRESS_TYPE addType, TCP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress) These two new functions replace the V5 TCP/IP Stack TCPOpen function. The application code must replace the calls to TCPOpen with TCP_SOCKET TCPIP_TCP_ServerOpen or TCP_SOCKET TCPIP_TCP_ClientOpen, as appropriate. The new calls add the possibility to use IPV6 addresses and make clear the choice of parameters for server or client sockets. The parameters are: • typedef union { IPV4_ADDR v4Add; IPV6_ADDR v6Add; }IP_MULTI_ADDRESS; • typedef enum { IP_ADDRESS_TYPE_ANY = 0, // either IPv4 or IPv6; unspecified; IP_ADDRESS_TYPE_IPV4 = 1, // IPv4 address type IP_ADDRESS_TYPE_IPV6 // IPv6 address type }IP_ADDRESS_TYPE; Note: Currently, IP_ADDRESS_TYPE_ANY is only supported for server sockets. Disconnecting a Socket The functions to disconnect a socket have changed to include added functionality: • TCPIP_TCP_Disconnect(TCP_SOCKET hTCP) This function closes the TX side of a connection by sending a FIN (if currently connected) to the remote node of the connection. It no longer sends a RST signal to the remote node so that a sequence of two sequential calls to the function is no longer needed. If the socket has the Linger option set (default), the queued TX data transmission will be attempted before sending the FIN. If the Linger option is off, the queued TX data will be discarded. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3549 No more data can be sent by this socket, but more data can be received (the socket will be eventually closed when a FIN is received from the remote node or by a time-out dictated by the TCP_FIN_WAIT_2_TIMEOUT value in tcp_config.h). Please note that this call may fail in which case it can be reissued. Setting the socket options is done using the function TCPIP_TCP_OptionsSet(). • TCPIP_TCP_Abort(TCP_SOCKET hTCP, bool killSocket) This function aborts a connection to a remote node by sending a RST (if currently connected). Any pending TX/RX data is discarded. A client socket will always be closed and the associated resources released. The socket cannot be used again after this call. A server socket will abort the current connection if: - killSocket == false (the socket will remain listening) - killSocket == true (the socket will be closed and all associated resources released. The socket cannot be used again after this call.) • TCPIP_TCP_Close(TCP_SOCKET hTCP) This function disconnects an open socket and destroys the socket handle, releasing the associated resources. If the graceful option is set for the socket (default) a TCPIP_TCP_Disconnect will be tried (FIN will be sent): - If the linger option is set (default) the TCPIP_TCP_Disconnect will attempt to send any queued TX data before issuing the FIN - If the FIN send operation fails or the socket is not connected, an abort is generated If the graceful option is not set, or the previous step could not send the FIN: - A TCPIP_TCP_Abort() is called, sending a RST to the remote node and communication is closed. The socket is no longer valid and the associated resources are freed. Setting the socket options is done using the call TCPIP_TCP_OptionsSet();. Adjusting Socket Size The function to adjust the size of a socket’s RX and TX buffers has changed to include added functionality: • TCPIP_TCP_FifoSizeAdjust(TCP_SOCKET hTCP, uint16_t wMinRXSize, uint16_t wMinTXSize, TCP_ADJUST_FLAGS vFlags) The TX and RX FIFOs (buffers) associated with a socket are now completely separate and independent. Two new flags, TCP_ADJUST_TX_ONLY and TCP_ADJUST_RX_ONLY, have been added, which allow changing the size of TX and RX buffers independently. This is the preferred option. However, when either flag is not set, for the purpose of this function, the TX and RX FIFOs are considered to be contiguous so that the total FIFO space is divided between the TX and RX FIFOs. This provides backward compatibility with previous versions of this function. Note: The TX or RX associated buffer sizes can be independently changed too using the socket options. See the TCPIP_TCP_OptionsSet help for more information. 5.8.2.4.4.2 UDP Changes This topic discusses the changes made to the udp.h file. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3550 Description UDP Changes The TCP/IP Stack include header file, udp.h, has been updated as follows. • DNS Resolution - DNS resolution is no longer performed automatically when opening a UDP socket. The UDP layer takes only an IP address as an input parameter. If you need a DNS resolution, you have to perform it before opening a socket (see dns.h). • IPV6 Support - Support for IPV6 has been added Opening UDP Sockets To open UDP sockets, the required functions are now: UDP_SOCKET TCPIP_UDP_ServerOpen(IP_ADDRESS_TYPE addType, UDP_PORT localPort, IP_MULTI_ADDRESS* localAddress); and UDP_SOCKET TCPIP_UDP_ClientOpen(IP_ADDRESS_TYPE addType, UDP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress); These two new functions replace the V5 TCP/IP Stack UDPOpen function. The application code must replace any calls to UDPOpen with UDP_SOCKET TCPIP_UDP_ServerOpen() or UDP_SOCKET TCPIP_UDP_ClientOpen(), as appropriate. Note: Currently, IP_ADDRESS_TYPE_ANY is only supported for server sockets. 5.8.2.4.4.3 ARP Changes This topic discusses the changes made to the arp.h file. Description ARP Changes The header file, arp.h, has been updated as follows. The ARP module has been redesigned to support multiple network interfaces and to implement internal storage (caches) per interface for eliminating the need for frequent access to the network. Some of the most important changes include: • Manipulation/control of the cache entries (TCPIP_ARP_EntryGet, TCPIP_ARP_EntrySet, TCPIP_ARP_EntryRemove) with permanent entries support • Dynamic notification mechanism (TCPIP_ARP_HandlerRegister, TCPIP_ARP_HandlerDeRegister) for signaling of the ARP events • Resolution calls (TCPIP_ARP_Resolve, TCPIP_ARP_Probe, TCPIP_ARP_IsResolved). Normally, the application does not need access to the ARP module. The address resolution is performed internally by the stack. The ARP module cache manipulation access is meant for TCP/IP Stack control and configuration depending on the actual network topology. 5.8.2.4.4.4 HTTP Changes This topic discusses the changes made to the http.h file. Note: This file was named http2.h in the V6 Beta TCP/IP Stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3551 Description HTTP Changes The TCP/IP Stack include header file, http.h, has been updated as follows. All of the functions that the HTTP exposes as its API now take a first parameter, a HTTP connection handle, named HTTP_CONN_HANDLE. This allows a cleaner and better behavior in both multi-threaded environments and in the situation where we it may be desired to run multiple instances of the HTTP process itself, allowing for serving multiple independent connections. For example, the HTTP functions now appear as: • TCPIP_HTTP_FileInclude(HTTP_CONN_HANDLE connHandle, const uint8_t* cFile) ; • HTTPExecuteGet(HTTP_CONN_HANDLE connHandle); • HTTPExecutePost(HTTP_CONN_HANDLE connHandle); • TCPIP_HTTP_CurrentConnectionFileGet(HTTP_CONN_HANDLE connHandle); • TCPIP_HTTP_CurrentConnectionCallbackPosGet(HTTP_CONN_HANDLE connHandle); Support has been added for the HTTP module client to store/retrieve its own connection related data. For example: • TCPIP_HTTP_CurrentConnectionUserDataSet(HTTP_CONN_HANDLE connHandle, const void* uData); • TCPIP_HTTP_CurrentConnectionUserDataGet(HTTP_CONN_HANDLE connHandle); HTTP Print Also, the functions exposed in http_print.h take the connection handle parameter. For example: • HTTPPrint(HTTP_CONN_HANDLE connHandle, uint32_t callbackID); • HTTPPrint_hellomsg(HTTP_CONN_HANDLE connHandle); These changes affect all of the function calls in the file, custom_http_app.c, such as: • HTTPExecuteGet(HTTP_CONN_HANDLE connHandle); • HTTPExecutePost(HTTP_CONN_HANDLE connHandle); To port an existing application, the extra parameter will have to be added. The connection handle is passed to the application as part of the HTTP callback. The modifications should be minimal and possible using an editor without any other impact. Please note that the MPFS2 generator tool (mpfs2.jar) has been updated to support the new HTTP API. See the list of the complete API changes in http.h and http_print.h. 5.8.2.4.4.5 MPLAB Harmony TCP/IP Stack Storage Changes This topic describes the storage changes in the MPLAB Harmony TCP/IP Stack. Description MPLAB Harmony TCP/IP Stack Storage Changes The V5 TCP/IP Stack include header file, tcpip_storage.h, does not exist in the MPLAB Harmony TCP/IP Stack. The TCP/IP Stack storage has become obsolete and is no longer maintained. This is mainly due to the way the dynamic initialization of the stack is done in the V5 TCP/IP Stack: • Each module has its own initialization data • There are many parameters that could be relevant for an application and that may require storage besides the IP address, IP Mask, or SSID, etc. • The data is passed dynamically at the stack initialization. There is no more “build time” set of parameters against which to 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3552 check at stack configuration (although support for a default configuration set at build time is present). The actual data contents are the application responsibility. • A system database service will be added that will use the File System. The database service will maintain configurations for all the modules in the system, including the TCP/IP. The system database service API will be available to the applications as well for storing/retrieving proprietary information. • The parameter, TCPIP_STACK_USE_STORAGE, in the file, tcpip_config.h, should not be enabled. Future plans call for this service to be removed from the distribution. 5.8.2.4.4.6 MPLAB Harmony TCP/IP Stack Configuration Changes This topic describes the configuration changes in the MPLAB Harmony TCP/IP Stack. Description The stack configuration has a completely new structure. Each project has its own configuration folder that stores multiple configurations based on CPU platforms and hardware boards. Note: V5 TCP/IP Stack configuration files cannot be reused in the MPLAB Harmony TCP/IP Stack. The following is a list of the most important features: • system_config folder for projects – all profiles are stored in this location • Multiple profiles per project, which are separated by CPU platform. The TCP/IP profile is usually common. • tcpip_config.h – selects modules that are part of the build • Each module has its own profile: arp_config.h, tcp_config.h, ssl_config.h, etc. • BSP profiles per development board containing: • hardware_config.h – the BSP specific hardware settings • media_storage_config.h – storage media and partitioning settings • sys_fs_config.h – file system configuration and settings • mpfs_config.h – MPFS file system settings • network_config.h – configuration for every network interface: NetBIOS names, default IP addresses, etc. • system_config.h – system configuration (i.e, system tick, system console selection, system debug services, etc.) 5.8.2.4.4.6.1 MPLAB Harmony TCP/IP Stack Configuration This topic provides information on the configuration of the MPLAB Harmony TCP/IP Stack. Description MPLAB Harmony TCP/IP Stack Configuration The presented structure is simply a model and a different layout can be chosen. The only requirement is to use the proper path in your project so that the necessary configuration files are found at build time. For example, depending on your exact hardware platform or development board, a path similar to the following can be added to your project path: ..\harmony\\apps\tcpip\tcpip_web_server_demo_app\firmware\src\system_config\pic32_eth_ sk_int_dyn\tcpip_profile 5.8.2.4.4.6.2 MPLAB Harmony TCP/IP Stack Heap Configuration This topic provides information on the heap configuration of the MPLAB Harmony TCP/IP Stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3553 Description MPLAB Harmony TCP/IP Stack Heap Configuration The MPLAB Harmony TCP/IP Stack uses dynamic memory for both initialization and run time buffers. Therefore, there are two requirements for a project containing the stack to work properly. The first requirement is that the TCP/IP stack should be configured with enough heap space. The amount of heap used by the stack is specified by the TCPIP_STACK_DRAM_SIZE parameter in the tcpip_config.h file. The value of the required TCP/IP heap for a project is application dependent. Some of the most important factors that impact the heap size are: • Number of TCP sockets • By default, each TCP socket requires 512 bytes for a RX buffer and 512 bytes for a TX buffer. These parameters can be adjusted by modifying the values specified in tcp_config.h or dynamically through the TCPIP_TCP_OptionsSet() function. • Number of UDP sockets: • For each UDP socket that needs to initiate a transmission, the IP layer will have to allocate the required space (suggested by the functions, UDPv4IsTxPutReady or UDPv4IsTxPutReady • Once the UDP buffering will be added, each socket will have its own RX and TX buffers. These parameters can be adjusted by modifying the values specified in the file, udp_config.h, or dynamically through the TCPIP_UDP_OptionsSet() function • The type of Ethernet MAC that is used: • The PIC32MX6XX/7XX devices with a built-in 100 Mbps Ethernet controller use system memory for buffering incoming RX traffic. For sustained 100 Mbps operation, adequate RX buffer space must be provided. This parameter can be adjusted by modifying the values specified in the file, network_config.h, using the array, TCPIP_HOSTS_CONFIGURATION[]. • If SSL is enabled, it will require additional buffering for encryption/decryption at run-time. The SSL module buffering requirement is dependent on the RSA key length specified in ssl_config.h. The second requirement is that the project that includes the MPLAB Harmony TCP/IP Stack must be built with sufficient heap size to accommodate the stack (at a minimum, the project needs the TCPIP_STACK_DRAM_SIZE bytes of heap). This parameter is adjusted on the Linker tab in the project properties. In general, for a TCP/IP project running on a PIC32MX device with an embedded Ethernet controller, at least 8 KB of heap space is needed by the stack. However, the following is implied: • 100 Mbps traffic is not sustained • No SSL • Relatively few sockets A typical value for comfortably handling 100 Mbps Ethernet traffic would be 40 KB of TCP/IP heap space. The amount of the required heap is less for an external Ethernet MAC. Keep in mind the following when assigning heap space: • If there is not enough heap space the stack initialization may fail • If there is not enough heap space some run time buffer allocation may fail and some packets transmission will have to be deferred until a later time, thus impacting the stack performance • It is always a good idea to have a reserve, at least an extra 2 KB of heap space above the total amount of space that is used • A very useful tool in understanding the heap allocation and how the space is distributed among the stack modules is the TCP/IP command processor By enabling the parameter, TCPIP_STACK_DRAM_DEBUG_ENABLE, in the tcpip_config.h file, the stack will output debug messages when it runs out of memory. Then, using the heapinfo command at the TCP/IP command processor prompt will 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3554 return a snapshot of the current TCP/IP heap status and can help in early detection of problems. Optionally, enabling the parameter, TCPIP_STACK_DRAM_TRACE_ENABLE in the tcpip_config.h file, will instruct the TCP/IP heap allocation module to store trace information that will be displayed with the heapinfo command. 5.8.2.4.4.7 New MPLAB Harmony TCP/IP Stack API Functions This topic describes some of the important new API functions in the MPLAB Harmony TCP/IP Stack. Description There are many new functions available that have been introduced to take advantage of new features, such as IPV6 and support of multiple interfaces. However, there is no concern for the porting process regarding the new API calls as the previous stack implementation did not support this kind of service. A new API function should be added to the application only when the access to the new feature is needed. Existent applications should port easily without using the new API. For reference, the following are a few of the most important new API functions that could prove useful in the porting of your application: • Initialization of the stack network interfaces: • TCPIP_STACK_NetUp() • TCPIP_STACK_NetDown() • Default interface selection: • TCPIP_STACK_NetDefaultGet() • TCPIP_STACK_NetDefaultSet() • TCP/UDP multiple interface support: • TCPIP_TCP_Bind() • TCPIP_TCP_RemoteBind() • TCPIP_TCP_SocketNetGet() • TCPIP_TCP_SocketNetSet() • TCPIP_UDPBind() • TCPIP_UDP_RemoteBind() • TCPIP_UDP_SocketNetGet() • TCPIP_UDP_SocketNetSet() Refer to the file, tcpip_manager.h, for a complete list of all new network interface APIs. 5.8.2.4.4.7.1 Main Program Changes This topic describes the main program changes in the MPLAB Harmony TCP/IP Stack. Description Main Program Changes There are few changes that the main program loop has to take care of. A full working example is given with the file, main_demo.c, which is provided with the stack distribution. The main program should call the following functions: • SYS_Initialize() – This function is what initializes the system and runs the Board Support Package (BSP) specific code 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3555 • SYS_Tasks() – This is the function that takes care of the system tasks and must be called periodically • TCPIP_STACK_Task() – This is the TCP/IP stack tasks function that runs all of the state machines that are part of the TCP/IP stack. This function must be called periodically. Please note the name change. To gain access to a network interface the TCPIP_STACK_NetHandle(“iname”) function should be used. Examples are provided in the previous section. 5.8.2.4.4.8 MPLAB Harmony TCP/IP Stack Initialization Changes This topic describes the initialization updates to the MPLAB Harmony TCP/IP Stack. Description The TCP/IP Stack include header file, tcpip_manager.h, has been updated as follows. To initialize the stack the call is now: TCPIP_STACK_Initialize(const TCPIP_NETWORK_CONFIG* pNetConf, int nNets, TCPIP_STACK_MODULE_CONFIG* pModConfig, int nModules); Where: • pNetConf – is a pointer to an array of configurations for all the initialized network interfaces • nNets – is the number of the network interfaces that the stack is to support • pModConfig – is a pointer to an table storing configuration data for the TCP/IP stack modules • nModules – is the number of entries in this table, (i.e., the number of initialized modules) The default TCP/IP stack configuration is provided with the stack distribution and consists of: • network_config.h: TCPIP_HOSTS_CONFIGURATION[] – an array of TCPIP_NETWORK_CONFIG entries describing the default configuration of each network interface • tcpip_modules_config.h: TCPIP_STACK_MODULE_CONFIG_TBL[] – an array of TCPIP_STACK_MODULE_CONFIG entries storing the default configuration data for each module of the TCP/IP stack. This is just an aggregate of all the default configurations per module found in the module configuration header files, such as tcp_config.h, udp_config.h, arp_config.h, and so on. These tables are defined by default in the configuration files. See MPLAB Harmony TCP/IP Stack Configuration Changes for details. You can change the parameters of these structures as appropriate. An example of the TCP/IP initialization is part of the distributed file, main_demo.c. This file is located in the following Windows® path: .\harmony\apps\tcpip\tcpip_web_server_demo_app\firmware\src Note: The stack initialization may fail. The application code must check the result of this call to detect if the stack failed to initialize properly. 5.8.2.4.4.9 MPLAB Harmony TCP/IP Stack Access Changes This topic describes the stack access updates that were made to the MPLAB Harmony TCP/IP Stack. Description The TCP/IP Stack include header file, tcpip_manager.h, has been updated as follows. Direct access to the internally maintained stack structures has been removed. To access the information for a specific network interface a handle must be obtained using the interface name. For example: TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet("PIC32INT"); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3556 or TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet(“MRF24W”); Once a handle to the interface has been obtained, different parameters of that network interface can be queried and set. For example: • TCPIP_STACK_NetAddress(TCPIP_NET_HANDLE netH) – returns the network interface address • TCPIP_STACK_NetAddressGateway(TCPIP_NET_HANDLE netH) – returns the interface gateway address Refer to the tcpip_manager.h file for a complete list of functions. Note: The TCPIP_NET_HANDLE is an opaque data type. The well known names of the network interfaces are currently in the file, tcpip.h. The exact header file that exposes the network interfaces names may change in the future; however, the names of the supported network interfaces will be retained. Use the file, network_config.h, as an example. Refer to the file, main_demo.c, for an example of how to use the interface handle functions. 5.8.2.5 MPLAB Harmony TCP/IP Stack Utilities This topic describes the MPLAB Harmony TPC/IP Stack utilities. Description The MPLAB Harmony TCP/IP Stack includes the following utilities: • MPFS2 - The MPFS2 Java utility that assists the application in generating the MPFS image of the files needed by the Web server has been updated. This utility supports both the V5 and MPLAB Harmony versions of the TCP/IP stack with improved functionality. The V5 TCP/IP Stack utility can still be used; however, some minor adjustments may need to be done manually. • TCP/IP Discoverer - The TCP/IP Discoverer Java utility has been updated to support not only the MPLAB Harmony TCP/IP Stack, but also IPV6. This utility is up and running and is backward compatible with the V5 TCP/IP Stack. • TCP/IP Configuration - The TCP/IP Configuration utility is currently not supported. The need of individually configuring TCP and UDP sockets is no longer needed, as all sockets behave similarly and they are allocated dynamically as needed. 5.8.2.6 MPLAB Harmony TCP/IP Stack SSL/RSA Usage This topic provides information regarding the usage of SSL and RSA. Description The SSL design has been updated to support multiple interfaces. The same is true for the RSA engine. However, the SSL module does not currently use the Microchip Crypto Library. Until the proper Crypto Library support is added to SSL, the stack is distributed with the RSA and RC4 code embedded into the stack. In the future, the Crypto Library will be completely removed from the TCP/IP stack, and the stack will be just a client to the Crypto Library. 5.8.2.7 Porting Applications from the V6 Beta TCP/IP Stack to the MPLAB Harmony TCP/IP Stack Porting an application from the V6 Beta TCP/IP Stack into the TCP/IP Stack within MPLAB Harmony consists of updating 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3557 existing TCP/IP Stack function names in your application to the new MPLAB Harmony function names. 5.8.2.7.1 MPLAB Harmony TCP/IP Stack Function Name Compliance This topic provides header file function mapping tables that show the V6 Beta TCP/IP Stack function name and the compliant name within the MPLAB Harmony TCP/IP Stack. Description The replacement names chosen to make existing TCP/IP Stack functions compliant with MPLAB Harmony are shown in individual tables per header file name. The files listed in the tables are located in the following two MPLAB Harmony installation folders: .\harmony\\framework\tcpip .\harmony\\framework\tcpip\src Each table shows the original and new names used. Note that other than name changes, no other modifications were made to the middleware functions. Header File: arp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name ARP_ENTRY_QUERY TCPIP_ARP_ENTRY_QUERY ARP_ENTRY_TYPE TCPIP_ARP_ENTRY_TYPE ARP_EVENT_HANDLER TCPIP_ARP_EVENT_HANDLER ARP_EVENT_TYPE TCPIP_ARP_EVENT_TYPE ARP_HANDLE TCPIP_ARP_HANDLE ARP_OPERATION_TYPE TCPIP_ARP_OPERATION_TYPE ARP_RESULT TCPIP_ARP_RESULT ARPCacheGetEntriesNo TCPIP_ARP_CacheEntriesNoGet ARPCacheSetThreshold TCPIP_ARP_CacheThresholdSet ARPEntryGet TCPIP_ARP_EntryGet ARPEntryQuery TCPIP_ARP_EntryQuery ARPEntryRemove TCPIP_ARP_EntryRemove ARPEntryRemoveAll TCPIP_ARP_EntryRemoveAll ARPEntryRemoveNet TCPIP_ARP_EntryRemoveNet ARPEntrySet TCPIP_ARP_EntrySet ARPDeRegisterHandler TCPIP_ARP_HandlerDeRegister ARPIsResolved TCPIP_ARP_IsResolved ARPProbe TCPIP_ARP_Probe ARPRegisterHandler TCPIP_ARP_HandlerRegister ARPResolve TCPIP_ARP_Resolve ARPRegisterCallbacks TCPIP_ARP_CallbacksRegister Header File: dhcp.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3558 V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name DHCPDeRegisterHandler TCPIP_DHCP_HandlerDeRegister DHCPRegisterHandler TCPIP_DHCP_HandlerRegister DHCPSetRequestTimeout TCPIP_DHCP_RequestTimeoutSet DHCP_EVENT_HANDLER TCPIP_DHCP_EVENT_HANDLER DHCP_EVENT_TYPE TCPIP_DHCP_EVENT_TYPE DHCP_HANDLE TCPIP_DHCP_HANDLE DHCPDisable TCPIP_DHCP_Disable DHCPEnable TCPIP_DHCP_Enable DHCPIsBound TCPIP_DHCP_IsBound DHCPIsEnabled TCPIP_DHCP_IsEnabled DHCPIsServerDetected TCPIP_DHCP_IsServerDetected Header File: dhcps.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name DHCPServerIsEnabled TCPIP_DHCPS_IsEnabled DHCPServerLeaseEntryGet TCPIP_DHCPS_LeaseEntryGet DCHPServerGetPoolEntries TCPIP_DHCPS_GetPoolEntries DCHPServerRemovePoolEntries TCPIP_DHCPS_RemovePoolEntries DHCPServerDisable TCPIP_DHCPS_Disable DHCPServerEnable TCPIP_DHCPS_Enable DHCPServerIsEnabled TCPIP_DHCPS_IsEnabled Header File: ddns.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name DDNSForceUpdate TCPIP_DDNS_UpdateForce DDNSSetService TCPIP_DDNS_ServiceSet DDNSGetLastIP TCPIP_DDNS_LastIPGet DDNSGetLastStatus TCPIP_DDNS_LastStatusGet Header File: dns.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name DNSBeginUsage TCPIP_DNS_UsageBegin DNSEndUsage TCPIP_DNS_UsageEnd DNSResolve TCPIP_DNS_Resolve DNSIsResolved TCPIP_DNS_IsResolved Header File: http.h (formerly http2.h) V6 Beta TCP/IP Stack Name (http2.h) MPLAB Harmony Compliant Name (http.h) HTTPURLDecode TCPIP_HTTP_URLDecode 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3559 HTTPGetArg TCPIP_HTTP_ArgGet HTTPReadPostName TCPIP_HTTP_PostNameRead HTTPReadPostValue TCPIP_HTTP_PostValueRead HTTPIncFile TCPIP_HTTP_FileInclude HTTPCurConnectionFileGet TCPIP_HTTP_CurrentConnectionFileGet HTTPCurConnectionPostSmGet TCPIP_HTTP_CurrentConnectionPostSmGet HTTPCurConnectionPostSmSet TCPIP_HTTP_CurrentConnectionPostSmSet HTTPCurConnectionDataBufferGet TCPIP_HTTP_CurrentConnectionDataBufferGet HTTPCurConnectionCallbackPosGet TCPIP_HTTP_CurrentConnectionCallbackPosGet HTTPCurConnectionCallbackPosSet TCPIP_HTTP_CurrentConnectionCallbackPosSet HTTPCurConnectionStatusSet TCPIP_HTTP_CurrentConnectionStatusSet HTTPCurConnectionHasArgsSet TCPIP_HTTP_CurrentConnectionHasArgsSet HTTPCurConnectionByteCountGet TCPIP_HTTP_CurrentConnectionByteCountGet HTTPCurConnectionByteCountSet TCPIP_HTTP_CurrentConnectionByteCountSet HTTPCurConnectionByteCountDec TCPIP_HTTP_CurrentConnectionByteCountDec HTTPCurConnectionSocketGet TCPIP_HTTP_CurrentConnectionSocketGet Header File: icmp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name ICMPDeRegisterCallback TCPIP_ICMP_CallbackDeregister ICMPRegisterCallback TCPIP_ICMP_CallbackRegister ICMPSendEchoRequest TCPIP_ICMP_EchoRequestSend Header File: icmpv6.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_ICMPV6_DeRegisterCallback TCPIP_ICMPV6_CallbackDeregister TCPIP_ICMPV6_PutHeaderEchoRequest TCPIP_ICMPV6_HeaderEchoRequestPut TCPIP_ICMPV6_RegisterCallback TCPIP_ICMPV6_CallbackRegister TCPIP_IPV6_GetDestAddress TCPIP_IPV6_AddressDestGet TCPIP_IPV6_GetSourceAddress TCPIP_IPV6_AddressSourceGet TCPIP_IPV6_SetDestAddress TCPIP_IPV6_AddressDestSet TCPIP_IPV6_SetSourceAddress TCPIP_IPV6_AddressSourceSet TCPIP_IPV6_DAS_SelectSourceAddress TCPIP_IPV6_DAS_AddressSourceSelect TCPIP_IPV6_AddUnicastAddress TCPIP_IPV6_AddressUnicastAdd TCPIP_IPV6_RemoveUnicastAddress TCPIP_IPV6_AddressUnicastRemove TCPIP_IPV6_AddMulticastListener TCPIP_IPV6_MulticastListenerAdd TCPIP_IPV6_RemoveMulticastListener TCPIP_IPV6_MulticastListenerRemove TCPIP_IPV6_RegisterHandler TCPIP_IPV6_HandlerRegister TCPIP_IPV6_DeRegisterHandler TCPIP_IPV6_HandlerDeRegister 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3560 Header File: ipv6.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_IPV6_InterfaceIsReady Not Applicable TCPIP_IPV6_Put Not Applicable TCPIP_IPV6_AddressIsSolicitedNodeMulticast Not Applicable TCPIP_IPV6_Flush Not Applicable TCPIP_IPV6_PutArrayHelper TCPIP_IPV6_ArrayPutHelper TCPIP_IPV6_DAS_SelectSourceAddress TCPIP_IPV6_DASSourceAddressSelect TCPIP_IPV6_GetDestAddress TCPIP_IPV6_DestAddressGet TCPIP_IPV6_SetDestAddress TCPIP_IPV6_DestAddressSet TCPIP_IPV6_DeRegisterHandler TCPIP_IPV6_HandlerDeregister TCPIP_IPV6_RegisterHandler TCPIP_IPV6_HandlerRegister TCPIP_IPV6_AddMulticastListener TCPIP_IPV6_MulticastListenerAdd IPv6RemoveMulticastListener TCPIP_IPV6_MulticastListenerRemove TCPIP_IPV6_FreePacket TCPIP_IPV6_PacketFree TCPIP_IPV6_SetPayload TCPIP_IPV6_PayloadSet TCPIP_IPV6_GetSourceAddress TCPIP_IPV6_SourceAddressGet TCPIP_IPV6_SetSourceAddress TCPIP_IPV6_SourceAddressSet TCPIP_IPV6_IsTxPutReady TCPIP_IPV6_TxIsPutReady TCPIP_IPV6_AllocateTxPacket TCPIP_IPV6_TxPacketAllocate TCPIP_IPV6_AddUnicastAddress TCPIP_IPV6_UnicastAddressAdd TCPIP_IPV6_GetArray TCPIP_IPV6_ArrayGet IPv6RemoveUnicastAddress TCPIP_IPV6_UnicastAddressRemove Header File: ndp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_NDP_NeighborConfirmReachability TCPIP_NDP_NborReachConfirm Header File: smtp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name SMTPPutArray TCPIP_SMTP_ArrayPut SMTPFlush TCPIP_SMTP_Flush SMTPIsBusy TCPIP_SMTP_IsBusy SMTPIsPutReady TCPIP_SMTP_IsPutReady SMTPSendMail TCPIP_SMTP_MailSend SMTPPut TCPIP_SMTP_Put SMTPPutDone TCPIP_SMTP_PutIsDone SMTPPutString TCPIP_SMTP_StringPut SMTPBeginUsage TCPIP_SMTP_UsageBegin 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3561 SMTPEndUsage TCPIP_SMTP_UsageEnd Header File: snmp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name SNMPNotify TCPIP_SNMP_Notify SNMPIsNotifyReady TCPIP_SNMP_NotifyIsReady SNMPNotifyPrepare TCPIP_SNMP_NotifyPrepare SNMPGetPktProcessingDynMemStubPtrs TCPIP_SNMP_PacketProcStubPtrsGet SNMPGetProcessBuffData TCPIP_SNMP_ProcessBufferDataGet SNMPPutDataToProcessBuff TCPIP_SNMP_DataCopyToProcessBuffer SNMPRetrieveReadCommunity TCPIP_SNMP_ReadCommunityGet SNMPGetTrapTime TCPIP_SNMP_TrapTimeGet SNMPUdpClientGetNet TCPIP_SNMP_ClientGetNet SNMPRetrieveWriteCommunity TCPIP_SNMP_WriteCommunityGet Header File: sntp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name SNTPGetUTCSeconds TCPIP_SNTP_UTCSecondsGet Header File: tcpip_manager.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_STACK_SetNetAddress TCPIP_STACK_NetAddressSet TCPIP_STACK_SetNetGatewayAddress TCPIP_STACK_NetAddressGatewaySet TCPIP_STACK_SetNetPriDNSAddress TCPIP_STACK_NetAddressDnsPrimarySet TCPIP_STACK_SetNetSecondDNSAddress TCPIP_STACK_NetAddressDnsSecondSet TCPIP_STACK_SetNetMask TCPIP_STACK_NetMaskSet TCPIP_STACK_SetNetMacAddress TCPIP_STACK_NetAddressMacSet TCPIP_STACK_NetGatewayAddress TCPIP_STACK_NetAddressGateway TCPIP_STACK_NetPriDNSAddress TCPIP_STACK_NetAddressDnsPrimary TCPIP_STACK_NetSecondDNSAddress TCPIP_STACK_NetAddressDnsSecond TCPIP_STACK_NetMacAddress TCPIP_STACK_NetAddressMac TCPIP_STACK_NetBcastAddress TCPIP_STACK_NetAddressBcast TCPIP_STACK_SetNetBIOSName TCPIP_STACK_NetBiosNameSet TCPIP_STACK_GetDefaultNet TCPIP_STACK_NetDefaultGet TCPIP_STACK_SetDefaultNet TCPIP_STACK_NetDefaultSet TCPIP_STACK_IsNetLinked TCPIP_STACK_NetIsLinked TCPIP_STACK_CreateNetInfo TCPIP_STACK_NetInfoCreate TCPIP_STACK_IsNetUp TCPIP_STACK_NetIsUp 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3562 Header File: tcp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIsGetReady TCPIP_TCP_GetIsReady TCPGetArray TCPIP_TCP_ArrayGet TCPPeek TCPIP_TCP_Peek TCPPeekArray TCPIP_TCP_ArrayPeek TCPGetRxFIFOFree TCPIP_TCP_FifoRxFreeGet TCPGetTxFIFOFull TCPIP_TCP_FifoTxFullGet TCPDiscard TCPIP_TCP_Discard TCPGet TCPIP_TCP_Get TCPFind TCPIP_TCP_Find TCPFindArray TCPIP_TCP_ArrayFind TCPAdjustFIFOSize TCPIP_TCP_FifoSizeAdjust TCPOpenServer TCPIP_TCP_ServerOpen TCPOpenClient TCPIP_TCP_ClientOpen TCPBind TCPIP_TCP_Bind TCPRemoteBind TCPIP_TCP_RemoteBind TCPSetOptions TCPIP_TCP_OptionsSet TCPGetOptions TCPIP_TCP_OptionsGet TCPIsConnected TCPIP_TCP_IsConnected TCPWasReset TCPIP_TCP_WasReset TCPDisconnect TCPIP_TCP_Disconnect TCPClose TCPIP_TCP_Close TCPGetSocketInfo TCPIP_TCP_SocketInfoGet TCPSocketSetNet TCPIP_TCP_SocketNetSet TCPSocketGetNet TCPIP_TCP_SocketNetGet TCPIsPutReady TCPIP_TCP_PutIsReady TCPPut TCPIP_TCP_Put TCPPutArray TCPIP_TCP_ArrayPut TCPPutString TCPIP_TCP_StringPut TCPFlush TCPIP_TCP_Flush TCPGetRxFIFOFull TCPIP_TCP_FifoRxFullGet TCPGetTxFIFOFree TCPIP_TCP_FifoTxFreeGet TCPAbort TCPIP_TCP_Abort TCPAddSSLListener TCPIP_TCPSSL_ListenerAdd TCPIsSSL TCPIP_TCP_SocketIsSecuredBySSL TCPSetDestinationIPAddress TCPIP_TCP_DestinationIPAddressSet TCPSetSourceIPAddress TCPIP_TCP_SourceIPAddressSet 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3563 TCPSSLIsHandshaking TCPIP_TCPSSL_StillHandshaking TCpSSLMessageTransmit TCPIP_TCPSSL_MessageTransmit TCPSSLPutRecordHeader TCPIP_TCPSSL_RecordHeaderPut TCPStartSSLClient TCPIP_TCPSSL_ClientStart TCPStartSSLClientEx TCPIP_TCPSSL_ClientBegin TCPStartSSLServer TCPIP_TCPSSL_ServerStart Header File: tcpip_events.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_STACK_GetPendingEvents TCPIP_STACK_EventsPendingGet TCPIP_STACK_RegisterHandler TCPIP_STACK_HandlerRegister TCPIP_STACK_DeRegisterHandler TCPIP_STACK_HandlerDeregister Header File: ipv4.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name TCPIP_IPV4_GetArray TCPIP_IPV4_ArrayGet TCPIP_IPV4_PutArray TCPIP_IPV4_ArrayPut TCPIP_IPV4_PutArrayHelper TCPIP_IPV4_ArrayPutHelper TCPIP_IPV4_GetDestAddress TCPIP_IPV4_DestAddressGet TCPIP_IPV4_SetDestAddress TCPIP_IPV4_DestAddressSet TCPIP_IPV4_FreePacket TCPIP_IPV4_PacketFree TCPIP_IPV4_SetPayload TCPIP_IPV4_PayloadSet TCPIP_IPV4_GetSourceAddress TCPIP_IPV4_SourceAddressGet TCPIP_IPV4_SetSourceAddress TCPIP_IPV4_SourceAddressSet TCPIP_IPV4_IsTxPutReady TCPIP_IPV4_TxIsPutReady TCPIP_IPV4_IsTxReady TCPIP_IPV4_TxIsReady TCPIP_IPV4_AllocateTxPacket TCPIP_IPV4_TxPacketAllocate Header File: udp.h V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name UDPIsGetReady TCPIP_UDP_GetIsReady UDPSetRxOffset TCPIP_UDP_RxOffsetSet UDPGetArray TCPIP_UDP_ArrayGet UDPDiscard TCPIP_UDP_Discard UDPGet TCPIP_UDP_Get UDPOpenServer TCPIP_UDP_ServerOpen UDPOpenClient TCPIP_UDP_ClientOpen UDPBind TCPIP_UDP_Bind UDPRemoteBind TCPIP_UDP_RemoteBind 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3564 UDPSetOptions TCPIP_UDP_OptionsSet UDPGetOptions TCPIP_UDP_OptionsGet UDPIsConnected TCPIP_UDP_IsConnected UDPIsOpened TCPIP_UDP_IsOpened UDPClose TCPIP_UDP_Close UDPGetSocketInfo TCPIP_UDP_SocketInfoGet UDPSocketSetNet TCPIP_UDP_SocketNetSet UDPSocketGetNet TCPIP_UDP_SocketNetGet UDPSetTxOffset TCPIP_UDP_TxOffsetSet UDPIsTxPutReady TCPIP_UDP_TxPutIsReady UDPPutArray TCPIP_UDP_ArrayPut UDPPutString TCPIP_UDP_StringPut UDPGetTxCount TCPIP_UDP_TxCountGet UDPFlush TCPIP_UDP_Flush UDPPut TCPIP_UDP_Put UDPSetBcastIPV4Address TCPIP_UDP_BcastIPV4AddressSet UDPSetSourceIPAddress TCPIP_UDP_SourceIPAddressSet UDPSetDestinationIPAddress TCPIP_UDP_DestinationIPAddressSet 5.8.2.7.2 Development Information (Advance Information) This advance information is specifically provided to assist MPLAB Harmony driver development for porting the existing Ethernet Controller Library and MAC/PHY drivers to the new platform. 5.8.2.7.2.1 Porting the MPLAB Harmony Drivers and Peripheral Library Note: This information is considered to be Advance Information. This topic provides function mapping tables that show the V6 Beta TCP/IP Stack function name and the compliant name within the MPLAB Harmony TCP/IP Stack for the purpose of porting to the MPLAB Harmony Ethernet Drivers and Ethernet Peripheral Library. Description Note: This information is considered to be Advance Information. Porting the MPLAB Harmony Ethernet Drivers and the MPLAB Harmony Ethernet Peripheral Library involves replacing the Ethernet Controller Library with calls to MPLAB Harmony equivalents. This information is listed in Table 1. Please note that function arguments were modified in some instances. To understand how a function of the Ethernet Controller Library is different from its equivalent MPLAB Harmony function, the header of the MPLAB Harmony function should be examined. The MPLAB Harmony function header always lists the Ethernet Controller Library function(s) that the new MPLAB Harmony function replaces, including the arguments of the old function. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3565 Table 1: TCP/IP Stack Function Mapping Ethernet Controller Peripheral Library Name MPLAB Harmony Name EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthEventsClr EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthInit EthMACGetAddress EthMACOpen EthMACSetAddress EthMACSetMaxFrame EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxGetBuffer EthRxGetPacket EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove PLIB_ETH_EventsClr PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet DRV_ETHMAC_LegacyInit PLIB_ETH_MACGetAddress DRV_ETHMAC_LegacyMACOpen PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket Table 2 shows the MPLAB Harmony Ethernet Controller Peripheral Library equivalents for functions in the MPLAB Harmony Ethernet MAC Driver and the MPLAB Harmony Ethernet PHY Driver. The Ethernet Controller Library files are located in the following Windows® installation path: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3566 C:\Program Files\Microchip\xc32\\pic32-libs\peripheral\eth\source Table 2: Ethernet Controller Peripheral Library Function Mapping Ethernet Controller Peripheral Library Name MPLAB Harmony Ethernet MAC Driver Name EthClose EthDescriptorGetBuffer EthDescriptorsPoolAdd EthDescriptorsPoolCleanUp EthDescriptorsPoolRemove EthInit EthMACOpen EthRxAcknowledgeBuffer EthRxAcknowledgePacket EthRxBuffersAppend EthRxGetBuffer EthRxGetPacket EthTxAcknowledgeBuffer EthTxAcknowledgePacket EthTxGetBufferStatus EthTxGetPacketStatus EthTxSendBuffer EthTxSendPacket DRV_ETHMAC_LegacyClose DRV_ETHMAC_LegacyDescriptorGetBuffer DRV_ETHMAC_LegacyDescriptorsPoolAdd DRV_ETHMAC_LegacyDescriptorsPoolCleanUp DRV_ETHMAC_LegacyDescriptorsPoolRemove DRV_ETHMAC_LegacyInit DRV_ETHMAC_LegacyMACOpen DRV_ETHMAC_LegacyRxAcknowledgeBuffer DRV_ETHMAC_LegacyRxAcknowledgePacket DRV_ETHMAC_LegacyRxBuffersAppend DRV_ETHMAC_LegacyRxGetBuffer DRV_ETHMAC_LegacyRxGetPacket DRV_ETHMAC_LegacyTxAcknowledgeBuffer DRV_ETHMAC_LegacyTxAcknowledgePacket DRV_ETHMAC_LegacyTxGetBufferStatus DRV_ETHMAC_LegacyTxGetPacketStatus DRV_ETHMAC_LegacyTxSendBuffer DRV_ETHMAC_LegacyTxSendPacket Ethernet Controller Peripheral Library Name MPLAB Harmony Ethernet Peripheral Library Name EthEventsEnableClr EthEventsEnableGet EthEventsEnableSet EthEventsEnableWrite EthEventsGet EthMACGetAddress EthMACSetAddress EthMACSetMaxFrame EthRxFiltersClr EthRxFiltersHTSet EthRxFiltersPMClr EthRxFiltersPMSet EthRxFiltersSet EthRxFiltersWrite EthRxSetBufferSize EthStatRxAlgnErrCnt EthStatRxFcsErrCnt EthStatRxOkCnt EthStatRxOvflCnt EthStatTxMColCnt EthStatTxOkCnt EthStatTxSColCnt PLIB_ETH_EventsEnableClr PLIB_ETH_EventsEnableGet PLIB_ETH_EventsEnableSet PLIB_ETH_EventsEnableWrite PLIB_ETH_EventsGet PLIB_ETH_MACGetAddress PLIB_ETH_MACSetAddress PLIB_ETH_MACSetMaxFrame PLIB_ETH_RxFiltersClr PLIB_ETH_RxFiltersHTSet PLIB_ETH_RxFiltersPMClr PLIB_ETH_RxFiltersPMSet PLIB_ETH_RxFiltersSet PLIB_ETH_RxFiltersWrite PLIB_ETH_RxSetBufferSize PLIB_ETH_StatRxAlgnErrCnt PLIB_ETH_StatRxFcsErrCnt PLIB_ETH_StatRxOkCnt PLIB_ETH_StatRxOvflCnt PLIB_ETH_StatTxMColCnt PLIB_ETH_StatTxOkCnt PLIB_ETH_StatTxSColCnt 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3567 Table 3 shows the existing and new function names for the TCP/IP MAC driver. Please note that the following v6 Beta TCP/IP Stack files are now obsolete: • eth_pic32_ext_phy.c • eth_pic32_ext_phy_*.c • eth_pic32_int_mac.c • mac_events_pic32.c Table 3: TCP/IP MAC Driver (tcpip_mac.h) – V6 Beta TCP/IP Stack to MPLAB Harmony TCP/IP Stack Conversion V6 Beta TCP/IP Stack Name MPLAB Harmony Compliant Name MAC_ADDR TCPIP_MAC_ADDR MAC_ETHERNET_HEADER TCPIP_MAC_ETHERNET_HEADER MAC_NOTIFY_HANDLER TCPIP_MAC_NOTIFY_HANDLER MAC_PACKET TCPIP_MAC_PACKET MAC_RX_PKT_STAT TCPIP_MAC_RX_PKT_STAT MACEventAck TCPIP_MAC_EventAck MACEventClearNotifyEvents TCPIP_MAC_EventNotifyClear MACEventGetPending TCPIP_MAC_EventPendingEventsGet MACEventSetNotifyEvents TCPIP_MAC_EventNotifyEventsSet MACEventSetNotifyHandler TCPIP_MAC_EventNotifyHandlerSet MACFCEnable TCPIP_MAC_FlowControlEnable MACFCSetPauseValue TCPIP_MAC_FlowControlPauseValueSet MACFCSetRxWMark TCPIP_MAC_FlowControlRxWMarkSet TCPIP_MAC_FC_TYPE TCPIP_MAC_FLOWCONTROLTYPE MACCheckLink TCPIP_MAC_LinkCheck MACCalcIPBufferChecksum TCPIP_MAC_ChecksumIPBufferCalc MACCalcRxChecksum TCPIP_MAC_ChecksumRxCalc MACConnect TCPIP_MAC_Connect MACPowerDown TCPIP_MAC_PowerDown MACPowerUp TCPIP_MAC_PowerUp MACGetHeader TCPIP_MAC_HeaderGet MACDiscardRx TCPIP_MAC_RxDiscard MACGet TCPIP_MAC_Get MACGetArray TCPIP_MAC_ArrayGet MACGetReadPtrInRx TCPIP_MAC_RxReadPtrGet MACGetRxSize TCPIP_MAC_RxSizeGet MACSetBaseReadPtr TCPIP_MAC_ReadPtrBaseSet MACSetReadPtr TCPIP_MAC_ReadPtrSet MACSetReadPtrInRx TCPIP_MAC_RxReadPtrSet MACIsRxReady TCPIP_MAC_RxIsReady 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP/IP Stack Porting Guide 5-3568 MACRxAcknowledge TCPIP_MAC_RxAcknowledge MACRxGetPacket TCPIP_MAC_RxPacketGet MACRxProfile TCPIP_MAC_RxProfile MACRxRegisterNotifyHandler TCPIP_MAC_RxNotifyHandlerRegister MACRxFilterOperation TCPIP_MAC_RxFilterOperation MACRxFilterPatternMode TCPIP_MAC_RxFilterPatternMode MACRxFilterSetHashTableEntry TCPIP_MAC_RxFilterHashTableEntrySet MACTxPacket TCPIP_MAC_TxPacket MACTxProfile TCPIP_MAC_TxProfile MACTxRegisterNotifyHandler TCPIP_MAC_TxNotifyHandlerRegister MACIsTxReady TCPIP_MAC_TxIsReady MACFlush TCPIP_MAC_Flush MACGetSslBaseAddr TCPIP_MAC_SslBaseAddrGet MACGetTxBaseAddr TCPIP_MAC_TxBaseAddrGet MACGetTxBuffSize TCPIP_MAC_TxBuffSizeGet MACPut TCPIP_MAC_Put MACPutArray TCPIP_MAC_ArrayPut MACPutHeader TCPIP_MAC_HeaderPut MACSetWritePtr TCPIP_MAC_WritePtrSet 5.8.3 Announce TCP/IP Stack Library 5.8.3.1 Introduction Announce TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the Announce TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description This module will facilitate device discovery on DHCP enabled networks by broadcasting a UDP message on port 30303 whenever the local IP address changes. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Announce TCP/IP Stack Library 5-3569 5.8.3.2 Release Notes MPLAB Harmony Version: v0.70b Announce TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.3.4 Using the Library This topic describes the basic architecture of the Announce TCPIP Stack Library and provides information and examples on how to use it. Interface Header File: tcpip_announce_config.h The interface to the Announce TCPIP Stack library is defined in the "tcpip_announce_config.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the Announce TCPIP Stack library should include "tcpip.h". Library File: The Announce TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCPIP Stack interacts with the framework. 5.8.3.4.1 Abstraction Model This library provides the API of the Announce TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Announce TCP/IP Stack Library 5-3570 Description Announce Software Abstraction Block Diagram Note: This diagram was not available at time of release and will included in a future release of MPLAB Harmony. 5.8.3.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Announce module. Library Interface Section Description Functions Routines for Configuring DHCP Data Types and Constants This section provides various definitions describing This API 5.8.3.5 Configuring the Library Macros Name Description ANNOUNCE_MAX_PAYLOAD Maximum size of a payload sent once ANNOUNCE_PORT The announce port Description The configuration of the Announce TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the Announce TCP/IP Stack Library. Based on the selections made, the Announce TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the AnnounceTCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.3.5.1 ANNOUNCE_MAX_PAYLOAD Macro C #define ANNOUNCE_MAX_PAYLOAD (512) Description Maximum size of a payload sent once 5.8.3.5.2 ANNOUNCE_PORT Macro C #define ANNOUNCE_PORT 30303 Description The announce port 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Announce TCP/IP Stack Library 5-3571 5.8.3.6 Building the Library This section list the files that are available in the \src of the Announce driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.3.7 Library Interface Data Types and Constants Name Description TCPIP_ANNOUNCE_MODULE_CONFIG Announce layer configuration/initialization Functions Name Description TCPIP_ANNOUNCE_DeInit This is function TCPIP_ANNOUNCE_DeInit. TCPIP_ANNOUNCE_Init manager TCPIP_ANNOUNCE_Send This is function TCPIP_ANNOUNCE_Send. TCPIP_ANNOUNCE_Task This is function TCPIP_ANNOUNCE_Task. TCPIP_ANNOUNCE_TaskPending This is function TCPIP_ANNOUNCE_TaskPending. Description This section describes the Application Programming Interface (API) functions of the Announce TCP/IP Stack. Refer to each section for a detailed description. 5.8.3.7.1 Functions 5.8.3.7.1.1 TCPIP_ANNOUNCE_DeInit Function C void TCPIP_ANNOUNCE_DeInit( const TCPIP_STACK_MODULE_CTRL* const stackData ); Description This is function TCPIP_ANNOUNCE_DeInit. 5.8.3.7.1.2 TCPIP_ANNOUNCE_Init Function C bool TCPIP_ANNOUNCE_Init( const TCPIP_STACK_MODULE_CTRL* const stackData, const TCPIP_ANNOUNCE_MODULE_CONFIG* announceData ); Description manager 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Announce TCP/IP Stack Library 5-3572 5.8.3.7.1.3 TCPIP_ANNOUNCE_Send Function C void TCPIP_ANNOUNCE_Send(); Description This is function TCPIP_ANNOUNCE_Send. 5.8.3.7.1.4 TCPIP_ANNOUNCE_Task Function C bool TCPIP_ANNOUNCE_Task( TCPIP_NET_IF * pNetIf ); Description This is function TCPIP_ANNOUNCE_Task. 5.8.3.7.1.5 TCPIP_ANNOUNCE_TaskPending Function C bool TCPIP_ANNOUNCE_TaskPending(); Description This is function TCPIP_ANNOUNCE_TaskPending. 5.8.3.7.2 Data Types and Constants 5.8.3.7.2.1 TCPIP_ANNOUNCE_MODULE_CONFIG Structure C typedef struct { } TCPIP_ANNOUNCE_MODULE_CONFIG; Description Announce layer configuration/initialization 5.8.3.8 Files Files Name Description tcpip_announce_config.h Announce configuration file tcpip_announce_manager.h Description 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Announce TCP/IP Stack Library 5-3573 5.8.3.8.1 tcpip_announce_config.h Announce Configuration file This file contains the Announce module configuration options Macros Name Description ANNOUNCE_MAX_PAYLOAD Maximum size of a payload sent once ANNOUNCE_PORT The announce port 5.8.3.8.2 tcpip_announce_manager.h TCPIP Announce Manager Header Functions Name Description TCPIP_ANNOUNCE_DeInit This is function TCPIP_ANNOUNCE_DeInit. TCPIP_ANNOUNCE_Init manager TCPIP_ANNOUNCE_Send This is function TCPIP_ANNOUNCE_Send. TCPIP_ANNOUNCE_Task This is function TCPIP_ANNOUNCE_Task. TCPIP_ANNOUNCE_TaskPending This is function TCPIP_ANNOUNCE_TaskPending. Structures Name Description TCPIP_ANNOUNCE_MODULE_CONFIG Announce layer configuration/initialization 5.8.4 ARP TCP/IP Stack Library 5.8.4.1 Introduction Address Resolution Protocol (ARP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the ARP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Address Resolution Protocol, or ARP, is a foundation layer of TCP/IP. It translates IP addresses to physical MAC addresses, or locates a gateway through which a machine may be located. TCP and UDP applications will not need to access ARP directly. The TCPOpen and UDPOpen functions will handle both ARP and DNS operations transparently. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3574 Responses to incoming ARP requests are processed automatically. Resolution of ARP requests follows a simple state machine, as indicated in the following diagram. 5.8.4.2 Release Notes MPLAB Harmony Version: v0.70b ARP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.4.4 Using the Library This topic describes the basic architecture of the ARP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: arp.h The interface to the arp TCP/IP Stack library is defined in the "arp.h" header file. This file is included by the "tcpip.h" file. Any C 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3575 language source (.c) file that uses the ARP TCP/IP Stack library should include "tcpip.h". Library File: The ARP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.4.4.1 Abstraction Model This library provides the API of the ARP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description ARP Software Abstraction Block Diagram This module provides software abstraction of the ARP module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. ARP Resolution Process 5.8.4.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the ARP module. Library Interface Section Description General Functions Functions used by the ARP library interface. Cache Manipulation Functions This section provides an interface to the internal data storage (cache) that the ARP module implements. Data Types and Constants Derived types and enumerations used by the ARP library interface. 5.8.4.4.3 How the Library Works The ARP module provides address resolution capabilities for the TCP/IP stack. The ARP module is an independent module that maintains its state across calls and updates its state machine. A data storage (cache) is maintained and updated internally for each interface existent in the system. The number of entries in each cache is configurable at initialization time. The ARP state machine can remove entries from the cache and can provide signals when a specific entry has been resolved or has timed out. The purging of the cache is done internally base on a time-out parameter that is dynamically configurable. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3576 The module provides a notification mechanism which simplifies the design of the ARP clients. The most important client of the ARP module is the IPv4 layer. 5.8.4.5 Configuring the Library Macros Name Description ARP_CACHE_ENTRIES_97J60 This is macro ARP_CACHE_ENTRIES_97J60. ARP_CACHE_ENTRIES_DEFAULT number of entries in the cache default number of entries per interface ARP_CACHE_ENTRIES_ENCJ60 This is macro ARP_CACHE_ENTRIES_ENCJ60. ARP_CACHE_ENTRIES_ENCJ600 This is macro ARP_CACHE_ENTRIES_ENCJ600. ARP_CACHE_ENTRIES_MRF24W This is macro ARP_CACHE_ENTRIES_MRF24W. ARP_CACHE_ENTRIES_PIC32INT specific interaces numbers ARP_CACHE_PENDING_ENTRY_TMO timeout for a pending to be solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been solved a solved entry moves to the solved entries timeout ARP_CACHE_PENDING_RETRY_TMO timeout for resending an ARP request for a pending entry In order to prevent the ARP flooding the standard recommends it to be greater than 1 sec. Of course, it should be less than ARP_CACHE_PENDING_ENTRY_TMO ARP_CACHE_PERMANENT_QUOTA max percentage of permanent entries in the cache note that since permanent entries cannot be removed they tend to degrade the efficiency of the cache look up ARP_CACHE_PURGE_QUANTA how many entries to delete, once the threshold is reached ARP_CACHE_PURGE_THRESHOLD default purge threshold, percentage once the number of resolved entries in the cache gets beyond the threshold some resolved entries will be purged ARP_CACHE_SOLVED_ENTRY_TMO timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again ARP_TASK_PROCESS_RATE ARP task processing rate, in seconds the ARP module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. Choose it so that the other ARP_CACHE_xxx_TMO are multiple of this Description The configuration of the TCP/IP Stack ARP is based on the file sys_config.h This header file contains the configuration selection for the TCP/IP Stack ARP. Based on the selections made, the TCP/IP Stack ARP will support or not support selected features. These configuration settings will apply to the single instance of the TCP/IP Stack ARP. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.4.5.1 ARP_CACHE_ENTRIES_97J60 Macro C #define ARP_CACHE_ENTRIES_97J60 5 Description This is macro ARP_CACHE_ENTRIES_97J60. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3577 5.8.4.5.2 ARP_CACHE_ENTRIES_DEFAULT Macro C #define ARP_CACHE_ENTRIES_DEFAULT 5 Description number of entries in the cache default number of entries per interface 5.8.4.5.3 ARP_CACHE_ENTRIES_ENCJ60 Macro C #define ARP_CACHE_ENTRIES_ENCJ60 5 Description This is macro ARP_CACHE_ENTRIES_ENCJ60. 5.8.4.5.4 ARP_CACHE_ENTRIES_ENCJ600 Macro C #define ARP_CACHE_ENTRIES_ENCJ600 5 Description This is macro ARP_CACHE_ENTRIES_ENCJ600. 5.8.4.5.5 ARP_CACHE_ENTRIES_MRF24W Macro C #define ARP_CACHE_ENTRIES_MRF24W 5 Description This is macro ARP_CACHE_ENTRIES_MRF24W. 5.8.4.5.6 ARP_CACHE_ENTRIES_PIC32INT Macro C #define ARP_CACHE_ENTRIES_PIC32INT 5 Description specific interaces numbers 5.8.4.5.7 ARP_CACHE_PENDING_ENTRY_TMO Macro C #define ARP_CACHE_PENDING_ENTRY_TMO (1 * 60) Description timeout for a pending to be solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been solved a solved entry moves to the solved entries timeout 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3578 5.8.4.5.8 ARP_CACHE_PENDING_RETRY_TMO Macro C #define ARP_CACHE_PENDING_RETRY_TMO (2) Description timeout for resending an ARP request for a pending entry In order to prevent the ARP flooding the standard recommends it to be greater than 1 sec. Of course, it should be less than ARP_CACHE_PENDING_ENTRY_TMO 5.8.4.5.9 ARP_CACHE_PERMANENT_QUOTA Macro C #define ARP_CACHE_PERMANENT_QUOTA 50 Description max percentage of permanent entries in the cache note that since permanent entries cannot be removed they tend to degrade the efficiency of the cache look up 5.8.4.5.10 ARP_CACHE_PURGE_QUANTA Macro C #define ARP_CACHE_PURGE_QUANTA 3 Description how many entries to delete, once the threshold is reached 5.8.4.5.11 ARP_CACHE_PURGE_THRESHOLD Macro C #define ARP_CACHE_PURGE_THRESHOLD 75 Description default purge threshold, percentage once the number of resolved entries in the cache gets beyond the threshold some resolved entries will be purged 5.8.4.5.12 ARP_CACHE_SOLVED_ENTRY_TMO Macro C #define ARP_CACHE_SOLVED_ENTRY_TMO (20 * 60) Description timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again 5.8.4.5.13 ARP_TASK_PROCESS_RATE Macro C #define ARP_TASK_PROCESS_RATE (2) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3579 Description ARP task processing rate, in seconds the ARP module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. Choose it so that the other ARP_CACHE_xxx_TMO are multiple of this 5.8.4.6 Building the Library This section list the files that are available in the \src of the ARP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • arp.c 5.8.4.7 Library Interface Data Types and Constants Name Description TCPIP_ARP_ENTRY_QUERY ARP Entry Query TCPIP_ARP_ENTRY_TYPE Type of ARP entry TCPIP_ARP_EVENT_HANDLER Notification handler that can be called when a specific entry is resolved. TCPIP_ARP_EVENT_TYPE Events reported by ARP TCPIP_ARP_HANDLE ARP Handle TCPIP_ARP_OPERATION_TYPE Type of ARP operation TCPIP_ARP_RESULT ARP Results (success and failure codes) ARP_MODULE_CONFIG This is type ARP_MODULE_CONFIG. arp_app_callbacks TCPIP_STACK_USE_ZEROCONF_LINK_LOCAL API specific Definitions Cache Manipulation Functions Name Description TCPIP_ARP_CacheEntriesNoGet Used to retrieve the number of entereies for a specific interface TCPIP_ARP_CacheThresholdSet Sets the cache threshold for the specified interface in % TCPIP_ARP_EntryQuery Querries an ARP cache entry using the index of the cache line. TCPIP_ARP_EntryRemoveAll Removes all the mapping belonging to an interface. General Functions Name Description TCPIP_ARP_CallbacksDeregister De-Registering callbacks with ARP module that are registered previously. TCPIP_ARP_CallbacksRegister Registering callback with ARP module to get notified about certian events. TCPIP_ARP_Deinitialize Deinitializes the ARP module. TCPIP_ARP_EntryGet gets the current mapping for an IP address TCPIP_ARP_EntryRemove removes the mapping of an address, even a permanent one TCPIP_ARP_EntryRemoveNet Removes all the entries belonging to a network interface. TCPIP_ARP_HandlerDeRegister deregister the event handler TCPIP_ARP_HandlerRegister Register an ARP resolve handler TCPIP_ARP_Initialize Initializes the ARP module. TCPIP_ARP_IsResolved Determines if an ARP request has been resolved yet. TCPIP_ARP_Probe Transmits an ARP probe to resolve an IP address. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3580 TCPIP_ARP_Resolve Transmits an ARP request to resolve an IP address. TCPIP_ARP_Task Performs ARP tasks from within TCPIP stack tasks. TCPIP_ARP_TaskIsPending Returns true if an ARP task is pending, false otherwise. TCPIP_ARP_EntrySet Adds an ARP cache entry for the specified interface. TCPIP_ARP_Process Processes an incoming ARP packet. Description This section describes the Application Programming Interface (API) functions of the ARP TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.4.7.1 General Functions 5.8.4.7.1.1 TCPIP_ARP_CallbacksDeregister Function C bool TCPIP_ARP_CallbacksDeregister( int8_t id ); Description This function allows end user-application to de-register with callbacks, which were registered previously. This is called by user-application, when its no longer interested in notifications from ARP-Module. This allows the other application to get registered with ARP-module. Preconditions None Parameters Parameters Description reg_id Registration-id returned in TCPIP_ARP_CallbacksRegister call Returns true - On success false - Failure to indicate invalid reg_id 5.8.4.7.1.2 TCPIP_ARP_CallbacksRegister Function C int8_t TCPIP_ARP_CallbacksRegister( struct arp_app_callbacks * app ); Description This function allows end user application to register with callbacks, which will be called by ARP module to give notification to user-application about events occurred at ARP layer. For ex: when a ARP-packet is received, which is conflicting with our own pair of addresses (MAC-Address and IP-address). This is an extension for zeroconf protocol implementation (ZeroconfLL.c) Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3581 Parameters Parameters Description app ARP-Application callbacks structure supplied by user-application Returns id > 0 - Returns non-negative value that represents the id of registration The same id needs to be used in de-registration -1 - When registered applications exceed MAX_REG_APPS and there is no free slot for registration 5.8.4.7.1.3 TCPIP_ARP_Deinitialize Function C void TCPIP_ARP_Deinitialize( const TCPIP_STACK_MODULE_CTRL* const stackData ); Description Deinitializes the ARP module. Preconditions None. Parameters Parameters Description stackCtrl stack initialization parameters, used by TCPIP_ARP_Initialize to initialize the ARP module. Returns None. Remarks None. 5.8.4.7.1.4 TCPIP_ARP_EntryGet Function C TCPIP_ARP_RESULT TCPIP_ARP_EntryGet( TCPIP_NET_HANDLE hNet, IPV4_ADDR* ipAdd, TCPIP_MAC_ADDR* pHwAdd, bool probe ); Description If probe == false The function behaves identical to TCPIP_ARP_IsResolved(): If the corresponding MAC address exists in the cache it is copied to the user supplied pHwAdd If probe == true The function behaves identical to TCPIP_ARP_Resolve(): • If the corresponding MAC address does not exist in the cache this function transmits and ARP request. Upon the address resolution it calls the registered handler (if available) with the supplied notification parameter (if != 0) • If the hardware address exists, the result is written to pHwAdd 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3582 Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface to use ipAdd The ip address to get entries from pHwAdd pointer to store the hardware address probe boolean to specify if ARP probing is initiated or not Returns ARP_RES_ENTRY_SOLVED - if the required entry is already solved ARP_RES_ENTRY_QUEUED - if the required entry was already queued ARP_RES_ENTRY_NEW - if the operation succeeded and a new entry was added (and queued for resolving) ARP_RES_CACHE_FULL - if new entry could not be inserted, the cache was full ARP_RES_BAD_ADDRESS - bad address specified ARP_RES_NO_INTERFACE - no such interface Remarks similar to TCPIP_ARP_Resolve() + TCPIP_ARP_IsResolved() It avoids a double hash search when the mapping exists. Example None 5.8.4.7.1.5 TCPIP_ARP_EntryRemove Function C TCPIP_ARP_RESULT TCPIP_ARP_EntryRemove( TCPIP_NET_HANDLE hNet, IPV4_ADDR* ipAdd ); Description None Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface to use ipAdd ip Address to remove entries for Returns TCPIP_ARP_RESULT On Success - On Failure - ARP_RES_NO_ENTRY (if no such mapping exists) Remarks None Example None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3583 5.8.4.7.1.6 TCPIP_ARP_EntryRemoveNet Function C TCPIP_ARP_RESULT TCPIP_ARP_EntryRemoveNet( TCPIP_NET_HANDLE hNet, IPV4_ADDR* ipAdd, IPV4_ADDR* mask, TCPIP_ARP_ENTRY_TYPE type ); Description if(entry->type == type and entry->ipAdd & mask == ipAdd & mask) then remove entry Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface handle to use ipAdd ip address mask ip address of mask type type of entries to remove: valid types ARP_ENTRY_TYPE_PERMANENT ARP_ENTRY_TYPE_COMPLETE ARP_ENTRY_TYPE_INCOMPLETE ARP_ENTRY_TYPE_ANY Returns ARP_RES_OK Remarks None Example None 5.8.4.7.1.7 TCPIP_ARP_HandlerDeRegister Function C bool TCPIP_ARP_HandlerDeRegister( TCPIP_ARP_HANDLE hArp ); Description None Preconditions ARP module should have been initialized Parameters Parameters Description hArp ARP Handle Returns bool On Success - true On Failure - false (If no such handler registered) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3584 Remarks None Example None 5.8.4.7.1.8 TCPIP_ARP_HandlerRegister Function C TCPIP_ARP_HANDLE TCPIP_ARP_HandlerRegister( TCPIP_NET_HANDLE hNet, TCPIP_ARP_EVENT_HANDLER handler, const void* hParam ); Description NONE Preconditions ARP module should have been initialized Parameters Parameters Description hNet Specifies interface to register on. Use hNet == 0 to register on all interfaces available. handler Handler to be called for event. hParam The hParam is passed by the client and will be used by the ARP when the notification is made. It is used for per-thread content or if more modules, for example, share the same handler and need a way to differentiate the callback. Returns TCPIP_ARP_HANDLE On Success - Returns a valid handle On Failure - null handle Remarks NONE Example None 5.8.4.7.1.9 TCPIP_ARP_Initialize Function C bool TCPIP_ARP_Initialize( const TCPIP_STACK_MODULE_CTRL* const stackData, const ARP_MODULE_CONFIG* arpData ); Description Initializes the ARP module. Calls can be done with the request of not tearing down the ARP cache This helps for ifup/ifdown sequences. Of course, if this is the case the memory allocated for the ARP cache has to be from a persistent heap. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3585 Parameters Parameters Description stackCtrl stack initialization parameters arpData ARP specific initialization parameters Returns true if initialization succeded, false otherwise Remarks The request to maintain old ARP cache info (deleteOld field from the ARP_MODULE_CONFIG initialization data) is not implemented for stack nit/deinit sequences. To maintain the data after the stack is completely de-initialized would need a persistent heap that's not yet implemented. The selection cannot be changed by ifup since this operation does not carry ARP configuration parameters (arpDate == 0). 5.8.4.7.1.10 TCPIP_ARP_IsResolved Function C bool TCPIP_ARP_IsResolved( TCPIP_NET_HANDLE hNet, IPV4_ADDR* IPAddr, TCPIP_MAC_ADDR* MACAddr ); Description This function checks if an ARP request has been resolved yet, and if so, stores the resolved MAC address in the pointer provided. Preconditions ARP module should have been initialized Parameters Parameters Description hNet interface to use IPAddr The IP address to be resolved. This must match the IP address provided to the TCPIP_ARP_Resolve() function call. MACAddr A buffer to store the corresponding MAC address retrieved from the ARP query. Return Values Return Values Description true The IP address has been resolved and MACAddr MAC address field indicates the response. false The IP address is not yet resolved. Try calling TCPIP_ARP_IsResolved() again at a later time. If you don't get a response after a application specific timeout period, you may want to call TCPIP_ARP_Resolve() again to transmit another ARP query (in case if the original query or response was lost on the network). If you never receive an ARP response, this may indicate that the IP address isn't in use. 5.8.4.7.1.11 TCPIP_ARP_Probe Function C TCPIP_ARP_RESULT TCPIP_ARP_Probe( TCPIP_NET_HANDLE hNet, IPV4_ADDR* IPAddr, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3586 IPV4_ADDR* srcAddr, TCPIP_ARP_OPERATION_TYPE opType ); Description This function transmits and ARP probe to determine the hardware address of a given IP address. The packet will use the type of operation and the source address specified as parameters. Preconditions ARP module should have been initialized Parameters Parameters Description hNet interface to use IPAddr The IP address to be resolved. The address must be specified in network byte order (big endian). srcAddr The source address to be used in the ARP packet opTYpe Operation code to be set in the outgoing ARP packet Returns ARP_RES_ENTRY_SOLVED - if the required entry is already solved ARP_RES_ENTRY_QUEUED - if the required entry was already queued ARP_RES_ENTRY_NEW - if the operation succeeded and a new entry was added (and queued for resolving) ARP_RES_CACHE_FULL - if new entry could not be inserted, the cache was full ARP_RES_BAD_ADDRESS - bad address specified ARP_RES_NO_INTERFACE - no such interface Remarks This function is a more advanced version of TCPIP_ARP_Resolve. It allows the caller to specify the operation type and the source address of the outgoiong AARP packet. No check is done for IPAddr to be valid. To retrieve the ARP query result, call the TCPIP_ARP_IsResolved() function. 5.8.4.7.1.12 TCPIP_ARP_Resolve Function C TCPIP_ARP_RESULT TCPIP_ARP_Resolve( TCPIP_NET_HANDLE hNet, IPV4_ADDR* IPAddr ); Description This function transmits and ARP request to determine the hardware address of a given IP address. Upon the address resolution it calls the registered handler (if available) with the supplied notification parameter (if != 0) Preconditions ARP module should have been initialized Parameters Parameters Description hNet interface to use IPAddr The IP address to be resolved. The address must be specified in network byte order (big endian). 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3587 Returns An element from the TCPIP_ARP_RESULT enumeration. ARP_RES_ENTRY_SOLVED - if the required entry is already solved ARP_RES_ENTRY_QUEUED - if the required entry was already queued ARP_RES_ENTRY_NEW - if the operation succeeded and a new entry was added (and queued for resolving) ARP_RES_CACHE_FULL - if new entry could not be inserted, the cache was full ARP_RES_BAD_ADDRESS - bad address specified ARP_RES_NO_INTERFACE - no such interface Remarks To retrieve the ARP query result, call the TCPIP_ARP_IsResolved() function. 5.8.4.7.1.13 TCPIP_ARP_Task Function C void TCPIP_ARP_Task(); Description Performs ARP tasks from within TCPIP stack tasks. Preconditions None. Returns None. Remarks None. 5.8.4.7.1.14 TCPIP_ARP_TaskIsPending Function C bool TCPIP_ARP_TaskIsPending(); Description Returns true if an ARP task is pending, false otherwise. Preconditions None. Returns true - ARP task is pending false - ARP task is not pending 5.8.4.7.1.15 TCPIP_ARP_EntrySet Function C TCPIP_ARP_RESULT TCPIP_ARP_EntrySet( TCPIP_NET_HANDLE hNet, IPV4_ADDR* ipAdd, TCPIP_MAC_ADDR* hwAdd, bool perm ); Description Can be added as permanent. Not subject to timeouts. If cache is full, an entry will be deleted to make room. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3588 Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface to use ipAdd The ip address hwAdd perm Returns On Success - ARP_RES_OK/ARP_RES_ENTRY_EXIST ON Failure - An Error (for example, cache is full with permanent entries that cannot be purged or the permanent quota exceeded) Remarks None Example None 5.8.4.7.1.16 TCPIP_ARP_Process Function C TCPIP_ARP_RESULT TCPIP_ARP_Process( TCPIP_NET_IF* pIf, TCPIP_MAC_PACKET* pPkt ); Description Retrieves an ARP packet from the MAC buffer and determines if it is a response to our request (in which case the ARP is resolved) or if it is a request requiring our response (in which case we transmit one.) Preconditions ARP packet is ready in the MAC buffer. Return Values Return Values Description ARP_RES_OK processing OK. ARP_RES_error some error occurred 5.8.4.7.2 Cache Manipulation Functions 5.8.4.7.2.1 TCPIP_ARP_CacheEntriesNoGet Function C size_t TCPIP_ARP_CacheEntriesNoGet( TCPIP_NET_HANDLE hNet, TCPIP_ARP_ENTRY_TYPE type ); Description None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3589 Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface to use type Type of ARP entry Returns The number of entries of the specified type per interface Remarks None Example None 5.8.4.7.2.2 TCPIP_ARP_CacheThresholdSet Function C TCPIP_ARP_RESULT TCPIP_ARP_CacheThresholdSet( TCPIP_NET_HANDLE hNet, int purgeThres, int purgeEntries ); Description once the number of entries in the cache is > than the threshold a number of purgeEntries (usually one) will be discarded Preconditions ARP module should have been initialized Parameters Parameters Description hNet Interface handle to use purgeThres Threshold to start cache purging purgeEntries Number of entries to purge Returns ARP_RES_OK Remarks None Example None 5.8.4.7.2.3 TCPIP_ARP_EntryQuery Function C TCPIP_ARP_RESULT TCPIP_ARP_EntryQuery( TCPIP_NET_HANDLE hNet, size_t index, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3590 TCPIP_ARP_ENTRY_QUERY* pArpQuery ); Description None Preconditions ARP module should have been initialized The index has to be a valid one i.e. < then TCPIP_ARP_CacheEntriesNoGet() populates the supplied query routine if not NULL Parameters Parameters Description hNet Interface handle to use index Index to cache pArpQuery entry type, ip address, hardware address Returns On Success - ARP_RES_OK On Failure - ARP_RES_BAD_INDEX (if index is out of range) use it for displaying the cache contents Remarks None Example None 5.8.4.7.2.4 TCPIP_ARP_EntryRemoveAll Function C TCPIP_ARP_RESULT TCPIP_ARP_EntryRemoveAll( TCPIP_NET_HANDLE hNet ); Description None Preconditions ARP module should have been initialized Parameters Parameters Description hNet network interface handle Returns ARP_RES_OK Remarks None Example None 5.8.4.7.3 Data Types and Constants 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3591 5.8.4.7.3.1 TCPIP_ARP_ENTRY_QUERY Structure C typedef struct { TCPIP_ARP_ENTRY_TYPE entryType; IPV4_ADDR entryIpAdd; TCPIP_MAC_ADDR entryHwAdd; } TCPIP_ARP_ENTRY_QUERY; Description Structure: TCPIP_ARP_ENTRY_QUERY None Members Members Description TCPIP_ARP_ENTRY_TYPE entryType; what entry type IPV4_ADDR entryIpAdd; the entry IP address TCPIP_MAC_ADDR entryHwAdd; the entry hardware address 5.8.4.7.3.2 TCPIP_ARP_ENTRY_TYPE Enumeration C typedef enum { ARP_ENTRY_TYPE_INVALID, ARP_ENTRY_TYPE_PERMANENT, ARP_ENTRY_TYPE_COMPLETE, ARP_ENTRY_TYPE_INCOMPLETE, ARP_ENTRY_TYPE_ANY, ARP_ENTRY_TYPE_TOTAL } TCPIP_ARP_ENTRY_TYPE; Description Enumeration: TCPIP_ARP_ENTRY_TYPE None Members Members Description ARP_ENTRY_TYPE_INVALID empty entry ARP_ENTRY_TYPE_PERMANENT entry valid and permanent ARP_ENTRY_TYPE_COMPLETE entry valid ARP_ENTRY_TYPE_INCOMPLETE entry not resolved yet ARP_ENTRY_TYPE_ANY any busy entry (PERMANENT|COMPLETE|INCOMPLETE) ARP_ENTRY_TYPE_TOTAL total entries - the number of entries the cache can store Remarks None 5.8.4.7.3.3 TCPIP_ARP_EVENT_HANDLER Type C typedef void (* TCPIP_ARP_EVENT_HANDLER)(TCPIP_NET_HANDLE hNet, const IPV4_ADDR* ipAdd, const TCPIP_MAC_ADDR* MACAddr, TCPIP_ARP_EVENT_TYPE evType, const void* param); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3592 Description Type: TCPIP_ARP_EVENT_HANDLER None Remarks The param member significance is module dependent. It can be an IP address, pointer to some other structure, etc. The handler is called when an event of some sort occurs for a particular IP address entry. If pNetIf == 0 then the notification is called for events on any interface 5.8.4.7.3.4 TCPIP_ARP_EVENT_TYPE Enumeration C typedef enum { ARP_EVENT_SOLVED = 0x01, ARP_EVENT_UPDATED = 0x02, ARP_EVENT_PERM_UPDATE = 0x04, ARP_EVENT_TMO = -1 } TCPIP_ARP_EVENT_TYPE; Description Enumeration: TCPIP_ARP_EVENT_TYPE None Members Members Description ARP_EVENT_SOLVED = 0x01 a queued cache entry was solved; ARP_EVENT_UPDATED = 0x02 an existent cache entry was updated ARP_EVENT_PERM_UPDATE = 0x04 an update for an permanent entry was received however the permanent entry was not updated ARP_EVENT_TMO = -1 an entry could not be solved and a tmo occurred Remarks Possibly multiple events can be set, where it makes sense. 5.8.4.7.3.5 TCPIP_ARP_HANDLE Type C typedef const void* TCPIP_ARP_HANDLE; Description Type: TCPIP_ARP_HANDLE A handle that a client can use. Remarks This handle can be used by the client after the event handler has been registered. 5.8.4.7.3.6 TCPIP_ARP_OPERATION_TYPE Enumeration C typedef enum { ARP_OPERATION_REQ = 1, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3593 ARP_OPERATION_RESP = 2, ARP_OPERATION_MASK = 0x000f, ARP_OPERATION_CONFIGURE = 0x1000 } TCPIP_ARP_OPERATION_TYPE; Description Enumeration: TCPIP_ARP_OPERATION_TYPE Operation to be performed by an ARP probe Members Members Description ARP_OPERATION_REQ = 1 ARP request ARP_OPERATION_RESP = 2 ARP respone ARP_OPERATION_MASK = 0x000f extract ARP operation ARP_OPERATION_CONFIGURE = 0x1000 stack configuration ARP packet Remarks Used for low level functionality, TCPIP_ARP_Probe 5.8.4.7.3.7 TCPIP_ARP_RESULT Enumeration C typedef enum { ARP_RES_OK = 0, ARP_RES_ENTRY_NEW, ARP_RES_ENTRY_SOLVED, ARP_RES_ENTRY_QUEUED, ARP_RES_ENTRY_EXIST, ARP_RES_PERM_QUOTA_EXCEED, ARP_RES_NO_ENTRY = -1, ARP_RES_CACHE_FULL = -2, ARP_RES_TX_FAILED = -3, ARP_RES_BAD_INDEX = -4, ARP_RES_BAD_ADDRESS = -5, ARP_RES_NO_INTERFACE = -6, ARP_RES_BAD_TYPE = -7, ARP_RES_CONFIGURE_ERR = -8 } TCPIP_ARP_RESULT; Description Enumeration: TCPIP_ARP_RESULT Various Definitions for Success and Failure Codes Members Members Description ARP_RES_OK = 0 operation succeeded ARP_RES_ENTRY_NEW operation succeeded and a new entry was added ARP_RES_ENTRY_SOLVED the required entry is already solved ARP_RES_ENTRY_QUEUED the required entry was already queued ARP_RES_ENTRY_EXIST the required entry was already cached ARP_RES_PERM_QUOTA_EXCEED info: the quota of permanent entries was exceeded ARP_RES_NO_ENTRY = -1 no such entry exists ARP_RES_CACHE_FULL = -2 the cache is full and no entry could be removed to make room ARP_RES_TX_FAILED = -3 failed to transmit an ARP message 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3594 ARP_RES_BAD_INDEX = -4 bad query index ARP_RES_BAD_ADDRESS = -5 bad IP address specified ARP_RES_NO_INTERFACE = -6 no such interface exists ARP_RES_BAD_TYPE = -7 no such type is valid/exists ARP_RES_CONFIGURE_ERR = -8 interface is configuring now, no ARP probes Remarks None 5.8.4.7.3.8 ARP_MODULE_CONFIG Structure C typedef struct { size_t cacheEntries; bool deleteOld; int entrySolvedTmo; int entryPendingTmo; int entryRetryTmo; int permQuota; int purgeThres; int purgeQuanta; } ARP_MODULE_CONFIG; Description This is type ARP_MODULE_CONFIG. Members Members Description size_t cacheEntries; cache entries for this interface bool deleteOld; delete old cache if still in place, else don't re-initialize it int entrySolvedTmo; solved entry removed after this tmo if not referenced - seconds int entryPendingTmo; timeout for a pending to be solved entry in the cache, in seconds int entryRetryTmo; timeout for resending an ARP request for a pending entry - seconds 1 sec < tmo < entryPendingTmo int permQuota; max percentage of permanent entries allowed in the cache - int purgeThres; purge threshold - int purgeQuanta; no of entries to delete once the threshold is reached 5.8.4.7.3.9 arp_app_callbacks Structure C struct arp_app_callbacks { bool used; void (* TCPIP_ARP_PacketNotify)(TCPIP_NET_IF* pNetIf ,uint32_t SenderIPAddr ,uint32_t TargetIPAddr ,TCPIP_MAC_ADDR* SenderMACAddr ,TCPIP_MAC_ADDR* TargetMACAddr ,uint8_t op_req); }; Description TCPIP_STACK_USE_ZEROCONF_LINK_LOCAL API specific Definitions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3595 5.8.4.8 Files Files Name Description arp.h This is file arp.h. arp_config.h ARP configuration file arp_manager.h Stack internal definitions for ARP module Description 5.8.4.8.1 arp.h This is file arp.h. Enumerations Name Description TCPIP_ARP_ENTRY_TYPE Type of ARP entry TCPIP_ARP_EVENT_TYPE Events reported by ARP TCPIP_ARP_OPERATION_TYPE Type of ARP operation TCPIP_ARP_RESULT ARP Results (success and failure codes) Functions Name Description TCPIP_ARP_CacheEntriesNoGet Used to retrieve the number of entereies for a specific interface TCPIP_ARP_CacheThresholdSet Sets the cache threshold for the specified interface in % TCPIP_ARP_EntryGet gets the current mapping for an IP address TCPIP_ARP_EntryQuery Querries an ARP cache entry using the index of the cache line. TCPIP_ARP_EntryRemove removes the mapping of an address, even a permanent one TCPIP_ARP_EntryRemoveAll Removes all the mapping belonging to an interface. TCPIP_ARP_EntryRemoveNet Removes all the entries belonging to a network interface. TCPIP_ARP_EntrySet Adds an ARP cache entry for the specified interface. TCPIP_ARP_HandlerDeRegister deregister the event handler TCPIP_ARP_HandlerRegister Register an ARP resolve handler TCPIP_ARP_IsResolved Determines if an ARP request has been resolved yet. TCPIP_ARP_Probe Transmits an ARP probe to resolve an IP address. TCPIP_ARP_Resolve Transmits an ARP request to resolve an IP address. Structures Name Description ARP_MODULE_CONFIG This is type ARP_MODULE_CONFIG. TCPIP_ARP_ENTRY_QUERY ARP Entry Query Types Name Description TCPIP_ARP_EVENT_HANDLER Notification handler that can be called when a specific entry is resolved. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3596 TCPIP_ARP_HANDLE ARP Handle 5.8.4.8.2 arp_config.h Address Resolution Protocol (ARP) Configuration file This file contains the ARP module configuration options Macros Name Description ARP_CACHE_ENTRIES_97J60 This is macro ARP_CACHE_ENTRIES_97J60. ARP_CACHE_ENTRIES_DEFAULT number of entries in the cache default number of entries per interface ARP_CACHE_ENTRIES_ENCJ60 This is macro ARP_CACHE_ENTRIES_ENCJ60. ARP_CACHE_ENTRIES_ENCJ600 This is macro ARP_CACHE_ENTRIES_ENCJ600. ARP_CACHE_ENTRIES_MRF24W This is macro ARP_CACHE_ENTRIES_MRF24W. ARP_CACHE_ENTRIES_PIC32INT specific interaces numbers ARP_CACHE_PENDING_ENTRY_TMO timeout for a pending to be solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been solved a solved entry moves to the solved entries timeout ARP_CACHE_PENDING_RETRY_TMO timeout for resending an ARP request for a pending entry In order to prevent the ARP flooding the standard recommends it to be greater than 1 sec. Of course, it should be less than ARP_CACHE_PENDING_ENTRY_TMO ARP_CACHE_PERMANENT_QUOTA max percentage of permanent entries in the cache note that since permanent entries cannot be removed they tend to degrade the efficiency of the cache look up ARP_CACHE_PURGE_QUANTA how many entries to delete, once the threshold is reached ARP_CACHE_PURGE_THRESHOLD default purge threshold, percentage once the number of resolved entries in the cache gets beyond the threshold some resolved entries will be purged ARP_CACHE_SOLVED_ENTRY_TMO timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again ARP_TASK_PROCESS_RATE ARP task processing rate, in seconds the ARP module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. Choose it so that the other ARP_CACHE_xxx_TMO are multiple of this 5.8.4.8.3 arp_manager.h ARP module manager header This file contains the stack internal API for the ARP module Functions Name Description TCPIP_ARP_CallbacksDeregister De-Registering callbacks with ARP module that are registered previously. TCPIP_ARP_CallbacksRegister Registering callback with ARP module to get notified about certian events. TCPIP_ARP_Deinitialize Deinitializes the ARP module. TCPIP_ARP_Initialize Initializes the ARP module. TCPIP_ARP_Process Processes an incoming ARP packet. TCPIP_ARP_Task Performs ARP tasks from within TCPIP stack tasks. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ARP TCP/IP Stack Library 5-3597 TCPIP_ARP_TaskIsPending Returns true if an ARP task is pending, false otherwise. Structures Name Description arp_app_callbacks TCPIP_STACK_USE_ZEROCONF_LINK_LOCAL API specific Definitions 5.8.5 Berkeley TCP/IP Stack Library 5.8.5.1 Introduction Berkeley TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the berkeley TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Berkeley Socket Distribution (BSD) APIs provide a BSD wrapper to the native Microchip TCP/IP Stack APIs. Using this interface, programmers familiar with BSD sockets can quickly develop applications using Microchip's TCP/IP Stack. The illustration below shows a typical interaction for a TCP server or client using the Berkeley socket APIs. 5.8.5.2 Release Notes MPLAB Harmony Version: v0.70b Berkeley TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3598 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.5.4 Using the Library This topic describes the basic architecture of the Berkeley TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: berkeley_api.h The interface to the Berkeley TCP/IP Stack library is defined in the "berkeley_api.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the berkeley TCP/IP Stack library should include "tcpip.h". Library File: The Berkeley TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.5.4.1 Abstraction Model This library provides the API of the Berkeley TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Berkeley Software Abstraction Block Diagram The illustration below shows a typical interaction for a TCP server or client using the Berkeley socket APIs. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3599 5.8.5.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Berkeley module. Library Interface Section Description Functions Routines for Configuring DHCP Data Types and Constants This section provides various definitions describing This API 5.8.5.5 Configuring the Library Macros Name Description MAX_BSD_CLIENT_CONNECTIONS Berkeley API client Sockets simultaneous supported connections. MAX_BSD_SERVER_CONNECTIONS Berkeley API server Sockets simultaneous supported connections. Description The configuration of the Berkeley TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the Berkeley TCP/IP Stack. Based on the selections made, the Berkeley TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the Berkeley TCP/IP Stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3600 This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.5.5.1 MAX_BSD_CLIENT_CONNECTIONS Macro C #define MAX_BSD_CLIENT_CONNECTIONS (2) Description Berkeley API client Sockets simultaneous supported connections. 5.8.5.5.2 MAX_BSD_SERVER_CONNECTIONS Macro C #define MAX_BSD_SERVER_CONNECTIONS (2) Description Berkeley API server Sockets simultaneous supported connections. 5.8.5.6 Building the Library This section list the files that are available in the \src of the Berkeley driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.5.7 Library Interface Data Types and Constants Name Description AF_INET Internet Address Family - UDP, TCP, etc. INADDR_ANY IP address for server binding. INVALID_TCP_PORT Invalid TCP port IP_ADDR_ANY IP Address for server binding IPPROTO_IP Indicates IP pseudo-protocol. IPPROTO_TCP Indicates TCP for the internet address family. IPPROTO_UDP Indicates UDP for the internet address family. SOCK_DGRAM Connectionless datagram socket. Use UDP for the internet address family. SOCK_STREAM Connection based byte streams. Use TCP for the internet address family. SOCKET_CNXN_IN_PROGRESS Socket connection state. SOCKET_DISCONNECTED Socket disconnected SOCKET_ERROR Socket error BERKELEY_MODULE_CONFIG Berkeley API module configuration structure SOCKADDR generic address structure for all address families SOCKADDR_IN In the Internet address family SOCKET Socket descriptor in_addr in_addr structure 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3601 sockaddr generic address structure for all address families sockaddr_in In the Internet address family Functions Name Description accept This function accepts connection requests queued for a listening socket. bind This function assigns a name to the socket descriptor. closesocket The closesocket function closes an existing socket. connect This function connects to the peer communications end point. gethostname Returns the standard host name for the system. listen The listen function sets the specified socket in a listen mode recv The recv() function is used to receive incoming data that has been queued for a socket. recvfrom The recvfrom() function is used to receive incoming data that has been queued for a socket. send The send function is used to send outgoing data on an already connected socket. sendto This function used to send the data for both connection oriented and connection-less sockets. socket This function creates a new Berkeley socket. Description This section describes the Application Programming Interface (API) functions of the Berkeley TCP/IP Stack. Refer to each section for a detailed description. 5.8.5.7.1 Functions 5.8.5.7.1.1 accept Function C SOCKET accept( SOCKET s, struct sockaddr* addr, int* addrlen ); Description The accept function is used to accept connection requests queued for a listening socket. If a connection request is pending, accept removes the request from the queue, and a new socket is created for the connection. The original listening socket remains open and continues to queue new connection requests. The socket must be a SOCK_STREAM type socket. Preconditions listen function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. must be bound to a local name and in listening mode. addr Optional pointer to a buffer that receives the address of the connecting entity. addrlen Optional pointer to an integer that contains the length of the address addr 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3602 Returns If the accept function succeeds, it returns a non-negative integer that is a descriptor for the accepted socket. Otherwise, the value SOCKET_ERROR is returned. (and errno set accordingly). Remarks None. 5.8.5.7.1.2 bind Function C int bind( SOCKET s, const struct sockaddr* name, int namelen ); Description The bind function assigns a name to an unnamed socket. The name represents the local address of the communication endpoint. For sockets of type SOCK_STREAM, the name of the remote endpoint is assigned when a connect or accept function is executed. Preconditions socket function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. name pointer to the sockaddr structure containing the local address of the socket. namelen length of the sockaddr structure. Returns If bind is successful, a value of 0 is returned. A return value of SOCKET_ERROR indicates an error. (and errno set accordingly). Remarks None. 5.8.5.7.1.3 closesocket Function C int closesocket( SOCKET s ); Description The closesocket function closes an existing socket. This function releases the socket descriptor s. Any data buffered at the socket is discarded. If the socket s is no longer needed, closesocket() must be called in order to release all resources associated with s. Preconditions None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3603 Parameters Parameters Description s Socket descriptor returned from a previous call to socket Returns If closesocket is successful, a value of 0 is returned. A return value of SOCKET_ERROR (-1) indicates an error. (and errno set accordingly). Remarks None. 5.8.5.7.1.4 connect Function C int connect( SOCKET s, struct sockaddr* name, int namelen ); Description The connect function assigns the address of the peer communications endpoint. For stream sockets, connection is established between the endpoints. For datagram sockets, an address filter is established between the endpoints until changed with another connect() function. Preconditions socket function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. name pointer to the sockaddr structure containing the peer address and port number. namelen length of the sockaddr structure. Returns If the connect() function succeeds, it returns 0. Otherwise, the value SOCKET_ERROR is returned to indicate an error condition (and errno set accordingly). For stream based socket, if the connection is not established yet, connect returns SOCKET_ERROR and errno = EINPROGRESS. Remarks None. 5.8.5.7.1.5 gethostname Function C int gethostname( char* name, int namelen ); Description This function returns the standard host name of the system which is calling this function. The returned name is null-terminated. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3604 Preconditions None. Parameters Parameters Description name Pointer to a buffer that receives the local host name. namelen size of the name array. Returns Success will return a value of 0. If name is too short to hold the host name or any other error occurs, SOCKET_ERROR (-1) will be returned (and errno set accordingly). On error, *name will be unmodified and no null terminator will be generated. Remarks The function returns the host name as set on the default network interface. 5.8.5.7.1.6 listen Function C int listen( SOCKET s, int backlog ); Description This function sets the specified socket in a listen mode. Calling the listen function indicates that the application is ready to accept connection requests arriving at a socket of type SOCK_STREAM. The connection request is queued (if possible) until accepted with an accept function. The backlog parameter defines the maximum number of pending connections that may be queued. Preconditions bind() must have been called on the s socket first. Parameters Parameters Description s Socket identifier returned from a prior socket() call. backlog Maximum number of connection requests that can be queued. Note that each backlog requires a TCP socket to be allocated. Returns Returns 0 on success, else return SOCKET_ERROR. (and errno set accordingly). Remarks None 5.8.5.7.1.7 recv Function C int recv( SOCKET s, char* buf, int len, int flags ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3605 Description The recv() function is used to receive incoming data that has been queued for a socket. This function can be used with both datagram and stream socket. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of SOCK_DGRAM type sockets. For SOCK_STREAM types, the data is buffered internally so the application can retreive all data by multiple calls of recvfrom. Preconditions connect function should be called for TCP and UDP sockets. Server side, accept function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. buf application data receive buffer. len buffer length in bytes. flags no significance in this implementation Returns If recv is successful, the number of bytes copied to application buffer buf is returned. A return value of SOCKET_ERROR (-1) indicates an error condition (and errno set accordingly). A value of zero indicates socket has been shutdown by the peer. Remarks None. 5.8.5.7.1.8 recvfrom Function C int recvfrom( SOCKET s, char* buf, int len, int flags, struct sockaddr* from, int* fromlen ); Description The recvfrom() function is used to receive incoming data that has been queued for a socket. This function can be used with both datagram and stream type sockets. If the available data is too large to fit in the supplied application buffer buf, excess bytes are discarded in case of SOCK_DGRAM type sockets. For SOCK_STREAM types, the data is buffered internally so the application can retreive all data by multiple calls of recvfrom. Preconditions socket function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. buf application data receive buffer. len buffer length in bytes. flags message flags. Currently this is not supported. from pointer to the sockaddr structure that will be filled in with the destination address. fromlen size of buffer pointed by from. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3606 Returns If recvfrom is successful, the number of bytes copied to application buffer buf is returned. A return value of SOCKET_ERROR (-1) indicates an error condition (and errno set accordingly). A value of zero indicates socket has been shutdown by the peer. Remarks None. 5.8.5.7.1.9 send Function C int send( SOCKET s, const char* buf, int len, int flags ); Description The send function is used to send outgoing data on an already connected socket. This function is used to send a reliable, ordered stream of data bytes on a socket of type SOCK_STREAM but can also be used to send datagrams on a socket of type SOCK_DGRAM. Preconditions connect function should be called for TCP and UDP sockets. Server side, accept function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. buf application data buffer containing data to transmit. len length of data in bytes. flags message flags. Currently this field is not supported. Returns On success, send returns number of bytes sent. Zero indicates no data send. In case of error it returns SOCKET_ERROR (and errno set accordingly). Remarks None. 5.8.5.7.1.10 sendto Function C int sendto( SOCKET s, const char* buf, int len, int flags, const struct sockaddr* to, int tolen ); Description The sendto function is used to send outgoing data on a socket. The destination address is given by to and tolen. Both Datagram and stream sockets are supported. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3607 Preconditions socket function should be called. Parameters Parameters Description s Socket descriptor returned from a previous call to socket. buf application data buffer containing data to transmit. len length of data in bytes. flags message flags. Currently this field is not supported. to Optional pointer to the the sockaddr structure containing the destination address. If NULL, the currently bound remote port and IP address are used as the destination. tolen length of the sockaddr structure. Returns On success, sendto returns number of bytes sent. In case of error returns SOCKET_ERROR (and errno set accordingly). Remarks None. 5.8.5.7.1.11 socket Function C SOCKET socket( int af, int type, int protocol ); Description This function creates a new BSD socket for the microchip TCPIP stack. The return socket descriptor is used for the subsequent BSD operations. Preconditions BerkeleySocketInit function should be called. Parameters Parameters Description af address family - AF_INET. type socket type SOCK_DGRAM or SOCK_STREAM. protocol IP protocol IPPROTO_UDP or IPPROTO_TCP. Returns New socket descriptor. SOCKET_ERROR in case of error. (and errno set accordingly). Remarks None. 5.8.5.7.2 Data Types and Constants 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3608 5.8.5.7.2.1 AF_INET Macro C #define AF_INET 2 // Internet Address Family - UDP, TCP, etc. Description Internet Address Family - UDP, TCP, etc. 5.8.5.7.2.2 INADDR_ANY Macro C #define INADDR_ANY 0x00000000u // IP address for server binding. Description IP address for server binding. 5.8.5.7.2.3 INVALID_TCP_PORT Macro C #define INVALID_TCP_PORT (0L) //Invalid TCP port Description Invalid TCP port 5.8.5.7.2.4 IP_ADDR_ANY Macro C #define IP_ADDR_ANY 0u // IP Address for server binding Description IP Address for server binding 5.8.5.7.2.5 IPPROTO_IP Macro C #define IPPROTO_IP 0 // Indicates IP pseudo-protocol. Description Indicates IP pseudo-protocol. 5.8.5.7.2.6 IPPROTO_TCP Macro C #define IPPROTO_TCP 6 // Indicates TCP for the internet address family. Description Indicates TCP for the internet address family. 5.8.5.7.2.7 IPPROTO_UDP Macro C #define IPPROTO_UDP 17 // Indicates UDP for the internet address family. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3609 Description Indicates UDP for the internet address family. 5.8.5.7.2.8 SOCK_DGRAM Macro C #define SOCK_DGRAM 110 //Connectionless datagram socket. Use UDP for the internet address family. Description Connectionless datagram socket. Use UDP for the internet address family. 5.8.5.7.2.9 SOCK_STREAM Macro C #define SOCK_STREAM 100 //Connection based byte streams. Use TCP for the internet address family. Description Connection based byte streams. Use TCP for the internet address family. 5.8.5.7.2.10 SOCKET_CNXN_IN_PROGRESS Macro C #define SOCKET_CNXN_IN_PROGRESS (-2) //Socket connection state. Description Socket connection state. 5.8.5.7.2.11 SOCKET_DISCONNECTED Macro C #define SOCKET_DISCONNECTED (-3) //Socket disconnected Description Socket disconnected 5.8.5.7.2.12 SOCKET_ERROR Macro C #define SOCKET_ERROR (-1) //Socket error Description Socket error 5.8.5.7.2.13 BERKELEY_MODULE_CONFIG Structure C typedef struct { } BERKELEY_MODULE_CONFIG; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3610 Description Berkeley API module configuration structure 5.8.5.7.2.14 SOCKADDR Type C typedef struct sockaddr SOCKADDR; Description generic address structure for all address families 5.8.5.7.2.15 SOCKADDR_IN Type C typedef struct sockaddr_in SOCKADDR_IN; Description In the Internet address family 5.8.5.7.2.16 SOCKET Type C typedef int16_t SOCKET; Description Socket descriptor 5.8.5.7.2.17 in_addr Structure C struct in_addr { union { struct { uint8_t s_b1, s_b2, s_b3, s_b4; } S_un_b; struct { uint16_t s_w1, s_w2; } S_un_w; uint32_t S_addr; } S_un; }; Description in_addr structure 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3611 Members Members Description union { struct { uint8_t s_b1, s_b2, s_b3, s_b4; } S_un_b; struct { uint16_t s_w1, s_w2; } S_un_w; uint32_t S_addr; } S_un; union of IP address struct { uint8_t s_b1, s_b2, s_b3, s_b4; } S_un_b; IP address in Byte struct { uint16_t s_w1, s_w2; } S_un_w; IP address in Word uint32_t S_addr; IP address 5.8.5.7.2.18 sockaddr Structure C struct sockaddr { unsigned short sa_family; char sa_data[14]; }; Description generic address structure for all address families Members Members Description unsigned short sa_family; address family char sa_data[14]; up to 14 bytes of direct address 5.8.5.7.2.19 sockaddr_in Structure C struct sockaddr_in { short sin_family; uint16_t sin_port; struct in_addr sin_addr; char sin_zero[8]; }; Description In the Internet address family Members Members Description short sin_family; Address family; must be AF_INET. uint16_t sin_port; Internet Protocol (IP) port. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3612 struct in_addr sin_addr; IP address in network byte order. char sin_zero[8]; Padding to make structure the same size as SOCKADDR. 5.8.5.8 Files Files Name Description berekely_api_config.h Berekely Sockets API Client and Server berkeley_api.h Description 5.8.5.8.1 berekely_api_config.h Berekely Sockets API Configuration file This file contains the BerekelyAPI module configuration options Macros Name Description MAX_BSD_CLIENT_CONNECTIONS Berkeley API client Sockets simultaneous supported connections. MAX_BSD_SERVER_CONNECTIONS Berkeley API server Sockets simultaneous supported connections. 5.8.5.8.2 berkeley_api.h Berekely Socket Distribution API Header File Functions Name Description accept This function accepts connection requests queued for a listening socket. bind This function assigns a name to the socket descriptor. closesocket The closesocket function closes an existing socket. connect This function connects to the peer communications end point. gethostname Returns the standard host name for the system. listen The listen function sets the specified socket in a listen mode recv The recv() function is used to receive incoming data that has been queued for a socket. recvfrom The recvfrom() function is used to receive incoming data that has been queued for a socket. send The send function is used to send outgoing data on an already connected socket. sendto This function used to send the data for both connection oriented and connection-less sockets. socket This function creates a new Berkeley socket. Macros Name Description AF_INET Internet Address Family - UDP, TCP, etc. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Berkeley TCP/IP Stack Library 5-3613 INADDR_ANY IP address for server binding. INVALID_TCP_PORT Invalid TCP port IP_ADDR_ANY IP Address for server binding IPPROTO_IP Indicates IP pseudo-protocol. IPPROTO_TCP Indicates TCP for the internet address family. IPPROTO_UDP Indicates UDP for the internet address family. SOCK_DGRAM Connectionless datagram socket. Use UDP for the internet address family. SOCK_STREAM Connection based byte streams. Use TCP for the internet address family. SOCKET_CNXN_IN_PROGRESS Socket connection state. SOCKET_DISCONNECTED Socket disconnected SOCKET_ERROR Socket error Structures Name Description in_addr in_addr structure sockaddr generic address structure for all address families sockaddr_in In the Internet address family BERKELEY_MODULE_CONFIG Berkeley API module configuration structure Types Name Description SOCKADDR generic address structure for all address families SOCKADDR_IN In the Internet address family SOCKET Socket descriptor 5.8.6 DHCP TCP/IP Stack Library 5.8.6.1 Introduction Dynamic Host Configuration Protocol (DHCP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the DHCP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The DHCP client module will allow your application to dynamically obtain an IP address from a DHCP server on the same network. Doing this will reset the IP address, subnet mask, gateway address, and some other configuration parameters in your AppConfig structure. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3614 5.8.6.2 Release Notes MPLAB Harmony Version: v0.70b DHCP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.6.4 Using the Library This topic describes the basic architecture of the DHCP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: dhcp.h The interface to the DHCP TCP/IP Stack library is defined in the "dhcp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the DHCP TCP/IP Stack library should include "tcpip.h". Library File: The DHCP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.6.4.1 Abstraction Model This library provides the API of the DHCP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3615 Description DHCP Software Abstraction Block Diagram This module provides software abstraction of the DHCP module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. Typical DCHP Usage 5.8.6.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the DHCP module. Library Interface Section Description Configuration Functions Routines for Configuring DHCP Status Functions Routines for Obtaining DHCP Status Information Data Types and Constants This section provides various definitions describing This API 5.8.6.4.3 How the Library Works To use DHCP, include the files dhcp.c, dhcps.c, and dhcp.h in your project, and add or uncomment the definition "#define TCPIP_STACK_USE_DHCP_CLIENT" to tcpip_config.h. The TCP/IP stack also includes a simple DHCP server that can supply an IP address to one DHCP client. To enable this functionality, add the macro "#define TCPIP_STACK_USE_DHCP_SERVER" to tcpip_config.h. 5.8.6.5 Configuring the Library Macros Name Description DHCP_CLIENT_ENABLED enable/disable the DHCP client at stack start up DHCP_CLIENT_PORT UDP client local port for DHCP Client transactions DHCP_SERVER_PORT UDP remote port for DHCP Server DHCP_TASK_TICK_RATE 5 ms default rate DHCP_TIMEOUT Defines how long to wait before a DHCP request times out, seconds 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3616 Description The configuration of the DHCP TCP/IP Stack is based on the file sys_config.h This header file contains the configuration selection for the DHCP TCP/IP Stack. Based on the selections made, the DHCP TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the DHCP TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.6.5.1 DHCP_CLIENT_ENABLED Macro C #define DHCP_CLIENT_ENABLED 1 Description enable/disable the DHCP client at stack start up Remarks the interface initialization setting in TCPIP_NETWORK_CONFIG takes precedence! 5.8.6.5.2 DHCP_CLIENT_PORT Macro C #define DHCP_CLIENT_PORT (68u) Description UDP client local port for DHCP Client transactions 5.8.6.5.3 DHCP_SERVER_PORT Macro C #define DHCP_SERVER_PORT (67u) Description UDP remote port for DHCP Server 5.8.6.5.4 DHCP_TASK_TICK_RATE Macro C #define DHCP_TASK_TICK_RATE (5) // 5 ms default rate Description 5 ms default rate 5.8.6.5.5 DHCP_TIMEOUT Macro C #define DHCP_TIMEOUT (2ul) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3617 Description Defines how long to wait before a DHCP request times out, seconds 5.8.6.6 Building the Library This section list the files that are available in the \src of the DHCP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.6.7 Library Interface Data Types and Constants Name Description DHCP_MODULE_CONFIG DHCP Module Configuration Typedef TCPIP_DHCP_EVENT_HANDLER DHCP Event Handler TCPIP_DHCP_EVENT_TYPE DHCP Event Type TCPIP_DHCP_HANDLE DHCP Handle Configuration Functions Name Description TCPIP_DHCP_Disable Disables the DHCP Client for the specified interface. TCPIP_DHCP_Enable Enables the DHCP client for the specified interface. TCPIP_DHCP_HandlerDeRegister DHCP De-Register Handler TCPIP_DHCP_HandlerRegister DHCP Register Handler TCPIP_DHCP_Renew Renews the DHCP lease for the specified interface. TCPIP_DHCP_Request Requests the supplied IPv4 address from a DHCP server. TCPIP_DHCP_RequestTimeoutSet DHCP Set Request Timeout Status Functions Name Description TCPIP_DHCP_IsBound Determins if the DHCP client has an IP address lease on the specified interface. TCPIP_DHCP_IsEnabled Determins if the DHCP client is enabled on the specified interface. TCPIP_DHCP_IsServerDetected Determins if the DHCP client on the specified interface has seen a DHCP server. Description This section describes the Application Programming Interface (API) functions of the DHCP TCP/IP Stack. Refer to each section for a detailed description. 5.8.6.7.1 Configuration Functions 5.8.6.7.1.1 TCPIP_DHCP_Disable Function C bool TCPIP_DHCP_Disable( TCPIP_NET_HANDLE hNet ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3618 Description Disables the DHCP client for the specified interface. Preconditions None Parameters Parameters Description pNetIf Interface to disable the DHCP client on. Returns true if success false otherwise Remarks When the interface continues using its old configuration, it is possible that the lease may expire and the DHCP server provide the IP to another client. The application should not request the keeping of the old lease unless there is no danger of conflict. 5.8.6.7.1.2 TCPIP_DHCP_Enable Function C bool TCPIP_DHCP_Enable( TCPIP_NET_HANDLE hNet ); Description Enables the DHCP client for the specified interface, if it is disabled. If it is already enabled, nothing is done. Preconditions None Parameters Parameters Description hNet Interface to enable the DHCP client on. Returns true if success false otherwise 5.8.6.7.1.3 TCPIP_DHCP_HandlerDeRegister Function C bool TCPIP_DHCP_HandlerDeRegister( TCPIP_DHCP_HANDLE hDhcp ); Description deregister the event handler returns true or false if no such handler registered 5.8.6.7.1.4 TCPIP_DHCP_HandlerRegister Function C TCPIP_DHCP_HANDLE TCPIP_DHCP_HandlerRegister( TCPIP_NET_HANDLE hNet, TCPIP_DHCP_EVENT_HANDLER handler, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3619 const void* hParam ); Description Register an DHCP event handler. Use hNet == 0 to register on all interfaces available. Returns a valid handle if the call succeeds, or a null handle if the call failed. Function has to be called after the DHCP is initialized. The hParam is passed by the client and will be used by the DHCP when the notification is made. It is used for per-thread content or if more modules, for example, share the same handler and need a way to differentiate the callback. 5.8.6.7.1.5 TCPIP_DHCP_Renew Function C bool TCPIP_DHCP_Renew( TCPIP_NET_HANDLE hNet ); Description Tries to contact the server and renew the DHCP lease for the specified interface. The interface sgould have the DHCP enabled and in bound state for this call to succeed. Preconditions DHCP enabled, a valid lease Parameters Parameters Description hNet Interface to renew the DHCP lease on. Returns true if success false otherwise 5.8.6.7.1.6 TCPIP_DHCP_Request Function C bool TCPIP_DHCP_Request( TCPIP_NET_HANDLE hNet, IPV4_ADDR reqAddress ); Description If the DHCP client is not enabled on that interface, this call will first try to enable it. If this succeeds or the DHCP client was already enabled, the following steps are taken: The DHCP client probes the DHCP server and requests the supplied IPv4 address as a valid lease for the specified interface. If the server acknowledges the request, then this is the new IPv4 address of the interface. If the DHCP server rejects the request, then the whole DHCP process is resumed starting with the DHCP Discovery phase. Preconditions DHCP enabled, a valid lease Parameters Parameters Description hNet Interface to renew the DHCP lease on. Returns true if success false otherwise 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3620 Remarks The requested IPv4 address should be a previous lease that was granted to the host. This call should be used when the host is restarting. 5.8.6.7.1.7 TCPIP_DHCP_RequestTimeoutSet Function C bool TCPIP_DHCP_RequestTimeoutSet( TCPIP_NET_HANDLE hNet, int tmo ); Description Adjust the DHCP timeout. How long to wait before a DHCP request times out, seconds. 5.8.6.7.2 Status Functions 5.8.6.7.2.1 TCPIP_DHCP_IsBound Function C bool TCPIP_DHCP_IsBound( TCPIP_NET_HANDLE hNet ); Description Determins if the DHCP client has an IP address lease on the specified interface. Preconditions None Parameters Parameters Description hNet Interface to query Returns true - DHCP client has obtained an IP address lease (and likely other parameters) and these values are currently being used. false - No IP address is currently leased 5.8.6.7.2.2 TCPIP_DHCP_IsEnabled Function C bool TCPIP_DHCP_IsEnabled( TCPIP_NET_HANDLE hNet ); Description Determins if the DHCP client is enabled on the specified interface. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3621 Parameters Parameters Description hNet Interface to query. Returns None 5.8.6.7.2.3 TCPIP_DHCP_IsServerDetected Function C bool TCPIP_DHCP_IsServerDetected( TCPIP_NET_HANDLE hNet ); Description Determins if the DHCP client on the specified interface has seen a DHCP server. Preconditions None Parameters Parameters Description hNet Interface to query. Returns true - At least one DHCP server is attached to the specified network interface. false - No DHCP servers are currently detected on the specified network interface. 5.8.6.7.3 Data Types and Constants 5.8.6.7.3.1 DHCP_MODULE_CONFIG Structure C typedef struct { bool dhcpEnable; int dhcpTmo; int dhcpCliPort; int dhcpSrvPort; } DHCP_MODULE_CONFIG; Description DHCP Module Configuration Used in dhcp_config.h Members Members Description int dhcpTmo; timeout to wait for a DHCP request, seconds int dhcpCliPort; client port for DHCP client transactions int dhcpSrvPort; remote server port for DHCP server messages 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3622 5.8.6.7.3.2 TCPIP_DHCP_EVENT_HANDLER Type C typedef void (* TCPIP_DHCP_EVENT_HANDLER)(TCPIP_NET_HANDLE hNet, TCPIP_DHCP_EVENT_TYPE evType, const void* param); Description Type: TCPIP_DHCP_EVENT_HANDLER Prototype of a DHCP event handler clients can register a handler with the DHCP service. Once an DHCP event occurs the DHCP service will called the registered handler. The handler has to be short and fast. It is meant for setting an event flag, not for lengthy processing! 5.8.6.7.3.3 TCPIP_DHCP_EVENT_TYPE Enumeration C typedef enum { DHCP_EVENT_DISCOVER = 1, DHCP_EVENT_BOUND, DHCP_EVENT_LEASE_EXPIRED, DHCP_EVENT_CONN_LOST, DHCP_EVENT_SERVICE_DISABLED } TCPIP_DHCP_EVENT_TYPE; Description Enumeration: TCPIP_DHCP_EVENT_TYPE None Members Members Description DHCP_EVENT_DISCOVER = 1 DHCP cycle started DHCP_EVENT_BOUND DHCP lease obtained DHCP_EVENT_LEASE_EXPIRED lease expired DHCP_EVENT_CONN_LOST connection to the DHCP server lost, reverted to the defaultIP address DHCP_EVENT_SERVICE_DISABLED DHCP service disabled, reverted to the defaultIP address 5.8.6.7.3.4 TCPIP_DHCP_HANDLE Type C typedef const void* TCPIP_DHCP_HANDLE; Description Type: TCPIP_DHCP_HANDLE A handle that a client can use after the event handler has been registered. 5.8.6.8 Files Files Name Description dhcp.h Dynamic Host Configuration Protocol (DHCP) Client API 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3623 dhcp_config.h DCHP configuration file Description 5.8.6.8.1 dhcp.h Provides automatic IP address, subnet mask, gateway address, DNS server address, and other configuration parameters on DHCP enabled networks. • Reference: RFC 2131, 2132 Enumerations Name Description TCPIP_DHCP_EVENT_TYPE DHCP Event Type Functions Name Description TCPIP_DHCP_Disable Disables the DHCP Client for the specified interface. TCPIP_DHCP_Enable Enables the DHCP client for the specified interface. TCPIP_DHCP_HandlerDeRegister DHCP De-Register Handler TCPIP_DHCP_HandlerRegister DHCP Register Handler TCPIP_DHCP_IsBound Determins if the DHCP client has an IP address lease on the specified interface. TCPIP_DHCP_IsEnabled Determins if the DHCP client is enabled on the specified interface. TCPIP_DHCP_IsServerDetected Determins if the DHCP client on the specified interface has seen a DHCP server. TCPIP_DHCP_Renew Renews the DHCP lease for the specified interface. TCPIP_DHCP_Request Requests the supplied IPv4 address from a DHCP server. TCPIP_DHCP_RequestTimeoutSet DHCP Set Request Timeout Structures Name Description DHCP_MODULE_CONFIG DHCP Module Configuration Typedef Types Name Description TCPIP_DHCP_EVENT_HANDLER DHCP Event Handler TCPIP_DHCP_HANDLE DHCP Handle File Name dhcp.h Company Microchip Technology Incorporated 5.8.6.8.2 dhcp_config.h Dynamic Host Configuration Protocol (DCHP) Configuration file This file contains the DCHP module configuration options 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP TCP/IP Stack Library 5-3624 Macros Name Description DHCP_CLIENT_ENABLED enable/disable the DHCP client at stack start up DHCP_CLIENT_PORT UDP client local port for DHCP Client transactions DHCP_SERVER_PORT UDP remote port for DHCP Server DHCP_TASK_TICK_RATE 5 ms default rate DHCP_TIMEOUT Defines how long to wait before a DHCP request times out, seconds 5.8.7 DHCP Server TCP/IP Stack Library 5.8.7.1 Introduction DHCP Server TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the DHCP server TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The DHCP Server module is used to assign the IP address to the DHCP client from the configured IP address database.When the server receives a request from a client, the DHCP server determines the network to which the DHCP client is connected, and then allocates an IP address that is appropriate for the client, and sends configuration information appropriate for that client.DHCP servers typically grant IP addresses to clients only for a limited interval. DHCP clients are responsible for renewing their IP address before that interval has expired, and must stop using the address once the interval has expired, if they have not been able to renew it. 5.8.7.2 Release Notes MPLAB Harmony Version: v0.70b DHCP Serve r TCP/IP Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3625 Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.7.4 Using the Library This topic describes the basic architecture of the DHCP Server TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: dhcps.h The interface to the DHCP Server TCP/IP Stack library is defined in the "dhcps.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the DHCP Server TCP/IP Stack library should include "tcpip.h". Library File: The DHCP Server TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.7.4.1 Abstraction Model This library provides the API of the DHCP Server TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description DHCP Server Software Abstraction Block Diagram This module provides software abstraction of the DHCP Server module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. Typical DCHP Usage 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3626 5.8.7.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the DHCP Server module. Library Interface Section Description Configuration Functions Routines for Configuring DHCP server Status Functions Routines for Obtaining DHCP Status Information Data Types and Constants This section provides various definitions describing This API 5.8.7.4.3 How the Library Works To use DHCP Server, include the files dhcps.c, dhcp.c, and dhcp.h in your project, and add or uncomment the definition "#define TCPIP_STACK_USE_DHCP_SERVER" to tcpip_config.h. 5.8.7.5 Configuring the Library Macros Name Description DHCP_SERVER_GATEWAY_ADDRESS as we are in same network, Gateway address is same as server IP address. DHCP_SERVER_IP_ADDRESS First three octet should match to the TP address range for Server address and the begining address should be reserved for server address DHCP_SERVER_NETMASK_ADDRESS Net mask value DHCP_SERVER_PRIMARY_DNS_ADDRESS DNS Primary address DHCP_SERVER_SECONDARY_DNS_ADDRESS DNS Secondary address DHCPS_IP_ADDRESS_RANGE_START Address range is starting from 100, because the from 1 to 100 is reserved. Start address(192.168.100.1) should be used as server address DHCPS_LEASE_DURATION timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again DHCPS_LEASE_ENTRIES_DEFAULT number of entries in the cache default number of entries per interface DHCPS_LEASE_REMOVED_BEFORE_ACK The entry should be removed from the entry if there is no REQUEST after OFFER DHCPS_LEASE_SOLVED_ENTRY_TMO timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again DHCPS_TASK_PROCESS_RATE DHCPS task processing rate, in seconds the DHCPS module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. Description The configuration of the DHCP Server TCP/IP Stack is based on the file dhcps_config.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3627 This header file contains the configuration selection for the DHCP Server TCP/IP Stack. Based on the selections made, the DHCP Server TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the DHCP Server TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.7.5.1 DHCP_SERVER_GATEWAY_ADDRESS Macro C #define DHCP_SERVER_GATEWAY_ADDRESS "192.168.100.1" // as we are in same network, Gateway address is same as server IP address. Description as we are in same network, Gateway address is same as server IP address. 5.8.7.5.2 DHCP_SERVER_IP_ADDRESS Macro C #define DHCP_SERVER_IP_ADDRESS "192.168.100.1" // First three octet should match to the TP address range for Server address Description First three octet should match to the TP address range for Server address and the begining address should be reserved for server address 5.8.7.5.3 DHCP_SERVER_NETMASK_ADDRESS Macro C #define DHCP_SERVER_NETMASK_ADDRESS "255.255.255.0" // Net mask value Description Net mask value 5.8.7.5.4 DHCP_SERVER_PRIMARY_DNS_ADDRESS Macro C #define DHCP_SERVER_PRIMARY_DNS_ADDRESS "192.168.100.1" // DNS Primary address Description DNS Primary address 5.8.7.5.5 DHCP_SERVER_SECONDARY_DNS_ADDRESS Macro C #define DHCP_SERVER_SECONDARY_DNS_ADDRESS "192.168.100.1" // DNS Secondary address Description DNS Secondary address 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3628 5.8.7.5.6 DHCPS_IP_ADDRESS_RANGE_START Macro C #define DHCPS_IP_ADDRESS_RANGE_START "192.168.100.100" // Address range is starting from 100, because the from 1 to 100 is reserved. Start address(192.168.100.1) Description Address range is starting from 100, because the from 1 to 100 is reserved. Start address(192.168.100.1) should be used as server address 5.8.7.5.7 DHCPS_LEASE_DURATION Macro C #define DHCPS_LEASE_DURATION DHCPS_LEASE_SOLVED_ENTRY_TMO Description timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again 5.8.7.5.8 DHCPS_LEASE_ENTRIES_DEFAULT Macro C #define DHCPS_LEASE_ENTRIES_DEFAULT 15 Description number of entries in the cache default number of entries per interface 5.8.7.5.9 DHCPS_LEASE_REMOVED_BEFORE_ACK Macro C #define DHCPS_LEASE_REMOVED_BEFORE_ACK (5) Description The entry should be removed from the entry if there is no REQUEST after OFFER 5.8.7.5.10 DHCPS_LEASE_SOLVED_ENTRY_TMO Macro C #define DHCPS_LEASE_SOLVED_ENTRY_TMO (20 * 60) Description timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again 5.8.7.5.11 DHCPS_TASK_PROCESS_RATE Macro C #define DHCPS_TASK_PROCESS_RATE (1) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3629 Description DHCPS task processing rate, in seconds the DHCPS module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. 5.8.7.6 Building the Library This section list the files that are available in the \src of the DHCP server. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.7.7 Library Interface Data Types and Constants Name Description DHCP_SERVER_POOL_ENTRY_TYPE DHCP server pool types are used to get the leased IP address details. DHCPS_LEASE_ENTRY listing of the leases DHCPS_LEASE_HANDLE Lease details which is used by the CLI command prompt. DHCPS_MODULE_CONFIG DHCP server configuration details Configuration Functions Name Description TCPIP_DHCPS_Disable Disables the DHCP Server for the specified interface. TCPIP_DHCPS_Enable Enables the DHCP Server for the specified interface. TCPIP_DHCPS_GetPoolEntries Get all the entries or only used entries of a certain type belonging to a network interface. TCPIP_DHCPS_LeaseEntryGet returns a lease entry and allows iteration through the whole list of leases if leaseHandle it starts from the begining returns a non-zero DHCPS_LEASE_HANDLE to be used in the subsequent calls or 0 if end of list or wrong interface, or DHCP server not running on that interface TCPIP_DHCPS_RemovePoolEntries Removes all the entries or only used entries of a certain type belonging to a network interface. Status Functions Name Description TCPIP_DHCPS_IsEnabled Determines if the DHCP Server is enabled on the specified interface. Description This section describes the Application Programming Interface (API) functions of the DHCP Server TCP/IP Stack. Refer to each section for a detailed description. 5.8.7.7.1 Configuration Functions 5.8.7.7.1.1 TCPIP_DHCPS_Disable Function C bool TCPIP_DHCPS_Disable( TCPIP_NET_HANDLE hNet 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3630 ); Description Disables the DHCP Server for the specified interface. Preconditions None Parameters Parameters Description pNetIf Interface to disable the DHCP Server on. Returns true if success false otherwise Remarks When the interface continues using its old configuration, it is possible that the lease may take sometime to expire. And The communication will be there till it is not expired.Lease time is configured in dhcps_config.h. 5.8.7.7.1.2 TCPIP_DHCPS_Enable Function C bool TCPIP_DHCPS_Enable( TCPIP_NET_HANDLE hNet ); Description Enables the DHCP Server for the specified interface, if it is disabled. If it is already enabled, nothing is done. Preconditions None Parameters Parameters Description hNet Interface to enable the DHCP Server on. Returns true if success false otherwise 5.8.7.7.1.3 TCPIP_DHCPS_GetPoolEntries Function C int TCPIP_DHCPS_GetPoolEntries( TCPIP_NET_HANDLE netH, DHCP_SERVER_POOL_ENTRY_TYPE type ); Description This API is used to get the DHCP server entries from the pool as per DHCP_SERVER_POOL_ENTRY_TYPE. Preconditions DHCP server module should have been initialized 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3631 Parameters Parameters Description hNet Interface handle to use type type of entries to remove: valid types DHCP_SERVER_POOL_ENTRY_ALL, DHCP_SERVER_POOL_ENTRY_IN_USE Returns true or false Remarks None Example None 5.8.7.7.1.4 TCPIP_DHCPS_LeaseEntryGet Function C DHCPS_LEASE_HANDLE TCPIP_DHCPS_LeaseEntryGet( TCPIP_NET_HANDLE netH, DHCPS_LEASE_ENTRY* pLeaseEntry, DHCPS_LEASE_HANDLE leaseHandle ); Description returns a lease entry and allows iteration through the whole list of leases if leaseHandle it starts from the begining returns a non-zero DHCPS_LEASE_HANDLE to be used in the subsequent calls or 0 if end of list or wrong interface, or DHCP server not running on that interface 5.8.7.7.1.5 TCPIP_DHCPS_RemovePoolEntries Function C bool TCPIP_DHCPS_RemovePoolEntries( TCPIP_NET_HANDLE netH, DHCP_SERVER_POOL_ENTRY_TYPE type ); Description This API is used to remove the DHCP server entries from the pool as per DHCP_SERVER_POOL_ENTRY_TYPE. Preconditions DHCP server module should have been initialized Parameters Parameters Description hNet Interface handle to use type type of entries to remove: valid types DHCP_SERVER_POOL_ENTRY_ALL, DHCP_SERVER_POOL_ENTRY_IN_USE Returns true or false 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3632 Remarks None Example None 5.8.7.7.2 Status Functions 5.8.7.7.2.1 TCPIP_DHCPS_IsEnabled Function C bool TCPIP_DHCPS_IsEnabled( TCPIP_NET_HANDLE hNet ); Description Determines if the DHCP Server is enabled on the specified interface. Preconditions None Parameters Parameters Description hNet Interface to query. Returns None 5.8.7.7.3 Data Types and Constants 5.8.7.7.3.1 DHCP_SERVER_POOL_ENTRY_TYPE Enumeration C typedef enum { DHCP_SERVER_POOL_ENTRY_ALL, DHCP_SERVER_POOL_ENTRY_IN_USE } DHCP_SERVER_POOL_ENTRY_TYPE; Description DHCP server pool types are used to get the leased IP address details. Members Members Description DHCP_SERVER_POOL_ENTRY_ALL Get or Remove all the Leased address . There might be a address which may not be used. DHCP_SERVER_POOL_ENTRY_IN_USE Get or remove only Leased IP address. 5.8.7.7.3.2 DHCPS_LEASE_ENTRY Structure C typedef struct { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3633 TCPIP_MAC_ADDR hwAdd; IPV4_ADDR ipAddress; uint32_t leaseTime; } DHCPS_LEASE_ENTRY; Description listing of the leases Members Members Description TCPIP_MAC_ADDR hwAdd; Client MAC address IPV4_ADDR ipAddress; Leased IP address uint32_t leaseTime; Lease period 5.8.7.7.3.3 DHCPS_LEASE_HANDLE Type C typedef const void* DHCPS_LEASE_HANDLE; Description Lease details which is used by the CLI command prompt. 5.8.7.7.3.4 DHCPS_MODULE_CONFIG Structure C typedef struct { bool enabled; bool deleteOldLease; size_t leaseEntries; int entrySolvedTmo; char * startIpAddressRange; } DHCPS_MODULE_CONFIG; Description DHCP server configuration details Members Members Description bool enabled; enable DHCP server bool deleteOldLease; delete old cache if still in place, specific DHCP params size_t leaseEntries; max number of lease entries int entrySolvedTmo; solved entry removed after this tmo if not referenced - seconds char * startIpAddressRange; start value of the IP address for DHCP clients. 5.8.7.8 Files Files Name Description dhcps.h Dynamic Host Configuration Protocol(DHCP) Server APIs. dhcps_config.h DHCPS configuration file 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3634 Description 5.8.7.8.1 dhcps.h The DHCP server permanently assigns a free IP address to a requesting client from the range defined in the dhcps_config.h file. • Reference: RFC 2131, 2132 Enumerations Name Description DHCP_SERVER_POOL_ENTRY_TYPE DHCP server pool types are used to get the leased IP address details. Functions Name Description TCPIP_DHCPS_Disable Disables the DHCP Server for the specified interface. TCPIP_DHCPS_Enable Enables the DHCP Server for the specified interface. TCPIP_DHCPS_GetPoolEntries Get all the entries or only used entries of a certain type belonging to a network interface. TCPIP_DHCPS_IsEnabled Determines if the DHCP Server is enabled on the specified interface. TCPIP_DHCPS_LeaseEntryGet returns a lease entry and allows iteration through the whole list of leases if leaseHandle it starts from the begining returns a non-zero DHCPS_LEASE_HANDLE to be used in the subsequent calls or 0 if end of list or wrong interface, or DHCP server not running on that interface TCPIP_DHCPS_RemovePoolEntries Removes all the entries or only used entries of a certain type belonging to a network interface. Structures Name Description DHCPS_LEASE_ENTRY listing of the leases DHCPS_MODULE_CONFIG DHCP server configuration details Types Name Description DHCPS_LEASE_HANDLE Lease details which is used by the CLI command prompt. File Name dhcps.h Company Microchip Technology Incorporated 5.8.7.8.2 dhcps_config.h Dynamic Host Configuration Protocol (DHCPS) Configuration file This file contains the DHCPS module configuration options 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DHCP Server TCP/IP Stack Library 5-3635 Macros Name Description DHCP_SERVER_GATEWAY_ADDRESS as we are in same network, Gateway address is same as server IP address. DHCP_SERVER_IP_ADDRESS First three octet should match to the TP address range for Server address and the begining address should be reserved for server address DHCP_SERVER_NETMASK_ADDRESS Net mask value DHCP_SERVER_PRIMARY_DNS_ADDRESS DNS Primary address DHCP_SERVER_SECONDARY_DNS_ADDRESS DNS Secondary address DHCPS_IP_ADDRESS_RANGE_START Address range is starting from 100, because the from 1 to 100 is reserved. Start address(192.168.100.1) should be used as server address DHCPS_LEASE_DURATION timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again DHCPS_LEASE_ENTRIES_DEFAULT number of entries in the cache default number of entries per interface DHCPS_LEASE_REMOVED_BEFORE_ACK The entry should be removed from the entry if there is no REQUEST after OFFER DHCPS_LEASE_SOLVED_ENTRY_TMO timeout for a solved entry in the cache, in seconds the entry will be removed if the tmo elapsed and the entry has not been referenced again DHCPS_TASK_PROCESS_RATE DHCPS task processing rate, in seconds the DHCPS module will process a timer event with this rate for maintaining its own queues, processing timeouts, etc. 5.8.8 DNS TCP/IP Stack Library 5.8.8.1 Introduction Domain Name System (DNS) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the DNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Domain Name Service associates host names (such as www.microchip.com) with IP addresses (such as 10.0.54.2). The DNS Client module provides DNS resolution capabilities to the stack. TCP applications do not need to use the DNS module. Any necessary DNS operations can be handled by the TCPOpen function. Applications built using UDP may need to use DNS when the IP address of the remote server is unknown. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3636 5.8.8.2 Release Notes MPLAB Harmony Version: v0.70b DNS TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.8.4 Using the Library This topic describes the basic architecture of the DNS TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: dns.h The interface to the DNS TCP/IP Stack library is defined in the "dns.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the DNS TCP/IP Stack library should include "tcpip.h". Library File: The DNS TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.8.4.1 Abstraction Model This library provides the API of the DNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3637 Description DNS is part of the Application Layer: DNS resolution operations follow a simple state machine, as indicated in the diagram below. 5.8.8.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the DNS module. Library Interface Section Description General Functions This section provides general interface routines to DNS Data Types and Constants This section provides various definitions describing this API 5.8.8.5 Configuring the Library Macros Name Description DNS_CLIENT_ARP_TMO When the DNS Client performs an ARP request for the DNS Server this is the elapsed time after which a ARP resolution is considered to have timed out In seconds DNS_CLIENT_OPEN_TMO The DNS Client performs an UDP socket open request to communicate with the DNS Server This is the elapsed time after which an open request is considered to have timed out In seconds DNS_CLIENT_PORT Default port for DNS resolutions DNS_CLIENT_SERVER_TMO When the DNS Client connected to the DNS Server this is the elapsed time after which an the communication is considered to have timed failed if there was no reply from the server In seconds 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3638 DNS_CLIENT_TASK_PROCESS_RATE DNS Client task processing rate, in milli-seconds the DNS Client module will process a timer event with this rate for processing its own state machine, etc. DNS_CLIENT_VERSION_NO DNS Client version Depending on the version of the DNS implementation the DNS task process will be performed differently Description The configuration of the DNS TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the DNS TCP/IP Stack. Based on the selections made, the DNS TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the DNS TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.8.5.1 DNS_CLIENT_ARP_TMO Macro C #define DNS_CLIENT_ARP_TMO (1) Description When the DNS Client performs an ARP request for the DNS Server this is the elapsed time after which a ARP resolution is considered to have timed out In seconds 5.8.8.5.2 DNS_CLIENT_OPEN_TMO Macro C #define DNS_CLIENT_OPEN_TMO (1) Description The DNS Client performs an UDP socket open request to communicate with the DNS Server This is the elapsed time after which an open request is considered to have timed out In seconds 5.8.8.5.3 DNS_CLIENT_PORT Macro C #define DNS_CLIENT_PORT 53 Description Default port for DNS resolutions 5.8.8.5.4 DNS_CLIENT_SERVER_TMO Macro C #define DNS_CLIENT_SERVER_TMO (1) Description When the DNS Client connected to the DNS Server this is the elapsed time after which an the communication is considered to have timed failed if there was no reply from the server In seconds 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3639 5.8.8.5.5 DNS_CLIENT_TASK_PROCESS_RATE Macro C #define DNS_CLIENT_TASK_PROCESS_RATE (500) Description DNS Client task processing rate, in milli-seconds the DNS Client module will process a timer event with this rate for processing its own state machine, etc. 5.8.8.5.6 DNS_CLIENT_VERSION_NO Macro C #define DNS_CLIENT_VERSION_NO 1 Description DNS Client version Depending on the version of the DNS implementation the DNS task process will be performed differently 5.8.8.6 Building the Library This section list the files that are available in the \src of the DNS driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.8.7 Library Interface Data Types and Constants Name Description DNS_CLIENT_MODULE_CONFIG Provides a placeholder for DNS client configuration. DNS_RESOLVE_TYPE This enumeration provides the RecordType argument for TCPIP_DNS_Resolve. DNS_RESULT This enumeration provides result codes for various DNS operations. DNS_SERVER_MODULE_CONFIG Provides a placeholder for DNS server configuration. General Functions Name Description TCPIP_DNS_IsResolved Determines if the DNS resolution is complete and provides the IP. TCPIP_DNS_Resolve Begins resolution of an address. TCPIP_DNS_UsageBegin Claims access to the DNS module. TCPIP_DNS_UsageEnd Releases control of the DNS module. Description This section describes the Application Programming Interface (API) functions of the DNS TCP/IP Stack. Refer to each section for a detailed description. 5.8.8.7.1 General Functions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3640 5.8.8.7.1.1 TCPIP_DNS_IsResolved Function C DNS_RESULT TCPIP_DNS_IsResolved( const char* HostName, void* HostIP ); Description Call this function to determine if the DNS resolution of an address has been completed. If so, the resolved address will be provided in HostIP. Preconditions TCPIP_DNS_Resolve has been called. Parameters Parameters Description Hostname A pointer to the null terminated string specifiying the host for which to resolve an IP. HostIP A pointer to an IPV4_ADDR structure in which to store the resolved IP address once resolution is complete. Return Values Return Values Description DNS_RES_OK The DNS client has obtained an IP HostIP will contain the resolved address. DNS_RES_PENDING The resolution process is still in progress. DNS_RES_SERVER_TMO DNS server timed out DNS_RES_NO_ENTRY no such entry to be resolved exists Remarks None. 5.8.8.7.1.2 TCPIP_DNS_Resolve Function C DNS_RESULT TCPIP_DNS_Resolve( const char* HostName, DNS_RESOLVE_TYPE Type ); Description This function attempts to resolve a host name to an IP address. When called, it starts the DNS state machine. Call TCPIP_DNS_IsResolved repeatedly to determine if the resolution is complete. Only one DNS resoultion may be executed at a time. The Hostname must not be modified in memory until the resolution is complete. Preconditions TCPIP_DNS_UsageBegin returned DNS_RES_OK on a previous call. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3641 Parameters Parameters Description Hostname A pointer to the null terminated string specifiying the host for which to resolve an IP. RecordType DNS_TYPE_A or DNS_TYPE_MX depending on what type of record resolution is desired. Returns DNS_RES_OK Remarks This function requires access to one UDP socket. If none are available, UDP_MAX_SOCKETS may need to be increased. 5.8.8.7.1.3 TCPIP_DNS_UsageBegin Function C DNS_RESULT TCPIP_DNS_UsageBegin( TCPIP_NET_HANDLE netH ); Description This function acts as a semaphore to obtain usage of the DNS module. Call this function and ensure that it returns DNS_RES_OK before calling any other DNS APIs. Call TCPIP_DNS_UsageEnd when this application no longer needs the DNS module so that other applications may make use of it. Preconditions Stack is initialized. Parameters Parameters Description netH interface to use If 0, a default interface will be selected Return Values Return Values Description DNS_RES_OK the calling application has sucessfully taken ownership of the DNS module DNS_RES_BUSY The DNS module is currently in use. Yield to the stack and attempt this call again later. Remarks Ensure that TCPIP_DNS_UsageEnd is always called once your application has obtained control of the DNS module. If this is not done, the stack will hang for all future applications requiring DNS access. 5.8.8.7.1.4 TCPIP_DNS_UsageEnd Function C DNS_RESULT TCPIP_DNS_UsageEnd( TCPIP_NET_HANDLE netH ); Description This function acts as a semaphore to release control of the DNS module. Call this function when this application no longer needs the DNS module so that other applications may make use of it. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3642 Preconditions TCPIP_DNS_UsageBegin returned DNS_RES_OK on a previous call. Parameters Parameters Description netH interface to release Not used. Return Values Return Values Description DNS_RES_OK The DNS module successfully released. Remarks Ensure that TCPIP_DNS_UsageEnd is always called once your application has obtained control of the DNS module. If this is not done, the stack will hang for all future applications requiring DNS access. 5.8.8.7.2 Data Types and Constants 5.8.8.7.2.1 DNS_CLIENT_MODULE_CONFIG Structure C typedef struct { } DNS_CLIENT_MODULE_CONFIG; Description DNS_CLIENT_MODULE_CONFIG Structure Typedef Provides a placeholder for DNS client configuration. Remarks None. 5.8.8.7.2.2 DNS_RESOLVE_TYPE Enumeration C typedef enum { DNS_TYPE_A = 1, DNS_TYPE_MX = 15, DNS_TYPE_AAAA = 28u } DNS_RESOLVE_TYPE; Description DNS_RESOLVE_TYPE Enumeration This enumeration provides the RecordType argument for TCPIP_DNS_Resolve. Members Members Description DNS_TYPE_A = 1 Constant for record type in TCPIP_DNS_Resolve. Indicates an A (standard address) record. DNS_TYPE_MX = 15 Constant for record type in TCPIP_DNS_Resolve. Indicates an MX (mail exchanger) record. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3643 DNS_TYPE_AAAA = 28u Constant for record type in TCPIP_DNS_Resolve. Indicates a quad-A (IPv6 address) address record. Remarks None. 5.8.8.7.2.3 DNS_RESULT Enumeration C typedef enum { DNS_RES_OK = 0, DNS_RES_PENDING, DNS_RES_NO_ENTRY = -1, DNS_RES_CACHE_FULL = -2, DNS_RES_OPEN_TMO = -3, DNS_RES_SERVER_TMO = -4, DNS_RES_NO_SERVICE = -5, DNS_RES_NO_INTERFACE = -10, DNS_RES_BUSY = -11, DNS_RES_ARP_TMO = -12 } DNS_RESULT; Description DNS_RESULT Enumeration This enumeration provides result codes for various DNS operations. Members Members Description DNS_RES_OK = 0 operation succeeded DNS_RES_PENDING operation is ongoing DNS_RES_NO_ENTRY = -1 no such entry exists DNS_RES_CACHE_FULL = -2 the cache is full and no entry could be DNS_RES_OPEN_TMO = -3 DNS client couldn't get a socket DNS_RES_SERVER_TMO = -4 DNS server response tmo DNS_RES_NO_SERVICE = -5 DNS service not implemented DNS_RES_NO_INTERFACE = -10 an active/requested interface could not be found DNS_RES_BUSY = -11 module is in use by other task; retry later DNS_RES_ARP_TMO = -12 ARP tmo Remarks None. 5.8.8.7.2.4 DNS_SERVER_MODULE_CONFIG Structure C typedef struct { } DNS_SERVER_MODULE_CONFIG; Description DNS_SERVER_MODULE_CONFIG Structure Typedef Provides a placeholder for DNS server configuration. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3644 Remarks None. 5.8.8.8 Files Files Name Description dns.h DNS definitions and interface file dns_config.h DNS configuration file Description 5.8.8.8.1 dns.h Domain Name System (DNS) client Header file This source file contains the DNS client module API Enumerations Name Description DNS_RESOLVE_TYPE This enumeration provides the RecordType argument for TCPIP_DNS_Resolve. DNS_RESULT This enumeration provides result codes for various DNS operations. Functions Name Description TCPIP_DNS_IsResolved Determines if the DNS resolution is complete and provides the IP. TCPIP_DNS_Resolve Begins resolution of an address. TCPIP_DNS_UsageBegin Claims access to the DNS module. TCPIP_DNS_UsageEnd Releases control of the DNS module. Structures Name Description DNS_CLIENT_MODULE_CONFIG Provides a placeholder for DNS client configuration. DNS_SERVER_MODULE_CONFIG Provides a placeholder for DNS server configuration. 5.8.8.8.2 dns_config.h Domain Name Service (CNS) Configuration file This file contains the DNS module configuration options Macros Name Description DNS_CLIENT_ARP_TMO When the DNS Client performs an ARP request for the DNS Server this is the elapsed time after which a ARP resolution is considered to have timed out In seconds 5.8 TCP/IP Stack Library Help MPLAB Harmony Help DNS TCP/IP Stack Library 5-3645 DNS_CLIENT_OPEN_TMO The DNS Client performs an UDP socket open request to communicate with the DNS Server This is the elapsed time after which an open request is considered to have timed out In seconds DNS_CLIENT_PORT Default port for DNS resolutions DNS_CLIENT_SERVER_TMO When the DNS Client connected to the DNS Server this is the elapsed time after which an the communication is considered to have timed failed if there was no reply from the server In seconds DNS_CLIENT_TASK_PROCESS_RATE DNS Client task processing rate, in milli-seconds the DNS Client module will process a timer event with this rate for processing its own state machine, etc. DNS_CLIENT_VERSION_NO DNS Client version Depending on the version of the DNS implementation the DNS task process will be performed differently 5.8.9 Dynamic DNS TCP/IP Stack Library 5.8.9.1 Introduction Dynamic Domain Name System (DDNS) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the DDNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Dynamic DNS Client module provides a method for updating a dynamic IP address to a public DDNS service. These services can be used to provide DNS hostname mapping to devices that behind routers, firewalls, and/or on networks that dynamically assign IP addresses. Note that this only solves one of the two problems for communicating to devices on local subnets from the Internet. While Dynamic DNS can help to locate the device, the router or firewall it sits behind must still properly forward the incoming connection request. This generally requires port forwarding to be configured for the router behind which the device is located. The Dynamic DNS client supports the popular interface used by DynDNS.org, No-IP.com, and DNS-O-Matic.com. IMPORTANT: The dynamic DNS services stipulate that updates should be made no more frequently than 10 minutes, and only when the IP address has changed. Updates made more often than that are considered abusive, and may eventually cause your account to be disabled. Production devices that get rebooted frequently may need to store the last known IP in non-volatile memory. You also should not enable this module while testing the rest of your application. 5.8.9.2 Release Notes MPLAB Harmony Version: v0.70b DDNS TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3646 Known Issues: Nothing to report in this release. 5.8.9.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.9.4 Using the Library This topic describes the basic architecture of the DDNS TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: dyn_dns.h The interface to the DDNS TCP/IP Stack library is defined in the "dyn_dns.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the DDNS TCP/IP Stack library should include "tcpip.h". Library File: The DDNS TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.9.4.1 Abstraction Model This library provides the API of the DDNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description DDNS Software Abstraction Block Diagram Note: This diagram was not available at time of release and will be added in a future version of MPLAB Harmony. 5.8.9.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the DDNS module. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3647 Library Interface Section Description Functions Routines for Configuring DDNS Data Types and Constants This section provides various definitions describing this API 5.8.9.5 Configuring the Library Macros Name Description DDNS_CHECKIP_SERVER Default CheckIP server for determining current IP address DDNS_DEFAULT_PORT Default port for CheckIP server Description The configuration of the DDNS TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the DDNS TCP/IP Stack Library. Based on the selections made, the DDNS TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the DDNS TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.9.5.1 DDNS_CHECKIP_SERVER Macro C #define DDNS_CHECKIP_SERVER (const uint8_t*)"checkip.dyndns.com" Description Default CheckIP server for determining current IP address 5.8.9.5.2 DDNS_DEFAULT_PORT Macro C #define DDNS_DEFAULT_PORT (80u) Description Default port for CheckIP server 5.8.9.6 Building the Library This section list the files that are available in the \src of the DDNS driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3648 5.8.9.7 Library Interface Data Types and Constants Name Description DDNS_MODULE_CONFIG This is type DDNS_MODULE_CONFIG. DDNS_POINTERS Configuration parameters for the Dynamic DNS Client DDNS_SERVICES Dynamic DNS Services. Must support the DynDNS API (Auxlang) and correspond to ddnsServiceHosts and ddnsServicePorts in DynDNS.c. DDNS_STATUS Status message for DynDNS client. GOOD and NOCHG are ok, but ABUSE through 911 are fatal. UNCHANGED through INVALID are locally defined. Functions Name Description TCPIP_DDNS_LastIPGet Returns the status of the most recent update. TCPIP_DDNS_LastStatusGet Returns the last known external IP address of the device. TCPIP_DDNS_ServiceSet Selects a pre-configured Dynamic DNS service TCPIP_DDNS_UpdateForce Forces an immediate DDNS update Description This section describes the Application Programming Interface (API) functions of the DDNS TCP/IP Stack. Refer to each section for a detailed description. 5.8.9.7.1 Functions 5.8.9.7.1.1 TCPIP_DDNS_LastIPGet Function C IPV4_ADDR TCPIP_DDNS_LastIPGet(); Description This function returns the status of the most recent update. See the DDNS_STATUS enumeration for possible codes. Preconditions None Returns DDNS_STATUS indicating the status code for the most recent update. 5.8.9.7.1.2 TCPIP_DDNS_LastStatusGet Function C DDNS_STATUS TCPIP_DDNS_LastStatusGet(); Description This function returns the last known external IP address of the device. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3649 Returns The last known external IP address of the device. 5.8.9.7.1.3 TCPIP_DDNS_ServiceSet Function C void TCPIP_DDNS_ServiceSet( DDNS_SERVICES svc ); Description This function selects a Dynamic DNS service based on parameters configured in ddnsServiceHosts and ddnsServicePorts. These arrays must match the DDNS_SERVICES enumeration. Preconditions None Parameters Parameters Description svc one of the DDNS_SERVICES elements to indicate the selected service Returns None 5.8.9.7.1.4 TCPIP_DDNS_UpdateForce Function C void TCPIP_DDNS_UpdateForce(); Description This function forces the DDNS Client to execute a full update immediately. Any error message is cleared, and the update will be executed whether the IP address has changed or not. Call this function every time the DDNSClient parameters have been modified. Preconditions TCPIP_DDNS_Initialize must have been called. Returns None 5.8.9.7.2 Data Types and Constants 5.8.9.7.2.1 DDNS_MODULE_CONFIG Structure C typedef struct { } DDNS_MODULE_CONFIG; Description This is type DDNS_MODULE_CONFIG. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3650 5.8.9.7.2.2 DDNS_POINTERS Structure C typedef struct { union { uint8_t * szRAM; const uint8_t * szROM; } CheckIPServer; uint16_t CheckIPPort; union { uint8_t * szRAM; const uint8_t * szROM; } UpdateServer; uint16_t UpdatePort; union { uint8_t * szRAM; const uint8_t * szROM; } Username; union { uint8_t * szRAM; const uint8_t * szROM; } Password; union { uint8_t * szRAM; const uint8_t * szROM; } Host; struct { unsigned char CheckIPServer : 1; unsigned char UpdateServer : 1; unsigned char Username : 1; unsigned char Password : 1; unsigned char Host : 1; } ROMPointers; } DDNS_POINTERS; Description This structure of pointers configures the Dynamic DNS Client. Initially, all pointers will be null and the client will be disabled. Set DDNSClient.[field name].szRAM to use a string stored in RAM, or DDNSClient.[field name].szROM to use a string stored in const. (Where [field name] is one of the parameters below.) If a const string is specified, DDNSClient.ROMPointers.[field name] must also be set to 1 to indicate that this field should be retrieved from const instead of RAM. Parameters Parameters Description CheckIPServer The server used to determine the external IP address CheckIPPort Port on the above server to connect to UpdateServer The server where updates should be posted UpdatePort Port on the above server to connect to Username The user name for the dynamic DNS server Password The password to supply when making updates Host The host name you wish to update ROMPointers Indicates which parameters to read from const instead of RAM. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3651 5.8.9.7.2.3 DDNS_SERVICES Enumeration C typedef enum { DYNDNS_ORG = 0u, NO_IP_COM, DNSOMATIC_COM } DDNS_SERVICES; Description Dynamic DNS Services. Must support the DynDNS API (Auxlang) and correspond to ddnsServiceHosts and ddnsServicePorts in DynDNS.c. Members Members Description DYNDNS_ORG = 0u www.dyndns.org NO_IP_COM www.no-ip.com DNSOMATIC_COM www.dnsomatic.com 5.8.9.7.2.4 DDNS_STATUS Enumeration C typedef enum { DDNS_STATUS_GOOD = 0u, DDNS_STATUS_NOCHG, DDNS_STATUS_ABUSE, DDNS_STATUS_BADSYS, DDNS_STATUS_BADAGENT, DDNS_STATUS_BADAUTH, DDNS_STATUS_NOT_DONATOR, DDNS_STATUS_NOT_FQDN, DDNS_STATUS_NOHOST, DDNS_STATUS_NOT_YOURS, DDNS_STATUS_NUMHOST, DDNS_STATUS_DNSERR, DDNS_STATUS_911, DDNS_STATUS_UPDATE_ERROR, DDNS_STATUS_UNCHANGED, DDNS_STATUS_CHECKIP_ERROR, DDNS_STATUS_DNS_ERROR, DDNS_STATUS_SKT_ERROR, DDNS_STATUS_INVALID, DDNS_STATUS_UNKNOWN } DDNS_STATUS; Description Status message for DynDNS client. GOOD and NOCHG are ok, but ABUSE through 911 are fatal. UNCHANGED through INVALID are locally defined. Members Members Description DDNS_STATUS_GOOD = 0u Update successful, hostname is now updated DDNS_STATUS_NOCHG Update changed no setting and is considered abusive. Additional 'nochg' updates will cause hostname to be blocked. DDNS_STATUS_ABUSE The hostname specified is blocked for update abuse. DDNS_STATUS_BADSYS System parameter not valid. Should be dyndns, statdns or custom. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3652 DDNS_STATUS_BADAGENT The user agent was blocked or not sent. DDNS_STATUS_BADAUTH The username and password pair do not match a real user. DDNS_STATUS_NOT_DONATOR An option available only to credited users (such as offline URL) was specified, but the user is not a credited user. If multiple hosts were specified, only a single !donator will be returned. DDNS_STATUS_NOT_FQDN The hostname specified is not a fully-qualified domain name (not in the form hostname.dyndns.org or domain.com). DDNS_STATUS_NOHOST The hostname specified does not exist in this user account (or is not in the service specified in the system parameter). DDNS_STATUS_NOT_YOURS The hostname specified does not belong to this user account. DDNS_STATUS_NUMHOST Too many hosts specified in an update. DDNS_STATUS_DNSERR Unspecified DNS error encountered by the DDNS service. DDNS_STATUS_911 There is a problem or scheduled maintenance with the DDNS service. DDNS_STATUS_UPDATE_ERROR Error communicating with Update service. DDNS_STATUS_UNCHANGED The IP Check indicated that no update was necessary. DDNS_STATUS_CHECKIP_ERROR Error communicating with CheckIP service. DDNS_STATUS_DNS_ERROR DNS error resolving the CheckIP service. DDNS_STATUS_SKT_ERROR TCP socket opening error DDNS_STATUS_INVALID DDNS Client data is not valid. DDNS_STATUS_UNKNOWN DDNS client has not yet been executed with this configuration. 5.8.9.8 Files Files Name Description ddns.h ddns_config.h DynDNS configuration file Description 5.8.9.8.1 ddns.h DynDNS Headers for Microchip TCP/IP Stack Enumerations Name Description DDNS_SERVICES Dynamic DNS Services. Must support the DynDNS API (Auxlang) and correspond to ddnsServiceHosts and ddnsServicePorts in DynDNS.c. DDNS_STATUS Status message for DynDNS client. GOOD and NOCHG are ok, but ABUSE through 911 are fatal. UNCHANGED through INVALID are locally defined. Functions Name Description TCPIP_DDNS_LastIPGet Returns the status of the most recent update. TCPIP_DDNS_LastStatusGet Returns the last known external IP address of the device. TCPIP_DDNS_ServiceSet Selects a pre-configured Dynamic DNS service 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Dynamic DNS TCP/IP Stack Library 5-3653 TCPIP_DDNS_UpdateForce Forces an immediate DDNS update Structures Name Description DDNS_MODULE_CONFIG This is type DDNS_MODULE_CONFIG. DDNS_POINTERS Configuration parameters for the Dynamic DNS Client 5.8.9.8.2 ddns_config.h Dynamic Domain Name Service (DynDNS) Configuration file This file contains the DynDNS module configuration options Macros Name Description DDNS_CHECKIP_SERVER Default CheckIP server for determining current IP address DDNS_DEFAULT_PORT Default port for CheckIP server 5.8.10 FTP TCP/IP Stack Library 5.8.10.1 Introduction File Transfer Protocol (FTP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the FTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description An embedded FTP (File Transfer Protocol) server is an excellent addition to any network-enabled device. FTP server capability facilitates the uploading of files to, and downloading of files from, an embedded device. Almost all computers have, at the very least, a command line FTP client that will allow a user to connect to an embedded FTP server. 5.8.10.2 Release Notes MPLAB Harmony Version: v0.70b FTP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: The FTP server provided here with these following functionalities. You can easily add new functionality as required. The FTP server presented here incorporates the following features: • Server Works with both Passive and Active mode 5.8 TCP/IP Stack Library Help MPLAB Harmony Help FTP TCP/IP Stack Library 5-3654 • FTP Server APIs are compatible with PIC24 • FTP connection is authenticated by using username as "admin" and password "microchip". Anonymous login is provided • GET, MGET, PUT, and MPUT commands are provided Known Issues: None to report at this time. 5.8.10.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.10.4 Using the Library This topic describes the basic architecture of the FTP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: ftp.h The interface to the FTP TCP/IP Stack library is defined in the "ftp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the FTP TCP/IP Stack library should include "tcpip.h". Library File: The FTP TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.10.4.1 Abstraction Model This library provides the API of the FTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description FTP Server Dependencies 5.8 TCP/IP Stack Library Help MPLAB Harmony Help FTP TCP/IP Stack Library 5-3655 Since FTP server requires the use of TCP/IP stack and a file system which can be a MPFS or MDD , it also inherits the program memory and RAM requirements of those as well. 5.8.10.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the FTP module. Library Interface Section Description Data Types and Constants This section provides various definitions describing This API 5.8.10.5 Configuring the Library Macros Name Description TCPIP_FTP_DATA_SKT_RX_BUFF_SIZE Define the size of the RX buffer for the FTP Data socket Use 0 for default TCPIP_FTP_DATA_SKT_TX_BUFF_SIZE Define the size of the TX buffer for the FTP Data socket Use 0 for default TCPIP_FTP_MAX_CONNECTIONS Maximum number of FTP connections allowed per interface TCPIP_FTP_PASSWD_LEN Specifies the max length of FTP login password TCPIP_FTP_PUT_ENABLED Comment this line out to disable MPFS TCPIP_FTP_USER_NAME_LEN Specifies the max length for user name Description The configuration of the FTP TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the FTP TCP/IP Stack. Based on the selections made, the FTP TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the FTP TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.10.5.1 TCPIP_FTP_DATA_SKT_RX_BUFF_SIZE Macro C #define TCPIP_FTP_DATA_SKT_RX_BUFF_SIZE 0 5.8 TCP/IP Stack Library Help MPLAB Harmony Help FTP TCP/IP Stack Library 5-3656 Description Define the size of the RX buffer for the FTP Data socket Use 0 for default 5.8.10.5.2 TCPIP_FTP_DATA_SKT_TX_BUFF_SIZE Macro C #define TCPIP_FTP_DATA_SKT_TX_BUFF_SIZE 0 Description Define the size of the TX buffer for the FTP Data socket Use 0 for default 5.8.10.5.3 TCPIP_FTP_MAX_CONNECTIONS Macro C #define TCPIP_FTP_MAX_CONNECTIONS (1) Description Maximum number of FTP connections allowed per interface 5.8.10.5.4 TCPIP_FTP_PASSWD_LEN Macro C #define TCPIP_FTP_PASSWD_LEN (10) Description Specifies the max length of FTP login password 5.8.10.5.5 TCPIP_FTP_PUT_ENABLED Macro C #define TCPIP_FTP_PUT_ENABLED Description Comment this line out to disable MPFS 5.8.10.5.6 TCPIP_FTP_USER_NAME_LEN Macro C #define TCPIP_FTP_USER_NAME_LEN (10) Description Specifies the max length for user name 5.8.10.6 Building the Library This section list the files that are available in the \src of the FTP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help FTP TCP/IP Stack Library 5-3657 5.8.10.7 Library Interface Data Types and Constants Name Description FTP_MODULE_CONFIG FTP module dynamic configuration data Description This section describes the Application Programming Interface (API) functions of the FTP TCP/IP Stack. Refer to each section for a detailed description. 5.8.10.7.1 Data Types and Constants 5.8.10.7.1.1 FTP_MODULE_CONFIG Structure C typedef struct { uint16_t dataSktTxBuffSize; uint16_t dataSktRxBuffSize; uint8_t userName[10+1]; uint8_t password[10+1]; } FTP_MODULE_CONFIG; Description FTP module dynamic configuration data Members Members Description uint16_t dataSktTxBuffSize; size of Data socket TX buffer for the associatted socket; leave 0 for default uint16_t dataSktRxBuffSize; size of Data Socket RX buffer for the associatted socket; leave 0 for default uint8_t userName[10+1]; FTP login User name TCPIP_FTP_USER_NAME_LEN uint8_t password[10+1]; FTP login password TCPIP_FTP_PASSWD_LEN 5.8.10.8 Files Files Name Description ftp.h ftp_config.h FTP configuration file Description 5.8.10.8.1 ftp.h FTP Server Defs for Microchip TCP/IP Stack 5.8 TCP/IP Stack Library Help MPLAB Harmony Help FTP TCP/IP Stack Library 5-3658 Structures Name Description FTP_MODULE_CONFIG FTP module dynamic configuration data 5.8.10.8.2 ftp_config.h File Transfer Protocol (FTP) Configuration file This file contains the FTP module configuration options Macros Name Description TCPIP_FTP_DATA_SKT_RX_BUFF_SIZE Define the size of the RX buffer for the FTP Data socket Use 0 for default TCPIP_FTP_DATA_SKT_TX_BUFF_SIZE Define the size of the TX buffer for the FTP Data socket Use 0 for default TCPIP_FTP_MAX_CONNECTIONS Maximum number of FTP connections allowed per interface TCPIP_FTP_PASSWD_LEN Specifies the max length of FTP login password TCPIP_FTP_PUT_ENABLED Comment this line out to disable MPFS TCPIP_FTP_USER_NAME_LEN Specifies the max length for user name 5.8.11 HTTP Server TCP/IP Stack Library 5.8.11.1 Introduction Hypertext Transfer Protocol (HTTP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the HTTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The HTTP web server module and its associated MPFS2 file system module allow the board to act as a web server. This facilitates an easy method to view status information and control applications using any standard web browser. 5.8.11.2 Release Notes MPLAB Harmony Version: v0.70b HTTP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3659 Known Issues: Nothing to report in this release. 5.8.11.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.11.4 Using the Library This topic describes the basic architecture of the HTTP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: http.h The interface to the HTTP TCP/IP Stack library is defined in the "http.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the HTTP TCP/IP Stack library should include "tcpip.h". Library File: The HTTP TCPIP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.11.4.1 Abstraction Model This library provides the API of the HTTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description HTTP Software Abstraction Block Diagram Three main components are necessary to understand how the HTTP web server works: the web pages, the MPFS2 Utility, and the source files CustomHTTPApp.c and HTTPPrint.h. An overview of the entire process is shown below. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3660 Web Pages This includes all the HTML and associated images, CSS stylesheets, and JavaScript files necessary to display the website. A sample application including all these components is located in the WebPages2 folder. MPFS2 Utility This program, supplied by Microchip, packages the web pages into a format that can be efficiently stored in either external non-volatile storage, or internal flash program memory. This program also indexes dynamic variables found in the web pages and updates HTTPPrint.h with these indices. If external storage is being used, the MPFS2 Utility outputs a BIN file and can upload that file directly to the board. If the data 5.8.11.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the HTTP module. Library Interface Section Description Functions Routines for Configuring DHCP Data Types and Constants This section provides various definitions describing this API 5.8.11.5 Configuring the Library Macros Name Description HTTP_CACHE_LEN Max lifetime (sec) of static responses as string HTTP_CONFIG_FLAGS Define the HTTP module configuration flags Use 0 for default HTTP_DEFAULT_FILE Indicate what file to serve when no specific one is requested HTTP_DEFAULT_LEN For buffer overrun protection. Set to longest length of above two strings. HTTP_FILE_UPLOAD Configure MPFS over HTTP updating Comment this line to disable updating via HTTP HTTP_MAX_CONNECTIONS Maximum numbers of simultaneous supported HTTP connections. HTTP_MAX_DATA_LEN Define the maximum data length for reading cookie and GET/POST arguments (bytes) HTTP_MAX_HEADER_LEN Set to length of longest string above HTTP_MIN_CALLBACK_FREE Define the minimum number of bytes free in the TX FIFO before executing callbacks HTTP_PORT Define the listening port for the HTTP server 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3661 HTTP_SKT_RX_BUFF_SIZE Define the size of the RX buffer for the http socket Use 0 for default HTTP_SKT_TX_BUFF_SIZE Define the size of the TX buffer for the http socket Use 0 for default HTTP_SSL_ONLY_CHAR Files beginning with this character will only be served over HTTPS Set to 0x00 to require for all files Set to 0xff to require for no files HTTP_TIMEOUT Max time (sec) to await more data before timing out and disconnecting the socket HTTP_USE_AUTHENTICATION Enable basic authentication support HTTP_USE_COOKIES Enable cookie support HTTP_USE_POST Define which HTTP modules to use If not using a specific module, comment it to save resources Enable POST support HTTPS_DEFAULT_FILE Indicate what file to serve when no specific one is requested HTTPS_PORT Listening port for HTTPS server (when SSL enabled) TCPIP_STACK_USE_BASE64_DECODE TCPIP_STACK_USE_BASE64_DECODE HTTP_USE_AUTHENTICATION Description The configuration of the HTTP TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the HTTP TCP/IP Stack. Based on the selections made, the HTTP TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the HTTP TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.11.5.1 HTTP_CACHE_LEN Macro C #define HTTP_CACHE_LEN ("600") Description Max lifetime (sec) of static responses as string 5.8.11.5.2 HTTP_CONFIG_FLAGS Macro C #define HTTP_CONFIG_FLAGS 0 Description Define the HTTP module configuration flags Use 0 for default 5.8.11.5.3 HTTP_DEFAULT_FILE Macro C #define HTTP_DEFAULT_FILE "index.htm" Description Indicate what file to serve when no specific one is requested 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3662 5.8.11.5.4 HTTP_DEFAULT_LEN Macro C #define HTTP_DEFAULT_LEN (10u) Description For buffer overrun protection. Set to longest length of above two strings. 5.8.11.5.5 HTTP_FILE_UPLOAD Macro C #define HTTP_FILE_UPLOAD "mpfsupload" Description Configure MPFS over HTTP updating Comment this line to disable updating via HTTP 5.8.11.5.6 HTTP_MAX_CONNECTIONS Macro C #define HTTP_MAX_CONNECTIONS (4) Description Maximum numbers of simultaneous supported HTTP connections. 5.8.11.5.7 HTTP_MAX_DATA_LEN Macro C #define HTTP_MAX_DATA_LEN (100u) Description Define the maximum data length for reading cookie and GET/POST arguments (bytes) 5.8.11.5.8 HTTP_MAX_HEADER_LEN Macro C #define HTTP_MAX_HEADER_LEN (15u) Description Set to length of longest string above 5.8.11.5.9 HTTP_MIN_CALLBACK_FREE Macro C #define HTTP_MIN_CALLBACK_FREE (16u) Description Define the minimum number of bytes free in the TX FIFO before executing callbacks 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3663 5.8.11.5.10 HTTP_PORT Macro C #define HTTP_PORT (80u) Description Define the listening port for the HTTP server 5.8.11.5.11 HTTP_SKT_RX_BUFF_SIZE Macro C #define HTTP_SKT_RX_BUFF_SIZE 0 Description Define the size of the RX buffer for the http socket Use 0 for default 5.8.11.5.12 HTTP_SKT_TX_BUFF_SIZE Macro C #define HTTP_SKT_TX_BUFF_SIZE 0 Description Define the size of the TX buffer for the http socket Use 0 for default 5.8.11.5.13 HTTP_SSL_ONLY_CHAR Macro C #define HTTP_SSL_ONLY_CHAR (0xFF) Description Files beginning with this character will only be served over HTTPS Set to 0x00 to require for all files Set to 0xff to require for no files 5.8.11.5.14 HTTP_TIMEOUT Macro C #define HTTP_TIMEOUT (45u) Description Max time (sec) to await more data before timing out and disconnecting the socket 5.8.11.5.15 HTTP_USE_AUTHENTICATION Macro C #define HTTP_USE_AUTHENTICATION Description Enable basic authentication support 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3664 5.8.11.5.16 HTTP_USE_COOKIES Macro C #define HTTP_USE_COOKIES Description Enable cookie support 5.8.11.5.17 HTTP_USE_POST Macro C #define HTTP_USE_POST Description Define which HTTP modules to use If not using a specific module, comment it to save resources Enable POST support 5.8.11.5.18 HTTPS_DEFAULT_FILE Macro C #define HTTPS_DEFAULT_FILE "index.htm" Description Indicate what file to serve when no specific one is requested 5.8.11.5.19 HTTPS_PORT Macro C #define HTTPS_PORT (443u) Description Listening port for HTTPS server (when SSL enabled) 5.8.11.5.20 TCPIP_STACK_USE_BASE64_DECODE Macro C #define TCPIP_STACK_USE_BASE64_DECODE Description TCPIP_STACK_USE_BASE64_DECODE HTTP_USE_AUTHENTICATION 5.8.11.6 Library Interface Data Types and Constants Name Description HTTP_CONN_HANDLE HTTP connection identifier, handle of a HTTP connection HTTP_FILE_TYPE File type definitions HTTP_IO_RESULT Result states for execution callbacks 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3665 HTTP_MODULE_CONFIG HTTP module dynamic configuration data HTTP_MODULE_FLAGS HTTP module configuration flags HTTP_READ_STATUS Result states for HTTPPostReadName and HTTPPostReadValue HTTP_STATUS Supported Commands and Server Response Codes HTTPReadPostPair Reads a name and value pair from a URL encoded string in the TCP buffer. Functions Name Description TCPIP_HTTP_ActiveConnectionCountGet Gets the number of active connections. TCPIP_HTTP_ArgGet Locates a form field value in a given data array. TCPIP_HTTP_CurrentConnectionByteCountDec Decrements byte count. TCPIP_HTTP_CurrentConnectionByteCountGet Returns how many bytes have been read so far TCPIP_HTTP_CurrentConnectionByteCountSet Sets how many bytes have been read so far TCPIP_HTTP_CurrentConnectionCallbackPosGet Returns the callback position indicator. TCPIP_HTTP_CurrentConnectionCallbackPosSet Sets the callback position indicator. TCPIP_HTTP_CurrentConnectionDataBufferGet Returns pointer to connection general purpose data buffer. TCPIP_HTTP_CurrentConnectionFileGet Get handle to current connection's file. TCPIP_HTTP_CurrentConnectionHasArgsSet Sets whether there are get or cookie arguments TCPIP_HTTP_CurrentConnectionIsAuthorizedGet Get the authorized state for the current connection. TCPIP_HTTP_CurrentConnectionIsAuthorizedSet Sets the authorized state for the current connection. TCPIP_HTTP_CurrentConnectionPostSmGet Get the POST state machine state. TCPIP_HTTP_CurrentConnectionPostSmSet Set the POST state machine state. TCPIP_HTTP_CurrentConnectionSocketGet Get the socket for the current connection. TCPIP_HTTP_CurrentConnectionStatusSet Sets HTTP status. TCPIP_HTTP_CurrentConnectionUserDataGet Gets the user data parameter for the current connection. TCPIP_HTTP_CurrentConnectionUserDataSet Sets the user data parameter for the current connection. TCPIP_HTTP_FileInclude Writes a file byte-for-byte to the currently loaded TCP socket. TCPIP_HTTP_PostNameRead Reads a name from a URL encoded string in the TCP buffer. TCPIP_HTTP_PostValueRead Reads a value from a URL encoded string in the TCP buffer. TCPIP_HTTP_URLDecode Parses a string from URL encoding to plain-text. HTTPCheckAuth Performs validation on a specific user name and password. HTTPExecuteGet Processes GET form field variables and cookies. HTTPExecutePost Processes POST form variables and data. HTTPNeedsAuth Determines if a given file name requires authentication HTTPPrint_varname Inserts dynamic content into a web page Description This section describes the Application Programming Interface (API) functions of the HTTP TCP/IP Stack. Refer to each section for a detailed description. 5.8.11.6.1 Functions 5.8.11.6.1.1 TCPIP_HTTP_ActiveConnectionCountGet Function C int TCPIP_HTTP_ActiveConnectionCountGet(); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3666 Description Returns the number of active conenctions at the current time. Preconditions None Remarks The value returned by this function is informational only. The number of active connections changes dynamically. Example int nConns; nConns = TCPIP_HTTP_ActiveConnectionCountGet(); 5.8.11.6.1.2 TCPIP_HTTP_ArgGet Function C const uint8_t* TCPIP_HTTP_ArgGet( const uint8_t* cData, const uint8_t* cArg ); Description Searches through a data array to find the value associated with a given argument. It can be used to find form field values in data received over GET or POST. The end of data is assumed to be reached when a null name parameter is encountered. This requires the string to have an even number of null-terminated strings, followed by an additional null terminator. Preconditions The data array has a valid series of null terminated name/value pairs. Parameters Parameters Description data the buffer to search arg the name of the argument to find Returns A pointer to the argument value, or NULL if not found. Remarks None. Example void HTTPPrint_cookiename(HTTP_CONN_HANDLE connHandle) { const uint8_t *ptr; TCP_SOCKET sktHTTP; ptr = TCPIP_HTTP_ArgGet(TCPIP_HTTP_CurrentConnectionDataBufferGet(connHandle), (const uint8_t*)"name"); sktHTTP = TCPIP_HTTP_CurrentConnectionSocketGet(connHandle); if(ptr) TCPIP_TCP_StringPut(sktHTTP, ptr); else TCPIP_TCP_StringPut(sktHTTP, (const uint8_t*)"not set"); } 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3667 5.8.11.6.1.3 TCPIP_HTTP_CurrentConnectionByteCountDec Function C void TCPIP_HTTP_CurrentConnectionByteCountDec( HTTP_CONN_HANDLE connHandle, uint32_t byteCount ); Description Decrements byte count. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle byteCount byte count reduction Remarks None. Example 5.8.11.6.1.4 TCPIP_HTTP_CurrentConnectionByteCountGet Function C uint32_t TCPIP_HTTP_CurrentConnectionByteCountGet( HTTP_CONN_HANDLE connHandle ); Description Returns how many bytes have been read so far Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example switch(TCPIP_HTTP_CurrentConnectionPostSmGet(connHandle)) { case SM_CFG_SNMP_READ_NAME: // If all parameters have been read, end if(TCPIP_HTTP_CurrentConnectionByteCountGet(connHandle) == 0u) { return HTTP_IO_DONE; } . . . 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3668 } 5.8.11.6.1.5 TCPIP_HTTP_CurrentConnectionByteCountSet Function C void TCPIP_HTTP_CurrentConnectionByteCountSet( HTTP_CONN_HANDLE connHandle, uint32_t byteCount ); Description Sets how many bytes have been read so far Parameters Parameters Description connHandle HTTP connection handle byteCount byte count to be set Remarks None. Example 5.8.11.6.1.6 TCPIP_HTTP_CurrentConnectionCallbackPosGet Function C uint32_t TCPIP_HTTP_CurrentConnectionCallbackPosGet( HTTP_CONN_HANDLE connHandle ); Description Returns the callback position indicator for connection defined by connHandle. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example uint32_t callbackPos; callbackPos = TCPIP_HTTP_CurrentConnectionCallbackPosGet(connHandle); if(callbackPos == 0x00u) callbackPos = (uint32_t)DDNSClient.Host.szRAM; callbackPos = (uint32_t)TCPIP_TCP_StringPut(TCPIP_HTTP_CurrentConnectionSocketGet(connHandle), (uint8_t*)callbackPos); if(*(uint8_t*)callbackPos == '0') callbackPos = 0x00; TCPIP_HTTP_CurrentConnectionCallbackPosSet(connHandle, callbackPos); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3669 5.8.11.6.1.7 TCPIP_HTTP_CurrentConnectionCallbackPosSet Function C void TCPIP_HTTP_CurrentConnectionCallbackPosSet( HTTP_CONN_HANDLE connHandle, uint32_t ); Description Sets the callback position indicator for connection defined by connHandle. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example void HTTPPrint_builddate(HTTP_CONN_HANDLE connHandle) { TCP_SOCKET sktHTTP; sktHTTP = TCPIP_HTTP_CurrentConnectionSocketGet(connHandle); TCPIP_HTTP_CurrentConnectionCallbackPosSet(connHandle, 0x01); if(TCPIP_TCP_PutIsReady(sktHTTP) < strlen((const char*)__DATE__" "__TIME__)) { // Don't have room to output build date and time return; } TCPIP_HTTP_CurrentConnectionCallbackPosSet(connHandle, 0x00); TCPIP_TCP_StringPut(sktHTTP, (const void*)__DATE__" "__TIME__); } 5.8.11.6.1.8 TCPIP_HTTP_CurrentConnectionDataBufferGet Function C uint8_t* TCPIP_HTTP_CurrentConnectionDataBufferGet( HTTP_CONN_HANDLE connHandle ); Description Returns pointer to connection general purpose data buffer. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3670 Example void HTTPPrint_cookiename(HTTP_CONN_HANDLE connHandle) { const uint8_t *ptr; TCP_SOCKET sktHTTP; ptr = TCPIP_HTTP_ArgGet(TCPIP_HTTP_CurrentConnectionDataBufferGet(connHandle), (const uint8_t*)"name"); sktHTTP = TCPIP_HTTP_CurrentConnectionSocketGet(connHandle); if(ptr) TCPIP_TCP_StringPut(sktHTTP, ptr); else TCPIP_TCP_StringPut(sktHTTP, (const uint8_t*)"not set"); } 5.8.11.6.1.9 TCPIP_HTTP_CurrentConnectionFileGet Function C FILE_HANDLE TCPIP_HTTP_CurrentConnectionFileGet( HTTP_CONN_HANDLE connHandle ); Description Get handle to current connection's file. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example uint8_t filename[20]; // Load the file name // Make sure uint8_t filename[] above is large enough for your longest name MPFSGetFilename(TCPIP_HTTP_CurrentConnectionFileGet(connHandle), filename, 20); 5.8.11.6.1.10 TCPIP_HTTP_CurrentConnectionHasArgsSet Function C void TCPIP_HTTP_CurrentConnectionHasArgsSet( HTTP_CONN_HANDLE connHandle, bool args ); Description Sets whether there are get or cookie arguments Preconditions None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3671 Parameters Parameters Description connHandle HTTP connection handle args boolean if there arguments or not Remarks None. Example else if(!memcmp(filename, "cookies.htm", 11)) { // If it's the LED updater file TCPIP_HTTP_CurrentConnectionHasArgsSet(connHandle, true); } 5.8.11.6.1.11 TCPIP_HTTP_CurrentConnectionIsAuthorizedGet Function C uint8_t TCPIP_HTTP_CurrentConnectionIsAuthorizedGet( HTTP_CONN_HANDLE connHandle ); Description Get the authorization status for the current connection. Preconditions None Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example uint8_t isAuth; isAuth = TCPIP_HTTP_CurrentConnectionIsAuthorizedGet(connHandle); 5.8.11.6.1.12 TCPIP_HTTP_CurrentConnectionIsAuthorizedSet Function C void TCPIP_HTTP_CurrentConnectionIsAuthorizedSet( HTTP_CONN_HANDLE connHandle, uint8_t auth ); Description Sets the authorization status for the current connection. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3672 Parameters Parameters Description connHandle HTTP connection handle auth new authorization state Remarks None. Example uint8_t auth = 0x80; TCPIP_HTTP_CurrentConnectionIsAuthorizedSet(connHandle, auth); 5.8.11.6.1.13 TCPIP_HTTP_CurrentConnectionPostSmGet Function C int TCPIP_HTTP_CurrentConnectionPostSmGet( HTTP_CONN_HANDLE connHandle ); Description Get the POST state machine state for connection defined by connHandle Preconditions None Parameters Parameters Description connHandle HTTP connection handle Remarks None Example switch(TCPIP_HTTP_CurrentConnectionPostSmGet(connHandle)) { // Find the name case SM_POST_LCD_READ_NAME: . . . // Found the value, so store the LCD and return case SM_POST_LCD_READ_VALUE: . . . } 5.8.11.6.1.14 TCPIP_HTTP_CurrentConnectionPostSmSet Function C void TCPIP_HTTP_CurrentConnectionPostSmSet( HTTP_CONN_HANDLE connHandle, int state ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3673 Description Set the POST state machine state for connection defined by connHandle Preconditions None. Parameters Parameters Description connHandle HTTP connection handle state Integer state for POST state machine Remarks None Example uint8_t* httpDataBuff; switch(TCPIP_HTTP_CurrentConnectionPostSmGet(connHandle)) { // Find the name case SM_POST_LCD_READ_NAME: // Read a name if(TCPIP_HTTP_PostNameRead(connHandle, httpDataBuff, HTTP_MAX_DATA_LEN) == HTTP_READ_INCOMPLETE) return HTTP_IO_NEED_DATA; TCPIP_HTTP_CurrentConnectionPostSmSet(connHandle, SM_POST_LCD_READ_VALUE); // No break...continue reading value // Found the value, so store the LCD and return case SM_POST_LCD_READ_VALUE: . . . } 5.8.11.6.1.15 TCPIP_HTTP_CurrentConnectionSocketGet Function C TCP_SOCKET TCPIP_HTTP_CurrentConnectionSocketGet( HTTP_CONN_HANDLE connHandle ); Description Get the socket for the current connection. Preconditions None Parameters Parameters Description connHandle HTTP connection handle Remarks None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3674 Example uint32_t byteCount; TCP_SOCKET sktHTTP; byteCount = TCPIP_HTTP_CurrentConnectionByteCountGet(connHandle); sktHTTP = TCPIP_HTTP_CurrentConnectionSocketGet(connHandle); if(byteCount > TCPIP_TCP_GetIsReady(sktHTTP) + TCPIP_TCP_FifoRxFreeGet(sktHTTP)) { // Configuration Failure TCPIP_HTTP_CurrentConnectionStatusSet(connHandle, HTTP_REDIRECT); return HTTP_IO_DONE; } 5.8.11.6.1.16 TCPIP_HTTP_CurrentConnectionStatusSet Function C void TCPIP_HTTP_CurrentConnectionStatusSet( HTTP_CONN_HANDLE connHandle, HTTP_STATUS stat ); Description Sets HTTP status to value in enumeration HTTP_STATUS. Preconditions None. Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example byteCount = TCPIP_HTTP_CurrentConnectionByteCountGet(connHandle); sktHTTP = TCPIP_HTTP_CurrentConnectionSocketGet(connHandle); if(byteCount > TCPIP_TCP_GetIsReady(sktHTTP) + TCPIP_TCP_FifoRxFreeGet(sktHTTP)) { // Configuration Failure // 302 Redirect will be returned TCPIP_HTTP_CurrentConnectionStatusSet(connHandle, HTTP_REDIRECT); } 5.8.11.6.1.17 TCPIP_HTTP_CurrentConnectionUserDataGet Function C const void* TCPIP_HTTP_CurrentConnectionUserDataGet( HTTP_CONN_HANDLE connHandle ); Description Returns the value of the user parameter for the current connection. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3675 Parameters Parameters Description connHandle HTTP connection handle Remarks None. Example uint32_t myConnData; myConnData = (uint32_t)TCPIP_HTTP_CurrentConnectionUserDataGet(connHandle); 5.8.11.6.1.18 TCPIP_HTTP_CurrentConnectionUserDataSet Function C void TCPIP_HTTP_CurrentConnectionUserDataSet( HTTP_CONN_HANDLE connHandle, const void* uData ); Description Sets the user data value for the current connection. Preconditions None Parameters Parameters Description connHandle HTTP connection handle uData user supplied data Remarks None. Example uint32_t myConnData; TCPIP_HTTP_CurrentConnectionUserDataSet(connHandle, (const void*)myConnData); 5.8.11.6.1.19 TCPIP_HTTP_FileInclude Function C void TCPIP_HTTP_FileInclude( HTTP_CONN_HANDLE connHandle, const uint8_t* cFile ); Description Allows an entire file to be included as a dynamic variable, providing a basic templating system for HTML web pages. This reduces unneeded duplication of visual elements such as headers, menus, etc. When pHttpCon->callbackPos is 0, the file is opened and as many bytes as possible are written. The current position is then saved to pHttpCon->callbackPos and the file is closed. On subsequent calls, reading begins at the saved location and continues. Once the end of the input file is reached, pHttpCon->callbackPos is set back to 0 to indicate completion. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3676 Preconditions None Parameters Parameters Description cFile the name of the file to be sent Returns None Remarks Users should not call this function directly, but should instead add dynamic variables in the form of ~inc:filename.ext~ in their HTML code to include (for example) the file "filename.ext" at that specified location. The MPFS2 Generator utility will handle the rest. Example 5.8.11.6.1.20 TCPIP_HTTP_PostNameRead Function C HTTP_READ_STATUS TCPIP_HTTP_PostNameRead( HTTP_CONN_HANDLE connHandle, uint8_t* cData, uint16_t wLen ); Description Reads a name from a URL encoded string in the TCP buffer. This function is meant to be called from an HTTPExecutePost callback to facilitate easier parsing of incoming data. This function also prevents buffer overflows by forcing the programmer to indicate how many bytes are expected. At least 2 extra bytes are needed in cData over the maximum length of data expected to be read. This function will read until the next '=' character, which indicates the end of a name parameter. It assumes that the front of the buffer is the beginning of the name paramter to be read. This function properly updates pHttpCon->byteCount by decrementing it by the number of bytes read. It also removes the delimiting '=' from the buffer. Preconditions Front of TCP buffer is the beginning of a name parameter, and the rest of the TCP buffer contains a URL-encoded string with a name parameter terminated by a '=' character. Parameters Parameters Description connHandle HTTP connection handle cData where to store the name once it is read wLen how many bytes can be written to cData Return Values Return Values Description HTTP_READ_OK name was successfully read HTTP_READ_TRUNCTATED entire name could not fit in the buffer, so the value was truncated and data has been lost 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3677 HTTP_READ_INCOMPLETE entire name was not yet in the buffer, so call this function again later to retrieve Remarks None Example 5.8.11.6.1.21 TCPIP_HTTP_PostValueRead Function C HTTP_READ_STATUS TCPIP_HTTP_PostValueRead( HTTP_CONN_HANDLE connHandle, uint8_t* cData, uint16_t wLen ); Description Reads a value from a URL encoded string in the TCP buffer. This function is meant to be called from an HTTPExecutePost callback to facilitate easier parsing of incoming data. This function also prevents buffer overflows by forcing the programmer to indicate how many bytes are expected. At least 2 extra bytes are needed in cData above the maximum length of data expected to be read. This function will read until the next '&' character, which indicates the end of a value parameter. It assumes that the front of the buffer is the beginning of the value paramter to be read. If pHttpCon->byteCount indicates that all expected bytes are in the buffer, it assumes that all remaining data is the value and acts accordingly. This function properly updates pHttpCon->byteCount by decrementing it by the number of bytes read. The terminating '&' character is also removed from the buffer. Preconditions Front of TCP buffer is the beginning of a name parameter, and the rest of the TCP buffer contains a URL-encoded string with a name parameter terminated by a '=' character. Parameters Parameters Description connHandle HTTP connection handle cData where to store the value once it is read wLen how many bytes can be written to cData Return Values Return Values Description HTTP_READ_OK value was successfully read HTTP_READ_TRUNCTATED entire value could not fit in the buffer, so the value was truncated and data has been lost HTTP_READ_INCOMPLETE entire value was not yet in the buffer, so call this function again later to retrieve Remarks None Example 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3678 5.8.11.6.1.22 TCPIP_HTTP_URLDecode Function C uint8_t* TCPIP_HTTP_URLDecode( uint8_t* cData ); Description Parses a string from URL encoding to plain-text. The following conversions are made: ‘=’ to ‘0’, ‘&’ to ‘0’, ‘+’ to ‘ ‘, and “%xx” to a single hex byte. After completion, the data has been decoded and a null terminator signifies the end of a name or value. A second null terminator (or a null name parameter) indicates the end of all the data. Preconditions The data parameter is null terminated and has at least one extra byte free. Parameters Parameters Description cData The string which is to be decoded in place. Returns A pointer to the last null terminator in data, which is also the first free byte for new data. Remarks This function is called by the stack to parse GET arguments and cookie data. User applications can use this function to decode POST data, but first need to verify that the string is null-terminated. Example code> 5.8.11.6.1.23 HTTPCheckAuth Function C uint8_t HTTPCheckAuth( HTTP_CONN_HANDLE connHandle, uint8_t* cUser, uint8_t* cPass ); Description This function is implemented by the application developer in CustomHTTPApp.c. Its function is to determine if the user name and password supplied by the client are acceptable for this resource. The value of curHTTP.isAuthorized will be set to the previous return value of HTTPRequiresAuthorization. This callback function can check this value to determine if only specific user names or passwords will be accepted for this resource. Return values 0x80 - 0xff indicate that the credentials were accepted, while values from 0x00 to 0x79 indicate that authorization failed. While most applications will only use a single value to grant access, flexibility is provided to store multiple values in order to indicate which user (or user's group) logged in. The return value of this function is saved as curHTTP.isAuthorized, and will be available to future callbacks, including any of the HTTPExecuteGet, HTTPExecutePost, or HTTPPrint_varname callbacks. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3679 Preconditions None Parameters Parameters Description connHandle HTTP connection handle cUser the user name supplied by the client cPass the password supplied by the client Return Values Return Values Description <= 0x79 the credentials were rejected >= 0x80 access is granted for this connection Remarks This function is only called when an Authorization header is encountered. This function may NOT write to the TCP buffer. 5.8.11.6.1.24 HTTPExecuteGet Function C HTTP_IO_RESULT HTTPExecuteGet( HTTP_CONN_HANDLE connHandle ); Description This function is implemented by the application developer in CustomHTTPApp.c. Its purpose is to parse the data received from URL parameters (GET method forms) and cookies and perform any application-specific tasks in response to these inputs. Any required authentication has already been validated. When this function is called, curHTTP.data contains sequential name/value pairs of strings representing the data received. In this format, TCPIP_HTTP_ArgGet can be used to search for specific variables in the input. If data buffer space associated with this connection is required, curHTTP.data may be overwritten here once the application is done with the values. Any data placed there will be available to future callbacks for this connection, including HTTPExecutePost and any HTTPPrint_varname dynamic substitutions. This function may also issue redirections by setting curHTTP.data to the destination file name or URL, and curHTTP.httpStatus to HTTP_REDIRECT. Finally, this function may set cookies. Set curHTTP.data to a series of name/value string pairs (in the same format in which parameters arrive) and then set curHTTP.hasArgs equal to the number of cookie name/value pairs. The cookies will be transmitted to the browser, and any future requests will have those values available in curHTTP.data. Preconditions None Parameters Parameters Description connHandle HTTP connection handle 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3680 Return Values Return Values Description HTTP_IO_DONE application is done processing HTTP_IO_NEED_DATA this value may not be returned because more data will not become available HTTP_IO_WAITING the application is waiting for an asynchronous process to complete, and this function should be called again later Remarks This function is only called if variables are received via URL parameters or Cookie arguments. This function may NOT write to the TCP buffer. This function may service multiple HTTP requests simultaneously. Exercise caution when using global or static variables inside this routine. Use curHTTP.callbackPos or curHTTP.data for storage associated with individual requests. 5.8.11.6.1.25 HTTPExecutePost Function C HTTP_IO_RESULT HTTPExecutePost( HTTP_CONN_HANDLE connHandle ); Description This function is implemented by the application developer in CustomHTTPApp.c. Its purpose is to parse the data received from POST forms and perform any application-specific tasks in response to these inputs. Any required authentication has already been validated before this function is called. When this function is called, POST data will be waiting in the TCP buffer. curHTTP.byteCount will indicate the number of bytes remaining to be received before the browser request is complete. Since data is still in the TCP buffer, the application must call TCPIP_TCP_Get or TCPIP_TCP_ArrayGet in order to retrieve bytes. When this is done, curHTTP.byteCount MUST be updated to reflect how many bytes now remain. The functions TCPIP_TCP_Find, TCPFindString, and TCPIP_TCP_ArrayFind may be helpful to locate data in the TCP buffer. In general, data submitted from web forms via POST is URL encoded. The TCPIP_HTTP_URLDecode function can be used to decode this information back to a standard string if required. If data buffer space associated with this connection is required, curHTTP.data may be overwritten here once the application is done with the values. Any data placed there will be available to future callbacks for this connection, including HTTPExecutePost and any HTTPPrint_varname dynamic substitutions. Whenever a POST form is processed it is recommended to issue a redirect back to the browser, either to a status page or to the same form page that was posted. This prevents accidental duplicate submissions (by clicking refresh or back/forward) and avoids browser warnings about "resubmitting form data". Redirects may be issued to the browser by setting curHTTP.data to the destination file or URL, and curHTTP.httpStatus to HTTP_REDIRECT. Finally, this function may set cookies. Set curHTTP.data to a series of name/value string pairs (in the same format in which parameters arrive) and then set curHTTP.hasArgs equal to the number of cookie name/value pairs. The cookies will be transmitted to the browser, and any future requests will have those values available in curHTTP.data. Preconditions None Parameters Parameters Description connHandle HTTP connection handle 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3681 Return Values Return Values Description HTTP_IO_DONE application is done processing HTTP_IO_NEED_DATA more data is needed to continue, and this function should be called again later HTTP_IO_WAITING the application is waiting for an asynchronous process to complete, and this function should be called again later Remarks This function is only called when the request method is POST, and is only used when HTTP_USE_POST is defined. This method may NOT write to the TCP buffer. This function may service multiple HTTP requests simultaneously. Exercise caution when using global or static variables inside this routine. Use curHTTP.callbackPos or curHTTP.data for storage associated with individual requests. 5.8.11.6.1.26 HTTPNeedsAuth Function C uint8_t HTTPNeedsAuth( HTTP_CONN_HANDLE connHandle, uint8_t* cFile ); Description This function is implemented by the application developer in CustomHTTPApp.c. Its function is to determine if a file being requested requires authentication to view. The user name and password, if supplied, will arrive later with the request headers, and will be processed at that time. Return values 0x80 - 0xff indicate that authentication is not required, while values from 0x00 to 0x79 indicate that a user name and password are required before proceeding. While most applications will only use a single value to grant access and another to require authorization, the range allows multiple "realms" or sets of pages to be protected, with different credential requirements for each. The return value of this function is saved as curHTTP.isAuthorized, and will be available to future callbacks, including HTTPCheckAuth and any of the HTTPExecuteGet, HTTPExecutePost, or HTTPPrint_varname callbacks. Preconditions None Parameters Parameters Description connHandle HTTP connection handle cFile the name of the file being requested Return Values Return Values Description <= 0x79 valid authentication is required >= 0x80 access is granted for this connection Remarks This function may NOT write to the TCP buffer. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3682 5.8.11.6.1.27 HTTPPrint_varname Function C void HTTPPrint_varname( HTTP_CONN_HANDLE connHandle, uint16_t wParam1, uint16_t wParam2, ... ); Description Functions in this style are implemented by the application developer in CustomHTTPApp.c. These functions generate dynamic content to be inserted into web pages and other files returned by the HTTP server. Functions of this type are called when a dynamic variable is located in a web page. (ie, ~varname~ ) The name between the tilde '~' characters is appended to the base function name. In this example, the callback would be named HTTPPrint_varname. The function prototype is located in your project's http_print.h, which is automatically generated by the MPFS2 Utility. The prototype will have uint16_t parameters included for each parameter passed in the dynamic variable. For example, the variable "~myArray(2,6)~" will generate the prototype "void HTTPPrint_varname(uint16_t, uint16_t);". When called, this function should write its output directly to the TCP socket using any combination of TCPIP_TCP_PutIsReady, TCPIP_TCP_Put, TCPIP_TCP_ArrayPut, TCPIP_TCP_StringPut, TCPIP_TCP_ArrayPut, and TCPIP_TCP_StringPut. Before calling, the HTTP server guarantees that at least HTTP_MIN_CALLBACK_FREE bytes (defaults to 16 bytes) are free in the output buffer. If the function is writing less than this amount, it should simply write the data to the socket and return. In situations where a function needs to write more this amount, it must manage its output state using curHTTP.callbackPos. This value will be set to zero before the function is called. If the function is managing its output state, it must set this to a non-zero value before returning. Typically this is used to track how many bytes have been written, or how many remain to be written. If curHTTP.callbackPos is non-zero, the function will be called again when more buffer space is available. Once the callback completes, set this value back to zero to resume normal servicing of the request. Preconditions None Parameters Parameters Description connHandle HTTP connection handle wParam1 first parameter passed in the dynamic variable (if any) wParam2 second parameter passed in the dynamic variable (if any) ... additional parameters as necessary Returns None Remarks This function may service multiple HTTP requests simultaneously, especially when managing its output state. Exercise caution when using global or static variables inside this routine. Use curHTTP.callbackPos or curHTTP.data for storage associated with individual requests. 5.8.11.6.2 Data Types and Constants 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3683 5.8.11.6.2.1 HTTP_CONN_HANDLE Type C typedef const void* HTTP_CONN_HANDLE; Description HTTP connection identifier, handle of a HTTP connection 5.8.11.6.2.2 HTTP_FILE_TYPE Enumeration C typedef enum { HTTP_TXT = 0u, HTTP_HTM, HTTP_HTML, HTTP_CGI, HTTP_XML, HTTP_CSS, HTTP_GIF, HTTP_PNG, HTTP_JPG, HTTP_JAVA, HTTP_WAV, HTTP_UNKNOWN } HTTP_FILE_TYPE; Description File type definitions Members Members Description HTTP_TXT = 0u File is a text document HTTP_HTM File is HTML (extension .htm) HTTP_HTML File is HTML (extension .html) HTTP_CGI File is HTML (extension .cgi) HTTP_XML File is XML (extension .xml) HTTP_CSS File is stylesheet (extension .css) HTTP_GIF File is GIF image (extension .gif) HTTP_PNG File is PNG image (extension .png) HTTP_JPG File is JPG image (extension .jpg) HTTP_JAVA File is java (extension .java) HTTP_WAV File is audio (extension .wav) HTTP_UNKNOWN File type is unknown 5.8.11.6.2.3 HTTP_IO_RESULT Enumeration C typedef enum { HTTP_IO_DONE = 0u, HTTP_IO_NEED_DATA, HTTP_IO_WAITING } HTTP_IO_RESULT; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3684 Description Result states for execution callbacks Members Members Description HTTP_IO_DONE = 0u Finished with procedure HTTP_IO_NEED_DATA More data needed to continue, call again later HTTP_IO_WAITING Waiting for asynchronous process to complete, call again later 5.8.11.6.2.4 HTTP_MODULE_CONFIG Structure C typedef struct { uint16_t nConnections; uint16_t dataLen; uint16_t sktTxBuffSize; uint16_t sktRxBuffSize; uint16_t configFlags; } HTTP_MODULE_CONFIG; Description HTTP module dynamic configuration data Members Members Description uint16_t nConnections; number of http connections uint16_t dataLen; size of the data buffer for reading cookie and GET/POST arguments (bytes) uint16_t sktTxBuffSize; size of TX buffer for the associatted socket; leave 0 for default uint16_t sktRxBuffSize; size of RX buffer for the associatted socket; leave 0 for default uint16_t configFlags; a HTTP_MODULE_FLAGS value. 5.8.11.6.2.5 HTTP_MODULE_FLAGS Enumeration C typedef enum { HTTP_MODULE_FLAG_ADJUST_SKT_FIFOS = 0x01, HTTP_MODULE_FLAG_NO_DELAY = 0x02 } HTTP_MODULE_FLAGS; Description HTTP module configuration flags Members Members Description HTTP_MODULE_FLAG_ADJUST_SKT_FIFOS = 0x01 adjust corresponding socket FIFO at run time improves throughput when the socket buffers are small HTTP_MODULE_FLAG_NO_DELAY = 0x02 create the http sockets with NO-DELAY option it will flush data as soon as possible 5.8.11.6.2.6 HTTP_READ_STATUS Enumeration C typedef enum { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3685 HTTP_READ_OK = 0u, HTTP_READ_TRUNCATED, HTTP_READ_INCOMPLETE } HTTP_READ_STATUS; Description Result states for HTTPPostReadName and HTTPPostReadValue Members Members Description HTTP_READ_OK = 0u Read was successful HTTP_READ_TRUNCATED Buffer overflow prevented by truncating value HTTP_READ_INCOMPLETE Entire object is not yet in the buffer. Try again later. 5.8.11.6.2.7 HTTP_STATUS Enumeration C typedef enum { HTTP_GET = 0u, HTTP_POST, HTTP_BAD_REQUEST, HTTP_UNAUTHORIZED, HTTP_NOT_FOUND, HTTP_OVERFLOW, HTTP_INTERNAL_SERVER_ERROR, HTTP_NOT_IMPLEMENTED, HTTP_REDIRECT, HTTP_SSL_REQUIRED, HTTP_MPFS_FORM, HTTP_MPFS_UP, HTTP_MPFS_OK, HTTP_MPFS_ERROR } HTTP_STATUS; Description Supported Commands and Server Response Codes Members Members Description HTTP_GET = 0u GET command is being processed HTTP_POST POST command is being processed HTTP_BAD_REQUEST 400 Bad Request will be returned HTTP_UNAUTHORIZED 401 Unauthorized will be returned HTTP_NOT_FOUND 404 Not Found will be returned HTTP_OVERFLOW 414 Request-URI Too Long will be returned HTTP_INTERNAL_SERVER_ERROR 500 Internal Server Error will be returned HTTP_NOT_IMPLEMENTED 501 Not Implemented (not a GET or POST command) HTTP_REDIRECT 302 Redirect will be returned HTTP_SSL_REQUIRED 403 Forbidden is returned, indicating SSL is required HTTP_MPFS_FORM Show the MPFS Upload form HTTP_MPFS_UP An MPFS Upload is being processed HTTP_MPFS_OK An MPFS Upload was successful HTTP_MPFS_ERROR An MPFS Upload was not a valid image 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3686 5.8.11.6.2.8 HTTPReadPostPair Macro C #define HTTPReadPostPair(connHandle, cData, wLen) TCPIP_HTTP_PostValueRead(connHandle, cData, wLen) Description Reads a name and value pair from a URL encoded string in the TCP buffer. This function is meant to be called from an HTTPExecutePost callback to facilitate easier parsing of incoming data. This function also prevents buffer overflows by forcing the programmer to indicate how many bytes are expected. At least 2 extra bytes are needed in cData over the maximum length of data expected to be read. This function will read until the next '&' character, which indicates the end of a value parameter. It assumes that the front of the buffer is the beginning of the name paramter to be read. This function properly updates curHTTP.byteCount by decrementing it by the number of bytes read. It also removes the delimiting '&' from the buffer. Once complete, two strings will exist in the cData buffer. The first is the parameter name that was read, while the second is the associated value. Preconditions Front of TCP buffer is the beginning of a name parameter, and the rest of the TCP buffer contains a URL-encoded string with a name parameter terminated by a '=' character and a value parameter terminated by a '&'. Parameters Parameters Description connHandle HTTP connection handle cData where to store the name and value strings once they are read wLen how many bytes can be written to cData Return Values Return Values Description HTTP_READ_OK name and value were successfully read HTTP_READ_TRUNCTATED entire name and value could not fit in the buffer, so input was truncated and data has been lost HTTP_READ_INCOMPLETE entire name and value was not yet in the buffer, so call this function again later to retrieve Remarks This function is aliased to TCPIP_HTTP_PostValueRead, since they effectively perform the same task. The name is provided only for completeness. 5.8.11.7 Files Files Name Description http.h http_config.h HTTP configuration file 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3687 Description 5.8.11.7.1 http.h HTTP Headers for Microchip TCP/IP Stack Enumerations Name Description HTTP_FILE_TYPE File type definitions HTTP_IO_RESULT Result states for execution callbacks HTTP_MODULE_FLAGS HTTP module configuration flags HTTP_READ_STATUS Result states for HTTPPostReadName and HTTPPostReadValue HTTP_STATUS Supported Commands and Server Response Codes Functions Name Description HTTPCheckAuth Performs validation on a specific user name and password. HTTPExecuteGet Processes GET form field variables and cookies. HTTPExecutePost Processes POST form variables and data. HTTPNeedsAuth Determines if a given file name requires authentication HTTPPrint_varname Inserts dynamic content into a web page TCPIP_HTTP_ActiveConnectionCountGet Gets the number of active connections. TCPIP_HTTP_ArgGet Locates a form field value in a given data array. TCPIP_HTTP_CurrentConnectionByteCountDec Decrements byte count. TCPIP_HTTP_CurrentConnectionByteCountGet Returns how many bytes have been read so far TCPIP_HTTP_CurrentConnectionByteCountSet Sets how many bytes have been read so far TCPIP_HTTP_CurrentConnectionCallbackPosGet Returns the callback position indicator. TCPIP_HTTP_CurrentConnectionCallbackPosSet Sets the callback position indicator. TCPIP_HTTP_CurrentConnectionDataBufferGet Returns pointer to connection general purpose data buffer. TCPIP_HTTP_CurrentConnectionFileGet Get handle to current connection's file. TCPIP_HTTP_CurrentConnectionHasArgsSet Sets whether there are get or cookie arguments TCPIP_HTTP_CurrentConnectionIsAuthorizedGet Get the authorized state for the current connection. TCPIP_HTTP_CurrentConnectionIsAuthorizedSet Sets the authorized state for the current connection. TCPIP_HTTP_CurrentConnectionPostSmGet Get the POST state machine state. TCPIP_HTTP_CurrentConnectionPostSmSet Set the POST state machine state. TCPIP_HTTP_CurrentConnectionSocketGet Get the socket for the current connection. TCPIP_HTTP_CurrentConnectionStatusSet Sets HTTP status. TCPIP_HTTP_CurrentConnectionUserDataGet Gets the user data parameter for the current connection. TCPIP_HTTP_CurrentConnectionUserDataSet Sets the user data parameter for the current connection. TCPIP_HTTP_FileInclude Writes a file byte-for-byte to the currently loaded TCP socket. TCPIP_HTTP_PostNameRead Reads a name from a URL encoded string in the TCP buffer. TCPIP_HTTP_PostValueRead Reads a value from a URL encoded string in the TCP buffer. TCPIP_HTTP_URLDecode Parses a string from URL encoding to plain-text. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help HTTP Server TCP/IP Stack Library 5-3688 Macros Name Description HTTPReadPostPair Reads a name and value pair from a URL encoded string in the TCP buffer. Structures Name Description HTTP_MODULE_CONFIG HTTP module dynamic configuration data Types Name Description HTTP_CONN_HANDLE HTTP connection identifier, handle of a HTTP connection 5.8.11.7.2 http_config.h HyperText Transfer Protocol (HTTP) Configuration file This file contains the HTTP module configuration options Macros Name Description HTTP_CACHE_LEN Max lifetime (sec) of static responses as string HTTP_CONFIG_FLAGS Define the HTTP module configuration flags Use 0 for default HTTP_DEFAULT_FILE Indicate what file to serve when no specific one is requested HTTP_DEFAULT_LEN For buffer overrun protection. Set to longest length of above two strings. HTTP_FILE_UPLOAD Configure MPFS over HTTP updating Comment this line to disable updating via HTTP HTTP_MAX_CONNECTIONS Maximum numbers of simultaneous supported HTTP connections. HTTP_MAX_DATA_LEN Define the maximum data length for reading cookie and GET/POST arguments (bytes) HTTP_MAX_HEADER_LEN Set to length of longest string above HTTP_MIN_CALLBACK_FREE Define the minimum number of bytes free in the TX FIFO before executing callbacks HTTP_PORT Define the listening port for the HTTP server HTTP_SKT_RX_BUFF_SIZE Define the size of the RX buffer for the http socket Use 0 for default HTTP_SKT_TX_BUFF_SIZE Define the size of the TX buffer for the http socket Use 0 for default HTTP_SSL_ONLY_CHAR Files beginning with this character will only be served over HTTPS Set to 0x00 to require for all files Set to 0xff to require for no files HTTP_TIMEOUT Max time (sec) to await more data before timing out and disconnecting the socket HTTP_USE_AUTHENTICATION Enable basic authentication support HTTP_USE_COOKIES Enable cookie support HTTP_USE_POST Define which HTTP modules to use If not using a specific module, comment it to save resources Enable POST support HTTPS_DEFAULT_FILE Indicate what file to serve when no specific one is requested HTTPS_PORT Listening port for HTTPS server (when SSL enabled) TCPIP_STACK_USE_BASE64_DECODE TCPIP_STACK_USE_BASE64_DECODE HTTP_USE_AUTHENTICATION 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3689 5.8.12 ICMP TCP/IP Stack Library 5.8.12.1 Introduction Internet Control Message Protocol (ICMP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the ICMP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Internet Control Message Protocol is used to send error and status messages and requests. The ICMP module implements the Echo Reply message type (commonly referred to as a ping) which can be used to determine if a specified host is reachable across an IP network from a device running the TCP/IP stack. An ICMP server is also supported to respond to pings from other devices. 5.8.12.2 Release Notes MPLAB Harmony Version: v0.70b ICMP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.12.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3690 MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.12.4 Using the Library This topic describes the basic architecture of the ICMP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: icmp.h The interface to the ICMP TCP/IP Stack library is defined in the "icmp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the ICMP TCP/IP Stack library should include "tcpip.h". Library File: The ICMP TCP/IP Stack library archive (.a) file is installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.12.4.1 Abstraction Model This library provides the API of the ICMP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description ICMP Software Abstraction Block Diagram 5.8.12.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the ICMP module. Library Interface Section Description Functions This section provides general interface routines Data Types and Constants This section provides various definitions describing this API 5.8.12.5 Configuring the Library Macros Name Description ICMP_TIMEOUT ICMP Timeout Value 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3691 Description The configuration of the ICMP TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the ICMP TCP/IP Stack. Based on the selections made, the ICMP TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the ICMP TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.12.5.1 ICMP_TIMEOUT Macro C #define ICMP_TIMEOUT (4ul*SYS_TICK_TicksPerSecondGet()) Description ICMP Timeout Value 5.8.12.6 Building the Library This section list the files that are available in the \src of the ICMP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.12.7 Library Interface Data Types and Constants Name Description ICMP_ECHO_RESULT result of an ICMPSendEchoRequest call ICMP_HANDLE a handle that a client can use after the event handler has been registered ICMP_MODULE_CONFIG Provides a placeholder for ICMP module configuration. Functions Name Description TCPIP_ICMP_CallbackDeregister De-registers the ICMP callback function. TCPIP_ICMP_CallbackRegister Registers a callback to allow the application layer to process incoming ICMPv4 packets TCPIP_ICMP_EchoRequestSend Sends an ICMP echo request to a remote node. Description This section describes the Application Programming Interface (API) functions of the ICMP TCP/IP Stack. Refer to each section for a detailed description. 5.8.12.7.1 Functions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3692 5.8.12.7.1.1 TCPIP_ICMP_CallbackDeregister Function C bool TCPIP_ICMP_CallbackDeregister( ICMP_HANDLE hIcmp ); Description This function a stack client to remove its former registered notification handler. After this operation the client will no longer be notified about the receiving of replies to the ICMP requests. Preconditions TCPIP Stack initialized, up and running. A previous successful call to TCPIP_ICMP_CallbackRegister() has been done. Parameters Parameters Description hIcmp an ICMP handle obtained by TCPIP_ICMP_CallbackRegister() Returns true - if the notification handler has been successfully removed false - if such notification handler couldn't be found Remarks None Example void MyICMPCallbackFunction(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data); ICMP_HANDLE hIcmp = TCPIP_ICMP_CallbackRegister(&MyICMPCallbackFunction); if(hIcmp != 0) { // successfully registered my handler // send requests and process the incoming results // ... // later on, once ew're done, remove the notification handler TCPIP_ICMP_CallbackDeregister(hIcmp); } 5.8.12.7.1.2 TCPIP_ICMP_CallbackRegister Function C ICMP_HANDLE TCPIP_ICMP_CallbackRegister( void (*callback)(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data) ); Description Allows a stack client to be notified of the receiving of a response from an ICMP query. Once an Echo request reply is received, the notification handler callback will be called, letting the client know of the result of the query. The callback will contain as parameters: • the network interface handle on which the query reply was received • the remote host IP address • a 32 bit value containing the sequence number in the low 16 bit part and the identifier value in th ehigh 16 bit part. Preconditions TCPIP Stack initialized, up and running. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3693 Parameters Parameters Description callback notification function to be registered This function will be called when an echo request reply is received. Returns • A non-null handle if the registration succeeded • 0 if the registration operation failed (out of memory, for example). Remarks None Example // Callback function prototype void MyICMPCallbackFunction(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data); // ***************************************************************************** // Register callback function ICMP_HANDLE hIcmp = TCPIP_ICMP_CallbackRegister(&MyICMPCallbackFunction); if(hIcmp == 0) { // process error; couldn't register a handler } // success; I can send an Echo request an receive notification // ***************************************************************************** IPV4_ADDR remoteIP = 0xc0a00101; uint16_t mySequenceNumber = 1; uint16_t myId = 0x1234; // send an ICMP query request TCPIP_ICMP_EchoRequestSend(&remoteIP, mySequenceNumber, myId; // ***************************************************************************** // process the ICMP reply in the callback function void MyICMPCallbackFunction(TCPIP_NET_HANDLE hNetIf, IPV4_ADDR * remoteIP, void * data) { // process request from interface hNetIf and remoteIP address uint16_t* pReply = (uint16_t*)data; uint16_t myRecvId = *pReply; uint16_t myRecvSequenceNumber = *(pReply + 1); // check that the sequence number, ID and IP address match, etc. } 5.8.12.7.1.3 TCPIP_ICMP_EchoRequestSend Function C ICMP_ECHO_RESULT TCPIP_ICMP_EchoRequestSend( IPV4_ADDR * targetAddr, uint16_t sequenceNumber, uint16_t identifier ); Description This function allows a stack client to send an ICMP query message to a remote host. The supplied sequence number and identifier will be used in the query message. The user will be notified by the result of the query using a notification handle registered by using the TCPIP_ICMP_CallbackRegister function. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3694 Preconditions TCPIP Stack initialized, up and running. Parameters Parameters Description targetAddr remote host IP address. Returns true - if the query request was successfully sent false otherwise (interface not ready for transmission) Remarks None Example IPV4_ADDR remoteAddress = 0xc0a00101; uint16_t mySequenceNumber = 1; uint16_t myId = 0x1234; if(TCPIP_ICMP_EchoRequestSend(&remoteAddress, mySequenceNumber, myId) ) { // successfully sent the ICMP request // } else { // process the error } 5.8.12.7.2 Data Types and Constants 5.8.12.7.2.1 ICMP_ECHO_RESULT Enumeration C typedef enum { ICMP_ECHO_OK = 0, ICMP_ECHO_ALLOC_ERROR = -1, ICMP_ECHO_ROUTE_ERROR = -2, ICMP_ECHO_TRANSMIT_ERROR = -3 } ICMP_ECHO_RESULT; Description result of an ICMPSendEchoRequest call Members Members Description ICMP_ECHO_OK = 0 operation successful error codes, < 0 ICMP_ECHO_ALLOC_ERROR = -1 could not allocate memory ICMP_ECHO_ROUTE_ERROR = -2 could not find a route to destination ICMP_ECHO_TRANSMIT_ERROR = -3 could not transmit (dead interface, etc.) 5.8.12.7.2.2 ICMP_HANDLE Type C typedef const void* ICMP_HANDLE; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3695 Description a handle that a client can use after the event handler has been registered 5.8.12.7.2.3 ICMP_MODULE_CONFIG Structure C typedef struct { } ICMP_MODULE_CONFIG; Description ICMP Module Configuration Structure Typedef Provides a placeholder for ICMP module configuration. Remarks None. 5.8.12.8 Files Files Name Description icmp.h icmp_config.h ICMP configuration file Description 5.8.12.8.1 icmp.h ICMP Module Defs for Microchip TCP/IP Stack Enumerations Name Description ICMP_ECHO_RESULT result of an ICMPSendEchoRequest call Functions Name Description TCPIP_ICMP_CallbackDeregister De-registers the ICMP callback function. TCPIP_ICMP_CallbackRegister Registers a callback to allow the application layer to process incoming ICMPv4 packets TCPIP_ICMP_EchoRequestSend Sends an ICMP echo request to a remote node. Structures Name Description ICMP_MODULE_CONFIG Provides a placeholder for ICMP module configuration. Types Name Description ICMP_HANDLE a handle that a client can use after the event handler has been registered 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMP TCP/IP Stack Library 5-3696 5.8.12.8.2 icmp_config.h Internet Control Message Protocol (ICMP) Configuration file This file contains the ICMP module configuration options Macros Name Description ICMP_TIMEOUT ICMP Timeout Value 5.8.13 ICMPv6 TCP/IP Stack Library 5.8.13.1 Introduction ICMPv6 TCP/IP Library for Microchip Microcontrollers This library provides the API of the ICMPv6 TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description This document specifies a set of APIs of Internet Control Message Protocol (ICMP) messages for use with version 6 of the Internet Protocol (IPv6). The Internet Protocol, version 6 (IPv6) is a new version of IP, uses the Internet Control Message Protocol (ICMP) as defined for IPv4 [RFC-792], with a number of changes. It is called ICMPv6, and has an IPv6 Next Header value of 58. ICMPv6 messages are used by IPv6 nodes to report error messages and information messages. ICMPv6 is also used for Ipv6 node diagnostic (i.e., IPv6 ping). The ICMPv6 protocol also provides a framework for the following: Neighbor Discovery Neighbor Discovery is a series of five ICMPv6 messages that manage node-to-node communication on a link. Neighbor Discovery replaces Address Resolution Protocol (ARP), ICMP(IPv4) Router Discovery, and the ICMP(IPv4) Redirect message. Multicast Listener Discovery (MLD) Multicast Listener Discovery is a series of three ICMP messages that manage subnet multicast membership. Multicast Listener Discovery replaces version 2 of the Internet Group Management Protocol (IGMP) for IPv4. Path MTU Discovery The maximum transmission unit (MTU) for a path is the minimum link MTU of all links on a path between a source and a destination. IPv6 packets that are smaller than the path MTU do not require fragmentation by the host and are successfully forwarded by all routers on the path. To discover the path MTU, the sending host uses the receipt of ICMPv6 Packet Too Big 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3697 messages. ICMPv6 Common Messages Functions Echo Request Sent to check IPv6 connectivity to a particular host. Echo Reply Sent in response to an ICMPv6 Echo Request. Destination Unreachable Sent by a router or the destination host to inform the sending host that the packet or payload cannot be delivered. Packet to big Sent by a router to inform a sending host that a packet is too large to forward. Time exceeded Sent by a router to inform a sending host that the Hop Limit of an IPv6 packet has expired. Parameter Problem Sent by a router to inform a sending host that an error was encountered in processing the IPv6 header or an IPv6 extension header. 5.8.13.2 Release Notes MPLAB Harmony Version: v0.70b ICMPv6 TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.13.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.13.4 Using the Library This topic describes the basic architecture of the ICMPv6 TCP/IP Library and provides information and examples on how to use it. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3698 Interface Header File: icmpv6.h The interface to the ICMPv6 TCP/IP library is defined in the "icmpv6.h" header file. Any C language source (.c) file that uses the ICMPv6 TCP/IP library should include "IPv6.h , icmpv6.h and ndp.h". Library File: The IP TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCPIP Stack interacts with the framework. 5.8.13.4.1 Abstraction Model This library provides the API of the ICMPv6 TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description ICMPv6 Software Abstraction Block Diagram This module provides software abstraction of the IPv6 module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. IPv6 Block Diagram ICMPv6 message communication 5.8.13.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the IPv6 and ICMPv6 module. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3699 Library Interface Section Description Functions This section provides general interface routines Data Types and Constants This section provides various definitions describing this API 5.8.13.5 Configuring the Library Macros Name Description ICMPV6_TIMEOUT ICMPv6 Timeout Value Description The configuration of the ICMPv6 TCP/IP Stack is based on the file icmpv6_config.h This header file contains the configuration selection for the ICMPv6 TCP/IP Stack. Based on the selections made, the ICMPv6 TCP/IP Stack IP will support or not support selected features. These configuration settings will apply to all instances of the ICMPv6 TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. 5.8.13.5.1 ICMPV6_TIMEOUT Macro C #define ICMPV6_TIMEOUT (4ul*SYS_TICK_ResolutionGet()) Description ICMPv6 Timeout Value 5.8.13.6 Building the Library This section list the files that are available in the \src of the IPv6 and ICMPv6 driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • ipv6.c • icmpv6.c • ndp.c TCPIP_STACK_USE_IPV6 is enabled from tcpip_config.h . 5.8.13.7 Library Interface Data Types and Constants Name Description ICMPV6_ERR_PTB_CODE Definition for ICMPv6 Packet Too Big error code ICMPV6_INFO_EREQ_CODE Definition for ICMPv6 Packet Echo Request info code ICMPV6_INFO_ERPL_CODE Definition for ICMPv6 Packet Echo Reply info code 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3700 TCPIP_ICMPV6_PutHeaderEchoReply This is macro TCPIP_ICMPV6_PutHeaderEchoReply. ICMPV6_ERR_DU_CODE Definitions for ICMPv6 Destination Unreachable error code ICMPV6_ERR_PP_CODE Definitions for ICMPv6 Parameter Problem error code ICMPV6_ERR_TE_CODE Definitions for ICMPv6 Time Exceeded error code ICMPV6_HANDLE a handle that a client can use after the event handler has been registered ICMPV6_HEADER_ECHO Header for an ICMPv6 Echo Request/Reply packet ICMPV6_HEADER_ERROR Header for an ICMPv6 Error packet ICMPV6_PACKET_TYPES ICMPv6 packet types Functions Name Description TCPIP_ICMPV6_CallbackDeregister Deregisters an upper-layer function from ICMPv6 callback. TCPIP_ICMPV6_CallbackRegister Registers an upper-layer function for ICMPv6 callback. TCPIP_ICMPV6_Close This is function TCPIP_ICMPV6_Close. TCPIP_ICMPV6_Flush Flushes an ICMPv6 Packet TCPIP_ICMPV6_HeaderEchoRequestPut Allocates a packet, IPv6 Header, and Upper-layer header for an ICMPv6 echo request. Description This section describes the Application Programming Interface (API) functions of the ICMPv6 TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.13.7.1 Functions 5.8.13.7.1.1 TCPIP_ICMPV6_CallbackDeregister Function C bool TCPIP_ICMPV6_CallbackDeregister( ICMPV6_HANDLE hIcmpv6 ); Description deregisters an upper-layer function from the ICMPv6 register list. Preconditions None Parameters Parameters Description hIcmpv6 ICMPv6 handler Returns true or false Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3701 5.8.13.7.1.2 TCPIP_ICMPV6_CallbackRegister Function C ICMPV6_HANDLE TCPIP_ICMPV6_CallbackRegister( void (*callback)(TCPIP_NET_HANDLE hNetIf, uint8_t type, IPV6_ADDR * localIP, IPV6_ADDR * remoteIP, void * header) ); Description Registers an upper-layer function to handle ICMPv6 messages that may require action at the application layer (Echo Replies, Error messages) Preconditions None Parameters Parameters Description type ICMPv6 header type localIP IPv6 destination address of the incoming message remoteIP IPv6 address of the node that originated the incoming message header Pointer to the ICMPv6 header Returns A ICMPV6_HANDLE Remarks None 5.8.13.7.1.3 TCPIP_ICMPV6_Close Function C void TCPIP_ICMPV6_Close( IPV6_PACKET * pkt ); Description This is function TCPIP_ICMPV6_Close. 5.8.13.7.1.4 TCPIP_ICMPV6_Flush Function C bool TCPIP_ICMPV6_Flush( IPV6_PACKET * pkt ); Description Flushes an ICMPv6 Packet Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3702 Parameters Parameters Description pkt The packet to flush Returns true if the packet was flushed, false if the packet was queued Remarks None 5.8.13.7.1.5 TCPIP_ICMPV6_HeaderEchoRequestPut Function C IPV6_PACKET * TCPIP_ICMPV6_HeaderEchoRequestPut( TCPIP_NET_HANDLE hNetIf, IPV6_ADDR * localIP, IPV6_ADDR * remoteIP, uint8_t type, uint16_t identifier, uint16_t sequenceNumber ); Description Allocates a packet, IPv6 Header, and Upper-layer header for an ICMPv6 echo request. Preconditions None Parameters Parameters Description pNetIf The interface for the outgoing packet. localIP The local address that should be used for this packet. remoteIP The packet's destination address type Echo Request or Echo Reply identifier The Echo Request id. sequenceNumber The Echo request sequence number Returns IPV6_PACKET * - The constructed error packet or NULL Remarks None 5.8.13.7.2 Data Types and Constants 5.8.13.7.2.1 ICMPV6_ERR_PTB_CODE Macro C #define ICMPV6_ERR_PTB_CODE 0u 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3703 Description Definition for ICMPv6 Packet Too Big error code 5.8.13.7.2.2 ICMPV6_INFO_EREQ_CODE Macro C #define ICMPV6_INFO_EREQ_CODE 0u Description Definition for ICMPv6 Packet Echo Request info code 5.8.13.7.2.3 ICMPV6_INFO_ERPL_CODE Macro C #define ICMPV6_INFO_ERPL_CODE 0u Description Definition for ICMPv6 Packet Echo Reply info code 5.8.13.7.2.4 TCPIP_ICMPV6_PutHeaderEchoReply Macro C #define TCPIP_ICMPV6_PutHeaderEchoReply TCPIP_ICMPV6_HeaderEchoRequestPut Description This is macro TCPIP_ICMPV6_PutHeaderEchoReply. 5.8.13.7.2.5 ICMPV6_ERR_DU_CODE Enumeration C typedef enum { ICMPV6_ERR_DU_NO_ROUTE = 0u, ICMPV6_ERR_DU_PROHIBITED = 1u, ICMPV6_ERR_DU_OUTSIDE_SCOPE = 2u, ICMPV6_ERR_DU_ADDR_UNREACHABLE = 3u, ICMPV6_ERR_DU_PORT_UNREACHABLE = 4u, ICMPV6_ERR_DU_SRC_FAILED_INGRESS_POLICY = 5u, ICMPV6_ERR_DU_REJECT_ROUTE = 6u } ICMPV6_ERR_DU_CODE; Description Definitions for ICMPv6 Destination Unreachable error code Members Members Description ICMPV6_ERR_DU_NO_ROUTE = 0u No route to destination ICMPV6_ERR_DU_PROHIBITED = 1u Communication with destination administratively prohibited ICMPV6_ERR_DU_OUTSIDE_SCOPE = 2u Beyond scope of source address ICMPV6_ERR_DU_ADDR_UNREACHABLE = 3u Address unreachable ICMPV6_ERR_DU_PORT_UNREACHABLE = 4u Port unreachable 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3704 ICMPV6_ERR_DU_SRC_FAILED_INGRESS_POLICY = 5u Source address failed ingress/egress policy ICMPV6_ERR_DU_REJECT_ROUTE = 6u Reject route to destination 5.8.13.7.2.6 ICMPV6_ERR_PP_CODE Enumeration C typedef enum { ICMPV6_ERR_PP_ERRONEOUS_HEADER = 0u, ICMPV6_ERR_PP_UNRECOGNIZED_NEXT_HEADER = 1u, ICMPV6_ERR_PP_UNRECOGNIZED_IPV6_OPTION = 2u } ICMPV6_ERR_PP_CODE; Description Definitions for ICMPv6 Parameter Problem error code Members Members Description ICMPV6_ERR_PP_ERRONEOUS_HEADER = 0u Erroneous header field encountered ICMPV6_ERR_PP_UNRECOGNIZED_NEXT_HEADER = 1u Unrecognized Next Header type encountered ICMPV6_ERR_PP_UNRECOGNIZED_IPV6_OPTION = 2u Unrecognized IPv6 option encountered 5.8.13.7.2.7 ICMPV6_ERR_TE_CODE Enumeration C typedef enum { ICMPV6_ERR_TE_HOP_LIMIT_EXCEEDED = 0u, ICMPV6_ERR_TE_FRAG_ASSEMBLY_TIME_EXCEEDED = 1u } ICMPV6_ERR_TE_CODE; Description Definitions for ICMPv6 Time Exceeded error code Members Members Description ICMPV6_ERR_TE_HOP_LIMIT_EXCEEDED = 0u Hop limit exceeded in transit ICMPV6_ERR_TE_FRAG_ASSEMBLY_TIME_EXCEEDED = 1u Fragment reassembly time exceeded 5.8.13.7.2.8 ICMPV6_HANDLE Type C typedef const void* ICMPV6_HANDLE; Description a handle that a client can use after the event handler has been registered 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3705 5.8.13.7.2.9 ICMPV6_HEADER_ECHO Structure C typedef struct { uint8_t vType; uint8_t vCode; uint16_t wChecksum; uint16_t identifier; uint16_t sequenceNumber; } ICMPV6_HEADER_ECHO; Description Header for an ICMPv6 Echo Request/Reply packet Members Members Description uint8_t vType; icmpV6 request or reply type uint8_t vCode; Erro code uint16_t wChecksum; Packet TX and RX checksum uint16_t identifier; incoming and outgoing packet identifier uint16_t sequenceNumber; request and reply sequence number 5.8.13.7.2.10 ICMPV6_HEADER_ERROR Structure C typedef struct { uint8_t vType; uint8_t vCode; uint16_t wChecksum; uint32_t additionalData; } ICMPV6_HEADER_ERROR; Description Header for an ICMPv6 Error packet Members Members Description uint8_t vType; icmpV6 request or reply type uint8_t vCode; error code uint16_t wChecksum; Packet TX and RX checksum uint32_t additionalData; Unused for Dest. Unreachable and Time Exceeded. MTU for MTU. Pointer for Parameter Problem. 5.8.13.7.2.11 ICMPV6_PACKET_TYPES Enumeration C typedef enum { ICMPV6_ERROR_DEST_UNREACHABLE = 1u, ICMPV6_ERROR_PACKET_TOO_BIG = 2u, ICMPV6_ERROR_TIME_EXCEEDED = 3u, ICMPV6_ERROR_PARAMETER_PROBLEM = 4u, ICMPV6_INFO_ECHO_REQUEST = 128u, ICMPV6_INFO_ECHO_REPLY = 129u, ICMPV6_INFO_ROUTER_SOLICITATION = 133u, ICMPV6_INFO_ROUTER_ADVERTISEMENT = 134u, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3706 ICMPV6_INFO_NEIGHBOR_SOLICITATION = 135u, ICMPV6_INFO_NEIGHBOR_ADVERTISEMENT = 136u, ICMPV6_INFO_REDIRECT = 137u } ICMPV6_PACKET_TYPES; Description ICMPv6 packet types Members Members Description ICMPV6_ERROR_DEST_UNREACHABLE = 1u Destination Unreachable error packet ICMPV6_ERROR_PACKET_TOO_BIG = 2u Packet Too Big error packet ICMPV6_ERROR_TIME_EXCEEDED = 3u Time Exceeded error packet ICMPV6_ERROR_PARAMETER_PROBLEM = 4u Parameter Problem error packet ICMPV6_INFO_ECHO_REQUEST = 128u Echo Request packet ICMPV6_INFO_ECHO_REPLY = 129u Echo Reply packet ICMPV6_INFO_ROUTER_SOLICITATION = 133u Router solicitation NDP packet ICMPV6_INFO_ROUTER_ADVERTISEMENT = 134u Router advertisement NDP packet ICMPV6_INFO_NEIGHBOR_SOLICITATION = 135u Neighbor Solicitation NDP packet ICMPV6_INFO_NEIGHBOR_ADVERTISEMENT = 136u Neighbor Advertisement NDP packet ICMPV6_INFO_REDIRECT = 137u Redirect NDP packet 5.8.13.8 Files Files Name Description icmpv6.h IPv6 Internet Communication Message Protocol icmpv6_config.h ICMPv6 configuration file Description 5.8.13.8.1 icmpv6.h Internet Control Message Protocol (ICMP) in IPv6 functions the same as ICMP in IPv4.ICMPv6 is used to report error messages and information messages for IPv6 nodes. ICMP packets in IPv6 are used in the IPv6 neighbor discovery process, path MTU discovery, and the Multicast Listener Discovery (MLD) protocol for IPv6. Enumerations Name Description ICMPV6_ERR_DU_CODE Definitions for ICMPv6 Destination Unreachable error code ICMPV6_ERR_PP_CODE Definitions for ICMPv6 Parameter Problem error code ICMPV6_ERR_TE_CODE Definitions for ICMPv6 Time Exceeded error code 5.8 TCP/IP Stack Library Help MPLAB Harmony Help ICMPv6 TCP/IP Stack Library 5-3707 ICMPV6_PACKET_TYPES ICMPv6 packet types Functions Name Description TCPIP_ICMPV6_CallbackDeregister Deregisters an upper-layer function from ICMPv6 callback. TCPIP_ICMPV6_CallbackRegister Registers an upper-layer function for ICMPv6 callback. TCPIP_ICMPV6_Close This is function TCPIP_ICMPV6_Close. TCPIP_ICMPV6_Flush Flushes an ICMPv6 Packet TCPIP_ICMPV6_HeaderEchoRequestPut Allocates a packet, IPv6 Header, and Upper-layer header for an ICMPv6 echo request. Macros Name Description ICMPV6_ERR_PTB_CODE Definition for ICMPv6 Packet Too Big error code ICMPV6_INFO_EREQ_CODE Definition for ICMPv6 Packet Echo Request info code ICMPV6_INFO_ERPL_CODE Definition for ICMPv6 Packet Echo Reply info code TCPIP_ICMPV6_PutHeaderEchoReply This is macro TCPIP_ICMPV6_PutHeaderEchoReply. Structures Name Description ICMPV6_HEADER_ECHO Header for an ICMPv6 Echo Request/Reply packet ICMPV6_HEADER_ERROR Header for an ICMPv6 Error packet Types Name Description ICMPV6_HANDLE a handle that a client can use after the event handler has been registered File Name icmpv6.h Company Microchip Technology Incorporated 5.8.13.8.2 icmpv6_config.h Internet Control Message Protocol for IPv6 (ICMPv6) Configuration file This file contains the ICMPv6 module configuration options Macros Name Description ICMPV6_TIMEOUT ICMPv6 Timeout Value 5.8.14 IPv4 TCP/IP Stack Library 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3708 5.8.14.1 Introduction Internet Protocol (IP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the IP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description IP is the workhorse protocol of the TCP/IP protocol suite. All TCP, UDP, ICMP, and IGMP data gets transmitted as IP datagrams (Figure 1.4). IP provides an unreliable, connectionless datagram delivery service. IP provides a best effort service. When something goes wrong, such as a router temporarily running out of buffers, IP has a simple error handling algorithm: throw away the datagram and try to send an ICMP message back to the source. Any required reliability must be provided by the upper layers (e.g., TCP). The term connectionless means that IP does not maintain any state information about successive datagrams. Each datagram is handled independently from all other datagrams. This also means that IP datagrams can get delivered out of order. If a source sends two consecutive datagrams (first A, then B) to the same destination, each is routed independently and can take different routes, with B arriving before A. 5.8.14.2 Release Notes MPLAB Harmony Version: v0.70b IPv4 TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.14.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3709 To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.14.4 Using the Library This topic describes the basic architecture of the IP TCPIP Stack Library and provides information and examples on how to use it. Interface Header File: ip.h The interface to the IPv4 TCP/IP Stack library is defined in the "ip.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the IPv4 TCP/IP Stack library should include "tcpip.h". Library File: The IPv4 TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.14.4.1 Abstraction Model This library provides the API of the IPv4 TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description IPv4 Software Abstraction Block Diagram This module provides software abstraction of the IPv4 module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. Note: This diagram was not available at time of release and will be added in a future version of MPLAB Harmony. 5.8.14.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the IP module. Library Interface Section Description Functions Routines for configuring IPv4 Data Types and Constants This section provides various definitions describing this API 5.8.14.5 Configuring the Library Macros Name Description IP_DEFAULT_ALLOCATION_BLOCK_SIZE Used to configure payload size IPV4_QUEUED_PACKET_LIMIT This option defines the maximum number of queued IPv4 TX packets. If an additional packet is queued, the oldest packet in the queue will be removed. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3710 IPV4_QUEUED_PACKET_TIMEOUT This option defines the number of seconds an IPv4 TX packet will remain in the queue before being timed out IPV4_TASK_PROCESS_RATE default 1 second Description The configuration of the IPv4 TCP/IP Stack is based on the file sys_config.h This header file contains the configuration selection for the IPv4 TCP/IP Stack. Based on the selections made, the IPv4 TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the IPv4 TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.14.5.1 IP_DEFAULT_ALLOCATION_BLOCK_SIZE Macro C #define IP_DEFAULT_ALLOCATION_BLOCK_SIZE (64u) Description Used to configure payload size 5.8.14.5.2 IPV4_QUEUED_PACKET_LIMIT Macro C #define IPV4_QUEUED_PACKET_LIMIT 4u Description This option defines the maximum number of queued IPv4 TX packets. If an additional packet is queued, the oldest packet in the queue will be removed. 5.8.14.5.3 IPV4_QUEUED_PACKET_TIMEOUT Macro C #define IPV4_QUEUED_PACKET_TIMEOUT 10u Description This option defines the number of seconds an IPv4 TX packet will remain in the queue before being timed out 5.8.14.5.4 IPV4_TASK_PROCESS_RATE Macro C #define IPV4_TASK_PROCESS_RATE (1000) // default 1 second Description default 1 second 5.8.14.6 Building the Library This section list the files that are available in the \src of the IP driver. It lists which files need to be included in the build based on 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3711 either a hardware feature present on the board or configuration option selected by the system. • ip.c 5.8.14.7 Library Interface Data Types and Constants Name Description IPV4_HEADER None IPV4_HEADER_TYPE None IPV4_MODULE_CONFIG IPV4_PACKET Packet structure/state tracking for IPv4 packets Functions Name Description TCPIP_IPV4_PacketFormatTx Formats an IPV4 packet and makes it ready for transmission. TCPIP_IPV4_PacketGetDestAddress Returns the IPv4 destination address associated with a TCPIP_MAC_PACKET TCPIP_IPV4_PacketGetSourceAddress Returns the IPv4 source address associated with a TCPIP_MAC_PACKET TCPIP_IPV4_PacketTransmit Transmits an IPV4 packet over the network. TCPIP_IPV4_SelectSourceInterface Selects a source address and an interface based on the IPv4 destination address Description This section describes the Application Programming Interface (API) functions of the IPv4 TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.14.7.1 Functions 5.8.14.7.1.1 TCPIP_IPV4_PacketFormatTx Function C void TCPIP_IPV4_PacketFormatTx( IPV4_PACKET* pPkt, uint8_t protocol, uint16_t ipLen ); Description The necessary fields are set into the IPv4 packet. Preconditions Properly allocated pPkt. The source and destination addresses should be updated in the packet. Parameters Parameters Description pPkt the packet to be formatted protocol the protocol associated with the packet 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3712 ipLoadLen the IPv4 packet payload length Returns None Remarks The segments should be properly updated with the right number of bytes (segLen). The ipLoadLen is added only to the 1st segment of the packet! Other segments (for packets having multiple packets) are not touched. 5.8.14.7.1.2 TCPIP_IPV4_PacketGetDestAddress Function C __inline__ const IPV4_ADDR* TCPIP_IPV4_PacketGetDestAddress( TCPIP_MAC_PACKET* pPkt ); Description The function will return a pointer to where the IPv4 destination address is located in the TCPIP_MAC_PACKET. The TCPIP_MAC_PACKET is supposed to be a valid IPv4 packet that has properly destination address set. Preconditions pPkt - valid IPv4 packet, pNetLayer filed properly set Parameters Parameters Description pPkt packet to query Returns a valid pointer to an IPV4_ADDR if it succeeds 0 - if call failed Remarks This function is mainly meant for RX packets. 5.8.14.7.1.3 TCPIP_IPV4_PacketGetSourceAddress Function C __inline__ const IPV4_ADDR* TCPIP_IPV4_PacketGetSourceAddress( TCPIP_MAC_PACKET* pPkt ); Description The function will return a pointer to where the IPv4 source address is located in the TCPIP_MAC_PACKET. The TCPIP_MAC_PACKET is supposed to be a valid IPv4 packet that has properly source address set. Preconditions pPkt - valid IPv4 packet, pNetLayer filed properly set Parameters Parameters Description pPkt packet to query Returns a valid pointer to an IPV4_ADDR if it succeeds 0 - if call failed 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3713 Remarks This function is mainly meant for RX packets. 5.8.14.7.1.4 TCPIP_IPV4_PacketTransmit Function C bool TCPIP_IPV4_PacketTransmit( IPV4_PACKET* pPkt ); Description The IPv4 packet is sent to the MAC for transmission. Preconditions pPkt should have been properly formatted with TCPIP_IPV4_PacketFormatTx(). The packet interface should be updated. Parameters Parameters Description pPkt the packet to be transmitted Returns true - if the packet was handed to the MAC or is queued for transmission false - the packet cannot be transmitted (wrong interface, etc.) Remarks Only single packets can be transmitted. Chained packets are not supported for now. 5.8.14.7.1.5 TCPIP_IPV4_SelectSourceInterface Function C TCPIP_NET_HANDLE TCPIP_IPV4_SelectSourceInterface( TCPIP_NET_HANDLE netH, IPV4_ADDR* pDestAddress, IPV4_ADDR* pSrcAddress, bool srcSet ); Description Updates the pSrcAddress and returns the needed interface, if successful if srcSet == 1 and netH != 0 the function won't change anything if srcSet == 1 and netH == 0 then the call will never fail it will use whatever value in pSrcAddress (even 0) and will try to come up with an appropriate interface. if srcSet == 0 and netH == 0 it will use the destination address if srcSet == 0 and netH != 0 it will use the address of that interface Preconditions netH has to be valid (if non 0) Parameters Parameters Description netH network interface handle pDestAddress pointer to destination address pSrcAddress pointer to source address srcSet boolean; true if address pointed by pSrcAddress is valid 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3714 Returns a valid interface - if it succeeds and a valid source interface selected 0 - interface selection failed Remarks None 5.8.14.7.2 Data Types and Constants 5.8.14.7.2.1 IPV4_HEADER Structure C typedef struct { uint8_t VersionIHL; uint8_t TypeOfService; uint16_t TotalLength; uint16_t Identification; uint16_t FragmentInfo; uint8_t TimeToLive; uint8_t Protocol; uint16_t HeaderChecksum; IPV4_ADDR SourceAddress; IPV4_ADDR DestAddress; } IPV4_HEADER; Description IPv4 packet header definition None Remarks None 5.8.14.7.2.2 IPV4_HEADER_TYPE Enumeration C typedef enum { IP_PROT_ICMP = (1u), IP_PROT_TCP = (6u), IP_PROT_UDP = (17u) } IPV4_HEADER_TYPE; Description IPv4 supported protocols None Remarks None 5.8.14.7.2.3 IPV4_MODULE_CONFIG Structure C typedef struct { } IPV4_MODULE_CONFIG; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3715 5.8.14.7.2.4 IPV4_PACKET Structure C typedef struct { TCPIP_MAC_PACKET macPkt; IPV4_ADDR srcAddress; IPV4_ADDR destAddress; TCPIP_NET_HANDLE netIfH; IPV4_ADDR arpTarget; } IPV4_PACKET; Description Packet structure/state tracking for IPv4 packets Members Members Description TCPIP_MAC_PACKET macPkt; standard MAC packet header safe cast to TCPIP_MAC_PACKET IPV4_ADDR srcAddress; packet source IPV4_ADDR destAddress; packet destination TCPIP_NET_HANDLE netIfH; packet interface IPV4_ADDR arpTarget; ARP resolution target 5.8.14.8 Files Files Name Description ip_config.h IP configuration file ipv4.h Description 5.8.14.8.1 ip_config.h Internet Protocol (IP) Configuration file This file contains the IP module configuration options Macros Name Description IP_DEFAULT_ALLOCATION_BLOCK_SIZE Used to configure payload size IPV4_QUEUED_PACKET_LIMIT This option defines the maximum number of queued IPv4 TX packets. If an additional packet is queued, the oldest packet in the queue will be removed. IPV4_QUEUED_PACKET_TIMEOUT This option defines the number of seconds an IPv4 TX packet will remain in the queue before being timed out IPV4_TASK_PROCESS_RATE default 1 second IPV6_DEFAULT_BASE_REACHABLE_TIME 30 seconds IPV6_DEFAULT_CUR_HOP_LIMIT (IPv4 Time-to-Live parameter) IPV6_DEFAULT_LINK_MTU Default Maximum Transmission Unit 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv4 TCP/IP Stack Library 5-3716 IPV6_DEFAULT_RETRANSMIT_TIME 1 second IPV6_INIT_TASK_PROCESS_RATE default 32 ms IPV6_MINIMUM_LINK_MTU Sets the lower bounds of the the Maximum Transmission Unit IPV6_NEIGHBOR_CACHE_ENTRY_STALE_TIMEOUT 10 minutes IPV6_QUEUE_MCAST_PACKET_LIMIT This option defines the maximum number of multicast queued IPv6 If an additional packet is queued, the oldest packet in the queue will be removed. IPV6_QUEUE_NEIGHBOR_PACKET_LIMIT This option defines the maximum number of queued packets per remote. If an additional packet needs to be queued, the oldest packet in the queue will be removed. IPV6_QUEUED_MCAST_PACKET_TIMEOUT This option defines the number of seconds an IPv6 multicast packet will remain in the queue before being timed out IPV6_TASK_PROCESS_RATE default 1 second IPV6_ULA_NTP_ACCESS_TMO NTP access timeout for the IPv6 ULA address generation, ms IPV6_ULA_NTP_VALID_WINDOW the NTP time stamp validity window, ms if a stamp was obtained outside this interval from the moment of the request a new request wil be issued 5.8.14.8.2 ipv4.h IPv4 Defs for Microchip TCP/IP Stack Enumerations Name Description IPV4_HEADER_TYPE None Functions Name Description TCPIP_IPV4_PacketFormatTx Formats an IPV4 packet and makes it ready for transmission. TCPIP_IPV4_PacketGetDestAddress Returns the IPv4 destination address associated with a TCPIP_MAC_PACKET TCPIP_IPV4_PacketGetSourceAddress Returns the IPv4 source address associated with a TCPIP_MAC_PACKET TCPIP_IPV4_PacketTransmit Transmits an IPV4 packet over the network. TCPIP_IPV4_SelectSourceInterface Selects a source address and an interface based on the IPv4 destination address Structures Name Description IPV4_HEADER None IPV4_MODULE_CONFIG IPV4_PACKET Packet structure/state tracking for IPv4 packets 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3717 5.8.15 IPv6 TCP/IP Stack Library 5.8.15.1 Introduction Internet Protocol (IP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the IPv6 TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description IPv6 is the workhorse protocol of the TCP/IP protocol suite. All TCP, UDP, ICMP, and IGMP data gets transmitted as IP datagrams (Figure 1.4). IP provides an unreliable, connectionless datagram delivery service. IPv6 provides a best effort service. When something goes wrong, such as a router temporarily running out of buffers, IPv6 has a simple error handling algorithm: throw away the datagram and try to send an ICMP message back to the source. Any required reliability must be provided by the upper layers (e.g., TCP). The term connectionless means that IPv6 does not maintain any state information about successive datagrams. Each datagram is handled independently from all other datagrams. This also means that IPv6 datagrams can get delivered out of order. If a source sends two consecutive datagrams (first A, then B) to the same destination, each is routed independently and can take different routes, with B arriving before A. 5.8.15.2 Release Notes MPLAB Harmony Version: v0.70b IPv6 TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.15.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3718 YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.15.4 Using the Library This topic describes the basic architecture of the IPv6 TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: ip.h The interface to the IPv6 TCP/IP Stack library is defined in the "ip.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the IPv6 TCP/IP Stack library should include "tcpip.h". Library File: The IPv6 TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.15.4.1 Abstraction Model This library provides the API of the IP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description IP Software Abstraction Block Diagram This module provides software abstraction of the IP module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. Note: This diagram was not available at time of release and will be added in a future version of MPLAB Harmony. 5.8.15.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the IP module. Library Interface Section Description Functions Routines for Configuring IPv6 Data Types and Constants This section provides various definitions describing this API 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3719 5.8.15.5 Configuring the Library Macros Name Description IPV6_INIT_TASK_PROCESS_RATE default 32 ms IPV6_MINIMUM_LINK_MTU Sets the lower bounds of the the Maximum Transmission Unit IPV6_NEIGHBOR_CACHE_ENTRY_STALE_TIMEOUT 10 minutes IPV6_QUEUE_MCAST_PACKET_LIMIT This option defines the maximum number of multicast queued IPv6 If an additional packet is queued, the oldest packet in the queue will be removed. IPV6_QUEUE_NEIGHBOR_PACKET_LIMIT This option defines the maximum number of queued packets per remote. If an additional packet needs to be queued, the oldest packet in the queue will be removed. IPV6_QUEUED_MCAST_PACKET_TIMEOUT This option defines the number of seconds an IPv6 multicast packet will remain in the queue before being timed out IPV6_TASK_PROCESS_RATE default 1 second IPV6_ULA_NTP_ACCESS_TMO NTP access timeout for the IPv6 ULA address generation, ms IPV6_ULA_NTP_VALID_WINDOW the NTP time stamp validity window, ms if a stamp was obtained outside this interval from the moment of the request a new request wil be issued IPV6_DEFAULT_BASE_REACHABLE_TIME 30 seconds IPV6_DEFAULT_CUR_HOP_LIMIT (IPv4 Time-to-Live parameter) IPV6_DEFAULT_LINK_MTU Default Maximum Transmission Unit IPV6_DEFAULT_RETRANSMIT_TIME 1 second Description The configuration of the IPv6 TCP/IP Stack is based on the file sys_config.h This header file contains the configuration selection for the IPv6 TCP/IP Stack. Based on the selections made, the IPv6 TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the IPv6 TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.15.5.1 IPV6_INIT_TASK_PROCESS_RATE Macro C #define IPV6_INIT_TASK_PROCESS_RATE (32) // default 32 ms Description default 32 ms 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3720 5.8.15.5.2 IPV6_MINIMUM_LINK_MTU Macro C #define IPV6_MINIMUM_LINK_MTU 1280u Description Sets the lower bounds of the the Maximum Transmission Unit 5.8.15.5.3 IPV6_NEIGHBOR_CACHE_ENTRY_STALE_TIMEOUT Macro C #define IPV6_NEIGHBOR_CACHE_ENTRY_STALE_TIMEOUT 600ul // 10 minutes Description 10 minutes 5.8.15.5.4 IPV6_QUEUE_MCAST_PACKET_LIMIT Macro C #define IPV6_QUEUE_MCAST_PACKET_LIMIT 4 Description This option defines the maximum number of multicast queued IPv6 If an additional packet is queued, the oldest packet in the queue will be removed. 5.8.15.5.5 IPV6_QUEUE_NEIGHBOR_PACKET_LIMIT Macro C #define IPV6_QUEUE_NEIGHBOR_PACKET_LIMIT 1 Description This option defines the maximum number of queued packets per remote. If an additional packet needs to be queued, the oldest packet in the queue will be removed. 5.8.15.5.6 IPV6_QUEUED_MCAST_PACKET_TIMEOUT Macro C #define IPV6_QUEUED_MCAST_PACKET_TIMEOUT 10u Description This option defines the number of seconds an IPv6 multicast packet will remain in the queue before being timed out 5.8.15.5.7 IPV6_TASK_PROCESS_RATE Macro C #define IPV6_TASK_PROCESS_RATE (1000) // default 1 second Description default 1 second 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3721 5.8.15.5.8 IPV6_ULA_NTP_ACCESS_TMO Macro C #define IPV6_ULA_NTP_ACCESS_TMO (12000) Description NTP access timeout for the IPv6 ULA address generation, ms 5.8.15.5.9 IPV6_ULA_NTP_VALID_WINDOW Macro C #define IPV6_ULA_NTP_VALID_WINDOW (1000) Description the NTP time stamp validity window, ms if a stamp was obtained outside this interval from the moment of the request a new request wil be issued 5.8.15.5.10 IPV6_DEFAULT_BASE_REACHABLE_TIME Macro C #define IPV6_DEFAULT_BASE_REACHABLE_TIME 30u Description 30 seconds 5.8.15.5.11 IPV6_DEFAULT_CUR_HOP_LIMIT Macro C #define IPV6_DEFAULT_CUR_HOP_LIMIT 64u Description (IPv4 Time-to-Live parameter) 5.8.15.5.12 IPV6_DEFAULT_LINK_MTU Macro C #define IPV6_DEFAULT_LINK_MTU 1500u Description Default Maximum Transmission Unit 5.8.15.5.13 IPV6_DEFAULT_RETRANSMIT_TIME Macro C #define IPV6_DEFAULT_RETRANSMIT_TIME 1000u Description 1 second 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3722 5.8.15.6 Building the Library This section list the files that are available in the \src of the IP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • ip.c 5.8.15.7 Library Interface Data Types and Constants Name Description IP_VERSION_4 Using IPv4 IP_VERSION_6 Using IPv6 IPV6_DATA_DYNAMIC_BUFFER Data to transmit is allocated in dynamically allocated RAM IPV6_DATA_NETWORK_FIFO Data to transmit is stored in the Network Controller's FIFOs IPV6_DATA_NONE The data segment is unused IPV6_DATA_PIC_RAM Data to transmit is stored in PIC RAM IPV6_HEADER_OFFSET_DEST_ADDR Header offset for destination address IPV6_HEADER_OFFSET_NEXT_HEADER Header offset for next header IPV6_HEADER_OFFSET_PAYLOAD_LENGTH Header offset for payload length IPV6_HEADER_OFFSET_SOURCE_ADDR Header offset for source address IPV6_NO_UPPER_LAYER_CHECKSUM Value flag for no upper layer checksum IPV6_TLV_HBHO_PAYLOAD_JUMBOGRAM IPv6 Type-length-value type code for the Hop-by-hop "Jumbogram Payload" option IPV6_TLV_HBHO_ROUTER_ALERT IPv6 Type-length-value type code for the Hop-by-hop "Router Alert" option IPV6_TLV_PAD_1 IPv6 Type-length-value type code for the Pad 1 option IPV6_TLV_PAD_N IPv6 Type-length-value type code for the Pad N option IPV6_TLV_UNREC_OPT_DISCARD_PP IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message IPV6_TLV_UNREC_OPT_DISCARD_PP_NOT_MC IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message is the destination addr isn't a multicast address IPV6_TLV_UNREC_OPT_DISCARD_SILENT IPv6 action code for the unrecognized option reaction to discard the packet silently IPV6_TLV_UNREC_OPT_SKIP_OPTION IPv6 action code for the unrecognized option reaction to skip the option TCPIP_IPV6_PutArray Writes data to a packet IPV6_ACTION Provides a list of possible IPv6 actions. IPV6_ADDRESS_POLICY IPV6_ADDRESS_PREFERENCE Provides selection of public versus temporary addresses. IPV6_ADDRESS_TYPE Data structure for IPv6 addresses. IPV6_DATA_SEGMENT_HEADER IPV6_EVENT_HANDLER Clients can register a handler with the IPv6 service. IPV6_EVENT_TYPE None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3723 IPV6_FRAGMENT_HEADER IPV6_HANDLE Pointer to IPv6 object IPV6_HEADER None IPV6_MODULE_CONFIG Provides a placeholdef for IPv6 configuration. IPV6_NEXT_HEADER_TYPE Defines a list of next header types IPV6_PACKET Packet structure/state tracking for IPv6 packets IPV6_PACKET_ACK_FNC None IPV6_RX_FRAGMENT_BUFFER IPV6_SEGMENT_TYPE Provides an enumeration of IPv6 segment types. IPV6_TLV_OPTION_TYPE Data structure for IPv6 TLV options. IPV6_ULA_FLAGS Provides a list of possible flags for the Unique Local Address (ULA) generation. IPV6_ULA_RESULT Provides a list of possible results for the Unique Local Address (ULA) generation. Functions Name Description TCPIP_IPV6_AddressUnicastRemove Removed a configured unicast address from an interface. TCPIP_IPV6_ArrayGet Reads the next byte of data from the specified MAC. TCPIP_IPV6_ArrayPutHelper Helper function to write data to a packet. TCPIP_IPV6_DASSourceAddressSelect Determines the appropriate source address for a given destination address. TCPIP_IPV6_DestAddressGet Gets the destination address for an IPv6 packet. TCPIP_IPV6_DestAddressSet Sets the destination address for an IPv6 packet. TCPIP_IPV6_Flush Flushes an IP TX packet. TCPIP_IPV6_Get Reads the next byte of data from the specified MAC. TCPIP_IPV6_HandlerDeregister Deregisters an IPv6 event handler callback function. TCPIP_IPV6_HandlerRegister Registers an IPv6 event handler callback function. TCPIP_IPV6_InterfaceIsReady Determines if an interface is ready for IPv6 transactions. TCPIP_IPV6_MulticastListenerAdd Adds a multicast listener to an interface. TCPIP_IPV6_MulticastListenerRemove Removes a multicast listener from a given interface. TCPIP_IPV6_PacketFree Frees a TCP/IP Packet structure from dynamic memory. TCPIP_IPV6_PayloadSet Allocates a segment on the end of a packet segment chain and uses it to address pre-buffered data. TCPIP_IPV6_Put Writes a character of data to a packet. TCPIP_IPV6_SourceAddressGet Gets the source address for an IPv6 packet. TCPIP_IPV6_SourceAddressSet Sets the source address for an IPv6 packet. TCPIP_IPV6_TxIsPutReady Determines whether a TX packet can be written to. TCPIP_IPV6_TxPacketAllocate Dynamically allocates a packet for transmitting IP protocol data. TCPIP_IPV6_UnicastAddressAdd Adds a unicast address to a specified interface TCPIP_IPV6_UniqueLocalUnicastAddressAdd Adds a Unique Local Unicast Address (ULA) to a specified interface Description This section describes the Application Programming Interface (API) functions of the IPv6 TCP/IP Stack Library. Refer to each section for a detailed description. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3724 5.8.15.7.1 Functions 5.8.15.7.1.1 TCPIP_IPV6_AddressUnicastRemove Function C void TCPIP_IPV6_AddressUnicastRemove( TCPIP_NET_HANDLE netH, IPV6_ADDR * address ); Description Removed a configured unicast address from an interface. Preconditions None Parameters Parameters Description netH The interface. address The address Returns None Remarks None 5.8.15.7.1.2 TCPIP_IPV6_ArrayGet Function C uint8_t TCPIP_IPV6_ArrayGet( TCPIP_MAC_PACKET* pRxPkt, uint8_t * val, uint16_t len ); Description Reads a character of data from a packet. Preconditions None Parameters Parameters Description pRxPkt The MAC RX packet to read data from val The buffer to store the data len The amount of data to read Returns uint8_t - The number of bytes read. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3725 Remarks None 5.8.15.7.1.3 TCPIP_IPV6_ArrayPutHelper Function C unsigned short TCPIP_IPV6_ArrayPutHelper( IPV6_PACKET * pkt, const void * dataSource, uint8_t dataType, unsigned short len ); Description Helper function to write data to a packet. Preconditions None Parameters Parameters Description ptrPacket The packet. dataSource The address of the data on its medium. dataType Descriptor of the data type (dynamic memory on PIC, in a network FIFO, in static PIC RAM) len Length of the data. Returns unsigned short - The number of bytes of data written. Remarks None 5.8.15.7.1.4 TCPIP_IPV6_DASSourceAddressSelect Function C IPV6_ADDR_STRUCT * TCPIP_IPV6_DASSourceAddressSelect( TCPIP_NET_HANDLE hNetIf, IPV6_ADDR * dest, IPV6_ADDR * requestedSource ); Description Determines the appropriate source address for a given destination address. Preconditions None Parameters Parameters Description hNetIf The given interface. dest The destination address. requestedSource A specified source. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3726 Returns IPV6_ADDR_STRUCT * - The selected source address. Remarks None 5.8.15.7.1.5 TCPIP_IPV6_DestAddressGet Function C IPV6_ADDR * TCPIP_IPV6_DestAddressGet( IPV6_PACKET * p ); Description Gets the destination address for an IPv6 packet. Preconditions None. Parameters Parameters Description p pointer to IPv6 packet Returns Destination address. Remarks None. 5.8.15.7.1.6 TCPIP_IPV6_DestAddressSet Function C void TCPIP_IPV6_DestAddressSet( IPV6_PACKET * p, const IPV6_ADDR * addr ); Description Sets the destination address for an IPv6 packet. Preconditions None. Parameters Parameters Description p pointer to IPv6 packet addrValue destination address Returns None. Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3727 5.8.15.7.1.7 TCPIP_IPV6_Flush Function C int TCPIP_IPV6_Flush( IPV6_PACKET * pkt ); Description Flushes an IP TX packet. Determines the link-layer address if necessary. Calculates the upper-layer checksum if necessary. Preconditions None Parameters Parameters Description ptrPacket The packet to flush. Returns 1 - if the packet has been transmitted 0 - if the packet has been queued. < 0 - if the packet has been discarded for some error Remarks None 5.8.15.7.1.8 TCPIP_IPV6_Get Function C uint8_t TCPIP_IPV6_Get( TCPIP_MAC_PACKET* pRxPkt, uint8_t* pData ); Description Reads a character of data from a packet. Preconditions None Parameters Parameters Description pRxPkt The MAC RX packet to read data from Returns The data read. Remarks None 5.8.15.7.1.9 TCPIP_IPV6_HandlerDeregister Function C bool TCPIP_IPV6_HandlerDeregister( IPV6_HANDLE hIpv6 ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3728 Description Deregisters an IPv6 event handler callback function. Preconditions None Parameters Parameters Description hIpv6 Handle to registered callback Returns true - if deregister successful false - otherwise. Remarks None 5.8.15.7.1.10 TCPIP_IPV6_HandlerRegister Function C IPV6_HANDLE TCPIP_IPV6_HandlerRegister( TCPIP_NET_HANDLE hNet, IPV6_EVENT_HANDLER handler, const void* hParam ); Description Registers an IPv6 event handler callback function. Preconditions None Parameters Parameters Description netH The interface handler event handler hParam Returns Handle to registered callback. Remarks None 5.8.15.7.1.11 TCPIP_IPV6_InterfaceIsReady Function C bool TCPIP_IPV6_InterfaceIsReady( TCPIP_NET_HANDLE netH ); Description Determines if an interface is ready for IPv6 transactions. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3729 Preconditions None Parameters Parameters Description pNetIf The interface to check Returns true if the interface has IPv6 functionality available, false otherwise Remarks None 5.8.15.7.1.12 TCPIP_IPV6_MulticastListenerAdd Function C IPV6_ADDR_STRUCT * TCPIP_IPV6_MulticastListenerAdd( TCPIP_NET_HANDLE hNet, IPV6_ADDR * address ); Description Adds a multicast listener to an interface. Preconditions None Parameters Parameters Description pNetIf The interface to add the address to. address The new listener Returns IPV6_ADDR_STRUCT * - Pointer to the new listener, or NULL Remarks None 5.8.15.7.1.13 TCPIP_IPV6_MulticastListenerRemove Function C void TCPIP_IPV6_MulticastListenerRemove( TCPIP_NET_HANDLE netH, IPV6_ADDR * address ); Description Removes a multicast listener from a given interface. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3730 Parameters Parameters Description netH The interface address The address Returns None Remarks None 5.8.15.7.1.14 TCPIP_IPV6_PacketFree Function C void TCPIP_IPV6_PacketFree( IPV6_PACKET * pkt ); Description Frees a TCP/IP Packet structure from dynamic memory. Preconditions None Parameters Parameters Description ptrPacket The packet to free. Returns None Remarks None 5.8.15.7.1.15 TCPIP_IPV6_PayloadSet Function C unsigned short TCPIP_IPV6_PayloadSet( IPV6_PACKET * pkt, uint8_t* payload, unsigned short len ); Description This function will allocate a data segment header and append it to the end of a chain of segments in a TX packet. It will set the data ptr in the packet segment to a pre-existing buffer of data. Preconditions None Parameters Parameters Description ptrPacket The packet. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3731 payload Address of the data payload. len Length of the data payload Returns unsigned short - The amount of data added to the packet length. Remarks This function is useful for adding payloads to outgoing packets without copying them if the data is in another preexisting buffer (i.e. TCP). 5.8.15.7.1.16 TCPIP_IPV6_Put Function C bool TCPIP_IPV6_Put( IPV6_PACKET * pkt, unsigned char v ); Description Writes a character of data to a packet. Preconditions None Parameters Parameters Description pkt The packet. v The characeter. Returns true if the character was written, false otherwise Remarks None 5.8.15.7.1.17 TCPIP_IPV6_SourceAddressGet Function C IPV6_ADDR * TCPIP_IPV6_SourceAddressGet( IPV6_PACKET * p ); Description Gets the source address for an IPv6 packet. Parameters Parameters Description p pointer to IPv6 packet Returns Source address. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3732 Remarks None. 5.8.15.7.1.18 TCPIP_IPV6_SourceAddressSet Function C void TCPIP_IPV6_SourceAddressSet( IPV6_PACKET * p, const IPV6_ADDR * addr ); Description Sets the source address for an IPv6 packet. Preconditions None. Parameters Parameters Description p pointer to IPv6 packet addrValue source address Returns None. Remarks None 5.8.15.7.1.19 TCPIP_IPV6_TxIsPutReady Function C unsigned short TCPIP_IPV6_TxIsPutReady( IPV6_PACKET * pkt, unsigned short count ); Description Determines whether a TX packet can be written to. This function will allocate additional space to the packet to accomodate the user. Preconditions None Parameters Parameters Description ptrPacket The packet to check. count The amount of writable space to check for, Returns unsigned short - The amount of space available. Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3733 5.8.15.7.1.20 TCPIP_IPV6_TxPacketAllocate Function C IPV6_PACKET * TCPIP_IPV6_TxPacketAllocate( TCPIP_NET_HANDLE netH, IPV6_PACKET_ACK_FNC ackFnc, void* ackParam ); Description Dynamically allocates a packet for transmitting IP protocol data. Preconditions None Parameters Parameters Description netH Interface of the outgoing packet. ackFnc function to be called when IP is done with the TX packet (finished transmitting) ackParam parameter to be used for this callback This has meaning only for the caller of the TCPIP_IPV6_TxPacketAllocate Returns IPV6_PACKET * - Pointer to the allocated packet. Remarks None 5.8.15.7.1.21 TCPIP_IPV6_UnicastAddressAdd Function C IPV6_ADDR_STRUCT * TCPIP_IPV6_UnicastAddressAdd( TCPIP_NET_HANDLE netH, IPV6_ADDR * address, uint8_t skipProcessing ); Description Adds a unicast address to a specified interface. Starts duplicate address detection if necessary. Preconditions None Parameters Parameters Description netH The interface to add the address to. address The address to add. skipProcessing true to skip Duplicate address detection, false otherwise Returns IPV6_ADDR_STRUCT * - Pointer to the structure of the newly allocated address Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3734 5.8.15.7.1.22 TCPIP_IPV6_UniqueLocalUnicastAddressAdd Function C IPV6_ULA_RESULT TCPIP_IPV6_UniqueLocalUnicastAddressAdd( TCPIP_NET_HANDLE netH, uint16_t subnetID, IPV6_ULA_FLAGS genFlags, IP_MULTI_ADDRESS* ntpAddress ); Description This function starts the process of adding an ULA address to the specified interface. The segments of the generated address are as follows: FC00::/7 - ULA prefix L - 1 bit set to 1, locally assigned Global ID - 40 bit random generated identifier subnet ID - 16 bit subnet identifier Interface ID - 64 bit interface identifier generated as a EUI64 from the specified interface MAC. The randomness of the "Global ID" prefix of the generated IPv6 address is obtained by using an NTP server. The supplied NTP server will be contacted to obtain an NTP timestamp. This timestamp together with the EUI64 identifier obtained from the interface MAC are passed through a 160 bits hash alhorithm (SHA1) and the least seigbificant 40 bits are used as the GlobalID of the interface. Preconditions None Parameters Parameters Description netH the interface to add the address to. subnetID the subnet ID to be used. 5.8.15.7.2 Data Types and Constants 5.8.15.7.2.1 IP_VERSION_4 Macro C #define IP_VERSION_4 (0u) // Using IPv4 Description Using IPv4 5.8.15.7.2.2 IP_VERSION_6 Macro C #define IP_VERSION_6 (1u) // Using IPv6 Description Using IPv6 5.8.15.7.2.3 IPV6_DATA_DYNAMIC_BUFFER Macro C #define IPV6_DATA_DYNAMIC_BUFFER (0x1u) // Data to transmit is allocated in dynamically allocated RAM 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3735 Description Data to transmit is allocated in dynamically allocated RAM 5.8.15.7.2.4 IPV6_DATA_NETWORK_FIFO Macro C #define IPV6_DATA_NETWORK_FIFO (0x2u) // Data to transmit is stored in the Network Controller's FIFOs Description Data to transmit is stored in the Network Controller's FIFOs 5.8.15.7.2.5 IPV6_DATA_NONE Macro C #define IPV6_DATA_NONE (0x0u) // The data segment is unused Description The data segment is unused 5.8.15.7.2.6 IPV6_DATA_PIC_RAM Macro C #define IPV6_DATA_PIC_RAM (0x3u) // Data to transmit is stored in PIC RAM Description Data to transmit is stored in PIC RAM 5.8.15.7.2.7 IPV6_HEADER_OFFSET_DEST_ADDR Macro C #define IPV6_HEADER_OFFSET_DEST_ADDR (0x08u + sizeof (IPV6_ADDR)) // Header offset for destination address Description Header offset for destination address 5.8.15.7.2.8 IPV6_HEADER_OFFSET_NEXT_HEADER Macro C #define IPV6_HEADER_OFFSET_NEXT_HEADER (0x06u) // Header offset for next header Description Header offset for next header 5.8.15.7.2.9 IPV6_HEADER_OFFSET_PAYLOAD_LENGTH Macro C #define IPV6_HEADER_OFFSET_PAYLOAD_LENGTH (0x04u) // Header offset for payload length Description Header offset for payload length 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3736 5.8.15.7.2.10 IPV6_HEADER_OFFSET_SOURCE_ADDR Macro C #define IPV6_HEADER_OFFSET_SOURCE_ADDR (0x08u) // Header offset for source address Description Header offset for source address 5.8.15.7.2.11 IPV6_NO_UPPER_LAYER_CHECKSUM Macro C #define IPV6_NO_UPPER_LAYER_CHECKSUM (0xFFFFu) // Value flag for no upper layer checksum Description Value flag for no upper layer checksum 5.8.15.7.2.12 IPV6_TLV_HBHO_PAYLOAD_JUMBOGRAM Macro C #define IPV6_TLV_HBHO_PAYLOAD_JUMBOGRAM 0xC2u Description IPv6 Type-length-value type code for the Hop-by-hop "Jumbogram Payload" option 5.8.15.7.2.13 IPV6_TLV_HBHO_ROUTER_ALERT Macro C #define IPV6_TLV_HBHO_ROUTER_ALERT 0x05u Description IPv6 Type-length-value type code for the Hop-by-hop "Router Alert" option 5.8.15.7.2.14 IPV6_TLV_PAD_1 Macro C #define IPV6_TLV_PAD_1 0u Description IPv6 Type-length-value type code for the Pad 1 option 5.8.15.7.2.15 IPV6_TLV_PAD_N Macro C #define IPV6_TLV_PAD_N 1u Description IPv6 Type-length-value type code for the Pad N option 5.8.15.7.2.16 IPV6_TLV_UNREC_OPT_DISCARD_PP Macro C #define IPV6_TLV_UNREC_OPT_DISCARD_PP 0b10 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3737 Description IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message 5.8.15.7.2.17 IPV6_TLV_UNREC_OPT_DISCARD_PP_NOT_MC Macro C #define IPV6_TLV_UNREC_OPT_DISCARD_PP_NOT_MC 0b11 Description IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message is the destination addr isn't a multicast address 5.8.15.7.2.18 IPV6_TLV_UNREC_OPT_DISCARD_SILENT Macro C #define IPV6_TLV_UNREC_OPT_DISCARD_SILENT 0b01 Description IPv6 action code for the unrecognized option reaction to discard the packet silently 5.8.15.7.2.19 IPV6_TLV_UNREC_OPT_SKIP_OPTION Macro C #define IPV6_TLV_UNREC_OPT_SKIP_OPTION 0b00 Description IPv6 action code for the unrecognized option reaction to skip the option 5.8.15.7.2.20 TCPIP_IPV6_PutArray Macro C #define TCPIP_IPV6_PutArray(pkt,data,len) TCPIP_IPV6_ArrayPutHelper(pkt, data, IPV6_DATA_PIC_RAM, len) Description Writes data to an outgoing packet. Preconditions The TCPIP_IPV6_TxIsPutReady function must have returned a value greater than or equal to 'len.' Parameters Parameters Description ptrPacket The packet. dataSource Pointer to the data to copy to the packet. len Length of the data. Returns unsigned short - The number of bytes of data written. Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3738 5.8.15.7.2.21 IPV6_ACTION Enumeration C typedef enum { IPV6_ACTION_NONE = 0, IPV6_ACTION_DISCARD_SILENT, IPV6_ACTION_DISCARD_PP_0, IPV6_ACTION_DISCARD_PP_2, IPV6_ACTION_DISCARD_PP_2_NOT_MC, IPV6_ACTION_BEGIN_EX_HEADER_PROCESSING } IPV6_ACTION; Description IPV6_ACTION Enumeration Provides a list of possible IPv6 actions. Remarks None 5.8.15.7.2.22 IPV6_ADDRESS_POLICY Structure C typedef struct { IPV6_ADDR address; unsigned char prefixLength; unsigned char precedence; unsigned char label; } IPV6_ADDRESS_POLICY; Description IPV6_ADDRESS_POLICY Structure Typedef Remarks None 5.8.15.7.2.23 IPV6_ADDRESS_PREFERENCE Enumeration C typedef enum { IPV6_PREFER_PUBLIC_ADDRESSES = 0, IPV6_PREFER_TEMPORARY_ADDRESSES } IPV6_ADDRESS_PREFERENCE; Description IPV6_ADDRESS_PREFERENCE Enumeration Provides selection of public versus temporary addresses. Remarks None 5.8.15.7.2.24 IPV6_ADDRESS_TYPE Union C typedef union { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3739 unsigned char byte; struct { unsigned scope : 4; unsigned type : 2; } bits; } IPV6_ADDRESS_TYPE; Description IPV6_ADDRESS_TYPE Union Typedef Data structure for IPv6 addresses. Remarks None 5.8.15.7.2.25 IPV6_DATA_SEGMENT_HEADER Type C typedef struct _IPV6_DATA_SEGMENT_HEADER IPV6_DATA_SEGMENT_HEADER; Description IPV6_DATA_SEGMENT_HEADER Structure Typedef Remarks None 5.8.15.7.2.26 IPV6_EVENT_HANDLER Type C typedef void (* IPV6_EVENT_HANDLER)(TCPIP_NET_HANDLE hNet, IPV6_EVENT_TYPE evType, const void* evParam, const void* usrParam); Description Prototype of an IPv6 event handler Once an IPv6 event occurs the IPv6 service will call the registered handler The handler has to be short and fast. It is meant for setting an event flag, not for lengthy processing! evParam is a parameter that's associated to an IPv6 event • For an address event (IPV6_EVENT_ADDRESS_ADDED, IPV6_EVENT_ADDRESS_REMOVED) it should be typecasted to (const IPV6_ADDR_STRUCT*) • For an IPV6_EVENT_ULA_ADDRESS_GENERATED ULA event it should be typecasted to (const IPV6_ADDR*) • For an IPV6_EVENT_ULA_ADDRESS_FAILED ULA event the evParam is an IPV6_ULA_RESULT error code The evParam is invalid outside of the IPV6_EVENT_HANDLER context call and should not be stored by the caller. Info that's needed has to be copied into caller's own context. usrParam is an user supplied parameter Remarks For address related events the passed (const IPV6_ADDR_STRUCT*) parameter is invalid after the notification call. 5.8.15.7.2.27 IPV6_EVENT_TYPE Enumeration C typedef enum { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3740 IPV6_EVENT_ADDRESS_ADDED = 1, IPV6_EVENT_ADDRESS_REMOVED, IPV6_EVENT_ULA_ADDRESS_GENERATED, IPV6_EVENT_ULA_ADDRESS_FAILED } IPV6_EVENT_TYPE; Description IPV6_EVENT_TYPE Enumeration None Remarks None 5.8.15.7.2.28 IPV6_FRAGMENT_HEADER Structure C typedef struct { uint8_t nextHeader; uint8_t reserved; union { struct { unsigned m : 1; unsigned reserved2 : 2; unsigned fragmentOffset : 13; } bits; uint16_t w; } offsetM; uint32_t identification; } IPV6_FRAGMENT_HEADER; Description IPV6_FRAGMENT_HEADER Structure Typedef Remarks None 5.8.15.7.2.29 IPV6_HANDLE Type C typedef const void * IPV6_HANDLE; Description Pointer to IPv6 object 5.8.15.7.2.30 IPV6_HEADER Structure C typedef struct { unsigned long V_T_F; unsigned short PayloadLength; unsigned char NextHeader; unsigned char HopLimit; IPV6_ADDR SourceAddress; IPV6_ADDR DestAddress; } IPV6_HEADER; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3741 Description IPv6 packet header definition None Remarks None 5.8.15.7.2.31 IPV6_MODULE_CONFIG Structure C typedef struct { } IPV6_MODULE_CONFIG; Description IPV6_MODULE_CONFIG Structure Typedef Provides a placeholdef for IPv6 configuration. Remarks None 5.8.15.7.2.32 IPV6_NEXT_HEADER_TYPE Enumeration C typedef enum { IPV6_PROT_HOP_BY_HOP_OPTIONS_HEADER = (0u), IPV6_PROT_ICMP = (1u), IPV6_PROT_TCP = (6u), IPV6_PROT_UDP = (17u), IPV6_PROT_IPV6 = (41u), IPV6_PROT_ROUTING_HEADER = (43u), IPV6_PROT_FRAGMENTATION_HEADER = (44u), IPV6_PROT_ENCAPSULATING_SECURITY_PAYLOAD_HEADER = (50u), IPV6_PROT_AUTHENTICATION_HEADER = (51u), IPV6_PROT_ICMPV6 = (58u), IPV6_PROT_NONE = (59u), IPV6_PROT_DESTINATION_OPTIONS_HEADER = (60u) } IPV6_NEXT_HEADER_TYPE; Description IPV6_NEXT_HEADER_TYPE Enumeration Defines a list of next header types Members Members Description IPV6_PROT_HOP_BY_HOP_OPTIONS_HEADER = (0u) IPv6 Hop-by-Hop Opt. Header IPV6_PROT_IPV6 = (41u) IPv6 Protocol IPV6_PROT_ROUTING_HEADER = (43u) IPv6 Routing Header IPV6_PROT_FRAGMENTATION_HEADER = (44u) IPv6 Fragmentation Header IPV6_PROT_ENCAPSULATING_SECURITY_PAYLOAD_HEADER = (50u) Encapsulating Security Payload Header IPV6_PROT_AUTHENTICATION_HEADER = (51u) Authentication Header 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3742 IPV6_PROT_ICMPV6 = (58u) ICMPv6 Protocol IPV6_PROT_NONE = (59u) No next header IPV6_PROT_DESTINATION_OPTIONS_HEADER = (60u) Destination Options Header Remarks None 5.8.15.7.2.33 IPV6_PACKET Type C typedef struct _IPV6_PACKET IPV6_PACKET; Description Packet structure/state tracking for IPv6 packets 5.8.15.7.2.34 IPV6_PACKET_ACK_FNC Type C typedef void (* IPV6_PACKET_ACK_FNC)(void*, bool, const void*); Description Packet allocation callback function 1st parameter will be an IPV6_PACKET* 2nd parameter is supplied by the caller Remarks None 5.8.15.7.2.35 IPV6_RX_FRAGMENT_BUFFER Type C typedef struct _IPV6_RX_FRAGMENT_BUFFER IPV6_RX_FRAGMENT_BUFFER; Description IPV6_RX_FRAGMENT_BUFFER Structure Typedef Remarks None 5.8.15.7.2.36 IPV6_SEGMENT_TYPE Enumeration C typedef enum { TYPE_IPV6_HEADER = 1u, TYPE_IPV6_EX_HEADER_HOP_BY_HOP_OPTIONS, TYPE_IPV6_EX_HEADER_DESTINATION_OPTIONS_1, TYPE_IPV6_EX_HEADER_ROUTING, TYPE_IPV6_EX_HEADER_FRAGMENT, TYPE_IPV6_EX_HEADER_AUTHENTICATION_HEADER, TYPE_IPV6_EX_HEADER_ENCAPSULATING_SECURITY_PAYLOAD, TYPE_IPV6_EX_HEADER_DESTINATION_OPTIONS_2, TYPE_IPV6_UPPER_LAYER_HEADER, TYPE_IPV6_UPPER_LAYER_PAYLOAD, TYPE_IPV6_BEGINNING_OF_WRITABLE_PART, TYPE_IPV6_END_OF_LIST 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3743 } IPV6_SEGMENT_TYPE; Description IPV6_SEGMENT_TYPE Enumeration Provides an enumeration of IPv6 segment types. Remarks None 5.8.15.7.2.37 IPV6_TLV_OPTION_TYPE Union C typedef union { unsigned char b; struct { unsigned option : 6; unsigned unrecognizedAction : 2; } bits; } IPV6_TLV_OPTION_TYPE; Description IPV6_TLV_OPTION_TYPE Union Typedef Data structure for IPv6 TLV options. Remarks None 5.8.15.7.2.38 IPV6_ULA_FLAGS Enumeration C typedef enum { IPV6_ULA_FLAG_NTPV4 = 0x01, IPV6_ULA_FLAG_GENERATE_ONLY = 0x02, IPV6_ULA_FLAG_SKIP_DAD = 0x04 } IPV6_ULA_FLAGS; Description IPV6_ULA_FLAGS Enumeration Provides a list of possible ULA action flags. Members Members Description IPV6_ULA_FLAG_NTPV4 = 0x01 use an IPv4 NTP server access in Unique Local Address generation default is an IPv6 server IPV6_ULA_FLAG_GENERATE_ONLY = 0x02 generate an address only, don't add it to the interface addresses IPV6_ULA_FLAG_SKIP_DAD = 0x04 when adding the address to the interface, skip the Duplicate Address Detection Remarks None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3744 5.8.15.7.2.39 IPV6_ULA_RESULT Enumeration C typedef enum { IPV6_ULA_RES_OK, IPV6_ULA_RES_BUSY = -1, IPV6_ULA_RES_IF_ERR = -2, IPV6_ULA_RES_NTP_ACCESS_ERR = -3, IPV6_ULA_RES_NTP_TSTAMP_ERR = -4 } IPV6_ULA_RESULT; Description IPV6_ULA_RESULT Enumeration Provides a list of possible ULA results. Members Members Description IPV6_ULA_RES_OK the address generation was started successfully IPV6_ULA_RES_BUSY = -1 address generation module is busy IPV6_ULA_RES_IF_ERR = -2 interface non existent IPV6_ULA_RES_NTP_ACCESS_ERR = -3 NTP module could not be accessed IPV6_ULA_RES_NTP_TSTAMP_ERR = -4 wrong NTP time stamp received Remarks None 5.8.15.8 Files Files Name Description ipv6.h Description 5.8.15.8.1 ipv6.h IPv6 Defs for Microchip TCP/IP Stack Enumerations Name Description IPV6_ACTION Provides a list of possible IPv6 actions. IPV6_ADDRESS_PREFERENCE Provides selection of public versus temporary addresses. IPV6_EVENT_TYPE None IPV6_NEXT_HEADER_TYPE Defines a list of next header types IPV6_SEGMENT_TYPE Provides an enumeration of IPv6 segment types. IPV6_ULA_FLAGS Provides a list of possible flags for the Unique Local Address (ULA) generation. IPV6_ULA_RESULT Provides a list of possible results for the Unique Local Address (ULA) generation. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3745 Functions Name Description TCPIP_IPV6_AddressUnicastRemove Removed a configured unicast address from an interface. TCPIP_IPV6_ArrayGet Reads the next byte of data from the specified MAC. TCPIP_IPV6_ArrayPutHelper Helper function to write data to a packet. TCPIP_IPV6_DASSourceAddressSelect Determines the appropriate source address for a given destination address. TCPIP_IPV6_DestAddressGet Gets the destination address for an IPv6 packet. TCPIP_IPV6_DestAddressSet Sets the destination address for an IPv6 packet. TCPIP_IPV6_Flush Flushes an IP TX packet. TCPIP_IPV6_Get Reads the next byte of data from the specified MAC. TCPIP_IPV6_HandlerDeregister Deregisters an IPv6 event handler callback function. TCPIP_IPV6_HandlerRegister Registers an IPv6 event handler callback function. TCPIP_IPV6_InterfaceIsReady Determines if an interface is ready for IPv6 transactions. TCPIP_IPV6_MulticastListenerAdd Adds a multicast listener to an interface. TCPIP_IPV6_MulticastListenerRemove Removes a multicast listener from a given interface. TCPIP_IPV6_PacketFree Frees a TCP/IP Packet structure from dynamic memory. TCPIP_IPV6_PayloadSet Allocates a segment on the end of a packet segment chain and uses it to address pre-buffered data. TCPIP_IPV6_Put Writes a character of data to a packet. TCPIP_IPV6_SourceAddressGet Gets the source address for an IPv6 packet. TCPIP_IPV6_SourceAddressSet Sets the source address for an IPv6 packet. TCPIP_IPV6_TxIsPutReady Determines whether a TX packet can be written to. TCPIP_IPV6_TxPacketAllocate Dynamically allocates a packet for transmitting IP protocol data. TCPIP_IPV6_UnicastAddressAdd Adds a unicast address to a specified interface TCPIP_IPV6_UniqueLocalUnicastAddressAdd Adds a Unique Local Unicast Address (ULA) to a specified interface Macros Name Description IP_VERSION_4 Using IPv4 IP_VERSION_6 Using IPv6 IPV6_DATA_DYNAMIC_BUFFER Data to transmit is allocated in dynamically allocated RAM IPV6_DATA_NETWORK_FIFO Data to transmit is stored in the Network Controller's FIFOs IPV6_DATA_NONE The data segment is unused IPV6_DATA_PIC_RAM Data to transmit is stored in PIC RAM IPV6_HEADER_OFFSET_DEST_ADDR Header offset for destination address IPV6_HEADER_OFFSET_NEXT_HEADER Header offset for next header IPV6_HEADER_OFFSET_PAYLOAD_LENGTH Header offset for payload length IPV6_HEADER_OFFSET_SOURCE_ADDR Header offset for source address IPV6_NO_UPPER_LAYER_CHECKSUM Value flag for no upper layer checksum IPV6_TLV_HBHO_PAYLOAD_JUMBOGRAM IPv6 Type-length-value type code for the Hop-by-hop "Jumbogram Payload" option IPV6_TLV_HBHO_ROUTER_ALERT IPv6 Type-length-value type code for the Hop-by-hop "Router Alert" option IPV6_TLV_PAD_1 IPv6 Type-length-value type code for the Pad 1 option IPV6_TLV_PAD_N IPv6 Type-length-value type code for the Pad N option 5.8 TCP/IP Stack Library Help MPLAB Harmony Help IPv6 TCP/IP Stack Library 5-3746 IPV6_TLV_UNREC_OPT_DISCARD_PP IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message IPV6_TLV_UNREC_OPT_DISCARD_PP_NOT_MC IPv6 action code for the unrecognized option reaction to discard the packet and send an ICMP parameter problem message is the destination addr isn't a multicast address IPV6_TLV_UNREC_OPT_DISCARD_SILENT IPv6 action code for the unrecognized option reaction to discard the packet silently IPV6_TLV_UNREC_OPT_SKIP_OPTION IPv6 action code for the unrecognized option reaction to skip the option TCPIP_IPV6_PutArray Writes data to a packet Structures Name Description IPV6_ADDRESS_POLICY IPV6_FRAGMENT_HEADER IPV6_HEADER None IPV6_MODULE_CONFIG Provides a placeholdef for IPv6 configuration. Types Name Description IPV6_DATA_SEGMENT_HEADER IPV6_EVENT_HANDLER Clients can register a handler with the IPv6 service. IPV6_HANDLE Pointer to IPv6 object IPV6_PACKET Packet structure/state tracking for IPv6 packets IPV6_PACKET_ACK_FNC None IPV6_RX_FRAGMENT_BUFFER Unions Name Description IPV6_ADDRESS_TYPE Data structure for IPv6 addresses. IPV6_TLV_OPTION_TYPE Data structure for IPv6 TLV options. 5.8.15.8.2 ip_config.h Refer to the IPv4 Help for this file: ip_config.h 5.8.16 MAC TCP/IP Stack Library 5.8.16.1 Introduction Media Access Control (MAC) TCP/IP Stack Library for 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3747 Microchip Microcontrollers This library provides the API of the MAC TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description In the seven-layer OSI model of computer networking, media access control (MAC) data communication protocol is a sublayer of the data link layer, which itself is layer 2. The MAC sublayer provides addressing and channel access control mechanisms that make it possible for several terminals or network nodes to communicate within a multiple access network that incorporates a shared medium, e.g. Ethernet. The hardware that implements the MAC is referred to as a medium access controller. The MAC sublayer acts as an interface between the logical link control (LLC) sublayer and the network's physical layer. The MAC layer emulates a full-duplex logical communication channel in a multi-point network. This channel may provide unicast, multicast or broadcast communication service. 5.8.16.2 Release Notes MPLAB Harmony Version: v0.70b MAC TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.16.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.16.4 Using the Library This topic describes the basic architecture of the MAC TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: tcpip_mac.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3748 The interface to the MAC TCP/IP Stack library is defined in the "tcpip_mac.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the MAC TCP/IP Stack library should include "tcpip.h". Library File: The MAC TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.16.4.1 Abstraction Model This library provides the API of the MAC TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description MAC Software Abstraction Block Diagram Note: This diagram was not available at time of release and will be added in a future version of MPLAB Harmony. 5.8.16.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the MAC module. Library Interface Section Description Functions Routines for configuring the MAC TCP/IP Stack Data Types and Constants This section provides various definitions describing this API 5.8.16.5 Configuring the Library Macros Name Description EMAC_RX_BUFF_SIZE size of a RX buffer. should be multiple of 16 this is the size of all receive buffers processed by the ETHC The size should be enough to accomodate any network received packet If the packets are larger, they will have to take multiple RX buffers and the packet manipulation is less efficient #define EMAC_RX_BUFF_SIZE 512 EMAC_RX_DESCRIPTORS number of the RX descriptors and RX buffers to be created EMAC_RX_FRAGMENTS MAC maximum number of supported fragments Based on the values of EMAC_RX_MAX_FRAME and EMAC_RX_BUFF_SIZE an incoming frame may span multiple RX buffers (fragments). Note that excessive fragmentation leads to performance degradation. The default and recommended value should be 1. #define EMAC_RX_FRAGMENTS 1 Alternatively you can use the calculation of the number of fragments based on the selected RX sizes: EMAC_RX_MAX_FRAME Maximum MAC supported RX frame size. Any incoming ETH frame that's longer than this size will be discarded. The default value is 1536 (allows for VLAN tagged frames, although the VLAN tagged frames are discarded) Normally you shouldn't need to touch this value unless you know exactly the maximum size of the frames you want to process or you need to control packets fragmentation (together with the EMAC_RX_BUFF_SIZE. EMAC_TX_DESCRIPTORS number of the TX descriptors to be created ETH_CFG_10 use/advertise 10 Mbps capability 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3749 ETH_CFG_100 use/advertise 100 Mbps capability ETH_CFG_AUTO use auto negotiation ETH_CFG_AUTO_MDIX use/advertise auto MDIX capability ETH_CFG_FDUPLEX use/advertise full duplex capability ETH_CFG_HDUPLEX use/advertise half duplex capability ETH_CFG_LINK set to 1 if you need to config the link to specific following parameters otherwise the default connection will be attempted depending on the selected PHY ETH_CFG_LINK_INIT_DELAY some PHYs need an initialization delay for insuring that the PHY is ready to transmit data. milliseconds ETH_CFG_SWAP_MDIX use swapped MDIX. else normal MDIX Description The configuration of the MAC TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the MAC TCP/IP Stack. Based on the selections made, the MAC TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the MAC TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.16.5.1 EMAC_RX_BUFF_SIZE Macro C #define EMAC_RX_BUFF_SIZE 1536 Description size of a RX buffer. should be multiple of 16 this is the size of all receive buffers processed by the ETHC The size should be enough to accomodate any network received packet If the packets are larger, they will have to take multiple RX buffers and the packet manipulation is less efficient #define EMAC_RX_BUFF_SIZE 512 5.8.16.5.2 EMAC_RX_DESCRIPTORS Macro C #define EMAC_RX_DESCRIPTORS 6 Description number of the RX descriptors and RX buffers to be created 5.8.16.5.3 EMAC_RX_FRAGMENTS Macro C #define EMAC_RX_FRAGMENTS ((EMAC_RX_MAX_FRAME + (EMAC_RX_BUFF_SIZE -1 )) / (EMAC_RX_BUFF_SIZE)) Description MAC maximum number of supported fragments Based on the values of EMAC_RX_MAX_FRAME and EMAC_RX_BUFF_SIZE an incoming frame may span multiple RX buffers (fragments). Note that excessive fragmentation leads to performance degradation. The default and recommended value should be 1. #define EMAC_RX_FRAGMENTS 1 Alternatively you can use the calculation of the number of fragments based on the selected RX sizes: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3750 5.8.16.5.4 EMAC_RX_MAX_FRAME Macro C #define EMAC_RX_MAX_FRAME 1536 Description Maximum MAC supported RX frame size. Any incoming ETH frame that's longer than this size will be discarded. The default value is 1536 (allows for VLAN tagged frames, although the VLAN tagged frames are discarded) Normally you shouldn't need to touch this value unless you know exactly the maximum size of the frames you want to process or you need to control packets fragmentation (together with the EMAC_RX_BUFF_SIZE. Remarks Always multiple of 16! 5.8.16.5.5 EMAC_TX_DESCRIPTORS Macro C #define EMAC_TX_DESCRIPTORS 8 Description number of the TX descriptors to be created 5.8.16.5.6 ETH_CFG_10 Macro C #define ETH_CFG_10 1 Description use/advertise 10 Mbps capability 5.8.16.5.7 ETH_CFG_100 Macro C #define ETH_CFG_100 1 Description use/advertise 100 Mbps capability 5.8.16.5.8 ETH_CFG_AUTO Macro C #define ETH_CFG_AUTO 1 Description use auto negotiation 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3751 5.8.16.5.9 ETH_CFG_AUTO_MDIX Macro C #define ETH_CFG_AUTO_MDIX 1 Description use/advertise auto MDIX capability 5.8.16.5.10 ETH_CFG_FDUPLEX Macro C #define ETH_CFG_FDUPLEX 1 Description use/advertise full duplex capability 5.8.16.5.11 ETH_CFG_HDUPLEX Macro C #define ETH_CFG_HDUPLEX 1 Description use/advertise half duplex capability 5.8.16.5.12 ETH_CFG_LINK Macro C #define ETH_CFG_LINK 0 Description set to 1 if you need to config the link to specific following parameters otherwise the default connection will be attempted depending on the selected PHY 5.8.16.5.13 ETH_CFG_LINK_INIT_DELAY Macro C #define ETH_CFG_LINK_INIT_DELAY 500 Description some PHYs need an initialization delay for insuring that the PHY is ready to transmit data. milliseconds 5.8.16.5.14 ETH_CFG_SWAP_MDIX Macro C #define ETH_CFG_SWAP_MDIX 1 Description use swapped MDIX. else normal MDIX 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3752 5.8.16.6 Building the Library This section list the files that are available in the \src of the MAC driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.16.7 Library Interface Data Types and Constants Name Description 5.8.16.7.1 Functions 5.8.16.7.1.1 TCPIP_MAC_Close Function C TCPIP_MAC_RES TCPIP_MAC_Close( TCPIP_MAC_HANDLE hMac ); Description closes a MAC client 5.8.16.7.1.2 TCPIP_MAC_Deinitialize Function C TCPIP_MAC_RES TCPIP_MAC_Deinitialize( const TCPIP_MAC_MODULE_CTRL * const ); Description MAC de-initialization function Returns a result to indicate that everything has been cleaned up. 5.8.16.7.1.3 TCPIP_MAC_EventAcknowledge Function C bool TCPIP_MAC_EventAcknowledge( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_EVENT macEvents ); Description acknowledges reported event(s) returns false if no event to be acknowledged true otherwise 5.8.16.7.1.4 TCPIP_MAC_EventMaskSet Function C bool TCPIP_MAC_EventMaskSet( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3753 ); Description enables/disables the events to be reported multiple events could be or-ed returns false if some error occurred 5.8.16.7.1.5 TCPIP_MAC_EventPendingGet Function C TCPIP_MAC_EVENT TCPIP_MAC_EventPendingGet( TCPIP_MAC_HANDLE hMac ); Description returns current pending events 5.8.16.7.1.6 TCPIP_MAC_Initialize Function C TCPIP_MAC_RES TCPIP_MAC_Initialize( TCPIP_MAC_MODULE_CTRL* const stackData, const void* const moduleData ); Description TCPIP_MAC_Initialize 5.8.16.7.1.7 TCPIP_MAC_LinkCheck Function C bool TCPIP_MAC_LinkCheck( TCPIP_MAC_HANDLE hMac ); Description Link Interface functions 5.8.16.7.1.8 TCPIP_MAC_Open Function C TCPIP_MAC_HANDLE TCPIP_MAC_Open( unsigned int macId ); Description function to open a MAC and get a client handle 5.8.16.7.1.9 TCPIP_MAC_PacketRx Function C TCPIP_MAC_PACKET* TCPIP_MAC_PacketRx( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3754 Description TCPIP_MAC_PacketRx This is the MAC receive function. Once a pending packet is available in the MAC driver internal RX queues this function will dequeue the packet and hand it over to the MAC driver's client - i.e. the stack - for further processing. The flags for a RX packet have to be updated by the MAC driver: • TCPIP_MAC_PKT_FLAG_RX has to be set If the MAC supports it, it should set: • TCPIP_MAC_PKT_FLAG_UNICAST has to be set if that packet is a unicast packet • TCPIP_MAC_PKT_FLAG_BCAST has to be set if that packet is a broadcast packet • TCPIP_MAC_PKT_FLAG_MCAST has to be set if that packet is a multicast packet • TCPIP_MAC_PKT_FLAG_QUEUED has to be set • TCPIP_MAC_PKT_FLAG_SPLIT has to be set if the packet has multiple data segments Additional information about the packet is available by providing the pRes and ppPktStat fields. Parameters Parameters Description hMac handle identifying the MAC driver client pRes optional pointer to an address that will receive an additional result associated with the operation. Can be 0 if not needed. ppPktStat optional pointer to an address that will receive the received packet status. Note that this pointer cannot be used once the packet acknowledgement function was called. Can be 0 if not needed. Returns a valid pointer to an available RX packet 0 if no packet pending/available Remarks The MAC driver should dequeue and return to the caller just one single packet, and not multiple chained packets! Once the higher level layers in the stack are done with processing the RX packet, they have to call the corresponding packet acknowledgement function that tells the owner of that packet that it can resume control of that packet. Once the stack modules are done processing the RX packets and the acknowledge function is called it is up to the driver design to reuse the RX packets, or simply return them to the pool they were allocated from (assuming that some sort of allocation is implemented). This document makes no requirement about how the MAC RX packets are obtained, using dynamic or static allocation techniques. This is up to the design of the MAC. The MAC driver can use the TCPIP_MAC_Process() for obtaining new RX packets if needed. Not all the MACs have hardware support for the received packet status. If the MAC driver cannot supply the TCPIP_MAC_PACKET_RX_STAT info, it should set the ppPktStat to 0. 5.8.16.7.1.10 TCPIP_MAC_PacketTx Function C TCPIP_MAC_RES TCPIP_MAC_PacketTx( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3755 Description TCPIP_MAC_PacketTx This is the MAC transmit function. The MAC driver has to suport internal queueing! A packet is to be rejected only if it's not properly formatted. Otherwise it has to be scheduled for transmission in an internal queue! Once the packet is scheduled for transmission the MAC driver has to set the TCPIP_MAC_PKT_FLAG_QUEUED flag so that the stack is aware that this packet is under processing cnd cannot be modified! Once the packet is transmitted, the TCPIP_MAC_PKT_FLAG_QUEUED has to be cleared, the proper packet acknowledgement result (ackRes) has to be set and the packet acknowledgement function (ackFunc) has to be called. It is implementation dependant if all these steps are implemented as part of the ackFunc itself or as discrete steps. Parameters Parameters Description hMac handle identifying the MAC driver client ptrPacket pointer to a TCPIP_MAC_PACKET that's completely formatted and ready to be transmitted over the network Remarks See notes for the segLoadOffset member. On 32 bit machines the 1st segment payload of a packet is allocated so that it is always 32 bit aligned and its size is 32 bits multiple. The segLoadOffset adds to the payload address and insures that the network layer data is 32 bit aligned. • PIC32 MAC driver specific : the driver checks that the segLoadOffset >= 2. The packet is not required to contain the Frame Check Sequence (FCS/CRC32) field. The MAC driver/controller will insert that field itself, if it's required. The MAC driver is required to support the transmission of multiple chained packets. 5.8.16.7.1.11 TCPIP_MAC_Process Function C TCPIP_MAC_RES TCPIP_MAC_Process( TCPIP_MAC_HANDLE hMac ); Description TCPIP_MAC_Process This is a function that allows for internal processing by the MAC driver. It is meant for processing that cannot be done from within ISR. Some of the processing that this is intended for: • the MAC driver can process its pending TX queues (although it should do that preferrably from within the TX ISR) • RX buffers replenishing. If the number of packets in the RX queue falls below a specified limit, the MAC driver can use this function to allocate some extra RX packets. Similarly, if there are too many allocated RX packets, the MAC driver can free some of them. Normally this function will be called in response to an TX and/or RX event signalled by the driver. This is specified by the MAC driver at initialization time using TCPIP_MAC_MODULE_CTRL. An alternative approach is that the MAC driver uses a system service to create a timer signal that will call the TCPIP_MAC_Process on a periodic basis. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3756 Parameters Parameters Description hMac handle identifying the MAC driver client Returns TCPIP_MAC_RES_OK if all processing went on OK a TCPIP_MAC_RES error code if processing failed for some reason Remarks None. 5.8.16.7.1.12 TCPIP_MAC_Reinitialize Function C TCPIP_MAC_RES TCPIP_MAC_Reinitialize( const TCPIP_MAC_MODULE_CTRL* const stackData, const void* const moduleData ); Description MAC re-initialization function Allows re-initialization of the MAC with different power modes, etc. probably the same signature as TCPIP_MAC_Initialize Optional function 5.8.16.7.1.13 TCPIP_MAC_RxFilterHashTableEntrySet Function C TCPIP_MAC_RES TCPIP_MAC_RxFilterHashTableEntrySet( TCPIP_MAC_HANDLE hMac, TCPIP_MAC_ADDR* DestMACAddr ); Description set the hash table filter 5.8.16.7.2 Data Types and Constants 5.8.16.7.2.1 TCPIP_MAC_ACTION Enumeration C typedef enum { TCPIP_MAC_ACTION_INIT, TCPIP_MAC_ACTION_REINIT, TCPIP_MAC_ACTION_DEINIT, TCPIP_MAC_ACTION_IF_UP, TCPIP_MAC_ACTION_IF_DOWN } TCPIP_MAC_ACTION; Description • Interface functions *********************************** network interface action for initialization/de-initialization 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3757 Members Members Description TCPIP_MAC_ACTION_INIT stack is initialized TCPIP_MAC_ACTION_REINIT stack is re-initialized TCPIP_MAC_ACTION_DEINIT stack is de-initialized TCPIP_MAC_ACTION_IF_UP interface is brought up TCPIP_MAC_ACTION_IF_DOWN interface is brought down 5.8.16.7.2.2 TCPIP_MAC_ADDR Structure C typedef struct { uint8_t v[6]; } TCPIP_MAC_ADDR; Description Structure to contain a MAC address 5.8.16.7.2.3 TCPIP_MAC_DATA_SEGMENT Type C typedef struct _tag_MAC_DATA_SEGMENT TCPIP_MAC_DATA_SEGMENT; Description TCPIP MAC Data Segment Structure of a segment buffer transferred with the MAC. A MAC TX or RX packet can consist of multiple data segments. On TX the MAC has to be able to transmit packets that span multiple data segments. On RX of a network frame the MAC may have to use multiple segments to construct a packet. (For performance reasons, a contiguous MAC packet, with just one segment, if possible, is preferred). Remarks See notes for the segLoadOffset member. On 32 bit machines the segment payload is allocated so that it is always 32 bit aligned and its size is 32 bits multiple. The segLoadOffset adds to the payload address and insures that the network layer data is 32 bit aligned. 5.8.16.7.2.4 TCPIP_MAC_ETHERNET_HEADER Structure C typedef struct { TCPIP_MAC_ADDR DestMACAddr; TCPIP_MAC_ADDR SourceMACAddr; uint16_t Type; } TCPIP_MAC_ETHERNET_HEADER; Description A generic structure representing the Ethernet header starting all Ethernet frames 5.8.16.7.2.5 TCPIP_MAC_EVENT Enumeration C typedef enum { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3758 TCPIP_MAC_EV_NONE = 0x0000, TCPIP_MAC_EV_RX_PKTPEND = 0x0001, TCPIP_MAC_EV_RX_OVFLOW = 0x0002, TCPIP_MAC_EV_RX_BUFNA = 0x0004, TCPIP_MAC_EV_RX_ACT = 0x0008, TCPIP_MAC_EV_RX_DONE = 0x0010, TCPIP_MAC_EV_RX_FWMARK = 0x0020, TCPIP_MAC_EV_RX_EWMARK = 0x0040, TCPIP_MAC_EV_RX_BUSERR = 0x0080, TCPIP_MAC_EV_TX_DONE = 0x0100, TCPIP_MAC_EV_TX_ABORT = 0x0200, TCPIP_MAC_EV_TX_BUSERR = 0x0400, TCPIP_MAC_EV_CONN_ESTABLISHED = 0x0800, TCPIP_MAC_EV_CONN_LOST = 0x1000, TCPIP_MAC_EV_RX_ALL = (TCPIP_MAC_EV_RX_PKTPEND|TCPIP_MAC_EV_RX_OVFLOW|TCPIP_MAC_EV_RX_BUFNA|TCPIP_MAC_EV_RX_ACT| TCPIP_MAC_EV_RX_DONE|TCPIP_MAC_EV_RX_FWMARK|TCPIP_MAC_EV_RX_EWMARK|TCPIP_MAC_EV_RX_BUSERR), TCPIP_MAC_EV_TX_ALL = (TCPIP_MAC_EV_TX_DONE|TCPIP_MAC_EV_TX_ABORT|TCPIP_MAC_EV_TX_BUSERR), TCPIP_MAC_EV_RXTX_ERRORS = (TCPIP_MAC_EV_RX_OVFLOW|TCPIP_MAC_EV_RX_BUFNA|TCPIP_MAC_EV_RX_BUSERR|TCPIP_MAC_EV_TX_ABORT|TCPI P_MAC_EV_TX_BUSERR), TCPIP_MAC_EV_CONN_ALL = (TCPIP_MAC_EV_CONN_ESTABLISHED|TCPIP_MAC_EV_CONN_LOST) } TCPIP_MAC_EVENT; Description TCPIP MAC Events Codes This enumeration defines all the possible events that can be reported by the MAC to the stack. Depending on the type of the hardware Ethernet/WiFi interface, etc., not all events are possible. Members Members D e s c r i p t i o n TCPIP_MAC_EV_NONE = 0x0000 n o e v e n t 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3759 TCPIP_MAC_EV_RX_PKTPEND = 0x0001 R X t r i g g e r e d e v e n t s A r e c e i v e p a c k e t i s p e n d i n g 5.8.16.7.2.6 TCPIP_MAC_EventF Type C typedef void (* TCPIP_MAC_EventF)(TCPIP_MAC_EVENT event, const void* eventParam); Description event notification Function: typedef void (*TCPIP_MAC_EventF)(TCPIP_MAC_EVENT event, const void* eventParam); This function describes the MAC event notification handler. This is a handler specified by the user of the MAC (the TCP/IP stack). The stack can use the handler to be notified of MAC events. Whenever a notification occurs the passed events have to be eventually processed: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3760 • Stack should process the TCPIP_EV_RX_PKTPEND/TCPIP_EV_RX_DONE, TCPIP_EV_TX_DONE events • Process the specific (error) condition • Acknowledge the events by calling TCPIP_MAC_EventAcknowledge() so that they can be re-enabled. Preconditions None Parameters Parameters Description event event that's reported (multiple events can be OR-ed) eventParam user parameter that's used in the notification handler Returns None Remarks The notification handler will be called from the ISR which detects the corresponding event. The event notification handler has to be kept as short as possible and non-blocking. Mainly useful for RTOS integration where this handler will wake-up a thread that waits for a MAC event to occur. The event notification system also enables the user of the TCPIP stack to call into the stack for processing only when there are relevant events rather than being forced to periodically call from within a loop at unknown moments. Without a notification handler the stack user can still call TCPIP_MAC_EventPendingGet() to see if processing by the stack needed. This is a default way of adding MAC interrupt processing to the TCP/IP stack. 5.8.16.7.2.7 TCPIP_MAC_HANDLE Type C typedef const void* TCPIP_MAC_HANDLE; Description handle to a MAC 5.8.16.7.2.8 TCPIP_MAC_HEAP_CallocF Type C typedef void* (* TCPIP_MAC_HEAP_CallocF)(TCPIP_MAC_HEAP_HANDLE heapH, size_t nElems, size_t elemSize); Description calloc function 5.8.16.7.2.9 TCPIP_MAC_HEAP_FreeF Type C typedef int (* TCPIP_MAC_HEAP_FreeF)(TCPIP_MAC_HEAP_HANDLE heapH, const void* pBuff); Description free function 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3761 5.8.16.7.2.10 TCPIP_MAC_HEAP_HANDLE Type C typedef const void* TCPIP_MAC_HEAP_HANDLE; Description handle to a heap 5.8.16.7.2.11 TCPIP_MAC_HEAP_MallocF Type C typedef void* (* TCPIP_MAC_HEAP_MallocF)(TCPIP_MAC_HEAP_HANDLE heapH, size_t nBytes); Description malloc function 5.8.16.7.2.12 TCPIP_MAC_MODULE_CTRL Structure C typedef struct { int nIfs; TCPIP_MAC_HEAP_MallocF mallocF; TCPIP_MAC_HEAP_CallocF callocF; TCPIP_MAC_HEAP_FreeF freeF; TCPIP_MAC_HEAP_HANDLE memH; TCPIP_MAC_PKT_AllocF pktAllocF; TCPIP_MAC_PKT_FreeF pktFreeF; TCPIP_MAC_PKT_AckF pktAckF; TCPIP_MAC_EventF eventF; const void* eventParam; unsigned int moduleId; int netIx; TCPIP_MAC_ACTION macAction; TCPIP_MAC_POWER_MODE powerMode; TCPIP_MAC_ADDR ifPhyAddress; TCPIP_MAC_PROCESS_FLAGS processFlags; } TCPIP_MAC_MODULE_CTRL; Description data that's passed as reference to MAC driver module init/deinit. Members Members Description int nIfs; permanent data; this data is maintained by the stack for one full session i.e. accross Initialize() -> DeInitialize() calls number of the interfaces supported in this seession TCPIP_MAC_HEAP_MallocF mallocF; transient data; contains info for a specific module call allocation functions/parameters TCPIP_MAC_HEAP_HANDLE memH; handle to be used in the stack allocation service calls TCPIP_MAC_PKT_AllocF pktAllocF; packet allocation functions TCPIP_MAC_EventF eventF; function to be used by the MAC for event reporting const void* eventParam; parameter to be used when the event function is called unsigned int moduleId; module identifier; allows multiple channels/ports, etc. MAC support int netIx; index of the current interface 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3762 TCPIP_MAC_ACTION macAction; current action for the MAC/stack TCPIP_MAC_POWER_MODE powerMode; the power mode for this interface to go to valid only if stackAction == init/re-init; ignored for de-init TCPIP_MAC_ADDR ifPhyAddress; physical address of the interface 5.8.16.7.2.13 TCPIP_MAC_PACKET Type C typedef struct _tag_TCPIP_MAC_PACKET TCPIP_MAC_PACKET; Description forward declaration 5.8.16.7.2.14 TCPIP_MAC_PACKET_ACK_FUNC Type C typedef void (* TCPIP_MAC_PACKET_ACK_FUNC)(TCPIP_MAC_PACKET* pkt, const void* param); Description This is type TCPIP_MAC_PACKET_ACK_FUNC. 5.8.16.7.2.15 TCPIP_MAC_PACKET_FLAGS Enumeration C typedef enum { TCPIP_MAC_PKT_FLAG_STATIC = 0x0001, TCPIP_MAC_PKT_FLAG_TX = 0x0002, TCPIP_MAC_PKT_FLAG_SPLIT = 0x0004, TCPIP_MAC_PKT_FLAG_QUEUED = 0x0008, TCPIP_MAC_PKT_FLAG_UNICAST = 0x0010, TCPIP_MAC_PKT_FLAG_BCAST = 0x0020, TCPIP_MAC_PKT_FLAG_MCAST = 0x0040, TCPIP_MAC_PKT_FLAG_CAST_MASK = 0x0070, TCPIP_MAC_PKT_FLAG_CAST_DISABLED = 0x0000, TCPIP_MAC_PKT_FLAG_USER = 0x0100 } TCPIP_MAC_PACKET_FLAGS; Description 16 bits only packet flags! Members Members Description TCPIP_MAC_PKT_FLAG_STATIC = 0x0001 packet/segment can not be dynamically deallocated set when the packet is allocated TCPIP_MAC_PKT_FLAG_TX = 0x0002 if set, it's an TX packet/segment else is an RX packet TCPIP_MAC_PKT_FLAG_SPLIT = 0x0004 packet data spans multiple segments - ZC functionality if not set the packet has only one data segment set by the MAC driver when a RX packet spans multiple data segments TCPIP_MAC_PKT_FLAG_QUEUED = 0x0008 packet data is queued somewhere, cannot be freed flag is set by the packet source when the packet is passed for further processing to a destination cleared by the packet destination when the packet processing was completed. TCPIP_MAC_PKT_FLAG_UNICAST = 0x0010 MAC updated: it's an unicast packet 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3763 TCPIP_MAC_PKT_FLAG_BCAST = 0x0020 MAC updated: it's an broadcast packet TCPIP_MAC_PKT_FLAG_MCAST = 0x0040 MAC updated: it's an multicast packet TCPIP_MAC_PKT_FLAG_CAST_MASK = 0x0070 packet cast mask bits TCPIP_MAC_PKT_FLAG_CAST_DISABLED = 0x0000 if all zeroes MAC packet MCAST/BCAST fields are not updated by the MAC RX process TCPIP_MAC_PKT_FLAG_USER = 0x0100 available user flags start here 5.8.16.7.2.16 TCPIP_MAC_PACKET_RX_STAT Structure C typedef struct { unsigned chksumOk : 1; unsigned pktChecksum : 16; unsigned runtPkt : 1; unsigned notMeUcast : 1; unsigned htMatch : 1; unsigned magicMatch : 1; unsigned pmMatch : 1; unsigned uMatch : 1; unsigned bMatch : 1; unsigned mMatch : 1; unsigned rxBytes : 16; unsigned crcError : 1; unsigned lenError : 1; unsigned lenRange : 1; unsigned rxOk : 1; unsigned mcast : 1; unsigned bcast : 1; unsigned rxCtrl : 1; unsigned rxVLAN : 1; } TCPIP_MAC_PACKET_RX_STAT; Description Received Packet Status This structure contains the status of a received packet. Members Members Description unsigned chksumOk : 1; correct checksum filled in unsigned pktChecksum : 16; Packet payload checksum unsigned runtPkt : 1; Runt packet received unsigned notMeUcast : 1; Unicast, not me packet, unsigned htMatch : 1; Hash table match unsigned magicMatch : 1; Magic packet match unsigned pmMatch : 1; Pattern match match unsigned uMatch : 1; Unicast match unsigned bMatch : 1; Broadcast match unsigned mMatch : 1; Multicast match unsigned rxBytes : 16; Received bytes unsigned crcError : 1; CRC error in packet unsigned lenError : 1; Receive length check error 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3764 unsigned lenRange : 1; Receive length out of range unsigned rxOk : 1; Receive OK unsigned mcast : 1; Multicast packet unsigned bcast : 1; Broadcast packet unsigned rxCtrl : 1; Control frame received unsigned rxVLAN : 1; Received VLAN tagged frame Remarks Not all the MACs have hardware support for the received packet status. 5.8.16.7.2.17 TCPIP_MAC_PKT_ACK_RES Enumeration C typedef enum { TCPIP_MAC_PKT_ACK_NONE = 0, TCPIP_MAC_PKT_ACK_TX_OK = 1, TCPIP_MAC_PKT_ACK_RX_OK = 2, TCPIP_MAC_PKT_ACK_LINK_DOWN = -1, TCPIP_MAC_PKT_ACK_NET_DOWN = -2, TCPIP_MAC_PKT_ACK_BUFFER_ERR = -3, TCPIP_MAC_PKT_ACK_ARP_TMO = -4, TCPIP_MAC_PKT_ACK_ARP_NET_ERR = -5, TCPIP_MAC_PKT_ACK_CHKSUM_ERR = -10, TCPIP_MAC_PKT_ACK_SOURCE_ERR = -11, TCPIP_MAC_PKT_ACK_TYPE_ERR = -12, TCPIP_MAC_PKT_ACK_STRUCT_ERR = -13, TCPIP_MAC_PKT_ACK_PROTO_DEST_ERR = -14, TCPIP_MAC_PKT_ACK_FRAGMENT_ERR = -15, TCPIP_MAC_PKT_ACK_PROTO_DEST_CLOSE = -16, TCPIP_MAC_PKT_ACK_ALLOC_ERR = -17 } TCPIP_MAC_PKT_ACK_RES; Description list of return codes for a packet acknowledge function 16 bits only acknowledge results! Members Members Description TCPIP_MAC_PKT_ACK_NONE = 0 packet result unknown, unspecified TX success code - positive TCPIP_MAC_PKT_ACK_TX_OK = 1 packet was transmitted successfully RX success code - positive TCPIP_MAC_PKT_ACK_RX_OK = 2 packet was received/processed successfully TX error codes - negative TCPIP_MAC_PKT_ACK_LINK_DOWN = -1 packet was dropped because the link was down TCPIP_MAC_PKT_ACK_NET_DOWN = -2 packet was dropped because the network is down TCPIP_MAC_PKT_ACK_BUFFER_ERR = -3 packet was dropped because the buffer type is not supported TCPIP_MAC_PKT_ACK_ARP_TMO = -4 packet was dropped because of an ARP timeout TCPIP_MAC_PKT_ACK_ARP_NET_ERR = -5 packet associated interface is down or non existent RX error codes - negative TCPIP_MAC_PKT_ACK_CHKSUM_ERR = -10 packet was dropped because the checksum was incorrect TCPIP_MAC_PKT_ACK_SOURCE_ERR = -11 packet was dropped because of wrong interface source address TCPIP_MAC_PKT_ACK_TYPE_ERR = -12 packet was dropped because the type was unknown TCPIP_MAC_PKT_ACK_STRUCT_ERR = -13 internal packet structure error 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3765 TCPIP_MAC_PKT_ACK_PROTO_DEST_ERR = -14 the packet protocol couldn't find a destination for it TCPIP_MAC_PKT_ACK_FRAGMENT_ERR = -15 the packet too fragmented TCPIP_MAC_PKT_ACK_PROTO_DEST_CLOSE = -16 the packet destination is closing TCPIP_MAC_PKT_ACK_ALLOC_ERR = -17 memory allocation error 5.8.16.7.2.18 TCPIP_MAC_PKT_AckF Type C typedef void (* TCPIP_MAC_PKT_AckF)(TCPIP_MAC_PACKET* pPkt, TCPIP_MAC_PKT_ACK_RES ackRes); Description acknowledges a packet clears the TCPIP_MAC_PKT_FLAG_QUEUED flag a packet should always have an acknowledgment function packet's ackRes is updated only if the parameter ackRes != TCPIP_MAC_PKT_ACK_NONE. 5.8.16.7.2.19 TCPIP_MAC_PKT_AllocF Type C typedef TCPIP_MAC_PACKET* (* TCPIP_MAC_PKT_AllocF)(uint16_t pktLen, uint16_t segLoadLen, TCPIP_MAC_PACKET_FLAGS flags); Description allocates a TCPIP_MAC_PACKET packet (TCPIP_MAC_ETHERNET_HEADER always added); pktLen - the size of the packet (it will be 32 bits rounded up) segLoadLen - the payload size for the segment associated to this packet; Payload is always 32 bit aligned if 0 no segment is created/attached to the packet 5.8.16.7.2.20 TCPIP_MAC_PKT_FreeF Type C typedef void (* TCPIP_MAC_PKT_FreeF)(TCPIP_MAC_PACKET* pPkt); Description frees a previously allocated packet that neither the packet nor segments marked with TCPIP_MAC_PKT_FLAG_STATIC/TCPIP_MAC_SEG_FLAG_STATIC are not freed Also note that this function does not free explicitely the external segment payload. A payload that was created contiguously when the segment was created will be automatically freed by this function. 5.8.16.7.2.21 TCPIP_MAC_POWER_MODE Enumeration C typedef enum { TCPIP_MAC_POWER_NONE, TCPIP_MAC_POWER_FULL, TCPIP_MAC_POWER_LOW, TCPIP_MAC_POWER_DOWN } TCPIP_MAC_POWER_MODE; Description supported MAC power mode state 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3766 Members Members Description TCPIP_MAC_POWER_NONE unknown power mode; TCPIP_MAC_POWER_FULL up and running; valid for init/re-init TCPIP_MAC_POWER_LOW low power mode; valid for init/re-init TCPIP_MAC_POWER_DOWN interface is down; 5.8.16.7.2.22 TCPIP_MAC_PROCESS_FLAGS Enumeration C typedef enum { TCPIP_MAC_PROCESS_FLAG_NONE = 0x0000, TCPIP_MAC_PROCESS_FLAG_RX = 0x0001, TCPIP_MAC_PROCESS_FLAG_TX = 0x0002, TCPIP_MAC_PROCESS_FLAG_ANY = 0x0100 } TCPIP_MAC_PROCESS_FLAGS; Description specific MAC process flags multiple flags can be orred Members Members Description TCPIP_MAC_PROCESS_FLAG_NONE = 0x0000 the stack never has to call the TCPIP_MAC_Process function TCPIP_MAC_PROCESS_FLAG_RX = 0x0001 the stack has to call the TCPIP_MAC_Process after an RX signal TCPIP_MAC_PROCESS_FLAG_TX = 0x0002 the stack has to call the TCPIP_MAC_Process after an TX signal TCPIP_MAC_PROCESS_FLAG_ANY = 0x0100 the stack has to call the TCPIP_MAC_Process after any type of signal 5.8.16.7.2.23 TCPIP_MAC_RES Enumeration C typedef enum { TCPIP_MAC_RES_OK = 0, TCPIP_MAC_RES_PENDING = 1, TCPIP_MAC_RES_TYPE_ERR = -1, TCPIP_MAC_RES_IS_BUSY = -2, TCPIP_MAC_RES_INIT_FAIL = -3, TCPIP_MAC_RES_PHY_INIT_FAIL = -4, TCPIP_MAC_RES_EVENT_INIT_FAIL = -5, TCPIP_MAC_RES_OP_ERR = -6, TCPIP_MAC_RES_ALLOC_ERR = -7, TCPIP_MAC_RES_INSTANCE_ERR = -8, TCPIP_MAC_RES_FRAGMENT_ERR = -9, TCPIP_MAC_RES_PACKET_ERR = -10, TCPIP_MAC_RES_QUEUE_TX_FULL = -11 } TCPIP_MAC_RES; Description list of return codes from MAC functions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3767 Members Members Description TCPIP_MAC_RES_OK = 0 operation successful benign operation results - positive codes TCPIP_MAC_RES_PENDING = 1 operation is pending upon some hardware resource call again to completion error codes - negative TCPIP_MAC_RES_TYPE_ERR = -1 unsupported type TCPIP_MAC_RES_IS_BUSY = -2 device is in use TCPIP_MAC_RES_INIT_FAIL = -3 generic initialization failure TCPIP_MAC_RES_PHY_INIT_FAIL = -4 PHY initialization failure TCPIP_MAC_RES_EVENT_INIT_FAIL = -5 Event system initialization failure TCPIP_MAC_RES_OP_ERR = -6 unsupported operation TCPIP_MAC_RES_ALLOC_ERR = -7 memory allocation error TCPIP_MAC_RES_INSTANCE_ERR = -8 already instantiated, initialized error TCPIP_MAC_RES_FRAGMENT_ERR = -9 too fragmented, RX buffer too small TCPIP_MAC_RES_PACKET_ERR = -10 unsupported/corrupted packet error TCPIP_MAC_RES_QUEUE_TX_FULL = -11 TX queue exceeded the limit 5.8.16.7.2.24 TCPIP_MAC_SEGMENT_FLAGS Enumeration C typedef enum { TCPIP_MAC_SEG_FLAG_STATIC = 0x0001, TCPIP_MAC_SEG_FLAG_TX = 0x0002, TCPIP_MAC_SEG_FLAG_USER = 0x0100 } TCPIP_MAC_SEGMENT_FLAGS; Description 16 bits only segment flags! Members Members Description TCPIP_MAC_SEG_FLAG_STATIC = 0x0001 segment can not be dynamically deallocated set when the segment is allocated TCPIP_MAC_SEG_FLAG_TX = 0x0002 if set, it's an TX segment else is an RX packet available user segment flags start here 5.8.16.7.2.25 TCPIP_MODULE_MAC_97J60_CONFIG Structure C typedef struct { } TCPIP_MODULE_MAC_97J60_CONFIG; Description This is type TCPIP_MODULE_MAC_97J60_CONFIG. 5.8.16.7.2.26 TCPIP_MODULE_MAC_ENCJ60_CONFIG Structure C typedef struct { } TCPIP_MODULE_MAC_ENCJ60_CONFIG; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3768 Description MAC initialization data Each supported MAC has its own specific init/configuration data 5.8.16.7.2.27 TCPIP_MODULE_MAC_ENCJ600_CONFIG Structure C typedef struct { } TCPIP_MODULE_MAC_ENCJ600_CONFIG; Description This is type TCPIP_MODULE_MAC_ENCJ600_CONFIG. 5.8.16.7.2.28 TCPIP_MODULE_MAC_MRF24W_CONFIG Structure C typedef struct { } TCPIP_MODULE_MAC_MRF24W_CONFIG; Description This is type TCPIP_MODULE_MAC_MRF24W_CONFIG. 5.8.16.7.2.29 TCPIP_MODULE_MAC_PIC32INT_CONFIG Structure C typedef struct { int nTxDescriptors; int rxBuffSize; int nRxDescriptors; } TCPIP_MODULE_MAC_PIC32INT_CONFIG; Description This is type TCPIP_MODULE_MAC_PIC32INT_CONFIG. Members Members Description int nTxDescriptors; number of TX descriptors int rxBuffSize; size of the corresponding RX buffer int nRxDescriptors; number of RX descriptors 5.8.16.8 Files Files Name Description tcpip_mac.h tcpip_mac_config.h configuration file Description 5.8 TCP/IP Stack Library Help MPLAB Harmony Help MAC TCP/IP Stack Library 5-3769 5.8.16.8.1 tcpip_mac.h MAC Module Defs for Microchip Stack Enumerations Name Description 5.8.16.8.2 tcpip_mac_config.h MAC Configuration file This file contains the MAC module configuration options Macros Name Description EMAC_RX_BUFF_SIZE size of a RX buffer. should be multiple of 16 this is the size of all receive buffers processed by the ETHC The size should be enough to accomodate any network received packet If the packets are larger, they will have to take multiple RX buffers and the packet manipulation is less efficient #define EMAC_RX_BUFF_SIZE 512 EMAC_RX_DESCRIPTORS number of the RX descriptors and RX buffers to be created EMAC_RX_FRAGMENTS MAC maximum number of supported fragments Based on the values of EMAC_RX_MAX_FRAME and EMAC_RX_BUFF_SIZE an incoming frame may span multiple RX buffers (fragments). Note that excessive fragmentation leads to performance degradation. The default and recommended value should be 1. #define EMAC_RX_FRAGMENTS 1 Alternatively you can use the calculation of the number of fragments based on the selected RX sizes: EMAC_RX_MAX_FRAME Maximum MAC supported RX frame size. Any incoming ETH frame that's longer than this size will be discarded. The default value is 1536 (allows for VLAN tagged frames, although the VLAN tagged frames are discarded) Normally you shouldn't need to touch this value unless you know exactly the maximum size of the frames you want to process or you need to control packets fragmentation (together with the EMAC_RX_BUFF_SIZE. EMAC_TX_DESCRIPTORS number of the TX descriptors to be created ETH_CFG_10 use/advertise 10 Mbps capability ETH_CFG_100 use/advertise 100 Mbps capability ETH_CFG_AUTO use auto negotiation ETH_CFG_AUTO_MDIX use/advertise auto MDIX capability ETH_CFG_FDUPLEX use/advertise full duplex capability ETH_CFG_HDUPLEX use/advertise half duplex capability ETH_CFG_LINK set to 1 if you need to config the link to specific following parameters otherwise the default connection will be attempted depending on the selected PHY ETH_CFG_LINK_INIT_DELAY some PHYs need an initialization delay for insuring that the PHY is ready to transmit data. milliseconds ETH_CFG_SWAP_MDIX use swapped MDIX. else normal MDIX 5.8.17 Manager TCP/IP Stack Library 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3770 5.8.17.1 Introduction Manager TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the Manager TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Handles internal RX packet pre-processing prior to dispatching to upper application layers. 5.8.17.2 Release Notes MPLAB Harmony Version: v0.70b Manager TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.17.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.17.4 Using the Library This topic describes the basic architecture of the Manager TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: tcpip_manager.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3771 The interface to the Manager TCPIP Stack library is defined in the "tcpip_manager.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the Manager TCP/IP Stack library should include "tcpip.h". Library File: The Manager TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.17.4.1 Abstraction Model This library provides the API of the Manager TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Manager Software Abstraction Block Diagram Handles internal RX packet pre-processing prior to dispatching to upper application layers. 5.8.17.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the MAC module. Library Interface Section Description Task and Initialize Functions Routines to Initialize and De-Initialize this Module Network Up/Down/Linked Functions Routines to Set and Get the Network's Up/Down Status Network Status and Control Functions Routines to Set and Get the Various Network Controls Network Address Status and Control Functions Routines to Set and Get the Network's Address Status Network Structure Storage Functions Network Information Routines. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3772 Data Types and Constants This section provides various definitions describing This API 5.8.17.5 Configuring the Library The configuration of the Manager TCP/IP Stack is based on the file sys_config.h This header file contains the configuration selection for the Manager TCP/IP Stack. Based on the selections made, the Manager TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the Manager TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.17.6 Building the Library This section list the files that are available in the \src of the Manager driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.17.7 Library Interface Data Types and Constants Name Description TCPIP_LOCAL_MASK_TYPE types of masks used in the detection of a local/nonlocal network TCPIP_NET_HANDLE a network interface handle Network Address Status and Control Functions Name Description TCPIP_STACK_ModuleGetConfig This function returns the current configuration data of the stack module specified by the corresponding module ID. TCPIP_STACK_NetAddress TCPIP_STACK_NetAddressBcast TCPIP_STACK_NetAddressDnsPrimary TCPIP_STACK_NetAddressDnsPrimarySet TCPIP_STACK_NetAddressDnsSecond TCPIP_STACK_NetAddressDnsSecondSet TCPIP_STACK_NetAddressGateway TCPIP_STACK_NetAddressGatewaySet TCPIP_STACK_NetAddressMac TCPIP_STACK_NetAddressMacSet TCPIP_STACK_NetAddressSet TCPIP_STACK_NetIPv6AddressGet This function allows the listing of the IPv6 addresses associated with an interface. Network Status and Control Functions Name Description TCPIP_STACK_IndexToNet 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3773 TCPIP_STACK_NetBIOSName TCPIP_STACK_NetBiosNameSet TCPIP_STACK_NetDefaultGet TCPIP_STACK_NetDefaultSet TCPIP_STACK_NetHandleGet TCPIP_STACK_NetIndexGet TCPIP_STACK_NetMask TCPIP_STACK_NetNameGet TCPIP_STACK_NumberOfNetworksGet Network Structure Storage Functions Name Description TCPIP_STACK_NetConfigGet This function dumps the current configuration data of the network interface specified by the corresponding network handle into the supplied buffer. 5.8.17.7.1 Task and Initialize Functions 5.8.17.7.1.1 TCPIP_STACK_Deinitialize Function C void TCPIP_STACK_Deinitialize(); Description This function performs the de-initialization of the TCPIP stack Preconditions None Returns None Side Effects None Remarks None 5.8.17.7.1.2 TCPIP_STACK_Initialize Function C bool TCPIP_STACK_Initialize( const TCPIP_NETWORK_CONFIG* pNetConf, int nNets, const TCPIP_STACK_MODULE_CONFIG* pModConfig, int nModules ); Description The function initializes the stack. If an error occurs, the SYS_ERROR() is called and the function de-initialize itself and will return false. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3774 Preconditions None Parameters Parameters Description pNetConf pointer to an array of TCPIP_NETWORK_CONFIG to support nNets number of network configurations in the array pModConfig pointer to an array of TCPIP_STACK_MODULE_CONFIG nModules number of modules to initialize Returns true if Stack and its componets are initialized false otherwise Side Effects None Remarks This function must be called before any of the stack or its component routines are used. New TCPIP_NETWORK_CONFIG types should be added/removed at run time for implementations that support dynamic network interface creation. 5.8.17.7.1.3 TCPIP_STACK_SetLocalMasks Function C bool TCPIP_STACK_SetLocalMasks( TCPIP_NET_HANDLE netH, uint32_t andMask, uint32_t orMask ); Description This function sets the masks used in the stack decision of a destination address being a local or nonlocal address. These masks will be used when the corresponding mask type is set to TCPIP_LOCAL_MASK_SET. Preconditions None Parameters Parameters Description netH handle of the interface to use andMask AND mask to use for local network detection, big endian (BE) format orType OR mask to use for local network detection , BE format Returns if interface exists then this function will set the masks and return true. otherwise it will return false Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_SetLocalMasks(netH, 0x0101a0c0, 0x0); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3775 5.8.17.7.1.4 TCPIP_STACK_SetLocalMasksType Function C bool TCPIP_STACK_SetLocalMasksType( TCPIP_NET_HANDLE netH, TCPIP_LOCAL_MASK_TYPE andType, TCPIP_LOCAL_MASK_TYPE orType ); Description This function sets the types of masks used in the stack decision of a destination address being a local or nonlocal address. For example, when a TCP connection is made, the advertised MSS usually has different values for local versus nonlocal networks. In order to decide if a destination IP address (destAdd) is local to a network interface (having the netAdd address) the following calculation is performed: if( ((destAdd & andMask) | orMask) == ((netAdd & andMask) | orMask)) then the destination address is considered to be a local address. else the destination address is nonlocal. This function sets the types of masks used for the AND and OR operations, as follows: • TCPIP_LOCAL_MASK_ZERO: use the all 0's mask (0x00000000) • TCPIP_LOCAL_MASK_ONE: use the all 1's mask (0xffffffff) • TCPIP_LOCAL_MASK_NET: use the current network mask • TCPIP_LOCAL_MASK_SET: use a mask that's set by the application There are operations to set a specific AND and OR masks Using different valuse for the AND and OR masks an application can select various destination networks to be considered as local/nonlocal: • only the own network • any network • no network • specific (range of) networks • etc. Preconditions None Parameters Parameters Description netH handle of the interface to use andType AND type of mask to use for local network detection orType OR type of mask to use for local network detection Returns if interface exists then this function will set the mask types and return true. otherwise it will return false Remarks The default value for both AND and OR masks is set to TCPIP_LOCAL_MASK_ZERO so that any destination network is considered to be local! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_SetLocalMasksType(netH, TCPIP_LOCAL_MASK_NET, TCPIP_LOCAL_MASK_ZERO); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3776 5.8.17.7.1.5 TCPIP_STACK_Task Function C void TCPIP_STACK_Task(); Preconditions TCPIP_STACK_Initialize() is already called. Returns Stack Finite-state Machine (FSM) is executed. Side Effects None Remarks This FSM checks for new incoming packets, and routes it to appropriate stack components. It also performs timed operations. This function must be called periodically to ensure timely responses. 5.8.17.7.2 Network Status and Control Functions 5.8.17.7.2.1 TCPIP_STACK_IndexToNet Function C TCPIP_NET_HANDLE TCPIP_STACK_IndexToNet( int netIx ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle. Returns Resolves an index to an network handle. Side Effects None Remarks None 5.8.17.7.2.2 TCPIP_STACK_NetBIOSName Function C const char* TCPIP_STACK_NetBIOSName( TCPIP_NET_HANDLE netH ); Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3777 Parameters Parameters Description netH Interface handle to get name of. Returns if interface is enabled then it returns the NetBIOS name of that interface else return 0 Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); const char* biosName = TCPIP_STACK_NetBIOSName(netH); 5.8.17.7.2.3 TCPIP_STACK_NetBiosNameSet Function C bool TCPIP_STACK_NetBiosNameSet( TCPIP_NET_HANDLE netH, const char* biosName ); Preconditions None Parameters Parameters Description netH Interface handle to set name of. Returns if interface exists then it sets the NetBIOS name of that interface and returns true else return false Remarks See Important Note above! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetBiosNameSet(netH, myBiosName); 5.8.17.7.2.4 TCPIP_STACK_NetDefaultGet Function C TCPIP_NET_HANDLE TCPIP_STACK_NetDefaultGet(); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Returns The default net interface for multi-homed hosts Side Effects None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3778 Remarks Function to dynamically change the default interface will be added. 5.8.17.7.2.5 TCPIP_STACK_NetDefaultSet Function C bool TCPIP_STACK_NetDefaultSet( TCPIP_NET_HANDLE netH ); Preconditions None Parameters Parameters Description netH Interface handle. Returns true if success false if failed (the old interface does not change) Side Effects None Remarks sets the default interface 5.8.17.7.2.6 TCPIP_STACK_NetHandleGet Function C TCPIP_NET_HANDLE TCPIP_STACK_NetHandleGet( const char* interface ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description interface The names specified in tcpip_config.h::TCPIP_NETWORK_CONFIG. Returns Resolves an interface name to a handle. Side Effects None Remarks None Example TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet("PIC32INT"); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3779 5.8.17.7.2.7 TCPIP_STACK_NetIndexGet Function C int TCPIP_STACK_NetIndexGet( TCPIP_NET_HANDLE hNet ); Preconditions None Parameters Parameters Description hNet Interface handle. Returns Index of this entry in the stack network handles Side Effects None Remarks None 5.8.17.7.2.8 TCPIP_STACK_NetMask Function C uint32_t TCPIP_STACK_NetMask( TCPIP_NET_HANDLE netH ); Preconditions None Parameters Parameters Description netH Interface handle to get mask of. Returns if interface is enabled then it returns the IP address mask of that interface else return 0 Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); uint32_t subMask = TCPIP_STACK_NetMask(netH); 5.8.17.7.2.9 TCPIP_STACK_NetNameGet Function C const char* TCPIP_STACK_NetNameGet( TCPIP_NET_HANDLE netH ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3780 Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get the name of. Returns it returns the name associated to that interface handle returns 0 if no such name Side Effects None Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_IndexToNet(0); const char* netName = TCPIP_STACK_NetNameGet(netH); 5.8.17.7.2.10 TCPIP_STACK_NumberOfNetworksGet Function C int TCPIP_STACK_NumberOfNetworksGet(); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Returns Number of network interfaces Side Effects None Remarks None 5.8.17.7.3 Network Up/Down/Linked Functions 5.8.17.7.3.1 TCPIP_STACK_NetDown Function C bool TCPIP_STACK_NetDown( TCPIP_NET_HANDLE netH ); Description This function performs the de-initialization of a net interface Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3781 Parameters Parameters Description netH Interface handle. Returns true if success false if no such network Side Effects None Remarks None 5.8.17.7.3.2 TCPIP_STACK_NetIsLinked Function C bool TCPIP_STACK_NetIsLinked( TCPIP_NET_HANDLE hNet ); Preconditions None Parameters Parameters Description hNet Interface handle. Returns true if interface exists and the corresponding MAC is linked false otherwise Side Effects None Remarks None 5.8.17.7.3.3 TCPIP_STACK_NetIsUp Function C bool TCPIP_STACK_NetIsUp( TCPIP_NET_HANDLE hNet ); Preconditions None Parameters Parameters Description hNet Interface handle. Returns true if interface exists and is enabled false otherwise 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3782 Side Effects None Remarks None 5.8.17.7.3.4 TCPIP_STACK_NetUp Function C bool TCPIP_STACK_NetUp( TCPIP_NET_HANDLE netH, const TCPIP_NETWORK_CONFIG* pUsrConfig ); Description This function brings the desired interface up. Preconditions None Parameters Parameters Description netH Interface handle. pUsrConfig pointer to a TCPIP_NETWORK_CONFIG for the interface initialization Returns true if success false if no such network or an error occurred Side Effects None Remarks None 5.8.17.7.4 Network Address Status and Control Functions 5.8.17.7.4.1 TCPIP_STACK_ModuleGetConfig Function C size_t TCPIP_STACK_ModuleGetConfig( TCPIP_STACK_MODULE modId, void* configBuff, size_t buffSize, size_t* pNeededSize ); Description This function returns the current configuration data of the stack module specified by the corresponding module ID. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3783 Parameters Parameters Description modId the ID that identifies the requested module configBuff pointer to a buffer that will receive the configuration data If this pointer is 0, just the pNeededSize will be updated buffSize size of the provided buffer pNeededSize pointer to an address to store the number of bytes needed to store this module configuration data Can be NULL if not needed. Returns number of bytes copied to the user buffer: -1 if the module ID is invalid 0 if the configBuff is NULL or buffSize is less than required >0 if the call succeeded and the configuration was copied Remarks None Example uint8_t configBuffer[200]; size_t configSize; size_t copiedSize; copiedSize = TCPIP_STACK_ModuleGetConfig(TCPIP_MODULE_MAC_MRF24W, configBuffer, sizeof(configBuffer), &configSize); 5.8.17.7.4.2 TCPIP_STACK_NetAddress Function C uint32_t TCPIP_STACK_NetAddress( TCPIP_NET_HANDLE netH ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get address of. Returns if interface is enabled then it returns the IP address of that interface else return 0 Side Effects None Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); uint32_t ipAdd = TCPIP_STACK_NetAddress(netH); 5.8.17.7.4.3 TCPIP_STACK_NetAddressBcast Function C uint32_t TCPIP_STACK_NetAddressBcast( TCPIP_NET_HANDLE netH ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3784 Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get address of. Returns if interface is enabled then it returns the broadcast IP address mask of that interface else return 0 Side Effects None Remarks None 5.8.17.7.4.4 TCPIP_STACK_NetAddressDnsPrimary Function C uint32_t TCPIP_STACK_NetAddressDnsPrimary( TCPIP_NET_HANDLE netH ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get the DNS address of. Returns the primary DNS address if succes false if not such interface or interface is down Side Effects None Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); myIPAddress = TCPIP_STACK_NetAddressDnsPrimary(netH); 5.8.17.7.4.5 TCPIP_STACK_NetAddressDnsPrimarySet Function C bool TCPIP_STACK_NetAddressDnsPrimarySet( TCPIP_NET_HANDLE netH, IPV4_ADDR* ipAddress ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3785 Parameters Parameters Description netH Interface handle to set the DNS address of. ipAddress IP address to set Returns true if succes false if not such interface Side Effects None Remarks See Important Note above! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetAddressDnsPrimarySet(netH, &myIPAddress); 5.8.17.7.4.6 TCPIP_STACK_NetAddressDnsSecond Function C uint32_t TCPIP_STACK_NetAddressDnsSecond( TCPIP_NET_HANDLE netH ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get the DNS address of. Returns the secondary DNS address if succes false if not such interface or interface is down Side Effects None Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); myIPAddress = TCPIP_STACK_NetAddressDnsSecond(netH); 5.8.17.7.4.7 TCPIP_STACK_NetAddressDnsSecondSet Function C bool TCPIP_STACK_NetAddressDnsSecondSet( TCPIP_NET_HANDLE netH, IPV4_ADDR* ipAddress ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3786 Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to set the secondary DNS address of. ipAddress IP address to set Returns true if succes false if not such interface Side Effects None Remarks See Important Note above! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetAddressDnsSecondSet(netH, &myIPAddress); 5.8.17.7.4.8 TCPIP_STACK_NetAddressGateway Function C uint32_t TCPIP_STACK_NetAddressGateway( TCPIP_NET_HANDLE netH ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to get address of. Returns if interface is enabled then it returns the gateway address of that interface else return 0 Side Effects None Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); uint32_t ipAdd = TCPIP_STACK_NetAddressGateway(netH); 5.8.17.7.4.9 TCPIP_STACK_NetAddressGatewaySet Function C bool TCPIP_STACK_NetAddressGatewaySet( 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3787 TCPIP_NET_HANDLE netH, IPV4_ADDR* ipAddress ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to set the gateway address of. ipAddress IP address to set Returns true if succes false if not such interface Side Effects None Remarks See Important Note above! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetAddressGatewaySet(netH, &myIPAddress); 5.8.17.7.4.10 TCPIP_STACK_NetAddressMac Function C const uint8_t* TCPIP_STACK_NetAddressMac( TCPIP_NET_HANDLE netH ); Preconditions None Parameters Parameters Description netH Interface handle to get the address of. Returns if interface is enabled then it returns a constant pointer to the MAC address of that interface else return 0 Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); const TCPIP_MAC_ADDR* pAdd = TCPIP_STACK_NetAddressMac(netH); 5.8.17.7.4.11 TCPIP_STACK_NetAddressMacSet Function C bool TCPIP_STACK_NetAddressMacSet( TCPIP_NET_HANDLE netH, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3788 const TCPIP_MAC_ADDR* pAddr ); Preconditions None Parameters Parameters Description netH Interface handle to set the address of. Returns if interface is enabled then it returns a constant pointer to the MAC address of that interface else return 0 Remarks See Important Note above! Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetAddressMacSet(netH, &myMacAddress); 5.8.17.7.4.12 TCPIP_STACK_NetAddressSet Function C bool TCPIP_STACK_NetAddressSet( TCPIP_NET_HANDLE netH, IPV4_ADDR* ipAddress, IPV4_ADDR* mask, bool setDefault ); Preconditions TCPIP stack should have been initialized by TCPIP_STACK_Initialize() Parameters Parameters Description netH Interface handle to set address of. ipAddress IP address to set (could be NULL to set only the mask) mask corresponding network mask to set (could be NULL to set only the IP address) setDefault if true, the interface default address/mask is also set Returns true if succes false if not such interface Side Effects None Remarks See Important Note above! This function sets the associated network IP address and/or mask. If you're changing the network then it's preferred that you set both these values simultaneously to avoid having the stack running with a mismatch between its IP address and mask. Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_NetAddressSet(netH, &myIPAddress); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3789 5.8.17.7.4.13 TCPIP_STACK_NetIPv6AddressGet Function C IPV6_ADDR_HANDLE TCPIP_STACK_NetIPv6AddressGet( TCPIP_NET_HANDLE netH, IPV6_ADDR_TYPE addType, IPV6_ADDR_STRUCT* pAddStruct, IPV6_ADDR_HANDLE addHandle ); Description This function allows the listing of the IPv6 addresses associated with an interface. Preconditions None Parameters Parameters Description netH handle of the interface to retrieve the addresses for addType type of address to request: IPV6_ADDR_TYPE_UNICAST and IPV6_ADDR_TYPE_MULTICAST supported for now pAddStruct structure provided by the user that will be filled with corresponding IPV6_ADDR_STRUCT data addHandle an address handle that allows iteration across multiple IPv6 addresses. On the first call has to be 0; it will begin the listing of the IPv6 addresses On subsequent calls has to be a handle previously returned by a call to this function Returns - a non NULL IPV6_ADDR_HANDLE if an valid IPv6 address was found and the pAddStruct structure was filled with data • 0 if no other IPv6 exists or if the supplied IPV6_ADDR_HANDLE is invalid Remarks None Example IPV6_ADDR_STRUCT currAddr; IPV6_ADDR_HANDLE currHandle; TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet("PIC32INT"); char ipv6AddBuff[44]; currHandle = 0; do { currHandle = TCPIP_STACK_NetIPv6AddressGet(netH, IPV6_ADDR_TYPE_UNICAST, &currAddr, currHandle); if(currHandle) { // have a valid address; display it TCPIP_HELPER_IPv6AddressToString(&currAddr.address, ipv6AddBuff, sizeof(ipv6AddBuff)); } }while(currHandle != 0); 5.8.17.7.5 Network Structure Storage Functions 5.8.17.7.5.1 TCPIP_STACK_NetConfigGet Function C size_t TCPIP_STACK_NetConfigGet( TCPIP_NET_HANDLE netH, void* configStoreBuff, size_t configStoreSize, size_t* pNeededSize ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3790 Description This function dumps the current configuration data of the network interface specified by the corresponding network handle into the supplied buffer. Preconditions None Parameters Parameters Description netH the handle that identifies the requested interface configStoreBuff pointer to a buffer that will receive the current configuration data. All the data that's needed to restore a TCPIP_NETWORK_CONFIG structure is stored in this buffer. Can be NULL if only the storage size is needed. configStoreSize size of the supplied buffer pNeededSize pointer to store the size needed for storage; Can be NULL if not needed Returns -1 if the interface is invalid or the stack is not initialized 0 if no data is copied (no supplied buffer of buffer too small) >0 for success, indicating the amount of data copied. Remarks The function is a helper for retrieving the network configuration data. Its companion function, TCPIP_STACK_NetConfigSet, restores the TCPIP_NETWORK_CONFIG from the dump buffer. Currently the data is saved in plain binary format into the supplied buffer. However the application must not make use of this assumption as it may change in the future releases (some compression scheme may be implemented). Example uint8_t currConfig[100]; size_t neededSize, result; TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet("PIC32INT"); result = TCPIP_STACK_NetConfigGet(hNet, currConfig, sizeof(currConfig), &neededSize); if(result > 0) { // store the currConfig to some external storage } 5.8.17.7.5.2 TCPIP_STACK_NetConfigSet Function C TCPIP_NETWORK_CONFIG* TCPIP_STACK_NetConfigSet( void* configStoreBuff, void* netConfigBuff, size_t buffSize, size_t* pNeededSize ); Description This function restores data from a previously dump buffer and updates the supplied interface configuration. All the data is recovered and constructed into the netConfigBuff (supposing this buffer is large enough). If this operation succeeded, the netConfigBuff can be safely cast to a (TCPIP_NETWORK_CONFIG*). The structure of the netConfigBuff is as follows: • a TCPIP_NETWORK_CONFIG sturcture is created at the very beginning of the buffer • all the needed fields that are part of the TCPIP_NETWORK_CONFIG will be placed in the buffer itself. Preconditions None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3791 Parameters Parameters Description configStoreBuff pointer to a buffer that received configuration data from a TCPIP_STACK_NetConfigGet call. netConfigBuff pointer to a buffer that will receive the TCPIP_NETWORK_CONFIG data buffSize size of the supplied netConfigBuff buffer pNeededSize pointer to store the size needed for storage; Can be NULL if not needed Returns a valid TCPIP_NETWORK_CONFIG pointer (netConfigBuff) if the netConfigBuff is successfully updated 0 - if the netConfigBuff is not supplied or not big enough If supplied, the pNeededSize will be updated with the actual size that's needed for the netConfigBuff Remarks The function is a helper for being able to restore the configuration data. Its companion function, TCPIP_STACK_NetConfigGet, saves the TCPIP_NETWORK_CONFIG to a dump buffer. Example uint8_t currConfig[100]; uint8_t restoreBuff[100]; size_t neededSize, result; TCPIP_NET_HANDLE hNet = TCPIP_STACK_NetHandleGet("PIC32INT"); result = TCPIP_STACK_NetConfigGet(hNet, currConfig, sizeof(currConfig), &neededSize); if(result > 0) { // store the currConfig buffer to some external storage (neededSize bytes needed) // later on restore the configuration TCPIP_NETWORK_CONFIG* netConfig; // extract the network configuration from the previously saved buffer netConfig = TCPIP_STACK_NetConfigSet(currConfig, restoreBuff, sizeof(restoreBuff), neededSize); if(netConfig) { // use this netConfig to initialize a network interface TCPIP_STACK_NetUp(hNet, netConfig); } } 5.8.17.7.5.3 TCPIP_STACK_NetMACId Function C TCPIP_STACK_MODULE TCPIP_STACK_NetMACId( TCPIP_NET_HANDLE netH ); Description This function returns the module ID of the MAC that's attached to the specified network interface. Preconditions None Parameters Parameters Description netH handle of the interface to use Returns a TCPIP_STACK_MODULE ID that belongs to the MAC of that network interface. Remarks None Example TCPIP_NET_HANDLE netH = TCPIP_STACK_NetHandleGet("PIC32INT"); TCPIP_STACK_MODULE modId = TCPIP_STACK_NetMACId(netH); if(modId == TCPIP_MODULE_MAC_PIC32INT) { // an internal PIC32 MAC attached to this 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3792 interface } 5.8.17.7.6 Data Types and Constants 5.8.17.7.6.1 TCPIP_LOCAL_MASK_TYPE Enumeration C typedef enum { TCPIP_LOCAL_MASK_ZERO, TCPIP_LOCAL_MASK_ONE, TCPIP_LOCAL_MASK_NET, TCPIP_LOCAL_MASK_SET } TCPIP_LOCAL_MASK_TYPE; Description types of masks used in the detection of a local/nonlocal network Members Members Description TCPIP_LOCAL_MASK_ZERO use an all zero network mask TCPIP_LOCAL_MASK_ONE use an all ones network mask TCPIP_LOCAL_MASK_NET use the current network mask TCPIP_LOCAL_MASK_SET use the set value for the network mask there are operations available that set the local/nonlocal detection network mask 5.8.17.7.6.2 TCPIP_NET_HANDLE Type C typedef const void* TCPIP_NET_HANDLE; Description a network interface handle 5.8.17.8 Files Files Name Description tcpip_manager.h Description 5.8.17.8.1 tcpip_manager.h Microchip TCP/IP Stack Definitions Enumerations Name Description TCPIP_LOCAL_MASK_TYPE types of masks used in the detection of a local/nonlocal network 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Manager TCP/IP Stack Library 5-3793 Functions Name Description TCPIP_STACK_Deinitialize This function performs the de-initialization of the TCPIP stack TCPIP_STACK_IndexToNet TCPIP_STACK_Initialize The function initializes the stack. If an error occurs, the SYS_ERROR() is called and the function de-initialize itself and will return false. TCPIP_STACK_ModuleGetConfig This function returns the current configuration data of the stack module specified by the corresponding module ID. TCPIP_STACK_NetAddress TCPIP_STACK_NetAddressBcast TCPIP_STACK_NetAddressDnsPrimary TCPIP_STACK_NetAddressDnsPrimarySet TCPIP_STACK_NetAddressDnsSecond TCPIP_STACK_NetAddressDnsSecondSet TCPIP_STACK_NetAddressGateway TCPIP_STACK_NetAddressGatewaySet TCPIP_STACK_NetAddressMac TCPIP_STACK_NetAddressMacSet TCPIP_STACK_NetAddressSet TCPIP_STACK_NetBIOSName TCPIP_STACK_NetBiosNameSet TCPIP_STACK_NetConfigGet This function dumps the current configuration data of the network interface specified by the corresponding network handle into the supplied buffer. 5.8.18 NBNS TCP/IP Stack Library 5.8.18.1 Introduction NetBIOS (NBNS) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the NBNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The NetBIOS Name Service protocol associates host names with IP addresses, similarly to DNS, but on the same IP subnet. Practically, this allows the assignment of human-name hostnames to access boards on the same subnet. For example. in the "TCP/IP Demo App" demonstration project, the demo board is programmed with the human name 'mchpboard' so it can be accessed directly instead of with its IP address. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NBNS TCP/IP Stack Library 5-3794 5.8.18.2 Release Notes MPLAB Harmony Version: v0.70b NBNS TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.18.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.18.4 Using the Library This topic describes the basic architecture of the NBNS TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: nbns.h The interface to the NBNS TCPIP Stack library is defined in the "nbns.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the NBNS TCP/IP Stack library should include "tcpip.h". Library File: The NBNS TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.18.4.1 Abstraction Model This library provides the API of the NBNS TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NBNS TCP/IP Stack Library 5-3795 Description NBNS Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.18.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the NBNS module. Library Interface Section Description Data Types and Constants This section provides various definitions describing This API 5.8.18.5 Configuring the Library Macros Name Description NBNS_PORT NetBIOS Name Service port Description The configuration of the NBNS TCP/IP Stack is based on the file tcpip_config.h This header file contains the configuration selection for the NBNS TCP/IP Stack. Based on the selections made, the NBNS TCP/IP Stack will support or not support selected features. These configuration settings will apply to all instances of the NBNS TCP/IP Stack. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.18.5.1 NBNS_PORT Macro C #define NBNS_PORT (137u) Description NetBIOS Name Service port 5.8.18.6 Building the Library This section list the files that are available in the \src of the NBNS driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NBNS TCP/IP Stack Library 5-3796 5.8.18.7 Library Interface Data Types and Constants Name Description NBNS_MODULE_CONFIG Provides a placeholder for NBNS configuration upgrades. Description 5.8.18.7.1 Data Types and Constants 5.8.18.7.1.1 NBNS_MODULE_CONFIG Structure C typedef struct { } NBNS_MODULE_CONFIG; Description NBNS_MODULE_CONFIG Structure Typedef Provides a placeholder for NBNS configuration upgrades. Remarks None 5.8.18.8 Files Files Name Description nbns.h nbns_config.h NBNS configuration file Description 5.8.18.8.1 nbns.h NetBIOS Name Service (NBNS) Server public API -Responds to NBNS name requests to allow human name assignment to the board Structures Name Description NBNS_MODULE_CONFIG Provides a placeholder for NBNS configuration upgrades. 5.8.18.8.2 nbns_config.h NetBIOS Name Service (NBNS) Configuration file 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NBNS TCP/IP Stack Library 5-3797 This file contains the NBNS module configuration options Macros Name Description NBNS_PORT NetBIOS Name Service port 5.8.19 NDP TCP/IP Stack Library 5.8.19.1 Introduction NDP TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the NDP ( Neighbor Discovery Protocol) TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description This document provides NDP( Neighbor Discovery Protocol) for IP version 6.IPv6 nodes on same link use neighbor discovery to discover each other's presence. RFC - 4861. It is responsible for 1. Address Auto configuration of nodes 2. Discovery of other nodes in the link( It can be a Router Discovery or Neighbor Discovery) 3. Determining the link layer address of other nodes 4. Duplicate address detection ( DAD) 5. Finding available routers and Domain Name System ( DNS) servers 6. Address Prefix discovery 7. Parameter Discovery (Such as Link MTU or Hop limit ) Comparing with IPv4 • NDP is a substitute of ARP (Address Resolution protocol ). This new mechanism uses a mix of ICMPv6 and multicast addresses to discover the IPv6 node on same link. • NDP includes Neighbor Unreachability Detection (NUD) , thus improving the robustness of packet delivery. • Unlike IPv4 broadcast addresses, IPv6 address resolution multicasts are spread over 4 billion (2^32) multicast addresses, greatly reducing address resolution-related interrupts on nodes other than the target. Moreover, non-IPv6 machines should not be interrupted at all. • Neighbor Discovery defines five different ICMPv6 packet types. Five different ICMPv6 Packet types - 1. Router Solicitation - Hosts inquire with Router Solicitation message to locate routers on the attached link. 2. Router Advertisement - Router advertise their presence periodically to all the nodes or in response to the Router Solicitation 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3798 message. 3. Neighbor Solicitation - Neighbor solicitations are used by nodes to determine the Link Layer address of a neighbor, or to verify that a neighbor is still reachable via a cached Link Layer address. 4. Neighbor Advertisement - Neighbor advertisements are used by nodes to respond to a Neighbor Solicitation message 5. Redirect - Routers may inform hosts of a better first hop router for a destination. 5.8.19.2 Release Notes MPLAB Harmony Version: v0.70b NDP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.19.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.19.4 Using the Library This topic describes the basic architecture of the NDP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: ndp.h The interface to the NDP TCP/IP Stack Library is defined in the "ndp.h" header file. Any C language source (.c) file that uses the NDP TCP/IP library should include "IPv6.h , icmpv6.h and ndp.h". Library File: The NDP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack Library interacts with the framework. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3799 5.8.19.4.1 Abstraction Model This library provides the API of the NDP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description NDP with IPv6 Software Abstraction Block Diagram This module provides software abstraction of the IPv6 module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. IPv6 Block Diagram -------------------------------------- Link Layer Neighbor Discovery 1) Using the address FEC0::1:0:0:1 :A, node A wants to deliver packets to destination node B using the IPv6 address FEC0::1 :0:0:1 :B on the same local link. However, node A does not know node B's link-layer address. Node A sends an ICMPv6 Type 135 message (neighbor solicitation) on the local link using its site-local address FEC0::1:0:0:1:A as the IPv6 source address, the solicited-node multicast address FF02::1 :FF01:B corresponding to the target address FEC0::1 :0:0:1 :B as the destination IPv6 address, and the source link-layer address 00:04:a3:13:12:b4 of the sender, node A, as data of the ICMPv6 message. The source link-layer address of this frame is the link-layer address 00:04:a3:13:12:b4 of node A. The destination link-layer address 33:33:FF:01 :00:0B of this frame uses multicast mapping of the destination IPv6 address FF02::1 :FF01 :B. 2) Node B, which is listening to the local link for multicast addresses, intercepts the neighbor solicitation message because the destination IPv6 address FF02::1:FF01:B represents the solicited-node multicast address corresponding to its IPv6 address FEC0::1:0:0:1:B. 3) Node B replies by sending a neighbor advertisement message using its site-local address FEC0::1 :0:0:1 :B as the IPv6 source address and the site-local address FEC0::1 :0:0:1 :A as the destination IPv6 address. It also includes its link-layer address 00:04:a3:13:12:b5 in the ICMPv6 message. After receiving neighbor solicitation and neighbor advertisement messages, node A and node B know each other's link-layer addresses. Learned link-layer addresses are kept in a neighbor discovery table (neighbor cache). Therefore, the nodes can communicate on the local link. The neighbor solicitation message is also used by nodes to verify the reachability of neighbor nodes in the neighbor discovery table (neighbor cache). However, the unicast addresses of the neighbor nodes are used as destination IPv6 addresses in ICMPv6 messages instead of solicited-node multicast addresses in this situation. It is possible for a node that changes its link-layer address to inform all other neighbor nodes on the local link by sending a neighbor advertisement message using the all-nodes multicast address FF02::1 . The neighbor discovery table of the nodes on the local link is updated with the new linklayer address. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3800 5.8.19.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the IPv6 , ICMPv6 and NDP module. Library Interface Section Description Reachability Functions Reachability routine functionality 5.8.19.5 Configuring the Library Macros Name Description DELAY_FIRST_PROBE_TIME 5 s IPV6_MTU_INCREASE_TIMEOUT 600 seconds MAX_ANYCAST_DELAY_TIME 1 s MAX_MULTICAST_SOLICIT 3 transmissions MAX_NEIGHBOR_ADVERTISEMENT 3 transmissions MAX_RTR_SOLICITATION_DELAY 1 s MAX_RTR_SOLICITATIONS 3 transmissions MAX_UNICAST_SOLICIT 3 transmissions NDP_TASK_TIMER_RATE default 32 ms NDP_VALID_LIFETIME_TWO_HOURS Sets the lifetime to 2 hours REACHABLE_TIME 30 s RETRANS_TIMER 1 s RTR_SOLICITATION_INTERVAL 4 s Description The configuration of the TCPIP Stack IPv6 is based on the file ndp_config.h This header file contains the configuration selection for the TCPIP Stack IP. Based on the selections made, the TCPIP Stack IP will support or not support selected features. These configuration settings will apply to all instances of the TCPIP Stack IP. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3801 successful build. 5.8.19.5.1 DELAY_FIRST_PROBE_TIME Macro C #define DELAY_FIRST_PROBE_TIME 5u // 5 s Description 5 s 5.8.19.5.2 IPV6_MTU_INCREASE_TIMEOUT Macro C #define IPV6_MTU_INCREASE_TIMEOUT 600ul // 600 seconds Description 600 seconds 5.8.19.5.3 MAX_ANYCAST_DELAY_TIME Macro C #define MAX_ANYCAST_DELAY_TIME 1u // 1 s Description 1 s 5.8.19.5.4 MAX_MULTICAST_SOLICIT Macro C #define MAX_MULTICAST_SOLICIT 3u // 3 transmissions Description 3 transmissions 5.8.19.5.5 MAX_NEIGHBOR_ADVERTISEMENT Macro C #define MAX_NEIGHBOR_ADVERTISEMENT 3u // 3 transmissions Description 3 transmissions 5.8.19.5.6 MAX_RTR_SOLICITATION_DELAY Macro C #define MAX_RTR_SOLICITATION_DELAY 1u // 1 s Description 1 s 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3802 5.8.19.5.7 MAX_RTR_SOLICITATIONS Macro C #define MAX_RTR_SOLICITATIONS 3u // 3 transmissions Description 3 transmissions 5.8.19.5.8 MAX_UNICAST_SOLICIT Macro C #define MAX_UNICAST_SOLICIT 3u // 3 transmissions Description 3 transmissions 5.8.19.5.9 NDP_TASK_TIMER_RATE Macro C #define NDP_TASK_TIMER_RATE (32) // default 32 ms Description default 32 ms 5.8.19.5.10 NDP_VALID_LIFETIME_TWO_HOURS Macro C #define NDP_VALID_LIFETIME_TWO_HOURS (60 * 60 * 2) Description Sets the lifetime to 2 hours 5.8.19.5.11 REACHABLE_TIME Macro C #define REACHABLE_TIME 30u // 30 s Description 30 s 5.8.19.5.12 RETRANS_TIMER Macro C #define RETRANS_TIMER 1u // 1 s Description 1 s 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3803 5.8.19.5.13 RTR_SOLICITATION_INTERVAL Macro C #define RTR_SOLICITATION_INTERVAL 4u // 4 s Description 4 s 5.8.19.6 Building the Library This section list the files that are available in the \src of the IPv6 and ICMPv6 driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • ipv6.c • icmpv6.c • ndp.c TCPIP_STACK_USE_IPV6 is enabled from tcpip_config.h . 5.8.19.7 Library Interface Reachability Functions Name Description TCPIP_NDP_NborReachConfirm Confirms that a neighbor is reachable. Description This section describes the Application Programming Interface (API) functions of the NDP TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.19.7.1 Reachability Functions 5.8.19.7.1.1 TCPIP_NDP_NborReachConfirm Function C void TCPIP_NDP_NborReachConfirm( TCPIP_NET_HANDLE netH, IPV6_ADDR * address ); Description This function is used by upper-layer protocols to indicate that round-trip communications were confirmed with a neighboring node. Preconditions None Parameters Parameters Description pNetIf The interface the neighbor is on. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3804 address The address of the neighbor. Returns None. Remarks None 5.8.19.8 Files Files Name Description ndp.h IPv6 Internet Communication Message Protocol ndp_config.h NDP configuration file Description 5.8.19.8.1 ndp.h Neighbor Discovery Protocol (NDP) in IPv6 is the substitute of as ARP( Which is used in IPv4 for address resolve).NDP is used discover link local addresses of the IPv6 nodes present in the local link using a mix of ICMPv6 messages and multicast addresses, Stateless auto-configuration and router redirection. Functions Name Description TCPIP_NDP_NborReachConfirm Confirms that a neighbor is reachable. File Name ndp.h Company Microchip Technology Incorporated 5.8.19.8.2 ndp_config.h Neighbor Discovery Protocol (NDP) Configuration file This file contains the NDP module configuration options Macros Name Description DELAY_FIRST_PROBE_TIME 5 s IPV6_MTU_INCREASE_TIMEOUT 600 seconds MAX_ANYCAST_DELAY_TIME 1 s MAX_MULTICAST_SOLICIT 3 transmissions MAX_NEIGHBOR_ADVERTISEMENT 3 transmissions MAX_RTR_SOLICITATION_DELAY 1 s MAX_RTR_SOLICITATIONS 3 transmissions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help NDP TCP/IP Stack Library 5-3805 MAX_UNICAST_SOLICIT 3 transmissions NDP_TASK_TIMER_RATE default 32 ms NDP_VALID_LIFETIME_TWO_HOURS Sets the lifetime to 2 hours REACHABLE_TIME 30 s RETRANS_TIMER 1 s RTR_SOLICITATION_INTERVAL 4 s 5.8.20 Reboot TCP/IP Stack Library 5.8.20.1 Introduction Reboot TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the Reboot TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Reboot module will allow a user to remotely reboot the PIC microcontroller that is running the TCP/IP stack. This feature is primarily used for bootloader applications, which must reset the microcontroller to enter the bootloader code section. This module will execute a task that listens on a specified UDP port for a packet, and then reboots if it receives one. 5.8.20.2 Release Notes Harmony Version: v0.70b Reboot TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.20.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Reboot TCP/IP Stack Library 5-3806 ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.20.4 Using the Library This topic describes the basic architecture of the Reboot TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: tcpip_reboot_config.h The interface to the Reboot TCP/IP Stack library is defined in the "tcpip_reboot_config.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the Reboot TCP/IP Stack library should include "tcpip.h". Library File: The Reboot TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.20.4.1 Abstraction Model This library provides the API of the Reboot TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Reboot Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.20.5 Configuring the Library Macros Name Description REBOOT_PORT UDP TFTP port REBOOT_SAME_SUBNET_ONLY For improved security, you might want to limit reboot capabilities to only users on the same IP subnet. Define REBOOT_SAME_SUBNET_ONLY to enable this access restriction. Description The configuration of the Reboot TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the Reboot TCP/IP Stack Library. Based on the selections made, the Reboot TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the Reboot TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Reboot TCP/IP Stack Library 5-3807 successful build. Refer to the Applications Overview section for more details. 5.8.20.5.1 REBOOT_PORT Macro C #define REBOOT_PORT 69 Description UDP TFTP port 5.8.20.5.2 REBOOT_SAME_SUBNET_ONLY Macro C #define REBOOT_SAME_SUBNET_ONLY Description For improved security, you might want to limit reboot capabilities to only users on the same IP subnet. Define REBOOT_SAME_SUBNET_ONLY to enable this access restriction. 5.8.20.6 Building the Library This section list the files that are available in the \src of the Reboot driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.20.7 Library Interface This section describes the Application Programming Interface (API) functions of the Reboot TCP/IP Stack, if applicable. 5.8.20.8 Files Files Name Description tcpip_reboot_config.h Configuration file Description 5.8.20.8.1 tcpip_reboot_config.h Reboot Configuration file This file contains the Reboot module configuration options Macros Name Description REBOOT_PORT UDP TFTP port 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Reboot TCP/IP Stack Library 5-3808 REBOOT_SAME_SUBNET_ONLY For improved security, you might want to limit reboot capabilities to only users on the same IP subnet. Define REBOOT_SAME_SUBNET_ONLY to enable this access restriction. 5.8.21 SMTP TCP/IP Stack Library 5.8.21.1 Introduction Simple Mail Transfer Protocol (SMTP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the SMTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The SMTP client module in the TCP/IP Stack lets applications send e-mails to any recipient worldwide. These message could include status information or important alerts. Using the e-mail to SMS gateways provided by most cell phone carriers, these messages can also be delivered directly to cell phone handsets. Using the SMTP client requires access to a local mail server (such as mail.yourdomain.com) for reliable operation. Your MPLAB Harmony or network administrator can provide the correct address, but end-user applications will need an interface to provide this data. 5.8.21.2 Release Notes MPLAB Harmony Version: v0.70b SMTP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.21.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3809 FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.21.4 Using the Library This topic describes the basic architecture of the SMTP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: smtp.h The interface to the SMTP TCP/IP Stack library is defined in the "smtp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the SMTP TCP/IP Stack library should include "tcpip.h". Library File: The SMTP TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.21.4.1 Abstraction Model This library provides the API of the SMTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description SMTP Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.21.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SMTP module. Library Interface Section Description Functions Routines to configure this module Data Types and Constants This section provides various definitions describing this API 5.8.21.4.3 SMTP Client Examples Module SMTP Client 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3810 Description The following two examples demonstrate the use of the SMTP client in different scenarios. The first, and simpler example, sends a short message whose contents are all located in RAM at once. The second example is more involved and demonstrates generating a message on the fly in the case where the entire message cannot fit into RAM at once. In this case, the message 5.8.21.4.3.1 SMTP Client Short Message Example The SMTP client API is simplified when messages can be buffered entirely in RAM. The SMTPDemo ( see page 99) example provided in MainDemo.c sends a brief e-mail message indicating the current status of the board's buttons. This document will walk through that example. Make sure STACK_USE_SMTP_CLIENT is uncommented in TCPIPConfig.h before continuing. The following diagram provides an overview of the process: First, call SMTPBeginUsage ( see page 304) to verify that the SMTP client is available and to begin a new message. If FALSE is returned, the SMTP client is busy and the application must return to the main loop to allow StackTask to execute again. Next, set the local relay server to use as SMTPClient.Server. If the local relay server requires a user name and password, set SMTPClient.Username and SMTPClient.Password to the appropriate credentials. If server parameters are not set, the stack will attempt to deliver the message directly to its destination host. This will likely fail due to spam prevention measures put in place by most ISPs and network administrators. Continue on to set the header strings as necessary for the message. This includes the subject line, from address, and any recipients you need to add. Finally, set SMTPClient.Body to the message to be sent. At this point, verify that SMTPClient.ROMPointers is correctly configured for any strings that are stored in program memory. Once the message is ready to send, call SMTPSendMail ( see page 310) to instruct the SMTP client to begin transmission. The application must now call SMTPIsBusy ( see page 306) until it returns FALSE. Each time TRUE is returned, return to the main loop and wait for StackTask to execute again. This allows the SMTP server to continue its work in a cooperative multitasking manner. Once FALSE is returned, call SMTPEndUsage ( see page 305) to release the SMTP client. Check the return value of this function to determine if the message was successfully sent. The example in MainDemo.c needs minor modifications to use your e-mail address. The Server and To fields must be set in SMTPDemo ( see page 99) in order for the message to be properly delivered. Once this is done, holding down BUTTON2 and BUTTON3 simultaneously (the left-most two buttons) will begin sending the message. LED1 will light as the message is being 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3811 processed, and will extinguish when the SMTP state machine completes. If the transmission was successful LED2 will light, otherwise it will remain dark. 5.8.21.4.3.2 SMTP Client Long Message Example The SMTP client API is capable of sending messages that do not fit entirely in RAM. To do so, the application must manage its output state and only write as many bytes as are available in the buffer at a time. The second SMTPDemo ( see page 99) example provided in MainDemo.c sends a message that is a dump of all contents of the PIC's RAM. This example is currently commented out. Comment out the previous Short Message Example and uncomment the Long Message Example. This document will walk through sending a longer message. Make sure STACK_USE_SMTP_CLIENT is uncommented in TCPIPConfig.h before continuing. Sending longer messages is divided into three stages. The first stage configures the SMTP client to send the message. The second stage sends the message in small chunks as buffer space is available. The final stage finishes the transmission and determines whether or not the message was successful. The following diagram illustrates the first stage: The first stage is largely similar to the first few steps in sending a short message. First, call SMTPBeginUsage ( see page 304) to verify that the SMTP client is available and to begin a new message. If FALSE is returned, the SMTP client is busy and the application must return to the main loop to allow StackTask to execute again. Next, set the local relay server to use as SMTPClient.Server. If the local relay server requires a user name and password, set SMTPClient.Username and SMTPClient.Password to the appropriate credentials. If server parameters are not set, the stack will attempt to deliver the message directly to its destination host. This will likely fail due to spam prevention measures put in place by most ISPs and network administrators. Continue on to set the header strings as necessary for the message. This includes the subject line, from address, and any recipients you need to add. The next portion of the process differs. Ensure that SMTPClient.Body remains set to its default (NULL). At this point, call SMTPSendMail ( see page 310) to open a connection to the remote server and transmit the headers. The application is now ready to proceed to the second stage and send the message body. The following diagram provides an overview of stage two and three: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3812 Upon entering stage two, the application should call SMTPIsBusy ( see page 306) to verify that the connection to the remote server is active and has not been lost. If the call succeeds, call SMTPIsPutReady ( see page 306) to determine how many bytes are available in the TX buffer. If no bytes are available, return to the main loop so that StackTask can transmit the data to the remote node and free up the buffer. If space is available, any combination of the SMTPPut ( see page 307), SMTPPutArray ( see page 307), SMTPPutROMArray ( see page 308), SMTPPutString ( see page 309), and SMTPPutROMString ( see page 309) functions may be called to transmit the message. These functions return the number of bytes successfully written. Use this value, along with the value originally returned from SMTPIsPutReady ( see page 306) to track how much free space remains in the TX buffer. Once the buffer is depleted, call SMTPFlush ( see page 305) to force the data written to be sent. The SMTP client module can accept ( see page 170) as much data as the TCP TX FIFO can hold. This is determined by the socket initializer for TCP_PURPOSE_DEFAULT type sockets in TCPIPConfig.h, which defaults to 200 bytes. If the TX buffer is exhausted before the message is complete, return to the main loop so that StackTask may transmit the data to the remote node and free up the buffer. Upon return, go to the beginning of the second stage to transmit the next portion of the message. Once the message is complete, the application will move to the third stage. Call SMTPPutDone ( see page 308) to inform the SMTP client that no more data remains. Then call SMTPIsBusy ( see page 306) repeatedly. Each time TRUE is returned, return to the main loop and wait for StackTask to execute again. Once FALSE is returned, the message transmission has completed and the application must call SMTPEndUsage ( see page 305) to release the SMTP client. Check the return value of this function to determine if the message was successfully sent. The example in MainDemo.c needs minor modifications to use your e-mail address. Set the Server and To fields in SMTPDemo ( see page 99), and ensure that these fields are being properly assigned to SMTPClient ( see page 305) struct. The demo works exactly the same way as the previous one, with BUTTON2 and BUTTON3 held down simultaneously (the left-most two buttons) kicking off the state machine. LED1 will light as the message is being processed, and will extinguish when the SMTP state machine completes. If the transmission was successful LED2 will light, otherwise it will remain dark. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3813 5.8.21.5 Configuring the Library Macros Name Description MAX_SMTP_CONNECTIONS Maximum number of SMTP connections allowed SMTP_PORT Default port to use when unspecified SMTP_SERVER_REPLY_TIMEOUT How long to wait before assuming the connection has been dropped (default 8 seconds) Description The configuration of the SMPT TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the SMTP TCP/IP Stack Library. Based on the selections made, the SMTP TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the SMTP TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.21.5.1 MAX_SMTP_CONNECTIONS Macro C #define MAX_SMTP_CONNECTIONS (1) Description Maximum number of SMTP connections allowed 5.8.21.5.2 SMTP_PORT Macro C #define SMTP_PORT 25 Description Default port to use when unspecified 5.8.21.5.3 SMTP_SERVER_REPLY_TIMEOUT Macro C #define SMTP_SERVER_REPLY_TIMEOUT (8ul) Description How long to wait before assuming the connection has been dropped (default 8 seconds) 5.8.21.6 Building the Library This section list the files that are available in the \src of the SMTP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3814 5.8.21.7 Library Interface Functions Name Description TCPIP_SMTP_ArrayPut Writes a series of bytes to the SMTP client. TCPIP_SMTP_Flush Flushes the SMTP socket and forces all data to be sent. TCPIP_SMTP_IsBusy Determines if the SMTP client is busy. TCPIP_SMTP_IsPutReady Determines how much data can be written to the SMTP client. TCPIP_SMTP_MailSend Initializes the message sending process. TCPIP_SMTP_Put Writes a single byte to the SMTP client. TCPIP_SMTP_PutIsDone Indicates that the on-the-fly message is complete. TCPIP_SMTP_StringPut Writes a string to the SMTP client. TCPIP_SMTP_UsageBegin Requests control of the SMTP client module. TCPIP_SMTP_UsageEnd Releases control of the SMTP client module. Data Types and Functions Name Description SMTP_CONNECT_ERROR Connection to SMTP server failed SMTP_RESOLVE_ERROR DNS lookup for SMTP server failed SMTP_SUCCESS Message was successfully sent SMTP_CLIENT_MODULE_CONFIG This is type SMTP_CLIENT_MODULE_CONFIG. SMTP_POINTERS Configures the SMTP client to send a message Description This section describes the Application Programming Interface (API) functions of the SMTP TCP/IP Stack. Refer to each section for a detailed description. 5.8.21.7.1 Functions 5.8.21.7.1.1 TCPIP_SMTP_ArrayPut Function C uint16_t TCPIP_SMTP_ArrayPut( uint8_t* Data, uint16_t Len ); Description Writes a series of bytes to the SMTP client. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Parameters Parameters Description Data The data to be written Len How many bytes should be written 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3815 Returns The number of bytes written. If less than Len, then the TX FIFO became full before all bytes could be written. Remarks This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) 5.8.21.7.1.2 TCPIP_SMTP_Flush Function C void TCPIP_SMTP_Flush(); Description Flushes the SMTP socket and forces all data to be sent. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Returns None Remarks This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) 5.8.21.7.1.3 TCPIP_SMTP_IsBusy Function C bool TCPIP_SMTP_IsBusy(); Description Call this function to determine if the SMTP client is busy performing background tasks. This function should be called after any call to TCPIP_SMTP_MailSend, TCPIP_SMTP_PutIsDone to determine if the stack has finished performing its internal tasks. It should also be called prior to any call to TCPIP_SMTP_IsPutReady to verify that the SMTP client has not prematurely disconnected. When this function returns false, the next call should be to TCPIP_SMTP_UsageEnd to release the module and obtain the status code for the operation. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Return Values Return Values Description true The SMTP Client is busy with internal tasks or sending an on-the-fly message. false The SMTP Client is terminated and is ready to be released. 5.8.21.7.1.4 TCPIP_SMTP_IsPutReady Function C uint16_t TCPIP_SMTP_IsPutReady(); Description Use this function to determine how much data can be written to the SMTP client when generating an on-the-fly message. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3816 Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call, and an on-the-fly message is being generated. This requires that TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL. Returns The number of free bytes the SMTP TX FIFO. Remarks This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) 5.8.21.7.1.5 TCPIP_SMTP_MailSend Function C void TCPIP_SMTP_MailSend( SMTP_POINTERS* smtpClientMessage ); Description This function starts the state machine that performs the actual transmission of the message. Call this function after all the fields in SMTPClient have been set. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Parameters Parameters Description smtpClientMessage message to send Returns None 5.8.21.7.1.6 TCPIP_SMTP_Put Function C bool TCPIP_SMTP_Put( char c ); Description Writes a single byte to the SMTP client. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Parameters Parameters Description c The byte to be written Return Values Return Values Description true The byte was successfully written 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3817 false The byte was not written, most likely because the buffer was full Remarks This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) 5.8.21.7.1.7 TCPIP_SMTP_PutIsDone Function C void TCPIP_SMTP_PutIsDone(); Description Indicates that the on-the-fly message is complete. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call, and the SMTP client is generated an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) Returns None 5.8.21.7.1.8 TCPIP_SMTP_StringPut Function C uint16_t TCPIP_SMTP_StringPut( char* Data ); Description Writes a string to the SMTP client. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Parameters Parameters Description Data The data to be written Returns The number of bytes written. If less than the length of Data, then the TX FIFO became full before all bytes could be written. Remarks This function should only be called externally when the SMTP client is generating an on-the-fly message. (That is, TCPIP_SMTP_MailSend was called with SMTPClient.Body set to NULL.) 5.8.21.7.1.9 TCPIP_SMTP_UsageBegin Function C bool TCPIP_SMTP_UsageBegin(); Description Call this function before calling any other SMTP Client APIs. This function obtains a lock on the SMTP Client, which can only be used by one stack application at a time. Once the application is finished with the SMTP client, it must call 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3818 TCPIP_SMTP_UsageEnd to release control of the module to any other waiting applications. This function initializes all the SMTP state machines and variables back to their default state. Preconditions None Return Values Return Values Description true The application has successfully obtained control of the module false The SMTP module is in use by another application. Call TCPIP_SMTP_UsageBegin again later, after returning to the main program loop 5.8.21.7.1.10 TCPIP_SMTP_UsageEnd Function C uint16_t TCPIP_SMTP_UsageEnd(); Description Call this function to release control of the SMTP client module once an application is finished using it. This function releases the lock obtained by TCPIP_SMTP_UsageBegin, and frees the SMTP client to be used by another application. Preconditions TCPIP_SMTP_UsageBegin returned true on a previous call. Return Values Return Values Description SMTP_SUCCESS A message was successfully sent SMTP_RESOLVE_ERROR The SMTP server could not be resolved SMTP_CONNECT_ERROR The connection to the SMTP server failed or was prematurely terminated 1-199 and 300-399 The last SMTP server response code 5.8.21.7.2 Data Types and Functions 5.8.21.7.2.1 SMTP_CONNECT_ERROR Macro C #define SMTP_CONNECT_ERROR (0x8001u) // Connection to SMTP server failed Description Connection to SMTP server failed 5.8.21.7.2.2 SMTP_RESOLVE_ERROR Macro C #define SMTP_RESOLVE_ERROR (0x8000u) // DNS lookup for SMTP server failed Description DNS lookup for SMTP server failed 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3819 5.8.21.7.2.3 SMTP_SUCCESS Macro C #define SMTP_SUCCESS (0x0000u) // Message was successfully sent Description Message was successfully sent 5.8.21.7.2.4 SMTP_CLIENT_MODULE_CONFIG Structure C typedef struct { } SMTP_CLIENT_MODULE_CONFIG; Description This is type SMTP_CLIENT_MODULE_CONFIG. 5.8.21.7.2.5 SMTP_POINTERS Structure C typedef struct { char* Server; char* Username; char* Password; char* To; char* CC; char* BCC; char* From; char* Subject; char* OtherHeaders; char* Body; bool UseSSL; uint16_t ServerPort; } SMTP_POINTERS; Description This structure of pointers configures the SMTP Client to send an e-mail message. Parameters Parameters Description Server the SMTP server to relay the message through Username the user name to use when logging into the SMTP server, if any is required Password the password to supply when logging in, if any is required To the destination address for this message. May be a comma-separated list of addresss, and/or formatted. CC The CC addresses for this message, if any. May be a comma-separated list of addresss, and/or formatted. BCC The BCC addresses for this message, if any. May be a comma-separated list of addresss, and/or formatted. From The From address for this message. May be formatted. Subject The Subject header for this message. OtherHeaders Any additional headers for this message. Each additional header, including the last one, must be terminated with a CRLF pair. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3820 Body When sending a message from memory, the location of the body of this message in memory. Leave as NULL to build a message on-the-fly. UseSSL When TCPIP_STACK_USE_SSL_CLIENT is enabled, this flag causes the SMTP client to make an SSL connection to the server. ServerPort (uint16_t value) Indicates the port on which to connect to the remote SMTP server. Remarks When formatting an e-mail address, the SMTP standard format for associating a printable name may be used. This format places the printable name in quotation marks, with the address following in pointed brackets, such as "John Smith" 5.8.21.8 Files Files Name Description smtp.h Module for Microchip TCP/IP Stack smtp_config.h SMTP configuration file Description 5.8.21.8.1 smtp.h Simple Mail Transfer Protocol (SMTP) Client Functions Name Description TCPIP_SMTP_ArrayPut Writes a series of bytes to the SMTP client. TCPIP_SMTP_Flush Flushes the SMTP socket and forces all data to be sent. TCPIP_SMTP_IsBusy Determines if the SMTP client is busy. TCPIP_SMTP_IsPutReady Determines how much data can be written to the SMTP client. TCPIP_SMTP_MailSend Initializes the message sending process. TCPIP_SMTP_Put Writes a single byte to the SMTP client. TCPIP_SMTP_PutIsDone Indicates that the on-the-fly message is complete. TCPIP_SMTP_StringPut Writes a string to the SMTP client. TCPIP_SMTP_UsageBegin Requests control of the SMTP client module. TCPIP_SMTP_UsageEnd Releases control of the SMTP client module. Macros Name Description SMTP_CONNECT_ERROR Connection to SMTP server failed SMTP_RESOLVE_ERROR DNS lookup for SMTP server failed SMTP_SUCCESS Message was successfully sent Structures Name Description SMTP_CLIENT_MODULE_CONFIG This is type SMTP_CLIENT_MODULE_CONFIG. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SMTP TCP/IP Stack Library 5-3821 SMTP_POINTERS Configures the SMTP client to send a message 5.8.21.8.2 smtp_config.h Simple Mail Transfer Protocol (SMTP) Configuration file This file contains the SMTP module configuration options Macros Name Description MAX_SMTP_CONNECTIONS Maximum number of SMTP connections allowed SMTP_PORT Default port to use when unspecified SMTP_SERVER_REPLY_TIMEOUT How long to wait before assuming the connection has been dropped (default 8 seconds) 5.8.22 SNMP TCP/IP Stack Library 5.8.22.1 Introduction Simple Network Management Protocol (SNMP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the SNMP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.22.2 Release Notes MPLAB Harmony Version: v0.70b SNMP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.22.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3822 licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.22.4 Using the Library This topic describes the basic architecture of the SNMP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: snmp.h The interface to the SNMP TCP/IP Stack library is defined in the "snmp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the SNMP TCP/IP Stack library should include "tcpip.h". Library File: The SNMP TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.22.4.1 Abstraction Model This library provides the API of the SNMP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description SNMP Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.22.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SNMP module. Library Interface Section Description SNMP Module Functions Routines to configure this module SNMPv3 Module Functions Routines to configure this module SNMP Application Functions Routines to configure an application SNMPv3 Application Functions Routines to configure an application SNMP Data Types and Constants This section provides various definitions describing this API 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3823 SNMPv3 Data Types and Constants This section provides various definitions describing this API 5.8.22.5 Configuring the Library Macros Name Description AUTH_LOCALIZED_PASSWORD_KEY_LEN SNMPv3 Authentication Localized passwed key lenegth size END_OF_SNMP_READ_COMMUNITIES ?? END_OF_SNMP_WRITE_COMMUNITIES ?? MY_DEFAULT_SNMP_IF For multi-homed hosts, the default SNMP interface NOTIFY_COMMUNITY_LEN Length of Community name array OID_MAX_LEN Change this to match your OID string length. PRIV_LOCALIZED_PASSWORD_KEY_LEN SNMPv3 Privacy Pasword key length size SNMP_BIB_FILE_NAME Name of the bib file for snmp SNMP_COMMUNITY_MAX_LEN This is the maximum length for community string. Application must ensure that this length is observed. SNMP module adds one byte extra after SNMP_COMMUNITY_MAX_LEN for adding '0' NULL character. SNMP_MAX_COMMUNITY_SUPPORT Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying fewer strings is legal, as long as at least one is present. SNMP_MAX_MSG_SIZE SNMP MIN and MAX message 484 bytes in size. As per RFC 3411 snmpEngineMaxMessageSize and RFC 1157 ( section 4- protocol specification ) and implementation supports more than 484 whenever feasible. SNMP_MAX_NON_REC_ID_OID Update the Non record id OID value which is part of CustomSnmpDemo.c file 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3824 SNMP_READ_COMMUNITIES Default SNMPv2C community names. These can be overridden at run time if alternate strings are present in external EEPROM or Flash (actual strings coould be stored by the TCPIP storage service. These strings are case sensitive. An empty string means disabled (not matchable). For application security, these default community names should not be used, but should all be disabled to force the end user to select unique community names. These defaults are provided only to make it easier to start development. Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying... more SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE This macro will be used to avoid SNMP OID memory buffer corruption SNMP_WRITE_COMMUNITIES Default SNMPv2C community names. See SNMP_READ_COMMUNITIES for more information. SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE SNMPv3 authentication localized Key length for memory validation SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE SNMPv3 privacy key length size for memory validation SNMPV3_TRAP_MSG_PROCESS_MODEL_DB This is macro SNMPV3_TRAP_MSG_PROCESS_MODEL _DB. SNMPV3_TRAP_SECURITY_LEVEL_DB This is macro SNMPV3_TRAP_SECURITY_LEVEL_DB. SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB This is macro SNMPV3_TRAP_SECURITY_MODEL_TYPE _DB. SNMPV3_TRAP_USER_SECURITY_NAME_DB This is macro SNMPV3_TRAP_USER_SECURITY_NAME _DB. SNMPV3_USER_AUTH_PASSWD_DB This is macro SNMPV3_USER_AUTH_PASSWD_DB. SNMPV3_USER_AUTH_TYPE_DB This is macro SNMPV3_USER_AUTH_TYPE_DB. SNMPV3_USER_PRIV_PASSWD_DB This is macro SNMPV3_USER_PRIV_PASSWD_DB. SNMPV3_USER_PRIV_TYPE_DB This is macro SNMPV3_USER_PRIV_TYPE_DB. SNMPV3_USER_SECURITY_NAME_DB This is macro SNMPV3_USER_SECURITY_NAME_DB. SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE User security name length for memory validation SNMPV3_USM_MAX_USER Client configuration options TRAP_COMMUNITY_MAX_LEN Maximum length of community name table TRAP_TABLE_SIZE This table maintains list of intereseted receivers who should receive notifications when some interesting event occurs. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3825 USER_SECURITY_NAME_LEN SNMPv3 User Security Name length Structures Name Description SNMP_NET_CONFIG SNMP Network Configuration structure typedef Description The configuration of the SNMP TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the SNMP TCP/IP Stack Library. Based on the selections made, the SNMP TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the SNMP TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.22.5.1 AUTH_LOCALIZED_PASSWORD_KEY_LEN Macro C #define AUTH_LOCALIZED_PASSWORD_KEY_LEN (20) Description SNMPv3 Authentication Localized passwed key lenegth size 5.8.22.5.2 END_OF_SNMP_READ_COMMUNITIES Macro C #define END_OF_SNMP_READ_COMMUNITIES Description ?? 5.8.22.5.3 END_OF_SNMP_WRITE_COMMUNITIES Macro C #define END_OF_SNMP_WRITE_COMMUNITIES Description ?? 5.8.22.5.4 MY_DEFAULT_SNMP_IF Macro C #define MY_DEFAULT_SNMP_IF "PIC32INT" Description For multi-homed hosts, the default SNMP interface 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3826 5.8.22.5.5 NOTIFY_COMMUNITY_LEN Macro C #define NOTIFY_COMMUNITY_LEN (SNMP_COMMUNITY_MAX_LEN) Description Length of Community name array 5.8.22.5.6 OID_MAX_LEN Macro C #define OID_MAX_LEN (18) Description Change this to match your OID string length. 5.8.22.5.7 PRIV_LOCALIZED_PASSWORD_KEY_LEN Macro C #define PRIV_LOCALIZED_PASSWORD_KEY_LEN (20) Description SNMPv3 Privacy Pasword key length size 5.8.22.5.8 SNMP_BIB_FILE_NAME Macro C #define SNMP_BIB_FILE_NAME "snmp.bib" Description Name of the bib file for snmp 5.8.22.5.9 SNMP_COMMUNITY_MAX_LEN Macro C #define SNMP_COMMUNITY_MAX_LEN (8u) Description This is the maximum length for community string. Application must ensure that this length is observed. SNMP module adds one byte extra after SNMP_COMMUNITY_MAX_LEN for adding '0' NULL character. 5.8.22.5.10 SNMP_MAX_COMMUNITY_SUPPORT Macro C #define SNMP_MAX_COMMUNITY_SUPPORT (3u) Description Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying fewer strings is legal, as long as at least one is present. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3827 5.8.22.5.11 SNMP_MAX_MSG_SIZE Macro C #define SNMP_MAX_MSG_SIZE 484 Description SNMP MIN and MAX message 484 bytes in size. As per RFC 3411 snmpEngineMaxMessageSize and RFC 1157 ( section 4- protocol specification ) and implementation supports more than 484 whenever feasible. 5.8.22.5.12 SNMP_MAX_NON_REC_ID_OID Macro C #define SNMP_MAX_NON_REC_ID_OID 3 Description Update the Non record id OID value which is part of CustomSnmpDemo.c file 5.8.22.5.13 SNMP_READ_COMMUNITIES Macro C #define SNMP_READ_COMMUNITIES {"public", "read", ""} Description Default SNMPv2C community names. These can be overridden at run time if alternate strings are present in external EEPROM or Flash (actual strings coould be stored by the TCPIP storage service. These strings are case sensitive. An empty string means disabled (not matchable). For application security, these default community names should not be used, but should all be disabled to force the end user to select unique community names. These defaults are provided only to make it easier to start development. Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying fewer strings is legal, as long as at least one is present. A string larger than SNMP_COMMUNITY_MAX_LEN bytes will be ignored. 5.8.22.5.14 SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE Macro C #define SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE (8) Description This macro will be used to avoid SNMP OID memory buffer corruption 5.8.22.5.15 SNMP_WRITE_COMMUNITIES Macro C #define SNMP_WRITE_COMMUNITIES {"private", "write", "public"} Description Default SNMPv2C community names. See SNMP_READ_COMMUNITIES for more information. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3828 5.8.22.5.16 SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE Macro C #define SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE (AUTH_LOCALIZED_PASSWORD_KEY_LEN+1) Description SNMPv3 authentication localized Key length for memory validation 5.8.22.5.17 SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE Macro C #define SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE (PRIV_LOCALIZED_PASSWORD_KEY_LEN+1) Description SNMPv3 privacy key length size for memory validation 5.8.22.5.18 SNMPV3_TRAP_MSG_PROCESS_MODEL_DB Macro C #define SNMPV3_TRAP_MSG_PROCESS_MODEL_DB {SNMPV3_MSG_PROCESSING_MODEL,SNMPV3_MSG_PROCESSING_MODEL,SNMPV3_MSG_PROCESSING_MODEL} Description This is macro SNMPV3_TRAP_MSG_PROCESS_MODEL_DB. 5.8.22.5.19 SNMPV3_TRAP_SECURITY_LEVEL_DB Macro C #define SNMPV3_TRAP_SECURITY_LEVEL_DB {AUTH_PRIV,AUTH_NO_PRIV,NO_AUTH_NO_PRIV} Description This is macro SNMPV3_TRAP_SECURITY_LEVEL_DB. 5.8.22.5.20 SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB Macro C #define SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB {SNMPV3_USM_SECURITY_MODEL,SNMPV3_USM_SECURITY_MODEL,SNMPV3_USM_SECURITY_MODEL} Description This is macro SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB. 5.8.22.5.21 SNMPV3_TRAP_USER_SECURITY_NAME_DB Macro C #define SNMPV3_TRAP_USER_SECURITY_NAME_DB {"microchip","SnmpAdmin","root"} 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3829 Description This is macro SNMPV3_TRAP_USER_SECURITY_NAME_DB. 5.8.22.5.22 SNMPV3_USER_AUTH_PASSWD_DB Macro C #define SNMPV3_USER_AUTH_PASSWD_DB {"auth12345","ChandlerUS",""} Description This is macro SNMPV3_USER_AUTH_PASSWD_DB. 5.8.22.5.23 SNMPV3_USER_AUTH_TYPE_DB Macro C #define SNMPV3_USER_AUTH_TYPE_DB {SNMPV3_HAMC_MD5,SNMPV3_HMAC_SHA1,SNMPV3_NO_HMAC_AUTH} Description This is macro SNMPV3_USER_AUTH_TYPE_DB. 5.8.22.5.24 SNMPV3_USER_PRIV_PASSWD_DB Macro C #define SNMPV3_USER_PRIV_PASSWD_DB {"priv12345","",""} Description This is macro SNMPV3_USER_PRIV_PASSWD_DB. 5.8.22.5.25 SNMPV3_USER_PRIV_TYPE_DB Macro C #define SNMPV3_USER_PRIV_TYPE_DB {SNMPV3_AES_PRIV,SNMPV3_NO_PRIV,SNMPV3_NO_PRIV} Description This is macro SNMPV3_USER_PRIV_TYPE_DB. 5.8.22.5.26 SNMPV3_USER_SECURITY_NAME_DB Macro C #define SNMPV3_USER_SECURITY_NAME_DB {"microchip","SnmpAdmin","root"} Description This is macro SNMPV3_USER_SECURITY_NAME_DB. 5.8.22.5.27 SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE Macro C #define SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE (USER_SECURITY_NAME_LEN+1) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3830 Description User security name length for memory validation 5.8.22.5.28 SNMPV3_USM_MAX_USER Macro C #define SNMPV3_USM_MAX_USER 3 Description Client configuration options 5.8.22.5.29 TRAP_COMMUNITY_MAX_LEN Macro C #define TRAP_COMMUNITY_MAX_LEN (SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE+1) Description Maximum length of community name table 5.8.22.5.30 TRAP_TABLE_SIZE Macro C #define TRAP_TABLE_SIZE (2) Description This table maintains list of intereseted receivers who should receive notifications when some interesting event occurs. 5.8.22.5.31 USER_SECURITY_NAME_LEN Macro C #define USER_SECURITY_NAME_LEN (16) Description SNMPv3 User Security Name length 5.8.22.5.32 SNMP_NET_CONFIG Structure C typedef struct { uint8_t readCommunity[SNMP_MAX_COMMUNITY_SUPPORT][SNMP_COMMUNITY_MAX_LEN+1]; uint8_t writeCommunity[SNMP_MAX_COMMUNITY_SUPPORT][SNMP_COMMUNITY_MAX_LEN+1]; uint32_t SnmpEngineBootRcrd; } SNMP_NET_CONFIG; Description SNMP Network Configuration structure typedef 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3831 Members Members Description uint8_t readCommunity[SNMP_MAX_COMMUNITY_SUPPORT][SNMP_COMMUNITY_MAX_LEN+1]; SNMPv2C Read community names SNMP_COMMUNITY_MAX_LE N (8) + 1 null termination byte uint8_t writeCommunity[SNMP_MAX_COMMUNITY_SUPPORT][SNMP_COMMUNITY_MAX_LEN+1]; SNMPv2C Write community names SNMP_COMMUNITY_MAX_LE N (8) + 1 null termination byte uint32_t SnmpEngineBootRcrd; SNMP Engine Boot Record location 5.8.22.6 Building the Library This section list the files that are available in the \src of the SNMP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.22.7 Library Interface SNMP Application Functions Name Description SNMPGetExactIndex To search for exact index node in case of a Sequence variable. SNMPGetNextIndex To search for next index node in case of a Sequence variable. SNMPGetVar Used to Get/collect OID variable information. SNMPIsValidSetLen Validates the set variable data length to data type. SNMPSendTrap Prepare, validate remote node which will receive trap and send trap pdu. SNMPSetVar This routine Set the mib variable with the requested value. SNMPValidateCommunity Validates community name for access control. SNMP Data Types and Constants Name Description SNMP_END_OF_VAR This is macro SNMP_END_OF_VAR. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3832 SNMP_H FileName: SNMP.h Copyright © 2012 released Microchip Technology Inc. All rights reserved. Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement). You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations. SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND... more SNMP_INDEX_INVALID This is macro SNMP_INDEX_INVALID. SNMP_START_OF_VAR SNMP_V1 SNMP_V2C This is macro SNMP_V2C. SNMP_V3 This is macro SNMP_V3. GENERIC_TRAP_NOTIFICATION_TYPE This is type GENERIC_TRAP_NOTIFICATION_TYPE. IPV6_SNMP_TRAP_INFO This is type IPV6_SNMP_TRAP_INFO. SNMP_BUFFER_DATA SNMPv1/v2c SNMP_COMMUNITY_TYPE This is type SNMP_COMMUNITY_TYPE. SNMP_ID This is the SNMP OID variable id. This id is assigned via MIB file. Only dynamic and AgentID variables can contian ID. MIB2BIB utility enforces this rules when BIB was generated. typedef int SNMP_ID; SNMP_INDEX This is type SNMP_INDEX. SNMP_MODULE_CONFIG This is type SNMP_MODULE_CONFIG. SNMP_NON_MIB_RECD_INFO This is type SNMP_NON_MIB_RECD_INFO. SNMP_NOTIFY_INFO // the only if that runs SNMP SNMP_PROCESSING_MEM_INFO_PTRS This is type SNMP_PROCESSING_MEM_INFO_PTRS. SNMP_STACK_DCPT_STUB SNMP_TRAP_INFO This is type SNMP_TRAP_INFO. SNMP_TRAP_IP_ADDRESS_TYPE This is type SNMP_TRAP_IP_ADDRESS_TYPE. SNMP_VAL This is type SNMP_VAL. TCPIP_SNMP_DCPT TCPIP_STACK_USE_IPV6 TCPIP_SNMP_SM This is type TCPIP_SNMP_SM. VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE This is type VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE. tIPV6_SNMP_TRAP_INFO This is type IPV6_SNMP_TRAP_INFO. tSNMP_TRAP_INFO This is type SNMP_TRAP_INFO. SNMP Module Functions Name Description TCPIP_SNMP_ClientGetNet TCPIP_SNMP_DataCopyToProcessBuffer Copies uint8_t data to dynamically allocated memory buffer. TCPIP_SNMP_EventNotifyGet To Get the IPv6 DHCP event notification. TCPIP_SNMP_Notify Creates and Sends TRAP pdu. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3833 TCPIP_SNMP_NotifyIsReady Resolves given remoteHost IP address into MAC address. TCPIP_SNMP_NotifyPrepare Collects trap notification info and send ARP to remote host. TCPIP_SNMP_PacketProcStubPtrsGet Get SNMP packet processing memory pointer. TCPIP_SNMP_ProcessBufferDataGet Reads uint8_t data from dynamically allocated memory buffer. TCPIP_SNMP_ReadCommunityGet Get the readCommunity String with Snmp index. TCPIP_SNMP_TrapTimeGet Get SNMP Trap UDP client open socket timeout. TCPIP_SNMP_WriteCommunityGet Get the writeCommunity String with Snmp index. SNMPv3 Application Functions Name Description SNMPv3ComputeHMACIpadOpadForAuthLoclzedKey Compute HMAC inner and outer pad for authorization localized key. SNMPv3USMAuthPrivPswdLocalization Convert Auth and Priv password to the localized Key using SNMPEngineID. TCPIP_SNMPv3_CmprTrapSecNameAndSecLvlWithUSMDb Routine to find the index of the user name in the user data base table. SNMPv3 Data Types and Constants Name Description SNMPV3_PROCESSING_MEM_INFO_PTRS SNMPv3 Processing Memory Pointers SNMPV3_STACK_DCPT_STUB SNMPv3 Descriptor Structure Typedef SNMPv3 Module Functions Name Description TCPIP_SNMPv3_Notify Creates and Sends SNMPv3 TRAP pdu. TCPIP_SNMPV3_PacketProcStubPtrsGet Get SNMPv3 packet processing memory pointer. Description This section describes the Application Programming Interface (API) functions of the SNMP TCP/IP Stack. Refer to each section for a detailed description. 5.8.22.7.1 SNMP Module Functions 5.8.22.7.1.1 TCPIP_SNMP_ClientGetNet Function C TCPIP_NET_HANDLE TCPIP_SNMP_ClientGetNet(); 5.8.22.7.1.2 TCPIP_SNMP_DataCopyToProcessBuffer Function C bool TCPIP_SNMP_DataCopyToProcessBuffer( uint8_t val, SNMP_BUFFER_DATA * putbuf ); Description The SNMPv1 and v2c stack implementation uses dynamically allocated memory buffer for processing of request and response packets. This routine copies the uint8_t data to the allocated buffer and updates the offset length couter. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3834 Preconditions The SNMPv1 and v2c stack has sucessfully allocated dynamic memory buffer from the Heap Parameters Parameters Description val uint8_t value to be written to the buffer putbuf pointer to the dynamically allocated buffer to which the 'val' to be written Return Values Return Values Description true if successfully write to the buffer false failure in writing to the buffer Remarks This routine is used by the SNMP stack. If required to be used by the application code, valid pointers should be passed to this routine. 5.8.22.7.1.3 TCPIP_SNMP_EventNotifyGet Function C IPV6_EVENT_TYPE TCPIP_SNMP_EventNotifyGet( TCPIP_NET_HANDLE hNet ); Description This rutine is used to get the DHCP with IPv6 notication if the IPv6 unicast address is updated. Preconditions TCPIP_SNMP_Initialize() is called. Parameters Parameters Description hNet Interface Remarks None. 5.8.22.7.1.4 TCPIP_SNMP_Notify Function C bool TCPIP_SNMP_Notify( SNMP_ID var, SNMP_VAL val, SNMP_INDEX index ); Description This function creates SNMP V2 Trap PDU and sends it to previously specified remoteHost. SNMP V1 trap pdu: | PDU-type | enterprise | agent-addr | generic-trap | specific-trap | | time-stamp | varbind-list | The v1 enterprise is mapped directly to SNMPv2TrapOID.0 SNMP V2 trap pdu: version (0 or 1) | community | SNMP-PDU |pdu-type | request-id | error-status |err-index |varbinds 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3835 The first two variables (in varbind-list) of snmpv2 are: sysUpTime.0 and SNMPv2TrapOID.0 Generic Trap OID is used as the varbind for authentication failure. Preconditions TCPIP_SNMP_NotifyIsReady() is already called and returned true. Parameters Parameters Description var SNMP var ID that is to be used in notification val Value of var. Only value of uint8_t, uint16_t or uint32_t can be sent. index Index of var. If this var is a single,index would be 0, or else if this var Is a sequence, index could be any value from 0 to 127 Return Values Return Values Description true if SNMP notification was successful sent. This does not guarantee that remoteHost recieved it. false Notification sent failed. This would fail under following contions 1) Given SNMP_BIB_FILE does not exist in file system 2) Given var does not exist. 3) Previously given agentID does not exist 4) Data type of given var is unknown possible if file system itself was corrupted. Remarks This would fail if there were not UDP socket to open. 5.8.22.7.1.5 TCPIP_SNMP_NotifyIsReady Function C bool TCPIP_SNMP_NotifyIsReady( IP_MULTI_ADDRESS* remoteHost, SNMP_TRAP_IP_ADDRESS_TYPE eTrapMultiAddressType ); Description This function resolves given remoteHost IP address into MAC address using ARP module. If remoteHost is not aviailable, this function would never return true. Application must implement timeout logic to handle "remoteHost not avialable" situation. Preconditions TCPIP_SNMP_NotifyPrepare() is already called. Parameters Parameters Description remoteHost Pointer to remote Host IP address Return Values Return Values Description true If remoteHost IP address is resolved and TCPIP_SNMP_Notify may be called. false If remoteHost IP address is not resolved. Remarks This would fail if there were not UDP socket to open. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3836 5.8.22.7.1.6 TCPIP_SNMP_NotifyPrepare Function C void TCPIP_SNMP_NotifyPrepare( IP_MULTI_ADDRESS* remoteHost, char* community, uint8_t communityLen, SNMP_ID agentIDVar, uint8_t notificationCode, uint32_t timestamp ); Description This function prepares SNMP module to send SNMP trap notification to remote host. It sends ARP request to remote host to learn remote host MAC address. Preconditions TCPIP_SNMP_Initialize() is already called. Parameters Parameters Description remoteHost pointer to remote Host IP address community Community string to use to notify communityLen Community string length agentIDVar System ID to use identify this agent notificaitonCode Notification Code to use timestamp Notification timestamp in 100th of second. Returns None Remarks This is first of series of functions to complete SNMP notification. 5.8.22.7.1.7 TCPIP_SNMP_PacketProcStubPtrsGet Function C void TCPIP_SNMP_PacketProcStubPtrsGet( SNMP_PROCESSING_MEM_INFO_PTRS * dynMemInfoPtr ); Description This function is used to get dynamic memory allocation pointer details which is used for SNMP packet processing. Preconditions TCPIP_SNMP_Initialize() is already called. Parameters Parameters Description dynMemInfoPtr Dynamic memory pointer for packet processing Remarks None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3837 5.8.22.7.1.8 TCPIP_SNMP_ProcessBufferDataGet Function C uint8_t TCPIP_SNMP_ProcessBufferDataGet( SNMP_BUFFER_DATA getbuf, uint16_t pos ); Description The SNMPstack implementation uses dynamically allocated memory buffer for processing of request and response packets. This routine reads the uint8_t data from the allocated buffer at the positions (offset) provided. Preconditions The SNMPv1 and v2c stack has sucessfully allocated dynamic memory buffer from the Heap Parameters Parameters Description getbuf Structure from where to read the data byte. pos position in the buffer from which the data to be read Return Values Return Values Description uint8_t 1 byte value read Remarks The read position offset is required to be provided every time the routine is called. This API do not increment the buffer read offset automatically, everytime it is called. 5.8.22.7.1.9 TCPIP_SNMP_ReadCommunityGet Function C uint8_t* TCPIP_SNMP_ReadCommunityGet( int index ); Description Get the readCommunity String with Snmp index. Preconditions _SNMP_ProcessVariables() is called. Parameters Parameters Description index SNMP_MAX_COMMUNITY_SUPPORT. Return Values Return Values Description uint8_t * unsigned char community string Remarks None. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3838 5.8.22.7.1.10 TCPIP_SNMP_TrapTimeGet Function C SYS_TICK TCPIP_SNMP_TrapTimeGet(); Description This function returns a SYS_TICK time(snmpTrapTimer) which is used to timeout a SNMP TRAP notification for a HOST. snmpTrapTimer is initialized when there is UDP client socket open either for a HOST IPv4 or IPv6 address. Preconditions TCPIP_SNMP_Initialize() is already called. Remarks None. 5.8.22.7.1.11 TCPIP_SNMP_WriteCommunityGet Function C uint8_t* TCPIP_SNMP_WriteCommunityGet( int index ); Description Get the writeCommunity String with Snmp index. Preconditions _SNMP_ProcessVariables() is called. Parameters Parameters Description index SNMP_MAX_COMMUNITY_SUPPORT. Return Values Return Values Description uint8_t * unsigned char community string Remarks None. 5.8.22.7.2 SNMPv3 Module Functions 5.8.22.7.2.1 TCPIP_SNMPv3_Notify Function C bool TCPIP_SNMPv3_Notify( SNMP_ID var, SNMP_VAL val, SNMP_INDEX index, uint8_t targetIndex ); Description This function creates SNMPv3 trap PDU and sends it to previously specified remoteHost. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3839 Preconditions TRAP event is triggered. Parameters Parameters Description var SNMP var ID that is to be used in notification val Value of var. Only value of uint8_t, uint16_t or uint32_t can be sent. index Index of var. If this var is a single,index would be 0, or else if this var Is a sequence, index could be any value from 0 to 127 targetIndex -index of the 'Snmpv3TrapConfigData' table's security user name for which the TRAP PDU message header to constructed. Return Values Return Values Description true if SNMP notification was successful sent. This does not guarantee that remoteHost recieved it. false Notification sent failed. This would fail under following contions 1) Given SNMP_BIB_FILE does not exist in file system 2) Given var does not exist. 3) Previously given agentID does not exist 4) Data type of given var is unknown only possible if file system itself was corrupted. SNMPV3_MSG_PRIV_FAIL -encryption of the trap msg failed SNMPV3_MSG_AUTH_FAIL HAMC of the trap msg failed Remarks None 5.8.22.7.2.2 TCPIP_SNMPV3_PacketProcStubPtrsGet Function C void TCPIP_SNMPV3_PacketProcStubPtrsGet( SNMPV3_PROCESSING_MEM_INFO_PTRS * dynMemInfoPtr ); Description This function is used to get dynamic memory allocation pointer details which is used for SNMPv3 packet processing. Preconditions TCPIP_SNMP_Initialize() is already called. Parameters Parameters Description dynMemInfoPtr Dynamic memory pointer for packet processing Remarks The source code for this routine is found in snmp.c, not snmpv3.c. 5.8.22.7.3 SNMP Application Functions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3840 5.8.22.7.3.1 SNMPGetExactIndex Function C bool SNMPGetExactIndex( SNMP_ID var, SNMP_INDEX * index ); Description This is a callback function called by SNMP module. SNMP user must implement this function in user application and provide appropriate data when called. This function will only be called for OID variable of type sequence. Preconditions None Parameters Parameters Description var Variable id as per mib.h (input) index Index of variable (input) Return Values Return Values Description true If the exact index value exists for given variable at given index. false Otherwise. Remarks Only sequence index needs to be handled in this function. 5.8.22.7.3.2 SNMPGetNextIndex Function C bool SNMPGetNextIndex( SNMP_ID var, SNMP_INDEX* index ); Description This is a callback function called by SNMP module. SNMP user must implement this function in user application and provide appropriate data when called. This function will only be called for OID variable of type sequence. Preconditions None Parameters Parameters Description var Variable id whose value is to be returned index Next Index of variable that should be transferred Return Values Return Values Description true If a next index value exists for given variable at given index and index parameter contains next valid index. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3841 false Otherwise. Remarks Only sequence index needs to be handled in this function. 5.8.22.7.3.3 SNMPGetVar Function C bool SNMPGetVar( SNMP_ID var, SNMP_INDEX index, uint8_t* ref, SNMP_VAL* val ); Description This is a callback function called by SNMP module. SNMP user must implement this function in user application and provide appropriate data when called. Preconditions None Parameters Parameters Description var Variable id whose value is to be returned index Index of variable that should be transferred ref Variable reference used to transfer multi-byte data It is always SNMP_START_OF_VAR when very first byte is requested. Otherwise, use this as a reference to keep track of multi-byte transfers. val Pointer to up to 4 byte buffer. If var data type is uint8_t, transfer data in val->byte If var data type is uint16_t, transfer data in val->word If var data type is uint32_t, transfer data in val->dword If var data type is IP_ADDRESS, transfer data in val->v[] or val->dword If var data type is COUNTER32, TIME_TICKS or GAUGE32, transfer data in val->dword If var data type is ASCII_STRING or OCTET_STRING transfer data in val->byte using multi-byte transfer mechanism. Return Values Return Values Description true If a value exists for given variable at given index. false Otherwise. Remarks None. 5.8.22.7.3.4 SNMPIsValidSetLen Function C bool SNMPIsValidSetLen( SNMP_ID var, uint8_t len, uint8_t index ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3842 Description This routine is used to validate the dyanmic variable data length to the variable data type. It is used when SET request is processed. This is a callback function called by module. User application must implement this function. Preconditions TCPIP_SNMP_ProcessSetVar() is called. Parameters Parameters Description var Variable id whose value is to be set len Length value that is to be validated. Return Values Return Values Description true if given var can be set to given len false if otherwise. Remarks This function will be called for only dynamic variables that are defined as ASCII_STRING and OCTET_STRING (i.e. data length greater than 4 bytes) 5.8.22.7.3.5 SNMPSendTrap Function C void SNMPSendTrap(); Description This function is used to send trap notification to previously configured ip address if trap notification is enabled. There are different trap notification code. The current implementation sends trap for authentication failure (4). Preconditions If application defined event occurs to send the trap. Returns None. Remarks This is a callback function called by the application on certain predefined events. This routine only implemented to send a authentication failure Notification-type macro with PUSH_BUTTON oid stored in MPFS. If the ARP is no resolved i.e. if TCPIP_SNMP_NotifyIsReady() returns false, this routine times out in 5 seconds. This routine should be modified according to event occured and should update corrsponding OID and notification type to the trap pdu. 5.8.22.7.3.6 SNMPSetVar Function C bool SNMPSetVar( SNMP_ID var, SNMP_INDEX index, uint8_t ref, SNMP_VAL val ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3843 Description This is a callback function called by module for the snmp SET request.User application must modify this function for the new variables address. Preconditions TCPIP_SNMP_ProcessVariables() is called. Parameters Parameters Description var Variable id whose value is to be set ref Variable reference used to transfer multi-byte data 0 if first byte is set otherwise nonzero value to indicate corresponding byte being set. val Up to 4 byte data value. If var data type is uint8_t, variable value is in val->byte If var data type is uint16_t, variable value is in val->word If var data type is uint32_t, variable value is in val->dword. If var data type is IP_ADDRESS, COUNTER32, or GAUGE32, value is in val->dword If var data type is OCTET_STRING, ASCII_STRING value is in val->byte; multi-byte transfer will be performed to transfer remaining bytes of data. Return Values Return Values Description true if it is OK to set more byte(s). false if otherwise. Remarks This function may get called more than once depending on number of bytes in a specific set request for given variable. only dynamic read-write variables needs to be handled. 5.8.22.7.3.7 SNMPValidateCommunity Function C uint8_t SNMPValidateCommunity( uint8_t* community ); Description This function validates the community name for the mib access to NMS. The snmp community name received in the request pdu is validated for read and write community names. The agent gives an access to the mib variables only if the community matches with the predefined values. This routine also sets a gloabal flag to send trap if authentication failure occurs. Preconditions TCPIP_SNMP_Initialize is already called. Parameters Parameters Description community Pointer to community string as sent by NMS. Returns This routine returns the community validation result as READ_COMMUNITY or WRITE_COMMUNITY or INVALID_COMMUNITY Remarks This is a callback function called by module. User application must implement this function and verify that community matches 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3844 with predefined value. This validation occurs for each NMS request. 5.8.22.7.4 SNMPv3 Application Functions 5.8.22.7.4.1 SNMPv3ComputeHMACIpadOpadForAuthLoclzedKey Function C void SNMPv3ComputeHMACIpadOpadForAuthLoclzedKey( uint8_t userDBIndex ); Description This routine computes HMAC inner and outer pad strings for authorization localized key. RFC - 2104. Preconditions TCPIP_SNMPv3_Initialize() and ProcessVariabels() are called. Parameters Parameters Description userDBIndex password storage poniter Remarks None 5.8.22.7.4.2 SNMPv3USMAuthPrivPswdLocalization Function C void SNMPv3USMAuthPrivPswdLocalization( uint8_t userDBIndex ); Description This routine converts MD5 or SHA1 and AES privacy password key to localized key using snmpSngineID(RFC- 3414 - section 6). Preconditions TCPIP_SNMPv3_Initialize() and ProcessVariabels() are called. Parameters Parameters Description userDBIndex authentication protocol type Remarks None 5.8.22.7.4.3 TCPIP_SNMPv3_CmprTrapSecNameAndSecLvlWithUSMDb Function C bool TCPIP_SNMPv3_CmprTrapSecNameAndSecLvlWithUSMDb( uint8_t tragetIndex, uint8_t userTrapSecLen, uint8_t * userTrapSecurityName, STD_BASED_SNMPV3_SECURITY_LEVEL securityLevel ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3845 Description There are two different data base tables defined with SNMPv3 stack, like 'UserInfoDataBase' and 'Snmpv3TrapConfigData'. This routine is used to validte the trap user security level setting with SET request. Preconditions SET operation would be allowed if the USM security conditions and user security name in the request is matched to one of the user security name stored in the usm user database. Parameters Parameters Description userTrapSecLen user sec name length in the SET request userTrapSecurityName pointer to user sec name in the SET request securityLevel trap security level to be SET on the agent Return Values Return Values Description true if the trap target user sec level setting is successful FLASE If the SET failed due to non matching of the security parameters Remarks None. 5.8.22.7.5 SNMP Data Types and Constants 5.8.22.7.5.1 SNMP_END_OF_VAR Macro C #define SNMP_END_OF_VAR (0xff) Description This is macro SNMP_END_OF_VAR. 5.8.22.7.5.2 SNMP_H Macro C #define SNMP_H Description FileName: SNMP.h Copyright © 2012 released Microchip Technology Inc. All rights reserved. Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement). You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations. SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROCHIP OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT, NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3846 OTHER LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS. 5.8.22.7.5.3 SNMP_INDEX_INVALID Macro C #define SNMP_INDEX_INVALID (0xff) Description This is macro SNMP_INDEX_INVALID. 5.8.22.7.5.4 SNMP_START_OF_VAR Macro C #define SNMP_START_OF_VAR (0) 5.8.22.7.5.5 SNMP_V1 Macro C #define SNMP_V1 (0) 5.8.22.7.5.6 SNMP_V2C Macro C #define SNMP_V2C (1) Description This is macro SNMP_V2C. 5.8.22.7.5.7 SNMP_V3 Macro C #define SNMP_V3 (3) Description This is macro SNMP_V3. 5.8.22.7.5.8 GENERIC_TRAP_NOTIFICATION_TYPE Enumeration C typedef enum { COLD_START = 0x0, WARM_START = 0x1, LINK_DOWN = 0x2, LINK_UP = 0x3, AUTH_FAILURE = 0x4, EGP_NEBOR_LOSS = 0x5, ENTERPRISE_SPECIFIC = 0x6 } GENERIC_TRAP_NOTIFICATION_TYPE; Description This is type GENERIC_TRAP_NOTIFICATION_TYPE. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3847 5.8.22.7.5.9 IPV6_SNMP_TRAP_INFO Structure C typedef struct tIPV6_SNMP_TRAP_INFO { uint8_t Size; struct { uint8_t communityLen; char community[TRAP_COMMUNITY_MAX_LEN]; IPV6_ADDR IPv6Address; struct { unsigned int bEnabled : 1; } Flags; } table[TRAP_TABLE_SIZE]; } IPV6_SNMP_TRAP_INFO; Description This is type IPV6_SNMP_TRAP_INFO. Members Members Description uint8_t communityLen; Community name length char community[TRAP_COMMUNITY_MAX_LEN]; Community name array IPV6_ADDR IPv6Address; IPv6 address to which trap to be sent unsigned int bEnabled : 1; Trap enabled flag 5.8.22.7.5.10 SNMP_BUFFER_DATA Structure C typedef struct { uint8_t * head; uint16_t length; } SNMP_BUFFER_DATA; Description SNMPv1/v2c 5.8.22.7.5.11 SNMP_COMMUNITY_TYPE Enumeration C typedef enum { READ_COMMUNITY = 1, WRITE_COMMUNITY = 2, INVALID_COMMUNITY = 3 } SNMP_COMMUNITY_TYPE; Description This is type SNMP_COMMUNITY_TYPE. Members Members Description READ_COMMUNITY = 1 Read only community WRITE_COMMUNITY = 2 Read write community INVALID_COMMUNITY = 3 Community invalid 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3848 5.8.22.7.5.12 SNMP_ID Type C typedef uint32_t SNMP_ID; Description This is the SNMP OID variable id. This id is assigned via MIB file. Only dynamic and AgentID variables can contian ID. MIB2BIB utility enforces this rules when BIB was generated. typedef int SNMP_ID; 5.8.22.7.5.13 SNMP_INDEX Type C typedef uint8_t SNMP_INDEX; Description This is type SNMP_INDEX. 5.8.22.7.5.14 SNMP_MODULE_CONFIG Structure C typedef struct { } SNMP_MODULE_CONFIG; Description This is type SNMP_MODULE_CONFIG. 5.8.22.7.5.15 SNMP_NON_MIB_RECD_INFO Structure C typedef struct { uint8_t oidstr[16]; uint8_t version; } SNMP_NON_MIB_RECD_INFO; Description This is type SNMP_NON_MIB_RECD_INFO. 5.8.22.7.5.16 SNMP_NOTIFY_INFO Structure C typedef struct { char community[NOTIFY_COMMUNITY_LEN]; uint8_t communityLen; SNMP_ID agentIDVar; uint8_t notificationCode; UDP_SOCKET socket; TCPIP_UINT32_VAL timestamp; SNMP_ID trapIDVar; TCPIP_NET_HANDLE snmpTrapInf; } SNMP_NOTIFY_INFO; Description // the only if that runs SNMP 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3849 Members Members Description char community[NOTIFY_COMMUNITY_LEN]; Community name array uint8_t communityLen; Community name length SNMP_ID agentIDVar; Agent id for trap identification uint8_t notificationCode; Trap notification code UDP_SOCKET socket; Udp socket number TCPIP_UINT32_VAL timestamp; Time stamp for trap SNMP_ID trapIDVar; SNMPV2 specific trap TCPIP_NET_HANDLE snmpTrapInf; interface we use for the SNMP TRAP 5.8.22.7.5.17 SNMP_PROCESSING_MEM_INFO_PTRS Structure C typedef struct { SNMP_STACK_DCPT_STUB* snmpStkDynMemStubPtr; const void* snmpHeapMemHandler; TCPIP_SNMP_DCPT* snmpDcptPtr; } SNMP_PROCESSING_MEM_INFO_PTRS; Description This is type SNMP_PROCESSING_MEM_INFO_PTRS. 5.8.22.7.5.18 SNMP_STACK_DCPT_STUB Structure C typedef struct { uint8_t gOIDCorrespondingSnmpMibID; uint8_t gSetTrapSendFlag; bool getZeroInstance; uint8_t appendZeroToOID; uint8_t gSendTrapFlag; uint8_t gGenericTrapNotification; uint8_t gSpecificTrapNotification; SNMP_NOTIFY_INFO SNMPNotifyInfo; SNMP_BUFFER_DATA outPduBufData; SNMP_BUFFER_DATA trapPduOutBufData; SNMP_NET_CONFIG snmpNetConfig; } SNMP_STACK_DCPT_STUB; Members Members Description SNMP_NOTIFY_INFO SNMPNotifyInfo; notify info for trap 5.8.22.7.5.19 SNMP_TRAP_INFO Structure C typedef struct tSNMP_TRAP_INFO { uint8_t Size; struct { uint8_t communityLen; char community[TRAP_COMMUNITY_MAX_LEN]; IPV4_ADDR IPAddress; struct { 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3850 unsigned int bEnabled : 1; } Flags; } table[TRAP_TABLE_SIZE]; } SNMP_TRAP_INFO; Description This is type SNMP_TRAP_INFO. Members Members Description uint8_t communityLen; Community name length char community[TRAP_COMMUNITY_MAX_LEN]; Community name array IPV4_ADDR IPAddress; IP address to which trap to be sent unsigned int bEnabled : 1; Trap enabled flag 5.8.22.7.5.20 SNMP_TRAP_IP_ADDRESS_TYPE Enumeration C typedef enum { IPV4_SNMP_TRAP = 1, IPV6_SNMP_TRAP } SNMP_TRAP_IP_ADDRESS_TYPE; Description This is type SNMP_TRAP_IP_ADDRESS_TYPE. 5.8.22.7.5.21 SNMP_VAL Union C typedef union { uint32_t dword; uint16_t word; uint8_t byte; uint8_t v[sizeof(uint32_t)]; } SNMP_VAL; Description This is type SNMP_VAL. Members Members Description uint32_t dword; double word value uint16_t word; word value uint8_t byte; byte value uint8_t v[sizeof(uint32_t)]; byte array 5.8.22.7.5.22 TCPIP_SNMP_DCPT Structure C typedef struct { TCPIP_SNMP_SM sm; UDP_SOCKET skt; bool readFromSnmpBuf; IPV6_HANDLE snmpIPV6Handler; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3851 IPV6_EVENT_TYPE ipv6EventType; } TCPIP_SNMP_DCPT; Description TCPIP_STACK_USE_IPV6 Members Members Description TCPIP_SNMP_SM sm; current status UDP_SOCKET skt; associated socket 5.8.22.7.5.23 TCPIP_SNMP_SM Enumeration C typedef enum { SNMP_HOME = 0, SNMP_LISTEN, SNMP_PROCESS, SNMP_PACKET_DISCARD } TCPIP_SNMP_SM; Description This is type TCPIP_SNMP_SM. 5.8.22.7.5.24 VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE Enumeration C typedef enum { VENDOR_TRAP_DEFAULT = 0x0, BUTTON_PUSH_EVENT = 0x1, POT_READING_MORE_512 = 0x2 } VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE; Description This is type VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE. 5.8.22.7.6 SNMPv3 Data Types and Constants 5.8.22.7.6.1 SNMPV3_PROCESSING_MEM_INFO_PTRS Structure C typedef struct { SNMPV3_STACK_DCPT_STUB * snmpv3StkProcessingDynMemStubPtr; const void* snmpHeapMemHandler; } SNMPV3_PROCESSING_MEM_INFO_PTRS; Description SNMPv3 Processing Memory Pointers 5.8.22.7.6.2 SNMPV3_STACK_DCPT_STUB Structure C typedef struct { uint16_t UserInfoDataBaseIndx; uint8_t SnmpEngineID[32]; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3852 uint8_t SnmpEngnIDLength; uint16_t SnmpMsgBufSeekPos; uint16_t ScopedPduDataPos; uint32_t SnmpEngineTimeOffset; uint32_t SnmpEngineBoots; TCPIP_UINT16_VAL UsmStatsEngineID; TCPIP_UINT32_VAL AuthoritativeSnmpEngineBoots; TCPIP_UINT32_VAL AuthoritativeSnmpEngnTime; TCPIP_UINT32_VAL IncmngSnmpPduMsgID; TCPIP_UINT32_VAL SnmpEngineTime; TCPIP_UINT32_VAL SnmpEngnMaxMsgSize; SNMPV3_REQUEST_WHOLEMSG InPduWholeMsgBuf; SNMPV3_RESPONSE_WHOLEMSG OUTPduWholeMsgBuf; SNMPV3_RESPONSE_WHOLEMSG TrapOUTPduWholeMsgBuf; snmpV3TrapConfigDataBase Snmpv3TrapConfigData[SNMPV3_USM_MAX_USER]; SNMPV3MSGDATA ScopedPduRequstBuf; SNMPV3MSGDATA ScopedPduRespnsBuf; SNMPV3MSGDATA PduHeaderBuf; SNMPV3MSGDATA TrapMsgHeaderBuf; SNMPV3MSGDATA TrapScopdPduRespnsBuf; dispatcherProcessPdu incomingPdu; uint8_t SnmpSecurityLevel; uint8_t SnmpRespnsSecrtyFlg; uint8_t SnmpInMsgAuthParmStrng[12+1]; uint8_t SnmpInMsgAuthParamLen; uint8_t snmpInMsgPrvParamStrng[8+1]; uint8_t SnmpInMsgPrivParmLen; uint8_t SnmpOutMsgAuthParaStrng[12+1]; uint8_t SnmpOutMsgAuthParmLen; uint8_t SnmpOutMsgPrvParmStrng[8+1]; uint8_t SnmpOutMsgPrivParmLen; uint32_t SnmpEngnSecurityModel; uint32_t SnmpEngnMsgProcessModel; SecuritySysProcessIncomingMsg SecurtyPrimtvesOfIncmngPdu; snmpV3EngnUserDataBase UserInfoDataBase[SNMPV3_USM_MAX_USER]; } SNMPV3_STACK_DCPT_STUB; Description SNMPv3 Descriptor Structure Typedef Members Members Description uint8_t SnmpEngineID[32]; Reserving 32 bytes for the snmpEngineID as the octet string length can vary form 5 to 32 uint32_t SnmpEngineBoots; The number of times that the SNMP engine has (re-)initialized itself since snmpEngineID was last configured. TCPIP_UINT32_VAL SnmpEngineTime; The number of seconds since the value of the SnmpEngineBoots object last changed snmpV3TrapConfigDataBase Snmpv3TrapConfigData[SNMPV3_USM_MAX_USER]; snmv3 global database for trap table uint32_t SnmpEngnSecurityModel; Maximum range (2^31-1), RFC3411 uint32_t SnmpEngnMsgProcessModel; Maximum range (2^31-1), RFC3411 5.8.22.8 Files Files Name Description snmp.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3853 snmp_config.h SNMP configuration file snmpv3.h This is file snmpv3.h. snmpv3_config.h SNMPv3 configuration file Description 5.8.22.8.1 snmp.h SNMP Defs for Microchip TCP/IP Stack Enumerations Name Description GENERIC_TRAP_NOTIFICATION_TYPE This is type GENERIC_TRAP_NOTIFICATION_TYPE. SNMP_COMMUNITY_TYPE This is type SNMP_COMMUNITY_TYPE. SNMP_TRAP_IP_ADDRESS_TYPE This is type SNMP_TRAP_IP_ADDRESS_TYPE. TCPIP_SNMP_SM This is type TCPIP_SNMP_SM. VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE This is type VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE. Functions Name Description SNMPGetExactIndex To search for exact index node in case of a Sequence variable. SNMPGetNextIndex To search for next index node in case of a Sequence variable. SNMPGetVar Used to Get/collect OID variable information. SNMPIsValidSetLen Validates the set variable data length to data type. SNMPSendTrap Prepare, validate remote node which will receive trap and send trap pdu. SNMPSetVar This routine Set the mib variable with the requested value. SNMPValidateCommunity Validates community name for access control. TCPIP_SNMP_ClientGetNet TCPIP_SNMP_DataCopyToProcessBuffer Copies uint8_t data to dynamically allocated memory buffer. TCPIP_SNMP_EventNotifyGet To Get the IPv6 DHCP event notification. TCPIP_SNMP_Notify Creates and Sends TRAP pdu. TCPIP_SNMP_NotifyIsReady Resolves given remoteHost IP address into MAC address. TCPIP_SNMP_NotifyPrepare Collects trap notification info and send ARP to remote host. TCPIP_SNMP_PacketProcStubPtrsGet Get SNMP packet processing memory pointer. TCPIP_SNMP_ProcessBufferDataGet Reads uint8_t data from dynamically allocated memory buffer. TCPIP_SNMP_ReadCommunityGet Get the readCommunity String with Snmp index. TCPIP_SNMP_TrapTimeGet Get SNMP Trap UDP client open socket timeout. TCPIP_SNMP_WriteCommunityGet Get the writeCommunity String with Snmp index. Macros Name Description SNMP_END_OF_VAR This is macro SNMP_END_OF_VAR. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3854 SNMP_H FileName: SNMP.h Copyright © 2012 released Microchip Technology Inc. All rights reserved. Microchip licenses to you the right to use, modify, copy and distribute Software only when embedded on a Microchip microcontroller or digital signal controller that is integrated into your product or third party product (pursuant to the sublicense terms in the accompanying license agreement). You should refer to the license agreement accompanying this Software for additional information regarding your rights and obligations. SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT AND... more SNMP_INDEX_INVALID This is macro SNMP_INDEX_INVALID. SNMP_START_OF_VAR SNMP_V1 SNMP_V2C This is macro SNMP_V2C. SNMP_V3 This is macro SNMP_V3. Structures Name Description tIPV6_SNMP_TRAP_INFO This is type IPV6_SNMP_TRAP_INFO. tSNMP_TRAP_INFO This is type SNMP_TRAP_INFO. IPV6_SNMP_TRAP_INFO This is type IPV6_SNMP_TRAP_INFO. SNMP_BUFFER_DATA SNMPv1/v2c SNMP_MODULE_CONFIG This is type SNMP_MODULE_CONFIG. SNMP_NON_MIB_RECD_INFO This is type SNMP_NON_MIB_RECD_INFO. SNMP_NOTIFY_INFO // the only if that runs SNMP SNMP_PROCESSING_MEM_INFO_PTRS This is type SNMP_PROCESSING_MEM_INFO_PTRS. SNMP_STACK_DCPT_STUB SNMP_TRAP_INFO This is type SNMP_TRAP_INFO. TCPIP_SNMP_DCPT TCPIP_STACK_USE_IPV6 Types Name Description SNMP_ID This is the SNMP OID variable id. This id is assigned via MIB file. Only dynamic and AgentID variables can contian ID. MIB2BIB utility enforces this rules when BIB was generated. typedef int SNMP_ID; SNMP_INDEX This is type SNMP_INDEX. Unions Name Description SNMP_VAL This is type SNMP_VAL. 5.8.22.8.2 snmp_config.h Simple Network Managment Protocol (SNMP) Configuration file This file contains the SNMP module configuration options 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3855 Macros Name Description END_OF_SNMP_READ_COMMUNITIES ?? END_OF_SNMP_WRITE_COMMUNITIES ?? MY_DEFAULT_SNMP_IF For multi-homed hosts, the default SNMP interface NOTIFY_COMMUNITY_LEN Length of Community name array OID_MAX_LEN Change this to match your OID string length. SNMP_BIB_FILE_NAME Name of the bib file for snmp SNMP_COMMUNITY_MAX_LEN This is the maximum length for community string. Application must ensure that this length is observed. SNMP module adds one byte extra after SNMP_COMMUNITY_MAX_LEN for adding '0' NULL character. SNMP_MAX_COMMUNITY_SUPPORT Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying fewer strings is legal, as long as at least one is present. SNMP_MAX_MSG_SIZE SNMP MIN and MAX message 484 bytes in size. As per RFC 3411 snmpEngineMaxMessageSize and RFC 1157 ( section 4- protocol specification ) and implementation supports more than 484 whenever feasible. SNMP_MAX_NON_REC_ID_OID Update the Non record id OID value which is part of CustomSnmpDemo.c file SNMP_READ_COMMUNITIES Default SNMPv2C community names. These can be overridden at run time if alternate strings are present in external EEPROM or Flash (actual strings coould be stored by the TCPIP storage service. These strings are case sensitive. An empty string means disabled (not matchable). For application security, these default community names should not be used, but should all be disabled to force the end user to select unique community names. These defaults are provided only to make it easier to start development. Specifying more strings than SNMP_MAX_COMMUNITY_SUPPORT will result in the later strings being ignored (but still wasting program memory). Specifying... more SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE This macro will be used to avoid SNMP OID memory buffer corruption SNMP_WRITE_COMMUNITIES Default SNMPv2C community names. See SNMP_READ_COMMUNITIES for more information. TRAP_COMMUNITY_MAX_LEN Maximum length of community name table TRAP_TABLE_SIZE This table maintains list of intereseted receivers who should receive notifications when some interesting event occurs. Structures Name Description SNMP_NET_CONFIG SNMP Network Configuration structure typedef 5.8.22.8.3 snmpv3.h This is file snmpv3.h. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3856 Functions Name Description SNMPv3ComputeHMACIpadOpadForAuthLoclzedKey Compute HMAC inner and outer pad for authorization localized key. SNMPv3USMAuthPrivPswdLocalization Convert Auth and Priv password to the localized Key using SNMPEngineID. TCPIP_SNMPv3_CmprTrapSecNameAndSecLvlWithUSMDb Routine to find the index of the user name in the user data base table. TCPIP_SNMPv3_Notify Creates and Sends SNMPv3 TRAP pdu. TCPIP_SNMPV3_PacketProcStubPtrsGet Get SNMPv3 packet processing memory pointer. Structures Name Description SNMPV3_PROCESSING_MEM_INFO_PTRS SNMPv3 Processing Memory Pointers SNMPV3_STACK_DCPT_STUB SNMPv3 Descriptor Structure Typedef 5.8.22.8.4 snmpv3_config.h Simple Network Managment Protocol (SNMPv3) Configuration file This file contains the SNMPv3 module configuration options Macros Name Description AUTH_LOCALIZED_PASSWORD_KEY_LEN SNMPv3 Authentication Localized passwed key lenegth size PRIV_LOCALIZED_PASSWORD_KEY_LEN SNMPv3 Privacy Pasword key length size SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE SNMPv3 authentication localized Key length for memory validation SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_USE SNMPv3 privacy key length size for memory validation SNMPV3_TRAP_MSG_PROCESS_MODEL_DB This is macro SNMPV3_TRAP_MSG_PROCESS_MODEL _DB. SNMPV3_TRAP_SECURITY_LEVEL_DB This is macro SNMPV3_TRAP_SECURITY_LEVEL_DB. SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB This is macro SNMPV3_TRAP_SECURITY_MODEL_TYPE _DB. SNMPV3_TRAP_USER_SECURITY_NAME_DB This is macro SNMPV3_TRAP_USER_SECURITY_NAME _DB. SNMPV3_USER_AUTH_PASSWD_DB This is macro SNMPV3_USER_AUTH_PASSWD_DB. SNMPV3_USER_AUTH_TYPE_DB This is macro SNMPV3_USER_AUTH_TYPE_DB. SNMPV3_USER_PRIV_PASSWD_DB This is macro SNMPV3_USER_PRIV_PASSWD_DB. SNMPV3_USER_PRIV_TYPE_DB This is macro SNMPV3_USER_PRIV_TYPE_DB. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNMP TCP/IP Stack Library 5-3857 SNMPV3_USER_SECURITY_NAME_DB This is macro SNMPV3_USER_SECURITY_NAME_DB. SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE User security name length for memory validation SNMPV3_USM_MAX_USER Client configuration options USER_SECURITY_NAME_LEN SNMPv3 User Security Name length 5.8.23 SNTP TCP/IP Stack Library 5.8.23.1 Introduction Simple Network Time Protocol (SNTP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the SNTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The SNTP module implements the Simple Network Time Protocol. The module (by default) updates its internal time every 10 minutes using a pool of public global time servers. It then calculates reference times on any call to SNTPGetUTCSeconds (see page 458) using the internal Tick timer module. The SNTP module is good for providing absolute time stamps. However, it should not be relied upon for measuring time differences (especially small differences). The pool of public time servers is implemented using round-robin DNS, so each update will come from a different server. Differing network delays and the fact that these servers are not verified implies that this time could be non-linear. While it is deemed reliable, it is not guaranteed to be accurate. The Tick module provides much better accuracy (since it is driven by a hardware clock) and resolution, and should be used for measuring timeouts and other internal requirements. Developers can change the value of NTP_SERVER ( see page 462) if they wish to always point to a preferred time server, or to specify a region when accessing time servers. The default is to use the global pool. 5.8.23.2 Release Notes MPLAB Harmony Version: v0.70b SNTP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3858 Nothing to report in this release. 5.8.23.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.23.4 Using the Library This topic describes the basic architecture of the SNTP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: sntp.h The interface to the SNTP TCP/IP Stack library is defined in the "sntp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the SNTP TCP/IP Stack library should include "tcpip.h". Library File: The SNTP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.23.4.1 Abstraction Model This library provides the API of the SNTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description SNTP Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.23.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SNTP module. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3859 Library Interface Section Description Functions Routines for configuring SNTP Data Types and Constants This section provides various definitions describing this API 5.8.23.5 Configuring the Library Macros Name Description NTP_DEFAULT_CONNECTION_TYPE The default connection type to use: IPv4/IPv6 NTP_DEFAULT_IF for multi-homed hosts, the default SNTP interface NTP_EPOCH Reference Epoch to use. (default: 01-Jan-1970 00:00:00) NTP_FAST_QUERY_INTERVAL Defines how long to wait to retry an update after a failure, seconds. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry. NTP_MAX_RETRIES Number of retries to connect to the server NTP_MAX_STRATUM The maximum acceptable NTP stratum number Should be less than 16 (unsynchronized server) NTP_QUERY_INTERVAL Defines how frequently to resynchronize the date/time, seconds (default: 10 minutes) NTP_REPLY_TIMEOUT Defines how long to wait before assuming the query has failed, seconds NTP_SERVER These are normally available network time servers. The actual IP returned from the pool will vary every minute so as to spread the load around stratum 1 timeservers. For best accuracy and network overhead you should locate the pool server closest to your geography, but it will still work if you use the global pool.ntp.org address or choose the wrong one or ship your embedded device to another geography. NTP_SERVER_PORT Port for contacting NTP servers NTP_TIME_STAMP_TMO elapsed time that qualifies a time stamp as stale normally it should be correlated with NTP_QUERY_INTERVAL NTP_VERSION The default NTP version to use (3 or 4) Description The configuration of the SNTP TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the SNTP TCP/IP Stack Library. Based on the selections made, the SNTP TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the SNTP TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.23.5.1 NTP_DEFAULT_CONNECTION_TYPE Macro C #define NTP_DEFAULT_CONNECTION_TYPE (IP_ADDRESS_TYPE_IPV4) Description The default connection type to use: IPv4/IPv6 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3860 5.8.23.5.2 NTP_DEFAULT_IF Macro C #define NTP_DEFAULT_IF "PIC32INT" Description for multi-homed hosts, the default SNTP interface 5.8.23.5.3 NTP_EPOCH Macro C #define NTP_EPOCH (86400ul * (365ul * 70ul + 17ul)) Description Reference Epoch to use. (default: 01-Jan-1970 00:00:00) 5.8.23.5.4 NTP_FAST_QUERY_INTERVAL Macro C #define NTP_FAST_QUERY_INTERVAL (14ul) Description Defines how long to wait to retry an update after a failure, seconds. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry. 5.8.23.5.5 NTP_MAX_RETRIES Macro C #define NTP_MAX_RETRIES (3) Description Number of retries to connect to the server 5.8.23.5.6 NTP_MAX_STRATUM Macro C #define NTP_MAX_STRATUM (15) Description The maximum acceptable NTP stratum number Should be less than 16 (unsynchronized server) 5.8.23.5.7 NTP_QUERY_INTERVAL Macro C #define NTP_QUERY_INTERVAL (10ul*60ul) Description Defines how frequently to resynchronize the date/time, seconds (default: 10 minutes) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3861 5.8.23.5.8 NTP_REPLY_TIMEOUT Macro C #define NTP_REPLY_TIMEOUT (6ul) Description Defines how long to wait before assuming the query has failed, seconds 5.8.23.5.9 NTP_SERVER Macro C #define NTP_SERVER "pool.ntp.org" Description These are normally available network time servers. The actual IP returned from the pool will vary every minute so as to spread the load around stratum 1 timeservers. For best accuracy and network overhead you should locate the pool server closest to your geography, but it will still work if you use the global pool.ntp.org address or choose the wrong one or ship your embedded device to another geography. 5.8.23.5.10 NTP_SERVER_PORT Macro C #define NTP_SERVER_PORT (123ul) Description Port for contacting NTP servers 5.8.23.5.11 NTP_TIME_STAMP_TMO Macro C #define NTP_TIME_STAMP_TMO (11 * 60) Description elapsed time that qualifies a time stamp as stale normally it should be correlated with NTP_QUERY_INTERVAL 5.8.23.5.12 NTP_VERSION Macro C #define NTP_VERSION (4) Description The default NTP version to use (3 or 4) 5.8.23.6 Building the Library This section list the files that are available in the \src of the SNTP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3862 5.8.23.7 Library Interface Data Types and Constants Name Description SNTP_MODULE_CONFIG Placeholder for SNTP Module Configuration SNTP_RESULT Provides a list of possible results for the SNTP module. Functions Name Description TCPIP_SNTP_ConnectionInitiate Forces a connection to the NTP server TCPIP_SNTP_ConnectionParamSet Sets the current SNTP connection parameters TCPIP_SNTP_LastErrorGet Gets the last error code set in the NTP server TCPIP_SNTP_TimeStampGet Gets the last valid timestamp obtained from an NTP server TCPIP_SNTP_UTCSecondsGet Obtains the current time from the SNTP module. Description This section describes the Application Programming Interface (API) functions of the SNTP TCP/IP Stack. Refer to each section for a detailed description. 5.8.23.7.1 Functions 5.8.23.7.1.1 TCPIP_SNTP_ConnectionInitiate Function C SNTP_RESULT TCPIP_SNTP_ConnectionInitiate(); Description This function will start a conenction to the NTP server Preconditions TCP/IP Stack should have been initialized Returns SNTP_RES_OK - if the call succeded SNTP_RES_BUSY error code if the connection could not have been started Remarks None 5.8.23.7.1.2 TCPIP_SNTP_ConnectionParamSet Function C SNTP_RESULT TCPIP_SNTP_ConnectionParamSet( TCPIP_NET_HANDLE netH, IP_ADDRESS_TYPE ntpConnType ); Description This function sets the parameters for the next SNTP connections. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3863 Preconditions TCP/IP Stack should have been initialized Parameters Parameters Description netH new interface to use as default SNTP interface if 0, the current interface is not changed ntpConnType type of conenction to make: IPv4 or IPv6 if IP_ADDRESS_TYPE_ANY, the current setting is not changed Returns SNTP_RES_OK - if the call succeded SNTP_RESULT error code otherwise Remarks None 5.8.23.7.1.3 TCPIP_SNTP_LastErrorGet Function C SNTP_RESULT TCPIP_SNTP_LastErrorGet(); Description This function returns the last NTP error code and clears the current error code Preconditions TCP/IP Stack should have been initialized Returns the last error code encountered by the NTP module Remarks None 5.8.23.7.1.4 TCPIP_SNTP_TimeStampGet Function C SNTP_RESULT TCPIP_SNTP_TimeStampGet( uint64_t* pTStamp, SYS_TICK* pLastUpdate ); Description This function gets the last valid timestamp obtained from an NTP server Preconditions TCP/IP Stack should have been initialized Parameters Parameters Description pTStamp pointer to a 64 bit buffer to store the last NTP timestamp could be NULL if the timestamp not needed pLastUpdate pointer to store the last time stamp update tick could be NULL if the update time not needed 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3864 Returns SNTP_RES_OK - if the call succeded SNTP_RES_TSTAMP_STALE error code if there's no recent time stamp Remarks None 5.8.23.7.1.5 TCPIP_SNTP_UTCSecondsGet Function C uint32_t TCPIP_SNTP_UTCSecondsGet(); Description This function obtains the current time as reported by the SNTP module. Use this value for absolute time stamping. The value returned is (by default) the number of seconds since 01-Jan-1970 00:00:00. Preconditions TCP/IP Stack should have been initialized Returns The number of seconds since the Epoch. (Default 01-Jan-1970 00:00:00) Remarks Do not use this function for time difference measurements. The Tick module is more appropriate for those requirements. 5.8.23.7.2 Data Types and Constants 5.8.23.7.2.1 SNTP_MODULE_CONFIG Structure C typedef struct { } SNTP_MODULE_CONFIG; Description Placeholder for SNTP Module Configuration 5.8.23.7.2.2 SNTP_RESULT Enumeration C typedef enum { SNTP_RES_OK, SNTP_RES_PROGRESS, SNTP_RES_BUSY = -1, SNTP_RES_TSTAMP_STALE = -2, SNTP_RES_SKT_ERR = -3, SNTP_RES_NTP_SERVER_TMO = -4, SNTP_RES_NTP_VERSION_ERR = -5, SNTP_RES_NTP_TSTAMP_ERR = -6, SNTP_RES_NTP_SYNC_ERR = -7, SNTP_RES_NTP_KOD_ERR = -8, SNTP_RES_NTP_DNS_ERR = -9 } SNTP_RESULT; Description SNTP_RESULT Enumeration 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3865 Provides a list of possible SNTP results. Members Members Description SNTP_RES_OK the operation was successful SNTP_RES_PROGRESS an NTP operation is in progress SNTP_RES_BUSY = -1 module is busy SNTP_RES_TSTAMP_STALE = -2 timestamp is stale, there's no recent timestamp SNTP_RES_SKT_ERR = -3 NTP socket could not be opened SNTP_RES_NTP_SERVER_TMO = -4 NTP server could not be accessed SNTP_RES_NTP_VERSION_ERR = -5 wrong NTP version received SNTP_RES_NTP_TSTAMP_ERR = -6 wrong NTP time stamp received SNTP_RES_NTP_SYNC_ERR = -7 NTP time synchronization error SNTP_RES_NTP_KOD_ERR = -8 an NTP KissOfDeath code has been received SNTP_RES_NTP_DNS_ERR = -9 an NTP DNS error Remarks None 5.8.23.8 Files Files Name Description sntp.h sntp_config.h SNTP configuration file Description 5.8.23.8.1 sntp.h SNTP Client Module Header Enumerations Name Description SNTP_RESULT Provides a list of possible results for the SNTP module. Functions Name Description TCPIP_SNTP_ConnectionInitiate Forces a connection to the NTP server TCPIP_SNTP_ConnectionParamSet Sets the current SNTP connection parameters TCPIP_SNTP_LastErrorGet Gets the last error code set in the NTP server TCPIP_SNTP_TimeStampGet Gets the last valid timestamp obtained from an NTP server TCPIP_SNTP_UTCSecondsGet Obtains the current time from the SNTP module. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SNTP TCP/IP Stack Library 5-3866 Structures Name Description SNTP_MODULE_CONFIG Placeholder for SNTP Module Configuration 5.8.23.8.2 sntp_config.h Network Time Protocol (SNTP) Configuration file This file contains the SNTP module configuration options Macros Name Description NTP_DEFAULT_CONNECTION_TYPE The default connection type to use: IPv4/IPv6 NTP_DEFAULT_IF for multi-homed hosts, the default SNTP interface NTP_EPOCH Reference Epoch to use. (default: 01-Jan-1970 00:00:00) NTP_FAST_QUERY_INTERVAL Defines how long to wait to retry an update after a failure, seconds. Updates may take up to 6 seconds to fail, so this 14 second delay is actually only an 8-second retry. NTP_MAX_RETRIES Number of retries to connect to the server NTP_MAX_STRATUM The maximum acceptable NTP stratum number Should be less than 16 (unsynchronized server) NTP_QUERY_INTERVAL Defines how frequently to resynchronize the date/time, seconds (default: 10 minutes) NTP_REPLY_TIMEOUT Defines how long to wait before assuming the query has failed, seconds NTP_SERVER These are normally available network time servers. The actual IP returned from the pool will vary every minute so as to spread the load around stratum 1 timeservers. For best accuracy and network overhead you should locate the pool server closest to your geography, but it will still work if you use the global pool.ntp.org address or choose the wrong one or ship your embedded device to another geography. NTP_SERVER_PORT Port for contacting NTP servers NTP_TIME_STAMP_TMO elapsed time that qualifies a time stamp as stale normally it should be correlated with NTP_QUERY_INTERVAL NTP_VERSION The default NTP version to use (3 or 4) 5.8.24 SSL TCP/IP Stack Library 5.8.24.1 Introduction Secure Sockets Layer (SSL) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the SSL TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3867 Description The SSL module adds encryption support to the TCP layer by implementing the SSLv3 protocol. This protocol is the standard for secure communications across the Internet, and prevents snooping or tampering of data as it travels across an untrusted network. This implementation of SSL supports the RSA asymmetric encryption protocol and the ARCFOUR symmetric encryption protocol. To comply with US Export Control restrictions, the encryption portion of the SSL module must be purchased separately from Microchip. The library of Data Encryption Routines (SW300052) is available for a nominal fee from microchipDirect. Newer versions of the TCP/IP Stack include modifications to the SSL module to enable an expanded range of RSA key lengths. This will allow the TCP/IP Stack to support a wider range of SSL client/servers. Because of these changes, you may need to manually modify your copy of RSA.c or obtain an updated copy from microchipDirect. The following table enumerates which cryptographic add-on is required for which stack version. 5.8.24.2 Release Notes MPLAB Harmony Version: v0.70b SSL TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.24.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.24.4 Using the Library This topic describes the basic architecture of the SSL TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: ssl.h 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3868 The interface to the SSL TCP/IP Stack library is defined in the "ssl.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the SSL TCP/IP Stack library should include "tcpip.h". Library File: The SSL TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.24.4.1 Abstraction Model This library provides the API of the SSL TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description SSL Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.24.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the SSL module. Library Interface Section Description Functions Routines for configuring SSL Data Types and Constants This section provides various definitions describing this API 5.8.24.4.3 How the Library Works 5.8.24.4.3.1 SSL Client Support An SSL client can be initiated by first opening a TCP connection, then calling TCPStartSSLSession to initiate the SSL handshake process. The handshake uses the public key from the certificate provided by the server. Key lengths up to 1024 bits are supported on all processors; key lengths up to 2048 bits are supported on PIC32 microcontrollers. The SSL_RSA_CLIENT_SIZE macro in SSLClientSize.h sets the maximum certificate key length that your client should process. #define SSL_RSA_CLIENT_SIZE (1024ul) // Size of Encryption Buffer (must be larger than key size) Once the handshake has started, call TCPSSLIsHandshaking ( see page 468) until it returns FALSE. This will indicate that the handshake has completed and all traffic is now secured using 128-bit ARCFOUR encryption. If the handshake fails for any reason, the TCP connection will automatically be terminated as required by the SSL protocol specification. For faster performance, the SSL module caches security parameters for the most recently made connections. This allows quick reconnections to the same node without the computational expense of another RSA handshake. By default, the two most recent connections are cached, but this can be modified in TCPIPConfig.h. SSL client support is already enabled for SMTP. When STACK_USE_SSL_CLIENT is defined, the SMTP module automatically adds a field to SMTPClient ( see page 304) called UseSSL. That field controls whether or not the SMTP client module will attempt to make an SSL connection before transmitting any data. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3869 Note that TCP sockets using SSL may required an increase in TX/RX buffer size to support SSL. You can adjust the size of your sockets using the TCP/IP Configuration Utility included with the stack. 5.8.24.4.3.2 SSL Server Support To initiate an SSL server, first open a TCP socket for listening using TCPOpen ( see page 542). Then call TCPAddSSLListener ( see page 468) to listen ( see page 175) for incoming SSL connections on an alternate port. This allows a single socket to share application-level resources and listen ( see page 175) for connections on two different ports. Connections occurring on the originally opened port will proceed unsecured, while connections on the SSL port will first complete an SSL handshake to secure the data. If you application will not accept ( see page 169) unsecured traffic, simply open a non-secured socket on a free port number, then verify that each incoming connection is secured (not on that port) by calling TCPIsSSL ( see page 469). SSL server support is automatically enabled for HTTP2 when STACK_USE_SSL_SERVER is defined. By default, the HTTP2 module will then listen ( see page 175) for unsecured traffic on port 80 and secured connections on port 443. This SSL server implementation supports key lengths up to 1024 bits on most PIC microcontrollers, and 2048 bits on PIC32 microcontrollers. The SSL_RSA_KEY_SIZE ( see page 471) macro in TCPIPConfig.h sets the server certificate key length. // Bits in SSL RSA key. This parameter is used for SSL sever // connections only. #define SSL_RSA_KEY_SIZE (512ul) Note that TCP sockets using SSL may required an increase in TX/RX buffer size to support SSL. You can adjust the size ofyour sockets using the TCP/IP Configuration Utility included with the stack. 5.8.24.4.3.3 SSL Limitations SSL was designed for desktop PCs with faster processors and significantly more resources than are available on an embedded platform. A few compromises must be made in order to use SSL in a less resource-intensive manner. The SSL client module does not perform any validation or verification of certificates. Doing so would require many root certificates to be stored locally for verification, which is not feasible for memory-limited parts. This does not compromise security once the connection has been established, but does not provide complete security against man-in-the-middle attacks. (This sort of attack is uncommon and would be difficult to execute.) Neither the SSL client nor the server can completely verify MACs before processing data. SSL records include a signature to verify that messages were not modified in transit. This Message Authentication ( see page 89) Code, or MAC, is inserted after at least every 16kB of traffic. (It usually is inserted much more frequently than that.) Without 16kB of RAM to buffer packets for each socket, incoming data must be handed to the application layer before the MAC can be completely verified. Invalid MACs will still cause the connection to terminate immediately, but by the time this is detected some bad data may have already reached the application. Since the ARCFOUR cipher in use is a stream cipher, it would be difficult to exploit this in any meaningful way. An attacker would not be able to control what data is actually modified or inserted, as doing so without knowledge of the key would yield garbage. However, it is important to understand that incoming data is not completely verified before being passed to the application. 5.8.24.4.4 Generating Server Certificates The SSL certificates used by the TCP/IP Stack's SSL module are stored in the CustomSSLCert.c source file. The following series of steps describe how to create the structures in CustomSSLCert.c using an SSL certificate. 1. Download and install the OpenSSL library. There are several third-party sites that offer SSL installers (e.g. http://www.slproweb.com/products/Win32OpenSSL.html). Note that some distributions may not include all commands specified by the OpenSSL documentation. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3870 2. Open a console and change directory to the OpenSSL/bin folder. 3. If you don't have a key and certificate, you can generate them first. The following example console commands will generate a a 512-bit key: 1. Generate the key: openssl genrsa -out 512bits.key 512 2. Generate the Certificate Signing Request (CSR). You will need to add additional information when prompted: openssl req -new -key 512bits.key -out 512bits.csr 3. Generate the X.509 certificate if self-signing (or send the CSR to a Certificate Authority for signing): openssl x509 -req -days 365 -in 512bits.csr -signkey 512bits.key -out 512bits.crt (note that if the -days option is not specified, the default expiration time is 30 days) 4. For additional documentation, refer to http://www.openssl.org/docs/apps/openssl.html. 4. Parse your key file using the command: openssl.exe asn1parse -in "[directory containing your key]\512bits.key" 5. You should see a screen like this: 6. If you are not using an ENCX24J600 family device, then the last 5 integers displayed here are the SSL_P, SSL_Q, SSL_dP, SSL_dQ, and SSL_qInv parameters, respectively. However, they are displayed here in big-endian format, and the Microchip cryptographic library implementation requires parameters in little-endian format, so you will have to enter the parameters into the C arrays in opposite order. For example, the INTEGER at offset 145: 145:d=1 h1=2 ;= 33 prim: INTEGER :D777566780029FCD610200B66D89507D 915E3E5BDB6FAB0233B5DFA2E4081DF7 will be swapped in the CustomSSLCert.c file: ROM BYTE SSL_P[] = { 0xF7 , 0x1D, 0x08, 0xE4, 0xA2, 0xDF, 0xB5, 0x33, 0x02, 0xAB, 0x6F, 0xDB, 0x5B, 0x3E, 0x5E, 0x91, 0x7D, 0x50, 0x89, 0x6D, 0xB6, 0x00, 0x02, 0x61, 0xCD, 0x9F, 0x02, 0x80, 0x67, 0x56, 0x77, 0xD7 }; 7. If you are using an ENCX24J600 family device, then the second and fourth integers displayed here are the SSL_N and SSL_D parameters, respectively. There is no need to do an endian format change for these parameters. For the example, the expected SSL_N and SSL_D values are shown in the figure below: 8. Parse your X.509 certificate using the command: openssl.exe asn1parse -in "[directory containing your cert]\512bits.crt" -out cert.bin 9. Open the cert.bin output file in a hex editor. For example, here is the default certificate information generated from 512bits.crt given in the stack: 10. This information must be copied verbatim into the SSL_CERT [] array. Note that this is binary data (not a large integer) so it does not get endian-swapped like the private key parameters. ROM BYTE SSL_CERT[524] = { 0x30, 0x82, 0x02, 0x08, 0x30, 0x82, 0x01, 0xb2, 0x02, 0x09, 0x00, 0xa5, 0x6a, 0xea, 0x1a, 0xa9, 0x52, 0x9d, 0x1e, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x05, 0x05, 0x00, 0x30, 0x81, 0x8a, 0x31, 0x0b, 0x30, 0x09, 0x06, 0x03, 0x55, 0x04, 0x06, 0x13, 0x02, 0x55, 0x53, 0x31, 0x10, 0x30, 0x0e, 0x06, 0x03, 0x55, 0x04, 0x08, 0x13, 0x07, 0x41, 0x72, 0x69, 0x7a, 0x6f, 0x6e, 0x61, 0x31, 0x11, 0x30, 0x0f, 0x06, 0x03, 0x55, 0x04, 0x07, 0x13, 0x08, 0x43, 0x68, 0x61, 0x6e, 0x64, 0x6c, 0x65, 0x72, 0x31, 0x23, 0x30, 0x21, 0x06, 0x03, 0x55, 0x04, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3871 0x0a, 0x13, 0x1a, 0x4d, 0x69, 0x63, 0x72, 0x6f, 0x63, 0x68, 0x69, 0x70, 0x20, 0x54, 0x65, 0x63, 0x68, 0x6e, 0x6f, 0x6c, 0x6f, 0x67, 0x79, 0x2c, 0x20, 0x49, 0x6e, 0x63, 0x2e, 0x31, 0x1d, 0x30, 0x1b, 0x06, 0x03, 0x55, 0x04, 0x0b, 0x13, 0x14, 0x53, 0x53, 0x4c, 0x20, 0x44, 0x65, 0x6d, 0x6f, 0x20, 0x43, 0x65, 0x72, 0x74, 0x69, 0x66, 0x69, 0x63, 0x61, 0x74, 0x65, 0x31, 0x12, 0x30, 0x10, 0x06, 0x03, 0x55, 0x04, 0x03, 0x13, 0x09, 0x6d, 0x63, 0x68, 0x70, 0x62, 0x6f, 0x61, 0x72, 0x64, 0x30, 0x1e, 0x17, 0x0d, 0x30, 0x37, 0x31, 0x30, 0x30, 0x39, 0x31, 0x38, 0x33, 0x37, 0x32, 0x37, 0x5a, 0x17, 0x0d, 0x31, 0x37, 0x31, 0x30, 0x30, 0x36, 0x31, 0x38, 0x33, 0x37, 0x32, 0x37, 0x5a, 0x30, 0x81, 0x8a, 0x31, 0x0b, 0x30, 0x09, 0x06, 0x03, 0x55, 0x04, 0x06, 0x13, 0x02, 0x55, 0x53, 0x31, 0x10, 0x30, 0x0e, 0x06, 0x03, 0x55, 0x04, 0x08, 0x13, 0x07, 0x41, 0x72, 0x69, 0x7a, 0x6f, 0x6e, 0x61, 0x31, 0x11, 0x30, 0x0f, 0x06, 0x03, 0x55, 0x04, 0x07, 0x13, 0x08, 0x43, 0x68, 0x61, 0x6e, 0x64, 0x6c, 0x65, 0x72, 0x31, 0x23, 0x30, 0x21, 0x06, 0x03, 0x55, 0x04, 0x0a, 0x13, 0x1a, 0x4d, 0x69, 0x63, 0x72, 0x6f, 0x63, 0x68, 0x69, 0x70, 0x20, 0x54, 0x65, 0x63, 0x68, 0x6e, 0x6f, 0x6c, 0x6f, 0x67, 0x79, 0x2c, 0x20, 0x49, 0x6e, 0x63, 0x2e, 0x31, 0x1d, 0x30, 0x1b, 0x06, 0x03, 0x55, 0x04, 0x0b, 0x13, 0x14, 0x53, 0x53, 0x4c, 0x20, 0x44, 0x65, 0x6d, 0x6f, 0x20, 0x43, 0x65, 0x72, 0x74, 0x69, 0x66, 0x69, 0x63, 0x61, 0x74, 0x65, 0x31, 0x12, 0x30, 0x10, 0x06, 0x03, 0x55, 0x04, 0x03, 0x13, 0x09, 0x6d, 0x63, 0x68, 0x70, 0x62, 0x6f, 0x61, 0x72, 0x64, 0x30, 0x5c, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00, 0x03, 0x4b, 0x00, 0x30, 0x48, 0x02, 0x41, 0x00, 0xaa, 0x96, 0xca, 0x97, 0xea, 0x27, 0xb0, 0xd7, 0xe9, 0x21, 0xd0, 0x40, 0xd4, 0x2c, 0x09, 0x5a, 0x2e, 0x3a, 0xe4, 0x12, 0x64, 0x2d, 0x4b, 0x1b, 0x92, 0xdf, 0x79, 0x68, 0x4e, 0x3c, 0x51, 0xf4, 0x43, 0x48, 0x0d, 0xf2, 0xc8, 0x50, 0x9b, 0x6e, 0xe5, 0xea, 0xfe, 0xef, 0xd9, 0x10, 0x41, 0x08, 0x14, 0xf9, 0x85, 0x49, 0xfc, 0x50, 0xd3, 0x57, 0x34, 0xdc, 0x3a, 0x0d, 0x79, 0xf8, 0xd3, 0x99, 0x02, 0x03, 0x01, 0x00, 0x01, 0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x05, 0x05, 0x00, 0x03, 0x41, 0x00, 0x18, 0x18, 0xfe, 0x8b, 0x2d, 0x0d, 0xf7, 0x0d, 0x65, 0x9d, 0x29, 0xec, 0xb3, 0x51, 0x6e, 0x3b, 0x93, 0xbb, 0x40, 0x1a, 0x0b, 0x34, 0x07, 0x63, 0x5e, 0x6a, 0x1c, 0x74, 0x59, 0xd4, 0x54, 0xd2, 0x1b, 0xf3, 0x31, 0xb7, 0x57, 0x4b, 0xa5, 0xe6, 0xe2, 0x35, 0xf7, 0xb3, 0x6a, 0x15, 0x6e, 0x3c, 0x93, 0x85, 0xb2, 0xca, 0xf5, 0x35, 0x00, 0xf4, 0x49, 0xe7, 0x00, 0x8a, 0x00, 0xd8, 0xe8, 0xcf }; 11. Update the SSL_CERT_LEN variable to contain the correct value. 5.8.24.5 Configuring the Library Macros Name Description SSL_MAX_BUFFERS Max # of SSL buffers (2 per socket) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3872 SSL_MAX_CONNECTIONS Maximum number of simultaneous connections via SSL SSL_MAX_HASHES Max # of SSL hashes (2 per socket, plus 1 to avoid deadlock) SSL_MAX_SESSIONS Max number of cached SSL sessions SSL_MIN_SESSION_LIFETIME Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time (seconds) has elapsed SSL_MULTIPLE_INTERFACES SSL on all interfaces in a multi-homed host set to 0 to work only on one interface SSL_RSA_CLIENT_SIZE Size of encryption buffer, must be at least as big as the key size SSL_RSA_KEY_SIZE Bits in SSL RSA key. This parameter is used for SSL sever connections only. The only valid value is 512 bits (768 and 1024 bits do not work at this time). Note, however, that SSL client operations do currently work up to 1024 bit RSA key length. SSL_RSA_LIFETIME_EXTENSION Lifetime extension for RSA operations Sessions lifetime is extended by this amount (seconds) when an RSA calculation is made SSL_VERSION Moved from MicrochipIncludeTCPIP StackSSL.h SSL_VERSION_HI SSL version number (high byte) SSL_VERSION_LO SSL version number (low byte) Description The configuration of the SSL TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the SSL TCP/IP Stack Library. Based on the selections made, the SSL TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the TCP/IP Stack SSL Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.24.5.1 SSL_MAX_BUFFERS Macro C #define SSL_MAX_BUFFERS (4) Description Max # of SSL buffers (2 per socket) 5.8.24.5.2 SSL_MAX_CONNECTIONS Macro C #define SSL_MAX_CONNECTIONS (2) Description Maximum number of simultaneous connections via SSL 5.8.24.5.3 SSL_MAX_HASHES Macro C #define SSL_MAX_HASHES (5) Description Max # of SSL hashes (2 per socket, plus 1 to avoid deadlock) 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3873 5.8.24.5.4 SSL_MAX_SESSIONS Macro C #define SSL_MAX_SESSIONS (2) Description Max number of cached SSL sessions 5.8.24.5.5 SSL_MIN_SESSION_LIFETIME Macro C #define SSL_MIN_SESSION_LIFETIME (1ul) Description Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time (seconds) has elapsed 5.8.24.5.6 SSL_MULTIPLE_INTERFACES Macro C #define SSL_MULTIPLE_INTERFACES 1 Description SSL on all interfaces in a multi-homed host set to 0 to work only on one interface 5.8.24.5.7 SSL_RSA_CLIENT_SIZE Macro C #define SSL_RSA_CLIENT_SIZE (1024ul) Description Size of encryption buffer, must be at least as big as the key size 5.8.24.5.8 SSL_RSA_KEY_SIZE Macro C #define SSL_RSA_KEY_SIZE (1024ul) Description Bits in SSL RSA key. This parameter is used for SSL sever connections only. The only valid value is 512 bits (768 and 1024 bits do not work at this time). Note, however, that SSL client operations do currently work up to 1024 bit RSA key length. 5.8.24.5.9 SSL_RSA_LIFETIME_EXTENSION Macro C #define SSL_RSA_LIFETIME_EXTENSION (8ul) Description Lifetime extension for RSA operations Sessions lifetime is extended by this amount (seconds) when an RSA calculation is made 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3874 5.8.24.5.10 SSL_VERSION Macro C #define SSL_VERSION (0x0300u) // Moved from Microchip\Include\TCPIP Stack\SSL.h Description Moved from MicrochipIncludeTCPIP StackSSL.h 5.8.24.5.11 SSL_VERSION_HI Macro C #define SSL_VERSION_HI (0x03u) Description SSL version number (high byte) 5.8.24.5.12 SSL_VERSION_LO Macro C #define SSL_VERSION_LO (0x00u) Description SSL version number (low byte) 5.8.24.6 Building the Library This section list the files that are available in the \src of the SSL driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.24.7 Library Interface Data Types and Constants Name Description SSL_MODULE_CONFIG SSL layer configuration/initialization Functions Name Description TCPIP_TCP_SocketIsSecuredBySSL Determines if a TCP connection is secured with SSL. TCPIP_TCPSSL_ClientBegin Begins an SSL client session. TCPIP_TCPSSL_ClientStart Begins an SSL client session. TCPIP_TCPSSL_HandshakeClear Clears the SSL handshake flag. TCPIP_TCPSSL_ListenerAdd Listens for SSL connection on a specific port. TCPIP_TCPSSL_ServerStart Begins an SSL server session. TCPIP_TCPSSL_StillHandshaking Determines if an SSL session is still handshaking. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3875 Description This section describes the Application Programming Interface (API) functions of the SSL TCP/IP Stack. Refer to each section for a detailed description. 5.8.24.7.1 Functions 5.8.24.7.1.1 TCPIP_TCP_SocketIsSecuredBySSL Function C bool TCPIP_TCP_SocketIsSecuredBySSL( TCP_SOCKET hTCP ); Description Call this function to determine whether or not a TCP connection is secured with SSL. Preconditions TCP is initialized and hTCP is connected. Parameters Parameters Description hTCP TCP connection to check Return Values Return Values Description true Connection is secured via SSL false Connection is not secured 5.8.24.7.1.2 TCPIP_TCPSSL_ClientBegin Function C bool TCPIP_TCPSSL_ClientBegin( TCP_SOCKET hTCP, uint8_t* host, void * buffer, uint8_t suppDataType ); Description This function escalates the current connection to an SSL secured connection by initiating an SSL client handshake. Preconditions TCP is initialized and hTCP is already connected. Parameters Parameters Description hTCP TCP connection to secure host Expected host name on certificate (currently ignored) buffer Buffer for supplementary data return suppDataType Type of supplementary data to copy 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3876 Return Values Return Values Description true an SSL connection was initiated false Insufficient SSL resources (stubs) were available Remarks The host parameter is currently ignored and is not validated. 5.8.24.7.1.3 TCPIP_TCPSSL_ClientStart Function C bool TCPIP_TCPSSL_ClientStart( TCP_SOCKET hTCP, uint8_t* host ); Description This function escalates the current connection to an SSL secured connection by initiating an SSL client handshake. Preconditions TCP is initialized and hTCP is already connected. Parameters Parameters Description hTCP TCP connection to secure host Expected host name on certificate (currently ignored) Return Values Return Values Description true an SSL connection was initiated false Insufficient SSL resources (stubs) were available Remarks The host parameter is currently ignored and is not validated. 5.8.24.7.1.4 TCPIP_TCPSSL_HandshakeClear Function C void TCPIP_TCPSSL_HandshakeClear( TCP_SOCKET hTCP ); Description This function clears the flag indicating that an SSL handshake is complete. Preconditions TCP is initialized and hTCP is connected. Parameters Parameters Description hTCP TCP connection to set 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3877 Returns None Remarks This function should never be called by an application. It is used only by the SSL module itself. 5.8.24.7.1.5 TCPIP_TCPSSL_ListenerAdd Function C bool TCPIP_TCPSSL_ListenerAdd( TCP_SOCKET hTCP, uint16_t port ); Description This function adds an additional listening port to a TCP connection. Connections made on this alternate port will be secured via SSL. Preconditions TCP is initialized and hTCP is listening. Parameters Parameters Description hTCP TCP connection to secure port SSL port to listen on Return Values Return Values Description true SSL port was added. false The socket was not a listening socket. 5.8.24.7.1.6 TCPIP_TCPSSL_ServerStart Function C bool TCPIP_TCPSSL_ServerStart( TCP_SOCKET hTCP ); Description This function sets up an SSL server session when a new connection is established on an SSL port. Preconditions TCP is initialized and hTCP is already connected. Parameters Parameters Description hTCP TCP connection to secure Return Values Return Values Description true an SSL connection was initiated false Insufficient SSL resources (stubs) were available 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3878 5.8.24.7.1.7 TCPIP_TCPSSL_StillHandshaking Function C bool TCPIP_TCPSSL_StillHandshaking( TCP_SOCKET hTCP ); Description Call this function after calling TCPIP_TCPSSL_ClientStart until false is returned. Then your application may continue with its normal data transfer (which is now secured). Preconditions TCP is initialized and hTCP is connected. Parameters Parameters Description hTCP TCP connection to check Return Values Return Values Description true SSL handshake is still progressing false SSL handshake has completed 5.8.24.7.2 Data Types and Constants 5.8.24.7.2.1 SSL_MODULE_CONFIG Structure C typedef struct { } SSL_MODULE_CONFIG; Description SSL layer configuration/initialization 5.8.24.8 Files Files Name Description ssl.h ssl_config.h SSL configuration file Description 5.8.24.8.1 ssl.h SSLv3 Module Headers 5.8 TCP/IP Stack Library Help MPLAB Harmony Help SSL TCP/IP Stack Library 5-3879 Functions Name Description TCPIP_TCP_SocketIsSecuredBySSL Determines if a TCP connection is secured with SSL. TCPIP_TCPSSL_ClientBegin Begins an SSL client session. TCPIP_TCPSSL_ClientStart Begins an SSL client session. TCPIP_TCPSSL_HandshakeClear Clears the SSL handshake flag. TCPIP_TCPSSL_ListenerAdd Listens for SSL connection on a specific port. TCPIP_TCPSSL_ServerStart Begins an SSL server session. TCPIP_TCPSSL_StillHandshaking Determines if an SSL session is still handshaking. Structures Name Description SSL_MODULE_CONFIG SSL layer configuration/initialization 5.8.24.8.2 ssl_config.h Secure Sockets Layer (SSL) Configuration file This file contains the SSL module configuration options Macros Name Description SSL_MAX_BUFFERS Max # of SSL buffers (2 per socket) SSL_MAX_CONNECTIONS Maximum number of simultaneous connections via SSL SSL_MAX_HASHES Max # of SSL hashes (2 per socket, plus 1 to avoid deadlock) SSL_MAX_SESSIONS Max number of cached SSL sessions SSL_MIN_SESSION_LIFETIME Minimum lifetime for SSL Sessions Sessions cannot be reallocated until this much time (seconds) has elapsed SSL_MULTIPLE_INTERFACES SSL on all interfaces in a multi-homed host set to 0 to work only on one interface SSL_RSA_CLIENT_SIZE Size of encryption buffer, must be at least as big as the key size SSL_RSA_KEY_SIZE Bits in SSL RSA key. This parameter is used for SSL sever connections only. The only valid value is 512 bits (768 and 1024 bits do not work at this time). Note, however, that SSL client operations do currently work up to 1024 bit RSA key length. SSL_RSA_LIFETIME_EXTENSION Lifetime extension for RSA operations Sessions lifetime is extended by this amount (seconds) when an RSA calculation is made SSL_VERSION Moved from MicrochipIncludeTCPIP StackSSL.h SSL_VERSION_HI SSL version number (high byte) SSL_VERSION_LO SSL version number (low byte) 5.8.25 TCP TCP/IP Stack Library 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3880 5.8.25.1 Introduction Transmission Control Protocol (TCP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the TCP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description TCP is a standard transport layer protocol described in RFC 793. It provides reliable stream-based connections over unreliable networks, and forms the foundation for HTTP, SMTP, and many other protocol standards. 5.8.25.2 Release Notes MPLAB Harmony Version: v0.70b TCP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.25.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.25.4 Using the Library This topic describes the basic architecture of the TCP TCP/IP Stack Library and provides information and examples on how to use it. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3881 Interface Header File: tcp.h The interface to the TCP TCP/IP Stack library is defined in the "tcp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the TCP TCP/IP Stack library should include "tcpip.h". Library File: The TCP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.25.4.1 Abstraction Model This library provides the API of the TCP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description TCP Software Abstraction Block Diagram This module provides software abstraction of the TCP module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. Typical TCP Implementation 5.8.25.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the TCP module. Library Interface Section Description Socket Management Functions Routines for Managing TCP Sockets Transmit Data Transfer Functions Routines for Managing Outgoing Data Transmissions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3882 Receive Data Transfer Functions Routines for Managing Incoming Data Transmissions Data Types and Constants This section provides various definitions describing This API 5.8.25.4.3 How the Library Works Connections made over TCP guarantee data transfer at the expense of throughput. Connections are made through a three-way handshake process, ensuring a one-to-one connection. Remote nodes advertise how much data they are ready to receive, and all data transmitted must be acknowledged. If a remote node fails to acknowledge the receipt of data, it is automatically retransmitted. This ensures that network errors such as lost, corrupted, or out-of-order packets are automatically corrected. To accomplish this, TCP must operate in a buffer. Once the transmit buffer is full, no more data can be sent until the remote node has acknowledged receipt. For the Microchip TCP/IP Stack, the application must return to the main stack loop in order for this to happen. Likewise, the remote node cannot transmit more data until the local device has acknowledged receipt and that space is available in the buffer. When a local application needs to read more data, it must return to the main stack loop and wait for a new packet to arrive. 5.8.25.4.3.1 Core Functionality The TCP flow diagram below provides an overview for the use of the TCP module: Sockets are opened using TCPOpen . This function can either open a listening socket to wait for client connections, or can make a client connection to the remote node. The remote node can be specified by a host name string to be resolved in DNS, an IP address, or a NODE_INFO struct containing previously resolved IP and MAC address information. Once connected, applications can read and write data. On each entry, the application must verify that the socket is still connected. For most applications a call to TCPIP_TCP_IsConnected will be sufficient, but TCPIP_TCP_WasReset may also be used for listening sockets that may turn over quickly. To write data, call TCPIP_TCP_PutIsReady to check how much space is available. Then, call any of the TCPIP_TCP_Put family of functions to write data as space is vailable. Once complete, call TCPIP_TCP_Flush to transmit data immediately. Alternately, return to the main stack loop. Data will be transmitted when either a) half of the transmit buffer becomes full or b) a delay time has passed. To read data, call TCPIP_TCP_GetIsReady to determine how many bytes are ready to be retrieved. Then use the TCPIP_TCP_Get family of functions to read data from the socket, and/or the TCPIP_TCP_Find family of functions to locate data in the buffer. When no more data remains, return to the main stack loop to wait for more data to arrive. If the application needs to close the connection, call TCPIP_TCP_Disconnect, then return to the main stack loop and wait for the 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3883 remote node to acknowledge the disconnection. Client sockets will return to the idle state, while listening sockets will wait for a new connection. For more information, refer to the GenericTCPClient or GenericTCPServer examples, or read the associated RFC. 5.8.25.5 Configuring the Library Macros Name Description LOCAL_TCP_PORT_END_NUMBER Last port number for randomized local port number selection LOCAL_TCP_PORT_START_NUMBER First port number for randomized local port number selection Use the dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range TCP_AUTO_TRANSMIT_TIMEOUT_VAL Timeout before automatically transmitting unflushed data, ms; Default 40 ms TCP_CLOSE_WAIT_TIMEOUT Timeout for the CLOSE_WAIT state, ms TCP_DELAYED_ACK_TIMEOUT Timeout for delayed-acknowledgement algorithm, ms TCP_FIN_WAIT_2_TIMEOUT Timeout for FIN WAIT 2 state, ms TCP_KEEP_ALIVE_TIMEOUT Timeout for keep-alive messages when no traffic is sent, ms TCP_MAX_RETRIES Maximum number of retransmission attempts TCP_MAX_SEG_SIZE_RX_LOCAL TCP Maximum Segment Size for RX (MSS). This value is advertised during TCP connection establishment and the remote node should obey it. The value has to be set in such a way to avoid IP layer fragmentation from causing packet loss. However, raising its value can enhance performance at the (small) risk of introducing incompatibility with certain special remote nodes (ex: ones connected via a slow dial up modem). On Ethernet networks the standard value is 1460. On dial-up links, etc. the default values should be 536. Adjust these values according to your network. The stack will use the local... more TCP_MAX_SEG_SIZE_RX_NON_LOCAL Max segment size, non local TCP_MAX_SEG_SIZE_TX TCP Maximum Segment Size for TX. The TX maximum segment size is actually governed by the remote node's MSS option advertised during connection establishment. However, if the remote node specifies an unhandlably large MSS (ex: > Ethernet MTU), this define sets a hard limit so that we don't cause any TX buffer overflows. If the remote node does not advirtise a MSS option, all TX segments are fixed at 536 bytes maximum. TCP_MAX_SOCKETS The maximum number of sockets to create in the stack. When defining TCP_MAX_SOCKETS take into account the number of interfaces the stack is supporting TCP_MAX_SYN_RETRIES Smaller than all other retries to reduce SYN flood DoS duration TCP_MAX_UNACKED_KEEP_ALIVES Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection TCP_SOCKET_DEFAULT_RX_SIZE default socket Rx buffer size TCP_SOCKET_DEFAULT_TX_SIZE default socket Tx buffer size TCP_START_TIMEOUT_VAL TCP Timeout and retransmit numbers All timeouts in milliseconds Timeout to retransmit unacked data, ms TCP_TASK_TICK_RATE 5 ms default rate TCP_WINDOW_UPDATE_TIMEOUT_VAL Timeout before automatically transmitting a window update due to a TCPIP_TCP_Get() or TCPIP_TCP_ArrayGet() function call, ms 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3884 Description The configuration of the TCP/IP TCP is based on the file sys_config.h This header file contains the configuration selection for the TCP/IP TCP. Based on the selections made, the TCP/IP TCP will support or not support selected features. These configuration settings will apply to all instances of the TCP/IP TCP. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.25.5.1 LOCAL_TCP_PORT_END_NUMBER Macro C #define LOCAL_TCP_PORT_END_NUMBER (65535) Description Last port number for randomized local port number selection 5.8.25.5.2 LOCAL_TCP_PORT_START_NUMBER Macro C #define LOCAL_TCP_PORT_START_NUMBER (49152) Description First port number for randomized local port number selection Use the dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range 5.8.25.5.3 TCP_AUTO_TRANSMIT_TIMEOUT_VAL Macro C #define TCP_AUTO_TRANSMIT_TIMEOUT_VAL (40ul) Description Timeout before automatically transmitting unflushed data, ms; Default 40 ms 5.8.25.5.4 TCP_CLOSE_WAIT_TIMEOUT Macro C #define TCP_CLOSE_WAIT_TIMEOUT (200ul) Description Timeout for the CLOSE_WAIT state, ms 5.8.25.5.5 TCP_DELAYED_ACK_TIMEOUT Macro C #define TCP_DELAYED_ACK_TIMEOUT (100ul) Description Timeout for delayed-acknowledgement algorithm, ms 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3885 5.8.25.5.6 TCP_FIN_WAIT_2_TIMEOUT Macro C #define TCP_FIN_WAIT_2_TIMEOUT (5000ul) Description Timeout for FIN WAIT 2 state, ms 5.8.25.5.7 TCP_KEEP_ALIVE_TIMEOUT Macro C #define TCP_KEEP_ALIVE_TIMEOUT (10000ul) Description Timeout for keep-alive messages when no traffic is sent, ms 5.8.25.5.8 TCP_MAX_RETRIES Macro C #define TCP_MAX_RETRIES (5u) Description Maximum number of retransmission attempts 5.8.25.5.9 TCP_MAX_SEG_SIZE_RX_LOCAL Macro C #define TCP_MAX_SEG_SIZE_RX_LOCAL (1460) Description TCP Maximum Segment Size for RX (MSS). This value is advertised during TCP connection establishment and the remote node should obey it. The value has to be set in such a way to avoid IP layer fragmentation from causing packet loss. However, raising its value can enhance performance at the (small) risk of introducing incompatibility with certain special remote nodes (ex: ones connected via a slow dial up modem). On Ethernet networks the standard value is 1460. On dial-up links, etc. the default values should be 536. Adjust these values according to your network. The stack will use the local value for local destination networks and the default value for nonlocal networks. 5.8.25.5.10 TCP_MAX_SEG_SIZE_RX_NON_LOCAL Macro C #define TCP_MAX_SEG_SIZE_RX_NON_LOCAL (536) // Max segment size, non local Description Max segment size, non local 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3886 5.8.25.5.11 TCP_MAX_SEG_SIZE_TX Macro C #define TCP_MAX_SEG_SIZE_TX (1460u) Description TCP Maximum Segment Size for TX. The TX maximum segment size is actually governed by the remote node's MSS option advertised during connection establishment. However, if the remote node specifies an unhandlably large MSS (ex: > Ethernet MTU), this define sets a hard limit so that we don't cause any TX buffer overflows. If the remote node does not advirtise a MSS option, all TX segments are fixed at 536 bytes maximum. 5.8.25.5.12 TCP_MAX_SOCKETS Macro C #define TCP_MAX_SOCKETS (10) Description The maximum number of sockets to create in the stack. When defining TCP_MAX_SOCKETS take into account the number of interfaces the stack is supporting 5.8.25.5.13 TCP_MAX_SYN_RETRIES Macro C #define TCP_MAX_SYN_RETRIES (2u) Description Smaller than all other retries to reduce SYN flood DoS duration 5.8.25.5.14 TCP_MAX_UNACKED_KEEP_ALIVES Macro C #define TCP_MAX_UNACKED_KEEP_ALIVES (6u) Description Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection 5.8.25.5.15 TCP_SOCKET_DEFAULT_RX_SIZE Macro C #define TCP_SOCKET_DEFAULT_RX_SIZE 512 Description default socket Rx buffer size 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3887 5.8.25.5.16 TCP_SOCKET_DEFAULT_TX_SIZE Macro C #define TCP_SOCKET_DEFAULT_TX_SIZE 512 Description default socket Tx buffer size 5.8.25.5.17 TCP_START_TIMEOUT_VAL Macro C #define TCP_START_TIMEOUT_VAL (1000ul) Description TCP Timeout and retransmit numbers All timeouts in milliseconds Timeout to retransmit unacked data, ms 5.8.25.5.18 TCP_TASK_TICK_RATE Macro C #define TCP_TASK_TICK_RATE (5) // 5 ms default rate Description 5 ms default rate 5.8.25.5.19 TCP_WINDOW_UPDATE_TIMEOUT_VAL Macro C #define TCP_WINDOW_UPDATE_TIMEOUT_VAL (200ul) Description Timeout before automatically transmitting a window update due to a TCPIP_TCP_Get() or TCPIP_TCP_ArrayGet() function call, ms 5.8.25.6 Building the Library This section list the files that are available in the \src of the TCP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • tcp.c 5.8.25.7 Library Interface Data Types and Constants Name Description TCPIP_TCP_FifoRxFullGet TCP Get Rx First In, First Out Full TCPIP_TCP_FifoTxFreeGet TCP Get TX First In, First Out Free TCP_ADJUST_FLAGS TCP Adjust Falgs 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3888 TCP_MODULE_CONFIG TCP layer configuration/initialization TCP_OPTION_LINGER_DATA Linger options TCP_PORT TCP Port TCP_SOCKET TCP Socket TCP_SOCKET_INFO TCP Socket Information TCP_SOCKET_OPTION TCP Socket Option INVALID_SOCKET The socket is invalid or could not be opened Receive Data Transfer Functions Name Description TCPIP_TCP_ArrayFind Searches for a string in the TCP RX buffer. TCPIP_TCP_ArrayGet Reads an array of data bytes from a TCP socket's receive FIFO. The data is removed from the FIFO in the process. TCPIP_TCP_ArrayPeek Reads a specified number of data bytes from the TCP RX FIFO without removing them from the buffer. TCPIP_TCP_Discard Discards any pending data in the TCP RX FIFO. TCPIP_TCP_FifoSizeAdjust Adjusts the relative sizes of the RX and TX buffers. TCPIP_TCP_Find Searches for a byte in the TCP RX buffer. TCPIP_TCP_Get Retrieves a single byte to a TCP socket. TCPIP_TCP_GetIsReady Determines how many bytes can be read from the TCP RX buffer. TCPIP_TCP_Peek Peaks at one byte in the TCP RX FIFO without removing it from the buffer. TCPIP_TCP_FifoRxFreeGet Determines how many bytes are free in the RX FIFO. Socket Management Functions Name Description TCPIP_TCP_Bind Bind a socket to a local address This function is meant for unconnected server and client sockets. It is similar to TCPIP_TCP_SocketNetSet() that assigns a specific source interface for a socket. If localPort is 0 the stack will assign a unique local port TCPIP_TCP_ClientOpen Opens a TCP socket as a client. TCPIP_TCP_Close Disconnects an open socket and destroys the socket handle, releasing the associated resources. TCPIP_TCP_Connect Connects a client socket. TCPIP_TCP_Disconnect Disconnects an open socket. TCPIP_TCP_IsConnected Determines if a socket has an established connection. TCPIP_TCP_OptionsGet Allows getting the options for a socket like: current Rx/Tx buffer size, etc TCPIP_TCP_OptionsSet Allows setting options to a socket like adjust Rx/Tx buffer size, etc TCPIP_TCP_RemoteBind Bind a socket to a remote address This function is meant for unconnected server and client sockets. TCPIP_TCP_ServerOpen Opens a TCP socket as a server. TCPIP_TCP_SocketInfoGet Obtains information about a currently open socket. TCPIP_TCP_SocketNetGet Gets the MAC interface of an TCP socket TCPIP_TCP_WasReset Self-clearing semaphore inidicating socket reset. TCPIP_TCP_Abort Aborts a connection. TCPIP_TCP_SocketNetSet Sets the interface for an TCP socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3889 Transmit Data Transfer Functions Name Description TCPIP_TCP_ArrayPut Writes an array from RAM to a TCP socket. TCPIP_TCP_FifoTxFullGet Determines how many bytes are pending in the TCP TX FIFO. TCPIP_TCP_Flush Immediately transmits all pending TX data. TCPIP_TCP_Put Writes a single byte to a TCP socket. TCPIP_TCP_PutIsReady Determines how much free space is available in the TCP TX buffer. TCPIP_TCP_StringPut Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket. Description This section describes the Application Programming Interface (API) functions of the TCP TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.25.7.1 Socket Management Functions 5.8.25.7.1.1 TCPIP_TCP_Bind Function C bool TCPIP_TCP_Bind( TCP_SOCKET hTCP, IP_ADDRESS_TYPE addType, TCP_PORT localPort, IP_MULTI_ADDRESS* localAddress ); Description Sockets don't need specific binding, it is done automatically by the stack However, specific binding can be requested using these functions. Works for both client and server sockets. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP Socket to bind addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. localPort Local port to use If 0, the stack will assign a unique local port localAddress The local address to bind to. Could be NULL if the local address does not need to be changed Returns True of success false otherwise Remarks The call should fail if the socket is already connected (both server and client sockets). However this is not currently implemented. It is the user's responsibility to call this function only for sockets that are not connected. Changing the socket parameters while the socket is connected will result in connection loss/unpredictable behavior. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3890 5.8.25.7.1.2 TCPIP_TCP_ClientOpen Function C TCP_SOCKET TCPIP_TCP_ClientOpen( IP_ADDRESS_TYPE addType, TCP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress ); Description Provides a unified method for opening TCP client sockets. Sockets are dynamically allocated at stack initialization, and can be claimed with this function and freed using TCPIP_TCP_Abort or TCPIP_TCP_Close. Preconditions TCP is initialized. Parameters Parameters Description IP_ADDRESS_TYPE addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. TCP_PORT remotePort TCP port to connect to. The local port for client sockets will be automatically picked by the TCP module. IP_MULTI_ADDRESS* remoteAddress The remote address to be used. If 0 then the address is unspecified Returns INVALID_SOCKET - No sockets of the specified type were available to be opened. Otherwise - A TCP_SOCKET handle. Save this handle and use it when calling all other TCP APIs. Remarks IP_ADDRESS_TYPE_ANY is not supported (not a valid type for client open)! If the remoteAddress != 0 (and the address pointed by remoteAddress != 0) then the socket will immediately initiate a connection to the remote host If the remoteAddress is unspecified, then no connection is initiated. Client socket parameters can be se using TCPIP_TCP_Bind(), TCPIP_TCP_RemoteBind(), etc. calls and then connection initiated by calling TCPIP_TCP_Connect(). 5.8.25.7.1.3 TCPIP_TCP_Close Function C void TCPIP_TCP_Close( TCP_SOCKET hTCP ); Description 1. If the graceful option is set for the socket (default): • a TCPIP_TCP_Disconnect will be tried. If the linger option is set (default) the TCPIP_TCP_Disconnect will try to send any queued TX data before issuing FIN. If the FIN send operation fails or the socket is not connected the abort is generated. 2. If the graceful option is not set, or the previous step could not send the FIN: A TCPAbort() is called, sending a RST to the remote node. Communication is closed, the socket is no longer valid and the associated resources are freed. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3891 Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP Handle to the socket to disconnect and close. Returns None 5.8.25.7.1.4 TCPIP_TCP_Connect Function C bool TCPIP_TCP_Connect( TCP_SOCKET hTCP ); Description This function will try to initiate a connection on a client socket that's not connected yet. The client socket should have been created with a call to TCPIP_TCP_ClientOpen having the remoteAddress set to 0; Preconditions TCP socket should have been opened with TCPIP_TCP_ClientOpen() with an unspecified address. hTCP - valid socket Parameters Parameters Description hTCP Handle to the client socket to connect. Returns true is the call succeeded false otherwise Remarks the call will fail if the client socket has no remote host specified. Use TCPIP_TCP_RemoteBind() to specify a remote host address for the client socket. 5.8.25.7.1.5 TCPIP_TCP_Disconnect Function C bool TCPIP_TCP_Disconnect( TCP_SOCKET hTCP ); Description This function closes the TX side of a connection by sending a FIN (if currently connected) to the remote node of the connection. If the socket has the linger option set (default), the queued TX data transmission will be attempted before sending the FIN. If the linger option is off, the queued TX data will be discarded. Please note that this call may fail in which case it can be re-issued. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3892 Parameters Parameters Description hTCP Handle of the socket to disconnect. Returns true if the call succeeded false otherwise; that means that the notification could not be sent to the remote host. the call can be re-issued at a later time if desired Remarks If the socket is using SSL, a CLOSE_NOTIFY record will be transmitted first to allow the SSL session to be resumed at a later time. 5.8.25.7.1.6 TCPIP_TCP_IsConnected Function C bool TCPIP_TCP_IsConnected( TCP_SOCKET hTCP ); Description This function determines if a socket has an established connection to a remote node. Call this function after calling TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen() to determine when the connection is set up and ready for use. This function was historically used to check for disconnections, but TCPIP_TCP_WasReset is now a more appropriate solution. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP The socket to check. Return Values Return Values Description true The socket has an established connection to a remote node. false The socket is not currently connected. Remarks A socket is said to be connected only if it is in the TCP_ESTABLISHED state. Sockets in the process of opening or closing will return false. 5.8.25.7.1.7 TCPIP_TCP_OptionsGet Function C bool TCPIP_TCP_OptionsGet( TCP_SOCKET hTCP, TCP_SOCKET_OPTION option, void* optParam ); Description Various options can be get at the socket level. This function provides compatibility with BSD implementations. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3893 Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP socket to get options for option specific option to get optParam pointer to an area that will receive the option value; this is option dependent the size of the area has to be large enough to accomodate the specific option TCP_OPTION_LINGER -- pointer to a TCP_OPTION_LINGER_DATA structure TCP_OPTION_KEEPPALIVE -- not supported yet TCP_OPTION_RX_BUFF -- size of the new RX buffer TCP_OPTION_TX_BUFF -- size of the new TX buffer TCP_OPTION_RX_TMO -- not supported yet TCP_OPTION_TX_TMO -- not supported yet TCP_OPTION_NODELAY -- pointer to boolean to return current NO DELAY status TCP_OPTION_EXCLUSIVE_ADDRESS -- not supported yet Returns true if success false otherwise 5.8.25.7.1.8 TCPIP_TCP_OptionsSet Function C bool TCPIP_TCP_OptionsSet( TCP_SOCKET hTCP, TCP_SOCKET_OPTION option, void* optParam ); Description Various options can be set at the socket level. This function provides compatibility with BSD implementations. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP socket to set options for option specific option to be set optParam the option value; this is option dependent TCP_OPTION_LINGER -- pointer to a TCP_OPTION_LINGER_DATA structure TCP_OPTION_KEEPPALIVE -- not supported yet TCP_OPTION_RX_BUFF -- size of the new RX buffer TCP_OPTION_TX_BUFF -- size of the new TX buffer TCP_OPTION_RX_TMO -- not supported yet TCP_OPTION_TX_TMO -- not supported yet TCP_OPTION_NODELAY -- boolean to enable/disable the NO DELAY functionality TCP_OPTION_EXCLUSIVE_ADDRESS -- not supported yet Returns true if success false otherwise 5.8.25.7.1.9 TCPIP_TCP_RemoteBind Function C bool TCPIP_TCP_RemoteBind( TCP_SOCKET hTCP, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3894 IP_ADDRESS_TYPE addType, TCP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress ); Description Sockets don't need specific remote binding, they should accept connections on any incoming interface. Thus the binding is done automatically by the stack. However, specific remote binding can be requested using these functions. For a server socket it can be used to restrict accepting connections from a specific remote host. For a client socket it will just change the default binding done when the socket was opened. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP Socket to bind addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. remotePort remote port to use Could be 0 if the remote port does not need to be changed remoteAddress The remote address to bind to. Could be NULL if the remote address does not need to be changed Returns True of success false otherwise Remarks The socket remote port is changed only if a non-zero remotePort value is passed. The socket remote host address is changed only if a non-zero remoteAddress value is passed. The call should fail if the socket is already connected (both server and client sockets). However this is not currently implemented. It is the user's responsibility to call this function only for sockets that are not connected. Changing the socket parameters while the socket is connected will result in connection loss/unpredictable behavior. 5.8.25.7.1.10 TCPIP_TCP_ServerOpen Function C TCP_SOCKET TCPIP_TCP_ServerOpen( IP_ADDRESS_TYPE addType, TCP_PORT localPort, IP_MULTI_ADDRESS* localAddress ); Description Provides a unified method for opening TCP server sockets. Sockets are statically/dynamically allocated on boot, and can be claimed with this function and freed using TCPIP_TCP_Close. Preconditions TCP is initialized. Parameters Parameters Description IP_ADDRESS_TYPE addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. TCP_PORT localPort TCP port to listen on for connections. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3895 IP_MULTI_ADDRESS* localAddress Local address to use. Returns INVALID_SOCKET - No sockets of the specified type were available to be opened. Otherwise - A TCP_SOCKET handle. Save this handle and use it when calling all other TCP APIs. 5.8.25.7.1.11 TCPIP_TCP_SocketInfoGet Function C bool TCPIP_TCP_SocketInfoGet( TCP_SOCKET hTCP, TCP_SOCKET_INFO* pInfo ); Description Fills the provided TCP_SOCKET_INFO structure associated with this socket. This contains the NODE_INFO structure with IP and MAC address (or gateway MAC) and the remote port. Preconditions TCP is initialized and the socket is connected. Parameters Parameters Description hTCP The socket to check. Returns true if the call succeeded false if no such socket or the socket is not opened 5.8.25.7.1.12 TCPIP_TCP_SocketNetGet Function C TCPIP_NET_HANDLE TCPIP_TCP_SocketNetGet( TCP_SOCKET hTCP ); Description This function returns the interface handle of an TCP socket Preconditions TCP socket should have been opened with _TCP_Open(). hTCP - valid socket Parameters Parameters Description hTCP The TCP socket Returns the handle of the local interface this socket is bound to. 5.8.25.7.1.13 TCPIP_TCP_WasReset Function C bool TCPIP_TCP_WasReset( TCP_SOCKET hTCP 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3896 ); Description This function is a self-clearing semaphore indicating whether or not a socket has been disconnected since the previous call. This function works for all possible disconnections: a call to TCPIP_TCP_Disconnect, a FIN from the remote node, or an acknowledgement timeout caused by the loss of a network link. It also returns true after the first call to TCPIP_TCP_Initialize. Applications should use this function to reset their state machines. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to check. Return Values Return Values Description true The socket has been disconnected since the previous call. false The socket has not been disconnected since the previous call. 5.8.25.7.1.14 TCPIP_TCP_Abort Function C void TCPIP_TCP_Abort( TCP_SOCKET hTCP, bool killSocket ); Description This function aborts a connection to a remote node by sending a RST (if currently connected). Any pending TX/RX data is discarded. A client socket will always be closed and the associated resources released. The socket cannot be used again after this call. A server socket will abort the current connection: • if killSocket == false the socket will remain listening • if killSocket == true the socket will be closed and all associated resources released. The socket cannot be used again after this call. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP Handle to the socket to disconnect. killSocket if true, it kills a server socket Returns None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3897 5.8.25.7.1.15 TCPIP_TCP_SocketNetSet Function C bool TCPIP_TCP_SocketNetSet( TCP_SOCKET hTCP, TCPIP_NET_HANDLE hNet ); Description This function sets the network interface for an TCP socket Preconditions TCP socket should have been opened with _TCP_Open(). hTCP - valid socket Parameters Parameters Description hTCP The TCP socket hNet interface handle. Returns true if success false otherwise. Remarks None 5.8.25.7.2 Transmit Data Transfer Functions 5.8.25.7.2.1 TCPIP_TCP_ArrayPut Function C uint16_t TCPIP_TCP_ArrayPut( TCP_SOCKET hTCP, const uint8_t* Data, uint16_t Len ); Description Writes an array from RAM to a TCP socket. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to which data is to be written. data Pointer to the array to be written. len Number of bytes to be written. Returns The number of bytes written to the socket. If less than len, the buffer became full or the socket is not conected. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3898 5.8.25.7.2.2 TCPIP_TCP_FifoTxFullGet Function C uint16_t TCPIP_TCP_FifoTxFullGet( TCP_SOCKET hTCP ); Description Determines how many bytes are pending in the TCP TX FIFO. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to check. Returns Number of bytes pending to be flushed in the TCP TX FIFO. 5.8.25.7.2.3 TCPIP_TCP_Flush Function C bool TCPIP_TCP_Flush( TCP_SOCKET hTCP ); Description This function immediately transmits all pending TX data with a PSH flag. If this function is not called, data will automatically be sent when either a) the TX buffer is half full or b) the TCP_AUTO_TRANSMIT_TIMEOUT_VAL (default: 40ms) has elapsed. Preconditions TCP is initialized and the socket is connected. Parameters Parameters Description hTCP The socket whose data is to be transmitted. Returns None Remarks SSL application data is automatically flushed, so this function has no effect for SSL sockets. 5.8.25.7.2.4 TCPIP_TCP_Put Function C uint16_t TCPIP_TCP_Put( TCP_SOCKET hTCP, uint8_t byte ); Description Writes a single byte to a TCP socket. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3899 Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP The socket to which data is to be written. byte The byte to write. Return Values Return Values Description 0 The byte was written to the transmit buffer. 1 The transmit buffer was full, or the socket is not connected. Remarks Note that the following function is inefficient. A buffered approach (TCPIP_TCP_ArrayPut) should be preferred 5.8.25.7.2.5 TCPIP_TCP_PutIsReady Function C uint16_t TCPIP_TCP_PutIsReady( TCP_SOCKET hTCP ); Description Call this function to determine how many bytes can be written to the TCP TX buffer. If this function returns zero, the application must return to the main stack loop before continuing in order to transmit more data. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to check. Returns The number of bytes available to be written in the TCP TX buffer. 5.8.25.7.2.6 TCPIP_TCP_StringPut Function C const uint8_t* TCPIP_TCP_StringPut( TCP_SOCKET hTCP, const uint8_t* Data ); Description Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket. Preconditions TCP is initialized. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3900 Parameters Parameters Description hTCP The socket to which data is to be written. data Pointer to the string to be written. Returns Pointer to the byte following the last byte written to the socket. If this pointer does not dereference to a NUL byte, the buffer became full or the socket is not connected. Remarks The return value of this function differs from that of TCPIP_TCP_ArrayPut. To write long strings in a single state, initialize the *data pointer to the first byte, then call this function repeatedly (breaking to the main stack loop after each call) until the return value dereferences to a NUL byte. Save the return value as the new starting *data pointer otherwise. 5.8.25.7.3 Receive Data Transfer Functions 5.8.25.7.3.1 TCPIP_TCP_ArrayFind Function C uint16_t TCPIP_TCP_ArrayFind( TCP_SOCKET hTCP, const uint8_t* cFindArray, uint16_t wLen, uint16_t wStart, uint16_t wSearchLen, bool bTextCompare ); Description This function finds the first occurrance of an array of bytes in the TCP RX buffer. It can be used by an application to abstract searches out of their own application code. For increased efficiency, the function is capable of limiting the scope of search to a specific range of bytes. It can also perform a case-insensitive search if required. For example, if the buffer contains "I love PIC MCUs!" and the search array is "love" with a length of 4, a value of 2 will be returned. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to search within. cFindArray The array of bytes to find in the buffer. wLen Length of cFindArray. wStart Zero-indexed starting position within the buffer. wSearchLen Length from wStart to search in the buffer. bTextCompare true for case-insensitive text search, false for binary search Return Values Return Values Description 0xFFFF Search array not found 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3901 Otherwise Zero-indexed position of the first occurrance Remarks Since this function usually must transfer data from external storage to internal RAM for comparison, its performance degrades significantly when the buffer is full and the array is not found. For better performance, try to search for characters that are expected to exist or limit the scope of the search as much as possible. The HTTP module, for example, uses this function to parse headers. However, it searches for newlines, then the separating colon, then reads the header name to RAM for final comparison. This has proven to be significantly faster than searching for full header name strings outright. 5.8.25.7.3.2 TCPIP_TCP_ArrayGet Function C uint16_t TCPIP_TCP_ArrayGet( TCP_SOCKET hTCP, uint8_t* buffer, uint16_t count ); Description Reads an array of data bytes from a TCP socket's receive FIFO. The data is removed from the FIFO in the process. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket from which data is to be read. buffer Pointer to the array to store data that was read. len Number of bytes to be read. Returns The number of bytes read from the socket. If less than len, the RX FIFO buffer became empty or the socket is not conected. 5.8.25.7.3.3 TCPIP_TCP_ArrayPeek Function C uint16_t TCPIP_TCP_ArrayPeek( TCP_SOCKET hTCP, uint8_t * vBuffer, uint16_t wLen, uint16_t wStart ); Description Reads a specified number of data bytes from the TCP RX FIFO without removing them from the buffer. No TCP control actions are taken as a result of this function (ex: no window update is sent to the remote node). Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to peak from (read without removing from stream). 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3902 vBuffer Destination to write the peeked data bytes. wLen Length of bytes to peak from the RX FIFO and copy to vBuffer. wStart Zero-indexed starting position within the FIFO to start peeking from. Remarks None 5.8.25.7.3.4 TCPIP_TCP_Discard Function C uint16_t TCPIP_TCP_Discard( TCP_SOCKET hTCP ); Description Discards any pending data in the TCP RX FIFO. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket whose RX FIFO is to be cleared. Returns Number of bytes that have been discarded from the RX buffer. 5.8.25.7.3.5 TCPIP_TCP_FifoSizeAdjust Function C bool TCPIP_TCP_FifoSizeAdjust( TCP_SOCKET hTCP, uint16_t wMinRXSize, uint16_t wMinTXSize, TCP_ADJUST_FLAGS vFlags ); Description This function can be used to simultaneously adjust the sizes of the RX and TX FIFOs. Adjusting the size of the TX/RX FIFO on the fly can allow for optimal transmission speed for one-sided application protocols. For example, HTTP typically begins by receiving large amounts of data from the client, then switches to serving large amounts of data back. Adjusting the FIFO at these points can increase performance in systems that have limited resources. Once the FIFOs are adjusted, a window update is sent. The TCP_ADJUST_FLAGS control the distribution of the remaining available space between the TX and RX FIFOs. If neither or both of TCP_ADJUST_GIVE_REST_TO_TX and TCP_ADJUST_GIVE_REST_TO_RX are set, the function distributes the remaining space (if any) equally. If the new requested FIFOs space is greater that the old existing FIFOs space the TCP_ADJUST_GIVE_REST_TO_TX and TCP_ADJUST_GIVE_REST_TO_RX are ignored. TCP_ADJUST_PRESERVE_RX and TCP_ADJUST_PRESERVE_TX request the preserving of the existing data. Existing data can be preserved as long as the old data in the buffer does not exceed the capacity of the new buffer. Preconditions TCP is initialized. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3903 Parameters Parameters Description hTCP The socket to be adjusted wMinRXSize Minimum number of bytes for the RX FIFO wMinTXSize Minimum number of bytes for the TX FIFO vFlags If TCP_ADJUST_TX_ONLY or TCP_ADJUST_RX_ONLY are not set, then the TX and RX bufferrs are evaluated together and any 5.8.25.7.3.6 TCPIP_TCP_Find Function C uint16_t TCPIP_TCP_Find( TCP_SOCKET hTCP, uint8_t cFind, uint16_t wStart, uint16_t wSearchLen, bool bTextCompare ); Description This function finds the first occurrance of a byte in the TCP RX buffer. It can be used by an application to abstract searches out of their own application code. For increased efficiency, the function is capable of limiting the scope of search to a specific range of bytes. It can also perform a case-insensitive search if required. For example, if the buffer contains "I love PIC MCUs!" and the cFind byte is ' ', a value of 1 will be returned. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to search within. cFind The byte to find in the buffer. wStart Zero-indexed starting position within the buffer. wSearchLen Length from wStart to search in the buffer. bTextCompare true for case-insensitive text search, false for binary search Return Values Return Values Description 0xFFFF Search array not found Otherwise Zero-indexed position of the first occurrance Remarks Since this function usually must transfer data from external storage to internal RAM for comparison, its performance degrades significantly when the buffer is full and the array is not found. For better performance, try to search for characters that are expected to exist or limit the scope of the search as much as possible. The HTTP module, for example, uses this function to parse headers. However, it searches for newlines, then the separating colon, then reads the header name to RAM for final comparison. This has proven to be significantly faster than searching for full header name strings outright. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3904 5.8.25.7.3.7 TCPIP_TCP_Get Function C uint16_t TCPIP_TCP_Get( TCP_SOCKET hTCP, uint8_t* byte ); Description Retrieves a single byte to a TCP socket. Preconditions TCP socket should have been opened with TCPIP_TCP_ServerOpen()/TCPIP_TCP_ClientOpen()(). hTCP - valid socket Parameters Parameters Description hTCP The socket from which to read. byte Pointer to location in which the read byte should be stored. Return Values Return Values Description 1 A byte was read from the buffer. 0 The buffer was empty, or the socket is not connected. Remarks Note that the following function is inefficient. A buffered approach (TCPIP_TCP_ArrayGet) should be preferred 5.8.25.7.3.8 TCPIP_TCP_GetIsReady Function C uint16_t TCPIP_TCP_GetIsReady( TCP_SOCKET hTCP ); Description Call this function to determine how many bytes can be read from the TCP RX buffer. If this function returns zero, the application must return to the main stack loop before continuing in order to wait for more data to arrive. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to check. Returns The number of bytes available to be read from the TCP RX buffer. 5.8.25.7.3.9 TCPIP_TCP_Peek Function C uint8_t TCPIP_TCP_Peek( TCP_SOCKET hTCP, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3905 uint16_t wStart ); Description Peaks at one byte in the TCP RX FIFO without removing it from the buffer. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to peak from (read without removing from stream). wStart Zero-indexed starting position within the FIFO to peek from. Remarks Use the TCPIP_TCP_ArrayPeek() function to read more than one byte. It will perform better than calling TCPIP_TCP_Peek() in a loop. 5.8.25.7.3.10 TCPIP_TCP_FifoRxFreeGet Function C uint16_t TCPIP_TCP_FifoRxFreeGet( TCP_SOCKET hTCP ); Description Determines how many bytes are free in the RX FIFO. Preconditions TCP is initialized. Parameters Parameters Description hTCP The socket to check. Returns The number of bytes free in the TCP RX FIFO. If zero, no additional data can be received until the application removes some data using one of the TCPIP_TCP_Get family functions. 5.8.25.7.4 Data Types and Constants 5.8.25.7.4.1 TCPIP_TCP_FifoRxFullGet Macro C #define TCPIP_TCP_FifoRxFullGet(a) TCPIP_TCP_GetIsReady(a) Description Macro: TCPIP_TCP_FifoRxFullGet Alias to TCPIP_TCP_GetIsReady provided for API completeness 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3906 5.8.25.7.4.2 TCPIP_TCP_FifoTxFreeGet Macro C #define TCPIP_TCP_FifoTxFreeGet(a) TCPIP_TCP_PutIsReady(a) Description Macro: TCPIP_TCP_FifoTxFreeGet(TCP_SOCKET hTCP) Alias to TCPIP_TCP_PutIsReady provided for API completeness Parameters Parameters Description hTCP The socket to check. Returns The number of bytes available to be written in the TCP TX buffer. 5.8.25.7.4.3 TCP_ADJUST_FLAGS Enumeration C typedef enum { TCP_ADJUST_GIVE_REST_TO_RX = 0x01, TCP_ADJUST_GIVE_REST_TO_TX = 0x02, TCP_ADJUST_PRESERVE_RX = 0x04, TCP_ADJUST_PRESERVE_TX = 0x08, TCP_ADJUST_TX_ONLY = 0x10, TCP_ADJUST_RX_ONLY = 0x20 } TCP_ADJUST_FLAGS; Description Enumeration: TCP_ADJUST_FLAGS Adjust socket buffer sizes. Members Members Description TCP_ADJUST_GIVE_REST_TO_RX = 0x01 Resize flag: extra bytes go to RX TCP_ADJUST_GIVE_REST_TO_TX = 0x02 Resize flag: extra bytes go to TX TCP_ADJUST_PRESERVE_RX = 0x04 Resize flag: attempt to preserve RX buffer TCP_ADJUST_PRESERVE_TX = 0x08 Resize flag: attempt to preserve TX buffer TCP_ADJUST_TX_ONLY = 0x10 Resize flag: adjust the TX buffer only TCP_ADJUST_RX_ONLY = 0x20 Resize flag: adjust the RX buffer only 5.8.25.7.4.4 TCP_MODULE_CONFIG Structure C typedef struct { int nSockets; uint16_t sktTxBuffSize; uint16_t sktRxBuffSize; } TCP_MODULE_CONFIG; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3907 Description Structure: TCP_MODULE_CONFIG TCP layer configuration/initialization Members Members Description int nSockets; number of sockets to be created uint16_t sktTxBuffSize; size of the socket tx buffer uint16_t sktRxBuffSize; size of the socket rx buffer 5.8.25.7.4.5 TCP_OPTION_LINGER_DATA Structure C typedef struct { bool lingerEnable; bool gracefulEnable; uint16_t lingerTmo; } TCP_OPTION_LINGER_DATA; Description Structure: TCP_OPTION_LINGER_DATA Linger options Members Members Description bool lingerEnable; enable/disable linger; enabled by default for any socket bool gracefulEnable; enable/disable graceful close; enabled by default for any socket uint16_t lingerTmo; linger timeout in seconds (when enabled) this option is not supported yet 5.8.25.7.4.6 TCP_PORT Type C typedef uint16_t TCP_PORT; Description Type: TCP_PORT TCP Port Number identifier 5.8.25.7.4.7 TCP_SOCKET Type C typedef int16_t TCP_SOCKET; Description Type: TCP_SOCKET A TCP_SOCKET is stored as a single uint8_t 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3908 5.8.25.7.4.8 TCP_SOCKET_INFO Structure C typedef struct { IP_ADDRESS_TYPE addressType; IP_MULTI_ADDRESS remoteIPaddress; IP_MULTI_ADDRESS localIPaddress; TCP_PORT remotePort; TCP_PORT localPort; } TCP_SOCKET_INFO; Description Structure: TCP_SOCKET_INFO Information about a socket Members Members Description TCP_PORT remotePort; Port number associated with remote node TCP_PORT localPort; local port number 5.8.25.7.4.9 TCP_SOCKET_OPTION Enumeration C typedef enum { TCP_OPTION_LINGER, TCP_OPTION_KEEPPALIVE, TCP_OPTION_RX_BUFF, TCP_OPTION_TX_BUFF, TCP_OPTION_RX_TMO, TCP_OPTION_TX_TMO, TCP_OPTION_NODELAY, TCP_OPTION_EXCLUSIVE_ADDRESS } TCP_SOCKET_OPTION; Description Enumeration: TCP_SOCKET_OPTION Socket options Members Members Description TCP_OPTION_LINGER The LINGER option controls the action taken when unsent data is queued on a socket and the socket is closed. The linger option can be turned on/off and the timeout can be specified. TCP_OPTION_KEEPPALIVE enable the use of keep-alive packets on TCP connections The option can be turned on/off and the timeout can be specified TCP_OPTION_RX_BUFF request different RX buffer size. Has to call TCPIP_TCP_OptionsGet to see the exact space allocated TCP_OPTION_TX_BUFF request different TX buffer size. Has to call TCPIP_TCP_OptionsGet to see the exact space allocated TCP_OPTION_RX_TMO specifies the RX timeout. If no data arrives in the specified timeout the socket is closed TCP_OPTION_TX_TMO specifies the TX timeout. If no data can be sent in the specified timeout the socket is closed TCP_OPTION_NODELAY enables the NO DELAY/Nagle algorithm functionality; 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3909 TCP_OPTION_EXCLUSIVE_ADDRESS enables a socket to be bound for exclusive access. 5.8.25.7.4.10 INVALID_SOCKET Macro C #define INVALID_SOCKET (-1) // The socket is invalid or could not be opened Description The socket is invalid or could not be opened 5.8.25.8 Files Files Name Description tcp.h Transmission Control Protocol (TCP) Communications Layer API tcp_config.h TCP configuration file Description 5.8.25.8.1 tcp.h • Provides reliable, handshaked transport of application stream oriented data with flow control • Reference: RFC 793 Enumerations Name Description TCP_ADJUST_FLAGS TCP Adjust Falgs TCP_SOCKET_OPTION TCP Socket Option Functions Name Description TCPIP_TCP_Abort Aborts a connection. TCPIP_TCP_ArrayFind Searches for a string in the TCP RX buffer. TCPIP_TCP_ArrayGet Reads an array of data bytes from a TCP socket's receive FIFO. The data is removed from the FIFO in the process. TCPIP_TCP_ArrayPeek Reads a specified number of data bytes from the TCP RX FIFO without removing them from the buffer. TCPIP_TCP_ArrayPut Writes an array from RAM to a TCP socket. TCPIP_TCP_Bind Bind a socket to a local address This function is meant for unconnected server and client sockets. It is similar to TCPIP_TCP_SocketNetSet() that assigns a specific source interface for a socket. If localPort is 0 the stack will assign a unique local port TCPIP_TCP_ClientOpen Opens a TCP socket as a client. TCPIP_TCP_Close Disconnects an open socket and destroys the socket handle, releasing the associated resources. TCPIP_TCP_Connect Connects a client socket. TCPIP_TCP_Discard Discards any pending data in the TCP RX FIFO. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3910 TCPIP_TCP_Disconnect Disconnects an open socket. TCPIP_TCP_FifoRxFreeGet Determines how many bytes are free in the RX FIFO. TCPIP_TCP_FifoSizeAdjust Adjusts the relative sizes of the RX and TX buffers. TCPIP_TCP_FifoTxFullGet Determines how many bytes are pending in the TCP TX FIFO. TCPIP_TCP_Find Searches for a byte in the TCP RX buffer. TCPIP_TCP_Flush Immediately transmits all pending TX data. TCPIP_TCP_Get Retrieves a single byte to a TCP socket. TCPIP_TCP_GetIsReady Determines how many bytes can be read from the TCP RX buffer. TCPIP_TCP_IsConnected Determines if a socket has an established connection. TCPIP_TCP_OptionsGet Allows getting the options for a socket like: current Rx/Tx buffer size, etc TCPIP_TCP_OptionsSet Allows setting options to a socket like adjust Rx/Tx buffer size, etc TCPIP_TCP_Peek Peaks at one byte in the TCP RX FIFO without removing it from the buffer. TCPIP_TCP_Put Writes a single byte to a TCP socket. TCPIP_TCP_PutIsReady Determines how much free space is available in the TCP TX buffer. TCPIP_TCP_RemoteBind Bind a socket to a remote address This function is meant for unconnected server and client sockets. TCPIP_TCP_ServerOpen Opens a TCP socket as a server. TCPIP_TCP_SocketInfoGet Obtains information about a currently open socket. TCPIP_TCP_SocketNetGet Gets the MAC interface of an TCP socket TCPIP_TCP_SocketNetSet Sets the interface for an TCP socket TCPIP_TCP_StringPut Writes a null-terminated string from RAM to a TCP socket. The null-terminator is not copied to the socket. TCPIP_TCP_WasReset Self-clearing semaphore inidicating socket reset. Macros Name Description INVALID_SOCKET The socket is invalid or could not be opened TCPIP_TCP_FifoRxFullGet TCP Get Rx First In, First Out Full TCPIP_TCP_FifoTxFreeGet TCP Get TX First In, First Out Free Structures Name Description TCP_MODULE_CONFIG TCP layer configuration/initialization TCP_OPTION_LINGER_DATA Linger options TCP_SOCKET_INFO TCP Socket Information Types Name Description TCP_PORT TCP Port TCP_SOCKET TCP Socket File Name tcp.h Company Microchip Technology Incorporated 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TCP TCP/IP Stack Library 5-3911 5.8.25.8.2 tcp_config.h Transmission Control Protocol (TCP) Configuration file This file contains the TCP module configuration options Macros Name Description LOCAL_TCP_PORT_END_NUMBER Last port number for randomized local port number selection LOCAL_TCP_PORT_START_NUMBER First port number for randomized local port number selection Use the dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range TCP_AUTO_TRANSMIT_TIMEOUT_VAL Timeout before automatically transmitting unflushed data, ms; Default 40 ms TCP_CLOSE_WAIT_TIMEOUT Timeout for the CLOSE_WAIT state, ms TCP_DELAYED_ACK_TIMEOUT Timeout for delayed-acknowledgement algorithm, ms TCP_FIN_WAIT_2_TIMEOUT Timeout for FIN WAIT 2 state, ms TCP_KEEP_ALIVE_TIMEOUT Timeout for keep-alive messages when no traffic is sent, ms TCP_MAX_RETRIES Maximum number of retransmission attempts TCP_MAX_SEG_SIZE_RX_LOCAL TCP Maximum Segment Size for RX (MSS). This value is advertised during TCP connection establishment and the remote node should obey it. The value has to be set in such a way to avoid IP layer fragmentation from causing packet loss. However, raising its value can enhance performance at the (small) risk of introducing incompatibility with certain special remote nodes (ex: ones connected via a slow dial up modem). On Ethernet networks the standard value is 1460. On dial-up links, etc. the default values should be 536. Adjust these values according to your network. The stack will use the local... more TCP_MAX_SEG_SIZE_RX_NON_LOCAL Max segment size, non local TCP_MAX_SEG_SIZE_TX TCP Maximum Segment Size for TX. The TX maximum segment size is actually governed by the remote node's MSS option advertised during connection establishment. However, if the remote node specifies an unhandlably large MSS (ex: > Ethernet MTU), this define sets a hard limit so that we don't cause any TX buffer overflows. If the remote node does not advirtise a MSS option, all TX segments are fixed at 536 bytes maximum. TCP_MAX_SOCKETS The maximum number of sockets to create in the stack. When defining TCP_MAX_SOCKETS take into account the number of interfaces the stack is supporting TCP_MAX_SYN_RETRIES Smaller than all other retries to reduce SYN flood DoS duration TCP_MAX_UNACKED_KEEP_ALIVES Maximum number of keep-alive messages that can be sent without receiving a response before automatically closing the connection TCP_SOCKET_DEFAULT_RX_SIZE default socket Rx buffer size TCP_SOCKET_DEFAULT_TX_SIZE default socket Tx buffer size TCP_START_TIMEOUT_VAL TCP Timeout and retransmit numbers All timeouts in milliseconds Timeout to retransmit unacked data, ms TCP_TASK_TICK_RATE 5 ms default rate TCP_WINDOW_UPDATE_TIMEOUT_VAL Timeout before automatically transmitting a window update due to a TCPIP_TCP_Get() or TCPIP_TCP_ArrayGet() function call, ms 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Telnet TCP/IP Stack Library 5-3912 5.8.26 Telnet TCP/IP Stack Library 5.8.26.1 Introduction Telnet TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the Telnet TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Telnet provides bidirectional, interactive communication between two nodes on the Internet or on a Local Area Network. The sTelnet code included with Microchip's TCP/IP stack is a demonstration of the structure of a Telnet application. This demo begins by listening for a Telnet connection. When a client attempts to make one, the demo will prompt the client for a username and password, and if the correct one is provided, will output and periodically refresh several values obtained from the demo board. There are several changes that you may need to make to Telnet.c and/or Telnet.h to suit your application. All of the Telnet Public members can be re-defined in the application-specific section of TCPIPConfig.h. You may also wish to change some of the Telnet Internal Member strings, located in Telnet.c, to more accurately reflect your application. You will also need to modify the TelnetTask ( see page 574) function to include the functionality you'd like. You may insert or change states in TelnetTask ( see page 574) as needed. 5.8.26.2 Release Notes MPLAB Harmony Version: v0.70b Telnet TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.26.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Telnet TCP/IP Stack Library 5-3913 FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.26.4 Using the Library This topic describes the basic architecture of the Telnet TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: telnet.h The interface to the Telnet TCP/IP Stack library is defined in the "telnet.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the Telnet TCP/IP Stack library should include "tcpip.h". Library File: The Telnet TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.26.4.1 Abstraction Model This library provides the API of the Telnet TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Telnet Software Abstraction Block Diagram Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.26.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Telnet module. Library Interface Section Description Data Types and Constants This section provides various definitions describing this API 5.8.26.5 Configuring the Library Macros Name Description MAX_TELNET_CONNECTIONS Maximum number of Telnet connections TELNET_PASSWORD Default Telnet password 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Telnet TCP/IP Stack Library 5-3914 TELNET_PORT Unsecured Telnet port TELNET_USERNAME Default Telnet user name TELNETS_PORT SSL Secured Telnet port (ignored if TCPIP_STACK_USE_SSL_SERVER is undefined) Description The configuration of the Telnet TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the Telnet TCP/IP Stack Library. Based on the selections made, the Telnet TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the Telnet TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.26.5.1 MAX_TELNET_CONNECTIONS Macro C #define MAX_TELNET_CONNECTIONS (2u) Description Maximum number of Telnet connections 5.8.26.5.2 TELNET_PASSWORD Macro C #define TELNET_PASSWORD "microchip" Description Default Telnet password 5.8.26.5.3 TELNET_PORT Macro C #define TELNET_PORT 23 Description Unsecured Telnet port 5.8.26.5.4 TELNET_USERNAME Macro C #define TELNET_USERNAME "admin" Description Default Telnet user name 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Telnet TCP/IP Stack Library 5-3915 5.8.26.5.5 TELNETS_PORT Macro C #define TELNETS_PORT 992 Description SSL Secured Telnet port (ignored if TCPIP_STACK_USE_SSL_SERVER is undefined) 5.8.26.6 Building the Library This section list the files that are available in the \src of the Telnet driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.26.7 Library Interface Data Types and Constants Name Description TELNET_MODULE_CONFIG Telnet Configuration structure placeholder Description There are no user accessible functions in this interface. There is only a place holder for Telnet module configuration. 5.8.26.7.1 Data Types and Constants 5.8.26.7.1.1 TELNET_MODULE_CONFIG Structure C typedef struct { } TELNET_MODULE_CONFIG; Description Telnet Configuration structure placeholder 5.8.26.8 Files Files Name Description telnet.h telnet_config.h Configuration file Description 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Telnet TCP/IP Stack Library 5-3916 5.8.26.8.1 telnet.h Telnet Server Module for Microchip TCP/IP Stack -Listens on TCP Port 23 Structures Name Description TELNET_MODULE_CONFIG Telnet Configuration structure placeholder 5.8.26.8.2 telnet_config.h Telnet Configuration file This file contains the Telnet module configuration options Macros Name Description MAX_TELNET_CONNECTIONS Maximum number of Telnet connections TELNET_PASSWORD Default Telnet password TELNET_PORT Unsecured Telnet port TELNET_USERNAME Default Telnet user name TELNETS_PORT SSL Secured Telnet port (ignored if TCPIP_STACK_USE_SSL_SERVER is undefined) 5.8.27 TFTP TCP/IP Stack Library 5.8.27.1 Introduction Trivial File Transfer Protocol (TFTP) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the TFTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description The Trivial File Transfer Protocol provides unreliable upload and download services to applications connected to the UDP-based TFTP server. 5.8.27.2 Release Notes MPLAB Harmony Version: v0.70b TFTP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3917 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.27.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.27.4 Using the Library This topic describes the basic architecture of the TFTP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: tftpc.h The interface to the TFTP TCP/IP Stack library is defined in the "tftpc.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the tftpc.h TCP/IP Stack library should include "tcpip.h". Library File: The TFTP TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.27.4.1 Abstraction Model This library provides the API of the TFTP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description TFTP Software Abstraction Block Diagram 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3918 5.8.27.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the TFTP module. Library Interface Section Description General Functions This section provides general interface routines to TFTP Data Types and Constants This section provides various definitions describing this API 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3919 5.8.27.5 Configuring the Library Macros Name Description TFTP_ARP_TIMEOUT_VAL Number of seconds to wait before declaring TIMEOUT error on Put, seconds TFTP_BLOCK_SIZE The size of a TFTP block - 512 bytes TFTP_BLOCK_SIZE_MSB The MSB of the TFTP_BLOCK_SIZE TFTP_CLIENT_PORT The TFTP Client port - a unique port on this device TFTP_GET_TIMEOUT_VAL Number of seconds to wait before declaring TIMEOUT error on Get, seconds. TFTP_MAX_RETRIES Number of attempts before declaring TIMEOUT error. TFTP_SERVER_PORT The TFTP Server Port Description The configuration of the TFTP TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the TFTP TCP/IP Stack Library. Based on the selections made, the TFTP TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the TFTP TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.27.5.1 TFTP_ARP_TIMEOUT_VAL Macro C #define TFTP_ARP_TIMEOUT_VAL (3ul) Description Number of seconds to wait before declaring TIMEOUT error on Put, seconds 5.8.27.5.2 TFTP_BLOCK_SIZE Macro C #define TFTP_BLOCK_SIZE (0x200L) Description The size of a TFTP block - 512 bytes 5.8.27.5.3 TFTP_BLOCK_SIZE_MSB Macro C #define TFTP_BLOCK_SIZE_MSB (0x02u) Description The MSB of the TFTP_BLOCK_SIZE 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3920 5.8.27.5.4 TFTP_CLIENT_PORT Macro C #define TFTP_CLIENT_PORT 65352L Description The TFTP Client port - a unique port on this device 5.8.27.5.5 TFTP_GET_TIMEOUT_VAL Macro C #define TFTP_GET_TIMEOUT_VAL (3ul) Description Number of seconds to wait before declaring TIMEOUT error on Get, seconds. 5.8.27.5.6 TFTP_MAX_RETRIES Macro C #define TFTP_MAX_RETRIES (3u) Description Number of attempts before declaring TIMEOUT error. 5.8.27.5.7 TFTP_SERVER_PORT Macro C #define TFTP_SERVER_PORT (69L) Description The TFTP Server Port 5.8.27.6 Building the Library This section list the files that are available in the \src of the TFTP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8.27.7 Library Interface Data Types and Constants Name Description TFTP_UPLOAD_COMPLETE Status codes for TCPIP_TFTP_UploadStatusGet() function. Zero means upload success, >0 means working and <0 means fatal error. TFTP_UPLOAD_CONNECT This is macro TFTP_UPLOAD_CONNECT. TFTP_UPLOAD_CONNECT_TIMEOUT This is macro TFTP_UPLOAD_CONNECT_TIMEOUT. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3921 TFTP_UPLOAD_GET_DNS This is macro TFTP_UPLOAD_GET_DNS. TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT. TFTP_UPLOAD_RESOLVE_HOST This is macro TFTP_UPLOAD_RESOLVE_HOST. TFTP_UPLOAD_SEND_DATA This is macro TFTP_UPLOAD_SEND_DATA. TFTP_UPLOAD_SEND_FILENAME This is macro TFTP_UPLOAD_SEND_FILENAME. TFTP_UPLOAD_SERVER_ERROR This is macro TFTP_UPLOAD_SERVER_ERROR. TFTP_UPLOAD_WAIT_FOR_CLOSURE This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE. TFTPClose Macro: void TFTPClose(void) Closes TFTP client socket. TFTPGetError Macro: uint16_t TFTPGetError(void) Returns previously saved error code. TFTPIsFileOpenReady Macro: bool TFTPIsFileOpenReady(void) Checks to see if it is okay to send TFTP file open request to remote server. TFTP_ACCESS_ERROR Standard error codes as defined by TFTP spec. Use to decode value retuned by TFTPGetError(). TFTP_CHUNK_DESCRIPTOR This is type TFTP_CHUNK_DESCRIPTOR. TFTP_FILE_MODE File open mode as used by TFTPFileOpen(). TFTP_RESULT Enum. of results returned by most of the TFTP functions. Functions Name Description TCPIP_TFTP_DataByteGet This is function TCPIP_TFTP_DataByteGet. TCPIP_TFTP_DataBytePut This is function TCPIP_TFTP_DataBytePut. TCPIP_TFTP_DataIsGetReady This is function TCPIP_TFTP_DataIsGetReady. TCPIP_TFTP_FileClose This is function TCPIP_TFTP_FileClose. TCPIP_TFTP_FileIsClosed This is function TCPIP_TFTP_FileIsClosed. TCPIP_TFTP_FileIsOpen This is function TCPIP_TFTP_FileIsOpen. TCPIP_TFTP_FragRAMFileUploadToHost This is function TCPIP_TFTP_FragRAMFileUploadToHost. TCPIP_TFTP_IsOpen This is function TCPIP_TFTP_IsOpen. TCPIP_TFTP_IsReadyForPut This is function TCPIP_TFTP_IsReadyForPut. TCPIP_TFTP_Open This is function TCPIP_TFTP_Open. TCPIP_TFTP_RAMFileUploadToHost This is function TCPIP_TFTP_RAMFileUploadToHost. TCPIP_TFTP_UploadStatusGet This is function TCPIP_TFTP_UploadStatusGet. TFTPOpenFile This is function TFTPOpenFile. Description This section describes the Application Programming Interface (API) functions of the TFTP TCP/IP Stack. Refer to each section for a detailed description. 5.8.27.7.1 Functions 5.8.27.7.1.1 TCPIP_TFTP_DataByteGet Function C uint8_t TCPIP_TFTP_DataByteGet(); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3922 Description This is function TCPIP_TFTP_DataByteGet. 5.8.27.7.1.2 TCPIP_TFTP_DataBytePut Function C void TCPIP_TFTP_DataBytePut( uint8_t c ); Description This is function TCPIP_TFTP_DataBytePut. 5.8.27.7.1.3 TCPIP_TFTP_DataIsGetReady Function C TFTP_RESULT TCPIP_TFTP_DataIsGetReady(); Description This is function TCPIP_TFTP_DataIsGetReady. 5.8.27.7.1.4 TCPIP_TFTP_FileClose Function C void TCPIP_TFTP_FileClose(); Description This is function TCPIP_TFTP_FileClose. 5.8.27.7.1.5 TCPIP_TFTP_FileIsClosed Function C TFTP_RESULT TCPIP_TFTP_FileIsClosed(); Description This is function TCPIP_TFTP_FileIsClosed. 5.8.27.7.1.6 TCPIP_TFTP_FileIsOpen Function C TFTP_RESULT TCPIP_TFTP_FileIsOpen(); Description This is function TCPIP_TFTP_FileIsOpen. 5.8.27.7.1.7 TCPIP_TFTP_FragRAMFileUploadToHost Function C void TCPIP_TFTP_FragRAMFileUploadToHost( const uint8_t * vRemoteHost, const uint8_t * vFilename, TFTP_CHUNK_DESCRIPTOR * vFirstChunkDescriptor ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3923 Description This is function TCPIP_TFTP_FragRAMFileUploadToHost. 5.8.27.7.1.8 TCPIP_TFTP_IsOpen Function C TFTP_RESULT TCPIP_TFTP_IsOpen(); Description This is function TCPIP_TFTP_IsOpen. 5.8.27.7.1.9 TCPIP_TFTP_IsReadyForPut Function C TFTP_RESULT TCPIP_TFTP_IsReadyForPut(); Description This is function TCPIP_TFTP_IsReadyForPut. 5.8.27.7.1.10 TCPIP_TFTP_Open Function C void TCPIP_TFTP_Open( IPV4_ADDR * host ); Description This is function TCPIP_TFTP_Open. 5.8.27.7.1.11 TCPIP_TFTP_RAMFileUploadToHost Function C void TCPIP_TFTP_RAMFileUploadToHost( const uint8_t * vRemoteHost, const uint8_t * vFilename, uint8_t * vData, uint16_t wDataLength ); Description This is function TCPIP_TFTP_RAMFileUploadToHost. 5.8.27.7.1.12 TCPIP_TFTP_UploadStatusGet Function C int8_t TCPIP_TFTP_UploadStatusGet(); Description This is function TCPIP_TFTP_UploadStatusGet. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3924 5.8.27.7.1.13 TFTPOpenFile Function C void TFTPOpenFile( const uint8_t * fileName, TFTP_FILE_MODE mode ); Description This is function TFTPOpenFile. 5.8.27.7.2 Data Types and Constants 5.8.27.7.2.1 TFTP_UPLOAD_COMPLETE Macro C #define TFTP_UPLOAD_COMPLETE 0 Description Status codes for TCPIP_TFTP_UploadStatusGet() function. Zero means upload success, >0 means working and <0 means fatal error. 5.8.27.7.2.2 TFTP_UPLOAD_CONNECT Macro C #define TFTP_UPLOAD_CONNECT 3 Description This is macro TFTP_UPLOAD_CONNECT. 5.8.27.7.2.3 TFTP_UPLOAD_CONNECT_TIMEOUT Macro C #define TFTP_UPLOAD_CONNECT_TIMEOUT -2 Description This is macro TFTP_UPLOAD_CONNECT_TIMEOUT. 5.8.27.7.2.4 TFTP_UPLOAD_GET_DNS Macro C #define TFTP_UPLOAD_GET_DNS 1 Description This is macro TFTP_UPLOAD_GET_DNS. 5.8.27.7.2.5 TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT Macro C #define TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT -1 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3925 Description This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT. 5.8.27.7.2.6 TFTP_UPLOAD_RESOLVE_HOST Macro C #define TFTP_UPLOAD_RESOLVE_HOST 2 Description This is macro TFTP_UPLOAD_RESOLVE_HOST. 5.8.27.7.2.7 TFTP_UPLOAD_SEND_DATA Macro C #define TFTP_UPLOAD_SEND_DATA 5 Description This is macro TFTP_UPLOAD_SEND_DATA. 5.8.27.7.2.8 TFTP_UPLOAD_SEND_FILENAME Macro C #define TFTP_UPLOAD_SEND_FILENAME 4 Description This is macro TFTP_UPLOAD_SEND_FILENAME. 5.8.27.7.2.9 TFTP_UPLOAD_SERVER_ERROR Macro C #define TFTP_UPLOAD_SERVER_ERROR -3 Description This is macro TFTP_UPLOAD_SERVER_ERROR. 5.8.27.7.2.10 TFTP_UPLOAD_WAIT_FOR_CLOSURE Macro C #define TFTP_UPLOAD_WAIT_FOR_CLOSURE 6 Description This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE. 5.8.27.7.2.11 TFTPClose Macro C #define TFTPClose(void) TCPIP_UDP_Close(_tftpSocket) Description Macro: void TFTPClose(void) Closes TFTP client socket. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3926 Preconditions TCPIP_TFTP_Open is already called and TCPIP_TFTP_IsOpen() returned TFTP_OK. Returns None Side Effects None Remarks Once closed, application must do TCPIP_TFTP_Open to perform any new TFTP operations. If TFTP server does not change during application life-time, one may not need to call TFTPClose and keep TFTP socket open. 5.8.27.7.2.12 TFTPGetError Macro C #define TFTPGetError (_tftpError) Description Macro: uint16_t TFTPGetError(void) Returns previously saved error code. Preconditions One of the TFTP function returned with TFTP_ERROR result. Returns Error code as returned by remote server. Application may use TFTP_ACCESS_ERROR enum. to decode standard error code. Side Effects None Remarks None 5.8.27.7.2.13 TFTPIsFileOpenReady Macro C #define TFTPIsFileOpenReady UDPIsPutReady(_tftpSocket) Description Macro: bool TFTPIsFileOpenReady(void) Checks to see if it is okay to send TFTP file open request to remote server. Preconditions TCPIP_TFTP_Open is already called and TCPIP_TFTP_IsOpen() returned TFTP_OK. Returns true, if it is ok to call TFTPOpenFile() false, if otherwise. Side Effects None 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3927 Remarks None 5.8.27.7.2.14 TFTP_ACCESS_ERROR Type C typedef enum _TFTP_ACCESS_ERROR TFTP_ACCESS_ERROR; Description Standard error codes as defined by TFTP spec. Use to decode value retuned by TFTPGetError(). 5.8.27.7.2.15 TFTP_CHUNK_DESCRIPTOR Structure C typedef struct { uint8_t * vDataPointer; uint16_t wDataLength; } TFTP_CHUNK_DESCRIPTOR; Description This is type TFTP_CHUNK_DESCRIPTOR. 5.8.27.7.2.16 TFTP_FILE_MODE Type C typedef enum _TFTP_FILE_MODE TFTP_FILE_MODE; Description File open mode as used by TFTPFileOpen(). 5.8.27.7.2.17 TFTP_RESULT Type C typedef enum _TFTP_RESULT TFTP_RESULT; Description Enum. of results returned by most of the TFTP functions. 5.8.27.8 Files Files Name Description tftpc.h tftpc_config.h (TFTP) Configuration file Description 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3928 5.8.27.8.1 tftpc.h TFTP Client module for Microchip TCP/IP Stack Functions Name Description TCPIP_TFTP_DataByteGet This is function TCPIP_TFTP_DataByteGet. TCPIP_TFTP_DataBytePut This is function TCPIP_TFTP_DataBytePut. TCPIP_TFTP_DataIsGetReady This is function TCPIP_TFTP_DataIsGetReady. TCPIP_TFTP_FileClose This is function TCPIP_TFTP_FileClose. TCPIP_TFTP_FileIsClosed This is function TCPIP_TFTP_FileIsClosed. TCPIP_TFTP_FileIsOpen This is function TCPIP_TFTP_FileIsOpen. TCPIP_TFTP_FragRAMFileUploadToHost This is function TCPIP_TFTP_FragRAMFileUploadToHost. TCPIP_TFTP_IsOpen This is function TCPIP_TFTP_IsOpen. TCPIP_TFTP_IsReadyForPut This is function TCPIP_TFTP_IsReadyForPut. TCPIP_TFTP_Open This is function TCPIP_TFTP_Open. TCPIP_TFTP_RAMFileUploadToHost This is function TCPIP_TFTP_RAMFileUploadToHost. TCPIP_TFTP_UploadStatusGet This is function TCPIP_TFTP_UploadStatusGet. TFTPOpenFile This is function TFTPOpenFile. Macros Name Description TFTP_MAX_RETRIES Number of attempts before declaring TIMEOUT error. TFTP_UPLOAD_COMPLETE Status codes for TCPIP_TFTP_UploadStatusGet() function. Zero means upload success, >0 means working and <0 means fatal error. TFTP_UPLOAD_CONNECT This is macro TFTP_UPLOAD_CONNECT. TFTP_UPLOAD_CONNECT_TIMEOUT This is macro TFTP_UPLOAD_CONNECT_TIMEOUT. TFTP_UPLOAD_GET_DNS This is macro TFTP_UPLOAD_GET_DNS. TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT This is macro TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT. TFTP_UPLOAD_RESOLVE_HOST This is macro TFTP_UPLOAD_RESOLVE_HOST. TFTP_UPLOAD_SEND_DATA This is macro TFTP_UPLOAD_SEND_DATA. TFTP_UPLOAD_SEND_FILENAME This is macro TFTP_UPLOAD_SEND_FILENAME. TFTP_UPLOAD_SERVER_ERROR This is macro TFTP_UPLOAD_SERVER_ERROR. TFTP_UPLOAD_WAIT_FOR_CLOSURE This is macro TFTP_UPLOAD_WAIT_FOR_CLOSURE. TFTPClose Macro: void TFTPClose(void) Closes TFTP client socket. TFTPGetError Macro: uint16_t TFTPGetError(void) Returns previously saved error code. TFTPIsFileOpenReady Macro: bool TFTPIsFileOpenReady(void) Checks to see if it is okay to send TFTP file open request to remote server. Structures Name Description TFTP_CHUNK_DESCRIPTOR This is type TFTP_CHUNK_DESCRIPTOR. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help TFTP TCP/IP Stack Library 5-3929 Types Name Description TFTP_ACCESS_ERROR Standard error codes as defined by TFTP spec. Use to decode value retuned by TFTPGetError(). TFTP_FILE_MODE File open mode as used by TFTPFileOpen(). TFTP_RESULT Enum. of results returned by most of the TFTP functions. 5.8.27.8.2 tftpc_config.h Trivial File Transfer Protocol (TFTP) Configuration file This file contains the TFTP module configuration options Macros Name Description TFTP_ARP_TIMEOUT_VAL Number of seconds to wait before declaring TIMEOUT error on Put, seconds TFTP_BLOCK_SIZE The size of a TFTP block - 512 bytes TFTP_BLOCK_SIZE_MSB The MSB of the TFTP_BLOCK_SIZE TFTP_CLIENT_PORT The TFTP Client port - a unique port on this device TFTP_GET_TIMEOUT_VAL Number of seconds to wait before declaring TIMEOUT error on Get, seconds. TFTP_SERVER_PORT The TFTP Server Port 5.8.28 UDP TCP/IP Stack Library 5.8.28.1 Introduction UDP TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the UDP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description UDP is a standard transport layer protocol described in RFC 768. It provides fast but unreliable data-gram based transfers over networks, and forms the foundation SNTP, SNMP, DNS, and many other protocol standards. 5.8.28.2 Release Notes MPLAB Harmony Version: v0.70b UDP TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3930 This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.28.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.28.4 Using the Library This topic describes the basic architecture of the UDP TCP/IP Stack Library and provides information and examples on how to use it. Interface Header File: udp.h The interface to the UDP TCP/IP Stack library is defined in the "udp.h" header file. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the UDP TCP/IP Stack library should include "tcpip.h". Library File: The UDP TCPIP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.28.4.1 Abstraction Model This library provides the API of the UDP TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description UDP Software Abstraction Block Diagram This module provides software abstraction of the UDP module existent in any TCP/IP Stack implementation. It removes the overhead of address resolution from all other modules in the stack. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3931 Typical UDP Implementation 5.8.28.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the UDP module. Library Interface Section Description Socket Management Functions Routines for Managing UDP Sockets Transmit Data Transfer Functions Routines for Managing Outgoing Data Transmissions Receive Data Transfer Functions Routines for Managing Incoming Data Transmissions Data Types and Constants This section provides various definitions describing This API 5.8.28.4.3 How the Library Works Connections over UDP should be thought of as data-gram based transfers. Each packet is a separate entity, the application should expect some packets to arrive out-of-order or even fail to reach the destination node. This is in contrast to TCP, in which the connection is thought of as a stream and network errors are automatically corrected. These tradeoffs in reliability are made for an increase in throughput. In general, UDP transfers operate 2 to 3 times faster than those made over TCP. Since UDP is packet-oriented, each packet must be dealt with in its entirety by your application before returning to the main stack loop. When a packet is received, your application will be called to handle it. This packet will no longer be available the next time your application is called, so you must either perform all necessary processing or copy the data elsewhere before returning. When transmitting a packet, your application must build and transmit the complete packet in one cycle. 5.8.28.4.3.1 Core Functionality The UDP flow diagram below provides an overview for the use of the UDP module: Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. Sockets are opened using UDPOpen. This function can either open a listening socket to wait for incoming segments, or can make a client connection to a remote node. When making a client connection, you will need to perform any required DNS and/or ARP resolution using those modules directly before invoking UDPOpen. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3932 Once the socket is opened, you can immediately begin transmitting data. To transmit a segment, call UDPIsPutReady to determine how many bytes can be written and to designate a currently active socket. Then, use any of the TCPIP_UDP_Put family of functions to write data to the socket. Once all data has been written, call TCPIP_UDP_Flush to build and transmit the packet. This sequence must be accomplished all in one step. If your application returns to the main stack loop after calling TCPIP_UDP_Put but before calling TCPIP_UDP_Flush, the data may be lost or the module may behave unpredictably. 5.8.28.5 Configuring the Library Macros Name Description UDP_LOCAL_PORT_END_NUMBER Last port number for randomized local port number selection UDP_LOCAL_PORT_START_NUMBER The dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range First port number for randomized local port number selection UDP_MAX_SOCKETS global number of UDP sockets created dynamically UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT the maximum number of packets that can be queued by an UDP socket at a certain time. For sockets that need to transfer a lot of data (iperf, for example), especially on slow conenctions this limit prevents running out of memory because the MAC transfer cannot keep up with the UDP packet allocation rate imposed by the aapplication. Adjust depending on the UDP_SOCKET_DEFAULT_TX_SIZE, the connection speed and the amount of memory available to the stack. UDP_SOCKET_DEFAULT_TX_SIZE default socket Tx buffer size UDP_SOCKET_POOL_BUFFER_SIZE size of the buffers in the UDP pool any UDP socket that is enabled to use the pool and has the TX size <= than this size can use a buffer from the pool UDP_SOCKET_POOL_BUFFERS use 0 to disable the feature UDP_USE_RX_CHECKSUM check incoming packets to have proper checksum UDP_USE_TX_CHECKSUM This slows UDP TX performance by nearly 50%, except when using the ENCX24J600, which has a super fast DMA and incurs virtually no speed pentalty. Description The configuration of the UDP TCP/IP Stack Library is based on the file sys_config.h This header file contains the configuration selection for the UP TCP/IP Stack Library. Based on the selections made, the UDP TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the UDP TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.28.5.1 UDP_LOCAL_PORT_END_NUMBER Macro C #define UDP_LOCAL_PORT_END_NUMBER (65535) Description Last port number for randomized local port number selection 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3933 5.8.28.5.2 UDP_LOCAL_PORT_START_NUMBER Macro C #define UDP_LOCAL_PORT_START_NUMBER (49152) Description The dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range First port number for randomized local port number selection 5.8.28.5.3 UDP_MAX_SOCKETS Macro C #define UDP_MAX_SOCKETS (10) Description global number of UDP sockets created dynamically 5.8.28.5.4 UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT Macro C #define UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT 3 Description the maximum number of packets that can be queued by an UDP socket at a certain time. For sockets that need to transfer a lot of data (iperf, for example), especially on slow conenctions this limit prevents running out of memory because the MAC transfer cannot keep up with the UDP packet allocation rate imposed by the aapplication. Adjust depending on the UDP_SOCKET_DEFAULT_TX_SIZE, the connection speed and the amount of memory available to the stack. 5.8.28.5.5 UDP_SOCKET_DEFAULT_TX_SIZE Macro C #define UDP_SOCKET_DEFAULT_TX_SIZE 512 Description default socket Tx buffer size 5.8.28.5.6 UDP_SOCKET_POOL_BUFFER_SIZE Macro C #define UDP_SOCKET_POOL_BUFFER_SIZE 512 // size of the buffers in the UDP pool Description size of the buffers in the UDP pool any UDP socket that is enabled to use the pool and has the TX size <= than this size can use a buffer from the pool 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3934 5.8.28.5.7 UDP_SOCKET_POOL_BUFFERS Macro C #define UDP_SOCKET_POOL_BUFFERS 4 // use 0 to disable the feature Description use 0 to disable the feature 5.8.28.5.8 UDP_USE_RX_CHECKSUM Macro C #define UDP_USE_RX_CHECKSUM Description check incoming packets to have proper checksum 5.8.28.5.9 UDP_USE_TX_CHECKSUM Macro C #define UDP_USE_TX_CHECKSUM Description This slows UDP TX performance by nearly 50%, except when using the ENCX24J600, which has a super fast DMA and incurs virtually no speed pentalty. 5.8.28.6 Building the Library This section list the files that are available in the \src of the UDP driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. • udp.c 5.8.28.7 Library Interface Data Types and Constants Name Description INVALID_UDP_SOCKET Indicates a UDP socket that is not valid TCPIP_UDP_IsOpened backward compatibility call UDP_MODULE_CONFIG UDP layer configuration/initialization UDP_PORT Stores a UDP Port Number UDP_SOCKET Provides a handle to a UDP Socket UDP_SOCKET_BCAST_TYPE This is type UDP_SOCKET_BCAST_TYPE. UDP_SOCKET_INFO Information about a socket UDP_SOCKET_OPTION UDP socket options 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3935 Receive Data Transfer Functions Name Description TCPIP_UDP_Discard Discards any remaining RX data from a UDP socket. TCPIP_UDP_Get Reads a byte from the UDP socket. TCPIP_UDP_GetIsReady Determines how many bytes can be read from the UDP socket. TCPIP_UDP_RxOffsetSet Moves the pointer within the RX buffer. Socket Management Functions Name Description TCPIP_UDP_BcastIPV4AddressSet Sets the broadcast IP address of a socket Allows an UDP socket to send broadcasts. TCPIP_UDP_Bind Bind a socket to a local address and port. This function is meant for client sockets. It assigns a specific source address and port for a socket. TCPIP_UDP_ClientOpen Opens a UDP socket as a client. TCPIP_UDP_Close Closes a UDP socket and frees the handle. TCPIP_UDP_DestinationIPAddressSet Sets the destination IP address of a socket TCPIP_UDP_IsConnected Determines if a socket has an established connection. TCPIP_UDP_OptionsGet Allows getting the options for a socket like: current Rx/Tx buffer size, etc TCPIP_UDP_OptionsSet Allows setting options to a socket like adjust Rx/Tx buffer size, etc TCPIP_UDP_RemoteBind Bind a socket to a remote address This function is meant for server sockets. TCPIP_UDP_ServerOpen Opens a UDP socket as a server. TCPIP_UDP_SocketInfoGet Points handle at socket unfo for socket hUDP TCPIP_UDP_SocketNetGet Gets the network interface of an UDP socket TCPIP_UDP_SocketNetSet Sets the network interface for an UDP socket TCPIP_UDP_SourceIPAddressSet Sets the source IP address of a socket TCPIP_UDP_TxOffsetSet Moves the pointer within the TX buffer. Transmit Data Transfer Functions Name Description TCPIP_UDP_ArrayGet Reads an array of bytes from the UDP socket. TCPIP_UDP_Flush Transmits all pending data in a UDP socket. TCPIP_UDP_Put Writes a byte to the UDP socket. TCPIP_UDP_StringPut Writes null-terminated string to the UDP socket. TCPIP_UDP_TxCountGet Returns the amount of bytes written into the UDP socket. TCPIP_UDP_TxPutIsReady Determines how many bytes can be written to the UDP socket. TCPIP_UDP_ArrayPut Writes an array of bytes to the UDP socket. UDPIsPutReady Determines how many bytes can be written to the UDP socket. Description This section describes the Application Programming Interface (API) functions of the UDP TCP/IP Stack Library. Refer to each section for a detailed description. 5.8.28.7.1 Socket Management Functions 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3936 5.8.28.7.1.1 TCPIP_UDP_BcastIPV4AddressSet Function C bool TCPIP_UDP_BcastIPV4AddressSet( UDP_SOCKET s, UDP_SOCKET_BCAST_TYPE bcastType, TCPIP_NET_HANDLE hNet ); Description It sets the broadcast address for the socket Preconditions UDP initialized UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). s - valid socket Parameters Parameters Description s the UDP socket bcastType Type of broadcast hNet handle of an interface to use for the network directed broadcast Not used for network limited broadcast Returns True if success False otherwise Remarks This function allows changing of the destination IPv4 address dynamically. However, the call will fail if the socket was previously set to broadcast using the TCPIP_UDP_OptionsSet call. TCPIP_UDP_OptionsSet takes precedence. 5.8.28.7.1.2 TCPIP_UDP_Bind Function C bool TCPIP_UDP_Bind( UDP_SOCKET hUDP, IP_ADDRESS_TYPE addType, UDP_PORT localPort, IP_MULTI_ADDRESS* localAddress ); Description Sockets don't need specific binding, it is done automatically by the stack However, specific binding can be requested using these functions. Works for both client and server sockets. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP The socket to bind. addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. localPort The local port to bind to. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3937 localAddress Local address to use. Returns True if success False otherwise Remarks If localAddress == 0 the local address of the socket won't be changed. If localPort is 0 the stack will assign a unique local port 5.8.28.7.1.3 TCPIP_UDP_ClientOpen Function C UDP_SOCKET TCPIP_UDP_ClientOpen( IP_ADDRESS_TYPE addType, UDP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress ); Description Provides a unified method for opening UDP client sockets. Preconditions UDP is initialized. Parameters Parameters Description IP_ADDRESS_TYPE addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. UDP_PORT remotePort The remote UDP port to which a connection should be made. The local port for client sockets will be automatically picked by the UDP module. IP_MULTI_ADDRESS* remoteAddress The remote address to connect to. Returns INVALID_SOCKET - No sockets of the specified type were available to be opened. Otherwise - A UDP_SOCKET handle. Save this handle and use it when calling all other UDP APIs. Remarks IP_ADDRESS_TYPE_ANY is not supported! 5.8.28.7.1.4 TCPIP_UDP_Close Function C void TCPIP_UDP_Close( UDP_SOCKET hUDP ); Description Closes a UDP socket and frees the handle. Call this function to release a socket and return it to the pool for use by future communications. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3938 Parameters Parameters Description hUDP The socket handle to be released. Returns None 5.8.28.7.1.5 TCPIP_UDP_DestinationIPAddressSet Function C bool TCPIP_UDP_DestinationIPAddressSet( UDP_SOCKET s, IP_ADDRESS_TYPE addType, IP_MULTI_ADDRESS* remoteAddress ); Description • It sets the IP destination address This allows changing the destination IPv4 address dynamically. Preconditions UDP initialized UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). s - valid socket remoteAddress - valid address pointer Parameters Parameters Description s the UDP socket addType Type of address: IPv4/IPv6 remoteAddress pointer to an address to use Returns true if success false otherwise Remarks The call will fail if the socket was previously set to broadcast using the TCPIP_UDP_OptionsSet call. TCPIP_UDP_OptionsSet takes precedence. The call will fail if remoteAddress is 0. The destination IP address will not be changed. 5.8.28.7.1.6 TCPIP_UDP_IsConnected Function C bool TCPIP_UDP_IsConnected( UDP_SOCKET hUDP ); Description This function determines if a socket has an established connection to a remote node . Call this function after calling TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen() to determine when the connection is set up and ready for use. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3939 Parameters Parameters Description hUDP The socket to check. Return Values Return Values Description true The socket has been opened and ARP has been resolved. false The socket is not currently connected. Remarks None 5.8.28.7.1.7 TCPIP_UDP_OptionsGet Function C bool TCPIP_UDP_OptionsGet( UDP_SOCKET hUDP, UDP_SOCKET_OPTION option, void* optParam ); Description Various options can be get at the socket level. This function provides compatibility with BSD implementations. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP socket to get options for option specific option to get optParam pointer to an area that will receive the option value; this is option dependent the size of the area has to be large enough to accomodate the specific option UDP_OPTION_STRICT_PORT -- pointer to boolean UDP_OPTION_STRICT_NET -- pointer to boolean UDP_OPTION_BROADCAST -- UDP_SOCKET_BCAST_TYPE UDP_OPTION_BUFFER_POOL -- pointer to boolean UDP_OPTION_TX_BUFF -- pointer to a 16 bit value to receive bytes of the TX buffer UDP_OPTION_TX_QUEUE_LIMIT -- pointer to an 8 bit value to receive the TX queue limit Returns true if success false otherwise 5.8.28.7.1.8 TCPIP_UDP_OptionsSet Function C bool TCPIP_UDP_OptionsSet( UDP_SOCKET hUDP, UDP_SOCKET_OPTION option, void* optParam ); Description Various options can be set at the socket level. This function provides compatibility with BSD implementations. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3940 Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP socket to set options for option specific option to be set optParam the option value; this is option dependent UDP_OPTION_STRICT_PORT -- boolean enable/disable UDP_OPTION_STRICT_NET -- boolean enable/disable UDP_OPTION_BROADCAST -- UDP_SOCKET_BCAST_TYPE UDP_OPTION_BUFFER_POOL -- boolean enable/disable Returns true if success false otherwise Remarks changing the UDP_OPTION_BUFFER_POOL will discard the data in the current socket buffer UDP_OPTION_TX_BUFF -- 16 bit value in bytes of the TX buffer the UDP_OPTION_TX_BUFF will discard the data in the current socket buffer UDP_OPTION_TX_QUEUE_LIMIT -- 8 bit value of the TX queue limit 5.8.28.7.1.9 TCPIP_UDP_RemoteBind Function C bool TCPIP_UDP_RemoteBind( UDP_SOCKET hUDP, IP_ADDRESS_TYPE addType, UDP_PORT remotePort, IP_MULTI_ADDRESS* remoteAddress ); Description Sockets don't need specific remote binding, they should accept connections on any incoming interface. Thus the binding is done automatically by the stack. However, specific binding can be requested using these functions. For a server socket it can be used to restrict accepting connections from a specific remote host. For a client socket it will just change the default binding done when the socket was opened. TBD: the call should fail if the socket is already bound to an interface (a server socket is connected or a client socket already sent the data on an interface). Implementation pending Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP The socket to bind. addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. remotePort The remote port to bind to. remoteAddress Remote address to use. Returns True if success False otherwise 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3941 Remarks If remoteAddress == 0 the remote address of the socket won't be changed. The remote port is always changed, even if remotePort == 0. 5.8.28.7.1.10 TCPIP_UDP_ServerOpen Function C UDP_SOCKET TCPIP_UDP_ServerOpen( IP_ADDRESS_TYPE addType, UDP_PORT localPort, IP_MULTI_ADDRESS* localAddress ); Description Provides a unified method for opening UDP server sockets. Preconditions UDP is initialized. Parameters Parameters Description IP_ADDRESS_TYPE addType The type of address being used. Example: IP_ADDRESS_TYPE_IPV4. UDP_PORT localPort UDP port on which to listen for connections IP_MULTI_ADDRESS* localAddress Local address to use. Can be NULL if any incoming interface will do. Returns INVALID_SOCKET - No sockets of the specified type were available to be opened. Otherwise - A UDP_SOCKET handle. Save this handle and use it when calling all other UDP APIs. 5.8.28.7.1.11 TCPIP_UDP_SocketInfoGet Function C bool TCPIP_UDP_SocketInfoGet( UDP_SOCKET hUDP, UDP_SOCKET_INFO* pInfo ); Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description UDP_SOCKET hUDP Socket to obtain info for. UDP_SOCKET_INFO* pInfo pointer to reference info location. 5.8.28.7.1.12 TCPIP_UDP_SocketNetGet Function C TCPIP_NET_HANDLE TCPIP_UDP_SocketNetGet( UDP_SOCKET hUDP ); 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3942 Description This function returns the interface handle of an UDP socket Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP The UDP socket Returns IHandle of the interface that socket currently uses. 5.8.28.7.1.13 TCPIP_UDP_SocketNetSet Function C bool TCPIP_UDP_SocketNetSet( UDP_SOCKET hUDP, TCPIP_NET_HANDLE hNet ); Description This function sets the network interface for an UDP socket Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP The UDP socket hNet interface handle Returns true if success false otherwise. Remarks An invalid hNet can be passed (0) so that the current socket network interface selection will be cleared 5.8.28.7.1.14 TCPIP_UDP_SourceIPAddressSet Function C bool TCPIP_UDP_SourceIPAddressSet( UDP_SOCKET s, IP_ADDRESS_TYPE addType, IP_MULTI_ADDRESS* localAddress ); Description • It sets the IP source address This allows changing the source IPv4 address dynamically. Preconditions UDP initialized UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). s - valid socket localAddress - valid address pointer 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3943 Parameters Parameters Description s the UDP socket addType Type of address: IPv4/IPv6 localAddress pointer to an address to use Returns true if success false otherwise Remarks The call will fail if localAddress is 0. The source IP address will not be changed. 5.8.28.7.1.15 TCPIP_UDP_TxOffsetSet Function C bool TCPIP_UDP_TxOffsetSet( UDP_SOCKET hUDP, uint16_t wOffset, bool relative ); Description This function allows the write location within the TX buffer to be specified. Future calls to TCPIP_UDP_Put, TCPIP_UDP_ArrayPut, TCPIP_UDP_StringPut, etc will write data from the indicated location. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle wOffset Offset in the UDP packet data payload to move the write pointer. relative if true, the wOffset is added to the current write pointer. else the wOffset is from the beginning of the UDP buffer Returns true if the offset is a valid one false otherwise 5.8.28.7.2 Transmit Data Transfer Functions 5.8.28.7.2.1 TCPIP_UDP_ArrayGet Function C uint16_t TCPIP_UDP_ArrayGet( UDP_SOCKET hUDP, uint8_t * cData, uint16_t wDataLen ); Description This function reads an array of bytes from the UDP socket, while decrementing the remaining bytes available. TCPIP_UDP_GetIsReady could be used before calling this function to get the numberof the available bytes in the socket. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3944 Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle cData The buffer to receive the bytes being read. If NULL, the bytes are simply discarded without being written anywhere (effectively skips over the bytes in the RX buffer, although if you need to skip a lot of data, seeking using the TCPIP_UDP_RxOffsetSet() will be more efficient). wDateLen Number of bytes to be read from the socket. Returns The number of bytes successfully read from the UDP buffer. If this value is less than wDataLen, then the buffer was emptied and no more data is available. 5.8.28.7.2.2 TCPIP_UDP_Flush Function C uint16_t TCPIP_UDP_Flush( UDP_SOCKET hUDP ); Description This function builds a UDP packet with the pending TX data and marks it for transmission over the network interface. There is no UDP state machine to send the socket data automatically. The UDP socket client must call this function to actually send the data over the network. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle Returns The number of bytes that currently were in the socket TX buffer and have been flushed. Remarks Note that unlike TCPIP_TCP_Flush, TCPIP_UDP_Flush must be called before returning to the main stack loop. There is no auto transmit for UDP segments. 5.8.28.7.2.3 TCPIP_UDP_Put Function C uint16_t TCPIP_UDP_Put( UDP_SOCKET hUDP, uint8_t v ); Description This function writes a single byte to the UDP socket, while incrementing the buffer length. TCPIP_UDP_TxPutIsReady could be used before calling this function to verify that there is room in the socket buffer. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3945 Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle v The byte to be loaded into the transmit buffer. Return Values Return Values Description 1 The byte was successfully written to the socket. 0 The transmit buffer is already full and so the write failed. Remarks The following function is very inefficient. A buffered approach (TCPIP_UDP_ArrayPut) should be preferred 5.8.28.7.2.4 TCPIP_UDP_StringPut Function C const uint8_t* TCPIP_UDP_StringPut( UDP_SOCKET hUDP, const uint8_t * strData ); Description This function writes a null-terminated string to the UDP socket while incrementing the buffer length. TCPIP_UDP_TxPutIsReady could be used before calling this function to verify that there is room in the socket buffer. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle cData Pointer to the string to be written to the socket. Returns A pointer to the byte following the last byte written. Note that this is different than the TCPIP_UDP_ArrayPut functions. If this pointer does not dereference to a NULL byte, then the buffer became full and the input data was truncated. 5.8.28.7.2.5 TCPIP_UDP_TxCountGet Function C uint16_t TCPIP_UDP_TxCountGet( UDP_SOCKET hUDP ); Description This function returns the amount of bytes written into the UDP socket, Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3946 Parameters Parameters Description hUDP UDP socket handle 5.8.28.7.2.6 TCPIP_UDP_TxPutIsReady Function C uint16_t TCPIP_UDP_TxPutIsReady( UDP_SOCKET hUDP, unsigned short count ); Description This function determines how many bytes can be written to the specified UDP socket. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle count Number of bytes requested Returns The number of bytes that can be written to this socket. Remarks The function won't increase the size of the UDP TX buffer. If this is needed use TCPIP_UDP_OptionsSet(). The count variable is not used. 5.8.28.7.2.7 TCPIP_UDP_ArrayPut Function C uint16_t TCPIP_UDP_ArrayPut( UDP_SOCKET hUDP, const uint8_t * cData, uint16_t wDataLen ); Description This function writes an array of bytes to the UDP socket, while incrementing the buffer length. TCPIP_UDP_TxPutIsReady could be used before calling this function to verify that there is room in the socket buffer. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description cData The array to write to the socket. wDateLen Number of bytes from cData to be written. Returns The number of bytes successfully placed in the UDP transmit buffer. If this value is less than wDataLen, then the buffer became 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3947 full and the input was truncated. 5.8.28.7.2.8 UDPIsPutReady Function C uint16_t UDPIsPutReady( UDP_SOCKET hUDP ); Description This function determines how many bytes can be written to the specified UDP socket. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle Returns The number of bytes that can be written to this socket. Remarks The function is similar to the TCPIP_UDP_TxPutIsReady and maintained for backward compatibility. 5.8.28.7.3 Receive Data Transfer Functions 5.8.28.7.3.1 TCPIP_UDP_Discard Function C void TCPIP_UDP_Discard( UDP_SOCKET hUDP ); Description This function discards any remaining received data in the UDP socket. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP socket handle Returns None Remarks It is safe to call this function more than is necessary. If no data is available, this function does nothing. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3948 5.8.28.7.3.2 TCPIP_UDP_Get Function C uint16_t TCPIP_UDP_Get( UDP_SOCKET hUDP, uint8_t * v ); Description This function reads a single byte from the UDP socket, while decrementing the remaining buffer length. TCPIP_UDP_GetIsReady could be used before calling this function to get the number of bytes available in the socket. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP socket handle v The buffer to receive the data being read. Return Values Return Values Description 1 A byte was successfully read 0 No data remained in the read buffer or invalid socket Remarks The following function is very inefficient. A buffered approach (TCPIP_UDP_ArrayGet) should be preferred 5.8.28.7.3.3 TCPIP_UDP_GetIsReady Function C uint16_t TCPIP_UDP_GetIsReady( UDP_SOCKET hUDP ); Description This function determines if bytes can be read from the specified UDP socket. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle Returns The number of bytes that can be read from this socket. 5.8.28.7.3.4 TCPIP_UDP_RxOffsetSet Function C void TCPIP_UDP_RxOffsetSet( UDP_SOCKET hUDP, 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3949 uint16_t rOffset ); Description This function allows the read location within the RX buffer to be specified. Future calls to TCPIP_UDP_Get and TCPIP_UDP_ArrayGet will read data from the indicated location forward. Preconditions UDP socket should have been opened with TCPIP_UDP_ServerOpen()/TCPIP_UDP_ClientOpen()(). hUDP - valid socket Parameters Parameters Description hUDP UDP socket handle wOffset Offset from beginning of UDP packet data payload to place the read pointer. Returns None 5.8.28.7.4 Data Types and Constants 5.8.28.7.4.1 INVALID_UDP_SOCKET Macro C #define INVALID_UDP_SOCKET (-1) // Indicates a UDP socket that is not valid Description Indicates a UDP socket that is not valid 5.8.28.7.4.2 TCPIP_UDP_IsOpened Macro C #define TCPIP_UDP_IsOpened(s) TCPIP_UDP_IsConnected(s) Description backward compatibility call 5.8.28.7.4.3 UDP_MODULE_CONFIG Structure C typedef struct { uint16_t nSockets; uint16_t sktTxBuffSize; uint16_t poolBuffers; uint16_t poolBufferSize; } UDP_MODULE_CONFIG; Description UDP layer configuration/initialization Members Members Description uint16_t nSockets; number of sockets to be created 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3950 uint16_t sktTxBuffSize; size of the socket tx buffer uint16_t poolBuffers; number of buffers in the pool; 0 if none uint16_t poolBufferSize; size of the buffers in the pool; all equal 5.8.28.7.4.4 UDP_PORT Type C typedef uint16_t UDP_PORT; Description Stores a UDP Port Number 5.8.28.7.4.5 UDP_SOCKET Type C typedef int16_t UDP_SOCKET; Description Provides a handle to a UDP Socket 5.8.28.7.4.6 UDP_SOCKET_BCAST_TYPE Enumeration C typedef enum { UDP_BCAST_NONE, UDP_BCAST_NETWORK_LIMITED, UDP_BCAST_NETWORK_DIRECTED } UDP_SOCKET_BCAST_TYPE; Description This is type UDP_SOCKET_BCAST_TYPE. Members Members Description UDP_BCAST_NONE no broadcast UDP_BCAST_NETWORK_LIMITED network limited broadcast UDP_BCAST_NETWORK_DIRECTED network directed broadcast 5.8.28.7.4.7 UDP_SOCKET_INFO Structure C typedef struct { IP_ADDRESS_TYPE addressType; IP_MULTI_ADDRESS remoteIPaddress; IP_MULTI_ADDRESS localIPaddress; UDP_PORT remotePort; UDP_PORT localPort; } UDP_SOCKET_INFO; Description Information about a socket 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3951 Members Members Description UDP_PORT remotePort; Port number associated with remote node UDP_PORT localPort; local port number 5.8.28.7.4.8 UDP_SOCKET_OPTION Enumeration C typedef enum { UDP_OPTION_STRICT_PORT, UDP_OPTION_STRICT_NET, UDP_OPTION_BROADCAST, UDP_OPTION_BUFFER_POOL, UDP_OPTION_TX_BUFF, UDP_OPTION_TX_QUEUE_LIMIT } UDP_SOCKET_OPTION; Description UDP socket options Members Members Description UDP_OPTION_STRICT_PORT When connection is done the socket stores the remote host local port. If option is enabled the remote host local port is always checked to match the initial one. If disabled the remote host local port is not checked. Disabled by default on a socket server. Enabled by default on a client socket. UDP_OPTION_STRICT_NET When connection is done the socket stores th enetwork interface the connection occurred on. If option is enabled the socket accepts data only from the interface that matches the initial connection. If disabled the socket receives data from any remote host irrespective of the interface on which the packet arrived. Disabled by default on a socket server. Enabled by default on a client socket. UDP_OPTION_BROADCAST Enables the Broadcast transmission by the socket UDP_OPTION_BUFFER_POOL Enables the socket to use the private UDP buffers pool. The size of the TX buffer has to be less than the size of the buffers in the pool UDP_OPTION_TX_BUFF request different TX buffer size. Has to call TCPIP_UDP_OptionsGet to see the exact space allocated UDP_OPTION_TX_QUEUE_LIMIT Sets the maximum number of packets that can be queued/allocated by an UDP socket at a certain time. For sockets that need to transmit a lot of data (iperf client, for example), especially on slow conenctions this limit prevents running out of memory because the MAC transfer cannot keep up with the UDP packet allocation rate imposed by the aapplication. Adjust depending on the size of the UDP TX buffer, the connection speed and the amount of memory available to the stack. 5.8.28.8 Files Files Name Description udp.h udp_config.h UDP onfiguration file Description 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3952 5.8.28.8.1 udp.h UDP Module Defs for Microchip TCP/IP Stack Enumerations Name Description UDP_SOCKET_BCAST_TYPE This is type UDP_SOCKET_BCAST_TYPE. UDP_SOCKET_OPTION UDP socket options Functions Name Description TCPIP_UDP_ArrayGet Reads an array of bytes from the UDP socket. TCPIP_UDP_ArrayPut Writes an array of bytes to the UDP socket. TCPIP_UDP_BcastIPV4AddressSet Sets the broadcast IP address of a socket Allows an UDP socket to send broadcasts. TCPIP_UDP_Bind Bind a socket to a local address and port. This function is meant for client sockets. It assigns a specific source address and port for a socket. TCPIP_UDP_ClientOpen Opens a UDP socket as a client. TCPIP_UDP_Close Closes a UDP socket and frees the handle. TCPIP_UDP_DestinationIPAddressSet Sets the destination IP address of a socket TCPIP_UDP_Discard Discards any remaining RX data from a UDP socket. TCPIP_UDP_Flush Transmits all pending data in a UDP socket. TCPIP_UDP_Get Reads a byte from the UDP socket. TCPIP_UDP_GetIsReady Determines how many bytes can be read from the UDP socket. TCPIP_UDP_IsConnected Determines if a socket has an established connection. TCPIP_UDP_OptionsGet Allows getting the options for a socket like: current Rx/Tx buffer size, etc TCPIP_UDP_OptionsSet Allows setting options to a socket like adjust Rx/Tx buffer size, etc TCPIP_UDP_Put Writes a byte to the UDP socket. TCPIP_UDP_RemoteBind Bind a socket to a remote address This function is meant for server sockets. TCPIP_UDP_RxOffsetSet Moves the pointer within the RX buffer. TCPIP_UDP_ServerOpen Opens a UDP socket as a server. TCPIP_UDP_SocketInfoGet Points handle at socket unfo for socket hUDP TCPIP_UDP_SocketNetGet Gets the network interface of an UDP socket TCPIP_UDP_SocketNetSet Sets the network interface for an UDP socket TCPIP_UDP_SourceIPAddressSet Sets the source IP address of a socket TCPIP_UDP_StringPut Writes null-terminated string to the UDP socket. TCPIP_UDP_TxCountGet Returns the amount of bytes written into the UDP socket. TCPIP_UDP_TxOffsetSet Moves the pointer within the TX buffer. TCPIP_UDP_TxPutIsReady Determines how many bytes can be written to the UDP socket. UDPIsPutReady Determines how many bytes can be written to the UDP socket. Macros Name Description INVALID_UDP_SOCKET Indicates a UDP socket that is not valid TCPIP_UDP_IsOpened backward compatibility call 5.8 TCP/IP Stack Library Help MPLAB Harmony Help UDP TCP/IP Stack Library 5-3953 Structures Name Description UDP_MODULE_CONFIG UDP layer configuration/initialization UDP_SOCKET_INFO Information about a socket Types Name Description UDP_PORT Stores a UDP Port Number UDP_SOCKET Provides a handle to a UDP Socket 5.8.28.8.2 udp_config.h User Datagram Protocol (UDP) Configuration file This file contains the UDP module configuration options Macros Name Description UDP_LOCAL_PORT_END_NUMBER Last port number for randomized local port number selection UDP_LOCAL_PORT_START_NUMBER The dynamic port range defined by IANA consists of the 49152-65535 range and is meant for the selection of ephemeral ports (RFC 6056). Adjust to your needs but stay within the IANA range First port number for randomized local port number selection UDP_MAX_SOCKETS global number of UDP sockets created dynamically UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT the maximum number of packets that can be queued by an UDP socket at a certain time. For sockets that need to transfer a lot of data (iperf, for example), especially on slow conenctions this limit prevents running out of memory because the MAC transfer cannot keep up with the UDP packet allocation rate imposed by the aapplication. Adjust depending on the UDP_SOCKET_DEFAULT_TX_SIZE, the connection speed and the amount of memory available to the stack. UDP_SOCKET_DEFAULT_TX_SIZE default socket Tx buffer size UDP_SOCKET_POOL_BUFFER_SIZE size of the buffers in the UDP pool any UDP socket that is enabled to use the pool and has the TX size <= than this size can use a buffer from the pool UDP_SOCKET_POOL_BUFFERS use 0 to disable the feature UDP_USE_RX_CHECKSUM check incoming packets to have proper checksum UDP_USE_TX_CHECKSUM This slows UDP TX performance by nearly 50%, except when using the ENCX24J600, which has a super fast DMA and incurs virtually no speed pentalty. 5.8.29 Zeroconf TCP/IP Stack Library 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3954 5.8.29.1 Introduction Zero Configuration (Zeroconf) TCP/IP Stack Library for Microchip Microcontrollers This library provides the API of the Zero Conf TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Zero configuration (Zeroconf), provides a mechanism to ease the configuration of a device on a network. It also provides for a more human-like naming convention, instead of relying on IP addresses alone. Zeroconf also goes by the names Bonjour (Apple) and Avahi (Linux), and is an IETF standard. 5.8.29.2 Release Notes MPLAB Harmony Version: v0.70b Zero Conf TCP/IP Stack Library Version : 1.0 Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.8.29.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.8.29.4 Using the Library This topic describes the basic architecture of the Zeroconf TCP/IP Stack Library and provides information and examples on how to use it. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3955 Interface Header Files: zero_conf_helper.h, zero_conf_link_local.h, and zero_conf_multicast_dns.h The interface to the Zeroconf TCP/IP Stack library is defined in the "zero_conf_helper.h", "zero_conf_link_local.h", and "zero_conf_multicast_dns.h" header files. This file is included by the "tcpip.h" file. Any C language source (.c) file that uses the Zeroconf TCP/IP Stack library should include "tcpip.h". Library File: The Zeroconf TCP/IP Stack library archive (.a) file installed with MPLAB Harmony. Please refer to the MPLAB Harmony Overview for how the TCP/IP Stack interacts with the framework. 5.8.29.4.1 Abstraction Model This library provides the API of the Zeroconf TCP/IP Module that is available on the Microchip family of microcontrollers with a convenient C language interface. It is a module that belongs to the TCP/IP stack. Description Zero Conf Software Abstraction Block Note: This image was not available at time of release and will be added in a future release of MPLAB Harmony. 5.8.29.4.2 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Zeroconf module. Library Interface Section Description Multicast DNS Functions This section provides multicast DNS interface routines to Zeroconf Link Local Functions This section provides Link Local interface routines to Zeroconf Data Types and Constants This section provides various definitions describing this API 5.8.29.4.3 Core Functionality 5.8.29.4.3.1 Enabling Zeroconf can be enabled by setting the following two defines in TCPIPConfig.h: • STACK_USE_ZEROCONF_LINK_LOCAL • STACK_USE_ZEROCONF_MDNS_SD Currently, the use of Zeroconf is limited to the W-iFi demo applications (and the MRF24WB0M module). Future versions of the stack should enable Zeroconf support across all Ethernet solutions. 5.8.29.4.3.2 Link Local (Zeroconf) The first component of Zeroconf is the ability to self-assign an IP address to each member of a network. Normally, a DHCP server would handle such situations. However, in cases where no DHCP server exists, Zeroconf enabled devices negotiate unique IP addresses amongst themselves. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3956 5.8.29.4.3.3 mDNS The second component of Zeroconf is the ability to self-assign human-readable hostnames for themselves. Multicast DNS provides a local network the ability to have the features of a DNS server. Users can use easily remembered hostnames to accesses the devices on the network. In the event that devices elect to use the same hostname, as in the IP address resolution, each of the devices will auto-negotiate new names for themselves (usually by appending a number to the end of the name). 5.8.29.4.3.4 Service Discovery The last component of Zeroconf is service discovery. All Zeroconf devices can broadcast what services they provide. For instance, a printer can broadcast that it has printing services available. A thermostat can broadcast that it has an HVAC control service. Other interested parties on the network who are looking for certain services can then see a list of devices that have the capability of providing the service, and connect directly to it. This further eliminates the need to know whether something exists on a network (and what it's IP or hostname is). As an end-user, all you would need to do is query the network if a certain service exists, and easily connect to it. 5.8.29.4.3.5 Demonstration The demo, when enabled, shows all three items above working together. Each development kit in the network assumes the hostname of MCHPBOARD-x.local, where x is an incrementing number from 1 (only in the case where multiple kits are programmed for the network). Each board will broadcast it's service, which is the DemoWebServer. 5.8.29.4.3.6 Zeroconf Enabled Environments All Apple products have Zeroconf enabled by default. On Windows, you'll need to download the Safari web browser, and during the install, enable support for Bonjour. Note that in the Safari browser, you can browse and see a list of all Bonjour enabled devices, and click through to them automatically. 5.8.29.5 Configuring the Library The configuration of the Zeroconf TCP/IP Stack Library is based on the file tcpip_config.h This header file contains the configuration selection for the Zeroconf TCP/IP Stack Library. Based on the selections made, the Zeroconf TCP/IP Stack Library will support or not support selected features. These configuration settings will apply to all instances of the Zeroconf TCP/IP Stack Library. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. 5.8.29.6 Building the Library This section list the files that are available in the \src of the Zeroconf driver. It lists which files need to be included in the build based on either a hardware feature present on the board or configuration option selected by the system. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3957 5.8.29.7 Library Interface Data Types and Constants Name Description MDNSD_ERR_CODE void DisplayHostName(uint8_t *HostName); ZCLL_MODULE_CONFIG Placeholder for Zero Configuration Link Layer module configuration. Link Local Functions Name Description TCPIP_ZCLL_Disable disables the ZCLL on an interface TCPIP_ZCLL_Enable enables ZCLL on an interface TCPIP_ZCLL_IsEnabled returns true if ZCLL is currently enabled on that interface Multicast DNS Functions Name Description TCPIP_MDNS_ServiceDeregister DNS-Service Discovery API for end-user to De-register a service-advertisement, which was previously registered with TCPIP_MDNS_ServiceRegister API. TCPIP_MDNS_ServiceRegister DNS-Service Discovery API for end-users to register a service-advertisement. The service is associated with all interfaces. TCPIP_MDNS_ServiceUpdate DNS-Service Discovery API for end-user to update the service -advertisement, which was previously registered with TCPIP_MDNS_ServiceRegister Description This section describes the Application Programming Interface (API) functions of the Zeroconf TCP/IP Stack. Refer to each section for a detailed description. 5.8.29.7.1 Multicast DNS Functions 5.8.29.7.1.1 TCPIP_MDNS_ServiceDeregister Function C MDNSD_ERR_CODE TCPIP_MDNS_ServiceDeregister( TCPIP_NET_HANDLE netH ); Description This API is used by end-user application to de-register DNS-Service Discovery on a local network. When this gets invoked by end-user DNS-SD stack sends out Good-Bye packets to update all peer machines that service will no longer be present. All peer machines remove the corresponding entry from Browser list. This is the last API that needs to be invoked by end-user application to free-up the DNS-SD stack for some other app. Preconditions TCPIP_MDNS_ServiceRegister must be invoked before this call. Parameters Parameters Description netH handle of the network to be de-registered 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3958 Returns MDNSD_ERR_CODE - Returns Error-code to indicate registration is success or not. 1) MDNSD_SUCCESS - returns on success of call 2) MDNSD_ERR_INVAL - When the input parameters are invalid or if the API is invoked in invalid state 5.8.29.7.1.2 TCPIP_MDNS_ServiceRegister Function C MDNSD_ERR_CODE TCPIP_MDNS_ServiceRegister( TCPIP_NET_HANDLE netH, const char * srv_name, const char * srv_type, uint16_t port, const uint8_t * txt_record, uint8_t auto_rename, void (*call_back)(char *name, MDNSD_ERR_CODE err, void *context), void * context ); Description DNS-Service Discovery APIs ************************************************************ This API is used by end-user application to announce its service on local network. All peer machines that are compliant with Multicast-DNS & DNS-Service Discovery protocol can detect the announcement and lists out an entry in Service-Browser list. End-User selects an entry to connect to this service. So ultimately this is an aid to end-user to discover any service of interest on a local network. This is the first API that needs to be invoked by end-user application. Presently Multicast-DNS & Service-discovery stack supports only single service-advertisement. Once the application wants to terminate the service it has to invoke TCPIP_MDNS_ServiceDeregister() API to free-up the DNS-SD stack for some other application. Preconditions None Parameters Parameters Description netH handle of the network to be registered srv_name Service Name, which is being advertised srv_type For a HTTP-Service its "_http._tcp.local" _http is application protocol preceeded with under-score _tcp is lower-layer protocol on which service runs local is to represent service is on local-network For a iTunes Music Sharing "_daap._tcp.local" For a Priniting Service "_ipp._tcp.local" Refer to http://www.dns-sd.org/ServiceTypes.html for more service types port Port number on which service is running txt_len For additional information about service like default page (eg "index.htm") for HTTP-service. Length of such additional information txt_record String of additional information (eg "index.htm") for HTTP-service. auto_rename A flag to indicate DNS-SD stack, whether to rename the service automatically or not. If this is set to '0' Callback parameter will be used to indicate the conflict error and user has to select different name and re-register with this API. If this is set to '1' service-name will be automatically renamed with numerical suffix. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3959 callback Callback function, which is user-application defined. This callback gets invoked on completion of service advertisement. If an service name-conflit error is detected and auto_rename is set to '0' callback gets invoked with MDNSD_ERR_CONFLICT as error-code. context Opaque context (pointer to opaque data), which needs to be used in callback function. Returns MDNSD_ERR_CODE - Returns Error-code to indicate registration is success or not. 1) MDNSD_SUCCESS - returns on success of call 2) MDNSD_ERR_BUSY - When already some other service is being advertised using this DNS-SD stack 3) MDNSD_ERR_INVAL - Invalid Parameter 5.8.29.7.1.3 TCPIP_MDNS_ServiceUpdate Function C MDNSD_ERR_CODE TCPIP_MDNS_ServiceUpdate( TCPIP_NET_HANDLE netH, uint16_t port, const uint8_t * txt_record ); Description This API is used by end-user application to update its service which was previously registered. With this API end-user app update the port number on which the service is running. It can update the additional information of service. For example: the default page can be updated to new page and corresponding page name can be input to this API to update all peer machines. The modified service will be announced with new contents on local network. This is an optional API and hsould be invoked only if it is necessary. Preconditions TCPIP_MDNS_ServiceRegister must be invoked before this call. Parameters Parameters Description netH handle of the network to perform the service update port Port number on which service is running txt_record String of additional information (eg "index.htm") for HTTP-service. Returns MDNSD_ERR_CODE - Returns Error-code to indicate registration is success or not. 1) MDNSD_SUCCESS - returns on success of call 2) MDNSD_ERR_INVAL - When the input parameters are invalid or if the API is invoked in invalid state 5.8.29.7.2 Link Local Functions 5.8.29.7.2.1 TCPIP_ZCLL_Disable Function C bool TCPIP_ZCLL_Disable( TCPIP_NET_HANDLE hNet ); Description disables the ZCLL on an interface 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3960 5.8.29.7.2.2 TCPIP_ZCLL_Enable Function C bool TCPIP_ZCLL_Enable( TCPIP_NET_HANDLE hNet ); Description enables ZCLL on an interface 5.8.29.7.2.3 TCPIP_ZCLL_IsEnabled Function C bool TCPIP_ZCLL_IsEnabled( TCPIP_NET_HANDLE hNet ); Description returns true if ZCLL is currently enabled on that interface 5.8.29.7.3 Data Types and Constants 5.8.29.7.3.1 MDNSD_ERR_CODE Enumeration C typedef enum { MDNSD_SUCCESS = 0, MDNSD_ERR_BUSY = 1, MDNSD_ERR_CONFLICT = 2, MDNSD_ERR_INVAL = 3 } MDNSD_ERR_CODE; Description void DisplayHostName(uint8_t *HostName); Members Members Description MDNSD_ERR_BUSY = 1 Already Being used for another Service MDNSD_ERR_CONFLICT = 2 Name Conflict MDNSD_ERR_INVAL = 3 Invalid Parameter 5.8.29.7.3.2 ZCLL_MODULE_CONFIG Structure C typedef struct { } ZCLL_MODULE_CONFIG; Description Placeholder for Zero Configuration Link Layer module configuration. 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3961 5.8.29.8 Files Files Name Description zero_conf_link_local.h zero_conf_multicast_dns.h This is file zero_conf_multicast_dns.h. Description 5.8.29.8.1 zero_conf_link_local.h Zero Confiruation (Zeroconf) IPV4 Link Local Addressing Module for Microchip TCP/IP Stack Functions Name Description TCPIP_ZCLL_Disable disables the ZCLL on an interface TCPIP_ZCLL_Enable enables ZCLL on an interface TCPIP_ZCLL_IsEnabled returns true if ZCLL is currently enabled on that interface Structures Name Description ZCLL_MODULE_CONFIG Placeholder for Zero Configuration Link Layer module configuration. 5.8.29.8.2 zero_conf_multicast_dns.h This is file zero_conf_multicast_dns.h. Enumerations Name Description MDNSD_ERR_CODE void DisplayHostName(uint8_t *HostName); Functions Name Description TCPIP_MDNS_ServiceDeregister DNS-Service Discovery API for end-user to De-register a service-advertisement, which was previously registered with TCPIP_MDNS_ServiceRegister API. TCPIP_MDNS_ServiceRegister DNS-Service Discovery API for end-users to register a service-advertisement. The service is associated with all interfaces. TCPIP_MDNS_ServiceUpdate DNS-Service Discovery API for end-user to update the service -advertisement, which was previously registered with TCPIP_MDNS_ServiceRegister 5.8 TCP/IP Stack Library Help MPLAB Harmony Help Zeroconf TCP/IP Stack Library 5-3962 5.9 USB Library Help 5.9.1 USB Device Library - Getting Started 5.9.1.1 Introduction Provides an introduction to the MPLAB Harmony USB Device Library Description The MPLAB Harmony USB Device Library (referred to as the USB Device Library) provides embedded application developers with a framework to design and develop a wide variety of USB Devices. A choice of Full Speed only or Full Speed and Hi-Speed USB operations are available, depending on the selected PIC32 microcontroller. The USB Device Library facilitates development of standard USB devices through function drivers that implement standard USB Device class specification. Custom USB devices can also be implemented via a Generic Function driver. The USB Device Library is modular, thus allowing application developers to readily design composite USB devices. The USB Device Library is a part of the MPLAB Harmony installation and is accompanied by demonstration applications that highlight library usage. These demonstrations can also be modified or updated to build custom applications. The USB Device Library also features the following: - Support for different USB device classes (CDC, Audio, HID, MSC and Generic) - Supports multiple instance of the same class in a composite device - Supports multiple configurations at different speeds - Supports full speed and high speed operation - Supports multiple USB peripherals (allows multiple device stacks) - Modular and Layered architecture - Supports deferred control transfer responses. - Completely non-blocking - Supports both polled and interrupt operation. - Works readily in an RTOS environment. This document serves as getting started guide and provides information on the following: - USB Device Stack Architecture - USB Device Library - Application Interaction - Creating your own USB device Note: This document assumes that the reader is familiar with the USB 2.0 specification (available at www.usbif.org). While the document, for the sake completeness, does cover certain aspects of the USB 2.0 protocol, it is recommended that the reader 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3963 refer to the specification for a complete description of USB operation. 5.9.1.2 Release Notes MPLAB Harmony Version: v0.70b Release Date: 18Nov2013 New This Release: Nothing to report in this release. Known Issues: • USB Device Stack: • Limited USB chapter 9 testing performed on HID and MSD function drivers. • The stack has not been tested for USB Interoperability. • The USB Device Stack has not been tested with a Real Time Operating System. • Attach/Detach behavior has been tested in a limited capacity. • The device stack only supports interrupt mode operation. Polled mode operation will be added in a future release. • While running the device stack on PIC32MZ microcontroller, the stack requires 3 seconds to initialize. This is due to a hardware issue with PIC32MZ USB module. • Device stack operation has been tested with Windows XP and Windows 7 OS based PC USB Host. • The USB_DEVICE_ResumeStart() and USB_DEVICE_ResumeStop() functions are not implemented. • USB Host Stack: • The host Stack has not been tested with a Real Time Operating System. • Attach/Detach behavior has been tested in a limited capacity. • The host stack only supports interrupt mode operation. Polled mode operation will be added in a future release. • While running the host stack on PIC32MZ microcontroller, the stack requires 3 seconds to initialize. This is due to a hardware issue with PIC32MZ USB module. The 3 second delay is implemented using a while loop. This will replaced with System Timer services in the next release. • MSD Host has been tested with a limited number of commercially available USB Flash Drives. • MSD Host and the USB Host Layer have not been tested for read/write throughput. This will be done in a future release. • Host stack has not been tested with low speed devices. • The PIC32MZ host layer performs direct access of Timer 2 peripheral SFR, for its timing requirements. This will be replaced with Harmony System Timer services in the next release of the host stack. • USB_HOST_DeviceSuspend() and the USB_HOST_DeviceResume() functions are not implemented. 5.9.1.2.1 Previous Versions 5.9.1.2.1.1 v0.51b Release notes for version 0.51b of the MPLAB Harmony USB Stack. Description New features in this release: 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3964 • Added Device Stack support for Mass Storage device class. • Added Device Stack support for Audio Device class. • Added demonstration applications for Audio and Mass Storage Device classes. • Added support for PIC32MZ devices and High Speed operation. • HID Basic Demonstration application tested for USB 2.0 chapter-9 conformance. • MSD Basic Demonstration application tested for USB2.0 chapter-9 conformance. • First Release of Host Layer and CDC Host Driver along with a demonstration application. Limitations and Known Issues: The following are the known issues in this release. These issues will be fixed in the subsequent releases of the MPLAB Harmony USB Stack. • The USB device stack is tested with Windows environment only. Performance and working of the device stack is not tested with other OS environments. • The stack is not thoroughly tested for inter operability with other USB devices when connected to hub along with other devices. • All demos are tested in dynamic interrupt mode only. • Limited testing is done with hub. • Limited testing is done with RTOS. • APIs may change in subsequent releases and are not final. • PIC32MZ USB Driver supports only on instance of the USB peripheral. • The Mass Storage Device Class demonstration application works with Windows XP OS only. • The Audio Speaker demo may not restart audio playback if the playback is paused from the PC. • The CDC Host layer has been in tested in a limited capacity. • PIC32MZ and Hi-Speed USB support is tested with CDC and HID device classes only. • HID Keyboard demonstration application does not receive output report from PC USB host. 5.9.1.2.1.2 v0.51.02b Release notes for the current version of the MPLAB Harmony USB Stack Description New features in this release: • Updated documentation to include a Getting Started with USB Device Library. • Updated the documentation for CDC and HID Function Drivers. Improved code size and RAM requirement of the demos. • The following issues from the v0.51b are fixed in this release • HID Keyboard demonstration application does not receive output report from PC USB host. • The Audio Speaker demo may not restart audio playback if the playback is paused from the PC. • The Mass Storage Device Class demonstration application works with Windows XP OS only. The demo now works with Windows 7. Limitations and Known Issues: The following are the known issues in this release. These issues will be fixed in the subsequent releases of the MPLAB Harmony USB Stack. • The USB device stack is tested with Windows environment only. Performance and working of the device stack is not tested with other OS environments. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3965 • The stack is not thoroughly tested for inter operability with other USB devices when connected to hub along with other devices. • All demos are tested in dynamic interrupt mode only. • Limited testing is done with hub. Limited testing is done with RTOS. • Audio Speaker demo may not work with all USB Hosts. This has been observed with faster PC Hosts. • APIs are not final and may change in subsequent releases. • PIC32MZ USB Driver supports only on instance of the USB peripheral. • The CDC Host layer has been in tested in a limited capacity. • PIC32MZ and Hi-Speed USB support is tested with CDC and HID device classes only. • Polling operation is not implemented • Static USB Controller Driver is not available. 5.9.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.1.4 USB Device Library Architecture Describes the USB Device Library Architecture. Description The USB Device Library features a modular and layered architecture. This is shown in figure 1. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3966 Figure 1: USB Device Library Architecture As seen in figure 1, the USB Device Library consists of the 3 major components 1. The USB Controller Driver (USBCD) manages the state of the USB peripheral and provides the Device Layer with structured data access methods to the USB. It also provides the device layer with USB events. The USBCD is a MPLAB Harmony driver and uses the Harmony framework components (the USB peripheral Library, the Interrupt System Service) for its operation. It supports only one client per instance of the USB Peripheral. This client would typically be the Device Layer. In case of multiple USB peripherals, the USBCD can manage multiple USB peripherals, each being accessed by one client. The driver is accessed exclusively by the Device Layer in the USB Device Layer Architecture. It is initialized by the Device Layer (when the Device Layer is initialized) and in case of polling operation, it's Tasks routine is called by the Device Layer. The USBCD provides functions to - enable, disable and stall endpoints - schedule USB transfers. - attach or detach the device - control resume signalling 2. The Device Layer responds to the enumeration requests issued by the USB host. It has exclusive access to an instance of the USBCD and Endpoint 0 which is the control endpoint. When the host issues a class specific control transfer request, the Device Layer will analyze the setup packet of the control transfer and will route the control transfer to the appropriate function driver. The Device Layer must be initialized with the following data: - Master Descriptor Table: This is a table of all the configuration descriptors and string descriptors. - Function Driver Registration Table : This table contains information about the function drivers in the application - USBCD initialization information: This specifies the USB peripheral interrupt, the USB Peripheral instance and sleep mode operation options. The Device Layer initializes all function drivers that are registered with it when it receives a Set Configuration (for a supported configuration) from the host. It de-initializes the function drivers when a USB reset event occurs. It initializes the USBCD, opens it and registers a event handler to receive USB events. The Device Layer can also be opened by the application (the application 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3967 becomes a client to the Device Layer). The application can then receive bus and device events and respond to control transfer requests. The Device Layer provides events to the application such as device configured or device reset. The application must then respond appropriately to these events. 3. The Function Drivers implements various USB device classes as per the class specification. The USB Device Library architecture can support multiple instances of a function driver. An example would be a USB CDC device that emulates 2 serial ports. Function drivers provide an abstracted and an easy to use interface to the application. The application must register an event handler with the function driver to receive function driver events and must respond to some of these events with control transfer read/write functions. Function driver access the bus through the Device Layer. 5.9.1.5 USB Device Library - Application Interaction Describes how the application must interact with the USB Device Stack Description Figure 2 highlights the steps that the application must follow in order to use the USB Device Library. Figure 2: Application Interaction with Device Layer The application must first initialize the Device Layer. As a part of the Device Layer initialization process, the Device Layer initialization structure must be defined which in turn requires the following data structures to be designed - The master descriptor table - The function driver registration table Figure 3 shows a pictorial representation of the data that forms the Device Layer initialization structure. Additional information on Device Layer initialization is available in the Device Layer Help File. Figure 3. Device Layer Initialization After successful initialization of the device layer, the application can open the device layer and register a device layer event handler. The device layer event handler receives device level events such as device configured, device de-configured, device reset and device suspended. The device configured event and de-configured event are important. The application can use the device deconfigured event to re-initialize its internal state machine. When the application receives a device configured event, it must register event handlers for each function driver that is relevant to the configuration that was set. The function driver event handler registration must be done in the device configured event context because the device layer acknowledges the set configuration request from the host when it exits the device configured event handler context. The application at this point should be ready to respond to function driver events which require application intervention. Note: Not registering the function driver event handler in the device layer device configured event could cause the device to not 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3968 respond to the host requests and hence be non-compliant. Once configured, the device is now ready to serve it intended function on the USB. The application interacts with the device layer and function drivers through API function and event handlers. The application must be aware of function driver events which require application response. For example, the USB_DEVICE_CDC_EVENT_SET_LINE_CODING event from the CDC Function Driver requires the application to respond with a USB_DEVICE_CDC_ControlRead() function. This function provides the buffer to accept the line coding parameters that the host will be provide in the data stage of the Set Line Coding control transfer. Figure 4 shows the application interaction with device layer and function driver after the device has been configured. Figure 4: Application - Device Layer Interaction after device configuration In figure 4, the application should have registered the device layer event handler before attaching the device on the bus. It should have registered the function driver event handler before exiting the device configured - device layer event. The application will then receive function driver instance specific events via the function driver event handlers. Deferring Control Transfer Responses: Some function driver events require the application to respond to the data stage and/or the status stage of the function driver (class) specific control transfer associated with the event. The application responds to the data stage by specifying a buffer that either contains the data that needs to sent to host (control read) or will contain the data that host sends to the device (control write). In case of a control write, the application may wish to inspect the data which was received from the host and the acknowledge or stall the status stage of the control transfer. In such cases, it is possible that the application may not be ready within the function driver event handler context, with data that needs to be sent in the control read transfer or the success/ failure decision in response to the control write transfer. Performing extended processing or waiting for external hardware within the function driver event handler context is not recommended as USB 2.0 specification places restrictions on the control transfer response time. In cases where the application is not ready to respond to control transfer requests within the function driver event handler context, the USB Device Library provides the option of deferring the response to the event. The application can respond to the control transfer request out of function driver event handler context. The function driver generates a control transfer handle, which the application must use while responding to the function driver event outside the event handler context. The application must still observe the USB 2.0 specification control transfer timing requirements while responding to the control transfer. Deferring the response in such a manner provides the application with flexibility to analyze the control transfer without affecting the dynamic response of the device. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3969 5.9.1.6 Creating Your Own USB Device Describes how to create a USB device with MPLAB Harmony USB Device Library Description The first step in creating a USB device is identifying if the desired device function fits into any of the standard USB device class functions. Using standard USB classes may be advantageous as major operating systems feature ready Host driver support for standard USB devices. The application may however not wish to tolerate the overhead associated with standard USB device class protocols, in which case, a custom USB device can be implemented. A custom USB device can be implemented by using the Generic Device function driver in the USB Device Library, but these devices will requires development of host drivers for their operation. Having identified the device class to be used, the following approaches are available for developing a USB device by using the USB Device Library. 1. Use the available library demonstration applications. The USB Device Library release package contains a set of demo applications which are representative of common USB devices. These can be modified easily to include application specific initialization and application logic. The application logic must be non-blocking and could be implemented as a state machine. - The application specific initialization can be called in the SYS_Initialize() function (in the sys_init.c file). The SYS_Initialize is called when the device comes out of power on reset. - The application logic can be called in the SYS_Tasks() function (in the sys_tasks.c file). The application logic can interact with the function driver and the device layer by using relevant API calls. - The application logic can track device events by processing the events in the application USB device event handler function (APP_USBDeviceEventHandler() function in app.c). 2. Build a USB Device Library application from scratch. In a case where the available demo applications do not meet the end application requirements, a USB device can be created by building a USB Device Library application from scratch. Figure 5 shows a flowchart for the steps that need to be followed to do this. Figure 5: Steps to create a USB Device Library Application Step 1: Create a MPLAB Project and add the required USB Device Library file to the project. The following files are needed to build the a USB Device Library project 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3970 - system_config.h - This file should contain the compile time configuration macros for the Function Driver, Device Layer and Controller Driver. Refer to the "Configuring the Library" section in the documentation - usb_device.c - This is the device layer implementation - drv_usb.c and drv_usb_device.c - These files implement the USB device mode Controller Driver. - sys_int_pic32.c and plib_int_pic32.c - These files implement the system interrupt service that is required by the USBCD. - function driver implementation files - This depends on the USB device function being implemented. The "Using the Library" section in the function driver specific help file provides more details on the files to be included while using the function driver. - Application specific files - These file will implement the application logic Step 2: Setup the fuse configuration bits to enable PLL. The code snippets below can be used to do this for PIC32MX and PIC32MZ processors /************************************************************* * The following code snippet shows the USB PLL related * fuse configuration bits for PIC32MX processors. A 8MHz * external crystal/oscillator is assumed. ***************************************************************/ #pragma config UPLLEN = ON /* Enable USB PLL */ #pragma config UPLLIDIV = DIV_2 /* USB PLL input divider */ /************************************************************* * The following code snippet shows the USB PLL related * fuse configuration bits for PIC32MZ processors. A 24MHz * external crystal/oscillator is assumed. ***************************************************************/ #pragma config UPLLFSEL = FREQ_24MHZ // USB PLL Input Frequency Selection #pragma config UPLLEN = ON Step 3: Design the USB Device, Configuration and Class specific descriptors that are required for successful enumeration of the USB device. These should comply with the USB 2.0 specification. Class Specific descriptors should comply with the class specifications. The device and configuration descriptors should be added to the Master Descriptor Table. A Function Driver Registration Table should be created and registered with the Device Layer. The function driver registration table associates instance of a function driver with a Device Layer instance. Refer to "Setting up Master Descriptor Table" and "Function Driver Registration" in the Device Layer help file for more information. Step 4: The application should create a Device Layer Event Handler which will handle all the events generated by the Device Layer. The following code snippet shows a list of all possible events that are generated by the Device Layer. The code snippet can be used in the application and updated to meet the application requirements. Refer to "Device Events" in the Device Layer documentation for more details on the Device Layer Event Handling. void APP_USBDeviceEventHandler(USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData) { switch(event) { case USB_DEVICE_EVENT_RESET: break; case USB_DEVICE_EVENT_DECONFIGURED: break; case USB_DEVICE_EVENT_CONFIGURED: break; case USB_DEVICE_EVENT_SUSPENDED: break; case USB_DEVICE_EVENT_RESUMED: break; 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3971 case USB_DEVICE_EVENT_ATTACHED: break; case USB_DEVICE_EVENT_DETACHED: break; case USB_DEVICE_EVENT_ERROR: break; default: break; } } Step 5: The application should create a Function Driver Event Handler which will handle all the events generated by the Function Driver. Refer to "Event Handling" section in the applicable function driver documentation for more details on the Function Driver Event Handling. Step 6: If the application intends to operate the USB Device Library in polling mode, the a interrupt service routine is not required. If the application intends to operate in interrupt mode, a USB Interrupt Handler should be defined as shown here: /* Use this for PIC32MX */ void __ISR ( _USB_1_VECTOR ) _InterruptHandler_USB_stub ( void ) { DRV_USB_Tasks_ISR((SYS_MODULE_OBJ)0); } /* Use this for PIC32MZ */ void __ISR ( _USB_VECTOR,ipl4 ) _InterruptHandler_USB_stub ( void ) { DRV_USB_Tasks_ISR((SYS_MODULE_OBJ)0); } Step 7: The application should create a while(1) loop that continuously updates the USB Device Layer State machine and the application state machine. This requires the application state machine to be non-blocking. /* This while(1) loop will continuously update Device Layer State machine * and the application state machine */ while(1) { USB_DEVICE_Tasks(deviceLayerObject); APP_Tasks(); } Step 8: If interrupt based operation is needed, the interrupts need to be enabled first. The application should then initialize and open the device layer. When the device layer is opened successfully, a device layer event handler can be registered. The device can then be attached on the bus. Refer to the "Initializing the Library" section in the USB Device Layer documentation for more details on initializing the USB Device Layer /* Initialize the interrupt system */ SYS_INT_Initialize(); /* Initialize the global interrupts */ SYS_INT_Enable(); SYS_INT_VectorPrioritySet(INT_VECTOR_USB, INT_PRIORITY_LEVEL3); SYS_INT_VectorSubprioritySet(INT_VECTOR_USB, INT_SUBPRIORITY_LEVEL3); /* Initialize the USB device layer */ deviceLayerObject = USB_DEVICE_Initialize (USB_DEVICE_INDEX_0 , 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3972 ( SYS_MODULE_INIT* ) & usbDevInitData); /* check if the object returned by the device layer is valid */ SYS_ASSERT((SYS_MODULE_OBJ_INVALID != deviceLayerObject), "Invalid USB DEVICE object"); /* Open an instance of the device layer */ appData.deviceHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0, DRV_IO_INTENT_READWRITE ); /* Register a callback with device layer to get * event notification (for end point 0) */ USB_DEVICE_EventCallBackSet(appData.deviceHandle, APP_USBDeviceEventHandler); /* Attach the device */ USB_DEVICE_Attach(appData.deviceHandle); 5.9.1.7 USB Device Stack Migration Guide 5.9.1.7.1 Introduction This topic provides information for migrating from USB Device from MLA to MPLAB Harmony. 5.9.1.7.2 Source Files to Include This topic provides information on the source files to be included when migrating from USB device projects from MLA to MPLAB Harmony. Description The following table lists the source files that must be included for MLA based and MPLAB Harmony based USB device projects. In MLA there is no separate controller driver implementation. Both enumeration functionality and controller driver is implemented in usb_device.c file. In MPLAB Harmony USB Device Stack, the controller driver is implemented in drv_usb.c and drv_usb_device.c files and enumeration functionality is implemented in usb_device.c file. MLA MPLAB Harmony Description usb_device.c usb_device.c In MLA, this file contains enumeration functionality and controller driver implementations. In MPLAB Harmony, this file implements enumeration functionality only. usb_function_xxx.c (Where xxx stands for function driver name like hid, msd, etc.) usb_device_xxx.c (Where xxx stands for function driver name like hid, msd, etc.) Contains all function driver implementations. usb_descriptors.c system_config.c Contains USB stack configurations N/A drv_usb.c and drv_usb_device.c USB peripheral driver implementation. 5.9.1.7.3 Initializing the USB Device Stack This topic provides initialization information when migrating a USB device project from MLA to MPLAB Harmony. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3973 Description In MLA, initializing the USB device stack consists of calling USB functions in the sequence shown in the following flow chart. USBDeviceInit() function will initialize the USB Device stack. USBDeviceAttach() function will attach the device to bus. USBDeviceTasks() function will run the stack task routine. In MPLAB Harmony USB Device Stack, initializing the USB device stack consists of calling USB functions in the sequence shown in the following chart. The USB_DEVICE_Initialize() function will initialize the USB device stack. On successful initialization, this function returns a valid system object. USB_DEVICE_Open() returns a client handle to the application. The application must use this client handle for any further communication with the USB device stack. USB_DEVICE_Attach() function attaches the device to USB bus. USB_DEVICE_Tasks() will run the task routine of the stack. 5.9.1.7.4 Configuring the Stack This topic provides stack configuration information when migrating from a USB device project from MLA to MPLAB Harmony. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3974 Description To configure the stack in MLA, USB descriptors have to be defined in the usb_descriptors.c file. The configuration is done in usb_config.h. Where as in MPLAB Harmony, USB descriptors are defined in system_config.c. The MPLAB Harmony USB Device Stack configuration is done in system_config.h. Apart from descriptors, user also will have to define a function registration table and a master descriptor table in system_config.c. Refer to USB device help file of MPLAB Harmony for more information on the function registration table and the master descriptor table. 5.9.1.7.5 Event Handling This topic provides event handling information when migrating a USB device project from MLA to MPLAB Harmony. Description In MLA, user will have to handle events inside USER_USB_CALLBACK_EVENT_HANDLER function. Whereas in case of MPLAB Harmony, user application client will have to register an event handler with the USB device stack using USB_DEVICE_EventCallBackSet() function. All USB bus events are then forwarded to this user registered event handler function. In case of multi client environment, it is possible for each client to register its own event handler with the USB stack. This allows each application clients to individually manage the events separately. Following code snippet shows an example of registering the event handler in case of MPAB Harmony stack using USB_DEVICE_EventCallBackSet() function. In the following code snippet, APP_UsbDeviceEventCallBack() function is the application event handler. The following code snippet shows the implementation of APP_UsbDeviceEventCallBack function. 5.9.1.7.6 Initializing and Communicating with the Endpoint This topic provides endpoint initialization and communication information when migrating a USB device project from MLA to MPLAB Harmony. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3975 Description In MLA, user application will have to explicitly initialize the required endpoints and can directly read and write to the endpoints. The following code snippet shows how MLA initializes the endpoints in event handler when the device is configured. In case of MPLAB Harmony the user application has no direct access to endpoints. USB device layer initializes the endpoint and any communication to endpoint must happen through function driver APIs. The USB device layer initializes the endpoint based on the information provided by the user in the configurations descriptor. The USB device layer does this by parsing the descriptors table at run time. So the user does not have to explicitly enable or disable the endpoint. 5.9.1.7.7 Handling Endpoint 0 (EP0) Packets This topic provides information for handling Endpoint 0 packets when migrating a USB device project from MLA to MPLAB Harmony. Description Standard device requests are handled by device stack in both MLA and MPLAB Harmony. The difference lies in handling class specific requests. In MLA, the class specific requests are forwarded to the application as EP0 events and application forwards them to appropriate function driver. The following code snippet shows how application forwards them to appropriate function driver in the event handler. In the case of MPLAB Harmony USB Device Stack, EP0 events are generated from appropriate function driver as meaningful events. For example the HID function driver in MPLAB harmony parses the EP0 packet to generate events like USB_DEVICE_HID_EVENT_GET_IDLE, USB_DEVICE_HID_EVENT_SET_REPORT and USB_DEVICE_HID_EVENT_SET_IDLE etc. 5.9 USB Library Help MPLAB Harmony Help USB Device Library - Getting Started 5-3976 The following code snippet shows how the event handler callback is registered with the HID function driver using USB_DEVICE_HID_EventHandlerSet() function. The following code snippet shows the implementation of the HID event handler function in the application. Note how the HID function driver converts EP0 requests to meaningful format for the application. 5.9.2 USB Audio Device Library 5.9.2.1 Introduction Introduces the MPLAB Harmony USB Device Audio Library. Description This library provides a high-level abstraction of the Universal Serial Bus (USB) Audio Device Class function driver that is part of the MPLAB Harmony USB stack with a convenient C language interface. This library supports revision 1.0 of the USB Audio specification release by the USB Implementers forum. The Audio Device Class Definition applies to all devices or functions embedded in composite devices that are used to manipulate audio, voice, and sound-related functionality. This includes both audio data (analog and digital) and the functionality that is used to directly control the audio environment, such as Volume and Tone Control. Audio device can also MIDI Data stream through USB. USB Audio is used with many applications related to voice telephony, audio playback, and recording eg:- Speaker, Microphone, 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3977 Mixer etc. The MPLAB Harmony USB Device Audio library offers services to the application to interact and respond to the host requests. The MPLAB Harmony USB Device Audio library is also referred to as Audio function driver in this document. 5.9.2.2 Release Notes MPLAB Harmony Version: v0.70b USB Audio Device Library Version : 0.01 Alpha Release Date: 18Nov2013 This is the first release of the library. The interface can change in the beta and\or 1.0 release. New This Release: Nothing to report in this release. Known Issues: Nothing to report in this release. 5.9.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.2.4 Library Architecture Provides an Architectural Overview of the Audio Function Driver. Description The USB Audio function driver offers various services to a USB Audio device to communicate with the host by abstracting USB specification details. It must be used along with the USB Device layer and USB controller to communicate with the USB host. Figure 1 shows a block diagram representation of the MPLAB Harmony USB Architecture and where the USB Audio Function Driver is placed. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3978 Figure 1: USB Device Audio Function Driver The USB controller driver takes the responsibility of managing the USB peripheral on the device. The USB device layer handles the device enumeration etc. The Audio function driver receives The USB Device layer forwards all Audio specific control transfers to the Audio Function Driver. The Audio Function Driver interprets the control transfers and requests application's intervention through event handlers and well defined set of API. The application must respond to the Audio events either in or out of the event handler. The application must interact directly with the Audio Function Driver to send/receive data and Audio Control data. 5.9.2.5 Using the Library 5.9.2.5.1 Files to Include Describes which files to include in project while using the Audio Function Driver. Description Table 2 shows the files that must be included in the project in order to use the Audio Function Driver. These files are located in the framework folder of the MPLAB Harmony installation. It is assumed that the Device Layer files ( and the files needed by the Device Layer) are already included in the project. Filename Description \framework\usb\src\dynamic\usb_device_audio.c This file contains all of functions, macros, definitions, variables, datatypes, etc. that are required for usage with the USB device Audio function driver. \framework\usb\usb_device_audio.h Must be included in every source file that needs to invoke Audio function driver API. system_config.h User created file which contains the Audio function driver configuration. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3979 Table 2: Files to be included in USB Audio Device Project. 5.9.2.5.2 Initializing the Library Describes how Audio function driver is initialized. Description The Audio function driver instance for a USB device configuration is initialized by the Device Layer when the configuration is set by the host. This process does not require application intervention. Each instance of the Audio function driver should be registered with the Device layer through the Device Layer Function Driver Registration Table. The Audio function driver does not require a initialization data structure.The funcDriverInit member of the function driver registration table entry for the Audio function driver instance should be set to NULL. The audioFuncDriver object is a global object provided by the Audio function driver and points to the Audio function driver - Device Layer interface functions which are required by the Device Layer. The code snippet below shows an example of how multiple instances of Audio Function driver can registered with the Device Layer. /* This code snippet shows an example of how an Audio function * driver instances can be registered with the Device Layer * via the Device Layer Function Driver Registration Table. * In this case Device Configuration 1 consists of one Audio * function driver instance. */ const USB_DEVICE_FUNC_REGISTRATION_TABLE funcRegistrationTable[1] = { { .speed = USB_SPEED_FULL|USB_SPEED_HIGH, // Supported speed .configurationValue = 1, // To be initialized for Configuration 1 .interfaceNumber = 0, // Starting interface number. .numberOfInterfaces = 2, // Number of interfaces in this instance .funcDriverIndex = 0, // Function Driver instance index is 0 .funcDriverInit = NULL, // Function Driver does not need initialization data structure .driver = &audioFuncDriver // Pointer to Function Driver - Device Layer interface functions }, }; The sequence for initializing the USB Audio Function driver is depicted in the Figure 2. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3980 Figure 2. USB Audio function driver Initialization 1. Call set of APIs to initialize USB Device Layer. Refer USB Device Layer documentation for details about these APIs. 2. The Device Layer provides a callback to the application for any USB Device events like attached, powered, configured etc. The application should receive a callback with an event USB_DEVICE_EVENT_CONFIGURED to proceed. 3. Once the Device Layer is configured the application needs to register callback functions with USB Audio function driver to receive Audio Control transfers and also other audio function driver events. Now the application can use audio function driver APIs to communicate with USB Host. 5.9.2.5.3 Event Handling Describes Audio function driver event handler registration and event handling. Description Registering Audio Function Driver callback functions: While creating USB Audio Device based application, an event handler must be registered with the Device Layer (the Device Layer Event Handler) and every Audio function driver instance (Audio Function Driver Event Handler). The application needs to register two callback functions with Audio function driver 1. For receiving Audio Control Requests from Host like Volume Control, Mute Control etc. 2. For handling other events from Audio function driver. eg:- Data Write Complete or Data Read Complete The callback functions should be registered before the USB device layer acknowledges the SET CONFIGURATION request from the USB Host. In order to ensure this, the callback functions should be set in the USB_DEVICE_EVENT_CONFIGURED event that is generated by the device layer. The code example below shows an example of how this can be done. /* This a sample Application Device Layer Event Handler * Note how the Audio Function Driver callback functions * APP_AudioEntitySettingsCallback() and APP_AudioEventCallback() * are registered in the USB_DEVICE_EVENT_CONFIGURED event. */ void APP_USBDeviceEventCallBack ( USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData ) 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3981 { switch ( event ) { case USB_DEVICE_EVENT_RESET: case USB_DEVICE_EVENT_DECONFIGURED: // USB device is reset or device is deconfigured. // This means that USB device layer is about to deininitialize // all function drivers. break; case USB_DEVICE_EVENT_CONFIGURED: /* check the configuration */ if ( eventData->eventConfigured.configurationValue == 1) { /* Register the callback function for handling Audio Control requests.*/ USB_DEVICE_AUDIO_RegisterCallBacks (USB_DEVICE_CDC_INDEX_0 , APP_AudioEntitySettingsCallback , USB_DEVICE_AUDIO_CALLBACK_ENTITY_SETTINGS ); /* Register the callback function for handling Audio function driver Events*/ USB_DEVICE_AUDIO_RegisterCallBacks (USB_DEVICE_CDC_INDEX_0 , APP_AudioEventCallback , USB_DEVICE_AUDIO_CALLBACK_EVENTS ); /* mark that set configuration is complete */ appData.isConfigured = true; } break; case USB_DEVICE_EVENT_SUSPENDED: break; case USB_DEVICE_EVENT_RESUMED: case USB_DEVICE_EVENT_ATTACHED: case USB_DEVICE_EVENT_DETACHED: case USB_DEVICE_EVENT_ERROR: default: break; } } Handling Audio Control Requests: The audio function driver notifies the application by calling the provided callback function, whenever an Audio Control request is received from USB Host. Below example shows how to handle Audio Control request. // This code example shows handling Audio Control requests. The below handles a Mute request (both SET GET) received from USB Host. //The below are ID of each terminal/Unit in the USB audio function. //Device makes these IDs known to Host through USB descriptors // if that terminal/unit is present in this USB audio device application. #define APP_ID_INPUT_TERMINAL 0x01 #define APP_ID_OUTPUT_TERMINAL 0x02 #define APP_ID_MIXER_UNIT 0x03 #define APP_ID_SELECTOR_UNIT 0x04 #define APP_ID_FEATURE_UNIT 0x05 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3982 #define APP_ID_PROCESSING_UNIT 0x06 #define APP_ID_EXTENSION_UNIT 0x07 int APP_AudioEntitySettingsCallback ( USB_DEVICE_AUDIO_INDEX iAudio , uintptr_t controlHandle, SETUP_PKT *setupPkt ) { int8_t err=-1; USB_AUDIO_CONTROL_INTERFACE_REQUEST* controlRequest; controlRequest = (USB_AUDIO_CONTROL_INTERFACE_REQUEST*) setupPkt; switch(controlRequest->entityID) { case APP_ID_INPUT_TERMINAL: case APP_ID_OUTPUT_TERMINAL: err = APP_TerminalRequestHandler (controlRequest); break; case APP_ID_FEATURE_UNIT: err = APP_FeatureUnitRequestHandler (iAudio, controlHandle, controlRequest); break; case APP_ID_MIXER_UNIT: case APP_ID_SELECTOR_UNIT: case APP_ID_PROCESSING_UNIT: case APP_ID_EXTENSION_UNIT: default: //This USB Audio Speaker application does not support any other control request // received for other unit from Host. So Stall if any other request recieved from Host. USB_DEVICE_ControlStatus(appData.usbDevHandle, controlHandle,USB_DEVICE_CONTROL_STATUS_STALL); break; }//end of switch(controlRequest->entityID) return err; }//end of function APP_AudioEntitySettingsCallback int APP_FeatureUnitRequestHandler ( USB_DEVICE_AUDIO_INDEX iAudio , uintptr_t controlHandle, USB_AUDIO_CONTROL_INTERFACE_REQUEST* controlRequest ) { USB_AUDIO_FEATURE_CONTROL_REQUEST* featureRequest; featureRequest = (USB_AUDIO_FEATURE_CONTROL_REQUEST*) controlRequest; int8_t err = 0; switch(featureRequest->controlSelector) { case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_MUTE_CONTROL: { if (featureRequest->bRequest == USB_AUDIO_CLASS_SPECIFIC_REQUEST_CODE_SET_CUR ) { //A control write transfer recived from Host. Now recieve data from Host. USB_DEVICE_ControlReceive(appData.usbDevHandle, controlHandle,(uint8_t *) &DACMute, 1 ); } else if(featureRequest->bRequest == USB_AUDIO_CLASS_SPECIFIC_REQUEST_CODE_GET_CUR) { /*Handle Get request*/ USB_DEVICE_ControlSend(appData.usbDevHandle, controlHandle, (uint8_t *)&DACMute, 1 ); 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3983 } else { USB_DEVICE_ControlStatus( appData.usbDevHandle, controlHandle, USB_DEVICE_CONTROL_STATUS_STALL); } } break; case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_VOLUME_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_BASS_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_MID_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_TREBLE_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_GRAPHIC_EQUALIZER_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_AUTOMATIC_GAIN_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_DELAY_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_BASS_BOOST_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_LOUDNESS_CONTROL: case USB_AUDIO_FEATURE_UNIT_CONTROL_SELECTOR_FU_CONTROL_UNDEFINED: default: //This USB Audio Speaker application does not support any other feature unit request // from Host. So Stall if any other feature unit request recieved from Host. USB_DEVICE_ControlStatus (appData.usbDevHandle,controlHandle, USB_DEVICE_CONTROL_STATUS_STALL); break; } // end of switch(featureRequest->controlSelector) return err; } //end of function APP_FeatureUnitRequestHandler Handling Audio function driver events : The audio function driver events are discussed at USB_DEVICE_AUDIO_EVENT Enumeration. 5.9.2.5.4 Transferring Data Describes how to send/receive data to/from USB Host using this USB Audio function driver. Description The USB Audio function driver offers API to send, receive data. Receiving Data : USB_DEVICE_AUDIO_Read Function can be used to schedule a data read from the USB Host. Whenever there is data available from Host, the USB audio function driver calls back USB audio event handler with an event USB_DEVICE_AUDIO_EVENT_READ_COMPLETE. User can take necessary actions once the data is received like playback the audio samples through a CODEC and/or schedule next read request for audio samples. Sending Data : USB_DEVICE_AUDIO_Write Function can be used to schedule a data send to the Host. The data will be send to Host, whenever it is ready to receive. Once the data send is complete the audio function driver callsback USB audio event handler with a event USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE. User can take necessary action once the data write is complete like schedule next data write, etc. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3984 5.9.2.6 Configuring the Library Describes how to configure the Audio Function Driver. Description The application designer must specify the following configuration parameters while using the Audio Function Driver. The configuration macros that implement these parameters must be located in the system_config.h file in the application project and a compiler include path (to point to the folder that contains this file) should be specified. Configuration Macro Name Description Comments USB_DEVICE_AUDIO_INSTANCES_NUMBER Number of Audio Function Driver Instances in the application This macro defines the number of instances of the Audio Function Driver. For example, if the application needs to implement two instances of the Audio Function Driver on one USB Device, the macro should USB_DEVICE_AUDIO_INSTANCES_NUMBER be set to 2. Note that implementing a USB Device that features multiple Audio interfaces requires appropriate USB configuration descriptors. USB_DEVICE_AUDIO_QUEUE_SIZE Audio Function Driver Buffer Queue size This macro defines the Audio function driver internal buffer queue. The choice of this parameter defines the readiness of the function driver to respond successfully to read and write requests. The queue is shared by USB_DEVICE_AUDIO_INSTANCES_NUMBER number of Audio instances. A buffer in the queue is allocated to a read, write or a serial state notification request. In a simple application, that does not require buffer queuing and serial state notification, the USB_DEVICE_AUDIO_QUEUE_SIZE macro can be set to 2. In a case where higher throughput is required, this parameter should be set to a higher value. Note that increasing the queue size requires more RAM. 5.9.2.7 Library Interface Data Types and Constants Name Description USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE USB Device Audio Function Driver Event Handler Response Type None. USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID USB Device Audio Function Driver Invalid Transfer Handle Definition. USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE USB Device Audio Function Driver Control Transfer Handle USB_DEVICE_AUDIO_EP_INSTANCE This is type USB_DEVICE_AUDIO_EP_INSTAN CE. USB_DEVICE_AUDIO_EVENT USB Device Audio Function Driver Control Transfer Status 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3985 USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE USB Device Audio Function Driver Read and Write Complete Event Data. USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE USB Device Audio Function Driver Read and Write Complete Event Data. USB_DEVICE_AUDIO_EVENT_HANDLER USB Device Audio Event Handler Function Pointer Type. USB_DEVICE_AUDIO_EVENT_RESPONSE USB Device Audio Function Driver Event Callback Response Type USB_DEVICE_AUDIO_INDEX USB Device Audio Function Driver Index USB_DEVICE_AUDIO_INSTANCE This is type USB_DEVICE_AUDIO_INSTANCE. USB_DEVICE_AUDIO_INSTANCE_STATE This is type USB_DEVICE_AUDIO_INSTANCE_ STATE. USB_DEVICE_AUDIO_INTERFACE_COLLECTION This is type USB_DEVICE_AUDIO_INTERFACE _COLLECTION. USB_DEVICE_AUDIO_INTERFACE_INFO This is type USB_DEVICE_AUDIO_INTERFACE _INFO. USB_DEVICE_AUDIO_INTERFACE_TYPE This is type USB_DEVICE_AUDIO_INTERFACE _TYPE. USB_DEVICE_AUDIO_IRP_OBJECT USB Device Audio Function Driver IRP object. USB_DEVICE_AUDIO_RESULT USB Device Audio Function Driver USB Device Audio Result enumeration. USB_DEVICE_AUDIO_STREAMING_INTERFACE This is type USB_DEVICE_AUDIO_STREAMING _INTERFACE. USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING This is type USB_DEVICE_AUDIO_STREAMING _INTERFACE_ALTERNATE_SETTI NG. USB_DEVICE_AUDIO_TRANSFER_HANDLE USB Device Audio Function Driver Transfer Handle Definition. Functions Name Description USB_DEVICE_AUDIO_ControlReceive This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_AUDIO_ControlSend This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_AUDIO_ControlStatus This function allows the application to complete the status stage of the the Audio Function Driver specific control transfer request. USB_DEVICE_AUDIO_EventHandlerSet This function registers an event handler for the specified Audio function driver instance. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3986 USB_DEVICE_AUDIO_Read This function requests a data read from the USB Device Audio Function Driver Layer. USB_DEVICE_AUDIO_Write This function requests a data write to the USB Device Audio Function Driver Layer. Description This section describes the Application Programming Interface (API) functions of the USB Device Audio Library Refer to each section for a detailed description. 5.9.2.7.1 Functions 5.9.2.7.1.1 USB_DEVICE_AUDIO_ControlReceive Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_ControlReceive( USB_DEVICE_AUDIO_INDEX instanceIndex, USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); Description This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. For example,when the Host wants to set current Volume settings to Device, the Host first sends a SETUP packet to the Device indicating that it intedns to set Volume. After receving the SETUP packet the Device should be prepared to recieve cuurent Volume from Host. Application should make use of USB_DEVICE_AUDIO_ControlReceive() function to receive data from the Host in such cases. The function can be called in the Audio Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the data buffer out of the event handler context, especially if the data buffer to receive the data is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a Audio function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device Audio Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data buffer to receive the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_AUDIO_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_AUDIO_RESULT_OK - The request was successful. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3987 Example // ------------------------------------------------------------------ // In this example, the application receives current Mute info // with in the event handler. The application uses the // USB_DEVICE_AUDIO_ControlReceive() function to do this. // ------------------------------------------------------------------ uint8_t DACMute = 1; // Holds the status of Mute Control USB_DEVICE_AUDIO_EVENT_RESPONSE USBDeviceAudioEventHandler ( USB_DEVICE_AUDIO_INDEX instanceIndex, USB_DEVICE_AUDIO_EVENT event, USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_AUDIO_EVENT_DATA * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_AUDIO_EVENT_ENTITY_SETTINGS_RECEIVED: //In this example we have received a Set Mute request from the Host. // Typcast the recived data into interface request. controlRequest = (USB_AUDIO_CONTROL_INTERFACE_REQUEST*) pData; //check entity ID (Note: Entity IDs are specified in the USB device descriptor. switch(controlRequest->entityID) { case APP_ID_FEATURE_UNIT : featureRequest = (USB_AUDIO_FEATURE_CONTROL_REQUEST*)pData; switch(featureRequest->controlSelector) { case USB_AUDIO_FCS_MUTE_CONTROL: { if(featureRequest->bRequest == USB_AUDIO_CSRC_SET_CUR) { //A control write transfer recived from Host. Now recieve data from Host. USB_DEVICE_AUDIO_ControlReceive(iAudio, controlHandle,(uint8_t *) &DACMute, 1 ); } } break; } break; } break; case USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_RECEIVED: USB_DEVICE_ControlStatus(appData.usbDevHandle,controlTransferHandle, USB_DEVICE_CONTROL_STATUS_OK ); if (appData.currentInterfaceAlternateSetting == 1) AK4953ADACMute(pCodecHandle, DACMute); break; }Remarks: None. 5.9.2.7.1.2 USB_DEVICE_AUDIO_ControlSend Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_ControlSend( USB_DEVICE_AUDIO_INDEX instanceIndex, USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3988 Description This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. For example, if the Host requests current Volume settings to Device, then the Device needs to send a control transfer data to the Host. The function can be called in the Audio Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the response data out of the event handler context, especially if the data is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a Audio function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device Audio Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data that represents the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_AUDIO_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_AUDIO_RESULT_OK - The request was successful. Example // ------------------------------------------------------------------ // In this example, the application responds to am Audio Control request // with in the event handler. The application uses the // USB_DEVICE_AUDIO_ControlSend() function to do this. // ------------------------------------------------------------------ uint8_t DACMute = 1; // Holds the status of Mute Control USB_DEVICE_AUDIO_EVENT_RESPONSE USBDeviceAudioEventHandler ( USB_DEVICE_AUDIO_INDEX instanceIndex, USB_DEVICE_AUDIO_EVENT event, USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_AUDIO_EVENT_DATA * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_AUDIO_EVENT_ENTITY_SETTINGS_RECEIVED: //In this example we have received a Get Mute request from the Host. // Typcast the recived data into interface request. controlRequest = (USB_AUDIO_CONTROL_INTERFACE_REQUEST*) pData; //check entity ID (Note: Entity IDs are specified in the USB device descriptor. switch(controlRequest->entityID) { case APP_ID_FEATURE_UNIT : featureRequest = (USB_AUDIO_FEATURE_CONTROL_REQUEST*)pData; switch(featureRequest->controlSelector) { case USB_AUDIO_FCS_MUTE_CONTROL: 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3989 { if(featureRequest->bRequest == USB_AUDIO_CSRC_GET_CUR) { // In this case, the application should send the current mute // status to the host. The application must send the // USB_DEVICE_AUDIO_ControlSend() function to send the data. USB_DEVICE_AUDIO_ControlSend(iAudio, controlHandle, (uint8_t *)&DACMute, 1 ); } } break; } break; } break; } Remarks: None. 5.9.2.7.1.3 USB_DEVICE_AUDIO_ControlStatus Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_ControlStatus( USB_DEVICE_AUDIO_INDEX instanceIndex, USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_AUDIO_CONTROL_STATUS status ); Description This function allows the application to complete the status stage of the the Audio Function Driver specific control transfer request. The application can either accept the data stage or stall it. Calling this function with status set to USB_DEVICE_AUDIO_CONTROL_STATUS_OK will acknowledge the status stage of the control transfer. The control transfer can be stalled by setting the status parameter to USB_DEVICE_AUDIO_CONTROL_STATUS_STALL. The function can be called in the Audio Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to analyze the event response outside the event handler. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. The application must be aware of events and associated control transfers that do or do not require data stages. Incorrect usage of the USB_DEVICE_AUDIO_ControlStatus() function could cause the device function to be non-compliant. Preconditions This function should only be called in response to a Audio function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device Audio Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. status Set to USB_DEVICE_AUDIO_CONTROL_STATUS_OK to acknowledge the control transfer. Set to USB_DEVICE_AUDIO_CONTROL_STATUS_STALL to stall the transfer. Returns USB_DEVICE_AUDIO_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_AUDIO_RESULT_OK - The request was successful. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3990 Example Remarks: None. 5.9.2.7.1.4 USB_DEVICE_AUDIO_EventHandlerSet Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_EventHandlerSet( USB_DEVICE_AUDIO_INDEX iAudio, USB_DEVICE_AUDIO_EVENT_HANDLER eventHandler, uintptr_t context ); Description This function registers a event handler for the specified Audio function driver instance. This function should be called by the client when it receives a SET CONFIGURATION event from the device layer. A event handler must be registered for function driver to respond to function driver specific commands. If the event handler is not registered, the device layer will stall function driver specific commands and the USB device may not function. Preconditions This function should be called when the function driver has been initialized as a result of a set configuration. Parameters Parameters Description instance Instance of the Audio Function Driver. eventHandler A pointer to event handler function. context Application specific context that is returned in the event handler. Returns USB_DEVICE_AUDIO_RESULT_OK - The operation was successful USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_HANDLER - The eventHandler parameter is NULL Remarks None. Example // This code snippet shows an example registering an event handler. Here // the application specifies the context parameter as a pointer to an // application object (appObject) that should be associated with this // instance of the Audio function driver. USB_DEVICE_AUDIO_RESULT result; USB_DEVICE_AUDIO_EVENT_RESPONSE APP_USBDeviceAUDIOEventHandler ( USB_DEVICE_AUDIO_INDEX instanceIndex , USB_DEVICE_AUDIO_EVENT event , USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle void* pData, uintptr_t context ) { // Event Handling comes here switch(event) { ... } 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3991 return(USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE); } result = USB_DEVICE_AUDIO_EventHandlerSet ( 0 ,&APP_EventHandler, (uintptr_t) &appObject); if(USB_DEVICE_AUDIO_RESULT_OK != result) { SYS_ASSERT ( false , "invalid event handler function" ); } 5.9.2.7.1.5 USB_DEVICE_AUDIO_Read Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_Read( USB_DEVICE_AUDIO_INDEX iAudio, USB_DEVICE_AUDIO_TRANSFER_HANDLE* transferHandle, uint8_t interfaceNum, void * data, size_t size ); Description This function requests a data read from the USB Device Audio Function Driver Layer. The function places a requests with driver, the request will get serviced as data is made available by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_AUDIO_EVENT_READ_COMPLETE event. The amount of data read and the transfer handle associated with the request is returned along with the event. The transfer handle expires when event handler for the USB_DEVICE_AUDIO_EVENT_READ_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID. Preconditions The function driver should have been configured. Parameters Parameters Description instance USB Device Audio Function Driver instance. transferHandle Pointer to a USB_DEVICE_AUDIO_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the read request was successful. interfaceNum The USB Audio streaming interface number on which read request is to placed. data pointer to the data buffer where read data will be stored. size Size of the data buffer. Refer to the description section for more details on how the size affects the transfer. Returns USB_DEVICE_AUDIO_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write request could not be added. USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_SIZE_INVALID - The specified transfer size was not a mulitple of endpoint size or is 0. USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3992 and is invalid. Remarks None Example // Shows an example of how to read. This assumes that // driver was opened successfully. USB_DEVICE_AUDIO_INDEX iAudio; USB_DEVICE_AUDIO_TRANSFER_HANDLE transferHandle; unit8_t interfaceNumber; unit8_t rxBuffer[192]; USB_DEVICE_AUDIO_RESULT readRequestResult; iAudio = 0; //specify the Audio Function driver instance number. interfaceNumber = 1; //Specify the Audio Streaming interface number. readRequestResult = USB_DEVICE_AUDIO_Read ( iAudio, &transferHandle, interfaceNumber, &rxBuffer, 192 ); if(USB_DEVICE_AUDIO_RESULT_OK != readRequestResult) { //Do Error handling here } // The completion of the read request will be indicated by the // USB_DEVICE_AUDIO_EVENT_READ_COMPLETE event. 5.9.2.7.1.6 USB_DEVICE_AUDIO_Write Function C USB_DEVICE_AUDIO_RESULT USB_DEVICE_AUDIO_Write( USB_DEVICE_AUDIO_INDEX iAudio, USB_DEVICE_AUDIO_TRANSFER_HANDLE* transferHandle, uint8_t interfaceNum, void * data, size_t size ); Description This function requests a data write to the USB Device Audio Function Driver Layer. The function places a requests with driver, the request will get serviced as data is requested by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE event. The amount of data written and the transfer handle associated with the request is returned along with the event in writeCompleteData member of the pData parameter in the event handler. The transfer handle expires when event handler for the USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID. Preconditions The function driver should have been configured. Parameters Parameters Description instance USB Device Audio Function Driver instance. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3993 transferHandle Pointer to a USB_DEVICE_AUDIO_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the write request was successful. interfaceNum The USB Audio streaming interface number on which the write request is to placed. data pointer to the data buffer contains the data to be written. size Size of the data buffer. Refer to the description section for more details on how the size affects the transfer. Returns USB_DEVICE_AUDIO_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write request could not be added. USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_SIZE_INVALID - The specified transfer size was not a mulitple of endpoint size or is 0. USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid. Remarks None Example // Shows an example of how to write. This assumes that // driver was opened successfully. USB_DEVICE_AUDIO_INDEX iAudio; USB_DEVICE_AUDIO_TRANSFER_HANDLE transferHandle; unit8_t interfaceNumber; unit8_t txBuffer[192]; USB_DEVICE_AUDIO_RESULT writeRequestResult; iAudio = 0; //specify the Audio Function driver instance number. interfaceNumber = 1; //Specify the Audio Streaming interface number. writeRequestResult = USB_DEVICE_AUDIO_Write ( iAudio, &transferHandle, interfaceNumber, &txBuffer 192 ); if(USB_DEVICE_AUDIO_RESULT_OK != writeRequestResult) { //Do Error handling here } // The completion of the write request will be indicated by the // USB_DEVICE_AUDIO_EVENT_Write_COMPLETE event. 5.9.2.7.2 Data Types and Constants 5.9.2.7.2.1 USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE Macro C #define USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3994 Description USB Device Audio Function Driver Event Handler Response None This is the definition of the Audio Function Driver Event Handler Response Type none. Remarks Intentionally defined to be empty. 5.9.2.7.2.2 USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID Macro C #define USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID ((USB_DEVICE_AUDIO_TRANSFER_HANDLE)(-1)) Description USB Device Audio Function Driver Invalid Transfer Handle Definition This definition defines a USB Device Audio Function Driver Invalid Transfer Handle. A Invalid Transfer Handle is returned by the USB_DEVICE_Audio_Write() and USB_DEVICE_Audio_Read() functions when the request was not successful. Remarks None. 5.9.2.7.2.3 USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE Type C typedef USB_DEVICE_CONTROL_TRANSFER_HANDLE USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE; Description USB Device Audio Function Driver Control Transfer Handle This is returned by the Audio function driver event handler and should be used by the application while responding to Audio function driver control transfer requests. Remarks None. 5.9.2.7.2.4 USB_DEVICE_AUDIO_EP_INSTANCE Structure C typedef struct { uint8_t epAddr; uint16_t epMaxPacketSize; USB_DEVICE_AUDIO_IRP_OBJECT irpObject[USB_DEVICE_AUDIO_QUEUE_SIZE]; } USB_DEVICE_AUDIO_EP_INSTANCE; Description This is type USB_DEVICE_AUDIO_EP_INSTANCE. Members Members Description uint8_t epAddr; End point address uint16_t epMaxPacketSize; End point maximum payload USB_DEVICE_AUDIO_IRP_OBJECT irpObject[USB_DEVICE_AUDIO_QUEUE_SIZE]; IRP object Q per end point 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3995 5.9.2.7.2.5 USB_DEVICE_AUDIO_EVENT Enumeration C typedef enum { USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE, USB_DEVICE_AUDIO_EVENT_READ_COMPLETE, USB_DEVICE_AUDIO_EVENT_INTERAFCE_ALTERNATE_SETTING, USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_RECEIVED, USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_SENT, USB_DEVICE_AUDIO_EVENT_ENTITY_SETTINGS_RECEIVED } USB_DEVICE_AUDIO_EVENT; Description USB Device Audio Function Driver Control Transfer Status This flag is used along with the USB_DEVICE_AUDIO_ControlStatus() function to indicate success or failure of an Audio class specific control transfer request. Members Members Description USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE This event occurs when a write operation scheduled by calling the USB_DEVICE_AUDIO_Write() function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE_ DATA type. USB_DEVICE_AUDIO_EVENT_READ_COMPLETE This event occurs when a read operation scheduled by calling the USB_DEVICE_AUDIO_Read() function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_READ_COMPLETE_D ATA type. USB_DEVICE_AUDIO_EVENT_INTERAFCE_ALTERNATE_SETTING USB spec allows Devices to have multiple alternate settings for the same interface. This event occurs when Host trying set an alternate setting for an interface present in this audio function. The callback function USB_DEVICE_AUDIO_EVENT_CALLBACK also sends Interface Number and Alternate setting number when this event occurs. An application need to take necessary action based on the interface alternate setting. USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_RECEIVED This event occurs when the data stage of a control write transfer has completed. This would occur after the application would respond with a USB_DEVICE_ControlReceive() function to a control write request from Host. This event notifies the application that the data is recived from Host and is available at the location passed by the USB_DEVICE_ControlReceive() function. The application should respond to Host with Zero Length Packet by calling USB_DEVICE_ControlStatus() function. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3996 USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_SENT This event occurs when the data stage of a control read transfer has completed. This event would occur after the application uses the USB_DEVICE_ControlSend() function to respond to an entity request recived from Host. Remarks None. 5.9.2.7.2.6 USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE Structure C typedef struct { USB_DEVICE_AUDIO_TRANSFER_HANDLE handle; uint16_t length; } USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE, USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE; Description USB Device Audio Function Driver Read and Write Complete Event Data. This data type defines the data structure returned by the driver along with USB_DEVICE_AUDIO_EVENT_READ_COMPLETE and USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE events. Members Members Description 5.9.2.7.2.7 USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE Structure C typedef struct { USB_DEVICE_AUDIO_TRANSFER_HANDLE handle; uint16_t length; } USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE, USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE; Description USB Device Audio Function Driver Read and Write Complete Event Data. This data type defines the data structure returned by the driver along with USB_DEVICE_AUDIO_EVENT_READ_COMPLETE and USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE events. Members Members Description 5.9.2.7.2.8 USB_DEVICE_AUDIO_EVENT_HANDLER Type C typedef USB_DEVICE_AUDIO_EVENT_RESPONSE (* USB_DEVICE_AUDIO_EVENT_HANDLER)(USB_DEVICE_AUDIO_INDEX iAudio , USB_DEVICE_AUDIO_EVENT event , USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context); Description USB Device Audio Event Handler Function Pointer Type. This data type defines the required function signature USB Device Audio Function Driver event handling callback function. The application must register a pointer to an Audio Function Driver events handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive event call backs from the Audio Function 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3997 Driver. The function driver will invoke this function with event relevant parameters. The description of the event handler function parameters is given here. instanceIndex - Instance index of the Audio Function Driver that generated the event. event - Type of event generated. controlTransferHandle - Control Transfer Handle for Audio function driver events that require application response. The application should use this handle when the USB Audio Device Control Transfer functions to respond to the events. pData - This parameter should be type casted to a event specific pointer type based on the event that has occurred. Refer to the USB_DEVICE_AUDIO_EVENT enumeration description for more details. context - Value identifying the context of the application that registered the event handling function. Remarks None. 5.9.2.7.2.9 USB_DEVICE_AUDIO_EVENT_RESPONSE Type C typedef void USB_DEVICE_AUDIO_EVENT_RESPONSE; Description USB Device Audio Function Driver Event Handler Response Type This is the return type of the Audio Function Driver event handler. Remarks None. 5.9.2.7.2.10 USB_DEVICE_AUDIO_INDEX Type C typedef uintptr_t USB_DEVICE_AUDIO_INDEX; Description USB Device Audio Function Driver Index This uniquely identifies a Audio Function Driver instance. Remarks None. 5.9.2.7.2.11 USB_DEVICE_AUDIO_INSTANCE Structure C typedef struct { USB_DEVICE_HANDLE devLayerHandle; USB_DEVICE_AUDIO_INDEX audioIndex; USB_DEVICE_AUDIO_INTERFACE_COLLECTION infCollection; USB_DEVICE_AUDIO_INSTANCE_STATE state; USB_DEVICE_AUDIO_EVENT_HANDLER appEventCallBack; uintptr_t userData; } USB_DEVICE_AUDIO_INSTANCE; Description This is type USB_DEVICE_AUDIO_INSTANCE. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3998 Members Members Description USB_DEVICE_HANDLE devLayerHandle; device layer instance associated with this function driver instance USB_DEVICE_AUDIO_INDEX audioIndex; instance index USB_DEVICE_AUDIO_INSTANCE_STATE state; Current state of the function driver instance USB_DEVICE_AUDIO_EVENT_HANDLER appEventCallBack; Application callback uintptr_t userData; Application user data 5.9.2.7.2.12 USB_DEVICE_AUDIO_INSTANCE_STATE Enumeration C typedef enum { USB_DEVICE_AUDIO_INSTANCE_NOT_INITIALIZED = 0, USB_DEVICE_AUDIO_INSTANCE_INITIALIZED, USB_DEVICE_AUDIO_INSTANCE_OPENED, USB_DEVICE_AUDIO_INSTANCE_CLOSED } USB_DEVICE_AUDIO_INSTANCE_STATE; Description This is type USB_DEVICE_AUDIO_INSTANCE_STATE. 5.9.2.7.2.13 USB_DEVICE_AUDIO_INTERFACE_COLLECTION Structure C typedef struct { uint8_t bControlInterfaceNum; uint8_t numStreamingInf; uint16_t bcdADC; USB_DEVICE_AUDIO_EP_INSTANCE intEp[1]; bool isIntEpExists; USB_DEVICE_AUDIO_STREAMING_INTERFACE streamInf[USB_DEVICE_AUDIO_MAX_STREAMING_INTERFACES]; } USB_DEVICE_AUDIO_INTERFACE_COLLECTION; Description This is type USB_DEVICE_AUDIO_INTERFACE_COLLECTION. Members Members Description uint8_t bControlInterfaceNum; control interface number uint8_t numStreamingInf; number of streaming interfaces uint16_t bcdADC; Audio spec in BCD 0x100 or 0x200 USB_DEVICE_AUDIO_EP_INSTANCE intEp[1]; optional interrupt ep info bool isIntEpExists; presence or absence of the interrupt EP 5.9.2.7.2.14 USB_DEVICE_AUDIO_INTERFACE_INFO Structure C typedef struct { uint8_t interfaceNumber; uint8_t interfaceAlternateSettting; } USB_DEVICE_AUDIO_INTERFACE_INFO; 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-3999 Description This is type USB_DEVICE_AUDIO_INTERFACE_INFO. 5.9.2.7.2.15 USB_DEVICE_AUDIO_INTERFACE_TYPE Enumeration C typedef enum { USB_DEVICE_AUDIO_INTERFACE_STREAM_UNDEFINED = 0, USB_DEVICE_AUDIO_INTERFACE_STREAM_AUDIO, USB_DEVICE_AUDIO_INTERFACE_STREAM_MIDI, USB_DEVICE_AUDIO_INTERFACE_FEEDBACK } USB_DEVICE_AUDIO_INTERFACE_TYPE; Description This is type USB_DEVICE_AUDIO_INTERFACE_TYPE. 5.9.2.7.2.16 USB_DEVICE_AUDIO_IRP_OBJECT Structure C typedef struct { USB_DEVICE_IRP irp; USB_DEVICE_AUDIO_INDEX iAudio; } USB_DEVICE_AUDIO_IRP_OBJECT; Description USB Device Audio Function Driver IRP object. IRP object used by the Audio to service application requests. Remarks None. 5.9.2.7.2.17 USB_DEVICE_AUDIO_RESULT Enumeration C typedef enum { USB_DEVICE_AUDIO_RESULT_OK, USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_SIZE_INVALID, USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL, USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID, USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_NOT_CONFIGURED, USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_HANDLER, USB_DEVICE_AUDIO_RESULT_ERROR_CONTROL_TRANSFER_FAILED, USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_INTERFACE_ID, USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_BUFFER } USB_DEVICE_AUDIO_RESULT; Description USB Device Audio Function Driver USB Device Audio Result enumeration. This enumeration lists the possible USB Device Audio Function Driver operation results. These values are returned by the USB_DEVICE_AUDIO_Write() and USB_DEVICE_AUDIO_Read() functions. Members Members Description USB_DEVICE_AUDIO_RESULT_OK The operation was successful 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-4000 USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_SIZE_INVALID The transfer size is invalid. Refer to the description of the read or write function for more details USB_DEVICE_AUDIO_RESULT_ERROR_TRANSFER_QUEUE_FULL The transfer queue is full and no new transfers can be scheduled USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_INVALID The specified instance is not provisioned in the system USB_DEVICE_AUDIO_RESULT_ERROR_INSTANCE_NOT_CONFIGURED The specified instance is not configured yet USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_HANDLER The event handler provided is NULL USB_DEVICE_AUDIO_RESULT_ERROR_CONTROL_TRANSFER_FAILED The control transfer was aborted USB_DEVICE_AUDIO_RESULT_ERROR_INVALID_INTERFACE_ID Interface number passed to the read or write function is invalid. Remarks None. 5.9.2.7.2.18 USB_DEVICE_AUDIO_STREAMING_INTERFACE Structure C typedef struct { uint8_t interfaceNum; USB_DEVICE_AUDIO_INTERFACE_TYPE infType; uint8_t activeSetting; USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING alterntSetting[USB_DEVICE_AUDIO_MAX_ALTERNATE_SETTING]; } USB_DEVICE_AUDIO_STREAMING_INTERFACE; Description This is type USB_DEVICE_AUDIO_STREAMING_INTERFACE. Members Members Description uint8_t interfaceNum; interface number uint8_t activeSetting; currently active alternate setting 5.9.2.7.2.19 USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING Structure C typedef struct { uint8_t numEndPoints; USB_DEVICE_AUDIO_EP_INSTANCE isoDataEp; USB_DEVICE_AUDIO_EP_INSTANCE isoSyncEp; } USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING; Description This is type USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING. Members Members Description uint8_t numEndPoints; number of end-points in this interface USB_DEVICE_AUDIO_EP_INSTANCE isoDataEp; end points associated with this interface 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-4001 5.9.2.7.2.20 USB_DEVICE_AUDIO_TRANSFER_HANDLE Type C typedef uintptr_t USB_DEVICE_AUDIO_TRANSFER_HANDLE; Description USB Device Audio Function Driver Transfer Handle Definition This definition defines a USB Device Audio Function Driver Transfer Handle. A Transfer Handle is owned by the application but its value is modified by the USB_DEVICE_AUDIO_Write() and USB_DEVICE_AUDIO_Read() functions. The transfer handle is valid for the life time of the transfer and expires when the transfer related event had occurred. Remarks None. 5.9.2.8 Files Files Name Description usb_device_audio.h USB Device AUDIO function Driver Interface Description 5.9.2.8.1 usb_device_audio.h USB DEVICE AUDIO Function Driver Interface This file describes the USB Device AUDIO Function Driver interface. Enumerations Name Description USB_DEVICE_AUDIO_EVENT USB Device Audio Function Driver Control Transfer Status USB_DEVICE_AUDIO_INSTANCE_STATE This is type USB_DEVICE_AUDIO_INSTANCE_STATE. USB_DEVICE_AUDIO_INTERFACE_TYPE This is type USB_DEVICE_AUDIO_INTERFACE_TYPE. USB_DEVICE_AUDIO_RESULT USB Device Audio Function Driver USB Device Audio Result enumeration. Functions Name Description USB_DEVICE_AUDIO_ControlReceive This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_AUDIO_ControlSend This function allows the application to respond to the Audio function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_AUDIO_ControlStatus This function allows the application to complete the status stage of the the Audio Function Driver specific control transfer request. USB_DEVICE_AUDIO_EventHandlerSet This function registers an event handler for the specified Audio function driver instance. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-4002 USB_DEVICE_AUDIO_Read This function requests a data read from the USB Device Audio Function Driver Layer. USB_DEVICE_AUDIO_Write This function requests a data write to the USB Device Audio Function Driver Layer. Macros Name Description USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE USB Device Audio Function Driver Event Handler Response Type None. USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID USB Device Audio Function Driver Invalid Transfer Handle Definition. Structures Name Description USB_DEVICE_AUDIO_EP_INSTANCE This is type USB_DEVICE_AUDIO_EP_INSTAN CE. USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE USB Device Audio Function Driver Read and Write Complete Event Data. USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE USB Device Audio Function Driver Read and Write Complete Event Data. USB_DEVICE_AUDIO_INSTANCE This is type USB_DEVICE_AUDIO_INSTANCE. USB_DEVICE_AUDIO_INTERFACE_COLLECTION This is type USB_DEVICE_AUDIO_INTERFACE _COLLECTION. USB_DEVICE_AUDIO_INTERFACE_INFO This is type USB_DEVICE_AUDIO_INTERFACE _INFO. USB_DEVICE_AUDIO_IRP_OBJECT USB Device Audio Function Driver IRP object. USB_DEVICE_AUDIO_STREAMING_INTERFACE This is type USB_DEVICE_AUDIO_STREAMING _INTERFACE. USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNATE_SETTING This is type USB_DEVICE_AUDIO_STREAMING _INTERFACE_ALTERNATE_SETTI NG. Types Name Description USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE USB Device Audio Function Driver Control Transfer Handle USB_DEVICE_AUDIO_EVENT_HANDLER USB Device Audio Event Handler Function Pointer Type. USB_DEVICE_AUDIO_EVENT_RESPONSE USB Device Audio Function Driver Event Callback Response Type USB_DEVICE_AUDIO_INDEX USB Device Audio Function Driver Index USB_DEVICE_AUDIO_TRANSFER_HANDLE USB Device Audio Function Driver Transfer Handle Definition. 5.9 USB Library Help MPLAB Harmony Help USB Audio Device Library 5-4003 File Name usb_device_audio.h Company Microchip Technology Incorporated 5.9.3 USB Device Layer Library 5.9.3.1 Introduction Introduces the MPLAB Harmony USB Device Layer Description The USB device layer library is part of the USB device stack that is available for the Microchip family of microcontrollers. This library has a dependency on the USB device driver to interact with the USB peripheral and therefore cannot operate independently. Within the USB device stack, the USB device layer is basically responsible for enumeration and performing control transfers. The USB device library implementation adheres to USB Device Framework of chapter-9 of USB specification 2.0. In the USB device stack, the device layer features the following: • Supports both USB Full-Speed and Hi-Speed operation • Based on a modular and event driven architecture • Supports the PIC32MX and PIC32MZ families of microcontrollers • Supports composite USB devices • Contains function drivers to implement the following type of device classes: • CDC-ACM • MSD • Generic • Audio • HID • Supports non-blocking operation and is RTOS friendly • Designed to integrate readily with other Harmony Middleware • Supports both interrupt and polling operation 5.9.3.2 Release Notes MPLAB Harmony Version: v0.70b USB Device Layer Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4004 Known Issues: • Limited USB chapter 9 testing performed on HID and MSD function drivers. • The stack has not been tested for USB Interoperability. • The USB Device Stack has not been tested with a Real Time Operating System. • Attach/Detach behavior has been tested in a limited capacity. • The device stack only supports interrupt mode operation. Polled mode operation will be added in a future release. • While running the device stack on PIC32MZ microcontroller, the stack requires 3 seconds to initialize. This is due to a hardware issue with PIC32MZ USB module. • Device stack operation has been tested with Windows XP and Windows 7 OS based PC USB Host. 5.9.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.3.4 Using the Library 5.9.3.4.1 Abstraction Model Describes the Abstraction Model of the USB Device Layer. Description The block diagram shows USB device layer interaction with USB controller driver, function drivers, user application and the system. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4005 USB Device Layer Software Abstraction Block Diagram System Interaction The system is responsible for initializing and de-initializing the device layer. It is also responsible for calling the USB device layer task routine. Function driver interaction The USB device layer interacts with a function driver for following reasons. • Device layer initializes the function driver when device is configured by the host. This can happen when host issues a set configuration request to the device. The device layer initializes only those function drivers that are valid for the selected configuration. • Device layer de-initializes the function driver when host issues a bus reset or when device is detached from the host or when host unconfigures the device by setting configuration value to 0. • The function driver task routines are run by the device layer. This means that function driver tasks runs at the same priority as device layer task. • The device layer forwards class/interface specific setup requests from host to function drivers for processing. The function drivers can use device layer APIs to read data stage from endpoint 0 or write data stage to endpoint 0. All of the above interactions are initiated by the device layer and hence it is required for a function driver to register a set of standard APIs with the device layer for initializing/de-initializing the function driver, for handling control transfers and for running the task routines. Registering of these callback functions with the device layer is compile time option and is done using function driver registration table. Function driver registration is explained in the subsequent sections of this help file. User application ( client ) interaction User application clients can register a callback function with the device layer to get USB device events. Apart from device events, the clients can interact with USB device layer to know other status like USB speed and remote wakeup status. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4006 5.9.3.4.2 Library Overview Provides an overview of the USB Device Layer Library Description The USB device layer mainly interacts with system, its clients and function drivers as shown in USB Device Layer Software Abstraction Block Diagram. Hence the interfaces provided by the USB device layer can be broadly be classified as shown in the below table. Please refer to section "Library Interface" for more information on APIs, data types and constants. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, de-initialization, re-initialization and task functions Client Core Functions Provides function to register callbacks, mechanism to pass events to clients and functions to know the status. Driver Interaction Functions Provides function driver level interfaces for handling event callbacks and performing control transfers 5.9.3.5 How the Library Works 5.9.3.5.1 Files to Include Describes which files to include in project while using the USB Device Layer Description Table 1 shows the files that must be included in the project in order to use the USB Device Layer. These files are located in the framework folder of the MPLAB Harmony installation. It is assumed that the USB Driver files are already included in the project. Filename Description \framework\usb\src\dynamic\usb_device.c Contains the USB Device Layer Implementation. \framework\usb\usb_device.h Must included in every source file that needs to invoke USB Device Layer API. system_config.h User created file which contains the USB Device Layer Configuration MAcors. Table 1: Files to be included in USB Device Project 5.9.3.5.2 Initializing the Library Describes how the USB Device Layer must be initialized Description Following are the components that a user must initialize and register with the USB device stack for the proper operation of the stack. • Descriptors • Master descriptor table • Function registration table 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4007 The subsequent sections of this help file explains how these components must be initialized using code examples. The flow chart shows the steps that has to be followed by the system and clients to initialize the USB device layer. The system initializes the USB device layer. After system initializes the device layer, clients can open handle to device layer, setup callback into the device layer and start capturing the events from the device layer. Flowchart showing the sequence for initializing the USB device layer The following code example shows the system side initialization sequence. Example: SYS_MODULE_OBJ usbDeviceObj; DRV_HANDLE usbDevHandle; // System module initialization deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; // Identifies peripheral (PLIB-level) ID deviceLayerInit.usbID = USB_ID_1; // Boolean flag: true -> Stop USB module in Idle Mode deviceLayerInit.stopInIdle = false; // Boolean flag: true -> Suspend USB in Sleep Mode deviceLayerInit.suspendInSleep = false; // Interrupt Source for USB module deviceLayerInit.interruptSource = INT_SOURCE_USB_1; // Number of function drivers registered to this instance of the USB device layer deviceLayerInit.registeredFuncCount = 1; // Function driver table registered to this instance of the USB device layer deviceLayerInit.registeredFunctions = funcRegistrationTable; // Pointer to USB Descriptor structure deviceLayerInit.usbMasterDescriptor = &usbMasterDescriptor; // USB operation spee. deviceLayerInit.deviceSpeed = USB_SPEED_HIGH; // USB device initialization usbDeviceObj = USB_DEVICE_Initialize(USB_DEVICE_INDEX_0, &deviceLayerInit); 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4008 if (SYS_MODULE_OBJ_INVALID == usbDriverObj) { // Handle error } while(1) { // Call device layer task USB_DEVICE_Tasks( usbDeviceObj ); } The following code example shows how a client can open an handle to device layer and use the same. Example: void clientIntialize( void ) { DRV_HANDLE usbDevHandle; // Open the device layer. usbDevHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0 ); if(DRV_HANDLE_INVALID == usbDevHandle) { // Handle error } // Register a callback with device layer to get event notification (for end point 0) USB_DEVICE_EventCallBackSet(usbDevHandle, usbDeviceEventCallBack); // Where usbDeviceEventCallBack is a callback function // that must be provided by the client } void usbDeviceEventCallBack( USB_DEVICE_EVENTS events, USB_DEVICE_EVENT_DATA * eventData ) { // Handle all device layer events here. switch( event ) { case USB_DEVICE_EVENT_RESET: case USB_DEVICE_EVENT_DECONFIGURED: /* Bus reset is detected or device is unconfigured */ /* TODO: Add user code here. */ break; case USB_DEVICE_EVENT_CONFIGURED: if( eventData->eventConfigured.configurationValue == 1 ) { /* The device is in configured state */ /* TODO: Add user code here. */ } break; case USB_DEVICE_EVENT_SUSPENDED: /* Device is suspended */ /* TODO: Add user code here. */ break; case USB_DEVICE_EVENT_RESUMED: case USB_DEVICE_EVENT_ATTACHED: case USB_DEVICE_EVENT_DETACHED: case USB_DEVICE_EVENT_ERROR: default: break; 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4009 } } 5.9.3.5.2.1 Descriptors A USB device reports its attributes to host using descriptors that are defined in chapter 9 of USB Specification, Revision 2.0. The user must initialize device descriptor, configurations descriptor, string descriptors and device qualifier descriptor using static tables. If the device supports dual speeds then there can be two sets of these descriptors, one for for full speed and another for high speed. These descriptors are then registered to the USB device stack using master descriptor table. The following code example shows how the descriptors are initialized in system_config.c file using static tables. Refer to Master Descriptor Table to know how to register these descriptors into USB device stack. /* Example USB descriptors for a MSD device */ /* Device Descriptor Table */ const USB_DEVICE_DESCRIPTOR deviceDescriptor = { 0x12, // Size of this descriptor in bytes USB_DESCRIPTOR_DEVICE, // DEVICE descriptor type 0x0110, // USB Spec Release Number in BCD format 0x00, // Class Code 0x00, // Subclass code 0x00, // Protocol code USB_DEVICE_EP0_BUFFER_SIZE, // Max packet size for EP0, see usbcfg.h 0x04D8, // Vendor ID 0x0009, // Product ID: mass storage device demo 0x0001, // Device release number in BCD format 0x01, // Manufacturer string index 0x02, // Product string index 0x03, // Device serial number string index 0x01 // Number of possible configurations }; /* Configurations Descriptor Table */ const uint8_t configDescriptor[] = { /* Configuration Descriptor */ 9, // Size of this descriptor in bytes USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type 0x20,0x00, // Total length of data for this cfg 1, // Number of interfaces in this cfg 1, // Index value of this configuration 0, // Configuration string index USB_ATTRIBUTE_DEFAULT | USB_ATTRIBUTE_SELF_POWERED, // Attributes, see usbdefs_std_dsc.h 50, // Max power consumption (2X mA) /* Interface Descriptor */ 9, // Size of this descriptor in bytes USB_DESCRIPTOR_INTERFACE, // INTERFACE descriptor type 0, // Interface Number 0, // Alternate Setting Number 2, // Number of endpoints in this intf USB_DEVICE_MSD_INTF, // Class code USB_DEVICE_MSD_INTF_SUBCLASS, // Subclass code USB_DEVICE_MSD_PROTOCOL, // Protocol code 0, // Interface string index /* Endpoint Descriptor */ 7, USB_DESCRIPTOR_ENDPOINT, 0x01 | USB_EP_DIRECTION_IN, USB_TRANSFER_TYPE_BULK, MSD_IN_EP_SIZE, 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4010 0x00, 0x00, 7, USB_DESCRIPTOR_ENDPOINT, 0x01 | USB_EP_DIRECTION_OUT, USB_TRANSFER_TYPE_BULK, MSD_OUT_EP_SIZE, 0x00, 0x00 }; /* String descriptors Table */ /* Language code string descriptor */ const struct { uint8_t bLength; uint8_t bDscType; uint16_t string[1]; } sd000 = { sizeof(sd000), USB_DESCRIPTOR_STRING, { 0x0409 } }; /* Manufacturer string descriptor */ const struct { const uint8_t bLength; uint8_t bDscType; uint16_t string[25]; } sd001 = { sizeof(sd001), USB_DESCRIPTOR_STRING, { 'M','i','c','r','o','c','h','i','p',' ', 'T','e','c','h','n','o','l','o','g','y',' ','I','n','c','.' } }; /* Product string descriptor */ const struct { const uint8_t bLength; uint8_t bDscType; uint16_t string[22]; } sd002 = { sizeof(sd002), USB_DESCRIPTOR_STRING, { 'S','i','m','p','l','e',' ','M','S','D',' ', 'D','e','v','i','c','e',' ','D','e','m','o' } }; /* Serial number string descriptor. Note: This should be unique for each unit built on the assembly line. Plugging in two units simultaneously with the same serial number into a single machine can cause problems. Additionally, not all hosts support all character values in the serial number string. The MSD Bulk Only Transport (BOT) specs v1.0 restrict the serial number to consist only of ASCII characters "0" through "9" and capital letters "A" through "F". */ 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4011 const struct { uint8_t bLength; uint8_t bDscType; uint16_t string[12]; } sd003 = { sizeof(sd003),USB_DESCRIPTOR_STRING, {'1','2','3','4','5','6','7','8','9','9','9','9'} }; 5.9.3.5.2.2 Master Descriptor Table Master Descriptor Table is a static table that holds collection of pointers that points to USB descriptors. User will have to initialize the master descriptor table and must register it with the USB device stack. During the device enumeration the stack uses these information from the Master Descriptor Table to respond to the setup requests from the host. Following code example shows how to set up the Master Descriptor Table. The Master Descriptor Table must then be registered with the USB device stack while initializing the USB device layer. Refer to Initializing the Data Structure to know how it can be registered with the USB device stack. /* Array of string descriptors */ /* Refer to Descriptors section to see how the string descriptors sd000 to sd003 are defined */ const uint8_t *const USB_SD_Ptr[4]= { (const uint8_t *const)&sd000, (const uint8_t *const)&sd001, (const uint8_t *const)&sd002, (const uint8_t *const)&sd003 }; /* Array of full speed config descriptors */ /* Refer to Descriptors section to see how the configurations descriptor configDescriptor[] is defined */ const uint8_t *const fullSpeedConfigDescSet[1] = { (const uint8_t *const)&configDescriptor[0] }; /* Initialize the master descriptor table */ const USB_MASTER_DESCRIPTOR usbMasterDescriptor = { /* Low/Full speed device descriptor */ /* Refer to Descriptors section to see how deviceDescriptor is initialized */ (uint8_t *)&deviceDescriptor , /* Total number of low/full speed configurations available */ sizeof( fullSpeedConfigDescSet )/sizeof( uint8_t* ) , /* Pointer to array of low/full speed configurations descriptors */ ( USB_DEVICE_CONFIG_DESCS_PTR )&fullSpeedConfigDescSet[0] , /* High speed device descriptor. Not supported in this example and is set to NULL.*/ NULL, /* Total number of high speed configurations available. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4012 Zero for this example */ 0, /* Pointer to array of high speed configurations descriptors. Not supported in this example*/ NULL, /* Total number of string descriptors available */ sizeof( USB_SD_Ptr )/sizeof( uint8_t* ), /* Pointer to array of string descriptors */ (USB_DEVICE_STRING_DESCS_PTR)USB_SD_Ptr, /* Pointer to full speed dev qualifier. Not supported in this example */ NULL, /* Pointer to high speed dev qualifier. Not supported in this example*/ NULL, }; 5.9.3.5.2.3 Functions Registeration Table This section explains how function drivers can be registered with the USB device layer using Function Registration Table. Function Registration Table is a static table and must be configured at compile time. It contains mapping of function driver instance to USB speed and configuration. This table helps the USB device layer to initialize the appropriate function driver for a configuration value and device speed selected by the host. Following code example shows how to build a function registration table. /* This is a code example that registers MSD function driver to the USB device stack*/ #define MSD_INDEX 0 const USB_DEVICE_FUNC_REGISTRATION_TABLE funcRegistrationTable[1] = { { /* Speed: Indicating both full/high speeds here will make the device stack to load MSD function driver for both the speeds */ USB_SPEED_FULL | USB_SPEED_HIGH, /* Configuration value */ 1, /* InterfaceNumber */ 0, /* Total number of interfaces in this driver */ 1, /* Instance Index of the MSD function driver that will be loaded for this configuration value and speed */ MSD_INDEX, /* MSD initialization data structure. See MSD documentation for this structure */ (void*)&msdInit, /* Pointer to the structure that contains collection of MSD driver function pointers. The USB device stack calls out these MSD functions appropriately */ (USB_DEVICE_FUNCTION_DRIVER*) &msdFunctionDriver } 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4013 }; 5.9.3.5.2.4 Initializing the Data Structure This section explains about the USB device initialization data structure. Before initializing this data structure user must keep the descriptors table, master descriptor table and function registration table ready and initialized. This structure maps these static tables to an instance of USB device layer and provides a mechanism to register these static tables with the USB device layer. Pointer to this initialization structure is then passed to USB device layer using USB_DEVICE_Initialize() function. Following code example shows how to initialize this structure and register the same with the USB device stack. /* USB Device initialization data structure */ const USB_DEVICE_INIT usbDevInitData = { /* System module initialization */ {SYS_MODULE_POWER_RUN_FULL}, /* Identifies peripheral (PLIB-level) ID */ USB_ID_1, /* Stop in idle */ false, /* Stop in sleep */ false, /* Interrupt source */ INT_SOURCE_USB_1, /* Number of functions registered to this instance of the USB device layer. See Function Registration Table section of this help file. We are registering on */ (sizeof(funcRegistrationTable)/sizeof(USB_DEVICE_FUNC_REGISTRATION_TABLE)), /* Function driver table registered to this instance of the USB device layer*/ (USB_DEVICE_FUNC_REGISTRATION_TABLE*)funcRegistrationTable, /* Pointer to Master Descriptor structure. See Master Descriptor Table section of this help file. */ (USB_MASTER_DESCRIPTOR*)&usbMasterDescriptor }; /* This is an example that shows how the device initialization structure is registered with USB_DEVICE_Initialize() */ typedef struct { /* device layer object returned by device layer init function */ SYS_MODULE_OBJ usbDevObject; /* Controller driver object returned by controller driver init function */ SYS_MODULE_OBJ usbCDObject; } APP_DRV_OBJECTS; typedef struct { /* device layer handle returned by device layer open function */ DRV_HANDLE usbDevHandle; } APP_DATA; /* Application objects */ APP_DRV_OBJECTS appDrvObject; 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4014 /* Application data */ APP_DATA appData = { /* device layer handle */ DRV_HANDLE_INVALID }; void SYS_Initialize ( void ) { /* Set up cache and wait states for * maximum performance. */ SYSTEMConfigPerformance(80000000); /* Initialize the BSP */ BSP_Initialize( ); /* Initialize the USB device layer. Note the registration of initialization data structure with the USB device layer */ appDrvObject.usbDevObject = USB_DEVICE_Initialize (USB_DEVICE_INDEX_0 , ( SYS_MODULE_INIT* ) & usbDevInitData); /* check if the object returned by the device layer is valid */ SYS_ASSERT((SYS_MODULE_OBJ_INVALID != appDrvObject.usbDevObject), "Invalid USB DEVICE object"); /* open an instance of the device layer */ appData.usbDevHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0, 0 ); /* Register a callback with device layer to get event notification (for end point 0) */ USB_DEVICE_EventCallBackSet(appData.usbDevHandle, APP_UsbDeviceEventCallBack); /* Enable USB device layer */ USB_DEVICE_Attach(appData.usbDevHandle); /* Initialize the Application */ APP_Initialize ( ); /* Initializethe interrupt system */ SYS_INT_Initialize(); /* set priority for USB interrupt source */ SYS_INT_VectorPrioritySet(INT_VECTOR_USB, INT_PRIORITY_LEVEL3); /* set sub-priority for USB interrupt source */ SYS_INT_VectorSubprioritySet(INT_VECTOR_USB, INT_SUBPRIORITY_LEVEL3); /* Initialize the global interrupts */ SYS_INT_Enable(); } 5.9.3.5.3 Device Events Describes the USB Device Layer Events Description The device layer generates following events. The application clients can capture these events by registering a callback function into the device layer using USB_DEVICE_EventCallBackSet() function. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4015 Events Description USB_DEVICE_EVENT_RESET USB bus reset occurred. This event is an indication to the application client that device layer has de-initialized the function drivers. For application client, this event means that USB device has moved to default state and any further communication with the function drivers must be stopped. USB_DEVICE_EVENT_SUSPENDED This event is an indication to the application client that device is suspended and it can put the device to power-down mode if required. USB_DEVICE_EVENT_RESUMED Event that indicates that device has resumed from suspended state. USB_DEVICE_EVENT_ERROR This event is an indication to the application client that an error occurred on the USB bus. USB_DEVICE_EVENT_SOF This event is generated for every new start of frame. Application client can use this SOF event for general time based house keeping activities. USB_DEVICE_EVENT_DETACHED This event is an indication to the application client that the device is detached from the host and device layer is about to de-initialize the function drivers. For application client, this event means that it has to stop any further interactions with the function driver. USB_DEVICE_EVENT_DECONFIGURED This event is generated when the USB host unconfigures the device by configuring the device to configuration value 0. USB_DEVICE_EVENT_CONFIGURED This event is generated when the device is configured by the host. The device layer loads all the function drivers applicable to that configuration and application client can interact with function drivers. USB_DEVICE_EVENT_ATTACHED Device is attached to the USB, but is not powered. The following code example shows how the application clients can register callback function with the to capture these events Example: void SYS_Initialize( void ) { /* Add user initialization code here */ /* Register a callback with device layer to get event notification (for end point 0) */ USB_DEVICE_EventCallBackSet(appData.usbDevHandle, APP_UsbDeviceEventCallBack); /* Enable the device */ USB_DEVICE_Attach(appData.usbDevHandle); } void APP_UsbDeviceEventCallBack( USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * pEventData ) { switch( event ) { case USB_DEVICE_EVENT_RESET: case USB_DEVICE_EVENT_DECONFIGURED: /* USB device is reset or device is deconfigured. */ /* Add user code here */ break; case USB_DEVICE_EVENT_CONFIGURED: /* Device is configured */ /* Check the configuration value */ if(pEventData->eventConfigured.configurationValue == 1) 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4016 { /* Host selected configuration value 1 */ } break; case USB_DEVICE_EVENT_SUSPENDED: /* Add user's code here to handle USB bus suspend event */ break; case USB_DEVICE_EVENT_RESUMED: case USB_DEVICE_EVENT_ERROR: case USB_DEVICE_EVENT_SOF: case USB_DEVICE_EVENT_DETACHED: case USB_DEVICE_EVENT_ATTACHED: default: break; } } 5.9.3.5.4 Developing Vendor-specific Function Drivers This topic describes the development of vendor-specific function drivers. Description This section is important for the users who wish to develop their own function drivers. This section covers the interface between the function driver and USB device layer. The framework explains how the USB device layer manages function driver through a set of callbacks. Framework showing the interaction between Function Driver and Device Layer The USB device layer manages the function driver using a set of standard callout functions. A function driver must implement these callout functions as described in the following paragraphs. The pointer to these callout functions must be packed in USB_DEVICE_FUNCTION_DRIVER structure and pointer to this structure must be registered with the USB device layer using function registration table. InitializeByDescriptor() Device layer initializes a function driver by calling this function when host issues a set configuration request. This function is called multiple times by the device layer for every descriptor that is found under the interface owned by the function driver. The function driver must implement appropriate logic to configure itself for each descriptor. This function is called from with in the interrupt context. Therefore the function driver design must ensure that the execution time of this function is short. The example code for initializeByDescriptor() is shown below. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4017 /****************************************************************************** Function: void USB_DEVICE_MYCLASS_InitializeByDescriptorType ( SYS_MODULE_INDEX iFunctionDriver, SYS_MODULE_INDEX iDriver, SYS_MODULE_INDEX iUsbDevice, void* funcDriverInit , uint8_t* pConfigDesc ) Summary: USB Device MYCLASS function driver initialization. The device layer calls this function to initialize the function driver based on the descriptor found (from the configurations descriptor). Precondition: None. Parameters: iFunctionDriver : Function driver instance index. usbDeviceHandle : USB device handle for communicating with the USB device layer. funcDriverInit : Pointer to function driver init data structure. User can have his own function driver init data structure and can register the same in the function registration table. intfNumber : The interface number the descriptor identified by descriptorType belongs to. altSetting : The alternate setting of the descriptor that is identified by descriptorType belongs to. pDescriptor : Pointer to the descriptor. This can point to interface descriptor or endpoint descriptor or any class specific descriptor based on the descriptorType. Returns: None. Remarks: None */ void USB_DEVICE_MYCLASS_InitializeByDescriptorType(SYS_MODULE_INDEX iFunctionDriver, DRV_HANDLE usbDeviceHandle, void* funcDriverInit, uint8_t intfNumber, uint8_t altSetting, uint8_t descriptorType, uint8_t * pDescriptor) { USB_ENDPOINT endpoint; USB_ENDPOINT_DESCRIPTOR endpointDescriptor switch(descriptorType ) { case USB_DESCRIPTOR_ENDPOINT: // Get the endpoint endpointDescriptor = (USB_ENDPOINT_DESCRIPTOR *)pDescriptor; // Enable endpoint. USB_DEVICE_EndpointEnable(usbDeviceHandle, endpointDescriptor->endpoint, endpointDescriptor->transferType, endpointDescriptor->wMaxPacketSize); break; case USB_DESCRIPTOR_INTERFACE: // Do interface specific initialization here. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4018 break; default: // Handle class specific descriptor. break; } } DeInitialize() Device layer de-initializes a function driver by calling this callout function when host issues a USB bus reset or when host deconfigures the device by selecting configuration value as 0. In the DeInitialize() function, user must implement functionalities to close endpoints and cancel the IRPs owned by that particular function driver. This callout function is called from with in the interrupt context. Therefore the design must ensure that the execution time of this callout function is short. The example code for DeInitialize() is shown below. /****************************************************************************** Function: void USB_DEVICE_MYCLASS_DeInitialize( SYS_MODULE_INDEX iFunctionDriver ) Summary: Deinitializes an instance of the MYCLASS. Description: Parameters: iFunctionDriver - function driver index Returns: None. */ static void USB_DEVICE_MYCLASS_DeInitialize( SYS_MODULE_INDEX iFunctionDriver ) { /* Cancel all IRPs on the endpoint/s used by MYCLASS function driver */ USB_DEVICE_IRPCancelAll( usbDeviceHandle, endpoint ); /* Disable endpoints used by this function driver */ USB_DEVICE_EndpointDisable( usbDeviceHandle, endpoint ); } ControlTransferNotification() Only standard setup packets whose recipient is device/endpoint is supported by the device layer. All other types of setup packet targeted to interface/class is forwarded to appropriate function driver using "controlTransferNotification()" callout function. Setup packets with "other" as recipient is discarded by the device layer and and a STALL is generated on the control endpoint. In this callout function, the function driver has to parse the setup packet. If the request is supported, function driver can initiate data stage by using USB_DEVICE_ControlSend/USB_DEVICE_ControlReceive functions . If the request is not supported, function driver can stall the control endpoints by using USB_DEVICE_ControlStatus function. This callout function is called from with in the interrupt context. Therefore the design must ensure that the execution time of this callout function is short. This is not a mandatory callout function and can be set to NULL if a function driver does not support class specific setup request. /****************************************************************************** Function: void USB_DEVICE_MYCLASS_ControlTransferHandler( USB_DEVICE_CONTROL_TRANSFER_HANDLE controlHandle, SYS_MODULE_INDEX iFunctionDriver, USB_DEVICE_CONTROL_TRANSFER_EVENT controlEvent, 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4019 void * pEventData ) Summary: Handles all MYCLASS related control transfers. Description: Parameters: controlHandle - Control Handle iFunctionDriver - Function driver index controlEvent - Control transfer event pEventData - Pointer to event related data Returns: None. */ void USB_DEVICE_MYCLASS_ControlTransferHandler( USB_DEVICE_CONTROL_TRANSFER_HANDLE controlHandle, SYS_MODULE_INDEX iFunctionDriver, USB_DEVICE_CONTROL_TRANSFER_EVENT controlEvent, USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA * pEventData ) { USB_DEVICE_HID_INSTANCE *hidThisInstance; SETUP_PKT * setupPkt = pEventData->setupRequest; USB_DEVICE_HID_EVENT_DATA eventData; hidThisInstance = &gUsbDeviceHidInstance[iHID] ; if( controlEvent == USB_DEVICE_CONTROL_SETUP_REQUEST ) { /* Setup request is received */ if( setupPkt->bmRequestType & SETUP_RECIPIENT_INTERFACE) { /* Handle interface specific requests here */ /* Use USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive or USB_DEVICE_ControlStatus functions appropriately to respond to setup packet */ } else if( ( setupPkt->bmRequestType & SETUP_TYPE_CLASS ) && ( hidThisInstance->appCallBack != NULL ) ) { /* Handle class specific requests here */ /* Use USB_DEVICE_ControlSend, USB_DEVICE_ControlReceive or USB_DEVICE_ControlStatus functions appropriately to respond to setup packet */ } } else if ( controlEvent == USB_DEVICE_CONTROL_DATA_RECEIVED ) { /* Data stage is received. Handle the data */ /* Use USB_DEVICE_ControlStatus functions appropriately to respond to data stage */ } else if ( controlEvent == USB_DEVICE_CONTROL_DATA_SENT ) { /* Data stage is sent */ /* This is just a success event. If required inform the same to application clients here. */ } } 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4020 Tasks() All function driver tasks are called from with in the device layer tasks. Device layer can call function driver task routine using this function driver provided callout function. With in this callout function, a function driver can implement its task specific routines. This is not a mandatory callback function. Set this callout function to NULL if it is not supported by the function driver. /****************************************************************************** Function: void USB_DEVICE_MYCLASS_Tasks ( SYS_MODULE_INDEX iFunctionDriver ) Summary: This function handles the main MSD state machine. Description: Precondition: None. Parameters: iFunctionDriver : Function driver index. Returns: None. Remarks: None */ void USB_DEVICE_MYCLASS_Tasks ( SYS_MODULE_INDEX iFunctionDriver ) { /* Perform all function driver tasks here */ } Registering the callout functions To register the above callout functions with the device layer, create a static table of type USB_DEVICE_FUNCTION_DRIVER structure with pointers to callout functions. The structure must then be registered to USB device layer using function registration table. Here is the code snippet that shows the same. /* Make a table of USB_DEVICE_FUNCTION_DRIVER with pointers to callout functions */ const USB_DEVICE_FUNCTION_DRIVER myclassDriver = { /* MYCLASS init function */ .initializeByDescriptor = USB_DEVICE_MYCLASS_InitializeByDescriptorType , /* MYCLASS de-init function */ .deInitialize = USB_DEVICE_MYCLASS_Deinitialization , /* MYCLASS set-up packet handler */ .controlTransferNotification = USB_DEVICE_MYCLASS_ControlTransferHandler , /* MYCALSS tasks function */ .tasks = USB_DEVICE_MYCLASS_Tasks }; /* Using the function registration table register MYCLASS driver with USB device stack */ const USB_DEVICE_FUNC_REGISTRATION_TABLE funcRegistrationTable[1] = { { // Speed USB_SPEED_FULL | USB_SPEED_HIGH, // Configuration value 1, // interface number of MYCLASS 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4021 0, // number of interfaces in MYCLASS 1, // instance index of MYCLASS 0, // MYCLASS data init structure. This structure is class specific data structure // that will be passed as funcDriverInit parameter to // USB_DEVICE_MYCLASS_InitializeByDescriptorType() &myclassInit, // My class driver structure having pointers to all the callouts &myclassDriver } }; 5.9.3.5.5 Library Configuration Describes how to configure the USB Device Library Macros Name Description USB_DEVICE_MAX_CLIENTS Sets the maximum possible number of clients an instance of the USB device can open using USB_DEVICE_Open. USB_DEVICE_MAX_FUNCTION_DRIVER Sets the maximum number of function drivers at a time that are supported by an instance of the USB device layer. USB_DEVICE_MAX_INSTANCES Sets the maximum possible number of instances of the USB device that can be instantiated by using USB_DEVICE_Initialize() routine. Description The application designer must specify the following configuration parameters while using the USB Device Library. The configuration macros that implement these parameters must be located in the system_config.h file in the application project and a compiler include path (to point to the folder that contains this file) should be specified. Configuration Macro Name Description Comments USB_DEVICE_MAX_INSTANCES Sets the maximum possible number of instances of the USB device that can be instantiated by using USB_DEVICE_Initialize() routine. In case of microcontrollers with more than one USB peripheral, the value of this constant can be increased to support more than one instances of USB device layer. The static implementation supports only one instance. Setting the value of this constant to > 1 has no effect on static implementations. Only in dynamic implementations of the USB device layer this value can be set > 1. The USB device layer has to support at least one instance. Therefore, ensure that the value of this constant is set to > 0.Increasing the instance count consumes RAM and can lead to performance degradation. USB_DEVICE_MAX_CLIENTS Sets the maximum possible number of clients an instance of the USB device can open using USB_DEVICE_Open. If multiple clients need USB device layer services, user can set the value of this constant to > 1. The value of this macro must not be set to zero. Each instance of the USB device layer must support at least one client. Therefore, set the value to at least 1. The static single client implementation of the USB device layer supports only one client. Therefore, increasing the value of this constant > 1 has no effect in static single client implementation. Increasing the client count consumes RAM and can lead to performance degradation. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4022 5.9.3.5.5.1 USB_DEVICE_MAX_CLIENTS Macro C #define USB_DEVICE_MAX_CLIENTS 1 Description If multiple clients need USB device layer services, user can set the value of this constant to > 1. Remarks The value of this macro must not be set to zero. Each instance of the USB device layer must support at least one client. Therefore, set the value to at least 1. The static single client implementaion of the USB device layer supports only one client. Therefore, increasing the value of this constant > 1 has no effect in static single client implementation. Increase the client count consumes RAM and can lead to performance degradation. 5.9.3.5.5.2 USB_DEVICE_MAX_FUNCTION_DRIVER Macro C #define USB_DEVICE_MAX_FUNCTION_DRIVER 3 Description This constant sets the maximum number of function drivers that are loaded by a USB device instance for a configuration set by the USB host. Remarks None. 5.9.3.5.5.3 USB_DEVICE_MAX_INSTANCES Macro C #define USB_DEVICE_MAX_INSTANCES 1 Description In case of microcontrollers with more than one USB peripheral, the value of this constant can be increased to support more than one instances of USB device layer. Remarks The static implementation supports only one instance. Setting the value of this constant to > 1 has no effect on static implementations. Only in dynamic implementations of the USB device layer this value can be set > 1. The USB device layer has to support at least one instance. Therefore, ensure that the value of this constant is set to > 0. Increasing the instance count consumes RAM and can lead to performance degradation. 5.9.3.6 Library Interface Data Types and Constants Name Description USB_DEVICE_INDEX_0 USB device layer index definitions. USB_DEVICE_INDEX_1 This is macro USB_DEVICE_INDEX_1. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4023 USB_DEVICE_INDEX_2 This is macro USB_DEVICE_INDEX_2. USB_DEVICE_INDEX_3 This is macro USB_DEVICE_INDEX_3. USB_DEVICE_INDEX_4 This is macro USB_DEVICE_INDEX_4. USB_DEVICE_INDEX_5 This is macro USB_DEVICE_INDEX_5. USB_DEVICE_INDEX_COUNT Number of valid USB Device Layer indices USB_DEVICE_CALLBACK Pointer to a USB Device Layer callback function data type for bus events. USB_DEVICE_CONFIG_DESCS_PTR Pointer to an array that contains pointer to configuration descriptors. USB_DEVICE_CONTROL_STATUS This enumerated data-type identifies the status stage of control transfer. USB_DEVICE_CONTROL_TRANSFER_CALLBACK USB_DEVICE_CONTROL_TRANSFER_EVENT This datatype defines the different control transfer events. USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA USB device control transfer event data. USB_DEVICE_CONTROL_TRANSFER_HANDLE Data type of USB device control transfer handle. USB_DEVICE_CONTROL_TRANSFER_RESULT Enumerated data type identifying results of a control transfer. USB_DEVICE_EVENT Enumerated data-type identifying the bus events that has occurred in the USB device layer. USB_DEVICE_EVENT_DATA Data assosciated with USB bus events. USB_DEVICE_EVENT_DATA_CONFIGURED Data-type that holds the data related to USB device configured event. USB_DEVICE_FUNC_REGISTRATION_TABLE A function driver has to be registered with the USB device layer using this structure. USB_DEVICE_FUNCTION_DRIVER A function driver has to expose standard APIs to device layer using following structure. USB_DEVICE_HANDLE Data type for USB device handle. USB_DEVICE_INIT This structure has to be initialized by the system/application and must be passed as parameter to USB_DEVICE_Initialize(). USB_DEVICE_POWER_STATE Enumerated data type that identifies if the device is self powered or bus powered . USB_DEVICE_REMOTE_WAKEUP_STATUS Enumerated data type that identifies if the remote wakeup status of the device. USB_DEVICE_STATE Standard USB device states as described in Chapter-9 of USB 2.0 Specification. USB_DEVICE_STRING_DESCS_PTR Pointer to an array that contains pointer to string descriptors. USB_MASTER_DESCRIPTOR Global USB descriptor structure containing pointers to standard USB descriptor structures. USB_DEVICE_ENDPOINT_TABLE_SIZE This is macro USB_DEVICE_ENDPOINT_TABLE_SIZE. USB_DEVICE_HANDLE_INVALID Macro that defines the value of invalid device handle. Client Core Functions Name Description USB_DEVICE_Open Opens the specified USB device layer instance and returns a handle to it. USB_DEVICE_ControlReceive Receives data stage of the control transfer from host to device. USB_DEVICE_ControlSend Sends data stage of the control transfer from device to host. USB_DEVICE_Attach This function will attach the device to the USB. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4024 USB_DEVICE_Detach This function will detach the device from the USB. USB_DEVICE_Status Provides the current status of the USB device layer USB_DEVICE_ClientStatus Gets the current client-specific status of the USB device layer. USB_DEVICE_ResumeStart This function will start the resume signalling. USB_DEVICE_ResumeStop This function will stop the resume signalling. USB_DEVICE_GetDeviceSpeed Informs the client of the current operation speed of the USB bus. USB_DEVICE_GetDeviceState Returns the current state of the USB device. USB_DEVICE_GetConfigurationValue Informs the client of the current USB device configuration set by the USB host. USB_DEVICE_RemoteWakeupIsEnabled Gets the "Remote wakeup" status of the device. USB_DEVICE_PowerStateSet Sets power state of the device. Driver Interaction Functions Name Description USB_DEVICE_ControlStatus Initiates status stage of the control transfer. USB_DEVICE_EndpointEnable This function enables a endpoint for the specified direction and endpoint size. USB_DEVICE_EndpointIsEnabled This function returns the enable/ disable status of the specified endpoint and direction. USB_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. USB_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. USB_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. USB_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. USB_DEVICE_IRPSubmit This function submits a I/O Request Packet (IRP) for processing to the USB Driver. System Interaction Functions Name Description USB_DEVICE_Deinitialize Deinitializes the specified instance of the USB device layer. USB_DEVICE_Close Closes an opened handle to an instance of the USB device layer. USB_DEVICE_Initialize Creates and initializes an instance of the USB device layer. USB_DEVICE_ControlEventCallBackSet Client can register its call-back function into the device layer to get control transfer events. USB_DEVICE_Reinitialize Reinitializes the USB device layer USB_DEVICE_EndpointDisable This function disables an endpoint. USB_DEVICE_EventCallBackSet Client can register its call-back function into the device layer. USB_DEVICE_Tasks USB Device layer calls all other function driver tasks in this function. It also generates and forwards events to its clients. Description This section describes the Application Programming Interface (API) functions of the USB device layer library Refer to each section for a detailed description. 5.9.3.6.1 System Interaction Functions 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4025 5.9.3.6.1.1 USB_DEVICE_Deinitialize Function C void USB_DEVICE_Deinitialize( SYS_MODULE_OBJ usbDeviceObj ); Description This function deinitializes the specified instance of the USB device layer, disabling its operation (and any hardware) and invalidates all of the internal data. Preconditions Function USB_DEVICE_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameters Parameters Description object USB device layer object handle, returned by USB_DEVICE_Initialize Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Example 5.9.3.6.1.2 USB_DEVICE_Close Function C void USB_DEVICE_Close( USB_DEVICE_HANDLE usbDeviceHandle ); Description This function closes an opened handle to an instance of the USB device layer, invalidating the handle. Preconditions The USB_DEVICE_Initialize function must have been called for the specified device layer instance. USB_DEVICE_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from USB_DEVICE_Open Returns None Remarks After calling this routine, the handle passed in "usbDevHandle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling USB_DEVICE_Open() before the client may use the device layer again. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4026 Example USB_DEVICE_HANDLE usbDeviceHandle; // Before opening a handle, USB device must have been initialized // by calling USB_DEVICE_Initialize(). usbDeviceHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0 ); if(USB_DEVICE_HANDLE_INVALID == usbDeviceHandle) { //Failed to open handle. } ................. ................. // User's code ................. ................. // Close handle USB_DEVICE_Close( usbDevHandle ); 5.9.3.6.1.3 USB_DEVICE_Initialize Function C SYS_MODULE_OBJ USB_DEVICE_Initialize( const SYS_MODULE_INDEX instanceIndex, const SYS_MODULE_INIT * const init ); Description This function initializes an instance of USB device layer, making it ready for clients to open and use it. The number of instances is limited by the value of macro USB_DEVICE_MAX_INSTANCES. Preconditions None. Parameters Parameters Description instanceIndex In case of microcontrollers with multiple USB peripherals, user can create multiple instances of USB device layer. Parameter instanceIndex identifies this instance. init Pointer to a data structure containing any data necessary to initialize the USB device layer Returns If successful, returns a valid handle to a device layer object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Remarks This routine must be called before any other USB Device Layer routine is called and after the initialization of USB Device Driver. This routine should only be called once during system initialization. Example USB_DEVICE_INIT deviceLayerInit; SYS_MODULE_OBJ usbDeviceObj; // System module initialization deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; // Identifies peripheral (PLIB-level) ID deviceLayerInit.usbID = USB_ID_1; // Boolean flag: true -> Stop USB module in Idle Mode deviceLayerInit.stopInIdle = false; 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4027 // Boolean flag: true -> Suspend USB in Sleep Mode deviceLayerInit.suspendInSleep = false; // Interrupt Source for USB module deviceLayerInit.interruptSource = INT_SOURCE_USB_1; // Number of function drivers registered to this instance of the USB device layer deviceLayerInit.registeredFuncCount = 1; // Function driver table registered to this instance of the USB device layer deviceLayerInit.registeredFunctions = funcRegistrationTable; // Pointer to USB Descriptor structure deviceLayerInit.usbMasterDescriptor = &usbMasterDescriptor; // USB device initialization usbDeviceObj = USB_DEVICE_Initialize(USB_DEVICE_INDEX_0, &deviceLayerInit); if (SYS_MODULE_OBJ_INVALID == usbDeviceObj) { // Handle error } 5.9.3.6.1.4 USB_DEVICE_ControlEventCallBackSet Function C USB_ERROR USB_DEVICE_ControlEventCallBackSet( USB_DEVICE_HANDLE usbDeviceHandle, const USB_DEVICE_CONTROL_TRANSFER_CALLBACK callBackFunc ); Description The USB Device Layer notifies the control transfer events to the client by calling callBackFunc. Preconditions The device layer must have been initialized by calling USB_DEVICE_Initialize and a valid handle to the instance must have been obtained by calling USB_DEVICE_Open. Parameters Parameters Description usbDeviceHandle Pointer to the device layer handle that is returned from USB_DEVICE_Open callBackFunc Pointer to the control transfer event handler. The device layer notifies the client about control transfer event by calling this function. Returns Returns USB_ERROR_NONE if successful. Remarks None. Example 5.9.3.6.1.5 USB_DEVICE_Reinitialize Function C void USB_DEVICE_Reinitialize( SYS_MODULE_OBJ usbDeviceObj, const SYS_MODULE_INIT * const init ); Description This function reinitializes the USB device layer. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4028 Preconditions USB device driver and USB device layer must have been initialized. Parameters Parameters Description usbDeviceObj Driver object handle, returned by USB_DEVICE_Initialize init Pointer to a data structure containing any data necessary to reinitialize the USB device layer. Returns None Remarks This function can be called multiple times to reinitialize the USB device layer. This operation reinitializes all the module variables of the USB device layer associated with the instance specified by the parameter "usbDeviceObj". Example USB_DEVICE_INIT deviceLayerInit; // System module initialization deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; // Identifies peripheral (PLIB-level) ID deviceLayerInit.usbID = USB_ID_1; // Boolean flag: true -> Stop USB module in Idle Mode deviceLayerInit.stopInIdle = false; // Boolean flag: true -> Suspend USB in Sleep Mode deviceLayerInit.suspendInSleep = false; // Interrupt Source for USB module deviceLayerInit.interruptSource = INT_SOURCE_USB_1; // Number of function drivers registered to this instance of the USB device layer deviceLayerInit.registeredFuncCount = 1; // Function driver table registered to this instance of the USB device layer deviceLayerInit.registeredFunctions = funcRegistrationTable; // Pointer to USB Descriptor structure deviceLayerInit.usbMasterDescriptor = &usbMasterDescriptor; // USB device initialization usbDeviceObj = USB_DEVICE_Initialize(USB_DEVICE_INDEX_0, &deviceLayerInit); if (SYS_MODULE_OBJ_INVALID == usbDeviceObj) { } // Do something here. // Re-initialize if required. // System module initialization deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; // Identifies peripheral (PLIB-level) ID deviceLayerInit.usbID = USB_ID_1; // Boolean flag: true -> Stop USB module in Idle Mode deviceLayerInit.stopInIdle = false; // Boolean flag: true -> Suspend USB in Sleep Mode deviceLayerInit.suspendInSleep = false; // Interrupt Source for USB module deviceLayerInit.interruptSource = INT_SOURCE_USB_1; // Number of function drivers registered to this instance of the 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4029 USB device layer deviceLayerInit.registeredFuncCount = 1; // Function driver table registered to this instance of the USB device layer deviceLayerInit.registeredFunctions = funcRegistrationTable; // Pointer to USB Descriptor structure deviceLayerInit.usbMasterDescriptor = &usbMasterDescriptor; USB_DEVICE_ReInitialize(USB_DEVICE_INDEX_0, &deviceLayerInit); 5.9.3.6.1.6 USB_DEVICE_EndpointDisable Function C USB_ERROR USB_DEVICE_EndpointDisable( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection ); Description This function disables an endpoint. If the endpoint type is control type then both directions are disabled. For non-control endpoints, the function disables one direction at a time. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks This function must not be called by the application clients. Application has no access to modify the endpoint features. Example // This code snippet shows an example of how to disable // a control endpoint. Note that the direction parameter is ignored. // For a control endpoinnt, both the directions are disabled. handle = USB_DEVICE_Open(USB_DEVICE_INDEX_0); USB_ENDPOINT ep; ep.endpoint = 0; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointDisable(handle, ep ); // This code snippet shows an example of how to disable a BULK IN // endpoint USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointDisable(handle, ep ); 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4030 5.9.3.6.1.7 USB_DEVICE_EventCallBackSet Function C USB_ERROR USB_DEVICE_EventCallBackSet( USB_DEVICE_HANDLE usbDeviceHandle, const USB_DEVICE_CALLBACK callBackFunc ); Description The USB Device Layer notifies the event to the client by calling callBackFunc. Preconditions The device layer must have been initialized by calling USB_DEVICE_Initialize and a valid handle to the instance must have been obtained by calling USB_DEVICE_Open. Parameters Parameters Description usbDeviceHandle Pointer to the device layer handle that is returned from USB_DEVICE_Open callBackFunc Pointer to the call back function. The device layer calls notifies the client about bus event by calling this function. Returns Returns USB_ERROR_NONE if successful. Remarks None. Example 5.9.3.6.1.8 USB_DEVICE_Tasks Function C void USB_DEVICE_Tasks( SYS_MODULE_OBJ object ); Description This function must be periodically called by the user application. The USB Device layer calls all other function driver tasks in this function. It also generates and forwards events to its clients. Preconditions Device layer must have been initialized by calling USB_DEVICE_Initialize. Parameters Parameters Description devLayerObj Pointer to the Device Layer Object that is returned from USB_DEVICE_Initialize Returns none. Remarks This function must be called only after the device layer is initialized by calling function USB_DEVICE_Initialize. Example 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4031 5.9.3.6.2 Client Core Functions 5.9.3.6.2.1 USB_DEVICE_Open Function C USB_DEVICE_HANDLE USB_DEVICE_Open( const SYS_MODULE_INDEX instanceIndex, const DRV_IO_INTENT intent ); Description This function opens the USB device layer instance specified by instance index and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the USB device layer. The number of handles a client can open is limited by the value set to USB_DEVICE_MAX_CLIENTS. Preconditions This function must be called after USB device driver initialization and after the initialization of USB Device Layer. Parameters Parameters Description instanceIndex USB device layer instance index intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Returns If successful, returns a valid handle to a device layer object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Remarks This routine must be called after USB device driver initialization and after the initialization of USB Device Layer. This routine should be called only once during system initialization. Example USB_DEVICE_HANDLE usbDeviceHandle; // Before opening a handle, USB device must have been initialized // by calling USB_DEVICE_Initialize(). usbDeviceHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0, DRV_IO_INTENT_BLOCKING ); if(USB_DEVICE_HANDLE_INVALID == usbDeviceHandle) { //Failed to open handle. } 5.9.3.6.2.2 USB_DEVICE_ControlReceive Function C USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlReceive( USB_DEVICE_HANDLE usbDeviceHandle, USB_DEVICE_CONTROL_TRANSFER_HANDLE controlXferHandle, void * data, size_t length ); Preconditions Client handle should be valid. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4032 Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). controlXferHandle Control transfer handle that is returned by bus event callback function. data Pointer to buffer that holds data. length Size in bytes. Returns USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED - If control transfer is failed due to host aborting the previous control transfer. USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS - Control endpoint is successfully armed with data buffer. Example 5.9.3.6.2.3 USB_DEVICE_ControlSend Function C USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlSend( USB_DEVICE_HANDLE usbDeviceHandle, USB_DEVICE_CONTROL_TRANSFER_HANDLE controlXferHandle, void * data, size_t length ); Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). controlXferHandle Control transfer handle that is returned by the in bus event callback function. data Pointer to buffer that holds data. length Size in bytes. Returns USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED - If control transfer is failed due to host aborting the previous control transfer. USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS - Control endpoint is successfully armed with data buffer. Example 5.9.3.6.2.4 USB_DEVICE_Attach Function C void USB_DEVICE_Attach( USB_DEVICE_HANDLE usbDeviceHandle ); Description This function will attach the device to the USB. It does this by enabling the pull up resistors on the D+ or D- lines. This function should be called when the USB device layer is ready to receive communication from the host (typically after all initialization is complete). 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4033 Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle Client's USB device layer handle (returned from USB_DEVICE_Open) Returns None. Remarks None. Example USB_DEVICE_INIT deviceLayerInit; SYS_MODULE_OBJ usbDeviceObj; USB_DEVICE_HANDLE usbDeviceHandle; // System module initialization deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; // Identifies peripheral (PLIB-level) ID deviceLayerInit.usbID = USB_ID_1; // Boolean flag: true -> Stop USB module in Idle Mode deviceLayerInit.stopInIdle = false; // Boolean flag: true -> Suspend USB in Sleep Mode deviceLayerInit.suspendInSleep = false; // Interrupt Source for USB module deviceLayerInit.interruptSource = INT_SOURCE_USB_1; // Number of function drivers registered to this instance of the USB device layer deviceLayerInit.registeredFuncCount = 1; // Function driver table registered to this instance of the USB device layer deviceLayerInit.registeredFunctions = funcRegistrationTable; // Pointer to USB Descriptor structure deviceLayerInit.usbMasterDescriptor = &usbMasterDescriptor; // USB device initialization usbDeviceObj = USB_DEVICE_Initialize(USB_DEVICE_INDEX_0, &deviceLayerInit); if (SYS_MODULE_OBJ_INVALID == usbDeviceObj) { // Handle error } // Get an handle to the USB device layer. usbDeviceHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0, DRV_IO_INTENT_BLOCKING ); if(USB_DEVICE_HANDLE_INVALID == usbDeviceHandle) { // Failed to open handle. // Handle error. } // Now, connect device to USB USB_DEVICE_Attach(usbDeviceHandle); 5.9.3.6.2.5 USB_DEVICE_Detach Function C void USB_DEVICE_Detach( 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4034 USB_DEVICE_HANDLE usbDeviceHandle ); Description This function will detach the device from the USB. It does this by disabling the pull up resistors on the D+ or D- lines. This function should be called when the application wants to disconnect the device from the bus (typically to implement a soft detach or switch to host mode operation). Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle Client's driver handle (returned from USB_DEVICE_Open) Returns None. Remarks None. Example USB_DEVICE_HANDLE usbDeviceHandle; // Detach the device from the USB USB_DEVICE_Detach( usbDeviceHandle ); 5.9.3.6.2.6 USB_DEVICE_Status Function C SYS_STATUS USB_DEVICE_Status( SYS_MODULE_OBJ object ); Description This function provides the current status of the USB device layer. Preconditions The USB_DEVICE_Initialize function must have been called before calling this function. Parameters Parameters Description object Driver object handle, returned from USB_DEVICE_Initialize Returns SYS_STATUS_READY - Indicates that the device is busy with a previous system level operation and cannot start another Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the device is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the device is busy with a previous system level operation and cannot start another SYS_STATUS_UNINITIALIZED - Indicates that the device has never been initialized SYS_STATUS_ERROR - Indicates that the device is in an error state 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4035 Any value less than SYS_STATUS_ERROR is also an error state. None. Example SYS_MODULE_OBJ object; // Returned from DRV_USB_Initialize SYS_STATUS status; status = USB_DEVICE_Status(object); if (SYS_STATUS_ERROR >= status) { // Handle error } 5.9.3.6.2.7 USB_DEVICE_ClientStatus Function C DRV_CLIENT_STATUS USB_DEVICE_ClientStatus( USB_DEVICE_HANDLE usbDevHandle ); Description This function gets the client-specfic status of the USB device layer associated with the specified handle. Preconditions The USB_DEVICE_Initialize function must have been called. USB_DEVICE_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open instance handle, returned from USB_DEVICE_Open Returns A value of enum type DRV_CLIENT_STATUS describing the current status of the USB device layer. Remarks None. Example 5.9.3.6.2.8 USB_DEVICE_ResumeStart Function C void USB_DEVICE_ResumeStart( USB_DEVICE_HANDLE usbDeviceHandle ); Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle Client's driver handle (returned from USB_DEVICE_Open) Returns None. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4036 Remarks None. Example 5.9.3.6.2.9 USB_DEVICE_ResumeStop Function C void USB_DEVICE_ResumeStop( USB_DEVICE_HANDLE usbDeviceHandle ); Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle Client's driver handle (returned from USB_DEVICE_Open) Returns None. Remarks None. Example 5.9.3.6.2.10 USB_DEVICE_GetDeviceSpeed Function C USB_SPEED USB_DEVICE_GetDeviceSpeed( USB_DEVICE_HANDLE usbDeviceHandle ); Description The USB device stack supports both high speed and full speed operations. This function returns the current operation speed of the USB bus. Preconditions The USB device layer must have been initialized and a valid handle to USB device layer must have been opened. Parameters Parameters Description usbDeviceHandle Pointer to device layer handle that is returned from USB_DEVICE_Open Returns USB_SPEED_LOW - USB module is at low speed USB_SPEED_FULL - USB module is at full speed USB_SPEED_HIGH - USB module is at high speed Remarks This function must be called only after the device layer is initialized and opened by calling USB_DEVICE_Initialize and USB_DEVICE_Open. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4037 Example 5.9.3.6.2.11 USB_DEVICE_GetDeviceState Function C USB_DEVICE_STATE USB_DEVICE_GetDeviceState( USB_DEVICE_HANDLE usbDeviceHandle ); Description This function returns the current state of the USB device, as described in Chapter 9 of USB 2.0 Specification. Preconditions The USB device layer must have been initialized and opened before calling this function. Parameters Parameters Description usbDeviceHandle Pointer to the device layer handle that is returned from USB_DEVICE_Open Returns USB_DEVICE_STATE_DETACHED - Device is not in any of the known states USB_DEVICE_STATE_ATTACHED - Device is attached to the USB, but is not powered USB_DEVICE_STATE_POWERED - Device is attached to the USB and powered, but has not been reset USB_DEVICE_STATE_DEFAULT - Device is attached to the USB and powered and has been reset, but has not been assigned a unique address USB_DEVICE_STATE_ADDRESS - Device is attached to the USB, powered, has been reset, and a unique device address has been assigned USB_DEVICE_STATE_CONFIGURED - Device is attached to the USB, powered, has been reset, has a unique address, is configured, and is not suspended USB_DEVICE_STATE_SUSPENDED - Device is, at minimum, attached to the USB and is powered and has not seen bus activity for 3 ms. The device is still in addresed state. Remarks This function must be called only after the device layer is initialized and opened by calling USB_DEVICE_Initialize and USB_DEVICE_Open. Example USB_DEVICE_STATE usbDevState; // Get USB Device State. usbDevState = USB_DEVICE_GetDeviceState( usbDeviceHandle ); switch(usbDevState) { case USB_DEVICE_STATE_ATTACHED: // Add code here break; case USB_DEVICE_STATE_POWERED: // Add code here break; default: 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4038 break; } 5.9.3.6.2.12 USB_DEVICE_GetConfigurationValue Function C uint8_t USB_DEVICE_GetConfigurationValue( USB_DEVICE_HANDLE usbDeviceHandle ); Description This function returns the current active USB device configuration. Preconditions The USB Device Layer must have been initialized and opened before calling this function. Parameters Parameters Description usbDeviceHandle Pointer to the Device Layer Handle that is returned from USB_DEVICE_Open Returns Present active configuration. Remarks This function must be called only after the device layer is initialized and opened by calling USB_DEVICE_Initialize and USB_DEVICE_Open. Example 5.9.3.6.2.13 USB_DEVICE_RemoteWakeupIsEnabled Function C USB_DEVICE_REMOTE_WAKEUP_STATUS USB_DEVICE_RemoteWakeupIsEnabled( USB_DEVICE_HANDLE usbDeviceHandle ); Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). Returns USB_DEVICE_REMOTE_WAKEUP_ENABLED - Remote wakeup is enabled. USB_DEVICE_REMOTE_WAKEUP_DISABLED - Remote wakeup is disabled. Example 5.9.3.6.2.14 USB_DEVICE_PowerStateSet Function C void USB_DEVICE_PowerStateSet( USB_DEVICE_HANDLE usbDeviceHandle, USB_DEVICE_POWER_STATE powerState ); 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4039 Description Application clients can use this function to set the power state of the device. A USB device can be bus powered ot self powered. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). powerState USB_DEVICE_POWER_STATE_BUS_POWERED/ USB_DEVICE_POWER_STATE_SELF_POWERED Returns None. Example 5.9.3.6.3 Driver Interaction Functions 5.9.3.6.3.1 USB_DEVICE_ControlStatus Function C USB_DEVICE_CONTROL_TRANSFER_RESULT USB_DEVICE_ControlStatus( USB_DEVICE_HANDLE usbDeviceHandle, USB_DEVICE_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_CONTROL_STATUS status ); Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). controlTransferHandle Control transfer handle that is returned by bus event callback function. status USB_DEVICE_CONTROL_STATUS_SEND_ZLP/ USB_DEVICE_CONTROL_STATUS_STALL Returns USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED - If control transfer is failed due to host aborting the previous control transfer. USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS - Control endpoint is successfully armed with data buffer. Example 5.9.3.6.3.2 USB_DEVICE_EndpointEnable Function C USB_ERROR USB_DEVICE_EndpointEnable( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4040 ); Description This function enables a endpoint for the specified direction and endpoint size. The function will enable the endpoint for communication in one direction at a time. It must be called twice if the endpoint is required to communicate in both the directions, except for control endpoints. If the endpoint type is a control endpoint, the endpoint is always bi-directional and the function needs to be called only once. The size of the endpoint must match the wMaxPacketSize reported in the endpoint descriptor for this endpoint. The function does not check if the endpoint is already in use. It is the client's responsibility to make sure that a endpoint is not accidently re-used. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. transferType Should be USB_TRANSFER_TYPE_CONTROL for control endpoint, USB_TRANSFER_TYPE_BULK for bulk endpoint, USB_TRANSFER_TYPE_INTERRUPT for interrupt endpoint and USB_TRANSFER_TYPE_ISOCHRONOUS for isochronous endpoint. endpointSize Maximum size (in bytes) of the endpoint as reported in the endpoint descriptor. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks None. Example // This code snippet shows an example of how to enable endpoint // 0 for control transfers. Note that for a control endpoint, the // direction parameter is ignored. A control endpoint is always // bi-directional. Endpoint sizeis 64 bytes. USB_ENDPOINT ep; handle = USB_DEVICE_Open(USB_DEVICE_INDEX_0); ep.endpoint = 0; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_CONTROL, 64); // This code snippet shows an example of how to set up a endpoint // for BULK IN transfer. For an IN transfer, data moves from device // to host. In this example, endpoint 1 is enabled. The maximum // packet size is 64. USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); // If endpoint 1 must also be set up for BULK OUT, then the enable // function must be called again, as shown here. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4041 ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_HOST_TO_DEVICE; USB_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); 5.9.3.6.3.3 USB_DEVICE_EndpointIsEnabled Function C bool USB_DEVICE_EndpointIsEnabled( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection ); Description This function returns the enable/ disable status of the specified endpoint and direction. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns Returns true if the endpoint is enabled, false otherwise. Remarks This function must not be called by the application clients. Application has no access to read the endpoint features. Example // This code snippet shows an example of how the // USB_DEVICE_EndpointIsEnabled() function can be used to obtain the // status of the endpoint 1 and IN direction. USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; if(DRV_USB_ENDPOINT_STATE_DISABLED == USB_DEVICE_EndpointIsEnabled(handle, ep)) { // Endpoint is disabled. Enaable endpoint. USB_DEVICE_EndpointEnable(handle, ep, USB_ENDPOINT_TYPE_BULK, 64); } 5.9.3.6.3.4 USB_DEVICE_EndpointIsStalled Function C bool USB_DEVICE_EndpointIsStalled( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpoint ); Description This function returns the stall status of the specified endpoint and direction. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4042 Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns Returns true if endpoint is stalled, false otherwise. Remarks This function must not be called by the application clients. Application has no access to read the endpoint features. Example // This code snippet shows an example of how the // USB_DEVICE_EndpointIsStalled() function can be used to obtain the // stall status of the endpoint 1 and IN direction. USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; if(true == USB_DEVICE_EndpointIsStalled (handle, ep)) { // Endpoint stall is enabled. Clear the stall. USB_DEVICE_EndpointStallClear(handle, ep); } 5.9.3.6.3.5 USB_DEVICE_EndpointStall Function C USB_ERROR USB_DEVICE_EndpointStall( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection ); Description This function stalls an endpoint in the specified direction. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4043 Remarks This function must not be called by the application clients. Application has no access to modify the endpoint features. Example // This code snippet shows an example of how to stall an endpoint. In // this case , endpoint 1 IN direction is stalled. USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointStall(handle, ep); 5.9.3.6.3.6 USB_DEVICE_EndpointStallClear Function C USB_ERROR USB_DEVICE_EndpointStallClear( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection ); Description This function clears the stall on an endpoint in the specified direction. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks This function must not be called by the application clients. Application has no access to modify the endpoint features. Example // This code snippet shows an example of how to clear a stall. In this // example. the stall on endpoint 1 IN direction is cleared. USB_ENDPOINT ep; ep.endpoint = 1; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; USB_DEVICE_EndpointStallClear(handle, ep); 5.9.3.6.3.7 USB_DEVICE_IRPCancelAll Function C USB_ERROR USB_DEVICE_IRPCancelAll( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection ); 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4044 Description This function cancels all IRPs that are queued and in progress at the specified endpoint. The driver checks if IRPs are to be cancelled at two instances; when it has called the IRP callback and is ready to proccess the next IRP in the queue and when it is ready to process the next transaction in the the current IRP. It is recommended that this function be called in the IRP callback of the IRP that just completed as this ensures that an IRP in progress is not cancelled. Cancelling an IRP that is progress may cause disturbance to the USB host firmware. Cancelling the IRP from any other location, other than a IRP callback could cause an IRP that is in progress to get cancelled. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. Returns USB_ERROR_NONE - The endpoint was successfully enabled. USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is is out of the valid endpoint defined for this driver instance. Remarks This function must not be called by the application clients. Application has no access modify the IRPs. Example // This code snippet shows an exampl of how to cancel all IRPs. void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if this is setup command if(irp->status == USB_DEVICE_IRP_STATUS_SETUP) { if(IsSetupCommandSupported(irp->data) == false) { // This means that this setup command is not // supported. Stall the endpoint. USB_DEVICE_IRPCancelAll(handle, ep); USB_DEVICE_EndpointStall(handle, ep); } } } 5.9.3.6.3.8 USB_DEVICE_IRPSubmit Function C USB_ERROR USB_DEVICE_IRPSubmit( USB_DEVICE_HANDLE usbDeviceHandle, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp ); Description This function submits a I/O Request Packet (IRP) for processing to the USB Driver. The IRP allows a client to send and receive data from the USB Host. The data will sent or received through the specified endpoint. The direction of the data transfer is indicated by the direction flag in the endpointAndDirection structure. Submitting an IRP arms the endpoint to either send data to 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4045 or receive data from the host. If an IRP is under progress on the endpoint, then the subsequent IRP submit operation will result in the IRPs getting queued. The contents of the IRP should not be changed till the IRP has been processed. Particular attention should be paid to the size parameter of IRP. The following should be noted: • The size parameter while sending data to the host can be less than, greater than, equal to or be an exact multiple of maximum packet size for the endpoint. The maximum packet size for the endpoint determines the number of transactions required to process the IRP. • If the size parameter while sending data to the host is less than maximum packet size, the transfer will complete in one transaction. • If the size parameter while sending data to the host is greater than maximum packet size, the IRP will be processed in mulitple transactions. • If the size parameter while sending data to the host is equal to or an exact multiple of the maximum packet size, the client can optionally ask the driver to send a Zero Length packet by specifying the USB_DEVICE_IRP_FLAG_SEND_ZLP flag as the flag parameter. • The size parameter while receiving data from the host must be an exact multiple of the maximum packet size of the endpoint. If this is not the case, the driver will return a USB_DEVICE_IRP_SUBMIT_RESULT_INVALID_SIZE result. If while processing the IRP, the driver receives less than maximum packet size or a ZLP from the host, the driver considers the IRP as processed. The size paramter at this point contains the actual amount of data received from the host. Preconditions Client handle should be valid. Parameters Parameters Description usbDeviceHandle USB device handle returned by USB_DEVICE_Open(). endpointAndDirection Specifies the endpoint and direction. irp Pointer to the USB_DEVICE_IRP structure. Returns USB_ERROR_NONE - if the IRP was submitted successful. USB_ERROR_IRP_SIZE_INVALID - if the size parameter of the IRP is not correct. USB_ERROR_IRP_QUEUE_FULL - if the driver IRP queue is full. Remarks This function must not be called by the application clients. Application must not submit IRP directly. Example // The following code snippet shows an example of how to schedule a // IRP to send data from device to host. Assume that max packet size // is 64 and endpoint is 1. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_DATA_DIRECTION_DEVICE_TO_HOST; ep.endpoint = 1; irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_NONE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (USB_DEVICE_IRPSubmit(handle, ep, irp) != USB_ERROR_NONE) { 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4046 // This means there was an error. } else { // The status of the IRP can be checked. while(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Wait or run a task routine. } } // The following code snippet shows how the client can request // the driver to send a ZLP when the size is an exact multiple of // end point size. irp.data = myDataBufferToSend; irp.size = 128; irp.flags = USB_DEVICE_IRP_FLAG_SEND_ZLP; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; // Note that while receiving data from the host, the size should // be an exact multiple maximum packet size of the endpoint. In the // example below, the USB_DEVICE_IRPSubmit() function will // return a USB_DEVICE_IRP_SUBMIT_RESULT_INVALID_SIZE value. ep.direction = USB_DATA_DIRECTION_HOST_TO_DEVICE; ep.endpoint = 1; irp.data = myDataBufferToSend; irp.size = 60; // THIS SIZE IS NOT CORRECT irp.flags = USB_DEVICE_IRP_FLAG_NONE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; 5.9.3.6.4 Data Types and Constants 5.9.3.6.4.1 USB_DEVICE_INDEX_0 Macro C #define USB_DEVICE_INDEX_0 0 Description USB Device Layer Index Numbers These constants provide USB device layer index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the USB_DEVICE_Initialize and USB_DEVICE_Open routines to identify the device layer instance in use. 5.9.3.6.4.2 USB_DEVICE_INDEX_1 Macro C #define USB_DEVICE_INDEX_1 1 Description This is macro USB_DEVICE_INDEX_1. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4047 5.9.3.6.4.3 USB_DEVICE_INDEX_2 Macro C #define USB_DEVICE_INDEX_2 2 Description This is macro USB_DEVICE_INDEX_2. 5.9.3.6.4.4 USB_DEVICE_INDEX_3 Macro C #define USB_DEVICE_INDEX_3 3 Description This is macro USB_DEVICE_INDEX_3. 5.9.3.6.4.5 USB_DEVICE_INDEX_4 Macro C #define USB_DEVICE_INDEX_4 4 Description This is macro USB_DEVICE_INDEX_4. 5.9.3.6.4.6 USB_DEVICE_INDEX_5 Macro C #define USB_DEVICE_INDEX_5 5 Description This is macro USB_DEVICE_INDEX_5. 5.9.3.6.4.7 USB_DEVICE_INDEX_COUNT Macro C #define USB_DEVICE_INDEX_COUNT _USB_DEVICE_EXISTS Description USB Device Layer Module Index Count This constant identifies number of valid USB device layer indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. 5.9.3.6.4.8 USB_DEVICE_CALLBACK Type C typedef void (* USB_DEVICE_CALLBACK)(USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData); 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4048 Description USB Device Layer Callback Function Pointer This is the data type of the callback function that will be called by the USB device layer when there is a bus event from USB device layer. Remarks A USB Device Layer callback function must have the following function signature: void MyCallBack ( USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData ); Where, "event" indicates an event on the USB device layer, and "MyCallBack" can be any name desired as the function is called through the pointer. 5.9.3.6.4.9 USB_DEVICE_CONFIG_DESCS_PTR Type C typedef uint8_t** USB_DEVICE_CONFIG_DESCS_PTR; Description Configuration descriptors pointer 5.9.3.6.4.10 USB_DEVICE_CONTROL_STATUS Enumeration C typedef enum { USB_DEVICE_CONTROL_STATUS_OK, USB_DEVICE_CONTROL_STATUS_ERROR } USB_DEVICE_CONTROL_STATUS; Description Control transfer status stage Members Members Description USB_DEVICE_CONTROL_STATUS_OK Control transfer is supported. Send ZLP in the status stage. USB_DEVICE_CONTROL_STATUS_ERROR Control transfer is not supported. Stall control endpoint. Remarks Also see, USB_DEVICE_ControlStatus 5.9.3.6.4.11 USB_DEVICE_CONTROL_TRANSFER_CALLBACK Type C typedef void (* USB_DEVICE_CONTROL_TRANSFER_CALLBACK)(USB_DEVICE_CONTROL_TRANSFER_HANDLE handle, USB_DEVICE_CONTROL_TRANSFER_EVENT event, USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA * eventData); Description USB Device Layer control transfer callback Function Pointer This is the data type of the callback function that will be called by the USB device layer when there is a control transfer event from USB device layer. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4049 Remarks A USB Device Layer callback function must have the following function signature: void MyCallBack ( USB_DEVICE_EVENT event, USB_DEVICE ); Where, "event" indicates an event on the USB device layer, and "MyCallBack" can be any name desired as the function is called through the pointer. 5.9.3.6.4.12 USB_DEVICE_CONTROL_TRANSFER_EVENT Enumeration C typedef enum { USB_DEVICE_CONTROL_TRANSFER_ABORTED, USB_DEVICE_CONTROL_DATA_RECEIVED, USB_DEVICE_CONTROL_SETUP_REQUEST, USB_DEVICE_CONTROL_DATA_SENT = 3 } USB_DEVICE_CONTROL_TRANSFER_EVENT; Description USB Device control transfer events Members Members Description USB_DEVICE_CONTROL_TRANSFER_ABORTED Previous control transfer was aborted. USB_DEVICE_CONTROL_DATA_RECEIVED Control transfer data stage was completed USB_DEVICE_CONTROL_SETUP_REQUEST A setup packet was received and control transfer is in setup stage USB_DEVICE_CONTROL_DATA_SENT = 3 Control transfer data stage transmit is complete Remarks None. 5.9.3.6.4.13 USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA Union C typedef union { USB_SETUP_PACKET * setupRequest; } USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA; Description USB Device control transfer event data. Members Members Description USB_SETUP_PACKET * setupRequest; Data associated with USB_DEVICE_CONTROL_SETUP_REQUEST Remarks None. 5.9.3.6.4.14 USB_DEVICE_CONTROL_TRANSFER_HANDLE Type C typedef uintptr_t USB_DEVICE_CONTROL_TRANSFER_HANDLE; 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4050 Description Data type of control transfer handle. This is the data type of the handle that must be used by the application client for all control transfers. Remarks Also see, USB_DEVICE_ControlSend USB_DEVICE_ControlReceive USB_DEVICE_ControlStatus 5.9.3.6.4.15 USB_DEVICE_CONTROL_TRANSFER_RESULT Enumeration C typedef enum { USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED, USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS } USB_DEVICE_CONTROL_TRANSFER_RESULT; Description These enumerated values are the possible return values for control transfer operation. Members Members Description USB_DEVICE_CONTROL_TRANSFER_RESULT_FAILED Control transfer failed. This could be because the control transfer handle is no more valid since the control transfer was aborted by host by sending a new setup packet USB_DEVICE_CONTROL_TRANSFER_RESULT_SUCCESS Control transfer was successful Remarks Also see, USB_DEVICE_ControlSend USB_DEVICE_ControlReceive USB_DEVICE_ControlStatus 5.9.3.6.4.16 USB_DEVICE_EVENT Enumeration C typedef enum { USB_DEVICE_EVENT_RESET, USB_DEVICE_EVENT_SUSPENDED, USB_DEVICE_EVENT_RESUMED, USB_DEVICE_EVENT_ERROR, USB_DEVICE_EVENT_SOF, USB_DEVICE_EVENT_DETACHED, USB_DEVICE_EVENT_DECONFIGURED, USB_DEVICE_EVENT_CONFIGURED, USB_DEVICE_EVENT_ATTACHED } USB_DEVICE_EVENT; Description Datatype that identifies the event that is active in the USB device layer. Members Members Description USB_DEVICE_EVENT_RESET USB bus reset occurred. This event is an indication to the application client that device layer is about to de-initialize the function drivers. For application client, this event means that it has to close any open handles to function drivers USB_DEVICE_EVENT_SUSPENDED This event is an indication to the application client that device is suspended and it can put the device to power-down mode if required. USB_DEVICE_EVENT_RESUMED This event indicates that device has resumed from suspended state. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4051 USB_DEVICE_EVENT_ERROR This event is an indication to the application client that an error occurred on the USB bus 5.9.3.6.4.17 USB_DEVICE_EVENT_DATA Union C typedef union { USB_DEVICE_EVENT_DATA_CONFIGURED eventConfigured; } USB_DEVICE_EVENT_DATA; Members Members Description USB_DEVICE_EVENT_DATA_CONFIGURED eventConfigured; Data related to configured event Remarks Also see USB_DEVICE_CALLBACK 5.9.3.6.4.18 USB_DEVICE_EVENT_DATA_CONFIGURED Structure C typedef struct { uint8_t configurationValue; USB_SPEED speed; } USB_DEVICE_EVENT_DATA_CONFIGURED; Members Members Description uint8_t configurationValue; Configuration value selected by the host USB_SPEED speed; USB speed at which the device is connected to host Remarks Also see USB_DEVICE_EVENT_DATA USB_DEVICE_CALLBACK 5.9.3.6.4.19 USB_DEVICE_FUNC_REGISTRATION_TABLE Structure C typedef struct { USB_SPEED speed; uint8_t configurationValue; uint8_t interfaceNumber; uint8_t numberOfInterfaces; SYS_MODULE_INDEX funcDriverIndex; void* funcDriverInit; USB_DEVICE_FUNCTION_DRIVER* driver; } USB_DEVICE_FUNC_REGISTRATION_TABLE; Description Global USB Device function registration structure Members Members Description USB_SPEED speed; Type of speed (high, full or low speed) uint8_t configurationValue; Configuration Value to which the function driver has to be tied 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4052 uint8_t interfaceNumber; Interface number to which this function driver has to be tied uint8_t numberOfInterfaces; Number of interfaces used by the function SYS_MODULE_INDEX funcDriverIndex; Function driver instance index void* funcDriverInit; Pointer to a structure that contains function driver initialization data USB_DEVICE_FUNCTION_DRIVER* driver; Pinter to a standard structure that exposes function driver APIs to USB device layer 5.9.3.6.4.20 USB_DEVICE_FUNCTION_DRIVER Structure C typedef struct { void (* initializeByDescriptor)(SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_HANDLE usbDeviceHandle, void* funcDriverInit, uint8_t interfaceNumber, uint8_t alternateSetting, uint8_t descriptorType, uint8_t * pDescriptor); void (* deInitialize)(SYS_MODULE_INDEX funcDriverIndex); void (* controlTransferNotification)(USB_DEVICE_CONTROL_TRANSFER_HANDLE controlHandle, SYS_MODULE_INDEX index, USB_DEVICE_CONTROL_TRANSFER_EVENT controlEvent, USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA * controlEventData); void (* tasks)(SYS_MODULE_INDEX funcDriverIndex); } USB_DEVICE_FUNCTION_DRIVER; Description USB function driver structure All function drivers (including vendor specific ones) must provide callback functions to USB device layer in the format specified by this structure. The USB device layer calls these callback functions at the time of appropriate event. Members Members Description void (* initializeByDescriptor)(SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_HANDLE usbDeviceHandle, void* funcDriverInit, uint8_t interfaceNumber, uint8_t alternateSetting, uint8_t descriptorType, uint8_t * pDescriptor); Initialize gets called by the Device layer when it recieves set configuration event. The device layer will initialize a function driver for every descriptor. Based on the descriptor type the function driver has to initialize itself. void (* deInitialize)(SYS_MODULE_INDEX funcDriverIndex); deInit gets called when the device layer detects a device dettach, change in configuration or ob USB bus reset. void (* controlTransferNotification)(USB_DEVICE_CONTROL_TRANSFER_HANDLE controlHandle, SYS_MODULE_INDEX index, USB_DEVICE_CONTROL_TRANSFER_EVENT controlEvent, USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA * controlEventData); This function will be called by the device layer when there is a interface specific setup packet request void (* tasks)(SYS_MODULE_INDEX funcDriverIndex); Function driver Tasks Remarks Even the vendor specific function drivers must provide callback functions in this format. 5.9.3.6.4.21 USB_DEVICE_HANDLE Type C typedef uintptr_t USB_DEVICE_HANDLE; Description Data type for USB device handle. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4053 The data type of the handle that is returned from USB_DEVICE_Open function. Remarks None. 5.9.3.6.4.22 USB_DEVICE_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; unsigned int usbID; bool stopInIdle; bool suspendInSleep; INT_SOURCE interruptSource; void * endpointTable; uint16_t registeredFuncCount; USB_DEVICE_FUNC_REGISTRATION_TABLE * registeredFunctions; USB_MASTER_DESCRIPTOR * usbMasterDescriptor; USB_SPEED deviceSpeed; } USB_DEVICE_INIT; Description USB Device Initialization Structure Members Members Description SYS_MODULE_INIT moduleInit; System module initialization unsigned int usbID; Identifies peripheral (PLIB-level) ID bool stopInIdle; Boolean flag: true -> Stop USB module in Idle Mode bool suspendInSleep; Boolean flag: true -> Suspend USB in Sleep Mode INT_SOURCE interruptSource; Interrupt Source for USB module void * endpointTable; Endpoint Table Buffer uint16_t registeredFuncCount; Number of function drivers registered to this instance of the USB device layer USB_DEVICE_FUNC_REGISTRATION_TABLE * registeredFunctions; Function driver table registered to this instance of the USB device layer USB_MASTER_DESCRIPTOR * usbMasterDescriptor; Pointer to USB Descriptor structure USB_SPEED deviceSpeed; Speed at which this device speed should operate Remarks Also see, USB_DEVICE_Initialization 5.9.3.6.4.23 USB_DEVICE_POWER_STATE Enumeration C typedef enum { USB_DEVICE_POWER_STATE_BUS_POWERED, USB_DEVICE_POWER_STATE_SELF_POWERED } USB_DEVICE_POWER_STATE; Description Power state 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4054 Members Members Description USB_DEVICE_POWER_STATE_BUS_POWERED Device is bus powered USB_DEVICE_POWER_STATE_SELF_POWERED Device is self powered Remarks Also see, USB_DEVICE_PowerStateSet 5.9.3.6.4.24 USB_DEVICE_REMOTE_WAKEUP_STATUS Enumeration C typedef enum { USB_DEVICE_REMOTE_WAKEUP_DISABLED, USB_DEVICE_REMOTE_WAKEUP_ENABLED } USB_DEVICE_REMOTE_WAKEUP_STATUS; Description Remote wakeup status Members Members Description USB_DEVICE_REMOTE_WAKEUP_DISABLED Remote wakeup is disabled USB_DEVICE_REMOTE_WAKEUP_ENABLED Remote wakeup is enabled Remarks Also see, USB_DEVICE_RemoteWakeupIsEnabled 5.9.3.6.4.25 USB_DEVICE_STATE Enumeration C typedef enum { USB_DEVICE_STATE_DETACHED, USB_DEVICE_STATE_ATTACHED, USB_DEVICE_STATE_POWERED, USB_DEVICE_STATE_DEFAULT, USB_DEVICE_STATE_ADDRESSED, USB_DEVICE_STATE_CONFIGURED, USB_DEVICE_STATE_SUSPENDED } USB_DEVICE_STATE; Description USB device states as described in chapter-9 of USB 2.0 specification This data type identifies the USB Device States. Members Members Description USB_DEVICE_STATE_DETACHED Device is not in any of the known USB states USB_DEVICE_STATE_ATTACHED Device is in attached state USB_DEVICE_STATE_POWERED Device is in powered state USB_DEVICE_STATE_DEFAULT Device is in default state USB_DEVICE_STATE_ADDRESSED Device is in addressed state USB_DEVICE_STATE_CONFIGURED Device is in configured state 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4055 USB_DEVICE_STATE_SUSPENDED Device is in suspended state Remarks The USB specification doesn't define the state of a device when it is detached from the USB. The USB_DEVICE_STATE_DETACHED is not the standard state, but is required to indicate the user, that the device is not in any of the known states. 5.9.3.6.4.26 USB_DEVICE_STRING_DESCS_PTR Type C typedef uint8_t** USB_DEVICE_STRING_DESCS_PTR; Description String descriptors pointer 5.9.3.6.4.27 USB_MASTER_DESCRIPTOR Structure C typedef struct { uint8_t* ptrDeviceDescriptor; uint8_t configDescriptorCount; USB_DEVICE_CONFIG_DESCS_PTR ptrConfigDescriptor; uint8_t* ptrHighSpeedDeviceDescriptor; uint8_t highSpeedConfigDescriptorCount; USB_DEVICE_CONFIG_DESCS_PTR ptrHighSpeedConfigDescriptor; uint8_t stringDescCount; USB_DEVICE_STRING_DESCS_PTR ptrStringDesc; uint8_t* ptrFullSpeedDeviceQualifier; uint8_t* ptrHighSpeedDeviceQualifier; } USB_MASTER_DESCRIPTOR; Description Global USB Descriptor Structure. Members Members Description uint8_t* ptrDeviceDescriptor; Pointer to standard device descriptor (for low/full speed) uint8_t configDescriptorCount; Total number configurations available (for low/full speed) USB_DEVICE_CONFIG_DESCS_PTR ptrConfigDescriptor; Pointer to array of configurations descriptor pointers (for low/full speed) uint8_t* ptrHighSpeedDeviceDescriptor; Pointer to array of high speed standard Device descriptor. Assign this to NULL if not supported. uint8_t highSpeedConfigDescriptorCount; Total number of high speed configurations available. Set this to zero if not supported USB_DEVICE_CONFIG_DESCS_PTR ptrHighSpeedConfigDescriptor; Pointer to array of high speed configurations descriptor pointers. Set this to NULL if not supported uint8_t stringDescCount; Total number of string descriptors available (common to all speeds) USB_DEVICE_STRING_DESCS_PTR ptrStringDesc; Pointer to array of string Descriptor pointers (common to all speeds) uint8_t* ptrFullSpeedDeviceQualifier; Pointer to full speed device_qualifier descriptor. Device responds with this descriptor when it is operating at high speed uint8_t* ptrHighSpeedDeviceQualifier; Pointer to high speed device_qualifier descriptor. Device responds with this descriptor when it is operating at full speed 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4056 5.9.3.6.4.28 USB_DEVICE_ENDPOINT_TABLE_SIZE Macro C #define USB_DEVICE_ENDPOINT_TABLE_SIZE (DRV_USB_ENDPOINTS_NUMBER * DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE) Description This is macro USB_DEVICE_ENDPOINT_TABLE_SIZE. 5.9.3.6.4.29 USB_DEVICE_HANDLE_INVALID Macro C #define USB_DEVICE_HANDLE_INVALID ((USB_DEVICE_HANDLE)(-1)) Description USB Device Layer invalid handle 5.9.3.7 Files Files Name Description usb_device.h USB Device Layer Interface Header usb_device_config_template.h USB device configuration template header file. Description 5.9.3.7.1 usb_device.h USB Device Layer Interface Definition This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB device layer. Enumerations Name Description USB_DEVICE_CONTROL_STATUS This enumerated data-type identifies the status stage of control transfer. USB_DEVICE_CONTROL_TRANSFER_EVENT This datatype defines the different control transfer events. USB_DEVICE_CONTROL_TRANSFER_RESULT Enumerated data type identifying results of a control transfer. USB_DEVICE_EVENT Enumerated data-type identifying the bus events that has occurred in the USB device layer. USB_DEVICE_POWER_STATE Enumerated data type that identifies if the device is self powered or bus powered . USB_DEVICE_REMOTE_WAKEUP_STATUS Enumerated data type that identifies if the remote wakeup status of the device. USB_DEVICE_STATE Standard USB device states as described in Chapter-9 of USB 2.0 Specification. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4057 Functions Name Description USB_DEVICE_Attach This function will attach the device to the USB. USB_DEVICE_ClientStatus Gets the current client-specific status of the USB device layer. USB_DEVICE_Close Closes an opened handle to an instance of the USB device layer. USB_DEVICE_ControlEventCallBackSet Client can register its call-back function into the device layer to get control transfer events. USB_DEVICE_ControlReceive Receives data stage of the control transfer from host to device. USB_DEVICE_ControlSend Sends data stage of the control transfer from device to host. USB_DEVICE_ControlStatus Initiates status stage of the control transfer. USB_DEVICE_Deinitialize Deinitializes the specified instance of the USB device layer. USB_DEVICE_Detach This function will detach the device from the USB. USB_DEVICE_EndpointDisable This function disables an endpoint. USB_DEVICE_EndpointEnable This function enables a endpoint for the specified direction and endpoint size. USB_DEVICE_EndpointIsEnabled This function returns the enable/ disable status of the specified endpoint and direction. USB_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. USB_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. USB_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. USB_DEVICE_EventCallBackSet Client can register its call-back function into the device layer. USB_DEVICE_GetConfigurationValue Informs the client of the current USB device configuration set by the USB host. USB_DEVICE_GetDeviceSpeed Informs the client of the current operation speed of the USB bus. USB_DEVICE_GetDeviceState Returns the current state of the USB device. USB_DEVICE_Initialize Creates and initializes an instance of the USB device layer. USB_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. USB_DEVICE_IRPSubmit This function submits a I/O Request Packet (IRP) for processing to the USB Driver. USB_DEVICE_Open Opens the specified USB device layer instance and returns a handle to it. USB_DEVICE_PowerStateSet Sets power state of the device. USB_DEVICE_Reinitialize Reinitializes the USB device layer USB_DEVICE_RemoteWakeupIsEnabled Gets the "Remote wakeup" status of the device. USB_DEVICE_ResumeStart This function will start the resume signalling. USB_DEVICE_ResumeStop This function will stop the resume signalling. USB_DEVICE_Status Provides the current status of the USB device layer USB_DEVICE_Tasks USB Device layer calls all other function driver tasks in this function. It also generates and forwards events to its clients. Macros Name Description USB_DEVICE_ENDPOINT_TABLE_SIZE This is macro USB_DEVICE_ENDPOINT_TABLE_SIZE. USB_DEVICE_HANDLE_INVALID Macro that defines the value of invalid device handle. USB_DEVICE_INDEX_0 USB device layer index definitions. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4058 USB_DEVICE_INDEX_1 This is macro USB_DEVICE_INDEX_1. USB_DEVICE_INDEX_2 This is macro USB_DEVICE_INDEX_2. USB_DEVICE_INDEX_3 This is macro USB_DEVICE_INDEX_3. USB_DEVICE_INDEX_4 This is macro USB_DEVICE_INDEX_4. USB_DEVICE_INDEX_5 This is macro USB_DEVICE_INDEX_5. USB_DEVICE_INDEX_COUNT Number of valid USB Device Layer indices Structures Name Description USB_DEVICE_EVENT_DATA_CONFIGURED Data-type that holds the data related to USB device configured event. USB_DEVICE_FUNC_REGISTRATION_TABLE A function driver has to be registered with the USB device layer using this structure. USB_DEVICE_FUNCTION_DRIVER A function driver has to expose standard APIs to device layer using following structure. USB_DEVICE_INIT This structure has to be initialized by the system/application and must be passed as parameter to USB_DEVICE_Initialize(). USB_MASTER_DESCRIPTOR Global USB descriptor structure containing pointers to standard USB descriptor structures. Types Name Description USB_DEVICE_CALLBACK Pointer to a USB Device Layer callback function data type for bus events. USB_DEVICE_CONFIG_DESCS_PTR Pointer to an array that contains pointer to configuration descriptors. USB_DEVICE_CONTROL_TRANSFER_CALLBACK USB_DEVICE_CONTROL_TRANSFER_HANDLE Data type of USB device control transfer handle. USB_DEVICE_HANDLE Data type for USB device handle. USB_DEVICE_STRING_DESCS_PTR Pointer to an array that contains pointer to string descriptors. Unions Name Description USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA USB device control transfer event data. USB_DEVICE_EVENT_DATA Data assosciated with USB bus events. File Name usb_device.h Company Microchip Technology Inc. 5.9.3.7.2 usb_device_config_template.h USB Device Layer Compile Time Options This file contains USB device layer compile time options (macros) that are to be configured by the user. This file is a template file and must be used as an example only. This file must not be directly included in the project. 5.9 USB Library Help MPLAB Harmony Help USB Device Layer Library 5-4059 Macros Name Description USB_DEVICE_MAX_CLIENTS Sets the maximum possible number of clients an instance of the USB device can open using USB_DEVICE_Open. USB_DEVICE_MAX_FUNCTION_DRIVER Sets the maximum number of function drivers at a time that are supported by an instance of the USB device layer. USB_DEVICE_MAX_INSTANCES Sets the maximum possible number of instances of the USB device that can be instantiated by using USB_DEVICE_Initialize() routine. File Name usb_device_config_template.h Company Microchip Technology Inc. 5.9.4 USB Device CDC Library 5.9.4.1 Introduction Introduces the MPLAB Harmony USB Device CDC Library Description The MPLAB Harmony USB Device CDC library provides a high-level abstraction of the Universal Serial Bus (USB) Communications Device Class (CDC). This function driver is a part of the MPLAB Harmony USB Device stack. The library offers a convenient C language interface and supports revision 1.2 of the USB CDC specification release. The USB Communications Device Class (or USB CDC) is a composite Universal Serial Bus device class. The communications device class is primarily used for • Telecommunication Devices (analog modems, ISDN terminal adapters, digital telephones, and analog phones) • Networking Devices (ADSL modems, cable modems and Ethernet cross-over cables. USB CDC specification, and associated subclass specifications, do not attempt to redefine existing standards for connection and control of communications services. The Communications Class defines mechanisms for a device and host to identify which existing protocols to use. Where possible, existing data formats are used and the transport of these formats are merely enabled by the USB through the definition of the appropriate descriptors, interfaces, and requests. The MPLAB Harmony USB Device CDC library (also referred to as CDC function driver in this document) offers services to the application to interact and respond to the host requests. 5.9.4.2 Release Notes MPLAB Harmony Version: v0.70b USB Device CDC Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4060 Known Issues: Nothing to report in this release. 5.9.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.4.4 Library Architecture 5.9.4.4.1 Abstraction Model Provides an Architectural Overview of the CDC Function Driver. Description The CDC Function Driver offers services to a USB CDC device to communicate with the host by abstracting the USB specification details. It must be used along with the USB Device layer and USB controller to communicate with the USB host. Figure 1 shows a block diagram representation of the MPLAB Harmony USB Architecture and where the USB CDC Function Driver is placed. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4061 Figure 1: USB CDC Function Driver The USB controller driver takes the responsibility of managing the USB peripheral on the device. The USB device layer handles the device enumeration etc. The USB Device layer forwards all CDC specific control transfers to the CDC Function Driver. The CDC Function Driver ACM sub-layer interprets the control transfers and requests application's intervention through event handlers and well defined set of API. The application must register a event handler with the CDC function driver in the Device Layer Set Configuration Event. While the application must respond to the CDC ACM events, it can do this either in the event handler or out of it. The application interacts directly with the CDC Function Driver to send/receive data and to send serial state notifications. As per the CDC specification,a USB CDC device is a collection of following interfaces. - Communication Interface (Device Management) on endpoint 0 - Communication Interface (Notification) on an interrupt endpoint. This is optional - Data Interface (either a bulk or isochronous endpoint). This is optional. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4062 Figure 2: CDC Function Driver Architecture Figure 2 shows the architecture of the CDC Function Driver. The device management on end point zero is handled by the device library(class specific requests are routed to the CDC function driver by USB Device Layer). So an instance of CDC function driver actually consists of a data interface and a notification interface. The library is implemented in two .c files. The usb_device_cdc.c file implements the CDC data and serial state notification. The usb_device_cdc_acm.c file implements the control transfer interpretation and and event generation. 5.9.4.4.2 Abstract Control Model (ACM) Describes the various ACM commands supported by this CDC Function Driver Implementation Description One of the basic supported models for communication by CDC is POTS (Plain Old Telephone Service). The POTS model is for devices that communicate via ordinary phone lines and generic COM port devices. The USB CDC specification refers to this basic model as PSTN (Public Switched Telephone Network). Depending on the amount of data processing the device is responsible for POTS/PSTN is divided into several models. The processing of data can include modulation, demodulation, error correction and data compression. Of the supported PSTN models, this CDC function driver implements Abstract Control Model (ACM). In the ACM the device handles modulation, demodulation and handles V.25ter (AT) commands. This model (ACM) also supports requests and notifications to get and set R-232 status, control and asynchronous port part parameters. Virtual COM port devices use Abstract Control Model. The following sections describe the management requests and notifications supported by the CDC ACM function driver. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4063 Management Requests: The host requests/sends some information in the form of management requests on the bi-directional end-point 0. Table 1 shows shows the CDC specification ACM sub class management requests and how these request are handled by the CDC Function Driver. Request Code Required/Optional Comments SEND_ENCAPSULATED_COMMAND Required Implemented by CDC Function Driver ACM layer. This request is stalled. GET_ENCAPSULATED_RESPONSE Required Implemented by CDC Function Driver ACM layer. This request is stalled. SET_COMM_FEATURE Optional Not Implemented GET_COMM_FEATURE Optional Not Implemented CLEAR_COMM_FEATURE Optional Not Implemented SET_LINE_CODING Optional Implemented by CDC Function Driver ACM layer. Requires application response GET_LINE_CODING Optional Implemented by CDC Function Driver ACM layer. Requires application response SET_CONTROL_LINE_STATE Optional Implemented by CDC Function Driver ACM layer. Requires application response SEND_BREAK Optional Implemented by CDC Function Driver ACM layer. Requires application response Table 1: CDC ACM management requests and CDC Function Driver support status. 5.9.4.5 Using the Library 5.9.4.5.1 Files to Include Describes which files to include in project while using the CDC Function Driver Description Table 2 shows the files that must be included in the project in order to use the CDC Function Driver. These files are located in the framework folder of the MPLAB Harmony installation. It is assumed that the Device Layer files ( and the files needed by the Device Layer) are already included in the project. Filename Description \framework\usb\src\dynamic\usb_device_cdc.c Contains the CDC data and serial notification transfer functions implementation. \framework\usb\src\dynamic\usb_device_cdc_acm.c Implements the control transfer interpretation and and event generation of CDC-ACM events. \framework\usb\usb_device_cdc.h Must included in every source file that needs to invoke CDC function driver API. system_config.h User created file which contains the CDC function driver configuration. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4064 Table 2: Files to be included in USB CDC Device Project. 5.9.4.5.2 Library Configuration Describes how to configure the CDC Function Driver Description The application designer must specify the following configuration parameters while using the CDC Function Driver. The configuration macros that implement these parameters must be located in the system_config.h file in the application project and a compiler include path (to point to the folder that contains this file) should be specified. Configuration Macro Name Description Comments USB_DEVICE_CDC_INSTANCES_NUMBER Number of CDC Function Driver Instances in the application This macro defines the number of instances of the CDC Function Driver. For example, if the application needs to implement two instances of the CDC Function Driver (to create two COM ports) on one USB Device, the macro should be set to 2. Note that implementing a USB Device that features multiple CDC interfaces requires appropriate USB configuration descriptors. USB_DEVICE_CDC_QUEUE_SIZE CDC Function Driver Buffer Combined Queue size This macro defines the number of entries in all queues in all instances of the CDC function driver. This value can be obtained by adding up the read and write queue sizes of each CDC Function driver instance. In a simple single instance USB CDC device application, that does not require buffer queuing and serial state notification, the USB_DEVICE_CDC_QUEUE_SIZE macro can be set to 2. Consider a case with two CDC function driver instances, CDC 1 has a read queue size of 2 and write queue size of 3, CDC 2 has a read queue size of 4 and write queue size of 1, this macro should be set to 10 (2 +3 + 4 + 1). 5.9.4.5.3 Library Initialization Describes how the CDC Function Driver is initialized. Description The CDC function driver instance for a USB device configuration is initialized by the Device Layer when the configuration is set by the host. This process does not require application intervention. Each instance of the CDC function driver should be registered with the Device layer through the Device Layer Function Driver Registration Table. The CDC function driver does not require a initialization data structure.The funcDriverInit member of the function driver registration table entry for the CDC function driver instance should be set to NULL. The cdcFuncDriver object is a global object provided by the CDC function driver and points to the CDC function driver - Device Layer interface functions which are required by the Device Layer. The code snippet below shows an example of how multiple instances of CDC Function driver can registered with the Device Layer. /* This code snippet shows an example of how two CDC function * driver instances can be registered with the Device Layer * via the Device Layer Function Driver Registration Table. * In this case Device Configuration 1 consists of two CDC * function driver instances. */ /* Define the CDC intialization data structure for CDC instance 0. * Set read queue size to 2 and write queue size to 3 */ const USB_DEVICE_CDC_INIT cdcInit0 = {.queueSizeRead = 2, .queueSizeWrite = 3}; 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4065 /* Define the CDC intialization data structure for CDC instance 1. * Set read queue size to 4 and write queue size to 1 */ const USB_DEVICE_CDC_INIT cdcInit1 = {.queueSizeRead = 4, .queueSizeWrite = 1}; const USB_DEVICE_FUNC_REGISTRATION_TABLE funcRegistrationTable[2] = { /* This is the first instance of the CDC Function Driver */ { .speed = USB_SPEED_FULL|USB_SPEED_HIGH, // Supported speed .configurationValue = 1, // To be initialized for Configuration 1 .interfaceNumber = 0, // Starting interface number. .numberOfInterfaces = 2, // Number of interfaces in this instance .funcDriverIndex = 0, // Function Driver instance index is 0 .funcDriverInit = &cdcInit0, // Function Driver initialization data structure .driver = &cdcFuncDriver // Pointer to Function Driver - Device Layer interface functions }, /* This is the second instance of the CDC Function Driver */ { .speed = USB_SPEED_FULL|USB_SPEED_HIGH, // Supported speed .configurationValue = 1, // To be initialized for Configuration 1 .interfaceNumber = 2, // Starting interface number. .numberOfInterfaces = 2, // Number of interfaces in this instance .funcDriverIndex = 1, // Function Driver instance index is 1 .funcDriverInit = &cdcInit1, // Function Driver initialization data structure .driver = &cdcFuncDriver // Pointer to Function Driver - Device Layer interface functions }, }; 5.9.4.5.4 Event Handling Describes CDC function driver event handler registration and event handling. Description Registering a CDC Function Driver Event Handler: While creating a USB CDC Device based application, an event handler must be registered with the Device Layer (the Device Layer Event Handler) and every CDC function driver instance (CDC Function Driver Event Handler). The CDC function driver event handler receives CDC and CDC ACM events. This event handler should be registered before the USB device layer acknowledges the SET CONFIGURATION request from the USB Host. In order to ensure this, the event handler should be set in the USB_DEVICE_EVENT_CONFIGURED event that is generated by the device layer. While registering the CDC function driver event handler, the CDC function driver allows the application to also pass a application context object. This object gets associated with the instance of the CDC function driver and is returned by the CDC function driver when a CDC function driver event occurs. The code example below shows an example of how this can be done. /* This a sample Application Device Layer Event Handler * Note how the CDC Function Driver event handler APP_USBDeviceCDCEventHandler() * is registered in the USB_DEVICE_EVENT_CONFIGURED event. The appData * object that is passed in the USB_DEVICE_CDC_EventHandlerSet() * function will be returned as the userData parameter in the * when the APP_USBDeviceCDCEventHandler() function is invoked */ void APP_USBDeviceEventCallBack ( USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData ) { switch ( event ) { case USB_DEVICE_EVENT_RESET: case USB_DEVICE_EVENT_DECONFIGURED: 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4066 // USB device is reset or device is deconfigured. // This means that USB device layer is about to deininitialize // all function drivers. break; case USB_DEVICE_EVENT_CONFIGURED: /* check the configuration */ if ( eventData->eventConfigured.configurationValue == 1) { /* Register the CDC Device application event handler here. * Note how the appData object pointer is passed as the * user data */ USB_DEVICE_CDC_EventHandlerSet(USB_DEVICE_CDC_INDEX_0, APP_USBDeviceCDCEventHandler, (uintptr_t)&appData); /* mark that set configuration is complete */ appData.isConfigured = true; } break; case USB_DEVICE_EVENT_SUSPENDED: break; case USB_DEVICE_EVENT_RESUMED: case USB_DEVICE_EVENT_ATTACHED: case USB_DEVICE_EVENT_DETACHED: case USB_DEVICE_EVENT_ERROR: default: break; } } CDC Function Driver Events: The CDC Function Driver generates events that the application must respond. Some of these events are management requests communicated through control transfers. The application must therefore complete the control transfer. Based on the generated event, the application may be required to: • Respond with a USB_DEVICE_CDC_ControlSend() function which is completes the data stage of a Control Read Transfer. • Respond with a USB_DEVICE_CDC_ControlReceive() function which provisions the data stage of a Control Write Transfer. • Respond with a USB_DEVICE_CDC_ControlStatus() function which completes the handshake stage of the Control Transfer. The application can either STALL or Acknowledge the handshake stage via the USB_DEVICE_CDC_ControlStatus() function. • Analyze the pData member of the event handler and check for event specific data. This data member should be type cast to an event specific data type. The table below shows the event and the data type to use while type casting. Note that the pData member is not required for all events CDC Function Driver Event Related pData type USB_DEVICE_CDC_EVENT_SET_LINE_CODING Not Applicable USB_DEVICE_CDC_EVENT_GET_LINE_CODING Not Applicable USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE USB_DEVICE_CDC_EVENT_DATA_SET_CON TROL_LINE_STATE * 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4067 USB_DEVICE_CDC_EVENT_SEND_BREAK USB_DEVICE_CDC_EVENT_DATA_SEND_BR EAK * USB_DEVICE_CDC_EVENT_WRITE_COMPLETE USB_DEVICE_CDC_EVENT_DATA_WRITE_C OMPLETE * USB_DEVICE_CDC_EVENT_READ_COMPLETE USB_DEVICE_CDC_EVENT_DATA_READ_C OMPLETE * USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE USB_DEVICE_CDC_EVENT_DATA_SERIAL_S TATE_NOTIFICATION_COMPLETE * USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT Not Applicable USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED Not Applicable The possible CDC Function Driver events are described here along with the required application response, event specific data and likely follow up function driver event: 1. USB_DEVICE_CDC_EVENT_SET_LINE_CODING Application Response: This event occurs when the host issues a SET LINE CODING command. The application must provide a USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING data structure to the device layer to receive the line coding data that the host will provide. The application must provide the buffer by calling the USB_DEVICE_CDC_ControlReceive() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_CDC_ControlReceive() function. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command. Event Specific Data (pData): The pData parameter will be NULL. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event. This indicates that the data was received successfully. The application must either acknowledge or stall the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_OK or USB_DEVICE_CONTROL_STATUS_ERROR flag respectively. 2. USB_DEVICE_CDC_EVENT_GET_LINE_CODING Application Response: This event occurs when the host issues a GET LINE CODING command. The application must provide a USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING data structure to the device layer that contains the line coding data that to be provided to the host. The application must provide the buffer by calling the USB_DEVICE_CDC_ControlSend() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_CDC_ControlSend() function. The size of the buffer is indicated by the length parameter. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command. Event Specific Data (pData): The pData parameter will be NULL. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT event. This indicates that the data was sent to the host successfully. The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_CDC_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_OK flag. 3. USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4068 Application Response: This event occurs when the host issues a SET CONTROL LINE STATE command. . The application can then use the USB_DEVICE_CDC_ControlStatus() function to indicate acceptance of rejection of the command. The USB_DEVICE_CDC_ControlStatus() function can be called from the event handler or in the application (out of the event handler context). The application should use the controlTransferHandle while calling the USB_DEVICE_ControlStatus() function. Event Specific Data (pData): The application must interpret the pData parameter as a pointer to a USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE data type that contains the control line state data. Likely Follow-up event: None. 4. USB_DEVICE_CDC_EVENT_SEND_BREAK Application Response: This event occurs when the host issues a SEND BREAK command. The application can then use the USB_DEVICE_CDC_ControlStatus() function to indicate acceptance of rejection of the command. The USB_DEVICE_CDC_ControlStatus() function can be called from the event handler or in the application (out of the event handler context). The application should use the controlTransferHandle while calling the USB_DEVICE_CDC_ControlStatus() function. Event Specific Data (pData): The application must interpret the pData parameter as a pointer to a USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK data type that contains the break duration data. Likely Follow-up event: None. 5. USB_DEVICE_CDC_EVENT_WRITE_COMPLETE Application Response: This event occurs when a write operation scheduled by calling the USB_DEVICE_CDC_Write() function has completed. This event does not require the application to respond with any function calls.. Event Specific Data (pData): The pData member in the event handler will point to USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE type. Likely Follow-up event: None. 6. USB_DEVICE_CDC_EVENT_READ_COMPLETE Application Response: This event occurs when a read operation scheduled by calling the USB_DEVICE_CDC_Read() function has completed. This event does not require the application to respond with any function calls.. Event Specific Data (pData): The pData member in the event handler will point to USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE type. Likely Follow-up event: None. 7. USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE Application Response: This event occurs when a serial state notfication send scheduled by calling the USB_DEVICE_CDC_SerialStateNotificationSend() function has completed. This event does not require the application to respond with any function calls.. Event Specific Data (pData): The pData member in the event handler will point to USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE type. Likely Follow-up event: None. 8. USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT Application Response: This event occurs when the data stage of a control read transfer has completed in response to the USB_DEVICE_CDC_ControlSend() function (in the USB_DEVICE_CDC_EVENT_GET_LINE_CODING event). The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_CDC_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_OK flag. Event Specific Data (pData): The pData parameter will be NULL. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4069 Likely Follow-up event: None. 9. USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED Application Response: This event occurs when the data stage of a control write transfer has completed in response to the USB_DEVICE_CDC_ControlReceive() function (in the USB_DEVICE_CDC_EVENT_SET_LINE_CODING event). The application must either acknowledge or stall the handshake stage of the control transfer by calling USB_DEVICE_CDC_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_OK or USB_DEVICE_CONTROL_STATUS_ERROR flag respectively. Event Specific Data (pData): The pData parameter will be NULL. Likely Follow-up event: None. CDC Function Driver Event Handling: The following code snippet shows an example event handling scheme. The application always returns from the event handler with a USB_DEVICE_CDC_EVENT_RESPONSE_NONE value. // This code example shows all CDC Function Driver possible events // and a possible scheme for handling these events. In this case // event responses are not deferred. USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING_DATA setLineCodingData; USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING_DATA getLineCodingData; USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_DATA controlLineStateData; USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK_DATA breakData; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, uintptr_t controlTransferHandle, void * data, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_SET_LINE_CODING: // In this case, the application should read the line coding // data that is sent by the host. USB_DEVICE_CDC_ControlReceive(usbDeviceHandle, controlTransferHandle &setLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING)); break; case USB_DEVICE_CDC_EVENT_GET_LINE_CODING: // In this case, the application should send the line coding // data to the host. USB_DEVICE_CDC_ControlSend(usbDeviceHandle, controlTransferHandle &getLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING)); break; case USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE: // In this case, pData will point to a // USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATtype data object that // will contain the control line state data sent by the host. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4070 controlLineStateData.dtr = ((USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE *)pData)->dtr; controlLineStateData.carrier = ((USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE *)pData)->carrier; USB_DEVICE_CDC_ControlStatus(usbDeviceHandle, controlTransferHandle, USB_DEVICE_CONTROL_STATUS_OK); break; case USB_DEVICE_CDC_EVENT_SEND_BREAK: // In this case, pData will point to a // USB_DEVICE_CDC_EVENT_SEND_BREAK_DATA type data object that // will contain the break duration sent by the host. breakData.duration = ((USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK *)pData)->duration; USB_DEVICE_CDC_ControlStatus(usbDeviceHandle, controlTransferHandle, USB_DEVICE_CONTROL_STATUS_OK); break; case USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT: case USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED: // This means that the data stage is complete. The data in // setLineCodingData is valid or data in getLineCodingData was // sent to the host. The application can now decide whether it // supports this data. It is not mandatory to do this in the // event handler. USB_DEVICE_ControlStatus(usbDeviceHandle, controlTransferHandle, USB_DEVICE_CONTROL_STATUS_OK); case USB_DEVICE_CDC_EVENT_WRITE_COMPLETE: // This means USB_DEVICE_CDC_Write() operation completed. // The pData member will point to a // USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE type of data. break; case USB_DEVICE_CDC_EVENT_READ_COMPLETE: // This means USB_DEVICE_CDC_Read() operation completed. // The pData member will point to a // USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE type of data. break; case USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE: // This means USB_DEVICE_CDC_SerialStateNotification() operation // completed. The pData member will point to a // USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE type of data. break; default: break; } return(USB_DEVICE_CDC_EVENT_RESPONSE_NONE); } Refer to the USB_DEVICE_CDC_EVENT enumeration for more details on each event. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4071 5.9.4.5.5 Sending Data Describes how to send data to the CDC Host. Description The application may need to send data or serial state notification to the USB CDC Host. This is done by using the USB_DEVICE_CDC_Write() and USB_DEVICE_CDC_SerialStateNotificationSend() functions respectively. 1. Sending data to the USB Host: The application can send data to the host by using the USB_DEVICE_CDC_Write() function. This function returns a transfer handler that allows the application to track the read request. The request is completed when the host as requested for the data. The completion of the write transfer is indicated by USB_DEVICE_CDC_EVENT_WRITE_COMPLETE event. A write request could fail if the function driver instance transfer queue is full. The USB_DEVICE_CDC_Write() function also allows the application to send data to the host without ending the transfer. This is done by specifying the USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_PENDING flag. The application can use this option when the data to be sent is not readily available or when the application is memory constrained. The combination of the transfer flag and the transfer size affects how the function driver sends the data to the host. a. If size is a multiple of maxPacketSize (the IN endpoint size) and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function will append a Zero Length Packet (ZLP) to complete the transfer. b. If size is a multiple of maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function will not append a ZLP and hence will not complete the transfer. c. If size is greater than but not a multiple of maxPacketSize and flags is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function schedules (length/maxPacketSize) packets and one packet for the residual data. d. If size is greater than but not a multiple of maxPacketSize and flags is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function schedules (size/maxPacketSize) packets only. e. If size is less than maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function schedules one packet. f. If size is less than maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function returns an error code and sets the transferHandle parameter to USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID. The following code snippet explains this in more detail: // Below is a set of examples showing various conditions trying to // send data with the USB_DEVICE_CDC_Write() command. // // This assumes that driver was opened successfully. // Assume maxPacketSize is 64. USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle; USB_DEVICE_CDC_RESULT writeRequestHandle; USB_DEVICE_CDC_INDEX instance; //------------------------------------------------------- // In this example we want to send 34 bytes only. writeRequestResult = USB_DEVICE_CDC_Write(instance, &transferHandle, data, 34, 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4072 USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // In this example we want to send 64 bytes only. // This will cause a ZLP to be sent. writeRequestResult = USB_DEVICE_CDC_Write(instance, &transferHandle, data, 64, USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // This example will return an error because size is less // than maxPacketSize and the flag indicates that more // data is pending. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 32, USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING); //------------------------------------------------------- // In this example we want to place a request for a 70 byte transfer. // The 70 bytes will be sent out in a 64 byte transaction and a 6 byte // transaction completing the transfer. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 70, USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // In this example we want to place a request for a 70 bytes to be sent // but that we don't end the transfer as more data is coming. 64 bytes // of the 70 will be sent out and the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE // with 64 bytes. This indicates that the extra 6 bytes weren't // sent because it would cause the end of the transfer. Thus the // user needs add these 6 bytes back to the buffer for the next group // of data that needs to be sent out. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 70, USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } // The completion of the write request will be indicated by the // USB_DEVICE_CDC_EVENT_WRITE_COMPLETE event. 2. Sending a serial state notification: The application can send a Serial State Notification by using the USB_DEVICE_CDC_SerialStateSend() function. his function 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4073 returns a transfer handler that allows the application to track the read request. The request is completed when the host as requested for the data. The completion of the transfer is USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE event. A request could fail if the function driver transfer queue is full. The following code snippet shows an example of how this can be done. USB_DEVICE_CDC_INDEX instanceIndex; USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle; USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA notificationData; // This application function could possibly update the notificationData // data structure. APP_UpdateNotificationData(¬ificationData); // Now send the updated notification data to the host. result = USB_DEVICE_CDC_SerialStateDataSend(instanceIndex, &transferHandle, ¬ificationData); if(USB_DEVICE_CDC_RESULT_OK != result) { // Error handling here } 5.9.4.5.6 Receiving Data Describes how the CDC device can read data from the Host. Description The application can receive data from the host by using the USB_DEVICE_CDC_Read() function. This function returns a transfer handler that allows the application to track the read request. The request is completed when the host sends the required amount or less than required amount of data. The application must make sure that it allocates a buffer size that is at least the size or a multiple of the receive endpoint size. The return value of the function indicates the success of the request. A read request could fail if the function driver transfer queue is full. The completion of the read transfer is USB_DEVICE_CDC_EVENT_READ_COMPLETE event. The request completes based on the amount of the data that was requested and size of the transaction initiated by the host. a. If the size parameter is not a multiple of maxPacketSize or is 0, the function returns USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID in transferHandle and returns USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_SIZE_INVALID as a return value. b. If the size parameter is a multiple of maxPacketSize and the host send less than maxPacketSize data in any transaction, the transfer completes and the function driver will issue a USB_DEVICE_CDC_EVENT_READ_COMPLETE event along with the USB_DEVICE_CDC_EVENT_READ_COMPLETE_DATA data structure. c. If the size parameter is a multiple of maxPacketSize and the host sends maxPacketSize amount of data, and total data received does not exceed size, then the function driver will wait for the next packet. The following code snippet shows an example if the USB_DEVICE_CDC_Read() function: // Shows an example of how to read. This assumes that // driver was opened successfully. USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle; USB_DEVICE_CDC_RESULT readRequestResult; USB_DEVICE_CDC_HANDLE instanceHandle; readRequestResult = USB_DEVICE_CDC_Read(instanceHandle, &transferHandle, data, 128); if(USB_DEVICE_CDC_RESULT_OK != readRequestResult) 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4074 { //Do Error handling here } // The completion of the read request will be indicated by the // USB_DEVICE_CDC_EVENT_READ_COMPLETE event. 5.9.4.6 Library Interface Data Types and Constants Name Description USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE USB Device CDC Function Driver Control Transfer Handle USB_DEVICE_CDC_EVENT USB Device CDC Function Driver Control Transfer Status USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING USB Device CDC Event Get Line Coding Data Type. USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK USB Device CDC Event Set Break Data Type. USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE USB Device CDC Event Set Line Coding Data Type. USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING USB Device CDC Event Set Line Coding Data Type. USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_EVENT_HANDLER USB Device CDC Event Handler Function Pointer Type. USB_DEVICE_CDC_EVENT_RESPONSE USB Device CDC Function Driver Event Callback Response Type USB_DEVICE_CDC_INDEX USB Device CDC Function Driver Index USB_DEVICE_CDC_INIT USB Device CDC Function Driver Initialization Data Structure USB_DEVICE_CDC_RESULT USB Device CDC Function Driver USB Device CDC Result enumeration. USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA USB Device Serial State Notification Data Type. USB_DEVICE_CDC_TRANSFER_FLAGS USB Device CDC Function Driver Transfer Flags 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4075 USB_DEVICE_CDC_TRANSFER_HANDLE USB Device CDC Function Driver Transfer Handle Definition. USB_DEVICE_CDC_EVENT_RESPONSE_NONE USB Device CDC Function Driver Event Handler Response Type None. USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID USB Device CDC Function Driver Invalid Transfer Handle Definition. Functions Name Description USB_DEVICE_CDC_ControlReceive This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_CDC_ControlSend This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_CDC_ControlStatus This function allows the application to complete the status stage of the the CDC Function Driver specific control transfer request. USB_DEVICE_CDC_EventHandlerSet This function registers a event handler for the specified CDC function driver instance. USB_DEVICE_CDC_Read This function requests a data read from the USB Device CDC Function Driver Layer. USB_DEVICE_CDC_SerialStateNotificationSend This function schedules a request to send serial state notification to the host. USB_DEVICE_CDC_Write This function requests a data write to the USB Device CDC Function Driver Layer. Description 5.9.4.6.1 Functions 5.9.4.6.1.1 USB_DEVICE_CDC_ControlReceive Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_ControlReceive( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); Description This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. For example, the USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING event requires a control transfer response. The function can be called in the CDC Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the data buffer out of the event handler context, especially if the data buffer to receive the data is not readily available. Note however, that there are timing 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4076 considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a CDC function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device CDC Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data buffer to receive the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_CDC_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_CDC_RESULT_OK - The request was successful. Remarks None. Example // ------------------------------------------------------------------ // In this example, the application responds to the SET LINE CODING // with in the event handler. The application uses the // USB_DEVICE_CDC_ControlReceive() function to do this. // ------------------------------------------------------------------ USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING setLineCodingData; USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_SET_LINE_CODING: // In this case, the application should receive the line coding // data from the host. The application must use the // USB_DEVICE_CDC_ControlReceive() function to receive the data. USB_DEVICE_CDC_ControlReceive(instanceIndex, controlTransferHandle &setLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING)); break; } } // -------------------------------------------------------------------- // In this example, the application defers the response to the // event. This is done by calling the USB_DEVICE_CDC_ControlReceive() 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4077 // function after the event handler exits. // -------------------------------------------------------------------- USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING setLineCodingData; USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE thisControlTransferHandle; bool sendLineCodingToHost; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_SET_LINE_CODING: // In this case, the application should send the line coding // data to the host. The application must responds to the // event outside the event handler because the data buffer is // not available. thisControlTransferHandle = controlTransferHandle; getLineCodingFromHost = true; break; } } if(getLineCodingFromHost) { // The application allocates a buffer using an arbitrary function // Note that this happens after the event handler exits. setLineCoding = AllocateMemoryBuffer(); USB_DEVICE_CDC_ControlReceive(instanceIndex, thisControlTransferHandle &setLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING)); } 5.9.4.6.1.2 USB_DEVICE_CDC_ControlSend Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_ControlSend( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); Description This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. For example, the USB_DEVICE_CDC_EVENT_GET_LINE_CODING event requires a control transfer response. The function can be called in the CDC Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the response data out of the event handler context, especially if the data is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4078 device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a CDC function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device CDC Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data that represents the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_CDC_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_CDC_RESULT_OK - The request was successful. Remarks None. Example // ------------------------------------------------------------------ // In this example, the application responds to the GET LINE CODING // with in the event handler. The application uses the // USB_DEVICE_CDC_ControlSend() function to do this. // ------------------------------------------------------------------ USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING getLineCodingData; USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_GET_LINE_CODING: // In this case, the application should send the line coding // data to the host. The application must use the // USB_DEVICE_CDC_ControlSend() function to send the data. USB_DEVICE_CDC_ControlSend(instanceIndex, controlTransferHandle &getLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING)); break; } } // -------------------------------------------------------------------- // In this example, the application defers the response to the // event. This is done by calling the USB_DEVICE_CDC_ControlSend() // function after the event handler exits. // -------------------------------------------------------------------- 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4079 USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING getLineCodingData; USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE thisControlTransferHandle; bool sendLineCodingToHost; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_GET_LINE_CODING: // In this case, the application should send the line coding // data to the host. The application does not call // USB_DEVICE_CDC_ControlSend() function // in the event handler, because it does not have the line // coding data ready. thisControlTransferHandle = controlTransferHandle; sendLineCodingToHost = true; break; } } // This is outside the event handler. if(sendLineCodingToHost) { // The application fetches the line coding from the // an EEPROM. GetLineCodingFromEEPROM(&getLineCoding); USB_DEVICE_CDC_ControlSend(instanceIndex, thisControlTransferHandle &getLineCodingData, sizeof(USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING)); } 5.9.4.6.1.3 USB_DEVICE_CDC_ControlStatus Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_ControlStatus( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_CDC_CONTROL_STATUS status ); Description This function allows the application to complete the status stage of the the CDC Function Driver specific control transfer request. The application can either accept the data stage or stall it. Calling this function with status set to USB_DEVICE_CDC_CONTROL_STATUS_OK will acknowledge the status stage of the control transfer. The control transfer can be stalled by setting the status parameter to USB_DEVICE_CDC_CONTROL_STATUS_ERROR. The function can be called in the CDC Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to analyze the event response outside the event handler. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4080 handle that was generated along with the event as the controlTransferHandle. The application must be aware of events and associated control transfers that do or do not require data stages. Incorrect usage of the USB_DEVICE_CDC_ControlStatus() function could cause the device function to be non-compliant. Preconditions This function should only be called in response to a CDC function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device CDC Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. status Set to USB_DEVICE_CDC_CONTROL_STATUS_OK to acknowledge the control transfer. Set to USB_DEVICE_CDC_CONTROL_STATUS_ERROR to stall the transfer. Returns USB_DEVICE_CDC_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_CDC_RESULT_OK - The request was successful. Remarks None. Example // ------------------------------------------------------------------ // In this code example, the application responds to the the // SEND BREAK event in the event handler. // ------------------------------------------------------------------ USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK * sendBreakData; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_SEND_BREAK: // The application can check if the break duration is supported. sendBreakData = (USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK *)pData; if(IsBreakDurationSupported(sendBreakData->duration)) { USB_DEVICE_CDC_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_CDC_CONTROL_STATUS_OK); } else { // If the break duration is not supported the application // can stall it. USB_DEVICE_CDC_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_CDC_CONTROL_STATUS_ERROR); 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4081 } break; } } // -------------------------------------------------------------------- // In this example, the application defers the response to the // SEND BREAK event. The application responds to the event // after the event handler exits. // -------------------------------------------------------------------- USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE thisControlTransferHandle; USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK * sendBreakData; uint16_t breakDuration; bool sendBreakEvent; USB_DEVICE_CDC_EVENT_RESPONSE USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_CDC_EVENT_SEND_BREAK: // Get the break duration. sendBreakData = (USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK *)pData; breakDuration = sendBreakData->duration sendBreakEvent = true; break; } } if(sendBreakData) { // The application checks if the duration is supported // Note that this occurs after the event handler has exited. if(IsBreakDurationSupported(breakDuration)) { USB_DEVICE_CDC_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_CDC_CONTROL_STATUS_OK); } else { // If the break duration is not supported the application // can stall it. USB_DEVICE_CDC_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_CDC_CONTROL_STATUS_ERROR); } } 5.9.4.6.1.4 USB_DEVICE_CDC_EventHandlerSet Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_EventHandlerSet( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT_HANDLER eventHandler, 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4082 uintptr_t context ); Description This function registers a event handler for the specified CDC function driver instance. This function should be called by the client when it receives a SET CONFIGURATION event from the device layer. A event handler must be registered for function driver to respond to function driver specific commands. If the event handler is not registered, the device layer will stall function driver specific commands and the USB device may not function. Preconditions This function should be called when the function driver has been initialized as a result of a set configuration. Parameters Parameters Description instance Instance of the CDC Function Driver. eventHandler A pointer to event handler function. context Application specific context that is returned in the event handler. Returns USB_DEVICE_CDC_RESULT_OK - The operation was successful USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_DEVICE_CDC_RESULT_ERROR_PARAMETER_INVALID - The eventHandler parameter is NULL Remarks None. Example // This code snippet shows an example registering an event handler. Here // the application specifies the context parameter as a pointer to an // application object (appObject) that should be associated with this // instance of the CDC function driver. USB_DEVICE_CDC_RESULT result; USB_DEVICE_CDC_EVENT_RESPONSE APP_USBDeviceCDCEventHandler ( USB_DEVICE_CDC_INDEX instanceIndex , USB_DEVICE_CDC_EVENT event , USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle void* pData, uintptr_t context ) { // Event Handling comes here switch(event) { ... } return(USB_DEVICE_CDC_EVENT_RESPONSE_NONE); } result = USB_DEVICE_CDC_EventHandlerSet ( 0 ,&APP_EventHandler, (uintptr_t) &appObject); if(USB_DEVICE_CDC_RESULT_OK != result) { SYS_ASSERT ( false , "invalid event handler function" ); } 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4083 5.9.4.6.1.5 USB_DEVICE_CDC_Read Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_Read( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_TRANSFER_HANDLE * transferHandle, void * data, size_t size ); Description This function requests a data read from the USB Device CDC Function Driver Layer. The function places a requests with driver, the request will get serviced as data is made available by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_CDC_EVENT_READ_COMPLETE event. The amount of data read and the transfer handle associated with the request is returned along with the event in the pData parameter of the event handler. The transfer handle expires when event handler for the USB_DEVICE_CDC_EVENT_READ_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID. If the size parameter is not a multiple of maxPacketSize or is 0, the function returns USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID in transferHandle and returns an error code as a return value. If the size parameter is a multiple of maxPacketSize and the host send less than maxPacketSize data in any transaction, the transfer completes and the function driver will issue a USB_DEVICE_CDC_EVENT_READ_COMPLETE event along with the USB_DEVICE_CDC_EVENT_READ_COMPLETE_DATA data structure. If the size parameter is a multiple of maxPacketSize and the host sends maxPacketSize amount of data, and total data received does not exceed size, then the function driver will wait for the next packet. Preconditions The function driver should have been configured. Parameters Parameters Description instance USB Device CDC Function Driver instance. transferHandle Pointer to a USB_DEVICE_CDC_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the read request was successful. data pointer to the data buffer where read data will be stored. size Size of the data buffer. Refer to the description section for more details on how the size affects the transfer. Returns USB_DEVICE_CDC_RESULT_OK - The read request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write request could not be added. USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_SIZE_INVALID - The specified transfer size was not a mulitple of endpoint size or is 0. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4084 Example // Shows an example of how to read. This assumes that // driver was opened successfully. USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle; USB_DEVICE_CDC_RESULT readRequestResult; USB_DEVICE_CDC_HANDLE instanceHandle; readRequestResult = USB_DEVICE_CDC_Read(instanceHandle, &transferHandle, data, 128); if(USB_DEVICE_CDC_RESULT_OK != readRequestResult) { //Do Error handling here } // The completion of the read request will be indicated by the // USB_DEVICE_CDC_EVENT_READ_COMPLETE event. 5.9.4.6.1.6 USB_DEVICE_CDC_SerialStateNotificationSend Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_SerialStateNotificationSend( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_TRANSFER_HANDLE * transferHandle, USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA * notificationData ); Description This function places a request to send serial state notificatin data to the host. The function will place the request with the driver, the request will get serviced when the data is requested by the USB host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE event. The amount of data transmitted and the transfer handle associated with the request is returned along with the event in the serialStateNotificationCompleteData member of pData paramter of the event handler. The transfer handle expires when the event handler for the USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE event exits. If the send request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID. Preconditions The function driver should have been configured Parameters Parameters Description instance USB Device CDC Function Driver instance. transferHandle Pointer to a output only variable that will contain transfer handle. notificationData USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA type of notification data to be sent to the host. Returns USB_DEVICE_CDC_RESULT_OK - The request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - Internal request queue is full. The request could not be added. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4085 and is invalid. Remarks None. Example USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA notificationData; // This application function could possibly update the notificationData // data structure. APP_UpdateNotificationData(¬ificationData); // Now send the updated notification data to the host. result = USB_DEVICE_CDC_SerialStateNotificationSend (instanceIndex, &transferHandle, ¬ificationData); if(USB_DEVICE_CDC_RESULT_OK != result) { // Error handling here. The transferHandle will contain // USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID in this case. } 5.9.4.6.1.7 USB_DEVICE_CDC_Write Function C USB_DEVICE_CDC_RESULT USB_DEVICE_CDC_Write( USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_TRANSFER_HANDLE * transferHandle, const void * data, size_t size, USB_DEVICE_CDC_TRANSFER_FLAGS flags ); Description This function requests a data write to the USB Device CDC Function Driver Layer. The function places a requests with driver, the request will get serviced as data is requested by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE event. The amount of data written and the transfer handle associated with the request is returned along with the event in writeCompleteData member of the pData parameter in the event handler. The transfer handle expires when event handler for the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE exits. If the read request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID. The behavior of the write request depends on the flags and size parameter. If the application intends to send more data in a request, then it should use the USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING flag. If there is no more data to be sent in the request, the application must use the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE flag. This is explained in more detail here: • If size is a multiple of maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function will append a Zero Length Packet (ZLP) to complete the transfer. • If size is a multiple of maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function will not append a ZLP and hence will 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4086 not complete the transfer. • If size is greater than but not a multiple of maxPacketSize and flags is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function schedules (length/maxPacketSize) packets and one packet for the residual data. • If size is greater than but not a multiple of maxPacketSize and flags is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function schedules (size/maxPacketSize) packets only. • If size is less than maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, the write function schedules one packet. • If size is less than maxPacketSize and flag is set as USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING, the write function returns an error code and sets the transferHandle parameter to USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID. Completion of the write transfer is indicated by the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE event. The amount of data written along with the transfer handle is returned along with the event. Preconditions The function driver should have been configured. Parameters Parameters Description instance USB Device CDC Function Driver instance. transferHandle Pointer to a USB_DEVICE_CDC_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the write request was successful. data pointer to the data buffer that contains the data to written. size Size of the data buffer. Refer to the description section for more details on how the size affects the transfer. flags Flags that indicate whether the transfer should continue or end. Refer to the description for more details. Returns USB_DEVICE_CDC_RESULT_OK - The write request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The write request could not be added. USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_SIZE_INVALID - The specified transfer size and flag parameter are invalid. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4087 Example // Below is a set of examples showing various conditions trying to // send data with the Write() command. // // This assumes that driver was opened successfully. // Assume maxPacketSize is 64. USB_DEVICE_CDC_TRANSFER_HANDLE transferHandle; USB_DEVICE_CDC_RESULT writeRequestHandle; USB_DEVICE_CDC_INDEX instance; //------------------------------------------------------- // In this example we want to send 34 bytes only. writeRequestResult = USB_DEVICE_CDC_Write(instance, &transferHandle, data, 34, USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // In this example we want to send 64 bytes only. // This will cause a ZLP to be sent. writeRequestResult = USB_DEVICE_CDC_Write(instance, &transferHandle, data, 64, USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // This example will return an error because size is less // than maxPacketSize and the flag indicates that more // data is pending. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 32, USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING); //------------------------------------------------------- // In this example we want to place a request for a 70 byte transfer. // The 70 bytes will be sent out in a 64 byte transaction and a 6 byte // transaction completing the transfer. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 70, USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } //------------------------------------------------------- // In this example we want to place a request for a 70 bytes to be sent but // that we don't end the transfer as more data is coming. 64 bytes of the // 70 will be sent out and the USB_DEVICE_CDC_EVENT_WRITE_COMPLETE with 64 // bytes. This indicates that the extra 6 bytes weren't sent because it // would cause the end of the transfer. Thus the user needs add these 6 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4088 // bytes back to the buffer for the next group of data that needs to be sent // out. writeRequestResult = USB_DEVICE_CDC_Write(instanceHandle, &transferHandle, data, 70, USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING); if(USB_DEVICE_CDC_RESULT_OK != writeRequestResult) { //Do Error handling here } // The completion of the write request will be indicated by the // USB_DEVICE_CDC_EVENT_WRITE_COMPLETE event. 5.9.4.6.2 Data Types and Constants 5.9.4.6.2.1 USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE Type C typedef USB_DEVICE_CONTROL_TRANSFER_HANDLE USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE; Description USB Device CDC Function Driver Control Transfer Handle This is returned by the CDC function driver event handler and should be used by the application while responding to CDC function driver control transfer requests. Remarks None. 5.9.4.6.2.2 USB_DEVICE_CDC_EVENT Enumeration C typedef enum { USB_DEVICE_CDC_EVENT_SET_LINE_CODING, USB_DEVICE_CDC_EVENT_GET_LINE_CODING, USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE, USB_DEVICE_CDC_EVENT_SEND_BREAK, USB_DEVICE_CDC_EVENT_WRITE_COMPLETE, USB_DEVICE_CDC_EVENT_READ_COMPLETE, USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE, USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT, USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED } USB_DEVICE_CDC_EVENT; Description USB Device CDC Function Driver Control Transfer Status This flag is used along with the USB_DEVICE_CDC_ControlStatus() function to indicate success or failure of a CDC class specific control transfer request. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4089 Members Members Description USB_DEVICE_CDC_EVENT_SET_LINE_CODING This event occurs when the host issues a SET LINE CODING command. The application must provide a USB_DEVICE_CDC_EVENT_DATA_SET_LINE _CODING data structure to the device layer to receive the line coding data that the host will provide. The application must provide the buffer by calling the USB_DEVICE_CDC_ControlReceive() function either in the event handler or in the application (outside the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_CDC_ControlReceive() function. The pData parameter will be NULL. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRAN SFER_DATA_RECEIVED event to track completion of the command. USB_DEVICE_CDC_EVENT_GET_LINE_CODING This event occurs when the host issues a GET LINE CODING command. The application must provide a USB_DEVICE_CDC_EVENT_DATA_GET_LINE _CODING data structure to the device layer that contains the line coding data to be provided to the host. The application must provide the buffer by calling the USB_DEVICE_CDC_ControlSend() function either in the event handler or in the application (outside the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_CDC_ControlSend() function. The size of the buffer is indicated by the length parameter. The application can use the USB_DEVICE_CDC_EVENT_CONTROL_TRAN SFER_DATA_SENT event to track completion of the command. USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE This event occurs when the host issues a SET CONTROL LINE STATE command. The application must interpret the pData parameter as USB_DEVICE_CDC_EVENT_DATA_SET_CON TROL_LINE_STATE pointer type. This data structure contains the control line state data. The application can then use the USB_DEVICE_CDC_ControlStatus() function to indicate acceptance or rejection of the command. The USB_DEVICE_CDC_ControlStatus() function can be called from the event handler or in the application (out of the event handler context). The application should use the controlTransferHandle while calling the USB_DEVICE_CDC_ControlStatus() function. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4090 USB_DEVICE_CDC_EVENT_SEND_BREAK This event occurs when the host issues a SEND BREAK command. The application must interpret the pData parameter as a USB_DEVICE_CDC_EVENT_SEND_BREAK_D ATA pointer type. This data structure contains the break duration data. The application can then use the USB_DEVICE_CDC_ControlStatus() function to indicate acceptance of rejection of the command. The USB_DEVICE_CDC_ControlStatus() function can be called from the event handler or in the application (out of the event handler context). The application should use the controlTransferHandle while calling the USB_DEVICE_CDC_ControlStatus() function. USB_DEVICE_CDC_EVENT_WRITE_COMPLETE This event occurs when a write operation scheduled by calling the USB_DEVICE_CDC_Write() function has completed. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_WRITE_C OMPLETE pointer type. This will contain the transfer handle associated with the completed write transfer and the amount of data written. USB_DEVICE_CDC_EVENT_READ_COMPLETE This event occurs when a read operation scheduled by calling the USB_DEVICE_CDC_Read() function has completed. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_READ_CO MPLETE pointer type. This will contain the transfer handle associated with the completed read transfer and the amount of data read. USB_DEVICE_CDC_EVENT_SERIAL_STATE_NOTIFICATION_COMPLETE This event occurs when a serial state notification scheduled using the USB_DEVICE_CDC_SerialDataSend() function, was sent to the host. The pData parameter should be interpreted as a USB_DEVICE_CDC_EVENT_DATA_SERIAL_S TATE_NOTIFICATION_COMPLETE pointer type and will contain the transfer handle associated with the completed send transfer and the amount of data sent. USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_SENT This event occurs when the data stage of a control read transfer has completed. This event would occur after the application uses the USB_DEVICE_CDC_ControlSend() function to respond to the USB_DEVICE_CDC_EVENT_GET_LINE_CODI NG event. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4091 USB_DEVICE_CDC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED This event occurs when the data stage of a control write transfer has completed. This would occur after the application would respond with a USB_DEVICE_CDC_ControlReceive() function to the USB_DEVICE_CDC_EVENT_SET_LINE_CODI NG_EVENT and the data has been received. Remarks None. 5.9.4.6.2.3 USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING Type C typedef USB_CDC_LINE_CODING USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING; Description USB Device CDC Event Get Line Coding Data Type. This type defines the data type of the data that the user needs to respond with as a result of a USB_DEVICE_CDC_EVENT_GET_LINE_CODING event. This data is sent to the host via the USB_DEVICE_ControlWrite() function. The valid values for the members of this structure are defined in table 17 of the PSTN120.pdf document. This document is part of the CDC specification download available on the USB.org website: http://www.usb.org/developers/devclass_docs/CDC1.2_WMC1.1_012011.zip Remarks None. 5.9.4.6.2.4 USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE Structure C typedef struct { USB_DEVICE_CDC_TRANSFER_HANDLE handle; size_t length; } USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE; Description USB Device CDC Function Driver Read and Write Complete Event Data. This data type defines the data structure returned by the driver along with USB_DEVICE_CDC_EVENT_READ_COMPLETE and USB_DEVICE_CDC_EVENT_WRITE_COMPLETE events. Members Members Description 5.9.4.6.2.5 USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK Structure C typedef struct { uint16_t duration; } USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK; 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4092 Description USB Device CDC Event Set Break Data Type. This defines the data type of the data generated to the CDC event handler on a USB_DEVICE_CDC_EVENT_SEND_BREAK event. The SEND_BREAK command is described in section 6.3.13 of the PSTN120.pdf document. This document is part of the CDC specification download available on the USB.org website: http://www.usb.org/developers/devclass_docs/CDC1.2_WMC1.1_012011.zip Remarks None. 5.9.4.6.2.6 USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE Structure C typedef struct { USB_DEVICE_CDC_TRANSFER_HANDLE handle; size_t length; } USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE; Description USB Device CDC Function Driver Read and Write Complete Event Data. This data type defines the data structure returned by the driver along with USB_DEVICE_CDC_EVENT_READ_COMPLETE and USB_DEVICE_CDC_EVENT_WRITE_COMPLETE events. Members Members Description 5.9.4.6.2.7 USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE Type C typedef USB_CDC_CONTROL_LINE_STATE USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE; Description USB Device CDC Event Set Control Line State Data Type. This defines the data type of the data that should be provided to the function driver via the USB_DEVICE_CDC_ControlReceive() function when the function driver generates USB_DEVICE_CDC_EVENT_SET_CONTROL_LINE_STATE event. Remarks None. 5.9.4.6.2.8 USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING Type C typedef USB_CDC_LINE_CODING USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING; Description USB Device CDC Event Set Line Coding Data Type. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4093 This defines the data type of the data generated to the CDC event handler on a USB_DEVICE_CDC_EVENT_SET_LINE_CODING event. The valid values for the members of this structure are defined in table 17 of the PSTN120.pdf document. This document is part of the CDC specification download available on the USB.org website: http://www.usb.org/developers/devclass_docs/CDC1.2_WMC1.1_012011.zip Remarks None. 5.9.4.6.2.9 USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE Structure C typedef struct { USB_DEVICE_CDC_TRANSFER_HANDLE handle; size_t length; } USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE, USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE; Description USB Device CDC Function Driver Read and Write Complete Event Data. This data type defines the data structure returned by the driver along with USB_DEVICE_CDC_EVENT_READ_COMPLETE and USB_DEVICE_CDC_EVENT_WRITE_COMPLETE events. Members Members Description 5.9.4.6.2.10 USB_DEVICE_CDC_EVENT_HANDLER Type C typedef USB_DEVICE_CDC_EVENT_RESPONSE (* USB_DEVICE_CDC_EVENT_HANDLER)(USB_DEVICE_CDC_INDEX instanceIndex, USB_DEVICE_CDC_EVENT event, USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context); Description USB Device CDC Event Handler Function Pointer Type. This data type defines the required function signature of the USB Device CDC Function Driver event handling callback function. The application must register a pointer to a CDC Function Driver events handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive event call backs from the CDC Function Driver. The function driver will invoke this function with event relevant parameters. The description of the event handler function parameters is given here. instanceIndex - Instance index of the CDC Function Driver that generated the event. event - Type of event generated. controlTransferHandle - Control Transfer Handle for CDC function driver events that require application response. The application should use this handle when calling the USB CDC Device Control Transfer functions to respond to the events. pData - This parameter should be type casted to a event specific pointer type based on the event that has occurred. Refer to the USB_DEVICE_CDC_EVENT enumeration description for more details. context - Value identifying the context of the application that was registered along with the event handling function. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4094 5.9.4.6.2.11 USB_DEVICE_CDC_EVENT_RESPONSE Type C typedef void USB_DEVICE_CDC_EVENT_RESPONSE; Description USB Device CDC Function Driver Event Handler Response Type This is the return type of the CDC Function Driver event handler. Remarks None. 5.9.4.6.2.12 USB_DEVICE_CDC_INDEX Type C typedef uintptr_t USB_DEVICE_CDC_INDEX; Description USB Device CDC Function Driver Index This uniquely identifies a CDC Function Driver instance. Remarks None. 5.9.4.6.2.13 USB_DEVICE_CDC_INIT Structure C typedef struct { size_t queueSizeRead; size_t queueSizeWrite; size_t queueSizeSerialStateNotification; } USB_DEVICE_CDC_INIT; Description USB Device CDC Function Driver Initialization Data Structure This data structure must be defined for every instance of the CDC function driver. It is passed to the CDC function driver, by the Device Layer, at the time of initialization. The funcDriverInit member of the Device Layer Function Driver registration table entry must point to this data structure for an instance of the CDC function driver. Members Members Description 5.9.4.6.2.14 USB_DEVICE_CDC_RESULT Enumeration C typedef enum { USB_DEVICE_CDC_RESULT_OK, USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_SIZE_INVALID, USB_DEVICE_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL, USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_INVALID, USB_DEVICE_CDC_RESULT_ERROR_INSTANCE_NOT_CONFIGURED, USB_DEVICE_CDC_RESULT_ERROR_PARAMETER_INVALID, USB_DEVICE_CDC_RESULT_ERROR_CONTROL_TRANSFER_FAILED 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4095 } USB_DEVICE_CDC_RESULT; Description USB Device CDC Function Driver USB Device CDC Result enumeration. This enumeration lists the possible USB Device CDC Function Driver operation results. These values are returned by USB Device CDC Library functions. Members Members Description USB_DEVICE_CDC_RESULT_OK The operation was successful 5.9.4.6.2.15 USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA Type C typedef USB_CDC_SERIAL_STATE USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA; Description USB Device CDC Serial State Notification Data Type. This defines the data type for the CDC Serial State. This data is sent to the host over the CDC notification interface. Remarks None. 5.9.4.6.2.16 USB_DEVICE_CDC_TRANSFER_FLAGS Enumeration C typedef enum { USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE, USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING } USB_DEVICE_CDC_TRANSFER_FLAGS; Description USB Device CDC Transfer Flags These flags are used to indicate status of the pending data while sending data to the host by using the USB_DEVICE_CDC_Write() function. Members Members Description USB_DEVICE_CDC_TRANSFER_FLAGS_DATA_COMPLETE This flag indicates there is no further data to be sent in this transfer and that the transfer should end. If the size of the transfer is a multiple of the maximum packet size for related endpoint configuration, the function driver will send a zero length packet to indicate end of the transfer to the host. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4096 USB_DEVICE_CDC_TRANSFER_FLAGS_MORE_DATA_PENDING This flag indicates there is more data to be sent in this transfer. If the size of the transfer is a multiple of the maximum packet size for the related endpoint configuration, the function driver will not send a zero length packet. If the size of the transfer is greater than (but not a multiple of) the maximum packet size, the function driver will only send maximum packet size amount of data. If the size of the transfer is greater than endpoint size but not an exact multiple of endpoint size, only the closest endpoint size multiple bytes of data will be sent. This flag should not be specified if the size of the transfer is less than maximum packet size. Remarks The relevance of the specified flag depends on the size of the buffer. Refer to the individual flag descriptions for more details. 5.9.4.6.2.17 USB_DEVICE_CDC_TRANSFER_HANDLE Type C typedef uintptr_t USB_DEVICE_CDC_TRANSFER_HANDLE; Description USB Device CDC Function Driver Transfer Handle Definition This definition defines a USB Device CDC Function Driver Transfer Handle. A Transfer Handle is owned by the application but its value is modified by the USB_DEVICE_CDC_Write(), USB_DEVICE_CDC_Read() and the USB_DEVICE_CDC_SerialStateDataSend functions. The transfer handle is valid for the life time of the transfer and expires when the transfer related event had occurred. Remarks None. 5.9.4.6.2.18 USB_DEVICE_CDC_EVENT_RESPONSE_NONE Macro C #define USB_DEVICE_CDC_EVENT_RESPONSE_NONE Description USB Device CDC Function Driver Event Handler Response None This is the definition of the CDC Function Driver Event Handler Response Type none. Remarks Intentionally defined to be empty. 5.9.4.6.2.19 USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID Macro C #define USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID ((USB_DEVICE_CDC_TRANSFER_HANDLE)(-1)) Description USB Device CDC Function Driver Invalid Transfer Handle Definition This definition defines a USB Device CDC Function Driver Invalid Transfer Handle. A Invalid Transfer Handle is returned by the USB_DEVICE_CDC_Write(), USB_DEVICE_CDC_Read() and the USB_DEVICE_CDC_SerialStateNotificationSend() functions 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4097 when the request was not successful. Remarks None. 5.9.4.7 Files Files Name Description usb_device_cdc.h USB Device CDC Function Driver Interface Description 5.9.4.7.1 usb_device_cdc.h USB Device CDC Function Driver Interface This file describes the USB Device CDC Function Driver interface. Enumerations Name Description USB_DEVICE_CDC_EVENT USB Device CDC Function Driver Control Transfer Status USB_DEVICE_CDC_RESULT USB Device CDC Function Driver USB Device CDC Result enumeration. USB_DEVICE_CDC_TRANSFER_FLAGS USB Device CDC Function Driver Transfer Flags Functions Name Description USB_DEVICE_CDC_ControlReceive This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_CDC_ControlSend This function allows the application to respond to the CDC function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_CDC_ControlStatus This function allows the application to complete the status stage of the the CDC Function Driver specific control transfer request. USB_DEVICE_CDC_EventHandlerSet This function registers a event handler for the specified CDC function driver instance. USB_DEVICE_CDC_Read This function requests a data read from the USB Device CDC Function Driver Layer. USB_DEVICE_CDC_SerialStateNotificationSend This function schedules a request to send serial state notification to the host. USB_DEVICE_CDC_Write This function requests a data write to the USB Device CDC Function Driver Layer. 5.9 USB Library Help MPLAB Harmony Help USB Device CDC Library 5-4098 Macros Name Description USB_DEVICE_CDC_EVENT_RESPONSE_NONE USB Device CDC Function Driver Event Handler Response Type None. USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID USB Device CDC Function Driver Invalid Transfer Handle Definition. Structures Name Description USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK USB Device CDC Event Set Break Data Type. USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE USB Device CDC Function Driver Read and Write Complete Event Data. USB_DEVICE_CDC_INIT USB Device CDC Function Driver Initialization Data Structure Types Name Description USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE USB Device CDC Function Driver Control Transfer Handle USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING USB Device CDC Event Get Line Coding Data Type. USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE USB Device CDC Event Set Line Coding Data Type. USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING USB Device CDC Event Set Line Coding Data Type. USB_DEVICE_CDC_EVENT_HANDLER USB Device CDC Event Handler Function Pointer Type. USB_DEVICE_CDC_EVENT_RESPONSE USB Device CDC Function Driver Event Callback Response Type USB_DEVICE_CDC_INDEX USB Device CDC Function Driver Index USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA USB Device Serial State Notification Data Type. USB_DEVICE_CDC_TRANSFER_HANDLE USB Device CDC Function Driver Transfer Handle Definition. Company Microchip Technology Incorporated FileName: usb_device_cdc.h 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4099 5.9.5 USB Generic Device Library 5.9.5.1 Introduction Introduces the MPLAB Harmony USB Generic Device Library. Description The USB Generic Device library provides a framework to develop custom or vendor class USB device applications . The library supports all USB transfer types (control, bulk, interrupt, isochronous) along with endpoint management functions. The USB device generic library implementation supports USB specification 2.0. Following figure illustrates how Generic Device Library fits into the MPLAB Harmony USB Device Stack architecture . Figure: MPLAB Harmony USB Device library architecture This USB Generic Device Library offers services to the application to interact and respond to the host requests. USB Generic Device library is also referred to as Generic function driver in this document. 5.9.5.2 Release Notes MPLAB Harmony Version: v0.70b USB Generic Device Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4100 Known Issues: Nothing to report in this release. 5.9.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.5.4 Library Architecture 5.9.5.4.1 Library Overview Provides an overview of the Generic Device function driver. Description The Generic Device function driver overview diagram is shown below. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4101 Figure: USB DEVICE GENERIC Library Overview diagram A Generic function driver instance is a collection of Generic USB interfaces. The device management on end point zero is handled by the device library(vendor class specific requests are routed to the Generic function driver by device library). The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the USB DEVICE Generic module. Library Interface Section Description Client Setup Details Opening an instance of the USB Generic function driver, registering callback with the USB Generic function driver and closing an instance of the USB Generic function driver. Client Data Handling Details read/write to/from the host Client Subclass Specific Details the supported sub class specific management requests and notification. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4102 5.9.5.4.2 Abstraction Model Provides an architectural overview of the USB Generic Device function driver. Description The USB Generic Device function driver offers various services to a vendor specific class USB device to communicate with the host by abstracting USB specification details. The USB Generic Device function driver with USB DEVICE layer and USB controller driver forms the basic library entity using which the device can communicate with the USB host.The basic software architecture into which Generic function driver fits into is depicted in the following diagram. Figure: USB DEVICE Generic Software Abstraction Block Diagram Vendor specific functions have to register a set of standard APIs with the generic library. This library calls these APIs as call back function at run time. For example, vendor specific tasks function routine is called when USB device generic function driver receives vendor specific transfer from a USB host. All generic function driver tasks are called from the task routine of USB device layer. so here maximum performance of the device can be achieved with this library. The USB controller driver takes the responsibility of managing the USB peripheral on the device. The USB device layer handles the device enumeration etc. For more details about the USB controller driver and USB device layer library kindly refer to the corresponding documents. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4103 5.9.5.5 Using the Library 5.9.5.5.1 Files to Include Describes which files to include in the project to use the Generic Device Function Driver. Description The following table shows the files that must be included in the project in order to use the Generic Function Driver. These files are located in the framework folder of the MPLAB Harmony installation. It is assumed that the Device Layer files ( and the files needed by the Device Layer) are already included in the project. A path to the framework folder in the Harmony installation should be added to the project include search path. Filename Description \framework\usb\src\usb_device_generic.c Contains the implementation of the Generic device function driver. \framework\usb\usb_device_generic.h Must be included in every file that needs to invoke the Generic device function driver API system_config.h User created file which contains the Generic device function driver configuration. 5.9.5.5.2 Library Configuration Describes how to configure the Generic Function Driver. Description The configuration of the USB Generic Device Function Driver is contained in system_config.h These configuration settings will apply to all instances of the USB Generic Device Function Driver. This header can be placed anywhere; however, the path of this header needs to be present in the include search path for a successful build. Refer to the Applications Overview section for more details. This section explains the data structures that need to be setup by the application to use the Generic function driver. For setting data relevant for other modules (device layer and controller driver) kindly refer to the respective module documentation. Constants: USB_DEVICE_GEN_DRIVER_MAX_INSTANCES: The maximum number of Generic function driver instances to be supported. The valid values are greater than or equal to 1. this constant is not defined the default value taken by the Generic function driver is 1. Data structures: The application should form structure USB_DEVICE_GEN_DRIVER_INIT_INSTANCE. The structure takes pointers to the following functions. - A vendor defined initialize function that is called by the device layer when it initializes the generic function driver. This will happen when the device layer process a SET CONFIGURATION command from the host. - A vendor defined de-initialize function that is called by the device layer when it de-initializes the generic function driver. This will happen when the device layer process a reset event or is required to change the configuration by the host. - A vendor defined Setup packet handler. This function is called by the device layer when it needs to pass class specific control 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4104 transfer to the generic function driver. - A vendor specified tasks functions. This is called periodically by the device layer. This function can maintain a vendor device state machine. The application needs to define an array of USB_DEVICE_GEN_DRIVER_MAX_INSTANCES(defined by the application in system_config.h) such structures. For example, if the application needs two instances of the Generic Device, then the size of this array should be two. Example: Creating the USB_DEVICE_GEN_DRIVER_INIT_INSTANCE structure. USB_DEVICE_GEN_DRIVER_INIT_INSTANCE genUsbInitInstance[] = { { .vendorSpecificInitialize = APP_Initialize, .vendorSpecificDeInitialize = APP_DeInitialize, .vendorSpecificSetupPacketHandler = APP_SetupPacketHandler, .tasks = APP_Tasks } }; 5.9.5.5.3 Client Setup Note: To invoke any of the client setup routines listed in this section the device should be in configured state. Any attempts invoking the client setup routines before the configured state will result in graceful exit. Before using any of the USB Generic function driver services it needs to be setup once in the application. Setting up the USB Generic function driver involves 1. Opening an instance of the USB Generic function driver. 2. Registering callback with the USB Generic function driver. 3. Closing an instance of the USB Generic function driver. Opening an Instance of the USB GENERIC function driver: Before attempting to use any of the USB Generic function driver services an instance of it needs to be opened by the application. An instance of USB Generic function driver is defined as a group of minimum interfaces that constitute a Generic USB device. To open an instance of USB Generic function driver application should call the function USB_DEVICE_GEN_DRIVER_Open. Example: Opening a USB Generic instance // Client Handle DRV_HANDLE genHandle; // open Generic USB device function driver instance 0 genHandle = USB_DEVICE_GEN_DRIVER_Open ( 0 ); // Check the validity of the handle returned if(DRV_HANDLE_INVALID == genHandle) { \ Handle the error } Registering callback with the USB GENERIC function driver: USB Generic function driver will inform the status of various events (both management and data) to the application using a callback function registered with the USB Generic function driver. This callback function should be registered with the function driver before expecting any event notifications. There are three sources of generating events 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4105 • Data transmission request ( USB_DEVICE_GEN_DRIVER_CALLBACK_TX_ ) • Data reception request ( USB_DEVICE_GEN_DRIVER_CALLBACK_RX ) • Management Requests ( USB_DEVICE_GEN_DRIVER_CALLBACK_MANAGEMENT ) Each of these requests will result in the generation of events of type USB_DEVICE_GEN_DRIVER_CALLBACK_TYPE For a detailed list of events go through the above enum data type. To register a callback with the Generic function driver application should first define a function of the signature USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT. Once defined it can be registered with the Generic function driver using the function USB_DEVICE_GEN_DRIVER_RegisterCallBack. Example: Registering an application callback with the Generic function driver // Application callback to handle relevant events. void app_gen_CallBack ( SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_GEN_DRIVER_CALLBACK_TYPE callback, USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT event) { switch (callback) { case USB_DEVICE_GEN_DRIVER_CALLBACK_TX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_RX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_MANAGEMENT: break; default: break; } } int main () { DRV_HANDLE genHandle; USB_ERROR_STATUS err; // open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_Open ( 0 ); err = USB_DEVICE_GEN_DRIVER_RegisterCallBack (genHandle,app_gen_CallBack ); if(err) { //handle error } // app code // Occurrance of any event of type USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT results in // calling of the registered application callback return 0; } Closing an Instance of the USB Generic function driver: 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4106 If at all the application wants to close an opened Generic function driver instance it can do so by calling the function USB_DEVICE_GEN_DRIVER_Close. The application should pass the client handle it received with opened the Generic function driver instance as the parameter. If the close is successful 0 is returned by the Generic to indicate success. Example: Closing a Generic USB instance // Return status USB_ERROR_STATUS status; // Close Generic USB device driver instance 0 status = USB_DEVICE_GEN_DRIVER_Close(0); if(USB_ERROR_INVALID_HANDLE ==status) { // Generic USB device function driver instance 0 is either not opened/initialized yet } else if(status == USB_ERROR_OK) { // Generic USB device function driver instance 0 is successfully closed. // app code } Before closing the Generic function driver instance the application should be aware of the following 1. Once an instance of the Generic function driver is closed the application cannot write to or read from the data end points(if driven by Generic function driver). 2. The application will not get any event notifications . INITIAL SETUP: Before invoking any of the services offered by the Generic function driver following steps should have been completed 1. Certain key data structures need to be setup(initialized) by the application. 2. Certain system functions belonging to the MPLAB Harmony USB Device library should have been called. 3. The device should be in configured state. The setup of the key data structures is explained in the Configuring the Library section. The following section focuses on the key system functions that need to be called by the application before using Generic function driver. The following diagram explains the sequence of system functions (belonging to the MPLAB Harmony USB Device library only) invocations. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4107 Figure: System Initialization Example: System initialization // Populate USB Controller driver init data usbInitData.usbID = USB_ID_1; usbInitData.usbModuleSetup.OpMode = USB_OPMODE_DEVICE; usbInitData.usbModuleSetup.ppMode = USB_PING_PONG_MODE_SELECTION; usbInitData.usbModuleSetup.StopInIdle = false; usbInitData.usbModuleSetup.SuspendInSleep = false; // Initialize the USB Control driver driverObjectHandle = DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT*)&usbInitData); if (SYS_MODULE_OBJ_INVALID == driverObjectHandle) { // Handle error } // NOTE: USB controller driver is opened by both device layer and function driver and not by the application. // Populate USB Device layer init data deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; deviceLayerInit.usbDriverIndex = DRV_USB_INDEX_0; deviceLayerInit.usbMasterDescriptor = (USB_MASTER_DESCRIPTOR*)&usbMasterDescriptor; deviceLayerInit.registeredFuncCount = 1; deviceLayerInit.registeredFunctions = (USB_DEVICE_FUNC_REGISTRATION_TABLE*)funcRegistrationTable; 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4108 // Initialize the USB device layer usbDeviceObj = USB_DEVICE_Initialize( USB_DEVICE_INDEX_0, (SYS_MODULE_INIT*)&deviceLayerInit ); // Open the device layer. usbDevHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0 ); // Register a callback with device layer to get event notification (for end point 0) USB_DEVICE_EventCallBackSet(usbDevHandle, usbDeviceEventCallBack); The following example provides a complete Generic function driver setup. This example do not use separate functions to do activities like system initialization, Generic function driver setup etc for the sake of clarity. It is recommended to use separate functions to have a structured view of the project. // Application callback to handle relevant events. void app_gen_CallBack ( SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_GEN_DRIVER_CALLBACK_TYPE callback, USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT event) { switch (callback) { case USB_DEVICE_GEN_DRIVER_CALLBACK_TX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_RX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_MANAGEMENT: break; default: break; } } // Device event callback of the application. // This will be registered with the device layer // during the system initialization. void usbDeviceEventCallBack(USB_DEVICE_EVENTS events) { if(events.setConfiguration) { // Device is configured. // Initialize function drivers. isConfigured = true; ///////////////// Generic function driver Setup- Begin////////////////////// DRV_HANDLE genHandle; USB_ERROR_STATUS err; // open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_Open ( 0 ); err = USB_DEVICE_GEN_DRIVER_RegisterCallBack (genHandle,app_gen_CallBack ); if(err) { //handle error } ///////////////// Generic function driver Setup- End////////////////////// } } int main () { 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4109 // Device layer Init structure USB_DEVICE_INIT deviceLayerInit; // objects for Controller driver and device layer (returned by init routines) SYS_MODULE_OBJ driverObjectHandle, usbDeviceObj; // Client handle DRV_HANDLE genHandle; // Client handle for device layer DRV_HANDLE usbDevHandle; // USB controller driver init data DRV_USB_INIT usbInitData; ///////////////// system initialization- Begin////////////////////// // Populate USB Controller driver init data usbInitData.usbID = USB_ID_1; usbInitData.usbModuleSetup.OpMode = USB_OPMODE_DEVICE; usbInitData.usbModuleSetup.ppMode = USB_PING_PONG_MODE_SELECTION; usbInitData.usbModuleSetup.StopInIdle = false; usbInitData.usbModuleSetup.SuspendInSleep = false; // Initialize the USB Control driver driverObjectHandle = DRV_USB_Initialize(DRV_USB_INDEX_0, (SYS_MODULE_INIT*)&usbInitData); if (SYS_MODULE_OBJ_INVALID == driverObjectHandle) { // Handle error } // NOTE: USB controller driver is opened by both device layer and // function driver and not by the application. // Populate USB Device layer init data deviceLayerInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; deviceLayerInit.usbDriverIndex = DRV_USB_INDEX_0; deviceLayerInit.usbMasterDescriptor = (USB_MASTER_DESCRIPTOR*)&usbMasterDescriptor; deviceLayerInit.registeredFuncCount = 1; deviceLayerInit.registeredFunctions = (USB_DEVICE_FUNC_REGISTRATION_TABLE*)funcRegistrationTable; // Initialize the USB device layer usbDeviceObj = USB_DEVICE_Initialize( USB_DEVICE_INDEX_0, (SYS_MODULE_INIT*)&deviceLayerInit ); // Open the device layer. usbDevHandle = USB_DEVICE_Open( USB_DEVICE_INDEX_0 ); // Register a callback with device layer to get event notification (for end point 0) USB_DEVICE_EventCallBackSet(usbDevHandle, usbDeviceEventCallBack); ///////////////// system initialization- End////////////////////// // the application body while(1) { // Device layer task USB_DEVICE_Tasks(usbDeviceObj); // Check if the enumeration is complete if(isConfigured) { // Start calling application tasks } } 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4110 return 0; } 5.9.5.5.4 Client Data Handling The USB Generic function driver provides APIs to handle data to/from the host. The following section provides the usage of these APIs. The data transfer in the Generic function driver happens over the end points with all the type of transfer modes (BULK, ISOCHRONOUS, INTERRUPT) at both direction of IN and OUT. The following sections focus on the data transmission over the end points . The read and write naming conventions used for the data handling APIs are from the device point of view. So USB_DEVICE_GEN_DRIVER_ReadEp function is a request to the MPLAB Harmony USB Device library to get data available from the host. Similarly USB_DEVICE_GEN_DRIVER_WriteEp function is a request to make data available to the host. Generic USB Buffer Objects: In order place a read/write request with the Generic function driver the application should first create a buffer object of the type USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT. It is recommended to create separate buffer objects for read and write operations. A USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT contains a pointer to the data buffer, length of the buffer and transfer count. The transfer count is updated by the Generic function driver (after the read/write request is submitted) to indicate the actual amount of data transferred to/from the host. Example: Generic USB DATA Buffer Object Creation // buffer for read operation of size 64 bytes uint8_t inBuffer[64]; // define and initialize the buffer object USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT inBufferObject = {(uint8_t*)&inBuffer, 64, 0}; Read From the Host: As explained above the application should make use of the API USB_DEVICE_GEN_DRIVER_ReadEp to get data from the host. Before placing a read request with the Generic function driver the application should get the pipeHandle using USB_DEVICE_GEN_DRIVER_GetPipeHandle . If the received is valid , applicatio has to check if it can place the next read request. This status can be obtained using the API USB_DEVICE_GEN_DRIVER_TxRx_StatusGet. If this API returns USB_DEVICE_GEN_DRIVER_INSTANCE_RX_READY then the application can place a request for a read operation. If the received status is anything else then the application should poll until the receive status is ready. The following example shows the usage of read request. Example: Data Read Request #define APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX 0 // create buffer uint8_t outBuffer[64]; uint8_t datalen = 64; uint8_t epNum = 1; dirn = USB_DEVICE_GEN_DRIVER_EP_IN_INDEX; //OUT:(0x00) or IN: 0x01) DRV_HANDLE genHandle,pipeHandle; USB_ERROR_STATUS genErr; //create the buffer object with datalength 64 USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT readBufferObject = {&outBuffer, 64, 0}; 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4111 // open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_Open ( APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX ); if(USB_DEVICE_GEN_DRIVER_RegisterCallBack (genHandle,app_gen_CallBack )) { //handle error } //Get the pipe handle for the endpoint pipeHandle = USB_DEVICE_GEN_DRIVER_GetPipeHandle(genHandle, epNum, dirn)) if ( DRV_HANDLE_INVALID == pipeHandle) { //The request was not successful } //Got the pipe handle for the endpoint //Pass the pipe handle to USB_DEVICE_GEN_DRIVER_ReadEp genErr = USB_DEVICE_GEN_DRIVER_ReadEp( pipeHandle,&readBufferObject); if(USB_ERROR_OK != genErr) { //Read request is not accepted. } If the application has registered a callback function with the Generic function driver then any events related to the read request will be informed to the application via this callback. In the callback the application can check whether all of the data requested is received. The following example shows this. Example: Data Read Request with application callback #define APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX 0 // Application callback to handle relevant events. void app_gen_CallBack ( SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_GEN_DRIVER_CALLBACK_TYPE callback, USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT event) { switch (callback) { case USB_DEVICE_GEN_DRIVER_CALLBACK_TX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_RX: if (readBufferObject.transferCount == readBufferObject.dataLen) { //entire data is read from the host. } else { //some of the data is not read. //get some logic in place to handle this } break; case USB_DEVICE_GEN_DRIVER_CALLBACK_MANAGEMENT: break; default: break; } } 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4112 int main () { // create buffer uint8_t outBuffer[64]; uint8_t datalen = 64; uint8_t epNum = 1; dirn = USB_DEVICE_GEN_DRIVER_EP_OUT_INDEX; //OUT:(0x00) or IN: 0x01) DRV_HANDLE genHandle; USB_ERROR_STATUS genErr; DRVHANDLE pipeHandle; //create the buffer object with datalength 64 USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT readBufferObject = {&outBuffer, 64, 0}; // open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_Open ( 0 ); if(USB_DEVICE_GEN_DRIVER_RegisterCallBack (genHandle,app_gen_CallBack )) { //handle error } //Get the pipe handle for the endpoint pipeHandle = USB_DEVICE_GEN_DRIVER_GetPipeHandle(genHandle, epNum, dirn)) if ( DRV_HANDLE_INVALID == pipeHandle) { //The request was not successful } //we got the pipe handle for the endpoint //Pass the pipe handle to USB_DEVICE_GEN_DRIVER_ReadEp genErr = USB_DEVICE_GEN_DRIVER_ReadEp( pipeHandle,&readBufferObject); if(USB_ERROR_OK == genErr) { //read request is accepted //if app callback is registered, rest needs to be handled //in the appcallback, which is called by the Generic USB device function //driver when it is intimated by the device layer about //the transfer. } else { // something wrong in the read request // handle the error case switch ( genErr ) { case USB_ERROR_INVALID_HANDLE: break; case USB_ERROR_INVALID_BUFFER: break; case USB_ERROR_BUSY: break; } } return 0; } 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4113 The read request code flow can be better understood with the following diagram. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4114 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4115 Write to the Host: The application should make use of the API USB_DEVICE_GEN_DRIVER_WriteEp to get transfer data to the host. Before placing a write request with the Generic function driver the application should the application should get the pipeHandle using USB_DEVICE_GEN_DRIVER_GetPipeHandle . If the received is valid , application has tocheck if it can place the next write request. This status can be obtained using the API USB_DEVICE_GEN_DRIVER_TxRx_StatusGet. If this API returns USB_DEVICE_GEN_DRIVER_INSTANCE_TX_READY then the application can place a request for a write operation. If the received status is anything else then the application should poll until the transmit status is ready.The following example shows the usage of read request. Example: Data Read Request #define APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX 0 // create buffer. Assuming data end-point max packet size is 64 bytes. uint8_t inBuffer[64] ; uint8_t datalen = 64; uint8_t epNum = 1; uint8_t dirn = USB_DEVICE_GEN_DRIVER_EP_IN_INDEX;// OUT :0x00 or IN : 0x01 DRV_HANDLE pipeHandle,genHandle; //create the buffer object with datalength 64 USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT writeBufferObject = {&inBuffer, 64, 0}; //open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_DRIVER_Open (APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX); if(USB_DEVICE_GEN_DRIVER_DRIVER_RegisterCallBacks (genHandle,app_gen_CallBack )) { //handle error } //Get the pipe handle for the endpoint pipeHandle = USB_DEVICE_GEN_DRIVER_GetPipeHandle(genHandle, epNum, dirn)) if ( DRV_HANDLE_INVALID == pipeHandle) { //The request was not successful. } //we got the pipe handle for the endpoint //Pass the pipe handle to USB_DEVICE_GEN_DRIVER_WriteEp genErr = USB_DEVICE_GEN_DRIVER_WriteEp( pipeHandle,&writeBufferObject); if(USB_ERROR_OK != genErr) { //write request is not accepted } If the application has registered a callback function with the Generic function driver then any events related to the write request will be informed to the application via this callback. In the callback the application can check whether all of the data requested is transmitted. The following example shows this. Example: Data Read Request with application callback #define APP_USB_DEVICE_GEN_DRIVER_FUNC_INDEX 0 // Application callback to handle relevant events. void app_gen_CallBack ( SYS_MODULE_INDEX funcDriverIndex, USB_DEVICE_GEN_DRIVER_CALLBACK_TYPE callback, USB_DEVICE_GEN_DRIVER_CALLBACK_EVENT event) 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4116 { switch (callback) { case USB_DEVICE_GEN_DRIVER_CALLBACK_TX: if (writeBufferObject.transferCount == writeBufferObject.dataLen) { //entire data is written to host. } else { //some of the data is not sent to the host. //think and get some logic in place to handle this } break; case USB_DEVICE_GEN_DRIVER_CALLBACK_RX: break; case USB_DEVICE_GEN_DRIVER_CALLBACK_MANAGEMENT: break; default: break; } } int main () { // create buffer. Assuming data end-point max packet size is 64 bytes. uint8_t inBuffer[64] ; uint8_t datalen = 64; uint8_t epNum = 1; uint8_t dirn = USB_DEVICE_GEN_DRIVER_EP_OUT_INDEX;// OUT :0x00 or IN : 0x01 DRV_HANDLE pipeHandle,genHandle; //create the buffer object with datalength 64 USB_DEVICE_GEN_DRIVER_DATA_BUFFER_OBJECT writeBufferObject = {&inBuffer, 64, 0}; //open the Generic USB device driver instance 0 ( or what ever is applicable) genHandle = USB_DEVICE_GEN_DRIVER_DRIVER_Open ( 0 ); if(USB_DEVICE_GEN_DRIVER_DRIVER_RegisterCallBacks (genHandle,app_gen_CallBack )) { //handle error } //Get the pipe handle for the endpoint pipeHandle = USB_DEVICE_GEN_DRIVER_GetPipeHandle(genHandle, epNum, dirn)) if ( DRV_HANDLE_INVALID == pipeHandle) { //The request was not successful. } //we got the pipe handle for the endpoint //Pass the pipe handle to USB_DEVICE_GEN_DRIVER_WriteEp genErr = USB_DEVICE_GEN_DRIVER_WriteEp( pipeHandle,&writeBufferObject); if(USB_ERROR_OK != genErr) { //write request is not accepted 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4117 } return 0; } The write request code flow can be better understood with the following diagram. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4118 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4119 5.9.5.5.5 Client Subclass Specific This section details the vendor specific sub-class specific requests and notifications handled by the Generic function driver. 5.9.5.6 Library Interface Data Types and Constants Name Description USB_DEVICE_GENERIC_EVENT This is type USB_DEVICE_GENERIC _EVENT. USB_DEVICE_GENERIC_EVENT_DATA Union that holds event data for different generic driver events. USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_DATA_CONTR OL_TRANSFER_SETUP _REQUEST event. USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_ENDPOINT_R EAD_COMPLETE event. USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_ENDPOINT_W RITE_COMPLETE event. USB_DEVICE_GENERIC_EVENT_HANDLER The data-type that defines the signature of the event callback function. USB_DEVICE_GENERIC_EVENT_RESPONSE The return type of the application callback function. USB_DEVICE_GENERIC_INDEX Data-type for USB device generic driver index. USB_DEVICE_GENERIC_RESULT The enumerated data-type that idnetifies the possible result of an operation. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4120 USB_DEVICE_GENERIC_TRANSFER_FLAG Enumerated data-type that identifies the USB device generic function driver's transfer flag. USB_DEVICE_GENERIC_TRANSFER_HANDLE Data-type of the generic driver transfer handle. Functions Name Description USB_DEVICE_GENERIC_EndpointIsEnabled This function returns true if the requested endpoint is enabled. USB_DEVICE_GENERIC_EndpointRead Reads data received from host on the requested endpoint. USB_DEVICE_GENERIC_EndpointStall This function stalls the requested endpoint. USB_DEVICE_GENERIC_EndpointStallClear Clears STALL on the endpoint. USB_DEVICE_GENERIC_EndpointStallStatusGet USB Generic function driver library function that returns true if STALL is enabled on the endpoint. USB_DEVICE_GENERIC_EndpointWrite This function allows the application client to transfer data from device to host on the requested endpoint. USB_DEVICE_GENERIC_EventHandlerSet This function allows the application client to register event handler callback with the generic function driver library. Description This section describes the Application Programming Interface (API) functions of the USB Generic Device Library. Refer to each section for a detailed description. 5.9.5.6.1 Functions 5.9.5.6.1.1 USB_DEVICE_GENERIC_EndpointIsEnabled Function C bool USB_DEVICE_GENERIC_EndpointIsEnabled( USB_DEVICE_GENERIC_INDEX iGEN, USB_ENDPOINT endpoint ); Preconditions USB device layer be initialized. Parameters Parameters Description iGEN USB generic driver function driver instance ID. endpoint endpoint address. Returns true if endpoint is enabled. Remarks None. Example 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4121 5.9.5.6.1.2 USB_DEVICE_GENERIC_EndpointRead Function C USB_DEVICE_GENERIC_RESULT USB_DEVICE_GENERIC_EndpointRead( USB_DEVICE_GENERIC_INDEX iGEN, USB_DEVICE_GENERIC_TRANSFER_HANDLE * transferHandle, USB_ENDPOINT endpoint, uint8_t * buffer, size_t bufferSize ); Preconditions USB device layer be initialized. Parameters Parameters Description iGEN USB generic function driver instance ID. transferHandle Pointer to transfer handle. endpoint endpoint address buffer Buffer pointer bufferSize Buffer size Returns See USB_DEVICE_GENERIC_RESULT. Remarks None. Example 5.9.5.6.1.3 USB_DEVICE_GENERIC_EndpointStall Function C USB_DEVICE_GENERIC_RESULT USB_DEVICE_GENERIC_EndpointStall( USB_DEVICE_GENERIC_INDEX iGEN, USB_ENDPOINT endpoint ); Preconditions USB device layer must be initialized. Parameters Parameters Description iGEN USB device generic function driver instance ID. endpoint Endpoint address. Returns See USB_DEVICE_GENERIC_RESULT Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4122 Example 5.9.5.6.1.4 USB_DEVICE_GENERIC_EndpointStallClear Function C USB_DEVICE_GENERIC_RESULT USB_DEVICE_GENERIC_EndpointStallClear( USB_DEVICE_GENERIC_INDEX iGEN, USB_ENDPOINT endpoint ); Preconditions USB device layer be initialized. Parameters Parameters Description iGEN Generic driver instance index. endpoint Endpoint address for which the stall has to be cleared. Returns See USB_DEVICE_GENERIC_RESULT. Remarks None. Example 5.9.5.6.1.5 USB_DEVICE_GENERIC_EndpointStallStatusGet Function C bool USB_DEVICE_GENERIC_EndpointStallStatusGet( USB_DEVICE_GENERIC_INDEX iGEN, USB_ENDPOINT endpoint ); Preconditions USB device layer be initialized. Parameters Parameters Description iGEN USB generic function driver instance ID. endpoint endpoint address. Returns true if endpoint is stalled. Remarks None. Example 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4123 5.9.5.6.1.6 USB_DEVICE_GENERIC_EndpointWrite Function C USB_DEVICE_GENERIC_RESULT USB_DEVICE_GENERIC_EndpointWrite( USB_DEVICE_GENERIC_INDEX iGEN, USB_DEVICE_GENERIC_TRANSFER_HANDLE * transferHandle, USB_ENDPOINT endpoint, uint8_t * buffer, size_t bufferSize, USB_DEVICE_GENERIC_TRANSFER_FLAG flags ); Preconditions USB device layer be initialized. Parameters Parameters Description iGEN USB generic function driver instance ID. transferHandle Pointer to transfer handle. endpoint endpoint address buffer Buffer pointer bufferSize Buffer size flags Flag that specifies this function whether to end the transfer with a short packet or not. Returns See USB_DEVICE_GENERIC_RESULT. Remarks None. Example 5.9.5.6.1.7 USB_DEVICE_GENERIC_EventHandlerSet Function C USB_DEVICE_GENERIC_RESULT USB_DEVICE_GENERIC_EventHandlerSet( USB_DEVICE_GENERIC_INDEX iGEN, USB_DEVICE_GENERIC_EVENT_HANDLER eventHandler, uintptr_t userData ); Preconditions USB device layer be initialized. Parameters Parameters Description instanceIndex USB Generic function driver instance ID. eventHandler Pointer to application event handler callback function. Returns See USB_DEVICE_GENERIC_RESULT. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4124 Remarks None. Example 5.9.5.6.2 Data Types and Constants 5.9.5.6.2.1 USB_DEVICE_GENERIC_EVENT Enumeration C typedef enum { USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_SETUP_REQUEST, USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED, USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_DATA_SENT, USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_ABORTED, USB_DEVICE_GENERIC_EVENT_ENDPOINT_WRITE_COMPLETE, USB_DEVICE_GENERIC_EVENT_ENDPOINT_READ_COMPLETE } USB_DEVICE_GENERIC_EVENT; Description This is type USB_DEVICE_GENERIC_EVENT. Members Members Description USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_SETUP_REQUEST Control transfer data stage is received from host to device USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_DATA_RECEIVED Control transfer data stage is received from host to device USB_DEVICE_GENERIC_EVENT_CONTROL_TRANSFER_DATA_SENT Control transfer data stage is transmitted from device to host 5.9.5.6.2.2 USB_DEVICE_GENERIC_EVENT_DATA Union C typedef union { USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE endpointWriteComplete; USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE endpointReadComplete; USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST * ptrSetupRequest; } USB_DEVICE_GENERIC_EVENT_DATA; Description Event Data. Members Members Description USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE endpointWriteComplete; Data associated with USB_DEVICE_GENERIC_EVENT_E NDPOINT_WRITE_COMPLETE event USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE endpointReadComplete; Data associated with USB_DEVICE_GENERIC_EVENT_E NDPOINT_READ_COMPLETE event 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4125 USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST * ptrSetupRequest; Data associated with USB_DEVICE_GENERIC_EVENT_D ATACONTROL Remarks None. 5.9.5.6.2.3 USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST Structure C typedef struct { uint8_t bmRequestType; uint8_t bRequest; uint16_t wValue; uint16_t wIndex; uint16_t wLength; } USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST; Description Data assocated with USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST event. Members Members Description uint8_t bmRequestType; Format of setup packet from table 9-2 of USB 2.0 spec Remarks None. 5.9.5.6.2.4 USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE Structure C typedef struct { unsigned int dataSize; uint8_t * data; USB_DEVICE_IRP_STATUS status; USB_DEVICE_GENERIC_TRANSFER_HANDLE transferHandle; } USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE; Description Data assocated with USB_DEVICE_GENERIC_EVENT_ENDPOINT_READ_COMPLETE event. Members Members Description unsigned int dataSize; data size received uint8_t * data; Pointer to data buffer USB_DEVICE_IRP_STATUS status; Status USB_DEVICE_GENERIC_TRANSFER_HANDLE transferHandle; Transfer handle Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4126 5.9.5.6.2.5 USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE Structure C typedef struct { unsigned int dataSize; uint8_t * data; USB_DEVICE_IRP_STATUS status; USB_DEVICE_GENERIC_TRANSFER_HANDLE transferHandle; } USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE; Description Data assocated with USB_DEVICE_GENERIC_EVENT_ENDPOINT_WRITE_COMPLETE event. Members Members Description unsigned int dataSize; data size transmitted uint8_t * data; Pointer to data buffer USB_DEVICE_IRP_STATUS status; Status USB_DEVICE_GENERIC_TRANSFER_HANDLE transferHandle; Transfer handle Remarks None. 5.9.5.6.2.6 USB_DEVICE_GENERIC_EVENT_HANDLER Type C typedef USB_DEVICE_GENERIC_EVENT_RESPONSE (* USB_DEVICE_GENERIC_EVENT_HANDLER)(USB_DEVICE_GENERIC_INDEX instanceIndex, USB_DEVICE_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_GENERIC_EVENT event, USB_DEVICE_GENERIC_EVENT_DATA * eventData, uintptr_t userData); Description USB device generic function driver event handle. The application provided event callback function must be of this data-type. Remarks None. 5.9.5.6.2.7 USB_DEVICE_GENERIC_EVENT_RESPONSE Type C typedef void USB_DEVICE_GENERIC_EVENT_RESPONSE; Description Return type of the application callback function. Remarks Also see, USB_DEVICE_GENERIC_EVENT_HANDLER 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4127 5.9.5.6.2.8 USB_DEVICE_GENERIC_INDEX Type C typedef SYS_MODULE_INDEX USB_DEVICE_GENERIC_INDEX; Description Data-type for USB device generic driver index. Remarks None. 5.9.5.6.2.9 USB_DEVICE_GENERIC_RESULT Enumeration C typedef enum { USB_DEVICE_GENERIC_RESULT_QUEUE_FULL, USB_DEVICE_GENERIC_RESULT_OK, USB_DEVICE_GENERIC_RESULT_ENDPOINT_NOT_CONFIGURED, USB_DEVICE_GENERIC_RESULT_PARAMETER_INVALID } USB_DEVICE_GENERIC_RESULT; Description Possible results of Generic Driver operations. Members Members Description USB_DEVICE_GENERIC_RESULT_QUEUE_FULL Queue is full USB_DEVICE_GENERIC_RESULT_OK No Error USB_DEVICE_GENERIC_RESULT_ENDPOINT_NOT_CONFIGURED Endpoint not configured USB_DEVICE_GENERIC_RESULT_PARAMETER_INVALID One or more parameter/s of the function is invalid Remarks None. 5.9.5.6.2.10 USB_DEVICE_GENERIC_TRANSFER_FLAG Enumeration C typedef enum { USB_DEVICE_GENERIC_TRANSFER_FLAG_NONE, USB_DEVICE_GENERIC_TRANSFER_FLAG_DATA_COMPLETE } USB_DEVICE_GENERIC_TRANSFER_FLAG; Description USB device generic function driver transfer flags. Members Members Description USB_DEVICE_GENERIC_TRANSFER_FLAG_NONE Transfer flag that specifies no special request USB_DEVICE_GENERIC_TRANSFER_FLAG_DATA_COMPLETE Transfer flag that specifies the generic driver to complete the transfer Remarks Also see, USB_DEVICE_GENERIC_EndpointWrite 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4128 5.9.5.6.2.11 USB_DEVICE_GENERIC_TRANSFER_HANDLE Type C typedef uintptr_t USB_DEVICE_GENERIC_TRANSFER_HANDLE; Description Generic driver transfer handle. Remarks Also see, USB_DEVICE_GENERIC_EndpointRead USB_DEVICE_GENERIC_EndpointWrite 5.9.5.7 Files Files Name Description usb_device_generic.h Generic USB device function driver header Description 5.9.5.7.1 usb_device_generic.h Generic USB device function driver header file Generic USB device function driver header file Enumerations Name Description USB_DEVICE_GENERIC_EVENT This is type USB_DEVICE_GENERIC_EVENT. USB_DEVICE_GENERIC_RESULT The enumerated data-type that idnetifies the possible result of an operation. USB_DEVICE_GENERIC_TRANSFER_FLAG Enumerated data-type that identifies the USB device generic function driver's transfer flag. Functions Name Description USB_DEVICE_GENERIC_EndpointIsEnabled This function returns true if the requested endpoint is enabled. USB_DEVICE_GENERIC_EndpointRead Reads data received from host on the requested endpoint. USB_DEVICE_GENERIC_EndpointStall This function stalls the requested endpoint. USB_DEVICE_GENERIC_EndpointStallClear Clears STALL on the endpoint. USB_DEVICE_GENERIC_EndpointStallStatusGet USB Generic function driver library function that returns true if STALL is enabled on the endpoint. USB_DEVICE_GENERIC_EndpointWrite This function allows the application client to transfer data from device to host on the requested endpoint. USB_DEVICE_GENERIC_EventHandlerSet This function allows the application client to register event handler callback with the generic function driver library. 5.9 USB Library Help MPLAB Harmony Help USB Generic Device Library 5-4129 Structures Name Description USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSFER_SETUP_REQUEST The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_DATA_CONTR OL_TRANSFER_SETUP _REQUEST event. USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_COMPLETE The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_ENDPOINT_R EAD_COMPLETE event. USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_COMPLETE The data-type that holds the event data associated with USB_DEVICE_GENERIC _EVENT_ENDPOINT_W RITE_COMPLETE event. Types Name Description USB_DEVICE_GENERIC_EVENT_HANDLER The data-type that defines the signature of the event callback function. USB_DEVICE_GENERIC_EVENT_RESPONSE The return type of the application callback function. USB_DEVICE_GENERIC_INDEX Data-type for USB device generic driver index. USB_DEVICE_GENERIC_TRANSFER_HANDLE Data-type of the generic driver transfer handle. Unions Name Description USB_DEVICE_GENERIC_EVENT_DATA Union that holds event data for different generic driver events. File Name usb_device_generic.h Company Microchip Technology Inc. 5.9.6 USB HID Device Library 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4130 5.9.6.1 Introduction Introduces the MPLAB Harmony USB Device HID Library Description This library provides a high-level abstraction of the Human Interface Devices (HID) class under the Universal Serial Bus (USB) communication with a convenient C language interface. This library supports revision 1.11 of the USB HID specification release by the USB Implementers forum. This library is part of the MPLAB Harmony USB Device stack. USB Human Interface Devices class (or USB HID) supports class of devices that are used by humans to control the operation of computer systems. The HID class of devices include a wide variety of human interface, data indicator, data feedback devices with various types of outputs directed to the end user. Some common examples of HID class devices include: • Keyboards • Pointing devices such as standard mouse, joysticks, trackballs • Front-panel controls like knobs, switches, buttons, sliders • Controls found on telephony, gaming or simulation devices like steering wheels, rudder pedals, dial pads • Data devices such as bar-code scanners, thermometers, analyzers The USB Device HID library ( also referred to as HID function driver in this document) offers services to the application to interact and respond to the host requests. Additional information about the HID class can be obtained from the HID specification available www.usbif.org. 5.9.6.2 Release Notes MPLAB Harmony Version: v0.70b USB HID Device Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.9.6.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4131 paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.6.4 Library Architecture 5.9.6.4.1 Architecture Overview Provides an Architectural Overview of the HID Function Driver Description The HID Function Driver offers services to a USB HID device to communicate with the host by abstracting the HID specification details. It must be used along with the USB Device layer and USB controller to communicate with the USB host. Figure 1 shows a block diagram representation of the MPLAB Harmony USB Architecture and where the USB HID Function Driver is placed. Figure 1: USB HID Function Driver The HID function driver together with USB Device layer and USB controller driver forms the basic library entity through which a HID device can communicate with the USB host. The USB controller driver takes the responsibility of managing the USB peripheral on the device. The USB device layer handles the device enumeration etc. The USB Device layer forwards all HID specific control transfers to the HID Function Driver. The HID Function Driver interprets the control transfers and requests application's intervention through event handlers and well defined set of API. The application must register a event handler with the HID function driver in the Device Layer Set Configuration Event. While the application must respond to the HID function driver events, it can do this either in the event handler or out of it. The application interacts with HID Function Driver routines to send and receive HID reports over the USB. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4132 Figure 2 : Architecture of the HID function driver. Figure 2 shows the architecture of the HID function Driver. The function driver maintains the state of each instance. It receives HID class specific control transfers from the Device Layer. Class specific control transfers that require application response are forwarded to the application as function driver events. Depending on the type of device, the HID function driver can use the control endpoint and/or interrupt endpoints for data transfers. The HID device exchanges data with host through data objects called reports. The report data format is described by the HID report descriptor which is provided to the host when requested. Refer to the HID specification available www.usb.org for more details on the USB HID device class and how reports descriptors can be created. The HID function driver allows report descriptors to be specified for every instance. This allow the application to implement a composite HID device. 5.9.6.5 Using the Library 5.9.6.5.1 Files to Include Describes which files to include in project while using the HID Function Driver Description Table 1 shows the files that must be included in the project in order to use the HID Function Driver. These files are located in the 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4133 framework folder of the MPLAB Harmony installation. It is assumed that the Device Layer files ( and the files needed by the Device Layer) are already included in the project. Filename Description \framework\usb\src\dynamic\usb_device_hid.c Contains the HID Control Interface and Data Interface management routines \framework\usb\usb_device_hid.h Must included in every source file that needs to invoke HID function driver API. system_config.h User created file which contains the HID function driver configuration. Table 1: Files to be included in USB CDC Device Project. 5.9.6.5.2 Library Configuration Describes how to configure the HID Function Driver Description The following configuration parameters must be defined while using the HID Function Driver. The configuration macros that implement these parameters must be located in the system_config.h file in the application project and a compiler include path (to point to the folder that contains this file) should be specified. Configuration Macro Name Description Comments USB_DEVICE_HID_MAX_INSTANCES Number of HID Function Driver Instances in the application This macro defines the number of instances of the HID Function Driver. For example, if the application needs to implement two instances of the HID Function Driver (for example to create a mouse + keyboard device) on one USB Device, the macro USB_DEVICE_HID_INSTANCES_NUMBER should be set to 2. Note that implementing a USB Device that features multiple HID interfaces requires appropriate USB configuration descriptors. USB_DEVICE_HID_QUEUE_SIZE HID Function Driver Buffer Queue Combined size This macro defines the number of entries in all queues in all instances of the HID function driver. This value can be obtained by adding up the read and write queue sizes of each HID Function driver instance. In a simple single instance USB HID device application, that does not require buffer queuing , the USB_DEVICE_HID_QUEUE_DEPTH_COMBINED macro can be set to 2. Consider a case with two HIDfunction driver instances, CDC 1 has a read queue size of 2 and write queue size of 3, HID 2 has a read queue size of 4 and write queue size of 1, this macro should be set to 10 (2 +3 + 4 + 1). 5.9.6.5.3 Library Initialization Describes how the HID Function Driver is initialized. Description The HID function driver instance for a USB device configuration is initialized by the Device Layer when the configuration is set by the host. This process does not require application intervention. Each instance of the HID function driver should be registered with the Device layer through the Device Layer Function Driver Registration Table. The HID function driver requires a initialization data structure that contains details about the report descriptor associated with the specific instance of the HID function driver. The hidFuncDriver object is a global object provided by the HID function driver and points to the HID function driver - Device Layer interface functions which are required by the Device Layer. The code snippet below shows an example of how a HID function driver instance (implementing a USB HID Mouse) can be registered with the Device Layer. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4134 /* This code snippet shows an example of registering a HID function driver * with the Device Layer. While registering the function driver, an initialization * data structure must be specified. In this example, hidInit is the HID function * driver initialization data structure. */ /* This hid_rpt01 report descriptor describes a 3 button 2 * axis mouse pointing device */ const uint8_t hid_rpt01[]= { 0x06, 0x00, 0xFF, // Usage Page = 0xFF00 (Vendor Defined Page 1) 0x09, 0x01, // Usage (Vendor Usage 1) 0xA1, 0x01, // Collection (Application) 0x19, 0x01, // Usage Minimum 0x29, 0x40, // Usage Maximum //64 input usages total (0x01 to 0x40) 0x15, 0x01, // Logical Minimum (data bytes in the report may have minimum value = 0x00) 0x25, 0x40, // Logical Maximum (data bytes in the report may have maximum value = 0x00FF = unsigned 255) 0x75, 0x08, // Report Size: 8-bit field size 0x95, 0x40, // Report Count: Make sixty-four 8-bit fields (the next time the parser hits an "Input", "Output", or "Feature" item) 0x81, 0x00, // Input (Data, Array, Abs): Instantiates input packet fields based on the above report size, count, logical min/max, and usage. 0x19, 0x01, // Usage Minimum 0x29, 0x40, // Usage Maximum //64 output usages total (0x01 to 0x40) 0x91, 0x00, // Output (Data, Array, Abs): Instantiates output packet fields. Uses same report size and count as "Input" fields, since nothing // new or different was specified to the parser since the "Input" item. 0xC0 // End Collection }; /* HID Function Driver Initialization data structure. This * contains the size of the report descriptor and a pointer * to the report descriptor. If there are multiple HID instances * each with different report descriptors, then multiple such data * structures may be needed */ USB_DEVICE_HID_INITIALIZATION hidInit = { sizeof(hid_rpt01), (uint8_t *)&hid_rpt01 }; /* The HID function driver instance is now registered with * device layer through the function driver registration * table. */ const USB_DEVICE_FUNC_REGISTRATION_TABLE funcRegistrationTable[1] = { { .speed = USB_SPEED_FULL|USB_SPEED_HIGH, // Supported speed .configurationValue = 1, // To be initialized for Configuration 1 .interfaceNumber = 0, // Starting interface number .numberOfInterfaces = 1, // Number of Interfaces .funcDriverIndex = 0, // Function Driver instance index is 0 .funcDriverInit = &hidInit, // Function Driver Initialization .driver = &hidFuncDriver // Pointer to the function driver - Device Layer Interface functions } }; 5.9.6.5.4 Event Handling Describes HID function driver event handler registration and event handling. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4135 Description Registering a HID Function Driver Event Handler: While creating USB HID Device based application, an event handler must be registered with the Device Layer (the Device Layer Event Handler) and every HID function driver instance (HID Function Driver Event Handler). The HID function driver event handler receives HID events. This event handler should be registered before the USB device layer acknowledges the SET CONFIGURATION request from the USB Host. In order to ensure this, the event handler should be set in the USB_DEVICE_EVENT_CONFIGURED event that is generated by the device layer. While registering the HID function driver event handler, the HID function driver allows the application to also pass a data object in the event handler register function. This data object gets associated with the instance of the HID function driver and is returned by the HID function driver when a HID function driver event occurs. The code example below shows an example of how this can be done. /* This a sample Application Device Layer Event Handler * Note how the HID Function Driver event handler APP_USBDeviceHIDEventHandler() * is registered in the USB_DEVICE_EVENT_CONFIGURED event. The appData * object that is passed in the USB_DEVICE_HID_EventHandlerSet() * function will be returned as the userData parameter in the * when the APP_USBDeviceHIDEventHandler() function is invoked */ void APP_USBDeviceEventCallBack ( USB_DEVICE_EVENT event, USB_DEVICE_EVENT_DATA * eventData ) { switch ( event ) { case USB_DEVICE_EVENT_RESET: case USB_DEVICE_EVENT_DECONFIGURED: // USB device is reset or device is deconfigured. // This means that USB device layer is about to deininitialize // all function drivers. break; case USB_DEVICE_EVENT_CONFIGURED: /* check the configuration */ if ( eventData->eventConfigured.configurationValue == 1) { /* Register the HID Device application event handler here. * Note how the appData object pointer is passed as the * user data */ USB_DEVICE_HID_EventHandlerSet(USB_DEVICE_HID_INDEX_0, APP_USBDeviceHIDEventHandler, (uintptr_t)&appData); /* mark that set configuration is complete */ appData.isConfigured = true; } break; case USB_DEVICE_EVENT_SUSPENDED: break; case USB_DEVICE_EVENT_RESUMED: case USB_DEVICE_EVENT_ATTACHED: case USB_DEVICE_EVENT_DETACHED: case USB_DEVICE_EVENT_ERROR: default: break; } 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4136 } HID Function Driver Events: The HID Function Driver generates events that the application must respond to. Some of these events are control requests communicated through control transfers. The application must therefore complete the control transfer. Based on the generated event, the application may be required to: • Respond with a USB_DEVICE_ControlSend() function which completes the data stage of a Control Read Transfer. • Respond with a USB_DEVICE_ControlReceive() function which provisions the data stage of a Control Write Transfer. • Respond with a USB_DEVICE_ControlStatus() function which completes the handshake stage of the Control Transfer. The application can either STALL or Acknowledge the handshake stage via the USB_DEVICE_ControlStatus() function. • Analyze the pData member of the event handler and check for event specific data. The possible HID Function Driver events are described here along with the required application response, event specific data and likely follow up function driver event: 1. USB_DEVICE_HID_EVENT_CONTROL_GET_REPORT Application Response: This event is generated when the HID host is requesting for a report over the control interface. The application must provide the report by calling the USB_DEVICE_ControlSend() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_ControlSend() function. The application can use the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command. Event Specific Data (eventData): The getReport member of the eventData data structure will contain the details about the requested report. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. This indicates that the data was sent to the host successfully. The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with the USB_DEVICE_CONTROL_STATUS_SEND_ZLP flag. 2. USB_DEVICE_HID_EVENT_CONTROL_SET_REPORT Application Response: This event is generated when the HID host wants to send a report over the control interface. The application must provide a buffer to receive the report by calling the USB_DEVICE_ControlReceive() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_ControlReceive() function. The application can use the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event to track completion of the command. Event Specific Data (eventData): The setReport member of the eventData data structure will contain the details about the report that the host intends to send. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event. This indicates that the data was received successfully. The application must either acknowledge or stall the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP or USB_DEVICE_CONTROL_STATUS_STALL flag respectively. 3. USB_DEVICE_HID_EVENT_CONTROL_GET_IDLE Application Response: This event is generated when the HID host wants to read the current idle rate for the specified report. The application must provide the idle rate through the USB_DEVICE_ControlSend() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_ControlSend() function. The application can use the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4137 Event Specific Data (eventData): The getIdle member of the eventData data structure will contain the details about the report for which the idle rate is requested. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. This indicates that the data was sent to the host successfully. The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with the USB_DEVICE_CONTROL_STATUS_SEND_ZLP flag. 4. USB_DEVICE_HID_EVENT_CONTROL_SET_IDLE Application Response: This event is generated when the HID host sends a Set Idle request to the device . The application must inspect the eventData and determine if the idle rate is to be supported. The application must either acknowledge (if the idle rate is supported) or stall the handshake stage of the control transfer (if the idle rate is not supported) by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP or USB_DEVICE_CONTROL_STATUS_STALL flag respectively. Event Specific Data (eventData): The setIdle member of the eventData data structure will contain the details about the report for which the idle rate should be set and the idle duration. Likely Follow-up event: None. 5. USB_DEVICE_HID_EVENT_CONTROL_SET_PROTOCOL Application Response: This event is generated when the HID host sends a Set Protocol request to the device . The application must inspect the eventData and determine if the protocol is to be supported. The application must either acknowledge (if the protocol is supported) or stall the handshake stage of the control transfer (if the protocol is not supported) by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP or USB_DEVICE_CONTROL_STATUS_STALL flag respectively. Event Specific Data (eventData): The setProtocol member of the eventData data structure will contain the details about the protocol to switch to. Likely Follow-up event: None. 6. USB_DEVICE_HID_EVENT_CONTROL_GET_PROTOCOL Application Response: This event is generated when the HID host issues a Get Protocol Request. The application must provide the current protocol through the USB_DEVICE_ControlSend() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_ControlSend() function. The application can use the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event to track completion of the command. Event Specific Data (eventData): None. Likely Follow-up event: This event will likely be followed by the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT event. This indicates that the data was sent to the host successfully. The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with the USB_DEVICE_CONTROL_STATUS_SEND_ZLP flag. 7. USB_DEVICE_HID_EVENT_CONTROL_SET_DESCRIPTOR Application Response: This event is generated when the HID host issues a Set Descriptor request. The application must provide a buffer to receive the descriptor through the USB_DEVICE_ControlReceive() function either in the event handler or in the application (outside of the event handler function). The application must use the controlTransferHandle parameter provided in the event while calling USB_DEVICE_ControlReceive() function. The application can use the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event to track completion of the command. Event Specific Data: None 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4138 Likely Follow-up event: This event will likely be followed by the USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED event. This indicates that the data was received successfully. The application must either acknowledge or stall the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP or USB_DEVICE_CONTROL_STATUS_STALL flag respectively. 8. USB_DEVICE_HID_EVENT_REPORT_SENT Application Response: This event occurs when a report send operation scheduled by calling the USB_DEVICE_HID_ReportSend() function has completed. This event does not require the application to respond with any function calls.. Event Specific Data (pData): The reportSent member of the eventData data structure will contains details about the report send operation. Likely Follow-up event: None. 9. USB_DEVICE_HID_EVENT_REPORT_RECEIVED Application Response: This event occurs when a report receive operation scheduled by calling the USB_DEVICE_HID_ReportReceive() function has completed. This event does not require the application to respond with any function calls.. Event Specific Data (pData): The reportReceived member of the eventData data structure will contains details about the report receive operation. Likely Follow-up event: None 10. USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT Application Response: This event occurs when the data stage of a control read transfer has completed in response to the USB_DEVICE_ControlSend() function. The application must acknowledge the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP flag. Event Specific Data (pData): None. Likely Follow-up event: None. 11. USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED Application Response: This event occurs when the data stage of a control write transfer has completed in response to the USB_DEVICE_ControlReceive() function. The application must either acknowledge or stall the handshake stage of the control transfer by calling USB_DEVICE_ControlStatus() function with USB_DEVICE_CONTROL_STATUS_SEND_ZLP or USB_DEVICE_CONTROL_STATUS_STALL flag respectively. Event Specific Data (pData): None Likely Follow-up event: None. 12. USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED Application Response: This event occurs when the a control transfer request is aborted by the host. The application can use this event to update its HID class specific control transfer state machine. Event Specific Data (pData): None Likely Follow-up event: None. 5.9.6.5.5 Sending a Report Describes how to send a report. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4139 Description The USB HID device sends data to the HID host as reports. The HID device application should use the USB_DEVICE_HID_ReportSend() function to send the report. This function returns a transfer handler that allows the application to track the read request. The request is completed when the host as requested for the data. A report send request could fail if the function driver instance transfer queue is full. The completion of the write transfer is indicated by USB_DEVICE_HID_EVENT_REPORT_SENT event. The transfer handle and the amount of data sent is returned in the reportSent member of the eventData data structure along with the event. The following code snippet shows an example of how USB HID Mouse application sends a report to the host. /* In this code example, the application uses the * USB_HID_MOUSE_ReportCreate to create the mouse report * and then uses the USB_DEVICE_HID_ReportSend() function * to send the report */ USB_HID_MOUSE_ReportCreate(appData.xCoordinate, appData.yCoordinate, appData.mouseButton, &appData.mouseReport); /* Send the mouse report. */ USB_DEVICE_HID_ReportSend(appData.hidInstance, &appData.reportTransferHandle, (uint8_t*)&appData.mouseReport, sizeof(USB_HID_MOUSE_REPORT)); 5.9.6.5.6 Receiving a Report Describes how to receive a report Description The application can receive a report from the host by using the USB_DEVICE_HID_ReportReceive() function. This function returns a transfer handler that allows the application to track the read request. The request is completed when the host sends the report. The application must make sure that it allocates a buffer size that is at least the size of the report. The return value of the function indicates the success of the request. A read request could fail if the function driver transfer queue is full. The completion of the read transfer is USB_DEVICE_HID_EVENT_REPORT_RECEIVED event. The reportReceived member of the eventData data structure contains details about the received report. The following code snippet shows an example of how a USB HID Keyboard can schedule a receive report operation to get the keyboard LED status. /* The following code snippet shows how the * USB HID Keyboard application schedules a * receive report operation to receive the * keyboard output report from the host. This * report contains the keyboard LED status. The * size of the report is 1 byte */ result = USB_DEVICE_HID_ReportReceive(appData.hidInstance, &appData.receiveTransferHandle, (uint8_t *)&appData.keyboardOutputReport,1); if(USB_DEVICE_HID_RESULT_OK != result) { /* Do error handling here */ } 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4140 5.9.6.6 Library Interface Data Types and Constants Name Description USB_DEVICE_HID_CONTROL_STATUS USB Device HID Function Driver Control Transfer Status USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE USB Device HID Function Driver Control Transfer Handle USB_DEVICE_HID_EVENT USB Device HID Function Driver Events USB_DEVICE_HID_EVENT_DATA_GET_IDLE USB Device HID Get Idle Event Data Type. USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL USB Device HID Get Protocol Event Data Type. USB_DEVICE_HID_EVENT_DATA_GET_REPORT USB Device HID Get Report Event Data Type. USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED USB Device HID Report Received Event Data Type. USB_DEVICE_HID_EVENT_DATA_REPORT_SENT USB Device HID Report Sent Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR USB Device HID Set Descriptor Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_IDLE USB Device HID Set Idle Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL USB Device HID Set Protocol Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_REPORT USB Device HID Set Report Event Data Type. USB_DEVICE_HID_EVENT_HANDLER USB Device HID Event Handler Function Pointer Type. USB_DEVICE_HID_EVENT_RESPONSE USB Device HID Function Driver Event Callback Response Type USB_DEVICE_HID_INDEX USB device HID Function Driver Index. USB_DEVICE_HID_INIT USB Device HID Function Driver Initialization Data Structure USB_DEVICE_HID_RESULT USB Device HID Function Driver USB Device HID Result enumeration. USB_DEVICE_HID_TRANSFER_HANDLE USB Device HID Function Driver Transfer Handle Definition. USB_DEVICE_HID_EVENT_RESPONSE_NONE USB Device HID Function Driver Event Handler Response Type None. USB_DEVICE_HID_INSTANCES_NUMBER Specifies the number of HID instances. USB_DEVICE_HID_QUEUE_DEPTH_COMINED DOM-IGONORE-BEGIN USB_DEVICE_HID_TRANSFER_HANDLE_INVALID USB Device HID Function Driver Invalid Transfer Handle Definition. Functions Name Description USB_DEVICE_HID_ControlReceive This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_HID_ControlSend This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_HID_ControlStatus This function allows the application to complete the status stage of the the HID Function Driver specific control transfer request. USB_DEVICE_HID_EventHandlerSet This function registers a event handler for the specified HID function driver instance. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4141 USB_DEVICE_HID_ReportReceive This function submits the buffer to HID function driver library to receive a report from host to device. USB_DEVICE_HID_ReportSend This function submits the buffer to HID function driver library to send a report from device to host. Description This section describes the Application Programming Interface (API) functions of the USB Device HID library. Refer to each section for a detailed description. 5.9.6.6.1 Functions 5.9.6.6.1.1 USB_DEVICE_HID_ControlReceive Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_ControlReceive( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); Description This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. For example, the USB_DEVICE_HID_EVENT_DATA_SET_REPORT event requires a control transfer response. The function can be called in the HID Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the data buffer out of the event handler context, especially if the data buffer to receive the daya is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a HID function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device HID Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data buffer to receive the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_HID_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_HID_RESULT_OK - The request was successful. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4142 Example // ------------------------------------------------------------------ // In this example, the application responds to the SET REPORT command with // in the event handler. The application uses the // USB_DEVICE_HID_ControlReceive() function to do this. // ------------------------------------------------------------------ USB_DEVICE_HID_EVENT_DATA_SET_REPORT * setReportEventData; USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle; uint8_t someReport[128]; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_SET_REPORT: // In this case, the application should receive the report // data from the host. The application must use the // USB_DEVICE_HID_ControlReceive() function to receive the data. setReportEventData = (USB_DEVICE_HID_EVENT_DATA_SET_REPORT *) pData; USB_DEVICE_HID_ControlReceive(instanceIndex, controlTransferHandle someReport, setReportEventData->reportSize); break; } } // -------------------------------------------------------------------- // In this example, the application defers the response to the // event. This is done by calling the USB_DEVICE_HID_ControlReceive() // function out side the event handler. // -------------------------------------------------------------------- USB_DEVICE_HID_EVENT_DATA_SET_REPORT setReportEventData; USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE thisControlTransferHandle; bool receiveReportFromHost; uint8_t * someReport; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_SET_LINE_CODING: // In this case, the application should send the line coding // data to the host. The application must responds to the // event outside the event handler because the data buffer is // not available. setReportEventData = (USB_DEVICE_HID_EVENT_DATA_GET_REPORT *)pData; 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4143 thisControlTransferHandle = controlTransferHandle; receiveReportFromHost = true; break; } } // This is outside the event handler. if(receiveReportFromHost) { // The application allocates a buffer using an arbitrary function setReport = AllocateMemoryBuffer(); USB_DEVICE_HID_ControlReceive(instanceIndex, thisControlTransferHandle setReport, setReportEventData->reportSize); } 5.9.6.6.1.2 USB_DEVICE_HID_ControlSend Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_ControlSend( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * data, size_t size ); Description This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. For example, the USB_DEVICE_HID_EVENT_DATA_REPORT_SENT event requires a control transfer response. The function can be called in the HID Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to prepare the response data out of the event handler context, especially if the data is not readily available. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. Preconditions This function should only be called in response to a HID function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device HID Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. data Data that represents the data stage of the control transfer. size size (in bytes) of the data to sent. Returns USB_DEVICE_HID_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB host cancelled the control transfer. USB_DEVICE_HID_RESULT_OK - The request was successful. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4144 Example // ------------------------------------------------------------------ // In this example, the application responds to the GET REPORT // with in the event handler. The application uses the // USB_DEVICE_HID_ControlSend() function to do this. // ------------------------------------------------------------------ USB_DEVICE_HID_EVENT_DATA_GET_REPORT * getReportEventData; USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle; uint8_t someReport[128]; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_GET_REPORT: // In this case, the application should send the report // to the host. The application must use the // USB_DEVICE_HID_ControlSend() function to send the data. getReportEventData = (USB_DEVICE_HID_EVENT_DATA_GET_REPORT *)pData; USB_DEVICE_HID_ControlSend(instanceIndex, controlTransferHandle someReport, getReportEventData->reportSize); break; } } // -------------------------------------------------------------------- // In this example, the application defers the response to the // event. This is done by calling the USB_DEVICE_HID_ControlSend() // function out side the event handler. // -------------------------------------------------------------------- USB_DEVICE_HID_EVENT_DATA_GET_REPORT * getReportEventData; USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle; uint8_t someReport[128]; bool sendReportToHost; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_GET_REPORT: // In this case, the application should send the report // data to the host. The application does not call this function // in the event handler, because it does not have the report // data ready. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4145 getReportEventData = (USB_DEVICE_HID_EVENT_DATA_GET_REPORT *)pData; thisControlTransferHandle = controlTransferHandle; sendReportToHost = true; break; } } // This is outside the event handler. if(sendReportToHost) { // The application fetches the report coding from the // an EEPROM. GetReportFromEEPROM(someReport); USB_DEVICE_HID_ControlSend(instanceIndex, controlTransferHandle someReport, getReportEventData->reportSize); } 5.9.6.6.1.3 USB_DEVICE_HID_ControlStatus Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_ControlStatus( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS status ); Description This function allows the application to complete the status stage of the the HID Function Driver specific control transfer request. The application can either accept the data stage or stall it. Calling this function with status set to USB_DEVICE_HID_CONTROL_STATUS_OK will acknowledge the status stage of the control transfer. The control transfer can be stalled by setting the status parameter to USB_DEVICE_HID_CONTROL_STATUS_ERROR. The function can be called in the HID Function Driver event handler or can be called outside the event handler. Calling this function outside the event handler defers the response to the event. This allows the application to analyze the event response outside the event handler. Note however, that there are timing considerations when responding to the control transfer. Exceeding the response time will cause the host to cancel the control transfer and may cause USB host to reject the device. The application must use the control transfer handle that was generated along with the event as the controlTransferHandle. The application must be aware of events and associated control transfers that do or do not require data stages. Incorrect usage of the USB_DEVICE_HID_ControlStatus() function could cause the device function to be non-compliant. Preconditions This function should only be called in response to a HID function driver event that requires a control transfer response. Parameters Parameters Description instance USB Device HID Function Driver instance. controlTransferHandle Control Transfer handle for the control transfer. status Set to USB_DEVICE_HID_CONTROL_STATUS_OK to acknowledge the control transfer. Set to USB_DEVICE_HID_CONTROL_STATUS_ERROR to stall the transfer. Returns USB_DEVICE_HID_RESULT_ERROR_CONTROL_TRANSFER_FAILED - The request was not successful because the USB 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4146 host cancelled the control transfer. USB_DEVICE_HID_RESULT_OK - The request was successful. Remarks None. Example // ------------------------------------------------------------------ // In this code example, the application responds to the the // SET IDLE event in the event handler. // ------------------------------------------------------------------ USB_DEVICE_HID_EVENT_DATA_SET_IDLE * setIdleEventData; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_SET_IDLE: // The application can check if the break duration is supported. setIdleEventData = (USB_DEVICE_HID_EVENT_DATA_SET_IDLE *)pData; if(IsDurationSupported(setIdleEventData->duration)) { USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_OK); } else { // If the duration is not supported the application // can stall it. USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_ERROR); } break; ... } return(USB_DEVICE_HID_EVENT_RESPONSE_NONE); } // -------------------------------------------------------------------- // In this example, the application defers the response to the // SET IDLE event. The application responds to the event in // outside the event handler. // -------------------------------------------------------------------- USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE thisControlTransferHandle; USB_DEVICE_HID_EVENT_DATA_SET_IDLE * setIdleEventData; uint8_t duration; bool setIdleEvent; USB_DEVICE_HID_EVENT_RESPONSE USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4147 USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { switch(event) { case USB_DEVICE_HID_EVENT_SEND_BREAK: // Get the idle duration. setIdleEventData = (USB_DEVICE_HID_EVENT_DATA_SET_IDLE *)pData; duration = setIdleEventData->duration; setIdleEvent = true; break; ... } return(USB_DEVICE_HID_EVENT_RESPONSE_NONE); } // This is outside the event handler. if(setIdleEvent) { // The application checks if the duration is supported if(IsDurationSupported(setIdleEventData->duration)) { USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_OK); } else { // If the duration is not supported the application // can stall it. USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_ERROR); } } 5.9.6.6.1.4 USB_DEVICE_HID_EventHandlerSet Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_EventHandlerSet( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT_HANDLER eventHandler, uintptr_t context ); Description This function registers a event handler for the specified HID function driver instance. This function should be called by the client when it receives a SET CONFIGURATION event from the device layer. A event handler must be registered for function driver to respond to function driver specific commands. If the event handler is not registered, the device layer will stall function driver specific commands and the USB device may not function. Preconditions This function should be called when the function driver has been initialized as a result of a set configuration. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4148 Parameters Parameters Description instance Instance of the HID Function Driver. eventHandler A pointer to event handler function. context Application specific context that is returned in the event handler. Returns USB_DEVICE_HID_RESULT_OK - The operation was successful USB_DEVICE_HID_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_DEVICE_HID_RESULT_ERROR_PARAMETER_INVALID - The eventHandler parameter is NULL Remarks None. Example // This code snippet shows an example registering an event handler. Here // the application specifies the context parameter as a pointer to an // application object (appObject) that should be associated with this // instance of the HID function driver. USB_DEVICE_HID_RESULT result; USB_DEVICE_HID_EVENT_RESPONSE APP_USBDeviceHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context ) { // Event Handling comes here switch(event) { ... } return(USB_DEVICE_HID_EVENT_RESPONSE_NONE); } result = USB_DEVICE_HID_EventHandlerSet ( 0 ,&APP_EventHandler, (uintptr_t) &appObject); if(USB_DEVICE_HID_RESULT_OK != result) { SYS_ASSERT ( false , "Error while registering event handler" ); } 5.9.6.6.1.5 USB_DEVICE_HID_ReportReceive Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_ReportReceive( USB_DEVICE_HID_INDEX iHID, USB_DEVICE_HID_TRANSFER_HANDLE * handle, void * buffer, size_t size ); Description This function submits the buffer to HID function driver library to receive a report from host to device. On completion of the 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4149 transfer the library generates USB_DEVICE_HID_EVENT_REPORT_RECEIVED event to the application. A handle to the request is passed in the transferHandle parameter. The transfer handle expires when event handler for the USB_DEVICE_HID_EVENT_REPORT_RECEIVED exits. If the receive request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_HID_TRANSFER_HANDLE_INVALID. Preconditions USB device layer must be initialized. Parameters Parameters Description iHID HID instance index. transferHandle HID transfer handle. buffer Pointer to buffer where the received report has to be received stored. size Buffer size. Returns USB_DEVICE_HID_RESULT_OK - The receive request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_HID_RESULT_ERROR_TRANSFER_QUEUE_FULL - internal request queue is full. The receive request could not be added. USB_DEVICE_HID_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_HID_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid. Remarks None. Example USB_DEVICE_HID_TRANSFER_HANDLE hidTransferHandle; USB_DEVICE_HID_RESULT result; // Register APP_HIDEventHandler function USB_DEVICE_HID_EventHandlerSet( USB_DEVICE_HID_INDEX_0 , APP_HIDEventHandler ); // Prepare report and request HID to send the report. result = USB_DEVICE_HID_ReportReceive( USB_DEVICE_HID_INDEX_0, &hidTransferHandle , &appReport[0], sizeof(appReport)); if( result != USB_DEVICE_HID_RESULT_OK) { //Handle error. } //Implementation of APP_HIDEventHandler USB_DEVICE_HIDE_EVENT_RESPONSE APP_HIDEventHandler { USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context } { USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED reportReceivedEventData; 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4150 // Handle HID events here. switch (event) { case USB_DEVICE_HID_EVENT_REPORT_RECEIVED: if( (reportReceivedEventData->reportSize == sizeof(appReport) && reportReceivedEventData->report == &appReport[0]) { // Previous transfer was complete. } break; .... } } 5.9.6.6.1.6 USB_DEVICE_HID_ReportSend Function C USB_DEVICE_HID_RESULT USB_DEVICE_HID_ReportSend( USB_DEVICE_HID_INDEX iHID, USB_DEVICE_HID_TRANSFER_HANDLE * handle, void * buffer, size_t size ); Description This function places a request to send a HID report with the USB Device HID Function Driver Layer. The function places a requests with driver, the request will get serviced when report is requested by the USB Host. A handle to the request is returned in the transferHandle parameter. The termination of the request is indicated by the USB_DEVICE_HID_EVENT_REPORT_SENT event. The amount of data sent, a pointer to the report and the transfer handle associated with the request is returned along with the event in the pData parameter of the event handler. The transfer handle expires when event handler for the USB_DEVICE_HID_EVENT_REPORT_SENT exits. If the send request could not be accepted, the function returns an error code and transferHandle will contain the value USB_DEVICE_HID_TRANSFER_HANDLE_INVALID. Preconditions USB device layer must be initialized. Parameters Parameters Description instance USB Device HID Function Driver instance. transferHandle Pointer to a USB_DEVICE_HID_TRANSFER_HANDLE type of variable. This variable will contain the transfer handle in case the send request was successful. data pointer to the data buffer containing the report to be sent. size Size (in bytes) of the report to be sent. Returns USB_DEVICE_HID_RESULT_OK - The send request was successful. transferHandle contains a valid transfer handle. USB_DEVICE_HID_RESULT_ERROR_TRANSFER_QUEUE_FULL - Internal request queue is full. The send request could not be added. USB_DEVICE_HID_RESULT_ERROR_INSTANCE_NOT_CONFIGURED - The specified instance is not configured yet. USB_DEVICE_HID_RESULT_ERROR_INSTANCE_INVALID - The specified instance was not provisioned in the application and is invalid. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4151 Example USB_DEVICE_HID_TRANSFER_HANDLE hidTransferHandle; USB_DEVICE_HID_RESULT result; // Register APP_HIDEventHandler function USB_DEVICE_HID_EventHandlerSet( USB_DEVICE_HID_INDEX_0 , APP_HIDEventHandler ); // Prepare report and request HID to send the report. result = USB_DEVICE_HID_ReportSend( USB_DEVICE_HID_INDEX_0, &hidTransferHandle , &appReport[0], sizeof(appReport)); if( result != USB_DEVICE_HID_RESULT_OK) { //Handle error. } //Implementation of APP_HIDEventHandler USB_DEVICE_HIDE_EVENT_RESPONSE APP_HIDEventHandler { USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context } { USB_DEVICE_HID_EVENT_DATA_REPORT_SENT * reportSentEventData; // Handle HID events here. switch (event) { case USB_DEVICE_HID_EVENT_REPORT_SENT: reportSentEventData = (USB_DEVICE_HID_EVENT_REPORT_SENT *)pData; if(reportSentEventData->reportSize == sizeof(appReport)) { // The report was sent completely. } break; .... } return(USB_DEVICE_HID_EVENT_RESPONSE_NONE); } 5.9.6.6.2 Data Types and Constants 5.9.6.6.2.1 USB_DEVICE_HID_CONTROL_STATUS Enumeration C typedef enum { USB_DEVICE_HID_CONTROL_STATUS_OK, USB_DEVICE_HID_CONTROL_STATUS_ERROR } USB_DEVICE_HID_CONTROL_STATUS; Description USB Device HID Function Driver Control Transfer Status 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4152 This flag is used along with the USB_DEVICE_HID_ControlStatus() function to indicate success or failure of a HID class specific control transfer request. Members Members Description USB_DEVICE_HID_CONTROL_STATUS_OK The application must use this flag when the data received through the USB_DEVICE_HID_ControlReceive() function was accepted. Using this flag causes the status stage of the associated control transfer to be completed. USB_DEVICE_HID_CONTROL_STATUS_ERROR The application must use this flag when the control request was not supported or the data received using the USB_DEVICE_HID_ControlReceive() function was not accepted. Using this flag causes the status stage of the associated control transfer to be stalled. Remarks None. 5.9.6.6.2.2 USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE Type C typedef USB_DEVICE_CONTROL_TRANSFER_HANDLE USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE; Description USB Device HID Function Driver Control Transfer Handle This is returned by the HID function driver event handler and should be used by the application while responding to HID function driver control transfer requests. Remarks None. 5.9.6.6.2.3 USB_DEVICE_HID_EVENT Enumeration C typedef enum { USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED, USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT, USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED, USB_DEVICE_HID_EVENT_GET_REPORT, USB_DEVICE_HID_EVENT_GET_IDLE, USB_DEVICE_HID_EVENT_GET_PROTOCOL, USB_DEVICE_HID_EVENT_SET_REPORT, USB_DEVICE_HID_EVENT_SET_IDLE, USB_DEVICE_HID_EVENT_SET_PROTOCOL, USB_DEVICE_HID_EVENT_SET_DESCRIPTOR, USB_DEVICE_HID_EVENT_REPORT_SENT, USB_DEVICE_HID_EVENT_REPORT_RECEIVED } USB_DEVICE_HID_EVENT; Description USB Device HID Function Driver Events These events are specific to the USB Device HID Function Driver instance. Each event description contains details about the parameters passed with event. The contents of pData depends on the generated event. Events that are associated with the HID Function Driver Specific Control Transfers require application response and will be 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4153 generated along with a HID Control Transfer Handle. This allows the application to respond to the HID function driver control transfer requests. The application should respond to these events by using the USB_DEVICE_HID_ControlReceive(), USB_DEVICE_HID_ControlSend() and USB_DEVICE_HID_ControlStatus() functions. Calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR will stall the control transfer request. The application would do this if the control transfer request is not supported. Calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_OK will complete the status stage of the control transfer request. The application would do this if the control transfer request is supported The following code snippet shows an example of a possible event handling scheme. // This code example shows all HID Function Driver events and a possible // scheme for handling these events. In this example event responses are not // deferred. USB_DEVICE_HID_EVENT_RESPONSE USB_AppHIDEventHandler ( USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t userData ) { USB_DEVICE_HID_EVENT_DATA_GET_REPORT * getReportEventData; USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL currentProtocol; USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL * setProtocolEventData; USB_DEVICE_HID_EVENT_DATA_SET_IDLE * setIdleEventData; USB_DEVICE_HID_EVENT_DATA_GET_IDLE * getIdleEventData; USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR * setDescriptorEventData; USB_DEVICE_HID_EVENT_DATA USB_DEVICE_HID_EVENT_DATA_SET_REPORT * setReportEventData; uint8_t idleRate; uint8_t someHIDReport[128]; uint8_t someHIDDescriptor[128]; switch(event) { case USB_DEVICE_HID_EVENT_GET_REPORT: // In this case, pData should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_GET_REPORT pointer. The application // must send the requested report by using the // USB_DEVICE_HID_ControlSend() function. getReportEventData = (USB_DEVICE_HID_EVENT_DATA_GET_REPORT *)pData; USB_DEVICE_HID_ControlSend(instanceIndex, controlTransferHandle, someHIDReport, getReportEventData->reportLength); break; case USB_DEVICE_HID_EVENT_GET_PROTOCOL: // In this case, pData will be NULL. The application // must send the current protocol to the host by using // the USB_DEVICE_HID_ControlSend() function. USB_DEVICE_HID_ControlSend(instanceIndex, controlTransferHandle, ¤tProtocol, sizeof(USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL)); break; case USB_DEVICE_HID_EVENT_GET_IDLE: 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4154 // In this case, pData will be a // USB_DEVICE_HID_EVENT_DATA_GET_IDLE pointer type. The application // must send the current idle rate to the host by using // the USB_DEVICE_HID_ControlSend() function. getLineCodingData = (USB_DEVICE_HID_EVENT_DATA_GET_IDLE *) pData; USB_DEVICE_HID_ControlSend(instanceIndex, controlTransferHandle, ¤tIdleRate, 1); break; case USB_DEVICE_HID_EVENT_SET_REPORT: // In this case, pData should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_SET_REPORT type pointer. The // application can analyze the request and then obtain the // report by using the USB_DEVICE_HID_ControlReceive() function. setReportEventData = (USB_DEVICE_HID_EVENT_DATA_SET_REPORT *)pData; USB_DEVICE_HID_ControlReceive(instanceIndex, controlTransferHandle someHIDReport, setReportEventData->reportLength); break; case USB_DEVICE_HID_EVENT_SET_PROTOCOL: // In this case, pData should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL type pointer. The // application can analyze the data and decide to stall // or accept the setting. This shows an example of accepting // the protocol setting. setProtocolEventData = (USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL *)pData; USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_OK); break; case USB_DEVICE_HID_EVENT_SET_IDLE: // In this case, pData should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_SET_IDLE type pointer. The // application can analyze the data and decide to stall // or accept the setting. This shows an example of accepting // the protocol setting. setIdleEventData = (USB_DEVICE_HID_EVENT_DATA_SET_IDLE *)pData; USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_OK); break; case USB_DEVICE_HID_EVENT_SET_DESCRIPTOR: // In this case, the pData should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR type pointer. The // application can analyze the request and then obtain the // descriptor by using the USB_DEVICE_HID_ControlReceive() function. setDescriptorEventData = (USB_DEVICE_HID_EVENT_DATA_SET_REPORT *)pData; USB_DEVICE_HID_ControlReceive(instanceIndex, controlTransferHandle someHIDReport, setReportEventData->reportLength); break; case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED: 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4155 // In this case, control transfer data was received. The // application can inspect that data and then stall the // handshake stage of the control transfer or accept it // (as shown here). USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle USB_DEVICE_HID_CONTROL_STATUS_OK); break; case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT: // This means that control transfer data was sent. The // application would typically acknowledge the handshake // stage of the control transfer. USB_DEVICE_HID_ControlStatus(instanceIndex, controlTransferHandle, USB_DEVICE_HID_CONTROL_STATUS_OK); break; case USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED: // This is an indication only event. The application must // reset any HID control transfer related tasks when it receives // this event. break; case USB_DEVICE_HID_EVENT_REPORT_RECEIVED: // This means a HID report receive request has completed. // The pData member should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED pointer type. break; case USB_DEVICE_HID_EVENT_REPORT_SENT: // This means a HID report send request has completed. // The pData member should be interpreted as a // USB_DEVICE_HID_EVENT_DATA_REPORT_SENT pointer type. break; } return(USB_DEVICE_HID_EVENT_RESPONSE_NONE); } Members Members Description USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_RECEIVED This event occurs when the data stage of a control write transfer has completed. This event would occur after the application uses the USB_DEVICE_HID_ControlReceive() function to respond to a HID Function Driver Control Transfer Event that requires data to be received from the host. The pData parameter will be NULL. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4156 USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_DATA_SENT This event occurs when the data stage of a control read transfer has completed. This event would occur after the application uses the USB_DEVICE_HID_ControlSend() function to respond to a HID Function Driver Control Transfer Event that requires data to be sent to the host. The pData parameter will be NULL USB_DEVICE_HID_EVENT_CONTROL_TRANSFER_ABORTED This event occurs when an ongoing control transfer was aborted. The application must stop any remaing activities on control transfers USB_DEVICE_HID_EVENT_GET_REPORT This event occurs when the host issues a GET REPORT command. The application must interpret the pData parameter as USB_DEVICE_HID_EVENT_DATA_GET_REPORT pointer type. If the report request is supported, the application must send the report to the host by using the USB_DEVICE_HID_ControlSend() function either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_SENT event. If the report request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. USB_DEVICE_HID_EVENT_GET_IDLE This event occurs when the host issues a GET IDLE command. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_GET_IDLE pointer type. If the request is supported, the application must send the idle rate to the host by calling the USB_DEVICE_HID_ControlSend() function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_SENT event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4157 USB_DEVICE_HID_EVENT_GET_PROTOCOL This event occurs when the host issues a GET PROTOCOL command. The pData parameter will be NULL. If the request is supported, the application must send a USB_DEVICE_HID_EVENT_DATA_GET_PROTOC OL data type object, containing the current protocol, to the host by calling the USB_DEVICE_HID_ControlSend() function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_SENT event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. USB_DEVICE_HID_EVENT_SET_REPORT This event occurs when the host issues a SET REPORT command. The application must interpret the pData parameter as a USB_DEVICE_HID_EVENT_DATA_SET_REPORT pointer type. If the report request is supported, the application must provide a buffer, to recevie the report, to the host by calling the USB_DEVICE_HID_ControlReceive() function either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_RECEIVED event. If the report request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. USB_DEVICE_HID_EVENT_SET_IDLE This event occurs when the host issues a SET IDLE command. The pData parameter will be USB_DEVICE_HID_EVENT_DATA_SET_IDLE pointer type. The application can analyze the idle duration and acknowledge or reject the setting by calling the USB_DEVICE_HID_ControlStatus() function. This function can be called in the event handler or after the event handler exits. If application can reject the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. It can accept the request by calling this function with USB_DEVICE_HID_CONTROL_STATUS_OK flag. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4158 USB_DEVICE_HID_EVENT_SET_PROTOCOL This event occurs when the host issues a SET PROTOCOL command. The pData parameter will be NULL. If the request is supported, the application must provide a USB_DEVICE_HID_EVENT_DATA_SET_PROTOC OL data type object to receive the current protocol from the host by calling the USB_DEVICE_HID_ControlReceive() function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_RECEIVED event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. USB_DEVICE_HID_EVENT_SET_DESCRIPTOR This event occurs when the host issues a SET DESCRIPTOR command. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_SET_DESCRIP TOR type pointer. If the request is supported, the application must provide a buffer to receive the descriptor from the host by calling the USB_DEVICE_HID_ControlReceive() function. This function can be called either in the event handler or after the event handler routine has returned. The application can track the completion of the request by using the USB_DEVICE_HID_EVENT_CONTROL_TRANSFE R_DATA_RECEIVED event. If the request is not supported, the application must stall the request by calling the USB_DEVICE_HID_ControlStatus() function with a USB_DEVICE_HID_CONTROL_STATUS_ERROR flag. USB_DEVICE_HID_EVENT_REPORT_SENT This event indicates that USB_DEVICE_HID_ReportSend() function completed a report transfer on interrupt endpoint from host to device. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_REPORT_SENT type. USB_DEVICE_HID_EVENT_REPORT_RECEIVED This event indicates that USB_DEVICE_HID_ReportReceive() function completed a report transfer on interrupt endpoint from device to host. The pData parameter will be a USB_DEVICE_HID_EVENT_DATA_REPORT_REC EIVED type Remarks Some of the events allow the application to defer responses. This allows the application some time to obtain the response data rather than having to respond to the event immediately. Note that a USB host will typically wait for event response for a finite 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4159 time duration before timing out and cancelling the event and associated transactions. Even when deferring response, the application must respond promptly if such timeouts have to be avoided. 5.9.6.6.2.4 USB_DEVICE_HID_EVENT_DATA_GET_IDLE Structure C typedef struct { uint8_t reportID; } USB_DEVICE_HID_EVENT_DATA_GET_IDLE; Description USB Device HID Get Idle Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_SET_REPORT event. Members Members Description uint8_t reportID; Report ID of the report of which idle rate is requested. Remarks None. 5.9.6.6.2.5 USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL Structure C typedef struct { USB_HID_PROTOCOL_CODE protocol; } USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL; Description USB Device HID Get Protocol Event Data Type. This defines the data type of the data to be sent to the host in response to USB_DEVICE_HID_EVENT_GET_PROTOCOL event. The data should be sent to the host by calling the USB_DEVICE_HID_ControlSend() function. Remarks None. 5.9.6.6.2.6 USB_DEVICE_HID_EVENT_DATA_GET_REPORT Structure C typedef struct { uint8_t reportType; uint8_t reportID; uint16_t reportLength; } USB_DEVICE_HID_EVENT_DATA_GET_REPORT; Description USB Device HID Get Report Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_GET_REPORT event. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4160 Members Members Description uint8_t reportType; Report type uint8_t reportID; Report ID uint16_t reportLength; Report Length Remarks None. 5.9.6.6.2.7 USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED Structure C typedef struct { USB_DEVICE_HID_TRANSFER_HANDLE handle; size_t length; } USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED; Description USB Device HID Report Received Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_REPORT_RECEIVED event. Members Members Description USB_DEVICE_HID_TRANSFER_HANDLE handle; Transfer handle size_t length; Report size received Remarks None. 5.9.6.6.2.8 USB_DEVICE_HID_EVENT_DATA_REPORT_SENT Structure C typedef struct { USB_DEVICE_HID_TRANSFER_HANDLE handle; size_t length; } USB_DEVICE_HID_EVENT_DATA_REPORT_SENT; Description USB Device HID Report Sent Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_REPORT_SENT event. Members Members Description USB_DEVICE_HID_TRANSFER_HANDLE handle; Transfer handle size_t length; Report size transmitted 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4161 Remarks None. 5.9.6.6.2.9 USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR Structure C typedef struct { uint8_t descriptorType; uint8_t descriptorIndex; uint16_t descriptorLength; } USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR; Description USB Device HID Set Descriptor Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_SET_DESCRIPTOR event. Members Members Description uint8_t descriptorType; Descriptor Type uint8_t descriptorIndex; Descriptor Index uint16_t descriptorLength; Descriptor Length Remarks None. 5.9.6.6.2.10 USB_DEVICE_HID_EVENT_DATA_SET_IDLE Structure C typedef struct { uint8_t duration; uint8_t reportID; } USB_DEVICE_HID_EVENT_DATA_SET_IDLE; Description USB Device HID Set Idle Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_SET_IDLE event. Members Members Description uint8_t duration; Idle duration uint8_t reportID; Report ID Remarks None. 5.9.6.6.2.11 USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL Structure C typedef struct { USB_HID_PROTOCOL_CODE protocol; } USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL; 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4162 Description USB Device HID Set Protocol Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_SET_PROTOCOL event. Remarks None. 5.9.6.6.2.12 USB_DEVICE_HID_EVENT_DATA_SET_REPORT Structure C typedef struct { uint8_t reportType; uint8_t reportID; uint16_t reportLength; } USB_DEVICE_HID_EVENT_DATA_SET_REPORT; Description USB Device HID Set Report Event Data Type. This defines the data type of the data generated to the HID event handler on a USB_DEVICE_HID_EVENT_SET_REPORT event. Members Members Description uint8_t reportType; Report type uint8_t reportID; Report ID uint16_t reportLength; Report Length Remarks None. 5.9.6.6.2.13 USB_DEVICE_HID_EVENT_HANDLER Type C typedef USB_DEVICE_HID_EVENT_RESPONSE (* USB_DEVICE_HID_EVENT_HANDLER)(USB_DEVICE_HID_INDEX instanceIndex, USB_DEVICE_HID_EVENT event, USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE controlTransferHandle, void * pData, uintptr_t context); Description USB Device HID Event Handler Function Pointer Type. This data type defines the required function signature of the USB Device HID Function Driver event handling callback function. The application must register a pointer to a HID Function Driver events handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive event call backs from the HID Function Driver. The function driver will invoke this function with event relevant parameters. The description of the event handler function parameters is given here. instanceIndex - Instance index of the HID Function Driver that generated the event. event - Type of event generated. controlTransferHandle - Control Transfer Handle for HID function driver events that require application response. The application should use this handle when calling the USB HID Device Control Transfer functions to respond to the events. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4163 pData - This parameter should be type casted to a event specific pointer type based on the event that has occurred. Refer to the USB_DEVICE_HID_EVENT enumeration description for more details. context - Value identifying the context of the application that registered the event handling function. Remarks None. 5.9.6.6.2.14 USB_DEVICE_HID_EVENT_RESPONSE Type C typedef void USB_DEVICE_HID_EVENT_RESPONSE; Description USB Device HID Function Driver Event Handler Response Type This is the return type of the HID Function Driver event handler. Remarks None. 5.9.6.6.2.15 USB_DEVICE_HID_INDEX Type C typedef uintptr_t USB_DEVICE_HID_INDEX; Description USB Device HID Driver Index Numbers This uniquely identifies a HID Function Driver instance. Remarks None. 5.9.6.6.2.16 USB_DEVICE_HID_INIT Structure C typedef struct { size_t hidReportDescriptorSize; void * hidReportDescriptor; size_t queueSizeReportSend; size_t queueSizeReportReceive; } USB_DEVICE_HID_INIT; Description USB Device HID Function Driver Initialization Data Structure This data structure must be defined for every instance of the HID function driver. It is passed to the HID function driver, by the Device Layer, at the time of initialization. The funcDriverInit member of the Device Layer Function Driver registration table entry must point to this data structure for an instance of the HID function driver. Members Members Description size_t hidReportDescriptorSize; Size of the HID report descriptor void * hidReportDescriptor; Pointer to HID report descriptor 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4164 size_t queueSizeReportSend; Report send queue size size_t queueSizeReportReceive; Report receive queue size Remarks None. 5.9.6.6.2.17 USB_DEVICE_HID_RESULT Enumeration C typedef enum { USB_DEVICE_HID_RESULT_OK, USB_DEVICE_HID_RESULT_ERROR_TRANSFER_QUEUE_FULL, USB_DEVICE_HID_RESULT_ERROR_INSTANCE_NOT_CONFIGURED, USB_DEVICE_HID_RESULT_ERROR_INSTANCE_INVALID } USB_DEVICE_HID_RESULT; Description USB Device HID Function Driver USB Device HID Result enumeration. This enumeration lists the possible USB Device HID Function Driver operation results. These values USB Device HID Library functions. Members Members Description USB_DEVICE_HID_RESULT_OK The operation was successful 5.9.6.6.2.18 USB_DEVICE_HID_TRANSFER_HANDLE Type C typedef uintptr_t USB_DEVICE_HID_TRANSFER_HANDLE; Description USB Device HID Function Driver Transfer Handle Definition This definition defines a USB Device HID Function Driver Transfer Handle. A Transfer Handle is owned by the application but its value is modified by the USB_DEVICE_HID_ReportSend() and USB_DEVICE_HID_ReportReceive() functions. The transfer handle is valid for the life time of the transfer and expires when the transfer related event has occurred. Remarks None. 5.9.6.6.2.19 USB_DEVICE_HID_EVENT_RESPONSE_NONE Macro C #define USB_DEVICE_HID_EVENT_RESPONSE_NONE Description USB Device HID Function Driver Event Handler Response None This is the definition of the HID Function Driver Event Handler Response Type none. Remarks Intentionally defined to be empty. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4165 5.9.6.6.2.20 USB_DEVICE_HID_INSTANCES_NUMBER Macro C #define USB_DEVICE_HID_INSTANCES_NUMBER Description USB Device HID Maximum Number of Instances This macro defines the number of instances of the HID Function Driver. For example, if the application needs to implement two instances of the HID Function Driver (to create composite device) on one USB Device, the macro should be set to 2. Note that implementing a USB Device that features multiple HID interfaces requires appropriate USB configuration descriptors. Remarks None. 5.9.6.6.2.21 USB_DEVICE_HID_QUEUE_DEPTH_COMINED Macro C #define USB_DEVICE_HID_QUEUE_DEPTH_COMINED Description DOM-IGONORE-BEGIN 5.9.6.6.2.22 USB_DEVICE_HID_TRANSFER_HANDLE_INVALID Macro C #define USB_DEVICE_HID_TRANSFER_HANDLE_INVALID ((USB_DEVICE_HID_TRANSFER_HANDLE)(-1)) Description USB Device HID Function Driver Invalid Transfer Handle Definition This definition defines a USB Device HID Function Driver Invalid Transfer Handle. A Invalid Transfer Handle is returned by the USB_DEVICE_HID_ReportReceive() and USB_DEVICE_HID_ReportSend() functions when the request was not successful. Remarks None. 5.9.6.7 Files Files Name Description usb_device_hid.h USB HID Function Driver usb_device_hid_config_template..h USB device HID class configuration definitions template, Description 5.9.6.7.1 usb_device_hid.h USB HID Function Driver 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4166 USB HID Function Driver Enumerations Name Description USB_DEVICE_HID_CONTROL_STATUS USB Device HID Function Driver Control Transfer Status USB_DEVICE_HID_EVENT USB Device HID Function Driver Events USB_DEVICE_HID_RESULT USB Device HID Function Driver USB Device HID Result enumeration. Functions Name Description USB_DEVICE_HID_ControlReceive This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to receive data from the host in the data stage of the control transfer. USB_DEVICE_HID_ControlSend This function allows the application to respond to the HID function driver specific control transfer requests. It allows the application to send data to the host in the data stage of the control transfer. USB_DEVICE_HID_ControlStatus This function allows the application to complete the status stage of the the HID Function Driver specific control transfer request. USB_DEVICE_HID_EventHandlerSet This function registers a event handler for the specified HID function driver instance. USB_DEVICE_HID_ReportReceive This function submits the buffer to HID function driver library to receive a report from host to device. USB_DEVICE_HID_ReportSend This function submits the buffer to HID function driver library to send a report from device to host. Macros Name Description USB_DEVICE_HID_EVENT_RESPONSE_NONE USB Device HID Function Driver Event Handler Response Type None. USB_DEVICE_HID_TRANSFER_HANDLE_INVALID USB Device HID Function Driver Invalid Transfer Handle Definition. Structures Name Description USB_DEVICE_HID_EVENT_DATA_GET_IDLE USB Device HID Get Idle Event Data Type. USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL USB Device HID Get Protocol Event Data Type. USB_DEVICE_HID_EVENT_DATA_GET_REPORT USB Device HID Get Report Event Data Type. USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED USB Device HID Report Received Event Data Type. USB_DEVICE_HID_EVENT_DATA_REPORT_SENT USB Device HID Report Sent Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR USB Device HID Set Descriptor Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_IDLE USB Device HID Set Idle Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL USB Device HID Set Protocol Event Data Type. USB_DEVICE_HID_EVENT_DATA_SET_REPORT USB Device HID Set Report Event Data Type. USB_DEVICE_HID_INIT USB Device HID Function Driver Initialization Data Structure Types Name Description USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE USB Device HID Function Driver Control Transfer Handle USB_DEVICE_HID_EVENT_HANDLER USB Device HID Event Handler Function Pointer Type. 5.9 USB Library Help MPLAB Harmony Help USB HID Device Library 5-4167 USB_DEVICE_HID_EVENT_RESPONSE USB Device HID Function Driver Event Callback Response Type USB_DEVICE_HID_INDEX USB device HID Function Driver Index. USB_DEVICE_HID_TRANSFER_HANDLE USB Device HID Function Driver Transfer Handle Definition. Company Microchip Technology Inc. FileName: usb_hid_function_driver.h 5.9.6.7.2 usb_device_hid_config_template..h USB Device HID Class Configuration Definitions for the Template These definitions statically define the device HID Class mode of operation. Macros Name Description USB_DEVICE_HID_INSTANCES_NUMBER Specifies the number of HID instances. USB_DEVICE_HID_QUEUE_DEPTH_COMINED DOM-IGONORE-BEGIN File Name usb_device_hid_config_template.h Company Microchip Technology Inc. 5.9.7 USB MSD Device Library 5.9.7.1 Introduction USB Mass Storage Device (MSD) Class Library for Microchip Microcontrollers This library provides a high-level abstraction of USB Mass Storage Device (MSD) function driver with a convenient C language interface. This library supports USB Mass Storage Class Bulk-Only Transport, Revision 1.0 from USB Implementers Forum. Description The mass storage device class function driver library enables the developers to add mass storage functionality to a device. This library along with USB device stack and a required media driver can be used to build devices like USB thumb drive and card readers. 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4168 5.9.7.2 Release Notes MPLAB Harmony Version: v0.70b USB MSD Device Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.9.7.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.7.4 Using the Library 5.9.7.4.1 Abstraction Model The basic software architecture into which USB mass storage device class function driver fits into is depicted in the following diagram. 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4169 The system makes no direct calls to MSD function driver. It is the USB device layer that initializes and deinitializes the MSD function driver. The MSD function driver is initialized when host configures the device. It is deinitialized when device exits the configured state. The device exits the configured state when device is detached from the host or if host issues a bus reset to the device or if host changes the device configuration to a new value. The MSD function driver task is called from with in the USB device layer task. This means that MSD function driver task runs at the same priority level as USB device layer task. So, the user has to register the MSD function driver with USB device layer to allow the USB device layer to make calls to MSD function driver callback functions at runtime. This registration can be done using compile time configuration. The system does the media driver initialization and is responsible for calling the media driver tasks. The MSD function driver interacts with media driver at runtime to perform sector read, write and erase by calling the media driver callback functions. This requires for the user to register the media driver with the MSD function driver using compile time configuration. The subsequent sections of this help document describes how to register the MSD function driver and media driver with USB device layer and MSD function driver respectively. 5.9.7.4.2 How the Library Works 5.9.7.4.2.1 System Interaction 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4170 The above figure shows the system interaction required for MSD function driver. The system has to initialize the media driver and the USB device layer. There are no direct calls the system has to make to initialize the MSD function driver. The USB device layer initializes and deinitializes the MSD function driver appropriately at runtime. The system is also responsible for calling the media driver tasks if applicable. 5.9.7.4.2.2 Object Initialization Each instance of MSD function driver must be initialized by an object of data type USB_DEVICE_MSD_INIT at compile time. If there are more than one instance of MSD function driver, then user must create multiple objects of this data type. The Init Object is then linked to an instance of MSD function driver by adding its pointer to the function driver registration table (Refer to section "Registering MSD function driver"). The MSD Init Object contains following data about an instance of MSD. 1. Interface number. 2. Bulk-IN endpoint address 3. Bulk-OUT endpoint address 4. Size of the endpoint 5. Number of logical units (LUN) supported by the particular instance of MSD. 6. One or more media driver instance number depending on the number of logical units supported. This is the media driver with which the particular logical unit will interact. 7. One or more inquiry response structure depending on the number of logical units supported. 8. Pointers to one or more sets of media driver callback functions depending on the number of logical units supported. The device layer passes the Init Object to MSD function driver when it initializes the function driver. The following code example shows how to initialize the MSD using Init Object. const USB_DEVICE_MSD_INIT msdInit = { 0, /* Interface number */ 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4171 1, /* Bulk IN endpoint */ 1, /* Bulk OUT endpoint */ 64, /* Size of the bulk endpoint */ 1, /* Number of logical unit (LUN) */ { /* Begin first LUN info */ { /* Media driver instance number */ USB_DEVICE_MDD_INTFLASH_INDEX, /* Inquiry response for the first logical unit */ { 0x00, /* peripheral device is connected, direct access block device */ 0x80, /* removable media */ 0x04, /* version = 00=> does not conform to any standard, 4=> SPC-2 */ 0x02, /* response is in format specified by SPC-2 */ 0x20, /* n-4 = 36-4=32= 0x20 */ 0x00, /* sccs etc.*/ 0x00, /* bque=1 and cmdque=0,indicates simple queuing 00 is obsolete but as in case of other device, we are just using 00. */ 0x00, /* 00 obsolete, 0x80 for basic task queuing */ { 'M','i','c','r','o','c','h','p' }, /* this is the T10 assigned Vendor ID */ { 'M','a','s','s',' ','S','t','o','r','a','g','e',' ',' ',' ',' ' }, { '0','0','0','1' } }, /* MDD function callback pointers for first loical uint */ { &USB_DEVICE_MDD_INTFLASH_Status, &USB_DEVICE_MDD_INTFLASH_Open, &USB_DEVICE_MDD_INTFLASH_ReadCapacity, &USB_DEVICE_MDD_INTFLASH_ReadSectorSize , &USB_DEVICE_MDD_INTFLASH_MediaDetect, &USB_DEVICE_MDD_INTFLASH_SectorRead, &USB_DEVICE_MDD_INTFLASH_WriteProtectState, &USB_DEVICE_MDD_INTFLASH_SectorWrite } } }/* End of first LUN info */ { /* Start of second LUN info */ } /* End of second LUN info */ }; 5.9.7.4.2.3 MSD Function Driver Registration The MSD function driver is registered with the USB device layer using the function registration table structure. The following code example shows how the MSD function driver can be registered with the USB device layer using function registration table. The structure variable msdFunctionDriver contains pointers to MSD function driver callbacks. Example: 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4172 /* The device layer invokes the MSD function driver if the speed is full speed and the host selects configuration value as 1 */ funcRegistrationTable[1] = { { /* Speed USB_SPEED_FULL, /* Configuration value */ 1, /* Interface number */ 0, /* Number of interfaces */ 1, /* MSD instance index */ USBMSD_FUNC_INDEX, /* MSD driver init object */ (void*)&msdInit, /* MSD driver */ &msdFunctionDriver } }; 5.9.7.4.2.4 Media Driver Registration The MSD function driver makes call to media driver functions at runtime to perform sector erase, read and write operations. Therefore, the user must register the pointers to media driver callback functions with the MSD function driver . This has to be done at compile time while initializing the Init Object. Refer to the code example shown in the "Init Object" section for more information. 5.9.7.5 Library Interface This section describes the configuration options provided by the MSD function driver to the system and the available data types. Refer to each section for a detailed description. 5.9.7.5.1 System Configuration Functions Macros Name Description USB_DEVICE_MSD_MAX_INSTANCES This constant sets maximum possible number of instances of USB device MSD function driver that can be instantiated by using USB_DEVICE_MSD_Initialize() routine. USB_DEVICE_MSD_MAX_LUN This constant sets maximum possible number of Logical Unit an instance of MSD can support. USB_DEVICE_MSD_MAX_SECTOR_SIZE This constant defines the max possible media sector size supported by the MSD. Description 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4173 5.9.7.5.1.1 USB_DEVICE_MSD_MAX_INSTANCES Macro C #define USB_DEVICE_MSD_MAX_INSTANCES 1 Remarks The static implementation supports only one instance. Setting the value of this constant to > 1 has no effect on static implementations. Only in dynamic implementation of USB device MSD function driver this value can be set > 1. USB device MSD function driver has to support atleast one instance. Hence, make sure the value of this constant is set to > 0. Increasing the instance count consumes RAM and can lead to performance degradation. 5.9.7.5.1.2 USB_DEVICE_MSD_MAX_LUN Macro C #define USB_DEVICE_MSD_MAX_LUN 1 Description This constant sets maximum possible number of Logical Unit (LUN) an instance of MSD can support. Remarks The value of this macro must not be set to zero. Each instance of USB MSDfunction driver can support atleast one LUN. Hence set the value to atleast 1. 5.9.7.5.1.3 USB_DEVICE_MSD_MAX_SECTOR_SIZE Macro C #define USB_DEVICE_MSD_MAX_SECTOR_SIZE 512 Description If there are two logical units (LUNs), one that supports sector size 512 bytes and then the other one that supports 1024 bytes, then set the value of this macro to 1024. Remarks none. 5.9.7.5.2 Data Types and Constants Macros Name Description USB_DEVICE_MSD_INTF MSD Interface Class Code USB_DEVICE_MSD_INTF_SUBCLASS Only scsi transparent is supported. USB_DEVICE_MSD_PROTOCOL MSD Interface Class Protocol Codes Structures Name Description USB_DEVICE_MSD_MEDIA_FUNCTIONS This structure contains all the media driver callback function pointers. The MSD driver makes call to these function pointers at run time to know the status of the media and to read and write the media. USB_DEVICE_MSD_INIT This structure contains required parameters for MSD initialization. 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4174 USB_DEVICE_MSD_INQUIRY_RESPONSE Inquiry response structure. USB_DEVICE_MSD_MEDIA_INIT_DATA This structure holds media related data of a particular logical unit. Description 5.9.7.5.2.1 USB_DEVICE_MSD_INTF Macro C #define USB_DEVICE_MSD_INTF 0x08 Description MSD Interface Class Code 5.9.7.5.2.2 USB_DEVICE_MSD_INTF_SUBCLASS Macro C #define USB_DEVICE_MSD_INTF_SUBCLASS 0x06 // Only scsi transparent is supported. Description Only scsi transparent is supported. 5.9.7.5.2.3 USB_DEVICE_MSD_PROTOCOL Macro C #define USB_DEVICE_MSD_PROTOCOL 0x50 Description MSD Interface Class Protocol Codes 5.9.7.5.2.4 USB_DEVICE_MSD_MEDIA_FUNCTIONS Structure C struct USB_DEVICE_MSD_MEDIA_FUNCTIONS { SYS_STATUS (* mediaInitState)(SYS_MODULE_OBJ objIndex); DRV_HANDLE (* open)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); void (* close)(DRV_HANDLE hClient); uint32_t (* readCapacity)(DRV_HANDLE drvHandle); uint32_t (* readSectorSize)(DRV_HANDLE drvHandle); bool (* mediaDetect)(DRV_HANDLE drvHandle); bool (* sectorRead)(DRV_HANDLE drvHandle, uint32_t sector_addr, uint8_t * buffer, void * refHandle, MEDIA_OP_CMPLT_CB callBack); uint8_t (* writeProtectState)(DRV_HANDLE drvHandle); bool (* sectorWrite)(DRV_HANDLE drvHandle, uint32_t sector_addr, uint8_t* buffer, void * refHandle, MEDIA_OP_CMPLT_CB callBack); }; Description The user must provide the callback function address of the media at compile time. MSD driver calls these function during run time to perform media operation or to know the media status. 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4175 Members Members Description SYS_STATUS (* mediaInitState)(SYS_MODULE_OBJ objIndex); Media init state. DRV_HANDLE (* open)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Function pointer to the MediaInitialize() function of the physical media being used. void (* close)(DRV_HANDLE hClient); Function pointer for closing the physical media. uint32_t (* readCapacity)(DRV_HANDLE drvHandle); Function pointer to the ReadCapacity() function of the physical media being used. uint32_t (* readSectorSize)(DRV_HANDLE drvHandle); Function pointer to the ReadSectorSize() function of the physical media being used. bool (* mediaDetect)(DRV_HANDLE drvHandle); Function pointer to the MediaDetect() function of the physical media being used. bool (* sectorRead)(DRV_HANDLE drvHandle, uint32_t sector_addr, uint8_t * buffer, void * refHandle, MEDIA_OP_CMPLT_CB callBack); Function pointer to the SectorRead() function of the physical media being used. uint8_t (* writeProtectState)(DRV_HANDLE drvHandle); Function pointer to the WriteProtectState() function of the physical media being used. bool (* sectorWrite)(DRV_HANDLE drvHandle, uint32_t sector_addr, uint8_t* buffer, void * refHandle, MEDIA_OP_CMPLT_CB callBack); Function pointer to the SectorWrite() function of the physical media being used. Remarks None. 5.9.7.5.2.5 USB_DEVICE_MSD_INIT Structure C struct USB_DEVICE_MSD_INIT { uint8_t numberOfLogicalUnits; USB_DEVICE_MSD_MEDIA_INIT_DATA mediaInit[USB_DEVICE_MSD_MAX_LUN]; }; Description USB MSD init structure. This structure contains interface number, bulk-IN and bulk-OUT endpoint addresses, endpointSize, number of logical units supported and pointer to array of structure that contains media initialization. Members Members Description uint8_t numberOfLogicalUnits; Number of logical units supported. USB_DEVICE_MSD_MEDIA_INIT_DATA mediaInit[USB_DEVICE_MSD_MAX_LUN]; Media related data Remarks This structure must be configured by the user at compile time. 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4176 5.9.7.5.2.6 USB_DEVICE_MSD_INQUIRY_RESPONSE Structure C struct USB_DEVICE_MSD_INQUIRY_RESPONSE { uint8_t peripheral; uint8_t removable; uint8_t version; uint8_t responseDataFormat; uint8_t additionalLength; uint8_t sccstp; uint8_t bqueetc; uint8_t cmdQue; uint8_t vendorID[8]; uint8_t productID[16]; uint8_t productRev[4]; }; Description USB Device MSD inquiry response structure as defined in SCSI Primary Commands - 4. Members Members Description uint8_t peripheral; Peripheral_Qualifier:3; Peripheral_DevType:5; uint8_t removable; Removable medium bit7 = 0 means non removable, rest reserved uint8_t version; Version uint8_t responseDataFormat; b7,b6 Obsolete, b5 Access control co-ordinator, b4 hierarchical addressing support b3:0 response data format 2 indicates response is in format defined by spec uint8_t additionalLength; length in bytes of remaining in standard inquiry data uint8_t sccstp; b7 SCCS, b6 ACC, b5-b4 TGPS, b3 3PC, b2-b1 Reserved, b0 Protected uint8_t bqueetc; b7 bque, b6- EncServ, b5-VS, b4-MultiP, b3-MChngr, b2-b1 Obsolete, b0-Addr16 uint8_t cmdQue; b7-b6 Obsolete, b5-WBUS, b4-Sync, b3-Linked, b2 Obsolete,b1 Cmdque, b0-VS uint8_t vendorID[8]; Vendor ID uint8_t productID[16]; Product ID uint8_t productRev[4]; Product Revision Remarks None. 5.9.7.5.2.7 USB_DEVICE_MSD_MEDIA_INIT_DATA Structure C struct USB_DEVICE_MSD_MEDIA_INIT_DATA { SYS_MODULE_INDEX instanceIndex; USB_DEVICE_MSD_INQUIRY_RESPONSE inquiryResponse; USB_DEVICE_MSD_MEDIA_FUNCTIONS mediaCallBackPtrs; }; Description It holds pointer to inquiry response, instance index and pointer to a structure that contains all media callback functions. Members Members Description SYS_MODULE_INDEX instanceIndex; Instance index of the media 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4177 USB_DEVICE_MSD_INQUIRY_RESPONSE inquiryResponse; Pointer to inquiry response USB_DEVICE_MSD_MEDIA_FUNCTIONS mediaCallBackPtrs; Callback function pointers of the media Remarks An object of this structure must be configured by the user at compile time. 5.9.7.6 Files Files Name Description usb_device_msd.h USB device MSD function driver interface header usb_device_msd_config_template.h usb device MSD configuration template header file Description 5.9.7.6.1 usb_device_msd.h USB MSD function driver interface header USB device MSD function driver interface header Macros Name Description USB_DEVICE_MSD_INTF MSD Interface Class Code USB_DEVICE_MSD_INTF_SUBCLASS Only scsi transparent is supported. USB_DEVICE_MSD_PROTOCOL MSD Interface Class Protocol Codes Structures Name Description USB_DEVICE_MSD_INIT This structure contains required parameters for MSD initialization. USB_DEVICE_MSD_INQUIRY_RESPONSE Inquiry response structure. USB_DEVICE_MSD_MEDIA_FUNCTIONS This structure contains all the media driver callback function pointers. The MSD driver makes call to these function pointers at run time to know the status of the media and to read and write the media. USB_DEVICE_MSD_MEDIA_INIT_DATA This structure holds media related data of a particular logical unit. File Name usb_device_msd.h Company Microchip Technology Inc. 5.9.7.6.2 usb_device_msd_config_template.h USB device MSD function driver compile time options This file contains USB device MSD function driver compile time options(macros) that has to be configured by the user. This file is 5.9 USB Library Help MPLAB Harmony Help USB MSD Device Library 5-4178 a template file and must be used as an example only. This file must not be directly included in the project. Macros Name Description USB_DEVICE_MSD_MAX_INSTANCES This constant sets maximum possible number of instances of USB device MSD function driver that can be instantiated by using USB_DEVICE_MSD_Initialize() routine. USB_DEVICE_MSD_MAX_LUN This constant sets maximum possible number of Logical Unit an instance of MSD can support. USB_DEVICE_MSD_MAX_SECTOR_SIZE This constant defines the max possible media sector size supported by the MSD. File Name usb_device_msd_config_template.h Company Microchip Technology Incorported 5.9.8 USB Host Layer Library 5.9.8.1 Introduction Introduces the MPLAB Harmony USB Host Library Description The USB Host layer library is part of USB Host stack that is available for the Microchip family of microcontrollers. This library uses the USB Host Controller Driver to interact with the USB peripheral and therefore cannot operate independently of it. Within the USB Host stack, the USB Host layer is responsible for enumeration the attached device, matching available class drivers and maintaining the class drivers. The USB Host layer library implementation adheres to USB Device Framework of chapter-9 of USB specification 2.0. In the USB Host stack, the host layer features the following: • Supports USB Low-Speed, Full-Speed, and Hi-Speed USB Devices • Based on a modular and event driven architecture. • Supports the PIC32MX and PIC32MZ families of microcontrollers • Designed to support multiple device and multiple configurations • Contains class driver to supports the following type of devices • CDC • MSD • Supports non-blocking operation and is RTOS friendly • Designed to integrate readily with other Harmony Middleware • Supports both interrupt and polling operation 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4179 5.9.8.2 Release Notes MPLAB Harmony Version: v0.70b USB Host Layer Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: • The host Stack has not been tested with a Real Time Operating System. • Attach/Detach behavior has been tested in a limited capacity. • The host stack only supports interrupt mode operation. Polled mode operation will be added in a future release. • While running the host stack on PIC32MZ microcontroller, the stack requires 3 seconds to initialize. This is due to a hardware issue with PIC32MZ USB module. • MSD Host has been tested with a limited number of commercially available USB Flash Drives. • MSD Host and the USB Host Layer have not been tested for read/write throughput. This will be done in a future release. • Host stack has not been tested with low speed devices. 5.9.8.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.8.4 Library Interface Data Types and Constants Name Description USB_HOST_HANDLE Handle identifying a client when calling Host layer client functions. USB_HOST_INIT Defines the data required to initialize a USB Host Layer instance. USB_HOST_HANDLE_INVALID Definition of an invalid USB Host Client Handle 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4180 USB_DEVICE_INFORMATION Defines the USB Device Information data strucutre. USB_HOST_EVENT_CALLBACK USB Host Event Handler Function Pointer Type. USB_HOST_EVENT_DATA_VBUS_REQUEST_POWER Defines the data returned along with the USB_HOST_EVENT_VBUS_REQUEST_POWER event. USB_HOST_EVENT_RESPONSE USB Host Event Handler Response Type USB_HOST_EVENTS Identifies the possible events that the host layer can generate. USB_HOST_TPL_FLAGS USB Host Layer Target Peripheral List Entry flags TPL_MATCH_VID_PID This macro when used in the TPL table will direct the Host Layer to match the corresponding class driver by device vendor ID (VID) and product ID (PID). USB_HOST_0 USB Host module index definitions USB_HOST_1 This is macro USB_HOST_1. USB_HOST_ENDPOINT_TABLE_SIZE USB Host Endpoint Table size needed while running the host on PIC32MX devices. USB_HOST_EVENT_RESPONSE_NONE USB Host Layer Event Handler Response Type None. Functions Name Description USB_HOST_Close Closes an opened-instance of the USB Host Layer. USB_HOST_Open Opens the specified Host Layer instance and returns a handle to it USB_HOST_Deinitialize Deinitializes the specified instance of the USB Host Layer. USB_HOST_DeviceInformationGet Returns select information about the attached device. USB_HOST_DeviceIsResumed Checks if the attached USB device has been resumed. USB_HOST_DeviceIsSuspended Checks if the attached USB device has been suspended. USB_HOST_DeviceResume Resumes the USB. USB_HOST_DeviceSuspend Suspends the USB. USB_HOST_EventCallBackSet Allows a client to identify an event handling function for the host layer to call back when host layer events are generated. USB_HOST_Initialize Initializes the USB Host layer instance for the specified instance index. USB_HOST_OperationDisable Disabled host operation. USB_HOST_OperationEnable Enables host operation. USB_HOST_OperationIsEnabled Allows the application to check if the host operation is enabled. USB_HOST_Status Gets the current status of the USB Host Layer. USB_HOST_Tasks Maintains the USB Host's state machine. It manages the USB Module driver and responds to USB Module driver events. Description This section describes the Application Programming Interface (API) functions of the USB Host Layer 5.9.8.4.1 Functions 5.9.8.4.1.1 USB_HOST_Close Function C void USB_HOST_Close( USB_HOST_HANDLE hostHandle ); 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4181 Description This routine closes an opened-instance of the USB Host Layer, invalidating the handle. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine Returns None Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling USB_HOST_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually there is no need for the driver client to verify that the Close operation has completed. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_HOST_Close(handle); 5.9.8.4.1.2 USB_HOST_Open Function C USB_HOST_HANDLE USB_HOST_Open( SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); Description This routine opens the specified Host Layer instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the host layer. The host layer can be opened exclusively by a client by specifying the ioIntent as DRV_IO_INTENT_EXCLUSIVE. Any other flag settings will not have an effect on clients interaction with the host layer. Preconditions Function USB_HOST_Initialize must have been called before calling this function. Parameters Parameters Description index Identifier for the object instance to be opened intent can be DRV_IO_INTENT_EXCLUSIVE which allows a client to open the host layer exclusively. Any other flags are ignored. Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is USB_HOST_HANDLE_INVALID. Error can occur • if the number of client ojects allocated via USB_HOST_CLIENTS_NUMBER is insufficient. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4182 • if the client is trying to open the host layer but host layer has been opened exclusively by another client. • if the host layer instance being opened is not initialized or is invalid. Remarks The handle returned is valid until the USB_HOST_Close routine is called. This routine will NEVER block waiting for hardware. This function is thread safe in a RTOS application. It should not be called in an ISR. Example USB_HOST_HANDLE handle; handle = USB_HOST_Open(USB_HOST_0, DRV_IO_INTENT_EXCLUSIVE); if (USB_HOST_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } 5.9.8.4.1.3 USB_HOST_Deinitialize Function C void USB_HOST_Deinitialize( SYS_MODULE_OBJ driverObject ); Description Deinitializes the specified instance of the USB Host Layer. This function will aslo deinitialize the USB Module driver and hence stop all USB Host related operation on the bus. All internal data structures will be reset. Preconditions Function USB_HOST_Initialize should have been called before calling this function. Parameters Parameters Description object USB Host layer object handle, returned from the USB_HOST_Initialize routine Returns None. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Example SYS_MODULE_OBJ object; // Returned from USB_HOST_Initialize SYS_STATUS status; USB_HOST_Deinitialize(object); status = USB_HOST_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4183 } 5.9.8.4.1.4 USB_HOST_DeviceInformationGet Function C USB_ERROR USB_HOST_DeviceInformationGet( USB_HOST_HANDLE hostHandle, uint8_t deviceAddress, USB_DEVICE_INFORMATION * deviceInfo ); Description This function returns select information about the attached device. The application may use this information to update it display or for other application purposes. The device information is returned in the deviceInformation data structure. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine address Address of the device. deviceInformation pointer to a data structure where the device information will be stored Returns USB_ERROR_NONE - Function was successful. USB_ERROR_PARAMETER_INVALID - Device address or host handle is invalid or deviceInformation pointer is NULL. Remarks None. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_ERROR result; USB_DEVICE_INFORMATION deviceInfo; // Get informationa about attached device with address 2 result = USB_HOST_DeviceInformationGet(handle, 2, &deviceInfo); if(USB_ERROR_NONE == result) { // Display the string descriptor of the attached device. APP_PrintToDisplay(deviceInformation.stringDesciptor); } 5.9.8.4.1.5 USB_HOST_DeviceIsResumed Function C bool USB_HOST_DeviceIsResumed( USB_HOST_HANDLE hostHandle, uint8_t deviceAddress ); Description This function checks if the attached USB device has been resumed. This function can be called after calling the USB_HOST_DeviceResume() function to check if resume request has been completed. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4184 Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine address Address of the device. Returns true - Device is resumed. false - Device is not resumed or device address or handle is invalid. Remarks In cases where the device is connected directly to the USB Module, the bus resume request will be serviced immediately. In cases where the device is connected to the USB module via a hub, the application must call the USB_HOST_DeviceIsResumed() function to check if the device has been resumed. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_ERROR result; // Resume the device with address 2 result = USB_HOST_DeviceResume(handle, 2); if(USB_ERROR_NONE == result) { // Wait till device is resumed. while(!USB_HOST_DeviceIsResumed(handle, 2)); } 5.9.8.4.1.6 USB_HOST_DeviceIsSuspended Function C bool USB_HOST_DeviceIsSuspended( USB_HOST_HANDLE hostHandle, uint8_t deviceAddress ); Description This function checks if the attached USB device has been suspended. This function can be called after calling the USB_HOST_DeviceSuspend() function to check if suspend request has been completed. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine address Address of the device. Returns true - Device is suspended. false - Device is not suspended or device address or handle is invalid. Remarks In cases where the device is connected directly to the USB Module, the bus suspend request will be serviced immediately. In cases where the device is connected to the USB module via a hub, the application must call the USB_HOST_DeviceIsSuspended() function to check if the device has been suspended. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4185 Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_ERROR result; // Suspend the device with address 2 result = USB_HOST_Device(handle, 2); if(USB_ERROR_NONE == result) { // Wait till device is suspended. while(!USB_HOST_DeviceIsSuspended(handle, 2)); } 5.9.8.4.1.7 USB_HOST_DeviceResume Function C USB_ERROR USB_HOST_DeviceResume( USB_HOST_HANDLE hostHandle, uint8_t deviceAddress ); Description The function resumes the USB. If address is an address of a device that is connected directly to the USB module, this function will directly resume the bus. If the address is an address of a device that is connected to the module via a hub, the USB Host layer will resume the hub port to which this device is connected. The function only places a request to resume the device. The application must use the USB_HOST_DeviceIsResumeed() function to check if the device resume is complete. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine address Address of the device. Returns USB_ERROR_NONE - The request was accepted successfully. USB_ERROR_PARAMETER_INVALID - The device address or handle is invalid. Remarks In cases where the device is connected directly to the USB Module, the bus resume request will be serviced immediately. In cases where the device is connected to the USB module via a hub, the application must call the USB_HOST_DeviceIsResumed() function to check if the device has been resumed. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_ERROR result; // Resume the device with address 2 result = USB_HOST_Device(handle, 2); if(USB_ERROR_NONE == result) { // Wait till device is resumed. while(!USB_HOST_DeviceIsResumed(handle, 2)); } 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4186 5.9.8.4.1.8 USB_HOST_DeviceSuspend Function C USB_ERROR USB_HOST_DeviceSuspend( USB_HOST_HANDLE hostHandle, uint8_t deviceAddress ); Description The function suspends the USB. If address is an address of a device that is connected directly to the USB module, this function will directly suspend the bus. If the address is an address of a device that is connected to the module via a hub, the USB Host layer will suspend the hub port to which this device is connected. The function only places a request to suspend the device. The application must use the USB_HOST_DeviceIsSuspended() function to check if the device suspend is complete. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine address Address of the device. Returns USB_ERROR_NONE - The request was accepted successfully. USB_ERROR_PARAMETER_INVALID - The device address or handle is invalid. Remarks In cases where the device is connected directly to the USB Module, the bus suspend request will be serviced immediately. In cases where the device is connected to the USB module via a hub, the application must call the USB_HOST_DeviceIsSuspended() function to check if the device has been suspended. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open USB_ERROR result; // Suspend the device with address 2 result = USB_HOST_Device(handle, 2); if(USB_ERROR_NONE == result) { // Wait till device is suspended. while(!USB_HOST_DeviceIsSuspended(handle, 2)); } 5.9.8.4.1.9 USB_HOST_EventCallBackSet Function C USB_ERROR USB_HOST_EventCallBackSet( USB_HOST_HANDLE hostHandle, USB_HOST_EVENT_CALLBACK callback, uintptr_t context ); Description This function allows a client to identify an event handling function for the host layer to call back when host layer events are generated. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4187 The event handler should be set before the client the host layer operation is enabled. The event handler once set, persists until the client closes the driver or sets another event handler. Preconditions The USB_HOST_Initialize routine must have been called for the specified Host Layer instance. USB_HOST_Open must have been called to obtain a valid opened Host Layer handle. Parameters Parameters Description handle A valid open-instance handle, returned from the host layer's open routine callback Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Returns USB_ERROR_NONE - Callback function was registered successfully. USB_ERROR_PARAMETER_INVALID - Callback function was NULL or hostHandle is invalid. Remarks None. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; USB_HOST_HANDLE usbHostHandle; // usbHostHandle is the handle returned // by the USB_HOST_Open function. // Client registers an event handler with host layer. USB_HOST_EventCallBackSet( usbHostHandle, APP_USBHostEventHandler, (uintptr_t)&myAppObj ); USB_HOST_EVENT_RESPONSE APP_USBHostEventHandler(uintptr_t context, USB_HOST_EVENTS event, void * eventData) { switch(event) { case USB_HOST_EVENT_UNSUPPORTED_DEVICE: break; ... } return(USB_HOST_EVENT_RESPONSE_NONE); } 5.9.8.4.1.10 USB_HOST_Initialize Function C SYS_MODULE_OBJ USB_HOST_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * init ); 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4188 Description This routine initializes the USB Host Layer instance for the specified instance index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The intialization may fail if the number of host layer objects allocated are insufficient or if the specificed host layer instance is already initialized. This function also initializes the USB Module driver for host mode operation. The init data structure thus contains information required for driver initialization. Note that initializing the Host Layer does not enable its operations. This must be done using USB_HOST_OperationEnable() function. Preconditions None. Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a USB_HOST_INIT data structure containing data necessary to initialize the driver. Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Remarks This routine must be called before any other USB Host routine is called. This routine should only be called once during system initialization unless USB_HOST_Deinitialize is called to de-initialize the Host Layer instance. This routine will NEVER block for hardware access. Example // Initializes the host layer for use with PIC32MX devices. // We assume that the TPL table is already created and has two // entries. USB_HOST_TARGET_PERIPHERAL_LIST * tplTable; USB_HOST_INIT usbHostInit; SYS_MODULE_OBJ objectHandle; // Allocate an endpoint table uint8_t __attribute__((aligned(512))) endpointTable[USB_HOST_ENDPOINT_TABLE_SIZE]; usbHostInit.moduleInit = SYS_MODULE_POWER_RUN_FULL; // The usbID member of the USB_HOST_INIT data structure // should be USB_ID_x for PIC32MX devices and should be // USBHS_ID_x PIC32MZ devices. Typical values are USB_ID_1 // for PIC32MX and USBHS_ID_0 for PIC32MZ devices. usbHostInit.usbID = USB_ID_1; //for PIC32MX devices usbHostInit.stopInIdle = false; usbHostInit.suspendInSleep = false; usbHostInit.endpointTable = endpointTable; usbHostInit.interruptSource = INT_SOURCE_USB_1; usbHostInit.nTPLEntries = 2 usbHostInit.usbSpeed = USB_SPEED_FULL; usbHostInit.tplTable = tplTable; objectHandle = USB_HOST_Initialize(USB_HOST_0, (SYS_MODULE_INIT*)usbHostInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4189 5.9.8.4.1.11 USB_HOST_OperationDisable Function C void USB_HOST_OperationDisable( USB_HOST_HANDLE hostHandle ); Description The function disables host operation. Disabling the host operation will cause the host to ignore attached device. All bus communication will be halted and USB bus will be suspended. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine Returns None Remarks This function may not be used in a typical USB Host application. One possible use could be in a case where a fatal system error has occurred. Once disabled, the Host operation must be enabled again using the USB_HOST_OperationEnable() function. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open // Enabled host operation USB_HOST_OperationDisable(handle); 5.9.8.4.1.12 USB_HOST_OperationEnable Function C void USB_HOST_OperationEnable( USB_HOST_HANDLE hostHandle ); Description The function enables host operation. When enabled, the host layer can detect and enumerate attached devices. The application must call the USB_HOST_OperationIsEnabled() function to check if the operation has completed. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine Returns None Remarks It is recommended that only on host layer client call this function. Multiple host layer clients calling this may cause indeterministic behavior. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4190 Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open // Enabled host operation USB_HOST_OperationEnable(handle); // Wait till host operation is enabled. while(!USB_HOST_OperationIsEnabled(handle)); 5.9.8.4.1.13 USB_HOST_OperationIsEnabled Function C bool USB_HOST_OperationIsEnabled( USB_HOST_HANDLE hostHandle ); Description The function allows the application to check if the host operation is enabled. This function should be called after the USB_HOST_OperationEnable() function is called to check if the operation has been enabled. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description handle A valid open-instance handle, returned from the Host Layers's open routine Returns None. Remarks None. Example USB_HOST_HANDLE handle; // Returned from USB_HOST_Open // Enabled host operation USB_HOST_OperationEnable(handle); // Wait till host operation is enabled. while(!USB_HOST_OperationIsEnabled(handle)); 5.9.8.4.1.14 USB_HOST_Status Function C SYS_STATUS USB_HOST_Status( SYS_MODULE_OBJ driverObject ); Description This routine provides the current status of the USB Host Layer. Preconditions Function USB_HOST_Initialize should have been called before calling this function. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4191 Parameters Parameters Description object USB Host Layer object handle, returned from the USB_HOST_Initialize routine Returns SYS_STATUS_READY - Indicates that the USB Host layer is ready for operations. SYS_STATUS_DEINITIALIZED - Indicates that the driver has been de-initialized Remarks None. Example SYS_MODULE_OBJ object; // Returned from USB_HOST_Initialize SYS_STATUS status; status = USB_HOST_Status(object); if (SYS_STATUS_READY == status) { // This means the driver can be opened using the // USB_HOST_Open() function. } 5.9.8.4.1.15 USB_HOST_Tasks Function C void USB_HOST_Tasks( SYS_MODULE_OBJ driverObject ); Description This routine maintains the USB Host layer's state machine. It manages and the USB Module driver and responds to USB module driver events. This function should be called from the SYS_Tasks() function. Preconditions The USB_HOST_Initialize routine must have been called for the specified USB Host Layer instance. Parameters Parameters Description object Object handle for the specified driver instance (returned from USB_HOST_Initialize) Returns None. Remarks This routine is normally not called directly by an application. Example SYS_MODULE_OBJ object; // Returned from USB_HOST_Initialize while (true) { USB_HOST_Tasks (object); // Do other tasks } 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4192 5.9.8.4.2 Data Types and Constants 5.9.8.4.2.1 USB_HOST_HANDLE Type C typedef uintptr_t USB_HOST_HANDLE; Description USB Host Client Handle A USB Host Client Handle is returned by a call to the USB_HOST_Open() function. The handle maintains the relationship between USB Host Layer and its client. All USB Host Client functions required the client handle to be specified when the functions are called. A client handle is valid till the the client calls the USB_HOST_Close() function at which point it becomes invalid. Remarks None. 5.9.8.4.2.2 USB_HOST_INIT Structure C typedef struct { SYS_MODULE_INIT moduleInit; uint8_t usbID; bool stopInIdle; bool suspendInSleep; void * endpointTable; INT_SOURCE interruptSource; unsigned int nTPLEntries; USB_SPEED usbSpeed; USB_HOST_TARGET_PERIPHERAL_LIST * tplList; } USB_HOST_INIT; Description USB Host Intialization Data Structure This data type defines the data required to initialize an USB Host Layer Instance. A pointer to a structure of this type is required by the USB_HOST_Initialize() function. Members Members Description SYS_MODULE_INIT moduleInit; System Module Initialization data uint8_t usbID; Identifies the Peripheral Library ID of the USB Peripheral to be used by this instance of the host layer bool stopInIdle; Identifies the Idle mode behavior. If true the USB module will stop when the microcontroller enter IDLE mode bool suspendInSleep; If true, the USB module will automatically suspend when the the microcontroller enter sleep mode void * endpointTable; Pointer to an endpoint table whose size should be USB_HOST_ENDPOINT_TABLE_SIZE number of bytes. INT_SOURCE interruptSource; Interrupt Peripheral Library ID of the interrupt source of USB module which this Host layer will control unsigned int nTPLEntries; Number of entries in the TPL table 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4193 USB_SPEED usbSpeed; Speed at which the module should operate USB_HOST_TARGET_PERIPHERAL_LIST * tplList; Pointer to the TPL table Remarks Intentionally defined to be empty. 5.9.8.4.2.3 USB_HOST_HANDLE_INVALID Macro C #define USB_HOST_HANDLE_INVALID Description USB Host Invalid Client Handle This is the definition of an invalid USB Host Client Handle. An invalid client handle is returned by the USB_HOST_Open() function when it was not able to open the USB Host Layer successfully. Remarks None. 5.9.8.4.2.4 USB_DEVICE_INFORMATION Structure C typedef struct { uint16_t vid; uint16_t pid; uint16_t stringDescriptor[USB_HOST_DEVICE_INFORMATION_STRING_LENGTH]; } USB_DEVICE_INFORMATION; Description USB Device Information Structure This data type defines the USB Device information data structure. This data structure is passed to USB_HOST_DeviceInformationGet() function to obtain specific information about the device. The application can use this information to update its display or for other purposes. When processed by the USB_HOST_DeviceInformationGet() function, the stringDesciptor member of this data structure will contain a NULL terminated string descriptor string in UTF-16 format. The vid and pid members of the data structure will be populated with VID and PID of the attached device respectively. Members Members Description uint16_t vid; VID of the attached device uint16_t pid; PID of the attached device uint16_t stringDescriptor[USB_HOST_DEVICE_INFORMATION_STRING_LENGTH]; String desciptor string in UTF-16 format. The string when returned by USB_HOST_DeviceInformationGet() function will be NULL terminated. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4194 5.9.8.4.2.5 USB_HOST_EVENT_CALLBACK Type C typedef USB_HOST_EVENT_RESPONSE (* USB_HOST_EVENT_CALLBACK)(USB_HOST_EVENTS event, void * eventData, uintptr_t context); Description USB Host Event Handler Function Pointer Type. This data type defines the required function signature of the USB Host Layer event handling callback function. The application must register a pointer to a USB Host Event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive event call backs from the USB Host Layer. The function driver will invoke this function with event relevant parameters. The description of the event handler function parameters is given here. event - Type of event generated. eventData - This parameter should be type casted to a event specific pointer type based on the event that has occurred. Refer to the USB_HOST_EVENTS enumeration description for more details. context - Value identifying the context of the application that registered the event handling function. Remarks None. 5.9.8.4.2.6 USB_HOST_EVENT_DATA_VBUS_REQUEST_POWER Structure C typedef struct { uint8_t port; uint8_t current; } USB_HOST_EVENT_DATA_VBUS_REQUEST_POWER; Description USB Host VBUS Power Request Event Data Structure This data type defines the data returned along with the USB_HOST_EVENT_VBUS_REQUEST_POWER event. Members Members Description uint8_t port; Port where the device is connected uint8_t current; Current (in 2mA units) that the device is requesting Remarks None. 5.9.8.4.2.7 USB_HOST_EVENT_RESPONSE Type C typedef void USB_HOST_EVENT_RESPONSE; Description USB Host Event Handler Response Type This is the return type of the USB Host Layer Event Handler 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4195 Remarks None. 5.9.8.4.2.8 USB_HOST_EVENTS Enumeration C typedef enum { USB_HOST_EVENT_VBUS_REQUEST_POWER, USB_HOST_EVENT_UNSUPPORTED_DEVICE, USB_HOST_EVENT_CANNOT_ENUMERATE } USB_HOST_EVENTS; Description USB Host Events This enumeration identifies the possible events that the host layer can generate. A Host Layer client should register an event handler using the USB_HOST_EventCallBackSet() function to receive host layer events. An event may have data associated with it. The event description before provides details of such cases. Members Members Description 5.9.8.4.2.9 USB_HOST_TPL_FLAGS Enumeration C typedef enum { TPL_FLAG_VID_PID = 0x1, TPL_FLAG_CLASS_SUBCLASS_PROTOCOL = 0x2 } USB_HOST_TPL_FLAGS; Description USB Host Layer TPL Table Entry Flags This type defines the possible flags that can be used when adding an entry into the TPL table. Using the TPL_FLAG_VID_PID will direct the host layer to match the class driver to the attached device based on the device Vendor ID and the Product ID. Using the TPL_FLAG_CLASS_SUBCLASS_PROTOCOL will direct the host layer to match the class driver to the attached device based on the device class, subclass and protocol fields. Members Members Description TPL_FLAG_VID_PID = 0x1 Match by VID and PID TPL_FLAG_CLASS_SUBCLASS_PROTOCOL = 0x2 Match by Class, Subclass and Protocol Remarks None. 5.9.8.4.2.10 TPL_MATCH_VID_PID Macro C #define TPL_MATCH_VID_PID(vid,pid) Description USB Host Class Driver Match by VID and PID 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4196 This macro when used in the TPL table will direct the Host Layer to match the corresponding class driver by device vendor ID and product ID. The applicaton must set the device member of the TPL table entry to this macro is order to match the attached device to the class driver by device Vendor ID and Product ID. Remarks None. 5.9.8.4.2.11 USB_HOST_0 Macro C #define USB_HOST_0 0 Description Driver USB Host Module Index These constants provide USB Host index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the USB_HOST_Initialize() and USB_HOST_Open() routines to identify the host layer instance in use. 5.9.8.4.2.12 USB_HOST_1 Macro C #define USB_HOST_1 1 Description This is macro USB_HOST_1. 5.9.8.4.2.13 USB_HOST_ENDPOINT_TABLE_SIZE Macro C #define USB_HOST_ENDPOINT_TABLE_SIZE Description USB Host Endpoint Table Size This macro defines the USB Endpoint Table size while running the host layer on PIC32MX devices. The application should allocate a uint8_t type array of this size. The array should be aligned at a 512 byte boundary. Remarks None. 5.9.8.4.2.14 USB_HOST_EVENT_RESPONSE_NONE Macro C #define USB_HOST_EVENT_RESPONSE_NONE Description USB Host Layer Event Handler Response None This is the definition of the USB Host Layer Event Handler Response Type None. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4197 Remarks Intentionally defined to be empty. 5.9.8.5 Files Files Name Description usb_host.h USB HOST Layer Interface Header Description 5.9.8.5.1 usb_host.h USB Host Layer Interface Definition This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB HOST layer. Enumerations Name Description USB_HOST_EVENTS Identifies the possible events that the host layer can generate. USB_HOST_TPL_FLAGS USB Host Layer Target Peripheral List Entry flags Functions Name Description USB_HOST_Close Closes an opened-instance of the USB Host Layer. USB_HOST_Deinitialize Deinitializes the specified instance of the USB Host Layer. USB_HOST_DeviceInformationGet Returns select information about the attached device. USB_HOST_DeviceIsResumed Checks if the attached USB device has been resumed. USB_HOST_DeviceIsSuspended Checks if the attached USB device has been suspended. USB_HOST_DeviceResume Resumes the USB. USB_HOST_DeviceSuspend Suspends the USB. USB_HOST_EventCallBackSet Allows a client to identify an event handling function for the host layer to call back when host layer events are generated. USB_HOST_Initialize Initializes the USB Host layer instance for the specified instance index. USB_HOST_Open Opens the specified Host Layer instance and returns a handle to it USB_HOST_OperationDisable Disabled host operation. USB_HOST_OperationEnable Enables host operation. USB_HOST_OperationIsEnabled Allows the application to check if the host operation is enabled. USB_HOST_Status Gets the current status of the USB Host Layer. USB_HOST_Tasks Maintains the USB Host's state machine. It manages the USB Module driver and responds to USB Module driver events. 5.9 USB Library Help MPLAB Harmony Help USB Host Layer Library 5-4198 Macros Name Description TPL_MATCH_VID_PID This macro when used in the TPL table will direct the Host Layer to match the corresponding class driver by device vendor ID (VID) and product ID (PID). USB_HOST_0 USB Host module index definitions USB_HOST_1 This is macro USB_HOST_1. USB_HOST_ENDPOINT_TABLE_SIZE USB Host Endpoint Table size needed while running the host on PIC32MX devices. USB_HOST_EVENT_RESPONSE_NONE USB Host Layer Event Handler Response Type None. USB_HOST_HANDLE_INVALID Definition of an invalid USB Host Client Handle Structures Name Description USB_DEVICE_INFORMATION Defines the USB Device Information data strucutre. USB_HOST_EVENT_DATA_VBUS_REQUEST_POWER Defines the data returned along with the USB_HOST_EVENT_VBUS_REQUEST_POWER event. USB_HOST_INIT Defines the data required to initialize a USB Host Layer instance. Types Name Description USB_HOST_EVENT_CALLBACK USB Host Event Handler Function Pointer Type. USB_HOST_EVENT_RESPONSE USB Host Event Handler Response Type USB_HOST_HANDLE Handle identifying a client when calling Host layer client functions. File Name usb_host.h Company Microchip Technology Incorported 5.9.9 USB CDC Host Library 5.9.9.1 Introduction Introduces the MPLAB Harmony USB Host CDC Class Driver Library Description The USB Host CDC Class Driver library is a part of the USB Host stack that is available for Microchip family of microcontrollers. This library uses the USB Host Layer to interact with the attached USB CDC device and therefore cannot operate independently of it. Within the USB Host stack, the CDC Class Driver library is responsible for providing the host application with access to the functionality of the attached CDC Device. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4199 The USB Host CDC Class Driver library implementation adheres to revision 1.2 of the USB CDC Specification release. The USB Host CDC Class Driver provides the following features: • Support CDC-ACM devices. • Abstracts CDC function interface details from the application and provides a clear interface to device functions. • Provides functions to send commands such as Set Line Coding , Get Line Coding to the attached CDC Device. • Provides functions to read and write data and request serial line notification from the device. • Generates bus related events to user application and class drivers. • Provides events to indicate completion and status of class driver functions. 5.9.9.2 Release Notes MPLAB Harmony Version: v0.70b USB CDC Host Library Version : 0.01 Alpha Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 5.9.9.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 5.9.9.4 Library Interface 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4200 5.9.9.4.1 Functions Functions Name Description USB_HOST_CDC_BreakSend This function sends a request to the attached to update it's break duration. USB_HOST_CDC_ControlLineStateSet This function sets the state of the control line connecting the host to the device. USB_HOST_CDC_EventHandlerSet This class registers a event handler for the specified CDC class driver instance. USB_HOST_CDC_LineCodingGet This function requests line coding from the attached CDC device. USB_HOST_CDC_LineCodingSet This function sets the line coding of the attached CDC device. USB_HOST_CDC_Read This function reads data from the attached CDC device. USB_HOST_CDC_SerialStateNotificationGet This function requests serial state noitification data from the attached CDC device. USB_HOST_CDC_Write This function writes data to the attached CDC device. Description 5.9.9.4.1.1 USB_HOST_CDC_BreakSend Function C USB_HOST_CDC_RESULT USB_HOST_CDC_BreakSend( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, uint16_t breakDuration ); Description This function sends a request to the attached to update it's break duration. The function schedules a SEND BREAK control transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_SEND_BREAK_COMPLETE event. The CDC Class driver does not support queuing of control transfers. If a control transfer is in progress, this function will return with an error. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. breakDuration Break duration. Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - Another control transfer is in progress and this transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4201 a CDC device associated with it. This can happen if the attached device was disconnected or the set request was called with an CDC class driver instance that was not attached with a CDC device. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Control Line State Set Request. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; uint16_t breakDuration; result = USB_HOST_CDC_BreakSend(USB_HOST_CDC_0, &transferHandle, breakDuration); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the set request can be tracked by using the // USB_HOST_CDC_EVENT_SEND_BREAK_COMPLETE event. 5.9.9.4.1.2 USB_HOST_CDC_ControlLineStateSet Function C USB_HOST_CDC_RESULT USB_HOST_CDC_ControlLineStateSet( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, USB_CDC_CONTROL_LINE_STATE * controlLineState ); Description This function sets the state of the control line connecting the host to the device. The function schedules a SET CONTROL LINE STATE control transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_SET_CONTROL_LINE_STATE_COMPLETE event. The CDC Class driver does not support queuing of control transfers. If a control transfer is in progress, this function will return with an error. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. controlLineState pointer to the buffer containing control line state data to be sent to the device Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - Another control transfer is in progress and this transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the set request was called with an 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4202 CDC class driver instance that was not attached with a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The controlLineState buffer pointer is NULL. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Control Line State Set Request. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; USB_CDC_HOST_CONTROL_LINE_STATE * buffer; result = USB_HOST_CDC_ControlLineStateSet(USB_HOST_CDC_0, &transferHandle, buffer); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the set request can be tracked by using the // USB_HOST_CDC_EVENT_SET_CONTROL_LINE_STATE_COMPLETE event. 5.9.9.4.1.3 USB_HOST_CDC_EventHandlerSet Function C USB_HOST_CDC_RESULT USB_HOST_CDC_EventHandlerSet( USB_HOST_CDC_INDEX index, USB_HOST_CDC_EVENT_HANDLER eventHandler, uintptr_t context ); Description This function registers an application event handler for the specified CDC class driver instance events. The event handler should be registered before the host layer operation is enabled. Preconditions None. Parameters Parameters Description instance Instance of the CDC Class Driver. eventHandler A pointer to event handler function. context Application specific context that is returned in the event handler. Returns USB_HOST_CDC_RESULT_OK - The operation was successful USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The eventHandler parameter is NULL Remarks None. Example // This code snippet shows an example of registering an event handler. Here // the application specifies the context parameter as a pointer to an 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4203 // application object (appObject) that should be associated with this // instance of the CDC class driver. USB_HOST_CDC_RESULT result; USB_HOST_CDC_EVENT_RESPONSE APP_USBHostCDCEventHandler ( USB_HOST_CDC_INDEX instanceIndex , USB_HOST_CDC_EVENT event , void * event, uintptr_t context ) { // Event Handling comes here switch(event) { ... } return(USB_HOST_CDC_EVENT_RESPONSE_NONE); } result = USB_HOST_CDC_EventHandlerSet ( 0 ,&APP_EventHandler, (uintptr_t) &appObject); if(USB_HOST_CDC_RESULT_OK != result) { SYS_ASSERT ( false , "invalid event handler class" ); } 5.9.9.4.1.4 USB_HOST_CDC_LineCodingGet Function C USB_HOST_CDC_RESULT USB_HOST_CDC_LineCodingGet( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, USB_CDC_LINE_CODING * lineCoding ); Description This function requests line coding from the attached CDC device. The function schedules a GET LINE CODING control transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_GET_LINE_CODING_COMPLETE event. When completed, the lineCoding parameter will contain the line coding. The CDC Class driver does not support queuing of control transfers. If a control transfer is in progress, this function will return with an error. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. lineCoding pointer to the buffer where the line coding data will be stored. Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4204 USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - Another control transfer is in progress and this transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the get request was called with an CDC class driver instance that was not attached with a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The lineCoding buffer pointer is NULL. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Get Line Coding Request. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; USB_CDC_LINE_CODING * buffer; result = USB_HOST_CDC_LineCodingGet(USB_HOST_CDC_0, &transferHandle, buffer); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the get request can be tracked by using the // USB_HOST_CDC_EVENT_GET_LINE_CODING_COMPLETE event. 5.9.9.4.1.5 USB_HOST_CDC_LineCodingSet Function C USB_HOST_CDC_RESULT USB_HOST_CDC_LineCodingSet( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, USB_CDC_LINE_CODING * lineCoding ); Description This function sets the line coding of the attached CDC device. The function schedules a SET LINE CODING control transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE event. The lineCoding parameter contain the line coding to be sent to the attached device. The CDC Class driver does not support queuing of control transfers. If a control transfer is in progress, this function will return with an error. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. lineCoding pointer to the buffer containing line coding data to be sent to the device Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4205 USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - Another control transfer is in progress and this transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the set request was called with an CDC class driver instance that was not attached with a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The lineCoding buffer pointer is NULL. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Set Line Coding Request. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; USB_CDC_LINE_CODING * buffer; result = USB_HOST_CDC_LineCodingSet(USB_HOST_CDC_0, &transferHandle, buffer); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the set request can be tracked by using the // USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE event. 5.9.9.4.1.6 USB_HOST_CDC_Read Function C USB_HOST_CDC_RESULT USB_HOST_CDC_Read( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, void * destination, size_t length ); Description This function reads data from the attached CDC device. The function will schedule a read transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_READ_COMPLETE event. Multiple read requests can be queued. In such a case, the transfer handle for each request will be unique. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. dest pointer to the buffer where the read data will be stored. length Amount of data to read (in bytes). 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4206 Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - The transfer queue is full and the requested transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the read function was called with an CDC class driver instance that was not attached to a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The destination buffer pointer is NULL or the length parameter is zero. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver read. In this example, the class driver reads 64 bytes from the // attached device. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; uint8_t buffer[64]; result = USB_HOST_CDC_Read(USB_HOST_CDC_0, &transferHandle, buffer, 64); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the read request can be tracked by using the // USB_HOST_CDC_EVENT_READ_COMPLETE. 5.9.9.4.1.7 USB_HOST_CDC_SerialStateNotificationGet Function C USB_HOST_CDC_RESULT USB_HOST_CDC_SerialStateNotificationGet( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA * dest ); Description This function requests serial state noitification data from the attached CDC device. The function will schedule a read transfer over the CDC notification interface. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_SERIAL_STATE_NOTIFICATION_RECEIVED event. Multiple get requests can be queued. In such a case, the transfer handle for each request will be unique. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4207 dest pointer to the buffer where the serial state notification data should be stored. Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - The transfer queue is full and the requested transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the get request was called with an CDC class driver instance that was not attached with a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The source buffer pointer is NULL. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Serial State Notification Get function. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA * buffer; result = USB_HOST_CDC_SerialStateNotificationGet(USB_HOST_CDC_0, &transferHandle, buffer); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the get request can be tracked by using the // USB_HOST_CDC_EVENT_SERIAL_STATE_NOTIFICATION_RECEIVED. 5.9.9.4.1.8 USB_HOST_CDC_Write Function C USB_HOST_CDC_RESULT USB_HOST_CDC_Write( USB_HOST_CDC_INDEX index, USB_HOST_CDC_TRANSFER_HANDLE * transferHandle, void * source, size_t length ); Description This function writes data to the attached CDC device. The function will schedule a write transfer. If successful, the transferHandle parameter will contain a valid transfer handle, else it will contain USB_HOST_CDC_TRANSFER_HANDLE_INVALID. When completed, the CDC class driver will generate a USB_HOST_CDC_EVENT_WRITE_COMPLETE event. Multiple write requests can be queued. In such a case, the transfer handle for each request will be unique. Preconditions None. Parameters Parameters Description index CDC Class Driver Instance Index where the request should be scheduled. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4208 transferHandle Pointer to USB_HOST_CDC_TRANSFER_HANDLE type of a variable. This will contain a valid transfer handle if the request was successful. source pointer to the buffer containing data to be written to the device. length Amount of data to written (in bytes). Returns USB_HOST_CDC_RESULT_OK - The operation was successful. transferHandle will contain a valid transfer handle. USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID - The specified instance does not exist. USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL - The transfer queue is full and the requested transfer cannot be scheduled. USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY - The specified instance does not have a CDC device associated with it. This can happen if the attached device was disconnected or the write function was called with an CDC class driver instance that was not attached to a CDC device. USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID - The source buffer pointer is NULL or the length parameter is zero. Remarks None. Example // The following code snippet shows an example of scheduling a CDC Class // Driver Write. In this example, the class driver writes 64 bytes to the // attached device. USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_RESULT result; uint8_t buffer[64]; result = USB_HOST_CDC_Write(USB_HOST_CDC_0, &transferHandle, buffer, 64); if(USB_HOST_CDC_RESULT_OK != result) { // Error handling here } // The completion of the write request can be tracked by using the // USB_HOST_CDC_EVENT_WRITE_COMPLETE. 5.9.9.4.2 Data Types and Constants Enumerations Name Description USB_HOST_CDC_EVENT Identifies the possible events that the CDC Class Driver can generate. USB_HOST_CDC_RESULT USB Host CDC Class Driver CDC Result enumeration. USB_HOST_CDC_TRANSFER_STATUS USB Host CDC Class Driver Transfer Status enumeration. Macros Name Description USB_HOST_CDC_EVENT_RESPONSE_NONE USB Host CDC Class Driver Event Handler Response Type None. USB_HOST_CDC_TRANSFER_HANDLE_INVALID USB Host CDC Class Driver Invalid Transfer Handle Definition. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4209 Structures Name Description USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_READ_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE USB Host CDC Class Driver Event Data. Types Name Description USB_HOST_CDC_TRANSFER_HANDLE USB Host CDC Class Driver Transfer Handle USB_HOST_CDC_EVENT_HANDLER USB Host CDC Class Driver Event Handler Function Pointer Type. USB_HOST_CDC_EVENT_RESPONSE USB Host CDC Class Driver Event Callback Response Type USB_HOST_CDC_INDEX USB Host CDC Class Driver Index USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA USB Host Serial State Notification Data Type. USB_HOST_CDC_CONTROL_LINE_STATE USB Host Control Line State Data Type. Description 5.9.9.4.2.1 USB_HOST_CDC_EVENT Enumeration C typedef enum { USB_HOST_CDC_EVENT_READ_COMPLETE, USB_HOST_CDC_EVENT_WRITE_COMPLETE, USB_HOST_CDC_EVENT_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_ATTACH, USB_HOST_CDC_EVENT_DETACH } USB_HOST_CDC_EVENT; Description CDC Class Driver Events This enumeration identifies the possible events that the CDC Class Driver can generate. The application should register an event handler using the USB_HOST_CDC_EventHandlerSet() function to receive CDC Class Driver events. An event may have data associated with it. Events that are generated due to a transfer of data between the host and device are accompanied by data structures that provide the status of the transfer termination. For example, the 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4210 USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE event is accompanied by a pointer to a USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE data structure. The transferStatus member of this data structure indicates the success or failure of the transfer. A transfer may fail due to device not responding on the bus, if the device stalls any stages of the transfer or due to NAK timeouts. The event description provides details on the nature of the event and the data that is associated with the event. The following code snippet shows an example event handling scheme for // This code snippet shows an example event handling scheme for // CDC Class Driver events. USB_HOST_CDC_EVENT_RESPONSE APP_USBHostCDCEventHandler ( USB_HOST_CDC_INDEX index, USB_HOST_CDC_EVENT event, void * eventData, uintptr_t context ) { uint8_t deviceAddress; USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE * setLineCodingEventData; USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE * getLineCodingEventData; USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE * setControlLineStateEventData; USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE * sendBreakEventData; USB_HOST_CDC_EVENT_DATA_READ_COMPLETE * readCompleteEventData; USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE * writeCompleteEventData; USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED * serialStateNotificationEventData; switch(event) { case USB_HOST_CDC_EVENT_ATTACH: // The event data in this case is the address of the // attached device. deviceAddress = (uint8_t *)eventData; break; case USB_HOST_CDC_EVENT_DETACH: // This means the device was detached. There is no event data // associated with this event. break; case USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE: // This means the Set Line Coding request completed. We can // find out if the request was successful. setLineCodingEventData = (USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE *)eventData; if(setLineCodingEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } break; case USB_HOST_CDC_EVENT_GET_LINE_CODING_COMPLETE: // This means the Get Line Coding request completed. We can // find out if the request was successful. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4211 getLineCodingEventData = (USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE *)eventData; if(getLineCodingEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } case USB_HOST_CDC_EVENT_SET_CONTROL_LINE_STATE_COMPLETE: // This means the Set Control Line State request completed. We can // find out if the request was successful. setControlLineStateEventData = (USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE *)eventData; if(setControlLineStateEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } break; case USB_HOST_CDC_EVENT_SEND_BREAK_COMPLETE: // This means the Send Break request completed. We can // find out if the request was successful. sendBreakEventData = (USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE *)eventData; if(sendBreakEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } break; case USB_HOST_CDC_EVENT_WRITE_COMPLETE: // This means the Write request completed. We can // find out if the request was successful. writeCompleteEventData = (USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE *)eventData; if(writeCompleteEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } break; case USB_HOST_CDC_EVENT_READ_COMPLETE: // This means the Read request completed. We can // find out if the request was successful. readCompleteEventData = (USB_HOST_CDC_EVENT_DATA_READ_COMPLETE *)eventData; if(readCompleteEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4212 // error. } break; case USB_HOST_CDC_EVENT_SERIAL_STATE_NOTIFICATION_RECEIVED: // This means the Serial State Notification request completed. // We can find out if the request was successful. serialStateNotificationEventData = (USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED *)eventData; if(serialStateNotificationEventData->transferStatus == USB_HOST_CDC_TRANSFER_STATUS_ERROR) { // This means there transfer terminated because of an // error. } break; default: break; } return(USB_HOST_CDC_EVENT_RESPONSE_NONE); } Members Members Description USB_HOST_CDC_EVENT_READ_COMPLETE This event occurs when a CDC Class Driver Read operation has completed i.e when the data has been received from the connected CDC device. This event is generated after the application calls the USB_HOST_CDC_Read() function. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_READ_COMPL ETE structure. This contains details about the transfer handle associated with this read request, the amount of data read and the termination status of the read request. USB_HOST_CDC_EVENT_WRITE_COMPLETE This event occurs when a CDC Class Driver Write operation has completed i.e when the data has been written to the connected CDC device. This event is generated after the application calls the USB_HOST_CDC_Wrte() function. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_WRITE_COMPL ETE structure. This contains details about the transfer handle associated with this write request, the amount of data written and the termination status of the write request. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4213 USB_HOST_CDC_EVENT_SERIAL_STATE_NOTIFICATION_RECEIVED This event occurs when a CDC Class Driver Serial State Notification Get operation has completed. This event is generated after the application calls the USB_HOST_CDC_SerialStateNotificationGet() and the device sends a serial state notification to the host. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_SERIAL_STATE _NOTIFICATION_RECEIVED structure. This contains details about the transfer handle associated with this request, the amount of data received and the termination status of the get request. USB_HOST_CDC_EVENT_GET_LINE_CODING_COMPLETE This event occurs when a CDC Class Driver Get Line Coding request has completed. This event is generated after the application calls the USB_HOST_CDC_LineCodingGet() function and the device sends the line coding to the host. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_GET_LINE_CO DING_COMPLETE structure. This contains details about the transfer handle associated with this request, the amount of data received and the termination status of the get request. USB_HOST_CDC_EVENT_SET_LINE_CODING_COMPLETE This event occurs when a CDC Class Driver Set Line Coding request has completed. This event is generated after the application calls the USB_HOST_CDC_LineCodingSet() function and the device either acknowledged or stalled the request. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_SET_LINE_COD ING_COMPLETE structure. This contains details about the transfer handle associated with this request, the amount of data sent and the termination status of the set request. USB_HOST_CDC_EVENT_SET_CONTROL_LINE_STATE_COMPLETE This event occurs when a CDC Class Driver Set Control Line State request has completed. This event is generated after the application calls the USB_HOST_CDC_ControlLineStateSet() function and the device has either acknowledged or stalled the request. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_SET_CONTROL _LINE_STATE_COMPLETE structure. This contains details about the transfer handle associated with this request, the amount of data sent and the termination status of the set request. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4214 USB_HOST_CDC_EVENT_SEND_BREAK_COMPLETE This event occurs when a CDC Class Driver Send Break request has completed. This event is generated after the application calls the USB_HOST_CDC_BreakSend() function and the device has either acknowledged or stalled the request. The eventData parameter in the event call back function will be of a pointer to a USB_HOST_CDC_EVENT_DATA_SET_CONTROL _LINE_STATE_COMPLETE structure. This contains details about the transfer handle associated with this request, the amount of data sent and the termination status of the set request. USB_HOST_CDC_EVENT_ATTACH This event occurs when the host layer has successfully attached the CDC Class Driver instance to the attached USB CDC device. The event also indicates that the class driver is fully initialized and is ready to accept command and data transfer requests from the application. The eventData parameter should be interpreted as a uint8_t pointer to the device address. USB_HOST_CDC_EVENT_DETACH This event occurs when host layer has detached the CDC class driver instance from a USB CDC device. This can happen if the device itself was detached, or if the device configuration was changed. There is no event data associated with this event. Remarks None. 5.9.9.4.2.2 USB_HOST_CDC_RESULT Enumeration C typedef enum { USB_HOST_CDC_RESULT_OK, USB_HOST_CDC_RESULT_ERROR_TRANSFER_QUEUE_FULL, USB_HOST_CDC_RESULT_ERROR_INSTANCE_INVALID, USB_HOST_CDC_RESULT_ERROR_INSTANCE_NOT_READY, USB_HOST_CDC_RESULT_ERROR_PARAMETER_INVALID } USB_HOST_CDC_RESULT; Description USB Host CDC Class Driver Result enumeration. This enumeration lists the possible USB Host CDC Class Driver operation results. These values are returned by CDC Class Driver functions. Members Members Description USB_HOST_CDC_RESULT_OK The operation was successful 5.9.9.4.2.3 USB_HOST_CDC_TRANSFER_HANDLE Type C typedef uintptr_t USB_HOST_CDC_TRANSFER_HANDLE; 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4215 Description USB Host CDC Class Driver Transfer Handle This is returned by the CDC Class driver command and data transfer routines and should be used by the application to track the transfer especially in cases where transfers are queued. Remarks None. 5.9.9.4.2.4 USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.5 USB_HOST_CDC_EVENT_DATA_READ_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4216 USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.6 USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4217 USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.7 USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.8 USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4218 USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.9 USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4219 USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.10 USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE Structure C typedef struct { USB_HOST_CDC_TRANSFER_HANDLE transferHandle; USB_HOST_CDC_TRANSFER_STATUS transferStatus; size_t length; } USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE; Description USB Host CDC Class Driver Event Data. This data type defines the data structure returned by the driver along with the following events: USB_HOST_CDC_EVENT_DATA_READ_COMPLETE, USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE, USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE, USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE, USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED Members Members Description USB_HOST_CDC_TRANSFER_HANDLE transferHandle; Transfer handle of this transfer USB_HOST_CDC_TRANSFER_STATUS transferStatus; Termination transfer status size_t length; Amount of data transferred Remarks None. 5.9.9.4.2.11 USB_HOST_CDC_EVENT_HANDLER Type C typedef USB_HOST_CDC_EVENT_RESPONSE (* USB_HOST_CDC_EVENT_HANDLER)(USB_HOST_CDC_INDEX index, USB_HOST_CDC_EVENT event, void * eventData, uintptr_t context); Description USB Host CDC Class Driver Event Handler Function Pointer Type. This data type defines the required function signature of the USB Host CDC Class Driver event handling callback function. The application must register a pointer to a CDC Class Driver events handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive event call backs from the CDC Class 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4220 Driver. The class driver will invoke this function with event relevant parameters. The description of the event handler function parameters is given here. instanceIndex - Instance index of the CDC Class Driver that generated the event. event - Type of event generated. eventData - This parameter should be type casted to a event specific pointer type based on the event that has occurred. Refer to the USB_HOST_CDC_EVENT enumeration description for more details. context - Value identifying the context of the application that was registered along with the event handling function. Remarks None. 5.9.9.4.2.12 USB_HOST_CDC_EVENT_RESPONSE Type C typedef void USB_HOST_CDC_EVENT_RESPONSE; Description USB Host CDC Class Driver Event Handler Response Type This is the return type of the CDC Class Driver event handler. Remarks None. 5.9.9.4.2.13 USB_HOST_CDC_INDEX Type C typedef uintptr_t USB_HOST_CDC_INDEX; Description USB Host CDC Class Driver Index This uniquely identifies a CDC Class Driver instance. Remarks None. 5.9.9.4.2.14 USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA Type C typedef USB_CDC_SERIAL_STATE USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA; Description USB Host CDC Serial State Notification Data Type. This defines the data type for the CDC Serial State. This data is requested from the device over the CDC notification interface. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4221 5.9.9.4.2.15 USB_HOST_CDC_TRANSFER_STATUS Enumeration C typedef enum { USB_HOST_CDC_TRANSFER_STATUS_OK, USB_HOST_CDC_TRANSFER_STATUS_ERROR } USB_HOST_CDC_TRANSFER_STATUS; Description USB Host CDC Class Driver Transfer Status. This enumeration lists the possible termination status of CDC class driver transfers. This information is a part of the event data that is returned along with transfer related events. Members Members Description USB_HOST_CDC_TRANSFER_STATUS_OK The transfer completed successfully. In case of read transfers, either the requested amount of data was received or the device sent less data USB_HOST_CDC_TRANSFER_STATUS_ERROR The transfer terminated due to an error. The error could be due to device malfunction on the bus, a NAK timeout occurred or the device stalled the request Remarks None. 5.9.9.4.2.16 USB_HOST_CDC_EVENT_RESPONSE_NONE Macro C #define USB_HOST_CDC_EVENT_RESPONSE_NONE Description USB Host CDC Class Driver Event Handler Response None This is the definition of the CDC Class Driver Event Handler Response Type none. Remarks Intentionally defined to be empty. 5.9.9.4.2.17 USB_HOST_CDC_TRANSFER_HANDLE_INVALID Macro C #define USB_HOST_CDC_TRANSFER_HANDLE_INVALID ((USB_HOST_CDC_TRANSFER_HANDLE)(-1)) Description USB Host CDC Class Driver Invalid Transfer Handle Definition This definition defines a USB Host CDC Class Driver Invalid Transfer Handle. A Invalid Transfer Handle is returned by the CDC Class Driver data and command transfer routines when the request was not successful. Remarks None. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4222 5.9.9.4.2.18 USB_HOST_CDC_CONTROL_LINE_STATE Type C typedef USB_CDC_CONTROL_LINE_STATE USB_HOST_CDC_CONTROL_LINE_STATE; Description USB Host CDC Control Line State Data Type. This defines the data type for the CDC Control Line State. This data is requested from the device over the CDC control interface. Remarks None. 5.9.9.5 Files Files Name Description usb_host_cdc.h USB Host CDC Class Driver Interface Header Description 5.9.9.5.1 usb_host_cdc.h USB Host CDC Class Driver Interface Definition This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the USB Host CDC Class Driver. Enumerations Name Description USB_HOST_CDC_EVENT Identifies the possible events that the CDC Class Driver can generate. USB_HOST_CDC_RESULT USB Host CDC Class Driver CDC Result enumeration. USB_HOST_CDC_TRANSFER_STATUS USB Host CDC Class Driver Transfer Status enumeration. Functions Name Description USB_HOST_CDC_BreakSend This function sends a request to the attached to update it's break duration. USB_HOST_CDC_ControlLineStateSet This function sets the state of the control line connecting the host to the device. USB_HOST_CDC_EventHandlerSet This class registers a event handler for the specified CDC class driver instance. USB_HOST_CDC_LineCodingGet This function requests line coding from the attached CDC device. USB_HOST_CDC_LineCodingSet This function sets the line coding of the attached CDC device. USB_HOST_CDC_Read This function reads data from the attached CDC device. USB_HOST_CDC_SerialStateNotificationGet This function requests serial state noitification data from the attached CDC device. USB_HOST_CDC_Write This function writes data to the attached CDC device. 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4223 Macros Name Description USB_HOST_CDC_EVENT_RESPONSE_NONE USB Host CDC Class Driver Event Handler Response Type None. USB_HOST_CDC_TRANSFER_HANDLE_INVALID USB Host CDC Class Driver Invalid Transfer Handle Definition. Structures Name Description USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_READ_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICATION_RECEIVED USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STATE_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMPLETE USB Host CDC Class Driver Event Data. USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE USB Host CDC Class Driver Event Data. Types Name Description USB_HOST_CDC_CONTROL_LINE_STATE USB Host Control Line State Data Type. USB_HOST_CDC_EVENT_HANDLER USB Host CDC Class Driver Event Handler Function Pointer Type. USB_HOST_CDC_EVENT_RESPONSE USB Host CDC Class Driver Event Callback Response Type USB_HOST_CDC_INDEX USB Host CDC Class Driver Index USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA USB Host Serial State Notification Data Type. USB_HOST_CDC_TRANSFER_HANDLE USB Host CDC Class Driver Transfer Handle File Name usb_host_cdc.h Company Microchip Technology Incorported 5.9 USB Library Help MPLAB Harmony Help USB CDC Host Library 5-4224 6 Third-Party Library Help 6 MPLAB Harmony Help 6-4225 6.1 Third-Party Library Overview 6.1.1 Introduction This topic provides an overview of the Third-Party Libraries in MPLAB Harmony. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 6.1.2 Release Notes MPLAB Harmony Version: v0.70b Release Date: 18Nov2013 New This Release: Nothing to report in this release. Known Issues: Nothing to report in this release. 6.1.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 6.1 Third-Party Library Overview MPLAB Harmony Help SW License Agreement 6-4226 7 Board Support Packages Help 7 MPLAB Harmony Help 7-4227 7.1 Board Support Packages Overview 7.1.1 Introduction This topic provides information for the Board Support Package (BSP) in MPLAB Harmony. Description A Board Support Package (BSP) provides code and configuration items necessary to support board-specific hardware. A BSP may be provided for Microchip development or demo boards or may be defined by customers for their own boards (which is recommended to make it easy to support multiple boards in the future, even of only a single board exists when a project is first created). A BSP may contain a board-specific configuration header ("bsp_config.h" and possibly others), a board-specific system initialization file ("bsp_sys_init.c"), a file containing board-specific ISR implementations ("bsp_sys_int.c"), a board-specific system "tasks" routine (implemented in a "bsp_sys_tasks.c" file), and even board-specific driver implementations (each with it's own directory). Everything that is contained within a BSP can be either used by or replaced by application specific items if desired. For example, the application may configure the system initialization routine ("SYS_Initialize") to directly call a board-specific initialization routine (called "BSP_Initialize") or it can use the BSP-specific initialization routine as an example from which to start developing application-specific board initialization code. Normally, Microchip demo applications will use the BSP code directly to avoid duplication of board-specific code. 7.1.2 Configuration This topic describes the BSP configuration header options. Description A BSP configuration header defines configuration options that are "fixed" by the board. That is, any option that cannot be changed unless the hardware on the board is changed may be defined in a BSP's "bsp_config.h" file (or in a file included by it). This will normally include board parameters such as the oscillator frequency for a fixed-frequency oscillator or convenient names by which board-specific features may be identified (such as which pins connect to switches or LEDs). It may also include options for libraries and drivers that can be used by an application running on that board that are "fixed" by the hardware on the board. However, it may not define all options necessary for a library, only the board-specific options. Application-specific headers may include BSP-specific headers to define the board-hardware-specific options or it may define them itself, thus overriding a BSP's options. 7.1 Board Support Packages Overview MPLAB Harmony Help Board Drivers 7-4228 7.1.3 Board Drivers This topic describes the board drivers of the BSP. Description Some peripheral hardware may not be directly built into the microcontroller. For example, devices such as external CODECs, EEPROMs, etc, may be built onto a board and will not be available as peripherals in the microcontroller. Devices such as these still need device drivers and these drivers still need to follow the MPLAB harmony driver architecture. However, they will not normally be provided as part of the standard MPLAB Harmony driver set for Microchip microcontrollers. Instead, all files related to drivers for devices mounted on Microchip demo and development boards will be contained within the "bsp/drivers" directory. They will otherwise, follow the same rules as all other MPLAB Harmony device drivers. 7.1.4 System Initialization This topic describes BSP system initialization. Description Normally, an application will define or configure the “SYS_Initialize” routine in any way that is necessary to initialize the system as desired. However, board-specific initialization may be necessary. When it is, a BSP must implement a board-specific initialization routine called "BSP_Initialize" that performs any necessary low-level board initialization necessary to support normal system operation. The "BSP_Initialize" routine may have an associated "initialization" structure, a pointer to which may be passed in as a parameter, to define any application-specific parameters necessary to initialize any low-level board hardware. Low-level board hardware may be things like power subsystems, bus enable signals, or other items necessary for basic board operations. It should not include the initialization of board-specific drivers as that is done separately. However, a BSP may define initialization data used to initialize board-specific drivers if that data is "fixed" by the board. 7.1.5 ISR Implementation This topic describes BSP ISR implentation. Description Like the SYS_Initialize routine, an ISR may be implemented by an application in any way necessary to support the desired system behavior. Unlike the initialization support, a BSP-specific ISR implementation should never be called by the application-specific ISR implementation. It must either be used exactly as defined by the BSP or the application's system interrupt support must define its own ISR implementation. If the application defines its own implementation, the BSP ISR can be used as an example. 7.1 Board Support Packages Overview MPLAB Harmony Help ISR Implementation 7-4229 7.2 Explorer 16 PIC32MX795F512L BSP Library 7.2.1 Introduction Explorer 16 PIC32MX795F512L BSP Library for Microchip Microcontrollers This library provides a low-level abstraction of the Explorer 16 PIC32MX795F512L BSP Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 7.2.2 Release Notes MPLAB Harmony Version: v0.70b Explorer 16 PIC32MX795F512L BSP Library Version : 0.51.03b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 7.2.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS 7.2 Explorer 16 PIC32MX795F512L BSP MPLAB Harmony Help SW License Agreement 7-4230 BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 7.2.4 Using the Library This topic describes the basic architecture of the Explorer 16 PIC32MX795F512L BSP Library and provides information and examples on how to use it. Interface Header File: bsp_config.h The interface to the Explorer 16 PIC32MX795F512L BSP library is defined in the "bsp_config.h" header file. Any C language source (.c) file that uses the Explorer 16 PIC32MX795F512L BSP library should include "bsp_config.h". 7.2.4.1 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the Explorer 16 PIC32MX795F512L BSP Library module. Library Interface Section Description Initialization Functions This section provides initialization functions. LED Control Functions This section provides functions for LED Control. Other Functions This section provides additional functions for this API. Data Types and Constants This section provides various definitions describing this API. 7.2 Explorer 16 PIC32MX795F512L BSP MPLAB Harmony Help Using the Library 7-4231 7.3 PIC32 USB Starter Kit II BSP Library 7.3.1 Introduction PIC332 USB Starter Kit II BSP Library for Microchip Microcontrollers This library provides a low-level abstraction of the PIC32 USB Starter Kit II Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 7.3.2 Release Notes MPLAB Harmony Version: v0.70b PIC32 USB Starter Kit II BSP Library Version : 0.51.03b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 7.3.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR 7.3 PIC32 USB Starter Kit II BSP Library MPLAB Harmony Help SW License Agreement 7-4232 CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 7.3.4 Using the Library This topic describes the basic architecture of the PIC32 USB Starter Kit II BSP Library and provides information and examples on how to use it. Interface Header File: bsp_config.h The interface to the PIC32 USB Starter Kit II BSP Library is defined in the "bsp_config.h" header file. Any C language source (.c) file that uses the PIC32 USB Starter Kit II BSP Library should include "bsp_config.h". 7.3.4.1 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the PIC32 USB Starter Kit II Library module. Library Interface Section Description Initialization Functions This section provides initialization functions. LED Control Functions This section provides functions for LED Control. Other Functions This section provides additional functions for this API. Data Types and Constants This section provides various definitions describing this API. 7.3 PIC32 USB Starter Kit II BSP Library MPLAB Harmony Help Using the Library 7-4233 7.4 PIC32MX USB Audio BSP Library 7.4.1 Introduction PIC32MX USB Audio BSP Library for Microchip Microcontrollers This library provides a low-level abstraction of the PIC32MX USB Audio BSP Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be provided in a future release of MPLAB Harmony. 7.4.2 Release Notes MPLAB Harmony Version: v0.70b PIC32MX USB Audio BSP Library Version : 0.51.03b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 7.4.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR 7.4 PIC32MX USB Audio BSP Library MPLAB Harmony Help SW License Agreement 7-4234 CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 7.4.4 Using the Library This topic describes the basic architecture of the PIC32MX USB Audio BSP Library and provides information and examples on how to use it. Interface Header File: bsp_config.h The interface to the PIC32MX USB Audio BSP Library is defined in the "bsp_config.h" header file. Any C language source (.c) file that uses the PIC32MX USB Audio BSP Library should include "bsp_config.h". 7.4.4.1 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the PIC32MX USB Audio BSP Library module. Library Interface Section Description Initialization Functions This section provides initialization functions. LED Control Functions This section provides functions for LED Control. Other Functions This section provides additional functions for this API. Data Types and Constants This section provides various definitions describing this API. 7.4 PIC32MX USB Audio BSP Library MPLAB Harmony Help Using the Library 7-4235 7.5 PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library 7.5.1 Introduction PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library for Microchip Microcontrollers This library provides a low-level abstraction of the PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library that is available on the Microchip family of microcontrollers with a convenient C language interface. It can be used to simplify low-level access to the module without the necessity of interacting directly with the module's registers, there by hiding differences from one microcontroller variant to another. Description Note: This information was not available at time of release and will be added in a future release of MPLAB Harmony. 7.5.2 Release Notes MPLAB Harmony Version: v0.70b PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library Version : 0.51.03b Release Date: 18Nov2013 New This Release: This is the first release of the library. The interface can change in the beta and\or 1.0 release. Known Issues: Nothing to report in this release. 7.5.3 SW License Agreement (c) 2013 Microchip Technology Inc. Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and its licensors, and is protected under applicable copyright laws. All rights reserved. SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, 7.5 PIC32MZ Embedded Connectivity (EC) MPLAB Harmony Help SW License Agreement 7-4236 FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FOR ANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TO YOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMS BY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY OR CONTRIBUTION, OR OTHER SIMILAR COSTS. To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you have paid directly to Microchip to use this software. MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS. 7.5.4 Using the Library This topic describes the basic architecture of the PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library and provides information and examples on how to use it. Interface Header File: bsp_config.h The interface to the PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library is defined in the "bsp_config.h" header file. Any C language source (.c) file that uses the PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library should include "bsp_config.h". 7.5.4.1 Library Overview The library interface routines are divided into various sub-sections, each of sub-section addresses one of the blocks or the overall operation of the PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library module. Library Interface Section Description Initialization Functions This section provides initialization functions. LED Control Functions This section provides functions for LED Control. Other Functions This section provides additional functions for this API. Data Types and Constants This section provides various definitions describing this API. 7.5 PIC32MZ Embedded Connectivity (EC) MPLAB Harmony Help Using the Library 7-4237 7.6 Library Interface 7.6.1 Initialization Functions Functions Name Description BSP_Initialize Performs the necessary actions to initialize a board Description 7.6.1.1 BSP_Initialize Function C void BSP_Initialize(); Description This routine performs the neccassary actions to initialize a board Preconditions None Returns None 7.6.2 LED Control Functions Functions Name Description BSP_SwitchOFFLED Turns OFF specified LED on the board. BSP_SwitchONLED Turns ON specified LED on the board. BSP_ToggleLED Toggles specified LED on the board. BSP_SwitchToggleLED Toggles the onboard LED. Description 7.6 Library Interface MPLAB Harmony Help LED Control Functions 7-4238 7.6.2.1 BSP_SwitchOFFLED Function C void BSP_SwitchOFFLED( BSP_LED led ); Description This fucntion turns OFF specified LED on the board. Preconditions BSP should be initialized by calling void BSP_Initialize(void) function. Parameters Parameters Description led LED ID as specified by BSP_LED enum. Returns None 7.6.2.2 BSP_SwitchONLED Function C void BSP_SwitchONLED( BSP_LED led ); Description This fucntion turns ON specified LED on the board. Preconditions BSP should be initialized by calling void BSP_Initialize(void) function. Parameters Parameters Description led LED ID as specified by BSP_LED enum. Returns None 7.6.2.3 BSP_ToggleLED Function C void BSP_ToggleLED( BSP_LED led ); Description This fucntion Toggles specified LED on the board. 7.6 Library Interface MPLAB Harmony Help LED Control Functions 7-4239 Preconditions BSP should be initialized by calling void BSP_Initialize(void) function. Parameters Parameters Description led LED ID as specified by BSP_LED enum. Returns None 7.6.2.4 BSP_SwitchToggleLED Function C void BSP_SwitchToggleLED( BSP_LED led ); Description This routine toggles the onboard LED. 7.6.3 Other Functions Functions Name Description SYSTEMConfigPerformance Configures the system cache and flash wait states for maximum performance. BSP_ReadCoreTimer Returns the current core timer value. BSP_ReadSwitch Reads the switch state. Description 7.6.3.1 SYSTEMConfigPerformance Function C unsigned int SYSTEMConfigPerformance( unsigned int sys_clock ); Description This function configures the system cache and flash wait states for maximum performance. Preconditions None 7.6 Library Interface MPLAB Harmony Help Other Functions 7-4240 Parameters Parameters Description sys_clock Value of system clock 7.6.3.2 BSP_ReadCoreTimer Function C uint32_t BSP_ReadCoreTimer(); Description Returns the current core timer value. Preconditions None 7.6.3.3 BSP_ReadSwitch Function C BSP_SWITCH_STATE BSP_ReadSwitch( BSP_SWITCH bspSwitch ); Description Reads the switch state. Preconditions None Parameters Parameters Description bspSwitch Switch ID as specified by BSP_SWITCH enum. Return Values Return Values Description BSP_SWITCH_STATE_PRESSED Switch is pressed. BSP_SWITCH_STATE_RELEASED Switch is not pressed. 7.6.4 Data Types and Constants Enumerations Name Description BSP_LED Holds LED numbers. BSP_SWITCH Holds Switch numbers. BSP_SWITCH_STATE Holds Switch status. 7.6 Library Interface MPLAB Harmony Help Data Types and Constants 7-4241 Macros Name Description BSP_ANALOG_PIN Defines the constant which identifies analog pin BSP_DIGITAL_PIN Defines the constant which identifies digital pin BSP_INPUT Defines the constant which identifies input BSP_OUTPUT Defines the constant which identifies output Description 7.6.4.1 BSP_ANALOG_PIN Macro C #define BSP_ANALOG_PIN PORTS_PIN_MODE_ANALOG Description analog Pin Constant This constant identifies analog pin 7.6.4.2 BSP_DIGITAL_PIN Macro C #define BSP_DIGITAL_PIN PORTS_PIN_MODE_DIGITAL Description Digital Pin Constant This constant identifies digital pin 7.6.4.3 BSP_INPUT Macro C #define BSP_INPUT 1 Description Input Constant This constant identifies input 7.6.4.4 BSP_OUTPUT Macro C #define BSP_OUTPUT 0 Description Output Constant 7.6 Library Interface MPLAB Harmony Help Data Types and Constants 7-4242 This constant identifies output 7.6.4.5 BSP_LED Enumeration C typedef enum { LED_3 = PORTS_BIT_POS_0, LED_4 = PORTS_BIT_POS_1, LED_5 = PORTS_BIT_POS_2, LED_6 = PORTS_BIT_POS_3, LED_7 = PORTS_BIT_POS_4, LED_8 = PORTS_BIT_POS_5, LED_9 = PORTS_BIT_POS_6, LED_10 = PORTS_BIT_POS_7 } BSP_LED; Description LED Number. This enumeration defines the LED numbers. Members Members Description LED_3 = PORTS_BIT_POS_0 LED 3 LED_4 = PORTS_BIT_POS_1 LED 4 LED_5 = PORTS_BIT_POS_2 LED 5 LED_6 = PORTS_BIT_POS_3 LED 6 LED_7 = PORTS_BIT_POS_4 LED 7 LED_8 = PORTS_BIT_POS_5 LED 8 LED_9 = PORTS_BIT_POS_6 LED 9 LED_10 = PORTS_BIT_POS_7 LED 10 Remarks None. 7.6.4.6 BSP_SWITCH Enumeration C typedef enum { SWITCH_3 = PORTS_BIT_POS_6, SWITCH_4 = PORTS_BIT_POS_13, SWITCH_5 = PORTS_BIT_POS_7, SWITCH_6 = PORTS_BIT_POS_7 } BSP_SWITCH; Description BSP Switch. This enumeration defines the Switch numbers. 7.6 Library Interface MPLAB Harmony Help Data Types and Constants 7-4243 Members Members Description SWITCH_3 = PORTS_BIT_POS_6 SWITCH 3 SWITCH_4 = PORTS_BIT_POS_13 SWITCH 4 SWITCH_5 = PORTS_BIT_POS_7 SWITCH 5 SWITCH_6 = PORTS_BIT_POS_7 SWITCH 6 Remarks None. 7.6.4.7 BSP_SWITCH_STATE Enumeration C typedef enum { BSP_SWITCH_STATE_PRESSED = 0, BSP_SWITCH_STATE_RELEASED = 1 } BSP_SWITCH_STATE; Description BSP Switch state. This enumeration defines the switch state. Members Members Description BSP_SWITCH_STATE_PRESSED = 0 Switch pressed BSP_SWITCH_STATE_RELEASED = 1 Switch not pressed Remarks None. 7.6 Library Interface MPLAB Harmony Help Data Types and Constants 7-4244 7.7 Files Files Name Description bsp_config.h Board support configuration file. Description 7.7.1 bsp_config.h Board support configuration file. This contains all the configuration that is required to be done for the application running on PIC32 USB starter kit Enumerations Name Description BSP_LED Holds LED numbers. BSP_SWITCH Holds Switch numbers. BSP_SWITCH_STATE Holds Switch status. Functions Name Description BSP_Initialize Performs the necessary actions to initialize a board BSP_ReadCoreTimer Returns the current core timer value. BSP_ReadSwitch Reads the switch state. BSP_SwitchOFFLED Turns OFF specified LED on the board. BSP_SwitchONLED Turns ON specified LED on the board. BSP_SwitchToggleLED Toggles the onboard LED. BSP_ToggleLED Toggles specified LED on the board. SYSTEMConfigPerformance Configures the system cache and flash wait states for maximum performance. Macros Name Description BSP_ANALOG_PIN Defines the constant which identifies analog pin BSP_DIGITAL_PIN Defines the constant which identifies digital pin BSP_INPUT Defines the constant which identifies input BSP_OUTPUT Defines the constant which identifies output File Name bsp_config.h Company Microchip Technology Incorported 7.7 Files MPLAB Harmony Help bsp_config.h 7-4245 8 Symbol Reference 8 MPLAB Harmony Help 8-4246 8.1 Macros Macros Name Description DRV_ETHMAC_INDEX_0 Ethernet driver index definitions. DRV_ETHMAC_INDEX_COUNT Number of valid Ethernet driver indices. 8.1.1 DRV_ETHMAC_INDEX_0 Macro C #define DRV_ETHMAC_INDEX_0 0 Description Ethernet Driver Module Index Numbers These constants provide Ethernet driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_ETHMAC_Initialize and DRV_ETHMAC_Open routines to identify the driver instance in use. 8.1.2 DRV_ETHMAC_INDEX_COUNT Macro C #define DRV_ETHMAC_INDEX_COUNT ETH_NUMBER_OF_MODULES Description Ethernet Driver Module Index Count This constant identifies number of valid Ethernet driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. 8.1 Macros MPLAB Harmony Help DRV_ETHMAC_INDEX_COUNT Macro 8-4247 Index _ _LIBQ_Q15_cos_Q2_13 function 5-1287 _LIBQ_Q15_sin_Q2_13 function 5-1286 _LIBQ_Q15FromFloat function 5-1298 _LIBQ_Q15FromString function 5-1301 _LIBQ_Q15Rand function 5-1297 _LIBQ_Q16_tan_Q2_29 function 5-1288 _LIBQ_Q16Div function 5-1281 _LIBQ_Q16Exp function 5-1285 _LIBQ_Q16Power function 5-1284 _LIBQ_Q16Sqrt function 5-1281 _LIBQ_Q2_13_acos_Q15 function 5-1292 _LIBQ_Q2_13_asin_Q15 function 5-1289 _LIBQ_Q2_13_atan_Q7_8 function 5-1294 _LIBQ_Q2_13_atan2_Q7_8 function 5-1295 _LIBQ_Q2_29_acos_Q31 function 5-1292 _LIBQ_Q2_29_acos_Q31_Fast function 5-1293 _LIBQ_Q2_29_asin_Q31 function 5-1290 _LIBQ_Q2_29_asin_Q31_Fast function 5-1291 _LIBQ_Q2_29_atan_Q16 function 5-1294 _LIBQ_Q2_29_atan2_Q16 function 5-1296 _LIBQ_Q3_12_log10_Q16 function 5-1282 _LIBQ_Q31_cos_Q2_29 function 5-1287 _LIBQ_Q31_sin_Q2_29 function 5-1286 _LIBQ_Q31FromFloat function 5-1299 _LIBQ_Q31Rand function 5-1297 _LIBQ_Q4_11_ln_Q16 function 5-1283 _LIBQ_Q5_10_log2_Q16 function 5-1283 _LIBQ_Q7_8_tan_Q2_13 function 5-1289 _LIBQ_ToFloatQ15 function 5-1300 _LIBQ_ToFloatQ31 function 5-1300 _LIBQ_ToStringQ15 function 5-1302 _PARM_EQUAL_FILTER structure 5-1265 _PARM_EQUAL_FILTER_16 structure 5-1266 _PARM_EQUAL_FILTER_32 structure 5-1266 _Q0_15 type 5-1305 _Q0_31 type 5-1305 _Q15 type 5-1305 _Q15_16 type 5-1306 _Q15_MAX macro 5-1302 _Q15_MIN macro 5-1303 _Q16 type 5-1306 _Q16_MAX macro 5-1303 _Q16_MIN macro 5-1303 _Q2_13 type 5-1306 _Q2_13_MAX macro 5-1303 _Q2_13_MIN macro 5-1303 _Q2_29 type 5-1306 _Q2_29_MAX macro 5-1303 _Q2_29_MIN macro 5-1303 _Q3_12 type 5-1306 _Q3_12_MAX macro 5-1304 _Q3_12_MIN macro 5-1304 _Q31 type 5-1306 _Q31_MAX macro 5-1304 _Q31_MIN macro 5-1304 _Q4_11 type 5-1307 _Q4_11_MAX macro 5-1304 _Q4_11_MIN macro 5-1304 _Q5_10 type 5-1307 _Q5_10_MAX macro 5-1305 _Q5_10_MIN macro 5-1305 _Q7_8 type 5-1307 _Q7_8_MAX macro 5-1305 _Q7_8_MIN macro 5-1305 _SYS_MSG_H macro 5-3462 _SYS_MSG_OBJECT macro 5-3462 _SYS_TASKS_PRIORITIES enumeration 5-3341 2 2. Creating Your Own Applications 1-21 3 3. Release Notes & Information 1-23 9 MPLAB Harmony Help a 4 4. Previous Releases 1-32 5 5. Tips and Tricks 1-36 6 6. Glossary 1-37 A About CAN Protocol 5-1555 Abstract Control Model (ACM) 5-4063 Abstraction Model 5-195, 5-228, 5-255, 5-290, 5-300, 5-310, 5-320, 5-334, 5-344, 5-368, 5-398, 5-419, 5-458, 5-513, 5-553, 5-607, 5-695, 5-1112, 5-1129, 5-1313, 5-3349, 5-3364, 5-3420, 5-3442, 5-3466, 5-3502, 5-3531, 5-3570, 5-3576, 5-3599, 5-3615, 5-3626, 5-3637, 5-3647, 5-3655, 5-3660, 5-3691, 5-3699, 5-3710, 5-3719, 5-3749, 5-3772, 5-3795, 5-3800, 5-3807, 5-3810, 5-3823, 5-3859, 5-3869, 5-3882, 5-3914, 5-3918, 5-3931, 5-3956, 5-4005, 5-4061, 5-4103, 5-4169 accept function 5-3602 Accessing the Result Buffers 5-1373 ADC Driver Library 5-193 ADC Peripheral Library 5-1361 ADC_ACQUISITION_TIME type 5-1438 ADC_BUFFER_MODE enumeration 5-1426 ADC_CHANNEL_GROUP enumeration 5-1423 ADC_CHANNEL123_INPUTS_NEG enumeration 5-1432 ADC_CHANNEL123_INPUTS_POS enumeration 5-1433 ADC_CLOCK_SOURCE enumeration 5-1424 ADC_CONVERSION_CLOCK type 5-1438 ADC_CONVERSION_ORDER enumeration 5-1435 ADC_CONVERSION_TRIGGER_SOURCE enumeration 5-1424 ADC_DMA_ADDRESS_INCREMENT enumeration 5-1435 ADC_DMA_BUFFER_MODE enumeration 5-1431 ADC_DMA_INPUT_BUFFER enumeration 5-1437 ADC_INPUTS_NEGATIVE enumeration 5-1421 ADC_INPUTS_POSITIVE enumeration 5-1433 ADC_INPUTS_SCAN enumeration 5-1428 ADC_MODULE_ID enumeration 5-1420 ADC_MUX enumeration 5-1427 ADC_PAIR enumeration 5-1431 ADC_REFERENCE_INPUT enumeration 5-1430 ADC_RESULT_BUF_STATUS enumeration 5-1427 ADC_RESULT_FORMAT enumeration 5-1430 ADC_RESULT_SIZE enumeration 5-1426 ADC_SAMPLE type 5-1439 ADC_SAMPLES_PER_INTERRUPT enumeration 5-1422 ADC_SAMPLING_MODE enumeration 5-1427 ADC_VOLTAGE_REFERENCE enumeration 5-1420 ADCP Peripheral Library 5-1471 ADCP_CLASS12_INPUT_ID enumeration 5-1507 ADCP_CLOCK_SOURCE enumeration 5-1507 ADCP_DCMP_ID enumeration 5-1513 ADCP_DSH_ID enumeration 5-1509 ADCP_INPUT_ID enumeration 5-1510 ADCP_MODULE_ID enumeration 5-1506 ADCP_ODFLTR_ID enumeration 5-1513 ADCP_ODFLTR_OSR enumeration 5-1514 ADCP_SCAN_TRG_SRC enumeration 5-1514 ADCP_SH_ID enumeration 5-1508 ADCP_SH_MODE enumeration 5-1509 ADCP_TRG_SRC enumeration 5-1515 ADCP_VREF_SOURCE enumeration 5-1507 adhocMode enumeration 5-655 Advanced Data Transfer 5-517 Advanced Font Features 5-1119 Advanced MPFS2 Settings 5-3544 AF_INET macro 5-3609 Alarm Config 5-479 Alarm Functionality 5-466 Alarm Functionality Examples 5-481 Alarm Mode Operations 5-2710 Alpha Blending 5-1116, 5-1123 ALPHA_DELTA macro 5-294 AN_READY type 5-1517 AN_SELECT union 5-1516 Announce TCP/IP Stack Library 5-3569 9 MPLAB Harmony Help b ANNOUNCE_MAX_PAYLOAD macro 5-3571 ANNOUNCE_PORT macro 5-3571 Application Interaction 5-3380 Applications Help 3-61 Applications Overview 3-62 Architecture 5-3378 Architecture Overview 5-4132 Arcs 5-1114 ARP Changes 5-3551 ARP TCP/IP Stack Library 5-3574 arp.h 5-3596 arp_app_callbacks structure 5-3595 ARP_CACHE_ENTRIES_97J60 macro 5-3577 ARP_CACHE_ENTRIES_DEFAULT macro 5-3578 ARP_CACHE_ENTRIES_ENCJ60 macro 5-3578 ARP_CACHE_ENTRIES_ENCJ600 macro 5-3578 ARP_CACHE_ENTRIES_MRF24W macro 5-3578 ARP_CACHE_ENTRIES_PIC32INT macro 5-3578 ARP_CACHE_PENDING_ENTRY_TMO macro 5-3578 ARP_CACHE_PENDING_RETRY_TMO macro 5-3579 ARP_CACHE_PERMANENT_QUOTA macro 5-3579 ARP_CACHE_PURGE_QUANTA macro 5-3579 ARP_CACHE_PURGE_THRESHOLD macro 5-3579 ARP_CACHE_SOLVED_ENTRY_TMO macro 5-3579 arp_config.h 5-3597 arp_manager.h 5-3597 ARP_MODULE_CONFIG structure 5-3595 ARP_TASK_PROCESS_RATE macro 5-3579 Assigning Buffer Memory 5-1558 Asynchronous Counter 5-3017 Asynchronous USART Mode 5-3090 Audio Protocol Interface Mode 5-2817 audio_speaker 3-166 AUTH_LOCALIZED_PASSWORD_KEY_LEN macro 5-3826 B Before You Start 1-2 berekely_api_config.h 5-3613 Berkeley TCP/IP Stack Library 5-3598 berkeley_api.h 5-3613 BERKELEY_MODULE_CONFIG structure 5-3610 Bevels 5-1115 bind function 5-3603 biquad16 structure 5-1264 BLACK macro 5-941 Blocking Applications 3-99 BLUE macro 5-941 BMX Peripheral Library 5-1519 BMX_MODULE_ID enumeration 5-1543 Board Drivers 7-4229 Board Support Packages Help 7-4227 Board Support Packages Overview 7-4228 BRIGHTBLUE macro 5-941 BRIGHTCYAN macro 5-942 BRIGHTGREEN macro 5-942 BRIGHTMAGENTA macro 5-942 BRIGHTRED macro 5-942 BRIGHTYELLOW macro 5-942 BROWN macro 5-942 BSP_ANALOG_PIN macro 7-4242 bsp_config.h 7-4245 BSP_DIGITAL_PIN macro 7-4242 BSP_Initialize function 7-4238 BSP_INPUT macro 7-4242 BSP_LED enumeration 7-4243 BSP_OUTPUT macro 7-4242 BSP_ReadCoreTimer function 7-4241 BSP_ReadSwitch function 7-4241 BSP_SWITCH enumeration 7-4243 BSP_SWITCH_STATE enumeration 7-4244 BSP_SwitchOFFLED function 7-4239 BSP_SwitchONLED function 7-4239 BSP_SwitchToggleLED function 7-4240 BSP_ToggleLED function 7-4239 Building MPFS2 Images 5-3542 Building Projects 4-178 Building Projects Help 4-177 Building the Application 3-109, 3-126, 3-145 9 MPLAB Harmony Help c Building the Library 5-202, 5-236, 5-262, 5-291, 5-301, 5-311, 5-326, 5-335, 5-352, 5-377, 5-400, 5-428, 5-482, 5-519, 5-574, 5-609, 5-701, 5-1124, 5-1130, 5-1324, 5-2256, 5-3368, 5-3444, 5-3474, 5-3517, 5-3572, 5-3580, 5-3601, 5-3618, 5-3630, 5-3640, 5-3648, 5-3657, 5-3692, 5-3700, 5-3711, 5-3723, 5-3753, 5-3773, 5-3796, 5-3804, 5-3808, 5-3814, 5-3832, 5-3862, 5-3875, 5-3888, 5-3916, 5-3921, 5-3935, 5-3957 Builiding the Library 5-3532 Bulk and Interrupt Transfers 5-570 BURLYWOOD macro 5-942 Bus Arbiter 5-1522 C Cache Control 5-1522 Cache Control Operations 5-2431 Cache Line Operations 5-2432 Cache Status Operations 5-2433 Can Bit Time Quanta 5-1556 CAN Peripheral Library 5-1553 CAN_CHANNEL enumeration 5-1620 CAN_CHANNEL_EVENT enumeration 5-1621 CAN_CHANNEL_MASK enumeration 5-1622 CAN_DNET_FILTER_SIZE enumeration 5-1623 CAN_ERROR_STATE enumeration 5-1624 CAN_FILTER enumeration 5-1625 CAN_FILTER_MASK enumeration 5-1627 CAN_FILTER_MASK_TYPE enumeration 5-1627 CAN_FUNCTONAL_MODES enumeration 5-1628 CAN_ID_TYPE enumeration 5-1628 CAN_MODULE_EVENT enumeration 5-1629 CAN_MODULE_ID enumeration 5-1629 CAN_MSG_EID structure 5-1630 CAN_OPERATION_MODES enumeration 5-1630 CAN_RECEIVE_CHANNEL enumeration 5-1631 CAN_RECEIVE_MODES enumeration 5-1631 CAN_RX_DATA_MODE enumeration 5-1632 CAN_RX_DATA_ONLY_SIZE_BYTES macro 5-1636 CAN_RX_MSG_BUFFER union 5-1632 CAN_RX_MSG_SID structure 5-1633 CAN_TIME_SEGMENT_LENGTH enumeration 5-1633 CAN_TX_CHANNEL_STATUS enumeration 5-1634 CAN_TX_MSG_BUFFER union 5-1634 CAN_TX_MSG_SID structure 5-1635 CAN_TX_RTR enumeration 5-1635 CAN_TX_RX_MESSAGE_SIZE_BYTES macro 5-1636 CAN_TXCHANNEL_PRIORITY enumeration 5-1635 cdc_basic 3-167 cdc_com_port_dual 3-154 cdc_com_port_single 3-152 cdc_serial_emulator 3-156 CH_CLR0 macro 5-943 CH_CLR1 macro 5-943 CH_CLR10 macro 5-943 CH_CLR11 macro 5-943 CH_CLR12 macro 5-943 CH_CLR13 macro 5-943 CH_CLR14 macro 5-944 CH_CLR15 macro 5-944 CH_CLR2 macro 5-944 CH_CLR3 macro 5-944 CH_CLR4 macro 5-944 CH_CLR5 macro 5-944 CH_CLR6 macro 5-944 CH_CLR7 macro 5-945 CH_CLR8 macro 5-945 CH_CLR9 macro 5-945 Change Notification 5-3472 Changing the Clock 5-3351 Changing the Default Font 5-1119 Channel Configuration 5-1559 Channel Events 5-1562 Channel Management 5-1743 CHART_MARGIN macro 5-945 CHART_YGRIDCOUNT macro 5-945 CHARTPARAM structure 5-888 Cient Transfer - Core 5-423 ClearPaletteChangeError function 5-827 Client Access 5-422, 5-516 Client Access Operation 5-346 Client Basic Operation 5-346 9 MPLAB Harmony Help d Client Block Data Operation 5-348 Client Config 5-480 Client Configuration 5-428 Client Core Functionality 5-196 Client Data Handling 5-4111 Client Functionality 5-608 Client Interaction 5-462 Client Operation 5-373 Client Setup 5-4105 Client Subclass Specific 5-4120 Client Transfer - Advanced 5-425 CLK_PERIPH_BUS_MZ enumeration 5-3361 CLK_SOURCE_PERIPHERAL enumeration 5-3361 Clock Sources 5-2334 Clock System Service Library 5-3347 closesocket function 5-3603 Closing a File 5-3395 CMP_CLOCK_DIVIDE enumeration 5-1716 CMP_CVREF_BANDGAP_SELECT enumeration 5-1716 CMP_CVREF_REFERENCE_SELECT enumeration 5-1717 CMP_CVREF_VALUE enumeration 5-1717 CMP_CVREF_VOLTAGE_SOURCE enumeration 5-1718 CMP_FILTER_CLOCK enumeration 5-1718 CMP_INTERRUPT_EVENT enumeration 5-1719 CMP_INVERTING_INPUT enumeration 5-1719 CMP_MASK_A enumeration 5-1719 CMP_MASK_B enumeration 5-1720 CMP_MASK_C enumeration 5-1721 CMP_MODULE_ID enumeration 5-1721 CMP_NON_INVERTING_INPUT enumeration 5-1722 CMP_SPEED_POWER enumeration 5-1722 Code Examples 5-197 COLOR_DEPTH macro 5-325 Colors 5-1123 Communication Mode 5-2822 Comparator Peripheral Library 5-1667 Comparison of API Names 5-3386 Compression Library 4-181 Configuration 7-4228 Configuring the Application 3-109, 3-127, 3-146 Configuring the Comparator Interrupts 5-1671 Configuring the Driver Library 5-311 Configuring the Hardware 3-67, 3-69, 3-72, 3-74, 3-76, 3-86, 3-88, 3-89, 3-90, 3-109, 3-114, 3-115, 3-116, 3-117, 3-126, 3-131, 3-133, 3-135, 3-145, 3-153, 3-154, 3-156, 3-158, 3-160, 3-161, 3-162, 3-164, 3-165, 3-167, 3-168, 3-169 Configuring the Libraries 3-110, 3-127, 3-146 Configuring the Library 5-202, 5-234, 5-259, 5-290, 5-300, 5-321, 5-335, 5-349, 5-376, 5-400, 5-428, 5-474, 5-519, 5-574, 5-608, 5-701, 5-1123, 5-1130, 5-1322, 5-1380, 5-1480, 5-1526, 5-1566, 5-1748, 5-1866, 5-2089, 5-2175, 5-2205, 5-2256, 5-2294, 5-2336, 5-2434, 5-2488, 5-2601, 5-2666, 5-2690, 5-2712, 5-2766, 5-2823, 5-2903, 5-3021, 5-3101, 5-3182, 5-3322, 5-3352, 5-3366, 5-3424, 5-3443, 5-3474, 5-3516, 5-3532, 5-3571, 5-3577, 5-3600, 5-3616, 5-3627, 5-3638, 5-3648, 5-3656, 5-3661, 5-3691, 5-3700, 5-3710, 5-3720, 5-3749, 5-3773, 5-3796, 5-3801, 5-3807, 5-3814, 5-3824, 5-3860, 5-3872, 5-3884, 5-3914, 5-3920, 5-3933, 5-3957, 5-3985 Configuring the Stack 5-3974 connect function 5-3604 Constants 5-190 Control Transfers 5-565 Controlling the Conversion Process 5-1371 Controlling the Sampling Process 5-1370 Conversion Sequence Examples 5-1375 ConvertColor25 macro 5-945 ConvertColor50 macro 5-946 ConvertColor75 macro 5-946 CopyPageWindow macro 5-946 Core Functionality 5-465, 5-515, 5-1112, 5-1315, 5-2896, 5-3366, 5-3883, 5-3932, 5-3956 Counter Modification 5-465 Creating Your Own USB Device 5-3970 Critical Section Operation 5-1320 Critical Sections 5-3422 CRYPT_AES_CBC_Decrypt function 5-1156 CRYPT_AES_CBC_Encrypt function 5-1157 CRYPT_AES_CTR_Encrypt function 5-1157 CRYPT_AES_CTX structure 5-1161 CRYPT_AES_DIRECT_Decrypt function 5-1158 CRYPT_AES_DIRECT_Encrypt function 5-1158 CRYPT_AES_IvSet function 5-1158 CRYPT_AES_KeySet function 5-1159 9 MPLAB Harmony Help e CRYPT_ECC_CTX structure 5-1162 CRYPT_ECC_DHE_KeyMake function 5-1146 CRYPT_ECC_DHE_SharedSecretMake function 5-1147 CRYPT_ECC_DSA_HashSign function 5-1147 CRYPT_ECC_DSA_HashVerify function 5-1148 CRYPT_ECC_Free function 5-1148 CRYPT_ECC_Initialize function 5-1148 CRYPT_ECC_KeySizeGet function 5-1149 CRYPT_ECC_PrivateImport function 5-1149 CRYPT_ECC_PublicExport function 5-1150 CRYPT_ECC_PublicImport function 5-1150 CRYPT_ECC_SignatureSizeGet function 5-1150 CRYPT_ERROR_StringGet function 5-1132 CRYPT_HMAC_CTX structure 5-1162 CRYPT_HMAC_DataAdd function 5-1135 CRYPT_HMAC_Finalize function 5-1136 CRYPT_HMAC_SetKey function 5-1136 CRYPT_HUFFMAN_Compress function 5-1145 CRYPT_HUFFMAN_DeCompress function 5-1146 CRYPT_MD5_CTX structure 5-1162 CRYPT_MD5_DataAdd function 5-1159 CRYPT_MD5_Finalize function 5-1160 CRYPT_MD5_Initialize function 5-1161 CRYPT_RNG_BlockGenerate function 5-1143 CRYPT_RNG_CTX structure 5-1162 CRYPT_RNG_Get function 5-1144 CRYPT_RNG_Initialize function 5-1144 CRYPT_RSA_CTX structure 5-1163 CRYPT_RSA_EncryptSizeGet function 5-1154 CRYPT_RSA_Free function 5-1154 CRYPT_RSA_Initialize function 5-1154 CRYPT_RSA_PrivateDecrypt function 5-1155 CRYPT_RSA_PrivateKeyDecode function 5-1155 CRYPT_RSA_PublicEncrypt function 5-1156 CRYPT_RSA_PublicKeyDecode function 5-1156 CRYPT_SHA_CTX structure 5-1163 CRYPT_SHA_DataAdd function 5-1141 CRYPT_SHA_Finalize function 5-1142 CRYPT_SHA_Initialize function 5-1142 CRYPT_SHA256_CTX structure 5-1163 CRYPT_SHA256_DataAdd function 5-1139 CRYPT_SHA256_Finalize function 5-1139 CRYPT_SHA256_Initialize function 5-1140 CRYPT_SHA384_CTX structure 5-1163 CRYPT_SHA384_DataAdd function 5-1137 CRYPT_SHA384_Finalize function 5-1137 CRYPT_SHA384_Initialize function 5-1138 CRYPT_SHA512_CTX structure 5-1164 CRYPT_SHA512_DataAdd function 5-1133 CRYPT_SHA512_Finalize function 5-1134 CRYPT_SHA512_Initialize function 5-1134 CRYPT_TDES_CBC_Decrypt function 5-1151 CRYPT_TDES_CBC_Encrypt function 5-1152 CRYPT_TDES_CTX structure 5-1164 CRYPT_TDES_IvSet function 5-1152 CRYPT_TDES_KeySet function 5-1153 Crypto Library 4-181 crypto.h 5-1165 Cryptographic (Crypto) Library 5-1127 Customizing the Application 3-110, 3-126, 3-147 CYAN macro 5-946 D DARKGRAY macro 5-946 DARKORANGE macro 5-947 Data Transfer 5-516 Data Types 5-188 Data Types and Constants 5-305, 5-317, 5-340, 5-4174, 5-4209, 7-4241 DATASERIES structure 5-889 ddns.h 5-3653 DDNS_CHECKIP_SERVER macro 5-3648 ddns_config.h 5-3654 DDNS_DEFAULT_PORT macro 5-3648 DDNS_MODULE_CONFIG structure 5-3650 DDNS_POINTERS structure 5-3651 DDNS_SERVICES enumeration 5-3652 DDNS_STATUS enumeration 5-3652 9 MPLAB Harmony Help f Defining Colors 5-1118 DELAY_FIRST_PROBE_TIME macro 5-3802 Delays 5-3512 Demonstration 5-3957 Demonstration Application Configurations 3-151 Demonstration Board Information 3-77, 3-91, 3-118, 3-136, 3-170 Demonstrations 3-65, 3-85, 3-114, 3-131, 3-152 Descriptor Table Example 5-1917 Descriptors 5-4010 Developing Vendor-specific Function Drivers 5-4017 Development Information (Advance Information) 5-3565 Device 3-152 Device Control System Service Library 5-3363 Device Events 5-4015 DHCP Server TCP/IP Stack Library 5-3625 DHCP TCP/IP Stack Library 5-3614 dhcp.h 5-3624 DHCP_CLIENT_ENABLED macro 5-3617 DHCP_CLIENT_PORT macro 5-3617 dhcp_config.h 5-3624 DHCP_MODULE_CONFIG structure 5-3622 DHCP_SERVER_GATEWAY_ADDRESS macro 5-3628 DHCP_SERVER_IP_ADDRESS macro 5-3628 DHCP_SERVER_NETMASK_ADDRESS macro 5-3628 DHCP_SERVER_POOL_ENTRY_TYPE enumeration 5-3633 DHCP_SERVER_PORT macro 5-3617 DHCP_SERVER_PRIMARY_DNS_ADDRESS macro 5-3628 DHCP_SERVER_SECONDARY_DNS_ADDRESS macro 5-3628 DHCP_TASK_TICK_RATE macro 5-3617 DHCP_TIMEOUT macro 5-3617 dhcps.h 5-3635 dhcps_config.h 5-3635 DHCPS_IP_ADDRESS_RANGE_START macro 5-3629 DHCPS_LEASE_DURATION macro 5-3629 DHCPS_LEASE_ENTRIES_DEFAULT macro 5-3629 DHCPS_LEASE_ENTRY structure 5-3633 DHCPS_LEASE_HANDLE type 5-3634 DHCPS_LEASE_REMOVED_BEFORE_ACK macro 5-3629 DHCPS_LEASE_SOLVED_ENTRY_TMO macro 5-3629 DHCPS_MODULE_CONFIG structure 5-3634 DHCPS_TASK_PROCESS_RATE macro 5-3629 DisablePalette function 5-827 DisplayUpdatePending variable 5-887 DMA Mode 5-2898 DMA Peripheral Library Help 5-1733 DMA_ADDRESS_OFFSET_TYPE enumeration 5-1821 DMA_CHANNEL enumeration 5-1821 DMA_CHANNEL_ADDRESSING_MODE enumeration 5-1822 DMA_CHANNEL_COLLISION enumeration 5-1822 DMA_CHANNEL_DATA_SIZE enumeration 5-1823 DMA_CHANNEL_PRIORITY enumeration 5-1823 DMA_CHANNEL_TRANSFER_DIRECTION enumeration 5-1824 DMA_CHANNEL_TRIGGER_TYPE enumeration 5-1824 DMA_CRC_BIT_ORDER enumeration 5-1824 DMA_CRC_BYTE_ORDER enumeration 5-1825 DMA_CRC_TYPE enumeration 5-1825 DMA_DESTINATION_ADDRESSING_MODE enumeration 5-1826 DMA_INT_TYPE enumeration 5-1826 DMA_ISR_TASK enumeration 5-307 DMA_MODULE_ID enumeration 5-1827 DMA_PATTERN_LENGTH enumeration 5-1827 DMA_PING_PONG_MODE enumeration 5-1828 DMA_SOURCE_ADDRESSING_MODE enumeration 5-1828 DMA_TRANSFER_MODE enumeration 5-1829 DMA_TRIGGER_SOURCE enumeration 5-1829 DNS TCP/IP Stack Library 5-3636 dns.h 5-3645 DNS_CLIENT_ARP_TMO macro 5-3639 DNS_CLIENT_MODULE_CONFIG structure 5-3643 DNS_CLIENT_OPEN_TMO macro 5-3639 DNS_CLIENT_PORT macro 5-3639 DNS_CLIENT_SERVER_TMO macro 5-3639 DNS_CLIENT_TASK_PROCESS_RATE macro 5-3640 DNS_CLIENT_VERSION_NO macro 5-3640 dns_config.h 5-3645 DNS_RESOLVE_TYPE enumeration 5-3643 9 MPLAB Harmony Help g DNS_RESULT enumeration 5-3644 DNS_SERVER_MODULE_CONFIG structure 5-3644 Double Buffering 5-1121 doubleBuffEnabled variable 5-888 DrawArc function 5-827 Driver Initialization 5-554 Driver Library Help 5-185 Driver Library Overview 5-185 driver.h 5-192 driver_common.h 5-193 DRIVER_COUNT macro 5-325 DriverInterfaceInit function 5-291 drv_adc.c 5-202 drv_adc.h 5-225 DRV_ADC_ACQUISITION_TIME macro 5-219 DRV_ADC_ALTERNATE_INPUT_SAMPLING_ENABLE macro 5-219 DRV_ADC_ANALOG_INPUT macro 5-220 DRV_ADC_AUTO_SAMPLING_ENABLE macro 5-220 drv_adc_client_multi.c 5-203 drv_adc_client_single.c 5-203 DRV_ADC_CLIENT_STATUS enumeration 5-217 DRV_ADC_CLIENTS_NUMBER macro 5-220 DRV_ADC_ClientStatus function 5-210 DRV_ADC_Close function 5-210 DRV_ADC_CONVERSION_CLOCK_PRESCALER macro 5-220 DRV_ADC_CONVERSION_CLOCK_SOURCE macro 5-221 DRV_ADC_CONVERSION_TRIGGER_SOURCE macro 5-221 DRV_ADC_Deinitialize function 5-205 drv_adc_hw_dynamic.c 5-203 drv_adc_hw_static.c 5-203 DRV_ADC_INDEX macro 5-221 DRV_ADC_INDEX_0 macro 5-222 DRV_ADC_INDEX_1 macro 5-222 DRV_ADC_INDEX_2 macro 5-222 DRV_ADC_INDEX_COUNT macro 5-222 DRV_ADC_INIT structure 5-218 DRV_ADC_INIT_FLAGS enumeration 5-219 DRV_ADC_Initialize function 5-206 DRV_ADC_InputsRegister function 5-211 DRV_ADC_INSTANCES_NUMBER macro 5-222 DRV_ADC_INTERNAL_BUFFER_SIZE macro 5-223 DRV_ADC_INTERRUPT_MODE macro 5-223 DRV_ADC_INTERRUPT_SOURCE macro 5-223 DRV_ADC_Open function 5-211 DRV_ADC_PERIPHERAL_ID macro 5-223 DRV_ADC_POWER_STATE macro 5-224 DRV_ADC_Reinitialize function 5-207 DRV_ADC_RESULT_FORMAT macro 5-224 DRV_ADC_SampleMaxGet function 5-214 DRV_ADC_SampleMinGet function 5-215 DRV_ADC_SAMPLES_PER_INTERRUPT macro 5-224 DRV_ADC_SamplesAvailable function 5-212 DRV_ADC_SamplesRead function 5-215 DRV_ADC_SamplesReadLatest function 5-216 DRV_ADC_Start function 5-213 DRV_ADC_Status function 5-208 DRV_ADC_Stop function 5-214 DRV_ADC_STOP_ON_CONVERSION_ENABLE macro 5-224 DRV_ADC_Tasks function 5-209 DRV_ADC_VOLTAGE_REFERENCE macro 5-225 DRV_CLIENT_STATUS enumeration 5-188 DRV_CONFIG_NOT_SUPPORTED macro 5-191 drv_ethernet_flags.h 5-252, 5-288 drv_ethmac.h 5-252 DRV_ETHMAC_CLIENTS_NUMBER macro 5-235 drv_ethmac_config.h 5-253 DRV_ETHMAC_INDEX macro 5-235 DRV_ETHMAC_INDEX_0 macro 8-4247 DRV_ETHMAC_INDEX_1 macro 5-251 DRV_ETHMAC_INDEX_COUNT macro 8-4247 DRV_ETHMAC_INSTANCES_NUMBER macro 5-235 DRV_ETHMAC_INTERRUPT_MODE macro 5-235 DRV_ETHMAC_INTERRUPT_SOURCE macro 5-236 DRV_ETHMAC_PERIPHERAL_ID macro 5-236 DRV_ETHMAC_PIC32MACClose function 5-238 DRV_ETHMAC_PIC32MACEventAcknowledge function 5-243 DRV_ETHMAC_PIC32MACEventMaskSet function 5-244 DRV_ETHMAC_PIC32MACEventPendingGet function 5-245 9 MPLAB Harmony Help h DRV_ETHMAC_PIC32MACGetConfig function 5-238 DRV_ETHMAC_PIC32MACLinkCheck function 5-239 DRV_ETHMAC_PIC32MACOpen function 5-239 DRV_ETHMAC_PIC32MACPacketRx function 5-241 DRV_ETHMAC_PIC32MACPacketTx function 5-242 DRV_ETHMAC_PIC32MACPowerMode function 5-246 DRV_ETHMAC_PIC32MACProcess function 5-246 DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet function 5-242 DRV_ETHMAC_PIC32MACSetup function 5-240 DRV_ETHMAC_PIC32MACTeardown function 5-240 DRV_ETHMAC_POWER_STATE macro 5-236 drv_ethphy.h 5-286 DRV_ETHPHY_CLIENT_STATUS enumeration 5-284 DRV_ETHPHY_CLIENTS_NUMBER macro 5-260 DRV_ETHPHY_ClientStatus function 5-268 DRV_ETHPHY_Close function 5-268 drv_ethphy_config.h 5-288 DRV_ETHPHY_Deinitialize function 5-264 DRV_ETHPHY_HWConfigFlagsGet function 5-269 DRV_ETHPHY_INDEX macro 5-260 DRV_ETHPHY_INDEX_0 macro 5-260 DRV_ETHPHY_INDEX_1 macro 5-251 DRV_ETHPHY_INDEX_COUNT macro 5-261 DRV_ETHPHY_INIT structure 5-285 DRV_ETHPHY_Initialize function 5-264 DRV_ETHPHY_INSTANCES_NUMBER macro 5-261 DRV_ETHPHY_LinkScanRead function 5-270 DRV_ETHPHY_LinkScanStart function 5-270 DRV_ETHPHY_LinkScanStop function 5-271 DRV_ETHPHY_LinkStatusGet function 5-271 DRV_ETHPHY_NegotiationIsComplete function 5-272 DRV_ETHPHY_NegotiationResultGet function 5-273 DRV_ETHPHY_Open function 5-273 DRV_ETHPHY_PERIPHERAL_ID macro 5-261 DRV_ETHPHY_Reinitialize function 5-265 DRV_ETHPHY_Reset function 5-274 DRV_ETHPHY_RestartNegotiation function 5-275 DRV_ETHPHY_Setup function 5-275 DRV_ETHPHY_SMIClockSet function 5-276 DRV_ETHPHY_SMIisBusy function 5-277 DRV_ETHPHY_SMIReadResultGet function 5-277 DRV_ETHPHY_SMIReadStart function 5-278 DRV_ETHPHY_SMIScanDataGet function 5-278 DRV_ETHPHY_SMIScanStart function 5-279 DRV_ETHPHY_SMIScanStatusGet function 5-279 DRV_ETHPHY_SMIScanStop function 5-280 DRV_ETHPHY_SMIWriteStart function 5-280 DRV_ETHPHY_Status function 5-266 DRV_ETHPHY_Tasks function 5-267 DRV_ETHPHY_VersionGet function 5-283 DRV_ETHPHY_VersionStrGet function 5-284 drv_gfx_config_template.h 5-299 drv_gfx_display.h 5-295 drv_gfx_lcc.h 5-296 drv_gfx_lcc_config_template.h 5-308 drv_gfx_otm2201a.h 5-318 drv_gfx_s1d13517.h 5-297 drv_gfx_s1d13517_config_template.h 5-332 drv_gfx_ssd1926.h 5-298 drv_gfx_ssd1926_config_template.h 5-341 DRV_HANDLE type 5-189 DRV_HANDLE_INVALID macro 5-191 DRV_IO_BUFFER_TYPES enumeration 5-189 DRV_IO_INTENT enumeration 5-189 DRV_IO_ISBLOCKING macro 5-191 DRV_IO_ISEXCLUSIVE macro 5-191 DRV_IO_ISNONBLOCKING macro 5-192 drv_nvm.h 5-365 DRV_NVM_BUFFER_HANDLE type 5-363 DRV_NVM_BUFFER_HANDLE_INVALID macro 5-362 DRV_NVM_BUFFER_OBJECT_NUMBER macro 5-349 DRV_NVM_BUFFER_STATUS enumeration 5-363 DRV_NVM_BufferStatus function 5-361 DRV_NVM_CLIENT_STATUS enumeration 5-364 DRV_NVM_CLIENTS_NUMBER macro 5-350 DRV_NVM_ClientStatus function 5-355 DRV_NVM_Close function 5-356 drv_nvm_config_template.h 5-366 9 MPLAB Harmony Help i DRV_NVM_Deinitialize function 5-353 DRV_NVM_Erase function 5-357 DRV_NVM_ERASE_SIZE macro 5-350 DRV_NVM_INDEX_0 macro 5-362 DRV_NVM_INDEX_1 macro 5-365 DRV_NVM_INDEX_COUNT macro 5-363 DRV_NVM_INIT structure 5-364 DRV_NVM_Initialize function 5-353 DRV_NVM_INSTANCES_NUMBER macro 5-350 DRV_NVM_INTERRUPT_MODE macro 5-350 DRV_NVM_Open function 5-357 DRV_NVM_Read function 5-359 DRV_NVM_ROW_SIZE macro 5-351 DRV_NVM_Status function 5-354 DRV_NVM_Tasks function 5-360 DRV_NVM_UNLOCK_KEY1 macro 5-351 DRV_NVM_UNLOCK_KEY2 macro 5-351 DRV_NVM_Write function 5-360 drv_pmp.h 5-395 DRV_PMP_CHIPX_STROBE_MODE enumeration 5-388 DRV_PMP_CLIENT_STATUS enumeration 5-388 DRV_PMP_CLIENTS_NUMBER macro 5-376 DRV_PMP_ClientStatus function 5-383 DRV_PMP_Close function 5-383 drv_pmp_config.h 5-396 DRV_PMP_Deinitialize function 5-378 DRV_PMP_ENDIAN_MODE enumeration 5-389 DRV_PMP_INDEX enumeration 5-389 DRV_PMP_INDEX_COUNT macro 5-388 DRV_PMP_INIT structure 5-389 DRV_PMP_Initialize function 5-379 DRV_PMP_INSTANCES_NUMBER macro 5-376 DRV_PMP_MODE_CONFIG structure 5-390 DRV_PMP_ModeConfig function 5-384 DRV_PMP_Open function 5-385 DRV_PMP_POLARITY_OBJECT structure 5-390 DRV_PMP_PORT_CONTROL enumeration 5-391 DRV_PMP_PORTS structure 5-391 DRV_PMP_QUEUE_ELEMENT_OBJ type 5-392 DRV_PMP_QUEUE_SIZE macro 5-376 DRV_PMP_Read function 5-386 DRV_PMP_Reinitialize function 5-380 DRV_PMP_Status function 5-381 DRV_PMP_Tasks function 5-382 DRV_PMP_TRANSFER_STATUS enumeration 5-392 DRV_PMP_TRANSFER_TYPE enumeration 5-393 DRV_PMP_TransferStatus function 5-387 DRV_PMP_VersionGet function 5-394 DRV_PMP_VersionStrGet function 5-394 DRV_PMP_WAIT_STATES structure 5-392 DRV_PMP_Write function 5-386 drv_sdcard.h 5-416 DRV_SDCARD_BUFFER_HANDLE type 5-414 DRV_SDCARD_BufferStatusGet function 5-409 DRV_SDCARD_CLIENT_STATUS enumeration 5-414 DRV_SDCARD_ClientStatus function 5-405 DRV_SDCARD_Close function 5-406 DRV_SDCARD_Deinitialize function 5-401 DRV_SDCARD_INDEX_0 macro 5-413 DRV_SDCARD_INDEX_1 macro 5-416 DRV_SDCARD_INDEX_2 macro 5-416 DRV_SDCARD_INDEX_3 macro 5-416 DRV_SDCARD_INDEX_COUNT macro 5-414 DRV_SDCARD_INIT type 5-415 DRV_SDCARD_Initialize function 5-402 DRV_SDCARD_MediaStatusGet function 5-410 DRV_SDCARD_Open function 5-407 DRV_SDCARD_Reinitialize function 5-403 DRV_SDCARD_SectorRead function 5-407 DRV_SDCARD_SectorsCountGet function 5-410 DRV_SDCARD_SectorSizeGet function 5-411 DRV_SDCARD_SectorWrite function 5-408 DRV_SDCARD_Status function 5-404 DRV_SDCARD_Tasks function 5-405 DRV_SDCARD_VersionGet function 5-412 DRV_SDCARD_VersionStrGet function 5-413 DRV_SDCARD_WriteProtectionIsEnabled function 5-412 drv_spi.h 5-455 9 MPLAB Harmony Help j DRV_SPI_BAUD_RATE macro 5-443 DRV_SPI_BAUD_RATE_CLOCK macro 5-444 DRV_SPI_BUFFER_EVENT enumeration 5-450 DRV_SPI_BUFFER_EVENT_HANDLER type 5-451 DRV_SPI_BUFFER_HANDLE type 5-452 DRV_SPI_BUFFER_HANDLE_INVALID macro 5-444 DRV_SPI_BUFFER_SIZE macro 5-444 DRV_SPI_BUFFER_TYPE enumeration 5-452 DRV_SPI_BUFFER_USAGE_TYPE macro 5-444 DRV_SPI_BufferAddRead function 5-438 DRV_SPI_BufferAddWrite function 5-439 DRV_SPI_BufferAddWriteRead function 5-440 DRV_SPI_BufferStatus function 5-435 DRV_SPI_CLIENT_SETUP type 5-453 DRV_SPI_CLIENTS_NUMBER macro 5-445 DRV_SPI_ClientSetup function 5-436 DRV_SPI_CLOCK_MODE enumeration 5-453 DRV_SPI_CLOCK_OPERATION_MODE macro 5-445 DRV_SPI_Close function 5-437 DRV_SPI_COMMUNICATION_WIDTH macro 5-445 drv_spi_config_template.h 5-456 DRV_SPI_Deinitialize function 5-430 DRV_SPI_FRAME_SYNC_PULSE_COUNT macro 5-445 DRV_SPI_FRAME_SYNC_PULSE_DIRECTION macro 5-446 DRV_SPI_FRAME_SYNC_PULSE_EDGE macro 5-446 DRV_SPI_FRAME_SYNC_PULSE_POLARITY macro 5-446 DRV_SPI_FRAME_SYNC_PULSE_WIDTH macro 5-446 DRV_SPI_INDEX macro 5-447 DRV_SPI_INDEX_0 macro 5-447 DRV_SPI_INDEX_1 macro 5-442 DRV_SPI_INDEX_2 macro 5-442 DRV_SPI_INDEX_3 macro 5-443 DRV_SPI_INDEX_4 macro 5-443 DRV_SPI_INDEX_5 macro 5-443 DRV_SPI_INDEX_COUNT macro 5-447 DRV_SPI_INIT type 5-453 DRV_SPI_Initialize function 5-431 DRV_SPI_INPUT_SAMPLE_PHASE macro 5-447 DRV_SPI_INSTANCES_NUMBER macro 5-448 DRV_SPI_INTERRUPT_MODE macro 5-448 DRV_SPI_INTERRUPT_SOURCE_ERROR macro 5-448 DRV_SPI_INTERRUPT_SOURCE_RX macro 5-448 DRV_SPI_INTERRUPT_SOURCE_TX macro 5-449 DRV_SPI_MODE enumeration 5-454 DRV_SPI_Open function 5-437 DRV_SPI_PERIPHERAL_ID macro 5-449 DRV_SPI_PORTS_REMAP_USAGE macro 5-449 DRV_SPI_POWER_STATE macro 5-450 DRV_SPI_PROTOCOL macro 5-450 DRV_SPI_PROTOCOL_TYPE enumeration 5-454 DRV_SPI_Read function 5-434 DRV_SPI_RX_FIFO_INTERRUPT_MODE macro 5-443 DRV_SPI_Status function 5-432 DRV_SPI_Tasks function 5-433 DRV_SPI_TX_FIFO_INTERRUPT_MODE macro 5-443 DRV_SPI_USAGE_MODE macro 5-450 DRV_SPI_VersionGet function 5-441 DRV_SPI_VersionStrGet function 5-442 DRV_SPI_Write function 5-434 drv_tmr.h 5-508 DRV_TMR_ALARM_CONFIG structure 5-504 DRV_TMR_ALARM_ENABLE macro 5-479 DRV_TMR_ALARM_PERIODIC macro 5-480 DRV_TMR_ALARM_TYPE enumeration 5-504 DRV_TMR_AlarmCountClear function 5-493 DRV_TMR_AlarmCountGet function 5-494 DRV_TMR_AlarmSet function 5-494 DRV_TMR_ASYNC_WRITE_ENABLE macro 5-481 DRV_TMR_CALLBACK type 5-505 DRV_TMR_CLIENT_STATUS enumeration 5-505 DRV_TMR_CLIENTS_NUMBER macro 5-480 DRV_TMR_ClientStatus function 5-488 DRV_TMR_CLOCK_SOURCE macro 5-474 DRV_TMR_Close function 5-489 drv_tmr_config_alarm.h 5-481 drv_tmr_config_template.h 5-509 DRV_TMR_COUNT_WIDTH macro 5-477 DRV_TMR_Counter16BitGet function 5-498 9 MPLAB Harmony Help k DRV_TMR_Counter16BitSet function 5-499 DRV_TMR_Counter32BitGet function 5-499 DRV_TMR_Counter32BitSet function 5-500 DRV_TMR_Counter8BitGet function 5-500 DRV_TMR_Counter8BitSet function 5-501 DRV_TMR_Deinitialize function 5-483 DRV_TMR_ElapsedStatusGetAndClear function 5-489 DRV_TMR_INDEX macro 5-477 DRV_TMR_INDEX_0 macro 5-477 DRV_TMR_INDEX_1 macro 5-477 DRV_TMR_INDEX_2 macro 5-478 DRV_TMR_INDEX_3 macro 5-478 DRV_TMR_INDEX_4 macro 5-478 DRV_TMR_INDEX_5 macro 5-478 DRV_TMR_INDEX_COUNT macro 5-478 DRV_TMR_INIT structure 5-506 DRV_TMR_Initialize function 5-484 DRV_TMR_INSTANCES_NUMBER macro 5-478 DRV_TMR_INTERRUPT_MODE macro 5-479 DRV_TMR_INTERRUPT_SOURCE macro 5-507 DRV_TMR_Open function 5-490 DRV_TMR_OperatingFrequencyGet function 5-502 DRV_TMR_Period16BitGet function 5-495 DRV_TMR_Period16BitSet function 5-495 DRV_TMR_Period32BitGet function 5-496 DRV_TMR_Period32BitSet function 5-497 DRV_TMR_Period8BitGet function 5-497 DRV_TMR_Period8BitSet function 5-498 DRV_TMR_PERIPHERAL_ID macro 5-475 DRV_TMR_POSTSCALE macro 5-475 DRV_TMR_POWER_STATE macro 5-507 DRV_TMR_PRESCALE macro 5-475 DRV_TMR_PRESCALER_ENABLE macro 5-481 DRV_TMR_Reinitialize function 5-485 DRV_TMR_SOURCE_EDGE macro 5-475 DRV_TMR_Start function 5-491 DRV_TMR_Status function 5-486 DRV_TMR_Stop function 5-491 DRV_TMR_SYNC_MODE enumeration 5-506 DRV_TMR_SYNCHRONIZATION_MODE macro 5-476 DRV_TMR_SyncModeGet function 5-492 DRV_TMR_SyncModeSet function 5-492 DRV_TMR_Tasks function 5-487 DRV_TMR_TickFrequencyGet function 5-502 DRV_TMR_TIMER_PERIOD macro 5-476 DRV_TMR_UNIFIED macro 5-507 DRV_TMR_VersionGet function 5-503 DRV_TMR_VersionStrGet function 5-503 drv_usart.h 5-549 DRV_USART_AUTO_BAUD_ENABLE macro 5-536 DRV_USART_BAUD_RATE macro 5-537 DRV_USART_BUFFER_FLAGS enumeration 5-543 DRV_USART_BUFFER_STATUS enumeration 5-543 DRV_USART_BufferAdd function 5-526 DRV_USART_BufferStatus function 5-527 DRV_USART_BufferTransferStatus function 5-532 DRV_USART_BYTE_Q_SIZE_RX macro 5-537 DRV_USART_BYTE_Q_SIZE_TX macro 5-537 DRV_USART_CALLBACK type 5-544 DRV_USART_CLIENT_STATUS enumeration 5-544 DRV_USART_CLIENTS_NUMBER macro 5-537 DRV_USART_ClientStatus function 5-533 DRV_USART_Close function 5-534 drv_usart_config_template.h 5-551 DRV_USART_Deinitialize function 5-521 DRV_USART_HANDSHAKE_MODE macro 5-537 DRV_USART_HANDSHAKE_MODES enumeration 5-545 DRV_USART_INDEX macro 5-538 DRV_USART_INDEX_0 macro 5-538 DRV_USART_INDEX_1 macro 5-538 DRV_USART_INDEX_2 macro 5-538 DRV_USART_INDEX_3 macro 5-538 DRV_USART_INDEX_4 macro 5-539 DRV_USART_INDEX_5 macro 5-539 DRV_USART_INDEX_COUNT macro 5-539 DRV_USART_INIT structure 5-545 DRV_USART_INIT_FLAGS enumeration 5-546 DRV_USART_Initialize function 5-522 9 MPLAB Harmony Help l DRV_USART_INSTANCES_NUMBER macro 5-539 DRV_USART_INTERRUPT_MODE macro 5-539 DRV_USART_INTERRUPT_SOURCE_ERROR macro 5-540 DRV_USART_INTERRUPT_SOURCE_RX macro 5-540 DRV_USART_INTERRUPT_SOURCE_TX macro 5-540 DRV_USART_IO_BUFFER structure 5-546 DRV_USART_LINE_CONTROL macro 5-540 DRV_USART_LINE_CONTROL_MODES enumeration 5-547 DRV_USART_Open function 5-534 DRV_USART_OPERATION_MODE macro 5-541 DRV_USART_OPERATION_MODE_INIT union 5-547 DRV_USART_OPERATION_MODES enumeration 5-548 DRV_USART_PERIPHERAL_ID macro 5-541 DRV_USART_POLARITY_INVERTED_RX macro 5-541 DRV_USART_POLARITY_INVERTED_TX macro 5-542 DRV_USART_POWER_STATE macro 5-542 DRV_USART_Read function 5-528 DRV_USART_ReadByte function 5-529 DRV_USART_Reinitialize function 5-523 DRV_USART_Status function 5-535 DRV_USART_TasksError function 5-524 DRV_USART_TasksRX function 5-525 DRV_USART_TasksTX function 5-525 DRV_USART_TRANSFER_STATUS enumeration 5-548 DRV_USART_TransferStatus function 5-530 DRV_USART_WAKE_ON_START_ENABLE macro 5-542 DRV_USART_Write function 5-530 DRV_USART_WriteByte function 5-531 DRV_USART_XFER_BUFFER_NUMBER macro 5-542 DRV_USART_XFER_HANDLE type 5-549 drv_usb.h 5-598 DRV_USB_ClientEventCallBackSet function 5-581 DRV_USB_Close function 5-579 drv_usb_config_template.h 5-600 DRV_USB_DEVICE_AddressSet function 5-582 DRV_USB_DEVICE_Attach function 5-582 DRV_USB_DEVICE_CurrentSpeedGet function 5-583 DRV_USB_DEVICE_Detach function 5-584 DRV_USB_DEVICE_EndpointDisable function 5-585 DRV_USB_DEVICE_EndpointDisableAll function 5-585 DRV_USB_DEVICE_EndpointEnable function 5-586 DRV_USB_DEVICE_EndpointIsEnabled function 5-587 DRV_USB_DEVICE_EndpointIsStalled function 5-588 DRV_USB_DEVICE_EndpointStall function 5-589 DRV_USB_DEVICE_EndpointStallClear function 5-589 DRV_USB_DEVICE_IRPCancelAll function 5-590 DRV_USB_DEVICE_IRPSubmit function 5-591 DRV_USB_ENDPOINT_TABLE_ENTRY_SIZE macro 5-595 DRV_USB_EVENT enumeration 5-596 DRV_USB_EVENT_CALLBACK type 5-597 DRV_USB_HOST_BusResetControl function 5-593 DRV_USB_HOST_DeviceCurrentSpeedGet function 5-593 DRV_USB_HOST_IRPCancel function 5-593 DRV_USB_HOST_IRPSubmit function 5-593 DRV_USB_HOST_OperationEnable function 5-593 DRV_USB_HOST_OperationIsEnabled function 5-578 DRV_USB_HOST_PIPE_HANDLE type 5-597 DRV_USB_HOST_PIPE_HANDLE_INVALID macro 5-595 DRV_USB_HOST_PipeClose function 5-581 DRV_USB_HOST_PipeSetup function 5-580 DRV_USB_HOST_StartOfFrameControl function 5-594 DRV_USB_HOST_TimerIsComplete function 5-594 DRV_USB_HOST_TimerReset function 5-594 DRV_USB_HOST_TimerStart function 5-594 DRV_USB_INDEX macro 5-595 DRV_USB_INDEX_0 macro 5-596 DRV_USB_INIT structure 5-597 DRV_USB_Initialize function 5-576 DRV_USB_INTERRUPT_SOURCE macro 5-596 DRV_USB_Open function 5-579 DRV_USB_PERIPHERAL_ID macro 5-596 DRV_USB_Status function 5-577 DRV_USB_Tasks function 5-594 DRV_USB_Tasks_ISR function 5-578 drv_wifi.h 5-674 DRV_WIFI_ADHOC_CONNECT_ONLY enumeration member 5-655 DRV_WIFI_ADHOC_CONNECT_THEN_START enumeration member 5-655 9 MPLAB Harmony Help m DRV_WIFI_ADHOC_MODES enumeration 5-655 DRV_WIFI_ADHOC_NETWORK_CONTEXT structure 5-655 DRV_WIFI_ADHOC_START_ONLY enumeration member 5-655 DRV_WIFI_AdhocContextSet function 5-636 DRV_WIFI_BSSID_LENGTH macro 5-647 DRV_WIFI_BssidGet function 5-613 DRV_WIFI_BssidSet function 5-614 DRV_WIFI_ChannelListGet function 5-615 DRV_WIFI_ChannelListSet function 5-615 DRV_WIFI_ConfigDataErase function 5-643 DRV_WIFI_ConfigDataLoad function 5-643 DRV_WIFI_ConfigDataPrint function 5-644 DRV_WIFI_ConfigDataSave function 5-644 DRV_WIFI_Connect function 5-641 DRV_WIFI_ConnectContextGet function 5-616 DRV_WIFI_CONNECTION_CONTEXT structure 5-656 DRV_WIFI_CONNECTION_STATES enumeration 5-656 DRV_WIFI_ConnectionStateGet function 5-616 DRV_WIFI_DEAUTH_REASONCODE_MASK macro 5-647 DRV_WIFI_DEFAULT_ADHOC_BEACON_PERIOD macro 5-647 DRV_WIFI_DEFAULT_ADHOC_HIDDEN_SSID macro 5-648 DRV_WIFI_DEFAULT_ADHOC_MODE macro 5-648 DRV_WIFI_DEFAULT_PS_DTIM_ENABLED macro 5-648 DRV_WIFI_DEFAULT_PS_DTIM_INTERVAL macro 5-648 DRV_WIFI_DEFAULT_PS_LISTEN_INTERVAL macro 5-648 DRV_WIFI_DEFAULT_SCAN_COUNT macro 5-648 DRV_WIFI_DEFAULT_SCAN_MAX_CHANNEL_TIME macro 5-649 DRV_WIFI_DEFAULT_SCAN_MIN_CHANNEL_TIME macro 5-649 DRV_WIFI_DEFAULT_SCAN_PROBE_DELAY macro 5-649 DRV_WIFI_DEFAULT_WEP_KEY_TYPE macro 5-649 DRV_WIFI_Deinitialize function 5-641 DRV_WIFI_DEVICE_INFO structure 5-657 DRV_WIFI_DEVICE_TYPES enumeration 5-657 DRV_WIFI_DeviceInfoGet function 5-617 DRV_WIFI_DISABLED macro 5-649 DRV_WIFI_DISASSOC_REASONCODE_MASK macro 5-649 DRV_WIFI_Disconnect function 5-641 DRV_WIFI_DOMAIN_CODES enumeration 5-657 DRV_WIFI_ENABLED macro 5-650 DRV_WIFI_EVENT_CONN_TEMP_LOST_CODES enumeration 5-658 DRV_WIFI_EVENT_INFO enumeration 5-658 DRV_WIFI_EVENTS enumeration 5-659 DRV_WIFI_GENERAL_ERRORS enumeration 5-660 DRV_WIFI_GratuitousArpStart function 5-638 DRV_WIFI_GratuitousArpStop function 5-638 DRV_WIFI_HIBERNATE_STATE structure 5-660 DRV_WIFI_HIBERNATE_STATES enumeration 5-660 DRV_WIFI_HibernateEnable function 5-639 DRV_WIFI_HWMulticastFilterGet function 5-617 DRV_WIFI_HWMulticastFilterSet function 5-618 DRV_WIFI_Initialize function 5-642 DRV_WIFI_isHibernateEnable function 5-639 DRV_WIFI_MAC_STATS structure 5-660 DRV_WIFI_MacAddressGet function 5-619 DRV_WIFI_MacAddressSet function 5-619 DRV_WIFI_MacStatsGet function 5-620 DRV_WIFI_MAX_CHANNEL_LIST_LENGTH macro 5-650 DRV_WIFI_MAX_NUM_RATES macro 5-650 DRV_WIFI_MAX_SECURITY_KEY_LENGTH macro 5-650 DRV_WIFI_MAX_SSID_LENGTH macro 5-650 DRV_WIFI_MAX_WEP_KEY_LENGTH macro 5-650 DRV_WIFI_MAX_WPA_PASS_PHRASE_LENGTH macro 5-650 DRV_WIFI_MAX_WPA2_PASS_PHRASE_LENGTH macro 5-651 DRV_WIFI_MGMT_ERRORS enumeration 5-661 DRV_WIFI_MGMT_INDICATE_SOFT_AP_EVENT structure 5-662 DRV_WIFI_MIN_WPA_PASS_PHRASE_LENGTH macro 5-651 DRV_WIFI_MULTICAST_FILTER_IDS enumeration 5-663 DRV_WIFI_MULTICAST_FILTERS enumeration 5-663 DRV_WIFI_NETWORK_TYPE_ADHOC macro 5-651 DRV_WIFI_NETWORK_TYPE_INFRASTRUCTURE macro 5-651 DRV_WIFI_NETWORK_TYPE_P2P macro 5-651 DRV_WIFI_NETWORK_TYPE_SOFT_AP macro 5-651 DRV_WIFI_NetworkTypeGet function 5-620 9 MPLAB Harmony Help n DRV_WIFI_NetworkTypeSet function 5-621 DRV_WIFI_NO_ADDITIONAL_INFO macro 5-652 DRV_WIFI_POWER_SAVE_STATES enumeration 5-664 DRV_WIFI_PowerSaveStateGet function 5-621 DRV_WIFI_ProcessEvent function 5-644 DRV_WIFI_PS_POLL_CONTEXT structure 5-664 DRV_WIFI_PsPollDisable function 5-640 DRV_WIFI_PsPollEnable function 5-640 DRV_WIFI_REASON_CODES enumeration 5-665 DRV_WIFI_RECONNECT_MODES enumeration 5-665 DRV_WIFI_ReconnectModeGet function 5-622 DRV_WIFI_ReconnectModeSet function 5-623 DRV_WIFI_RegionalDomainGet function 5-624 DRV_WIFI_RETRY_ADHOC macro 5-652 DRV_WIFI_RETRY_FOREVER macro 5-652 DRV_WIFI_RssiGet function 5-637 DRV_WIFI_RssiSet function 5-637 DRV_WIFI_RTS_THRESHOLD_MAX macro 5-652 DRV_WIFI_RtsThresholdGet function 5-625 DRV_WIFI_RtsThresholdSet function 5-625 DRV_WIFI_Scan function 5-642 DRV_WIFI_SCAN_CONTEXT structure 5-665 DRV_WIFI_SCAN_RESULT structure 5-666 DRV_WIFI_SCAN_TYPES enumeration 5-667 DRV_WIFI_ScanContextGet function 5-626 DRV_WIFI_ScanContextSet function 5-627 DRV_WIFI_ScanGetResult function 5-645 DRV_WIFI_SECURITY_CONTEXT union 5-667 DRV_WIFI_SECURITY_EAP macro 5-652 DRV_WIFI_SECURITY_OPEN macro 5-652 DRV_WIFI_SECURITY_WEP_104 macro 5-653 DRV_WIFI_SECURITY_WEP_40 macro 5-653 DRV_WIFI_SECURITY_WPA_AUTO_WITH_KEY macro 5-653 DRV_WIFI_SECURITY_WPA_AUTO_WITH_PASS_PHRASE macro 5-653 DRV_WIFI_SECURITY_WPA_WITH_KEY macro 5-653 DRV_WIFI_SECURITY_WPA_WITH_PASS_PHRASE macro 5-653 DRV_WIFI_SECURITY_WPA2_WITH_KEY macro 5-654 DRV_WIFI_SECURITY_WPA2_WITH_PASS_PHRASE macro 5-654 DRV_WIFI_SECURITY_WPS_PIN macro 5-654 DRV_WIFI_SECURITY_WPS_PUSH_BUTTON macro 5-654 DRV_WIFI_SecurityGet function 5-627 DRV_WIFI_SecurityOpenSet function 5-628 DRV_WIFI_SecurityWepSet function 5-628 DRV_WIFI_SecurityWpaSet function 5-629 DRV_WIFI_SecurityWpsSet function 5-630 DRV_WIFI_SetLinkDownThreshold function 5-645 DRV_WIFI_SetPSK function 5-646 DRV_WIFI_SOFT_AP_EVENT_REASON_CODES enumeration 5-667 DRV_WIFI_SOFT_AP_STATES enumeration 5-668 DRV_WIFI_SoftApEventInfoGet function 5-630 DRV_WIFI_SsidGet function 5-631 DRV_WIFI_SsidSet function 5-631 DRV_WIFI_STATUS_CODES enumeration 5-668 DRV_WIFI_SWMULTICAST_CONFIG structure 5-668 DRV_WIFI_SWMultiCastFilterEnable function 5-646 DRV_WIFI_SWMulticastFilterSet function 5-632 DRV_WIFI_TX_MODES enumeration 5-669 DRV_WIFI_TxModeGet function 5-633 DRV_WIFI_TxModeSet function 5-633 DRV_WIFI_TxPowerFactoryMaxGet function 5-634 DRV_WIFI_TxPowerMaxGet function 5-634 DRV_WIFI_TxPowerMaxSet function 5-635 DRV_WIFI_VERSION_NUMBER macro 5-654 DRV_WIFI_WEP_CONTEXT structure 5-669 DRV_WIFI_WEP_KEY_TYPE enumeration 5-670 DRV_WIFI_WEP104_KEY_LENGTH macro 5-654 DRV_WIFI_WEP40_KEY_LENGTH macro 5-654 DRV_WIFI_WepKeyTypeGet function 5-635 DRV_WIFI_WPA_CONTEXT structure 5-670 DRV_WIFI_WPA_KEY_INFO structure 5-671 DRV_WIFI_WPA_KEY_LENGTH macro 5-655 DRV_WIFI_WPA2_KEY_LENGTH macro 5-655 DRV_WIFI_WPS_AUTH_TYPES enumeration 5-671 DRV_WIFI_WPS_CONTEXT structure 5-671 DRV_WIFI_WPS_CREDENTIAL structure 5-672 DRV_WIFI_WPS_ENCODE_TYPES enumeration 5-673 9 MPLAB Harmony Help o DRV_WIFI_WPS_PIN_LENGTH macro 5-655 DRV_WIFI_WPSCredentialsGet function 5-636 DRV_WIFI_YieldPassphraseToHost function 5-647 DSP Fixed-Point Library 5-1167 DSP Math Library 4-181 dsp.h 5-1268 DSP_ComplexAdd32 function 5-1175 DSP_ComplexConj16 function 5-1175 DSP_ComplexConj32 function 5-1176 DSP_ComplexDotProd32 function 5-1177 DSP_ComplexMult32 function 5-1178 DSP_ComplexScalarMult32 function 5-1179 DSP_ComplexSub32 function 5-1180 DSP_FilterFIR32 function 5-1180 DSP_FilterFIRDecim32 function 5-1182 DSP_FilterFIRInterp32 function 5-1183 DSP_FilterIIR16 function 5-1184 DSP_FilterIIRBQ16 function 5-1185 DSP_FilterIIRBQ16_cascade8 function 5-1187 DSP_FilterIIRBQ16_cascade8_fast function 5-1188 DSP_FilterIIRBQ16_fast function 5-1190 DSP_FilterIIRBQ16_parallel8 function 5-1191 DSP_FilterIIRBQ16_parallel8_fast function 5-1193 DSP_FilterIIRBQ32 function 5-1194 DSP_FilterIIRSetup16 function 5-1195 DSP_FilterLMS16 function 5-1196 DSP_MatrixAdd32 function 5-1197 DSP_MatrixEqual32 function 5-1199 DSP_MatrixInit32 function 5-1199 DSP_MatrixMul32 function 5-1200 DSP_MatrixScale32 function 5-1202 DSP_MatrixSub32 function 5-1202 DSP_MatrixTranspose32 function 5-1204 DSP_TransformFFT16 function 5-1205 DSP_TransformFFT16_setup function 5-1206 DSP_TransformFFT32 function 5-1206 DSP_TransformFFT32_setup function 5-1207 DSP_TransformIFFT16 function 5-1208 DSP_TransformWindow_Bart16 function 5-1209 DSP_TransformWindow_Bart32 function 5-1210 DSP_TransformWindow_Black16 function 5-1211 DSP_TransformWindow_Black32 function 5-1212 DSP_TransformWindow_Cosine16 function 5-1213 DSP_TransformWindow_Cosine32 function 5-1213 DSP_TransformWindow_Hamm16 function 5-1214 DSP_TransformWindow_Hamm32 function 5-1215 DSP_TransformWindow_Hann16 function 5-1216 DSP_TransformWindow_Hann32 function 5-1217 DSP_TransformWindow_Kaiser16 function 5-1217 DSP_TransformWindow_Kaiser32 function 5-1218 DSP_TransformWinInit_Bart16 function 5-1219 DSP_TransformWinInit_Bart32 function 5-1220 DSP_TransformWinInit_Black16 function 5-1220 DSP_TransformWinInit_Black32 function 5-1221 DSP_TransformWinInit_Cosine16 function 5-1222 DSP_TransformWinInit_Cosine32 function 5-1223 DSP_TransformWinInit_Hamm16 function 5-1223 DSP_TransformWinInit_Hamm32 function 5-1224 DSP_TransformWinInit_Hann16 function 5-1225 DSP_TransformWinInit_Hann32 function 5-1225 DSP_TransformWinInit_Kaiser16 function 5-1226 DSP_TransformWinInit_Kaiser32 function 5-1227 DSP_VectorAbs16 function 5-1228 DSP_VectorAbs32 function 5-1228 DSP_VectorAdd16 function 5-1229 DSP_VectorAdd32 function 5-1230 DSP_VectorAddc16 function 5-1231 DSP_VectorAddc32 function 5-1232 DSP_VectorAutocorr16 function 5-1233 DSP_VectorBexp16 function 5-1234 DSP_VectorBexp32 function 5-1234 DSP_VectorChkEqu32 function 5-1235 DSP_VectorCopy function 5-1236 DSP_VectorCopyReverse32 function 5-1237 DSP_VectorDivC function 5-1238 DSP_VectorDotp16 function 5-1238 DSP_VectorDotp32 function 5-1239 DSP_VectorExp function 5-1240 9 MPLAB Harmony Help p DSP_VectorFill function 5-1241 DSP_VectorLn function 5-1242 DSP_VectorLog10 function 5-1243 DSP_VectorLog2 function 5-1244 DSP_VectorMax32 function 5-1244 DSP_VectorMaxIndex32 function 5-1245 DSP_VectorMean32 function 5-1246 DSP_VectorMin32 function 5-1247 DSP_VectorMinIndex32 function 5-1247 DSP_VectorMul16 function 5-1248 DSP_VectorMul32 function 5-1249 DSP_VectorMulc16 function 5-1250 DSP_VectorMulc32 function 5-1251 DSP_VectorNegate function 5-1252 DSP_VectorRecip function 5-1253 DSP_VectorRMS16 function 5-1254 DSP_VectorShift function 5-1254 DSP_VectorSqrt function 5-1255 DSP_VectorStdDev16 function 5-1256 DSP_VectorSub16 function 5-1257 DSP_VectorSub32 function 5-1258 DSP_VectorSumSquares16 function 5-1259 DSP_VectorSumSquares32 function 5-1259 DSP_VectorVari16 function 5-1260 DSP_VectorVariance function 5-1261 DSP_VectorZeroPad function 5-1262 Dual Compare Continuous Mode 5-2292 Dynamic Configuration 5-3426 Dynamic DNS TCP/IP Stack Library 5-3646 E EBI Peripheral Library 5-1864 EMAC_RX_BUFF_SIZE macro 5-3750 EMAC_RX_DESCRIPTORS macro 5-3750 EMAC_RX_FRAGMENTS macro 5-3750 EMAC_RX_MAX_FRAME macro 5-3751 EMAC_TX_DESCRIPTORS macro 5-3751 ENABLE_P2P_PRINTS macro 5-673 ENABLE_WPS_PRINTS macro 5-673 EnablePalette function 5-828 Enabling 5-3956 Enabling Events 5-1560 END_OF_SNMP_READ_COMMUNITIES macro 5-3826 END_OF_SNMP_WRITE_COMMUNITIES macro 5-3826 Endpoint Pipes 5-557 Enhanced Buffer Master Mode 5-2807 Enhanced Buffer Slave Mode 5-2809 Enhanced Buffer SPI Mode 5-2807 Error Operation 5-1321 ETH_AUTOPAD_OPTION enumeration 5-2050 ETH_CFG_10 macro 5-3751 ETH_CFG_100 macro 5-3751 ETH_CFG_AUTO macro 5-3751 ETH_CFG_AUTO_MDIX macro 5-3752 ETH_CFG_FDUPLEX macro 5-3752 ETH_CFG_HDUPLEX macro 5-3752 ETH_CFG_LINK macro 5-3752 ETH_CFG_LINK_INIT_DELAY macro 5-3752 ETH_CFG_SWAP_MDIX macro 5-3752 ETH_CLOSE_FLAGS enumeration 5-247 ETH_INTERRUPT_SOURCES enumeration 5-2050 ETH_LINK_STATUS enumeration 5-247 ETH_MIIM_CLK enumeration 5-2050 ETH_MODULE_STATUS enumeration 5-248 ETH_OPEN_FLAGS enumeration 5-248 ETH_PATTERN_MATCH_MODE type 5-2051 ETH_PAUSE_TYPE enumeration 5-249 ETH_RECEIVE_FILTER enumeration 5-2051 ETH_RESULT_CODE enumeration 5-250 ETH_RMII_SPEED enumeration 5-2052 Ethernet Controller Operation 5-1909 Ethernet DMA and Buffer Management Engine 5-1912 Ethernet Frame Overview 5-1909 Ethernet MAC Driver Library 5-226 Ethernet Peripheral Library 5-1902 Ethernet PHY Driver Library 5-254 ETHPHY_CONFIG_FLAGS enumeration 5-251 Event Handling 5-563, 5-3975, 5-3981, 5-4066, 5-4135 9 MPLAB Harmony Help q Events 5-1317 Example - Channel Scanning 5-1476 Example - Digital Comparator 5-1478 Example - Digital Oversampling Filter 5-1477 Example - Simultaneous Sampling Three Class 1 Inputs 5-1475 Example Code for Complete Operation 5-374 Example Usage of the Timer Driver 5-467 Examples 5-3514 Examples - Sample Functionality 5-609, 5-1324, 5-3366 Exception Generator 5-1522 Explorer 16 Development Board 3-78, 3-104, 3-124, 3-143, 3-171 Explorer 16 PIC32MX795F512L BSP Library 7-4230 Extended ID Message Format 5-1556 EXTPHY_MDIXCONFIGURE type 5-281 EXTPHY_MIICONFIGURE type 5-281 EXTPHY_SMIADDRESSGET type 5-282 EXTPHY_SMICLOCKGET type 5-282 F Fail-Safe Clock Monitor 5-2335 FAT_FS_MAX_LFN macro 5-3417 FAT_FS_MAX_SS macro 5-3417 FAT_FS_USE_LFN macro 5-3417 File EOF 5-3395 File Seek 5-3396 File System Demonstrations 3-64 File System Service Library 5-3376 File Tell 5-3396 FileFeof type 5-889 FileRead type 5-890 Files 3-111, 3-128, 3-148, 5-192, 5-225, 5-252, 5-286, 5-295, 5-308, 5-318, 5-332, 5-341, 5-365, 5-395, 5-416, 5-454, 5-508, 5-549, 5-598, 5-608, 5-674, 5-1062, 5-1126, 5-1164, 5-1268, 5-1307, 5-1358, 5-1466, 5-1518, 5-1551, 5-1662, 5-1730, 5-1858, 5-1900, 5-2052, 5-2166, 5-2200, 5-2250, 5-2285, 5-2328, 5-2423, 5-2475, 5-2588, 5-2659, 5-2686, 5-2702, 5-2759, 5-2796, 5-2887, 5-3006, 5-3081, 5-3164, 5-3312, 5-3330, 5-3345, 5-3362, 5-3374, 5-3418, 5-3437, 5-3463, 5-3498, 5-3528, 5-3534, 5-3573, 5-3596, 5-3613, 5-3623, 5-3634, 5-3645, 5-3653, 5-3658, 5-3687, 5-3696, 5-3707, 5-3716, 5-3745, 5-3769, 5-3793, 5-3797, 5-3805, 5-3808, 5-3821, 5-3853, 5-3866, 5-3879, 5-3910, 5-3916, 5-3928, 5-3952, 5-3962, 5-4002, 5-4057, 5-4098, 5-4129, 5-4166, 5-4178, 5-4198, 5-4223, 7-4245 Files to Include 5-3979, 5-4007, 5-4064, 5-4104, 5-4133 FileSeek type 5-890 FileTell type 5-890 Filters and Masks Configuration 5-1559 Fixed-Point Math Library 4-182 Flash ECC Operations 5-2434 Flash Operations 5-2256 Flow Control Overview 5-1911 FONT_ORIENTATION enumeration 5-890 Fonts 5-1123 Forming Transfers 5-2084 Framed SPI Modes 5-2810 Framework Help 5-184 FreeRTOS RTOS with Graphics 3-116 FreeRTOS_basic_demo 3-114 FTP TCP/IP Stack Library 5-3654 ftp.h 5-3658 ftp_config.h 5-3659 FTP_MODULE_CONFIG structure 5-3658 Functions 5-301, 5-311, 5-326, 5-335, 5-4201 Functions Registeration Table 5-4013 G Gated Timer 5-3019 General 5-1367 General Configuration 5-1736 Generating Server Certificates 5-3870 generic_device 3-164 GENERIC_TRAP_NOTIFICATION_TYPE enumeration 5-3847 gethostname function 5-3604 GetPaletteChangeError function 5-828 Getting Help 5-3542 Getting Started 5-3378 gfx.h 5-1062 GFX_ActivePageGet macro 5-947 GFX_ALIGNMENT enumeration 5-890 GFX_ALPHA_PARAMS structure 5-295 GFX_AlphaBlendingValueGet function 5-828 9 MPLAB Harmony Help r GFX_AlphaBlendingValueSet function 5-829 GFX_AlphaBlendWindow function 5-829 GFX_AlphaParamsSet macro 5-947 GFX_AnalogClockCreate function 5-718 GFX_BACKGROUND structure 5-891 GFX_BACKGROUND_TYPE enumeration 5-891 GFX_BackgroundColorGet function 5-830 GFX_BackgroundImageGet function 5-830 GFX_BackgroundImageLeftGet function 5-830 GFX_BackgroundImageTopGet function 5-831 GFX_BackgroundSet function 5-831 GFX_BackgroundTypeGet function 5-832 GFX_BackgroundTypeSet function 5-832 GFX_BarAlphaDraw function 5-832 GFX_BarDraw function 5-833 GFX_BarGradientDraw function 5-835 GFX_BEVEL_RENDER_TYPE enumeration 5-892 GFX_BevelDraw function 5-836 GFX_BevelDrawTypeGet function 5-836 GFX_BevelDrawTypeSet function 5-836 GFX_BevelGradientDraw function 5-836 GFX_BUFFER1 macro 5-948 GFX_BUFFER2 macro 5-948 GFX_CircleDraw function 5-838 GFX_CircleFillDraw function 5-838 GFX_COLOR type 5-892 GFX_ColorGet function 5-839 gfx_colors.h 5-1063 gfx_colors_w3.h 5-1064 gfx_colors_x11.h 5-1068 GFX_ColorSet function 5-839 GFX_COMP_MASK macro 5-948 GFX_CONFIG_DRIVER_COUNT macro 5-294 GFX_CONFIG_OBJECT_METER_DEGREECOUNT macro 5-948 GFX_CONFIG_OBJECT_METER_RESOLUTION macro 5-948 GFX_CONFIG_OBJECT_METER_SCALE_COUNT macro 5-949 gfx_config_template.h 5-1071 GFX_CosineGet macro 5-1125 GFX_DOUBLE_BUFFERING_MODE structure 5-892 GFX_DoubleBufferAreaGet function 5-840 GFX_DoubleBufferAreaMark function 5-840 GFX_DoubleBufferDisable function 5-840 GFX_DoubleBufferEnable function 5-840 GFX_DoubleBufferStatusGet function 5-841 GFX_DoubleBufferSyncAllStatusClear function 5-841 GFX_DoubleBufferSyncAllStatusGet function 5-841 GFX_DoubleBufferSyncAllStatusSet function 5-841 GFX_DoubleBufferSyncAreaCountGet function 5-841 GFX_DoubleBufferSyncAreaCountSet function 5-841 GFX_DoubleBufferSynchronize function 5-841 GFX_DoubleBufferSynchronizeCancel function 5-841 GFX_DoubleBufferSynchronizeRequest function 5-841 GFX_DoubleBufferSynchronizeSet function 5-841 GFX_DoubleBufferSynchronizeStatusGet function 5-841 GFX_DoubleBufferVisualPageUpdate function 5-842 GFX_DrawBufferGet function 5-842 GFX_DrawBufferSelect function 5-842 GFX_DrawBufferSet function 5-842 GFX_DRV_DATA structure 5-292 GFX_DRV_FontSet function 5-842 GFX_DRV_FUNCTIONS structure 5-293 GFX_DRV_lcc_BrightnessSet function 5-302 GFX_DRV_lcc_Close function 5-301 GFX_DRV_lcc_COMMAND structure 5-306 GFX_DRV_lcc_COMMANDQUEUESIZE macro 5-307 GFX_DRV_lcc_Initialize function 5-302 GFX_DRV_lcc_Layer function 5-305 GFX_DRV_lcc_Open function 5-302 GFX_DRV_lcc_PixelArrayGet function 5-303 GFX_DRV_lcc_PixelArrayPut function 5-303 GFX_DRV_lcc_PixelPut function 5-303 GFX_DRV_lcc_PixelsPut function 5-304 GFX_DRV_lcc_SetColor function 5-304 GFX_DRV_lcc_SetInstance function 5-304 GFX_DRV_lcc_SetPage function 5-305 GFX_DRV_lcc_Tasks function 5-302 GFX_DRV_OTM2201A_AddressSet function 5-312 9 MPLAB Harmony Help s GFX_DRV_OTM2201A_BrightnessSet function 5-312 GFX_DRV_OTM2201A_Busy function 5-312 GFX_DRV_OTM2201A_Close function 5-313 GFX_DRV_OTM2201A_ColorSet function 5-313 GFX_DRV_OTM2201A_COMMAND structure 5-317 GFX_DRV_OTM2201A_Initialize function 5-313 GFX_DRV_OTM2201A_InstanceSet function 5-314 GFX_DRV_OTM2201A_Open function 5-314 GFX_DRV_OTM2201A_PixelArrayGet function 5-314 GFX_DRV_OTM2201A_PixelArrayPut function 5-315 GFX_DRV_OTM2201A_PixelPut function 5-315 GFX_DRV_OTM2201A_PixelsPut function 5-316 GFX_DRV_OTM2201A_RegGet function 5-316 GFX_DRV_OTM2201A_RegSet function 5-316 GFX_DRV_OTM2201A_Tasks function 5-317 GFX_DRV_S1D13517_AlphaBlendWindow function 5-327 GFX_DRV_S1D13517_BrightnessSet function 5-327 GFX_DRV_S1D13517_Close function 5-327 GFX_DRV_S1D13517_COMMAND structure 5-331 GFX_DRV_S1D13517_GetReg function 5-327 GFX_DRV_S1D13517_Initialize function 5-328 GFX_DRV_S1D13517_Layer function 5-328 GFX_DRV_S1D13517_Open function 5-328 GFX_DRV_S1D13517_PixelArrayPut function 5-329 GFX_DRV_S1D13517_PixelPut function 5-329 GFX_DRV_S1D13517_PixelsPut function 5-329 GFX_DRV_S1D13517_SetColor function 5-330 GFX_DRV_S1D13517_SetInstance function 5-330 GFX_DRV_S1D13517_SetPage function 5-330 GFX_DRV_S1D13517_SetReg function 5-331 GFX_DRV_S1D13517_Tasks function 5-331 GFX_DRV_SSD1926_BarFill function 5-336 GFX_DRV_SSD1926_BrightnessSet function 5-336 GFX_DRV_SSD1926_Busy function 5-336 GFX_DRV_SSD1926_Close function 5-336 GFX_DRV_SSD1926_COMMAND structure 5-340 GFX_DRV_SSD1926_GetReg function 5-337 GFX_DRV_SSD1926_Initialize function 5-337 GFX_DRV_SSD1926_Open function 5-337 GFX_DRV_SSD1926_PixelArrayGet function 5-338 GFX_DRV_SSD1926_PixelArrayPut function 5-338 GFX_DRV_SSD1926_PixelPut function 5-339 GFX_DRV_SSD1926_PixelsPut function 5-339 GFX_DRV_SSD1926_SetColor function 5-339 GFX_DRV_SSD1926_SetInstance function 5-339 GFX_DRV_SSD1926_SetReg function 5-340 GFX_DRV_SSD1926_TASK structure 5-341 GFX_DRV_SSD1926_Tasks function 5-340 GFX_DRV_TextStringWidthGet function 5-842 GFX_ExternalCharInfoGet function 5-843 GFX_ExternalResourceCallback function 5-843 GFX_FEATURE_STATUS enumeration 5-893 GFX_FILL_STYLE enumeration 5-893 GFX_FillStyleGet function 5-844 GFX_FillStyleSet function 5-844 GFX_FlashCharInfoGet function 5-845 GFX_FONT_ANTIALIAS_TYPE enumeration 5-893 GFX_FONT_CURRENT structure 5-894 GFX_FONT_GLYPH_ENTRY structure 5-894 GFX_FONT_GLYPH_ENTRY_EXTENDED structure 5-895 GFX_FONT_HEADER structure 5-895 GFX_FONT_OUTCHAR structure 5-895 GFX_FONT_SPACE macro 5-949 GFX_FontAlignmentSet macro 5-949 GFX_FontAntiAliasGet function 5-845 GFX_FontAntiAliasSet function 5-845 GFX_FontGet function 5-846 GFX_FontSet function 5-846 GFX_FrameBufferGet function 5-846 GFX_FrameBufferSelect function 5-846 GFX_free macro 5-326 gfx_gol.h 5-1072 gfx_gol_analog_clock.h 5-1074 GFX_GOL_ANALOGCLOCK structure 5-896 GFX_GOL_ANALOGCLOCK_DISABLED macro 5-949 GFX_GOL_ANALOGCLOCK_DRAW macro 5-950 GFX_GOL_ANALOGCLOCK_HIDE macro 5-950 GFX_GOL_ANALOGCLOCK_PRESSED macro 5-950 9 MPLAB Harmony Help t GFX_GOL_ANALOGCLOCK_TICK macro 5-950 GFX_GOL_ANALOGCLOCK_UPDATE_HOUR macro 5-950 GFX_GOL_ANALOGCLOCK_UPDATE_MINUTE macro 5-950 GFX_GOL_ANALOGCLOCK_UPDATE_SECOND macro 5-951 GFX_GOL_AnalogClockDraw function 5-719 GFX_GOL_AnalogClockHandsDraw function 5-720 GFX_GOL_AnalogClockHourSet function 5-721 GFX_GOL_AnalogClockMinuteSet function 5-721 GFX_GOL_AnalogClockSecondSet function 5-722 GFX_GOL_BUTTON structure 5-896 gfx_gol_button.h 5-1075 GFX_GOL_BUTTON_STATE enumeration 5-897 GFX_GOL_ButtonActionGet function 5-722 GFX_GOL_ButtonActionSet function 5-723 GFX_GOL_ButtonCreate function 5-724 GFX_GOL_ButtonDraw function 5-726 GFX_GOL_ButtonPressStateImageGet macro 5-951 GFX_GOL_ButtonPressStateImageSet macro 5-951 GFX_GOL_ButtonReleaseStateImageGet macro 5-952 GFX_GOL_ButtonReleaseStateImageSet macro 5-952 GFX_GOL_ButtonTextAlignmentGet function 5-726 GFX_GOL_ButtonTextAlignmentSet function 5-727 GFX_GOL_ButtonTextGet macro 5-953 GFX_GOL_ButtonTextSet function 5-727 GFX_GOL_CHART structure 5-898 gfx_gol_chart.h 5-1076 GFX_GOL_CHART_3D_ENABLE macro 5-953 GFX_GOL_CHART_BAR macro 5-953 GFX_GOL_CHART_BAR_HOR macro 5-953 GFX_GOL_CHART_DISABLED macro 5-954 GFX_GOL_CHART_DONUT macro 5-954 GFX_GOL_CHART_DRAW macro 5-954 GFX_GOL_CHART_DRAW_DATA macro 5-954 GFX_GOL_CHART_HIDE macro 5-954 GFX_GOL_CHART_LEGEND macro 5-954 GFX_GOL_CHART_NUMERIC macro 5-955 GFX_GOL_CHART_PERCENT macro 5-955 GFX_GOL_CHART_PIE macro 5-955 GFX_GOL_CHART_VALUE macro 5-955 GFX_GOL_ChartActionGet function 5-733 GFX_GOL_ChartAxisLabelFontGet macro 5-955 GFX_GOL_ChartAxisLabelFontSet macro 5-956 GFX_GOL_ChartColorTableGet macro 5-956 GFX_GOL_ChartColorTableSet macro 5-957 GFX_GOL_ChartCreate function 5-734 GFX_GOL_ChartDataSeriesAdd function 5-736 GFX_GOL_ChartDataSeriesFree function 5-736 GFX_GOL_ChartDataSeriesRemove function 5-737 GFX_GOL_ChartDataSeriesSet function 5-737 GFX_GOL_ChartDraw function 5-738 GFX_GOL_ChartGridLabelFontGet macro 5-957 GFX_GOL_ChartGridLabelFontSet macro 5-958 GFX_GOL_ChartPercentMaxGet macro 5-958 GFX_GOL_ChartPercentMinGet macro 5-959 GFX_GOL_ChartPercentRangeGet macro 5-959 GFX_GOL_ChartPercentRangeSet function 5-738 GFX_GOL_ChartSampleEndGet macro 5-960 GFX_GOL_ChartSampleLabelGet macro 5-960 GFX_GOL_ChartSampleLabelSet macro 5-960 GFX_GOL_ChartSampleRangeGet macro 5-961 GFX_GOL_ChartSampleRangeSet function 5-739 GFX_GOL_ChartSampleStartGet macro 5-961 GFX_GOL_ChartSeriesHide macro 5-962 GFX_GOL_ChartShowSeriesCountGet macro 5-962 GFX_GOL_ChartShowSeriesSet macro 5-963 GFX_GOL_ChartShowSeriesStatusGet macro 5-963 GFX_GOL_ChartTitleFontGet macro 5-964 GFX_GOL_ChartTitleFontSet macro 5-964 GFX_GOL_ChartTitleGet macro 5-965 GFX_GOL_ChartTitleSet macro 5-965 GFX_GOL_ChartValueLabelGet macro 5-966 GFX_GOL_ChartValueLabelSet macro 5-966 GFX_GOL_ChartValueMaxGet macro 5-967 GFX_GOL_ChartValueMinGet macro 5-967 GFX_GOL_ChartValueRangeGet macro 5-968 GFX_GOL_ChartValueRangeSet function 5-740 gfx_gol_check_box.h 5-1080 GFX_GOL_CHECKBOX structure 5-898 9 MPLAB Harmony Help u GFX_GOL_CHECKBOX_STATE enumeration 5-899 GFX_GOL_CheckBoxActionGet function 5-728 GFX_GOL_CheckBoxActionSet function 5-729 GFX_GOL_CheckBoxCreate function 5-730 GFX_GOL_CheckBoxDraw function 5-731 GFX_GOL_CheckBoxTextAlignmentGet function 5-732 GFX_GOL_CheckBoxTextAlignmentSet function 5-732 GFX_GOL_CheckBoxTextGet macro 5-968 GFX_GOL_CheckBoxTextSet function 5-732 gfx_gol_custom_control.h 5-1080 GFX_GOL_CUSTOMCONTROL structure 5-899 GFX_GOL_CUSTOMCONTROL_DISABLED macro 5-969 GFX_GOL_CUSTOMCONTROL_DRAW macro 5-969 GFX_GOL_CUSTOMCONTROL_DRAW_BAR macro 5-969 GFX_GOL_CUSTOMCONTROL_HIDE macro 5-969 GFX_GOL_CustomControlActionGet function 5-740 GFX_GOL_CustomControlActionSet function 5-741 GFX_GOL_CustomControlCreate function 5-741 GFX_GOL_CustomControlDraw function 5-742 GFX_GOL_CustomControlGetPos macro 5-969 GFX_GOL_CustomControlSetPos macro 5-970 gfx_gol_digital_meter.h 5-1081 GFX_GOL_DIGITALMETER structure 5-900 GFX_GOL_DIGITALMETER_INDENT macro 5-970 GFX_GOL_DIGITALMETER_STATE enumeration 5-901 GFX_GOL_DIGITALMETER_WIDTH macro 5-970 GFX_GOL_DigitalMeterActionGet function 5-742 GFX_GOL_DigitalMeterCreate function 5-743 GFX_GOL_DigitalMeterDecrement function 5-744 GFX_GOL_DigitalMeterDraw function 5-745 GFX_GOL_DigitalMeterIncrement function 5-745 GFX_GOL_DigitalMeterTextAlignmentGet macro 5-1057 GFX_GOL_DigitalMeterTextAlignmentSet macro 5-1058 GFX_GOL_DigitalMeterValueGet macro 5-970 GFX_GOL_DigitalMeterValueSet function 5-746 GFX_GOL_DRAW_CALLBACK_FUNC type 5-901 GFX_GOL_DrawCallbackSet function 5-702 gfx_gol_edit_box.h 5-1082 GFX_GOL_EDITBOX structure 5-902 GFX_GOL_EDITBOX_STATE enumeration 5-1056 GFX_GOL_EditBoxActionGet function 5-747 GFX_GOL_EditBoxActionSet function 5-748 GFX_GOL_EditBoxCharAdd function 5-749 GFX_GOL_EditBoxCharRemove function 5-749 GFX_GOL_EditBoxCreate function 5-750 GFX_GOL_EditBoxDraw function 5-751 GFX_GOL_EditBoxTextAlignmentGet macro 5-1058 GFX_GOL_EditBoxTextAlignmentSet macro 5-1059 GFX_GOL_EditBoxTextGet macro 5-1059 GFX_GOL_EditBoxTextSet function 5-751 gfx_gol_font_default.h 5-1083 GFX_GOL_FONT_DEFAULT_H_FILE macro 5-971 gfx_gol_grid.h 5-1083 gfx_gol_group_box.h 5-1085 GFX_GOL_GROUPBOX structure 5-902 GFX_GOL_GROUPBOX_STATE enumeration 5-903 GFX_GOL_GroupboxActionGet function 5-759 GFX_GOL_GroupboxCreate function 5-760 GFX_GOL_GroupboxDraw function 5-761 GFX_GOL_GroupboxTextAlignmentGet function 5-761 GFX_GOL_GroupboxTextAlignmentSet function 5-762 GFX_GOL_GroupboxTextGet macro 5-971 GFX_GOL_GroupboxTextSet function 5-762 gfx_gol_list_box.h 5-1086 GFX_GOL_LISTBOX structure 5-903 GFX_GOL_LISTBOX_ITEM_STATUS enumeration 5-903 GFX_GOL_LISTBOX_STATE enumeration 5-904 GFX_GOL_ListBoxActionGet function 5-763 GFX_GOL_ListBoxActionSet function 5-764 GFX_GOL_ListBoxCreate function 5-765 GFX_GOL_ListBoxDraw function 5-766 GFX_GOL_ListBoxItemAdd function 5-767 GFX_GOL_ListBoxItemCountGet macro 5-972 GFX_GOL_ListBoxItemFocusGet function 5-768 GFX_GOL_ListBoxItemFocusSet function 5-769 GFX_GOL_ListBoxItemImageGet macro 5-972 GFX_GOL_ListBoxItemImageSet macro 5-973 GFX_GOL_ListBoxItemListGet macro 5-973 9 MPLAB Harmony Help v GFX_GOL_ListBoxItemListRemove function 5-769 GFX_GOL_ListBoxItemRemove function 5-770 GFX_GOL_ListBoxItemSelectStatusClear macro 5-974 GFX_GOL_ListBoxItemSelectStatusSet macro 5-974 GFX_GOL_ListBoxSelectionChange function 5-770 GFX_GOL_ListBoxSelectionGet function 5-771 GFX_GOL_ListBoxTextAlignmentGet macro 5-1060 GFX_GOL_ListBoxTextAlignmentSet macro 5-1060 GFX_GOL_ListBoxVisibleItemCountGet function 5-772 GFX_GOL_LISTITEM structure 5-904 GFX_GOL_MESSAGE structure 5-905 GFX_GOL_MessageCallbackSet function 5-702 GFX_GOL_METER structure 5-906 gfx_gol_meter.h 5-1087 GFX_GOL_METER_DRAW_TYPE enumeration 5-907 GFX_GOL_METER_STATE enumeration 5-907 GFX_GOL_MeterActionGet function 5-772 GFX_GOL_MeterActionSet function 5-773 GFX_GOL_MeterCreate function 5-773 GFX_GOL_MeterDecrement function 5-775 GFX_GOL_MeterDraw function 5-776 GFX_GOL_MeterIncrement function 5-776 GFX_GOL_MeterMaximumValueGet macro 5-975 GFX_GOL_MeterMinimumValueGet macro 5-975 GFX_GOL_MeterRangeSet function 5-777 GFX_GOL_MeterScaleColorsSet function 5-777 GFX_GOL_MeterTitleFontSet macro 5-976 GFX_GOL_MeterTypeSet macro 5-976 GFX_GOL_MeterValueFontSet macro 5-976 GFX_GOL_MeterValueGet macro 5-977 GFX_GOL_MeterValueSet function 5-778 GFX_GOL_OBJ_HEADER structure 5-908 GFX_GOL_OBJ_SCHEME structure 5-908 GFX_GOL_OBJ_TYPE enumeration 5-910 GFX_GOL_ObjectAdd function 5-703 GFX_GOL_ObjectBackGroundSet function 5-704 GFX_GOL_ObjectByIDDelete function 5-704 GFX_GOL_ObjectCanBeFocused function 5-704 GFX_GOL_ObjectDelete function 5-705 GFX_GOL_ObjectDrawDisable function 5-705 GFX_GOL_ObjectDrawEnable function 5-706 GFX_GOL_ObjectFind function 5-707 GFX_GOL_ObjectFocusGet function 5-707 GFX_GOL_ObjectFocusNextGet function 5-708 GFX_GOL_ObjectFocusPrevGet function 5-708 GFX_GOL_ObjectFocusSet function 5-709 GFX_GOL_ObjectHideDraw function 5-709 GFX_GOL_ObjectIDGet function 5-709 GFX_GOL_ObjectIsRedrawSet function 5-710 GFX_GOL_ObjectListDraw function 5-711 GFX_GOL_ObjectListFree function 5-711 GFX_GOL_ObjectListGet function 5-712 GFX_GOL_ObjectListNew function 5-712 GFX_GOL_ObjectListSet function 5-713 GFX_GOL_ObjectMessage function 5-714 GFX_GOL_ObjectNextGet function 5-715 GFX_GOL_ObjectRectangleRedraw function 5-715 GFX_GOL_ObjectStateClear macro 5-978 GFX_GOL_ObjectStateGet macro 5-978 GFX_GOL_ObjectStateSet macro 5-979 GFX_GOL_ObjectTypeGet function 5-716 GFX_GOL_PanelAlphaParameterSet function 5-717 GFX_GOL_PanelBackgroundSet function 5-717 GFX_GOL_PanelDraw function 5-717 GFX_GOL_PanelGradientParameterSet function 5-717 GFX_GOL_PanelParameterSet function 5-717 gfx_gol_picture.h 5-1087 GFX_GOL_PICTURECONTROL structure 5-1056 GFX_GOL_PictureControlActionGet function 5-783 GFX_GOL_PICTURECONTROLCONTROL_STATE enumeration 5-1057 GFX_GOL_PictureControlCreate function 5-784 GFX_GOL_PictureControlDraw function 5-785 GFX_GOL_PictureControlImageGet macro 5-1061 GFX_GOL_PictureControlImageSet macro 5-1061 GFX_GOL_PictureControlPartialSet function 5-785 GFX_GOL_PictureControlScaleSet macro 5-1062 gfx_gol_progress_bar.h 5-1088 GFX_GOL_PROGRESSBAR structure 5-911 9 MPLAB Harmony Help w GFX_GOL_PROGRESSBAR_STATE enumeration 5-911 GFX_GOL_ProgressBarActionGet function 5-779 GFX_GOL_ProgressBarCreate function 5-780 GFX_GOL_ProgressBarDraw function 5-781 GFX_GOL_ProgressBarPositionGet macro 5-980 GFX_GOL_ProgressBarPositionSet function 5-782 GFX_GOL_ProgressBarRangeGet macro 5-980 GFX_GOL_ProgressBarRangeSet function 5-782 gfx_gol_radio_button.h 5-1089 GFX_GOL_RADIOBUTTON structure 5-912 GFX_GOL_RADIOBUTTON_STATE enumeration 5-912 GFX_GOL_RadioButtonActionGet function 5-787 GFX_GOL_RadioButtonActionSet function 5-788 GFX_GOL_RadioButtonCheckGet function 5-788 GFX_GOL_RadioButtonCheckSet function 5-790 GFX_GOL_RadioButtonCreate function 5-790 GFX_GOL_RadioButtonDraw function 5-792 GFX_GOL_RadioButtonTextAlignmentGet function 5-792 GFX_GOL_RadioButtonTextAlignmentSet function 5-793 GFX_GOL_RadioButtonTextGet macro 5-980 GFX_GOL_RadioButtonTextSet function 5-793 gfx_gol_round_dial.h 5-1090 GFX_GOL_RoundDailActionGet function 5-794 GFX_GOL_RoundDailActionSet function 5-795 GFX_GOL_ROUNDDIAL structure 5-913 GFX_GOL_ROUNDDIAL_DISABLED macro 5-981 GFX_GOL_ROUNDDIAL_DRAW macro 5-981 GFX_GOL_ROUNDDIAL_HIDE macro 5-981 GFX_GOL_ROUNDDIAL_MAX_POSITIONS macro 5-981 GFX_GOL_ROUNDDIAL_QUADRANT_POSITIONS macro 5-981 GFX_GOL_ROUNDDIAL_ROT_CCW macro 5-982 GFX_GOL_ROUNDDIAL_ROT_CW macro 5-982 GFX_GOL_RoundDialCreate function 5-796 GFX_GOL_RoundDialDraw function 5-797 GFX_GOL_RoundDialValueDecrement macro 5-982 GFX_GOL_RoundDialValueGet macro 5-982 GFX_GOL_RoundDialValueIncrement macro 5-983 GFX_GOL_RoundDialValueSet macro 5-983 gfx_gol_scan_codes.h 5-1091 gfx_gol_scheme.h 5-1092 GFX_GOL_SchemeAlphaPrecentSet function 5-878 GFX_GOL_SchemeBackgroundColorGet function 5-878 GFX_GOL_SchemeBackgroundColorSet function 5-878 GFX_GOL_SchemeBackgroundImageSet function 5-879 GFX_GOL_SchemeBackgroundTypeGet function 5-879 GFX_GOL_SchemeBackgroundTypeSet function 5-879 GFX_GOL_SchemeColor0Get function 5-879 GFX_GOL_SchemeColor0Set function 5-879 GFX_GOL_SchemeColor1Get function 5-880 GFX_GOL_SchemeColor1Set function 5-880 GFX_GOL_SchemeColorDisabledGet function 5-880 GFX_GOL_SchemeColorDisabledSet function 5-880 GFX_GOL_SchemeColorSet function 5-880 GFX_GOL_SchemeEmbossDarkColorGet function 5-881 GFX_GOL_SchemeEmbossDarkColorSet function 5-881 GFX_GOL_SchemeEmbossLightColorGet function 5-881 GFX_GOL_SchemeEmbossLightColorSet function 5-881 GFX_GOL_SchemeEmbossSet function 5-881 GFX_GOL_SchemeEmbossSizeGet function 5-882 GFX_GOL_SchemeEmbossSizeSet function 5-882 GFX_GOL_SchemeFillStyleGet function 5-882 GFX_GOL_SchemeFillStyleSet function 5-882 GFX_GOL_SchemeFontGet function 5-882 GFX_GOL_SchemeFontSet function 5-883 GFX_GOL_SchemeGradientColorSet function 5-883 GFX_GOL_SchemeGradientEndColorGet function 5-883 GFX_GOL_SchemeGradientEndColorSet function 5-883 GFX_GOL_SchemeGradientStartColorGet function 5-883 GFX_GOL_SchemeGradientStartColorSet function 5-884 GFX_GOL_SchemeTextColor0Get function 5-884 GFX_GOL_SchemeTextColor0Set function 5-884 GFX_GOL_SchemeTextColor1Get function 5-884 GFX_GOL_SchemeTextColor1Set function 5-884 GFX_GOL_SchemeTextColorDisableGet function 5-885 GFX_GOL_SchemeTextColorDisableSet function 5-885 GFX_GOL_SchemeTextColorSet function 5-885 gfx_gol_scroll_bar.h 5-1093 GFX_GOL_SCROLLBAR structure 5-914 9 MPLAB Harmony Help x GFX_GOL_SCROLLBAR_STATE enumeration 5-914 GFX_GOL_ScrollBarActionGet function 5-798 GFX_GOL_ScrollBarActionSet function 5-799 GFX_GOL_ScrollBarCreate function 5-800 GFX_GOL_ScrollBarDraw function 5-802 GFX_GOL_ScrollBarPageGet function 5-802 GFX_GOL_ScrollBarPageSet function 5-803 GFX_GOL_ScrollBarPositionDecrement function 5-804 GFX_GOL_ScrollBarPositionGet function 5-804 GFX_GOL_ScrollBarPositionIncrement function 5-805 GFX_GOL_ScrollBarPositionSet function 5-806 GFX_GOL_ScrollBarRangeGet function 5-807 GFX_GOL_ScrollBarRangeSet function 5-807 gfx_gol_static_text.h 5-1094 GFX_GOL_STATICTEXT structure 5-915 GFX_GOL_STATICTEXT_STATE enumeration 5-915 GFX_GOL_StaticTextActionGet function 5-808 GFX_GOL_StaticTextAlignmentGet function 5-809 GFX_GOL_StaticTextAlignmentSet function 5-809 GFX_GOL_StaticTextCreate function 5-810 GFX_GOL_StaticTextDraw function 5-811 GFX_GOL_StaticTextGet function 5-811 GFX_GOL_StaticTextSet function 5-812 gfx_gol_text_entry.h 5-1095 GFX_GOL_TEXTENTRY structure 5-916 GFX_GOL_TEXTENTRY_KEY_COMMAND_TYPE enumeration 5-916 GFX_GOL_TEXTENTRY_STATE enumeration 5-917 GFX_GOL_TextEntryActionGet function 5-812 GFX_GOL_TextEntryActionSet function 5-814 GFX_GOL_TextEntryBufferClear function 5-815 GFX_GOL_TextEntryBufferGet function 5-815 GFX_GOL_TextEntryBufferSet function 5-816 GFX_GOL_TextEntryCharAdd function 5-816 GFX_GOL_TextEntryCreate function 5-817 GFX_GOL_TextEntryDraw function 5-818 GFX_GOL_TextEntryKeyCommandGet function 5-819 GFX_GOL_TextEntryKeyCommandSet function 5-819 GFX_GOL_TextEntryKeyIsPressed function 5-820 GFX_GOL_TextEntryKeyListCreate function 5-820 GFX_GOL_TextEntryKeyMemberListDelete function 5-821 GFX_GOL_TextEntryKeyTextSet function 5-821 GFX_GOL_TextEntryLastCharDelete function 5-822 GFX_GOL_TextEntrySpaceCharAdd function 5-822 GFX_GOL_TRANSLATED_ACTION enumeration 5-917 GFX_GOL_TRANSLATED_ACTION, \ GFX_GOL_OBJ_HEADER *, \ GFX_GOL_MESSAGE * \ ) type 5-919 GFX_GOL_TwoTonePanelDraw function 5-718 GFX_GOL_WINDOW structure 5-920 gfx_gol_window.h 5-1096 GFX_GOL_WINDOW_STATE enumeration 5-920 GFX_GOL_WindowActionGet function 5-823 GFX_GOL_WindowCreate function 5-823 GFX_GOL_WindowDraw function 5-824 GFX_GOL_WindowImageGet macro 5-984 GFX_GOL_WindowTextAlignmentGet function 5-825 GFX_GOL_WindowTextAlignmentSet function 5-825 GFX_GOL_WindowTextGet macro 5-984 GFX_GOL_WindowTextSet function 5-826 GFX_GRADIENT_STYLE structure 5-921 GFX_GradientColorSet function 5-847 GFX_GradientEndColorGet function 5-847 GFX_GradientStartColorGet function 5-847 GFX_GradientTypeSet macro 5-1125 gfx_imageDecoder.h 5-1096 GFX_ImageDraw function 5-848 GFX_ImageHeaderGet function 5-848 GFX_ImageHeightGet function 5-849 GFX_ImageOffsetAddressGet function 5-849 GFX_ImagePartialDraw function 5-850 GFX_ImageStretchSet macro 5-985 GFX_ImageWidthGet function 5-851 GFX_Initialize function 5-852 GFX_Layer function 5-852 GFX_LAYER_PARAMS structure 5-295 GFX_LINE_STYLE enumeration 5-921 GFX_LineDraw function 5-853 GFX_LinePositionRelativeSet function 5-853 GFX_LinePositionSet function 5-854 9 MPLAB Harmony Help y GFX_LinePositionXGet function 5-854 GFX_LinePositionYGet function 5-855 GFX_LineStyleGet function 5-855 GFX_LineStyleSet function 5-855 GFX_LineToDraw function 5-856 GFX_LineToRelativeDraw function 5-856 GFX_malloc macro 5-326 GFX_MAX_INVALIDATE_AREAS macro 5-985 GFX_MaxXGet macro 5-985 GFX_MaxYGet macro 5-985 GFX_MCHP_BITMAP_HEADER structure 5-922 GFX_MEM_MASK macro 5-986 GFX_PageSet function 5-857 gfx_palette.h 5-1098 GFX_PALETTE_ENTRY union 5-922 GFX_PARTIAL_IMAGE_PARAM structure 5-923 GFX_PixelPut macro 5-986 GFX_PixelsPut macro 5-986 GFX_PolygonDraw function 5-857 GFX_PrevAlphaColorGet macro 5-986 GFX_PrevAlphaColorSet macro 5-986 GFX_PRIM_SetPIPWindow function 5-305 gfx_primitive.h 5-1100 GFX_Primitive_DATA structure 5-923 GFX_Primitive_Initialize function 5-858 GFX_Primitive_instance variable 5-888 gfx_primitive_local.h 5-1104 GFX_RectangleDraw function 5-858 GFX_RectangleFillDraw function 5-859 GFX_RectangleRoundDraw function 5-860 GFX_RectangleRoundFillDraw function 5-861 GFX_RECTANGULAR_AREA structure 5-924 GFX_RenderingBufferGet function 5-862 GFX_RenderToDisplayBufferDisable function 5-862 GFX_RenderToDisplayBufferDisableFlagGet function 5-862 GFX_RenderToDisplayBufferEnable function 5-862 GFX_RESOURCE enumeration 5-924 GFX_RESOURCE_BINARY structure 5-926 GFX_RESOURCE_FONT structure 5-927 GFX_RESOURCE_HDR structure 5-927 GFX_RESOURCE_IMAGE structure 5-928 GFX_RESOURCE_PALETTE structure 5-929 GFX_RGBConvert macro 5-987 GFX_ScreenClear function 5-863 GFX_SetFontOrientation macro 5-987 GFX_SetTransitionParameters function 5-863 GFX_SineCosineGet function 5-1124 GFX_SineGet macro 5-1125 GFX_SolidLineDraw function 5-864 GFX_STATUS enumeration 5-929 GFX_STATUS_BIT enumeration 5-929 GFX_StyledLineDraw function 5-864 GFX_TextAreaBottomGet function 5-864 GFX_TextAreaBottomSet function 5-864 GFX_TextAreaLeftGet function 5-865 GFX_TextAreaLeftSet function 5-865 GFX_TextAreaRightGet function 5-865 GFX_TextAreaRightSet function 5-865 GFX_TextAreaTopGet function 5-865 GFX_TextAreaTopSet function 5-865 GFX_TextCharDraw function 5-866 GFX_TextCursorPositionSet function 5-866 GFX_TextCursorPositionXGet function 5-867 GFX_TextCursorPositionYGet function 5-867 GFX_TextStringBoxDraw function 5-868 GFX_TextStringDraw function 5-869 GFX_TextStringHeightGet function 5-869 GFX_TextStringWidthGet function 5-870 GFX_ThickBevelDraw function 5-871 GFX_Transition function 5-871 GFX_TRANSITION_DIRECTION enumeration 5-930 GFX_TRANSITION_PARAMS structure 5-930 GFX_TRANSITION_TYPE enumeration 5-930 gfx_transitions.h 5-1105 GFX_TransparentColorDisable function 5-871 GFX_TransparentColorEnable function 5-872 GFX_TransparentColorGet function 5-873 GFX_TransparentColorStatusGet function 5-873 9 MPLAB Harmony Help z GFX_TRIG_FUNCTION_TYPE enumeration 5-931 GFX_TYPE_MASK macro 5-988 gfx_types_font.h 5-1107 GFX_TYPES_FONTS_H macro 5-988 gfx_types_image.h 5-1107 GFX_TYPES_IMAGE_H macro 5-988 gfx_types_macros.h 5-1108 gfx_types_palette.h 5-1109 GFX_TYPES_PALETTE_H macro 5-988 gfx_types_resource.h 5-1109 GFX_TYPES_RESOURCE_H macro 5-988 GFX_UXCHAR macro 5-988 GFX_VisualPageGet macro 5-989 GFX_W3_ALICEBLUE macro 5-989 GFX_W3_ANTIQUEWHITE macro 5-989 GFX_W3_AQUA macro 5-989 GFX_W3_AQUAMARINE macro 5-989 GFX_W3_AZURE macro 5-989 GFX_W3_BEIGE macro 5-990 GFX_W3_BISQUE macro 5-990 GFX_W3_BLACK macro 5-990 GFX_W3_BLANCHEDALMOND macro 5-990 GFX_W3_BLUE macro 5-990 GFX_W3_BLUEVIOLET macro 5-990 GFX_W3_BROWN macro 5-990 GFX_W3_BURLYWOOD macro 5-991 GFX_W3_CADETBLUE macro 5-991 GFX_W3_CHARTREUSE macro 5-991 GFX_W3_CHOCOLATE macro 5-991 GFX_W3_CORAL macro 5-991 GFX_W3_CORNFLOWERBLUE macro 5-991 GFX_W3_CORNSILK macro 5-992 GFX_W3_CRIMSON macro 5-992 GFX_W3_CYAN macro 5-992 GFX_W3_DARKBLUE macro 5-992 GFX_W3_DARKCYAN macro 5-992 GFX_W3_darkgoldenrod macro 5-992 GFX_W3_DARKGRAY macro 5-992 GFX_W3_DARKGREEN macro 5-993 GFX_W3_DARKGREY macro 5-993 GFX_W3_DARKHAKI macro 5-993 GFX_W3_DARKMAGENTA macro 5-993 GFX_W3_DARKOLIVEGREEN macro 5-993 GFX_W3_DARKORANGE macro 5-993 GFX_W3_DARKORCHID macro 5-994 GFX_W3_DARKRED macro 5-994 GFX_W3_DARKSALMON macro 5-994 GFX_W3_DARKSEAGREEN macro 5-994 GFX_W3_DARKSLATEBLUE macro 5-994 GFX_W3_DARKSLATEGRAY macro 5-994 GFX_W3_DARKSLATEGREY macro 5-994 GFX_W3_DARKTURQUOISE macro 5-995 GFX_W3_DARKVIOLET macro 5-995 GFX_W3_DEEPPINK macro 5-995 GFX_W3_DEEPSKYBLUE macro 5-995 GFX_W3_DIMGRAY macro 5-995 GFX_W3_DIMGREY macro 5-995 GFX_W3_DODGERBLUE macro 5-996 GFX_W3_FIREBRICK macro 5-996 GFX_W3_FLORALWHITE macro 5-996 GFX_W3_FORESTGREEN macro 5-996 GFX_W3_FUCHSIA macro 5-996 GFX_W3_GAINSBORO macro 5-996 GFX_W3_GHOSTWHITE macro 5-996 GFX_W3_GOLD macro 5-997 GFX_W3_GOLDENROD macro 5-997 GFX_W3_GRAY macro 5-997 GFX_W3_GREEN macro 5-997 GFX_W3_GREENYELLOW macro 5-997 GFX_W3_GREY macro 5-997 GFX_W3_HONEYDEW macro 5-998 GFX_W3_HOTPINK macro 5-998 GFX_W3_INDIANRED macro 5-998 GFX_W3_INDIGO macro 5-998 GFX_W3_IVORY macro 5-998 GFX_W3_LAVENDER macro 5-998 GFX_W3_LAVENDERBLUSH macro 5-998 GFX_W3_LAWNGREEN macro 5-999 9 MPLAB Harmony Help aa GFX_W3_LEMONCHIFFON macro 5-999 GFX_W3_LIGHTBLUE macro 5-999 GFX_W3_LIGHTCORAL macro 5-999 GFX_W3_LIGHTCYAN macro 5-999 GFX_W3_LIGHTGOLDENRODYELLOW macro 5-999 GFX_W3_LIGHTGRAY macro 5-1000 GFX_W3_LIGHTGREEN macro 5-1000 GFX_W3_LIGHTGREY macro 5-1000 GFX_W3_LIGHTPINK macro 5-1000 GFX_W3_LIGHTSALMON macro 5-1000 GFX_W3_LIGHTSKYBLUE macro 5-1000 GFX_W3_LIGHTSLATEGRAY macro 5-1000 GFX_W3_LIGHTSLATEGREY macro 5-1001 GFX_W3_LIGHTSTEELBLUE macro 5-1001 GFX_W3_LIGHTYELLOW macro 5-1001 GFX_W3_LIGTHSEAGREEN macro 5-1001 GFX_W3_LIME macro 5-1001 GFX_W3_LIMEGREEN macro 5-1001 GFX_W3_LINEN macro 5-1002 GFX_W3_MAGENTA macro 5-1002 GFX_W3_MAROON macro 5-1002 GFX_W3_MEDIUMAQUAMARINE macro 5-1002 GFX_W3_MEDIUMBLUE macro 5-1002 GFX_W3_MEDIUMORCHID macro 5-1002 GFX_W3_MEDIUMPURPLE macro 5-1002 GFX_W3_MEDIUMSEAGREEN macro 5-1003 GFX_W3_MEDIUMSLATEBLUE macro 5-1003 GFX_W3_MEDIUMSPRINGGREEN macro 5-1003 GFX_W3_MEDIUMTURQUOISE macro 5-1003 GFX_W3_MEDIUMVIOLETRED macro 5-1003 GFX_W3_MIDNIGHTBLUE macro 5-1003 GFX_W3_MINTCREAM macro 5-1004 GFX_W3_MISTYROSE macro 5-1004 GFX_W3_MOCCASIN macro 5-1004 GFX_W3_NAVAJOWHITE macro 5-1004 GFX_W3_NAVY macro 5-1004 GFX_W3_OLDLACE macro 5-1004 GFX_W3_OLIVE macro 5-1004 GFX_W3_OLIVEDRAB macro 5-1005 GFX_W3_ORANGE macro 5-1005 GFX_W3_ORANGERED macro 5-1005 GFX_W3_ORCHID macro 5-1005 GFX_W3_PALEGOLDENROD macro 5-1005 GFX_W3_PALEGREEN macro 5-1005 GFX_W3_PALETURQUOISE macro 5-1006 GFX_W3_PALEVIOLETRED macro 5-1006 GFX_W3_PAPAYAWHIP macro 5-1006 GFX_W3_PEACHPUFF macro 5-1006 GFX_W3_PERU macro 5-1006 GFX_W3_PINK macro 5-1006 GFX_W3_PLUM macro 5-1006 GFX_W3_POWDERBLUE macro 5-1007 GFX_W3_PURPLE macro 5-1007 GFX_W3_RED macro 5-1007 GFX_W3_ROSYBROWN macro 5-1007 GFX_W3_ROYALBLUE macro 5-1007 GFX_W3_SADDLEBROWN macro 5-1007 GFX_W3_SALMON macro 5-1008 GFX_W3_SANDYGREEN macro 5-1008 GFX_W3_SEAGREEN macro 5-1008 GFX_W3_SEASHELL macro 5-1008 GFX_W3_SIENNA macro 5-1008 GFX_W3_SILVER macro 5-1008 GFX_W3_SKYBLUE macro 5-1008 GFX_W3_SLATEBLUE macro 5-1009 GFX_W3_SLATEGRAY macro 5-1009 GFX_W3_SLATEGREY macro 5-1009 GFX_W3_SNOW macro 5-1009 GFX_W3_SPRINGGREEN macro 5-1009 GFX_W3_STEELBLUE macro 5-1009 GFX_W3_TAN macro 5-1010 GFX_W3_TEAL macro 5-1010 GFX_W3_THISTLE macro 5-1010 GFX_W3_TOMATO macro 5-1010 GFX_W3_TURQUOISE macro 5-1010 GFX_W3_VIOLET macro 5-1010 GFX_W3_WHEAT macro 5-1010 GFX_W3_WHITE macro 5-1011 9 MPLAB Harmony Help bb GFX_W3_WHITESMOKE macro 5-1011 GFX_W3_YELLOW macro 5-1011 GFX_W3_YELLOWGREEN macro 5-1011 GFX_X11_ALICE_BLUE macro 5-1011 GFX_X11_ANTIQUE_WHITE macro 5-1011 GFX_X11_AQUA macro 5-1012 GFX_X11_AQUAMARINE macro 5-1012 GFX_X11_AZURE macro 5-1012 GFX_X11_BEIGE macro 5-1012 GFX_X11_BISQUE macro 5-1012 GFX_X11_BLACK macro 5-1012 GFX_X11_BLANCHED_ALMOND macro 5-1012 GFX_X11_BLUE macro 5-1013 GFX_X11_BLUE_VIOLET macro 5-1013 GFX_X11_BROWN macro 5-1013 GFX_X11_BURLY_WOOD macro 5-1013 GFX_X11_CADEL_BLUE macro 5-1013 GFX_X11_CHARTEUSE macro 5-1013 GFX_X11_CHOCOLATE macro 5-1014 GFX_X11_CORAL macro 5-1014 GFX_X11_CORNFLOWER_BLUE macro 5-1014 GFX_X11_CORNSILK macro 5-1014 GFX_X11_CRIMSON macro 5-1014 GFX_X11_CYAN macro 5-1014 GFX_X11_DARK_BLUE macro 5-1014 GFX_X11_DARK_CYAN macro 5-1015 GFX_X11_DARK_GOLDENROD macro 5-1015 GFX_X11_DARK_GREEN macro 5-1015 GFX_X11_DARK_GREY macro 5-1015 GFX_X11_DARK_KHAKI macro 5-1015 GFX_X11_DARK_MAGENTA macro 5-1015 GFX_X11_DARK_OLIVE_GREEN macro 5-1016 GFX_X11_DARK_ORANGE macro 5-1016 GFX_X11_DARK_ORCHID macro 5-1016 GFX_X11_DARK_RED macro 5-1016 GFX_X11_DARK_SALMON macro 5-1016 GFX_X11_DARK_SEA_GREEN macro 5-1016 GFX_X11_DARK_SLATE_BLUE macro 5-1016 GFX_X11_DARK_SLATE_GREY macro 5-1017 GFX_X11_DARK_TURQUOISE macro 5-1017 GFX_X11_DARK_VIOLET macro 5-1017 GFX_X11_DEEP_PINK macro 5-1017 GFX_X11_DEEP_SKY_BLUE macro 5-1017 GFX_X11_DIM_GREY macro 5-1017 GFX_X11_DODGER_BLUE macro 5-1018 GFX_X11_FIRE_BRICK macro 5-1018 GFX_X11_FLORAL_WHITE macro 5-1018 GFX_X11_FOREST_GREEN macro 5-1018 GFX_X11_FUCHSIA macro 5-1018 GFX_X11_GAINSBORO macro 5-1018 GFX_X11_GHOST_WHITE macro 5-1018 GFX_X11_GOLD macro 5-1019 GFX_X11_GOLDENROD macro 5-1019 GFX_X11_GREEN macro 5-1019 GFX_X11_GREEN_YELLOW macro 5-1019 GFX_X11_GREY macro 5-1019 GFX_X11_HONEYDEW macro 5-1019 GFX_X11_HOT_PINK macro 5-1020 GFX_X11_INDIAN_RED macro 5-1020 GFX_X11_INDIGO macro 5-1020 GFX_X11_IVORY macro 5-1020 GFX_X11_KHAKI macro 5-1020 GFX_X11_LAVENDER macro 5-1020 GFX_X11_LAVENDOR_BLUSH macro 5-1020 GFX_X11_LAWN_GREEN macro 5-1021 GFX_X11_LEMON_CHIFFON macro 5-1021 GFX_X11_LIGHT_BLUE macro 5-1021 GFX_X11_LIGHT_CAROL macro 5-1021 GFX_X11_LIGHT_CYAN macro 5-1021 GFX_X11_LIGHT_GOLDENROD_YELLOW macro 5-1021 GFX_X11_LIGHT_GRAY macro 5-1022 GFX_X11_LIGHT_GREEN macro 5-1022 GFX_X11_LIGHT_PINK macro 5-1022 GFX_X11_LIGHT_SALMON macro 5-1022 GFX_X11_LIGHT_SEA_GREEN macro 5-1022 GFX_X11_LIGHT_SKY_BLUE macro 5-1022 GFX_X11_LIGHT_SLATE_GREY macro 5-1022 GFX_X11_LIGHT_STEEL_BLUE macro 5-1023 9 MPLAB Harmony Help cc GFX_X11_LIGHT_YELLOW macro 5-1023 GFX_X11_LIME macro 5-1023 GFX_X11_LIME_GREEN macro 5-1023 GFX_X11_LINEN macro 5-1023 GFX_X11_MAGENTA macro 5-1023 GFX_X11_MARRON macro 5-1024 GFX_X11_MEDIUM_AQUAMARINE macro 5-1024 GFX_X11_MEDIUM_BLUE macro 5-1024 GFX_X11_MEDIUM_ORCHID macro 5-1024 GFX_X11_MEDIUM_PURPLE macro 5-1024 GFX_X11_MEDIUM_SEA_GREEN macro 5-1024 GFX_X11_MEDIUM_SLATE_BLUE macro 5-1024 GFX_X11_MEDIUM_SPRING_GREEN macro 5-1025 GFX_X11_MEDIUM_TURQUOISE macro 5-1025 GFX_X11_MEDIUM_VIOLET_RED macro 5-1025 GFX_X11_MIDNIGHT_BLUE macro 5-1025 GFX_X11_MINT_CREAM macro 5-1025 GFX_X11_MISTY_ROSE macro 5-1025 GFX_X11_MOCCASIN macro 5-1026 GFX_X11_NAVAJO_WHITE macro 5-1026 GFX_X11_NAVY macro 5-1026 GFX_X11_OLD_LACE macro 5-1026 GFX_X11_OLIVE macro 5-1026 GFX_X11_OLIVE_DRAB macro 5-1026 GFX_X11_ORANGE macro 5-1026 GFX_X11_ORANGE_RED macro 5-1027 GFX_X11_ORCHID macro 5-1027 GFX_X11_PALE_GOLDENROD macro 5-1027 GFX_X11_PALE_GREEN macro 5-1027 GFX_X11_PALE_TURQUOISE macro 5-1027 GFX_X11_PALE_VIOLET_RED macro 5-1027 GFX_X11_PAPAYA_WHIP macro 5-1028 GFX_X11_PEACH_PUFF macro 5-1028 GFX_X11_PERU macro 5-1028 GFX_X11_PINK macro 5-1028 GFX_X11_PLUM macro 5-1028 GFX_X11_POWDER_BLUE macro 5-1028 GFX_X11_PURPLE macro 5-1028 GFX_X11_RED macro 5-1029 GFX_X11_ROSY_BROWN macro 5-1029 GFX_X11_ROYAL_BLUE macro 5-1029 GFX_X11_SADDLE_BROWN macro 5-1029 GFX_X11_SALMON macro 5-1029 GFX_X11_SANDY_BROWN macro 5-1029 GFX_X11_SEA_GREEN macro 5-1030 GFX_X11_SEASHELL macro 5-1030 GFX_X11_SIENNA macro 5-1030 GFX_X11_SILVER macro 5-1030 GFX_X11_SKY_BLUE macro 5-1030 GFX_X11_SLATE_BLUE macro 5-1030 GFX_X11_SLATE_GREY macro 5-1030 GFX_X11_SNOW macro 5-1031 GFX_X11_SPRING_GREEN macro 5-1031 GFX_X11_STEEL_BLUE macro 5-1031 GFX_X11_TAN macro 5-1031 GFX_X11_TEAL macro 5-1031 GFX_X11_THISTLE macro 5-1031 GFX_X11_TOMATO macro 5-1032 GFX_X11_TURQUOISE macro 5-1032 GFX_X11_VIOLET macro 5-1032 GFX_X11_WHEAT macro 5-1032 GFX_X11_WHITE macro 5-1032 GFX_X11_WHITE_SMOKE macro 5-1032 GFX_X11_YELLOW macro 5-1032 GFX_X11_YELLOW_GREEN macro 5-1033 GFX_XCHAR macro 5-1033 GFXCirclePointGet function 5-1125 GOL_PANEL_PARAM structure 5-932 GOLD macro 5-1033 Gradients 5-1114 Graphic Display Driver Layer Changes 5-683 Graphic Object Layer (GOL) Changes 5-683 Graphic Primitive Layer Changes 5-682 Graphics (GFX) Driver Library 5-289 Graphics Demonstrations 3-84 Graphics Library Help 5-680 Graphics Library Porting Guide 5-680 Graphics Object Library 5-694 9 MPLAB Harmony Help dd Graphics Primitive Library 5-1110 GRAPHICS_LIBRARY_VERSION macro 5-1033 GRAY000 macro 5-1034 GRAY001 macro 5-1034 GRAY002 macro 5-1034 GRAY003 macro 5-1034 GRAY004 macro 5-1034 GRAY005 macro 5-1034 GRAY006 macro 5-1034 GRAY007 macro 5-1035 GRAY008 macro 5-1035 GRAY009 macro 5-1035 GRAY010 macro 5-1035 GRAY011 macro 5-1035 GRAY012 macro 5-1035 GRAY013 macro 5-1036 GRAY014 macro 5-1036 GRAY015 macro 5-1036 GRAY032 macro 5-1036 GRAY096 macro 5-1036 GRAY128 macro 5-1036 GRAY160 macro 5-1036 GRAY192 macro 5-1037 GRAY204 macro 5-1037 GRAY224 macro 5-1037 GRAY229 macro 5-1037 GRAY242 macro 5-1037 GREEN macro 5-1037 GRID structure 5-932 GRID_DISABLED macro 5-1038 GRID_DRAW_ALL macro 5-1038 GRID_DRAW_ITEMS macro 5-1038 GRID_FOCUSED macro 5-1038 GRID_HEIGHT macro 5-1038 GRID_HIDE macro 5-1038 GRID_MAX_COLUMNS macro 5-1039 GRID_MAX_ROWS macro 5-1039 GRID_OUT_OF_BOUNDS macro 5-1039 GRID_SHOW_BORDER_ONLY macro 5-1039 GRID_SHOW_FOCUS macro 5-1039 GRID_SHOW_LINES macro 5-1039 GRID_SHOW_SEPARATORS_ONLY macro 5-1039 GRID_SUCCESS macro 5-1040 GRID_TYPE_MASK macro 5-1040 GRID_WIDTH macro 5-1040 GridClearCellState function 5-752 GridCreate function 5-753 GridDraw function 5-754 GridFreeItems function 5-754 GridGetCell function 5-755 GridGetFocusX macro 5-1040 GridGetFocusY macro 5-1041 GRIDITEM structure 5-933 GRIDITEM_DRAW macro 5-1041 GRIDITEM_IS_BITMAP macro 5-1041 GRIDITEM_IS_TEXT macro 5-1041 GRIDITEM_SELECTED macro 5-1041 GRIDITEM_TEXTBOTTOM macro 5-1042 GRIDITEM_TEXTLEFT macro 5-1042 GRIDITEM_TEXTRIGHT macro 5-1042 GRIDITEM_TEXTTOP macro 5-1042 GridMsgDefault function 5-755 GridSetCell function 5-756 GridSetCellState function 5-757 GridSetFocus function 5-757 GridTranslateMsg function 5-758 H Handling Endpoint 0 (EP0) Packets 5-3976 Handling Errors 5-2085, 5-2487 Handling Events 5-1562 Hardware 3-103, 3-124, 3-143 Hardware Abstraction Model 5-1362, 5-1473, 5-1521, 5-1564, 5-1669, 5-1735, 5-1905, 5-2087, 5-2172, 5-2203, 5-2253, 5-2289, 5-2332, 5-2429, 5-2479, 5-2595, 5-2663, 5-2689, 5-2705, 5-2763, 5-2801, 5-2893, 5-3012, 5-3087, 5-3322 Hardware Abstraction Models 5-3171 Hardware Drivers 5-309 Hardware Information 3-103, 3-124, 3-143 9 MPLAB Harmony Help ee help_sys_ports.h 5-3498 hid_basic 3-158 hid_joystick 3-161 hid_keyboard 3-161 hid_mouse 3-160 HIDE_DATA macro 5-1042 Host 3-167 How the Library Works 5-195, 5-345, 5-369, 5-399, 5-421, 5-459, 5-514, 5-554, 5-607, 5-697, 5-1112, 5-1315, 5-1367, 5-1474, 5-1522, 5-1555, 5-1670, 5-1736, 5-1866, 5-1906, 5-2061, 5-2173, 5-2205, 5-2255, 5-2290, 5-2333, 5-2431, 5-2480, 5-2598, 5-2666, 5-2690, 5-2707, 5-2764, 5-2802, 5-2896, 5-3015, 5-3088, 5-3321, 5-3350, 5-3365, 5-3422, 5-3443, 5-3470, 5-3506, 5-3531, 5-3576, 5-3616, 5-3627, 5-3869, 5-3883, 5-3932, 5-4007, 5-4170 HTTP Changes 5-3551 HTTP Server TCP/IP Stack Library 5-3659 http.h 5-3688 HTTP_CACHE_LEN macro 5-3662 http_config.h 5-3689 HTTP_CONFIG_FLAGS macro 5-3662 HTTP_CONN_HANDLE type 5-3684 HTTP_DEFAULT_FILE macro 5-3662 HTTP_DEFAULT_LEN macro 5-3663 HTTP_FILE_TYPE enumeration 5-3684 HTTP_FILE_UPLOAD macro 5-3663 HTTP_IO_RESULT enumeration 5-3684 HTTP_MAX_CONNECTIONS macro 5-3663 HTTP_MAX_DATA_LEN macro 5-3663 HTTP_MAX_HEADER_LEN macro 5-3663 HTTP_MIN_CALLBACK_FREE macro 5-3663 HTTP_MODULE_CONFIG structure 5-3685 HTTP_MODULE_FLAGS enumeration 5-3685 HTTP_PORT macro 5-3664 HTTP_READ_STATUS enumeration 5-3685 HTTP_SKT_RX_BUFF_SIZE macro 5-3664 HTTP_SKT_TX_BUFF_SIZE macro 5-3664 HTTP_SSL_ONLY_CHAR macro 5-3664 HTTP_STATUS enumeration 5-3686 HTTP_TIMEOUT macro 5-3664 HTTP_USE_AUTHENTICATION macro 5-3664 HTTP_USE_COOKIES macro 5-3665 HTTP_USE_POST macro 5-3665 HTTPCheckAuth function 5-3679 HTTPExecuteGet function 5-3680 HTTPExecutePost function 5-3681 HTTPNeedsAuth function 5-3682 HTTPPrint_varname function 5-3683 HTTPReadPostPair macro 5-3687 HTTPS_DEFAULT_FILE macro 5-3665 HTTPS_PORT macro 5-3665 I I2C Peripheral Library 5-2059 I2C_MODULE_ID enumeration 5-2165 IC_BUFFER_SIZE enumeration 5-2188 IC_CLOCK_SOURCES enumeration 5-2188 IC_EDGE_TYPES enumeration 5-2189 IC_EVENTS_PER_INTERRUPT enumeration 5-2189 IC_INPUT_CAPTURE_MODES enumeration 5-2189 IC_MODULE_ID enumeration 5-2190 IC_SYNC_MODE_INPUTS enumeration 5-2191 IC_SYNC_MODES enumeration 5-2192 IC_TIMERS enumeration 5-2192 ICMP TCP/IP Stack Library 5-3690 icmp.h 5-3696 icmp_config.h 5-3697 ICMP_ECHO_RESULT enumeration 5-3695 ICMP_HANDLE type 5-3695 ICMP_MODULE_CONFIG structure 5-3696 ICMP_TIMEOUT macro 5-3692 ICMPv6 TCP/IP Stack Library 5-3697 icmpv6.h 5-3707 icmpv6_config.h 5-3708 ICMPV6_ERR_DU_CODE enumeration 5-3704 ICMPV6_ERR_PP_CODE enumeration 5-3705 ICMPV6_ERR_PTB_CODE macro 5-3703 ICMPV6_ERR_TE_CODE enumeration 5-3705 ICMPV6_HANDLE type 5-3705 ICMPV6_HEADER_ECHO structure 5-3706 ICMPV6_HEADER_ERROR structure 5-3706 9 MPLAB Harmony Help ff ICMPV6_INFO_EREQ_CODE macro 5-3704 ICMPV6_INFO_ERPL_CODE macro 5-3704 ICMPV6_PACKET_TYPES enumeration 5-3706 ICMPV6_TIMEOUT macro 5-3700 IMAGE_STRETCH enumeration 5-933 ImageAbort macro 5-1042 ImageDecoderInit function 5-874 ImageDecodeTask function 5-874 ImageFullScreenDecode macro 5-1043 ImageLoopCallbackRegister function 5-875 Images 5-1117, 5-1124 IMG_ALIGN_CENTER macro 5-1044 IMG_bAlignCenter variable 5-885 IMG_bDownScalingFactor variable 5-885 IMG_blAbortImageDecoding variable 5-886 IMG_DECODE_ABORTED macro 5-1044 IMG_DOWN_SCALE macro 5-1044 IMG_FCLOSE macro 5-1044 IMG_FEOF macro 5-1044 IMG_FILE macro 5-1044 IMG_FILE_FORMAT type 5-933 IMG_FILE_SYSTEM_API type 5-933 IMG_FOPEN macro 5-1045 IMG_FREAD macro 5-1045 IMG_FSEEK macro 5-1045 IMG_FTELL macro 5-1045 IMG_LOOP_CALLBACK type 5-933 IMG_pCurrentFile variable 5-886 IMG_pFileAPIs variable 5-886 IMG_PIXEL_OUTPUT type 5-934 IMG_PIXEL_XY_RGB_888 type 5-934 IMG_PixelXYColor variable 5-886 IMG_pLoopCallbackFn variable 5-886 IMG_pPixelOutput variable 5-886 IMG_SCREEN_HEIGHT macro 5-1045 IMG_SCREEN_WIDTH macro 5-1045 IMG_vCheckAndAbort macro 5-1045 IMG_vLoopCallback macro 5-1046 IMG_vPutPixel macro 5-1046 IMG_vSetboundaries function 5-875 IMG_vSetColor macro 5-1046 IMG_wHeight variable 5-886 IMG_wImageHeight variable 5-887 IMG_wImageWidth variable 5-887 IMG_wStartX variable 5-887 IMG_wStartY variable 5-887 IMG_wWidth variable 5-887 in_addr structure 5-3611 INADDR_ANY macro 5-3609 Initator Initialization 5-2764 Initialization 5-1367, 5-1670, 5-1915, 5-2481, 5-3350, 5-3387 Initialization Functions 7-4238 Initialization of CAN 5-1557 Initialization Overrides 5-474, 5-574, 5-608, 5-1323 Initializing and Communicating with the Endpoint 5-3975 Initializing the Data Structure 5-4014 Initializing the I2C 5-2061 Initializing the Library 5-3980, 5-4007 Initializing the USB Device Stack 5-3973 Input Capture Module Setup 5-2173 Input Capture Peripheral Library 5-2170 INPUT_DEVICE_EVENT enumeration 5-934 INPUT_DEVICE_TYPE enumeration 5-935 Installing the Configurator Plug-in 2-42 INT_EXTERNAL_SOURCES enumeration 5-2232 INT_PRIORITY_LEVEL enumeration 5-2233 INT_SOURCE enumeration 5-2233 INT_SUBPRIORITY_LEVEL enumeration 5-2237 INT_TRAP_SOURCE enumeration 5-2238 INT_VECTOR enumeration 5-2238 int16_gfx_image_prog type 5-935 int16_prog type 5-935 int16_prog_pack type 5-935 int16c structure 5-1264 int32_gfx_image_prog type 5-936 int32_prog type 5-936 int32_prog_pack type 5-936 int32c structure 5-1265 9 MPLAB Harmony Help gg int8_gfx_image_prog type 5-936 int8_prog type 5-936 int8_prog_pack type 5-936 Internal FRC Oscillator Tuning 5-2335 Interrupt Control and Management 5-1738 Interrupt Operation 5-1320 Interrupt Peripheral Library 5-2202 Interrupt State Machine 5-2076 Interrupt System Service Library 5-3419 Interrupt System Setup 5-3422 Interrupts 5-2823 Introduction 2-40, 3-64, 3-84, 3-98, 3-102, 3-113, 3-123, 3-130, 3-142, 3-149, 4-178, 5-193, 5-226, 5-254, 5-289, 5-299, 5-309, 5-319, 5-333, 5-342, 5-367, 5-397, 5-418, 5-457, 5-510, 5-552, 5-600, 5-680, 5-694, 5-1110, 5-1127, 5-1167, 5-1275, 5-1311, 5-1361, 5-1471, 5-1519, 5-1553, 5-1667, 5-1733, 5-1864, 5-1902, 5-2059, 5-2170, 5-2202, 5-2252, 5-2287, 5-2330, 5-2427, 5-2478, 5-2593, 5-2662, 5-2687, 5-2703, 5-2762, 5-2798, 5-2891, 5-3011, 5-3085, 5-3167, 5-3319, 5-3347, 5-3363, 5-3376, 5-3419, 5-3438, 5-3465, 5-3500, 5-3529, 5-3536, 5-3546, 5-3569, 5-3574, 5-3598, 5-3614, 5-3625, 5-3636, 5-3646, 5-3654, 5-3659, 5-3690, 5-3697, 5-3709, 5-3718, 5-3747, 5-3771, 5-3794, 5-3798, 5-3806, 5-3809, 5-3822, 5-3858, 5-3867, 5-3881, 5-3913, 5-3917, 5-3930, 5-3955, 5-3963, 5-3973, 5-3977, 5-4004, 5-4060, 5-4100, 5-4131, 5-4168, 5-4179, 5-4199, 6-4226, 7-4228, 7-4230, 7-4232, 7-4234, 7-4236 INVALID_SOCKET macro 5-3910 INVALID_TCP_PORT macro 5-3609 INVALID_UDP_SOCKET macro 5-3950 IP_ADDR_ANY macro 5-3609 ip_config.h 5-3716, 5-3747 IP_DEFAULT_ALLOCATION_BLOCK_SIZE macro 5-3711 IP_VERSION_4 macro 5-3735 IP_VERSION_6 macro 5-3735 IPPROTO_IP macro 5-3609 IPPROTO_TCP macro 5-3609 IPPROTO_UDP macro 5-3609 IPv4 TCP/IP Stack Library 5-3708 ipv4.h 5-3717 IPV4_HEADER structure 5-3715 IPV4_HEADER_TYPE enumeration 5-3715 IPV4_MODULE_CONFIG structure 5-3715 IPV4_PACKET structure 5-3716 IPV4_QUEUED_PACKET_LIMIT macro 5-3711 IPV4_QUEUED_PACKET_TIMEOUT macro 5-3711 IPV4_TASK_PROCESS_RATE macro 5-3711 IPv6 TCP/IP Stack Library 5-3718 ipv6.h 5-3745 IPV6_ACTION enumeration 5-3739 IPV6_ADDRESS_POLICY structure 5-3739 IPV6_ADDRESS_PREFERENCE enumeration 5-3739 IPV6_ADDRESS_TYPE union 5-3739 IPV6_DATA_DYNAMIC_BUFFER macro 5-3735 IPV6_DATA_NETWORK_FIFO macro 5-3736 IPV6_DATA_NONE macro 5-3736 IPV6_DATA_PIC_RAM macro 5-3736 IPV6_DATA_SEGMENT_HEADER type 5-3740 IPV6_DEFAULT_BASE_REACHABLE_TIME macro 5-3722 IPV6_DEFAULT_CUR_HOP_LIMIT macro 5-3722 IPV6_DEFAULT_LINK_MTU macro 5-3722 IPV6_DEFAULT_RETRANSMIT_TIME macro 5-3722 IPV6_EVENT_HANDLER type 5-3740 IPV6_EVENT_TYPE enumeration 5-3740 IPV6_FRAGMENT_HEADER structure 5-3741 IPV6_HANDLE type 5-3741 IPV6_HEADER structure 5-3741 IPV6_HEADER_OFFSET_DEST_ADDR macro 5-3736 IPV6_HEADER_OFFSET_NEXT_HEADER macro 5-3736 IPV6_HEADER_OFFSET_PAYLOAD_LENGTH macro 5-3736 IPV6_HEADER_OFFSET_SOURCE_ADDR macro 5-3737 IPV6_INIT_TASK_PROCESS_RATE macro 5-3720 IPV6_MINIMUM_LINK_MTU macro 5-3721 IPV6_MODULE_CONFIG structure 5-3742 IPV6_MTU_INCREASE_TIMEOUT macro 5-3802 IPV6_NEIGHBOR_CACHE_ENTRY_STALE_TIMEOUT macro 5-3721 IPV6_NEXT_HEADER_TYPE enumeration 5-3742 IPV6_NO_UPPER_LAYER_CHECKSUM macro 5-3737 IPV6_PACKET type 5-3743 IPV6_PACKET_ACK_FNC type 5-3743 IPV6_QUEUE_MCAST_PACKET_LIMIT macro 5-3721 IPV6_QUEUE_NEIGHBOR_PACKET_LIMIT macro 5-3721 IPV6_QUEUED_MCAST_PACKET_TIMEOUT macro 5-3721 IPV6_RX_FRAGMENT_BUFFER type 5-3743 9 MPLAB Harmony Help hh IPV6_SEGMENT_TYPE enumeration 5-3743 IPV6_SNMP_TRAP_INFO structure 5-3848 IPV6_TASK_PROCESS_RATE macro 5-3721 IPV6_TLV_HBHO_PAYLOAD_JUMBOGRAM macro 5-3737 IPV6_TLV_HBHO_ROUTER_ALERT macro 5-3737 IPV6_TLV_OPTION_TYPE union 5-3744 IPV6_TLV_PAD_1 macro 5-3737 IPV6_TLV_PAD_N macro 5-3737 IPV6_TLV_UNREC_OPT_DISCARD_PP macro 5-3737 IPV6_TLV_UNREC_OPT_DISCARD_PP_NOT_MC macro 5-3738 IPV6_TLV_UNREC_OPT_DISCARD_SILENT macro 5-3738 IPV6_TLV_UNREC_OPT_SKIP_OPTION macro 5-3738 IPV6_ULA_FLAGS enumeration 5-3744 IPV6_ULA_NTP_ACCESS_TMO macro 5-3722 IPV6_ULA_NTP_VALID_WINDOW macro 5-3722 IPV6_ULA_RESULT enumeration 5-3745 Isochronous Transfers 5-571 IsPaletteEnabled function 5-875 ISR Implementation 7-4229 K KEYMEMBER structure 5-936 KHAKI macro 5-1046 L LAYER_ACTIONS enumeration 5-937 LAYER_REGISTERS structure 5-332 LAYER_TYPE enumeration 5-294 lcc_demo 3-85 LCC_TASK enumeration 5-307 LED Control Functions 7-4238 LibQ Fixed-Point Math Library 5-1275 libq.h 5-1307 Library Architecture 5-2428, 5-2690, 5-2800, 5-3978, 5-4061, 5-4101, 5-4132 Library Configuration 5-4022, 5-4065, 5-4104, 5-4134 Library Initialization 5-4065, 5-4134 Library Interface 5-204, 5-237, 5-262, 5-291, 5-301, 5-311, 5-326, 5-335, 5-352, 5-377, 5-400, 5-428, 5-482, 5-519, 5-574, 5-609, 5-702, 5-1124, 5-1130, 5-1171, 5-1278, 5-1325, 5-1381, 5-1480, 5-1526, 5-1567, 5-1672, 5-1748, 5-1866, 5-1922, 5-2089, 5-2175, 5-2206, 5-2257, 5-2294, 5-2337, 5-2434, 5-2488, 5-2601, 5-2666, 5-2690, 5-2712, 5-2766, 5-2824, 5-2903, 5-3022, 5-3101, 5-3182, 5-3323, 5-3332, 5-3353, 5-3368, 5-3397, 5-3426, 5-3444, 5-3474, 5-3517, 5-3532, 5-3572, 5-3580, 5-3601, 5-3618, 5-3630, 5-3640, 5-3649, 5-3658, 5-3665, 5-3692, 5-3700, 5-3712, 5-3723, 5-3753, 5-3773, 5-3797, 5-3804, 5-3808, 5-3815, 5-3832, 5-3863, 5-3875, 5-3888, 5-3916, 5-3921, 5-3935, 5-3958, 5-3985, 5-4023, 5-4075, 5-4120, 5-4141, 5-4173, 5-4180, 5-4200, 7-4238 Library Overview 5-194, 5-230, 5-257, 5-290, 5-300, 5-310, 5-321, 5-334, 5-344, 5-369, 5-399, 5-420, 5-459, 5-514, 5-553, 5-607, 5-696, 5-1112, 5-1129, 5-1168, 5-1276, 5-1314, 5-1473, 5-1566, 5-2598, 5-3014, 5-3173, 5-3322, 5-3349, 5-3365, 5-3422, 5-3442, 5-3470, 5-3506, 5-3531, 5-3571, 5-3576, 5-3600, 5-3616, 5-3627, 5-3638, 5-3647, 5-3656, 5-3661, 5-3691, 5-3699, 5-3710, 5-3719, 5-3749, 5-3772, 5-3796, 5-3801, 5-3810, 5-3823, 5-3859, 5-3869, 5-3882, 5-3914, 5-3919, 5-3932, 5-3956, 5-4007, 5-4101, 7-4231, 7-4233, 7-4235, 7-4237 Library Usage Model 5-1366, 5-1670, 5-1736, 5-2088, 5-2204, 5-2254, 5-2333, 5-2480, 5-2665, 5-2706, 5-2895, 5-3088 LIGHTBLUE macro 5-1046 LIGHTCYAN macro 5-1047 LIGHTGRAY macro 5-1047 LIGHTGREEN macro 5-1047 LIGHTMAGENTA macro 5-1047 LIGHTORANGE macro 5-1047 LIGHTRED macro 5-1047 LIGHTYELLOW macro 5-1048 Link Local (Zeroconf) 5-3956 listen function 5-3605 LOCAL_TCP_PORT_END_NUMBER macro 5-3885 LOCAL_TCP_PORT_START_NUMBER macro 5-3885 Low-Cost Controllerless (LCC) Graphics Driver Library 5-299 M MAC TCP/IP Stack Library 5-3747 MAGENTA macro 5-1048 Main Program Changes 5-684, 5-3555 MAIN_RETURN macro 5-3341 MAIN_RETURN_CODE macro 5-3342 MAIN_RETURN_CODES enumeration 5-3334 Manager TCP/IP Stack Library 5-3770 9 MPLAB Harmony Help ii Managing Slave Addresses 5-2082 Master Descriptor Table 5-4012 Master Mode 5-2819 Math Library Help 5-1167 matrix32 structure 5-1265 MAX_ANYCAST_DELAY_TIME macro 5-3802 MAX_BSD_CLIENT_CONNECTIONS macro 5-3601 MAX_BSD_SERVER_CONNECTIONS macro 5-3601 MAX_MULTICAST_SOLICIT macro 5-3802 MAX_NEIGHBOR_ADVERTISEMENT macro 5-3802 MAX_NONBUFFERED_BYTE_COUNT macro 5-393 MAX_RTR_SOLICITATION_DELAY macro 5-3802 MAX_RTR_SOLICITATIONS macro 5-3803 MAX_SMTP_CONNECTIONS macro 5-3814 MAX_TELNET_CONNECTIONS macro 5-3915 MAX_UNICAST_SOLICIT macro 5-3803 MAX16 macro 5-1267 MAX32 macro 5-1267 MC_CRYPTO_API_H macro 5-1164 MCHP_BITMAP_NORMAL macro 5-1048 MCHP_BITMAP_PALETTE_STR macro 5-1048 mDNS 5-3957 MDNSD_ERR_CODE enumeration 5-3961 Media Driver Registration 5-4173 Media Independent Interface (MII) 5-1910 Memory Access Control 5-1524 Memory Operation 5-1322 Messaging Functionality 5-700 Messaging System Service Library 5-3438 Micrium uC_OS_III with Graphics 3-117 Migration Guide 5-3386 MIN16 macro 5-1267 MIN32 macro 5-1267 Miscellaneous 5-3473, 5-3513 Miscellaneous Config 5-480 Miscellaneous Configuration 5-428 Miscellaneous Functions 5-2256 Mode Configuration 5-1557 Module Events 5-1563 More Information 1-20 Mounting a Volume 5-3392 MPFS2 Command Line Options 5-3544 MPFS2 Utility 5-3542 MPLAB Harmony Configurator 2-40 MPLAB Harmony Configurator Help 2-39 MPLAB Harmony Graphics Library Access Changes 5-682 MPLAB Harmony Graphics Library API Changes 5-682 MPLAB Harmony Graphics Library BSP Configuration 5-685 MPLAB Harmony Graphics Library Configuration 5-685 MPLAB Harmony Graphics Library Configuration Changes 5-685 MPLAB Harmony Graphics Library Design 5-682 MPLAB Harmony Graphics Library File Name Compliance 5-686 MPLAB Harmony Graphics Library Function Name Compliance 5-687 MPLAB Harmony Graphics Library Initialization Changes 5-684 MPLAB Harmony Graphics Library Key Features 5-681 MPLAB Harmony Graphics Library Structure 5-681 MPLAB Harmony Graphics Library Utilities 5-685 MPLAB Harmony TCP/IP Stack Access Changes 5-3556 MPLAB Harmony TCP/IP Stack API Changes 5-3548 MPLAB Harmony TCP/IP Stack Configuration 5-3553 MPLAB Harmony TCP/IP Stack Configuration Changes 5-3553 MPLAB Harmony TCP/IP Stack Design 5-3548 MPLAB Harmony TCP/IP Stack Function Name Compliance 5-3558 MPLAB Harmony TCP/IP Stack Heap Configuration 5-3553 MPLAB Harmony TCP/IP Stack Initialization Changes 5-3556 MPLAB Harmony TCP/IP Stack Key Features 5-3546 MPLAB Harmony TCP/IP Stack SSL/RSA Usage 5-3557 MPLAB Harmony TCP/IP Stack Storage Changes 5-3552 MPLAB Harmony TCP/IP Stack Structure 5-3547 MPLAB Harmony TCP/IP Stack Utilities 5-3557 MPLAB Harmony vs. the Unified TCP/IP Stack 5-257 MPLAB Harmony vs. Unified Stack Functions 5-230 MRF24W Wi-Fi Driver Library 5-600 MSD Function Driver Registration 5-4172 msd_basic 3-164, 3-169 mul16 function 5-1263 9 MPLAB Harmony Help jj mul16r function 5-1263 mul32 function 5-1263 Multimedia Expansion Board (MEB) 3-96 Multimedia Expansion Board II (MEB II) 3-82, 3-96, 3-107, 3-140, 3-175 Mutex Operation 5-1318 MY_DEFAULT_SNMP_IF macro 5-3826 N NBNS TCP/IP Stack Library 5-3794 nbns.h 5-3797 nbns_config.h 5-3797 NBNS_MODULE_CONFIG structure 5-3797 NBNS_PORT macro 5-3796 NDP TCP/IP Stack Library 5-3798 ndp.h 5-3805 ndp_config.h 5-3805 NDP_TASK_TIMER_RATE macro 5-3803 NDP_VALID_LIFETIME_TWO_HOURS macro 5-3803 New MPLAB Harmony Graphics Library API Functions 5-684 New MPLAB Harmony TCP/IP Stack API Functions 5-3555 NMI Events Functions 5-2699 nmv_mpfs_single_disk 3-73 Non-Volatile Memory (NVM) Driver Library 5-342 NOTIFY_COMMUNITY_LEN macro 5-3827 NTP_DEFAULT_CONNECTION_TYPE macro 5-3860 NTP_DEFAULT_IF macro 5-3861 NTP_EPOCH macro 5-3861 NTP_FAST_QUERY_INTERVAL macro 5-3861 NTP_MAX_RETRIES macro 5-3861 NTP_MAX_STRATUM macro 5-3861 NTP_QUERY_INTERVAL macro 5-3861 NTP_REPLY_TIMEOUT macro 5-3862 NTP_SERVER macro 5-3862 NTP_SERVER_PORT macro 5-3862 NTP_TIME_STAMP_TMO macro 5-3862 NTP_VERSION macro 5-3862 NUM_ALPHA_LEVELS macro 5-294 NVM Driver Demonstration 3-102 NVM Peripheral Library 5-2252 nvm_fat_single_disk 3-66 nvm_sdcard_fat_mpfs_multi_disk 3-75 nvm_sdcard_fat_multi_disk 3-71 O Object Initialization 5-4171 object_demo 3-88 Objects Functionality 5-697 OC_16BIT_TIMERS enumeration 5-2312 OC_BUFFER_SIZE enumeration 5-2312 OC_CLOCK_RESOLUTION enumeration 5-2312 OC_COMPARE_MODES enumeration 5-2313 OC_FAULT_MODES enumeration 5-2314 OC_FAULT_OUT enumeration 5-2314 OC_FAULT_TRISTATE enumeration 5-2315 OC_FAULTS enumeration 5-2315 OC_MODULE_ID enumeration 5-2315 OC_SYNC_MODES enumeration 5-2316 OC_SYNC_SOURCES enumeration 5-2316 OC_TRIGGER_STATUS_MODES enumeration 5-2318 OID_MAX_LEN macro 5-3827 One Shot Callback 5-3510 ONEP25 macro 5-1048 Opening a File 5-3393 Opening the Driver 5-556 Operating as a Master 5-2483 Operating as a Master Receiver 5-2070 Operating as a Master Transmitter 5-2065 Operating as a Slave 5-2484 Operating as a Slave Receiver 5-2062 Operating as a Slave Transmitter 5-2063 Operating System Abstraction Layer (OSAL) Library Help 5-1311 Operating/Addressing Mode Management 5-1739 Optional Interfaces 5-467 ORANGE macro 5-1048 OSAL Operation 5-1322 osal.c 5-1325 9 MPLAB Harmony Help kk osal.h 5-1358 OSAL_CRIT_Enter function 5-1349 OSAL_CRIT_Leave function 5-1349 OSAL_CRIT_TYPE enumeration 5-1350 OSAL_CRIT_TYPE_HIGH enumeration member 5-1350 OSAL_CRIT_TYPE_LOW enumeration member 5-1350 OSAL_ERROR_CALLBACK_DEFAULT enumeration member 5-1352 OSAL_ERROR_CALLBACK_ERROR enumeration member 5-1352 OSAL_ERROR_CALLBACK_OUT_OF_MEMORY enumeration member 5-1352 OSAL_ERROR_CALLBACK_STACK_OVERFLOW enumeration member 5-1352 OSAL_ERROR_CALLBACK_TYPE enumeration 5-1352 OSAL_ErrorCallback function 5-1352 OSAL_Free function 5-1353 OSAL_Initialize function 5-1355 OSAL_ISR_Enter function 5-1351 OSAL_ISR_Exit function 5-1351 OSAL_Malloc function 5-1354 OSAL_MUTEX_Create function 5-1338 OSAL_MUTEX_DECLARE macro 5-1340 OSAL_MUTEX_Delete function 5-1338 OSAL_MUTEX_HANDLE_TYPE macro 5-1356 OSAL_MUTEX_Lock function 5-1339 OSAL_MUTEX_Unlock function 5-1340 OSAL_Name function 5-1355 OSAL_QUEUE_Add function 5-1341 OSAL_QUEUE_AddHead function 5-1342 OSAL_QUEUE_AddHeadISR function 5-1342 OSAL_QUEUE_AddISR function 5-1343 OSAL_QUEUE_Create function 5-1344 OSAL_QUEUE_DECLARE macro 5-1341 OSAL_QUEUE_Delete function 5-1345 OSAL_QUEUE_HANDLE_TYPE macro 5-1356 OSAL_QUEUE_Peek function 5-1345 OSAL_QUEUE_PeekISR function 5-1346 OSAL_QUEUE_Remove function 5-1347 OSAL_QUEUE_RemoveISR function 5-1348 OSAL_RESULT enumeration 5-1357 OSAL_RESULT_FALSE enumeration member 5-1357 OSAL_RESULT_NOT_IMPLEMENTED enumeration member 5-1357 OSAL_RESULT_TRUE enumeration member 5-1357 OSAL_SEM_Create function 5-1333 OSAL_SEM_DECLARE macro 5-1337 OSAL_SEM_Delete function 5-1334 OSAL_SEM_GetCount function 5-1334 OSAL_SEM_HANDLE_TYPE macro 5-1356 OSAL_SEM_Pend function 5-1335 OSAL_SEM_Post function 5-1336 OSAL_SEM_PostISR function 5-1336 OSAL_SEM_TYPE enumeration 5-1357 OSAL_SEM_TYPE_BINARY enumeration member 5-1357 OSAL_SEM_TYPE_COUNTING enumeration member 5-1357 OSAL_Start function 5-1356 OSAL_THREAD_Create function 5-1327 OSAL_THREAD_CreateDaemon function 5-1328 OSAL_THREAD_FUNCTION type 5-1327 OSAL_THREAD_HANDLE_TYPE macro 5-1357 OSAL_THREAD_PriorityGet function 5-1329 OSAL_THREAD_PrioritySet function 5-1330 OSAL_THREAD_Resume function 5-1330 OSAL_THREAD_ResumeAll function 5-1331 OSAL_THREAD_Sleep function 5-1331 OSAL_THREAD_Suspend function 5-1332 OSAL_THREAD_SuspendAll function 5-1333 OSAL_USE_NONE macro 5-1357 OSAL_WAIT_FOREVER macro 5-1357 OSC_AUX_CLOCK_SOURCE enumeration 5-2394 OSC_AUX_MODE enumeration 5-2394 OSC_AUXPLL_IN_DIV enumeration 5-2394 OSC_AUXPLL_MULTIPLIER enumeration 5-2395 OSC_AUXPLL_OUT_DIV enumeration 5-2395 OSC_DOZE_RATIO enumeration 5-2396 OSC_FRC_DIV enumeration 5-2396 OSC_FRC_TUNE enumeration 5-2397 OSC_GFX_CLOCK enumeration 5-2398 OSC_LFSR_TYPE enumeration 5-2398 OSC_MODULE_ID enumeration 5-2399 9 MPLAB Harmony Help ll OSC_OPERATION_ON_WAIT enumeration 5-2399 OSC_PB_CLOCK_DIV_TYPE macro 5-2393 OSC_PERIPHERAL_BUS enumeration 5-2399 OSC_PLL_SELECT enumeration 5-2400 OSC_PLLAUX_CLOCK_SOURCE enumeration 5-2400 OSC_REF_BASECLOCK enumeration 5-2401 OSC_REF_DIV enumeration 5-2401 OSC_REF_DIVISOR_TYPE macro 5-2393 OSC_REFERENCE enumeration 5-2402 OSC_REFERENCE_MAX_DIV macro 5-2393 OSC_SYS_CLOCK_DIV enumeration 5-2403 OSC_SYS_TYPE enumeration 5-2403 OSC_SYSPLL_FREQ_RANGE enumeration 5-2404 OSC_SYSPLL_IN_CLK_SOURCE enumeration 5-2404 OSC_SYSPLL_IN_DIV enumeration 5-2405 OSC_SYSPLL_MULTIPLIER_TYPE macro 5-2393 OSC_SYSPLL_OUT_DIV enumeration 5-2405 OSC_TUNING_MODE enumeration 5-2406 OSC_TUNING_SEQUENCERS enumeration 5-2406 OSC_USBCLOCK_SOURCE enumeration 5-2407 Oscillator Peripheral Library 5-2330 Oscillator Selection and Switching 5-2333 Oscillator Tuning 5-3351 Other Features 5-2086, 5-2487, 5-2822, 5-3020, 5-3099 Other Functionality 5-608, 5-1316, 5-2711 Other Functions 7-4240 Others 5-574, 5-609, 5-1324, 5-3366 OTM2201A Graphics Controller Driver Library 5-309 OTM2201A_TASK enumeration 5-318 Output Compare Peripheral Library 5-2287 Overview 3-65 P PA6_IO macro 5-673 PA6_TRISTATE macro 5-674 PAGE_TYPE enumeration 5-294 PALETTE_ENTRY union 5-938 PALETTE_EXTERNAL type 5-938 PALETTE_FLASH structure 5-938 PALETTE_HEADER structure 5-939 PaletteInit function 5-876 Parallel Master Port (PMP) Driver Library 5-367 PARM_EQUAL_FILTER structure 5-1265 PARM_EQUAL_FILTER_16 structure 5-1266 PARM_EQUAL_FILTER_32 structure 5-1266 PARM_FILTER_GAIN structure 5-1267 PCACHE_MODULE_ID enumeration 5-2463 Percentage2Alpha function 5-291 Period Modification 5-464 Periodic Callback 5-3509 Peripheral Libraries 4-182 Peripheral Library Example Applications 3-98 Peripheral Library Help 5-1361 Peripheral Pin Select 5-3473 PERU macro 5-1049 PGV Error Handling 5-2765 PHY_NEG_DONE_TMO macro 5-261 PHY_NEG_INIT_TMO macro 5-262 PHY_RESET_CLR_TMO macro 5-262 PIC32 Ethernet Starter Kit 3-136 PIC32 USB Digital Audio Accessory Board 3-173 PIC32 USB Starter Kit II 3-77, 3-91, 3-104, 3-118, 3-170 PIC32 USB Starter Kit II BSP Library 7-4232 pic32_ethernet_starter_kit 3-131 PIC32MX USB Audio BSP Library 7-4234 PIC32MX795F512 Plug-In-Module (PIM) 3-79 PIC32MX795F512L Plug-in Module (PIM) 3-105, 3-125, 3-144 PIC32MX795F512L Plug-In-Module (PIM) 3-96, 3-173 PIC32MZ Embedded Connectivity (EC) Starter Kit 3-80, 3-92, 3-106, 3-119, 3-137, 3-173 PIC32MZ Embedded Connectivity (EC) Starter Kit BSP Library 7-4236 PICtail Daughter Board for SD and MMC 3-80 PICtail Plus LCC Daughter Board 3-95 PICtail Plus S1D13517 Daughter Board 3-95 PICtail Plus SSD1926 Daughter Board 3-95 Pin Control 5-3470 PIO Mode 5-2900 PIP_BUFFER macro 5-307 9 MPLAB Harmony Help mm Pipe Close 5-560 Pipe Setup 5-558 Pipe Stall 5-561 Pipe Status 5-559 Pipe Transfer Queue 5-560 plib_adc.h 5-1467 PLIB_ADC_AsynchronousDedicatedSamplingDisable function 5-1417 PLIB_ADC_AsynchronousDedicatedSamplingEnable function 5-1417 PLIB_ADC_CalibrationDisable function 5-1389 PLIB_ADC_CalibrationEnable function 5-1388 PLIB_ADC_ChannelGroupSelect function 5-1393 PLIB_ADC_ConversionClockGet function 5-1402 PLIB_ADC_ConversionClockSet function 5-1402 PLIB_ADC_ConversionClockSourceSelect function 5-1403 PLIB_ADC_ConversionHasCompleted function 5-1400 PLIB_ADC_ConversionOrderSelect function 5-1404 PLIB_ADC_ConversionStart function 5-1399 PLIB_ADC_ConversionStopSequenceDisable function 5-1401 PLIB_ADC_ConversionStopSequenceEnable function 5-1401 PLIB_ADC_ConversionTriggerGroupSelect function 5-1404 PLIB_ADC_ConversionTriggerSourceSelect function 5-1400 PLIB_ADC_Disable function 5-1386 PLIB_ADC_DMAAddressIncrementSelect function 5-1405 PLIB_ADC_DMABufferModeSelect function 5-1405 PLIB_ADC_DMADisable function 5-1406 PLIB_ADC_DMAEnable function 5-1406 PLIB_ADC_DMAInputBufferSelect function 5-1407 PLIB_ADC_Enable function 5-1385 PLIB_ADC_ExistsAsynchronousDedicatedSampling function 5-1439 PLIB_ADC_ExistsCalibrationControl function 5-1439 PLIB_ADC_ExistsChannelGroup function 5-1440 PLIB_ADC_ExistsConversionClock function 5-1440 PLIB_ADC_ExistsConversionClockSource function 5-1441 PLIB_ADC_ExistsConversionControl function 5-1441 PLIB_ADC_ExistsConversionOrder function 5-1442 PLIB_ADC_ExistsConversionStatus function 5-1442 PLIB_ADC_ExistsConversionStopSequenceControl function 5-1443 PLIB_ADC_ExistsConversionTriggerGroup function 5-1443 PLIB_ADC_ExistsConversionTriggerSource function 5-1444 PLIB_ADC_ExistsDMAAddressIncrement function 5-1444 PLIB_ADC_ExistsDMABufferMode function 5-1445 PLIB_ADC_ExistsDMABuffersPerAnalogInput function 5-1445 PLIB_ADC_ExistsDMAControl function 5-1446 PLIB_ADC_ExistsEnableControl function 5-1446 PLIB_ADC_ExistsGlobalSoftwareTrigger function 5-1447 PLIB_ADC_ExistsInputSelect function 5-1447 PLIB_ADC_ExistsInternalReferenceChannelControl function 5-1448 PLIB_ADC_ExistsISRJumpTableBaseAddress function 5-1448 PLIB_ADC_ExistsMuxChannel0NegativeInput function 5-1449 PLIB_ADC_ExistsMuxChannel0PositiveInput function 5-1449 PLIB_ADC_ExistsMuxChannel123NegativeInput function 5-1450 PLIB_ADC_ExistsMuxChannel123PositiveInput function 5-1450 PLIB_ADC_ExistsMuxInputScanControl function 5-1451 PLIB_ADC_ExistsMuxInputScanSelect function 5-1451 PLIB_ADC_ExistsPairConversionControl function 5-1452 PLIB_ADC_ExistsPairInterruptOnConversion function 5-1453 PLIB_ADC_ExistsPairInterruptRequest function 5-1453 PLIB_ADC_ExistsPairSampleStatus function 5-1454 PLIB_ADC_ExistsPairTriggerSource function 5-1454 PLIB_ADC_ExistsResultBufferFillStatus function 5-1455 PLIB_ADC_ExistsResultBufferMode function 5-1455 PLIB_ADC_ExistsResultFormat function 5-1456 PLIB_ADC_ExistsResultGet function 5-1456 PLIB_ADC_ExistsResultGetByIndex function 5-1457 PLIB_ADC_ExistsResultSign function 5-1457 PLIB_ADC_ExistsResultSize function 5-1458 PLIB_ADC_ExistsSampleResolution function 5-1458 PLIB_ADC_ExistsSamplesPerInterruptSelect function 5-1459 PLIB_ADC_ExistsSamplingAcquisitionTime function 5-1459 PLIB_ADC_ExistsSamplingAutoStart function 5-1460 PLIB_ADC_ExistsSamplingControl function 5-1460 PLIB_ADC_ExistsSamplingModeControl function 5-1461 PLIB_ADC_ExistsSamplingStatus function 5-1461 PLIB_ADC_ExistsStopInIdleControl function 5-1462 PLIB_ADC_ExistsVoltageReference function 5-1462 9 MPLAB Harmony Help nn PLIB_ADC_GlobalSoftwareTriggerSet function 5-1418 PLIB_ADC_InputScanMaskAdd function 5-1390 PLIB_ADC_InputScanMaskRemove function 5-1391 PLIB_ADC_InputSelectNegative function 5-1390 PLIB_ADC_InputSelectPositive function 5-1389 PLIB_ADC_InternalReferenceChannelDisable function 5-1392 PLIB_ADC_InternalReferenceChannelEnable function 5-1392 PLIB_ADC_IsrJumpTableBaseAddressGet function 5-1419 PLIB_ADC_IsrJumpTableBaseAddressSet function 5-1419 PLIB_ADC_MuxAInputScanDisable function 5-1463 PLIB_ADC_MuxAInputScanEnable function 5-1463 PLIB_ADC_MuxChannel0InputNegativeSelect function 5-1464 PLIB_ADC_MuxChannel0InputPositiveSelect function 5-1465 PLIB_ADC_MuxChannel123InputNegativeSelect function 5-1465 PLIB_ADC_MuxChannel123InputPositiveSelect function 5-1466 PLIB_ADC_PairConversionIsPending function 5-1408 PLIB_ADC_PairConversionStart function 5-1408 PLIB_ADC_PairInterruptAfterFirstConversion function 5-1409 PLIB_ADC_PairInterruptAfterSecondConversion function 5-1409 PLIB_ADC_PairInterruptRequestDisable function 5-1410 PLIB_ADC_PairInterruptRequestEnable function 5-1410 PLIB_ADC_PairSampleIsAvailable function 5-1411 PLIB_ADC_PairSampleStatusClear function 5-1412 PLIB_ADC_PairTriggerSourceSelect function 5-1412 PLIB_ADC_ResultBufferModeSelect function 5-1413 PLIB_ADC_ResultBufferStatusGet function 5-1413 PLIB_ADC_ResultFormatSelect function 5-1414 PLIB_ADC_ResultGet function 5-1415 PLIB_ADC_ResultGetByIndex function 5-1415 PLIB_ADC_ResultSignGet function 5-1416 PLIB_ADC_ResultSizeSelect function 5-1416 PLIB_ADC_SampleAcqusitionTimeSet function 5-1394 PLIB_ADC_SampleAutoStartDisable function 5-1394 PLIB_ADC_SampleAutoStartEnable function 5-1395 PLIB_ADC_SampleMaxGet function 5-1395 PLIB_ADC_SampleMinGet function 5-1396 PLIB_ADC_SamplesPerInterruptSelect function 5-1396 PLIB_ADC_SamplingIsActive function 5-1397 PLIB_ADC_SamplingModeSelect function 5-1397 PLIB_ADC_SamplingStart function 5-1398 PLIB_ADC_SamplingStop function 5-1399 PLIB_ADC_StopInIdleDisable function 5-1386 PLIB_ADC_StopInIdleEnable function 5-1387 PLIB_ADC_VoltageReferenceSelect function 5-1387 plib_adcp.h 5-1518 PLIB_ADCP_AlternateInputSelect function 5-1489 PLIB_ADCP_CalibrationStart function 5-1484 PLIB_ADCP_ChannelScanConfigure function 5-1492 PLIB_ADCP_Class12TriggerConfigure function 5-1495 PLIB_ADCP_Configure function 5-1482 PLIB_ADCP_DefaultInputSelect function 5-1490 PLIB_ADCP_DigCmpAIdGet function 5-1500 PLIB_ADCP_DigCmpConfig function 5-1500 PLIB_ADCP_DigCmpDisable function 5-1499 PLIB_ADCP_DigCmpEnable function 5-1499 PLIB_ADCP_Disable function 5-1483 PLIB_ADCP_Enable function 5-1483 PLIB_ADCP_ExistsCalibration function 5-1486 PLIB_ADCP_ExistsChannelScan function 5-1493 PLIB_ADCP_ExistsConfiguration function 5-1488 PLIB_ADCP_ExistsConversionResults function 5-1498 PLIB_ADCP_ExistsDigCmp function 5-1502 PLIB_ADCP_ExistsEnableControl function 5-1486 PLIB_ADCP_ExistsInputSelect function 5-1491 PLIB_ADCP_ExistsLowPowerControl function 5-1487 PLIB_ADCP_ExistsModeSelect function 5-1491 PLIB_ADCP_ExistsOsampDigFilter function 5-1505 PLIB_ADCP_ExistsReadyStatus function 5-1489 PLIB_ADCP_ExistsTriggering function 5-1495 PLIB_ADCP_GlobalSoftwareTrigger function 5-1494 PLIB_ADCP_IndividualTrigger function 5-1494 PLIB_ADCP_LowPowerStateEnter function 5-1484 PLIB_ADCP_LowPowerStateExit function 5-1485 PLIB_ADCP_LowPowerStateGet function 5-1485 PLIB_ADCP_ModuleIsReady function 5-1488 PLIB_ADCP_OsampDigFilterConfig function 5-1505 PLIB_ADCP_OsampDigFilterDataGet function 5-1504 PLIB_ADCP_OsampDigFilterDataRdy function 5-1503 9 MPLAB Harmony Help oo PLIB_ADCP_OsampDigFilterDisable function 5-1503 PLIB_ADCP_OsampDigFilterEnable function 5-1502 PLIB_ADCP_ResultGet function 5-1497 PLIB_ADCP_ResultReady function 5-1496 PLIB_ADCP_ResultReadyGrpIntConfigure function 5-1497 PLIB_ADCP_SHModeSelect function 5-1492 plib_bmx.h 5-1552 PLIB_BMX_ARB_MODE enumeration 5-1543 PLIB_BMX_ArbitrationModeGet function 5-1535 PLIB_BMX_ArbitrationModeSet function 5-1535 PLIB_BMX_BusExceptionDataDisable function 5-1528 PLIB_BMX_BusExceptionDataEnable function 5-1529 PLIB_BMX_BusExceptionDMADisable function 5-1529 PLIB_BMX_BusExceptionDMAEnable function 5-1530 PLIB_BMX_BusExceptionICDDisable function 5-1530 PLIB_BMX_BusExceptionICDEnable function 5-1531 PLIB_BMX_BusExceptionInstructionDisable function 5-1531 PLIB_BMX_BusExceptionInstructionEnable function 5-1532 PLIB_BMX_BusExceptionIXIDisable function 5-1532 PLIB_BMX_BusExceptionIXIEnable function 5-1533 PLIB_BMX_DATA_RAM_WAIT_STATES enumeration 5-1543 PLIB_BMX_DataRAMKernelProgramOffsetGet function 5-1536 PLIB_BMX_DataRAMPartitionSet function 5-1536 PLIB_BMX_DataRAMSizeGet function 5-1537 PLIB_BMX_DataRAMUserDataOffsetGet function 5-1538 PLIB_BMX_DataRAMUserProgramOffsetGet function 5-1538 PLIB_BMX_DataRamWaitStateGet function 5-1539 PLIB_BMX_DataRamWaitStateSet function 5-1540 PLIB_BMX_DRM_BLOCK_SIZE macro 5-1544 PLIB_BMX_EXCEPTION_SRC enumeration 5-1544 PLIB_BMX_ExistsArbitrationMode function 5-1545 PLIB_BMX_ExistsBusExceptionData function 5-1545 PLIB_BMX_ExistsBusExceptionDMA function 5-1546 PLIB_BMX_ExistsBusExceptionICD function 5-1546 PLIB_BMX_ExistsBusExceptionInstruction function 5-1547 PLIB_BMX_ExistsBusExceptionIXI function 5-1547 PLIB_BMX_ExistsDataRAMPartition function 5-1548 PLIB_BMX_ExistsDataRAMSize function 5-1548 PLIB_BMX_ExistsDataRamWaitState function 5-1549 PLIB_BMX_ExistsProgramFlashBootSize function 5-1549 PLIB_BMX_ExistsProgramFlashMemoryCacheDma function 5-1550 PLIB_BMX_ExistsProgramFlashMemorySize function 5-1550 PLIB_BMX_ExistsProgramFlashPartition function 5-1551 PLIB_BMX_PFM_BLOCK_SIZE macro 5-1544 PLIB_BMX_ProgramFlashBootSizeGet function 5-1540 PLIB_BMX_ProgramFlashMemoryCacheDmaDisable function 5-1533 PLIB_BMX_ProgramFlashMemoryCacheDmaEnable function 5-1534 PLIB_BMX_ProgramFlashMemorySizeGet function 5-1541 PLIB_BMX_ProgramFlashPartitionGet function 5-1541 PLIB_BMX_ProgramFlashPartitionSet function 5-1542 plib_can.h 5-1662 PLIB_CAN_AllChannelEventsGet function 5-1595 PLIB_CAN_AllChannelOverflowStatusGet function 5-1596 PLIB_CAN_BusActivityWakeupDisable function 5-1572 PLIB_CAN_BusActivityWakeupEnable function 5-1572 PLIB_CAN_BusLine3TimesSamplingDisable function 5-1583 PLIB_CAN_BusLine3TimesSamplingEnable function 5-1584 PLIB_CAN_ChannelEventClear function 5-1597 PLIB_CAN_ChannelEventDisable function 5-1592 PLIB_CAN_ChannelEventEnable function 5-1598 PLIB_CAN_ChannelEventGet function 5-1599 PLIB_CAN_ChannelForReceiveSet function 5-1589 PLIB_CAN_ChannelForTransmitSet function 5-1590 PLIB_CAN_ChannelReset function 5-1590 PLIB_CAN_ChannelResetIsComplete function 5-1579 PLIB_CAN_ChannelUpdate function 5-1591 PLIB_CAN_DeviceNetConfigure function 5-1579 PLIB_CAN_Disable function 5-1573 PLIB_CAN_Enable function 5-1574 PLIB_CAN_ErrorStateGet function 5-1617 PLIB_CAN_ExistsActiveStatus function 5-1636 PLIB_CAN_ExistsAllChannelEvents function 5-1637 PLIB_CAN_ExistsAllChannelOverflow function 5-1637 PLIB_CAN_ExistsBusActivityWakeup function 5-1638 PLIB_CAN_ExistsBusLine3TimesSampling function 5-1638 PLIB_CAN_ExistsChannelEvent function 5-1639 9 MPLAB Harmony Help pp PLIB_CAN_ExistsChannelEventEnable function 5-1639 PLIB_CAN_ExistsChannelForReceiveSet function 5-1640 PLIB_CAN_ExistsChannelForTransmitSet function 5-1640 PLIB_CAN_ExistsChannelReset function 5-1641 PLIB_CAN_ExistsChannelUpdate function 5-1641 PLIB_CAN_ExistsDeviceNet function 5-1642 PLIB_CAN_ExistsEnableControl function 5-1642 PLIB_CAN_ExistsErrorState function 5-1643 PLIB_CAN_ExistsFilterConfigure function 5-1643 PLIB_CAN_ExistsFilterEnable function 5-1644 PLIB_CAN_ExistsFilterMaskConfigure function 5-1644 PLIB_CAN_ExistsFilterToChannelLink function 5-1645 PLIB_CAN_ExistsFunctionalMode function 5-1645 PLIB_CAN_ExistsLatestFilterMatchGet function 5-1646 PLIB_CAN_ExistsMemoryBufferAssign function 5-1646 PLIB_CAN_ExistsMessageIsReceived function 5-1647 PLIB_CAN_ExistsModuleEventClear function 5-1647 PLIB_CAN_ExistsModuleEventEnable function 5-1648 PLIB_CAN_ExistsModuleInfo function 5-1648 PLIB_CAN_ExistsOperationModeRead function 5-1649 PLIB_CAN_ExistsOperationModeWrite function 5-1649 PLIB_CAN_ExistsPendingEventsGet function 5-1650 PLIB_CAN_ExistsPendingTransmissionsAbort function 5-1650 PLIB_CAN_ExistsPhaseSegment1Length function 5-1651 PLIB_CAN_ExistsPhaseSegment2Length function 5-1651 PLIB_CAN_ExistsPhaseSegment2LengthFreelyProgrammable function 5-1652 PLIB_CAN_ExistsPropagationTimeSegment function 5-1652 PLIB_CAN_ExistsReceiveBufferClear function 5-1653 PLIB_CAN_ExistsReceiveBufferIsEmpty function 5-1653 PLIB_CAN_ExistsReceivedMessageGet function 5-1654 PLIB_CAN_ExistsReceiveErrorCount function 5-1654 PLIB_CAN_ExistsReceiveModeSelect function 5-1655 PLIB_CAN_ExistsRemoteTransmitReq function 5-1655 PLIB_CAN_ExistsRxFIFOFourLeftNotify function 5-1656 PLIB_CAN_ExistsRxFIFOOneLeftNotify function 5-1656 PLIB_CAN_ExistsStopInIdle function 5-1657 PLIB_CAN_ExistsSyncJumpWidthSet function 5-1657 PLIB_CAN_ExistsTimeStampEnable function 5-1658 PLIB_CAN_ExistsTimeStampPrescalar function 5-1658 PLIB_CAN_ExistsTimeStampValue function 5-1659 PLIB_CAN_ExistsTransmissionIsAborted function 5-1660 PLIB_CAN_ExistsTransmitBufferGet function 5-1660 PLIB_CAN_ExistsTransmitChannelFlush function 5-1661 PLIB_CAN_ExistsTransmitChannelStatus function 5-1661 PLIB_CAN_ExistsTransmitErrorCountGet function 5-1662 PLIB_CAN_FilterConfigure function 5-1612 PLIB_CAN_FilterDisable function 5-1612 PLIB_CAN_FilterEnable function 5-1613 PLIB_CAN_FilterIsDisabled function 5-1614 PLIB_CAN_FilterMaskConfigure function 5-1614 PLIB_CAN_FilterToChannelLink function 5-1615 PLIB_CAN_FunctionalModeGet function 5-1580 PLIB_CAN_FunctionalModeSelect function 5-1583 PLIB_CAN_IsActive function 5-1574 PLIB_CAN_LatestFilterMatchGet function 5-1616 PLIB_CAN_MemoryBufferAssign function 5-1580 PLIB_CAN_MessageIsReceived function 5-1609 PLIB_CAN_ModuleEventClear function 5-1593 PLIB_CAN_ModuleEventDisable function 5-1593 PLIB_CAN_ModuleEventEnable function 5-1594 PLIB_CAN_ModuleEventGet function 5-1595 PLIB_CAN_OperationModeGet function 5-1575 PLIB_CAN_OperationModeSelect function 5-1576 PLIB_CAN_PendingEventsGet function 5-1600 PLIB_CAN_PendingTransmissionsAbort function 5-1601 PLIB_CAN_PhaseSegment1LengthSet function 5-1585 PLIB_CAN_PhaseSegment2LengthFreelyProgrammableDisable function 5-1586 PLIB_CAN_PhaseSegment2LengthFreelyProgrammableEnable function 5-1586 PLIB_CAN_PhaseSegment2LengthSet function 5-1587 PLIB_CAN_PropagationTimeSegmentSet function 5-1588 PLIB_CAN_ReceiveBufferClear function 5-1610 PLIB_CAN_ReceiveBufferIsEmpty function 5-1610 PLIB_CAN_ReceivedMessageGet function 5-1605 PLIB_CAN_ReceiveErrorCountGet function 5-1616 PLIB_CAN_ReceiveModeGet function 5-1608 PLIB_CAN_ReceiveModeSelect function 5-1608 9 MPLAB Harmony Help qq PLIB_CAN_RemoteTransmitReqIsReceived function 5-1611 PLIB_CAN_RxFIFOFourLeftNotify function 5-1607 PLIB_CAN_RxFIFOOneLeftNotify function 5-1607 PLIB_CAN_StopInIdleDisable function 5-1576 PLIB_CAN_StopInIdleEnable function 5-1577 PLIB_CAN_SyncJumpWidthSet function 5-1588 PLIB_CAN_TimeStampDisable function 5-1577 PLIB_CAN_TimeStampEnable function 5-1578 PLIB_CAN_TimeStampPrescalarSet function 5-1581 PLIB_CAN_TimeStampValueGet function 5-1582 PLIB_CAN_TimeStampValueSet function 5-1582 PLIB_CAN_TotalChannelsGet function 5-1618 PLIB_CAN_TotalFiltersGet function 5-1618 PLIB_CAN_TotalMasksGet function 5-1619 PLIB_CAN_TransmissionIsAborted function 5-1601 PLIB_CAN_TransmitBufferGet function 5-1602 PLIB_CAN_TransmitChannelFlush function 5-1603 PLIB_CAN_TransmitChannelStatusGet function 5-1604 PLIB_CAN_TransmitErrorCountGet function 5-1605 plib_cmp.h 5-1730 PLIB_CMP_AndGateAInputDisable function 5-1696 PLIB_CMP_AndGateAInputEnable function 5-1697 PLIB_CMP_AndGateBInputDisable function 5-1697 PLIB_CMP_AndGateBInputEnable function 5-1698 PLIB_CMP_AndGateCInputDisable function 5-1704 PLIB_CMP_AndGateCInputEnable function 5-1698 PLIB_CMP_AndGateInvertedAInputDisable function 5-1699 PLIB_CMP_AndGateInvertedAInputEnable function 5-1699 PLIB_CMP_AndGateInvertedBInputDisable function 5-1700 PLIB_CMP_AndGateInvertedBInputEnable function 5-1700 PLIB_CMP_AndGateInvertedCInputDisable function 5-1701 PLIB_CMP_AndGateInvertedCInputEnable function 5-1701 PLIB_CMP_Cmp1OutputHighSelect function 5-1690 PLIB_CMP_Cmp1OutputLowSelect function 5-1690 PLIB_CMP_Cmp2OutputHighSelect function 5-1691 PLIB_CMP_Cmp2OutputLowSelect function 5-1691 PLIB_CMP_CVREF_BandGapReferenceSourceSelect function 5-1676 PLIB_CMP_CVREF_Disable function 5-1689 PLIB_CMP_CVREF_Enable function 5-1676 PLIB_CMP_CVREF_Output2Disable function 5-1677 PLIB_CMP_CVREF_Output2Enable function 5-1677 PLIB_CMP_CVREF_OutputDisable function 5-1678 PLIB_CMP_CVREF_OutputEnable function 5-1678 PLIB_CMP_CVREF_ReferenceVoltageSelect function 5-1679 PLIB_CMP_CVREF_SourceNegativeInputSelect function 5-1679 PLIB_CMP_CVREF_SourceVoltageSelect function 5-1680 PLIB_CMP_CVREF_ValueGet function 5-1680 PLIB_CMP_CVREF_ValueSelect function 5-1681 PLIB_CMP_CVREF_WideRangeDisable function 5-1681 PLIB_CMP_CVREF_WideRangeEnable function 5-1682 PLIB_CMP_CVREF_WideRangeIsEnabled function 5-1682 PLIB_CMP_Disable function 5-1683 PLIB_CMP_Enable function 5-1683 PLIB_CMP_EventHasOccurred function 5-1684 PLIB_CMP_EventStatusClear function 5-1684 PLIB_CMP_ExistsCVREFBGRefVoltageRangeSelect function 5-1722 PLIB_CMP_ExistsCVREFEnableControl function 5-1723 PLIB_CMP_ExistsCVREFOutputEnableControl function 5-1723 PLIB_CMP_ExistsCVREFRefVoltageRangeSelect function 5-1724 PLIB_CMP_ExistsCVREFValueSelect function 5-1724 PLIB_CMP_ExistsCVREFVoltageRangeSelect function 5-1725 PLIB_CMP_ExistsCVREFWideRangeControl function 5-1725 PLIB_CMP_ExistsEnableControl function 5-1726 PLIB_CMP_ExistsInterruptEventSelect function 5-1727 PLIB_CMP_ExistsInvertingInputSelect function 5-1727 PLIB_CMP_ExistsInvertOutputControl function 5-1728 PLIB_CMP_ExistsNonInvertingInputSelect function 5-1728 PLIB_CMP_ExistsOutputEnableControl function 5-1729 PLIB_CMP_ExistsOutputLevelControl function 5-1729 PLIB_CMP_ExistsStopInIdle function 5-1730 PLIB_CMP_FilterClockDivideSelect function 5-1704 PLIB_CMP_FilterDisable function 5-1705 PLIB_CMP_FilterEnable function 5-1705 PLIB_CMP_FilterInputClockSelect function 5-1706 PLIB_CMP_HighLevelMaskSelect function 5-1715 PLIB_CMP_HysteresisDisable function 5-1692 9 MPLAB Harmony Help rr PLIB_CMP_HysteresisEnable function 5-1692 PLIB_CMP_InterruptEventSelect function 5-1685 PLIB_CMP_InvertedOutputSelect function 5-1686 PLIB_CMP_InvertingInputChannelSelect function 5-1686 PLIB_CMP_LowLevelMaskSelect function 5-1715 PLIB_CMP_NegativeAndGateOutputDisable function 5-1702 PLIB_CMP_NegativeAndGateOutputEnable function 5-1702 PLIB_CMP_NonInvertedOutputSelect function 5-1687 PLIB_CMP_NonInvertingInputChannelSelect function 5-1687 PLIB_CMP_OpAmpModeDisable function 5-1706 PLIB_CMP_OpAmpModeEnable function 5-1707 PLIB_CMP_OpAmpOutputDisable function 5-1707 PLIB_CMP_OpAmpOutputEnable function 5-1708 PLIB_CMP_OrGateAInputDisable function 5-1708 PLIB_CMP_OrGateAInputEnable function 5-1709 PLIB_CMP_OrGateBInputDisable function 5-1709 PLIB_CMP_OrGateBInputEnable function 5-1710 PLIB_CMP_OrGateCInputDisable function 5-1710 PLIB_CMP_OrGateCInputEnable function 5-1711 PLIB_CMP_OrGateInvertedAInputDisable function 5-1711 PLIB_CMP_OrGateInvertedAInputEnable function 5-1712 PLIB_CMP_OrGateInvertedBInputDisable function 5-1712 PLIB_CMP_OrGateInvertedBInputEnable function 5-1713 PLIB_CMP_OrGateInvertedCInputDisable function 5-1713 PLIB_CMP_OrGateInvertedCInputEnable function 5-1714 PLIB_CMP_OutputDisable function 5-1688 PLIB_CMP_OutputEnable function 5-1688 PLIB_CMP_OutputHighSelect function 5-1693 PLIB_CMP_OutputLowSelect function 5-1693 PLIB_CMP_OutputStatusGet function 5-1689 PLIB_CMP_OutputSynchronousWithTimer1Disable function 5-1694 PLIB_CMP_OutputSynchronousWithTimer1Enable function 5-1694 PLIB_CMP_PositiveAndGateOutputDisable function 5-1703 PLIB_CMP_PositiveAndGateOutputEnable function 5-1703 PLIB_CMP_StopInIdleModeDisable function 5-1695 PLIB_CMP_StopInIdleModeEnable function 5-1696 plib_dma.h 5-1859 PLIB_DMA_AbortTransferSet function 5-1758 PLIB_DMA_BusyActiveReset function 5-1755 PLIB_DMA_BusyActiveSet function 5-1755 PLIB_DMA_ChannelBitsGet function 5-1820 PLIB_DMA_ChannelPriorityGet function 5-1788 PLIB_DMA_ChannelPrioritySelect function 5-1788 PLIB_DMA_ChannelXAbortIRQSet function 5-1759 PLIB_DMA_ChannelXAddressModeGet function 5-1766 PLIB_DMA_ChannelXAddressModeSelect function 5-1767 PLIB_DMA_ChannelXAutoDisable function 5-1789 PLIB_DMA_ChannelXAutoEnable function 5-1789 PLIB_DMA_ChannelXAutoIsEnabled function 5-1815 PLIB_DMA_ChannelXBufferedDataIsWritten function 5-1816 PLIB_DMA_ChannelXBusyActiveSet function 5-1790 PLIB_DMA_ChannelXBusyInActiveSet function 5-1790 PLIB_DMA_ChannelXBusyIsBusy function 5-1816 PLIB_DMA_ChannelXCellProgressPointerGet function 5-1779 PLIB_DMA_ChannelXCellSizeGet function 5-1779 PLIB_DMA_ChannelXCellSizeSet function 5-1780 PLIB_DMA_ChannelXChainDisable function 5-1791 PLIB_DMA_ChannelXChainEnable function 5-1791 PLIB_DMA_ChannelXChainIsEnabled function 5-1817 PLIB_DMA_ChannelXChainToHigher function 5-1792 PLIB_DMA_ChannelXChainToLower function 5-1792 PLIB_DMA_ChannelXCollisionStatus function 5-1817 PLIB_DMA_ChannelXDataSizeGet function 5-1780 PLIB_DMA_ChannelXDataSizeSelect function 5-1781 PLIB_DMA_ChannelXDestinationAddressModeGet function 5-1768 PLIB_DMA_ChannelXDestinationAddressModeSelect function 5-1768 PLIB_DMA_ChannelXDestinationPointerGet function 5-1782 PLIB_DMA_ChannelXDestinationSizeGet function 5-1782 PLIB_DMA_ChannelXDestinationSizeSet function 5-1783 PLIB_DMA_ChannelXDestinationStartAddressGet function 5-1774 PLIB_DMA_ChannelXDestinationStartAddressSet function 5-1774 PLIB_DMA_ChannelXDisable function 5-1793 PLIB_DMA_ChannelXDisabledDisablesEvents function 5-1796 PLIB_DMA_ChannelXDisabledEnablesEvents function 5-1797 PLIB_DMA_ChannelXEnable function 5-1793 9 MPLAB Harmony Help ss PLIB_DMA_ChannelXEventIsDetected function 5-1818 PLIB_DMA_ChannelXINTSourceDisable function 5-1763 PLIB_DMA_ChannelXINTSourceEnable function 5-1763 PLIB_DMA_ChannelXINTSourceFlagClear function 5-1764 PLIB_DMA_ChannelXINTSourceFlagGet function 5-1764 PLIB_DMA_ChannelXINTSourceFlagSet function 5-1765 PLIB_DMA_ChannelXINTSourceIsEnabled function 5-1766 PLIB_DMA_ChannelXIsEnabled function 5-1819 PLIB_DMA_ChannelXNullWriteModeDisable function 5-1769 PLIB_DMA_ChannelXNullWriteModeEnable function 5-1769 PLIB_DMA_ChannelXNullWriteModeIsEnabled function 5-1819 PLIB_DMA_ChannelXOperatingTransferModeGet function 5-1770 PLIB_DMA_ChannelXOperatingTransferModeSelect function 5-1770 PLIB_DMA_ChannelXPatternDataGet function 5-1783 PLIB_DMA_ChannelXPatternDataSet function 5-1784 PLIB_DMA_ChannelXPatternIgnoreByteDisable function 5-1797 PLIB_DMA_ChannelXPatternIgnoreByteEnable function 5-1798 PLIB_DMA_ChannelXPatternIgnoreByteIsEnabled function 5-1798 PLIB_DMA_ChannelXPatternIgnoreGet function 5-1799 PLIB_DMA_ChannelXPatternIgnoreSet function 5-1799 PLIB_DMA_ChannelXPatternLengthGet function 5-1800 PLIB_DMA_ChannelXPatternLengthSet function 5-1801 PLIB_DMA_ChannelXPeripheralAddressGet function 5-1775 PLIB_DMA_ChannelXPeripheralAddressSet function 5-1775 PLIB_DMA_ChannelXPingPongModeGet function 5-1820 PLIB_DMA_ChannelXPriorityGet function 5-1794 PLIB_DMA_ChannelXPrioritySelect function 5-1794 PLIB_DMA_ChannelXReloadDisable function 5-1771 PLIB_DMA_ChannelXReloadEnable function 5-1771 PLIB_DMA_ChannelXReloadIsEnabled function 5-1773 PLIB_DMA_ChannelXSourceAddressModeGet function 5-1772 PLIB_DMA_ChannelXSourceAddressModeSelect function 5-1772 PLIB_DMA_ChannelXSourcePointerGet function 5-1785 PLIB_DMA_ChannelXSourceSizeGet function 5-1785 PLIB_DMA_ChannelXSourceSizeSet function 5-1786 PLIB_DMA_ChannelXSourceStartAddressGet function 5-1776 PLIB_DMA_ChannelXSourceStartAddressSet function 5-1777 PLIB_DMA_ChannelXStartAddressOffsetGet function 5-1777 PLIB_DMA_ChannelXStartAddressOffsetSet function 5-1778 PLIB_DMA_ChannelXStartIRQSet function 5-1760 PLIB_DMA_ChannelXTransferCountGet function 5-1786 PLIB_DMA_ChannelXTransferCountSet function 5-1787 PLIB_DMA_ChannelXTransferDirectionGet function 5-1795 PLIB_DMA_ChannelXTransferDirectionSelect function 5-1796 PLIB_DMA_ChannelXTriggerDisable function 5-1761 PLIB_DMA_ChannelXTriggerEnable function 5-1761 PLIB_DMA_ChannelXTriggerIsEnabled function 5-1762 PLIB_DMA_CRCAppendModeDisable function 5-1801 PLIB_DMA_CRCAppendModeEnable function 5-1802 PLIB_DMA_CRCAppendModeIsEnabled function 5-1802 PLIB_DMA_CRCBitOrderSelect function 5-1803 PLIB_DMA_CRCByteOrderGet function 5-1803 PLIB_DMA_CRCByteOrderSelect function 5-1804 PLIB_DMA_CRCChannelGet function 5-1804 PLIB_DMA_CRCChannelSelect function 5-1805 PLIB_DMA_CRCDataRead function 5-1805 PLIB_DMA_CRCDataWrite function 5-1806 PLIB_DMA_CRCDisable function 5-1806 PLIB_DMA_CRCEnable function 5-1807 PLIB_DMA_CRCIsEnabled function 5-1811 PLIB_DMA_CRCPolynomialLengthGet function 5-1807 PLIB_DMA_CRCPolynomialLengthSet function 5-1808 PLIB_DMA_CRCTypeGet function 5-1808 PLIB_DMA_CRCTypeSet function 5-1809 PLIB_DMA_CRCWriteByteOrderAlter function 5-1809 PLIB_DMA_CRCWriteByteOrderMaintain function 5-1810 PLIB_DMA_CRCXOREnableGet function 5-1810 PLIB_DMA_CRCXOREnableSet function 5-1810 PLIB_DMA_Disable function 5-1756 PLIB_DMA_Enable function 5-1756 PLIB_DMA_ExistsAbortTransfer function 5-1835 PLIB_DMA_ExistsBusy function 5-1835 PLIB_DMA_ExistsChannelBits function 5-1836 PLIB_DMA_ExistsChannelX function 5-1837 PLIB_DMA_ExistsChannelXAbortIRQ function 5-1837 PLIB_DMA_ExistsChannelXAuto function 5-1838 9 MPLAB Harmony Help tt PLIB_DMA_ExistsChannelXBusy function 5-1838 PLIB_DMA_ExistsChannelXCellProgressPointer function 5-1839 PLIB_DMA_ExistsChannelXCellSize function 5-1839 PLIB_DMA_ExistsChannelXChain function 5-1840 PLIB_DMA_ExistsChannelXChainEnbl function 5-1840 PLIB_DMA_ExistsChannelXDestinationPointer function 5-1841 PLIB_DMA_ExistsChannelXDestinationSize function 5-1841 PLIB_DMA_ExistsChannelXDestinationStartAddress function 5-1842 PLIB_DMA_ExistsChannelXDisabled function 5-1843 PLIB_DMA_ExistsChannelXEvent function 5-1843 PLIB_DMA_ExistsChannelXINTSource function 5-1844 PLIB_DMA_ExistsChannelXINTSourceFlag function 5-1844 PLIB_DMA_ExistsChannelXPatternData function 5-1845 PLIB_DMA_ExistsChannelXPatternIgnore function 5-1845 PLIB_DMA_ExistsChannelXPatternIgnoreByte function 5-1846 PLIB_DMA_ExistsChannelXPatternLength function 5-1846 PLIB_DMA_ExistsChannelXPriority function 5-1847 PLIB_DMA_ExistsChannelXSourcePointer function 5-1847 PLIB_DMA_ExistsChannelXSourceSize function 5-1848 PLIB_DMA_ExistsChannelXSourceStartAddress function 5-1848 PLIB_DMA_ExistsChannelXStartIRQ function 5-1849 PLIB_DMA_ExistsChannelXTrigger function 5-1849 PLIB_DMA_ExistsCRC function 5-1850 PLIB_DMA_ExistsCRCAppendMode function 5-1850 PLIB_DMA_ExistsCRCBitOrder function 5-1851 PLIB_DMA_ExistsCRCByteOrder function 5-1852 PLIB_DMA_ExistsCRCChannel function 5-1852 PLIB_DMA_ExistsCRCData function 5-1853 PLIB_DMA_ExistsCRCPolynomialLength function 5-1853 PLIB_DMA_ExistsCRCType function 5-1854 PLIB_DMA_ExistsCRCWriteByteOrder function 5-1854 PLIB_DMA_ExistsCRCXOREnable function 5-1855 PLIB_DMA_ExistsEnableControl function 5-1855 PLIB_DMA_ExistsLastBusAccess function 5-1856 PLIB_DMA_ExistsRecentAddress function 5-1856 PLIB_DMA_ExistsStartTransfer function 5-1857 PLIB_DMA_ExistsStopInIdle function 5-1857 PLIB_DMA_ExistsSuspend function 5-1858 PLIB_DMA_IsBusy function 5-1812 PLIB_DMA_IsEnabled function 5-1812 PLIB_DMA_LastBusAccessIsRead function 5-1813 PLIB_DMA_LastBusAccessIsWrite function 5-1813 PLIB_DMA_LastChannelActive function 5-1814 PLIB_DMA_RecentAddressAccessed function 5-1814 PLIB_DMA_StartTransferSet function 5-1759 PLIB_DMA_StopInIdleDisable function 5-1756 PLIB_DMA_StopInIdleEnable function 5-1757 PLIB_DMA_SuspendDisable function 5-1757 PLIB_DMA_SuspendEnable function 5-1758 PLIB_DMA_SuspendIsEnabled function 5-1814 plib_ebi.h 5-1900 PLIB_EBI_AddressHoldTimeGet function 5-1869 PLIB_EBI_AddressPinEnableBitsSet function 5-1876 PLIB_EBI_AddressSetupTimeGet function 5-1870 PLIB_EBI_BaseAddressGet function 5-1870 PLIB_EBI_BaseAddressSet function 5-1876 PLIB_EBI_ByteSelectPinSet function 5-1877 PLIB_EBI_ChipSelectEnableSet function 5-1878 PLIB_EBI_ControlEnableClear function 5-1869 PLIB_EBI_ControlEnableGet function 5-1870 PLIB_EBI_ControlEnableSet function 5-1886 PLIB_EBI_DataEnableSet function 5-1878 PLIB_EBI_DataTurnAroundTimeGet function 5-1871 PLIB_EBI_ExistsAddressHoldTime function 5-1887 PLIB_EBI_ExistsAddressPinEnableBits function 5-1887 PLIB_EBI_ExistsAddressSetupTime function 5-1888 PLIB_EBI_ExistsBaseAddress function 5-1888 PLIB_EBI_ExistsByteSelectPin function 5-1889 PLIB_EBI_ExistsChipSelectEnable function 5-1889 PLIB_EBI_ExistsControlEnable function 5-1890 PLIB_EBI_ExistsDataEnable function 5-1890 PLIB_EBI_ExistsDataTurnAroundTime function 5-1891 PLIB_EBI_ExistsFlashPowerDownMode function 5-1891 PLIB_EBI_ExistsFlashResetPin function 5-1892 PLIB_EBI_ExistsFlashTiming function 5-1892 PLIB_EBI_ExistsMemoryCharacteristics function 5-1893 PLIB_EBI_ExistsMemoryPaging function 5-1893 9 MPLAB Harmony Help uu PLIB_EBI_ExistsMemoryTimingConfig function 5-1894 PLIB_EBI_ExistsPageMode function 5-1894 PLIB_EBI_ExistsPageReadTime function 5-1895 PLIB_EBI_ExistsReadCycleTime function 5-1895 PLIB_EBI_ExistsReadyMode function 5-1896 PLIB_EBI_ExistsReadyPin1Config function 5-1896 PLIB_EBI_ExistsReadyPin2Config function 5-1897 PLIB_EBI_ExistsReadyPin3Config function 5-1897 PLIB_EBI_ExistsReadyPinSens function 5-1898 PLIB_EBI_ExistsStaticMemoryWidthRegister function 5-1898 PLIB_EBI_ExistsWriteOutputControl function 5-1899 PLIB_EBI_ExistsWritePulseWidth function 5-1899 PLIB_EBI_FlashPowerDownModeGet function 5-1871 PLIB_EBI_FlashPowerDownModeSet function 5-1879 PLIB_EBI_FlashResetPinGet function 5-1872 PLIB_EBI_FlashResetPinSet function 5-1879 PLIB_EBI_FlashTimingGet function 5-1872 PLIB_EBI_FlashTimingSet function 5-1880 PLIB_EBI_MemoryCharacteristicsSet function 5-1880 PLIB_EBI_MemoryPagingSet function 5-1881 PLIB_EBI_MemoryTimingConfigSet function 5-1882 PLIB_EBI_PageModeGet function 5-1873 PLIB_EBI_PageReadCycleTimeGet function 5-1873 PLIB_EBI_PageSizeGet function 5-1873 PLIB_EBI_ReadCycleTimeGet function 5-1874 PLIB_EBI_ReadyModeGet function 5-1874 PLIB_EBI_ReadyModeSet function 5-1886 PLIB_EBI_ReadyPin1ConfigSet function 5-1882 PLIB_EBI_ReadyPin2ConfigSet function 5-1883 PLIB_EBI_ReadyPin3ConfigSet function 5-1884 PLIB_EBI_ReadyPinSensSet function 5-1884 PLIB_EBI_StaticMemoryWidthRegisterGet function 5-1875 PLIB_EBI_StaticMemoryWidthRegisterSet function 5-1885 PLIB_EBI_WriteOutputControlSet function 5-1885 PLIB_EBI_WritePulseWidthGet function 5-1875 plib_eth.h 5-2052 PLIB_ETH_AlignErrorCountClear function 5-2019 PLIB_ETH_AlignErrorCountGet function 5-2019 PLIB_ETH_AutoDetectPadClear function 5-1929 PLIB_ETH_AutoDetectPadGet function 5-1929 PLIB_ETH_AutoDetectPadSet function 5-1930 PLIB_ETH_AutoFlowControlDisable function 5-1998 PLIB_ETH_AutoFlowControlEnable function 5-1999 PLIB_ETH_AutoFlowControlIsEnabled function 5-1999 PLIB_ETH_BackPresNoBackoffDisable function 5-2000 PLIB_ETH_BackPresNoBackoffEnable function 5-2000 PLIB_ETH_BackPresNoBackoffIsEnabled function 5-2001 PLIB_ETH_BackToBackIPGGet function 5-1930 PLIB_ETH_BackToBackIPGSet function 5-1931 PLIB_ETH_CollisionWindowGet function 5-1932 PLIB_ETH_CollisionWindowSet function 5-1932 PLIB_ETH_CRCDisable function 5-1982 PLIB_ETH_CRCEnable function 5-1983 PLIB_ETH_CRCIsEnabled function 5-1983 PLIB_ETH_DataNotValid function 5-1984 PLIB_ETH_DelayedCRCDisable function 5-1933 PLIB_ETH_DelayedCRCEnable function 5-1933 PLIB_ETH_DelayedCRCIsEnabled function 5-1934 PLIB_ETH_Disable function 5-1934 PLIB_ETH_Enable function 5-1935 PLIB_ETH_EthernetIsBusy function 5-1984 PLIB_ETH_ExcessDeferDisable function 5-1935 PLIB_ETH_ExcessDeferEnable function 5-1936 PLIB_ETH_ExcessDeferIsEnabled function 5-1936 PLIB_ETH_ExistsAlignmentErrorCount function 5-2026 PLIB_ETH_ExistsAutoFlowControl function 5-2027 PLIB_ETH_ExistsCollisionCounts function 5-2028 PLIB_ETH_ExistsCollisionWindow function 5-2028 PLIB_ETH_ExistsEnable function 5-2029 PLIB_ETH_ExistsEthernetControllerStatus function 5-2029 PLIB_ETH_ExistsFCSErrorCount function 5-2030 PLIB_ETH_ExistsFramesTransmittedOK function 5-2030 PLIB_ETH_ExistsFramexReceivedOK function 5-2031 PLIB_ETH_ExistsHashTable function 5-2031 PLIB_ETH_ExistsInterPacketGaps function 5-2032 PLIB_ETH_ExistsInterrupt function 5-2033 PLIB_ETH_ExistsMAC_Configuration function 5-2033 PLIB_ETH_ExistsMAC_Resets function 5-2035 9 MPLAB Harmony Help vv PLIB_ETH_ExistsMAC_Testing function 5-2036 PLIB_ETH_ExistsManualFlowControl function 5-2037 PLIB_ETH_ExistsMaxFrameLength function 5-2037 PLIB_ETH_ExistsMIIM_Config function 5-2038 PLIB_ETH_ExistsMIIM_Indicators function 5-2038 PLIB_ETH_ExistsMIIMAddresses function 5-2039 PLIB_ETH_ExistsMIIMReadWrite function 5-2040 PLIB_ETH_ExistsMIIMScanMode function 5-2040 PLIB_ETH_ExistsMIIWriteReadData function 5-2041 PLIB_ETH_ExistsPatternMatch function 5-2041 PLIB_ETH_ExistsPauseTimer function 5-2042 PLIB_ETH_ExistsReceiveBufferSize function 5-2042 PLIB_ETH_ExistsReceiveFilters function 5-2043 PLIB_ETH_ExistsReceiveOverflowCount function 5-2043 PLIB_ETH_ExistsReceiveWmarks function 5-2044 PLIB_ETH_ExistsRetransmissionMaximum function 5-2045 PLIB_ETH_ExistsRMII_Support function 5-2045 PLIB_ETH_ExistsRxBufferCountDecrement function 5-2046 PLIB_ETH_ExistsRxEnable function 5-2046 PLIB_ETH_ExistsRxPacketDescriptorAddress function 5-2047 PLIB_ETH_ExistsStationAddress function 5-2047 PLIB_ETH_ExistsStopInIdle function 5-2048 PLIB_ETH_ExistsTransmitRTS function 5-2048 PLIB_ETH_ExistsTxPacketDescriptorAddress function 5-2049 PLIB_ETH_FCSErrorCountClear function 5-2020 PLIB_ETH_FCSErrorCountGet function 5-2020 PLIB_ETH_FrameLengthCheckDisable function 5-1937 PLIB_ETH_FrameLengthCheckEnable function 5-1937 PLIB_ETH_FrameLengthCheckIsEnabled function 5-1938 PLIB_ETH_FramesRxdOkCountClear function 5-2021 PLIB_ETH_FramesRxdOkCountGet function 5-2021 PLIB_ETH_FramesTxdOkCountClear function 5-2022 PLIB_ETH_FramesTxdOkCountGet function 5-2022 PLIB_ETH_FullDuplexDisable function 5-1938 PLIB_ETH_FullDuplexEnable function 5-1939 PLIB_ETH_FullDuplexIsEnabled function 5-1939 PLIB_ETH_HashTableGet function 5-1987 PLIB_ETH_HashTableSet function 5-1988 PLIB_ETH_HugeFrameDisable function 5-1940 PLIB_ETH_HugeFrameEnable function 5-1940 PLIB_ETH_HugeFrameIsEnabled function 5-1941 PLIB_ETH_InterruptClear function 5-2014 PLIB_ETH_InterruptSet function 5-2015 PLIB_ETH_InterruptsGet function 5-2015 PLIB_ETH_InterruptSourceDisable function 5-2016 PLIB_ETH_InterruptSourceEnable function 5-2016 PLIB_ETH_InterruptSourceIsEnabled function 5-2017 PLIB_ETH_InterruptSourcesGet function 5-2018 PLIB_ETH_InterruptStatusGet function 5-2018 PLIB_ETH_IsEnabled function 5-1941 PLIB_ETH_LinkHasFailed function 5-1985 PLIB_ETH_LongPreambleDisable function 5-1942 PLIB_ETH_LongPreambleEnable function 5-1942 PLIB_ETH_LongPreambleIsEnabled function 5-1943 PLIB_ETH_LoopbackDisable function 5-1943 PLIB_ETH_LoopbackEnable function 5-1944 PLIB_ETH_LoopbackIsEnabled function 5-1944 PLIB_ETH_ManualFlowControlDisable function 5-2001 PLIB_ETH_ManualFlowControlEnable function 5-2002 PLIB_ETH_ManualFlowControlIsEnabled function 5-2002 PLIB_ETH_MaxFrameLengthGet function 5-1945 PLIB_ETH_MaxFrameLengthSet function 5-1945 PLIB_ETH_MCSRxResetDisable function 5-1957 PLIB_ETH_MCSRxResetEnable function 5-1958 PLIB_ETH_MCSRxResetIsEnabled function 5-1958 PLIB_ETH_MCSTxResetDisable function 5-1959 PLIB_ETH_MCSTxResetEnable function 5-1959 PLIB_ETH_MCSTxResetIsEnabled function 5-1960 PLIB_ETH_MIIMClockGet function 5-1946 PLIB_ETH_MIIMClockSet function 5-1946 PLIB_ETH_MIIMIsBusy function 5-1985 PLIB_ETH_MIIMIsScanning function 5-1986 PLIB_ETH_MIIMNoPreDisable function 5-1947 PLIB_ETH_MIIMNoPreEnable function 5-1947 PLIB_ETH_MIIMNoPreIsEnabled function 5-1948 PLIB_ETH_MIIMReadDataGet function 5-1960 PLIB_ETH_MIIMReadStart function 5-1961 PLIB_ETH_MIIMResetDisable function 5-1961 9 MPLAB Harmony Help ww PLIB_ETH_MIIMResetEnable function 5-1962 PLIB_ETH_MIIMResetIsEnabled function 5-1962 PLIB_ETH_MIIMScanIncrDisable function 5-1963 PLIB_ETH_MIIMScanIncrEnable function 5-1963 PLIB_ETH_MIIMScanIncrIsEnabled function 5-1964 PLIB_ETH_MIIMScanModeDisable function 5-1964 PLIB_ETH_MIIMScanModeEnable function 5-1965 PLIB_ETH_MIIMScanModeIsEnabled function 5-1965 PLIB_ETH_MIIMWriteDataSet function 5-1966 PLIB_ETH_MIIMWriteStart function 5-1966 PLIB_ETH_MIIResetDisable function 5-1967 PLIB_ETH_MIIResetEnable function 5-1968 PLIB_ETH_MIIResetIsEnabled function 5-1968 PLIB_ETH_MultipleCollisionCountClear function 5-2023 PLIB_ETH_MultipleCollisionCountGet function 5-2023 PLIB_ETH_NoBackoffDisable function 5-2003 PLIB_ETH_NoBackoffEnable function 5-2003 PLIB_ETH_NoBackoffIsEnabled function 5-2004 PLIB_ETH_NonBackToBackIPG1Get function 5-1948 PLIB_ETH_NonBackToBackIPG1Set function 5-1949 PLIB_ETH_NonBackToBackIPG2Get function 5-1949 PLIB_ETH_NonBackToBackIPG2Set function 5-1950 PLIB_ETH_PassAllDisable function 5-1988 PLIB_ETH_PassAllEnable function 5-1989 PLIB_ETH_PassAllIsEnabled function 5-1989 PLIB_ETH_PatternMatchChecksumGet function 5-1990 PLIB_ETH_PatternMatchChecksumSet function 5-1990 PLIB_ETH_PatternMatchGet function 5-1991 PLIB_ETH_PatternMatchModeGet function 5-1991 PLIB_ETH_PatternMatchModeSet function 5-1992 PLIB_ETH_PatternMatchOffsetGet function 5-1992 PLIB_ETH_PatternMatchOffsetSet function 5-1993 PLIB_ETH_PatternMatchSet function 5-1993 PLIB_ETH_PauseTimerGet function 5-1950 PLIB_ETH_PauseTimerSet function 5-1951 PLIB_ETH_PHYAddressGet function 5-1969 PLIB_ETH_PHYAddressSet function 5-1969 PLIB_ETH_PurePreambleDisable function 5-1994 PLIB_ETH_PurePreambleEnable function 5-1994 PLIB_ETH_PurePreambleIsEnabled function 5-1995 PLIB_ETH_ReceiveBufferSizeGet function 5-1951 PLIB_ETH_ReceiveBufferSizeSet function 5-1952 PLIB_ETH_ReceiveDisable function 5-1952 PLIB_ETH_ReceiveEnable function 5-1953 PLIB_ETH_ReceiveFilterDisable function 5-1995 PLIB_ETH_ReceiveFilterEnable function 5-1996 PLIB_ETH_ReceiveFilterIsEnable function 5-1997 PLIB_ETH_ReceiveIsBusy function 5-1986 PLIB_ETH_ReceiveIsEnabled function 5-1953 PLIB_ETH_RegisterAddressGet function 5-1970 PLIB_ETH_RegisterAddressSet function 5-1970 PLIB_ETH_ReTxMaxGet function 5-1954 PLIB_ETH_ReTxMaxSet function 5-1954 PLIB_ETH_RMIIResetDisable function 5-1971 PLIB_ETH_RMIIResetEnable function 5-1971 PLIB_ETH_RMIIResetIsEnabled function 5-1972 PLIB_ETH_RMIISpeedGet function 5-1955 PLIB_ETH_RMIISpeedSet function 5-1955 PLIB_ETH_RxBufferCountDecrement function 5-1972 PLIB_ETH_RxDisable function 5-1973 PLIB_ETH_RxEmptyWmarkGet function 5-2004 PLIB_ETH_RxEmptyWmarkSet function 5-2005 PLIB_ETH_RxEnable function 5-1973 PLIB_ETH_RxFullWmarkGet function 5-2006 PLIB_ETH_RxFullWmarkSet function 5-2006 PLIB_ETH_RxFuncResetDisable function 5-1974 PLIB_ETH_RxFuncResetEnable function 5-1974 PLIB_ETH_RxFuncResetIsEnabled function 5-1975 PLIB_ETH_RxIsEnabled function 5-1975 PLIB_ETH_RxOverflowCountClear function 5-2024 PLIB_ETH_RxOverflowCountGet function 5-2024 PLIB_ETH_RxPacketCountGet function 5-2025 PLIB_ETH_RxPacketDescAddrGet function 5-1976 PLIB_ETH_RxPacketDescAddrSet function 5-1976 PLIB_ETH_RxPauseDisable function 5-2007 PLIB_ETH_RxPauseEnable function 5-2007 PLIB_ETH_RxPauseIsEnabled function 5-2008 PLIB_ETH_ShortcutQuantaDisable function 5-2008 9 MPLAB Harmony Help xx PLIB_ETH_ShortcutQuantaEnable function 5-2009 PLIB_ETH_ShortcutQuantaIsEnabled function 5-2009 PLIB_ETH_SimResetDisable function 5-2010 PLIB_ETH_SimResetEnable function 5-2010 PLIB_ETH_SimResetIsEnabled function 5-2011 PLIB_ETH_SingleCollisionCountClear function 5-2025 PLIB_ETH_SingleCollisionCountGet function 5-2026 PLIB_ETH_StationAddressGet function 5-1997 PLIB_ETH_StationAddressSet function 5-1998 PLIB_ETH_StopInIdleDisable function 5-1956 PLIB_ETH_StopInIdleEnable function 5-1956 PLIB_ETH_StopInIdleIsEnabled function 5-1957 PLIB_ETH_TestBackPressDisable function 5-2011 PLIB_ETH_TestBackPressEnable function 5-2012 PLIB_ETH_TestBackPressIsEnabled function 5-2012 PLIB_ETH_TestPauseDisable function 5-1977 PLIB_ETH_TestPauseEnable function 5-1977 PLIB_ETH_TestPauseIsEnabled function 5-1978 PLIB_ETH_TransmitIsBusy function 5-1987 PLIB_ETH_TxFuncResetDisable function 5-1978 PLIB_ETH_TxFuncResetEnable function 5-1979 PLIB_ETH_TxFuncResetIsEnabled function 5-1979 PLIB_ETH_TxPacketDescAddrGet function 5-1980 PLIB_ETH_TxPacketDescAddrSet function 5-1980 PLIB_ETH_TxPauseDisable function 5-2013 PLIB_ETH_TxPauseEnable function 5-2013 PLIB_ETH_TxPauseIsEnabled function 5-2014 PLIB_ETH_TxRTSDisable function 5-1981 PLIB_ETH_TxRTSEnable function 5-1981 PLIB_ETH_TxRTSIsEnabled function 5-1982 plib_i2c.h 5-2166 PLIB_I2C_AcksequenceIsInProgress function 5-2122 PLIB_I2C_ArbitrationLossClear function 5-2103 PLIB_I2C_ArbitrationLossHasOccurred function 5-2104 PLIB_I2C_BaudRateGet function 5-2109 PLIB_I2C_BaudRateSet function 5-2109 PLIB_I2C_BusIsIdle function 5-2105 PLIB_I2C_DataLineHoldTimeSet function 5-2123 PLIB_I2C_Disable function 5-2093 PLIB_I2C_Enable function 5-2094 PLIB_I2C_ExistsAcksequenceProgress function 5-2144 PLIB_I2C_ExistsArbitrationLoss function 5-2144 PLIB_I2C_ExistsBaudRate function 5-2145 PLIB_I2C_ExistsBusIsIdle function 5-2146 PLIB_I2C_ExistsClockStretching function 5-2146 PLIB_I2C_ExistsDataLineHoldTime function 5-2147 PLIB_I2C_ExistsGeneralCall function 5-2147 PLIB_I2C_ExistsGeneralCallAddressDetect function 5-2148 PLIB_I2C_ExistsHighFrequency function 5-2148 PLIB_I2C_ExistsIPMI function 5-2149 PLIB_I2C_ExistsMasterReceiverClock1Byte function 5-2149 PLIB_I2C_ExistsMasterStart function 5-2150 PLIB_I2C_ExistsMasterStartRepeat function 5-2150 PLIB_I2C_ExistsMasterStop function 5-2151 PLIB_I2C_ExistsModuleEnable function 5-2151 PLIB_I2C_ExistsReceivedByteAcknowledge function 5-2152 PLIB_I2C_ExistsReceivedByteAvailable function 5-2152 PLIB_I2C_ExistsReceivedByteGet function 5-2153 PLIB_I2C_ExistsReceiverOverflow function 5-2153 PLIB_I2C_ExistsReservedAddressProtect function 5-2154 PLIB_I2C_ExistsSlaveAddress10Bit function 5-2154 PLIB_I2C_ExistsSlaveAddress7Bit function 5-2155 PLIB_I2C_ExistsSlaveAddressDetect function 5-2155 PLIB_I2C_ExistsSlaveAddressHoldEnable function 5-2156 PLIB_I2C_ExistsSlaveBufferOverwrite function 5-2156 PLIB_I2C_ExistsSlaveBusCollisionDetect function 5-2157 PLIB_I2C_ExistsSlaveClockHold function 5-2157 PLIB_I2C_ExistsSlaveDataDetect function 5-2158 PLIB_I2C_ExistsSlaveInterruptOnStart function 5-2158 PLIB_I2C_ExistsSlaveInterruptOnStop function 5-2159 PLIB_I2C_ExistsSlaveMask function 5-2160 PLIB_I2C_ExistsSlaveReadRequest function 5-2160 PLIB_I2C_ExistsSMBus function 5-2161 PLIB_I2C_ExistsStartDetect function 5-2161 PLIB_I2C_ExistsStopDetect function 5-2162 PLIB_I2C_ExistsStopInIdle function 5-2162 PLIB_I2C_ExistsTransmitterByteAcknowledge function 5-2163 PLIB_I2C_ExistsTransmitterByteComplete function 5-2163 9 MPLAB Harmony Help yy PLIB_I2C_ExistsTransmitterByteSend function 5-2164 PLIB_I2C_ExistsTransmitterIsBusy function 5-2164 PLIB_I2C_ExistsTransmitterOverflow function 5-2165 PLIB_I2C_GeneralCallDisable function 5-2094 PLIB_I2C_GeneralCallEnable function 5-2095 PLIB_I2C_HighFrequencyDisable function 5-2096 PLIB_I2C_HighFrequencyEnable function 5-2096 PLIB_I2C_IPMIDisable function 5-2097 PLIB_I2C_IPMIEnable function 5-2098 PLIB_I2C_MasterReceiverClock1Byte function 5-2131 PLIB_I2C_MasterReceiverReadyToAcknowledge function 5-2143 PLIB_I2C_MasterStart function 5-2132 PLIB_I2C_MasterStartRepeat function 5-2132 PLIB_I2C_MasterStop function 5-2133 PLIB_I2C_ReceivedByteAcknowledge function 5-2139 PLIB_I2C_ReceivedByteGet function 5-2140 PLIB_I2C_ReceivedByteIsAvailable function 5-2140 PLIB_I2C_ReceiverByteAcknowledgeHasCompleted function 5-2141 PLIB_I2C_ReceiverOverflowClear function 5-2142 PLIB_I2C_ReceiverOverflowHasOccurred function 5-2142 PLIB_I2C_ReservedAddressProtectDisable function 5-2098 PLIB_I2C_ReservedAddressProtectEnable function 5-2099 PLIB_I2C_SlaveAddress10BitGet function 5-2110 PLIB_I2C_SlaveAddress10BitSet function 5-2111 PLIB_I2C_SlaveAddress10BitWasDetected function 5-2112 PLIB_I2C_SlaveAddress7BitGet function 5-2112 PLIB_I2C_SlaveAddress7BitSet function 5-2113 PLIB_I2C_SlaveAddressHoldDisable function 5-2114 PLIB_I2C_SlaveAddressHoldEnable function 5-2114 PLIB_I2C_SlaveAddressIsDetected function 5-2115 PLIB_I2C_SlaveAddressIsGeneralCall function 5-2116 PLIB_I2C_SlaveAddressModeIs10Bits function 5-2117 PLIB_I2C_SlaveBufferOverwriteDisable function 5-2124 PLIB_I2C_SlaveBufferOverwriteEnable function 5-2124 PLIB_I2C_SlaveBusCollisionDetectDisable function 5-2125 PLIB_I2C_SlaveBusCollisionDetectEnable function 5-2125 PLIB_I2C_SlaveClockHold function 5-2126 PLIB_I2C_SlaveClockRelease function 5-2127 PLIB_I2C_SlaveClockStretchingDisable function 5-2099 PLIB_I2C_SlaveClockStretchingEnable function 5-2100 PLIB_I2C_SlaveDataHoldDisable function 5-2127 PLIB_I2C_SlaveDataHoldEnable function 5-2128 PLIB_I2C_SlaveDataIsDetected function 5-2117 PLIB_I2C_SlaveInterruptOnStartDisable function 5-2129 PLIB_I2C_SlaveInterruptOnStartEnable function 5-2129 PLIB_I2C_SlaveInterruptOnStopDisable function 5-2130 PLIB_I2C_SlaveInterruptOnStopEnable function 5-2130 PLIB_I2C_SlaveMask10BitGet function 5-2119 PLIB_I2C_SlaveMask10BitSet function 5-2120 PLIB_I2C_SlaveMask7BitGet function 5-2121 PLIB_I2C_SlaveMask7BitSet function 5-2121 PLIB_I2C_SlaveReadIsRequested function 5-2118 PLIB_I2C_SMBDisable function 5-2101 PLIB_I2C_SMBEnable function 5-2101 PLIB_I2C_StartClear function 5-2106 PLIB_I2C_StartWasDetected function 5-2106 PLIB_I2C_StopClear function 5-2107 PLIB_I2C_StopInIdleDisable function 5-2102 PLIB_I2C_StopInIdleEnable function 5-2103 PLIB_I2C_StopWasDetected function 5-2108 PLIB_I2C_TransmitterByteHasCompleted function 5-2134 PLIB_I2C_TransmitterByteSend function 5-2134 PLIB_I2C_TransmitterByteWasAcknowledged function 5-2135 PLIB_I2C_TransmitterIsBusy function 5-2136 PLIB_I2C_TransmitterIsReady function 5-2137 PLIB_I2C_TransmitterOverflowClear function 5-2138 PLIB_I2C_TransmitterOverflowHasOccurred function 5-2138 plib_ic.h 5-2201 PLIB_IC_AlternateClockDisable function 5-2182 PLIB_IC_AlternateClockEnable function 5-2183 PLIB_IC_Buffer16BitGet function 5-2183 PLIB_IC_Buffer32BitGet function 5-2184 PLIB_IC_BufferIsEmpty function 5-2184 PLIB_IC_BufferOverflowHasOccurred function 5-2185 PLIB_IC_BufferSizeSelect function 5-2185 PLIB_IC_ClockSourceSelect function 5-2179 PLIB_IC_Disable function 5-2177 9 MPLAB Harmony Help zz PLIB_IC_Enable function 5-2177 PLIB_IC_EventsPerInterruptSelect function 5-2178 PLIB_IC_ExistsAlternateClock function 5-2193 PLIB_IC_ExistsBufferIsEmptyStatus function 5-2193 PLIB_IC_ExistsBufferOverflowStatus function 5-2194 PLIB_IC_ExistsBufferSize function 5-2194 PLIB_IC_ExistsBufferValue function 5-2195 PLIB_IC_ExistsCaptureMode function 5-2195 PLIB_IC_ExistsClockSource function 5-2196 PLIB_IC_ExistsEdgeCapture function 5-2196 PLIB_IC_ExistsEnable function 5-2197 PLIB_IC_ExistsEventsPerInterruptSelect function 5-2197 PLIB_IC_ExistsStopInIdle function 5-2198 PLIB_IC_ExistsSyncMode function 5-2198 PLIB_IC_ExistsSyncModeInput function 5-2199 PLIB_IC_ExistsTimerSelect function 5-2199 PLIB_IC_ExistsTimerTriggered function 5-2200 PLIB_IC_FirstCaptureEdgeSelect function 5-2179 PLIB_IC_ModeSelect function 5-2186 PLIB_IC_StopInIdleDisable function 5-2187 PLIB_IC_StopInIdleEnable function 5-2187 PLIB_IC_SyncModeInputSelect function 5-2180 PLIB_IC_SyncModeSelect function 5-2180 PLIB_IC_TimerIsTriggered function 5-2181 PLIB_IC_TimerSelect function 5-2181 plib_int.h 5-2250 PLIB_INT_AlternateVectorTableSelect function 5-2208 PLIB_INT_CPUCurrentPriorityLevelGet function 5-2228 PLIB_INT_Disable function 5-2209 PLIB_INT_DISIStatusGet function 5-2209 PLIB_INT_Enable function 5-2210 PLIB_INT_ExistsAlternateVectorTable function 5-2240 PLIB_INT_ExistsCPUCurrentPriorityLevel function 5-2240 PLIB_INT_ExistsEnableControl function 5-2241 PLIB_INT_ExistsExternalINTEdgeSelect function 5-2241 PLIB_INT_ExistsHighPriority function 5-2242 PLIB_INT_ExistsINTCPUPriority function 5-2242 PLIB_INT_ExistsINTCPUVector function 5-2243 PLIB_INT_ExistsINTNesting function 5-2243 PLIB_INT_ExistsLowPriority function 5-2244 PLIB_INT_ExistsPeripheralControl function 5-2244 PLIB_INT_ExistsPriority function 5-2245 PLIB_INT_ExistsProximityTimerControl function 5-2245 PLIB_INT_ExistsProximityTimerEnable function 5-2246 PLIB_INT_ExistsSingleVectorShadowSet function 5-2246 PLIB_INT_ExistsSourceControl function 5-2247 PLIB_INT_ExistsSourceFlag function 5-2247 PLIB_INT_ExistsTrapSource function 5-2248 PLIB_INT_ExistsVectorPriority function 5-2248 PLIB_INT_ExistsVectorSelect function 5-2249 PLIB_INT_ExternalFallingEdgeSelect function 5-2210 PLIB_INT_ExternalRisingEdgeSelect function 5-2211 PLIB_INT_IsEnabled function 5-2211 PLIB_INT_MultiVectorSelect function 5-2212 PLIB_INT_NestingDisable function 5-2213 PLIB_INT_NestingEnable function 5-2213 PLIB_INT_PeripheralsDisable function 5-2214 PLIB_INT_PeripheralsEnable function 5-2214 PLIB_INT_PriorityDisable function 5-2214 PLIB_INT_PriorityEnable function 5-2215 PLIB_INT_PriorityGet function 5-2216 PLIB_INT_PriorityHighDisable function 5-2216 PLIB_INT_PriorityHighEnable function 5-2217 PLIB_INT_PriorityLowDisable function 5-2217 PLIB_INT_PriorityLowEnable function 5-2218 PLIB_INT_ProximityTimerDisable function 5-2218 PLIB_INT_ProximityTimerEnable function 5-2219 PLIB_INT_ProximityTimerGet function 5-2229 PLIB_INT_ProximityTimerSet function 5-2230 PLIB_INT_SingleVectorSelect function 5-2219 PLIB_INT_SingleVectorShadowSetDisable function 5-2220 PLIB_INT_SingleVectorShadowSetEnable function 5-2220 PLIB_INT_SourceDisable function 5-2221 PLIB_INT_SourceEnable function 5-2222 PLIB_INT_SourceFlagClear function 5-2223 PLIB_INT_SourceFlagGet function 5-2224 PLIB_INT_SourceFlagSet function 5-2225 PLIB_INT_SourceIsEnabled function 5-2225 9 MPLAB Harmony Help aaa PLIB_INT_StandardVectorTableSelect function 5-2221 PLIB_INT_TrapSourceFlagClear function 5-2230 PLIB_INT_TrapSourceFlagGet function 5-2231 PLIB_INT_VectorGet function 5-2232 PLIB_INT_VectorPriorityGet function 5-2226 PLIB_INT_VectorPrioritySet function 5-2227 PLIB_INT_VectorSubPriorityGet function 5-2227 PLIB_INT_VectorSubPrioritySet function 5-2228 plib_nvm.h 5-2285 PLIB_NVM_BootPageWriteProtectionDisable function 5-2271 PLIB_NVM_BootPageWriteProtectionEnable function 5-2271 PLIB_NVM_DataBlockSourceAddress function 5-2263 PLIB_NVM_ExistsAccessEnable function 5-2274 PLIB_NVM_ExistsAddressModifyControl function 5-2275 PLIB_NVM_ExistsBootPageWriteProtect function 5-2275 PLIB_NVM_ExistsEEPROMReadInitiate function 5-2276 PLIB_NVM_ExistsFlashBankRegionSelect function 5-2276 PLIB_NVM_ExistsFlashWPMemoryRangeProvide function 5-2277 PLIB_NVM_ExistsKeySequence function 5-2277 PLIB_NVM_ExistsLockBootSelect function 5-2278 PLIB_NVM_ExistsLockPFMSelect function 5-2278 PLIB_NVM_ExistsLowVoltageError function 5-2279 PLIB_NVM_ExistsLowVoltageStatus function 5-2279 PLIB_NVM_ExistsMemoryModificationControl function 5-2280 PLIB_NVM_ExistsOperationMode function 5-2280 PLIB_NVM_ExistsProgramEraseOperation function 5-2281 PLIB_NVM_ExistsProvideData function 5-2281 PLIB_NVM_ExistsProvideQuadData function 5-2282 PLIB_NVM_ExistsSourceAddress function 5-2282 PLIB_NVM_ExistsStopInIdle function 5-2283 PLIB_NVM_ExistsWriteErrorStatus function 5-2283 PLIB_NVM_ExistsWriteOperation function 5-2284 PLIB_NVM_FlashAccessEnable function 5-2263 PLIB_NVM_FlashAddressToModify function 5-2264 PLIB_NVM_FlashEraseOperationSelect function 5-2264 PLIB_NVM_FlashEraseStart function 5-2265 PLIB_NVM_FlashProvideData function 5-2265 PLIB_NVM_FlashProvideQuadData function 5-2266 PLIB_NVM_FlashRead function 5-2266 PLIB_NVM_FlashWriteCycleHasCompleted function 5-2267 PLIB_NVM_FlashWriteKeySequence function 5-2267 PLIB_NVM_FlashWriteOperationSelect function 5-2268 PLIB_NVM_FlashWriteProtectMemoryAreaRange function 5-2268 PLIB_NVM_FlashWriteStart function 5-2269 PLIB_NVM_IsBootMemoryLocked function 5-2272 PLIB_NVM_IsBootPageWriteProtected function 5-2272 PLIB_NVM_IsProgramFlashMemoryLocked function 5-2269 PLIB_NVM_LockBootMemory function 5-2273 PLIB_NVM_LockProgramFlashMemory function 5-2274 PLIB_NVM_LowVoltageEventIsActive function 5-2259 PLIB_NVM_LowVoltageIsDetected function 5-2259 PLIB_NVM_MemoryModifyEnable function 5-2260 PLIB_NVM_MemoryModifyInhibit function 5-2260 PLIB_NVM_MemoryOperationSelect function 5-2261 PLIB_NVM_ProgramFlashBank1LowerRegion function 5-2270 PLIB_NVM_ProgramFlashBank2LowerRegion function 5-2270 PLIB_NVM_StopInIdleDisable function 5-2261 PLIB_NVM_StopInIdleEnable function 5-2262 PLIB_NVM_WriteOperationHasTerminated function 5-2262 plib_oc.h 5-2328 PLIB_OC_AlternateClockDisable function 5-2306 PLIB_OC_AlternateClockEnable function 5-2307 PLIB_OC_Buffer16BitSet function 5-2299 PLIB_OC_Buffer32BitSet function 5-2299 PLIB_OC_BufferSizeSelect function 5-2300 PLIB_OC_Disable function 5-2296 PLIB_OC_Enable function 5-2297 PLIB_OC_ExistsAlternateClock function 5-2318 PLIB_OC_ExistsBufferSize function 5-2319 PLIB_OC_ExistsBufferValue function 5-2319 PLIB_OC_ExistsCompareModeSelect function 5-2320 PLIB_OC_ExistsEnableControl function 5-2320 PLIB_OC_ExistsFaultInput function 5-2321 PLIB_OC_ExistsFaultModeSelect function 5-2321 PLIB_OC_ExistsFaultOutSelect function 5-2322 PLIB_OC_ExistsFaultStatus function 5-2322 PLIB_OC_ExistsFaultTristateSelect function 5-2323 PLIB_OC_ExistsPolarityInvert function 5-2323 9 MPLAB Harmony Help bbb PLIB_OC_ExistsPulseWidth function 5-2324 PLIB_OC_ExistsPWMDutyCycleResolutionControl function 5-2324 PLIB_OC_ExistsStopInIdle function 5-2325 PLIB_OC_ExistsSyncModeSelect function 5-2325 PLIB_OC_ExistsSyncSourceSelect function 5-2326 PLIB_OC_ExistsTimerSelect function 5-2326 PLIB_OC_ExistsTimerTriggered function 5-2327 PLIB_OC_ExistsTriggerControl function 5-2327 PLIB_OC_ExistsTriggerStatusModeSelect function 5-2328 PLIB_OC_FaultHasOccurred function 5-2309 PLIB_OC_FaultInputSelect function 5-2309 PLIB_OC_FaultModeSelect function 5-2310 PLIB_OC_FaultOutSelect function 5-2310 PLIB_OC_FaultTristateSelect function 5-2311 PLIB_OC_IsTriggered function 5-2302 PLIB_OC_ModeSelect function 5-2297 PLIB_OC_PolarityInvertedDisable function 5-2298 PLIB_OC_PolarityInvertedEnable function 5-2298 PLIB_OC_PulseWidth16BitSet function 5-2301 PLIB_OC_PulseWidth32BitSet function 5-2301 PLIB_OC_PWMDutyCycleResolutionSet function 5-2302 PLIB_OC_StopInIdleDisable function 5-2307 PLIB_OC_StopInIdleEnable function 5-2308 PLIB_OC_SyncModeSelect function 5-2303 PLIB_OC_SyncSourceSelect function 5-2304 PLIB_OC_TimerSelect function 5-2304 PLIB_OC_TriggerClear function 5-2305 PLIB_OC_TriggerSet function 5-2305 PLIB_OC_TriggerStatusModeSelect function 5-2306 plib_osc.h 5-2423 PLIB_OSC_AuxClockSourceGet function 5-2347 PLIB_OSC_AuxClockSourceSet function 5-2347 PLIB_OSC_AuxModeGet function 5-2348 PLIB_OSC_AuxModeSelect function 5-2348 PLIB_OSC_ClockHasFailed function 5-2392 PLIB_OSC_ClockSwitchingAbort function 5-2365 PLIB_OSC_ClockSwitchingIsComplete function 5-2366 PLIB_OSC_CurrentSysClockGet function 5-2366 PLIB_OSC_DozeModeDisable function 5-2368 PLIB_OSC_DozeModeEnable function 5-2368 PLIB_OSC_DozeRatioGet function 5-2369 PLIB_OSC_DozeRatioSelect function 5-2369 PLIB_OSC_DozeRecoverOnInterruptDisable function 5-2370 PLIB_OSC_DozeRecoverOnInterruptEnable function 5-2370 PLIB_OSC_DozeRecoverOnInterruptIsEnabled function 5-2371 PLIB_OSC_ExistsClockFail function 5-2408 PLIB_OSC_ExistsFRCDivisor function 5-2408 PLIB_OSC_ExistsFRCTuning function 5-2409 PLIB_OSC_ExistsOnWaitAction function 5-2409 PLIB_OSC_ExistsOscCurrentGet function 5-2410 PLIB_OSC_ExistsOscSelect function 5-2410 PLIB_OSC_ExistsOscSwitchInit function 5-2411 PLIB_OSC_ExistsPBClockDivisor function 5-2411 PLIB_OSC_ExistsPBClockOutputEnable function 5-2412 PLIB_OSC_ExistsPBClockReady function 5-2412 PLIB_OSC_ExistsPLLClockLock function 5-2413 PLIB_OSC_ExistsPLLLockStatus function 5-2413 PLIB_OSC_ExistsReferenceOscBaseClock function 5-2414 PLIB_OSC_ExistsReferenceOscChange function 5-2414 PLIB_OSC_ExistsReferenceOscChangeActive function 5-2415 PLIB_OSC_ExistsReferenceOscDivisor function 5-2415 PLIB_OSC_ExistsReferenceOscEnable function 5-2416 PLIB_OSC_ExistsReferenceOscStopInIdleEnable function 5-2416 PLIB_OSC_ExistsReferenceOscStopInSleep function 5-2417 PLIB_OSC_ExistsReferenceOscTrim function 5-2417 PLIB_OSC_ExistsReferenceOutputEnable function 5-2418 PLIB_OSC_ExistsSecondaryEnable function 5-2419 PLIB_OSC_ExistsSecondaryReady function 5-2419 PLIB_OSC_ExistsSysPLLFrequencyRange function 5-2420 PLIB_OSC_ExistsSysPLLInputClockSource function 5-2420 PLIB_OSC_ExistsSysPLLInputDivisor function 5-2421 PLIB_OSC_ExistsSysPLLMultiplier function 5-2421 PLIB_OSC_ExistsSysPLLOutputDivisor function 5-2422 PLIB_OSC_ExistsUsbClockSource function 5-2422 PLIB_OSC_FRCDitherEnable function 5-2359 PLIB_OSC_FRCDivisorGet function 5-2360 PLIB_OSC_FRCDivisorSelect function 5-2360 PLIB_OSC_FRCTuningModeGet function 5-2361 9 MPLAB Harmony Help ccc PLIB_OSC_FRCTuningModeSet function 5-2361 PLIB_OSC_FRCTuningSelect function 5-2362 PLIB_OSC_FRCTuningSequenceValueGet function 5-2362 PLIB_OSC_FRCTuningSequenceValueSet function 5-2363 PLIB_OSC_GraphicsClockDivisorGet function 5-2371 PLIB_OSC_GraphicsClockDivisorSet function 5-2372 PLIB_OSC_GraphicsClockSourceGet function 5-2372 PLIB_OSC_GraphicsClockSourceSelect function 5-2373 PLIB_OSC_LinearFeedbackShiftRegGet function 5-2364 PLIB_OSC_LinearFeedbackShiftRegSet function 5-2365 PLIB_OSC_OnWaitActionGet function 5-2342 PLIB_OSC_OnWaitActionSet function 5-2342 PLIB_OSC_PBClockDivisorGet function 5-2388 PLIB_OSC_PBClockDivisorIsReady function 5-2389 PLIB_OSC_PBClockDivisorSet function 5-2390 PLIB_OSC_PBOutputClockDisable function 5-2390 PLIB_OSC_PBOutputClockEnable function 5-2391 PLIB_OSC_PBOutputClockIsEnabled function 5-2391 PLIB_OSC_PLLAuxClockSourceGet function 5-2374 PLIB_OSC_PLLAuxClockSourceSelect function 5-2375 PLIB_OSC_PLLAuxInputDivisorGet function 5-2375 PLIB_OSC_PLLAuxInputDivisorSelect function 5-2376 PLIB_OSC_PLLAuxIsLocked function 5-2376 PLIB_OSC_PLLAuxMultiplierGet function 5-2377 PLIB_OSC_PLLAuxMultiplierSelect function 5-2378 PLIB_OSC_PLLAuxOutputDivisorGet function 5-2378 PLIB_OSC_PLLAuxOutputDivisorSet function 5-2379 PLIB_OSC_PLLClockIsLocked function 5-2379 PLIB_OSC_PLLClockLock function 5-2380 PLIB_OSC_PLLClockUnlock function 5-2380 PLIB_OSC_PLLDisable function 5-2381 PLIB_OSC_PLLEnable function 5-2381 PLIB_OSC_PLLIsEnabled function 5-2382 PLIB_OSC_PLLIsLocked function 5-2382 PLIB_OSC_PrimaryOscInSleepModeDisable function 5-2343 PLIB_OSC_PrimaryOscInSleepModeEnable function 5-2344 PLIB_OSC_PrimaryOscInSleepModeIsEnabled function 5-2344 PLIB_OSC_ReferenceOscBaseClockSelect function 5-2349 PLIB_OSC_ReferenceOscDisable function 5-2350 PLIB_OSC_ReferenceOscDivisorValueSet function 5-2350 PLIB_OSC_ReferenceOscEnable function 5-2351 PLIB_OSC_ReferenceOscIsEnabled function 5-2351 PLIB_OSC_ReferenceOscSourceChangeIsActive function 5-2352 PLIB_OSC_ReferenceOscStopInIdleDisable function 5-2353 PLIB_OSC_ReferenceOscStopInIdleEnable function 5-2353 PLIB_OSC_ReferenceOscStopInIdleIsEnabled function 5-2354 PLIB_OSC_ReferenceOscStopInSleepDisable function 5-2354 PLIB_OSC_ReferenceOscStopInSleepEnable function 5-2355 PLIB_OSC_ReferenceOscStopInSleepIsEnabled function 5-2356 PLIB_OSC_ReferenceOscSwitchIsComplete function 5-2356 PLIB_OSC_ReferenceOscTrimSet function 5-2357 PLIB_OSC_ReferenceOutputDisable function 5-2357 PLIB_OSC_ReferenceOutputEnable function 5-2358 PLIB_OSC_ReferenceOutputIsEnabled function 5-2358 PLIB_OSC_SecondaryDisable function 5-2345 PLIB_OSC_SecondaryEnable function 5-2345 PLIB_OSC_SecondaryIsEnabled function 5-2346 PLIB_OSC_SecondaryIsReady function 5-2346 PLIB_OSC_StartupTimerHasExpired function 5-2343 PLIB_OSC_SysClockSelect function 5-2367 PLIB_OSC_SysPLLFrequencyRangeGet function 5-2383 PLIB_OSC_SysPLLFrequencyRangeSet function 5-2383 PLIB_OSC_SysPLLInputClockSourceGet function 5-2384 PLIB_OSC_SysPLLInputClockSourceSet function 5-2384 PLIB_OSC_SysPLLInputDivisorGet function 5-2385 PLIB_OSC_SysPLLInputDivisorSet function 5-2386 PLIB_OSC_SysPLLMultiplierGet function 5-2386 PLIB_OSC_SysPLLMultiplierSelect function 5-2387 PLIB_OSC_SysPLLOutputDivisorGet function 5-2387 PLIB_OSC_SysPLLOutputDivisorSet function 5-2388 PLIB_OSC_UsbClockSourceGet function 5-2373 PLIB_OSC_UsbClockSourceSelect function 5-2374 plib_pcache.h 5-2475 PLIB_PCACHE_CacheHitRead function 5-2452 PLIB_PCACHE_CacheHitWrite function 5-2452 PLIB_PCACHE_CacheLineAddrGet function 5-2441 PLIB_PCACHE_CacheLineAddrSet function 5-2441 9 MPLAB Harmony Help ddd PLIB_PCACHE_CacheLineData function 5-2442 PLIB_PCACHE_CacheLineDeselect function 5-2442 PLIB_PCACHE_CacheLineFlashTypeBoot function 5-2443 PLIB_PCACHE_CacheLineFlashTypeInst function 5-2443 PLIB_PCACHE_CacheLineFlashTypeIsInst function 5-2444 PLIB_PCACHE_CacheLineInst function 5-2444 PLIB_PCACHE_CacheLineInvalid function 5-2445 PLIB_PCACHE_CacheLineIsInst function 5-2445 PLIB_PCACHE_CacheLineIsLocked function 5-2446 PLIB_PCACHE_CacheLineIsValid function 5-2447 PLIB_PCACHE_CacheLineLock function 5-2447 PLIB_PCACHE_CacheLineMaskGet function 5-2448 PLIB_PCACHE_CacheLineMaskSet function 5-2448 PLIB_PCACHE_CacheLineSelect function 5-2449 PLIB_PCACHE_CacheLineUnlock function 5-2449 PLIB_PCACHE_CacheLineValid function 5-2450 PLIB_PCACHE_CacheMissRead function 5-2453 PLIB_PCACHE_CacheMissWrite function 5-2453 PLIB_PCACHE_DATA_ENABLE enumeration 5-2463 PLIB_PCACHE_DataCacheEnableGet function 5-2437 PLIB_PCACHE_DataCacheEnableSet function 5-2438 PLIB_PCACHE_ExistsCacheHit function 5-2464 PLIB_PCACHE_ExistsCacheLine function 5-2465 PLIB_PCACHE_ExistsCacheLineAddr function 5-2465 PLIB_PCACHE_ExistsCacheLineFlashType function 5-2466 PLIB_PCACHE_ExistsCacheLineLock function 5-2466 PLIB_PCACHE_ExistsCacheLineMask function 5-2467 PLIB_PCACHE_ExistsCacheLineType function 5-2467 PLIB_PCACHE_ExistsCacheLineValid function 5-2468 PLIB_PCACHE_ExistsCacheMiss function 5-2468 PLIB_PCACHE_ExistsDataCacheEnable function 5-2469 PLIB_PCACHE_ExistsFlashDEDStatus function 5-2470 PLIB_PCACHE_ExistsFlashSECCount function 5-2470 PLIB_PCACHE_ExistsFlashSECInt function 5-2471 PLIB_PCACHE_ExistsFlashSECStatus function 5-2471 PLIB_PCACHE_ExistsInvalidateOnPFMProgram function 5-2472 PLIB_PCACHE_ExistsLeastRecentlyUsedState function 5-2472 PLIB_PCACHE_ExistsPrefetchAbort function 5-2473 PLIB_PCACHE_ExistsPrefetchEnable function 5-2473 PLIB_PCACHE_ExistsWaitState function 5-2474 PLIB_PCACHE_ExistsWord function 5-2474 PLIB_PCACHE_FlashDEDStatusClear function 5-2457 PLIB_PCACHE_FlashDEDStatusGet function 5-2457 PLIB_PCACHE_FlashSECCountGet function 5-2458 PLIB_PCACHE_FlashSECCountSet function 5-2458 PLIB_PCACHE_FlashSECIntDisable function 5-2459 PLIB_PCACHE_FlashSECIntEnable function 5-2460 PLIB_PCACHE_FlashSECStatusClear function 5-2460 PLIB_PCACHE_FlashSECStatusGet function 5-2461 PLIB_PCACHE_FlashSECStatusSet function 5-2461 PLIB_PCACHE_InvalidateOnPFMProgramAll function 5-2438 PLIB_PCACHE_InvalidateOnPFMProgramUnlocked function 5-2439 PLIB_PCACHE_LeastRecentlyUsedStateRead function 5-2454 PLIB_PCACHE_MAX_SEC_COUNT macro 5-2462 PLIB_PCACHE_NUM_LINES macro 5-2462 PLIB_PCACHE_NUM_WORDS_PER_LINE macro 5-2462 PLIB_PCACHE_PREFETCH_ENABLE enumeration 5-2463 PLIB_PCACHE_PrefetchAbortRead function 5-2456 PLIB_PCACHE_PrefetchAbortWrite function 5-2456 PLIB_PCACHE_PrefetchEnableGet function 5-2454 PLIB_PCACHE_PrefetchEnableSet function 5-2455 PLIB_PCACHE_WaitStateGet function 5-2439 PLIB_PCACHE_WaitStateSet function 5-2440 PLIB_PCACHE_WordRead function 5-2450 PLIB_PCACHE_WordWrite function 5-2451 plib_pmp.h 5-2588 PLIB_PMP_AddressGet function 5-2531 PLIB_PMP_AddressIncrementModeGet function 5-2494 PLIB_PMP_AddressIncrementModeSelect function 5-2495 PLIB_PMP_AddressLatchPolaritySelect function 5-2540 PLIB_PMP_AddressLatchStrobeDisable function 5-2496 PLIB_PMP_AddressLatchStrobeEnable function 5-2496 PLIB_PMP_AddressLinesA0A1Get function 5-2532 PLIB_PMP_AddressLinesA0A1Set function 5-2532 PLIB_PMP_AddressPortDisable function 5-2535 PLIB_PMP_AddressPortEnable function 5-2535 PLIB_PMP_AddressSet function 5-2533 PLIB_PMP_AlternateMasterHasAccess function 5-2513 9 MPLAB Harmony Help eee PLIB_PMP_AlternateMasterRequestStatus function 5-2514 PLIB_PMP_BusKeeperDisable function 5-2506 PLIB_PMP_BusKeeperEnable function 5-2506 PLIB_PMP_ByteEnablePolaritySelect function 5-2541 PLIB_PMP_ByteEnablePortDisable function 5-2536 PLIB_PMP_ByteEnablePortEnable function 5-2537 PLIB_PMP_ChipSelectFunctionSelect function 5-2497 PLIB_PMP_ChipSelectXAckPolaritySelect function 5-2543 PLIB_PMP_ChipSelectXByteEnablePortPolaritySelect function 5-2544 PLIB_PMP_ChipSelectXDisable function 5-2497 PLIB_PMP_ChipSelectXEnable function 5-2498 PLIB_PMP_ChipSelectXEnableStrobeDeSelect function 5-2507 PLIB_PMP_ChipSelectXEnableStrobeSelect function 5-2508 PLIB_PMP_ChipSelectXIsActive function 5-2499 PLIB_PMP_ChipSelectXPolaritySelect function 5-2542 PLIB_PMP_ChipSelectXPortDisable function 5-2539 PLIB_PMP_ChipSelectXPortEnable function 5-2540 PLIB_PMP_ChipSelectXReadWriteStrobePolaritySelect function 5-2545 PLIB_PMP_ChipSelectXWriteEnableStrobePolaritySelect function 5-2545 PLIB_PMP_ChipXAckModeSelect function 5-2509 PLIB_PMP_ChipXBaseAddressSet function 5-2534 PLIB_PMP_ChipXDataSizeSelect function 5-2510 PLIB_PMP_ChipXWaitStatesAlternateMasterSelect function 5-2527 PLIB_PMP_ChipXWaitStatesDataHoldSelect function 5-2528 PLIB_PMP_ChipXWaitStatesDataSetupSelect function 5-2529 PLIB_PMP_ChipXWaitStatesStrobeSelect function 5-2529 PLIB_PMP_DataSizeSelect function 5-2499 PLIB_PMP_Disable function 5-2500 PLIB_PMP_Enable function 5-2500 PLIB_PMP_EnhancedMasterModeSelect function 5-2510 PLIB_PMP_ExistsAddressControl function 5-2557 PLIB_PMP_ExistsAddressLatchPolarity function 5-2557 PLIB_PMP_ExistsAddressLatchStrobePortControl function 5-2558 PLIB_PMP_ExistsAddressPortPinControl function 5-2558 PLIB_PMP_ExistsAltMasterRequest function 5-2559 PLIB_PMP_ExistsBufferOverFlow function 5-2560 PLIB_PMP_ExistsBufferRead function 5-2560 PLIB_PMP_ExistsBufferType function 5-2561 PLIB_PMP_ExistsBufferUnderFlow function 5-2561 PLIB_PMP_ExistsBufferWrite function 5-2562 PLIB_PMP_ExistsBusKeeper function 5-2562 PLIB_PMP_ExistsBusyStatus function 5-2563 PLIB_PMP_ExistsByteEnablePolarity function 5-2563 PLIB_PMP_ExistsByteEnablePortControl function 5-2564 PLIB_PMP_ExistsChipSelectEnable function 5-2564 PLIB_PMP_ExistsChipSelectoperation function 5-2565 PLIB_PMP_ExistsChipXACKMode function 5-2565 PLIB_PMP_ExistsChipXACKPolarity function 5-2566 PLIB_PMP_ExistsChipXAltMasterWaitStates function 5-2566 PLIB_PMP_ExistsChipXBaseAddress function 5-2567 PLIB_PMP_ExistsChipXByteEnablePolarity function 5-2567 PLIB_PMP_ExistsChipXDataHoldWaitStates function 5-2568 PLIB_PMP_ExistsChipXDataSetupWaitStates function 5-2568 PLIB_PMP_ExistsChipXDataSize function 5-2569 PLIB_PMP_ExistsChipXEnableStorbeSelect function 5-2569 PLIB_PMP_ExistsChipXPolarity function 5-2570 PLIB_PMP_ExistsChipXReadWritePolarity function 5-2570 PLIB_PMP_ExistsChipXStrobeWaitStates function 5-2571 PLIB_PMP_ExistsChipXWriteEnablePolarity function 5-2571 PLIB_PMP_ExistsCSXActiveStatus function 5-2572 PLIB_PMP_ExistsCSXPortControl function 5-2572 PLIB_PMP_ExistsCurrentMaster function 5-2573 PLIB_PMP_ExistsDataHoldWaitStates function 5-2573 PLIB_PMP_ExistsDataSetUpWaitStates function 5-2574 PLIB_PMP_ExistsDataStrobeWaitStates function 5-2574 PLIB_PMP_ExistsDataTransferSize function 5-2575 PLIB_PMP_ExistsEnableControl function 5-2575 PLIB_PMP_ExistsEnhancedMasterMode function 5-2576 PLIB_PMP_ExistsIncrementMode function 5-2576 PLIB_PMP_ExistsInputBufferFull function 5-2577 PLIB_PMP_ExistsInputBufferXStatus function 5-2577 PLIB_PMP_ExistsInterruptMode function 5-2578 PLIB_PMP_ExistsMasterRXTX function 5-2578 PLIB_PMP_ExistsMUXModeSelect function 5-2579 PLIB_PMP_ExistsOperationMode function 5-2579 9 MPLAB Harmony Help fff PLIB_PMP_ExistsOutPutBufferEmpty function 5-2580 PLIB_PMP_ExistsOutputBufferXStatus function 5-2580 PLIB_PMP_ExistsReadWritePolarity function 5-2581 PLIB_PMP_ExistsReadWriteStrobePortControl function 5-2581 PLIB_PMP_ExistsReservedAddrSpace function 5-2582 PLIB_PMP_ExistsSlaveRX function 5-2582 PLIB_PMP_ExistsSlaveTX function 5-2583 PLIB_PMP_ExistsSmartAddress function 5-2583 PLIB_PMP_ExistsStopInIdleControl function 5-2584 PLIB_PMP_ExistsTransactionError function 5-2584 PLIB_PMP_ExistsTransactionTimeOut function 5-2585 PLIB_PMP_ExistsWaitStatesAddrHoldStrobe function 5-2585 PLIB_PMP_ExistsWaitStatesAddrLatchStrobe function 5-2586 PLIB_PMP_ExistsWriteEnablePolarity function 5-2586 PLIB_PMP_ExistsWriteEnablePortControl function 5-2587 PLIB_PMP_InputBuffersAreFull function 5-2518 PLIB_PMP_InputBufferTypeSelect function 5-2501 PLIB_PMP_InputBufferXByteReceive function 5-2519 PLIB_PMP_InputBufferXIsFull function 5-2519 PLIB_PMP_InputOverflowClear function 5-2515 PLIB_PMP_InputOverflowHasOccurred function 5-2512 PLIB_PMP_InterruptModeGet function 5-2502 PLIB_PMP_InterruptModeSelect function 5-2502 PLIB_PMP_IsDataReceived function 5-2520 PLIB_PMP_IsDataTransmitted function 5-2521 PLIB_PMP_IsEnabled function 5-2511 PLIB_PMP_MasterReceive function 5-2521 PLIB_PMP_MasterSend function 5-2522 PLIB_PMP_MultiplexModeGet function 5-2503 PLIB_PMP_MultiplexModeSelect function 5-2503 PLIB_PMP_OperationModeGet function 5-2504 PLIB_PMP_OperationModeSelect function 5-2504 PLIB_PMP_OutputBuffersAreEmpty function 5-2522 PLIB_PMP_OutputBufferXByteSend function 5-2523 PLIB_PMP_OutputBufferXIsEmpty function 5-2524 PLIB_PMP_OutputUnderflowClear function 5-2515 PLIB_PMP_OutputUnderflowHasOccurred function 5-2513 PLIB_PMP_PortIsBusy function 5-2512 PLIB_PMP_ReadWriteStrobePolaritySelect function 5-2542 PLIB_PMP_ReadWriteStrobePortDisable function 5-2537 PLIB_PMP_ReadWriteStrobePortEnable function 5-2538 PLIB_PMP_ReservedAddressSpaceBitsSet function 5-2534 PLIB_PMP_SlaveReceive function 5-2524 PLIB_PMP_SlaveSend function 5-2525 PLIB_PMP_SmartAddressStrobeDisable function 5-2508 PLIB_PMP_SmartAddressStrobeEnable function 5-2509 PLIB_PMP_StopInIdleDisable function 5-2505 PLIB_PMP_StopInIdleEnable function 5-2505 PLIB_PMP_TransactionErrorClear function 5-2516 PLIB_PMP_TransactionErrorHasOccurred function 5-2516 PLIB_PMP_TransactionHasTimedOut function 5-2517 PLIB_PMP_TransactionTimeoutClear function 5-2517 PLIB_PMP_WaitStatesAddressHoldStrobeSelect function 5-2530 PLIB_PMP_WaitStatesAddressLatchStrobeSelect function 5-2531 PLIB_PMP_WaitStatesDataHoldSelect function 5-2526 PLIB_PMP_WaitStatesDataSetUpSelect function 5-2526 PLIB_PMP_WaitStatesStrobeSelect function 5-2527 PLIB_PMP_WriteEnableStrobePolaritySelect function 5-2543 PLIB_PMP_WriteEnableStrobePortDisable function 5-2538 PLIB_PMP_WriteEnableStrobePortEnable function 5-2539 plib_ports.h 5-2659 PLIB_PORTS_ChangeNoticeDisable function 5-2618 PLIB_PORTS_ChangeNoticeEnable function 5-2618 PLIB_PORTS_ChangeNoticeInIdleDisable function 5-2619 PLIB_PORTS_ChangeNoticeInIdleEnable function 5-2619 PLIB_PORTS_ChangeNoticeInIdlePerPortDisable function 5-2620 PLIB_PORTS_ChangeNoticeInIdlePerPortEnable function 5-2620 PLIB_PORTS_ChangeNoticePerPortHasOccured function 5-2621 PLIB_PORTS_ChangeNoticePerPortTurnOff function 5-2622 PLIB_PORTS_ChangeNoticePerPortTurnOn function 5-2622 PLIB_PORTS_ChangeNoticePullDownPerPortDisable function 5-2623 PLIB_PORTS_ChangeNoticePullDownPerPortEnable function 5-2624 PLIB_PORTS_ChangeNoticePullUpDisable function 5-2624 PLIB_PORTS_ChangeNoticePullUpEnable function 5-2625 9 MPLAB Harmony Help ggg PLIB_PORTS_ChangeNoticePullUpPerPortDisable function 5-2625 PLIB_PORTS_ChangeNoticePullUpPerPortEnable function 5-2626 PLIB_PORTS_Clear function 5-2609 PLIB_PORTS_DirectionGet function 5-2610 PLIB_PORTS_DirectionInputSet function 5-2610 PLIB_PORTS_DirectionOutputSet function 5-2611 PLIB_PORTS_ExistsChangeNotice function 5-2650 PLIB_PORTS_ExistsChangeNoticeInIdle function 5-2650 PLIB_PORTS_ExistsChangeNoticePerPortInIdle function 5-2651 PLIB_PORTS_ExistsChangeNoticePerPortStatus function 5-2651 PLIB_PORTS_ExistsChangeNoticePerPortTurnOn function 5-2652 PLIB_PORTS_ExistsChangeNoticePullDownPerPort function 5-2652 PLIB_PORTS_ExistsChangeNoticePullUp function 5-2653 PLIB_PORTS_ExistsChangeNoticePullUpPerPort function 5-2653 PLIB_PORTS_ExistsPinChangeNotice function 5-2654 PLIB_PORTS_ExistsPinChangeNoticePerPort function 5-2654 PLIB_PORTS_ExistsPinMode function 5-2655 PLIB_PORTS_ExistsPinModePerPort function 5-2655 PLIB_PORTS_ExistsPortsDirection function 5-2656 PLIB_PORTS_ExistsPortsOpenDrain function 5-2656 PLIB_PORTS_ExistsPortsRead function 5-2657 PLIB_PORTS_ExistsPortsWrite function 5-2658 PLIB_PORTS_ExistsRemapInput function 5-2658 PLIB_PORTS_ExistsRemapOutput function 5-2659 PLIB_PORTS_OpenDrainDisable function 5-2615 PLIB_PORTS_OpenDrainEnable function 5-2616 PLIB_PORTS_PinChangeNoticeDisable function 5-2627 PLIB_PORTS_PinChangeNoticeEnable function 5-2627 PLIB_PORTS_PinChangeNoticePerPortDisable function 5-2628 PLIB_PORTS_PinChangeNoticePerPortEnable function 5-2628 PLIB_PORTS_PinClear function 5-2603 PLIB_PORTS_PinDirectionInputSet function 5-2604 PLIB_PORTS_PinDirectionOutputSet function 5-2605 PLIB_PORTS_PinGet function 5-2605 PLIB_PORTS_PinModePerPortSelect function 5-2608 PLIB_PORTS_PinModeSelect function 5-2606 PLIB_PORTS_PinOpenDrainDisable function 5-2611 PLIB_PORTS_PinOpenDrainEnable function 5-2612 PLIB_PORTS_PinSet function 5-2606 PLIB_PORTS_PinToggle function 5-2607 PLIB_PORTS_PinWrite function 5-2608 PLIB_PORTS_Read function 5-2613 PLIB_PORTS_RemapInput function 5-2616 PLIB_PORTS_RemapOutput function 5-2617 PLIB_PORTS_Set function 5-2613 PLIB_PORTS_Toggle function 5-2614 PLIB_PORTS_Write function 5-2614 plib_power.h 5-2686 PLIB_POWER_ClearIdleStatus function 5-2672 PLIB_POWER_ClearSleepStatus function 5-2673 PLIB_POWER_DeepSleepBORDisable function 5-2668 PLIB_POWER_DeepSleepBOREnable function 5-2668 PLIB_POWER_DeepSleepFaultDetectStatus function 5-2673 PLIB_POWER_DeepSleepInterruptOnChangeStatus function 5-2674 PLIB_POWER_DeepSleepMCLREventStatus function 5-2675 PLIB_POWER_DeepSleepModeDisable function 5-2669 PLIB_POWER_DeepSleepModeEnable function 5-2669 PLIB_POWER_DeepSleepPowerOnResetStatus function 5-2675 PLIB_POWER_DeviceWasInIdleMode function 5-2676 PLIB_POWER_DeviceWasInSleepMode function 5-2676 PLIB_POWER_ExistsDeepSleepBOR function 5-2681 PLIB_POWER_ExistsDeepSleepFaultDetect function 5-2681 PLIB_POWER_ExistsDeepSleepInterruptOnChange function 5-2682 PLIB_POWER_ExistsDeepSleepMCLREvent function 5-2682 PLIB_POWER_ExistsDeepSleepMode function 5-2683 PLIB_POWER_ExistsDeepSleepPowerOnReset function 5-2683 PLIB_POWER_ExistsIdleStatus function 5-2684 PLIB_POWER_ExistsPeripheralModuleControl function 5-2684 PLIB_POWER_ExistsSleepStatus function 5-2685 PLIB_POWER_ExistsVoltageRegulatorControl function 5-2685 PLIB_POWER_PeripheralModuleDisable function 5-2670 PLIB_POWER_PeripheralModuleEnable function 5-2670 9 MPLAB Harmony Help hhh PLIB_POWER_PeripheralModuleIsEnabled function 5-2671 PLIB_POWER_VoltageRegulatorDisable function 5-2671 PLIB_POWER_VoltageRegulatorEnable function 5-2672 PLIB_POWER_VoltageRegulatorIsEnabled function 5-2677 plib_reset.h 5-2702 PLIB_RESET_ConfigRegReadErrorGet function 5-2693 PLIB_RESET_ExistsConfigRegReadError function 5-2697 PLIB_RESET_ExistsNmiControl function 5-2698 PLIB_RESET_ExistsNmiCounter function 5-2698 PLIB_RESET_ExistsResetReasonStatus function 5-2696 PLIB_RESET_ExistsSoftwareResetTrigger function 5-2697 PLIB_RESET_ExistsWdtoInSleep function 5-2699 PLIB_RESET_NmiCounterValueGet function 5-2699 PLIB_RESET_NmiCounterValueSet function 5-2700 PLIB_RESET_NmiEventClear function 5-2701 PLIB_RESET_NmiEventTrigger function 5-2701 PLIB_RESET_NmiReasonGet function 5-2702 PLIB_RESET_ReasonClear function 5-2692 PLIB_RESET_ReasonGet function 5-2692 PLIB_RESET_SoftwareResetEnable function 5-2691 PLIB_RESET_WdtTimeOutHasOccurredInSleep function 5-2693 plib_rtcc.h 5-2759 PLIB_RTCC_AlarmChimeDisable function 5-2729 PLIB_RTCC_AlarmChimeEnable function 5-2729 PLIB_RTCC_AlarmDateGet function 5-2730 PLIB_RTCC_AlarmDateSet function 5-2730 PLIB_RTCC_AlarmDayGet function 5-2731 PLIB_RTCC_AlarmDaySet function 5-2731 PLIB_RTCC_AlarmDisable function 5-2732 PLIB_RTCC_AlarmEnable function 5-2732 PLIB_RTCC_AlarmHourGet function 5-2733 PLIB_RTCC_AlarmHourSet function 5-2734 PLIB_RTCC_AlarmMaskModeSelect function 5-2734 PLIB_RTCC_AlarmMinuteGet function 5-2735 PLIB_RTCC_AlarmMinuteSet function 5-2735 PLIB_RTCC_AlarmMonthGet function 5-2736 PLIB_RTCC_AlarmMonthSet function 5-2736 PLIB_RTCC_AlarmPulseInitialGet function 5-2737 PLIB_RTCC_AlarmPulseInitialSet function 5-2737 PLIB_RTCC_AlarmRepeatCountGet function 5-2738 PLIB_RTCC_AlarmRepeatCountSet function 5-2739 PLIB_RTCC_AlarmSecondGet function 5-2739 PLIB_RTCC_AlarmSecondSet function 5-2740 PLIB_RTCC_AlarmTimeGet function 5-2740 PLIB_RTCC_AlarmTimeSet function 5-2741 PLIB_RTCC_AlarmValueRegisterPointer function 5-2741 PLIB_RTCC_AlarmWeekDayGet function 5-2742 PLIB_RTCC_AlarmWeekDaySet function 5-2742 PLIB_RTCC_ClockOutputDisable function 5-2715 PLIB_RTCC_ClockOutputEnable function 5-2716 PLIB_RTCC_ClockRunningStatus function 5-2716 PLIB_RTCC_ClockSourceSelect function 5-2743 PLIB_RTCC_Disable function 5-2717 PLIB_RTCC_DriftCalibrateGet function 5-2744 PLIB_RTCC_DriftCalibrateSet function 5-2744 PLIB_RTCC_Enable function 5-2717 PLIB_RTCC_ExistsAlarmChimeControl function 5-2749 PLIB_RTCC_ExistsAlarmControl function 5-2749 PLIB_RTCC_ExistsAlarmDate function 5-2750 PLIB_RTCC_ExistsAlarmMaskControl function 5-2750 PLIB_RTCC_ExistsAlarmPulseInitial function 5-2751 PLIB_RTCC_ExistsAlarmRepeatControl function 5-2751 PLIB_RTCC_ExistsAlarmSyncronization function 5-2752 PLIB_RTCC_ExistsAlarmTime function 5-2752 PLIB_RTCC_ExistsCalibration function 5-2753 PLIB_RTCC_ExistsClockRunning function 5-2753 PLIB_RTCC_ExistsClockSelect function 5-2754 PLIB_RTCC_ExistsEnableControl function 5-2754 PLIB_RTCC_ExistsHalfSecond function 5-2755 PLIB_RTCC_ExistsOutputControl function 5-2755 PLIB_RTCC_ExistsOutputSelect function 5-2756 PLIB_RTCC_ExistsRTCDate function 5-2756 PLIB_RTCC_ExistsRTCTime function 5-2757 PLIB_RTCC_ExistsStopInIdleControl function 5-2757 PLIB_RTCC_ExistsSynchronization function 5-2758 PLIB_RTCC_ExistsWriteEnable function 5-2758 PLIB_RTCC_HalfSecondStatusGet function 5-2745 PLIB_RTCC_OutputSelect function 5-2745 9 MPLAB Harmony Help iii PLIB_RTCC_RTCDateGet function 5-2719 PLIB_RTCC_RTCDateSet function 5-2719 PLIB_RTCC_RTCDayGet function 5-2720 PLIB_RTCC_RTCDaySet function 5-2720 PLIB_RTCC_RTCHourGet function 5-2721 PLIB_RTCC_RTCHourSet function 5-2722 PLIB_RTCC_RTCMinuteGet function 5-2722 PLIB_RTCC_RTCMinuteSet function 5-2723 PLIB_RTCC_RTCMonthGet function 5-2723 PLIB_RTCC_RTCMonthSet function 5-2724 PLIB_RTCC_RTCSecondGet function 5-2724 PLIB_RTCC_RTCSecondSet function 5-2725 PLIB_RTCC_RTCTimeGet function 5-2725 PLIB_RTCC_RTCTimeSet function 5-2726 PLIB_RTCC_RTCWeekDayGet function 5-2726 PLIB_RTCC_RTCWeekDaySet function 5-2727 PLIB_RTCC_RTCYearGet function 5-2727 PLIB_RTCC_RTCYearSet function 5-2728 PLIB_RTCC_StopInIdleDisable function 5-2746 PLIB_RTCC_StopInIdleEnable function 5-2746 PLIB_RTCC_WriteDisable function 5-2718 PLIB_RTCC_WriteEnable function 5-2718 plib_sb.h 5-2796 PLIB_SB_ARB_POLICY enumeration 5-2781 PLIB_SB_CPUPrioritySet function 5-2786 PLIB_SB_DMAPrioritySet function 5-2786 PLIB_SB_ERROR enumeration 5-2781 PLIB_SB_ExistsCPUPriority function 5-2788 PLIB_SB_ExistsDMAPriority function 5-2788 PLIB_SB_ExistsInitPermGrp function 5-2789 PLIB_SB_ExistsPGRegAddr function 5-2789 PLIB_SB_ExistsPGRegRdPerm function 5-2790 PLIB_SB_ExistsPGRegSize function 5-2790 PLIB_SB_ExistsPGRegWrPerm function 5-2791 PLIB_SB_ExistsPGVErrClear function 5-2791 PLIB_SB_ExistsPGVErrClrMulti function 5-2792 PLIB_SB_ExistsPGVErrClrSingle function 5-2793 PLIB_SB_ExistsPGVErrCmdCode function 5-2793 PLIB_SB_ExistsPGVErrInitID function 5-2794 PLIB_SB_ExistsPGVErrPG function 5-2794 PLIB_SB_ExistsPGVErrRegion function 5-2795 PLIB_SB_ExistsPGVErrRptPri function 5-2795 PLIB_SB_ExistsPGVErrStatus function 5-2796 PLIB_SB_INIT_ID enumeration 5-2781 PLIB_SB_INIT_PG enumeration 5-2782 PLIB_SB_InitPermGrpSet function 5-2787 PLIB_SB_OCP_CMD_CODE enumeration 5-2782 PLIB_SB_PG_INITIATOR enumeration 5-2782 PLIB_SB_PGRegionAddrGet function 5-2768 PLIB_SB_PGRegionAddrSet function 5-2769 PLIB_SB_PGRegionReadPermClear function 5-2770 PLIB_SB_PGRegionReadPermSet function 5-2770 PLIB_SB_PGRegionSizeGet function 5-2771 PLIB_SB_PGRegionSizeSet function 5-2771 PLIB_SB_PGRegionWritePermClear function 5-2772 PLIB_SB_PGRegionWritePermSet function 5-2773 PLIB_SB_PGVErrorClearMulti function 5-2773 PLIB_SB_PGVErrorClearSingle function 5-2774 PLIB_SB_PGVErrorCode function 5-2775 PLIB_SB_PGVErrorCommandCode function 5-2775 PLIB_SB_PGVErrorInitiatorID function 5-2776 PLIB_SB_PGVErrorLogClearMulti function 5-2776 PLIB_SB_PGVErrorLogClearSingle function 5-2777 PLIB_SB_PGVErrorMulti function 5-2777 PLIB_SB_PGVErrorPermissionGroup function 5-2778 PLIB_SB_PGVErrorRegion function 5-2778 PLIB_SB_PGVErrorReportPrimaryDisable function 5-2779 PLIB_SB_PGVErrorReportPrimaryEnable function 5-2779 PLIB_SB_PGVErrorStatus function 5-2780 PLIB_SB_REGION_PG enumeration 5-2783 PLIB_SB_TGT_ID enumeration 5-2783 PLIB_SB_TGT_REGION enumeration 5-2784 plib_spi.h 5-2888 PLIB_SPI_AudioCommunicationWidthSelect function 5-2850 PLIB_SPI_AudioErrorDisable function 5-2851 PLIB_SPI_AudioErrorEnable function 5-2851 PLIB_SPI_AudioProtocolDisable function 5-2852 PLIB_SPI_AudioProtocolEnable function 5-2852 9 MPLAB Harmony Help jjj PLIB_SPI_AudioProtocolModeSelect function 5-2853 PLIB_SPI_AudioTransmitModeSelect function 5-2854 PLIB_SPI_BaudRateClockSelect function 5-2827 PLIB_SPI_BaudRateSet function 5-2828 PLIB_SPI_BufferClear function 5-2843 PLIB_SPI_BufferRead function 5-2844 PLIB_SPI_BufferWrite function 5-2844 PLIB_SPI_ClockPolaritySelect function 5-2829 PLIB_SPI_CommunicationWidthSelect function 5-2829 PLIB_SPI_Disable function 5-2830 PLIB_SPI_Enable function 5-2830 PLIB_SPI_ErrorInterruptDisable function 5-2831 PLIB_SPI_ErrorInterruptEnable function 5-2832 PLIB_SPI_ExistsAudioCommunicationWidth function 5-2868 PLIB_SPI_ExistsAudioErrorControl function 5-2868 PLIB_SPI_ExistsAudioProtocolControl function 5-2869 PLIB_SPI_ExistsAudioProtocolMode function 5-2869 PLIB_SPI_ExistsAudioTransmitMode function 5-2870 PLIB_SPI_ExistsBaudRate function 5-2870 PLIB_SPI_ExistsBaudRateClock function 5-2871 PLIB_SPI_ExistsBuffer function 5-2871 PLIB_SPI_ExistsBusStatus function 5-2872 PLIB_SPI_ExistsClockPolarity function 5-2872 PLIB_SPI_ExistsCommunicationWidth function 5-2873 PLIB_SPI_ExistsEnableControl function 5-2873 PLIB_SPI_ExistsErrorInterruptControl function 5-2874 PLIB_SPI_ExistsFIFOControl function 5-2874 PLIB_SPI_ExistsFIFOCount function 5-2875 PLIB_SPI_ExistsFIFOInterruptMode function 5-2875 PLIB_SPI_ExistsFIFOShiftRegisterEmptyStatus function 5-2876 PLIB_SPI_ExistsFramedCommunication function 5-2876 PLIB_SPI_ExistsFrameErrorStatus function 5-2877 PLIB_SPI_ExistsFrameSyncPulseCounter function 5-2877 PLIB_SPI_ExistsFrameSyncPulseDirection function 5-2878 PLIB_SPI_ExistsFrameSyncPulseEdge function 5-2878 PLIB_SPI_ExistsFrameSyncPulsePolarity function 5-2879 PLIB_SPI_ExistsFrameSyncPulseWidth function 5-2879 PLIB_SPI_ExistsInputSamplePhase function 5-2880 PLIB_SPI_ExistsMasterControl function 5-2880 PLIB_SPI_ExistsOutputDataPhase function 5-2881 PLIB_SPI_ExistsPinControl function 5-2881 PLIB_SPI_ExistsPrimaryPrescale function 5-2882 PLIB_SPI_ExistsReadDataSignStatus function 5-2882 PLIB_SPI_ExistsReceiveBufferStatus function 5-2883 PLIB_SPI_ExistsReceiveFIFOStatus function 5-2883 PLIB_SPI_ExistsReceiverOverflow function 5-2884 PLIB_SPI_ExistsSecondaryPrescale function 5-2884 PLIB_SPI_ExistsSlaveSelectControl function 5-2885 PLIB_SPI_ExistsStopInIdleControl function 5-2885 PLIB_SPI_ExistsTransmitBufferEmptyStatus function 5-2886 PLIB_SPI_ExistsTransmitBufferFullStatus function 5-2886 PLIB_SPI_ExistsTransmitUnderRunStatus function 5-2887 PLIB_SPI_FIFOCountGet function 5-2832 PLIB_SPI_FIFODisable function 5-2833 PLIB_SPI_FIFOEnable function 5-2833 PLIB_SPI_FIFOInterruptModeSelect function 5-2834 PLIB_SPI_FIFOShiftRegisterIsEmpty function 5-2835 PLIB_SPI_FramedCommunicationDisable function 5-2845 PLIB_SPI_FramedCommunicationEnable function 5-2846 PLIB_SPI_FrameErrorStatusGet function 5-2846 PLIB_SPI_FrameSyncPulseCounterSelect function 5-2847 PLIB_SPI_FrameSyncPulseDirectionSelect function 5-2847 PLIB_SPI_FrameSyncPulseEdgeSelect function 5-2848 PLIB_SPI_FrameSyncPulsePolaritySelect function 5-2849 PLIB_SPI_FrameSyncPulseWidthSelect function 5-2849 PLIB_SPI_InputSamplePhaseSelect function 5-2835 PLIB_SPI_IsBusy function 5-2836 PLIB_SPI_MasterEnable function 5-2836 PLIB_SPI_OutputDataPhaseSelect function 5-2837 PLIB_SPI_PinDisable function 5-2838 PLIB_SPI_PinEnable function 5-2838 PLIB_SPI_PrescalePrimarySelect function 5-2839 PLIB_SPI_PrescaleSecondarySelect function 5-2839 PLIB_SPI_ReadDataIsSignExtended function 5-2840 PLIB_SPI_ReceiverBufferIsFull function 5-2856 PLIB_SPI_ReceiverFIFOIsEmpty function 5-2857 PLIB_SPI_ReceiverHasOverflowed function 5-2857 PLIB_SPI_ReceiverOverflowClear function 5-2858 9 MPLAB Harmony Help kkk PLIB_SPI_SlaveEnable function 5-2841 PLIB_SPI_SlaveSelectDisable function 5-2841 PLIB_SPI_SlaveSelectEnable function 5-2842 PLIB_SPI_StopInIdleDisable function 5-2842 PLIB_SPI_StopInIdleEnable function 5-2843 PLIB_SPI_TransmitBufferIsEmpty function 5-2854 PLIB_SPI_TransmitBufferIsFull function 5-2855 PLIB_SPI_TransmitUnderRunStatusGet function 5-2855 plib_sqi.h 5-3006 PLIB_SQI_BurstEnable function 5-2908 PLIB_SQI_ByteCountGet function 5-2937 PLIB_SQI_ByteCountSet function 5-2938 PLIB_SQI_ChipSelectDeassertDisable function 5-2938 PLIB_SQI_ChipSelectDeassertEnable function 5-2939 PLIB_SQI_ChipSelectGet function 5-2940 PLIB_SQI_ChipSelectSet function 5-2940 PLIB_SQI_ClockDisable function 5-2909 PLIB_SQI_ClockDividerGet function 5-2925 PLIB_SQI_ClockDividerSet function 5-2925 PLIB_SQI_ClockEnable function 5-2926 PLIB_SQI_ClockIsStable function 5-2926 PLIB_SQI_ConfigWordGet function 5-2941 PLIB_SQI_ConfigWordSet function 5-2941 PLIB_SQI_ControlBufferThresholdGet function 5-2909 PLIB_SQI_ControlBufferThresholdSet function 5-2910 PLIB_SQI_ControlWordGet function 5-2910 PLIB_SQI_ControlWordSet function 5-2911 PLIB_SQI_CSOutputEnableSelect function 5-2912 PLIB_SQI_DataFormatGet function 5-2912 PLIB_SQI_DataFormatSet function 5-2913 PLIB_SQI_DataLineStatus function 5-2949 PLIB_SQI_DataModeGet function 5-2913 PLIB_SQI_DataModeSet function 5-2914 PLIB_SQI_DataOutputEnableSelect function 5-2914 PLIB_SQI_Disable function 5-2915 PLIB_SQI_DMABDBaseAddressGet function 5-2954 PLIB_SQI_DMABDBaseAddressSet function 5-2955 PLIB_SQI_DMABDControlWordGet function 5-2956 PLIB_SQI_DMABDCurrentAddressGet function 5-2955 PLIB_SQI_DMABDFetchStart function 5-2960 PLIB_SQI_DMABDIsBusy function 5-2960 PLIB_SQI_DMABDPollCounterSet function 5-2961 PLIB_SQI_DMABDPollDisable function 5-2962 PLIB_SQI_DMABDPollEnable function 5-2962 PLIB_SQI_DMABDPollIsEnabled function 5-2963 PLIB_SQI_DMABDReceiveBufferCountGet function 5-2957 PLIB_SQI_DMABDReceiveBufferLengthGet function 5-2957 PLIB_SQI_DMABDReceiveStateGet function 5-2958 PLIB_SQI_DMABDStateGet function 5-2963 PLIB_SQI_DMABDTransmitBufferCountGet function 5-2958 PLIB_SQI_DMABDTransmitBufferLengthGet function 5-2959 PLIB_SQI_DMABDTransmitStateGet function 5-2959 PLIB_SQI_DMADisable function 5-2964 PLIB_SQI_DMAEnable function 5-2964 PLIB_SQI_DMAHasStarted function 5-2965 PLIB_SQI_DMAIsEnabled function 5-2965 PLIB_SQI_Enable function 5-2915 PLIB_SQI_ExistsBDBaseAddress function 5-2974 PLIB_SQI_ExistsBDControlWord function 5-2975 PLIB_SQI_ExistsBDCurrentAddress function 5-2975 PLIB_SQI_ExistsBDPollCount function 5-2976 PLIB_SQI_ExistsBDPollingEnable function 5-2976 PLIB_SQI_ExistsBDProcessState function 5-2977 PLIB_SQI_ExistsBDRxBufCount function 5-2977 PLIB_SQI_ExistsBDRxLength function 5-2978 PLIB_SQI_ExistsBDRxState function 5-2978 PLIB_SQI_ExistsBDTxBufCount function 5-2979 PLIB_SQI_ExistsBDTxLength function 5-2979 PLIB_SQI_ExistsBDTxState function 5-2980 PLIB_SQI_ExistsBurstControl function 5-2980 PLIB_SQI_ExistsChipSelect function 5-2981 PLIB_SQI_ExistsClockControl function 5-2981 PLIB_SQI_ExistsClockDivider function 5-2982 PLIB_SQI_ExistsClockReady function 5-2982 PLIB_SQI_ExistsConBufThreshold function 5-2983 PLIB_SQI_ExistsConfigWord function 5-2983 PLIB_SQI_ExistsControlWord function 5-2984 PLIB_SQI_ExistsCSDeassert function 5-2984 9 MPLAB Harmony Help lll PLIB_SQI_ExistsCSOutputEnable function 5-2985 PLIB_SQI_ExistsDataFormat function 5-2985 PLIB_SQI_ExistsDataModeControl function 5-2986 PLIB_SQI_ExistsDataOutputEnable function 5-2986 PLIB_SQI_ExistsDataPinStatus function 5-2987 PLIB_SQI_ExistsDmaEnable function 5-2987 PLIB_SQI_ExistsDMAEngineBusy function 5-2988 PLIB_SQI_ExistsDMAProcessInProgress function 5-2988 PLIB_SQI_ExistsEnableControl function 5-2989 PLIB_SQI_ExistsHoldPinControl function 5-2989 PLIB_SQI_ExistsInterruptControl function 5-2990 PLIB_SQI_ExistsInterruptSignalControl function 5-2990 PLIB_SQI_ExistsInterruptStatus function 5-2991 PLIB_SQI_ExistsLaneMode function 5-2992 PLIB_SQI_ExistsReceiveLatch function 5-2992 PLIB_SQI_ExistsRxBufferCount function 5-2993 PLIB_SQI_ExistsRxBufIntThreshold function 5-2993 PLIB_SQI_ExistsRxBufThreshold function 5-2994 PLIB_SQI_ExistsRxData function 5-2994 PLIB_SQI_ExistsRxUnderRun function 5-2995 PLIB_SQI_ExistsSoftReset function 5-2995 PLIB_SQI_ExistsStartDMA function 5-2996 PLIB_SQI_ExistsTransferCommand function 5-2996 PLIB_SQI_ExistsTransferCount function 5-2997 PLIB_SQI_ExistsTransferModeControl function 5-2997 PLIB_SQI_ExistsTxBufferFree function 5-2998 PLIB_SQI_ExistsTxBufIntThreshold function 5-2998 PLIB_SQI_ExistsTxBufThreshold function 5-2999 PLIB_SQI_ExistsTxData function 5-2999 PLIB_SQI_ExistsTxOverFlow function 5-3000 PLIB_SQI_ExistsWPPinControl function 5-3000 PLIB_SQI_ExistsXIPChipSelect function 5-3001 PLIB_SQI_ExistsXIPControlWord1 function 5-3001 PLIB_SQI_ExistsXIPControlWord2 function 5-3002 PLIB_SQI_ExistsXIPLaneMode function 5-3003 PLIB_SQI_ExistsXIPModeBytes function 5-3003 PLIB_SQI_ExistsXIPModeCode function 5-3004 PLIB_SQI_ExistsXIPNumberOfAddressBytes function 5-3004 PLIB_SQI_ExistsXIPNumberOfDummyBytes function 5-3005 PLIB_SQI_ExistsXIPReadOpCode function 5-3005 PLIB_SQI_HoldClear function 5-2916 PLIB_SQI_HoldGet function 5-2916 PLIB_SQI_HoldSet function 5-2917 PLIB_SQI_InterruptDisable function 5-2950 PLIB_SQI_InterruptEnable function 5-2950 PLIB_SQI_InterruptFlagGet function 5-2951 PLIB_SQI_InterruptIsEnabled function 5-2952 PLIB_SQI_InterruptSignalDisable function 5-2952 PLIB_SQI_InterruptSignalEnable function 5-2953 PLIB_SQI_InterruptSignalIsEnabled function 5-2953 PLIB_SQI_LaneModeGet function 5-2917 PLIB_SQI_LaneModeSet function 5-2918 PLIB_SQI_NumberOfReceiveBufferReads function 5-2919 PLIB_SQI_ReceiveBufferIsUnderrun function 5-2942 PLIB_SQI_ReceiveData function 5-2919 PLIB_SQI_ReceiveLatchDisable function 5-2920 PLIB_SQI_ReceiveLatchEnable function 5-2920 PLIB_SQI_ReceiveLatchGet function 5-2921 PLIB_SQI_RxBufferThresholdGet function 5-2943 PLIB_SQI_RxBufferThresholdIntGet function 5-2943 PLIB_SQI_RxBufferThresholdIntSet function 5-2944 PLIB_SQI_RxBufferThresholdSet function 5-2944 PLIB_SQI_SoftReset function 5-2921 PLIB_SQI_TransferDirectionGet function 5-2945 PLIB_SQI_TransferDirectionSet function 5-2945 PLIB_SQI_TransferModeGet function 5-2922 PLIB_SQI_TransferModeSet function 5-2922 PLIB_SQI_TransmitBufferFreeSpaceGet function 5-2946 PLIB_SQI_TransmitBufferHasOverflowed function 5-2947 PLIB_SQI_TransmitData function 5-2923 PLIB_SQI_TxBufferThresholdGet function 5-2947 PLIB_SQI_TxBufferThresholdIntGet function 5-2948 PLIB_SQI_TxBufferThresholdIntSet function 5-2948 PLIB_SQI_TxBufferThresholdSet function 5-2949 PLIB_SQI_WriteProtectClear function 5-2923 PLIB_SQI_WriteProtectGet function 5-2924 PLIB_SQI_WriteProtectSet function 5-2924 PLIB_SQI_XIPAddressBytesGet function 5-2927 9 MPLAB Harmony Help mmm PLIB_SQI_XIPAddressBytesSet function 5-2927 PLIB_SQI_XIPChipSelectGet function 5-2928 PLIB_SQI_XIPChipSelectSet function 5-2928 PLIB_SQI_XIPControlWord1Get function 5-2929 PLIB_SQI_XIPControlWord1Set function 5-2930 PLIB_SQI_XIPControlWord2Get function 5-2931 PLIB_SQI_XIPControlWord2Set function 5-2931 PLIB_SQI_XIPDummyBytesGet function 5-2932 PLIB_SQI_XIPDummyBytesSet function 5-2932 PLIB_SQI_XIPLaneModeGet function 5-2933 PLIB_SQI_XIPLaneModeSet function 5-2933 PLIB_SQI_XIPModeBytesGet function 5-2934 PLIB_SQI_XIPModeBytesSet function 5-2935 PLIB_SQI_XIPModeCodeGet function 5-2935 PLIB_SQI_XIPModeCodeSet function 5-2936 PLIB_SQI_XIPReadOpcodeGet function 5-2936 PLIB_SQI_XIPReadOpcodeSet function 5-2937 plib_tmr.h 5-3081 PLIB_TMR_AssignmentSelect function 5-3025 PLIB_TMR_ClockSourceEdgeGet function 5-3034 PLIB_TMR_ClockSourceEdgeSelect function 5-3035 PLIB_TMR_ClockSourceExternalSyncDisable function 5-3035 PLIB_TMR_ClockSourceExternalSyncEnable function 5-3036 PLIB_TMR_ClockSourceSelect function 5-3036 PLIB_TMR_ContinousCountModeEnable function 5-3026 PLIB_TMR_Counter16BitClear function 5-3050 PLIB_TMR_Counter16BitGet function 5-3050 PLIB_TMR_Counter16BitSet function 5-3051 PLIB_TMR_Counter32BitClear function 5-3051 PLIB_TMR_Counter32BitGet function 5-3052 PLIB_TMR_Counter32BitSet function 5-3053 PLIB_TMR_Counter8BitClear function 5-3053 PLIB_TMR_Counter8BitGet function 5-3054 PLIB_TMR_Counter8BitSet function 5-3054 PLIB_TMR_CounterAsyncWriteDisable function 5-3055 PLIB_TMR_CounterAsyncWriteEnable function 5-3055 PLIB_TMR_CounterAsyncWriteInProgress function 5-3056 PLIB_TMR_ExistsClockSource function 5-3064 PLIB_TMR_ExistsClockSourceEdge function 5-3065 PLIB_TMR_ExistsClockSourceSync function 5-3065 PLIB_TMR_ExistsCounter16Bit function 5-3066 PLIB_TMR_ExistsCounter32Bit function 5-3066 PLIB_TMR_ExistsCounter8Bit function 5-3067 PLIB_TMR_ExistsCounterAsyncWriteControl function 5-3067 PLIB_TMR_ExistsCounterAsyncWriteInProgress function 5-3068 PLIB_TMR_ExistsCountMode function 5-3068 PLIB_TMR_ExistsEnableControl function 5-3069 PLIB_TMR_ExistsGateCurrentState function 5-3069 PLIB_TMR_ExistsGatedTimeAccumulation function 5-3070 PLIB_TMR_ExistsGatePolarity function 5-3070 PLIB_TMR_ExistsGateSinglePulseAcqusition function 5-3071 PLIB_TMR_ExistsGateSinglePulseMode function 5-3071 PLIB_TMR_ExistsGateSource function 5-3072 PLIB_TMR_ExistsGateToggleMode function 5-3072 PLIB_TMR_ExistsMode16Bit function 5-3073 PLIB_TMR_ExistsMode32Bit function 5-3073 PLIB_TMR_ExistsMode8Bit function 5-3074 PLIB_TMR_ExistsOperationInSleep function 5-3074 PLIB_TMR_ExistsPeriod16Bit function 5-3075 PLIB_TMR_ExistsPeriod32Bit function 5-3075 PLIB_TMR_ExistsPeriod8Bit function 5-3076 PLIB_TMR_ExistsPostscale function 5-3076 PLIB_TMR_ExistsPrescale function 5-3077 PLIB_TMR_ExistsPrescalerAssignment function 5-3078 PLIB_TMR_ExistsStopInIdleControl function 5-3078 PLIB_TMR_ExistsSystemClockStatus function 5-3079 PLIB_TMR_ExistsTimerAssignment function 5-3079 PLIB_TMR_ExistsTimerOperationMode function 5-3080 PLIB_TMR_ExistsTimerOscillator function 5-3080 PLIB_TMR_ExistsTriggerEventReset function 5-3081 PLIB_TMR_GateCurrentStateGet function 5-3037 PLIB_TMR_GateDisable function 5-3038 PLIB_TMR_GateEnable function 5-3038 PLIB_TMR_GatePolaritySelect function 5-3039 PLIB_TMR_GateSinglePulseAcquisitionHasCompleted function 5-3039 PLIB_TMR_GateSinglePulseAcquisitionStart function 5-3040 PLIB_TMR_GateSinglePulseModeDisable function 5-3040 9 MPLAB Harmony Help nnn PLIB_TMR_GateSinglePulseModeEnable function 5-3041 PLIB_TMR_GateSourceSelect function 5-3041 PLIB_TMR_GateToggleModeDisable function 5-3042 PLIB_TMR_GateToggleModeEnable function 5-3042 PLIB_TMR_IsPeriodMatchBased function 5-3058 PLIB_TMR_Mode16BitEnable function 5-3026 PLIB_TMR_Mode32BitEnable function 5-3027 PLIB_TMR_Mode8BitEnable function 5-3028 PLIB_TMR_OperateInSleepDisable function 5-3032 PLIB_TMR_OperateInSleepEnable function 5-3032 PLIB_TMR_Period16BitGet function 5-3046 PLIB_TMR_Period16BitSet function 5-3046 PLIB_TMR_Period32BitGet function 5-3047 PLIB_TMR_Period32BitSet function 5-3048 PLIB_TMR_Period8BitGet function 5-3048 PLIB_TMR_Period8BitSet function 5-3049 PLIB_TMR_PostscaleDivisorGet function 5-3057 PLIB_TMR_PostscaleGet function 5-3057 PLIB_TMR_PostscaleSelect function 5-3058 PLIB_TMR_PrescaleDivisorGet function 5-3043 PLIB_TMR_PrescaleGet function 5-3044 PLIB_TMR_PrescalerDisable function 5-3044 PLIB_TMR_PrescalerEnable function 5-3045 PLIB_TMR_PrescaleSelect function 5-3045 PLIB_TMR_SingleShotModeEnable function 5-3031 PLIB_TMR_Start function 5-3028 PLIB_TMR_Stop function 5-3029 PLIB_TMR_StopInIdleDisable function 5-3033 PLIB_TMR_StopInIdleEnable function 5-3033 PLIB_TMR_SystemClockFromTimerIsActive function 5-3059 PLIB_TMR_TimerOscillatorDisable function 5-3029 PLIB_TMR_TimerOscillatorEnable function 5-3030 PLIB_TMR_TriggerEventResetDisable function 5-3030 PLIB_TMR_TriggerEventResetEnable function 5-3031 plib_usart.h 5-3164 PLIB_USART_AlternateIODisable function 5-3105 PLIB_USART_AlternateIOEnable function 5-3105 PLIB_USART_BaudRateAutoDetectEnable function 5-3116 PLIB_USART_BaudRateAutoDetectIsComplete function 5-3117 PLIB_USART_BaudRateAutoDetectOverflowHasOccurred function 5-3117 PLIB_USART_BaudRateGet function 5-3118 PLIB_USART_BaudRateHighDisable function 5-3118 PLIB_USART_BaudRateHighEnable function 5-3119 PLIB_USART_BaudRateHighSet function 5-3119 PLIB_USART_BaudRateModeSelect function 5-3120 PLIB_USART_BaudRateSet function 5-3121 PLIB_USART_Disable function 5-3106 PLIB_USART_Enable function 5-3106 PLIB_USART_ExistsAlternateIO function 5-3144 PLIB_USART_ExistsBaudRate function 5-3145 PLIB_USART_ExistsBaudRateAutoDetect function 5-3145 PLIB_USART_ExistsBaudRateAutoDetectOverflow function 5-3146 PLIB_USART_ExistsBaudRateBitMode function 5-3146 PLIB_USART_ExistsBaudRateHigh function 5-3147 PLIB_USART_ExistsEnable function 5-3147 PLIB_USART_ExistsHandshakeMode function 5-3148 PLIB_USART_ExistsIrDA function 5-3148 PLIB_USART_ExistsLineControlMode function 5-3149 PLIB_USART_ExistsLoopback function 5-3149 PLIB_USART_ExistsOperationMode function 5-3150 PLIB_USART_ExistsReceiver function 5-3150 PLIB_USART_ExistsReceiverAddressAutoDetect function 5-3151 PLIB_USART_ExistsReceiverAddressDetect function 5-3151 PLIB_USART_ExistsReceiverDataAvailableStatus function 5-3152 PLIB_USART_ExistsReceiverEnable function 5-3152 PLIB_USART_ExistsReceiverFramingErrorStatus function 5-3153 PLIB_USART_ExistsReceiverIdleStateLowEnable function 5-3153 PLIB_USART_ExistsReceiverIdleStatus function 5-3154 PLIB_USART_ExistsReceiverInterruptMode function 5-3154 PLIB_USART_ExistsReceiverMode function 5-3155 PLIB_USART_ExistsReceiverOverrunStatus function 5-3155 PLIB_USART_ExistsReceiverParityErrorStatus function 5-3156 PLIB_USART_ExistsStopInIdle function 5-3156 PLIB_USART_ExistsSyncClockPolarity function 5-3157 9 MPLAB Harmony Help ooo PLIB_USART_ExistsSyncClockSource function 5-3158 PLIB_USART_ExistsSyncMode function 5-3158 PLIB_USART_ExistsTransmitter function 5-3159 PLIB_USART_ExistsTransmitter9BitsSend function 5-3159 PLIB_USART_ExistsTransmitterBreak function 5-3160 PLIB_USART_ExistsTransmitterBufferFullStatus function 5-3160 PLIB_USART_ExistsTransmitterEmptyStatus function 5-3161 PLIB_USART_ExistsTransmitterEnable function 5-3161 PLIB_USART_ExistsTransmitterIdleIsLow function 5-3162 PLIB_USART_ExistsTransmitterIdleStatus function 5-3162 PLIB_USART_ExistsTransmitterInterruptMode function 5-3163 PLIB_USART_ExistsWakeOnStart function 5-3163 PLIB_USART_HandshakeModeSelect function 5-3107 PLIB_USART_IrDADisable function 5-3108 PLIB_USART_IrDAEnable function 5-3108 PLIB_USART_LineControlModeSelect function 5-3109 PLIB_USART_LoopbackDisable function 5-3109 PLIB_USART_LoopbackEnable function 5-3110 PLIB_USART_OperationModeSelect function 5-3110 PLIB_USART_ReceiverAddressAutoDetectDisable function 5-3129 PLIB_USART_ReceiverAddressAutoDetectEnable function 5-3129 PLIB_USART_ReceiverAddressDetectDisable function 5-3130 PLIB_USART_ReceiverAddressDetectEnable function 5-3131 PLIB_USART_ReceiverAddressIsReceived function 5-3131 PLIB_USART_ReceiverByteReceive function 5-3132 PLIB_USART_ReceiverDataIsAvailable function 5-3133 PLIB_USART_ReceiverDisable function 5-3133 PLIB_USART_ReceiverEnable function 5-3134 PLIB_USART_ReceiverFramingErrorHasOccurred function 5-3134 PLIB_USART_ReceiverIdleStateLowDisable function 5-3135 PLIB_USART_ReceiverIdleStateLowEnable function 5-3135 PLIB_USART_ReceiverInterruptModeSelect function 5-3136 PLIB_USART_ReceiverIsIdle function 5-3136 PLIB_USART_ReceiverModeSelect function 5-3137 PLIB_USART_ReceiverOverrunErrorClear function 5-3138 PLIB_USART_ReceiverOverrunHasOccurred function 5-3138 PLIB_USART_ReceiverParityErrorHasOccurred function 5-3139 PLIB_USART_StopInIdleDisable function 5-3111 PLIB_USART_StopInIdleEnable function 5-3111 PLIB_USART_SyncClockPolarityIdleHighDisable function 5-3112 PLIB_USART_SyncClockPolarityIdleHighEnable function 5-3113 PLIB_USART_SyncClockSourceSelect function 5-3113 PLIB_USART_SyncModeSelect function 5-3114 PLIB_USART_Transmitter9BitsSend function 5-3122 PLIB_USART_TransmitterBreakSend function 5-3122 PLIB_USART_TransmitterBreakSendIsComplete function 5-3123 PLIB_USART_TransmitterBufferIsFull function 5-3124 PLIB_USART_TransmitterByteSend function 5-3124 PLIB_USART_TransmitterDisable function 5-3125 PLIB_USART_TransmitterEnable function 5-3125 PLIB_USART_TransmitterIdleIsLowDisable function 5-3126 PLIB_USART_TransmitterIdleIsLowEnable function 5-3127 PLIB_USART_TransmitterInterruptModeSelect function 5-3127 PLIB_USART_TransmitterIsEmpty function 5-3128 PLIB_USART_TransmitterIsIdle function 5-3128 PLIB_USART_WakeOnStartDisable function 5-3114 PLIB_USART_WakeOnStartEnable function 5-3115 PLIB_USART_WakeOnStartIsEnabled function 5-3115 plib_usb.h 5-3313 PLIB_USB_ActivityPending function 5-3260 PLIB_USB_AllInterruptEnable function 5-3188 PLIB_USB_AutoSuspendDisable function 5-3189 PLIB_USB_AutoSuspendEnable function 5-3190 PLIB_USB_BDTBaseAddressGet function 5-3201 PLIB_USB_BDTBaseAddressSet function 5-3201 PLIB_USB_BufferAddressGet function 5-3202 PLIB_USB_BufferAddressSet function 5-3203 PLIB_USB_BufferAllCancelReleaseToUSB function 5-3203 PLIB_USB_BufferByteCountGet function 5-3204 PLIB_USB_BufferByteCountSet function 5-3205 PLIB_USB_BufferCancelReleaseToUSB function 5-3205 PLIB_USB_BufferClearAll function 5-3206 PLIB_USB_BufferClearAllDTSEnable function 5-3207 PLIB_USB_BufferDataToggleGet function 5-3207 9 MPLAB Harmony Help ppp PLIB_USB_BufferDataToggleSelect function 5-3208 PLIB_USB_BufferDataToggleSyncDisable function 5-3209 PLIB_USB_BufferDataToggleSyncEnable function 5-3209 PLIB_USB_BufferEP0RxStatusInitialize function 5-3210 PLIB_USB_BufferIndexGet function 5-3211 PLIB_USB_BufferPIDBitsClear function 5-3211 PLIB_USB_BufferPIDGet function 5-3212 PLIB_USB_BufferReleasedToSW function 5-3213 PLIB_USB_BufferReleaseToUSB function 5-3214 PLIB_USB_BufferSchedule function 5-3214 PLIB_USB_BufferStallDisable function 5-3215 PLIB_USB_BufferStallEnable function 5-3216 PLIB_USB_BufferStallGet function 5-3217 PLIB_USB_DeviceAddressGet function 5-3190 PLIB_USB_DeviceAddressSet function 5-3191 PLIB_USB_Disable function 5-3191 PLIB_USB_Enable function 5-3192 PLIB_USB_EP0HostSetup function 5-3217 PLIB_USB_EP0LSDirectConnectDisable function 5-3218 PLIB_USB_EP0LSDirectConnectEnable function 5-3218 PLIB_USB_EP0NakRetryDisable function 5-3219 PLIB_USB_EP0NakRetryEnable function 5-3219 PLIB_USB_EPnAttributesClear function 5-3220 PLIB_USB_EPnAttributesSet function 5-3221 PLIB_USB_EPnControlTransferDisable function 5-3221 PLIB_USB_EPnControlTransferEnable function 5-3222 PLIB_USB_EPnDirectionDisable function 5-3222 PLIB_USB_EPnHandshakeDisable function 5-3223 PLIB_USB_EPnHandshakeEnable function 5-3223 PLIB_USB_EPnIsStalled function 5-3224 PLIB_USB_EPnRxDisable function 5-3225 PLIB_USB_EPnRxEnable function 5-3225 PLIB_USB_EPnRxSelect function 5-3226 PLIB_USB_EPnStallClear function 5-3226 PLIB_USB_EPnTxDisable function 5-3227 PLIB_USB_EPnTxEnable function 5-3227 PLIB_USB_EPnTxRxSelect function 5-3228 PLIB_USB_EPnTxSelect function 5-3229 PLIB_USB_ErrorInterruptDisable function 5-3234 PLIB_USB_ErrorInterruptEnable function 5-3235 PLIB_USB_ErrorInterruptFlagAllGet function 5-3235 PLIB_USB_ErrorInterruptFlagClear function 5-3236 PLIB_USB_ErrorInterruptFlagGet function 5-3236 PLIB_USB_ErrorInterruptFlagSet function 5-3237 PLIB_USB_ErrorInterruptIsEnabled function 5-3237 PLIB_USB_ExistsActivityPending function 5-3283 PLIB_USB_ExistsALL_Interrupt function 5-3284 PLIB_USB_ExistsAutomaticSuspend function 5-3284 PLIB_USB_ExistsBDTBaseAddress function 5-3285 PLIB_USB_ExistsBDTFunctions function 5-3285 PLIB_USB_ExistsBufferFreeze function 5-3286 PLIB_USB_ExistsDeviceAddress function 5-3287 PLIB_USB_ExistsEP0LowSpeedConnect function 5-3287 PLIB_USB_ExistsEP0NAKRetry function 5-3288 PLIB_USB_ExistsEPnRxEnable function 5-3289 PLIB_USB_ExistsEPnTxRx function 5-3289 PLIB_USB_ExistsERR_Interrupt function 5-3290 PLIB_USB_ExistsERR_InterruptStatus function 5-3290 PLIB_USB_ExistsEyePattern function 5-3291 PLIB_USB_ExistsFrameNumber function 5-3291 PLIB_USB_ExistsGEN_Interrupt function 5-3292 PLIB_USB_ExistsGEN_InterruptStatus function 5-3293 PLIB_USB_ExistsHostBusyWithToken function 5-3293 PLIB_USB_ExistsHostGeneratesReset function 5-3294 PLIB_USB_ExistsLastDirection function 5-3294 PLIB_USB_ExistsLastEndpoint function 5-3295 PLIB_USB_ExistsLastPingPong function 5-3295 PLIB_USB_ExistsLastTransactionDetails function 5-3296 PLIB_USB_ExistsLiveJState function 5-3296 PLIB_USB_ExistsLiveSingleEndedZero function 5-3297 PLIB_USB_ExistsModuleBusy function 5-3297 PLIB_USB_ExistsModulePower function 5-3298 PLIB_USB_ExistsNextTokenSpeed function 5-3298 PLIB_USB_ExistsOnChipPullup function 5-3299 PLIB_USB_ExistsOnChipTransceiver function 5-3299 PLIB_USB_ExistsOpModeSelect function 5-3300 PLIB_USB_ExistsOTG_ASessionValid function 5-3300 PLIB_USB_ExistsOTG_BSessionEnd function 5-3301 9 MPLAB Harmony Help qqq PLIB_USB_ExistsOTG_IDPinState function 5-3301 PLIB_USB_ExistsOTG_Interrupt function 5-3302 PLIB_USB_ExistsOTG_InterruptStatus function 5-3302 PLIB_USB_ExistsOTG_LineState function 5-3303 PLIB_USB_ExistsOTG_PullUpPullDown function 5-3303 PLIB_USB_ExistsOTG_SessionValid function 5-3304 PLIB_USB_ExistsOTG_VbusCharge function 5-3304 PLIB_USB_ExistsOTG_VbusDischarge function 5-3305 PLIB_USB_ExistsOTG_VbusPowerOnOff function 5-3305 PLIB_USB_ExistsPacketTransfer function 5-3306 PLIB_USB_ExistsPingPongMode function 5-3306 PLIB_USB_ExistsResumeSignaling function 5-3307 PLIB_USB_ExistsSleepEntryGuard function 5-3308 PLIB_USB_ExistsSOFThreshold function 5-3308 PLIB_USB_ExistsSpeedControl function 5-3309 PLIB_USB_ExistsStartOfFrames function 5-3309 PLIB_USB_ExistsStopInIdle function 5-3310 PLIB_USB_ExistsSuspend function 5-3310 PLIB_USB_ExistsTokenEP function 5-3311 PLIB_USB_ExistsTokenPID function 5-3311 PLIB_USB_ExistsUOEMonitor function 5-3312 PLIB_USB_ExternalComparatorMode2Pin function 5-3267 PLIB_USB_ExternalComparatorMode3Pin function 5-3267 PLIB_USB_EyePatternDisable function 5-3274 PLIB_USB_EyePatternEnable function 5-3274 PLIB_USB_FrameNumberGet function 5-3261 PLIB_USB_FullSpeedDisable function 5-3193 PLIB_USB_FullSpeedEnable function 5-3193 PLIB_USB_I2CInterfaceForExtModuleDisable function 5-3265 PLIB_USB_I2CInterfaceForExtModuleEnable function 5-3265 PLIB_USB_InterruptDisable function 5-3229 PLIB_USB_InterruptEnable function 5-3230 PLIB_USB_InterruptEnableGet function 5-3230 PLIB_USB_InterruptFlagAllGet function 5-3231 PLIB_USB_InterruptFlagClear function 5-3231 PLIB_USB_InterruptFlagGet function 5-3232 PLIB_USB_InterruptFlagSet function 5-3233 PLIB_USB_InterruptIsEnabled function 5-3233 PLIB_USB_IsBusyWithToken function 5-3241 PLIB_USB_JStateIsActive function 5-3261 PLIB_USB_LastTransactionDetailsGet function 5-3238 PLIB_USB_LastTransactionDirectionGet function 5-3239 PLIB_USB_LastTransactionEndPtGet function 5-3239 PLIB_USB_LastTransactionPingPongStateGet function 5-3240 PLIB_USB_ModuleIsBusy function 5-3275 PLIB_USB_OnChipPullUpDisable function 5-3194 PLIB_USB_OnChipPullUpEnable function 5-3194 PLIB_USB_OperatingModeSelect function 5-3195 PLIB_USB_OTG_BSessionHasEnded function 5-3249 PLIB_USB_OTG_IDPinStateIsTypeA function 5-3249 PLIB_USB_OTG_InterruptDisable function 5-3257 PLIB_USB_OTG_InterruptEnable function 5-3257 PLIB_USB_OTG_InterruptFlagClear function 5-3258 PLIB_USB_OTG_InterruptFlagGet function 5-3258 PLIB_USB_OTG_InterruptFlagSet function 5-3259 PLIB_USB_OTG_InterruptIsEnabled function 5-3259 PLIB_USB_OTG_LineStateIsStable function 5-3250 PLIB_USB_OTG_PullUpPullDownSetup function 5-3251 PLIB_USB_OTG_SessionValid function 5-3251 PLIB_USB_OTG_VBusChargeDisable function 5-3252 PLIB_USB_OTG_VBusChargeEnable function 5-3252 PLIB_USB_OTG_VBusChargeTo3V function 5-3253 PLIB_USB_OTG_VBusChargeTo5V function 5-3253 PLIB_USB_OTG_VBusDischargeDisable function 5-3254 PLIB_USB_OTG_VBusDischargeEnable function 5-3254 PLIB_USB_OTG_VBusPowerOff function 5-3255 PLIB_USB_OTG_VBusPowerOn function 5-3255 PLIB_USB_OTG_VBusValid function 5-3256 PLIB_USB_PacketTransferDisable function 5-3262 PLIB_USB_PacketTransferEnable function 5-3263 PLIB_USB_PacketTransferIsDisabled function 5-3263 PLIB_USB_PingPongFreeze function 5-3276 PLIB_USB_PingPongModeGet function 5-3195 PLIB_USB_PingPongModeSelect function 5-3196 PLIB_USB_PingPongReset function 5-3276 PLIB_USB_PingPongUnfreeze function 5-3277 PLIB_USB_PWMCounterDisable function 5-3268 PLIB_USB_PWMCounterEnable function 5-3268 9 MPLAB Harmony Help rrr PLIB_USB_PWMDisable function 5-3269 PLIB_USB_PWMEnable function 5-3269 PLIB_USB_PWMPolaritiyActiveLow function 5-3270 PLIB_USB_PWMPolarityActiveHigh function 5-3270 PLIB_USB_ResetSignalDisable function 5-3246 PLIB_USB_ResetSignalEnable function 5-3247 PLIB_USB_ResumeSignalingDisable function 5-3248 PLIB_USB_ResumeSignalingEnable function 5-3248 PLIB_USB_SE0InProgress function 5-3264 PLIB_USB_SleepGuardDisable function 5-3197 PLIB_USB_SleepGuardEnable function 5-3197 PLIB_USB_SOFDisable function 5-3241 PLIB_USB_SOFEnable function 5-3242 PLIB_USB_SOFThresholdGet function 5-3242 PLIB_USB_SOFThresholdSet function 5-3243 PLIB_USB_StopInIdleDisable function 5-3198 PLIB_USB_StopInIdleEnable function 5-3198 PLIB_USB_SuspendDisable function 5-3199 PLIB_USB_SuspendEnable function 5-3199 PLIB_USB_TokenEPGet function 5-3244 PLIB_USB_TokenEPSet function 5-3244 PLIB_USB_TokenPIDGet function 5-3245 PLIB_USB_TokenPIDSet function 5-3245 PLIB_USB_TokenSend function 5-3277 PLIB_USB_TokenSpeedSelect function 5-3246 PLIB_USB_TransceiverDisable function 5-3266 PLIB_USB_TransceiverEnable function 5-3266 PLIB_USB_UOEMonitorDisable function 5-3200 PLIB_USB_UOEMonitorEnable function 5-3200 PLIB_USB_VBoostDisable function 5-3271 PLIB_USB_VBoostEnable function 5-3271 PLIB_USB_VBUSComparatorDisable function 5-3272 PLIB_USB_VBUSComparatorEnable function 5-3272 PLIB_USB_VBUSPullUpDisable function 5-3273 PLIB_USB_VBUSPullUpEnable function 5-3273 plib_wdt.h 5-3330 PLIB_WDT_Disable function 5-3323 PLIB_WDT_Enable function 5-3324 PLIB_WDT_ExistsEnableControl function 5-3328 PLIB_WDT_ExistsPostscalarValue function 5-3328 PLIB_WDT_ExistsTimerClear function 5-3329 PLIB_WDT_ExistsWindowEnable function 5-3329 PLIB_WDT_IsEnabled function 5-3326 PLIB_WDT_PostscalarValueGet function 5-3327 PLIB_WDT_TimerClear function 5-3325 PLIB_WDT_WindowDisable function 5-3324 PLIB_WDT_WindowEnable function 5-3325 PMP Peripheral Library 5-2478 PMP_ACK_MODE enumeration 5-2546 PMP_ADDRESS_HOLD_LATCH_WAIT_STATES enumeration 5-2546 PMP_ADDRESS_LATCH enumeration 5-2547 PMP_ADDRESS_LATCH_WAIT_STATES enumeration 5-2547 PMP_ADDRESS_PORT enumeration 5-2548 PMP_ALTERNATE_MASTER_WAIT_STATES enumeration 5-2549 PMP_CHIP_SELECT enumeration 5-2549 PMP_CHIPSELECT_FUNCTION enumeration 5-2550 PMP_DATA_HOLD_STATES enumeration 5-2550 PMP_DATA_LENGTH enumeration 5-2551 PMP_DATA_SIZE enumeration 5-2551 PMP_DATA_WAIT_STATES enumeration 5-2551 PMP_INCREMENT_MODE enumeration 5-2552 PMP_INPUT_BUFFER_TYPE enumeration 5-2552 PMP_INTERRUPT_MODE enumeration 5-2553 PMP_MASTER_MODE enumeration 5-2553 PMP_MODULE_ID enumeration 5-2554 PMP_MUX_MODE enumeration 5-2554 PMP_OPERATION_MODE enumeration 5-2555 PMP_PMBE_PORT enumeration 5-2555 PMP_POLARITY_LEVEL enumeration 5-2556 PMP_STROBE_WAIT_STATES enumeration 5-2556 Porting Applications from the MLA Graphics Library to the MPLAB Harmony Graphics Library 5-686 Porting Applications from the V6 Beta TCP/IP Stack to the MPLAB Harmony TCP/IP Stack 5-3557 Porting the MPLAB Harmony Drivers and Peripheral Library 5-3565 Ports Change Notification 5-2599 Ports Control 5-2598, 5-3471 9 MPLAB Harmony Help sss Ports Function Remap 5-2599 Ports Peripheral Library 5-2593 Ports System Service Library 5-3465 PORTS_ANALOG_PIN enumeration 5-2629 PORTS_BIT_POS enumeration 5-2631 PORTS_CHANGE_NOTICE_PIN enumeration 5-2632 PORTS_CHANNEL enumeration 5-2635 PORTS_DATA_MASK type 5-2636 PORTS_DATA_TYPE type 5-2636 PORTS_MODULE_ID enumeration 5-2636 PORTS_PERIPHERAL_OD enumeration 5-2637 PORTS_PIN enumeration 5-2638 PORTS_PIN_MODE enumeration 5-2638 PORTS_REMAP_FUNCTION enumeration 5-2639 PORTS_REMAP_INPUT_FUNCTION enumeration 5-2642 PORTS_REMAP_INPUT_PIN enumeration 5-2643 PORTS_REMAP_OUTPUT_FUNCTION enumeration 5-2644 PORTS_REMAP_OUTPUT_PIN enumeration 5-2645 PORTS_REMAP_PIN enumeration 5-2646 Power Peripheral Library 5-2662 POWER_MODULE enumeration 5-2677 POWER_MODULE_ID enumeration 5-2680 Power-Saving Modes 5-1374, 5-1672, 5-2822 Prefetch Cache Peripheral Library 5-2427 Prefetch Control Operations 5-2433 Prefetch Status Operations 5-2433 Previous Versions 5-3964 primitive_demo 3-87 primitiveTaskImage variable 5-888 PRIV_LOCALIZED_PASSWORD_KEY_LEN macro 5-3827 Project Layout 1-10 PUTIMAGE_PARAM structure 5-939 PWM Mode with Enabled Faults 5-2293 Q Queue Operation 5-1319 QUEUE_ELEMENT_OBJECT type 5-393 R RdiaCosine function 5-797 RdiaSine function 5-798 REACHABLE_TIME macro 5-3803 Reading a Capture Value 5-2174 Reading a File 5-3394 Reboot TCP/IP Stack Library 5-3806 REBOOT_PORT macro 5-3808 REBOOT_SAME_SUBNET_ONLY macro 5-3808 Receive 5-1919 Receive Filtering Overview 5-1912 Receiving a CAN Message 5-1562 Receiving a Report 5-4140 Receiving Data 5-4074 recv function 5-3605 recvfrom function 5-3606 RED macro 5-1049 Reduced Media Independent Interface (RMII) 5-1910 Release Contents 1-25 Release Notes 1-23, 2-40, 3-64, 3-84, 3-99, 3-102, 3-113, 3-123, 3-130, 3-142, 3-149, 4-178, 5-194, 5-227, 5-254, 5-289, 5-299, 5-309, 5-320, 5-333, 5-343, 5-367, 5-397, 5-419, 5-457, 5-511, 5-552, 5-601, 5-680, 5-695, 5-1110, 5-1127, 5-1167, 5-1275, 5-1312, 5-1362, 5-1472, 5-1520, 5-1554, 5-1668, 5-1734, 5-1865, 5-1904, 5-2060, 5-2171, 5-2203, 5-2253, 5-2288, 5-2331, 5-2428, 5-2478, 5-2594, 5-2662, 5-2688, 5-2704, 5-2762, 5-2799, 5-2892, 5-3011, 5-3086, 5-3170, 5-3320, 5-3348, 5-3363, 5-3377, 5-3419, 5-3439, 5-3466, 5-3500, 5-3530, 5-3536, 5-3546, 5-3570, 5-3575, 5-3598, 5-3615, 5-3625, 5-3637, 5-3646, 5-3654, 5-3659, 5-3690, 5-3698, 5-3709, 5-3718, 5-3748, 5-3771, 5-3795, 5-3799, 5-3806, 5-3809, 5-3822, 5-3858, 5-3868, 5-3881, 5-3913, 5-3917, 5-3930, 5-3955, 5-3964, 5-3978, 5-4004, 5-4060, 5-4100, 5-4131, 5-4169, 5-4180, 5-4200, 6-4226, 7-4230, 7-4232, 7-4234, 7-4236 Release Types 1-30 Rendering 5-698 RequestEntirePaletteChange macro 5-1049 RequestPaletteChange function 5-876 Required Hardware 3-103, 3-124, 3-143 Reset Peripheral Library 5-2687 RESET_CONFIG_REG_READ_ERROR enumeration 5-2695 RESET_MODULE_ID enumeration 5-2694 9 MPLAB Harmony Help ttt RESET_NMI_COUNT_TYPE type 5-2695 RESET_NMI_REASON enumeration 5-2695 RETRANS_TIMER macro 5-3803 RTCC Mode Operations 5-2708 RTCC Peripheral Library 5-2703 RTCC_ALARM_MASK_CONFIGURATION enumeration 5-2747 RTCC_MODULE_ID enumeration 5-2748 RTCC_VALUE_REGISTER_POINTER enumeration 5-2748 RTOS Demonstrations 3-113 RTR_SOLICITATION_INTERVAL macro 5-3804 Running the Application 3-111, 3-128, 3-147 Running the Configurator Plug-in 2-44 Running the Demonstration 3-67, 3-70, 3-72, 3-74, 3-76, 3-86, 3-88, 3-90, 3-91, 3-115, 3-116, 3-118, 3-131, 3-133, 3-135, 3-153, 3-155, 3-156, 3-159, 3-160, 3-161, 3-162, 3-164, 3-165, 3-167, 3-168, 3-170 S S1D13517 Data Types and Constants 5-331 S1D13517 Graphics Controller Driver Library 5-319 SADDLEBROWN macro 5-1049 Sample Code 5-1912 SAT16 function 5-1263 SAT16N function 5-1264 SAT16P function 5-1264 SB_MODULE_ID enumeration 5-2786 SCAN_BS_PRESSED macro 5-1049 SCAN_BS_RELEASED macro 5-1050 SCAN_CR_PRESSED macro 5-1050 SCAN_CR_RELEASED macro 5-1050 SCAN_CRA_PRESSED macro 5-1050 SCAN_CRA_RELEASED macro 5-1050 SCAN_DEL_PRESSED macro 5-1050 SCAN_DEL_RELEASED macro 5-1051 SCAN_DOWN_PRESSED macro 5-1051 SCAN_DOWN_RELEASED macro 5-1051 SCAN_END_PRESSED macro 5-1051 SCAN_END_RELEASED macro 5-1051 SCAN_HOME_PRESSED macro 5-1051 SCAN_HOME_RELEASED macro 5-1051 SCAN_LEFT_PRESSED macro 5-1052 SCAN_LEFT_RELEASED macro 5-1052 SCAN_PGDOWN_PRESSED macro 5-1052 SCAN_PGDOWN_RELEASED macro 5-1052 SCAN_PGUP_PRESSED macro 5-1052 SCAN_PGUP_RELEASED macro 5-1052 SCAN_RIGHT_PRESSED macro 5-1053 SCAN_RIGHT_RELEASED macro 5-1053 SCAN_SPACE_PRESSED macro 5-1053 SCAN_SPACE_RELEASED macro 5-1053 SCAN_TAB_PRESSED macro 5-1053 SCAN_TAB_RELEASED macro 5-1053 SCAN_UP_PRESSED macro 5-1053 SCAN_UP_RELEASED macro 5-1054 Scheme Functionality 5-701 sd_card_fat_single_disk 3-69 SDCARD_MAX_LIMIT macro 5-415 Secure Digital (SD) Card Driver Library 5-397 Semaphores 5-1318 send function 5-3607 Sending a Report 5-4139 Sending Data 5-4072 sendto function 5-3607 Service Discovery 5-3957 SET_PA6_AS_OUTPUT macro 5-674 SetEntirePalette macro 5-1054 SetPalette function 5-876 SetPaletteBpp function 5-877 SetPaletteFlash function 5-877 Setting Bus Speed 5-1558 SHOW_DATA macro 5-1054 SIENNA macro 5-1054 SIN45 macro 5-1055 Single Compare Set High Mode 5-2291 Single Compare Toggle Mode 5-2292 Slave Mode 5-2821 SMI_SCAN_DATA_STATUS enumeration 5-285 SMTP Client Examples 5-3810 SMTP Client Long Message Example 5-3812 9 MPLAB Harmony Help uuu SMTP Client Short Message Example 5-3811 SMTP TCP/IP Stack Library 5-3809 smtp.h 5-3821 SMTP_CLIENT_MODULE_CONFIG structure 5-3820 smtp_config.h 5-3822 SMTP_CONNECT_ERROR macro 5-3819 SMTP_POINTERS structure 5-3820 SMTP_PORT macro 5-3814 SMTP_RESOLVE_ERROR macro 5-3819 SMTP_SERVER_REPLY_TIMEOUT macro 5-3814 SMTP_SUCCESS macro 5-3820 SNMP TCP/IP Stack Library 5-3822 snmp.h 5-3854 SNMP_BIB_FILE_NAME macro 5-3827 SNMP_BUFFER_DATA structure 5-3848 SNMP_COMMUNITY_MAX_LEN macro 5-3827 SNMP_COMMUNITY_TYPE enumeration 5-3848 snmp_config.h 5-3855 SNMP_END_OF_VAR macro 5-3846 SNMP_H macro 5-3846 SNMP_ID type 5-3849 SNMP_INDEX type 5-3849 SNMP_INDEX_INVALID macro 5-3847 SNMP_MAX_COMMUNITY_SUPPORT macro 5-3827 SNMP_MAX_MSG_SIZE macro 5-3828 SNMP_MAX_NON_REC_ID_OID macro 5-3828 SNMP_MODULE_CONFIG structure 5-3849 SNMP_NET_CONFIG structure 5-3831 SNMP_NON_MIB_RECD_INFO structure 5-3849 SNMP_NOTIFY_INFO structure 5-3849 SNMP_PROCESSING_MEM_INFO_PTRS structure 5-3850 SNMP_READ_COMMUNITIES macro 5-3828 SNMP_STACK_DCPT_STUB structure 5-3850 SNMP_START_OF_VAR macro 5-3847 SNMP_TRAP_COMMUNITY_MAX_LEN_MEM_USE macro 5-3828 SNMP_TRAP_INFO structure 5-3850 SNMP_TRAP_IP_ADDRESS_TYPE enumeration 5-3851 SNMP_V1 macro 5-3847 SNMP_V2C macro 5-3847 SNMP_V3 macro 5-3847 SNMP_VAL union 5-3851 SNMP_WRITE_COMMUNITIES macro 5-3828 SNMPGetExactIndex function 5-3841 SNMPGetNextIndex function 5-3841 SNMPGetVar function 5-3842 SNMPIsValidSetLen function 5-3842 SNMPSendTrap function 5-3843 SNMPSetVar function 5-3843 snmpv3.h 5-3856 SNMPV3_AUTH_LOCALIZED_PASSWORD_KEY_LEN_MEM_ USE macro 5-3829 snmpv3_config.h 5-3857 SNMPV3_PRIV_LOCALIZED_PASSWORD_KEY_LEN_MEM_ USE macro 5-3829 SNMPV3_PROCESSING_MEM_INFO_PTRS structure 5-3852 SNMPV3_STACK_DCPT_STUB structure 5-3852 SNMPV3_TRAP_MSG_PROCESS_MODEL_DB macro 5-3829 SNMPV3_TRAP_SECURITY_LEVEL_DB macro 5-3829 SNMPV3_TRAP_SECURITY_MODEL_TYPE_DB macro 5-3829 SNMPV3_TRAP_USER_SECURITY_NAME_DB macro 5-3829 SNMPV3_USER_AUTH_PASSWD_DB macro 5-3830 SNMPV3_USER_AUTH_TYPE_DB macro 5-3830 SNMPV3_USER_PRIV_PASSWD_DB macro 5-3830 SNMPV3_USER_PRIV_TYPE_DB macro 5-3830 SNMPV3_USER_SECURITY_NAME_DB macro 5-3830 SNMPV3_USER_SECURITY_NAME_LEN_MEM_USE macro 5-3830 SNMPV3_USM_MAX_USER macro 5-3831 SNMPv3ComputeHMACIpadOpadForAuthLoclzedKey function 5-3845 SNMPv3USMAuthPrivPswdLocalization function 5-3845 SNMPValidateCommunity function 5-3844 SNTP TCP/IP Stack Library 5-3858 sntp.h 5-3866 sntp_config.h 5-3867 SNTP_MODULE_CONFIG structure 5-3865 SNTP_RESULT enumeration 5-3865 SOCK_DGRAM macro 5-3610 9 MPLAB Harmony Help vvv SOCK_STREAM macro 5-3610 sockaddr structure 5-3612 SOCKADDR type 5-3611 sockaddr_in structure 5-3612 SOCKADDR_IN type 5-3611 socket function 5-3608 SOCKET type 5-3611 SOCKET_CNXN_IN_PROGRESS macro 5-3610 SOCKET_DISCONNECTED macro 5-3610 SOCKET_ERROR macro 5-3610 Software Drivers 5-299 Source Files to Include 5-3973 Source Interrupt Management 5-3423 Source/Destination/Peripheral Address Management 5-1745 Source/Destination/Peripheral Data Management 5-1746 Special Considerations 5-2600, 5-3473 Special Function Modules (CRC) 5-1747 SPI Driver Demonstrations 3-123 SPI Driver Library 5-417 SPI Error Handling 5-2823 SPI Master Mode and Frame Master Mode 5-2811 SPI Master Mode and Frame Slave Mode 5-2812 SPI Master Mode Clock Frequency 5-2823 SPI Peripheral Library 5-2798 SPI Receive-only Operation 5-2823 SPI Slave Mode and Frame Master Mode 5-2814, 5-2815 SPI_AUDIO_COMMUNICATION_WIDTH enumeration 5-2859 SPI_AUDIO_ERROR enumeration 5-2859 SPI_AUDIO_PROTOCOL enumeration 5-2859 SPI_AUDIO_TRANSMIT_MODE enumeration 5-2860 SPI_BAUD_RATE_CLOCK enumeration 5-2860 SPI_CLOCK_POLARITY enumeration 5-2860 SPI_COMMUNICATION_WIDTH enumeration 5-2861 SPI_DATA_TYPE type 5-2861 SPI_ERROR_INTERRUPT enumeration 5-2861 SPI_FIFO_INTERRUPT enumeration 5-2862 SPI_FIFO_TYPE enumeration 5-2863 SPI_FRAME_PULSE_DIRECTION enumeration 5-2863 SPI_FRAME_PULSE_EDGE enumeration 5-2863 SPI_FRAME_PULSE_POLARITY enumeration 5-2864 SPI_FRAME_PULSE_WIDTH enumeration 5-2864 SPI_FRAME_SYNC_PULSE enumeration 5-2864 SPI_INPUT_SAMPLING_PHASE enumeration 5-2865 SPI_MODULE_ID enumeration 5-2865 SPI_OUTPUT_DATA_PHASE enumeration 5-2866 SPI_PIN enumeration 5-2866 SPI_PRESCALE_PRIMARY enumeration 5-2867 SPI_PRESCALE_SECONDARY enumeration 5-2867 SQI Peripheral Library 5-2891 SQI_ADDR_BYTES enumeration 5-2966 SQI_BD_CTRL_WORD enumeration 5-2966 SQI_BD_STATE enumeration 5-2967 SQI_CLK_DIV enumeration 5-2968 SQI_CS_NUM enumeration 5-2969 SQI_CS_OEN enumeration 5-2969 SQI_DATA_FORMAT enumeration 5-2969 SQI_DATA_MODE enumeration 5-2970 SQI_DATA_OEN enumeration 5-2970 SQI_DATA_TYPE type 5-2970 SQI_DUMMY_BYTES enumeration 5-2971 SQI_INTERRUPTS enumeration 5-2971 SQI_LANE_MODE enumeration 5-2972 SQI_MODE_BYTES enumeration 5-2972 SQI_MODULE_ID enumeration 5-2973 SQI_XFER_CMD enumeration 5-2973 SQI_XFER_MODE enumeration 5-2974 ssd_demo 3-90 SSD1926 Graphics Controller Driver Library 5-333 SSL Client Support 5-3869 SSL Limitations 5-3870 SSL Server Support 5-3870 SSL TCP/IP Stack Library 5-3867 ssl.h 5-3879 ssl_config.h 5-3880 SSL_MAX_BUFFERS macro 5-3873 SSL_MAX_CONNECTIONS macro 5-3873 SSL_MAX_HASHES macro 5-3873 SSL_MAX_SESSIONS macro 5-3874 9 MPLAB Harmony Help www SSL_MIN_SESSION_LIFETIME macro 5-3874 SSL_MODULE_CONFIG structure 5-3879 SSL_MULTIPLE_INTERFACES macro 5-3874 SSL_RSA_CLIENT_SIZE macro 5-3874 SSL_RSA_KEY_SIZE macro 5-3874 SSL_RSA_LIFETIME_EXTENSION macro 5-3874 SSL_VERSION macro 5-3875 SSL_VERSION_HI macro 5-3875 SSL_VERSION_LO macro 5-3875 Standard ID Message Format 5-1555 Standard Master Mode 5-2804 Standard Slave Mode 5-2805 Standard SPI Mode 5-2804 Start Here 1-1 State Machine 5-2255, 5-2485, 5-2707, 5-2802, 5-3088 State-Driven Applications 3-101 States 5-698 Static Configuration 5-3425 Status (including Channel) 5-1748 Support for Legacy "Ethernet Controller Library" 5-232, 5-1920 Supported Demonstration Boards 3-67, 3-69, 3-71, 3-73, 3-75, 3-86, 3-87, 3-89, 3-90, 3-103, 3-114, 3-115, 3-116, 3-117, 3-124, 3-143, 3-153, 3-154, 3-156, 3-158, 3-160, 3-161, 3-162, 3-164, 3-166, 3-167, 3-169 Supported Hardware 3-131, 3-133, 3-135 Supported Libraries 4-181 SW License Agreement 2-41, 3-64, 3-85, 3-99, 3-102, 3-113, 3-123, 3-130, 3-142, 3-150, 5-194, 5-227, 5-254, 5-289, 5-299, 5-309, 5-320, 5-334, 5-343, 5-368, 5-398, 5-419, 5-458, 5-512, 5-553, 5-606, 5-680, 5-695, 5-1111, 5-1128, 5-1168, 5-1276, 5-1312, 5-1362, 5-1472, 5-1520, 5-1554, 5-1668, 5-1734, 5-1865, 5-1904, 5-2060, 5-2172, 5-2203, 5-2253, 5-2289, 5-2331, 5-2428, 5-2479, 5-2594, 5-2663, 5-2688, 5-2705, 5-2762, 5-2799, 5-2892, 5-3012, 5-3086, 5-3170, 5-3320, 5-3348, 5-3363, 5-3377, 5-3420, 5-3439, 5-3466, 5-3501, 5-3530, 5-3539, 5-3546, 5-3570, 5-3575, 5-3598, 5-3615, 5-3625, 5-3637, 5-3647, 5-3655, 5-3660, 5-3690, 5-3698, 5-3709, 5-3718, 5-3748, 5-3771, 5-3795, 5-3799, 5-3806, 5-3809, 5-3822, 5-3859, 5-3868, 5-3881, 5-3913, 5-3918, 5-3931, 5-3955, 5-3966, 5-3978, 5-4005, 5-4061, 5-4101, 5-4131, 5-4169, 5-4180, 5-4200, 6-4226, 7-4230, 7-4232, 7-4234, 7-4236 Sync Mode Selection 5-463 Synchronizing Timer 5-2174 Synchronous External Clock Counter 5-3016 Synchronous Internal Clock Counter 5-3015 Synchronous Master Mode 5-3095 Synchronous Slave Mode 5-3097 sys_clk.h 5-3362 SYS_CLK_ClockFailureCallbackRegister function 5-3353 SYS_CLK_ClockFrequencyGet function 5-3355 SYS_CLK_ClockFrequencySet function 5-3355 SYS_CLK_ClockIsReady function 5-3356 SYS_CLK_FRCTune function 5-3356 SYS_CLK_FRCTUNING_DATA structure 5-3358 SYS_CLK_FRCTuningSet function 5-3357 SYS_CLK_INIT structure 5-3358 SYS_CLK_Initialize function 5-3354 SYS_CLK_MZPeriphBusFreqGet function 5-3357 SYS_CLK_OUTPUT enumeration 5-3359 SYS_CLK_SOURCE enumeration 5-3360 sys_common.h 5-3345 sys_devcon.h 5-3375 sys_devcon_config.h 5-3375 SYS_DEVCON_Deinitialize function 5-3369 SYS_DEVCON_HANDLE type 5-3373 SYS_DEVCON_INDEX_0 macro 5-3374 SYS_DEVCON_INIT structure 5-3374 SYS_DEVCON_Initialize function 5-3369 SYS_DEVCON_PerformanceConfig function 5-3370 SYS_DEVCON_PIC32MX_MAX_PB_FREQ macro 5-3368 SYS_DEVCON_PRIMARY_CLOCK macro 5-3368 SYS_DEVCON_Reinitialize function 5-3371 SYS_DEVCON_Status function 5-3371 SYS_DEVCON_SYSTEM_CLOCK macro 5-3368 SYS_DEVCON_Tasks function 5-3372 sys_fs.h 5-3418 SYS_FS_ERROR enumeration 5-3411 SYS_FS_FILE_OPEN_ATTRIBUTES enumeration 5-3412 SYS_FS_FILE_SEEK_CONTROL enumeration 5-3413 SYS_FS_FILE_SYSTEM_TYPE enumeration 5-3414 SYS_FS_FileClose function 5-3398 SYS_FS_FileEOF function 5-3399 SYS_FS_FileError function 5-3407 SYS_FS_FileNameGet function 5-3406 9 MPLAB Harmony Help xxx SYS_FS_FileOpen function 5-3400 SYS_FS_FileRead function 5-3401 SYS_FS_FileSeek function 5-3401 SYS_FS_FileSize function 5-3402 SYS_FS_FileStat function 5-3403 SYS_FS_FileTell function 5-3404 SYS_FS_FileWrite function 5-3405 SYS_FS_FSTAT structure 5-3414 SYS_FS_FUNCTIONS structure 5-3415 SYS_FS_HANDLE type 5-3416 SYS_FS_HANDLE_INVALID macro 5-3417 SYS_FS_Initialize function 5-3407 SYS_FS_Mount function 5-3408 SYS_FS_REGISTRATION_TABLE structure 5-3416 SYS_FS_RESULT enumeration 5-3416 SYS_FS_Tasks 5-3397 SYS_FS_Tasks function 5-3410 SYS_FS_Unmount function 5-3410 SYS_Initialize function 5-3373 sys_int.h 5-3437 SYS_INT_Disable function 5-3429 SYS_INT_DynamicDeregister function 5-3428 SYS_INT_DynamicRegister function 5-3428 SYS_INT_Enable function 5-3430 SYS_INT_Initialize function 5-3427 SYS_INT_IsEnabled function 5-3430 SYS_INT_SourceDisable function 5-3431 SYS_INT_SourceEnable function 5-3432 SYS_INT_SourceIsEnabled function 5-3432 SYS_INT_SourceStatusClear function 5-3433 SYS_INT_SourceStatusGet function 5-3433 SYS_INT_SourceStatusSet function 5-3434 SYS_INT_TASKS_POINTER type 5-3437 SYS_INT_VectorPrioritySet function 5-3435 SYS_INT_VectorSubprioritySet function 5-3436 SYS_MEDIA_EVENT enumeration 5-415 sys_module.h 5-3346 SYS_MODULE_DATA structure 5-3334 SYS_MODULE_DEINITIALIZE_ROUTINE type 5-3335 SYS_MODULE_INDEX type 5-3335 SYS_MODULE_INIT union 5-3335 SYS_MODULE_INITIALIZE_ROUTINE type 5-3336 SYS_MODULE_INTERFACE structure 5-3337 SYS_MODULE_OBJ type 5-3338 SYS_MODULE_OBJ_INVALID macro 5-3342 SYS_MODULE_OBJ_STATIC macro 5-3343 SYS_MODULE_POWER_IDLE_RUN macro 5-3343 SYS_MODULE_POWER_IDLE_STOP macro 5-3343 SYS_MODULE_POWER_OFF macro 5-3344 SYS_MODULE_POWER_RUN_FULL macro 5-3344 SYS_MODULE_POWER_SLEEP macro 5-3344 SYS_MODULE_REINITIALIZE_ROUTINE type 5-3338 SYS_MODULE_STATUS_ROUTINE type 5-3339 SYS_MODULE_TASKS_DATA structure 5-3339 SYS_MODULE_TASKS_ROUTINE type 5-3340 SYS_MSB_MailboxClose function 5-3449 SYS_MSB_MailboxOpen function 5-3449 SYS_MSB_MailboxReinit function 5-3450 sys_msg.h 5-3463 SYS_MSG_BUFFER_SIZES macro 5-3458 sys_msg_config.h 5-3464 SYS_MSG_Deinitialize function 5-3445 SYS_MSG_GotMessages function 5-3454 SYS_MSG_ID2hMsgType function 5-3456 SYS_MSG_INIT structure 5-3459 SYS_MSG_Initialize function 5-3446 SYS_MSG_INSTANCE enumeration 5-3460 SYS_MSG_MAILBOXES_ADDONE macro 5-3462 SYS_MSG_MailboxMessagesGet function 5-3450 SYS_MSG_MailboxMsgAdd function 5-3451 SYS_MSG_MailboxMsgRemove function 5-3452 SYS_MSG_MAX_MAILBOXES macro 5-3458 SYS_MSG_MAX_MSGS_DELIVERED macro 5-3458 SYS_MSG_MAX_PRIORITY macro 5-3459 SYS_MSG_MAX_TYPES macro 5-3459 SYS_MSG_MessageDeliver function 5-3454 SYS_MSG_MessageReceive function 5-3455 SYS_MSG_MessageSend function 5-3456 9 MPLAB Harmony Help yyy SYS_MSG_NUM_MAILBOX_BITMAPS macro 5-3463 SYS_MSG_OBJECT structure 5-3460 SYS_MSG_QUEUE_STATUS enumeration 5-3461 SYS_MSG_QueueStatus function 5-3457 SYS_MSG_RECEIVE_CALLBACK type 5-3461 SYS_MSG_RESULTS enumeration 5-3461 SYS_MSG_Tasks function 5-3447 SYS_MSG_TypeCreate function 5-3453 SYS_MSG_TypeRemove function 5-3453 SYS_MSG_VersionGet function 5-3447 SYS_MSG_VersionStrGet function 5-3448 SYS_MSGQ_ELEMENT structure 5-3462 SYS_OBJ_HANDLE type 5-286 SYS_OBJ_HANDLE_INVALID macro 5-286 SYS_OBJ_HANDLE_STATIC macro 5-286 sys_ports.h 5-3498 SYS_PORTS_ChangeNotificationDisable function 5-3489 SYS_PORTS_ChangeNotificationEnable function 5-3489 SYS_PORTS_ChangeNotificationGlobalDisable function 5-3490 SYS_PORTS_ChangeNotificationGlobalEnable function 5-3490 SYS_PORTS_ChangeNotificationInIdleModeDisable function 5-3491 SYS_PORTS_ChangeNotificationInIdleModeEnable function 5-3491 SYS_PORTS_ChangeNotificationPullDownDisable function 5-3491 SYS_PORTS_ChangeNotificationPullDownEnable function 5-3492 SYS_PORTS_ChangeNotificationPullUpDisable function 5-3493 SYS_PORTS_ChangeNotificationPullUpEnable function 5-3493 SYS_PORTS_ChangeNotificationStatus function 5-3494 SYS_PORTS_Clear function 5-3482 SYS_PORTS_DirectionGet function 5-3483 SYS_PORTS_DirectionSelect function 5-3483 SYS_PORTS_IOLockDisable function 5-3494 SYS_PORTS_IOLockEnable function 5-3495 SYS_PORTS_IOLockIsActive function 5-3495 SYS_PORTS_OpenDrainDisable function 5-3484 SYS_PORTS_OpenDrainEnable function 5-3484 SYS_PORTS_PIN_DIRECTION enumeration 5-3497 SYS_PORTS_PinClear function 5-3481 SYS_PORTS_PinDirectionSelect function 5-3481 SYS_PORTS_PinModeSelect function 5-3476 SYS_PORTS_PinOpenDrainDisable function 5-3476 SYS_PORTS_PinOpenDrainEnable function 5-3477 SYS_PORTS_PinPullUpDisable function 5-3477 SYS_PORTS_PinPullUpEnable function 5-3478 SYS_PORTS_PinRead function 5-3479 SYS_PORTS_PinSet function 5-3479 SYS_PORTS_PinToggle function 5-3480 SYS_PORTS_PinWrite function 5-3480 SYS_PORTS_PULLUP_PULLDOWN_STATUS enumeration 5-3497 SYS_PORTS_PullUpDisable function 5-3485 SYS_PORTS_PullUpEnable function 5-3486 SYS_PORTS_Read function 5-3486 SYS_PORTS_RemapInput function 5-3496 SYS_PORTS_RemapOutput function 5-3496 SYS_PORTS_Set function 5-3487 SYS_PORTS_Toggle function 5-3487 SYS_PORTS_Write function 5-3488 SYS_STATUS enumeration 5-3340 SYS_Tasks function 5-3333 SYS_TASKS_PRIORITY enumeration 5-3341 SYS_TASKS_PRIORITY_HIGH enumeration member 5-3341 SYS_TASKS_PRIORITY_INVALID enumeration member 5-3341 SYS_TASKS_PRIORITY_LOW enumeration member 5-3341 SYS_TASKS_PRIORITY_MEDIUM enumeration member 5-3341 sys_tmr.h 5-3528 SYS_TMR_AlarmPeriodGet function 5-3525 SYS_TMR_CALLBACK type 5-3525 SYS_TMR_CallbackPeriodic function 5-3522 SYS_TMR_CallbackSingle function 5-3523 SYS_TMR_CallbackStop function 5-3523 sys_tmr_config.h 5-3529 SYS_TMR_Deinitialize function 5-3518 SYS_TMR_DELAY_STATUS enumeration 5-3526 SYS_TMR_DelayMS function 5-3524 SYS_TMR_DelayStatusGet function 5-3524 9 MPLAB Harmony Help zzz SYS_TMR_ERROR_TOLERANCE macro 5-3516 SYS_TMR_HANDLE type 5-3526 SYS_TMR_HANDLE_INVALID macro 5-3527 SYS_TMR_INDEX_0 macro 5-3527 SYS_TMR_INIT structure 5-3526 SYS_TMR_Initialize function 5-3519 SYS_TMR_INTERRUPT_MODE macro 5-3516 SYS_TMR_MAX_PERIODIC_EVENTS macro 5-3517 SYS_TMR_Reinitialize function 5-3520 SYS_TMR_RUNNING macro 5-3527 SYS_TMR_SINGLE_PERIODIC_EVENT macro 5-3517 SYS_TMR_Status function 5-3521 SYS_TMR_Tasks function 5-3521 SYS_TMR_TickCountGet function 5-3525 sys_wdt.h 5-3534 sys_wdt_config.h 5-3535 SYS_WDT_Disable function 5-3533 SYS_WDT_Enable function 5-3533 SYS_WDT_TimerClear function 5-3533 System Access 5-421 System Bus Peripheral Library 5-2762 System Config 5-476 System Configuration 5-428, 5-3390 System Configuration Functions 5-4173 System Initialization 5-195, 5-345, 5-370, 5-514, 5-608, 7-4229 System Interaction 5-459, 5-3365, 5-3507, 5-4170 System Overview 3-63 System Service Library Help 5-3332 System Service Overview 5-3332 system.h 5-3347 system_config.h 1-16 system_init.c 1-17 system_int.c 1-19 system_tasks.c 1-19 SYSTEMConfigPerformance function 7-4240 T Table of Library Functions 5-1170, 5-1277 TAN macro 5-1055 Target Initialization 5-2765 TCP Changes 5-3548 TCP TCP/IP Stack Library 5-3880 tcp.h 5-3910 TCP/IP Demonstrations 3-130 TCP/IP Discoverer 5-3545 TCP/IP Library Overview 5-3536 TCP/IP Stack Library Help 5-3536 TCP/IP Stack Porting Guide 5-3545 TCP_ADJUST_FLAGS enumeration 5-3907 TCP_AUTO_TRANSMIT_TIMEOUT_VAL macro 5-3885 TCP_CLOSE_WAIT_TIMEOUT macro 5-3885 tcp_config.h 5-3912 TCP_DELAYED_ACK_TIMEOUT macro 5-3885 TCP_FIN_WAIT_2_TIMEOUT macro 5-3886 TCP_KEEP_ALIVE_TIMEOUT macro 5-3886 TCP_MAX_RETRIES macro 5-3886 TCP_MAX_SEG_SIZE_RX_LOCAL macro 5-3886 TCP_MAX_SEG_SIZE_RX_NON_LOCAL macro 5-3886 TCP_MAX_SEG_SIZE_TX macro 5-3887 TCP_MAX_SOCKETS macro 5-3887 TCP_MAX_SYN_RETRIES macro 5-3887 TCP_MAX_UNACKED_KEEP_ALIVES macro 5-3887 TCP_MODULE_CONFIG structure 5-3907 TCP_OPTION_LINGER_DATA structure 5-3908 TCP_PORT type 5-3908 TCP_SOCKET type 5-3908 TCP_SOCKET_DEFAULT_RX_SIZE macro 5-3887 TCP_SOCKET_DEFAULT_TX_SIZE macro 5-3888 TCP_SOCKET_INFO structure 5-3909 TCP_SOCKET_OPTION enumeration 5-3909 TCP_START_TIMEOUT_VAL macro 5-3888 TCP_TASK_TICK_RATE macro 5-3888 TCP_WINDOW_UPDATE_TIMEOUT_VAL macro 5-3888 tcpip_announce_config.h 5-3574 TCPIP_ANNOUNCE_DeInit function 5-3572 TCPIP_ANNOUNCE_Init function 5-3572 tcpip_announce_manager.h 5-3574 TCPIP_ANNOUNCE_MODULE_CONFIG structure 5-3573 9 MPLAB Harmony Help aaaa TCPIP_ANNOUNCE_Send function 5-3573 TCPIP_ANNOUNCE_Task function 5-3573 TCPIP_ANNOUNCE_TaskPending function 5-3573 TCPIP_ARP_CacheEntriesNoGet function 5-3589 TCPIP_ARP_CacheThresholdSet function 5-3590 TCPIP_ARP_CallbacksDeregister function 5-3581 TCPIP_ARP_CallbacksRegister function 5-3581 TCPIP_ARP_Deinitialize function 5-3582 TCPIP_ARP_ENTRY_QUERY structure 5-3592 TCPIP_ARP_ENTRY_TYPE enumeration 5-3592 TCPIP_ARP_EntryGet function 5-3582 TCPIP_ARP_EntryQuery function 5-3590 TCPIP_ARP_EntryRemove function 5-3583 TCPIP_ARP_EntryRemoveAll function 5-3591 TCPIP_ARP_EntryRemoveNet function 5-3584 TCPIP_ARP_EntrySet function 5-3588 TCPIP_ARP_EVENT_HANDLER type 5-3592 TCPIP_ARP_EVENT_TYPE enumeration 5-3593 TCPIP_ARP_HANDLE type 5-3593 TCPIP_ARP_HandlerDeRegister function 5-3584 TCPIP_ARP_HandlerRegister function 5-3585 TCPIP_ARP_Initialize function 5-3585 TCPIP_ARP_IsResolved function 5-3586 TCPIP_ARP_OPERATION_TYPE enumeration 5-3593 TCPIP_ARP_Probe function 5-3586 TCPIP_ARP_Process function 5-3589 TCPIP_ARP_Resolve function 5-3587 TCPIP_ARP_RESULT enumeration 5-3594 TCPIP_ARP_Task function 5-3588 TCPIP_ARP_TaskIsPending function 5-3588 TCPIP_DDNS_LastIPGet function 5-3649 TCPIP_DDNS_LastStatusGet function 5-3649 TCPIP_DDNS_ServiceSet function 5-3650 TCPIP_DDNS_UpdateForce function 5-3650 TCPIP_DHCP_Disable function 5-3618 TCPIP_DHCP_Enable function 5-3619 TCPIP_DHCP_EVENT_HANDLER type 5-3623 TCPIP_DHCP_EVENT_TYPE enumeration 5-3623 TCPIP_DHCP_HANDLE type 5-3623 TCPIP_DHCP_HandlerDeRegister function 5-3619 TCPIP_DHCP_HandlerRegister function 5-3619 TCPIP_DHCP_IsBound function 5-3621 TCPIP_DHCP_IsEnabled function 5-3621 TCPIP_DHCP_IsServerDetected function 5-3622 TCPIP_DHCP_Renew function 5-3620 TCPIP_DHCP_Request function 5-3620 TCPIP_DHCP_RequestTimeoutSet function 5-3621 TCPIP_DHCPS_Disable function 5-3630 TCPIP_DHCPS_Enable function 5-3631 TCPIP_DHCPS_GetPoolEntries function 5-3631 TCPIP_DHCPS_IsEnabled function 5-3633 TCPIP_DHCPS_LeaseEntryGet function 5-3632 TCPIP_DHCPS_RemovePoolEntries function 5-3632 TCPIP_DNS_IsResolved function 5-3641 TCPIP_DNS_Resolve function 5-3641 TCPIP_DNS_UsageBegin function 5-3642 TCPIP_DNS_UsageEnd function 5-3642 TCPIP_FTP_DATA_SKT_RX_BUFF_SIZE macro 5-3656 TCPIP_FTP_DATA_SKT_TX_BUFF_SIZE macro 5-3657 TCPIP_FTP_MAX_CONNECTIONS macro 5-3657 TCPIP_FTP_PASSWD_LEN macro 5-3657 TCPIP_FTP_PUT_ENABLED macro 5-3657 TCPIP_FTP_USER_NAME_LEN macro 5-3657 TCPIP_HTTP_ActiveConnectionCountGet function 5-3666 TCPIP_HTTP_ArgGet function 5-3667 TCPIP_HTTP_CurrentConnectionByteCountDec function 5-3668 TCPIP_HTTP_CurrentConnectionByteCountGet function 5-3668 TCPIP_HTTP_CurrentConnectionByteCountSet function 5-3669 TCPIP_HTTP_CurrentConnectionCallbackPosGet function 5-3669 TCPIP_HTTP_CurrentConnectionCallbackPosSet function 5-3670 TCPIP_HTTP_CurrentConnectionDataBufferGet function 5-3670 TCPIP_HTTP_CurrentConnectionFileGet function 5-3671 TCPIP_HTTP_CurrentConnectionHasArgsSet function 5-3671 TCPIP_HTTP_CurrentConnectionIsAuthorizedGet function 5-3672 TCPIP_HTTP_CurrentConnectionIsAuthorizedSet function 5-3672 9 MPLAB Harmony Help bbbb TCPIP_HTTP_CurrentConnectionPostSmGet function 5-3673 TCPIP_HTTP_CurrentConnectionPostSmSet function 5-3673 TCPIP_HTTP_CurrentConnectionSocketGet function 5-3674 TCPIP_HTTP_CurrentConnectionStatusSet function 5-3675 TCPIP_HTTP_CurrentConnectionUserDataGet function 5-3675 TCPIP_HTTP_CurrentConnectionUserDataSet function 5-3676 TCPIP_HTTP_FileInclude function 5-3676 TCPIP_HTTP_PostNameRead function 5-3677 TCPIP_HTTP_PostValueRead function 5-3678 TCPIP_HTTP_URLDecode function 5-3679 TCPIP_ICMP_CallbackDeregister function 5-3693 TCPIP_ICMP_CallbackRegister function 5-3693 TCPIP_ICMP_EchoRequestSend function 5-3694 TCPIP_ICMPV6_CallbackDeregister function 5-3701 TCPIP_ICMPV6_CallbackRegister function 5-3702 TCPIP_ICMPV6_Close function 5-3702 TCPIP_ICMPV6_Flush function 5-3702 TCPIP_ICMPV6_HeaderEchoRequestPut function 5-3703 TCPIP_ICMPV6_PutHeaderEchoReply macro 5-3704 TCPIP_IF_PIC32INT macro 5-262 TCPIP_IPV4_PacketFormatTx function 5-3712 TCPIP_IPV4_PacketGetDestAddress function 5-3713 TCPIP_IPV4_PacketGetSourceAddress function 5-3713 TCPIP_IPV4_PacketTransmit function 5-3714 TCPIP_IPV4_SelectSourceInterface function 5-3714 TCPIP_IPV6_AddressUnicastRemove function 5-3725 TCPIP_IPV6_ArrayGet function 5-3725 TCPIP_IPV6_ArrayPutHelper function 5-3726 TCPIP_IPV6_DASSourceAddressSelect function 5-3726 TCPIP_IPV6_DestAddressGet function 5-3727 TCPIP_IPV6_DestAddressSet function 5-3727 TCPIP_IPV6_Flush function 5-3728 TCPIP_IPV6_Get function 5-3728 TCPIP_IPV6_HandlerDeregister function 5-3728 TCPIP_IPV6_HandlerRegister function 5-3729 TCPIP_IPV6_InterfaceIsReady function 5-3729 TCPIP_IPV6_MulticastListenerAdd function 5-3730 TCPIP_IPV6_MulticastListenerRemove function 5-3730 TCPIP_IPV6_PacketFree function 5-3731 TCPIP_IPV6_PayloadSet function 5-3731 TCPIP_IPV6_Put function 5-3732 TCPIP_IPV6_PutArray macro 5-3738 TCPIP_IPV6_SourceAddressGet function 5-3732 TCPIP_IPV6_SourceAddressSet function 5-3733 TCPIP_IPV6_TxIsPutReady function 5-3733 TCPIP_IPV6_TxPacketAllocate function 5-3734 TCPIP_IPV6_UnicastAddressAdd function 5-3734 TCPIP_IPV6_UniqueLocalUnicastAddressAdd function 5-3735 TCPIP_LOCAL_MASK_TYPE enumeration 5-3793 tcpip_mac.h 5-3770 TCPIP_MAC_ACTION enumeration 5-3757 TCPIP_MAC_ADDR structure 5-3758 TCPIP_MAC_Close function 5-3753 tcpip_mac_config.h 5-3770 TCPIP_MAC_DATA_SEGMENT type 5-3758 TCPIP_MAC_Deinitialize function 5-3753 TCPIP_MAC_ETHERNET_HEADER structure 5-3758 TCPIP_MAC_EVENT enumeration 5-3758 TCPIP_MAC_EventAcknowledge function 5-3753 TCPIP_MAC_EventF type 5-3760 TCPIP_MAC_EventMaskSet function 5-3753 TCPIP_MAC_EventPendingGet function 5-3754 TCPIP_MAC_HANDLE type 5-3761 TCPIP_MAC_HEAP_CallocF type 5-3761 TCPIP_MAC_HEAP_FreeF type 5-3761 TCPIP_MAC_HEAP_HANDLE type 5-3762 TCPIP_MAC_HEAP_MallocF type 5-3762 TCPIP_MAC_Initialize function 5-3754 TCPIP_MAC_LinkCheck function 5-3754 TCPIP_MAC_MODULE_CTRL structure 5-3762 TCPIP_MAC_Open function 5-3754 TCPIP_MAC_PACKET type 5-3763 TCPIP_MAC_PACKET_ACK_FUNC type 5-3763 TCPIP_MAC_PACKET_FLAGS enumeration 5-3763 TCPIP_MAC_PACKET_RX_STAT structure 5-3764 TCPIP_MAC_PacketRx function 5-3754 TCPIP_MAC_PacketTx function 5-3755 TCPIP_MAC_PKT_ACK_RES enumeration 5-3765 9 MPLAB Harmony Help cccc TCPIP_MAC_PKT_AckF type 5-3766 TCPIP_MAC_PKT_AllocF type 5-3766 TCPIP_MAC_PKT_FreeF type 5-3766 TCPIP_MAC_POWER_MODE enumeration 5-3766 TCPIP_MAC_Process function 5-3756 TCPIP_MAC_PROCESS_FLAGS enumeration 5-3767 TCPIP_MAC_Reinitialize function 5-3757 TCPIP_MAC_RES enumeration 5-3767 TCPIP_MAC_RxFilterHashTableEntrySet function 5-3757 TCPIP_MAC_SEGMENT_FLAGS enumeration 5-3768 tcpip_manager.h 5-3793 TCPIP_MDNS_ServiceDeregister function 5-3958 TCPIP_MDNS_ServiceRegister function 5-3959 TCPIP_MDNS_ServiceUpdate function 5-3960 TCPIP_MODULE_MAC_97J60_CONFIG structure 5-3768 TCPIP_MODULE_MAC_ENCJ60_CONFIG structure 5-3768 TCPIP_MODULE_MAC_ENCJ600_CONFIG structure 5-3769 TCPIP_MODULE_MAC_MRF24W_CONFIG structure 5-3769 TCPIP_MODULE_MAC_PIC32INT_CONFIG structure 5-3769 TCPIP_NDP_NborReachConfirm function 5-3804 TCPIP_NET_HANDLE type 5-3793 tcpip_reboot_config.h 5-3808 TCPIP_SMTP_ArrayPut function 5-3815 TCPIP_SMTP_Flush function 5-3816 TCPIP_SMTP_IsBusy function 5-3816 TCPIP_SMTP_IsPutReady function 5-3816 TCPIP_SMTP_MailSend function 5-3817 TCPIP_SMTP_Put function 5-3817 TCPIP_SMTP_PutIsDone function 5-3818 TCPIP_SMTP_StringPut function 5-3818 TCPIP_SMTP_UsageBegin function 5-3818 TCPIP_SMTP_UsageEnd function 5-3819 TCPIP_SNMP_ClientGetNet function 5-3834 TCPIP_SNMP_DataCopyToProcessBuffer function 5-3834 TCPIP_SNMP_DCPT structure 5-3851 TCPIP_SNMP_EventNotifyGet function 5-3835 TCPIP_SNMP_Notify function 5-3835 TCPIP_SNMP_NotifyIsReady function 5-3836 TCPIP_SNMP_NotifyPrepare function 5-3837 TCPIP_SNMP_PacketProcStubPtrsGet function 5-3837 TCPIP_SNMP_ProcessBufferDataGet function 5-3838 TCPIP_SNMP_ReadCommunityGet function 5-3838 TCPIP_SNMP_SM enumeration 5-3852 TCPIP_SNMP_TrapTimeGet function 5-3839 TCPIP_SNMP_WriteCommunityGet function 5-3839 TCPIP_SNMPv3_CmprTrapSecNameAndSecLvlWithUSMDb function 5-3845 TCPIP_SNMPv3_Notify function 5-3839 TCPIP_SNMPV3_PacketProcStubPtrsGet function 5-3840 TCPIP_SNTP_ConnectionInitiate function 5-3863 TCPIP_SNTP_ConnectionParamSet function 5-3863 TCPIP_SNTP_LastErrorGet function 5-3864 TCPIP_SNTP_TimeStampGet function 5-3864 TCPIP_SNTP_UTCSecondsGet function 5-3865 TCPIP_STACK_Deinitialize function 5-3774 TCPIP_STACK_IndexToNet function 5-3777 TCPIP_STACK_Initialize function 5-3774 TCPIP_STACK_ModuleGetConfig function 5-3783 TCPIP_STACK_NetAddress function 5-3784 TCPIP_STACK_NetAddressBcast function 5-3784 TCPIP_STACK_NetAddressDnsPrimary function 5-3785 TCPIP_STACK_NetAddressDnsPrimarySet function 5-3785 TCPIP_STACK_NetAddressDnsSecond function 5-3786 TCPIP_STACK_NetAddressDnsSecondSet function 5-3786 TCPIP_STACK_NetAddressGateway function 5-3787 TCPIP_STACK_NetAddressGatewaySet function 5-3787 TCPIP_STACK_NetAddressMac function 5-3788 TCPIP_STACK_NetAddressMacSet function 5-3788 TCPIP_STACK_NetAddressSet function 5-3789 TCPIP_STACK_NetBIOSName function 5-3777 TCPIP_STACK_NetBiosNameSet function 5-3778 TCPIP_STACK_NetConfigGet function 5-3790 TCPIP_STACK_NetConfigSet function 5-3791 TCPIP_STACK_NetDefaultGet function 5-3778 TCPIP_STACK_NetDefaultSet function 5-3779 TCPIP_STACK_NetDown function 5-3781 TCPIP_STACK_NetHandleGet function 5-3779 TCPIP_STACK_NetIndexGet function 5-3780 TCPIP_STACK_NetIPv6AddressGet function 5-3790 9 MPLAB Harmony Help dddd TCPIP_STACK_NetIsLinked function 5-3782 TCPIP_STACK_NetIsUp function 5-3782 TCPIP_STACK_NetMACId function 5-3792 TCPIP_STACK_NetMask function 5-3780 TCPIP_STACK_NetNameGet function 5-3780 TCPIP_STACK_NetUp function 5-3783 TCPIP_STACK_NumberOfNetworksGet function 5-3781 TCPIP_STACK_SetLocalMasks function 5-3775 TCPIP_STACK_SetLocalMasksType function 5-3776 TCPIP_STACK_Task function 5-3777 TCPIP_STACK_USE_BASE64_DECODE macro 5-3665 TCPIP_TCP_Abort function 5-3897 TCPIP_TCP_ArrayFind function 5-3901 TCPIP_TCP_ArrayGet function 5-3902 TCPIP_TCP_ArrayPeek function 5-3902 TCPIP_TCP_ArrayPut function 5-3898 TCPIP_TCP_Bind function 5-3890 TCPIP_TCP_ClientOpen function 5-3891 TCPIP_TCP_Close function 5-3891 TCPIP_TCP_Connect function 5-3892 TCPIP_TCP_Discard function 5-3903 TCPIP_TCP_Disconnect function 5-3892 TCPIP_TCP_FifoRxFreeGet function 5-3906 TCPIP_TCP_FifoRxFullGet macro 5-3906 TCPIP_TCP_FifoSizeAdjust function 5-3903 TCPIP_TCP_FifoTxFreeGet macro 5-3907 TCPIP_TCP_FifoTxFullGet function 5-3899 TCPIP_TCP_Find function 5-3904 TCPIP_TCP_Flush function 5-3899 TCPIP_TCP_Get function 5-3905 TCPIP_TCP_GetIsReady function 5-3905 TCPIP_TCP_IsConnected function 5-3893 TCPIP_TCP_OptionsGet function 5-3893 TCPIP_TCP_OptionsSet function 5-3894 TCPIP_TCP_Peek function 5-3905 TCPIP_TCP_Put function 5-3899 TCPIP_TCP_PutIsReady function 5-3900 TCPIP_TCP_RemoteBind function 5-3894 TCPIP_TCP_ServerOpen function 5-3895 TCPIP_TCP_SocketInfoGet function 5-3896 TCPIP_TCP_SocketIsSecuredBySSL function 5-3876 TCPIP_TCP_SocketNetGet function 5-3896 TCPIP_TCP_SocketNetSet function 5-3898 TCPIP_TCP_StringPut function 5-3900 TCPIP_TCP_WasReset function 5-3896 TCPIP_TCPSSL_ClientBegin function 5-3876 TCPIP_TCPSSL_ClientStart function 5-3877 TCPIP_TCPSSL_HandshakeClear function 5-3877 TCPIP_TCPSSL_ListenerAdd function 5-3878 TCPIP_TCPSSL_ServerStart function 5-3878 TCPIP_TCPSSL_StillHandshaking function 5-3879 TCPIP_TFTP_DataByteGet function 5-3922 TCPIP_TFTP_DataBytePut function 5-3923 TCPIP_TFTP_DataIsGetReady function 5-3923 TCPIP_TFTP_FileClose function 5-3923 TCPIP_TFTP_FileIsClosed function 5-3923 TCPIP_TFTP_FileIsOpen function 5-3923 TCPIP_TFTP_FragRAMFileUploadToHost function 5-3923 TCPIP_TFTP_IsOpen function 5-3924 TCPIP_TFTP_IsReadyForPut function 5-3924 TCPIP_TFTP_Open function 5-3924 TCPIP_TFTP_RAMFileUploadToHost function 5-3924 TCPIP_TFTP_UploadStatusGet function 5-3924 TCPIP_UDP_ArrayGet function 5-3944 TCPIP_UDP_ArrayPut function 5-3947 TCPIP_UDP_BcastIPV4AddressSet function 5-3937 TCPIP_UDP_Bind function 5-3937 TCPIP_UDP_ClientOpen function 5-3938 TCPIP_UDP_Close function 5-3938 TCPIP_UDP_DestinationIPAddressSet function 5-3939 TCPIP_UDP_Discard function 5-3948 TCPIP_UDP_Flush function 5-3945 TCPIP_UDP_Get function 5-3949 TCPIP_UDP_GetIsReady function 5-3949 TCPIP_UDP_IsConnected function 5-3939 TCPIP_UDP_IsOpened macro 5-3950 TCPIP_UDP_OptionsGet function 5-3940 TCPIP_UDP_OptionsSet function 5-3940 9 MPLAB Harmony Help eeee TCPIP_UDP_Put function 5-3945 TCPIP_UDP_RemoteBind function 5-3941 TCPIP_UDP_RxOffsetSet function 5-3949 TCPIP_UDP_ServerOpen function 5-3942 TCPIP_UDP_SocketInfoGet function 5-3942 TCPIP_UDP_SocketNetGet function 5-3942 TCPIP_UDP_SocketNetSet function 5-3943 TCPIP_UDP_SourceIPAddressSet function 5-3943 TCPIP_UDP_StringPut function 5-3946 TCPIP_UDP_TxCountGet function 5-3946 TCPIP_UDP_TxOffsetSet function 5-3944 TCPIP_UDP_TxPutIsReady function 5-3947 TCPIP_ZCLL_Disable function 5-3960 TCPIP_ZCLL_Enable function 5-3961 TCPIP_ZCLL_IsEnabled function 5-3961 TE_ROUNDEDBUTTON_RADIUS macro 5-1055 Telnet TCP/IP Stack Library 5-3913 telnet.h 5-3917 telnet_config.h 5-3917 TELNET_MODULE_CONFIG structure 5-3916 TELNET_PASSWORD macro 5-3915 TELNET_PORT macro 5-3915 TELNET_USERNAME macro 5-3915 TELNETS_PORT macro 5-3916 TFTP TCP/IP Stack Library 5-3917 TFTP_ACCESS_ERROR type 5-3928 TFTP_ARP_TIMEOUT_VAL macro 5-3920 TFTP_BLOCK_SIZE macro 5-3920 TFTP_BLOCK_SIZE_MSB macro 5-3920 TFTP_CHUNK_DESCRIPTOR structure 5-3928 TFTP_CLIENT_PORT macro 5-3921 TFTP_FILE_MODE type 5-3928 TFTP_GET_TIMEOUT_VAL macro 5-3921 TFTP_MAX_RETRIES macro 5-3921 TFTP_RESULT type 5-3928 TFTP_SERVER_PORT macro 5-3921 TFTP_UPLOAD_COMPLETE macro 5-3925 TFTP_UPLOAD_CONNECT macro 5-3925 TFTP_UPLOAD_CONNECT_TIMEOUT macro 5-3925 TFTP_UPLOAD_GET_DNS macro 5-3925 TFTP_UPLOAD_HOST_RESOLVE_TIMEOUT macro 5-3925 TFTP_UPLOAD_RESOLVE_HOST macro 5-3926 TFTP_UPLOAD_SEND_DATA macro 5-3926 TFTP_UPLOAD_SEND_FILENAME macro 5-3926 TFTP_UPLOAD_SERVER_ERROR macro 5-3926 TFTP_UPLOAD_WAIT_FOR_CLOSURE macro 5-3926 tftpc.h 5-3929 tftpc_config.h 5-3930 TFTPClose macro 5-3926 TFTPGetError macro 5-3927 TFTPIsFileOpenReady macro 5-3927 TFTPOpenFile function 5-3925 The Application File(s) 1-13 The Main File 1-12 Third-Party Library Help 6-4225 Third-Party Library Overview 6-4226 Thread Operation 5-1316 Timer Driver Library 5-457 Timer Peripheral Library 5-3011 Timer System Service Library 5-3500 tIPV6_SNMP_TRAP_INFO structure 5-3848 TMR_ASSIGNMENT enumeration 5-3060 TMR_CLOCK_SOURCE enumeration 5-3060 TMR_CLOCK_SOURCE_EDGE enumeration 5-3060 TMR_GATE_POLARITY enumeration 5-3061 TMR_GATE_SOURCE enumeration 5-3061 TMR_MODULE_ID enumeration 5-3062 TMR_POSTSCALE enumeration 5-3062 TMR_PRESCALE enumeration 5-3063 TPL_MATCH_VID_PID macro 5-4196 Transfer Abort 5-573 Transfer Operation 5-372 Transfer Requests 5-565 Transfer Status 5-572 Transfer/Abort (Asynchronous) Trigger Management 5-1737 Transfer/Abort (Synchronous) 5-1737 Transferring Data 5-3984 Transitions 5-1122 9 MPLAB Harmony Help ffff Transmit 5-1918 Transmitting a CAN Message 5-1561 TRAP_COMMUNITY_MAX_LEN macro 5-3831 TRAP_TABLE_SIZE macro 5-3831 tSNMP_TRAP_INFO structure 5-3850 Tutorial 2-49 U uC_OS_III_basic_demo 3-115 UDP Changes 5-3550 UDP TCP/IP Stack Library 5-3930 udp.h 5-3953 udp_config.h 5-3954 UDP_LOCAL_PORT_END_NUMBER macro 5-3933 UDP_LOCAL_PORT_START_NUMBER macro 5-3934 UDP_MAX_SOCKETS macro 5-3934 UDP_MODULE_CONFIG structure 5-3950 UDP_PORT type 5-3951 UDP_SOCKET type 5-3951 UDP_SOCKET_BCAST_TYPE enumeration 5-3951 UDP_SOCKET_DEFAULT_TX_QUEUE_LIMIT macro 5-3934 UDP_SOCKET_DEFAULT_TX_SIZE macro 5-3934 UDP_SOCKET_INFO structure 5-3951 UDP_SOCKET_OPTION enumeration 5-3952 UDP_SOCKET_POOL_BUFFER_SIZE macro 5-3934 UDP_SOCKET_POOL_BUFFERS macro 5-3935 UDP_USE_RX_CHECKSUM macro 5-3935 UDP_USE_TX_CHECKSUM macro 5-3935 UDPIsPutReady function 5-3948 uint16_gfx_image_prog type 5-940 uint16_prog type 5-940 uint16_prog_pack type 5-940 uint32_gfx_image_prog type 5-940 uint32_prog type 5-940 uint32_prog_pack type 5-940 uint8_gfx_image_prog type 5-941 uint8_prog type 5-941 uint8_prog_pack type 5-941 Upgrading from the MLA Graphics Library to the MPLAB Harmony Graphics Library 5-681 Upgrading from the V5 TCP/IP Stack to the MPLAB Harmony TCP/IP Stack 5-3546 Uploading Pre-built MPFS2 Images 5-3543 USART Driver Demonstration 3-142 USART Driver Library 5-510 USART Peripheral Library 5-3085 USART_BAUD_RATE_MODE enumeration 5-3140 USART_HANDSHAKE_MODE enumeration 5-3140 USART_LINECONTROL_MODE enumeration 5-3140 USART_MODULE_ID enumeration 5-3141 USART_OPERATION_MODE enumeration 5-3142 USART_RECEIVE_INTR_MODE enumeration 5-3142 USART_RECEIVE_MODES enumeration 5-3142 USART_SYNC_CLOCK_SOURCE enumeration 5-3143 USART_SYNC_MODES enumeration 5-3143 USART_TRANSMIT_INTR_MODE enumeration 5-3144 USB Audio Device Library 5-3977 USB Buffers and the Buffer Descriptor Table (BDT) 5-3175 USB CDC Host Library 5-4199 USB Demonstrations 3-149 USB Device CDC Library 5-4060 USB Device Layer Library 5-4004 USB Device Library - Application Interaction 5-3968 USB Device Library - Getting Started 5-3963 USB Device Library Architecture 5-3966 USB Device Stack Migration Guide 5-3973 USB Driver Library 5-552 USB Generic Device Library 5-4100 USB HID Device Library 5-4130 USB Host Layer Library 5-4179 USB Library Help 5-3963 USB MSD Device Library 5-4168 USB Peripheral Library 5-3167 USB Setup Example 5-3179 USB_BUFFER_DATA01 enumeration 5-3278 USB_BUFFER_DIRECTION enumeration 5-3278 USB_BUFFER_PING_PONG enumeration 5-3279 USB_BUFFER_SCHEDULE_DATA01 enumeration 5-3279 usb_device.h 5-4057 9 MPLAB Harmony Help gggg USB_DEVICE_Attach function 5-4033 usb_device_audio.h 5-4002 USB_DEVICE_AUDIO_CONTROL_TRANSFER_HANDLE type 5-3995 USB_DEVICE_AUDIO_ControlReceive function 5-3987 USB_DEVICE_AUDIO_ControlSend function 5-3988 USB_DEVICE_AUDIO_ControlStatus function 5-3990 USB_DEVICE_AUDIO_EP_INSTANCE structure 5-3995 USB_DEVICE_AUDIO_EVENT enumeration 5-3996 USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE structure 5-3997 USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE structure 5-3997 USB_DEVICE_AUDIO_EVENT_HANDLER type 5-3997 USB_DEVICE_AUDIO_EVENT_RESPONSE type 5-3998 USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE macro 5-3994 USB_DEVICE_AUDIO_EventHandlerSet function 5-3991 USB_DEVICE_AUDIO_INDEX type 5-3998 USB_DEVICE_AUDIO_INSTANCE structure 5-3998 USB_DEVICE_AUDIO_INSTANCE_STATE enumeration 5-3999 USB_DEVICE_AUDIO_INTERFACE_COLLECTION structure 5-3999 USB_DEVICE_AUDIO_INTERFACE_INFO structure 5-3999 USB_DEVICE_AUDIO_INTERFACE_TYPE enumeration 5-4000 USB_DEVICE_AUDIO_IRP_OBJECT structure 5-4000 USB_DEVICE_AUDIO_Read function 5-3992 USB_DEVICE_AUDIO_RESULT enumeration 5-4000 USB_DEVICE_AUDIO_STREAMING_INTERFACE structure 5-4001 USB_DEVICE_AUDIO_STREAMING_INTERFACE_ALTERNAT E_SETTING structure 5-4001 USB_DEVICE_AUDIO_TRANSFER_HANDLE type 5-4002 USB_DEVICE_AUDIO_TRANSFER_HANDLE_INVALID macro 5-3995 USB_DEVICE_AUDIO_Write function 5-3993 USB_DEVICE_CALLBACK type 5-4048 usb_device_cdc.h 5-4098 USB_DEVICE_CDC_CONTROL_TRANSFER_HANDLE type 5-4089 USB_DEVICE_CDC_ControlReceive function 5-4076 USB_DEVICE_CDC_ControlSend function 5-4078 USB_DEVICE_CDC_ControlStatus function 5-4080 USB_DEVICE_CDC_EVENT enumeration 5-4089 USB_DEVICE_CDC_EVENT_DATA_GET_LINE_CODING type 5-4092 USB_DEVICE_CDC_EVENT_DATA_READ_COMPLETE structure 5-4092 USB_DEVICE_CDC_EVENT_DATA_SEND_BREAK structure 5-4092 USB_DEVICE_CDC_EVENT_DATA_SERIAL_STATE_NOTIFIC ATION_COMPLETE structure 5-4093 USB_DEVICE_CDC_EVENT_DATA_SET_CONTROL_LINE_S TATE type 5-4093 USB_DEVICE_CDC_EVENT_DATA_SET_LINE_CODING type 5-4093 USB_DEVICE_CDC_EVENT_DATA_WRITE_COMPLETE structure 5-4094 USB_DEVICE_CDC_EVENT_HANDLER type 5-4094 USB_DEVICE_CDC_EVENT_RESPONSE type 5-4095 USB_DEVICE_CDC_EVENT_RESPONSE_NONE macro 5-4097 USB_DEVICE_CDC_EventHandlerSet function 5-4082 USB_DEVICE_CDC_INDEX type 5-4095 USB_DEVICE_CDC_INIT structure 5-4095 USB_DEVICE_CDC_Read function 5-4084 USB_DEVICE_CDC_RESULT enumeration 5-4095 USB_DEVICE_CDC_SERIAL_STATE_NOTIFICATION_DATA type 5-4096 USB_DEVICE_CDC_SerialStateNotificationSend function 5-4085 USB_DEVICE_CDC_TRANSFER_FLAGS enumeration 5-4096 USB_DEVICE_CDC_TRANSFER_HANDLE type 5-4097 USB_DEVICE_CDC_TRANSFER_HANDLE_INVALID macro 5-4097 USB_DEVICE_CDC_Write function 5-4086 USB_DEVICE_ClientStatus function 5-4036 USB_DEVICE_Close function 5-4026 USB_DEVICE_CONFIG_DESCS_PTR type 5-4049 usb_device_config_template.h 5-4059 USB_DEVICE_CONTROL_STATUS enumeration 5-4049 USB_DEVICE_CONTROL_TRANSFER_CALLBACK type 5-4049 9 MPLAB Harmony Help hhhh USB_DEVICE_CONTROL_TRANSFER_EVENT enumeration 5-4050 USB_DEVICE_CONTROL_TRANSFER_EVENT_DATA union 5-4050 USB_DEVICE_CONTROL_TRANSFER_HANDLE type 5-4050 USB_DEVICE_CONTROL_TRANSFER_RESULT enumeration 5-4051 USB_DEVICE_ControlEventCallBackSet function 5-4028 USB_DEVICE_ControlReceive function 5-4032 USB_DEVICE_ControlSend function 5-4033 USB_DEVICE_ControlStatus function 5-4040 USB_DEVICE_Deinitialize function 5-4026 USB_DEVICE_Detach function 5-4034 USB_DEVICE_ENDPOINT_TABLE_SIZE macro 5-4057 USB_DEVICE_EndpointDisable function 5-4030 USB_DEVICE_EndpointEnable function 5-4040 USB_DEVICE_EndpointIsEnabled function 5-4042 USB_DEVICE_EndpointIsStalled function 5-4042 USB_DEVICE_EndpointStall function 5-4043 USB_DEVICE_EndpointStallClear function 5-4044 USB_DEVICE_EVENT enumeration 5-4051 USB_DEVICE_EVENT_DATA union 5-4052 USB_DEVICE_EVENT_DATA_CONFIGURED structure 5-4052 USB_DEVICE_EventCallBackSet function 5-4031 USB_DEVICE_FUNC_REGISTRATION_TABLE structure 5-4052 USB_DEVICE_FUNCTION_DRIVER structure 5-4053 usb_device_generic.h 5-4129 USB_DEVICE_GENERIC_EndpointIsEnabled function 5-4121 USB_DEVICE_GENERIC_EndpointRead function 5-4122 USB_DEVICE_GENERIC_EndpointStall function 5-4122 USB_DEVICE_GENERIC_EndpointStallClear function 5-4123 USB_DEVICE_GENERIC_EndpointStallStatusGet function 5-4123 USB_DEVICE_GENERIC_EndpointWrite function 5-4124 USB_DEVICE_GENERIC_EVENT enumeration 5-4125 USB_DEVICE_GENERIC_EVENT_DATA union 5-4125 USB_DEVICE_GENERIC_EVENT_DATA_CONTROL_TRANSF ER_SETUP_REQUEST structure 5-4126 USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_READ_ COMPLETE structure 5-4126 USB_DEVICE_GENERIC_EVENT_DATA_ENDPOINT_WRITE_ COMPLETE structure 5-4127 USB_DEVICE_GENERIC_EVENT_HANDLER type 5-4127 USB_DEVICE_GENERIC_EVENT_RESPONSE type 5-4127 USB_DEVICE_GENERIC_EventHandlerSet function 5-4124 USB_DEVICE_GENERIC_INDEX type 5-4128 USB_DEVICE_GENERIC_RESULT enumeration 5-4128 USB_DEVICE_GENERIC_TRANSFER_FLAG enumeration 5-4128 USB_DEVICE_GENERIC_TRANSFER_HANDLE type 5-4129 USB_DEVICE_GetConfigurationValue function 5-4039 USB_DEVICE_GetDeviceSpeed function 5-4037 USB_DEVICE_GetDeviceState function 5-4038 USB_DEVICE_HANDLE type 5-4053 USB_DEVICE_HANDLE_INVALID macro 5-4057 usb_device_hid.h 5-4166 usb_device_hid_config_template..h 5-4168 USB_DEVICE_HID_CONTROL_STATUS enumeration 5-4152 USB_DEVICE_HID_CONTROL_TRANSFER_HANDLE type 5-4153 USB_DEVICE_HID_ControlReceive function 5-4142 USB_DEVICE_HID_ControlSend function 5-4144 USB_DEVICE_HID_ControlStatus function 5-4146 USB_DEVICE_HID_EVENT enumeration 5-4153 USB_DEVICE_HID_EVENT_DATA_GET_IDLE structure 5-4160 USB_DEVICE_HID_EVENT_DATA_GET_PROTOCOL structure 5-4160 USB_DEVICE_HID_EVENT_DATA_GET_REPORT structure 5-4160 USB_DEVICE_HID_EVENT_DATA_REPORT_RECEIVED structure 5-4161 USB_DEVICE_HID_EVENT_DATA_REPORT_SENT structure 5-4161 USB_DEVICE_HID_EVENT_DATA_SET_DESCRIPTOR structure 5-4162 USB_DEVICE_HID_EVENT_DATA_SET_IDLE structure 5-4162 USB_DEVICE_HID_EVENT_DATA_SET_PROTOCOL structure 5-4162 USB_DEVICE_HID_EVENT_DATA_SET_REPORT structure 5-4163 USB_DEVICE_HID_EVENT_HANDLER type 5-4163 9 MPLAB Harmony Help iiii USB_DEVICE_HID_EVENT_RESPONSE type 5-4164 USB_DEVICE_HID_EVENT_RESPONSE_NONE macro 5-4165 USB_DEVICE_HID_EventHandlerSet function 5-4148 USB_DEVICE_HID_INDEX type 5-4164 USB_DEVICE_HID_INIT structure 5-4164 USB_DEVICE_HID_INSTANCES_NUMBER macro 5-4166 USB_DEVICE_HID_QUEUE_DEPTH_COMINED macro 5-4166 USB_DEVICE_HID_ReportReceive function 5-4149 USB_DEVICE_HID_ReportSend function 5-4151 USB_DEVICE_HID_RESULT enumeration 5-4165 USB_DEVICE_HID_TRANSFER_HANDLE type 5-4165 USB_DEVICE_HID_TRANSFER_HANDLE_INVALID macro 5-4166 USB_DEVICE_INDEX_0 macro 5-4047 USB_DEVICE_INDEX_1 macro 5-4047 USB_DEVICE_INDEX_2 macro 5-4048 USB_DEVICE_INDEX_3 macro 5-4048 USB_DEVICE_INDEX_4 macro 5-4048 USB_DEVICE_INDEX_5 macro 5-4048 USB_DEVICE_INDEX_COUNT macro 5-4048 USB_DEVICE_INFORMATION structure 5-4194 USB_DEVICE_INIT structure 5-4054 USB_DEVICE_Initialize function 5-4027 USB_DEVICE_IRPCancelAll function 5-4044 USB_DEVICE_IRPSubmit function 5-4045 USB_DEVICE_MAX_CLIENTS macro 5-4023 USB_DEVICE_MAX_FUNCTION_DRIVER macro 5-4023 USB_DEVICE_MAX_INSTANCES macro 5-4023 usb_device_msd.h 5-4178 usb_device_msd_config_template.h 5-4178 USB_DEVICE_MSD_INIT structure 5-4176 USB_DEVICE_MSD_INQUIRY_RESPONSE structure 5-4177 USB_DEVICE_MSD_INTF macro 5-4175 USB_DEVICE_MSD_INTF_SUBCLASS macro 5-4175 USB_DEVICE_MSD_MAX_INSTANCES macro 5-4174 USB_DEVICE_MSD_MAX_LUN macro 5-4174 USB_DEVICE_MSD_MAX_SECTOR_SIZE macro 5-4174 USB_DEVICE_MSD_MEDIA_FUNCTIONS structure 5-4175 USB_DEVICE_MSD_MEDIA_INIT_DATA structure 5-4177 USB_DEVICE_MSD_PROTOCOL macro 5-4175 USB_DEVICE_Open function 5-4032 USB_DEVICE_POWER_STATE enumeration 5-4054 USB_DEVICE_PowerStateSet function 5-4039 USB_DEVICE_Reinitialize function 5-4028 USB_DEVICE_REMOTE_WAKEUP_STATUS enumeration 5-4055 USB_DEVICE_RemoteWakeupIsEnabled function 5-4039 USB_DEVICE_ResumeStart function 5-4036 USB_DEVICE_ResumeStop function 5-4037 USB_DEVICE_STATE enumeration 5-4055 USB_DEVICE_Status function 5-4035 USB_DEVICE_STRING_DESCS_PTR type 5-4056 USB_DEVICE_Tasks function 5-4031 USB_EP_TXRX enumeration 5-3279 usb_host.h 5-4198 USB_HOST_0 macro 5-4197 USB_HOST_1 macro 5-4197 usb_host_cdc.h 5-4223 USB_HOST_CDC_BreakSend function 5-4201 USB_HOST_CDC_CONTROL_LINE_STATE type 5-4223 USB_HOST_CDC_ControlLineStateSet function 5-4202 USB_HOST_CDC_EVENT enumeration 5-4210 USB_HOST_CDC_EVENT_DATA_GET_LINE_CODING_COM PLETE structure 5-4216 USB_HOST_CDC_EVENT_DATA_READ_COMPLETE structure 5-4216 USB_HOST_CDC_EVENT_DATA_SEND_BREAK_COMPLETE structure 5-4217 USB_HOST_CDC_EVENT_DATA_SERIAL_STATE_NOTIFICA TION_RECEIVED structure 5-4218 USB_HOST_CDC_EVENT_DATA_SET_CONTROL_LINE_STA TE_COMPLETE structure 5-4218 USB_HOST_CDC_EVENT_DATA_SET_LINE_CODING_COMP LETE structure 5-4219 USB_HOST_CDC_EVENT_DATA_WRITE_COMPLETE structure 5-4220 USB_HOST_CDC_EVENT_HANDLER type 5-4220 USB_HOST_CDC_EVENT_RESPONSE type 5-4221 USB_HOST_CDC_EVENT_RESPONSE_NONE macro 5-4222 9 MPLAB Harmony Help jjjj USB_HOST_CDC_EventHandlerSet function 5-4203 USB_HOST_CDC_INDEX type 5-4221 USB_HOST_CDC_LineCodingGet function 5-4204 USB_HOST_CDC_LineCodingSet function 5-4205 USB_HOST_CDC_Read function 5-4206 USB_HOST_CDC_RESULT enumeration 5-4215 USB_HOST_CDC_SERIAL_STATE_NOTIFICATION_DATA type 5-4221 USB_HOST_CDC_SerialStateNotificationGet function 5-4207 USB_HOST_CDC_TRANSFER_HANDLE type 5-4215 USB_HOST_CDC_TRANSFER_HANDLE_INVALID macro 5-4222 USB_HOST_CDC_TRANSFER_STATUS enumeration 5-4222 USB_HOST_CDC_Write function 5-4208 USB_HOST_Close function 5-4181 USB_HOST_Deinitialize function 5-4183 USB_HOST_DeviceInformationGet function 5-4184 USB_HOST_DeviceIsResumed function 5-4184 USB_HOST_DeviceIsSuspended function 5-4185 USB_HOST_DeviceResume function 5-4186 USB_HOST_DeviceSuspend function 5-4187 USB_HOST_ENDPOINT_TABLE_SIZE macro 5-4197 USB_HOST_EVENT_CALLBACK type 5-4195 USB_HOST_EVENT_DATA_VBUS_REQUEST_POWER structure 5-4195 USB_HOST_EVENT_RESPONSE type 5-4195 USB_HOST_EVENT_RESPONSE_NONE macro 5-4197 USB_HOST_EventCallBackSet function 5-4187 USB_HOST_EVENTS enumeration 5-4196 USB_HOST_HANDLE type 5-4193 USB_HOST_HANDLE_INVALID macro 5-4194 USB_HOST_INIT structure 5-4193 USB_HOST_Initialize function 5-4188 USB_HOST_Open function 5-4182 USB_HOST_OperationDisable function 5-4190 USB_HOST_OperationEnable function 5-4190 USB_HOST_OperationIsEnabled function 5-4191 USB_HOST_Status function 5-4191 USB_HOST_Tasks function 5-4192 USB_HOST_TPL_FLAGS enumeration 5-4196 USB_MASTER_DESCRIPTOR structure 5-4056 USB_MAX_EP_NUMBER macro 5-3283 USB_OPMODES enumeration 5-3280 USB_OTG_INTERRUPTS enumeration 5-3280 USB_OTG_PULL_UP_PULL_DOWN enumeration 5-3281 USB_PID enumeration 5-3281 USB_PING_PONG_MODE enumeration 5-3282 USB_PING_PONG_STATE enumeration 5-3282 USB_TOKEN_SPEED enumeration 5-3283 USE_ANALOGCLOCK macro 5-321 USE_BITMAP_FLASH macro 5-321 USE_BUTTON macro 5-321 USE_CHART macro 5-321 USE_CHECKBOX macro 5-322 USE_COMP_RLE macro 5-322 USE_CUSTOM macro 5-322 USE_DIGITALMETER macro 5-322 USE_EDITBOX macro 5-323 USE_FONT_FLASH macro 5-323 USE_GOL macro 5-323 USE_GRADIENT macro 5-323 USE_GROUPBOX macro 5-323 USE_HORZ_ASCENDING_ORDER macro 5-1055 USE_LCC_SCROLLING macro 5-306 USE_LISTBOX macro 5-323 USE_METER macro 5-323 USE_MULTIBYTECHAR macro 5-324 USE_PICTURE macro 5-324 USE_PIE_ENABLE_LABEL macro 5-1055 USE_PIP macro 5-306 USE_PROGRESSBAR macro 5-324 USE_RADIOBUTTON macro 5-324 USE_ROUNDDIAL macro 5-324 USE_SLIDER macro 5-324 USE_STATICTEXT macro 5-324 USE_TEXTENTRY macro 5-325 USE_TOUCHSCREEN macro 5-325 USE_WINDOW macro 5-325 USER_SECURITY_NAME_LEN macro 5-3831 9 MPLAB Harmony Help kkkk Using Primitive Rendering Functions 5-1112 Using Status Functions 5-3351 Using the Build Projects 4-179 Using the Configurator 2-42 Using the File System 5-3381 Using the Library 5-194, 5-228, 5-255, 5-290, 5-300, 5-310, 5-320, 5-334, 5-344, 5-368, 5-398, 5-419, 5-458, 5-513, 5-553, 5-607, 5-695, 5-1111, 5-1129, 5-1168, 5-1276, 5-1313, 5-1362, 5-1472, 5-1521, 5-1564, 5-1669, 5-1734, 5-1866, 5-1905, 5-2087, 5-2172, 5-2203, 5-2253, 5-2289, 5-2331, 5-2428, 5-2479, 5-2595, 5-2663, 5-2689, 5-2705, 5-2763, 5-2799, 5-2893, 5-3012, 5-3086, 5-3171, 5-3321, 5-3349, 5-3364, 5-3420, 5-3439, 5-3466, 5-3501, 5-3530, 5-3570, 5-3575, 5-3599, 5-3615, 5-3626, 5-3637, 5-3647, 5-3655, 5-3660, 5-3691, 5-3698, 5-3710, 5-3719, 5-3748, 5-3771, 5-3795, 5-3799, 5-3807, 5-3810, 5-3823, 5-3859, 5-3868, 5-3881, 5-3914, 5-3918, 5-3931, 5-3955, 5-3979, 5-4005, 5-4064, 5-4104, 5-4133, 5-4169, 7-4231, 7-4233, 7-4235, 7-4237 Utilities 5-3542 V v0.51.01b 5-601 v0.51.02b 5-3965 v0.51.03b 1-32 v0.51b 5-604, 5-3964 VENDOR_SPECIFIC_TRAP_NOTIFICATION_TYPE enumeration 5-3852 Version Numbers 1-29 W Wait States Initialization 5-2482 Watchdog Timer (WDT) System Service Library 5-3529 Watchdog Timer Peripheral Library 5-3319 WDT_MODULE_ID enumeration 5-3327 WDT_PLIB_ID macro 5-3532 web_server 3-131 web_server_nvm_mpfs 3-134 web_server_sdcard_fatfs 3-133 WF_WPS_PIN_LENGTH macro 5-674 What is MPLAB Harmony? 1-4 WHEAT macro 5-1055 WHITE macro 5-1055 Widget Objects 5-697 Writing a File 5-3394 X XIP Mode 5-2896 Y YELLOW macro 5-1056 Z ZCLL_MODULE_CONFIG structure 5-3961 zero_conf_link_local.h 5-3962 zero_conf_multicast_dns.h 5-3962 Zeroconf Enabled Environments 5-3957 Zeroconf TCP/IP Stack Library 5-3954 9 MPLAB Harmony Help llll

MPLAB Harmony Graphics Composer User's Guide MPLAB Harmony Integrated Software Framework © 2013-2017 Microchip Technology Inc. All rights reserved. MPLAB Harmony Graphics Composer User's Guide This section provides user information about using the MPLAB Harmony Graphics Composer (MHGC). MPLAB Harmony Graphics Composer User's © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 2 Introduction This user's guide provides information on the MPLAB Harmony Graphics Composer (MHGC), also referred to as the graphics composer, which is included in your installation of MPLAB Harmony. MHGC is tightly coupled with the Aria User Interface Library to facilitate rapid prototyping and optimization of the application's graphical user interface (GUI). Description The MPLAB Harmony Graphics Composer (MHGC), also referred to as the graphics composer, is a graphics user interface design tool that is integrated as part of the MPLAB Harmony Configurator (MHC). MHGC is tightly coupled with the Aria User Interface Library to facilitate rapid prototyping and optimization of the application's graphical user interface (GUI). The tool provides a "What you see is what you get" (WSYWIG) environment for users to design the graphics user interface for their application. Refer to Volume V: MPLAB Harmony Framework Reference > Graphics Library Help > Aria User Interface Library for more information. The MPLAB Harmony Graphics Composer (MHGC) Tool Suite and the Aria User Interface Library provide the following benefits to developers: • Enhanced User Experience – Libraries and tools are easy to learn and use. • Intuitive MHGC Window Tool – Flexible window docking/undocking. Undo/Redo and Copy/Paste support. Tree-based design model. Display design canvas control including zooming. • Tight Integration Experience – Graphics design & code generator tools are tightly integrated, providing rapid prototyping and optimization of look and feel • Powerful User Interface (UI) Library – Provides graphics objects and touch support • Multi-Layer UI design – Supported in the MHGC tool and Aria Library • Complete Code Generation – Can generate code for library initialization, library management, touch integration, color schemes and event handling with a single click • Supports Performance and Resource Optimization – Draw order, background caching, and advanced color mode support improve performance • Resource optimization – Measures Flash memory usage and can direct resources to external memory if needed. Global 8-bit color look-up table (LUT) supports reduced memory footprint. Heap Estimator tool, which helps to manage the SRAM memory footprint. • Text localization – Easily integrate international language characters into a design and seamlessly change between defined languages at run-time • Easy to Use Asset Management – Tools provide intuitive management of all graphics assets (fonts, images, text strings) • Image Optimization – Supports cropping, resizing, and color mode tuning of images • Expanded Color Mode Support – The graphics stack can manage frame buffers using 8-bit to 32-bit color • Powerful Asset Converter – Inputs several image formats, auto converts from input format to several popular internal asset formats, performs auto palette generation for image compression, supports run-length encoding. Supports automatic font character inclusion & rasterization. • Event Management – Wizard-based event configuration. Tight coupling to enable touch user events and external logical events to change the graphics state machine and graphics properties. • Abstract Hardware Support – Graphics controllers and accelerators can be added or removed without any change to the application Glossary of Terms Throughout this user's guide the following terms are used: Acronym or Term Description Action A specific task to perform when an event occurs. Asset An image, font, or binary data blob that is used by a user interface. Event A notification that a specific occurrence has taken place. Resolution The size of the target device screen in pixels. Screen A discreet presentation of organized objects. Tool An interface used to create objects. UI Abbreviation for User Interface. Widget A graphical object that resides on the user interface screen. MPLAB Harmony Graphics Composer User's Introduction © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 3 Graphics Composer Window User Interface This section describes the layout of the different windows and tool panels available through MHGC. Description MHGC is launched from the MHC toolbar Launch Utility menu. Launching the Graphics Composer creates a new screen. Shown below is the MHGC screen for the Aria Showcase demonstration. (If you don’t see this screen layout, reset the screen by selecting Window > Reset Dock Areas from the window’s menus.) Panels By default, there are five active panels and one minimize panel on this screen: • Screen Designer – Shows the screen design for the selected screen. Tabs on the bottom of the Screen Designer panel show the available screens. • Tree View – Shows the layer and widget hierarchy for the current screen. • Screens – Manages screens in the application. • Schemes – Manages coloring schemes in the application. Note: In v2.03b of MPLAB Harmony, a third tab named Options, along with Screens and Schemes was available. These properties are now located within the File > Settings menu. • Widget Tool Box – Available graphics widgets are shown on this panel. Widgets are added to the screen by selecting an icon and dragging or clicking. Widget properties are discussed in the Widget Properties section below. • Properties Editor – All properties for the currently selected object are shown in this panel. • The MHGC Output console is parked at the bottom of the Screen Designer window. This console panel can be used to debug problems when the Graphics Composer boots up or during its operation. Each of the panels has a window tool icon at the upper right corner. Minimizing a panel parks it on the screen just like the Output Console. Undocking the panel creates a new, free floating window. Redocking returns a previously undocked window to its original location on the Screen MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 4 Designer window. When a panel is undocked, its edges become active and support moving or manipulating the panel as an independent window. Tool Bar There are 18 tool bar icons on the Screen Designer Window, as described in the following figure. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 5 Create New Design brings up a New Project Wizard dialog that allows you to select anew the screen size, color mode, memory size, and project type. This will erase the currently displayed design. Save Design saves the current graphics design. Note: The target configuration's configuration.xml will not be updated to reflect these changes in the graphics design until one of the following events happens: 1. The application is regenerated in MHC, 2. The target configurations are changed in the MPLAB X IDE, 3. MPLAB X IDE is exited. In items 2 and 3 you will be prompted to save the new configuration. Undo and Redo manipulate changes in the screen design into internal MHC memory. Cut/Copy/Paste support the manipulation of graphics objects (widgets). Canvas Size Dialog brings up a dialog window allowing changes in the pixel width and height of the Screen Designer panel. (Note: Dimensions smaller than the display’s dimensions are ignored). Center View centers the panel’s view of the screen. Zoom In and Zoom Out allow you to change the scale of the Screen Designer’s display of the current window. Currently this only supports coarse zooming (powers of two zooms in and out). Toggle Line Snapping enables/disables line snapping when moving objects (widgets). Show Grid turns the Screen Designer pixel grid on/off. X and Y Grid Size adjust the pixel grid. Grid Color selects the pixel grid color. Toggle Object Clipping turns object clipping on/off. Toggle Screen Info turns the display of screen information (X and Y axes) on/off. Select Text Preview Language changes the language used on all text strings shown, when the application supports more than one language. Screen Designer Window Most of the work of the MPLAB Harmony Graphics Composer is done using the Screen Designer. This section covers the basics of how a graphical user interface is designed using the screen designer. Description The following figure shows the Screen Designer window for the Aria Quickstart demonstration, with the pic32mz_ef_sk_meb2 configuration selected. (Load whatever configuration belongs to your board and follow along.) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Screen Designer Window © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 6 The pixel dimensions of the display (480x272) are determined by the MHC Display Manager. Other configuration in Aria Quickstart can have different size displays (such as: 220x176, 320x24, or 800x480). This demonstration has three widgets: a label containing the title string at the top, an image of the MPLAB Harmony logo in the middle, and a button containing the text string “Make changes. Generate. Run.” at the bottom. The label widget’s text string was first created using the String Assets window before it was assigned to the label widget. The image assigned to the image widget was first imported using the Image Assets. The string embedded in the button widget was also created using the String Assets window before it was assigned to the button widget. The Tree View panel organizes the display’s widgets into groups using layers. Every display has at least one layer and complex designs can have many more. Within the tree view, the order of layers and the order of widgets within a layer determine the draw order. Draw order goes from top to bottom. Top-most layers and widgets are drawn first and bottom-most are drawn last. Controlling draw order is one of the ways to improve graphics performance by minimizing redrawing. Since the location of every widget within a layer is relative to the layer, you can move a layer’s worth of widgets by simply moving the layer. Layers also provide inheritance of certain properties from the layer to all the layer’s widgets. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Screen Designer Window © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 7 Exploring the Screen Designer Window We can add another widget to this screen by launching the Widget Tool Box panel into a separate window. Next, drag a circle from the tool box onto the display. Find a place on the display for this new widget. Besides dragging widgets onto the display, you can click on a widget in the Widget Tool Box, converting the cursor into that widget, and then click on the screen to drop the widget in place. Your display should now look appear like the following figure. Note how the Tree View panel now shows the widget you just added. Launch the Properties Editor for the circle. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Screen Designer Window © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 8 Next, change the fill property on the circle from “None” to “Fill”. Note: If the properties in the Properties Editor shown are not for CircleWidget1, click on the circle widget to change the focus of the Properties Window. When done, the screen should now appear, as follows. Turn on Line Snapping, which enables drawing guides to assist in aligning widgets on the display. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Screen Designer Window © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 9 Next, turn on Object Clipping, which allows you to see how widgets are clipped by the boundaries of the layer that contains them. Note: Clipping applies to layers, which can be smaller than the display. To delete a widget, select the widget and press Delete on your keyboard or use the delete icon ( ) on the Tree View panel. For more hands-on exploration of graphics using the Aria Quickstart demonstration, see Volume 1: Getting Started With MPLAB Harmony > Quick Start Guides > Graphics and Touch Quick Start Guides > Adding an Event to the Aria Quickstart Demonstration. The steps to create a new MPLAB Harmony project with touch input on a PIC32MZ EF Starter Kit with the Multimedia Expansion Board (MEB) II display can be found in Volume 1: Getting Started With MPLAB Harmony > Quick Start Guides > Graphics and Touch Quick Start Guides > Creating New Graphics Applications. Menus This section provides information on the menus for the MPLAB Harmony Graphics Composer screen. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Menus © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 10 Description File Menu New – Same as the Create New Design tool icon. Save – Same as the Save Design tool icon. Save As – Supports exporting the design under a new name. By default, the name is composer_export.xml. See Importing and Exporting Graphics Data for more information. Import - Reads in (imports) a previously exported design or a ./framework/src/system_config/{board_config}/configuration.xml file that contains the graphics design to be imported. See Importing and Exporting Graphics Data for more information. Export – Same as Save As. See Importing and Exporting Graphics Data for more information. Settings – Brings up Project and User Settings dialog, including: • Project Color Mode - How colors are managed • Using a Global Palette • Show Welcome Dialog • Pre-emption Level – Allows for sharing of the device’s cycles with other parts of the application • Hardware Acceleration – Is graphics hardware accelerator enabled in software? Exit – Closes the MHGC window and exits The choices for Project and User Settings > Project Color Mode are: • GS_8 - 8-bit gray scale • RGB_332 - Red/Green/Blue, 3 bits Red/Green, 2 bits Blue • RGB_565 - Red/Green/Blue, 5 bits Red, 6 bits Green, 5 bits Blue • RGBA_5551 - Red/Green/Blue/Alpha, 5 bits Red/ Green/Blue, 1 bit for Alpha Blending • RGB_888 - Red/Green/Blue, 8 bits Red/Green/Blue • RGBA_8888 - Red/Green/Blue/Alpha, 8 bits Red/Green/Blue/Alpha Blending • ARGB_8888 - Alpha/Red/Green/Blue, 8 bits Alpha Blending/Red/Green/Blue Ensure that the Project Color Mode chosen is compatible with the display hardware you are using; otherwise, the colors shown on the display will not match those shown on the Graphics Composer Screen Designer. Using a Global Palette enables frame buffer compression for applications using the Low-Cost Controllerless (LCC) Graphics Controller or Graphics LCD (GLCD) Controller. If the global palette is enabled, you will have to change the MHC configuration of the Graphics Controller to match. For the LCC controller, enable "Palette Mode". For the GLCD controller, change the Driver Settings > Frame Buffer Color Mode to "LUT8". If Using a Global Palette is enabled, the following warning appears. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Menus © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 11 If Show Welcome Dialog is enabled, the following welcome screen appears when launching MHGC. Note: If you are not creating a new project you can ignore this window. When the Preemption Level is set to zero, all dirty graphics objects are refreshed before the graphics process relinquishes control of the device. (Dirty means needing a redraw.) With the level set to two, graphics provides maximum sharing with the rest of the application, at the cost of slower display refreshes. A level of one provides an intermediate level of sharing. The Hardware Acceleration check box determines whether graphics uses the device’s built-in graphics hardware accelerator in software. Note: You must also specify the graphics hardware accelerator in the MPLAB Harmony Framework Configuration within the MHC Options tab. If the host device lacks a graphics processor, you will see a warning message when you try to select a processor that does not exist on your device. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Menus © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 12 Edit Menu This menu implements the same functions as the first seven tool icons. View Menu This implements the same functions as the remaining tool icons. Asset Menu These menu features are discussed in Graphics Composer Asset Management. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Menus © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 13 Tools Menu The Event Manager, Global Palette, and Heap Estimator are discussed in MHGC Tools. Window Menu Selecting Console opens the Output Console for the Graphics Composer. This console panel can be used to debug problems when the Graphics Composer boots up or during its operation. Selecting Reset Dock Areas restores the MHGC panel configuration to the default setup by redocking all of the panels that have been undocked into separate windows. New Project Wizard The New Project Wizard is launched from the Welcome dialog of the MPLAB Harmony Graphics Composer (MHGC), which supports the creation of a new graphics design, or the importing of an existing graphics design. Description Welcome Dialog window The Welcome dialog is launched when the Graphics Composer is chosen from the Launch Utility pull-down menu in the MPLAB Harmony Configurator (MHC). The window has three options: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface New Project Wizard © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 14 Note: If this window does not appear, it can be re-enabled from MHGC’s File > Settings > General menu. New Project Wizard Windows Selecting the first icon in the Welcome dialog launches the New Project Wizard. There are four stages in the New Project Wizard: Color Mode, Memory Size, Project Type, and Finish. The New Project Wizard can also be launched from the first icon (Create New Design) of MHGC’s tool bar: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface New Project Wizard © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 15 If the Graphics Stack has not been enabled in MHC, an Enable Graphics Stack? dialog will appear to support enabling the Graphics Stack before proceeding: In the Color Mode stage you choose the Display Color Mode for the new graphics design: This choice must be supported by the graphics controller defined in the board support package of the project configuration. (If you make a mistake it can be corrected using MHGC’s File > Settings > Project Color Mode menu.) Click Next moves the wizard on to the next stage. The Memory Size stage configures the Program Flash allocated to memory use. This value is only used by the Graphics Composer’s Asset menu Memory Configuration tool. The value used in the Memory Size stage can be updated using the Configuration sub-tab of the Memory Configuration tool window. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface New Project Wizard © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 16 Clicking Previous returns to the Color Mode stage and clicking Next moves the wizard to the Project Type stage. There are two choices at the Project Type stage: A completely blank design, and a template design with a few predefined widgets. Clicking Previous returns to the Memory Size stage, and clicking Next moves the wizard to the Finish stage. If the “Template” project type was chosen, MHGC’s Screen Designer will show: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface New Project Wizard © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 17 Tree View Panel The organization of application widgets and layers, including draw order, is managed using this panel. Description Example Tree View The following Tree View (from main screen of the Aria Coffee Maker demonstration shows the tree structure for a screen with three layers. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Tree View Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 18 The tool icons for this panel support layers and managing screen objects (layers/widgets). Drawing Order and Parent/Child Relationships The Graphics Composer Tree View panel allows you to organize the widgets per screen in the desired drawing order (z-order). It also allows for the user to organize the widgets into parent – child hierarchies to allow for the paint algorithm to draw the groups together in event of motion or re-draw. Please note that this does not associate or group the widgets by functionality. (Example: a group of radio buttons might not belong to a common parent on the screen.) This parent-child relationship is limited to the widgets location on the screen, motion on the screen and the drawing order on the screen. (Exceptions to this general rule are the Editor > Hidden, Alpha Blending properties, and layer single versus double buffering. These apply to the parent and all the parent's children.) The tree is traversed depth-first. This means that the z-order goes background (bottom of z-order) to foreground (top of z-order) as we go from top to bottom in the list of widgets, i.e., ImageWidget1, is the widget at the bottom of the z-order and the PanelWidget1 is the topmost widget on the z-order. The tree structure can be arranged and modified by dragging the widgets and releasing it under the desired parent/child. Also, the list can be modified by using the up/down arrows provided at the header of the Composer Widget tree window to traverse the tree. Editor > Hidden Property for Layers Setting Editor > Hidden hides the layer and all its children from the Graphics Composer Screen Designer but does not affect how the layer and its children are displayed when the application is running. This can be useful when designing complex screens with overlapping layers. Alpha Blending Property for Layers Enabling Alpha Blending allows you to control the transparency of a layer and all its children. You can experiment with Alpha Blending in the Aria Coffee Maker demonstration. Load the project, launch MHC, and then start the Graphics Composer Screen Designer. There are three layers (Layer0, Layer1, Layer2) in this demonstration. Layer1 (the drag panel on the right) and Layer2 (the drag panel on the left) have Alpha Blending enabled with Alpha Amount = 225. Setting the Alpha Amount to 255 is the same as disabling Alpha Blending (255 = no transparency). Setting the MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Tree View Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 19 Alpha Amount to 0 makes the layer invisible (0 = full transparency, i.e., invisible). The following figure shows the main screen with Alpha Blending = 225. The following figure shows the main screen with Layer 2’s Alpha Blending = 255. Double Buffering for Layers Graphics double buffering for the LCC driver is enabled in the Display Manager’s Display Setting screen when the application is changed to use external memory instead of internal. Click Configure to bring up the LCC Driver Configuration Settings Window. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Tree View Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 20 Configure the memory according to whether double buffering is to be enabled for the display’s layer or layers. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Tree View Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 21 Increasing the Buffer Count of a layer from 1 to 2 enables double buffering for the layer and all its child widgets. To prevent tearing on the display when switching from one buffer to the other, VSync Enabled should also be selected. Screens Panel Application screens are managed using the Screens Panel. Description The Screens panel tab manages all the application’s screens, as shown in the following figure. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Screens Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 22 Note: These screens are examples from the Aria Showcase demonstration project The underlined screen name identifies the primary screen (in this case, SplashScreen.) The bold screen name identifies the currently active screen in the Graphics Composer Screen Designer window (in this case MainMenu.) The blue background identifies the selected screen (i.e., the screen that is manipulated by the tool icons), in this case FirstScreen. Window Toolbar The window’s tools icons support: 1. Create New Screen – Create a new screen. You will be prompted for the name of the new screen, which will appear at the bottom of the Screens list. 2. Delete Screen – Delete the selected screen. This removes the selected screen from the application. 3. Set as Primary Screen – Sets the selected screen as the default screen displayed by the application at boot-up. 4. Make Screen Active – This selected screen is displayed in the Screen Designer panel. You can also select the active screen by clicking on the screen’s tab at the bottom of the Screen Designer panel. 5. Move Screen Up in Order – Moves the selected screen up in the list of screens, which is useful in organizing a large list of screens, but has no other significance. 6. Move Screen Down in Order – Moves the selected screen down in the list of screens. Useful in organizing a large list of screens, but has no other significance. Window Columns The Generate check box is used in selecting those screens that will be included in the application when MPLAB Harmony Configurator (MHC) generates/regenerates the application. (This, along with the Enabled check box for languages, allows customization of the application’s build to support different end uses from the same project.) The Visible check box can be cleared to hide a screen from the sub-tabs located at the bottom of the Screen Designer. The View column provides a mouse-over preview of the screen. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Schemes Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 23 Schemes Panel Application color schemes are managed using the Schemes Panel. Description Color schemes for the application’s graphics are managed using the Schemes sub-tab. Editing a Scheme To edit an existing scheme, select the scheme from the list and click Edit. The Scheme Editor dialog appears, which allows you to change the colors associated with this display scheme. Scheme Editor The Scheme Editor window supports editing the individual colors of a color scheme. Clicking the ellipsis ( … ) opens the Color Picker window. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Schemes Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 24 Color Picker The Color Picker window allows the user to easily select a color by providing a color wheel, brightness gauge, and some common predefined color choices. The user can change the individual color values or input a number in Hexadecimal format. The end result is displayed in the top right corner. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Schemes Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 25 Options Provides information on the defeatured Options window. Description In v2.03b, MPLAB Harmony Graphics Composer user interface provided a third window along with Screens and Schemes, named Options. Beginning with v2.04b of MPLAB Harmony, these options are now located within the File > Settings menu (see Menus for details). Widget Tool Box Panel The Widget Tool Box panel is the interface by which users add widgets into the screen representation. Description All the available graphics widgets are shown in the Widget Tool Box: MPLAB Harmony Graphics Composer provides automatic code optimization by keeping track of the widgets that are currently being used. When MHC generates or regenerates the application, only the Graphics Library code necessary for your design is included in the project. There are two primary methods for creating new widget objects: clicking and dragging. To add a new layer to a screen use the Screens sub-tab. Click Method The following actions can be performed by using the Click method: • Clicking an item selects it as active. Users can then move the cursor into the screen window and view a representation of the object about to be added. • Left-clicking confirms the placement of the new object • Right-clicking aborts object creation • Clicking the active item again deactivates it MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Tool Box Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 26 Drag Method Dragging and dropping a tool item into the Screen Designer Window creates a new instance of an object. When dragging a tool item, releasing the cursor outside of the Screen Designer Window cancels the drag operation. Widget List The Graphics Composer Tool Box is the interface by which users add widgets into the screen representation. Click Method The following actions can be performed by using the Click method: • Clicking an item selects it as active. Users can then move the cursor into the screen window and view a representation of the object about to be added. • Left-clicking confirms the placement of the new object • Right-clicking aborts object creation • Clicking the active item again deactivates it. Drag Method Dragging and dropping a tool item into the Screen Designer Window creates a new instance of an object. When dragging a tool item, releasing the cursor outside of the Screen Designer Window cancels the drag operation. Automatic Code Optimization MPLAB Harmony Graphics Composer keeps track of the types of widgets that are used and updates the MHC Tree constantly to ensure that only the Graphics Library code necessary for your design is included in the project. Widgets Widgets can be configured by using the Properties Editor on the right side of the MHGC interface. Each widget has multiple properties to manage their appearance as well as their functioning. Most properties related to appearance are common between widgets, though some widgets require specific property entries. Button - A binary On and Off control with events generation for Press and Release state. Check Box - A selection box with Checked and Unchecked states, and associated events. Circle - A graphical object in the shape of a circle. Draw Surface - A container with a callback from its paint loop. a draw surface lets the application have a chance to make draw calls directly to the HAL during LibAria's paint loop. Gradient - A draw window that can be associated with a gradient color scheme. This allows for color variation on the window. Group Box - A container with a border and a text title. With respect to functionality, a group box is similar to a window. Image Sequence - A special widget that allows image display on screen to be scheduled and sequenced. You can select the images to be displayed, the order for display, and the durations. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Tool Box Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 27 Image - Allows an image to be displayed on screen. The size and shape of the widget decides the visible part of the image, as scaling is not enabled for images at this time. Key Pad - A key entry widget that can can be designed for the number of entries divided as specified number of rows and column entries. The widget has a key click event that can be customized. Label - A text display widget. This does not have any input at runtime capability. A Text Field widget serves that purpose. Line - A graphical object in the shape of a line. List Wheel - Allows multiple radial selections that were usually touch-based selections and browsing. List - Allows making lists of text and image items. The list contents, number of items, and the sequence can be managed through a List Configuration dialog box in the Properties box. Panel - A container widget that is a simpler alternative to DrawSurface as it does not have the DrawSurface callback feature. Progress Bar - Displays the progress pointer for an event being monitored through the "Value Changed" event in the Properties Editor. Radio Button - A set of button widgets that are selected out of the group one at a time. The group is specified by the Group property in the Properties Editor. Note: The radio buttons in the same group must have the same group number specified in their properties. Rectangle - A graphical object in the shape of a rectangle. Scroll Bar - Intended to be used with another relevant widget such as the List Wheel to scroll up and down. It has a callback each time the value is changed. The callback allows users to trigger actions to be handled on the scroll value change event. Slider - Can change values with an external input such as touch. Event callbacks on value change are also available through the Properties Editor. Text Field - Text input can be accepted into the text field from an external input or from a widget such as keypad. Event 'Text Changed' in the Properties Editor is used for accepting the input. Touch Test - Allows tracking of touch inputs. Each new touch input is added to the list of displayed touch coordinates. The input is accepted through the 'Point Added' event callback in the Properties Editor. Window - A container widget similar to the Panel but has the customizable title bar. Properties Editor Panel The properties for all layers and widgets are managed using this panel. Description The Properties Editor displays options for the currently-selected object (layer or widget), or the options for the active screen if no objects are selected. To edit an option: left-click the value in the right column and then change the value. Some values have an ellipsis that will provide additional options. In the previous case, the ellipsis button will display the Color Picker dialog. Some properties, like the screen width and height, are locked and cannot be edited. Other properties offer check boxes and combo-type drop-down box choices. Some properties are grouped together like the Position and Size entries. Individual values of the group can be edited by expanding the group using the plus symbol. For example, the following figure shows properties for a Button Widget. A new support feature is the ? icon to the right of the Scheme pull-down, which brings up an “Scheme Helper” for the widget showing how it is colored when using a Bevel border. For a more complete description of widget coloring, see Widget Colors. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 28 Object Properties Provides information on widget, layer, and screen properties. Description Object Properties and Event Actions Each widget has a structured tree of properties, visible under the MPLAB Harmony Configurator window on the right of the standard window setup within MPLAB X IDE. Most widget properties have a Related Event action that can be use in an event or macro to change or set a property from the application. Each widget has 3-4 property sets: Editor – Controls the behavior of layers and widgets under the MPLAB Harmony Graphics Composer Suite Editor. Property Name Type Description Related Event Actions Locked Boolean Locks the object (widget), preventing changes by the designer. Only affects the object (widget) in the editor. N/A Hidden Boolean Hides the widget and its children in the designer window. Only affects the appearance of the widget in the editor. N/A Active Boolean For layers only. Sets the layer as active. Any objects (widgets) added to the screen will be added to this layer. N/A Locked to Screen Size Boolean For layers only. Locks the layer size to the size of the display’s screen. N/A Widget – Controls the behavior of screens, layers, and widgets on the display. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 29 Property Name Type Description Related Event Actions Name String Editable name for each object. By default, widgets are named NameWidget1, …,NameWidgetN. For example: ButtonWidget1, ButtonWidget2, … . N/A Position [X,Y] Pair of Integers Location on the layer of the upper left corner of the widget or the location on the display of the upper left corner of the layer. Measured in display pixels. X is measured from left-to-right and Y is measured from up-to-down from the upper left corner of the parent object (typically a Layer or Panel). Adjust Position, Set X Position, Set Y Position Size [X,Y] Pair of Integers X: Width, Y: Height of object, in display pixels. Adjust Size, Set Size, Set Width, Set Height Enabled Boolean Is the object enabled? Disabled objects are not built into the display’s firmware. Set Enabled Visible Boolean Is the object visible by default? Object visibility can be manipulated in firmware using laWidget_GetVisible and laWidget_SetVisible. Set Visible Border Widget Border Choices are: { None | Line | Bevel }. Set Border Type Margin Integer Four integers ([Left,Top,Right,Bottom]) defining the widget’s margins on the display, in display pixels. Set Margins Scheme Color scheme assigned to the layer or widget. Blank implies the default color scheme. Set Scheme Background Type Sets the background of the layer or widget. Choices are { None | Fill | Cache }. In MPLAB Harmony v2.03, this type was Boolean. Now, Off = None, On = Fill. With Fill selected, the widget's background is one solid color. With Cache selected, a copy (cache) of the framebuffer is created before the widget is drawn and this cache is used to fill the background of the widget. This supports transparent widgets in front of complex widgets, such as JPEG images. Instead of rerendering the JPEG image, it is just drawn from the cache. Set Draw Background Alpha Blending Boolean Is alpha blending enabled for this layer or widget and all of its children? If enabled, specify the amount of alpha blending as an 8-bit integer. Zero makes the object invisible, whereas 255 makes the background invisible. N/A Widget Advanced – Advanced control of layers and widgets Optimization Sub-Property Name Type Description Related Event Actions Draw Once Boolean Indicates that the widget should draw once per screen Show Event. All other attempts to invalidate or paint the widget will be rejected. N/A Force Opaque Boolean Provides a hint to the renderer that the entire area for this widget is opaque. Useful for widgets that may use something like an opaque image to fill the entire widget rectangle despite having fill mode set to None. This can help reduce unnecessary drawing. N/A Local Redraw Boolean Provides a “hint” to the widget’s renderer that the widget is responsible for removing old pixel data. This can avoid unnecessary redrawing. N/A Important! Use Local Redraw only if you know what you’re doing! Widget Name (e.g., Button Check Box, Circle, etc.) – Optional properties tied to each widget. See Dedicated Widget Properties and Event Actions. Events – Associates widget events with event call-backs. For example, you can enable and specify a button pressed event and button release event for the Button widget. For each event you specify: • Enabled/Disabled Check box – To enable or disable (default) the event. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 30 • Event Callback – Selected from the Event Editor Action List. There are additional Event actions that do not correspond to any specific property: • Set Parent – Set the parent of the object, including no parent. Dedicated Widget Properties and Event Actions Button Property Name Type Description Related Event Actions Toggleable Boolean Is button toggle enabled? Set Toggleable Pressed Boolean If Toggleable is enabled, provide default state of the button. This can be used to see the colors of an asserted button. Set Press State Text String Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical Text string alignment within the button object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Pressed Image Select image used for pressed state. Default: no image. Set Pressed Image Released Image Select image used for pressed state. Default: no image. Set Released Image Image Position Position of image relative to button text. Choices are: { LeftOf | Above | RightOf | Below | Bottom }. Set Image Position Pressed Offset Integer Offset of button contents when pressed. In Pixels. The X and Y position of the button contents is offset by this amount. Set Pressed Offset Check Box Property Name Type Description Related Event Actions Text String Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical Text string alignment within the button object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Checked Boolean Default state of the check box. Set Check State Unchecked Image Select image used for widget’s unchecked state. Default: no image. Set Unchecked Image Checked Image Select image used for the widget’s checked state. Default: no image. Set Checked Image Image Position Position of image relative to check box text. Choices are: : { LeftOf | Above | RightOf | Below | Bottom }. Set Image Position Image Margin Integer Space between image and text. In Pixels. Set Image Margin Circle Property Name Type Description Related Event Actions X Integer X offset of circle’s center, from widget’s upper left hand corner, in pixels. N/A Y Integer Y offset of circle’s center, from widget’s upper left hand corner, in pixels. N/A Radius Integer Circle’s radius, in pixels. Set Radius Draw Surface – No additional properties. Gradient Property Name Type Description Related Event Actions Direction Gradient draw direction. Choices are: { Right | Down | Left | Up }. Set Direction Group Box MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 31 Property Name Type Description Related Event Actions Text String Select widget’s text string from the Select String Dialog. Set Text Alignment Text string alignment within the widget. Choices are: { Left|Center|Right }. Set Alignment Image Sequence Property Name Type Description Related Event Actions Sequence Configuration Dialog Specify image sequence by using the Image Sequence Configuration Dialog window. Set Entry Image, Set Entry Horizontal Alignment, Set Entry Vertical Alignment, Set Entry Duration, Set Image Count Starting Image Integer Selects the first image to be shown. Set Active Image Play By Default Boolean Will image sequence play automatically? N/A Repeat Boolean Should the image sequence repeat? Set Repeat Additional related event actions: , Show Next, Start Playing, Stop Playing. Image Widget Property Name Type Description Related Event Actions Image Select image used. Set Image Alignment: • Horizontal • Vertical Image alignment within the image object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Key Pad Property Name Type Description Related Event Actions Row Count Integer Number of key pad rows. None. Column Count Integer Number of key pad columns. None. Key Pad Configuration Dialog (see Description) The Key Pad dialog window has the following: • Width – Integer. Width of each key, in pixels. • Height – Integer. Height of each key, in pixels. • Rows – Integer. Number of key rows. A duplicate of Row Count. • Columns – Integer. Number of key columns. A duplicate of Column Count. None. None. None. None. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 32 - - Selecting one of the keys on the key pad diagram displays the Cell Properties for that key: • Enabled – Boolean. Disabled cells (keys) are made invisible. • Text String – Select key’s text string from the Select String Dialog. • Pressed Image – Select image used for pressed state. Default: no image. • Released Image – Select image used for released state. Default: no image. • Image Position – Position of image relative to key text. Choices are: { LeftOf | Above | RightOf | Below | Behind }. • Image Margin – Integer. Space between image and text. In Pixels. • Draw Background – Boolean. Controls whether the key should fill its background rectangle. • Editor Action – Select the generic editor action that fires when the key is clicked. Choices are: { None | Accept | Append | • Editor Value String Other Key Event Actions: Set Key Enabled Set Key Text Set Key Pressed Image Set Key Released Image Set Key Image position Set Key Image Margin None. Set Key Action Set Key Value Set Key Background Type Label Property Name Type Description Related Event Actions Text String Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical Text string alignment within the widget. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Line Property Name Type Description Related Event Actions Start X Integer X start of line, in pixels, from upper left hand corner of the widget. Set Start Point Position Start Y Integer Y start of line, in pixels, from upper left hand corner of the widget. Set Start Point Position End X Integer X end of line, in pixels, from upper left hand corner of the widget. Set End Point Position. End Y Integer Y end of line, in pixels, from upper left hand corner of the widget. Set End Point Position. List Property Name Type Description Related Event Actions Selection Mode Select list selection mode. Choices are: {Single|Multiple|Contiguous}. Set Selection Mode Allow Empty Selection Boolean Is a list selection allowed to be empty? Set Allow Empty Selection Alignment Horizontal text alignment. Choices are: { Left | Center | Right }. Set Item Alignment Icon Position Position of list icons relative to list text. Choices are: { LeftOf | RightOf }. Set Icon Position Icon Margin Space between icon and text, in pixels. Set Icon Margin List Configuration Dialog Defines the string and icon image for each entry in the list. Set Item Icon, Set Item Icon (actually sets item text). Additional Related Event Actions: Deselect All Items, Insert Item, Remove All Items, Remove Item, Select All Items, Set Item Selected, Toggle Item Select(ed). MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 33 List Wheel Property Name Type Description Related Event Actions Alignment Sets horizontal text alignment. Choices are: { Left | Center | Right }. Set Item Alignment Icon Position Position of icons relative to text. Choices are: { LeftOf | RightOf }. Set Icon Position Icon Margin Integer Sets the space between icon and text. In pixels. Set Icon Margin Selected Index Integer Selects the default list item. Set Selected Index List Configuration Dialog Defines the image/text for each entry in the list. Set Item Icon, Set Item Icon (actually sets item text) Additional Related Event Actions: Append Item, Insert Item, Remove All Items, Remove Item, Select Next Item, Select Previous Item. Panel – No additional properties. Progress Bar Property Name Type Description Related Event Actions Direction Direction of progress bar. Choices are: { Right | Down | Left | Up }. Set Direction Value Default value of the progress bar. The primitives laProgressBarWidget_GetValue and laProgressBarWidget_GetValue can be used to manipulate the widget’s value during run time. Set Value Radio Button Property Name Type Description Related Event Actions Text String Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical Text string alignment within the widget. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Group Integer Radio Button Group Number. Default is -1, indicating no group. Only one radio button in a group can have a default selected value of On. All others in the group are Off N/A Selected Boolean If selected, the button has a default value of On. All other buttons in the group have a Selected value of Off. Select Selected Image Select image used for selected state. Default: no image. Set Selected Image Unselected Image Select image used for unselected state. Default: no image. Set Unselected Image Image Position Position of image relative to widget text. Choices are: { LeftOf | Above | RightOf | Below | Behind }. Set Image Position Image Margin Space between radio button image and text, in pixels. Set Image Margin Rectangle Property Name Type Description Related Event Actions Thickness Integer Line thickness in pixels. Set Thickness Scroll Bar Property Name Type Description Related Event Actions Orientation Scroll bar orientation. Choices are: { Vertical | Horizontal }. Set Orientation Maximum Integer Maximum scroll value (minimum = 0.) Set Maximum Value MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 34 Extent Integer Length of scroll bar slider, re scroll bar maximum value. Indicates the number of lines or size of window visible at each scroll setting. Set Extent Value Integer Initial scroll bar value. Set Value, Set Value Percentage Step Size Integer Step size value of scroll bar arrow buttons. ( Min = 1, Max = 9999 ). Set Step Size Additional Related Event Actions: Step Backward, Step Forward Slider Property Name Type Description Related Event Actions Orientation Orientation of the slider. Choices are: { Vertical | Horizontal }. Set Orientation Minimum Minimum slider value. Set Minimum Value Maximum Maximum slider value. Set Maximum Value Value Initial slider value. Set Value, Set Value Percentage Grip Size Grip size of slider, from 10 to 9999, in pixels. Set Grip Size Additional Related Event Actions: Step Text Field Property Name Type Description Related Event Actions Text String Select widget’s text string from the Select String Dialog. Clear Text followed by Append Text Alignment Horizontal alignment. Choices are: { Left | Center | Right }. Set Alignment Cursor Enable Boolean. Show blinking cursor while editing. Set Cursor Enabled Cursor Delay Cursor delay in milliseconds. From 1 to 999,999. Set Cursor Delay Additional Related Event Actions: Accept Text, Append Text, Backspace, Clear Text, Start Editing. Touch Test – No dedicated properties. Window Property Name Type Description Related Event Actions Title String Select widget’s title string from the Select String Dialog. Set Title Icon Image Select image used. Default: no image. Set Icon Image Margin Integer Space between icon and title, in pixels. N/A Layer Properties and Event Actions The property list for a graphic layer is close in look and feel to that of a widget. Each Layer has three property sets: Editor (see above), Widget (see above), and Layer (see below). Layer Properties Property Name Type Description Related Event Actions Transparency Enabled Boolean Automatically mask out pixels of with a specified color. If enabled Specify: N/A Mask Color Integer Red/Green/Blue or Red/Green/Blue/Alpha color value N/A All Input Passthrough Boolean Allow input events to pass through this layer to layers behind it. N/A VSync Enabled Boolean Layers should swap only during vertical syncs. N/A MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Properties Editor Panel © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 35 Buffer Count Integer Integer number of frame buffers associated with this layer, either 1 or 2. N/A Buffer N For each buffer (N= 1 or 2) you specify: Allocation Method Buffer allocation method. Choices are: { Auto | Address | Variable Name } • Auto – Automatically allocate frame buffer space • Address – Specify a memory address • Variable Name – Use variable name as buffer location N/A Memory Address If Address is the allocation method, specify the raw (physical) memory address as a hexadecimal number. N/A Variable Name String If Variable name is the allocation method, specify the variable name as a string value. N/A Screen Properties and Events The property list for a screen shares the Name and Size properties with Layers and Widgets but has these unique properties. Screen Properties Property Name Type Description Related Event Actions Orientation Display orientation: 0, 90, 180, 270 Degrees. This can also be set using the Display Manager. N/A Mirrored Boolean Enables screen mirroring. N/A Layer Swap Sync Boolean Enables that all layer buffer swapping happen at the same time, delaying lower layers until higher layers are finished drawing as well. For example, assume you make changes to layer 0 and layer 1 and you want to see those changes show up on the screen at the same time. Without this option you’d see layer 0’s changes as soon as it finishes when layer 1 has not yet started drawing. This option will hold layer 0’s swap operation until layer 1 finishes as well. Note: Currently, this property is only supported by the CLCD Graphics Controller Driver and is ignored by all other drivers. N/A Persistent Boolean Indicates that the screen should not free its widgets and memory when it is hidden. This results in faster load times and persistent data, but at the cost of higher memory consumption. N/A Export Boolean Includes this screen the application build. This can also be set using the Screens panel. N/A Primary Boolean Sets this screen as the primary screen. The primary screen is the first screen displayed when the application starts. This can also be done using the Screens Panel Generate check box. N/A Graphics Composer Asset Management The Asset menu supports managing all graphical assets (memory, images, languages, fonts, strings, and binary data). Memory Configuration Provides information on configuring memory locations. Description The Memory Locations window is launched from the Graphics Composer’s Asset menu. Selecting Memory Locations this brings up a window with three sub-tabs (in this example, the Aria Showcase demonstration is referenced): MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 36 Window Toolbar The window’s tools icons support: 1. Add New Memory Location – This supports multiple external memory resources. 2. Delete Selected Memory Location – Removes a previously defined memory location. 3. Rename Selected Memory Location – Renames a previously defined memory location. 4. Configure External Media Application Callback – This allow definition of media callbacks, which must be provided in the project. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 37 5. Show Values as Percent – Memory utilization on the bar graph can be in bytes or as a percent of the total internal flash memory assigned to support asset storage. (That memory allocation is set using the Configuration sub-tab.) The APIs for the external media callback functions are as follows: GFX_Result app_externalMediaOpen(GFXU_AssetHeader* asset); GFX_Result app_externalMediaRead(GFXU_ExternalAssetReader* reader, GFXU_AssetHeader* asset, void* address, uint32_t readSize, uint8_t* destBuffer, GFXU_MediaReadRequestCallback_FnPtr cb); void app_externalMediaClose(GFXU_AssetHeader* asset); The graphics demonstration project, aria_external_resources, provides an example of how to write these callbacks. This demonstration supports three types of external memory: SQI External Memory, USB Binary, and USB with File System. Examples of these callbacks are found in the project’s app.c file. The Aria demonstration projects Aria External Resources and Aria Flash provide more details on how to use external memory to store graphics assets. Sub-tabs There are three sub-tabs to this window. Summary Sub-tab This sub-tab summarizes program flash allocations for images, strings, and fonts. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 38 The memory allocation shown for “Font Glyphs” measure the space that holds all the font glyphs used by the application, either by static strings or by glyph ranges defined in support of dynamic strings. Strings are defined by arrays of pointers to glyphs, so string memory usage measures the size of these arrays, not the actual font glyphs used. (“Glyph” is defined here.) Note: The word “glyph” comes from the Greek for “carving”, as seen in the word hieroglyph – Greek for “sacred writing”. In modern usage, a glyph is an elemental or atomic symbol representing a readable character for purposes of communicating through writing. Configuration Sub-tab This sub-tab specifies the intended allocation of internal (program) flash memory to graphics assets (Total Size). (The default value is 1024 bytes.) It also names the graphics assets file name (here it will be gfx_assets.c). The allocation of flash is only used to scale the Total/Used/Available bar graph at the top of the display. Under sizing or oversizing this amount does not affect how the application is built. If your device has 1024 Kbytes (1048576 bytes) of flash, you can assign 40% to asset storage and 60% to code. In that case the “Total Size” in the above sub-tab would be set to 419430 (= 40% of 1048576). The Calculator button can assist you in allocating internal flash. Click on it and then set the device flash capacity. Then you can apply an adjustment to that value to assign that memory to asset storage. Example: If the device has 2 Mbytes of internal Flash, click 2MB. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 39 Then, to assign 75% of the 2 Mbytes to asset storage, click -25% to reduce the 2 MB by 25%, leaving 75%, and then click OK to finish. This will then assign 1,536,000 bytes to asset storage. Internal (program) Flash is shared between the application’s code and asset storage. If the application code and graphics assets (fonts, strings, images) won’t fit into the available flash memory then the linker will be unable to build the application and an error will be generated in MPLAB X IDE. The Output File Name must be compatible with the operating system hosting MPLAB X IDE. In most cases the default name (gfx_asset.c) will suffice, but this is provided for additional flexibility in building the application. Optimization Sub-tab The Optimization sub-tab for the Aria Quickstart demonstration is shown in the following figure. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 40 The Size column shows the bytes allocated for storage in internal flash for the images, fonts, and binaries of the application. The References column shows the number of known references for these assets by the application’s widgets. A references count of zero suggests that the asset is not used by the application, but it could also mean that the asset is only used in real-time when it is dynamically assigned to a widget by the application. Clicking the title of a column (Name, Size, or References) sorts the lists of graphics assets by that column. Clicking the same column again reverses the sort order. The window’s tools icons support: 1. Edit Selected Asset – This brings up the edit dialog for the image, font, or binary chosen 2. Delete Selected Assets – Removes the selected assets 3. Move Selected Assets – Move assets from one location to another. This is useful for moving assets to/from internal memory from/to external memory. 4. Show Only Images – Show image assets toggle on/off 5. Show Only Fonts – Show font assets toggle on/off 6. Show Only Binaries – Show binary assets toggle on/off Image Assets Provides information on the Image Assets features. Description The Image Assets window is launched from the Graphics Composer’s Asset menu. The Image Assets window lets you import images, select different image formats/color modes for each image, select compression methods (for example, RLE) for each image, and displays the memory footprint of each. Images can be imported as a BMP, GIF, JPEG, and PNG (but not TIFF). Images can be stored as Raw (BMP, GIF), JPEG, and PNG. Note: MHGC does not support image motion that can be found in GIF (.gif) files. GIF images are stored in the raw image format, meaning that there is no image header information stored with the image. When an image is imported into MGHC, the Graphics Asset Converter (GAC) stores the input format and color mode along with any relevant header data. The image’s pixel data is then promoted from its native format into a Java Image using 32 bits/pixel (8 bits for each color, RGB, and 8 bits for Alpha Blending). If the image contains Alpha Blending then this information is stored in the “A” of RGBA, otherwise the “A” is set to maximum opacity. When the application is built each image is stored in the image format and color mode selected. Images displayed in the Screen Designer are converted from Java Image format into the format/color mode selected so that the Screen Designer accurately represents what the application will show when running. The images are decoded on the fly by the graphics library and rendered on the screen. This provides the designer with considerable flexibility to MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 41 import using one format and store resources using another format, thus exploring and maximizing the best memory utilization for their application and hardware. This supports trading a smaller memory footprint at the cost of additional processing (for static or drawn-once) or reducing processing at the cost of a larger memory footprint (dynamic or drawn many times). The following figure shows the Image Assets window for the Aria Quickstart demonstration. Window Toolbar There are five icons on the toolbar below the Images tab: 1. Add Image Asset – Brings up “Import Image File” dialog window to select image file to add to the graphics application. 2. Replace Existing Image with New Image File – Brings up the same “Import Image File” dialog but instead of creating a new image, the file’s content replaces the currently selected image. 3. Rename Selected Image – Renames the selected image. 4. Create New Virtual Folder – Creates a new virtual folder, allowing you to organize images in a hierarchy. 5. Delete Selected Images – removes the selected images from the application. Selecting the Add Image Asset or Replace Existing Image icon opens the Import Image File dialog that can be used to select and import an image. After selecting the file and clicking Open, the Image Assets window opens. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 42 The size of the memory used for this image based on its color mode, format, compression, and global palette usage is shown by Size (bytes). See Image Format Options below for more details. The File Name of the original source file is also shown, but may be blank if the image was imported under MPLAB Harmony v2.03b or earlier. The format and color mode of the stored image can be changed to reduce the image’s memory footprint. (If using an LCC controller, you can also turn on the Global Palette, replacing each pixel in the image with just an 8 bit LUT index.) The three internal image formats are: • Raw – binary bit map with no associated header information. GIF and BMP images are imported into this format. • PNG – lossless image format with compression, 24 bits/pixel (RBG_888) or 32bits/pixel (RGBA_8888). A good choice for line drawings, text, and icons. • JPEG (JPG) – loss compressed format, uses much less storage than the equivalent bit map (raw). Good for photos and realistic images. The Image Assets window supports resizing, cropping, or resetting an image: • Resize – Brings up a dialog window to change the pixel dimensions of the image. The image is interpolated from the original pixel array into the new pixel array. • Crop – Places a cropping rectangle on the image. Click and drag a rectangle across the image to select the new image. Then click Ok to crop the image. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 43 • Reset – Allows undoing of a resize or crop. The original image is always stored in the project, so a Reset is always available to return the image to its original state. Original images are retained by MHGC by the superset Java Image format. So an image crop will change how the image is stored in the application but not how it is stored in MHGC. Reset will always restore the image back to the original pixels. (Reset is not an “undo”.) Example Images Example images are available from many sites on the internet. One of the best sites is found at the USC-SIPI Image Database (http://sipi.usc.edu/database/). There are many canonical test images, such as Lena, The Mandrill (Baboon), and other favorites, all in the TIFF format. The TIFF format is not supported by the Graphics Composer, but you can easily convert from TIFF to BMP, GIF, JPEG, or PNG using the export feature found in the GNU Image Manipulation Program (GIMP), which is available for free download at: https://www.gimp.org. GIMP also allows you to change the pixel size of these images, usually 512x512, to something that will fit on the MEB II display (either 256x256 or smaller). The following figure shows the Graphics Composer Screen Designer for the pic32mz_da_sk_meb2 configuration of the Aria Quick Start project after adding three images. The following figure shows the Optimization Tab after adding these images. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 44 Selecting the Baboon_GIF image and the Edit Selected Asset icon ( ) opens an Image Assets window, as shown in the following figure. Because this image had only 253 unique pixel colors (Unique Pixel Count = 253) the Enable Palette option was automatically enabled. This feature, which works on an image by image basis, is separate from enabling a Global Palette. The image is stored using 8 bits of indexing into an image-specific lookup table (LUT). If the image has more than 256 unique colors then the Enable Palette option is not available and is not shown. Image Format Options Raw Format Images Raw format images have the following options: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 45 Regardless of the Color Mode of the imported the image, the stored image can be stored in a different color mode. For example, a JPEG image could be in 24 bits/pixel RGB format but stored in the application using RGB_565 or even RBG_332 to save space. The Project Color Mode (set through the File > Settings menu) is different from the Color Mode of images. This is determined by the capabilities of the projects graphics controller. The graphics library converts images from the stored color mode to the project’s color mode before output. If the image has 256 or less unique pixel colors an option to Enable Palette is set by default. If the image has more than 256 unique colors this option is not displayed. This replaces the palette pixels with 8-bit indices into the image’s palette look up table (LUT). NOTE: Enabling the Global Palette disables this for all images and all image pixels are replaced by 8-bit indices into the global palette LUT. The Compression Mode for a raw format image is either None (no compression) or RLE for run-length encoding. Image masking is a form of cheap blending. For example, given the following image, you may want to show the image without having to match the lime green background. With image masking you can specify that the lime green color as the “mask color”, causing it to be ignored when drawing this image. The rasterizer will simply match a pixel to be drawn with the mask. If they match, the pixel is not rendered. PNG Format Images For PNG format images you can change the image format and the image color mode: JPEG Format Images For JPEG format images you can change from JPEG format to Raw or PNG: Once changed from JPEG into another format, the new format will have other options. Managing Complex Designs The Image assets tool lists the images in the order of their creation. In a future version of MPLAB Harmony this will be sortable by image name. For now, it is recommended that you use the Memory Locations asset tool, and use the Optimization sub-tab instead to manage a complex set of images. The Optimization sub-tab allows you to sort graphics assets (fonts, images, binaries) by Name, Size, and number of widget References. This makes it much easier to find and edit an image by its name rather than order of creation. Font Assets Provides information on the Font Assets features. Description The Font Assets window is launched from the Graphics Composer’s Asset menu. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window • Fonts are managed within the Font Assets window (this topic) • Strings are managed within the String Assets window The following figure shows the Font Assets window from the Aria Coffee Maker demonstration. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 46 The Size (bytes): for a Font asset shows how much memory is needed to store all the glyphs used by the application from this font. For static strings MHGC determines which glyphs are used by the application’s pre-defined strings and builds these glyphs into the application. For dynamic strings (i.e. strings created during run time) ranges of glyphs are selected by the designer and these ranges are also included in the application by MHGC. The memory needed to store all these glyphs is shown by Size (bytes): . Window Toolbar There are five icons on the toolbar below the Images tab: 1. Add Font From File – Adds a font asset from a file. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 47 2. Add Installed Font – Add a font installed on your computer. 3. Replace Existing Font Data with New Source Font – Both Add Font From File and Add Installed Font create a new font asset. This icon allows you to update an existing font asset, importing from a file or using a font installed on your computer. 4. Rename Selected Font – Renames an existing font asset. In the example above, the Arial font was installed twice, first as a 16 point font and second as a 12 point font. If added to the fonts assets in this order, the 12 point font will have the name Arial_1. This font asset was renamed to Arial_Small using this tool. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 48 5. Delete Selected Fonts – Removes selected font assets from the application. Sub-tabs There are three sub-tabs to this window. Style Sub-tab The Size (bytes): shown represents the memory needed to store all the font’s glyphs. The application only stores the glyphs that are used by static (build-time) strings and by predefined glyph ranges to support dynamic (run-time) strings. The choices for Memory Location must be defined before the font can be assigned. Go to the Memory Configuration window to add a new location before using it in this sub-tab. Each font asset consists of a font, size, and some combination of the { Bold, Italic, Anti-Aliasing } options, including selecting none of these options. If you need bold for one set of strings and italic for another, then you will need two font assets, one with Bold checked and a second with Italic checked. The same applies for font sizes. Each font size requires its own font asset. Thus if you need two sizes of Arial, with plain, bold, and italic for each size, you will need 6 separate assets (6 = 2 Sizes x 3 ). Glyphs are normally (Anti-Aliasing off) stored as a pixel bit array, with each pixel represented by only one bit. Turning on Anti-Aliasing replaces each pixel bit with an 8-bit gray scale, thereby increasing font storage by a factor of 8! What if a font is chosen that does not support the character types of the text used for a particular language in the application? How can you test and debug this? There a basically two ways: • Use an external font viewer to examine if the needed glyphs exist • Configure, build, and run the application and verify the strings are correctly rendered If the glyphs are not available they will be rendered as rectangles ( ). MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 49 Strings Sub-tab The Bound check box accomplishes the same thing as assigning a font to a text string in the Strings Assets window (Window:Strings menu). Assigning a string to a font means that the font will generate glyphs for that string. This is just another way to accomplish the binding of the string text to font. This sub-tab is also useful in a complicated graphics design to see how many strings use a particular font. Lightly-used or unused fonts can be eliminated to free up internal Flash memory. Glyphs Sub-tab Note: The word “glyph” comes from the Greek for “carving”, as seen in the word hieroglyph – Greek for “sacred writing”. In modern usage a glyph is an elemental or atomic symbol representing a readable character for purposes of communicating via writing. The Glyph sub-tab is only used when your application supports dynamic strings. For static (build-time) strings MHGC automatically determines which font glyphs are used based on the characters present in all the strings used by the application’s graphics widgets. Only these glyphs are included as part of the application’s font assets. With dynamic (i.e. run-time) strings this is not possible. This sub-tab allows you to specify which range of glyphs will be used by run-time strings. Once glyph ranges are defined, these glyphs are added to the font glyphs used by static strings. The Create New Custom Import Range icon ( ) allows you to input a new glyph range for the font. Selecting this icon opens the Font Assets window. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 50 String Table Configuration Provides information on the String Assets features. Description The String Table Configuration window is launched from the Graphics Composer’s Asset menu. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window (this topic) • Fonts are managed within the Font Assets window • Strings are managed within the String Assets window Within this window, the Languages supported by the application are defined and the encoding for all application glyphs selected. The “ID” string used for each language is merely for ease of use in building the texts to be used. “English”, “American”, or any other string can be used to identity that language, as long as it is understood by the application’s creator when selecting the text to be used for that particular language. Then the application can switch to supporting one of its languages using “ID” strings defined. Here is an example string asset definition, taken from the Aria Coffee Maker demonstration. This application supports English, French, Italian, and German. The text string “InfoText_Desc9” uses the Arial font, and text for each language is specified within the String Assets window. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 51 Any number of languages can be defined as long as there is memory to store the strings needed. The following figure shows the String Table Configuration for an application that uses English, Spanish, and Chinese. The size of all the strings for each language is shown in the Size column. String size represents the memory allocated for glyph indices for all the strings supporting that language. A language can be enabled/disabled via the check box in the Enabled column. Disabling a language removes it from the application build but keeps it in the project. Window Toolbar There are three icons on the toolbar: 1. Add New Language – Adds a new Language. 2. Set Default Language – Sets the application’s default language. Note, this is different than the abc tool on the Graphics Composer Window toolbar. The abc icon sets the preview language for the Screen Designer panel only. This icon sets the language used by the application after boot-up. 3. Remove Selected Language – Removes language from the application. Clicking Add New Language opens a new line, allowing you to select and edit the new language’s “ID” string. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 52 Then, for every string defined in the application there will be a line to define the needed text, and to specify the font to be used. If you don’t provide a value for the new language the string will be output as a null (empty string). If you don’t provide a Font selection then the string will be output as a series of blocks (?). The Aria User Interface Library primitive, LIB_EXPORT void laContext_SetStringLanguage(uint32_t id), allows the application to switch between languages using the Language ID #defines are specified in the application’s gfx_assets.h file. Sub-tabs There are two sub-tabs to this window. Language Definitions Sub-tab This sub-tab shows the languages defined for the application. A Language can be enabled/disabled to include or exclude it from the application’s generation/regeneration under MPLAB Harmony Configurator (MHC). New languages can be added by specifying a text string for the language. With a new language, go to the String Assets window to specify the text and fonts for all defined strings. Encoding Sub-tab Selecting the Character Encoding Format Selection Dialog icon gives you three choices for how the characters in all strings in the graphics application are encoded: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 53 The default is ASCII. It is typically the most efficient in terms of memory and processing, but it does not support as many glyphs. Chinese text should be encoded in UTF-8 or UTF-16, but Western language text can be encoded in ASCII to save memory. The trade-off between ASCII, UTF-8, and UTF-16 depends on the application. Changing from UTF-8 to UTF-16 will double the size of all strings in the application. This is because the sizes of all glyph indices double in size. (String sizes are the sizes of glyph reference indices, not the size of the particular font glyphs used to write out the string.) The memory utilization resulting from an encoding choice can be seen in the Summary sub-tab of the Memory Configuration window. String Assets Provides information on the String Assets features. Description The String Assets window is launched from the Graphics Composer’s Asset menu. The String Assets window supports managing the strings in the application. Strings are referenced by graphic widgets using an application-wide unique name. This unique name is built into an enumeration that the application’s C code uses. For each language supported text is defined and a font asset selected. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window • Fonts are managed within the Font Assets window • Strings are managed within the String Assets window (this topic) The following figure shows an example taken from the Aria Coffee Maker demonstration. The string name, InfoText_Desc9, defines a string asset that is used by the application. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 54 The Total Size in Byte: for a string asset represents the memory needed to store the glyph indices for all the text defined for that string asset. Adding more text will increase the number of glyph indices needed thus increasing the size of the string’s memory. Adding another language will do the same, since the number of glyph indices also increases. Changing the font does not increase the size of the string’s memory, but may increase the size of the font chosen if it is a “bigger” font and adds more glyphs to the new font. (By “bigger” we mean a font with more pixels, for example because it is bigger in size, or perhaps because it is anti-aliased and the original font was not.) Note: The Reference Count shown reflects the number of build-time references to the string. Dynamic uses of a string, such as through macros or events, is not reflected in this number. Window Toolbar There are four icons on the toolbar: 1. Add New String – Adds a new string. 2. Rename Selected Item – Allows renaming the string. 3. Create New Virtual Folder – Creates a new virtual folder, allowing you to organize strings in a hierarchy. Here’s an example reorganization of the existing strings. Note the order of virtual folders or items in the list is strictly alphabetical. Virtual folders and string asset organization is merely for the convenience of the developer. Neither has an effect on how the application is built. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 55 4. Delete Selected Items – Deletes selected strings from the application. Creating New Strings To create a new string, click Add New String ( ). Selecting this icon opens the Add String dialog to name the string. The text chosen for the string name should be acceptable as a C variable. After entering the new string’s name and click Create, the following String Assets window appears. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 56 In the String Assets window, there will be a line for each of the languages defined for the application. Provide the string text and font for each of the languages. If you don’t provide the text an empty string will be used instead. Not providing a font causes the string to be rendered as a string of boxes ( ). Binary Assets Provides information on the Binary Assets features. Description The Binary Assets window is launched from the Graphics Composer’s Asset menu. Selecting the Add Binary File icon ( opens the Import File dialog. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Graphics Composer Asset Management © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 57 This supports any formatted binary file. Developers can then add a custom-coded decoder to support the format implied by the imported file. (A future version of the GFX library will include a bin2code utility in support of this feature.) MHGC Tools The Tools menu supports managing all graphics events, using a global palette, and estimating heap memory usage. Event Manager This section provide information on the Event Manager. Description The Graphics Composer Event Manager provides a GUI interface to manage all of the events associated with a graphics application. In a general sense, an event is an action or occurrence that is processed by software using an “event handler”. Button pushes or keystrokes are widely recognized and handled events. Events related to a touch screen are commonly called “gestures”. This GUI allows the assignment of actions to events associated with graphics widgets and to events outside of the graphics library. Under the Graphics Composer Event Manager tab there are two sub-tabs, one for “Events” and a second for “Macros”. “Events” under the first tab are generated from within graphics widgets and can manipulate the properties of screen widgets or set semaphores that engage with the rest of the application. “Macros” are executed outside of graphics widgets by other parts of the application. “Macros” allow the application to change widget properties or behavior. Both “Events” and “Macros” event handlers can be built using collections of “Template” actions or using “Custom” developer-provided code. Most widget properties have an associated Template action that can be used to manipulate that property in an event handler (either “Event” or “Macro”). For more information on properties and related actions, see the discussion on the Properties Window below. To explore these capabilities, let’s look at the Aria Quickstart project after the completion of the Adding an Event to the Aria Quickstart Demonstration Quick Start Guide. Graphics Composer Events The Graphics Composer Screen Designer shows that there is one layer and three widgets in this demonstration. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 58 Of the three widgets shown above, only ButtonWidget1 can have events associated with it, one for button pressed and a second for button released. This can be seen in the Graphics Composer Event Manager window, which is available from the Tools menu: The events shown under “ButtonWidget1” are mirrored in the widget’s properties. Selecting or clearing an event in one window does the same in the other window, thus enabling (selecting) or disabling (clearing) the corresponding event. We can add a Check Box widget to the applications display and then use the Event Manager to assign actions to the widget’s events. A Check Box widget has two events, one for being “Checked” (i.e., selected) and another for being “Unchecked” (i.e., cleared). Enabling the “Checked” event then allows the selection of the action or actions for that event. The Actions: sub-window has five tool icons for managing the actions associated with an event: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 59 Clicking the Create New Action icon ( ) opens the Action Edit dialog. If you select Custom and click Next, you will see the following dialog. Unfortunately, there is no C code error checking with this window. It just copies the code into libaria.c and libaria.h. If there is a problem with the code you will not know about it until you try to build your application. An alternative is just to type a comment such as /*My event goes here*/, generate the code, and then find out where this comment landed in the code. (Typically, inside libaria_events.c, or libaria_macros.c) You can then write the action routine from within the MPLAB X IDE editor and compile just that file to debug the code written. If you select Template, the Action Edit dialog will update, as follows. Select ButtonWidget1. As shown previously, you next need to select the widget that you want to manipulate with this action. Note that the event originated with CheckBoxWidget1, but the event’s action can manipulate any of the existing widgets. In this case, ButtonWidget1 has been selected. Clicking Next MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 60 will then bring up a list of the actions available in manipulating a button widget. You can select the “Set Text” action, which will then change the button’s text property, followed by NEXT, which will open a dialog to select the text string for this action. You can then select from the available (already defined) strings which text to use for the button’s text field. Press the Finish button to complete the definition of this action. Screen Events As shown previously, the Graphics Composer Event Manager, Events sub-tab supports screen events when the screen is visible (On Show) and hidden (On Hide). These events can define event handlers based on Template actions or Custom, user-defined code. Widget Events Not all widgets can generate an event. For example, a Label Widget has nothing to generate, it just sits there on the screen, labeling. Here is a list of the widgets that can generate an event: • Button – Pressed and Released events • Check Box – Checked and Unchecked events • Draw Surface – Draw Notification event • Image Sequence – Image Changed event MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 61 • Key Pad – Key Click event • List Wheel – Select Item Changed event • List – Selection Changed event • Progress Bar – Value Changed event • Radio Button – Selected and Deselected event • Scroll Bar – Value Changed event • Slider Widget – Value Changed event • Text Field – Text Changed event • Touch Test – Point Added event Graphics Composer Macros Macros implement event handlers for events that originate outside of graphics primitives such as widgets and are designed to change or manipulate widgets inside of the graphics part of an application. (Events that originate outside of graphics and don’t touch the graphics part of the application are outside of the scope of the Graphics Event Manager and are not discussed here.) The following figure shows a simple example of a macro. The toolbar for Macros has three icons. Creating a new macro and selecting its actions is just like that of a widget event: 1. Create a new macro using the “Create New Macro” tool. The check box to the left of the new macro’s name enables/disables the macro. Clearing it removes the macro from the next code generation. 2. Select the new macro and edit it using the second icon (shown previously). 3. In the Actions: window, select Create New Action. An optional name can be provided in the Name: box. You can then choose to use a Template and select a predefined action or Custom to create a customized action. 4. If you chose a “Custom” action, proceed as discussed previous in Graphics Composer Events. When using templates the next step is to choose the target widget for the action. This choice is limited to those only the widgets in the currently “active” screen. If your application has multiple screens and the widget you are targeting is not part of the currently active screen you need to change the active screen. • Changing the active screen can be done by selecting the corresponding screen tab at the bottom of the Graphics Composer Screen Designer • Alternately, you can switch using the Graphics Composer Manager:Screens tab MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 62 5. After selecting the target widget for this macro, click Next button to select an action related to this widget. (Just as with template-based widget events.) The macro can contain more than one action, targeting more than one widget. Heap Estimator Provides information on heap space allocation. Description Many parts of a graphics design are implemented using memory allocated from the application’s heap space. Therefore, it is important to allocate sufficient memory for the heap. This tool can estimate heap usage by the allocation based on the widgets, layers, screens, and decoders currently in the design. When launching the tool from the Tools menu, the Heap Configuration window appears. Clicking Calculate estimates heap usage. The following figure shows what occurs within the Aria Quickstart demonstration if the heap space is only 4096 bytes: MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 63 The Summary tab shows how the estimated heap requirements was derived by summing up all the sizes shown under the “Size (Bytes)” column. Note that the largest contribution comes from the screen requiring the largest heap allocation (in this case MainMenu). If there is insufficient memory allocated to the heap, an exclamation point ( ! ) appears in the window. If you hold your mouse pointer over this icon, the following message appears: You can click Set MHC Heap Value to reset the heap allocation to match the estimated requirements. Selecting Add to MHC Heap Value adds the estimated heap requirements to the current heap value. (In the case above, this would change the heap allocation to 4096+10664 bytes.) Alternately, you can set the heap allocation to a larger value by going to the MPLAB Harmony Configurator window, selecting the Options tab and setting the Heap Size within Device & Project Configuration > Project Configuration. The Screen Details tab (from the Aria Showcase demonstration) shows screen-by-screen the heap space needed for each layer and widget on the screen selected. Note: After you have updated the Heap Size, either using the Heap Estimator tool or by directly editing the value as shown above, you must regenerate the project using the Generate Code button. This will update the actual heap size value used in building the application. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 64 Clicking the “Name” column will alphabetize the list. Clicking the “Size (Bytes)” column sorts the assets by size, with the largest at the top and smallest at the bottom. This sub-tab can help in managing the application’s utilization of heap space. For example, excess use of cached backgrounds for widgets can become ruinously expensive, expanding the application’s need for heap well beyond the capabilities of the device. As an example, consider a screen label from the Aria Showcase demonstration. The Heap Estimator tool shows that if caching is enabled for the label’s background, this widget requires 23699 bytes of heap to store the widget. Note that the label is twice the size of the text it contains, so one way of reducing the cost of the widget is to make it smaller, thereby reducing the number of background pixels that must be stored. If the label is resized, the heap allocation is reduced to 11688 bytes, which is a drop of appoximately 50%. Finally, if the background is changed from “Cache” to “Fill” the widget only needs 188 bytes. The lesson learned is to use Cache as a background only for widgets where it is absolutely necessary and to make the “cached” widgets as small as possible. Global Palette Provides information on the Global Palette features. Description The Global Palette window is launched from the Graphics Composer’s Asset pull-down menu. Using a Global Palette enables frame buffer compression for the LCC graphics controller. It creates a 256 color look up table (LUT) and then changes the entire user interface design to adhere to that LUT. Frame buffers are stored as 8 bits/pixel (bpp) indices rather than 16-32 bpp colors. The display driver performs a LUT operation to change each LUT index into a color before writing to the display/controller memory. This enables the use of double buffering, without using external memory, on devices that could not support it before. It also supports single buffering on larger displays. Of course, running the LUT requires more processing on the host. Currently only the LCC graphics controller supports this feature. The Aria demonstration Aria Basic Motion is an example of how using a Global Palette greatly improves the efficiency and capabilities of a design. Enable the Global Palette by clicking on the Enable Global Palette check box in the window or using the File > Settings menu. the Global palette can always be disabled. MHGC will then restore the project back to its original configuration. If the global palette is enabled you will have to change the MHC configuration of the Graphics Controller to match. For the LCC controller, enable MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 65 "Palette Mode". For the GLCD controller, change the Driver Settings > Fame Buffer Color Mode to "LUT8". The results of enabling the Global Palette: • 8bpp frame buffers. In the case of the most common demonstrations this means a 50% reduction in the size of the frame buffer. • This also opens up the capability to support a single frame buffer for some larger displays. What is lost by enabling the Global Palette: • First and foremost - No Dynamic Colors. Dynamic colors are unlikely to match up with an entry in the global palette’s look-up table. • No alpha blending capability. The level of alpha blending can be changed during run-time. (See No Dynamic Colors.) • No JPEGs or PNGs. Again, no dynamic colors. All images in MGHC will be changed to the color mode of the project, and generated as Raw. • No font anti-aliasing. Again, no dynamic colors. While the 8-bits/pixel for each glyph is known, the color of the text depends on the color scheme used, and color schemes can change at run time. • Additional overhead when performing LUT (index->color) operations in the display driver. The following figure shows the default “Global Palette” when Project Color Mode is set to RGB_888. This default palette is good for designs that use a wide array of colors. MHGC also supports developing a custom palette by importing an image defining the palette or by analyzing the pixel colors already in use by the application’s images. The palette’s color mode is determined by the Project Color Mode, which is determined by the graphics controller. Clicking on an entry in the palette with bring up the Color Picker dialog window, allowing you to edit the entry’s color. Window Toolbar There are four icons on the toolbar: 1. Import From Image File - Importing a global palette from an image file. Selecting this brings up the following warning. Images can be imported as a BMP,.GIF, JPEG, and PNG (but not TIFF). 2. Auto-Calculate Palette – Calculates a new palette using the current design. Selecting this brings up the following warning. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 66 • Selecting Yes opens a status window that shows the progress made in selecting a palette of 256 colors • This can be lengthy operation, but it will effectively generate a palette better tailored to the design. However, extreme (or rare) colors will be changed to nearby, more-plentiful colors, thereby eliminating some of the contrast in images. Whites will tend to darken and blacks lighten. This can be remedied by editing the calculated palette to whiten the whites, darken the blacks, and make other colors closer to the original. This of course may increase the posterization of the image, but that is a natural trade-off in using only 256 colors. 3. Reset to Default – This returns the Global Palette to its default values, which opens the Reset Global Palette dialog. 4. Enable Global Palette – This performs the same function as File > Settings: Using a Global Palette. Selecting this opens the Enable Global Palette Mode warning. MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface MHGC Tools © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 67 Widget Colors Provides information on widget coloring. Description Widget Colors Widget coloring can be customized by creating additional color schemes and assigning these customized schemes to a subset of the widgets uses. For example, a ButtonColorScheme could be customized and used only for Button Widgets. To help highlight the different colors available for each widget, a “CrazyScheme”, with extreme contrast among the 16 available colors, was used as the color scheme for each widget: Use this color scheme to help identify the relevant colors for the widgets listed below. The left column shows the coloring assignments for a Bezel boarder. The right side shows Line/No Border color assignments. Widget With Bezel Border Widget With Line or No Borders MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 68 MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 69 MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 70 MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 71 MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 72 MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface Widget Colors © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 73 Code Generation This topic describes using the graphics composer to generate code. Description MPLAB Harmony Graphics Composer data is generated the same way as the rest of the project within MHC through the Generate button. libaria_harmony.h/c – These files provide the interface that binds libaria to the overall MPLAB Harmony framework. They contain the implementations for the standard state management, variable storage, and initialization and tasks functions. If the touch functionality is enabled then the touch bindings are also generated in libaria_harmony.c. libaria_init.h/c - These files contain the main initialization functions for the library state and screens. The header file contains all predefined information for the library state including screen IDs, schemes, and widget pointers. The main initialization function initializes all schemes and screens, creates all screen objects, and sets the initial state of the library context. As each screen must be capable of being created at any time, each screen has a unique create function that can be called at any time by the library. The libaria_init.c file contains these create functions. libaria_events.h/c – The event files contain the definitions and implementations of all enabled MHGC events. Each event implementation will contain all generated actions for that event. libaria_macros.h/c – The macro files contain the definitions and implementations of all defined MHGC screen macros. A macro is similar to an event in that it can contain actions. However, it is meant to be called from an external source such as the main application. libaria_config.h – This file contains configuration values for the library. These are controlled through settings defined in the MHC settings tree. gfx_display_def.c – This file contains generated definitions for enabled graphics displays. gfx_driver_def.c – This file contains generated definitions for enabled graphics drivers. gfx_processor_def.c – This file contains generated definitions for enabled graphics processors. gfx_assets.h/c – These files contain generated asset data. MPLAB Harmony Graphics Composer User's Code Generation © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 74 Advanced Topics This section provides advanced information topics for MHGC. Adding Third-Party Graphics Products Using the Hardware Abstsraction Layer (HAL) This topic provides information on using the Hardware Abstraction Layer (HAL) to add third-party graphics products. Description The architecture of the MPLAB Harmony Graphics Stack is shown in the following diagram. Hardware Abstraction Layer (HAL) The HAL is a software layer that serves as a gatekeeper for all graphics controller and accelerator drivers. This layer is configured at initialization by the underlying graphics drivers and provides functionality such as buffer management, primitive shape drawing, hardware abstraction, and draw state management. This layer serves as a means of protection for the drivers, frame buffers, and draw state in order to prevent state mismanagement by the application. Third-Party Graphics Library The third-party graphics library can be used with the MPLAB Harmony framework to perform the graphics operations desired by the application. The third-party library has access to the HAL, which has been configured to service the frame buffer which is filled by the third-party graphics library. The third-party graphics library can access the MPLAB Harmony framework drivers such as touch drivers, graphics controller driver, and display driver through the HAL. The draw pipeline and the user interface (UI) design files come from the third-party graphics library. The third-party graphics library needs the frame buffer location to fill the frame buffer with the pixel values. Or, in case of external controllers, it would need a function to access the controller drivers to output pixels on the display. The HAL provides the third-party graphics library with the frame buffer location or the API to communicate the pixel values to the external controllers. The following figure from the MPLAB Harmony Configurator (MHC), shows the selections made in the Graphics Stack to enable the needed graphics display and controller features. Note that the Draw Pipeline for the MPLAB Harmony Graphics Stack has been disabled to assure that the third-party graphics alone is taking effect. The MPLAB Harmony Graphics Configurator (MHGC) is also not enabled, as the design tools from the third-party graphics library are used to generate the UI graphics. The LCDConf.c file has appropriate APIs for the third-party graphics library to communicate through the HAL with the display drivers and the framebuffer. MPLAB Harmony Graphics Composer User's Advanced Topics Adding Third-Party Graphics Products Using the © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 75 Example Demonstration Project The Aria demonstration project, emwin_quickstart, has three configurations. Each configuration has an API named LCD_X_Config, which is generated with the relevant calls for SEGGER emWin to communicate with the display driver and obtain the frame buffer location pointer to write the pixel data to it. For PIC32MZ DA and PIC32MZ EF configurations, the frame buffer pointer address is provided to SEGGER emWin by the HAL. For the S1D controller on PIC32MX devices (pic32mx_usb_sk2_s1d_pictail_wqvga), The pixel write function pointers are assigned to the appropriate S1D driver APIs, which allow SEGGER emWin to write to the display controller. Speed and Performance of Different Image Decode Formats in MHGC Provides information and recommendations for image decode formats. Description MHGC supports various image formats and the MHGC Image Assets Manager provides the ability to convert and store a source image into to the following formats • Bitmap RAW • Bitmap Raw Run-Length Encoded (RLE) • JPEG • PNG • Predecoded RAW Bitmap in DDR (PIC32MZ DA) The following table shows the relative rendering time and Flash memory requirements of the different image formats in the MPLAB Harmony Graphics Library. The rendering time includes decoding the image and drawing it to the screen. This information is helpful when optimizing a MPLAB Harmony graphics project for performance and/or Flash memory space. For example, as shown by the red highlighted text in the table, a 40x40 pixel 16-bit RAW image renders 2.38 times faster and uses 2.59 times more Flash space than a JPEG image. MPLAB Harmony Graphics Composer User's Advanced Topics Speed and Performance of Different Image © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 76 Predecoded Images in DDR (RAW) For PIC32MZ DA devices with DDR, the MHGC Image Asset Manager provides an option to predecode images from Flash and store them into DDR as RAW images. The GPU is used to render the decoded image from DDR to the frame buffer. This provides a faster render time than an equivalent RAW image in Flash memory, specifically for large images (up to 10 times faster for a 200x200 image). Conversely, predecoding small images 40x40 pixels or smaller in DDR may not render faster due to the additional overhead of setting up the GPU. Recommendations: • If there is adequate DDR memory available, consider predecoding images to DDR for best performance • Using JPEG images and predecoding them into DDR can provide the best rendering performance and most Flash memory savings. Note: The images are decoded from Flash to DDR memory by the Graphics Library during initialization and may introduce delay at boot-up, depending on the number and size of the images. RAW Images RAW images provide fast rendering time, as there is no decoding needed. However, depending on image content, it can be two times larger than a Run-Length Encoded (RLE) image and about 3 to 10 times larger than a JPEG. Recommendation: For small images that are to be rendered frequently, consider using a RAW image for better performance JPEG Images JPEG images provide the most Flash space savings, but are slower to render compared to RAW and RAW RLE. Recommendations: • If images are large and not used frequently, consider using the JPEG image format to save flash memory space • If DDR memory is available, consider predecoding JPEG images in DDR for better rendering performance Run-Length Encoded RAW Images In terms of rendering speed and size, RAW RLE images are in between RAW and other compressed formats like JPEG or PNG. Depending on the image contents, RAW RLE can be approximately 1.5 times faster than JPEG, but could be significantly larger in size for large images. Again, depending on the image content, RAW RLE can be about half the size and performance of a RAW image. Recommendation: If optimizing your application for both speed and flash size consider using RAW RLE images PNG Images Among the image formats, PNG is slowest to render and requires more memory to decode. Recommendations: • Unless fine levels of alpha-blending are needed, it is better to use other image formats to achieve the best performance. Use the MHGC Asset Manager to convert the source PNG image and store it in a different image format. • If you would like to use an image with a transparent background, it may be better to use a RAW RLE image with background color masking to achieve the same effect with better performance than a PNG. Color masking is supported in the MHGC Image Asset Manager. MPLAB Harmony Graphics Composer User's Advanced Topics Draw Pipeline Options © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 77 Draw Pipeline Options This section details how to use the Graphics Pipeline. Description The nominal rendering pipeline for an image is shown in the following figure. The order of rendering for other widgets may differ. For example, for a colored rectangle the color mask is first checked. If the rectangle’s fill matches the mask color defined then there is nothing to draw. Graphics Pipeline Provides information on the graphics pipeline. Description Layer Clipping In order of the processing, Layer Clipping is first applied to the image. If the image extends beyond the edges of the layer that contains it then those pixels are not drawn. Failure to clip out-of-bound pixels can cause the application to crash. The following figures shows an example of layer clipping: Before applying layer boundaries: After applying layer boundaries: MPLAB Harmony Graphics Composer User's Advanced Topics Draw Pipeline Options © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 78 Rectangle Clipping Next, the image is clipped to the boundaries of any widgets that contain it as a parent, such as a rectangle. Before applying the clipping rectangle.: After applying the clipping rectangle: Color Masking of Pixels Pixels in the image are matched to a mask color. If the colors match the pixel is discarded (not drawn). In the following example, the black border of the image is removed by defining the mask color to be black. Before applying color mask: MPLAB Harmony Graphics Composer User's Advanced Topics Draw Pipeline Options © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 79 After applying color mask: Orientation and Mirroring The logical orientation of the graphics design may not match the physical layout of the display. Pixels may need to be reoriented from logical to physical space before being rendered. Pixels may also need to be flipped (mirrored) before being rendered. MPLAB Harmony Graphics Composer User's Advanced Topics Draw Pipeline Options © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 80 Alpha Blending Each pixel drawn is a composite of the image color and the background color based on the alpha blend value defined by a global alpha value, the pixels alpha value, or both. Before alpha blending: After alpha blending: Color Conversion The image color format may not be the same as the destination frame buffer. Each pixel must be converted before it is written. In the following example, the image is stored using 24 bits per pixel; however, the frame buffer uses 16 bits per pixel. MPLAB Harmony Graphics Composer User's Advanced Topics Draw Pipeline Options © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 81 Frame Buffer Write The final stage in rendering an image is to write each-color converted pixel to the frame buffer. Graphics Pipeline Options Provides information graphics pipeline options. Description Each stage in the graphics pipeline adds overhead to the rendering. Stages can be removed from processing using MPLAB Harmony Configurator (MHC) options for the Draw Pipeline, found by selecting MPLAB Harmony Framework Configuration > Graphics Stack. For example, the Alpha Blending stage can be disabled if your graphics application does not use alpha blending. If the color mode of the display matches the color mode of all images you can disable Color Conversion. Disabling unneeded stages can improve performance and reduce code size. Also, a graphics controller driver may add additional stages, or opt to bypass stages completely depending on the capabilities of the graphics hardware supported by the driver. Improved Touch Performance with Phantom Buttons This topic provides information on the use of phantom buttons to improve touch performance. MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 82 aria_coffeemaker Demonstration Example Provides image examples with buttons in the aria_coffeemaker demonstration. Description Small buttons are hard to activate on the screen. The use of phantom (invisible) buttons can improve touch performance without increasing the size of the visible footprint of the button on the display. The aria_coffee_maker has a sliding tray on each side of the display. Sliding a tray in, or out, is accomplished by a phantom (invisible) button. Looking at the left tray, we see the three parts of this phantom button. 1. LeftTrayLid: An invisible button widget, whose outline is shown in blue. This area is the touch field. 2. ImageWidget5: An image widget containing a hand icon, providing a visual clue as to how to manipulate the tray. 3. The Release Image and Pressed Image: These are defined as part of the button widget properties. The Pressed Image has a darker coloring than the Released Image. This difference is what shows the user that the button has been pressed. The drawing hierarchy for this part of the design is shows that ImageWidget5 is a daughter widget to the LeftTrayLid button widget. Examining the properties of the LeftTrayLid button widget reveals more about how this works. The following figure demonstrates these three properties. 1. The Border is defined as None. 2. Background Type is defined as None. 3. The different images used will show when the button is Pressed or Released. MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 83 By setting the border and background to None, the button is invisible. Only by providing different images for Released versus Pressed does the user know when the button has been pressed. The actual touch region defined by the button is much larger than the images shown on the display. This extra area increases the touch response of the display. Small Buttons Controlled by Phantom Buttons Provides information on phantom button control of small buttons. Description When the border is not set to None, and the background is not set to None, the button widget provides a direct visible clue to the user when it is pressed. Which can be seen in the following figure with the button from aria_quickstart. In aria_quickstart, ButtonWidget1 has a bevel border, and a fill background. MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 84 Let’s use aria_quickstart to demonstrate how to control ButtonWidget1 using a phantom button to surround it, thereby increasing touch responsiveness. When using a bevel border and filled background, the button provides visible feedback when it is asserted. To use this feedback mechanism instead of images, there is a way to have a small button on the display, with a larger touch zone provided by another phantom button. Steps: 1. Click on ButtonWidget1 in the Screen Designer panel. Go to the Properties Editor panel for the widget and uncheck the Enabled property to disable the button. Enable Toggleable so that this button will have a memory. 2. Drag a new button from the Widget Tool Box panel and center it around ButtonWidget1. In the Properties Editor panel for this new button, change the name of the widget to PhantomButton. Change the Background Type to None. Leave the Border set as Bevel for now. The following figure displays the new button in the Screen Designer panel: MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 85 The Properties Editor panel should display the following information. 3. In the Tree View panel, drag ButtonWidget1 to be a daughter widget of PhantomWidget. When PhantomWidget is moved, ButtonWidget1 will move along with the parent. 4. Click on PhantomButton again in the Screen Designer panel and move to the Properties Editor. Enable both the Pressed and Released events. Then click on the (…) icon to define the events. (See the following two steps.) 5. Defining the Pressed Event. Click on the (…) icon. In the Event Editor, under Pressed dialog, click the New icon to define a new event. In the Action Edit Dialog that next appears, leave the selection on the template and hit the Next button. In the next window, select the target of the event. We want to change the state of ButtonWidget1, so select it and hit Next. The next dialog shows all the template actions that we can use to modify ButtonWidget1. Choose Set Pressed State and hit Next. Set the Argument to Enable Pressed. Name this event Set Press state for ButtonWidget1 then hit Finish. Leave the Event Editor by hitting Ok. MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 86 6. Defining the Released Event. Click on the (…) icon. In the Event Editor, under Released dialog, click the New icon to define a new event. In the Action Edit Dialog that next appears, leave the selection on the template and hit the Next button. In the next window, select the target of the event. We want to change the state of ButtonWidget1, so select it and hit Next. Choose Set Pressed State and hit Next. Leave the Argument disabled. Name this event Unset Press state for ButtonWidget1 then hit Finish. Leave the Event Editor by hitting Ok. 7. Generate the application from the MPLAB Harmony Configurator main menu. 8. From the MPLAB main menu, build and run the project. To verify that ButtonWidget1 does change, click outside of the original boundaries. 9. As a final step, hide the PhantomButton by changing its border to None. Next, Generate the code again from MHC. Finally, build and run the project from MPLAB and see how much easier it is to assert ButtonWidget1 using a phantom button. MPLAB Harmony Graphics Composer User's Advanced Topics Improved Touch Performance with Phantom © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 87 Importing and Exporting Graphics Data This topic provides information on importing and exporting graphics composer-related data. Description The MPLAB Harmony Graphics Composer (MHGC) provides the capability for users to import and export graphics designs. The user can export the state of an existing graphics composer configuration or import another graphics composer configuration from another project. Importing Data 1. To import a graphics design into MHGC, select File > Import. The Browse for MPLAB Harmony Graphics Composer XML file dialog appears, which allows the selection of a previously exported Graphics Composer .xml file, or the configuration.xml file that contains the desired graphics image. 2. After selecting a file and clicking Open, you will be prompted whether to overwrite existing data. 3. If you selected a composer_export.xml file, clicking Yes will replace the current graphics design with the new design. 4. Otherwise, if you selected a configuration.xml file, you will be prompted to import the data into the current graphics design. Click Yes to replace the current graphics design with the new design. MPLAB Harmony Graphics Composer User's Importing and Exporting Graphics Data © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 88 Exporting Data 1. To export a graphics design from MHGC, select File > Export. The Select File Location for MPLAB Harmony Graphics Composer XML file dialog appears. 2. To export a graphics design using a configuration.xml file, use the Save Configuration utility from the MPLAB Harmony Configurator (MHC) toolbar. MPLAB Harmony Graphics Composer User's Importing and Exporting Graphics Data © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 89 Index A Adding Third-Party Graphics Products Using the Hardware Abstsraction Layer (HAL) 75 Advanced Topics 75 aria_coffeemaker Demonstration Example 83 B Binary Assets 57 C Code Generation 74 D Draw Pipeline Options 78 E Event Manager 58 F Font Assets 46 G Global Palette 65 Graphics Composer Asset Management 36 Graphics Composer Window User Interface 4 Graphics Pipeline 78 Graphics Pipeline Options 82 H Heap Estimator 63 I Image Assets 41 Importing and Exporting Graphics Data 88 Improved Touch Performance with Phantom Buttons 82 Introduction 3 M Memory Configuration 36 Menus 10 MHGC Tools 58 MPLAB Harmony Graphics Composer User's Guide 2 N New Project Wizard 14 O Object Properties 29 Options 26 P Properties Editor Panel 28 S Schemes Panel 24 Screen Designer Window 6 Screens Panel 22 Small Buttons Controlled by Phantom Buttons 84 Speed and Performance of Different Image Decode Formats in MHGC 76 String Assets 54 String Table Configuration 51 T Tree View Panel 18 W Widget Colors 68 Widget Tool Box Panel 26 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.05 90

MPLAB Harmony Graphics Composer User's Guide MPLAB Harmony Integrated Software Framework © 2013-2018 Microchip Technology Inc. All rights reserved. Volume III: MPLAB Harmony Configurator (MHC) This volume provides user and developer-specific information on the MPLAB Harmony Configurator (MHC). Description The MPLAB Harmony Configurator (MHC) is a graphical utility used to configure MPLAB Harmony projects. MHC provides a "New MPLAB Harmony" project wizard and a graphical user interface for configuration of MPLAB Harmony projects. When used, it generates (or updates) a project outline, including the C-language main function and system configuration files and stores the project configuration selections for later retrieval, modification, and sharing. Volume III: MPLAB Harmony Configurator (MHC) © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 2 MPLAB Harmony Graphics Composer User's Guide This section provides user information about using the MPLAB Harmony Graphics Composer (MHGC). Introduction This user's guide provides information on the MPLAB Harmony Graphics Composer (MHGC), also referred to as the graphics composer, which is included in your installation of MPLAB Harmony. MHGC is tightly coupled with the Aria User Interface Library to facilitate rapid prototyping and optimization of the application's graphical user interface (GUI). Description The MPLAB Harmony Graphics Composer (MHGC), also referred to as the graphics composer, is a graphics user interface design tool that is integrated as part of the MPLAB Harmony Configurator (MHC). MHGC is tightly coupled with the Aria User Interface Library to facilitate rapid prototyping and optimization of the application's graphical user interface (GUI). The tool provides a "What you see is what you get" (WSYWIG) environment for users to design the graphics user interface for their application. Refer to Volume V: MPLAB Harmony Framework Reference > Graphics Library Help > Aria User Interface Library for more information. The MPLAB Harmony Graphics Composer (MHGC) Tool Suite and the Aria User Interface Library provide the following benefits to developers: • Enhanced User Experience – Libraries and tools are easy to learn and use. • Intuitive MHGC Window Tool – Flexible window docking/undocking. Undo/Redo and Copy/Paste support. Tree-based design model. Display design canvas control including zooming. • Tight Integration Experience – Graphics design & code generator tools are tightly integrated, providing rapid prototyping and optimization of look and feel • Powerful User Interface (UI) Library – Provides graphics objects and touch support • Multi-Layer UI design – Supported in the MHGC tool and Aria Library • Complete Code Generation – Can generate code for library initialization, library management, touch integration, color schemes and event handling with a single click • Supports Performance and Resource Optimization – Draw order, background caching, and advanced color mode support improve performance • Resource optimization – Measures Flash memory usage and can direct resources to external memory if needed. Global 8-bit color look-up table (LUT) supports reduced memory footprint. Heap Estimator tool, which helps to manage the SRAM memory footprint. • Text localization – Easily integrate international language characters into a design and seamlessly change between defined languages at run-time • Easy to Use Asset Management – Tools provide intuitive management of all graphics assets (fonts, images, text strings) • Image Optimization – Supports cropping, resizing, and color mode tuning of images • Expanded Color Mode Support – The graphics stack can manage frame buffers using 8-bit to 32-bit color • Powerful Asset Converter – Inputs several image formats, auto converts from input format to several popular internal asset formats, performs auto palette generation for image compression, supports run-length encoding. Supports automatic font character inclusion & rasterization. • Event Management – Wizard-based event configuration. Tight coupling to enable touch user events and external logical events to change the graphics state machine and graphics properties. • Abstract Hardware Support – Graphics controllers and accelerators can be added or removed without any change to the application Glossary of Terms Throughout this user's guide the following terms are used: Acronym or Term Description Action A specific task to perform when an event occurs. Asset An image, font, or binary data blob that is used by a user interface. Event A notification that a specific occurrence has taken place. Resolution The size of the target device screen in pixels. Screen A discreet presentation of organized objects. Tool An interface used to create objects. UI Abbreviation for User Interface. Widget A graphical object that resides on the user interface screen. Graphics Composer Window User Interface This section describes the layout of the different windows and tool panels available through MHGC. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 3 Description MHGC is launched from the MHC toolbar Launch Utility menu. Launching the Graphics Composer creates a new screen. Shown below is the MHGC screen for the Aria Showcase demonstration. (If you don’t see this screen layout, reset the screen by selecting Window > Reset Dock Areas from the window’s menus.) Panels By default, there are five active panels and one minimize panel on this screen: • Screen Designer – Shows the screen design for the selected screen. Tabs on the bottom of the Screen Designer panel show the available screens. • Tree View – Shows the layer and widget hierarchy for the current screen. • Screens – Manages screens in the application. • Schemes – Manages coloring schemes in the application. Note: In v2.03b of MPLAB Harmony, a third tab named Options, along with Screens and Schemes was available. These properties are now located within the File > Settings menu. • Widget Tool Box – Available graphics widgets are shown on this panel. Widgets are added to the screen by selecting an icon and dragging or clicking. Widget properties are discussed in the Widget Properties section below. • Properties Editor – All properties for the currently selected object are shown in this panel. • The MHGC Output console is parked at the bottom of the Screen Designer window. This console panel can be used to debug problems when the Graphics Composer boots up or during its operation. Each of the panels has a window tool icon at the upper right corner. Minimizing a panel parks it on the screen just like the Output Console. Undocking the panel creates a new, free floating window. Redocking returns a previously undocked window to its original location on the Screen Designer window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 4 When a panel is undocked, its edges become active and support moving or manipulating the panel as an independent window. Tool Bar There are 18 tool bar icons on the Screen Designer Window, as described in the following figure. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 5 Create New Design brings up a New Project Wizard dialog that allows you to select anew the screen size, color mode, memory size, and project type. This will erase the currently displayed design. Save Design saves the current graphics design. Note: The target configuration's configuration.xml will not be updated to reflect these changes in the graphics design until one of the following events happens: 1. The application is regenerated in MHC, 2. The target configurations are changed in the MPLAB X IDE, 3. MPLAB X IDE is exited. In items 2 and 3 you will be prompted to save the new configuration. Undo and Redo manipulate changes in the screen design into internal MHC memory. Cut/Copy/Paste support the manipulation of graphics objects (widgets). Canvas Size Dialog brings up a dialog window allowing changes in the pixel width and height of the Screen Designer panel. (Note: Dimensions smaller than the display’s dimensions are ignored). Center View centers the panel’s view of the screen. Zoom In and Zoom Out allow you to change the scale of the Screen Designer’s display of the current window. Currently this only supports coarse zooming (powers of two zooms in and out). Toggle Line Snapping enables/disables line snapping when moving objects (widgets). Show Grid turns the Screen Designer pixel grid on/off. X and Y Grid Size adjust the pixel grid. Grid Color selects the pixel grid color. Toggle Object Clipping turns object clipping on/off. Toggle Screen Info turns the display of screen information (X and Y axes) on/off. Select Text Preview Language changes the language used on all text strings shown, when the application supports more than one language. Screen Designer Window Most of the work of the MPLAB Harmony Graphics Composer is done using the Screen Designer. This section covers the basics of how a graphical user interface is designed using the screen designer. Description The following figure shows the Screen Designer window for the Aria Quickstart demonstration, with the pic32mz_ef_sk_meb2 configuration selected. (Load whatever configuration belongs to your board and follow along.) Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 6 The pixel dimensions of the display (480x272) are determined by the MHC Display Manager. Other configuration in Aria Quickstart can have different size displays (such as: 220x176, 320x24, or 800x480). This demonstration has three widgets: a label containing the title string at the top, an image of the MPLAB Harmony logo in the middle, and a button containing the text string “Make changes. Generate. Run.” at the bottom. The label widget’s text string was first created using the String Assets window before it was assigned to the label widget. The image assigned to the image widget was first imported using the Image Assets. The string embedded in the button widget was also created using the String Assets window before it was assigned to the button widget. The Tree View panel organizes the display’s widgets into groups using layers. Every display has at least one layer and complex designs can have many more. Within the tree view, the order of layers and the order of widgets within a layer determine the draw order. Draw order goes from top to bottom. Top-most layers and widgets are drawn first and bottom-most are drawn last. Controlling draw order is one of the ways to improve graphics performance by minimizing redrawing. Since the location of every widget within a layer is relative to the layer, you can move a layer’s worth of widgets by simply moving the layer. Layers also provide inheritance of certain properties from the layer to all the layer’s widgets. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 7 Exploring the Screen Designer Window We can add another widget to this screen by launching the Widget Tool Box panel into a separate window. Next, drag a circle from the tool box onto the display. Find a place on the display for this new widget. Besides dragging widgets onto the display, you can click on a widget in the Widget Tool Box, converting the cursor into that widget, and then click on the screen to drop the widget in place. Your display should now look appear like the following figure. Note how the Tree View panel now shows the widget you just added. Launch the Properties Editor for the circle. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 8 Next, change the fill property on the circle from “None” to “Fill”. Note: If the properties in the Properties Editor shown are not for CircleWidget1, click on the circle widget to change the focus of the Properties Window. When done, the screen should now appear, as follows. Turn on Line Snapping, which enables drawing guides to assist in aligning widgets on the display. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 9 Next, turn on Object Clipping, which allows you to see how widgets are clipped by the boundaries of the layer that contains them. Note: Clipping applies to layers, which can be smaller than the display. To delete a widget, select the widget and press Delete on your keyboard or use the delete icon ( ) on the Tree View panel. For more hands-on exploration of graphics using the Aria Quickstart demonstration, see Volume 1: Getting Started With MPLAB Harmony > Quick Start Guides > Graphics and Touch Quick Start Guides > Adding an Event to the Aria Quickstart Demonstration. The steps to create a new MPLAB Harmony project with touch input on a PIC32MZ EF Starter Kit with the Multimedia Expansion Board (MEB) II display can be found in Volume 1: Getting Started With MPLAB Harmony > Quick Start Guides > Graphics and Touch Quick Start Guides > Creating New Graphics Applications. Menus This section provides information on the menus for the MPLAB Harmony Graphics Composer screen. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 10 Description File Menu New – Same as the Create New Design tool icon. Save – Same as the Save Design tool icon. Save As – Supports exporting the design under a new name. By default, the name is composer_export.xml. See Importing and Exporting Graphics Data for more information. Import - Reads in (imports) a previously exported design or a ./framework/src/system_config/{board_config}/configuration.xml file that contains the graphics design to be imported. See Importing and Exporting Graphics Data for more information. Export – Same as Save As. See Importing and Exporting Graphics Data for more information. Settings – Brings up Project and User Settings dialog, including: • Project Color Mode - How colors are managed • Using a Global Palette • Show Welcome Dialog • Pre-emption Level – Allows for sharing of the device’s cycles with other parts of the application • Hardware Acceleration – Is graphics hardware accelerator enabled in software? Exit – Closes the MHGC window and exits The choices for Project and User Settings > Project Color Mode are: • GS_8 - 8-bit gray scale • RGB_332 - Red/Green/Blue, 3 bits Red/Green, 2 bits Blue • RGB_565 - Red/Green/Blue, 5 bits Red, 6 bits Green, 5 bits Blue • RGBA_5551 - Red/Green/Blue/Alpha, 5 bits Red/ Green/Blue, 1 bit for Alpha Blending • RGB_888 - Red/Green/Blue, 8 bits Red/Green/Blue • RGBA_8888 - Red/Green/Blue/Alpha, 8 bits Red/Green/Blue/Alpha Blending • ARGB_8888 - Alpha/Red/Green/Blue, 8 bits Alpha Blending/Red/Green/Blue Ensure that the Project Color Mode chosen is compatible with the display hardware you are using; otherwise, the colors shown on the display will not match those shown on the Graphics Composer Screen Designer. Using a Global Palette enables frame buffer compression for applications using the Low-Cost Controllerless (LCC) Graphics Controller or Graphics LCD (GLCD) Controller. If the global palette is enabled, you will have to change the MHC configuration of the Graphics Controller to match. For the LCC controller, enable "Palette Mode". For the GLCD controller, change the Driver Settings > Frame Buffer Color Mode to "LUT8". If Using a Global Palette is enabled, the following warning appears. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 11 If Show Welcome Dialog is enabled, the following welcome screen appears when launching MHGC. Note: If you are not creating a new project you can ignore this window. When the Preemption Level is set to zero, all dirty graphics objects are refreshed before the graphics process relinquishes control of the device. (Dirty means needing a redraw.) With the level set to two, graphics provides maximum sharing with the rest of the application, at the cost of slower display refreshes. A level of one provides an intermediate level of sharing. The Hardware Acceleration check box determines whether graphics uses the device’s built-in graphics hardware accelerator in software. Note: You must also specify the graphics hardware accelerator in the MPLAB Harmony Framework Configuration within the MHC Options tab. If the host device lacks a graphics processor, you will see a warning message when you try to select a processor that does not exist on your device. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 12 Edit Menu This menu implements the same functions as the first seven tool icons. View Menu This implements the same functions as the remaining tool icons. Asset Menu These menu features are discussed in Graphics Composer Asset Management. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 13 Tools Menu The Event Manager, Global Palette, and Heap Estimator are discussed in MHGC Tools. Window Menu Selecting Console opens the Output Console for the Graphics Composer. This console panel can be used to debug problems when the Graphics Composer boots up or during its operation. Selecting Reset Dock Areas restores the MHGC panel configuration to the default setup by redocking all of the panels that have been undocked into separate windows. New Project Wizard The New Project Wizard is launched from the Welcome dialog of the MPLAB Harmony Graphics Composer (MHGC), which supports the creation of a new graphics design, or the importing of an existing graphics design. Description Welcome Dialog window The Welcome dialog is launched when the Graphics Composer is chosen from the Launch Utility pull-down menu in the MPLAB Harmony Configurator (MHC). The window has three options: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 14 Note: If this window does not appear, it can be re-enabled from MHGC’s File > Settings > General menu. New Project Wizard Windows Selecting the first icon in the Welcome dialog launches the New Project Wizard. There are four stages in the New Project Wizard: Color Mode, Memory Size, Project Type, and Finish. The New Project Wizard can also be launched from the first icon (Create New Design) of MHGC’s tool bar: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 15 If the Graphics Stack has not been enabled in MHC, an Enable Graphics Stack? dialog will appear to support enabling the Graphics Stack before proceeding: In the Color Mode stage you choose the Display Color Mode for the new graphics design: This choice must be supported by the graphics controller defined in the board support package of the project configuration. (If you make a mistake it can be corrected using MHGC’s File > Settings > Project Color Mode menu.) Click Next moves the wizard on to the next stage. The Memory Size stage configures the Program Flash allocated to memory use. This value is only used by the Graphics Composer’s Asset menu Memory Configuration tool. The value used in the Memory Size stage can be updated using the Configuration sub-tab of the Memory Configuration tool window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 16 Clicking Previous returns to the Color Mode stage and clicking Next moves the wizard to the Project Type stage. There are two choices at the Project Type stage: A completely blank design, and a template design with a few predefined widgets. Clicking Previous returns to the Memory Size stage, and clicking Next moves the wizard to the Finish stage. If the “Template” project type was chosen, MHGC’s Screen Designer will show: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 17 Tree View Panel The organization of application widgets and layers, including draw order, is managed using this panel. Description Example Tree View The following Tree View (from main screen of the Aria Coffee Maker demonstration shows the tree structure for a screen with three layers. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 18 The tool icons for this panel support layers and managing screen objects (layers/widgets). Drawing Order and Parent/Child Relationships The Graphics Composer Tree View panel allows you to organize the widgets per screen in the desired drawing order (z-order). It also allows for the user to organize the widgets into parent – child hierarchies to allow for the paint algorithm to draw the groups together in event of motion or re-draw. Please note that this does not associate or group the widgets by functionality. (Example: a group of radio buttons might not belong to a common parent on the screen.) This parent-child relationship is limited to the widgets location on the screen, motion on the screen and the drawing order on the screen. (Exceptions to this general rule are the Editor > Hidden, Alpha Blending properties, and layer single versus double buffering. These apply to the parent and all the parent's children.) The tree is traversed depth-first. This means that the z-order goes background (bottom of z-order) to foreground (top of z-order) as we go from top to bottom in the list of widgets, i.e., ImageWidget1, is the widget at the bottom of the z-order and the PanelWidget1 is the topmost widget on the z-order. The tree structure can be arranged and modified by dragging the widgets and releasing it under the desired parent/child. Also, the list can be modified by using the up/down arrows provided at the header of the Composer Widget tree window to traverse the tree. Editor > Hidden Property for Layers Setting Editor > Hidden hides the layer and all its children from the Graphics Composer Screen Designer but does not affect how the layer and its children are displayed when the application is running. This can be useful when designing complex screens with overlapping layers. Alpha Blending Property for Layers Enabling Alpha Blending allows you to control the transparency of a layer and all its children. You can experiment with Alpha Blending in the Aria Coffee Maker demonstration. Load the project, launch MHC, and then start the Graphics Composer Screen Designer. There are three layers (Layer0, Layer1, Layer2) in this demonstration. Layer1 (the drag panel on the right) and Layer2 (the drag panel on the left) have Alpha Blending enabled with Alpha Amount = 225. Setting the Alpha Amount to 255 is the same as disabling Alpha Blending (255 = no transparency). Setting the Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 19 Alpha Amount to 0 makes the layer invisible (0 = full transparency, i.e., invisible). The following figure shows the main screen with Alpha Blending = 225. The following figure shows the main screen with Layer 2’s Alpha Blending = 255. Double Buffering for Layers Graphics double buffering for the LCC driver is enabled in the Display Manager’s Display Setting screen when the application is changed to use external memory instead of internal. Click Configure to bring up the LCC Driver Configuration Settings Window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 20 Configure the memory according to whether double buffering is to be enabled for the display’s layer or layers. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 21 Increasing the Buffer Count of a layer from 1 to 2 enables double buffering for the layer and all its child widgets. To prevent tearing on the display when switching from one buffer to the other, VSync Enabled should also be selected. Screens Panel Application screens are managed using the Screens Panel. Description The Screens panel tab manages all the application’s screens, as shown in the following figure. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 22 Note: These screens are examples from the Aria Showcase demonstration project The underlined screen name identifies the primary screen (in this case, SplashScreen.) The bold screen name identifies the currently active screen in the Graphics Composer Screen Designer window (in this case MainMenu.) The blue background identifies the selected screen (i.e., the screen that is manipulated by the tool icons), in this case FirstScreen. Window Toolbar The window’s tools icons support: 1. Create New Screen – Create a new screen. You will be prompted for the name of the new screen, which will appear at the bottom of the Screens list. 2. Delete Screen – Delete the selected screen. This removes the selected screen from the application. 3. Set as Primary Screen – Sets the selected screen as the default screen displayed by the application at boot-up. 4. Make Screen Active – This selected screen is displayed in the Screen Designer panel. You can also select the active screen by clicking on the screen’s tab at the bottom of the Screen Designer panel. 5. Move Screen Up in Order – Moves the selected screen up in the list of screens, which is useful in organizing a large list of screens, but has no other significance. 6. Move Screen Down in Order – Moves the selected screen down in the list of screens. Useful in organizing a large list of screens, but has no other significance. Window Columns The Generate check box is used in selecting those screens that will be included in the application when MPLAB Harmony Configurator (MHC) generates/regenerates the application. (This, along with the Enabled check box for languages, allows customization of the application’s build to support different end uses from the same project.) The Visible check box can be cleared to hide a screen from the sub-tabs located at the bottom of the Screen Designer. The View column provides a mouse-over preview of the screen. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 23 Schemes Panel Application color schemes are managed using the Schemes Panel. Description Color schemes for the application’s graphics are managed using the Schemes sub-tab. Editing a Scheme To edit an existing scheme, select the scheme from the list and click Edit. The Scheme Editor dialog appears, which allows you to change the colors associated with this display scheme. Scheme Editor The Scheme Editor window supports editing the individual colors of a color scheme. Clicking the ellipsis ( … ) opens the Color Picker window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 24 Color Picker The Color Picker window allows the user to easily select a color by providing a color wheel, brightness gauge, and some common predefined color choices. The user can change the individual color values or input a number in Hexadecimal format. The end result is displayed in the top right corner. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 25 Options Provides information on the defeatured Options window. Description In v2.03b, MPLAB Harmony Graphics Composer user interface provided a third window along with Screens and Schemes, named Options. Beginning with v2.04b of MPLAB Harmony, these options are now located within the File > Settings menu (see Menus for details). Widget Tool Box Panel The Widget Tool Box panel is the interface by which users add widgets into the screen representation. Description All the available graphics widgets are shown in the Widget Tool Box: MPLAB Harmony Graphics Composer provides automatic code optimization by keeping track of the widgets that are currently being used. When MHC generates or regenerates the application, only the Graphics Library code necessary for your design is included in the project. There are two primary methods for creating new widget objects: clicking and dragging. To add a new layer to a screen use the Screens sub-tab. Click Method The following actions can be performed by using the Click method: • Clicking an item selects it as active. Users can then move the cursor into the screen window and view a representation of the object about to be added. • Left-clicking confirms the placement of the new object • Right-clicking aborts object creation • Clicking the active item again deactivates it Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 26 Drag Method Dragging and dropping a tool item into the Screen Designer Window creates a new instance of an object. When dragging a tool item, releasing the cursor outside of the Screen Designer Window cancels the drag operation. Widget List The Graphics Composer Tool Box is the interface by which users add widgets into the screen representation. Widget Example Application Arc aria_showcase_reloaded Bar Graph aria_showcase_reloaded Button aria_adventure and many others, including aria_quickstart Check Box aria_showcase_reloaded, aria_video_player Circle None Circular Gauge aria_showcase_reloaded, aria_oven_controller Circular Slider aria_showcase_reloaded Draw Surface None Gradient aria_showcase (background) Group Box aria_video_player Image aria_quickstart Image Plus aria_oven_controller Image Sequence aria_showcase, aria_basic_motion Key Pad aria_showcase, aria_touchadc_calibrate Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 27 Label aria_quickstart Line aria_video_player, ./aps/examples/3rd_party_display Line Graph aria_showcase_reloaded List Wheel aria_showcase List aria_video_player Panel aria_video_player Pie Chart aria_showcase_reloaded Progress Bar aria_flash Radial Menu aria_radial_menu, aria_showcase_reloaded Radio Button aria_showcase Rectangle aria_benchmark Scroll Bar None Slider aria_video_player Text Field aria_showcase Touch Test aria_showcase, aria_touchadc_calibrate, ./apps/examples/3rd_party_display Window None Click Method The following actions can be performed by using the Click method: • Clicking an item selects it as active. Users can then move the cursor into the screen window and view a representation of the object about to be added. • Left-clicking confirms the placement of the new object • Right-clicking aborts object creation • Clicking the active item again deactivates it. Drag Method Dragging and dropping a tool item into the Screen Designer Window creates a new instance of an object. When dragging a tool item, releasing the cursor outside of the Screen Designer Window cancels the drag operation. Automatic Code Optimization MPLAB Harmony Graphics Composer keeps track of the types of widgets that are used and updates the MHC Tree constantly to ensure that only the Graphics Library code necessary for your design is included in the project. Widgets Widgets can be configured by using the Properties Editor on the right side of the MHGC interface. Each widget has multiple properties to manage their appearance as well as their functioning. Most properties related to appearance are common between widgets, though some widgets require specific property entries. Arc – A graphical object in the shape of an arc. The arc thickness can be set and filled. Bar Graph – A graphing widget that shows data in categories using rectangular bars. Button - A binary On and Off control with events generation for Press and Release state. Check Box - A selection box with Checked and Unchecked states, and associated events. Circle - A graphical object in the shape of a circle. Circular Gauge – A circular widget that operates like a gauge, where the hand/needle position indicates a value. Circular Slider – A circular widget that can change values based on external input like touch. The slider is filled based on the value of the widget relative to the maximum value. Draw Surface - A container with a callback from its paint loop. a draw surface lets the application have a chance to make draw calls directly to the HAL during LibAria's paint loop. Gradient - A draw window that can be associated with a gradient color scheme. This allows for color variation on the window. Group Box - A container with a border and a text title. With respect to functionality, a group box is similar to a window. Image Sequence - A special widget that allows image display on screen to be scheduled and sequenced. Select the images to be displayed, and the order for display. A timer to trigger the transitions must be created by calling the image sequence APIs to show the next image from the timer callback function. Image - Allows an image to be displayed on screen. The size and shape of the widget decides the visible part of the image, as scaling is not enabled for images at this time. Image Plus - Allows an image to be displayed on screen. The image can be resized (aspect ratio lock is optional). The widget can be set to accept two-finger touch input. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 28 Key Pad - A key entry widget that can can be designed for the number of entries divided as specified number of rows and column entries. The widget has a key click event that can be customized. Label - A text display widget. This does not have any input at runtime capability. A Text Field widget serves that purpose. Line - A graphical object in the shape of a line. Line Graph – A graphing widget that shows data in categories using points and lines. List Wheel - Allows multiple radial selections that were usually touch-based selections and browsing. List - Allows making lists of text and image items. The list contents, number of items, and the sequence can be managed through a List Configuration dialog box in the Properties box. Panel - A container widget that is a simpler alternative to DrawSurface as it does not have the DrawSurface callback feature. Pie Chart – A graphing widget that shows data entries as sectors in a circle. Progress Bar - Displays the progress pointer for an event being monitored through the "Value Changed" event in the Properties Editor. Radial Menu - A widget that groups any number of images into an elliptical carousel. It can configured as a touch interactive image carousel or interface menu. Radio Button - A set of button widgets that are selected out of the group one at a time. The group is specified by the Group property in the Properties Editor. Note: The radio buttons in the same group must have the same group number specified in their properties. Rectangle - A graphical object in the shape of a rectangle. Scroll Bar - Intended to be used with another relevant widget such as the List Wheel to scroll up and down. It has a callback each time the value is changed. The callback allows users to trigger actions to be handled on the scroll value change event. Slider - Can change values with an external input such as touch. Event callbacks on value change are also available through the Properties Editor. Text Field - Text input can be accepted into the text field from an external input or from a widget such as keypad. Event 'Text Changed' in the Properties Editor is used for accepting the input. Touch Test - Allows tracking of touch inputs. Each new touch input is added to the list of displayed touch coordinates. The input is accepted through the 'Point Added' event callback in the Properties Editor. Window - A container widget similar to the Panel but has the customizable title bar. Properties Editor Panel The properties for all layers and widgets are managed using this panel. Description The Properties Editor displays options for the currently-selected object (layer or widget), or the options for the active screen if no objects are selected. To edit an option: left-click the value in the right column and then change the value. Some values have an ellipsis that will provide additional options. In the previous case, the ellipsis button will display the Color Picker dialog. Some properties, like the screen width and height, are locked and cannot be edited. Other properties offer check boxes and combo-type drop-down box choices. Some properties are grouped together like the Position and Size entries. Individual values of the group can be edited by expanding the group using the plus symbol. For example, the following figure shows properties for a Button Widget. A new support feature is the ? icon to the right of the Scheme pull-down, which brings up an “Scheme Helper” for the widget showing how it is colored when using a Bevel border. For a more complete description of widget coloring, see Widget Colors. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 29 Object Properties Provides information on widget, layer, and screen properties. Description Object Properties and Event Actions Each widget has a structured tree of properties, visible under the MPLAB Harmony Configurator window on the right of the standard window setup within MPLAB X IDE. Most widget properties have a Related Event action that can be use in an event or macro to change or set a property from the application. Each widget has 3-4 property sets: Editor – Controls the behavior of layers and widgets under the MPLAB Harmony Graphics Composer Suite Editor. Property Name Type Description Related Event Actions Locked Boolean Locks the object (widget), preventing changes by the designer. Only affects the object (widget) in the editor. N/A Hidden Boolean Hides the widget and its children in the designer window. Only affects the appearance of the widget in the editor. N/A Active Boolean For layers only. Sets the layer as active. Any objects (widgets) added to the screen will be added to this layer. N/A Locked to Screen Size Boolean For layers only. Locks the layer size to the size of the display’s screen. N/A Widget – Controls the behavior of screens, layers, and widgets on the display. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 30 Property Name Type Description Related Event Actions Name String Editable name for each object. By default, widgets are named NameWidget1, …,NameWidgetN. For example: ButtonWidget1, ButtonWidget2, … . N/A Position [X,Y] Pair of Integers Location on the layer of the upper left corner of the widget or the location on the display of the upper left corner of the layer. Measured in display pixels. X is measured from left-to-right and Y is measured from up-to-down from the upper left corner of the parent object (typically a Layer or Panel). Adjust Position, Set X Position, Set Y Position Size [X,Y] Pair of Integers X: Width, Y: Height of object, in display pixels. Adjust Size, Set Size, Set Width, Set Height Enabled Boolean Is the object enabled? Disabled objects are not built into the display’s firmware. Set Enabled Visible Boolean Is the object visible by default? Object visibility can be manipulated in firmware using laWidget_GetVisible and laWidget_SetVisible. Set Visible Border Widget Border Choices are: { None | Line | Bevel }. Set Border Type Margin Integer Four integers ([Left,Top,Right,Bottom]) defining the widget’s margins on the display, in display pixels. Set Margins Scheme - Color scheme assigned to the layer or widget. Blank implies the default color scheme. Set Scheme Background Type - Sets the background of the layer or widget. Choices are { None | Fill | Cache }. In MPLAB Harmony v2.03, this type was Boolean. Now, Off = None, On = Fill. With Fill selected, the widget's background is one solid color. With Cache selected, a copy (cache) of the framebuffer is created before the widget is drawn and this cache is used to fill the background of the widget. This supports transparent widgets in front of complex widgets, such as JPEG images. Instead of rerendering the JPEG image, it is just drawn from the cache. Set Draw Background Alpha Blending Boolean Is alpha blending enabled for this layer or widget and all of its children? If enabled, specify the amount of alpha blending as an 8-bit integer. Zero makes the object invisible, whereas 255 makes the background invisible. N/A Widget Advanced – Advanced control of layers and widgets Optimization Sub-Property Name Type Description Related Event Actions Draw Once Boolean Indicates that the widget should draw once per screen Show Event. All other attempts to invalidate or paint the widget will be rejected. N/A Force Opaque Boolean Provides a hint to the renderer that the entire area for this widget is opaque. Useful for widgets that may use something like an opaque image to fill the entire widget rectangle despite having fill mode set to None. This can help reduce unnecessary drawing. N/A Local Redraw Boolean Provides a “hint” to the widget’s renderer that the widget is responsible for removing old pixel data. This can avoid unnecessary redrawing. N/A Important! Use Local Redraw only if you know what you’re doing! Widget Name (e.g., Button Check Box, Circle, etc.) – Optional properties tied to each widget. See Dedicated Widget Properties and Event Actions. Events – Associates widget events with event call-backs. For example, you can enable and specify a button pressed event and button release event for the Button widget. For each event you specify: • Enabled/Disabled Check box – To enable or disable (default) the event. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 31 • Event Callback – Selected from the Event Editor Action List. There are additional Event actions that do not correspond to any specific property: • Set Parent – Set the parent of the object, including no parent. Dedicated Widget Properties and Event Actions Arc Widget Property Name Type Description Related Event Actions Radius Integer The outside radius of the arc. Set Radius Start Angle Integer The starting angle of the arc in degrees. Set Start Angle Center Angle Integer The center angle of the arc in degrees. A positive angle draws the arc counter-clockwise from the start angle. A negative angle draws clockwise. Set Center Angle Thickness Integer The thickness of the arc fill, measured from the radius to center. (radius – thickness) determines the inside radius. Set Thickness Round Edge Boolean Draws round arc edge. Set Round Edge Bar Graph Widget Property Name Type Description Related Event Actions Stacked Boolean Stacks the bars for the entries in a category Set Stacked Bars Tick Length Integer The length, in pixels, of the ticks on each axis Set Tick Length Fill Graph Area Boolean Fills the graph area with scheme base color Fill Graph Area Value Axis Configuration • Maximum Value • Minimum Value • Tick Interval • Subtick Interval • Show Ticks • Tick Position • Show Tick Labels • Show Subticks • Subtick Position • Show Gridlines • String Set Integer Integer Integer Integer Boolean Enum Boolean Boolean Enum Boolean String Asset Configures the value (Y) axis The maximum value of the axis The minimum value of the axis The intervals between major ticks The interval between minor ticks Show/Hide the major ticks Position of major ticks on the value axis. Choices are: {Inside | Center | Outside} Show/Hide the tick labels Show/Hide the minor ticks Position of minor ticks on the value axis. Choices are: {Inside | Center | Outside} Show/Hide the gridlines The string asset containing the numeric characters for the tick labels. The asset must contain the characters for numbers 0 to 9. Set Max Value Set Min Value Set Tick Interval Set Subtick Interval Show Value Axis Ticks Set Value Axis Ticks Position Show Value Axis Labels Show Value Axis Subticks Set Value Axis Subticks Position Show Value Axis Gridlines Set Labels String Category Axis Configuration • Show Tick • Show Category Labels • Tick Position Boolean Boolean Enum Configures the category (X) axis Show/Hide the ticks Show/Hide the category labels Position of the ticks on the category axis. Choices are: {Inside | Center | Outside} Show Category Axis Ticks Show Category Axis Labels Set Category Axis Ticks Position Category Configuration Dialog (See Description) The Category Configuration Dialog lets users add categories to the line graph. The following properties can be set: • Label – String Asset. The label to show for each category None Data Configuration Dialog (See Description) The Data Configuration Dialog lets users add and configure data series to the line graph. The following properties can be set: • Scheme – Scheme. The color scheme of the data series • Category Values – Integer. Values in series for each category None Button Property Name Type Description Related Event Actions Toggleable Boolean Is button toggle enabled? Set Toggleable Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 32 Pressed Boolean If Toggleable is enabled, provide default state of the button. This can be used to see the colors of an asserted button. Set Press State Text String - Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical - Text string alignment within the button object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Pressed Image - Select image used for pressed state. Default: no image. Set Pressed Image Released Image - Select image used for pressed state. Default: no image. Set Released Image Image Position - Position of image relative to button text. Choices are: { LeftOf | Above | RightOf | Below | Bottom }. Set Image Position Pressed Offset Integer Offset of button contents when pressed. In Pixels. The X and Y position of the button contents is offset by this amount. Set Pressed Offset Check Box Property Name Type Description Related Event Actions Text String - Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical - Text string alignment within the button object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Checked Boolean Default state of the check box. Set Check State Unchecked Image - Select image used for widget’s unchecked state. Default: no image. Set Unchecked Image Checked Image - Select image used for the widget’s checked state. Default: no image. Set Checked Image Image Position - Position of image relative to check box text. Choices are: : { LeftOf | Above | RightOf | Below | Bottom }. Set Image Position Image Margin Integer Space between image and text. In Pixels. Set Image Margin Circle Property Name Type Description Related Event Actions X Integer X offset of circle’s center, from widget’s upper left hand corner, in pixels. N/A Y Integer Y offset of circle’s center, from widget’s upper left hand corner, in pixels. N/A Radius Integer Circle’s radius, in pixels. Set Radius Circular Gauge Widget Property Name Type Description Related Event Actions Radius Integer The outside radius of circular gauge. Set Radius Start Angle Integer The starting angle of the circular gauge in degrees. Set Start Angle Center Angle Integer The canter angle of the circular gauge in degrees. A positive value draws the gauge counter-clockwise. Clockwise if negative. Set Center Angle Start Value Integer The start value of the circular gauge. Set Start Value End Value Integer The end value of the circular gauge. Set End Value Value Integer The value of the circular gauge. Set Value String Set String Asset The string asset containing the numeric characters for the tick labels. The asset must contain the characters for numbers 0 to 9. - Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 33 Major Ticks Configuration • Ticks Visible • Tick Length • Tick Value • Tick Labels Visible Boolean Integer Integer Boolean Configures the major ticks. Shows/Hides the major ticks. The length of ticks in pixels. The interval between ticks. Shows/Hides the major tick labels. Show/Hide Ticks Set Tick Length Set Tick Value Show/Hide Tick Labels Hand Configuration • Hand Visible • Hand Radius • Center Circle Visible • Center Circle Radius • Center Circle Thickness Boolean Integer Integer Integer Integer Configures the gauge hand/needle. Shows/Hides the gauge hand/needle. Sets the length of the hand in pixels Shows/Hides the hand center circle. Sets the radius of the center circle in pixels Sets the thickness of the center circle in pixels. Show/Hide Hand Set Hand Radius/Length Show/Hide Center Circle Set Center Circle Radius Set Center Circle Thickness Advanced Configuration - Additional widget configuration options for adding minor ticks, labels and arcs. - Minor Ticks Configuration Dialog (See Description) The Minor Ticks configuration lets users add minor ticks to the widget. The following properties can be set: • Start Value – Integer. The value where the first tick starts • End Value – Integer. The value where the last tick ends • Interval – Integer. The interval between ticks • Radius – The radius in pixels where the ticks will be drawn from • Length – The length of the ticks in pixels, drawn from the radius towards the center • Scheme – The color scheme for the ticks None Minor Tick Labels Configuration Dialog (See Description) The Minor Ticks configuration lets users add minor tick labels to the widget. The following properties can be set: • Start Value – Integer. The value where the first tick label is drawn • End Value – Integer. The value where the last tick ends • Interval – Integer. The interval between ticks • Radius – Integer. The radius, in pixels, where the tick labels will be drawn from • Position – Enum, choices are {Outside | Inside}. Position of the label relative to the radius • Scheme – The color scheme for the ticks None Arcs Configuration Dialog (See Description) The Arcs configuration lets users draw arcs in the gauge widget. The arcs can be used to colorize regions or range of values in the gauge. The following properties can be set for each arc: • Type – Enum, choices are {VALUE | ANGLE}. A value type arc is drawn relative to the values in the gauge. An angle type arc is draw based on the angles and is not affected by the values in the gauge. • Start – Integer. The start value or angle of the arc • End – Integer. The start value or angle of the arc • Thickness – Integer. The thickness of the arc in pixels, filled inward from the radius towards the center • Radius – Integer. The radius of the arc in pixels • Scheme. The color scheme of the arc None Circular Slider Widget Property Name Type Description Related Event Actions Radius Integer The outside radius of circular slider. Set Radius Start Angle Integer The start angle of the circular slider, in degrees. Set Start Angle Start value Integer The start value of the circular slider. Set Start Value End Value Integer The end value of the circular slider. Set End Value Value Integer The value of the circular slider. Set Value Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 34 Border Circle Configuration • Show Outside Circle • Outside Circle Thickness • Show Inside Circle • Inner Circle Thickness Boolean Integer Boolean Integer Configures the border circle. Shows/Hides the outside circle border. The thickness of the outside circle border in pixels. Shows/Hides the inside circle border. The thickness of the inside circle border in pixels. Show/Hide Outside Border Set Outside Border Thickness Show/Hide Inside Border Set Inside Border Thickness Active Area Configuration • Fill Active Slider Area • Round Edges • Active Slider Area Thickness • Inner Circle Thickness Boolean Boolean Integer Integer Configures the slider active area. Fills the active slider area. Draws a round edge for the active area. The thickness of the slider active area in pixels. The thickness of the inside circle border in pixels. Show/Hide Active Arc Area Set Round Edges Set Active Arc Area Thickness Show/Hide Inactive Arc Area Button Configuration • Show Circular Button • Sticky Button • Touch on Button Only • Circular Button Radius • Circular Button Thickness Boolean Boolean Boolean Integer Integer Configures the slider button. Shows/Hides the circular slider button. If set, the button sticks when it reaches the start/end values. If set, the widget responds to touches within the button area only. The radius of the circular button in pixels. The thickness of the of the circular button border in pixels. Show/Hide Circular Button Set Sticky Button None Set Circular Button Radius Set Circular Button Thickness Draw Surface – No additional properties. Gradient Property Name Type Description Related Event Actions Direction - Gradient draw direction. Choices are: { Right | Down | Left | Up }. Set Direction Group Box Property Name Type Description Related Event Actions Text String - Select widget’s text string from the Select String Dialog. Set Text Alignment - Text string alignment within the widget. Choices are: { Left|Center|Right }. Set Alignment Image Sequence Property Name Type Description Related Event Actions Sequence Configuration Dialog - Specify image sequence by using the Image Sequence Configuration Dialog window. Set Entry Image, Set Entry Horizontal Alignment, Set Entry Vertical Alignment, Set Entry Duration, Set Image Count Starting Image Integer Selects the first image to be shown. Set Active Image Play By Default Boolean Will image sequence play automatically? N/A Repeat Boolean Should the image sequence repeat? Set Repeat Additional related event actions: , Show Next, Start Playing, Stop Playing. Image Widget Property Name Type Description Related Event Actions Image - Select image used. Set Image Alignment: • Horizontal • Vertical - Image alignment within the image object. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Image Plus Widget Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 35 Property Name Type Description Related Event Actions Image - Select Image used Set Image Resize To Fit Boolean Resize the image to fill the size of the widget area Toggles option to best fit the image to the widget area Interactive Boolean Makes the widget interactive, allowing the image to be translated, stretched and zoomed Toggles option to permit two-finger gestures to interact with the widget Key Pad Property Name Type Description Related Event Actions Row Count Integer Number of key pad rows. None. Column Count Integer Number of key pad columns. None. Key Pad Configuration Dialog (see Description) The Key Pad dialog window has the following: • Width – Integer. Width of each key, in pixels. • Height – Integer. Height of each key, in pixels. • Rows – Integer. Number of key rows. A duplicate of Row Count. • Columns – Integer. Number of key columns. A duplicate of Column Count. None. None. None. None. - - Selecting one of the keys on the key pad diagram displays the Cell Properties for that key: • Enabled – Boolean. Disabled cells (keys) are made invisible. • Text String – Select key’s text string from the Select String Dialog. • Pressed Image – Select image used for pressed state. Default: no image. • Released Image – Select image used for released state. Default: no image. • Image Position – Position of image relative to key text. Choices are: { LeftOf | Above | RightOf | Below | Behind }. • Image Margin – Integer. Space between image and text. In Pixels. • Draw Background – Boolean. Controls whether the key should fill its background rectangle. • Editor Action – Select the generic editor action that fires when the key is clicked. Choices are: { None | Accept | Append | • Editor Value String Other Key Event Actions: Set Key Enabled Set Key Text Set Key Pressed Image Set Key Released Image Set Key Image position Set Key Image Margin None. Set Key Action Set Key Value Set Key Background Type Label Property Name Type Description Related Event Actions Text String - Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical - Text string alignment within the widget. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Line Property Name Type Description Related Event Actions Start X Integer X start of line, in pixels, from upper left hand corner of the widget. Set Start Point Position Start Y Integer Y start of line, in pixels, from upper left hand corner of the widget. Set Start Point Position End X Integer X end of line, in pixels, from upper left hand corner of the widget. Set End Point Position. End Y Integer Y end of line, in pixels, from upper left hand corner of the widget. Set End Point Position. Line Graph Widget Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 36 Property Name Type Description Related Event Actions Stacked Boolean Stacks the values of the entries in a category Set Stacked Points Tick Length Integer The length of the ticks on each axis Set Tick Length Fill Graph Area Boolean Fills the graph area with scheme base color Fill Graph Area Fill Series Area Boolean Fills the series area with series scheme base color Fill Series Area Value Axis Configuration • Maximum Value • Minimum Value • Tick Interval • Subtick Interval • Show Ticks • Tick Position • Show Tick Labels • Show Subticks • Subtick Position • Show Gridlines • String Set Integer Integer Integer Integer Boolean Enum Boolean Boolean Enum Boolean String Asset Configures the value (Y) axis The maximum value of the axis. The minimum value of the axis. The intervals between major ticks. The interval between minor ticks. Show/Hide the major ticks. Position of major ticks on the value axis. Choices are: {Inside | Center | Outside}. Show/Hide the tick labels. Show/Hide the minor ticks. Position of minor ticks on the value axis. Choices are: {Inside | Center | Outside}. Show/Hide the gridlines. The string asset containing the numeric characters for the tick labels. The asset must contain the characters for numbers 0 to 9. Set Max Value Set Min Value Set Tick Interval Set Subtick Interval Show Value Axis Ticks Set Value Axis Ticks Position Show Value Axis Labels Show Value Axis Subticks Set Value Axis Subticks Position Show Value Axis Gridlines Set Labels String Category Axis Configuration • Show Tick • Show Category Labels • Tick Position Boolean Boolean Enum Configures the category (X) axis Show/Hide the ticks Show/Hide the category labels Position of the ticks on the category axis. Choices are: {Inside | Center | Outside} Show Category Axis Ticks Show Category Axis Labels Set Category Axis Ticks Position Category Configuration Dialog (See Description) The Category Configuration Dialog lets users add categories to the line graph. The following properties can be set: • Label – String Asset. The label to show for each category None Data Configuration Dialog (See Description) The Data Configuration Dialog lets users add and configure data series to the line graph. The following properties can be set: • Scheme – Scheme. The color scheme of the data series • Point Type – Enum. The point indicator to use for the series. Choices are: {None | Circle | Square} • Fill Points – Boolean. Fills the points with series scheme foreground color • Draw Lines – Boolean. Draws lines between points in the series using series scheme foreground color • Category Values – Integer. Values in series for each category None List Property Name Type Description Related Event Actions Selection Mode - Select list selection mode. Choices are: {Single|Multiple|Contiguous}. Set Selection Mode Allow Empty Selection Boolean Is a list selection allowed to be empty? Set Allow Empty Selection Alignment - Horizontal text alignment. Choices are: { Left | Center | Right }. Set Item Alignment Icon Position - Position of list icons relative to list text. Choices are: { LeftOf | RightOf }. Set Icon Position Icon Margin - Space between icon and text, in pixels. Set Icon Margin Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 37 List Configuration Dialog - Defines the string and icon image for each entry in the list. Set Item Icon, Set Item Icon (actually sets item text). Additional Related Event Actions: Deselect All Items, Insert Item, Remove All Items, Remove Item, Select All Items, Set Item Selected, Toggle Item Select(ed). List Wheel Property Name Type Description Related Event Actions Alignment - Sets horizontal text alignment. Choices are: { Left | Center | Right }. Set Item Alignment Icon Position - Position of icons relative to text. Choices are: { LeftOf | RightOf }. Set Icon Position Icon Margin Integer Sets the space between icon and text. In pixels. Set Icon Margin Selected Index Integer Selects the default list item. Set Selected Index List Configuration Dialog - Defines the image/text for each entry in the list. Set Item Icon, Set Item Icon (actually sets item text) Additional Related Event Actions: Append Item, Insert Item, Remove All Items, Remove Item, Select Next Item, Select Previous Item. Panel – No additional properties. Pie Chart Widget Property Name Type Description Related Event Actions Start Angle Integer The starting angle of the pie chart in degrees. Set Start Angle Center Angle Integer The center angle of the pie chart in degrees. A positive value draws the chart counter-clockwise. Clockwise if negative. Set Center Angle Labels Visible Boolean Shows/Hides the labels for each data Show/Hide Labels Labels Offset Integer The position of the labels relative to the center of the pie chart, in pixels. Set Label Offset String Set String Asset The string asset containing the numeric characters for the tick labels. The asset must contain the characters for numbers 0 to 9. Set Label String ID Data Configuration Dialog (See Description) The Data Configuration Dialog lets users add data entries to the pie chart. The following properties can be set: • Value – Integer. The value of the entry • Radius – Integer. The radius, in pixels, of the pie for the entry • Offset – Integer. The offset, in pixels, of the pie from the center • Scheme – The color scheme for the ticks None Progress Bar Property Name Type Description Related Event Actions Direction - Direction of progress bar. Choices are: { Right | Down | Left | Up }. Set Direction Value - Default value of the progress bar. The primitives laProgressBarWidget_GetValue and laProgressBarWidget_GetValue can be used to manipulate the widget’s value during run time. Set Value Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 38 Radial Menu Widget Property Name Type Description Related Event actions Ellipse Visible Boolean Show the elliptical track of the widget Elliptical track gets draw in Harmony Composer simulation and at runtime. Highlight Prominent Boolean Highlights the prominent item when the widget rotation has completed its reset to the static, selectable position by drawing a rectangle behind the prominent item. - Ellipse Type Enum Selects the type of elliptical track Default – an elliptical track that best fits the widget area based on the size of the tallest and widest images with the size scale settings factored-in. Orbital – a “flatter” elliptical track that is best used with the Theta setting for a tilted look Rolodex – a vertical track with Theta setting locked at 90 degrees Locks Theta to 90 degrees when Rolodex is selected Theta Integer The angle (in degrees) of tilt relative to the y-axis of the ellipse. The number range is 0 to 90 degrees. This field is only valid for Default and Orbital Ellipse Type setting. It is locked at 90 when Rolodex is selected. a Integer This is the half-length (in pixels) of the 0-180 axis of ellipse. It is auto-calculated based on the widget size, the tallest image’s height, the ellipse type and scale settings. - b Integer This is the half-length (in pixels) of the 90-270 axis of ellipse. It is auto-calculated based on the widget size, the widest image’s width, the ellipse type and scale settings. - Size Scale Configuration • Size Scale * Minimum Size Modifier * Maximum Size Modifier Enum Integer Integer Off – all images displays at its original size Gradual – images in the very back are scale to the Minimum Size Modifier setting, the scale is gradually increased, with the prominent front item scaled to the Maximum Size Modifier setting Prominent – the image that is at the front, prominent location is scaled based on the Maximum Size Modifier, all other images are scaled to the Minimum Size Modifier setting The value (in percent) for the widget to resize the image to. When Size Scale is set to Gradual, this value represents the lowest scale for the item in the back. When Size Scale is set to Prominent, this value represents the scaling value for every image in the widget except for the prominent item. This value is equal to or less than the Maximum Size Modifier value The value (in percent) for the widget to resize the image to. When Size Scale is set to Gradual, this value represents the largest scale for the item in the front (prominent position). When Size Scale is set to Prominent, this value represents the scaling value for the prominent item. This value is equal to or greater than the Minimum Size Modifier value - - - Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 39 Item List Configuration • Total Number of Items Shown * Total Number of Widget Items * Widget Items Configuration Dialog Integer Integer (See Description) The number images visible on the radial menu. This number does not may be less than or equal to the total images in the widget. The total number of images the widget contains. The Widget Items Configuration Dialog lets users add images to the widget. The follow properties can be set: • Image – Image Asset. The image to show for the widget item The widget automatically space-out the images along the elliptical track base on this value. If this number is greater than Total Number of Items Shown, some of the images will be hidden in a FIFO queue in the back - Touch Area Configuration • Show Touch Area * Touch Area X Offset * Touch Area Y Offset * Touch Area Width Percent * Touch Area Height Percent Boolean Integer Integer Integer Integer Show visually in Harmony Graphics composer the rectangular area that permits touch interaction. The X-coordinate in local space of the touch-allowed area for the widget. This is auto-calculated based on the Touch Area Width Percent. The Y-coordinate in local space of the touch-allowed area for the widget. This is auto-calculated based on the Touch Area Height Percent. The percentage of the width of the touch-allowed area as compared to the entire widget area. The percentage of the height of the touch-allowed area as compared to the entire widget area. The default value is 50. This setting is for preview in Harmony Graphics composer only. The touch area is not rendered at runtime. - - If this value is less than 100 percent, the area is horizontally centered. If this value is less than 100 percent, the area is defined starting from the bottom of the widget. Radio Button Property Name Type Description Related Event Actions Text String - Select widget’s text string from the Select String Dialog. Set Text Alignment: • Horizontal • Vertical - Text string alignment within the widget. Horizontal alignment. Choices are: { Left | Center | Right }. Vertical alignment. Choices are: { Top | Middle | Bottom }. Set Horizontal Alignment Set Vertical Alignment Group Integer Radio Button Group Number. Default is -1, indicating no group. Only one radio button in a group can have a default selected value of On. All others in the group are Off N/A Selected Boolean If selected, the button has a default value of On. All other buttons in the group have a Selected value of Off. Select Selected Image - Select image used for selected state. Default: no image. Set Selected Image Unselected Image - Select image used for unselected state. Default: no image. Set Unselected Image Image Position - Position of image relative to widget text. Choices are: { LeftOf | Above | RightOf | Below | Behind }. Set Image Position Image Margin - Space between radio button image and text, in pixels. Set Image Margin Circle Button Size - The diameter of the default circle button, in pixels Set Circle Button Size Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 40 Rectangle Property Name Type Description Related Event Actions Thickness Integer Line thickness in pixels. Set Thickness Scroll Bar Property Name Type Description Related Event Actions Orientation - Scroll bar orientation. Choices are: { Vertical | Horizontal }. Set Orientation Maximum Integer Maximum scroll value (minimum = 0.) Set Maximum Value Extent Integer Length of scroll bar slider, re scroll bar maximum value. Indicates the number of lines or size of window visible at each scroll setting. Set Extent Value Integer Initial scroll bar value. Set Value, Set Value Percentage Step Size Integer Step size value of scroll bar arrow buttons. ( Min = 1, Max = 9999 ). Set Step Size Additional Related Event Actions: Step Backward, Step Forward Slider Property Name Type Description Related Event Actions Orientation - Orientation of the slider. Choices are: { Vertical | Horizontal }. Set Orientation Minimum - Minimum slider value. Set Minimum Value Maximum - Maximum slider value. Set Maximum Value Value - Initial slider value. Set Value, Set Value Percentage Grip Size - Grip size of slider, from 10 to 9999, in pixels. Set Grip Size Additional Related Event Actions: Step Text Field Property Name Type Description Related Event Actions Text String - Select widget’s text string from the Select String Dialog. Clear Text followed by Append Text Alignment - Horizontal alignment. Choices are: { Left | Center | Right }. Set Alignment Cursor Enable - Boolean. Show blinking cursor while editing. Set Cursor Enabled Cursor Delay - Cursor delay in milliseconds. From 1 to 999,999. Set Cursor Delay Additional Related Event Actions: Accept Text, Append Text, Backspace, Clear Text, Start Editing. Touch Test – No dedicated properties. Window Property Name Type Description Related Event Actions Title String - Select widget’s title string from the Select String Dialog. Set Title Icon Image - Select image used. Default: no image. Set Icon Image Margin Integer Space between icon and title, in pixels. N/A Layer Properties and Event Actions The property list for a graphic layer is close in look and feel to that of a widget. Each Layer has three property sets: Editor (see above), Widget (see above), and Layer (see below). Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 41 Layer Properties Property Name Type Description Related Event Actions Transparency Enabled Boolean Automatically mask out pixels of with a specified color. If enabled Specify: N/A Mask Color Integer Red/Green/Blue or Red/Green/Blue/Alpha color value N/A All Input Passthrough Boolean Allow input events to pass through this layer to layers behind it. N/A VSync Enabled Boolean Layers should swap only during vertical syncs. N/A Buffer Count Integer Integer number of frame buffers associated with this layer, either 1 or 2. N/A Buffer N - For each buffer (N= 1 or 2) you specify: - Allocation Method - Buffer allocation method. Choices are: { Auto | Address | Variable Name } • Auto – Automatically allocate frame buffer space • Address – Specify a memory address • Variable Name – Use variable name as buffer location N/A Memory Address - If Address is the allocation method, specify the raw (physical) memory address as a hexadecimal number. N/A Variable Name String If Variable name is the allocation method, specify the variable name as a string value. N/A Screen Properties and Events The property list for a screen shares the Name and Size properties with Layers and Widgets but has these unique properties. Screen Properties Property Name Type Description Related Event Actions Orientation - Display orientation: 0, 90, 180, 270 Degrees. This can also be set using the Display Manager. N/A Mirrored Boolean Enables screen mirroring. N/A Layer Swap Sync Boolean Enables that all layer buffer swapping happen at the same time, delaying lower layers until higher layers are finished drawing as well. For example, assume you make changes to layer 0 and layer 1 and you want to see those changes show up on the screen at the same time. Without this option you’d see layer 0’s changes as soon as it finishes when layer 1 has not yet started drawing. This option will hold layer 0’s swap operation until layer 1 finishes as well. Note: Currently, this property is only supported by the CLCD Graphics Controller Driver and is ignored by all other drivers. N/A Persistent Boolean Indicates that the screen should not free its widgets and memory when it is hidden. This results in faster load times and persistent data, but at the cost of higher memory consumption. N/A Export Boolean Includes this screen the application build. This can also be set using the Screens panel. N/A Primary Boolean Sets this screen as the primary screen. The primary screen is the first screen displayed when the application starts. This can also be done using the Screens Panel Generate check box. N/A Graphics Composer Asset Management The Asset menu supports managing all graphical assets (memory, images, languages, fonts, strings, and binary data). Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 42 Memory Configuration Provides information on configuring memory locations. Description The Memory Locations window is launched from the Graphics Composer’s Asset menu. Selecting Memory Locations this brings up a window with three sub-tabs (in this example, the Aria Showcase demonstration is referenced): Window Toolbar The window’s tools icons support: 1. Add New Memory Location – This supports multiple external memory resources. 2. Delete Selected Memory Location – Removes a previously defined memory location. 3. Rename Selected Memory Location – Renames a previously defined memory location. 4. Configure External Media Application Callback – This allow definition of media callbacks, which must be provided in the project. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 43 5. Show Values as Percent – Memory utilization on the bar graph can be in bytes or as a percent of the total internal flash memory assigned to support asset storage. (That memory allocation is set using the Configuration sub-tab.) The APIs for the external media callback functions are as follows: GFX_Result app_externalMediaOpen(GFXU_AssetHeader* asset); GFX_Result app_externalMediaRead(GFXU_ExternalAssetReader* reader, GFXU_AssetHeader* asset, void* address, uint32_t readSize, uint8_t* destBuffer, GFXU_MediaReadRequestCallback_FnPtr cb); void app_externalMediaClose(GFXU_AssetHeader* asset); The graphics demonstration project, aria_external_resources, provides an example of how to write these callbacks. This demonstration supports three types of external memory: SQI External Memory, USB Binary, and USB with File System. Examples of these callbacks are found in the project’s app.c file. The Aria demonstration projects Aria External Resources and Aria Flash provide more details on how to use external memory to store graphics assets. Sub-tabs There are three sub-tabs to this window. Summary Sub-tab This sub-tab summarizes program flash allocations for images, strings, and fonts. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 44 The memory allocation shown for “Font Glyphs” measure the space that holds all the font glyphs used by the application, either by static strings or by glyph ranges defined in support of dynamic strings. Strings are defined by arrays of pointers to glyphs, so string memory usage measures the size of these arrays, not the actual font glyphs used. (“Glyph” is defined here.) Note: The word “glyph” comes from the Greek for “carving”, as seen in the word hieroglyph – Greek for “sacred writing”. In modern usage, a glyph is an elemental or atomic symbol representing a readable character for purposes of communicating through writing. Configuration Sub-tab This sub-tab specifies the intended allocation of internal (program) flash memory to graphics assets (Total Size). (The default value is 1024 bytes.) It also names the graphics assets file name (here it will be gfx_assets.c). The allocation of flash is only used to scale the Total/Used/Available bar graph at the top of the display. Under sizing or oversizing this amount does not affect how the application is built. If your device has 1024 Kbytes (1048576 bytes) of flash, you can assign 40% to asset storage and 60% to code. In that case the “Total Size” in the above sub-tab would be set to 419430 (= 40% of 1048576). The Calculator button can assist you in allocating internal flash. Click on it and then set the device flash capacity. Then you can apply an adjustment to that value to assign that memory to asset storage. Example: If the device has 2 Mbytes of internal Flash, click 2MB. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 45 Then, to assign 75% of the 2 Mbytes to asset storage, click -25% to reduce the 2 MB by 25%, leaving 75%, and then click OK to finish. This will then assign 1,536,000 bytes to asset storage. Internal (program) Flash is shared between the application’s code and asset storage. If the application code and graphics assets (fonts, strings, images) won’t fit into the available flash memory then the linker will be unable to build the application and an error will be generated in MPLAB X IDE. The Output File Name must be compatible with the operating system hosting MPLAB X IDE. In most cases the default name (gfx_asset.c) will suffice, but this is provided for additional flexibility in building the application. Optimization Sub-tab The Optimization sub-tab for the Aria Quickstart demonstration is shown in the following figure. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 46 The Size column shows the bytes allocated for storage in internal flash for the images, fonts, and binaries of the application. The References column shows the number of known references for these assets by the application’s widgets. A references count of zero suggests that the asset is not used by the application, but it could also mean that the asset is only used in real-time when it is dynamically assigned to a widget by the application. Clicking the title of a column (Name, Size, or References) sorts the lists of graphics assets by that column. Clicking the same column again reverses the sort order. The window’s tools icons support: 1. Edit Selected Asset – This brings up the edit dialog for the image, font, or binary chosen 2. Delete Selected Assets – Removes the selected assets 3. Move Selected Assets – Move assets from one location to another. This is useful for moving assets to/from internal memory from/to external memory. 4. Show Only Images – Show image assets toggle on/off 5. Show Only Fonts – Show font assets toggle on/off 6. Show Only Binaries – Show binary assets toggle on/off DDR Organizer The DDR Organizer tool supports managing buffers, raw images, and other memory resources in the DDR memory of DA devices and only DDR-enabled DA devices. This tool also requires that the DA’s built-in 2D graphics processor be enabled. Under Harmony Framework Configuration > Graphics Stack > Graphics Processor, select the NANO 2D processor: The DDR Organizer tool is launched from the Assets Management pull-down menu: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 47 The following window will appear if the tool has not been used before for the active project target configuration: Select the memory profile that corresponds to the target DDR-enabled DA device: Then select the Load Button to load that memory configuration into the tool. When Preprocessing is enabled for an image under the Image Assets tool: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 48 An entry for the image appears in the DDR Organizer window: When the memory profile is loaded, the tool automatically reserves DDR memory for the GLCD Frame Buffers sufficient for three double-buffered layers, allocating 32 bits (4 bytes) for RGBA_8888 format for each pixel. This provides 384,000 pixels (800x480) per frame buffer. The tool icons support adding non-image memory allocations to the DDR memory map. To add or remove the memory allocation belonging to an image, the Preprocessing enabled property for that image is enabled/disabled using the Image Asset tool. Image Assets Provides information on the Image Assets features. Description The Image Assets window is launched from the Graphics Composer’s Asset menu. The Image Assets window lets you import images, select different image formats/color modes for each image, select compression methods (for example, RLE) for each image, and displays the memory footprint of each. Images can be imported as a BMP, GIF, JPEG, and PNG (but not TIFF). Images can be stored as Raw (BMP, GIF), JPEG, and PNG. Note: MHGC does not support image motion that can be found in GIF (.gif) files. GIF images are stored in the raw image format, meaning that there is no image header information stored with the image. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 49 When an image is imported into MGHC, the Graphics Asset Converter (GAC) stores the input format and color mode along with any relevant header data. The image’s pixel data is then promoted from its native format into a Java Image using 32 bits/pixel (8 bits for each color, RGB, and 8 bits for Alpha Blending). If the image contains Alpha Blending then this information is stored in the “A” of RGBA, otherwise the “A” is set to maximum opacity. When the application is built each image is stored in the image format and color mode selected. Images displayed in the Screen Designer are converted from Java Image format into the format/color mode selected so that the Screen Designer accurately represents what the application will show when running. The images are decoded on the fly by the graphics library and rendered on the screen. This provides the designer with considerable flexibility to import using one format and store resources using another format, thus exploring and maximizing the best memory utilization for their application and hardware. This supports trading a smaller memory footprint at the cost of additional processing (for static or drawn-once) or reducing processing at the cost of a larger memory footprint (dynamic or drawn many times). The following figure shows the Image Assets window for the Aria Quickstart demonstration. Window Toolbar There are five icons on the toolbar below the Images tab: 1. Add Image Asset – Brings up “Import Image File” dialog window to select image file to add to the graphics application. 2. Replace Existing Image with New Image File – Brings up the same “Import Image File” dialog but instead of creating a new image, the file’s content replaces the currently selected image. 3. Rename Selected Image – Renames the selected image. 4. Create New Virtual Folder – Creates a new virtual folder, allowing you to organize images in a hierarchy. 5. Delete Selected Images – removes the selected images from the application. Selecting the Add Image Asset or Replace Existing Image icon opens the Import Image File dialog that can be used to select and import an image. After selecting the file and clicking Open, the Image Assets window opens. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 50 The size of the memory used for this image based on its color mode, format, compression, and global palette usage is shown by Size (bytes). See Image Format Options below for more details. The File Name of the original source file is also shown, but may be blank if the image was imported under MPLAB Harmony v2.03b or earlier. The format and color mode of the stored image can be changed to reduce the image’s memory footprint. (If using an LCC controller, you can also turn on the Global Palette, replacing each pixel in the image with just an 8 bit LUT index.) The three internal image formats are: • Raw – binary bit map with no associated header information. GIF and BMP images are imported into this format. • PNG – lossless image format with compression, 24 bits/pixel (RBG_888) or 32bits/pixel (RGBA_8888). A good choice for line drawings, text, and icons. • JPEG (JPG) – loss compressed format, uses much less storage than the equivalent bit map (raw). Good for photos and realistic images. New to Harmony 2.06 is the option to preprocess an image into raw pixels at boot-up, which will greatly improve image draw/redraw times though the use of the high performance 2-D graphics processing unit (GPU) that is available on DDR-enabled DA devices. Be sure that this feature is enabled in MPLAB Harmony Configurator. Under Harmony Framework Configuration > Graphics Stack > Graphics Processor, select the NANO 2D processor: Note: Do not enable image preprocessing except on DDR-enabled DA devices with the NANO 2D graphics processor enabled. To do so will produce an application that builds but does not run. With Preprocessing of the image enabled, additional options become available: • DDR Memory allocation for the image is automatically handled when the Managed option is selected • The Output Mode should be selected to match the GLCD’s color mode, typically RGBA_8888 • The Padding option expands the image size to the nearest power of two. For example, a 480x212 image would be increased to 512x256 pixels. • The expected size of the preprocessed image in DDR memory is shown in the Expected Size entry For more information on how images are stored within DDR memory, see the section on the Asset Management DDR Memory tool above. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 51 The Image Assets window supports resizing, cropping, or resetting an image: • Resize – Brings up a dialog window to change the pixel dimensions of the image. The image is interpolated from the original pixel array into the new pixel array. • Crop – Places a cropping rectangle on the image. Click and drag a rectangle across the image to select the new image. Then click Ok to crop the image. • Reset – Allows undoing of a resize or crop. The original image is always stored in the project, so a Reset is always available to return the image to its original state. Original images are retained by MHGC by the superset Java Image format. So an image crop will change how the image is stored in the application but not how it is stored in MHGC. Reset will always restore the image back to the original pixels. (Reset is not an “undo”.) Example Images Example images are available from many sites on the internet. One of the best sites is found at the USC-SIPI Image Database (http://sipi.usc.edu/database/). There are many canonical test images, such as Lena, The Mandrill (Baboon), and other favorites, all in the TIFF Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 52 format. The TIFF format is not supported by the Graphics Composer, but you can easily convert from TIFF to BMP, GIF, JPEG, or PNG using the export feature found in the GNU Image Manipulation Program (GIMP), which is available for free download at: https://www.gimp.org. GIMP also allows you to change the pixel size of these images, usually 512x512, to something that will fit on the MEB II display (either 256x256 or smaller). The following figure shows the Graphics Composer Screen Designer for the pic32mz_da_sk_meb2 configuration of the Aria Quick Start project after adding three images. The following figure shows the Optimization Tab after adding these images. Selecting the Baboon_GIF image and the Edit Selected Asset icon ( ) opens an Image Assets window, as shown in the following figure. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 53 Because this image had only 253 unique pixel colors (Unique Pixel Count = 253) the Enable Palette option was automatically enabled. This feature, which works on an image by image basis, is separate from enabling a Global Palette. The image is stored using 8 bits of indexing into an image-specific lookup table (LUT). If the image has more than 256 unique colors then the Enable Palette option is not available and is not shown. Image Format Options Raw Format Images Raw format images have the following options: Regardless of the Color Mode of the imported the image, the stored image can be stored in a different color mode. For example, a JPEG image could be in 24 bits/pixel RGB format but stored in the application using RGB_565 or even RBG_332 to save space. The Project Color Mode (set through the File > Settings menu) is different from the Color Mode of images. This is determined by the capabilities of the projects graphics controller. The graphics library converts images from the stored color mode to the project’s color mode before output. If the image has 256 or less unique pixel colors an option to Enable Palette is set by default. If the image has more than 256 unique colors this option is not displayed. This replaces the palette pixels with 8-bit indices into the image’s palette look up table (LUT). NOTE: Enabling the Global Palette disables this for all images and all image pixels are replaced by 8-bit indices into the global palette LUT. The Compression Mode for a raw format image is either None (no compression) or RLE for run-length encoding. Image masking is a form of cheap blending. For example, given the following image, you may want to show the image without having to match the lime green background. With image masking you can specify that the lime green color as the “mask color”, causing it to be ignored when drawing this image. The rasterizer will simply match a pixel to be drawn with the mask. If they match, the pixel is not rendered. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 54 PNG Format Images For PNG format images you can change the image format and the image color mode: JPEG Format Images For JPEG format images you can change from JPEG format to Raw or PNG: Once changed from JPEG into another format, the new format will have other options. Managing Complex Designs The Image assets tool lists the images in the order of their creation. In a future version of MPLAB Harmony this will be sortable by image name. For now, it is recommended that you use the Memory Locations asset tool, and use the Optimization sub-tab instead to manage a complex set of images. The Optimization sub-tab allows you to sort graphics assets (fonts, images, binaries) by Name, Size, and number of widget References. This makes it much easier to find and edit an image by its name rather than order of creation. Font Assets Provides information on the Font Assets features. Description The Font Assets window is launched from the Graphics Composer’s Asset menu. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window • Fonts are managed within the Font Assets window (this topic) • Strings are managed within the String Assets window The following figure shows the Font Assets window from the Aria Coffee Maker demonstration. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 55 The Size (bytes): for a Font asset shows how much memory is needed to store all the glyphs used by the application from this font. For static strings MHGC determines which glyphs are used by the application’s pre-defined strings and builds these glyphs into the application. For dynamic strings (i.e. strings created during run time) ranges of glyphs are selected by the designer and these ranges are also included in the application by MHGC. The memory needed to store all these glyphs is shown by Size (bytes): . Window Toolbar There are five icons on the toolbar below the Images tab: 1. Add Font From File – Adds a font asset from a file. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 56 2. Add Installed Font – Add a font installed on your computer. 3. Replace Existing Font Data with New Source Font – Both Add Font From File and Add Installed Font create a new font asset. This icon allows you to update an existing font asset, importing from a file or using a font installed on your computer. 4. Rename Selected Font – Renames an existing font asset. In the example above, the Arial font was installed twice, first as a 16 point font and second as a 12 point font. If added to the fonts assets in this order, the 12 point font will have the name Arial_1. This font asset was renamed to Arial_Small using this tool. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 57 5. Delete Selected Fonts – Removes selected font assets from the application. Sub-tabs There are three sub-tabs to this window. Style Sub-tab The Size (bytes): shown represents the memory needed to store all the font’s glyphs. The application only stores the glyphs that are used by static (build-time) strings and by predefined glyph ranges to support dynamic (run-time) strings. The choices for Memory Location must be defined before the font can be assigned. Go to the Memory Configuration window to add a new location before using it in this sub-tab. Each font asset consists of a font, size, and some combination of the { Bold, Italic, Anti-Aliasing } options, including selecting none of these options. If you need bold for one set of strings and italic for another, then you will need two font assets, one with Bold checked and a second with Italic checked. The same applies for font sizes. Each font size requires its own font asset. Thus if you need two sizes of Arial, with plain, bold, and italic for each size, you will need 6 separate assets (6 = 2 Sizes x 3 ). Glyphs are normally (Anti-Aliasing off) stored as a pixel bit array, with each pixel represented by only one bit. Turning on Anti-Aliasing replaces each pixel bit with an 8-bit gray scale, thereby increasing font storage by a factor of 8! What if a font is chosen that does not support the character types of the text used for a particular language in the application? How can you test and debug this? There a basically two ways: • Use an external font viewer to examine if the needed glyphs exist • Configure, build, and run the application and verify the strings are correctly rendered If the glyphs are not available they will be rendered as rectangles ( ). Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 58 Strings Sub-tab The Bound check box accomplishes the same thing as assigning a font to a text string in the Strings Assets window (Window:Strings menu). Assigning a string to a font means that the font will generate glyphs for that string. This is just another way to accomplish the binding of the string text to font. This sub-tab is also useful in a complicated graphics design to see how many strings use a particular font. Lightly-used or unused fonts can be eliminated to free up internal Flash memory. Glyphs Sub-tab Note: The word “glyph” comes from the Greek for “carving”, as seen in the word hieroglyph – Greek for “sacred writing”. In modern usage a glyph is an elemental or atomic symbol representing a readable character for purposes of communicating via writing. The Glyph sub-tab is only used when your application supports dynamic strings. For static (build-time) strings MHGC automatically determines which font glyphs are used based on the characters present in all the strings used by the application’s graphics widgets. Only these glyphs are included as part of the application’s font assets. With dynamic (i.e. run-time) strings this is not possible. This sub-tab allows you to specify which range of glyphs will be used by run-time strings. Once glyph ranges are defined, these glyphs are added to the font glyphs used by static strings. The Create New Custom Import Range icon ( ) allows you to input a new glyph range for the font. Selecting this icon opens the Font Assets window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 59 String Table Configuration Provides information on the String Assets features. Description The String Table Configuration window is launched from the Graphics Composer’s Asset menu. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window (this topic) • Fonts are managed within the Font Assets window • Strings are managed within the String Assets window Within this window, the Languages supported by the application are defined and the encoding for all application glyphs selected. The “ID” string used for each language is merely for ease of use in building the texts to be used. “English”, “American”, or any other string can be used to identity that language, as long as it is understood by the application’s creator when selecting the text to be used for that particular language. Then the application can switch to supporting one of its languages using “ID” strings defined. Here is an example string asset definition, taken from the Aria Coffee Maker demonstration. This application supports English, French, Italian, and German. The text string “InfoText_Desc9” uses the Arial font, and text for each language is specified within the String Assets window. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 60 Any number of languages can be defined as long as there is memory to store the strings needed. The following figure shows the String Table Configuration for an application that uses English, Spanish, and Chinese. The size of all the strings for each language is shown in the Size column. String size represents the memory allocated for glyph indices for all the strings supporting that language. A language can be enabled/disabled via the check box in the Enabled column. Disabling a language removes it from the application build but keeps it in the project. Window Toolbar There are three icons on the toolbar: 1. Add New Language – Adds a new Language. 2. Set Default Language – Sets the application’s default language. Note, this is different than the abc tool on the Graphics Composer Window toolbar. The abc icon sets the preview language for the Screen Designer panel only. This icon sets the language used by the application after boot-up. 3. Remove Selected Language – Removes language from the application. Clicking Add New Language opens a new line, allowing you to select and edit the new language’s “ID” string. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 61 Then, for every string defined in the application there will be a line to define the needed text, and to specify the font to be used. If you don’t provide a value for the new language the string will be output as a null (empty string). If you don’t provide a Font selection then the string will be output as a series of blocks (?). The Aria User Interface Library primitive, LIB_EXPORT void laContext_SetStringLanguage(uint32_t id), allows the application to switch between languages using the Language ID #defines are specified in the application’s gfx_assets.h file. Sub-tabs There are two sub-tabs to this window. Language Definitions Sub-tab This sub-tab shows the languages defined for the application. A Language can be enabled/disabled to include or exclude it from the application’s generation/regeneration under MPLAB Harmony Configurator (MHC). New languages can be added by specifying a text string for the language. With a new language, go to the String Assets window to specify the text and fonts for all defined strings. Encoding Sub-tab Selecting the Character Encoding Format Selection Dialog icon gives you three choices for how the characters in all strings in the graphics application are encoded: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 62 The default is ASCII. It is typically the most efficient in terms of memory and processing, but it does not support as many glyphs. Chinese text should be encoded in UTF-8 or UTF-16, but Western language text can be encoded in ASCII to save memory. The trade-off between ASCII, UTF-8, and UTF-16 depends on the application. Changing from UTF-8 to UTF-16 will double the size of all strings in the application. This is because the sizes of all glyph indices double in size. (String sizes are the sizes of glyph reference indices, not the size of the particular font glyphs used to write out the string.) The memory utilization resulting from an encoding choice can be seen in the Summary sub-tab of the Memory Configuration window. String Assets Provides information on the String Assets features. Description The String Assets window is launched from the Graphics Composer’s Asset menu. The String Assets window supports managing the strings in the application. Strings are referenced by graphic widgets using an application-wide unique name. This unique name is built into an enumeration that the application’s C code uses. For each language supported text is defined and a font asset selected. Note: There are three dimensions to text support: Languages, Fonts, and Strings. Language “ID” strings are identified when an application supports more than one language. (In the case of single language support, the language default is provided.) Fonts are imported and organized using the Font Assets window. Strings are defined by a string name, and this name is used by widgets to reference the string. For each string and each language supported the glyphs are defined to spell out the string’s text and the font is chosen for that text. • Languages are managed within the String Table Configuration window • Fonts are managed within the Font Assets window • Strings are managed within the String Assets window (this topic) The following figure shows an example taken from the Aria Coffee Maker demonstration. The string name, InfoText_Desc9, defines a string asset that is used by the application. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 63 The Total Size in Byte: for a string asset represents the memory needed to store the glyph indices for all the text defined for that string asset. Adding more text will increase the number of glyph indices needed thus increasing the size of the string’s memory. Adding another language will do the same, since the number of glyph indices also increases. Changing the font does not increase the size of the string’s memory, but may increase the size of the font chosen if it is a “bigger” font and adds more glyphs to the new font. (By “bigger” we mean a font with more pixels, for example because it is bigger in size, or perhaps because it is anti-aliased and the original font was not.) Note: The Reference Count shown reflects the number of build-time references to the string. Dynamic uses of a string, such as through macros or events, is not reflected in this number. Window Toolbar There are four icons on the toolbar: 1. Add New String – Adds a new string. 2. Rename Selected Item – Allows renaming the string. 3. Describe Selected String - Provides a Description field value for selected string. 4. Create New Virtual Folder – Creates a new virtual folder, allowing you to organize strings in a hierarchy. Here’s an example reorganization of the existing strings. Note the order of virtual folders or items in the list is strictly alphabetical. Virtual folders and string asset organization is merely for the convenience of the developer. Neither has an effect on how the application is built. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 64 5. Delete Selected Items – Deletes selected strings from the application. 6. Import String Table - Imports an Excel CSV (Comma Separated Value) file to replace the current string table. 7. Export String Table - Exports the current string table as an Excel CSV (Comma Separated Value) text file. Creating New Strings To create a new string, click Add New String ( ). Selecting this icon opens the Add String dialog to name the string. The text chosen for the string name should be acceptable as a C variable. After entering the new string’s name and click Create, the following String Assets window appears. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 65 In the String Assets window, there will be a line for each of the languages defined for the application. Provide the string text and font for each of the languages. An empty string will be used if the text is not provided. Not providing a font causes the string to be rendered as a string of boxes ( ). Importing and Exporting String Tables Importing an Excel CSV (Comma Separated Values) file replaces the existing string assets table. Exporting creates an Excel CSV file that can be imported into another project or target configuration. Exported string tables can be manipulated in Excel, even combining multiple string tables into a single string table that can then be imported. If the string asset table contains UTF-8 then the file cannot be directly loaded into Excel. Instead, within Excel create a new sheet. Import the string table using Get Data, selecting From File, From Text, or CSV. Then in the dialog window change the File Origin to Unicode (UTF-8). Note: Excel does not support importing UTF-16. Binary Assets Provides information on the Binary Assets features. Description The Binary Assets window is launched from the Graphics Composer’s Asset menu. Selecting the Add Binary File icon ( opens the Import File dialog. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 66 This supports any formatted binary file. Developers can then add a custom-coded decoder to support the format implied by the imported file. (A future version of the GFX library will include a bin2code utility in support of this feature.) MHGC Tools The Tools menu supports managing all graphics events, using a global palette, and estimating heap memory usage. Event Manager This section provide information on the Event Manager. Description The Graphics Composer Event Manager provides a GUI interface to manage all of the events associated with a graphics application. In a general sense, an event is an action or occurrence that is processed by software using an “event handler”. Button pushes or keystrokes are widely recognized and handled events. Events related to a touch screen are commonly called “gestures”. This GUI allows the assignment of actions to events associated with graphics widgets and to events outside of the graphics library. Under the Graphics Composer Event Manager tab there are two sub-tabs, one for “Events” and a second for “Macros”. The following table summarizes the difference between "events" and "macros" and provides examples of each instance of source to destination: Differences Between Events and Macros Source Inside of Graphics (Destination) Outside of Graphics (Destination) Inside of Graphics "Event" Example: Button changes button text "Event" Example: Button changes MEB2 LED color Outside of Graphics "Macro" Example: Mounting SD card changes screen Not supported by Event Manager Tool “Events” under the first tab are generated from within graphics widgets and can manipulate the properties of screen widgets or set semaphores that engage with the rest of the application. “Macros” are executed outside of graphics widgets by other parts of the application. “Macros” allow the application to change widget properties or behavior. Both “Events” and “Macros” event handlers can be built using collections of “Template” actions or using “Custom” developer-provided code. Most widget properties have an associated Template action that can be used to manipulate that property in an event handler (either “Event” or “Macro”). For more information on properties and related actions, see the discussion on the Properties Window below. To explore these capabilities, let’s look at the Aria Quickstart project after the completion of the Adding an Event to the Aria Quickstart Demonstration Quick Start Guide. Graphics Composer Events The Graphics Composer Screen Designer shows that there is one layer and three widgets in this demonstration. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 67 Of the three widgets shown above, only ButtonWidget1 can have events associated with it, one for button pressed and a second for button released. This can be seen in the Graphics Composer Event Manager window, which is available from the Tools menu: The events shown under “ButtonWidget1” are mirrored in the widget’s properties. Selecting or clearing an event in one window does the same in the other window, thus enabling (selecting) or disabling (clearing) the corresponding event. We can add a Check Box widget to the applications display and then use the Event Manager to assign actions to the widget’s events. A Check Box widget has two events, one for being “Checked” (i.e., selected) and another for being “Unchecked” (i.e., cleared). Enabling the “Checked” event then allows the selection of the action or actions for that event. The Actions: sub-window has five tool icons for managing the actions associated with an event: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 68 Clicking the Create New Action icon ( ) opens the Action Edit dialog. If you select Custom and click Next, you will see the following dialog. Unfortunately, there is no C code error checking with this window. It just copies the code into libaria.c and libaria.h. If there is a problem with the code you will not know about it until you try to build your application. An alternative is just to type a comment such as /*My event goes here*/, generate the code, and then find out where this comment landed in the code. (Typically, inside libaria_events.c, or libaria_macros.c) You can then write the action routine from within the MPLAB X IDE editor and compile just that file to debug the code written. If you select Template, the Action Edit dialog will update, as follows. Select ButtonWidget1. As shown previously, you next need to select the widget that you want to manipulate with this action. Note that the event originated with CheckBoxWidget1, but the event’s action can manipulate any of the existing widgets. In this case, ButtonWidget1 has been selected. Clicking Next Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 69 will then bring up a list of the actions available in manipulating a button widget. You can select the “Set Text” action, which will then change the button’s text property, followed by NEXT, which will open a dialog to select the text string for this action. You can then select from the available (already defined) strings which text to use for the button’s text field. Press the Finish button to complete the definition of this action. Screen Events As shown previously, the Graphics Composer Event Manager, Events sub-tab supports screen events when the screen is visible (On Show) and hidden (On Hide). These events can define event handlers based on Template actions or Custom, user-defined code. Widget Events Not all widgets can generate an event. For example, a Label Widget has nothing to generate, it just sits there on the screen, labeling. Here is a list of the widgets that can generate an event: • Button – Pressed and Released events • Check Box – Checked and Unchecked events • Draw Surface – Draw Notification event • Image Sequence – Image Changed event Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 70 • Key Pad – Key Click event • List Wheel – Select Item Changed event • List – Selection Changed event • Progress Bar – Value Changed event • Radio Button – Selected and Deselected event • Scroll Bar – Value Changed event • Slider Widget – Value Changed event • Text Field – Text Changed event • Touch Test – Point Added event Graphics Composer Macros Macros implement event handlers for events that originate outside of graphics primitives such as widgets and are designed to change or manipulate widgets inside of the graphics part of an application. (Events that originate outside of graphics and don’t touch the graphics part of the application are outside of the scope of the Graphics Event Manager and are not discussed here.) The following figure shows a simple example of a macro. The toolbar for Macros has three icons. Creating a new macro and selecting its actions is just like that of a widget event: 1. Create a new macro using the “Create New Macro” tool. The check box to the left of the new macro’s name enables/disables the macro. Clearing it removes the macro from the next code generation. 2. Select the new macro and edit it using the second icon (shown previously). 3. In the Actions: window, select Create New Action. An optional name can be provided in the Name: box. You can then choose to use a Template and select a predefined action or Custom to create a customized action. 4. If you chose a “Custom” action, proceed as discussed previous in Graphics Composer Events. When using templates the next step is to choose the target widget for the action. This choice is limited to those only the widgets in the currently “active” screen. If your application has multiple screens and the widget you are targeting is not part of the currently active screen you need to change the active screen. • Changing the active screen can be done by selecting the corresponding screen tab at the bottom of the Graphics Composer Screen Designer • Alternately, you can switch using the Graphics Composer Manager:Screens tab Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 71 5. After selecting the target widget for this macro, click Next button to select an action related to this widget. (Just as with template-based widget events.) The macro can contain more than one action, targeting more than one widget. Graphics Events Test Bed Additional examples of events and macros can be found in the MPLAB Harmony project found in ./apps/examples/events_testbed. This project is based on the Quick Start Guide “Adding an Event to the Aria Quickstart Demonstration” found in Volume 1 of MPLAB Harmony’s built-in documentation. This project has target configurations for PIC32MZ DA and EF starter kits with the MEB2 graphics board. It demonstrates the following events/macros: Event Testbed Source Inside of Graphics (Destination) Outside of Graphics (Destination) Inside of Graphics "Event" Button changes button text from "Make Changes. Generate. Run" to "Ouch! Ouch! Ouch!" "Event" Virtual Switch S1 changes MED2 LEDs D6 and D7 on/off via boolean semaphore Outside of Graphics "Macro" APP_Tasks changes color scheme for Virtual LEDs D6 and D7 between LED_OFF and LED_ON Not supported by Event Manager Tool MEB2 S1 changes MEB2 LEDs D6 and D7 Asserting the “Make Changes. Generate. Run” button on the display changes its text to “Ouch! Ouch! Ouch!”. Pressing the MEB2’s Switch S1 changes the LED D6 and D7 on the MEB2 board as well as changing the virtual LEDs D6 and D7 on the display. Pressing the display’s virtual S1 switch does the same. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 72 The application’s events are defined in libaria_events.c: #include "gfx/libaria/libaria_events.h" // CUSTOM CODE - DO NOT DELETE extern bool bDisplay_S1State; // END OF CUSTOM CODE // ButtonWidget1 - PressedEvent void ButtonWidget1_PressedEvent(laButtonWidget* btn) { // ButtonDown - Set Text - ButtonWidget1 laButtonWidget_SetText((laButtonWidget*)ButtonWidget1, laString_CreateFromID(string_OuchOuchOuch)); } // ButtonWidget1 - ReleasedEvent void ButtonWidget1_ReleasedEvent(laButtonWidget* btn) { // ButtonUp - Set Text - ButtonWidget1 laButtonWidget_SetText((laButtonWidget*)ButtonWidget1, laString_CreateFromID(string_Instructions)); } // Display_S1 - PressedEvent void Display_S1_PressedEvent(laButtonWidget* btn) { // CUSTOM CODE - DO NOT DELETE bDisplay_S1State = true; // END OF CUSTOM CODE } Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 73 // Display_S1 - ReleasedEvent void Display_S1_ReleasedEvent(laButtonWidget* btn) { // CUSTOM CODE - DO NOT DELETE bDisplay_S1State = false; // END OF CUSTOM CODE } The ButtonWidget1 changes the text using the laButtonWidget_SetText function. Details on how this is accomplished are discussed in the Quick Start Guide “Adding an Event to the Aria Quickstart Demonstration”. The Display_S1 widget just sets a Boolean semaphore bDisplay_S1State. Creating the events for the Display_S1 virtual switch is easy, just enable the widget’s events in the widget’s properties: This will create empty event handlers in libaria_events.c, which can then be modified to change the boolean semaphore bDisplay_S1State as shown above. The application’s macros are defined in libaria_macros.c change the coloring scheme for the display’s virtual LEDs: #include "gfx/libaria/libaria_macros.h" void LEDsTurnOn(void) { if(laContext_GetActiveScreenIndex() != default_ID) return; // TurnOnDisplayD6 - Set Scheme - MEB2_LED_D6 laWidget_SetScheme((laWidget*)MEB2_LED_D6, &LED_ON); // TurnOnDisplayD7 - Set Scheme - MEB2_LED_D7 laWidget_SetScheme((laWidget*)MEB2_LED_D7, &LED_ON); } void LEDsTurnOff(void) { if(laContext_GetActiveScreenIndex() != default_ID) return; // TurnOffDisplayD6 - Set Scheme - MEB2_LED_D6 laWidget_SetScheme((laWidget*)MEB2_LED_D6, &LED_OFF); // TurnOffDisplayD7 - Set Scheme - MEB2_LED_D7 laWidget_SetScheme((laWidget*)MEB2_LED_D7, &LED_OFF); Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 74 } The difference between the color scheme LED_OFF and LED_ON is only in the base color: The macros LEDsTurnOn and LEDsTurnOff are called from the application’s main task loop, APP_Tasks. The work of controlling the LEDs is done in the APP_STATE_SERVICE_TASKS case.: #include "gfx/libaria/libaria_macros.h" bool bMEB2_S1State = false; bool bDisplay_S1State = false; bool bLED_State = false; bool bLED_StateNow; void APP_Tasks ( void ) { /* Check the application's current state. */ switch ( appData.state ) { /* Application's initial state. */ case APP_STATE_INIT: { bool appInitialized = true; if (appInitialized) { appData.state = APP_STATE_SERVICE_TASKS; } break; } case APP_STATE_SERVICE_TASKS: { bMEB2_S1State = !BSP_SWITCH_S1StateGet(); // Closed --> grounded bLED_StateNow = bMEB2_S1State || bDisplay_S1State; if ( bLED_State != bLED_StateNow ) {// LED state has changed if ( bLED_StateNow ) { BSP_LED_D6On(); // MEB2 LED D6 On BSP_LED_D7On(); // MEB2 LED D7 On LEDsTurnOn(); // Turn display LEDs on } else { BSP_LED_D6Off(); // MEB2 LED D6 Off BSP_LED_D7Off(); // MEB2 LED D7 Off LEDsTurnOff(); // Turn display LEDs off }//end if ( bMEB2_S1State || bDisplay_S1State ) bLED_State = bLED_StateNow; // Remember new state } break; Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 75 } /* TODO: implement your application state machine.*/ /* The default state should never be executed. */ default: { /* TODO: Handle error in application's state machine. */ break; } } } Heap Estimator Provides information on heap space allocation. Description Many parts of a graphics design are implemented using memory allocated from the application’s heap space. Therefore, it is important to allocate sufficient memory for the heap. This tool can estimate heap usage by the allocation based on the widgets, layers, screens, and decoders currently in the design. When launching the tool from the Tools menu, the Heap Configuration window appears. Clicking Calculate estimates heap usage. The following figure shows what occurs within the Aria Quickstart demonstration if the heap space is only 4096 bytes: The Summary tab shows how the estimated heap requirements was derived by summing up all the sizes shown under the “Size (Bytes)” column. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 76 Note that the largest contribution comes from the screen requiring the largest heap allocation (in this case MainMenu). If there is insufficient memory allocated to the heap, an exclamation point ( ! ) appears in the window. If you hold your mouse pointer over this icon, the following message appears: You can click Set MHC Heap Value to reset the heap allocation to match the estimated requirements. Selecting Add to MHC Heap Value adds the estimated heap requirements to the current heap value. (In the case above, this would change the heap allocation to 4096+10664 bytes.) Alternately, you can set the heap allocation to a larger value by going to the MPLAB Harmony Configurator window, selecting the Options tab and setting the Heap Size within Device & Project Configuration > Project Configuration. The Screen Details tab (from the Aria Showcase demonstration) shows screen-by-screen the heap space needed for each layer and widget on the screen selected. Note: After you have updated the Heap Size, either using the Heap Estimator tool or by directly editing the value as shown above, you must regenerate the project using the Generate Code button. This will update the actual heap size value used in building the application. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 77 Clicking the “Name” column will alphabetize the list. Clicking the “Size (Bytes)” column sorts the assets by size, with the largest at the top and smallest at the bottom. This sub-tab can help in managing the application’s utilization of heap space. For example, excess use of cached backgrounds for widgets can become ruinously expensive, expanding the application’s need for heap well beyond the capabilities of the device. As an example, consider a screen label from the Aria Showcase demonstration. The Heap Estimator tool shows that if caching is enabled for the label’s background, this widget requires 23699 bytes of heap to store the widget. Note that the label is twice the size of the text it contains, so one way of reducing the cost of the widget is to make it smaller, thereby reducing the number of background pixels that must be stored. If the label is resized, the heap allocation is reduced to 11688 bytes, which is a drop of appoximately 50%. Finally, if the background is changed from “Cache” to “Fill” the widget only needs 188 bytes. The lesson learned is to use Cache as a background only for widgets where it is absolutely necessary and to make the “cached” widgets as small as possible. Global Palette Provides information on the Global Palette features. Description The Global Palette window is launched from the Graphics Composer’s Asset pull-down menu. Using a Global Palette enables frame buffer compression for the LCC graphics controller. It creates a 256 color look up table (LUT) and then changes the entire user interface design to adhere to that LUT. Frame buffers are stored as 8 bits/pixel (bpp) indices rather than 16-32 bpp colors. The display driver performs a LUT operation to change each LUT index into a color before writing to the display/controller memory. This enables the use of double buffering, without using external memory, on devices that could not support it before. It also supports single buffering on larger displays. Of course, running the LUT requires more processing on the host. Currently only the LCC graphics controller supports this feature. The Aria demonstration Aria Basic Motion is an example of how using a Global Palette greatly improves the efficiency and capabilities of a design. Enable the Global Palette by clicking on the Enable Global Palette check box in the window or using the File > Settings menu. the Global palette can always be disabled. MHGC will then restore the project back to its original configuration. If the global palette is enabled you will have to change the MHC configuration of the Graphics Controller to match. For the LCC controller, enable Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 78 "Palette Mode". For the GLCD controller, change the Driver Settings > Fame Buffer Color Mode to "LUT8". The results of enabling the Global Palette: • 8bpp frame buffers. In the case of the most common demonstrations this means a 50% reduction in the size of the frame buffer. • This also opens up the capability to support a single frame buffer for some larger displays. What is lost by enabling the Global Palette: • First and foremost - No Dynamic Colors. Dynamic colors are unlikely to match up with an entry in the global palette’s look-up table. • No alpha blending capability. The level of alpha blending can be changed during run-time. (See No Dynamic Colors.) • No JPEGs or PNGs. Again, no dynamic colors. All images in MGHC will be changed to the color mode of the project, and generated as Raw. • No font anti-aliasing. Again, no dynamic colors. While the 8-bits/pixel for each glyph is known, the color of the text depends on the color scheme used, and color schemes can change at run time. • Additional overhead when performing LUT (index->color) operations in the display driver. The following figure shows the default “Global Palette” when Project Color Mode is set to RGB_888. This default palette is good for designs that use a wide array of colors. MHGC also supports developing a custom palette by importing an image defining the palette or by analyzing the pixel colors already in use by the application’s images. The palette’s color mode is determined by the Project Color Mode, which is determined by the graphics controller. Clicking on an entry in the palette with bring up the Color Picker dialog window, allowing you to edit the entry’s color. Window Toolbar There are four icons on the toolbar: 1. Import From Image File - Importing a global palette from an image file. Selecting this brings up the following warning. Images can be imported as a BMP,.GIF, JPEG, and PNG (but not TIFF). 2. Auto-Calculate Palette – Calculates a new palette using the current design. Selecting this brings up the following warning. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 79 • Selecting Yes opens a status window that shows the progress made in selecting a palette of 256 colors • This can be lengthy operation, but it will effectively generate a palette better tailored to the design. However, extreme (or rare) colors will be changed to nearby, more-plentiful colors, thereby eliminating some of the contrast in images. Whites will tend to darken and blacks lighten. This can be remedied by editing the calculated palette to whiten the whites, darken the blacks, and make other colors closer to the original. This of course may increase the posterization of the image, but that is a natural trade-off in using only 256 colors. 3. Reset to Default – This returns the Global Palette to its default values, which opens the Reset Global Palette dialog. 4. Enable Global Palette – This performs the same function as File > Settings: Using a Global Palette. Selecting this opens the Enable Global Palette Mode warning. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 80 Widget Colors Provides information on widget coloring. Description Widget Colors Widget coloring can be customized by creating additional color schemes and assigning these customized schemes to a subset of the widgets uses. For example, a ButtonColorScheme could be customized and used only for Button Widgets. To help highlight the different colors available for each widget, a “CrazyScheme”, with extreme contrast among the 16 available colors, was used as the color scheme for each widget: Use this color scheme to help identify the relevant colors for the widgets listed below. The left column shows the coloring assignments for a Bezel boarder. The right side shows Line/No Border color assignments. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 81 Widget With Bezel Border Widget With Line or No Borders Arc Widget: Bar Graph: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 82 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 83 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 84 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 85 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 86 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 87 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Graphics Composer Window User Interface © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 88 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Code Generation © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 89 Code Generation This topic describes using the graphics composer to generate code. Description MPLAB Harmony Graphics Composer data is generated the same way as the rest of the project within MHC through the Generate button. libaria_harmony.h/c – These files provide the interface that binds libaria to the overall MPLAB Harmony framework. They contain the implementations for the standard state management, variable storage, and initialization and tasks functions. If the touch functionality is enabled then the touch bindings are also generated in libaria_harmony.c. libaria_init.h/c - These files contain the main initialization functions for the library state and screens. The header file contains all predefined information for the library state including screen IDs, schemes, and widget pointers. The main initialization function initializes all schemes and screens, creates all screen objects, and sets the initial state of the library context. As each screen must be capable of being created at any time, each screen has a unique create function that can be called at any time by the library. The libaria_init.c file contains these create functions. libaria_events.h/c – The event files contain the definitions and implementations of all enabled MHGC events. Each event implementation will contain all generated actions for that event. libaria_macros.h/c – The macro files contain the definitions and implementations of all defined MHGC screen macros. A macro is similar to an event in that it can contain actions. However, it is meant to be called from an external source such as the main application. libaria_config.h – This file contains configuration values for the library. These are controlled through settings defined in the MHC settings tree. gfx_display_def.c – This file contains generated definitions for enabled graphics displays. gfx_driver_def.c – This file contains generated definitions for enabled graphics drivers. gfx_processor_def.c – This file contains generated definitions for enabled graphics processors. gfx_assets.h/c – These files contain generated asset data. Advanced Topics This section provides advanced information topics for MHGC. Adding Third-Party Graphics Products Using the Hardware Abstsraction Layer (HAL) This topic provides information on using the Hardware Abstraction Layer (HAL) to add third-party graphics products. Description The architecture of the MPLAB Harmony Graphics Stack is shown in the following diagram. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 90 Hardware Abstraction Layer (HAL) The HAL is a software layer that serves as a gatekeeper for all graphics controller and accelerator drivers. This layer is configured at initialization by the underlying graphics drivers and provides functionality such as buffer management, primitive shape drawing, hardware abstraction, and draw state management. This layer serves as a means of protection for the drivers, frame buffers, and draw state in order to prevent state mismanagement by the application. Third-Party Graphics Library The third-party graphics library can be used with the MPLAB Harmony framework to perform the graphics operations desired by the application. The third-party library has access to the HAL, which has been configured to service the frame buffer which is filled by the third-party graphics library. The third-party graphics library can access the MPLAB Harmony framework drivers such as touch drivers, graphics controller driver, and display driver through the HAL. The draw pipeline and the user interface (UI) design files come from the third-party graphics library. The third-party graphics library needs the frame buffer location to fill the frame buffer with the pixel values. Or, in case of external controllers, it would need a function to access the controller drivers to output pixels on the display. The HAL provides the third-party graphics library with the frame buffer location or the API to communicate the pixel values to the external controllers. The following figure from the MPLAB Harmony Configurator (MHC), shows the selections made in the Graphics Stack to enable the needed graphics display and controller features. Note that the Draw Pipeline for the MPLAB Harmony Graphics Stack has been disabled to assure that the third-party graphics alone is taking effect. The MPLAB Harmony Graphics Configurator (MHGC) is also not enabled, as the design tools from the third-party graphics library are used to generate the UI graphics. The LCDConf.c file has appropriate APIs for the third-party graphics library to communicate through the HAL with the display drivers and the framebuffer. Example Demonstration Project The Aria demonstration project, emwin_quickstart, has three configurations. Each configuration has an API named LCD_X_Config, which is Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 91 generated with the relevant calls for SEGGER emWin to communicate with the display driver and obtain the frame buffer location pointer to write the pixel data to it. For PIC32MZ DA and PIC32MZ EF configurations, the frame buffer pointer address is provided to SEGGER emWin by the HAL. For the S1D controller on PIC32MX devices (pic32mx_usb_sk2_s1d_pictail_wqvga), The pixel write function pointers are assigned to the appropriate S1D driver APIs, which allow SEGGER emWin to write to the display controller. Speed and Performance of Different Image Decode Formats in MHGC Provides information and recommendations for image decode formats. Description MHGC supports various image formats and the MHGC Image Assets Manager provides the ability to convert and store a source image into to the following formats • Bitmap RAW • Bitmap Raw Run-Length Encoded (RLE) • JPEG • PNG • Predecoded RAW Bitmap in DDR (PIC32MZ DA) The following table shows the relative rendering time and Flash memory requirements of the different image formats in the MPLAB Harmony Graphics Library. The rendering time includes decoding the image and drawing it to the screen. This information is helpful when optimizing a MPLAB Harmony graphics project for performance and/or Flash memory space. For example, as shown by the red highlighted text in the table, a 40x40 pixel 16-bit RAW image renders 2.38 times faster and uses 2.59 times more Flash space than a JPEG image. Predecoded Images in DDR (RAW) For PIC32MZ DA devices with DDR, the MHGC Image Asset Manager provides an option to predecode images from Flash and store them into DDR as RAW images. The GPU is used to render the decoded image from DDR to the frame buffer. This provides a faster render time than an equivalent RAW image in Flash memory, specifically for large images (up to 10 times faster for a 200x200 image). Conversely, predecoding small images 40x40 pixels or smaller in DDR may not render faster due to the additional overhead of setting up the GPU. Recommendations: • If there is adequate DDR memory available, consider predecoding images to DDR for best performance • Using JPEG images and predecoding them into DDR can provide the best rendering performance and most Flash memory savings. Note: The images are decoded from Flash to DDR memory by the Graphics Library during initialization and may introduce delay at boot-up, depending on the number and size of the images. RAW Images RAW images provide fast rendering time, as there is no decoding needed. However, depending on image content, it can be two times larger than a Run-Length Encoded (RLE) image and about 3 to 10 times larger than a JPEG. Recommendation: For small images that are to be rendered frequently, consider using a RAW image for better performance JPEG Images JPEG images provide the most Flash space savings, but are slower to render compared to RAW and RAW RLE. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 92 Recommendations: • If images are large and not used frequently, consider using the JPEG image format to save flash memory space • If DDR memory is available, consider predecoding JPEG images in DDR for better rendering performance Run-Length Encoded RAW Images In terms of rendering speed and size, RAW RLE images are in between RAW and other compressed formats like JPEG or PNG. Depending on the image contents, RAW RLE can be approximately 1.5 times faster than JPEG, but could be significantly larger in size for large images. Again, depending on the image content, RAW RLE can be about half the size and performance of a RAW image. Recommendation: If optimizing your application for both speed and flash size consider using RAW RLE images PNG Images Among the image formats, PNG is slowest to render and requires more memory to decode. Recommendations: • Unless fine levels of alpha-blending are needed, it is better to use other image formats to achieve the best performance. Use the MHGC Asset Manager to convert the source PNG image and store it in a different image format. • If you would like to use an image with a transparent background, it may be better to use a RAW RLE image with background color masking to achieve the same effect with better performance than a PNG. Color masking is supported in the MHGC Image Asset Manager. Draw Pipeline Options This section details how to use the Graphics Pipeline. Description The nominal rendering pipeline for an image is shown in the following figure. The order of rendering for other widgets may differ. For example, for a colored rectangle the color mask is first checked. If the rectangle’s fill matches the mask color defined then there is nothing to draw. Graphics Pipeline Provides information on the graphics pipeline. Description Layer Clipping In order of the processing, Layer Clipping is first applied to the image. If the image extends beyond the edges of the layer that contains it then those pixels are not drawn. Failure to clip out-of-bound pixels can cause the application to crash. The following figures shows an example of layer clipping: Before applying layer boundaries: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 93 After applying layer boundaries: Rectangle Clipping Next, the image is clipped to the boundaries of any widgets that contain it as a parent, such as a rectangle. Before applying the clipping rectangle.: After applying the clipping rectangle: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 94 Color Masking of Pixels Pixels in the image are matched to a mask color. If the colors match the pixel is discarded (not drawn). In the following example, the black border of the image is removed by defining the mask color to be black. Before applying color mask: After applying color mask: Orientation and Mirroring The logical orientation of the graphics design may not match the physical layout of the display. Pixels may need to be reoriented from logical to physical space before being rendered. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 95 Pixels may also need to be flipped (mirrored) before being rendered. Alpha Blending Each pixel drawn is a composite of the image color and the background color based on the alpha blend value defined by a global alpha value, the pixels alpha value, or both. Before alpha blending: After alpha blending: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 96 Color Conversion The image color format may not be the same as the destination frame buffer. Each pixel must be converted before it is written. In the following example, the image is stored using 24 bits per pixel; however, the frame buffer uses 16 bits per pixel. Frame Buffer Write The final stage in rendering an image is to write each-color converted pixel to the frame buffer. Graphics Pipeline Options Provides information graphics pipeline options. Description Each stage in the graphics pipeline adds overhead to the rendering. Stages can be removed from processing using MPLAB Harmony Configurator (MHC) options for the Draw Pipeline, found by selecting MPLAB Harmony Framework Configuration > Graphics Stack. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 97 For example, the Alpha Blending stage can be disabled if your graphics application does not use alpha blending. If the color mode of the display matches the color mode of all images you can disable Color Conversion. Disabling unneeded stages can improve performance and reduce code size. Also, a graphics controller driver may add additional stages, or opt to bypass stages completely depending on the capabilities of the graphics hardware supported by the driver. Improved Touch Performance with Phantom Buttons This topic provides information on the use of phantom buttons to improve touch performance. aria_coffeemaker Demonstration Example Provides image examples with buttons in the aria_coffeemaker demonstration. Description Small buttons are hard to activate on the screen. The use of phantom (invisible) buttons can improve touch performance without increasing the size of the visible footprint of the button on the display. The aria_coffee_maker has a sliding tray on each side of the display. Sliding a tray in, or out, is accomplished by a phantom (invisible) button. Looking at the left tray, we see the three parts of this phantom button. 1. LeftTrayLid: An invisible button widget, whose outline is shown in blue. This area is the touch field. 2. ImageWidget5: An image widget containing a hand icon, providing a visual clue as to how to manipulate the tray. 3. The Release Image and Pressed Image: These are defined as part of the button widget properties. The Pressed Image has a darker coloring than the Released Image. This difference is what shows the user that the button has been pressed. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 98 The drawing hierarchy for this part of the design is shows that ImageWidget5 is a daughter widget to the LeftTrayLid button widget. Examining the properties of the LeftTrayLid button widget reveals more about how this works. The following figure demonstrates these three properties. 1. The Border is defined as None. 2. Background Type is defined as None. 3. The different images used will show when the button is Pressed or Released. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 99 By setting the border and background to None, the button is invisible. Only by providing different images for Released versus Pressed does the user know when the button has been pressed. The actual touch region defined by the button is much larger than the images shown on the display. This extra area increases the touch response of the display. Small Buttons Controlled by Phantom Buttons Provides information on phantom button control of small buttons. Description When the border is not set to None, and the background is not set to None, the button widget provides a direct visible clue to the user when it is pressed. Which can be seen in the following figure with the button from aria_quickstart. In aria_quickstart, ButtonWidget1 has a bevel border, and a fill background. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 100 Let’s use aria_quickstart to demonstrate how to control ButtonWidget1 using a phantom button to surround it, thereby increasing touch responsiveness. When using a bevel border and filled background, the button provides visible feedback when it is asserted. To use this feedback mechanism instead of images, there is a way to have a small button on the display, with a larger touch zone provided by another phantom button. Steps: 1. Click on ButtonWidget1 in the Screen Designer panel. Go to the Properties Editor panel for the widget and uncheck the Enabled property to disable the button. Enable Toggleable so that this button will have a memory. 2. Drag a new button from the Widget Tool Box panel and center it around ButtonWidget1. In the Properties Editor panel for this new button, change the name of the widget to PhantomButton. Change the Background Type to None. Leave the Border set as Bevel for now. The following figure displays the new button in the Screen Designer panel: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 101 The Properties Editor panel should display the following information. 3. In the Tree View panel, drag ButtonWidget1 to be a daughter widget of PhantomWidget. When PhantomWidget is moved, ButtonWidget1 will move along with the parent. 4. Click on PhantomButton again in the Screen Designer panel and move to the Properties Editor. Enable both the Pressed and Released events. Then click on the (…) icon to define the events. (See the following two steps.) 5. Defining the Pressed Event. Click on the (…) icon. In the Event Editor, under Pressed dialog, click the New icon to define a new event. In the Action Edit Dialog that next appears, leave the selection on the template and hit the Next button. In the next window, select the target of the event. We want to change the state of ButtonWidget1, so select it and hit Next. The next dialog shows all the template actions that we can use to modify ButtonWidget1. Choose Set Pressed State and hit Next. Set the Argument to Enable Pressed. Name this event Set Press state for ButtonWidget1 then hit Finish. Leave the Event Editor by hitting Ok. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 102 6. Defining the Released Event. Click on the (…) icon. In the Event Editor, under Released dialog, click the New icon to define a new event. In the Action Edit Dialog that next appears, leave the selection on the template and hit the Next button. In the next window, select the target of the event. We want to change the state of ButtonWidget1, so select it and hit Next. Choose Set Pressed State and hit Next. Leave the Argument disabled. Name this event Unset Press state for ButtonWidget1 then hit Finish. Leave the Event Editor by hitting Ok. 7. Generate the application from the MPLAB Harmony Configurator main menu. 8. From the MPLAB main menu, build and run the project. To verify that ButtonWidget1 does change, click outside of the original boundaries. 9. As a final step, hide the PhantomButton by changing its border to None. Next, Generate the code again from MHC. Finally, build and run the project from MPLAB and see how much easier it is to assert ButtonWidget1 using a phantom button. GPU Hardware Accelerated Features This section details how to configure the GPU hardware accelerated features. Description On the PIC32MZ DA devices, the on-board 2D Graphics Processing Unit (GPU) peripheral allows certain features to be accelerated. These features are: • Line draw • Single-color rectangle fill • Image Blit Once configured, these features are supported by the Hardware Abstraction Layer (HAL) and can be enabled or disabled at run-time. When disabled, the HAL falls back to the software-based algorithms, and relies on the CPU to perform the features. Configuring for GPU Hardware Acceleration The Nano2D library, is the driver library that permits hardware acceleration via the GPU. To make sure the Nano2D library is configured as part of your application, make sure to enable this in the MPLAB Harmony Configurator (MHC) under Graphics Stack > Use Graphics Stack > Graphics Processor > Select Processor Type > NANO 2D. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 103 Enabling/Disabling GPU Hardware Acceleration at Runtime Once configured, the hardware acceleration via the GPU is enabled by default at launch. The hardware acceleration can subsequently be turned on or off at runtime by calling the following lines of code: Enable acceleration: GFX_Set(GFXF_DRAW_PIPELINE_MODE, GFX_PIPELINE_GCUGPU); Disable acceleration: GFX_Set(GFXF_DRAW_PIPELINE_MODE, GFX_PIPELINE_GCU); This change takes effect immediately for subsequent draw instructions into HAL. Line Draw and Rectangle Fill Hardware Acceleration When the GPU hardware acceleration is enabled, line draw and rectangle fill features are automatically supported. This is supported by HAL function calls GFX_DrawLine and GFX_RectFill. The actual routing of the call between the hardware accelerated support versus the software-based algorithmic support is abstracted from the caller. The following table displays performance improvement by comparing the frame update rate of rectangular fills of varying sizes with, and without hardware acceleration. The table shows that the higher the frame update rate, the better the performance. The measurement is performed using the entire Harmony Graphics Stack but with most Aria draw pipeline features disabled, so that the focus is on HAL performance. Rect Fill Size No Acceleration Frame Update Frequency (Hz) Hardware accelerated Frame Update Frequency (Hz) Performance Improvement 60x60 101 160 58.4% 100x100 37 158 327.0% 140x140 19 157 726.3% 180x180 11 156 1318.2% 220x220 8 155 1837.5% Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 104 Note: The HAL uses a software algorithm for rectangle fill sizes below 50x50, as the CPU is able to perform the operation faster than the GPU below that size. Image Blit Hardware Acceleration The only way Image Blits significantly leverage hardware acceleration is via the block transfer of image data that has been preprocessed into DDR/Internal SRAM memory into frame buffer memory. Note: The GPU is able to interpret and transfer pixel data in RGB565 or RGBA8888 format only. The following table displays performance improvement by comparing the frame update rate of the image blit of the same 100x100 image in varying formats with, and without GPU acceleration. The table shows that the higher the frame update rate, the better the performance. There is a marked performance increase when using the preprocessing method (despite the amount of image data is doubled in RGBA8888 versus RGB565). Image Format (100x100) No Acceleration Frame Update Frequency (Hz) GPU Frame Update Frequency (Hz) Performance Improvement RGB565 raw pixels 37 60 62.1% RGB565 with RLE compression 26 34 30.8% JPEG (24-bit) 17 22 29.4% PNG (32-bit) 13 15 15.4% Preprocessed RGBA8888 raw pixels 29 161 455.2% The GPU works best with image sizes in powers of two (such as 128x128 instead of 125x105). Images with sizes that are not a power of two may be rendered with artifacts. This is often a case-by-case situation and the way to remedy this is to pad the memory footprint up to the nearest power of two. Prior to application use, images stored in flash storage will need to be preprocessed, converting them from the original format into a raw bitmap. There are two methods to achieve this: 1. Calling from application code: The API GFXU_Preprocess Image can be used to preprocess an image asset to a target memory location (DDR or internal SRAM) while specifying the destination color mode (RGB565 or RGBA8888). The application developer will need to manage the target memory and be careful not to stomp on other critical memory structures such as the frame buffer, or the GPU’s command buffer. Power of two padding can be enabled via the API. 2. The application developer can also use the Image Assets options within the MPLAB Harmony Graphics Composer User's Guide (MHGC) to specify that certain image assets should be preprocessed at application launch. This can be achieved by enabling image preprocessing as shown under the Preprocessing sub-section of the Image Asset window as shown in the following figure: For more information, see Image Assets and DDR Organizer under the Graphics Composer Asset Management section above. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 105 Image Preprocessing Memory Management This sections describes preprocessing. Description Whether using internal SRAM only or DDR memory, care must be taken when allocating memory for preprocessing images. For more information, see Image Assets and DDR Organizer under the Graphics Composer Asset Management section above. Preprocessing using DDR For PIC32MZ DA devices with access to DDR memory, the frame buffer and the command buffer for the GPU is also located on the DDR. It is important for the application developer to select the appropriate memory location in DDR for image preprocessing without trampling on these other memory structures. The following table specifies the available addressing region to access the DDR memory. Device Type Address Range Begin (KSEG1) Address Range End (KSEG1) Internal DDR (maximum size 32 MB) 0xA8000000 0xA9FFFFFF External DDR (maximum size 128 MB) 0xA8000000 0xAFFFFFFF At configuration time, MHGC generates the frame buffer allocation in the application’s system configuration code. This allocation is targeting a WVGA RGBA8888 3-overlay double-buffered configuration; therefore, six buffer allocations are specified. More DDR memory can be freed up for image preprocessing using the following: • WVGA Resolution is not required • Enable all three overlays • Double frame buffering The application developer may choose to change the allocation manually in system_config.h. The following table breaks down the allocation: Frame Buffer Address Range Begin Address Range End Layer0 Buffer 0 0xA8000000 0xA8176FFF Layer0 Buffer 1 0xA8465000 0xA85DBFFF Layer1 Buffer 0 0xA8177000 0xA82EDFFF Layer1 Buffer 1 0xA85DC000 0xA8752FFF Layer2 Buffer0 0xA82EE000 0xA8464FFF Layer2 Buffer1 0xA8753000 0xA88CBFFF For an example on using image preprocessing using DDR memory, please refer to the aria_coffee_maker application. Internal SRAM Only When operating with only the internal SRAM, the frame buffer can take up a significant portion of available memory. To avoid system stability issues with dynamically allocating memory for the preprocessing, the application developer may want to predetermine the memory footprint required for the image and assign the memory statically. For an example of image preprocessing using internal SRAM, please refer to the aria_radial_menu application. Creating a MPLAB Harmony Graphics Application Using a Third-Party Display This demonstration provides a step-by-step example of how to create a MPLAB Harmony graphics application using a non-Microchip (third-party) display. Description Introduction Creating a new MPLAB Harmony graphics application using a Microchip board and a Microchip display is very simple: A new MPLAB Harmony application is created and the Board Support Package (BSP) belonging to the hardware configuration is selected. If the project is using a third-party display then there are more steps and this tutorial will provide an example of the process. This tutorial shows how to connect a third-party display to the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit board (EF Starter Kit) using two Microchip Adapter boards and a custom ribbon cable. It shows how to setup the pinouts, configure graphics, and adapt an existing MPLAB Harmony capacitive touch driver to support the display board’s capacitive touch controller. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 106 Prerequisites Before beginning this tutorial, ensure that the MPLAB X IDE is installed along with the necessary language tools as described in Volume I: Getting Started With MPLAB Harmony > Prerequisites. In addition, ensure that MPLAB Harmony is installed on the hard drive, and that the correct MPLAB Harmony Configurator (MHC) plug-in is installed in the MPLAB X IDE. A basic familiarity with application development under MPLAB X and MPLAB Harmony is required, including how to use MPLAB Harmony Configurator (MHC). There are introductory videos on Microchip’s YouTube channel for those who have never used MPLAB Harmony. The first video to watch is Getting Started with MPLAB Harmony. There is also a Creating Your First Project tutorial in Volume 1 of MPLAB Harmony’s documentation. For first time users of MPLAB Harmony Graphics there is a video series on YouTube. The first video is MM MPLAB® Harmony Edition - Ep. 7 - MPLAB Harmony Graphics Composer Suite. In Volume 1 of MPLAB Harmony’s documentation there are Quick Start tutorials covering graphics, located at Quick Start Guides > Graphics and Touch Quick Start Guides. Tutorial Resources The folder ./apps/examples in MPLAB Harmony has a project that can be copied and used as the base of this tutorial, 3rd_party_display_start, and a project that represents the completed project from this tutorial, 3rd_party_display. This is what you will find in the ./apps/examples folder under Harmony 2.06: 3rd_party_display 3rd_party_display_start creating_your_first_project peripheral events_testbed system If there are difficulties then compare the completed project with the current project. Tutorial Hardware Of all the PIC32MZ devices available today, the PIC32MZ EF family is the best candidate for this effort. The EF family does not have on-chip graphics controller or Graphics Processing Unit (GPU), which makes it a less expensive and lower power solution for use with a display that has a built-in controller. Mikroelektronika (Mikroe) offers a prototype display that can be used using a ribbon cable between the display and the EF host. This third party (non-Microchip) board serves as the basis for this tutorial. The ‘TFT PROTO 5" Capacitive’ display costs around 100USD and is available for order online (https://www.mikroe.com/tft-proto-5-capacitive-board). It has an 800x480 pixel WVGA display, driven by an SSD1963 graphics controller. The SSD1963 graphics controller is already supported in MPLAB Harmony. It has a Focal Tech FT5x06 capacitive touch controller. This tutorial will cover how to design the pin-out between the EF host and display board, as well as how to adapt an existing MPLAB Harmony capacitive touch driver (MTCH6303) to support the Focal Tech touch controller. For this tutorial the following hardware will be used: 1. PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit board (Part # DM320007). 2. Starter Kit I/O Expansion Board (Part # DM320002) – this provides the 0.1” headers we need to connect up the display using a ribbon cable or 0.1" jumpers. 3. PIC32MZ Starter Kit Adaptor Board (Part # AC320006) – this provides an 168 to 132 pin adapter to adapt the 168-pin connector on the EF starter kit with the 132 pin connector on the I/O Expansion Board. 4. Mikroelektronika TFT PROTO 5" Capacitive display. 5. 40 to 50 pin ribbon cable to connect the I/O Expansion Board to the display, or a set of colored 0.1" jumpers. Here is how the hardware is assembled: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 107 The connectors that route signals from the EF pins to the display’s ribbon cable are: The EF Starter Kit + 168-132 Pin Adapter + I/0 Expansion board can host any number of prototype hardware configurations. A spreadsheet has been developed that maps every pin of the EF device to a pin on the I/O Expansion board, with one final spreadsheet tab that provides the pin outs for the ribbon cable that connects the display to the I/O Expansion Board. (The spreadsheet is found in the Zip file .\apps\examples\3rd_party_display\pinouts.zip.) The picture above shows the board connectors used in getting from a pin on the EF device to a pin on the display’s ribbon connector. This spreadsheet has the following tabs: 1. Sorted by Skit J1 Pins – This tab maps EF pins to pins on the J1 (168 pin) connector on the 168-132 pin adapter. It also maps the 168-pin J1 connecter to the J2 132-pin connecter. Pins are sorted by the pin order on the Starter Kit 168-pin J1 connector. 2. Sorted by Device Pins – A copy of the first tab, sorted by EF device pins. 3. Sorted by Adaptor J2 Pins – A copy of the first tab, sorted by the pins on the J2 132-pin adaptor. 4. PIC32 IO Expansion Pin Out – Provides the pin out of the I/O Expansion Board from the 132-pin J1 connector to the 0.1” pitch headers on the board (J10,J11). 5. End to End – maps the EF device pins to the 0.1” pitch headers on the I/O Expansion Board. This tab can be reused to map out other application pin outs. 6. Mikroe Display – Provides the pin outs for the 40-pin ribbon cable connector (CN3) on the display board. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 108 7. End to End by Device Pins – This tab combines Tab 4 with Tab 6. It shows how to build a ribbon cable between the I/O Expansion Board and the display. On this tab the rows belonging to EF device pins that aren’t part of the ribbon cable are hidden for the sake of simplicity. Tab 7 of the spreadsheet shows: The ribbon cable for this project is constructed using the map from J10 Pin#/J11 Pin # to the TFT Proto 5” Pin #. For example, the first line of the Tab 7 shows that pin 7 of the J10 header on the I/O expansion board is connected to pin 18 of the display connector, thereby connecting PMPD5 (PMP data pin 5) on the device to TFT-D5 on the display. Note: display pins with a “#” suffix indicate that the signal is active low (# = bar). TFT-Dn display pins are part of the SSD1963 display controller’s Parallel Master Port (PMP) interface. Other TFT-* pins are part of the controller to host interface. For example, TFT-WR# is connected to the controller’s WRbar (write strobe bar) pin, which is called WR_STROBE_BAR in the MPLAB Harmony Graphical Pin Manager. (Setting up the project’s pins using the Pin Manager is discussed later in the tutorial.) On the display connector FT5x06 capacitive touch controller pins are called CTP-*. There is an I2C clock pin (CTP-SCL), I2C data pin (CTP-SDA), an interrupt pin to alert the host of a touch event (CTP-INT#), and reset/wakeup pins (CTP-RST#/CTP-WAKE#). Creating the Project in MPLAB and MPLAB Harmony Getting Started The pre-installed project, 3rd_party_display_start can be used as a basis for the work discussed in this tutorial. Be sure to copy this project to a place in the MPLAB Harmony directory hierarchy that is just as deep. If this is not done, all the relative paths in the project’s configuration will no longer find the project’s files and nothing will build. For example, copying 3rd_party_display_start into a directory .\apps\3rd_party_display will not work, since the target directory is one level higher in MPLAB Harmony’s directory hierarchy. The directory .\apps\gfx\3rd_party_display will work since it is at the same level in the hierarchy. There is an extra file in the .\apps\examples\3rd_party_display_start file (xc32_vm.nn_pic32mx_include_assert.h) , which provides the modification to the compiler’s assert.h as discussed in Volume 1 of MPLAB Harmony’s documentation (Creating Your First Project). This modification supports producing breakpoints under the debugger when an assert fails, which can be very useful in debugging the code. Simply use this file to replace ./xc32/vm.nn/pic32mx/include/assert.h,where m.nn represents the version number of the compiler you are using. For first time users of the PIC32MZ product line and MPLAB Harmony should create the starting the project from scratch. Follow the instructions in “Creating Your First Project”, which is found in Volume 1: Getting Started With MPLAB Harmony Libraries and Applications. Call the new project 3rdPartyDisplay instead of Heartbeat. In Part 1, Step 3 of the Creating Your First Project, use a different application name than “heartbeat." For example accept the default “app”, then replace “heartbeat” with the new application name in the tutorial code examples. If the default application name “app” is used then “heartbeat” is replaced by “app” in the code examples. The header file heartbeat.h would be named app.h instead and it should contain: typedef enum { /* Application's state machine's initial state. */ APP_STATE_INIT=0, APP_STATE_SERVICE_TASKS, /* TODO: Define states used by the application state machine. */ APP_RESTART_TIMER } APP_STATES; Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 109 Here the enum is called APP_STATES instead of HEARTBEAT_STATES and the state APP_RESTART_TIMER replaces the state HEARTBEAT_RESTART_TIMER. The structure HEARTBEAT_DATA is now called APP_DATA: typedef struct { /* The application's current state */ APP_STATES state; /* TODO: Define any additional data used by the application. */ SYS_TMR_HANDLE hDelayTimer; // Handle for delay timer } APP_DATA; The same principle applies to app.c (instead of heartbeat.c in the tutorial). The structure heartbeatData is now called appData. The source file app.c should contain: { /* Check the application's current state. */ switch ( appData.state ) { /* Application's initial state. */ case APP_STATE_INIT: { bool appInitialized = true; if (appInitialized) { appData.hDelayTimer = SYS_TMR_DelayMS(HEARTBEAT_DELAY); if (appData.hDelayTimer != SYS_TMR_HANDLE_INVALID) { // Valid handle returned BSP_LEDOn(HEARTBEAT_LED); appData.state = APP_STATE_SERVICE_TASKS; } appData.state = APP_STATE_SERVICE_TASKS; } break; } case APP_STATE_SERVICE_TASKS: { if (SYS_TMR_DelayStatusGet(appData.hDelayTimer)) { // Single shot timer has now timed out. BSP_LEDToggle(HEARTBEAT_LED); appData.state = APP_RESTART_TIMER; } break; } /* TODO: implement your application state machine.*/ case APP_RESTART_TIMER: { // Create a new timer appData.hDelayTimer = SYS_TMR_DelayMS(HEARTBEAT_DELAY); if (appData.hDelayTimer != SYS_TMR_HANDLE_INVALID) { // Valid handle returned appData.state = APP_STATE_SERVICE_TASKS; } Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 110 break; } /* The default state should never be executed. */ default: { /* TODO: Handle error in application's state machine. */ break; } } } At the end of the Creating Your First Project tutorial, the project supports a HyperTerminal console on a PC, which can be used to display diagnostic messages. The project will also support the advanced error handling (asserts and exceptions) that MPLAB Harmony provides. When running this application, verify that the HyperTerminal application (115200 baud, 8 bits, no stop bits) sees an initialization message of, Application created Mar 1 2018 15:09:50 initialized! at startup, where the date and time report when the app.c file was last compiled. This message originates in the application initialization function: void APP_Initialize ( void ) { SYS_MESSAGE("\r\nApplication created " __DATE__ " " __TIME__ " initialized!\r\n"); //Test out error handling // assert(0); // { // uint8_t x, y, z; // x = 1; // y = 0; // z = x/y; // SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"x: %d, y: %d, z: %d\r\n",x,y,z); // } /* Place the App state machine in its initial state. */ appData.state = APP_STATE_INIT; /* TODO: Initialize your application's state machine and other * parameters. */ } Verify that asserts and exception handling work before proceeding. Uncomment the assert and test. Then comment out the assert and uncomment the {…} clause to test out exceptions. Note: If this is the first time hooking up a HyperTerminal session to the EF Starter Kit using the MCP2221, see Part 3 of the Creating Your First Project tutorial in Volume 1 of MPLAB Harmony’s documentation. This part of the tutorial shows how to hookup the EF Starter Kit to your PC. It also discusses in Steps 11 and 12 how to setup your HyperTerminal application. Setting Up Pins using the MPLAB Harmony Graphical Pin Manager Since a pre-defined Board Support Package is not available, pin assignments will have to be manually entered into the Pin Manger using the “Pin Settings” tab. Load the startup project, either from a copy made from .\apps\examples\3rd_party_display_start or one created from scratch. Then run MPLAB Harmony Configurator: From MPLAB Harmony Configurator, select the Pin Settings tab: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 111 Make these modifications to the pin table: The pins labeled USART to USB Bridge (BSP) support the MCP2221 USART to USB device on the EF Starter Kit board. It provides a HyperTerminal interface on the PC. This is setup in the 3rd_party_diaplay_start project. Be sure the touch interrupt event interrupt (pin 104, CTP_INT_BAR) pin is pulled high (CNPU enabled), otherwise touch event interrupts will never fire: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 112 Setting up Graphics In MPLAB Harmony Configurator, under the Options tab: open Harmony Framework Configuration > Graphics Stack and enable the Graphics Stack with the following settings. First select a “Custom Display” as the display type. Then enter the dimensions of the Mikroe display (800x480). Note: The display can be set in MHC’s Display Manager. Enable the Graphics Stack using the MHC’s Options tab, it is easier to do the basic display setup here. Later the Display Manager will be used to tune the display’s timing (syncs plus front porches and back porches) so that all 800x480 pixels are correctly displayed. For now, accept the default display timings.The equivalent setup using the Display Manager is: The Mikroe display uses a SSD1963 graphics controller to run the TFT display, which is supported in MPLAB Harmony. This graphics controller is connected to the EF host using the Parallel Master Port (PMP), I2C, and GPIO peripherals. (For details, see the Setting Up Pins using the MPLAB Harmony Graphical Pin Manager section above.) Under Graphics Stack > Graphics Controller, select the SSD1963 graphics controller, enable the controller’s backlight PWM. Change the pixel clock from the default to 30 MHz and click “Execute” to compute the Pixel Clock Prescaler value. Finally, since the system clock for the EF host runs at 200 MHz, add an additional NOP for correct Write Strobe timing. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 113 Finally, verify Use Touch System Service? (Deprecated) is enabled: When finished, re-generate the code to capture these new settings using the Generate Code button in MPLAB Harmony Configurator. Be sure to use the Prompt Merge For All Differences merge strategy to maintain code customizations installed outside of MHC. After regenerating the project, you will have to customize the system_init.c file, found in the project under Source Files / app / system_config / , where is typically "default". Move the SYS_PORTS_Initialize call from the middle of SYS_Initialize to between SYS_DEVCON_PerformanceConfig and BSP_Initialize. The Old location: The New location is: Tuning Display Timing Using Display Manager The next step is to tune the timing of the display using the Display Manger to prevent the edges of the screen from being clipped. A rectangle needs to be drawn on the edges of the screen. Then by building and running the application, we can see if any parts of the border rectangle are Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 114 clipped or missing. A different color is needed for each of the four sides of the border rectangle, as in some cases the display controller’s memory pointers can “wrap” a pixel from one side of the display to the opposite side. If all the sides are the same color this would not be apparent. Here is the screen to implement in the Screen Designer panel: Each side of the border will require a custom color scheme. The border is created by drawing four separate lines using four separate line widgets. Examine how line widgets are colored by dragging a line widget from the Widget Toolbox panel onto the Screen Designer panel and then pick the Properties Editor Panel for that widget. Click on the “?” to the right of the Scheme property. This will bring up the “Line Widget Scheme Helper” window: If the Background and Shape of the widget are colored with the same color, different for each side, then the four edges of the display are easily marked. Using the same colors for the line, and the widget’s background, allows the use of the size and position of the line widget rather than the line’s coordinates to mark that edge of the display. To create the display, within MHC, launch the Graphics Composer. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 115 Using the Scheme panel, create four new color schemes. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 116 Next, drag a line widget onto the display four times and edit each widget’s properties to create and position each edge of the display’s border: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 117 Note that the “Line” coordinates are set to [0,0,0,0] since it is the size of the widget rather than the widget’s line that marks each border line. The lines in these widgets are not used. Each widget’s position and size mark an edge of the display, not the line. Re-generate the application and then run it. The HyperTerminal application (115200 baud, 8 bits, no stop bits) should show the following when the application boots up: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 118 Examine the border of the resulting display,note that the top edge of the border is completely missing and the left edge is about half the width desired, compared to the right and bottom edges. To fix this the display timings need to be adjusted using the Display Manager: If this is the first time using the Display Manger, Volume 1 of MPLAB Harmony’s documentation has a Display Manager Quick Start Guide and Volume III has the MPLAB Harmony Display Manager User’s Guide. Increase the Horizonal Pulse Width by two clocks, re-generate, and then run. The left border should be fully visible. Next, tune the Vertical Pulse Width. Gradually increasing it to move the top border line down until it is fully visible. (22 H-syncs seems to be the correct value.) After each adjustment re-generate, build and run, then examine the resulting display. Stop when all borders are fully visible and there are no “dead” (black) pixels on the display. In the Display Manger, the final, optimal, settings for the display are: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 119 When finished, the display should be: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 120 A picture of each edge through a 10x power loupe verifies that each edge is exactly 4 pixels wide and there are no “dead” (black) pixels between the edges of the display and the colored border. The Mikroe board uses a Riverdi RVT50AQTNWC00 display. Table 8.3 of its datasheet covers display timing: Some explanation is required to match up this data with the Display Manager’s settings. Back porch timings are not shown in the table, but can be calculated by subtracting the HS/VS pulse width from the HS/VS Blanking: HS Back Porch = HS Blanking – HS pulse width = Thbp = Thb – Thfp VS Back Porch = VS Blanking – VS pulse width = Tvbp = Tvb – Tvfp The DCLK Frequency typical value of 30 MHz has already been used in setting up the display pixel clock speed. However, using the “Typ” (Typical) values, and the calculated Thbp and Tvbp values from the equations above, the timing will not work. The timing values that work for this tutorial meet the minimum or maximum range shown above with one exception: The “One Horizontal Line” timing, Th, has a minimum of 889 pixel clocks, but the one in use is: Th = Thpw + Thbp + 800 pixels+ Thfp = 44 + 2 +800 + 2 = 848 pixel clocks < 889 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 121 which is 41 pixel clocks (4.6%) below the minimum Th of 889 shown in Table 8.3 above. Results may vary on your display. This was tested on two different boards with the same results. Starting out with the default display timings and then iteratively tuning them to reduce pixel clipping and dead pixels, as discussed above, will provide the optimal display timings for the hardware regardless of the final settings. Supporting the Focal Tech FT5x06 Capacitive Touch Controller Microchip (Atmel) and Focal Tech are key providers of capacitive touch controllers. Focal Tech FT5x06 touch controllers are found on many of the displays used by Microchip customers, so a third-party display with a Focal Tech capacitive touch controller is a good choice for this tutorial. MPLAB Harmony provides these touch controller drivers: The Generic Touch Driver outlines the generic Touch Driver API supported by MPLAB Harmony. It provides a template that can serve as the base for a custom-built driver for the FT5x06 touch controller. A faster way to support the Focal Tech FT5x06 is to find a similar device that is already supported in MPLAB Harmony and simply modify the driver code for that device. This eliminates having to write all the supporting code needed to fit the new driver into MPLAB Harmony. Capacitive touch devices typically have an I2C interface with the host, and an interrupt signal that is driven low to alert the host that a touch event has been detected. In response to this external interrupt the host uses the I2C interface with the device to query the device and read the (x,y) pixel coordinates of the touch event. The FT5x06 command interface is closest to the MTCH6303 interface since it requires a write command followed by a read command to get the touch event. (The MTCH6301 only requires the read message.) The other thing to be aware of is the data order coming from the chip. FT5x06 Memory: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 122 Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 123 Modifying MPLAB Harmony’s MTCH6303 Touch Driver for the Focal Tech FT5x06 The first step towards supporting the FT5x06 is to add a MTCH6303 driver to the application, and then modify the MTCH6303’s code to support the FT5x06. To support the FT5x06, we will add a C preprocessor #if defined(FT_SUPPORT)…#else…#endif clauses to the code and then define FT_SUPPORT in the project’s C compiler properties. To add the MTCH6303 touch driver, make the following changes to the project’s MHC settings: Be sure to increase the event queue depth from the default of 10 to something larger, here it is 25. The controller’s CTP-INT# (CTP_INT_BAR in the Pin Settings table) is connected to INT0, so change the external interrupt source to INT_SOURCE_EXTERNAL_0. Next, enable the I2C driver, using a bit-banged implementation: The Interrupt System Service is enabled, with an Interrupt Priority of 5, connected to INT0, and triggered on a falling edge (since CTP-INT# is active low): Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 124 Re-generate the application to implement these changes to the application. Rather than edit the application’s MTCH6303 driver code, install the modified driver from the tutorial project found in .\apps\examples\3rdPartyDisplay. Copy the code found in directory .\apps\examples\3rdPartyDisplay\firmware\src\system_config\default\framework\driver\touch\mtch6303 into the same folder in the project. To keep these changes in the code whenever the project is regenerated, always choose the “Prompt Merge For All Differences” merge strategy and simply close all the windows related to the MTCH6303 driver. These changes are identified by // CUSTOM CODE – DO NOT DELETE … // END OF CUSTOM CODE flags in the code. Note: Ignore all proposed changes for the following files: • drv_mtch6303_static.h • drv_mtch6303_static.c • drv_mtch6303_static_local.h To enable Focal Tech support in the modified driver, open the project’s configuration and define FT_SUPPORT in the C compiler section. Adding a Touch Test Widget Bring up MHC’s Graphics Composer again and add a Touch Test widget to the screen. Resize the widget to cover most of the display. Next, create another color scheme, and customize it to see the cross hairs for all touch measurements reported by the widget. The TouchTest Widget has the following color scheme: First, create a new scheme, call it TouchTestScheme: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 125 Edit the Foreground and Background colors so that both are red. Finally, edit the properties for the Touch Test widget to have a Line border, and to use the TouchTestScheme color scheme: The Screen Designer panel should show: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 126 Close the Graphics Composer window and save the modifications to the graphics design. Re-generate the application’s code and then build and load the application. Testing the Final Application Here is what the display should look like during a touch event: Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Advanced Topics © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 127 Completed Tutorial Project The completed tutorial project can be found in .\apps\examples\3rdPartyDisplay. Importing and Exporting Graphics Data This topic provides information on importing and exporting graphics composer-related data. Description The MPLAB Harmony Graphics Composer (MHGC) provides the capability for users to import and export graphics designs. The user can export the state of an existing graphics composer configuration or import another graphics composer configuration from another project. Importing Data 1. To import a graphics design into MHGC, select File > Import. The Browse for MPLAB Harmony Graphics Composer XML file dialog appears, which allows the selection of a previously exported Graphics Composer .xml file, or the configuration.xml file that contains the desired graphics image. 2. After selecting a file and clicking Open, you will be prompted whether to overwrite existing data. 3. If you selected a composer_export.xml file, clicking Yes will replace the current graphics design with the new design. 4. Otherwise, if you selected a configuration.xml file, you will be prompted to import the data into the current graphics design. Click Yes to replace the current graphics design with the new design. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Importing and Exporting Graphics Data © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 128 Exporting Data 1. To export a graphics design from MHGC, select File > Export. The Select File Location for MPLAB Harmony Graphics Composer XML file dialog appears. 2. To export a graphics design using a configuration.xml file, use the Save Configuration utility from the MPLAB Harmony Configurator (MHC) toolbar. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer User's Importing and Exporting Graphics Data © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 129 MPLAB Harmony Graphics Composer Suite This section provides user information about using the MPLAB Harmony Graphics Composer Suite (MHGS). Description Please see Volume IV: MPLAB Harmony Framework Reference > Graphics Libraries Help > MPLAB Harmony Graphics Composer Suite for detailed information. Volume III: MPLAB Harmony Configurator (MHC) MPLAB Harmony Graphics Composer Suite © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 130 Index A Adding Third-Party Graphics Products Using the Hardware Abstsraction Layer (HAL) 90 Advanced Topics 90 aria_coffeemaker Demonstration Example 98 B Binary Assets 66 C Code Generation 90 Creating a MPLAB Harmony Graphics Application Using a Third-Party Display 106 Creating the Project in MPLAB and MPLAB Harmony 109 D DDR Organizer 47 Draw Pipeline Options 93 E Event Manager 67 F Font Assets 55 G Global Palette 78 GPU Hardware Accelerated Features 103 Graphics Composer Asset Management 42 Graphics Composer Window User Interface 3 Graphics Pipeline 93 Graphics Pipeline Options 97 H Heap Estimator 76 I Image Assets 49 Image Preprocessing Memory Management 106 Importing and Exporting Graphics Data 128 Improved Touch Performance with Phantom Buttons 98 Introduction 3 M Memory Configuration 43 Menus 10 MHGC Tools 67 MPLAB Harmony Graphics Composer Suite 130 MPLAB Harmony Graphics Composer User's Guide 3 N New Project Wizard 14 O Object Properties 30 Options 26 P Properties Editor Panel 29 S Schemes Panel 24 Screen Designer Window 6 Screens Panel 22 Small Buttons Controlled by Phantom Buttons 100 Speed and Performance of Different Image Decode Formats in MHGC 92 String Assets 63 String Table Configuration 60 Supporting the Focal Tech FT5x06 Capacitive Touch Controller 122 T Tree View Panel 18 V Volume III: MPLAB Harmony Configurator (MHC) 2 W Widget Colors 81 Widget Tool Box Panel 26 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 131

www.microchip.com/partners Authorized Design Partner Program Design Partner Program A UTHORIZED Consulting Services Hardware Design Software Design Reference Designs Manufacturing 2 Design Partner Program Design Partner Program Overview Program Overview Microchip’s Design Partner Program (DPP) capitalizes on the joint strengths of Microchip and its world-class Design Partner network, which ranges from small design houses to large international corporations. Through the Microchip DPP, Microchip identifies, recruits and supports partners who provide market-leading embedded software and hardware design services, reference designs and full turnkey manufacturing services implementing Microchip’s embedded technology solutions. Authorized design partners get access to priority support, hands-on technical trainings, joint marketing and PR opportunities and are highlighted on Microchip’s Design Partner website. Information supplied to our customers and Microchip’s worldwide sale force includes a detailed partner profile of each partner, their location(s) and areas of technological expertise. Our customers receive access to a network of experts needed throughout their design life cycle and service engagement, while partners benefit from an expanded customer base, increased revenue stream and the ability to differentiate themselves in today’s competitive marketplace. Authorized Design Partner Logo Program participants can use this official logo to demonstrate their affiliation with Microchip. Program Benefi ts More Complete Solutions ■ Access to Microchip's diverse product portfolio ■ Full range of easy-to-use development tools ■ Enhanced technical support Improved Time to Market ■ Seamless migration path ■ Shared integration resources ■ Optimized reference designs ■ Access to predeveloped software components Shared Risk and Lower System Cost ■ Reduced research and development ■ World-class quality and reliability ■ Access to technology experts Leverage Microchip's Resources ■ Engage more customers ■ Share insights, expertise and feedback ■ Access to more opportunities and design wins A UTHORIZED Design Partner Program 3 Get Rewarded by Microchip Microchip’s Design Partner Program offers two compensation options. Depending on your company’s business model, Microchip offers financial compensation for designing with Microchip’s broad product portfolio; or participants can receive special discounts on development tools, silicon products and Microchip’s annual MASTERs Conference. These rewards are applicable to qualified design partners who specify Microchip products for their end customers and/or to those who include Microchip’s devices in reference designs used by third parties. Microchip's Authorized Design Partner Program Benefi ts Option 1: Compensation-Based Program Financial Compensation Program Benefi ts Bronze Silver Gold Platinum Acceptance Level Required Agreement Signed Microchip Field Nomination and Approval 25 Design Wins per Calendar Year 40 Design Wins per Calendar Year Design Partner Certifi cate Issued Every Calendar Year ü ü ü ü 45% discount coupon for development tools at www.microchipDIRECT.com ü – – – Use of Microchip's Design Partner Program logo ü ü ü ü Partner profi le posted on Microchip's website at www.microchip.com/partners – ü ü ü Priority technical support at www.microchip.com/support ü ü ü ü Opportunity to become a third-party developer at www.EmbeddedCodeSource.com ü ü ü ü Free expanded sample counts at www.microchip.com/samples ü ü ü ü Free technical training at www.microchip.com/training ü ü ü ü Participation in special Microchip projects (articles, reference designs, etc.) – – ü ü Increased joint marketing and PR opportunities – – – ü Option 2: Discount-Based Program Discount-Based Program Benefi ts Bronze Silver Gold Platinum Acceptance Level Points Required 250 500 750 1000 Design Partner Certifi cate Issued Every Calendar Year ü ü ü ü Free MPLAB® ICD 3 In-Circuit Debugger (upon acceptance into the program) ü ü ü ü On-going discount on development tools at www.microchipDIRECT.com 45% 45% 45% 45% Discount on attendance at MASTERs Conference at www.microchip.com/MASTERs 20% 40% 60% 75% Use of Microchip's Design Partner Program logo ü ü ü ü Partner profi le posted on Microchip's website at www.microchip.com/partners ü ü ü ü Priority Technical Support at www.microchip.com/support ü ü ü ü Opportunity to become a third-party developer at www.EmbeddedCodeSource.com ü ü ü ü Free expanded sample counts at www.microchip.com/samples ü ü ü ü Free technical training at www.microchip.com/training ü ü ü ü Participation in special Microchip projects (articles, reference designs, etc.) – – ü ü Increased joint marketing and PR opportunities – – – ü Interested in Applying? Send us an email at designpartners@microchip.com or contact your local Microchip sales representative for more information. Microchip Technology Inc. 2355 W. Chandler Blvd. Chandler, AZ 85224-6199 www.microchip.com Support Microchip is committed to supporting its customers in developing products faster and more efficiently. We maintain a worldwide network of field applications engineers and technical support ready to provide product and system assistance. In addition, the following service areas are available at www.microchip.com: ■ Support link provides a way to get questions answered fast: http://support.microchip.com ■ Sample link offers evaluation samples of any Microchip device: http://sample.microchip.com ■ Forum link provides access to knowledge base and peer help: http://forum.microchip.com ■ Buy link provides locations of Microchip Sales Channel Partners: www.microchip.com/sales Training If additional training interests you, then Microchip can help. We continue to expand our technical training options, offering a growing list of courses and in-depth curriculum locally, as well as significant online resources – whenever you want to use them. ■ Technical Training and other Resources: www.microchip.com/training ■ MASTERs Conferences: www.microchip.com/masters ■ Worldwide Seminars: www.microchip.com/seminars ■ eLearning: www.microchip.com/webseminars The Microchip name and logo, the Microchip logo and MPLAB are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. All other trademarks mentioned herein are property of their respective companies. © 2015, Microchip Technology Incorporated. All Rights Reserved. Printed in the U.S.A. 9/15 DS00001077D Sales Offi ce Listing ASIA/PACIFIC Australia - Sydney Tel: 61-2-9868-6733 China - Beijing Tel: 86-10-8569-7000 China - Chengdu Tel: 86-28-8665-5511 China - Chongqing Tel: 86-23-8980-9588 China - Dongguan Tel: 86-769-8702-9880 China - Hangzhou Tel: 86-571-87928115 China - Hong Kong SAR Tel: 852-2943-5100 China - Nanjing Tel: 86-25-8473-2460 China - Qingdao Tel: 86-532-8502-7355 China - Shanghai Tel: 86-21-5407-5533 China - Shenyang Tel: 86-24-2334-2829 China - Shenzhen Tel: 86-755-8864-2200 China - Wuhan Tel: 86-27-5980-5300 China - Xiamen Tel: 86-592-2388138 China - Xian Tel: 86-29-8833-7252 China - Zhuhai Tel: 86-756-3210040 AMERICAS Atlanta Tel: 678-957-9614 Austin Tel: 512-257-3370 Boston Tel: 774-760-0087 Chandler Tel: 480-792-7200 Chicago Tel: 630-285-0071 Cleveland Tel: 216-447-0464 Dallas Tel: 972-818-7423 Detroit Tel: 248-538-2250 Houston Tel: 281-894-5983 Indianapolis Tel: 317-773-8323 Los Angeles Tel: 949-462-9523 New York Tel: 631-435-6000 San Jose Tel: 408-735-9110 Toronto Tel: 905-673-0699 EUROPE Austria - Wels Tel: 43-7242-2244-39 Denmark - Copenhagen Tel: 45-4450-2828 France - Paris Tel: 33-1-69-53-63-20 Germany - Dusseldorf Tel: 49-2129-3766400 Germany - Karlsruhe Tel: 49-721-625370 Germany - Munich Tel: 49-89-627-144-0 Italy - Milan Tel: 39-0331-742611 Italy - Venice Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Poland - Warsaw Tel: 48-22-3325737 Spain - Madrid Tel: 34-91-708-08-90 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 ASIA/PACIFIC India - Bangalore Tel: 91-80-3090-4444 India - New Delhi Tel: 91-11-4160-8631 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Japan - Tokyo Tel: 81-3-6880-3770 Korea - Daegu Tel: 82-53-744-4301 Korea - Seoul Tel: 82-2-554-7200 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Malaysia - Penang Tel: 60-4-227-8870 Philippines - Manila Tel: 63-2-634-9065 Singapore Tel: 65-6334-8870 Taiwan - Hsin Chu Tel: 886-3-5778-366 Taiwan - Kaohsiung Tel: 886-7-213-7828 Taiwan - Taipei Tel: 886-2-2508-8600 Thailand - Bangkok Tel: 66-2-694-1351 7/14/15 Features • High-performance, Low-power 32-bit Atmel® AVR® Microcontroller – Compact Single-cycle RISC Instruction Set Including DSP Instructions – Read-modify-write Instructions and Atomic Bit Manipulation – Performance • Up to 64DMIPS Running at 50MHz from Flash (1 Flash Wait State) • Up to 36DMIPS Running at 25MHz from Flash (0 Flash Wait State) – Memory Protection Unit (MPU) • Secure Access Unit (SAU) providing User-defined Peripheral Protection • picoPower® Technology for Ultra-low Power Consumption • Multi-hierarchy Bus System – High-performance Data Transfers on Separate Buses for Increased Performance – 12 Peripheral DMA Channels improve Speed for Peripheral Communication • Internal High-speed Flash – 256Kbytes, 128Kbytes, and 64Kbytes Versions – Single-cycle Access up to 25MHz – FlashVault Technology Allows Pre-programmed Secure Library Support for End User Applications – Prefetch Buffer Optimizing Instruction Execution at Maximum Speed – 100,000 Write Cycles, 15-year Data Retention Capability – Flash Security Locks and User-defined Configuration Area • Internal High-speed SRAM, Single-cycle Access at Full Speed – 32Kbytes (256Kbytes and 128Kbytes Flash) and 16Kbytes (64Kbytes Flash) • Interrupt Controller (INTC) – Autovectored Low-latency Interrupt Service with Programmable Priority • External Interrupt Controller (EIC) • Peripheral Event System for Direct Peripheral to Peripheral Communication • System Functions – Power and Clock Manager – SleepWalking Power Saving Control – Internal System RC Oscillator (RCSYS) – 32 KHz Oscillator – Multipurpose Oscillator, Phase Locked Loop (PLL), and Digital Frequency Locked Loop (DFLL) • Windowed Watchdog Timer (WDT) • Asynchronous Timer (AST) with Real-time Clock Capability – Counter or Calendar Mode Supported • Frequency Meter (FREQM) for Accurate Measuring of Clock Frequency • Universal Serial Bus (USBC) – Full Speed and Low Speed USB Device Support – Multi-packet Ping-pong Mode • Six 16-bit Timer/Counter (TC) Channels – External Clock Inputs, PWM, Capture, and Various Counting Capabilities • 36 PWM Channels (PWMA) – 12-bit PWM with a Source Clock up to 150MHz • Four Universal Synchronous/Asynchronous Receiver/Transmitters (USART) – Independent Baudrate Generator, Support for SPI – Support for Hardware Handshaking 32142D–06/2013 32-bit Atmel AVR Microcontroller ATUC256L3U ATUC128L3U ATUC64L3U ATUC256L4U ATUC128L4U ATUC64L4U 2 32142D–06/2013 ATUC64/128/256L3/4U • One Master/Slave Serial Peripheral Interface (SPI) with Chip Select Signals – Up to 15 SPI Slaves can be Addressed • Two Master and Two Slave Two-wire Interfaces (TWI), 400kbit/s I2 C-compatible • One 8-channel Analog-to-digital Converter (ADC) with up to 12 Bits Resolution – Internal Temperature Sensor • Eight Analog Comparators (AC) with Optional Window Detection • Capacitive Touch (CAT) Module – Hardware-assisted Atmel® AVR® QTouch® and Atmel® AVR® QMatrix Touch Acquisition – Supports QTouch and QMatrix Capture from Capacitive Touch Sensors • QTouch Library Support – Capacitive Touch Buttons, Sliders, and Wheels – QTouch and QMatrix Acquisition • Audio Bitstream DAC (ABDACB) Suitable for Stereo Audio • Inter-IC Sound (IISC) Controller – Compliant with Inter-IC Sound (I2 S) Specification • On-chip Non-intrusive Debug System – Nexus Class 2+, Runtime Control, Non-intrusive Data and Program Trace – aWire Single-pin Programming Trace and Debug Interface, Muxed with Reset Pin – NanoTrace Provides Trace Capabilities through JTAG or aWire Interface • 64-pin TQFP/QFN (51 GPIO Pins), 48-pin TQFP/QFN/TLLGA (36 GPIO Pins) • Six High-drive I/O Pins (64-pin Packages), Four High-drive I/O Pins (48-pin Packages) • Single 1.62-3.6V Power Supply 3 32142D–06/2013 ATUC64/128/256L3/4U 1. Description The Atmel® AVR® ATUC64/128/256L3/4U is a complete system-on-chip microcontroller based on the AVR32 UC RISC processor running at frequencies up to 50MHz. AVR32 UC is a highperformance 32-bit RISC microprocessor core, designed for cost-sensitive embedded applications, with particular emphasis on low power consumption, high code density, and high performance. The processor implements a Memory Protection Unit (MPU) and a fast and flexible interrupt controller for supporting modern and real-time operating systems. The Secure Access Unit (SAU) is used together with the MPU to provide the required security and integrity. Higher computation capability is achieved using a rich set of DSP instructions. The ATUC64/128/256L3/4U embeds state-of-the-art picoPower technology for ultra-low power consumption. Combined power control techniques are used to bring active current consumption down to 174µA/MHz, and leakage down to 220nA while still retaining a bank of backup registers. The device allows a wide range of trade-offs between functionality and power consumption, giving the user the ability to reach the lowest possible power consumption with the feature set required for the application. The Peripheral Direct Memory Access (DMA) controller enables data transfers between peripherals and memories without processor involvement. The Peripheral DMA controller drastically reduces processing overhead when transferring continuous and large data streams. The ATUC64/128/256L3/4U incorporates on-chip Flash and SRAM memories for secure and fast access. The FlashVault technology allows secure libraries to be programmed into the device. The secure libraries can be executed while the CPU is in Secure State, but not read by non-secure software in the device. The device can thus be shipped to end customers, who will be able to program their own code into the device to access the secure libraries, but without risk of compromising the proprietary secure code. The External Interrupt Controller (EIC) allows pins to be configured as external interrupts. Each external interrupt has its own interrupt request and can be individually masked. The Peripheral Event System allows peripherals to receive, react to, and send peripheral events without CPU intervention. Asynchronous interrupts allow advanced peripheral operation in low power sleep modes. The Power Manager (PM) improves design flexibility and security. The Power Manager supports SleepWalking functionality, by which a module can be selectively activated based on peripheral events, even in sleep modes where the module clock is stopped. Power monitoring is supported by on-chip Power-on Reset (POR), Brown-out Detector (BOD), and Supply Monitor (SM). The device features several oscillators, such as Phase Locked Loop (PLL), Digital Frequency Locked Loop (DFLL), Oscillator 0 (OSC0), and system RC oscillator (RCSYS). Either of these oscillators can be used as source for the system clock. The DFLL is a programmable internal oscillator from 20 to 150MHz. It can be tuned to a high accuracy if an accurate reference clock is running, e.g. the 32KHz crystal oscillator. The Watchdog Timer (WDT) will reset the device unless it is periodically serviced by the software. This allows the device to recover from a condition that has caused the system to be unstable. The Asynchronous Timer (AST) combined with the 32KHz crystal oscillator supports powerful real-time clock capabilities, with a maximum timeout of up to 136 years. The AST can operate in counter or calendar mode. 4 32142D–06/2013 ATUC64/128/256L3/4U The Frequency Meter (FREQM) allows accurate measuring of a clock frequency by comparing it to a known reference clock. The Full-speed USB 2.0 device interface (USBC) supports several USB classes at the same time, thanks to the rich end-point configuration. The device includes six identical 16-bit Timer/Counter (TC) channels. Each channel can be independently programmed to perform frequency measurement, event counting, interval measurement, pulse generation, delay timing, and pulse width modulation. The Pulse Width Modulation controller (PWMA) provides 12-bit PWM channels which can be synchronized and controlled from a common timer. 36 PWM channels are available, enabling applications that require multiple PWM outputs, such as LCD backlight control. The PWM channels can operate independently, with duty cycles set individually, or in interlinked mode, with multiple channels changed at the same time. The ATUC64/128/256L3/4U also features many communication interfaces, like USART, SPI, and TWI, for communication intensive applications. The USART supports different communication modes, like SPI Mode and LIN Mode. A general purpose 8-channel ADC is provided, as well as eight analog comparators (AC). The ADC can operate in 10-bit mode at full speed or in enhanced mode at reduced speed, offering up to 12-bit resolution. The ADC also provides an internal temperature sensor input channel. The analog comparators can be paired to detect when the sensing voltage is within or outside the defined reference window. The Capacitive Touch (CAT) module senses touch on external capacitive touch sensors, using the QTouch technology. Capacitive touch sensors use no external mechanical components, unlike normal push buttons, and therefore demand less maintenance in the user application. The CAT module allows up to 17 touch sensors, or up to 16 by 8 matrix sensors to be interfaced. All touch sensors can be configured to operate autonomously without software interaction, allowing wakeup from sleep modes when activated. Atmel offers the QTouch library for embedding capacitive touch buttons, sliders, and wheels functionality into AVR microcontrollers. The patented charge-transfer signal acquisition offers robust sensing and includes fully debounced reporting of touch keys as well as Adjacent Key Suppression® (AKS®) technology for unambiguous detection of key events. The easy-to-use QTouch Suite toolchain allows you to explore, develop, and debug your own touch applications. The Audio Bitstream DAC (ABDACB) converts a 16-bit sample value to a digital bitstream with an average value proportional to the sample value. Two channels are supported, making the ABDAC particularly suitable for stereo audio. The Inter-IC Sound Controller (IISC) provides a 5-bit wide, bidirectional, synchronous, digital audio link with external audio devices. The controller is compliant with the Inter-IC Sound (I2S) bus specification. The ATUC64/128/256L3/4U integrates a class 2+ Nexus 2.0 On-chip Debug (OCD) System, with non-intrusive real-time trace and full-speed read/write memory access, in addition to basic runtime control. The NanoTrace interface enables trace feature for aWire- or JTAG-based debuggers. The single-pin aWire interface allows all features available through the JTAG interface to be accessed through the RESET pin, allowing the JTAG pins to be used for GPIO or peripherals. 5 32142D–06/2013 ATUC64/128/256L3/4U 2. Overview 2.1 Block Diagram Figure 2-1. Block Diagram INTERRUPT CONTROLLER ASYNCHRONOUS TIMER PERIPHERAL DMA CONTROLLER HSB-PB BRIDGE B HSB-PB BRIDGE A S MM M S S M EXTERNAL INTERRUPT CONTROLLER HIGH SPEED BUS MATRIX GENERALPURPOSE I/Os GENERAL PURPOSE I/Os PA PB EXTINT[5..1] NMI PA PB SPI DMA MISO, MOSI NPCS[3..0] USART0 USART1 USART2 USART3 DMA RXD TXD CLK RTS, CTS WATCHDOG TIMER SCK JTAG INTERFACE MCKO MDO[5..0] MSEO[1..0] EVTI_N TDO TDI TMS CONFIGURATION REGISTERS BUS 256/128/64 KB S FLASH FLASH CONTROLLER EVTO_N AVR32UC CPU NEXUS CLASS 2+ OCD INSTR INTERFACE DATA INTERFACE MEMORY INTERFACE LOCAL BUS 32/16 KB SRAM MEMORY PROTECTION UNIT LOCAL BUS INTERFACE FREQUENCY METER PWMA[35..0] PWM CONTROLLER TWI MASTER 0 DMA TWI MASTER 1 TWI SLAVE 0 DMA TWI SLAVE 1 8-CHANNEL ADC DMA INTERFACE POWER MANAGER RESET CONTROLLER SLEEP CONTROLLER CLOCK CONTROLLER TCK RESET_N aWire CAPACITIVE TOUCH DMA MODULE AC INTERFACE ACREFN ACAN[3..0] ACBN[3..0] ACBP[3..0] ACAP[3..0] TWCK TWD TWALM TWCK TWD TWALM GLUE LOGIC CONTROLLER IN[7..0] OUT[1..0] USB 2.0 Interface 8EP DMA INTER-IC SOUND CONTROLLER TIMER/COUNTER 0 TIMER/COUNTER 1 A[2..0] B[2..0] AUDIO BITSTREAM DMA DAC DAC0, DAC1 DACN0, DACN1 ISCK IWS ISDI ISDO IMCK CLK SAU S/M S DM DP SYSTEM CONTROL INTERFACE GCLK[9..0] XIN32 XOUT32 OSC32K RCSYS XIN0 XOUT0 OSC0 DFLL RC32K RC120M RC32OUT PLL GCLK_IN[2..0] CSB[16:0] SMP CSA[16:0] SYNC VDIVEN DIS TRIGGER ADP[1..0] AD[8..0] DATAOUT ADVREFP CLK[2..0] 6 32142D–06/2013 ATUC64/128/256L3/4U 2.2 Configuration Summary Table 2-1. Configuration Summary Feature ATUC256L3U ATUC128L3U ATUC64L3U ATUC256L4U ATUC128L4U ATUC64L4U Flash 256KB 128KB 64KB 256KB 128KB 64KB SRAM 32KB 16KB 32KB 16KB GPIO 51 36 High-drive pins 6 4 External Interrupts 6 TWI 2 USART 4 Peripheral DMA Channels 12 Peripheral Event System 1 SPI 1 Asynchronous Timers 1 Timer/Counter Channels 6 PWM channels 36 Frequency Meter 1 Watchdog Timer 1 Power Manager 1 Secure Access Unit 1 Glue Logic Controller 1 Oscillators Digital Frequency Locked Loop 20-150MHz (DFLL) Phase Locked Loop 40-240MHz (PLL) Crystal Oscillator 0.45-16MHz (OSC0) Crystal Oscillator 32KHz (OSC32K) RC Oscillator 120MHz (RC120M) RC Oscillator 115kHz (RCSYS) RC Oscillator 32kHz (RC32K) ADC 8-channel 12-bit Temperature Sensor 1 Analog Comparators 8 Capacitive Touch Module 1 JTAG 1 aWire 1 USB 1 Audio Bitstream DAC 1 0 IIS Controller 1 0 Max Frequency 50MHz Packages TQFP64/QFN64 TQFP48/QFN48/TLLGA48 7 32142D–06/2013 ATUC64/128/256L3/4U 3. Package and Pinout 3.1 Package The device pins are multiplexed with peripheral functions as described in Section . Figure 3-1. ATUC64/128/256L4U TQFP48/QFN48 Pinout GND 1 PA09 2 PA08 3 PA03 4 PB12 5 PB00 6 PB02 7 PB03 8 PA22 9 PA06 10 PA00 11 PA05 12 13 PA02 14 PA01 15 PB13 16 PB14 17 VDDIN 18 VDDCORE 19 GND 20 PB05 21 PB04 22 RESET_N 23 PB10 24 PA21 PA14 36 VDDANA 35 ADVREFP 34 GNDANA 33 PB08 32 PB07 31 PB06 30 PB09 29 PA04 28 PA11 27 PA13 26 PA20 25 PA15 37 PA16 38 PA17 39 PA19 40 PA18 41 VDDIO 42 GND 43 PB11 44 GND 45 PA10 46 PA12 47 VDDIO 48 8 32142D–06/2013 ATUC64/128/256L3/4U Figure 3-2. ATUC64/128/256L4U TLLGA48 Pinout GND 1 PA09 2 PA08 3 PA03 4 PB12 5 PB00 6 PB02 7 PB03 8 PA22 9 PA06 10 PA00 11 PA05 12 PA02 13 14 PA01 15 PB13 16 PB14 17 VDDIN 18 VDDCORE 19 GND 20 PB05 21 PB04 22 RESET_N 23 PB10 24 PA21 PA14 36 VDDANA 35 ADVREFP 34 GNDANA 33 PB08 32 PB07 31 PB06 30 PB09 29 PA04 28 PA11 27 PA13 26 PA20 25 PA15 37 PA16 38 PA17 39 PA19 40 PA18 41 VDDIO 42 GND 43 PB11 44 GND 45 PA10 46 PA12 47 VDDIO 48 9 32142D–06/2013 ATUC64/128/256L3/4U Figure 3-3. ATUC64/128/256L3U TQFP64/QFN64 Pinout GND 1 PA09 2 PA08 3 PB19 4 PB20 5 PA03 6 PB12 7 PB00 8 PB02 9 PB03 10 VDDIO 11 GND 12 PA22 13 PA06 14 PA00 15 PA05 16 17 PA02 18 PA01 19 PA07 20 PB01 21 PB26 22 PB13 23 PB14 24 PB27 PB08 44 PB07 43 PB06 42 PB22 41 PB21 40 PB09 39 PA04 38 VDDIO 37 GND 36 PA11 35 PA13 34 PA20 33 PA15 49 PA16 50 PA17 51 PA19 52 PA18 53 PB23 54 PB24 55 PB11 56 PB15 57 PB16 58 PB17 59 PB18 60 25 VDDIN 26 27 GND 28 PB05 29 PB04 30 31 PB10 32 PA21 PA14 48 VDDANA 47 ADVREFP 46 GNDANA 45 PB25 61 PA10 62 PA12 63 VDDIO 64 VDDCORE RESET_N 10 32142D–06/2013 ATUC64/128/256L3/4U Peripheral Multiplexing on I/O lines 3.1.1 Multiplexed Signals Each GPIO line can be assigned to one of the peripheral functions. The following table describes the peripheral signals multiplexed to the GPIO lines. Table 3-1. GPIO Controller Function Multiplexing 48- pin 64- pin Pin Name G PI O Supply Pad Type GPIO Function ABCDE F GH 11 15 PA00 0 VDDIO Normal I/O USART0- TXD USART1- RTS SPINPCS[2] PWMAPWMA[0] SCIFGCLK[0] CATCSA[2] 14 18 PA01 1 VDDIO Normal I/O USART0- RXD USART1- CTS SPINPCS[3] USART1- CLK PWMAPWMA[1] ACIFBACAP[0] TWIMS0- TWALM CATCSA[1] 13 17 PA02 2 VDDIO Highdrive I/O USART0- RTS ADCIFBTRIGGER USART2- TXD TC0-A0 PWMAPWMA[2] ACIFBACBP[0] USART0- CLK CATCSA[3] 4 6 PA03 3 VDDIO Normal I/O USART0- CTS SPINPCS[1] USART2- TXD TC0-B0 PWMAPWMA[3] ACIFBACBN[3] USART0- CLK CATCSB[3] 28 38 PA04 4 VDDIO Normal I/O SPI-MISO TWIMS0- TWCK USART1- RXD TC0-B1 PWMAPWMA[4] ACIFBACBP[1] CATCSA[7] 12 16 PA05 5 VDDIO Normal I/O (TWI) SPI-MOSI TWIMS1- TWCK USART1- TXD TC0-A1 PWMAPWMA[5] ACIFBACBN[0] TWIMS0- TWD CATCSB[7] 10 14 PA06 6 VDDIO Highdrive I/O, 5V tolerant SPI-SCK USART2- TXD USART1- CLK TC0-B0 PWMAPWMA[6] EICEXTINT[2] SCIFGCLK[1] CATCSB[1] 19 PA07 7 VDDIO Normal I/O (TWI) SPINPCS[0] USART2- RXD TWIMS1- TWALM TWIMS0- TWCK PWMAPWMA[7] ACIFBACAN[0] EICNMI (EXTINT[0]) CATCSB[2] 3 3 PA08 8 VDDIO Highdrive I/O USART1- TXD SPINPCS[2] TC0-A2 ADCIFBADP[0] PWMAPWMA[8] CATCSA[4] 2 2 PA09 9 VDDIO Highdrive I/O USART1- RXD SPINPCS[3] TC0-B2 ADCIFBADP[1] PWMAPWMA[9] SCIFGCLK[2] EICEXTINT[1] CATCSB[4] 46 62 PA10 10 VDDIO Normal I/O TWIMS0- TWD TC0-A0 PWMAPWMA[10] ACIFBACAP[1] SCIFGCLK[2] CATCSA[5] 27 35 PA11 11 VDDIN Normal I/O PWMAPWMA[11] 47 63 PA12 12 VDDIO Normal I/O USART2- CLK TC0-CLK1 CAT-SMP PWMAPWMA[12] ACIFBACAN[1] SCIFGCLK[3] CATCSB[5] 26 34 PA13 13 VDDIN Normal I/O GLOCOUT[0] GLOCIN[7] TC0-A0 SCIFGCLK[2] PWMAPWMA[13] CAT-SMP EICEXTINT[2] CATCSA[0] 36 48 PA14 14 VDDIO Normal I/O ADCIFBAD[0] TC0-CLK2 USART2- RTS CAT-SMP PWMAPWMA[14] SCIFGCLK[4] CATCSA[6] 37 49 PA15 15 VDDIO Normal I/O ADCIFBAD[1] TC0-CLK1 GLOCIN[6] PWMAPWMA[15] CATSYNC EICEXTINT[3] CATCSB[6] 38 50 PA16 16 VDDIO Normal I/O ADCIFBAD[2] TC0-CLK0 GLOCIN[5] PWMAPWMA[16] ACIFBACREFN EICEXTINT[4] CATCSA[8] 11 32142D–06/2013 ATUC64/128/256L3/4U 39 51 PA17 17 VDDIO Normal I/O (TWI) TC0-A1 USART2- CTS TWIMS1- TWD PWMAPWMA[17] CAT-SMP CAT-DIS CATCSB[8] 41 53 PA18 18 VDDIO Normal I/O ADCIFBAD[4] TC0-B1 GLOCIN[4] PWMAPWMA[18] CATSYNC EICEXTINT[5] CATCSB[0] 40 52 PA19 19 VDDIO Normal I/O ADCIFBAD[5] TC0-A2 TWIMS1- TWALM PWMAPWMA[19] SCIFGCLK_IN[ 0] CAT-SYNC CATCSA[10] 25 33 PA20 20 VDDIN Normal I/O USART2- TXD TC0-A1 GLOCIN[3] PWMAPWMA[20] SCIFRC32OUT CATCSA[12] 24 32 PA21 21 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) USART2- RXD TWIMS0- TWD TC0-B1 ADCIFBTRIGGER PWMAPWMA[21] PWMAPWMAOD [21] SCIFGCLK[0] CATSMP 9 13 PA22 22 VDDIO Normal I/O USART0- CTS USART2- CLK TC0-B2 CAT-SMP PWMAPWMA[22] ACIFBACBN[2] CATCSB[10] 6 8 PB00 32 VDDIO Normal I/O USART3- TXD ADCIFBADP[0] SPINPCS[0] TC0-A1 PWMAPWMA[23] ACIFBACAP[2] TC1-A0 CATCSA[9] 20 PB01 33 VDDIO Highdrive I/O USART3- RXD ADCIFBADP[1] SPI-SCK TC0-B1 PWMAPWMA[24] TC1-A1 CATCSB[9] 7 9 PB02 34 VDDIO Normal I/O USART3- RTS USART3- CLK SPI-MISO TC0-A2 PWMAPWMA[25] ACIFBACAN[2] SCIFGCLK[1] CATCSB[11] 8 10 PB03 35 VDDIO Normal I/O USART3- CTS USART3- CLK SPI-MOSI TC0-B2 PWMAPWMA[26] ACIFBACBP[2] TC1-A2 CATCSA[11] 21 29 PB04 36 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) TC1-A0 USART1- RTS USART1- CLK TWIMS0- TWALM PWMAPWMA[27] PWMAPWMAOD [27] TWIMS1- TWCK CATCSA[14] 20 28 PB05 37 VDDIN Normal I/O (TWI, 5V tolerant, SMBus) TC1-B0 USART1- CTS USART1- CLK TWIMS0- TWCK PWMAPWMA[28] PWMAPWMAOD [28] SCIFGCLK[3] CATCSB[14] 30 42 PB06 38 VDDIO Normal I/O TC1-A1 USART3- TXD ADCIFBAD[6] GLOCIN[2] PWMAPWMA[29] ACIFBACAN[3] EICNMI (EXTINT[0]) CATCSB[13] 31 43 PB07 39 VDDIO Normal I/O TC1-B1 USART3- RXD ADCIFBAD[7] GLOCIN[1] PWMAPWMA[30] ACIFBACAP[3] EICEXTINT[1] CATCSA[13] 32 44 PB08 40 VDDIO Normal I/O TC1-A2 USART3- RTS ADCIFBAD[8] GLOCIN[0] PWMAPWMA[31] CATSYNC EICEXTINT[2] CATCSB[12] 29 39 PB09 41 VDDIO Normal I/O TC1-B2 USART3- CTS USART3- CLK PWMAPWMA[32] ACIFBACBN[1] EICEXTINT[3] CATCSB[15] 23 31 PB10 42 VDDIN Normal I/O TC1-CLK0 USART1- TXD USART3- CLK GLOCOUT[1] PWMAPWMA[33] SCIFGCLK_IN[ 1] EICEXTINT[4] CATCSB[16] 44 56 PB11 43 VDDIO Normal I/O TC1-CLK1 USART1- RXD ADCIFBTRIGGER PWMAPWMA[34] CATVDIVEN EICEXTINT[5] CATCSA[16] 5 7 PB12 44 VDDIO Normal I/O TC1-CLK2 TWIMS1- TWALM CATSYNC PWMAPWMA[35] ACIFBACBP[3] SCIFGCLK[4] CATCSA[15] 15 22 PB13 45 VDDIN USB I/O USBC-DM USART3- TXD TC1-A1 PWMAPWMA[7] ADCIFBADP[1] SCIFGCLK[5] CATCSB[2] 16 23 PB14 46 VDDIN USB I/O USBC-DP USART3- RXD TC1-B1 PWMAPWMA[24] SCIFGCLK[5] CATCSB[9] Table 3-1. GPIO Controller Function Multiplexing 12 32142D–06/2013 ATUC64/128/256L3/4U 3.2 See Section 3.3 for a description of the various peripheral signals. Refer to ”Electrical Characteristics” on page 897 for a description of the electrical properties of the pin types used. 3.2.1 TWI, 5V Tolerant, and SMBUS Pins Some normal I/O pins offer TWI, 5V tolerance, and SMBUS features. These features are only available when either of the TWI functions or the PWMAOD function in the PWMA are selected for these pins. Refer to the ”Electrical Characteristics” on page 897 for a description of the electrical properties of the TWI, 5V tolerance, and SMBUS pins. 57 PB15 47 VDDIO Highdrive I/O ABDACBCLK IISCIMCK SPI-SCK TC0-CLK2 PWMAPWMA[8] SCIFGCLK[3] CATCSB[4] 58 PB16 48 VDDIO Normal I/O ABDACBDAC[0] IISC-ISCK USART0- TXD PWMAPWMA[9] SCIFGCLK[2] CATCSA[5] 59 PB17 49 VDDIO Normal I/O ABDACBDAC[1] IISC-IWS USART0- RXD PWMAPWMA[10] CATCSB[5] 60 PB18 50 VDDIO Normal I/O ABDACBDACN[0] IISC-ISDI USART0- RTS PWMAPWMA[12] CATCSA[0] 4 PB19 51 VDDIO Normal I/O ABDACBDACN[1] IISC-ISDO USART0- CTS PWMAPWMA[20] EICEXTINT[1] CATCSA[12] 5 PB20 52 VDDIO Normal I/O TWIMS1- TWD USART2- RXD SPINPCS[1] TC0-A0 PWMAPWMA[21] USART1- RTS USART1- CLK CATCSA[14] 40 PB21 53 VDDIO Normal I/O TWIMS1- TWCK USART2- TXD SPINPCS[2] TC0-B0 PWMAPWMA[28] USART1- CTS USART1- CLK CATCSB[14] 41 PB22 54 VDDIO Normal I/O TWIMS1- TWALM SPINPCS[3] TC0-CLK0 PWMAPWMA[27] ADCIFBTRIGGER SCIFGCLK[0] CATCSA[8] 54 PB23 55 VDDIO Normal I/O SPI-MISO USART2- RTS USART2- CLK TC0-A2 PWMAPWMA[0] CAT-SMP SCIFGCLK[6] CATCSA[4] 55 PB24 56 VDDIO Normal I/O SPI-MOSI USART2- CTS USART2- CLK TC0-B2 PWMAPWMA[1] ADCIFBADP[1] SCIFGCLK[7] CATCSA[2] 61 PB25 57 VDDIO Normal I/O SPINPCS[0] USART1- RXD TC0-A1 PWMAPWMA[2] SCIFGCLK_IN[ 2] SCIFGCLK[8] CATCSA[3] 21 PB26 58 VDDIO Normal I/O SPI-SCK USART1- TXD TC0-B1 PWMAPWMA[3] ADCIFBADP[0] SCIFGCLK[9] CATCSB[3] 24 PB27 59 VDDIN Normal I/O USART1- RXD TC0-CLK1 PWMAPWMA[4] ADCIFBADP[1] EICNMI (EXTINT[0]) CATCSA[9] Table 3-1. GPIO Controller Function Multiplexing 13 32142D–06/2013 ATUC64/128/256L3/4U 3.2.2 Peripheral Functions Each GPIO line can be assigned to one of several peripheral functions. The following table describes how the various peripheral functions are selected. The last listed function has priority in case multiple functions are enabled on the same pin. 3.2.3 JTAG Port Connections If the JTAG is enabled, the JTAG will take control over a number of pins, irrespectively of the I/O Controller configuration. 3.2.4 Nexus OCD AUX Port Connections If the OCD trace system is enabled, the trace system will take control over a number of pins, irrespectively of the I/O Controller configuration. Two different OCD trace pin mappings are possible, depending on the configuration of the OCD AXS register. For details, see the AVR32 UC Technical Reference Manual. Table 3-2. Peripheral Functions Function Description GPIO Controller Function multiplexing GPIO and GPIO peripheral selection A to H Nexus OCD AUX port connections OCD trace system aWire DATAOUT aWire output in two-pin mode JTAG port connections JTAG debug port Oscillators OSC0, OSC32 Table 3-3. JTAG Pinout 48-pin 64-pin Pin name JTAG pin 11 15 PA00 TCK 14 18 PA01 TMS 13 17 PA02 TDO 4 6 PA03 TDI Table 3-4. Nexus OCD AUX Port Connections Pin AXS=1 AXS=0 EVTI_N PA05 PB08 MDO[5] PA10 PB00 MDO[4] PA18 PB04 MDO[3] PA17 PB05 MDO[2] PA16 PB03 MDO[1] PA15 PB02 MDO[0] PA14 PB09 14 32142D–06/2013 ATUC64/128/256L3/4U 3.2.5 Oscillator Pinout The oscillators are not mapped to the normal GPIO functions and their muxings are controlled by registers in the System Control Interface (SCIF). Please refer to the SCIF chapter for more information about this. 3.2.6 Other Functions The functions listed in Table 3-6 are not mapped to the normal GPIO functions. The aWire DATA pin will only be active after the aWire is enabled. The aWire DATAOUT pin will only be active after the aWire is enabled and the 2_PIN_MODE command has been sent. The WAKE_N pin is always enabled. Please refer to Section 6.1.4.2 on page 44 for constraints on the WAKE_N pin. EVTO_N PA04 PA04 MCKO PA06 PB01 MSEO[1] PA07 PB11 MSEO[0] PA11 PB12 Table 3-4. Nexus OCD AUX Port Connections Pin AXS=1 AXS=0 Table 3-5. Oscillator Pinout 48-pin 64-pin Pin Name Oscillator Pin 3 3 PA08 XIN0 46 62 PA10 XIN32 26 34 PA13 XIN32_2 2 2 PA09 XOUT0 47 63 PA12 XOUT32 25 33 PA20 XOUT32_2 Table 3-6. Other Functions 48-pin 64-pin Pin Name Function 27 35 PA11 WAKE_N 22 30 RESET_N aWire DATA 11 15 PA00 aWire DATAOUT 15 32142D–06/2013 ATUC64/128/256L3/4U 3.3 Signal Descriptions The following table gives details on signal name classified by peripheral. Table 3-7. Signal Descriptions List Signal Name Function Type Active Level Comments Audio Bitstream DAC - ABDACB CLK D/A Clock out Output DAC1 - DAC0 D/A Bitstream out Output DACN1 - DACN0 D/A Inverted bitstream out Output Analog Comparator Interface - ACIFB ACAN3 - ACAN0 Negative inputs for comparators "A" Analog ACAP3 - ACAP0 Positive inputs for comparators "A" Analog ACBN3 - ACBN0 Negative inputs for comparators "B" Analog ACBP3 - ACBP0 Positive inputs for comparators "B" Analog ACREFN Common negative reference Analog ADC Interface - ADCIFB AD8 - AD0 Analog Signal Analog ADP1 - ADP0 Drive Pin for resistive touch screen Output TRIGGER External trigger Input aWire - AW DATA aWire data I/O DATAOUT aWire data output for 2-pin mode I/O Capacitive Touch Module - CAT CSA16 - CSA0 Capacitive Sense A I/O CSB16 - CSB0 Capacitive Sense B I/O DIS Discharge current control Analog SMP SMP signal Output SYNC Synchronize signal Input VDIVEN Voltage divider enable Output External Interrupt Controller - EIC NMI (EXTINT0) Non-Maskable Interrupt Input EXTINT5 - EXTINT1 External interrupt Input Glue Logic Controller - GLOC IN7 - IN0 Inputs to lookup tables Input OUT1 - OUT0 Outputs from lookup tables Output Inter-IC Sound (I2S) Controller - IISC 16 32142D–06/2013 ATUC64/128/256L3/4U IMCK I2S Master Clock Output ISCK I2S Serial Clock I/O ISDI I2S Serial Data In Input ISDO I2S Serial Data Out Output IWS I2S Word Select I/O JTAG module - JTAG TCK Test Clock Input TDI Test Data In Input TDO Test Data Out Output TMS Test Mode Select Input Power Manager - PM RESET_N Reset Input Low Pulse Width Modulation Controller - PWMA PWMA35 - PWMA0 PWMA channel waveforms Output PWMAOD35 - PWMAOD0 PWMA channel waveforms, open drain mode Output Not all channels support open drain mode System Control Interface - SCIF GCLK9 - GCLK0 Generic Clock Output Output GCLK_IN2 - GCLK_IN0 Generic Clock Input Input RC32OUT RC32K output at startup Output XIN0 Crystal 0 Input Analog/ Digital XIN32 Crystal 32 Input (primary location) Analog/ Digital XIN32_2 Crystal 32 Input (secondary location) Analog/ Digital XOUT0 Crystal 0 Output Analog XOUT32 Crystal 32 Output (primary location) Analog XOUT32_2 Crystal 32 Output (secondary location) Analog Serial Peripheral Interface - SPI MISO Master In Slave Out I/O MOSI Master Out Slave In I/O NPCS3 - NPCS0 SPI Peripheral Chip Select I/O Low SCK Clock I/O Timer/Counter - TC0, TC1 A0 Channel 0 Line A I/O A1 Channel 1 Line A I/O A2 Channel 2 Line A I/O Table 3-7. Signal Descriptions List 17 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. ADCIFB: AD3 does not exist. B0 Channel 0 Line B I/O B1 Channel 1 Line B I/O B2 Channel 2 Line B I/O CLK0 Channel 0 External Clock Input Input CLK1 Channel 1 External Clock Input Input CLK2 Channel 2 External Clock Input Input Two-wire Interface - TWIMS0, TWIMS1 TWALM SMBus SMBALERT I/O Low TWCK Two-wire Serial Clock I/O TWD Two-wire Serial Data I/O Universal Synchronous Asynchronous Receiver Transmitter - USART0, USART1, USART2, USART3 CLK Clock I/O CTS Clear To Send Input Low RTS Request To Send Output Low RXD Receive Data Input TXD Transmit Data Output Table 3-7. Signal Descriptions List Table 3-8. Signal Description List, Continued Signal Name Function Type Active Level Comments Power VDDCORE Core Power Supply / Voltage Regulator Output Power Input/Output 1.62V to 1.98V VDDIO I/O Power Supply Power Input 1.62V to 3.6V. VDDIO should always be equal to or lower than VDDIN. VDDANA Analog Power Supply Power Input 1.62V to 1.98V ADVREFP Analog Reference Voltage Power Input 1.62V to 1.98V VDDIN Voltage Regulator Input Power Input 1.62V to 3.6V(1) GNDANA Analog Ground Ground GND Ground Ground Auxiliary Port - AUX MCKO Trace Data Output Clock Output MDO5 - MDO0 Trace Data Output Output 18 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. See Section 6. on page 39 3.4 I/O Line Considerations 3.4.1 JTAG Pins The JTAG is enabled if TCK is low while the RESET_N pin is released. The TCK, TMS, and TDI pins have pull-up resistors when JTAG is enabled. The TCK pin always has pull-up enabled during reset. The TDO pin is an output, driven at VDDIO, and has no pull-up resistor. The JTAG pins can be used as GPIO pins and multiplexed with peripherals when the JTAG is disabled. Please refer to Section 3.2.3 on page 13 for the JTAG port connections. 3.4.2 PA00 Note that PA00 is multiplexed with TCK. PA00 GPIO function must only be used as output in the application. 3.4.3 RESET_N Pin The RESET_N pin is a schmitt input and integrates a permanent pull-up resistor to VDDIN. As the product integrates a power-on reset detector, the RESET_N pin can be left unconnected in case no reset from the system needs to be applied to the product. The RESET_N pin is also used for the aWire debug protocol. When the pin is used for debugging, it must not be driven by external circuitry. 3.4.4 TWI Pins PA21/PB04/PB05 When these pins are used for TWI, the pins are open-drain outputs with slew-rate limitation and inputs with spike filtering. When used as GPIO pins or used for other peripherals, the pins have the same characteristics as other GPIO pins. Selected pins are also SMBus compliant (refer to Section on page 10). As required by the SMBus specification, these pins provide no leakage path to ground when the ATUC64/128/256L3/4U is powered down. This allows other devices on the SMBus to continue communicating even though the ATUC64/128/256L3/4U is not powered. After reset a TWI function is selected on these pins instead of the GPIO. Please refer to the GPIO Module Configuration chapter for details. MSEO1 - MSEO0 Trace Frame Control Output EVTI_N Event In Input Low EVTO_N Event Out Output Low General Purpose I/O pin PA22 - PA00 Parallel I/O Controller I/O Port 0 I/O PB27 - PB00 Parallel I/O Controller I/O Port 1 I/O Table 3-8. Signal Description List, Continued Signal Name Function Type Active Level Comments 19 32142D–06/2013 ATUC64/128/256L3/4U 3.4.5 TWI Pins PA05/PA07/PA17 When these pins are used for TWI, the pins are open-drain outputs with slew-rate limitation and inputs with spike filtering. When used as GPIO pins or used for other peripherals, the pins have the same characteristics as other GPIO pins. After reset a TWI function is selected on these pins instead of the GPIO. Please refer to the GPIO Module Configuration chapter for details. 3.4.6 GPIO Pins All the I/O lines integrate a pull-up resistor Programming of this pull-up resistor is performed independently for each I/O line through the GPIO Controllers. After reset, I/O lines default as inputs with pull-up resistors disabled, except PA00 which has the pull-up resistor enabled. PA20 selects SCIF-RC32OUT (GPIO Function F) as default enabled after reset. 3.4.7 High-drive Pins The six pins PA02, PA06, PA08, PA09, PB01, and PB15 have high-drive output capabilities. Refer to Section 35. on page 897 for electrical characteristics. 3.4.8 USB Pins PB13/PB14 When these pins are used for USB, the pins are behaving according to the USB specification. When used as GPIO pins or used for other peripherals, the pins have the same behaviour as other normal I/O pins, but the characteristics are different. Refer to Section 35. on page 897 for electrical characteristics. To be able to use the USB I/O the VDDIN power supply must be 3.3V nominal. 3.4.9 RC32OUT Pin 3.4.9.1 Clock output at startup After power-up, the clock generated by the 32kHz RC oscillator (RC32K) will be output on PA20, even when the device is still reset by the Power-On Reset Circuitry. This clock can be used by the system to start other devices or to clock a switching regulator to rise the power supply voltage up to an acceptable value. The clock will be available on PA20, but will be disabled if one of the following conditions are true: • PA20 is configured to use a GPIO function other than F (SCIF-RC32OUT) • PA20 is configured as a General Purpose Input/Output (GPIO) • The bit FRC32 in the Power Manager PPCR register is written to zero (refer to the Power Manager chapter) The maximum amplitude of the clock signal will be defined by VDDIN. Once the RC32K output on PA20 is disabled it can never be enabled again. 3.4.9.2 XOUT32_2 function PA20 selects RC32OUT as default enabled after reset. This function is not automatically disabled when the user enables the XOUT32_2 function on PA20. This disturbs the oscillator and may result in the wrong frequency. To avoid this, RC32OUT must be disabled when XOUT32_2 is enabled. 20 32142D–06/2013 ATUC64/128/256L3/4U 3.4.10 ADC Input Pins These pins are regular I/O pins powered from the VDDIO. However, when these pins are used for ADC inputs, the voltage applied to the pin must not exceed 1.98V. Internal circuitry ensures that the pin cannot be used as an analog input pin when the I/O drives to VDD. When the pins are not used for ADC inputs, the pins may be driven to the full I/O voltage range. 21 32142D–06/2013 ATUC64/128/256L3/4U 4. Processor and Architecture Rev: 2.1.2.0 This chapter gives an overview of the AVR32UC CPU. AVR32UC is an implementation of the AVR32 architecture. A summary of the programming model, instruction set, and MPU is presented. For further details, see the AVR32 Architecture Manual and the AVR32UC Technical Reference Manual. 4.1 Features • 32-bit load/store AVR32A RISC architecture – 15 general-purpose 32-bit registers – 32-bit Stack Pointer, Program Counter and Link Register reside in register file – Fully orthogonal instruction set – Privileged and unprivileged modes enabling efficient and secure operating systems – Innovative instruction set together with variable instruction length ensuring industry leading code density – DSP extension with saturating arithmetic, and a wide variety of multiply instructions • 3-stage pipeline allowing one instruction per clock cycle for most instructions – Byte, halfword, word, and double word memory access – Multiple interrupt priority levels • MPU allows for operating systems with memory protection • Secure State for supporting FlashVault technology 4.2 AVR32 Architecture AVR32 is a new, high-performance 32-bit RISC microprocessor architecture, designed for costsensitive embedded applications, with particular emphasis on low power consumption and high code density. In addition, the instruction set architecture has been tuned to allow a variety of microarchitectures, enabling the AVR32 to be implemented as low-, mid-, or high-performance processors. AVR32 extends the AVR family into the world of 32- and 64-bit applications. Through a quantitative approach, a large set of industry recognized benchmarks has been compiled and analyzed to achieve the best code density in its class. In addition to lowering the memory requirements, a compact code size also contributes to the core’s low power characteristics. The processor supports byte and halfword data types without penalty in code size and performance. Memory load and store operations are provided for byte, halfword, word, and double word data with automatic sign- or zero extension of halfword and byte data. The C-compiler is closely linked to the architecture and is able to exploit code optimization features, both for size and speed. In order to reduce code size to a minimum, some instructions have multiple addressing modes. As an example, instructions with immediates often have a compact format with a smaller immediate, and an extended format with a larger immediate. In this way, the compiler is able to use the format giving the smallest code size. Another feature of the instruction set is that frequently used instructions, like add, have a compact format with two operands as well as an extended format with three operands. The larger format increases performance, allowing an addition and a data move in the same instruction in a 22 32142D–06/2013 ATUC64/128/256L3/4U single cycle. Load and store instructions have several different formats in order to reduce code size and speed up execution. The register file is organized as sixteen 32-bit registers and includes the Program Counter, the Link Register, and the Stack Pointer. In addition, register R12 is designed to hold return values from function calls and is used implicitly by some instructions. 4.3 The AVR32UC CPU The AVR32UC CPU targets low- and medium-performance applications, and provides an advanced On-Chip Debug (OCD) system, no caches, and a Memory Protection Unit (MPU). Java acceleration hardware is not implemented. AVR32UC provides three memory interfaces, one High Speed Bus master for instruction fetch, one High Speed Bus master for data access, and one High Speed Bus slave interface allowing other bus masters to access data RAMs internal to the CPU. Keeping data RAMs internal to the CPU allows fast access to the RAMs, reduces latency, and guarantees deterministic timing. Also, power consumption is reduced by not needing a full High Speed Bus access for memory accesses. A dedicated data RAM interface is provided for communicating with the internal data RAMs. A local bus interface is provided for connecting the CPU to device-specific high-speed systems, such as floating-point units and I/O controller ports. This local bus has to be enabled by writing a one to the LOCEN bit in the CPUCR system register. The local bus is able to transfer data between the CPU and the local bus slave in a single clock cycle. The local bus has a dedicated memory range allocated to it, and data transfers are performed using regular load and store instructions. Details on which devices that are mapped into the local bus space is given in the CPU Local Bus section in the Memories chapter. Figure 4-1 on page 23 displays the contents of AVR32UC. 23 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-1. Overview of the AVR32UC CPU 4.3.1 Pipeline Overview AVR32UC has three pipeline stages, Instruction Fetch (IF), Instruction Decode (ID), and Instruction Execute (EX). The EX stage is split into three parallel subsections, one arithmetic/logic (ALU) section, one multiply (MUL) section, and one load/store (LS) section. Instructions are issued and complete in order. Certain operations require several clock cycles to complete, and in this case, the instruction resides in the ID and EX stages for the required number of clock cycles. Since there is only three pipeline stages, no internal data forwarding is required, and no data dependencies can arise in the pipeline. Figure 4-2 on page 24 shows an overview of the AVR32UC pipeline stages. AVR32UC CPU pipeline Instruction memory controller MPU High Speed Bus High Speed Bus OCD systemOCD interface Interrupt controller interface High Speed Bus slave High Speed Bus High Speed Bus master Power/ Reset control Reset interface CPU Local Bus master CPU Local Bus Data memory controller CPU RAM High Speed Bus master 24 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-2. The AVR32UC Pipeline 4.3.2 AVR32A Microarchitecture Compliance AVR32UC implements an AVR32A microarchitecture. The AVR32A microarchitecture is targeted at cost-sensitive, lower-end applications like smaller microcontrollers. This microarchitecture does not provide dedicated hardware registers for shadowing of register file registers in interrupt contexts. Additionally, it does not provide hardware registers for the return address registers and return status registers. Instead, all this information is stored on the system stack. This saves chip area at the expense of slower interrupt handling. 4.3.2.1 Interrupt Handling Upon interrupt initiation, registers R8-R12 are automatically pushed to the system stack. These registers are pushed regardless of the priority level of the pending interrupt. The return address and status register are also automatically pushed to stack. The interrupt handler can therefore use R8-R12 freely. Upon interrupt completion, the old R8-R12 registers and status register are restored, and execution continues at the return address stored popped from stack. The stack is also used to store the status register and return address for exceptions and scall. Executing the rete or rets instruction at the completion of an exception or system call will pop this status register and continue execution at the popped return address. 4.3.2.2 Java Support AVR32UC does not provide Java hardware acceleration. 4.3.2.3 Memory Protection The MPU allows the user to check all memory accesses for privilege violations. If an access is attempted to an illegal memory address, the access is aborted and an exception is taken. The MPU in AVR32UC is specified in the AVR32UC Technical Reference manual. 4.3.2.4 Unaligned Reference Handling AVR32UC does not support unaligned accesses, except for doubleword accesses. AVR32UC is able to perform word-aligned st.d and ld.d. Any other unaligned memory access will cause an IF ID ALU MUL Regfile write Prefetch unit Decode unit ALU unit Multiply unit Load-store unit LS Regfile Read 25 32142D–06/2013 ATUC64/128/256L3/4U address exception. Doubleword-sized accesses with word-aligned pointers will automatically be performed as two word-sized accesses. The following table shows the instructions with support for unaligned addresses. All other instructions require aligned addresses. 4.3.2.5 Unimplemented Instructions The following instructions are unimplemented in AVR32UC, and will cause an Unimplemented Instruction Exception if executed: • All SIMD instructions • All coprocessor instructions if no coprocessors are present • retj, incjosp, popjc, pushjc • tlbr, tlbs, tlbw • cache 4.3.2.6 CPU and Architecture Revision Three major revisions of the AVR32UC CPU currently exist. The device described in this datasheet uses CPU revision 3. The Architecture Revision field in the CONFIG0 system register identifies which architecture revision is implemented in a specific device. AVR32UC CPU revision 3 is fully backward-compatible with revisions 1 and 2, ie. code compiled for revision 1 or 2 is binary-compatible with revision 3 CPUs. Table 4-1. Instructions with Unaligned Reference Support Instruction Supported Alignment ld.d Word st.d Word 26 32142D–06/2013 ATUC64/128/256L3/4U 4.4 Programming Model 4.4.1 Register File Configuration The AVR32UC register file is shown below. Figure 4-3. The AVR32UC Register File 4.4.2 Status Register Configuration The Status Register (SR) is split into two halfwords, one upper and one lower, see Figure 4-4 and Figure 4-5. The lower word contains the C, Z, N, V, and Q condition code flags and the R, T, and L bits, while the upper halfword contains information about the mode and state the processor executes in. Refer to the AVR32 Architecture Manual for details. Figure 4-4. The Status Register High Halfword Application Bit 0 Supervisor Bit 31 PC SR INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R3 R1 R2 R0 Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 INT0 SP_APP SP_SYS R12 R11 R9 R10 R8 INT1 INT2 INT3 Exception NMI LR LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SYS LR Secure Bit 31 Bit 0 PC SR R12 INT0PC FINTPC INT1PC SMPC R7 R5 R6 R4 R11 R9 R10 R8 R3 R1 R2 R0 SP_SEC LR SS_STATUS SS_ADRF SS_ADRR SS_ADR0 SS_ADR1 SS_SP_SYS SS_SP_APP SS_RAR SS_RSR Bit 31 0 0 0 Bit 16 Interrupt Level 0 Mask Interrupt Level 1 Mask Interrupt Level 3 Mask Interrupt Level 2 Mask 0 0 0 0 0 0 1 1 0 0 0 0 1 - DM D - M2 M1 M0 EM I2MFE I0M GM LC 1 SS Initial value I1M Bit name Mode Bit 0 Mode Bit 1 - Mode Bit 2 Reserved Debug State - I3M Reserved Exception Mask Global Interrupt Mask Debug State Mask Secure State 27 32142D–06/2013 ATUC64/128/256L3/4U Figure 4-5. The Status Register Low Halfword 4.4.3 Processor States 4.4.3.1 Normal RISC State The AVR32 processor supports several different execution contexts as shown in Table 4-2. Mode changes can be made under software control, or can be caused by external interrupts or exception processing. A mode can be interrupted by a higher priority mode, but never by one with lower priority. Nested exceptions can be supported with a minimal software overhead. When running an operating system on the AVR32, user processes will typically execute in the application mode. The programs executed in this mode are restricted from executing certain instructions. Furthermore, most system registers together with the upper halfword of the status register cannot be accessed. Protected memory areas are also not available. All other operating modes are privileged and are collectively called System Modes. They have full access to all privileged and unprivileged resources. After a reset, the processor will be in supervisor mode. 4.4.3.2 Debug State The AVR32 can be set in a debug state, which allows implementation of software monitor routines that can read out and alter system information for use during application development. This implies that all system and application registers, including the status registers and program counters, are accessible in debug state. The privileged instructions are also available. All interrupt levels are by default disabled when debug state is entered, but they can individually be switched on by the monitor routine by clearing the respective mask bit in the status register. Bit 15 Bit 0 Reserved Carry Zero Sign 0 0 0 0 0 0 0 0 0 0 0 0 0 0 - T - - - - Bit name 0 0 Initial value - L Q V N Z C Overflow Saturation - - - Lock Reserved Scratch Table 4-2. Overview of Execution Modes, their Priorities and Privilege Levels. Priority Mode Security Description 1 Non Maskable Interrupt Privileged Non Maskable high priority interrupt mode 2 Exception Privileged Execute exceptions 3 Interrupt 3 Privileged General purpose interrupt mode 4 Interrupt 2 Privileged General purpose interrupt mode 5 Interrupt 1 Privileged General purpose interrupt mode 6 Interrupt 0 Privileged General purpose interrupt mode N/A Supervisor Privileged Runs supervisor calls N/A Application Unprivileged Normal program execution mode 28 32142D–06/2013 ATUC64/128/256L3/4U Debug state can be entered as described in the AVR32UC Technical Reference Manual. Debug state is exited by the retd instruction. 4.4.3.3 Secure State The AVR32 can be set in a secure state, that allows a part of the code to execute in a state with higher security levels. The rest of the code can not access resources reserved for this secure code. Secure State is used to implement FlashVault technology. Refer to the AVR32UC Technical Reference Manual for details. 4.4.4 System Registers The system registers are placed outside of the virtual memory space, and are only accessible using the privileged mfsr and mtsr instructions. The table below lists the system registers specified in the AVR32 architecture, some of which are unused in AVR32UC. The programmer is responsible for maintaining correct sequencing of any instructions following a mtsr instruction. For detail on the system registers, refer to the AVR32UC Technical Reference Manual. Table 4-3. System Registers Reg # Address Name Function 0 0 SR Status Register 1 4 EVBA Exception Vector Base Address 2 8 ACBA Application Call Base Address 3 12 CPUCR CPU Control Register 4 16 ECR Exception Cause Register 5 20 RSR_SUP Unused in AVR32UC 6 24 RSR_INT0 Unused in AVR32UC 7 28 RSR_INT1 Unused in AVR32UC 8 32 RSR_INT2 Unused in AVR32UC 9 36 RSR_INT3 Unused in AVR32UC 10 40 RSR_EX Unused in AVR32UC 11 44 RSR_NMI Unused in AVR32UC 12 48 RSR_DBG Return Status Register for Debug mode 13 52 RAR_SUP Unused in AVR32UC 14 56 RAR_INT0 Unused in AVR32UC 15 60 RAR_INT1 Unused in AVR32UC 16 64 RAR_INT2 Unused in AVR32UC 17 68 RAR_INT3 Unused in AVR32UC 18 72 RAR_EX Unused in AVR32UC 19 76 RAR_NMI Unused in AVR32UC 20 80 RAR_DBG Return Address Register for Debug mode 21 84 JECR Unused in AVR32UC 22 88 JOSP Unused in AVR32UC 23 92 JAVA_LV0 Unused in AVR32UC 29 32142D–06/2013 ATUC64/128/256L3/4U 24 96 JAVA_LV1 Unused in AVR32UC 25 100 JAVA_LV2 Unused in AVR32UC 26 104 JAVA_LV3 Unused in AVR32UC 27 108 JAVA_LV4 Unused in AVR32UC 28 112 JAVA_LV5 Unused in AVR32UC 29 116 JAVA_LV6 Unused in AVR32UC 30 120 JAVA_LV7 Unused in AVR32UC 31 124 JTBA Unused in AVR32UC 32 128 JBCR Unused in AVR32UC 33-63 132-252 Reserved Reserved for future use 64 256 CONFIG0 Configuration register 0 65 260 CONFIG1 Configuration register 1 66 264 COUNT Cycle Counter register 67 268 COMPARE Compare register 68 272 TLBEHI Unused in AVR32UC 69 276 TLBELO Unused in AVR32UC 70 280 PTBR Unused in AVR32UC 71 284 TLBEAR Unused in AVR32UC 72 288 MMUCR Unused in AVR32UC 73 292 TLBARLO Unused in AVR32UC 74 296 TLBARHI Unused in AVR32UC 75 300 PCCNT Unused in AVR32UC 76 304 PCNT0 Unused in AVR32UC 77 308 PCNT1 Unused in AVR32UC 78 312 PCCR Unused in AVR32UC 79 316 BEAR Bus Error Address Register 80 320 MPUAR0 MPU Address Register region 0 81 324 MPUAR1 MPU Address Register region 1 82 328 MPUAR2 MPU Address Register region 2 83 332 MPUAR3 MPU Address Register region 3 84 336 MPUAR4 MPU Address Register region 4 85 340 MPUAR5 MPU Address Register region 5 86 344 MPUAR6 MPU Address Register region 6 87 348 MPUAR7 MPU Address Register region 7 88 352 MPUPSR0 MPU Privilege Select Register region 0 89 356 MPUPSR1 MPU Privilege Select Register region 1 Table 4-3. System Registers (Continued) Reg # Address Name Function 30 32142D–06/2013 ATUC64/128/256L3/4U 4.5 Exceptions and Interrupts In the AVR32 architecture, events are used as a common term for exceptions and interrupts. AVR32UC incorporates a powerful event handling scheme. The different event sources, like Illegal Op-code and interrupt requests, have different priority levels, ensuring a well-defined behavior when multiple events are received simultaneously. Additionally, pending events of a higher priority class may preempt handling of ongoing events of a lower priority class. When an event occurs, the execution of the instruction stream is halted, and execution is passed to an event handler at an address specified in Table 4-4 on page 34. Most of the handlers are placed sequentially in the code space starting at the address specified by EVBA, with four bytes between each handler. This gives ample space for a jump instruction to be placed there, jumping to the event routine itself. A few critical handlers have larger spacing between them, allowing the entire event routine to be placed directly at the address specified by the EVBA-relative offset generated by hardware. All interrupt sources have autovectored interrupt service routine (ISR) addresses. This allows the interrupt controller to directly specify the ISR address as an address 90 360 MPUPSR2 MPU Privilege Select Register region 2 91 364 MPUPSR3 MPU Privilege Select Register region 3 92 368 MPUPSR4 MPU Privilege Select Register region 4 93 372 MPUPSR5 MPU Privilege Select Register region 5 94 376 MPUPSR6 MPU Privilege Select Register region 6 95 380 MPUPSR7 MPU Privilege Select Register region 7 96 384 MPUCRA Unused in this version of AVR32UC 97 388 MPUCRB Unused in this version of AVR32UC 98 392 MPUBRA Unused in this version of AVR32UC 99 396 MPUBRB Unused in this version of AVR32UC 100 400 MPUAPRA MPU Access Permission Register A 101 404 MPUAPRB MPU Access Permission Register B 102 408 MPUCR MPU Control Register 103 412 SS_STATUS Secure State Status Register 104 416 SS_ADRF Secure State Address Flash Register 105 420 SS_ADRR Secure State Address RAM Register 106 424 SS_ADR0 Secure State Address 0 Register 107 428 SS_ADR1 Secure State Address 1 Register 108 432 SS_SP_SYS Secure State Stack Pointer System Register 109 436 SS_SP_APP Secure State Stack Pointer Application Register 110 440 SS_RAR Secure State Return Address Register 111 444 SS_RSR Secure State Return Status Register 112-191 448-764 Reserved Reserved for future use 192-255 768-1020 IMPL IMPLEMENTATION DEFINED Table 4-3. System Registers (Continued) Reg # Address Name Function 31 32142D–06/2013 ATUC64/128/256L3/4U relative to EVBA. The autovector offset has 14 address bits, giving an offset of maximum 16384 bytes. The target address of the event handler is calculated as (EVBA | event_handler_offset), not (EVBA + event_handler_offset), so EVBA and exception code segments must be set up appropriately. The same mechanisms are used to service all different types of events, including interrupt requests, yielding a uniform event handling scheme. An interrupt controller does the priority handling of the interrupts and provides the autovector offset to the CPU. 4.5.1 System Stack Issues Event handling in AVR32UC uses the system stack pointed to by the system stack pointer, SP_SYS, for pushing and popping R8-R12, LR, status register, and return address. Since event code may be timing-critical, SP_SYS should point to memory addresses in the IRAM section, since the timing of accesses to this memory section is both fast and deterministic. The user must also make sure that the system stack is large enough so that any event is able to push the required registers to stack. If the system stack is full, and an event occurs, the system will enter an UNDEFINED state. 4.5.2 Exceptions and Interrupt Requests When an event other than scall or debug request is received by the core, the following actions are performed atomically: 1. The pending event will not be accepted if it is masked. The I3M, I2M, I1M, I0M, EM, and GM bits in the Status Register are used to mask different events. Not all events can be masked. A few critical events (NMI, Unrecoverable Exception, TLB Multiple Hit, and Bus Error) can not be masked. When an event is accepted, hardware automatically sets the mask bits corresponding to all sources with equal or lower priority. This inhibits acceptance of other events of the same or lower priority, except for the critical events listed above. Software may choose to clear some or all of these bits after saving the necessary state if other priority schemes are desired. It is the event source’s responsability to ensure that their events are left pending until accepted by the CPU. 2. When a request is accepted, the Status Register and Program Counter of the current context is stored to the system stack. If the event is an INT0, INT1, INT2, or INT3, registers R8-R12 and LR are also automatically stored to stack. Storing the Status Register ensures that the core is returned to the previous execution mode when the current event handling is completed. When exceptions occur, both the EM and GM bits are set, and the application may manually enable nested exceptions if desired by clearing the appropriate bit. Each exception handler has a dedicated handler address, and this address uniquely identifies the exception source. 3. The Mode bits are set to reflect the priority of the accepted event, and the correct register file bank is selected. The address of the event handler, as shown in Table 4-4 on page 34, is loaded into the Program Counter. The execution of the event handler routine then continues from the effective address calculated. The rete instruction signals the end of the event. When encountered, the Return Status Register and Return Address Register are popped from the system stack and restored to the Status Register and Program Counter. If the rete instruction returns from INT0, INT1, INT2, or INT3, registers R8-R12 and LR are also popped from the system stack. The restored Status Register contains information allowing the core to resume operation in the previous execution mode. This concludes the event handling. 32 32142D–06/2013 ATUC64/128/256L3/4U 4.5.3 Supervisor Calls The AVR32 instruction set provides a supervisor mode call instruction. The scall instruction is designed so that privileged routines can be called from any context. This facilitates sharing of code between different execution modes. The scall mechanism is designed so that a minimal execution cycle overhead is experienced when performing supervisor routine calls from timecritical event handlers. The scall instruction behaves differently depending on which mode it is called from. The behaviour is detailed in the instruction set reference. In order to allow the scall routine to return to the correct context, a return from supervisor call instruction, rets, is implemented. In the AVR32UC CPU, scall and rets uses the system stack to store the return address and the status register. 4.5.4 Debug Requests The AVR32 architecture defines a dedicated Debug mode. When a debug request is received by the core, Debug mode is entered. Entry into Debug mode can be masked by the DM bit in the status register. Upon entry into Debug mode, hardware sets the SR.D bit and jumps to the Debug Exception handler. By default, Debug mode executes in the exception context, but with dedicated Return Address Register and Return Status Register. These dedicated registers remove the need for storing this data to the system stack, thereby improving debuggability. The Mode bits in the Status Register can freely be manipulated in Debug mode, to observe registers in all contexts, while retaining full privileges. Debug mode is exited by executing the retd instruction. This returns to the previous context. 4.5.5 Entry Points for Events Several different event handler entry points exist. In AVR32UC, the reset address is 0x80000000. This places the reset address in the boot flash memory area. TLB miss exceptions and scall have a dedicated space relative to EVBA where their event handler can be placed. This speeds up execution by removing the need for a jump instruction placed at the program address jumped to by the event hardware. All other exceptions have a dedicated event routine entry point located relative to EVBA. The handler routine address identifies the exception source directly. AVR32UC uses the ITLB and DTLB protection exceptions to signal a MPU protection violation. ITLB and DTLB miss exceptions are used to signal that an access address did not map to any of the entries in the MPU. TLB multiple hit exception indicates that an access address did map to multiple TLB entries, signalling an error. All interrupt requests have entry points located at an offset relative to EVBA. This autovector offset is specified by an interrupt controller. The programmer must make sure that none of the autovector offsets interfere with the placement of other code. The autovector offset has 14 address bits, giving an offset of maximum 16384 bytes. Special considerations should be made when loading EVBA with a pointer. Due to security considerations, the event handlers should be located in non-writeable flash memory, or optionally in a privileged memory protection region if an MPU is present. If several events occur on the same instruction, they are handled in a prioritized way. The priority ordering is presented in Table 4-4 on page 34. If events occur on several instructions at different locations in the pipeline, the events on the oldest instruction are always handled before any events on any younger instruction, even if the younger instruction has events of higher priority 33 32142D–06/2013 ATUC64/128/256L3/4U than the oldest instruction. An instruction B is younger than an instruction A if it was sent down the pipeline later than A. The addresses and priority of simultaneous events are shown in Table 4-4 on page 34. Some of the exceptions are unused in AVR32UC since it has no MMU, coprocessor interface, or floatingpoint unit. 34 32142D–06/2013 ATUC64/128/256L3/4U Table 4-4. Priority and Handler Addresses for Events Priority Handler Address Name Event source Stored Return Address 1 0x80000000 Reset External input Undefined 2 Provided by OCD system OCD Stop CPU OCD system First non-completed instruction 3 EVBA+0x00 Unrecoverable exception Internal PC of offending instruction 4 EVBA+0x04 TLB multiple hit MPU PC of offending instruction 5 EVBA+0x08 Bus error data fetch Data bus First non-completed instruction 6 EVBA+0x0C Bus error instruction fetch Data bus First non-completed instruction 7 EVBA+0x10 NMI External input First non-completed instruction 8 Autovectored Interrupt 3 request External input First non-completed instruction 9 Autovectored Interrupt 2 request External input First non-completed instruction 10 Autovectored Interrupt 1 request External input First non-completed instruction 11 Autovectored Interrupt 0 request External input First non-completed instruction 12 EVBA+0x14 Instruction Address CPU PC of offending instruction 13 EVBA+0x50 ITLB Miss MPU PC of offending instruction 14 EVBA+0x18 ITLB Protection MPU PC of offending instruction 15 EVBA+0x1C Breakpoint OCD system First non-completed instruction 16 EVBA+0x20 Illegal Opcode Instruction PC of offending instruction 17 EVBA+0x24 Unimplemented instruction Instruction PC of offending instruction 18 EVBA+0x28 Privilege violation Instruction PC of offending instruction 19 EVBA+0x2C Floating-point UNUSED 20 EVBA+0x30 Coprocessor absent Instruction PC of offending instruction 21 EVBA+0x100 Supervisor call Instruction PC(Supervisor Call) +2 22 EVBA+0x34 Data Address (Read) CPU PC of offending instruction 23 EVBA+0x38 Data Address (Write) CPU PC of offending instruction 24 EVBA+0x60 DTLB Miss (Read) MPU PC of offending instruction 25 EVBA+0x70 DTLB Miss (Write) MPU PC of offending instruction 26 EVBA+0x3C DTLB Protection (Read) MPU PC of offending instruction 27 EVBA+0x40 DTLB Protection (Write) MPU PC of offending instruction 28 EVBA+0x44 DTLB Modified UNUSED 35 32142D–06/2013 ATUC64/128/256L3/4U 5. Memories 5.1 Embedded Memories • Internal high-speed flash – 256Kbytes (ATUC256L3U, ATUC256L4U) – 128Kbytes (ATUC128L3U, ATUC128L4U) – 64Kbytes (ATUC64L3U, ATUC64L4U) • 0 wait state access at up to 25MHz in worst case conditions • 1 wait state access at up to 50MHz in worst case conditions • Pipelined flash architecture, allowing burst reads from sequential flash locations, hiding penalty of 1 wait state access • Pipelined flash architecture typically reduces the cycle penalty of 1 wait state operation to only 8% compared to 0 wait state operation • 100 000 write cycles, 15-year data retention capability • Sector lock capabilities, bootloader protection, security bit • 32 fuses, erased during chip erase • User page for data to be preserved during chip erase • Internal high-speed SRAM, single-cycle access at full speed – 32Kbytes (ATUC256L3U, ATUC256L4U, ATUC128L3U, ATUC128L4U) – 16Kbytes (ATUC64L3U, ATUC64L4U) 5.2 Physical Memory Map The system bus is implemented as a bus matrix. All system bus addresses are fixed, and they are never remapped in any way, not even during boot. Note that AVR32 UC CPU uses unsegmented translation, as described in the AVR32 Architecture Manual. The 32-bit physical address space is mapped as follows: Table 5-1. ATUC64/128/256L3/4U Physical Memory Map Memory Start Address Size ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U Embedded SRAM 0x00000000 32Kbytes 32Kbytes 16Kbytes Embedded Flash 0x80000000 256Kbytes 128Kbytes 64Kbytes SAU Channels 0x90000000 256 bytes 256 bytes 256 bytes HSB-PB Bridge B 0xFFFE0000 64Kbytes 64Kbytes 64Kbytes HSB-PB Bridge A 0xFFFF0000 64Kbytes 64Kbytes 64Kbytes Table 5-2. Flash Memory Parameters Device Flash Size (FLASH_PW) Number of Pages (FLASH_P) Page Size (FLASH_W) ATUC256L3U, ATUC256L4U 256Kbytes 512 512 bytes ATUC128L3U, ATUC128L4U 128Kbytes 256 512 bytes ATUC64L3U, ATUC64L4U 64Kbytes 128 512 bytes 36 32142D–06/2013 ATUC64/128/256L3/4U 5.3 Peripheral Address Map Table 5-3. Peripheral Address Mapping Address Peripheral Name 0xFFFE0000 FLASHCDW Flash Controller - FLASHCDW 0xFFFE0400 HMATRIX HSB Matrix - HMATRIX 0xFFFE0800 SAU Secure Access Unit - SAU 0xFFFE1000 USBC USB 2.0 Interface - USBC 0xFFFF0000 PDCA Peripheral DMA Controller - PDCA 0xFFFF1000 INTC Interrupt controller - INTC 0xFFFF1400 PM Power Manager - PM 0xFFFF1800 SCIF System Control Interface - SCIF 0xFFFF1C00 AST Asynchronous Timer - AST 0xFFFF2000 WDT Watchdog Timer - WDT 0xFFFF2400 EIC External Interrupt Controller - EIC 0xFFFF2800 FREQM Frequency Meter - FREQM 0xFFFF2C00 GPIO General-Purpose Input/Output Controller - GPIO 0xFFFF3000 USART0 Universal Synchronous Asynchronous Receiver Transmitter - USART0 0xFFFF3400 USART1 Universal Synchronous Asynchronous Receiver Transmitter - USART1 0xFFFF3800 USART2 Universal Synchronous Asynchronous Receiver Transmitter - USART2 0xFFFF3C00 USART3 Universal Synchronous Asynchronous Receiver Transmitter - USART3 0xFFFF4000 SPI Serial Peripheral Interface - SPI 37 32142D–06/2013 ATUC64/128/256L3/4U 5.4 CPU Local Bus Mapping Some of the registers in the GPIO module are mapped onto the CPU local bus, in addition to being mapped on the Peripheral Bus. These registers can therefore be reached both by accesses on the Peripheral Bus, and by accesses on the local bus. Mapping these registers on the local bus allows cycle-deterministic toggling of GPIO pins since the CPU and GPIO are the only modules connected to this bus. Also, since the local bus runs at CPU speed, one write or read operation can be performed per clock cycle to the local busmapped GPIO registers. 0xFFFF4400 TWIM0 Two-wire Master Interface - TWIM0 0xFFFF4800 TWIM1 Two-wire Master Interface - TWIM1 0xFFFF4C00 TWIS0 Two-wire Slave Interface - TWIS0 0xFFFF5000 TWIS1 Two-wire Slave Interface - TWIS1 0xFFFF5400 PWMA Pulse Width Modulation Controller - PWMA 0xFFFF5800 TC0 Timer/Counter - TC0 0xFFFF5C00 TC1 Timer/Counter - TC1 0xFFFF6000 ADCIFB ADC Interface - ADCIFB 0xFFFF6400 ACIFB Analog Comparator Interface - ACIFB 0xFFFF6800 CAT Capacitive Touch Module - CAT 0xFFFF6C00 GLOC Glue Logic Controller - GLOC 0xFFFF7000 AW aWire - AW 0xFFFF7400 ABDACB Audio Bitstream DAC - ABDACB 0xFFFF7800 IISC Inter-IC Sound (I2S) Controller - IISC Table 5-3. Peripheral Address Mapping 38 32142D–06/2013 ATUC64/128/256L3/4U The following GPIO registers are mapped on the local bus: Table 5-4. Local Bus Mapped GPIO Registers Port Register Mode Local Bus Address Access 0 Output Driver Enable Register (ODER) WRITE 0x40000040 Write-only SET 0x40000044 Write-only CLEAR 0x40000048 Write-only TOGGLE 0x4000004C Write-only Output Value Register (OVR) WRITE 0x40000050 Write-only SET 0x40000054 Write-only CLEAR 0x40000058 Write-only TOGGLE 0x4000005C Write-only Pin Value Register (PVR) - 0x40000060 Read-only 1 Output Driver Enable Register (ODER) WRITE 0x40000140 Write-only SET 0x40000144 Write-only CLEAR 0x40000148 Write-only TOGGLE 0x4000014C Write-only Output Value Register (OVR) WRITE 0x40000150 Write-only SET 0x40000154 Write-only CLEAR 0x40000158 Write-only TOGGLE 0x4000015C Write-only Pin Value Register (PVR) - 0x40000160 Read-only 39 32142D–06/2013 ATUC64/128/256L3/4U 6. Supply and Startup Considerations 6.1 Supply Considerations 6.1.1 Power Supplies The ATUC64/128/256L3/4U has several types of power supply pins: • VDDIO: Powers I/O lines. Voltage is 1.8 to 3.3V nominal. • VDDIN: Powers I/O lines, the USB pins, and the internal regulator. Voltage is 1.8 to 3.3V nominal if USB is not used, and 3.3V nominal when USB is used. • VDDANA: Powers the ADC. Voltage is 1.8V nominal. • VDDCORE: Powers the core, memories, and peripherals. Voltage is 1.8V nominal. The ground pins GND are common to VDDCORE, VDDIO, and VDDIN. The ground pin for VDDANA is GNDANA. When VDDCORE is not connected to VDDIN, the VDDIN voltage must be higher than 1.98V. Refer to Section 35. on page 897 for power consumption on the various supply pins. For decoupling recommendations for the different power supplies, please refer to the schematic checklist. Refer to Section on page 10 for power supply connections for I/O pins. 6.1.2 Voltage Regulator The ATUC64/128/256L3/4U embeds a voltage regulator that converts from 3.3V nominal to 1.8V with a load of up to 60 mA. The regulator supplies the output voltage on VDDCORE. The regulator may only be used to drive internal circuitry in the device. VDDCORE should be externally connected to the 1.8V domains. See Section 6.1.3 for regulator connection figures. Adequate output supply decoupling is mandatory for VDDCORE to reduce ripple and avoid oscillations. The best way to achieve this is to use two capacitors in parallel between VDDCORE and GND as close to the device as possible. Please refer to Section 35.8 on page 911 for decoupling capacitors values and regulator characteristics. Figure 6-1. Supply Decoupling. The voltage regulator can be turned off in the shutdown mode to power down the core logic and keep a small part of the system powered in order to reduce power consumption. To enter this mode the 3.3V supply mode, with 1.8V regulated I/O lines power supply configuration must be used. 3.3V 1.8V VDDIN VDDCORE 1.8V Regulator CIN1 COUT1 COUT2 C IN3 IN2 C 40 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3 Regulator Connection The ATUC64/128/256L3/4U supports three power supply configurations: • 3.3V single supply mode – Shutdown mode is not available • 1.8V single supply mode – Shutdown mode is not available • 3.3V supply mode, with 1.8V regulated I/O lines – Shutdown mode is available 41 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.1 3.3V Single Supply Mode In 3.3V single supply mode the internal regulator is connected to the 3.3V source (VDDIN pin) and its output feeds VDDCORE. Figure 6-2 shows the power schematics to be used for 3.3V single supply mode. All I/O lines will be powered by the same power (VDDIN=VDDIO). Figure 6-2. 3.3V Single Supply Mode VDDIO VDDCORE + - 1.98-3.6V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control Linear regulator 42 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.2 1.8V Single Supply Mode In 1.8V single supply mode the internal regulator is not used, and VDDIO and VDDCORE are powered by a single 1.8V supply as shown in Figure 6-3. All I/O lines will be powered by the same power (VDDIN = VDDIO = VDDCORE). Figure 6-3. 1.8V Single Supply Mode VDDIO VDDCORE + - 1.62-1.98V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control 43 32142D–06/2013 ATUC64/128/256L3/4U 6.1.3.3 3.3V Supply Mode with 1.8V Regulated I/O Lines In this mode, the internal regulator is connected to the 3.3V source and its output is connected to both VDDCORE and VDDIO as shown in Figure 6-4. This configuration is required in order to use Shutdown mode. Figure 6-4. 3.3V Supply Mode with 1.8V Regulated I/O Lines In this mode, some I/O lines are powered by VDDIN while other I/O lines are powered by VDDIO. Refer to Section on page 10 for description of power supply for each I/O line. Refer to the Power Manager chapter for a description of what parts of the system are powered in Shutdown mode. Important note: As the regulator has a maximum output current of 60 mA, this mode can only be used in applications where the maximum I/O current is known and compatible with the core and peripheral power consumption. Typically, great care must be used to ensure that only a few I/O lines are toggling at the same time and drive very small loads. VDDIO VDDCORE + - 1.98-3.6V VDDANA ADC VDDIN GND GNDANA CPU, Peripherals, Memories, SCIF, BOD, RCSYS, DFLL, PLL OSC32K, RC32K, POR33, SM33 I/O Pins I/O Pins OSC32K_2, AST, Wake, Regulator control Linear regulator 44 32142D–06/2013 ATUC64/128/256L3/4U 6.1.4 Power-up Sequence 6.1.4.1 Maximum Rise Rate To avoid risk of latch-up, the rise rate of the power supplies must not exceed the values described in Table 35-3 on page 898. Recommended order for power supplies is also described in this chapter. 6.1.4.2 Minimum Rise Rate The integrated Power-on Reset (POR33) circuitry monitoring the VDDIN powering supply requires a minimum rise rate for the VDDIN power supply. See Table 35-3 on page 898 for the minimum rise rate value. If the application can not ensure that the minimum rise rate condition for the VDDIN power supply is met, one of the following configurations can be used: • A logic “0” value is applied during power-up on pin PA11 (WAKE_N) until VDDIN rises above 1.2V. • A logic “0” value is applied during power-up on pin RESET_N until VDDIN rises above 1.2V. 6.2 Startup Considerations This chapter summarizes the boot sequence of the ATUC64/128/256L3/4U. The behavior after power-up is controlled by the Power Manager. For specific details, refer to the Power Manager chapter. 6.2.1 Starting of Clocks After power-up, the device will be held in a reset state by the Power-on Reset (POR18 and POR33) circuitry for a short time to allow the power to stabilize throughout the device. After reset, the device will use the System RC Oscillator (RCSYS) as clock source. Please refer to Table 35-17 on page 910 for the frequency for this oscillator. On system start-up, all high-speed clocks are disabled. All clocks to all modules are running. No clocks have a divided frequency; all parts of the system receive a clock with the same frequency as the System RC Oscillator. When powering up the device, there may be a delay before the voltage has stabilized, depending on the rise time of the supply used. The CPU can start executing code as soon as the supply is above the POR18 and POR33 thresholds, and before the supply is stable. Before switching to a high-speed clock source, the user should use the BOD to make sure the VDDCORE is above the minimum level (1.62V). 6.2.2 Fetching of Initial Instructions After reset has been released, the AVR32 UC CPU starts fetching instructions from the reset address, which is 0x80000000. This address points to the first address in the internal Flash. The code read from the internal flash is free to configure the clock system and clock sources. Please refer to the PM and SCIF chapters for more details. 45 32142D–06/2013 ATUC64/128/256L3/4U 7. Peripheral DMA Controller (PDCA) Rev: 1.2.3.1 7.1 Features • Multiple channels • Generates transfers between memories and peripherals such as USART and SPI • Two address pointers/counters per channel allowing double buffering • Performance monitors to measure average and maximum transfer latency • Optional synchronizing of data transfers with extenal peripheral events • Ring buffer functionality 7.2 Overview The Peripheral DMA Controller (PDCA) transfers data between on-chip peripheral modules such as USART, SPI and memories (those memories may be on- and off-chip memories). Using the PDCA avoids CPU intervention for data transfers, improving the performance of the microcontroller. The PDCA can transfer data from memory to a peripheral or from a peripheral to memory. The PDCA consists of multiple DMA channels. Each channel has: • A Peripheral Select Register • A 32-bit memory pointer • A 16-bit transfer counter • A 32-bit memory pointer reload value • A 16-bit transfer counter reload value The PDCA communicates with the peripheral modules over a set of handshake interfaces. The peripheral signals the PDCA when it is ready to receive or transmit data. The PDCA acknowledges the request when the transmission has started. When a transmit buffer is empty or a receive buffer is full, an optional interrupt request can be generated. 46 32142D–06/2013 ATUC64/128/256L3/4U 7.3 Block Diagram Figure 7-1. PDCA Block Diagram 7.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 7.4.1 Power Management If the CPU enters a sleep mode that disables the PDCA clocks, the PDCA will stop functioning and resume operation after the system wakes up from sleep mode. 7.4.2 Clocks The PDCA has two bus clocks connected: One High Speed Bus clock (CLK_PDCA_HSB) and one Peripheral Bus clock (CLK_PDCA_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the PDCA before disabling the clocks, to avoid freezing the PDCA in an undefined state. 7.4.3 Interrupts The PDCA interrupt request lines are connected to the interrupt controller. Using the PDCA interrupts requires the interrupt controller to be programmed first. HSB to PB Bridge Peripheral DMA Controller (PDCA) Peripheral 0 High Speed Bus Matrix Handshake Interfaces Peripheral Bus IRQ HSB HSB Interrupt Controller Peripheral 1 Peripheral 2 Peripheral (n-1) ... Memory HSB 47 32142D–06/2013 ATUC64/128/256L3/4U 7.4.4 Peripheral Events The PDCA peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 7.5 Functional Description 7.5.1 Basic Operation The PDCA consists of multiple independent PDCA channels, each capable of handling DMA requests in parallel. Each PDCA channels contains a set of configuration registers which must be configured to start a DMA transfer. In this section the steps necessary to configure one PDCA channel is outlined. The peripheral to transfer data to or from must be configured correctly in the Peripheral Select Register (PSR). This is performed by writing the Peripheral Identity (PID) value for the corresponding peripheral to the PID field in the PSR register. The PID also encodes the transfer direction, i.e. memory to peripheral or peripheral to memory. See Section 7.5.6. The transfer size must be written to the Transfer Size field in the Mode Register (MR.SIZE). The size must match the data size produced or consumed by the selected peripheral. See Section 7.5.7. The memory address to transfer to or from, depending on the PSR, must be written to the Memory Address Register (MAR). For each transfer the memory address is increased by either a one, two or four, depending on the size set in MR. See Section 7.5.2. The number of data items to transfer is written to the TCR register. If the PDCA channel is enabled, a transfer will start immediately after writing a non-zero value to TCR or the reload version of TCR, TCRR. After each transfer the TCR value is decreased by one. Both MAR and TCR can be read while the PDCA channel is active to monitor the DMA progress. See Section 7.5.3. The channel must be enabled for a transfer to start. A channel is enable by writing a one to the EN bit in the Control Register (CR). 7.5.2 Memory Pointer Each channel has a 32-bit Memory Address Register (MAR). This register holds the memory address for the next transfer to be performed. The register is automatically updated after each transfer. The address will be increased by either one, two or four depending on the size of the DMA transfer (byte, halfword or word). The MAR can be read at any time during transfer. 7.5.3 Transfer Counter Each channel has a 16-bit Transfer Counter Register (TCR). This register must be written with the number of transfers to be performed. The TCR register should contain the number of data items to be transferred independently of the transfer size. The TCR can be read at any time during transfer to see the number of remaining transfers. 7.5.4 Reload Registers Both the MAR and the TCR have a reload register, respectively Memory Address Reload Register (MARR) and Transfer Counter Reload Register (TCRR). These registers provide the possibility for the PDCA to work on two memory buffers for each channel. When one buffer has completed, MAR and TCR will be reloaded with the values in MARR and TCRR. The reload logic is always enabled and will trigger if the TCR reaches zero while TCRR holds a non-zero value. After reload, the MARR and TCRR registers are cleared. 48 32142D–06/2013 ATUC64/128/256L3/4U If TCR is zero when writing to TCRR, the TCR and MAR are automatically updated with the value written in TCRR and MARR. 7.5.5 Ring Buffer When Ring Buffer mode is enabled the TCRR and MARR registers will not be cleared when TCR and MAR registers reload. This allows the PDCA to read or write to the same memory region over and over again until the transfer is actively stopped by the user. Ring Buffer mode is enabled by writing a one to the Ring Buffer bit in the Mode Register (MR.RING). 7.5.6 Peripheral Selection The Peripheral Select Register (PSR) decides which peripheral should be connected to the PDCA channel. A peripheral is selected by writing the corresponding Peripheral Identity (PID) to the PID field in the PSR register. Writing the PID will both select the direction of the transfer (memory to peripheral or peripheral to memory), which handshake interface to use, and the address of the peripheral holding register. Refer to the Peripheral Identity (PID) table in the Module Configuration section for the peripheral PID values. 7.5.7 Transfer Size The transfer size can be set individually for each channel to be either byte, halfword or word (8- bit, 16-bit or 32-bit respectively). Transfer size is set by writing the desired value to the Transfer Size field in the Mode Register (MR.SIZE). When the PDCA moves data between peripherals and memory, data is automatically sized and aligned. When memory is accessed, the size specified in MR.SIZE and system alignment is used. When a peripheral register is accessed the data to be transferred is converted to a word where bit n in the data corresponds to bit n in the peripheral register. If the transfer size is byte or halfword, bits greater than 8 and16 respectively are set to zero. Refer to the Module Configuration section for information regarding what peripheral registers are used for the different peripherals and then to the peripheral specific chapter for information about the size option available for the different registers. 7.5.8 Enabling and Disabling Each DMA channel is enabled by writing a one to the Transfer Enable bit in the Control Register (CR.TEN) and disabled by writing a one to the Transfer Disable bit (CR.TDIS). The current status can be read from the Status Register (SR). While the PDCA channel is enabled all DMA request will be handled as long the TCR and TCRR is not zero. 7.5.9 Interrupts Interrupts can be enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER) and disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The Interrupt Mask Register (IMR) can be read to see whether an interrupt is enabled or not. The current status of an interrupt source can be read through the Interrupt Status Register (ISR). The PDCA has three interrupt sources: • Reload Counter Zero - The TCRR register is zero. • Transfer Finished - Both the TCR and TCRR registers are zero. • Transfer Error - An error has occurred in accessing memory. 49 32142D–06/2013 ATUC64/128/256L3/4U 7.5.10 Priority If more than one PDCA channel is requesting transfer at a given time, the PDCA channels are prioritized by their channel number. Channels with lower numbers have priority over channels with higher numbers, giving channel zero the highest priority. 7.5.11 Error Handling If the Memory Address Register (MAR) is set to point to an invalid location in memory, an error will occur when the PDCA tries to perform a transfer. When an error occurs, the Transfer Error bit in the Interrupt Status Register (ISR.TERR) will be set and the DMA channel that caused the error will be stopped. In order to restart the channel, the user must program the Memory Address Register to a valid address and then write a one to the Error Clear bit in the Control Register (CR.ECLR). If the Transfer Error interrupt is enabled, an interrupt request will be generated when a transfer error occurs. 7.5.12 Peripheral Event Trigger Peripheral events can be used to trigger PDCA channel transfers. Peripheral Event synchronizations are enabled by writing a one to the Event Trigger bit in the Mode Register (MR.ETRIG). When set, all DMA requests will be blocked until a peripheral event is received. For each peripheral event received, only one data item is transferred. If no DMA requests are pending when a peripheral event is received, the PDCA will start a transfer as soon as a peripheral event is detected. If multiple events are received while the PDCA channel is busy transferring data, an overflow condition will be signaled in the Peripheral Event System. Refer to the Peripheral Event System chapter for more information. 7.6 Performance Monitors Up to two performance monitors allow the user to measure the activity and stall cycles for PDCA transfers. To monitor a PDCA channel, the corresponding channel number must be written to one of the MON0/1CH fields in the Performance Control Register (PCONTROL) and a one must be written to the corresponding CH0/1EN bit in the same register. Due to performance monitor hardware resource sharing, the two monitor channels should NOT be programmed to monitor the same PDCA channel. This may result in UNDEFINED performance monitor behavior. 7.6.1 Measuring mechanisms Three different parameters can be measured by each channel: • The number of data transfer cycles since last channel reset, both for read and write • The number of stall cycles since last channel reset, both for read and write • The maximum latency since last channel reset, both for read and write These measurements can be extracted by software and used to generate indicators for bus latency, bus load, and maximum bus latency. Each of the counters has a fixed width, and may therefore overflow. When an overflow is encountered in either the Performance Channel Data Read/Write Cycle registers (PRDATA0/1 and PWDATA0/1) or the Performance Channel Read/Write Stall Cycles registers (PRSTALL0/1 and PWSTALL0/1) of a channel, all registers in the channel are reset. This behavior is altered if the Channel Overflow Freeze bit is one in the Performance Control register (PCONTROL.CH0/1OVF). If this bit is one, the channel registers are frozen when either DATA or STALL reaches its maximum value. This simplifies one-shot readout of the counter values. 50 32142D–06/2013 ATUC64/128/256L3/4U The registers can also be manually reset by writing a one to the Channel Reset bit in the PCONTROL register (PCONTROL.CH0/1RES). The Performance Channel Read/Write Latency registers (PRLAT0/1 and PWLAT0/1) are saturating when their maximum count value is reached. The PRLAT0/1 and PWLAT0/1 registers can only be reset by writing a one to the corresponding reset bit in PCONTROL (PCONTROL.CH0/1RES). A counter is enabled by writing a one to the Channel Enable bit in the Performance Control Register (PCONTROL.CH0/1EN). 51 32142D–06/2013 ATUC64/128/256L3/4U 7.7 User Interface 7.7.1 Memory Map Overview The channels are mapped as shown in Table 7-1. Each channel has a set of configuration registers, shown in Table 7-2, where n is the channel number. 7.7.2 Channel Memory Map Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 7-1. PDCA Register Memory Map Address Range Contents 0x000 - 0x03F DMA channel 0 configuration registers 0x040 - 0x07F DMA channel 1 configuration registers ... ... (0x000 - 0x03F)+m*0x040 DMA channel m configuration registers 0x800-0x830 Performance Monitor registers 0x834 Version register Table 7-2. PDCA Channel Configuration Registers Offset Register Register Name Access Reset 0x000 + n*0x040 Memory Address Register MAR Read/Write 0x00000000 0x004 + n*0x040 Peripheral Select Register PSR Read/Write - (1) 0x008 + n*0x040 Transfer Counter Register TCR Read/Write 0x00000000 0x00C + n*0x040 Memory Address Reload Register MARR Read/Write 0x00000000 0x010 + n*0x040 Transfer Counter Reload Register TCRR Read/Write 0x00000000 0x014 + n*0x040 Control Register CR Write-only 0x00000000 0x018 + n*0x040 Mode Register MR Read/Write 0x00000000 0x01C + n*0x040 Status Register SR Read-only 0x00000000 0x020 + n*0x040 Interrupt Enable Register IER Write-only 0x00000000 0x024 + n*0x040 Interrupt Disable Register IDR Write-only 0x00000000 0x028 + n*0x040 Interrupt Mask Register IMR Read-only 0x00000000 0x02C + n*0x040 Interrupt Status Register ISR Read-only 0x00000000 52 32142D–06/2013 ATUC64/128/256L3/4U 7.7.3 Performance Monitor Memory Map Note: 1. The number of performance monitors is device specific. If the device has only one performance monitor, the Channel1 registers are not available. Please refer to the Module Configuration section at the end of this chapter for the number of performance monitors on this device. 7.7.4 Version Register Memory Map Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 7-3. PDCA Performance Monitor Registers(1) Offset Register Register Name Access Reset 0x800 Performance Control Register PCONTROL Read/Write 0x00000000 0x804 Channel0 Read Data Cycles PRDATA0 Read-only 0x00000000 0x808 Channel0 Read Stall Cycles PRSTALL0 Read-only 0x00000000 0x80C Channel0 Read Max Latency PRLAT0 Read-only 0x00000000 0x810 Channel0 Write Data Cycles PWDATA0 Read-only 0x00000000 0x814 Channel0 Write Stall Cycles PWSTALL0 Read-only 0x00000000 0x818 Channel0 Write Max Latency PWLAT0 Read-only 0x00000000 0x81C Channel1 Read Data Cycles PRDATA1 Read-only 0x00000000 0x820 Channel1 Read Stall Cycles PRSTALL1 Read-only 0x00000000 0x824 Channel1 Read Max Latency PRLAT1 Read-only 0x00000000 0x828 Channel1 Write Data Cycles PWDATA1 Read-only 0x00000000 0x82C Channel1 Write Stall Cycles PWSTALL1 Read-only 0x00000000 0x830 Channel1 Write Max Latency PWLAT1 Read-only 0x00000000 Table 7-4. PDCA Version Register Memory Map Offset Register Register Name Access Reset 0x834 Version Register VERSION Read-only - (1) 53 32142D–06/2013 ATUC64/128/256L3/4U 7.7.5 Memory Address Register Name: MAR Access Type: Read/Write Offset: 0x000 + n*0x040 Reset Value: 0x00000000 • MADDR: Memory Address Address of memory buffer. MADDR should be programmed to point to the start of the memory buffer when configuring the PDCA. During transfer, MADDR will point to the next memory location to be read/written. 31 30 29 28 27 26 25 24 MADDR[31:24] 23 22 21 20 19 18 17 16 MADDR[23:16] 15 14 13 12 11 10 9 8 MADDR[15:8] 76543210 MADDR[7:0] 54 32142D–06/2013 ATUC64/128/256L3/4U 7.7.6 Peripheral Select Register Name: PSR Access Type: Read/Write Offset: 0x004 + n*0x040 Reset Value: - • PID: Peripheral Identifier The Peripheral Identifier selects which peripheral should be connected to the DMA channel. Writing a PID will select both which handshake interface to use, the direction of the transfer and also the address of the Receive/Transfer Holding Register for the peripheral. See the Module Configuration section of PDCA for details. The width of the PID field is device specific and dependent on the number of peripheral modules in the device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PID 55 32142D–06/2013 ATUC64/128/256L3/4U 7.7.7 Transfer Counter Register Name: TCR Access Type: Read/Write Offset: 0x008 + n*0x040 Reset Value: 0x00000000 • TCV: Transfer Counter Value Number of data items to be transferred by the PDCA. TCV must be programmed with the total number of transfers to be made. During transfer, TCV contains the number of remaining transfers to be done. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TCV[15:8] 76543210 TCV[7:0] 56 32142D–06/2013 ATUC64/128/256L3/4U 7.7.8 Memory Address Reload Register Name: MARR Access Type: Read/Write Offset: 0x00C + n*0x040 Reset Value: 0x00000000 • MARV: Memory Address Reload Value Reload Value for the MAR register. This value will be loaded into MAR when TCR reaches zero if the TCRR register has a nonzero value. 31 30 29 28 27 26 25 24 MARV[31:24] 23 22 21 20 19 18 17 16 MARV[23:16] 15 14 13 12 11 10 9 8 MARV[15:8] 76543210 MARV[7:0] 57 32142D–06/2013 ATUC64/128/256L3/4U 7.7.9 Transfer Counter Reload Register Name: TCRR Access Type: Read/Write Offset: 0x010 + n*0x040 Reset Value: 0x00000000 • TCRV: Transfer Counter Reload Value Reload value for the TCR register. When TCR reaches zero, it will be reloaded with TCRV if TCRV has a positive value. If TCRV is zero, no more transfers will be performed for the channel. When TCR is reloaded, the TCRR register is cleared. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TCRV[15:8] 76543210 TCRV[7:0] 58 32142D–06/2013 ATUC64/128/256L3/4U 7.7.10 Control Register Name: CR Access Type: Write-only Offset: 0x014 + n*0x040 Reset Value: 0x00000000 • ECLR: Transfer Error Clear Writing a zero to this bit has no effect. Writing a one to this bit will clear the Transfer Error bit in the Status Register (SR.TERR). Clearing the SR.TERR bit will allow the channel to transmit data. The memory address must first be set to point to a valid location. • TDIS: Transfer Disable Writing a zero to this bit has no effect. Writing a one to this bit will disable transfer for the DMA channel. • TEN: Transfer Enable Writing a zero to this bit has no effect. Writing a one to this bit will enable transfer for the DMA channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - ECLR 76543210 - - - - - - TDIS TEN 59 32142D–06/2013 ATUC64/128/256L3/4U 7.7.11 Mode Register Name: MR Access Type: Read/Write Offset: 0x018 + n*0x040 Reset Value: 0x00000000 • RING: Ring Buffer 0:The Ring buffer functionality is disabled. 1:The Ring buffer functionality is enabled. When enabled, the reload registers, MARR and TCRR will not be cleared after reload. • ETRIG: Event Trigger 0:Start transfer when the peripheral selected in Peripheral Select Register (PSR) requests a transfer. 1:Start transfer only when or after a peripheral event is received. • SIZE: Size of Transfer 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - RING ETRIG SIZE Table 7-5. Size of Transfer SIZE Size of Transfer 0 Byte 1 Halfword 2 Word 3 Reserved 60 32142D–06/2013 ATUC64/128/256L3/4U 7.7.12 Status Register Name: SR Access Type: Read-only Offset: 0x01C + n*0x040 Reset Value: 0x00000000 • TEN: Transfer Enabled This bit is cleared when the TDIS bit in CR is written to one. This bit is set when the TEN bit in CR is written to one. 0: Transfer is disabled for the DMA channel. 1: Transfer is enabled for the DMA channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - TEN 61 32142D–06/2013 ATUC64/128/256L3/4U 7.7.13 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x020 + n*0x040 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 62 32142D–06/2013 ATUC64/128/256L3/4U 7.7.14 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x024 + n*0x040 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 63 32142D–06/2013 ATUC64/128/256L3/4U 7.7.15 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x028 + n*0x040 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 64 32142D–06/2013 ATUC64/128/256L3/4U 7.7.16 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x02C + n*0x040 Reset Value: 0x00000000 • TERR: Transfer Error This bit is cleared when no transfer errors have occurred since the last write to CR.ECLR. This bit is set when one or more transfer errors has occurred since reset or the last write to CR.ECLR. • TRC: Transfer Complete This bit is cleared when the TCR and/or the TCRR holds a non-zero value. This bit is set when both the TCR and the TCRR are zero. • RCZ: Reload Counter Zero This bit is cleared when the TCRR holds a non-zero value. This bit is set when TCRR is zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TERR TRC RCZ 65 32142D–06/2013 ATUC64/128/256L3/4U 7.7.17 Performance Control Register Name: PCONTROL Access Type: Read/Write Offset: 0x800 Reset Value: 0x00000000 • MON1CH: Performance Monitor Channel 1 • MON0CH: Performance Monitor Channel 0 The PDCA channel number to monitor with counter n Due to performance monitor hardware resource sharing, the two performance monitor channels should NOT be programmed to monitor the same PDCA channel. This may result in UNDEFINED monitor behavior. • CH1RES: Performance Channel 1 Counter Reset Writing a zero to this bit has no effect. Writing a one to this bit will reset the counter in the channel specified in MON1CH. This bit always reads as zero. • CH0RES: Performance Channel 0 Counter Reset Writing a zero to this bit has no effect. Writing a one to this bit will reset the counter in the channel specified in MON0CH. This bit always reads as zero. • CH1OF: Channel 1 Overflow Freeze 0: The performance channel registers are reset if DATA or STALL overflows. 1: All performance channel registers are frozen just before DATA or STALL overflows. • CH1OF: Channel 0 Overflow Freeze 0: The performance channel registers are reset if DATA or STALL overflows. 1: All performance channel registers are frozen just before DATA or STALL overflows. • CH1EN: Performance Channel 1 Enable 0: Performance channel 1 is disabled. 1: Performance channel 1 is enabled. • CH0EN: Performance Channel 0 Enable 0: Performance channel 0 is disabled. 1: Performance channel 0 is enabled. 31 30 29 28 27 26 25 24 - - MON1CH 23 22 21 20 19 18 17 16 - - MON0CH 15 14 13 12 11 10 9 8 - - - - - - CH1RES CH0RES 76543210 - - CH1OF CH0OF - - CH1EN CH0EN 66 32142D–06/2013 ATUC64/128/256L3/4U 7.7.18 Performance Channel 0 Read Data Cycles Name: PRDATA0 Access Type: Read-only Offset: 0x804 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 67 32142D–06/2013 ATUC64/128/256L3/4U 7.7.19 Performance Channel 0 Read Stall Cycles Name: PRSTALL0 Access Type: Read-only Offset: 0x808 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 68 32142D–06/2013 ATUC64/128/256L3/4U 7.7.20 Performance Channel 0 Read Max Latency Name: PRLAT0 Access Type: Read/Write Offset: 0x80C Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH0RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 69 32142D–06/2013 ATUC64/128/256L3/4U 7.7.21 Performance Channel 0 Write Data Cycles Name: PWDATA0 Access Type: Read-only Offset: 0x810 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 70 32142D–06/2013 ATUC64/128/256L3/4U 7.7.22 Performance Channel 0 Write Stall Cycles Name: PWSTALL0 Access Type: Read-only Offset: 0x814 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 71 32142D–06/2013 ATUC64/128/256L3/4U 7.7.23 Performance Channel 0 Write Max Latency Name: PWLAT0 Access Type: Read/Write Offset: 0x818 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH0RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 72 32142D–06/2013 ATUC64/128/256L3/4U 7.7.24 Performance Channel 1 Read Data Cycles Name: PRDATA1 Access Type: Read-only Offset: 0x81C Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 73 32142D–06/2013 ATUC64/128/256L3/4U 7.7.25 Performance Channel 1 Read Stall Cycles Name: PRSTALL1 Access Type: Read-only Offset: 0x820 Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 74 32142D–06/2013 ATUC64/128/256L3/4U 7.7.26 Performance Channel 1 Read Max Latency Name: PRLAT1 Access Type: Read/Write Offset: 0x824 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH1RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 75 32142D–06/2013 ATUC64/128/256L3/4U 7.7.27 Performance Channel 1 Write Data Cycles Name: PWDATA1 Access Type: Read-only Offset: 0x828 Reset Value: 0x00000000 • DATA: Data Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 76 32142D–06/2013 ATUC64/128/256L3/4U 7.7.28 Performance Channel 1 Write Stall Cycles Name: PWSTALL1 Access Type: Read-only Offset: 0x82C Reset Value: 0x00000000 • STALL: Stall Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock 31 30 29 28 27 26 25 24 STALL[31:24] 23 22 21 20 19 18 17 16 STALL[23:16] 15 14 13 12 11 10 9 8 STALL[15:8] 76543210 STALL[7:0] 77 32142D–06/2013 ATUC64/128/256L3/4U 7.7.29 Performance Channel 1 Write Max Latency Name: PWLAT1 Access Type: Read/Write Offset: 0x830 Reset Value: 0x00000000 • LAT: Maximum Transfer Initiation Cycles Counted Since Last Reset Clock cycles are counted using the CLK_PDCA_HSB clock This counter is saturating. The register is reset only when PCONTROL.CH1RES is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 LAT[15:8] 76543210 LAT[7:0] 78 32142D–06/2013 ATUC64/128/256L3/4U 7.7.30 PDCA Version Register Name: VERSION Access Type: Read-only Offset: 0x834 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 79 32142D–06/2013 ATUC64/128/256L3/4U 7.8 Module Configuration The specific configuration for each PDCA instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. The PDCA and the peripheral modules communicate through a set of handshake signals. The following table defines the valid settings for the Peripheral Identifier (PID) in the PDCA Peripheral Select Register (PSR). The direction is specified as observed from the memory, so RX means transfers from peripheral to memory, and TX means from memory to peripheral. Table 7-6. PDCA Configuration Feature PDCA Number of channels 12 Number of performance monitors 1 Table 7-7. PDCA Clocks Clock Name Description CLK_PDCA_HSB Clock for the PDCA HSB interface CLK_PDCA_PB Clock for the PDCA PB interface Table 7-8. Register Reset Values Register Reset Value PSR CH 0 0 PSR CH 1 1 PSR CH 2 2 PSR CH 3 3 PSR CH 4 4 PSR CH 5 5 PSR CH 6 6 PSR CH 7 7 PSR CH 8 8 PSR CH 9 9 PSR CH 10 10 PSR CH 11 11 VERSION 123 Table 7-9. Peripheral Identity Values PID Direction Peripheral Instance Peripheral Register 0 RX USART0 RHR 1 RX USART1 RHR 2 RX USART2 RHR 80 32142D–06/2013 ATUC64/128/256L3/4U 3 RX USART3 RHR 4 RX SPI RDR 5 RX TWIM0 RHR 6 RX TWIM1 RHR 7 RX TWIS0 RHR 8 RX TWIS1 RHR 9 RX ADCIFB LCDR 10 RX AW RHR 11 RX CAT ACOUNT 12 TX USART0 THR 13 TX USART1 THR 14 TX USART2 THR 15 TX USART3 THR 16 TX SPI TDR 17 TX TWIM0 THR 18 TX TWIM1 THR 19 TX TWIS0 THR 20 TX TWIS1 THR 21 TX AW THR 22 TX CAT MBLEN 23 TX ABDACB SDR0 24 TX ABDACB SDR1 25 RX IISC RHR (CH0) 26 RX IISC RHR (CH1) 27 TX IISC THR (CH0) 28 TX IISC THR (CH1) 29 RX CAT DMATSR 30 TX CAT DMATSW Table 7-9. Peripheral Identity Values PID Direction Peripheral Instance Peripheral Register 81 32142D–06/2013 ATUC64/128/256L3/4U 8. USB Interface (USBC) Rev: 2.0.0.15 8.1 Features • Compatible with the USB 2.0 specification • Supports full (12Mbit/s) and low (1.5Mbit/s) speed communication • Seven physical pipes/endpoints in ping-pong mode • Flexible pipe/endpoint configuration and reallocation of data buffers in embedded RAM • Up to two memory banks per pipe/endpoint • Built-in DMA with multi-packet support through ping-pong mode • On-chip transceivers with built-in pull-ups and pull-downs 8.2 Overview The Universal Serial Bus interface (USBC) module complies with the Universal Serial Bus (USB) 2.0 specification. Each pipe/endpoint can be configured into one of several transfer types. It can be associated with one or more memory banks (located inside the embedded system or CPU RAM) used to store the current data payload. If two banks are used (“ping-pong” mode), then one bank is read or written by the CPU (or any other HSB master) while the other is read or written by the USBC core. Table 8-1 describes the hardware configuration of the USBC module. 8.3 Block Diagram The USBC interfaces a USB link with a data flow stored in the embedded ram (CPU or HSB). The USBC requires a 48MHz ± 0.25% reference clock, which is the USB generic clock. For more details see ”Clocks” on page 84. The 48MHz clock is used to generate either a 12MHz fullspeed or a 1.5MHz low-speed bit clock from the received USB differential data, and to transmit data according to full- or low-speed USB device tolerances. Clock recovery is achieved by a digital phase-locked loop (a DPLL, not represented) in the USBC module, which complies with the USB jitter specifications. The USBC module consists of: • HSB master interface Table 8-1. Description of USB pipes/endpoints pipe/endpoint Mnemonic Max. size Number of available banks Type 0 PEP0 1023 bytes 1 Control/Isochronous/Bulk/Interrupt 1 PEP1 1023 bytes 2 Control/Isochronous/Bulk/Interrupt 2 PEP2 1023 bytes 2 Control/Isochronous/Bulk/Interrupt ... ... ... ... ... 6 PEP6 1023 bytes 2 Control/Isochronous/Bulk/Interrupt 82 32142D–06/2013 ATUC64/128/256L3/4U • User interface • USB Core • Transceiver pads Figure 8-1. USBC Block Diagram Note: in the block diagram is symbolic, it is mapped to a GPIO pin (See Section “8.5.1” on page 84.). The VBUS detection (rising edge detection on the GPIO pin) should be handled by software. Interrupt Controller USB interrupts DM USB_VBUS (1) USB DP User interface SCIF GCLK_USBC @ 48 MHz PB USB 2.0 Core USB clock domain System clock domain HSB HSB Master 83 32142D–06/2013 ATUC64/128/256L3/4U 8.4 I/O Lines Description Table 8-2. I/O Lines Description PIn Name Pin Description Type Active Level DM Data -: Differential Data Line - Port Input/Output DP Data +: Differential Data Line + Port Input/Output 84 32142D–06/2013 ATUC64/128/256L3/4U 8.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 8.5.1 I/O Lines The USBC pins may be multiplexed with the I/O Controller lines. The user must first configure the I/O Controller to assign the desired USBC pins to their peripheral functions. The USB VBUS line should be connected to a GPIO pin and the user should monitor this with software. 8.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the USBC, the USBC will stop functioning and resume operation after the system wakes up from sleep mode. 8.5.3 Clocks The USBC has two bus clocks connected: One High Speed Bus clock (CLK_USBC_HSB) and one Peripheral Bus clock (CLK_USBC_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by the Power Manager. It is recommended to disable the USBC before disabling the clocks, to avoid freezing the USBC in an undefined state. The 48MHz USB clock is generated by a dedicated generic clock from the SCIF module. Before using the USB, the user must ensure that the USB generic clock (GCLK_USBC) is enabled at 48MHz in the SCIF module. 8.5.4 Interrupts The USBC interrupt request line is connected to the interrupt controller. Using the USBC interrupt requires the interrupt controller to be programmed first. The USBC asynchronous interrupt can wake the CPU from any sleep mode: • The Wakeup Interrupt (WAKEUP) 85 32142D–06/2013 ATUC64/128/256L3/4U 8.6 Functional Description 8.6.1 USB General Operation 8.6.1.1 Initialization After a hardware reset, the USBC is in the Reset state. In this state: • The module is disabled. The USBC Enable bit in the General Control register (USBCON.USBE) is reset. • The module clock is stopped in order to minimize power consumption. The Freeze USB Clock bit in USBCON (USBCON.FRZCLK) is set. • The USB pad is in suspend mode. • The internal states and registers of the device are reset. • The Freeze USB Clock (FRZCLK), USBC Enable (USBE), in USBCON and the Low-Speed mode bit in the Device General Control register (UDCON.LS) can be written to by software, so that the user can configure pads and speed before enabling the module. These values are only taken into account once the module has been enabled and unfrozen. After writing a one to USBCON.USBE, the USBC enters device mode in idle state. Refer to Section 8.6.2 for the basic operation of the device mode. The USBC can be disabled at any time by writing a zero to USBCON.USBE, this acts as a hardware reset, except that the FRZCLK,bit in USBCON, and the LS bits in UDCON are not reset. 8.6.1.2 Interrupts One interrupt vector is assigned to the USBC. See Section 8.6.2.18 for further details about device interrupts. See Section 8.5.4 for asynchronous interrupts. 8.6.1.3 Frozen clock When the USB clock is frozen, it is still possible to access the following bits: FRZCLK, and USBE in the USBCON register, and LS in the UDCON register. When FRZCLK is set, only the asynchronous interrupt can trigger a USB interrupt (see Section 8.5.4). 8.6.1.4 Speed control • Device mode When the USBC interface is in device mode, the speed selection is done by the UDCON.LS bit, connecting an internal pull-up resistor to either DP (full-speed mode) or DM (low-speed mode). The LS bit shall be written before attaching the device, which can be simulated by clearing the UDCON.DETACH bit. 86 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-2. Speed Selection in device mode 8.6.1.5 Data management Endpoints and pipe buffers can be allocated anywhere in the embedded memory (CPU RAM or HSB RAM). See ”RAM management” on page 90. 8.6.1.6 Pad Suspend Figure 8-3 illustrates the behavior of the USB pad in device mode. Figure 8-3. Pad Behavior • In Idle state, the pad is in low power consumption mode. • In Active state, the pad is working. Figure 8-4 illustrates the pad events leading to a PAD state change. RPU UDCON.DETACH DP DM UDCON.LS VBUS Idle Active USBE = 1 & DETACH = 0 & Suspend USBE = 0 | DETACH = 1 | Suspend 87 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-4. Pad events The Suspend Interrupt bit in the Device Global Interrupt register (UDINT.SUSP) is set and the Wakeup Interrupt (UDINT.WAKEUP) bit is cleared when a USB Suspend state has been detected on the USB bus. This event automatically puts the USB pad in the Idle state. The detection of a non-idle event sets WAKEUP, clears SUSP, and wakes the USB pad. The pad goes to the Idle state if the module is disabled or if UDCON.DETACH is written to one. It returns to the Active state when USBCON.USBE is written to one and DETACH is written to zero. SUSP Suspend detected Cleared on Wakeup WAKEUP Wakeup detected Cleared by software to acknowledge the interrupt PAD state Active Idle Active 88 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2 USBC Device Mode Operation 8.6.2.1 Device Enabling In device mode, the USBC supports full- and low-speed data transfers. Including the default control endpoint, a total of seven endpoints are provided. They can be configured as isochronous, bulk or interrupt types, as described in Table 8-1 on page 81 After a hardware reset, the USBC device mode is in the reset state (see Section 8.6.1.1). In this state, the endpoint banks are disabled and neither DP nor DM are pulled up (DETACH is one). DP or DM will be pulled up according to the selected speed as soon as the DETACH bit is written to zero. See “Device mode” for further details. When the USBC is enabled (USBE is one) in device mode, it enters the Idle state, minimizing power consumption. Being in Idle state does not require the USB clocks to be activated. The USBC device mode can be disabled or reset at any time by disabling the USBC (by writing a zero to USBE). 8.6.2.2 USB reset The USB bus reset is initiated by a connected host and managed by hardware. When a USB reset state is detected on the USB bus, the following operations are performed by the controller: • UDCON register is reset except for the DETACH and SPDCONF bits. • Device Frame Number Register (UDFNUM), Endpoint n Configuration Register (UECFGn), and Endpoint n Control Register (UECONn) registers are cleared. • The data toggle sequencing in all the endpoints are cleared. • At the end of the reset process, the End of Reset (EORST) bit in the UDINT register is set. 8.6.2.3 Endpoint activation When an endpoint is disabled (UERST.EPENn = 0) the data toggle sequence, Endpoint n Status Set (UESTAn), and UECONn registers will be reset. The controller ignores all transactions to this endpoint as long as it is inactive. To complete an endpoint activation, the user should fill out the endpoint descriptor: see Figure 8- 5 on page 91. 8.6.2.4 Data toggle sequence In order to respond to a CLEAR_FEATURE USB request without disabling the endpoint, the user can clear the data toggle sequence by writing a one to the Reset Data Toggle Set bit in the Endpoint n Control Set register (UECONnSET.RSTDTS) 8.6.2.5 Busy bank enable In order to make an endpoint bank look busy regardless of its actual state, the user can write a one to the Busy Bank Enable bit in the Endpoint n Control Register (UECONnSET.BUSY0/1ES). If a BUSYnE bit is set, any transaction to this bank will be rejected with a NAK reply. 8.6.2.6 Address setup The USB device address is set up according to the USB protocol. 89 32142D–06/2013 ATUC64/128/256L3/4U • After all kinds of resets, the USB device address is 0. • The host starts a SETUP transaction with a SET_ADDRESS(addr) request. • The user writes this address to the USB Address field (UDCON.UADD), and writes a zero to the Address Enable bit (UDCON.ADDEN), resulting in the address remaining zero. • The user sends a zero-length IN packet from the control endpoint. • The user enables the stored USB device address by writing a one to ADDEN. Once the USB device address is configured, the controller filters the packets to only accept those targeting the address stored in UADD. UADD and ADDEN should not be written to simultaneously. They should be written sequentially, UADD field first. If UADD or ADDEN is cleared, the default device address 0 is used. UADD and ADDEN are cleared: • On a hardware reset. • When the USBC is disabled (USBE written to zero). • When a USB reset is detected. 8.6.2.7 Suspend and Wakeup When an idle USB bus state has been detected for 3 ms, the controller sets the Suspend (SUSP) interrupt bit in UDINT. In this case, the transceiver is suspended, reducing power consumption. To further reduce power consumption it is recommended to freeze the USB clock by writing a one to the Freeze USB Clock (FRZCLK) bit in USBCON when the USB bus is in suspend mode. The MCU can also enter the idle or frozen sleep mode to further lower power consumption. To recover from the suspend mode, the user shall wait for the Wakeup (WAKEUP) interrupt bit, which is set when a non-idle event is detected, and then write a zero to FRZCLK. As the WAKEUP interrupt bit in UDINT is set when a non-idle event is detected, it can occur regardless of whether the controller is in the suspend mode or not. The SUSP and WAKEUP interrupts are thus independent of each other except for that one bit is cleared when the other is set. 8.6.2.8 Detach The reset value of the DETACH bit located in the UDCON register, is one. It is possible to initiate a device re-enumeration simply by writing a one and then a zero to DETACH. DETACH acts on the pull-up connections of the DP and DM pads. See “Device mode” for further details. 8.6.2.9 Remote wakeup The remote wakeup request (also known as upstream resume) is the only request the device may send on its own initiative. This should be preceded by a DEVICE_REMOTE_WAKEUP request from the host. • First, the USBC must have detected a “Suspend” state on the bus, i.e. the remote wakeup request can only be sent after a SUSP interrupt has been set. 90 32142D–06/2013 ATUC64/128/256L3/4U • The user may then write a one to the remote wakeup (RMWKUP) bit in UDCON to send an Upstream Resume to the host initiating the wakeup. This will automatically be done by the controller after 5ms of inactivity on the USB bus. • When the controller sends the Upstream Resume, the Upstream Resume (UPRSM) interrupt is set and SUSP is cleared. • RMWKUP is cleared at the end of the transmitting Upstream Resume. • In case of a rebroadcast resume initiated by the host, the End of Resume (EORSM) interrupt is set when the rebroadcast resume is completed. 8.6.2.10 RAM management Endpoint data can be physically allocated anywhere in the embedded RAM. The USBC controller accesses these endpoints directly through the HSB master (built-in DMA). The USBC controller reads the USBC descriptors to know where each endpoint is located. The base address of the USBC descriptor (UDESC.UDESCA) needs to be written by the user. The descriptors can also be allocated anywhere in the embedded RAM. Before using an endpoint, the user should setup the endpoint address for each bank. Depending on the direction, the type, and the packet-mode (single or multi-packet), the user should also initialize the endpoint packet size, and the endpoint control and status fields, so that the USBC controller does not compute random values from the RAM. When using an endpoint the user should read the UESTAX.CURRBK field to know which bank is currently being processed. 91 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-5. Memory organization Each descriptor of an endpoint n consists of four words. • The address of the endpoint and the bank used (EPn_ADDR_BK0/1). • The packet size information for the endpoint and bank (EPn_PCKSIZE_BK0/1): Table 8-3. EPn_PCKSIZE_BK0/1 structure – AUTO_ZLP: Auto zero length packet, see ”Multi packet mode for IN endpoints” on page 96. – MULTI_PACKET_SIZE: see ”Multi packet mode and single packet mode.” on page 93. – BYTE_COUNT: see ”Multi packet mode and single packet mode.” on page 93. 31 30:16 15 14:0 AUTO_ZLP MULTI_PACKET_SIZE - BYTE_COUNT EPn BK0 EP0_CTR_STA_BK0 E P 0 _ P C K S IZ E _ B K 0 EP0_ADDR_BK0 UDESCA Growing Memory Addresses Descriptor EP0 R e se rve d EP0_CTR _STA_BK1 E P 0 _ P C K S IZ E _ B K 1 EP0_ADDR_BK1 R e se rve d Bank0 Bank1 +0x000 +0x004 +0x008 +0x00C +0x010 +0x014 +0x018 +0x01C EP1_CTR_STA_BK0 E P 1 _ P C K S IZ E _ B K 0 EP1_ADDR_BK0 Descriptor EP1 R e se rve d EP1_CTR _STA_BK1 E P 1 _ P C K S IZ E _ B K 1 EP1_ADDR_BK1 R e se rve d Bank0 Bank1 +0x020 +0x024 +0x028 +0x02C +0x030 +0x034 +0x038 +0x03C EPn_CTR_STA_BK0 E P n _ P C K S IZ E _ B K 0 EPn_ADDR_BK0 R e se rve d EPn_CTR _STA_BK1 E P n _ P C K S IZ E _ B K 1 EPn_ADDR_BK1 R e se rve d Bank0 Bank1 Descriptor EPn EPn BK1 U S B d e s c rip to rs U S B B u ffe rs 92 32142D–06/2013 ATUC64/128/256L3/4U • The control and status fields for the endpoint and bank (EPn_CTR_STA_BK0/1): Table 8-4. EPn_CTR_STA_BK0/1 structure – UNDERF: Underflow status for isochronous IN transfer. See ”Data flow error” on page 99. – OVERF: Overflow status for isochronous OUT transfer. See ”Data flow error” on page 99. – CRCERR: CRC error status for isochronous OUT transfer. See ”CRC error” on page 99. – STALLRQ_NEXT: Stall request for the next transfer. See ”STALL request” on page 92. 8.6.2.11 STALL request For each endpoint, the STALL management is performed using: • The STALL Request (STALLRQ) bit in UECONn is set to initiate a STALL request. • The STALLed Interrupt (STALLEDI) bit in UESTAn is set when a STALL handshake has been sent. To answer requests with a STALL handshake, STALLRQ has to be set by writing a one to the STALL Request Set (STALLRQS) bit. All following requests will be discarded (RXOUTI, etc. will not be set) and handshaked with a STALL until the STALLRQ bit is cleared, by receiving a new SETUP packet (for control endpoints) or by writing a one to the STALL Request Clear (STALLRQC) bit. Each time a STALL handshake is sent, the STALLEDI bit is set by the USBC and the EPnINT interrupt is set. The user can use the descriptor to manage STALL requests. The USBC controller reads the EPn_CTR_STA_BK0/1.STALLRQ_NEXT bit after successful transactions and if it is one the USBC controller will set UECON.STALLRQ. The STALL_NEXT bit will be cleared upon receiving a SETUP transaction and the USBC controller will then clear the STALLRQ bit. • Special considerations for control endpoints If a SETUP packet is received at a control endpoint where a STALL request is active, the Received SETUP Interrupt (RXSTPI) bit in UESTAn is set, and the STALLRQ and STALLEDI bits are cleared. It allows the SETUP to be always ACKed as required by the USB standard. This management simplifies the enumeration process management. If a command is not supported or contains an error, the user requests a STALL and can return to the main task, waiting for the next SETUP request. • STALL handshake and retry mechanism The retry mechanism has priority over the STALL handshake. A STALL handshake is sent if the STALLRQ bit is set and if there is no retry required. 31:19 18 17 16 15:1 0 Status elements Control elements - UNDERF OVERF CRCERR - STALLRQ_NEXT 93 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2.12 Multi packet mode and single packet mode. Single packet mode is the default mode where one USB packet is managed per bank. The multi-packet mode allows the user to manage data exceeding the maximum endpoint size (UECFGn.EPSIZE) for an endpoint bank across multiple packets without software intervention. This mode can also be coupled with the ping-pong mode. • For an OUT endpoint, the EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE field should be configured correctly to enable the multi-packet mode. See ”Multi packet mode for OUT endpoints” on page 98. For single packet mode, the MULTI_PACKET_SIZE should be initialized to 0. • For an IN endpoint, the EPn_PCKSIZE_BK0/1.BYTE_COUNT field should be configured correctly to enable the multi-packet mode. See”Multi packet mode for IN endpoints” on page 96. For single packet mode, the BYTE_COUNT should be less than EPSIZE. 8.6.2.13 Management of control endpoints • Overview A SETUP request is always ACKed. When a new SETUP packet is received, the RXSTPI is set, but not the Received OUT Data Interrupt (RXOUTI) bit. The FIFO Control (FIFOCON) bit in UECONn is irrelevant for control endpoints. The user should therefore never use it for these endpoints. When read, this value is always zero. Control endpoints are managed using: • The RXSTPI bit: is set when a new SETUP packet is received. This has to be cleared by firmware in order to acknowledge the packet and to free the bank. • The RXOUTI bit: is set when a new OUT packet is received. This has to be cleared by firmware in order to acknowledge the packet and to free the bank. • The Transmitted IN Data Interrupt (TXINI) bit: is set when the current bank is ready to accept a new IN packet. This has to be cleared by firmware in order to send the packet. • Control write Figure 8-6 on page 94 shows a control write transaction. During the status stage, the controller will not necessarily send a NAK on the first IN token: • If the user knows the exact number of descriptor bytes that will be read, the status stage can be predicted, and a zero-length packet can be sent after the next IN token. • Alternatively the bytes can be read until the NAKed IN Interrupt (NAKINI) is triggered, notifying that all bytes are sent by the host and that the transaction is now in the status stage. 94 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-6. Control Write • Control read Figure 8-7 on page 94 shows a control read transaction. The USBC has to manage the simultaneous write requests from the CPU and USB host. Figure 8-7. Control Read A NAK handshake is always generated as the first status stage command. The UESTAn.NAKINI bit is set. It allows the user to know that the host aborts the IN data stage. As a consequence, the user should stop processing the IN data stage and should prepare to receive the OUT status stage by checking the UESTAn.RXOUTI bit. The OUT retry is always ACKed. This OUT reception sets RXOUTI. Handle this with the following software algorithm: // process the IN data stage set TXINI wait for RXOUTI (rising) OR TXINI (falling) if RXOUTI is high, then process the OUT status stage if TXINI is low, then return to process the IN data stage Once the OUT status stage has been received, the USBC waits for a SETUP request. The SETUP request has priority over all other requests and will be ACKed. SETUP RXSTPI RXOUTI TXINI USB Bus HW SW OUT HW SW OUT HW SW IN IN NAK SW SETUP STATUS DATA SETUP RXSTPI RXOUTI TXINI USB Bus HW SW IN HW SW IN OUT OUT NAK SW SW HW Wr Enable HOST Wr Enable CPU SETUP STATUS DATA 95 32142D–06/2013 ATUC64/128/256L3/4U 8.6.2.14 Management of IN endpoints • Overview IN packets are sent by the USBC device controller upon IN requests from the host. The endpoint and its descriptor in RAM must be pre configured (see section ”RAM management” on page 90 for more details). When the current bank is clear, the TXINI and FIFO Control (UECONn.FIFOCON) bits will be set simultaneously. This triggers an EPnINT interrupt if the Transmitted IN Data Interrupt Enable (TXINE) bit in UECONn is one. TXINI shall be cleared by software (by writing a one to the Transmitted IN Data Interrupt Enable Clear bit in the Endpoint n Control Clear register (UECONnCLR.TXINIC)) to acknowledge the interrupt. This has no effect on the endpoint FIFO. The user writes the IN data to the bank referenced by the EPn descriptor and allows the USBC to send the data by writing a one to the FIFO Control Clear (UECONnCLR.FIFOCONC) bit. This will also cause a switch to the next bank if the IN endpoint is composed of multiple banks. The TXINI and FIFOCON bits will be updated accordingly. TXINI should always be cleared before clearing FIFOCON to avoid missing an TXINI event. Figure 8-8. Example of an IN endpoint with one data bank Figure 8-9. Example of an IN endpoint with two data banks IN DATA (bank 0) ACK TXINI FIFOCON HW write data to CPU BANK 0 SW SW SW SW IN NAK write data to CPU BANK 0 IN DATA (bank 0) ACK TXINI FIFOCON write data to CPU BANK 0 SW SW SW SW IN DATA (bank 1) ACK write data to CPU BANK 1 SW HW write data to CPU BANK0 96 32142D–06/2013 ATUC64/128/256L3/4U • Detailed description The data is written according to this sequence: • When the bank is empty, TXINI and FIFOCON are set, which triggers an EPnINT interrupt if TXINE is one. • The user acknowledges the interrupt by clearing TXINI. • The user reads the UESTAX.CURRBK field to see which the current bank is. • The user writes the data to the current bank, located in RAM as described by its descriptor: EPn_ADDR_BK0/1. • The user should write the size of the IN packet into the USB descriptor: EPn_PCKSIZE_BK0/1.BYTE_COUNT. • The user allows the controller to send the bank contents and switches to the next bank (if any) by clearing FIFOCON. If the endpoint uses several banks, the current one can be written while the previous one is being read by the host. When the user clears FIFOCON, the next current bank may already be clear and TXINI is set immediately. An “Abort” stage can be produced when a zero-length OUT packet is received during an IN stage of a control or isochronous IN transaction. The Kill IN Bank (KILLBK) bit in UECONn is used to kill the last written bank. The best way to manage this abort is to apply the algorithm represented on Figure 8-10 on page 96. See ”Endpoint n Control Register” on page 130 for more details about the KILLBK bit. Figure 8-10. Abort Algorithm • Multi packet mode for IN endpoints In multi packet mode, the user can prepare n USB packets in the bank to be sent on a multiple IN transaction. The packet sizes will equal UECFGn.EPSIZE unless the AUTO_ZLP option is Endpoint Abort Abort Done Abort is based on the fact that no bank is busy, i.e., that nothing has to be sent Disable the TXINI interrupt. EPRSTn = 1 NBUSYBK == 0? Yes TXINEC = 1 No KILLBKS = 1 KILLBK Yes == 1? Kill the last written bank. Wait for the end of the procedure No 97 32142D–06/2013 ATUC64/128/256L3/4U set, or if the total byte count is not an integral multiple of EPSIZE, whereby the last packet should be short. To enable the multi packet mode, the user should configure the endpoint descriptor (EPn_PCKSIZE_BK0/1.BYTE_COUNT) to the total size of the multi packet, which should be larger than the endpoint size (EPSIZE). Since the EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE is incremented (by the transmitted packet size) after each successful transaction, it should be set to zero when setting up a new multi packet transfer. The EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE is cleared by hardware when all the bank contents have been sent. The bank is considered as ready and the TX_IN flag is set when: • A short packet (smaller than EPSIZE) has been transmitted. • A packet has been successfully transmitted, the updated MULTI_PACKET_SIZE equals the BYTE_COUNT, and the AUTO_ZLP field is not set. • An extra zero length packet has been automatically sent for the last transfer of the current bank, if BYTE_COUNT is a multiple of EPSIZE and AUTO_ZLP is set. 8.6.2.15 Management of OUT endpoints • Overview The endpoint and its descriptor in RAM must be pre configured, see section ”RAM management” on page 90 for more details. When the current bank is full, the RXOUTI and FIFO Control (UECONn.FIFOCON) bits will be set simultaneously. This triggers an EPnINT interrupt if the Received OUT Data Interrupt Enable (RXOUTE) bit in UECONn is one. RXOUTI shall be cleared by software (by writing a one to the Received OUT Data Interrupt Clear (RXOUTIC) bit) to acknowledge the interrupt. This has no effect on the endpoint FIFO. The user reads the OUT data from the RAM and clears the FIFOCON bit to free the bank. This will also cause a switch to the next bank if the OUT endpoint is composed of multiple banks. RXOUTI should always be cleared before clearing FIFOCON to avoid missing an RXOUTI event. Figure 8-11. Example of an OUT endpoint with one data bank OUT DATA (bank 0) ACK RXOUTI FIFOCON HW OUT DATA (bank 0) ACK HW SW SW SW read data from CPU BANK 0 read data from CPU BANK 0 NAK 98 32142D–06/2013 ATUC64/128/256L3/4U Figure 8-12. Example of an OUT endpoint with two data banks • Detailed description Before using the OUT endpoint, one should properly initialize its descriptor for each bank. See Figure 8-5 on page 91. The data is read, according to this sequence: • When the bank is full, RXOUTI and FIFOCON are set, which triggers an EPnINT interrupt if RXOUTE is one. • The user acknowledges the interrupt by writing a one to RXOUTIC in order to clear RXOUTI. • The user reads the UESTAX.CURRBK field to know the current bank number. • The user reads the byte count of the current bank from the descriptor in RAM (EPn_PCKSIZE_BK0/1.BYTE_COUNT) to know how many bytes to read. • The user reads the data in the current bank, located in RAM as described by its descriptor: EPn_ADDR_BK0/1. • The user frees the bank and switches to the next bank (if any) by clearing FIFOCON. If the endpoint uses several banks, the current one can be read while the next is being written by the host. When the user clears FIFOCON, the following bank may already be ready and RXOUTI will be immediately set. • Multi packet mode for OUT endpoints In multi packet mode, the user can extend the size of the bank allowing the storage of n USB packets in the bank. To enable the multi packet mode, the user should configure the endpoint descriptor (EPn_PCKSIZE_BK0/1.MULTI_PACKET_SIZE) to match the size of the multi packet.This value should be a multiple of the endpoint size (UECFGn.EPSIZE). Since the EPn_PCKSIZE_BK0/1.BYTE_COUNT is incremented (by the received packet size) after each successful transaction, it should be set to zero when setting up a new multi packet transfer. As for single packet mode, the number of received data bytes is stored in the BYTE_CNT field. The bank is considered as “valid” and the RX_OUT flag is set when: OUT DATA (bank 0) ACK RXOUTI FIFOCON HW OUT DATA (bank 1) ACK SW read data from CPU SW BANK 0 HW SW read data from CPU BANK 1 99 32142D–06/2013 ATUC64/128/256L3/4U • A packet has been successfully received and the updated BYTE_COUNT equals the MULTI_PACKET_SIZE. • A short packet (smaller than EPSIZE) has been received. 8.6.2.16 Data flow error This error exists only for isochronous IN/OUT endpoints. It sets the Errorflow Interrupt (ERRORFI) bit in UESTAn, which triggers an EPnINT interrupt if the Errorflow Interrupt Enable (ERRORFE) bit is one. The user can check the EPn_CTR_STA_BK0/1.UNDERF and OVERF bits in the endpoint descriptor to see which current bank has been affected. • An underflow can occur during IN stage if the host attempts to read from an empty bank. A zero-length packet is then automatically sent by the USBC. The endpoint descriptor EPn_CTR_STA_BK0/1.UNDERF points out the bank from which the IN data should have originated. If a new successful transaction occurs, the UNDERF bit is overwritten to 0 only if the UESTAn.ERRORFI is cleared. • An overflow can occur during the OUT stage if the host tries to send a packet while the bank is full. Typically this occurs when a CPU is not fast enough. The packet data is not written to the bank and is lost. The endpoint descriptor EPn_CTR_STA_BK0/1.OVERF points out which bank the OUT data was destined to. If the UESTAn.ERRORFI bit is cleared and a new transaction is successful, the OVERF bit will be overwritten to zero. 8.6.2.17 CRC error This error exists only for isochronous OUT endpoints. It sets the CRC Error Interrupt (CRCERRI) bit in UESTAn, which triggers an EPnINT interrupt if the CRC Error Interrupt Enable (CRCERRE) bit is one. A CRC error can occur during an isochronous OUT stage if the USBC detects a corrupted received packet. The OUT packet is stored in the bank as if no CRC error had occurred (RXOUTI is set). The user can also check the endpoint descriptor to see which current bank is impacted by the CRC error by reading EPn_CTR_STA_BK0/1.CRCERR. 8.6.2.18 Interrupts There are two kinds of device interrupts: processing, i.e. their generation is part of the normal processing, and exception, i.e. errors not related to CPU exceptions. • Global interrupts The processing device global interrupts are: • The Suspend (SUSP) interrupt • The Start of Frame (SOF) interrupt with no frame number CRC error (the Frame Number CRC Error (FNCERR) bit in the Device Frame Number (UDFNUM) register is zero) • The End of Reset (EORST) interrupt • The Wakeup (WAKEUP) interrupt • The End of Resume (EORSM) interrupt • The Upstream Resume (UPRSM) interrupt • The Endpoint n (EPnINT) interrupt The exception device global interrupts are: 100 32142D–06/2013 ATUC64/128/256L3/4U • The Start of Frame (SOF) interrupt with a frame number CRC error (FNCERR is one) • Endpoint interrupts The processing device endpoint interrupts are: • The Transmitted IN Data Interrupt (TXINI) • The Received OUT Data Interrupt (RXOUTI) • The Received SETUP Interrupt (RXSTPI) • The Number of Busy Banks (NBUSYBK) interrupt The exception device endpoint interrupts are: • The Errorflow Interrupt (ERRORFI) • The NAKed OUT Interrupt (NAKOUTI) • The NAKed IN Interrupt (NAKINI) • The STALLed Interrupt (STALLEDI) • The CRC Error Interrupt (CRCERRI) 101 32142D–06/2013 ATUC64/128/256L3/4U 8.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 8-5. USBC Register Memory Map Offset Register Name Access Reset Value 0x0000 Device General Control Register UDCON Read/Write 0x00000100 0x0004 Device Global Interrupt Register UDINT Read-Only 0x00000000 0x0008 Device Global Interrupt Clear Register UDINTCLR Write-Only 0x00000000 0x000C Device Global Interrupt Set Register UDINTSET Write-Only 0x00000000 0x0010 Device Global Interrupt Enable Register UDINTE Read-Only 0x00000000 0x0014 Device Global Interrupt Enable Clear Register UDINTECLR Write-Only 0x00000000 0x0018 Device Global Interrupt Enable Set Register UDINTESET Write-Only 0x00000000 0x001C Endpoint Enable/Reset Register UERST Read/Write 0x00000000 0x0020 Device Frame Number Register UDFNUM Read-Only 0x00000000 0x0100 + n*4 Endpoint n Configuration Register UECFGn Read/Write 0x00000000 0x0130 + n*4 Endpoint n Status Register UESTAn Read-Only 0x00000100 0x0160 + n*4 Endpoint n Status Clear Register UESTAnCLR Write-Only 0x00000000 0x0190 + n*4 Endpoint n Status Set Register UESTAnSET Write-Only 0x00000000 0x01C0 + n*4 Endpoint n Control Register UECONn Read-Only 0x00000000 0x01F0 + n*4 Endpoint n Control Set Register UECONnSET Write-Only 0x00000000 0x0220 + n*4 Endpoint n Control Clear Register UECONnCLR Write-Only 0x00000000 0x0800 General Control Register USBCON Read/Write 0x00004000 0x0804 General Status Register USBSTA Read-Only 0x00000000 0x0808 General Status Clear Register USBSTACLR Write-Only 0x00000000 0x080C General Status Set Register USBSTASET Write-Only 0x00000000 0x0818 IP Version Register UVERS Read-Only -(1) 0x081C IP Features Register UFEATURES Read-Only -(1) 0x0820 IP PB Address Size Register UADDRSIZE Read-Only -(1) 0x0824 IP Name Register 1 UNAME1 Read-Only -(1) 0x0828 IP Name Register 2 UNAME2 Read-Only -(1) 0x082C USB Finite State Machine Status Register USBFSM Read-Only 0x00000009 0x0830 USB Descriptor address UDESC Read/Write 0x00000000 102 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1 USB General Registers 8.7.1.1 General Control Register Name: USBCON Access Type: Read/Write Offset: 0x0800 Reset Value: 0x00004000 • USBE: USBC Enable Writing a zero to this bit will disable the USBC, USB transceiver, and USB clock inputs. This will over-ride FRZCLK settings but not affect the value. Unless explicitly stated, all registers will become reset and read-only. Writing a one to this bit will enable the USBC. 0: The USBC is disabled. 1: The USBC is enabled. This bit can be written to even if FRZCLK is one. • FRZCLK: Freeze USB Clock Writing a zero to this bit will enable USB clock inputs. Writing a one to this bit will disable USB clock inputs. The resume detection will remain active. Unless explicitly stated, all registers will become read-only. 0: The clock inputs are enabled. 1: The clock inputs are disabled. This bit can be written to even if USBE is zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -- - -- - 15 14 13 12 11 10 9 8 USBE FRZCLK - - - - - - 76543210 -------- 103 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.2 General Status Register Register Name: USBSTA Access Type: Read-Only Offset: 0x0804 Reset Value: 0x00000000 • CLKUSABLE: Generic Clock Usable This bit is cleared when the USB generic clock is not usable. This bit is set when the USB generic clock (that should be 48 Mhz) is usable. • SPEED: Speed Status This field is set according to the controller speed mode. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CLKUSABLE SPEED - - - - 76543210 -------- SPEED Speed Status 00 full-speed mode 01 Reserved 10 low-speed mode 11 Reserved 104 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.3 General Status Clear Register Register Name: USBSTACLR Access Type: Write-Only Offset: 0x0808 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in USBSTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 105 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.4 General Status Set Register Register Name: USBSTASET Access Type: Write-Only Offset: 0x080C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in USBSTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 106 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.5 Version Register Register Name: UVERS Access Type: Read-Only Offset: 0x0818 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 107 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.6 Features Register Register Name: UFEATURES Access Type: Read-Only Offset: 0x081C Reset Value: - • EPTNBRMAX: Maximal Number of pipes/endpoints This field indicates the number of hardware-implemented pipes/endpoints: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - EPTNBRMAX 108 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.7 Address Size Register Register Name: UADDRSIZE Access Type: Read-Only Offset: 0x0820 Reset Value: - • UADDRSIZE: IP PB Address Size This field indicates the size of the PB address space reserved for the USBC IP interface. 31 30 29 28 27 26 25 24 UADDRSIZE[31:24] 23 22 21 20 19 18 17 16 UADDRSIZE[23:16] 15 14 13 12 11 10 9 8 UADDRSIZE[15:8] 76543210 UADDRSIZE[7:0] 109 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.8 IP Name Register 1 Register Name: UNAME1 Access Type: Read-Only Offset: 0x0824 Reset Value: - • UNAME1: IP Name Part One This field indicates the first part of the ASCII-encoded name of the USBC IP. 31 30 29 28 27 26 25 24 UNAME1[31:24] 23 22 21 20 19 18 17 16 UNAME1[23:16] 15 14 13 12 11 10 9 8 UNAME1[15:8] 76543210 UNAME1[7:0] 110 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.9 IP Name Register 2 Register Name: UNAME2 Access Type: Read-Only Offset: 0x0828 Reset Value: • UNAME2: IP Name Part Two This field indicates the second part of the ASCII-encoded name of the USBC IP. 31 30 29 28 27 26 25 24 UNAME2[31:24] 23 22 21 20 19 18 17 16 UNAME2[23:16] 15 14 13 12 11 10 9 8 UNAME2[15:8] 76543210 UNAME2[7:0] 111 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.10 Finite State Machine Status Register Register Name: USBFSM Access Type: Read-Only Offset: 0x082C Reset Value: 0x00000009 • DRDSTATE: Dual Role Device State This field indicates the state of the USBC. For Device mode it should always read 9. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - DRDSTATE 112 32142D–06/2013 ATUC64/128/256L3/4U 8.7.1.11 USB Descriptor Address Register Name: UDESC Access Type: Read-Write Offset: 0x0830 Reset Value: - • UDESCA: USB Descriptor Address This field contains the address of the USB descriptor. The three least significant bits are always zero. 31 30 29 28 27 26 25 24 UDESCA[31:24] 23 22 21 20 19 18 17 16 UDESCA[23:16] 15 14 13 12 11 10 9 8 UDESCA[15:8] 76543210 UDESCA[7:0] 113 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2 USB Device Registers 8.7.2.1 Device General Control Register Register Name: UDCON Access Type: Read/Write Offset: 0x0000 Reset Value: 0x00000100 • GNAK: Global NAK 0: Normal mode. 1: A NAK handshake is answered for each USB transaction regardless of the current endpoint memory bank status. • LS: low-speed mode force 0: The full-speed mode is active. 1: The low-speed mode is active. This bit can be written to even if USBE is zero or FRZCLK is one. Disabling the USBC (by writing a zero to the USBE bit) does not reset this bit. • RMWKUP: Remote wakeup Writing a zero to this bit has no effect. Writing a one to this bit will send an upstream resume to the host for a remote wakeup. This bit is cleared when the USBC receives a USB reset or once the upstream resume has been sent. • DETACH: Detach Writing a zero to this bit will reconnect the device. Writing a one to this bit will physically detach the device (disconnect internal pull-up resistor from DP and DM). • ADDEN: Address Enable Writing a zero to this bit has no effect. Writing a one to this bit will activate the UADD field (USB address). This bit is cleared when a USB reset is received. • UADD: USB Address This field contains the device address. This field is cleared when a USB reset is received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - GNAK - 15 14 13 12 11 10 9 8 - - - LS - - RMWKUP DETACH 76543210 ADDEN UADD 114 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.2 Device Global Interrupt Register Register Name: UDINT Access Type: Read-Only Offset: 0x0004 Reset Value: 0x00000000 Note: 1. EPnINT bits are within the range from EP0INT to EP6INT. • EPnINT: Endpoint n Interrupt This bit is cleared when the interrupt source is serviced. This bit is set when an interrupt is triggered by the endpoint n (UESTAn, UECONn). This triggers a USB interrupt if EPnINTE is one. • UPRSM: Upstream Resume Interrupt This bit is cleared when the UDINTCLR.UPRSMC bit is written to one to acknowledge the interrupt (USB clock inputs must be enabled before). This bit is set when the USBC sends a resume signal called “Upstream Resume”. This triggers a USB interrupt if UPRSME is one. • EORSM: End of Resume Interrupt This bit is cleared when the UDINTCLR.EORSMC bit is written to one to acknowledge the interrupt. This bit is set when the USBC detects a valid “End of Resume” signal initiated by the host. This triggers a USB interrupt if EORSME is one. • WAKEUP: Wakeup Interrupt This bit is cleared when the UDINTCLR.WAKEUPC bit is written to one to acknowledge the interrupt (USB clock inputs must be enabled before) or when the Suspend (SUSP) interrupt bit is set. This bit is set when the USBC is reactivated by a filtered non-idle signal from the lines (not by an upstream resume). This triggers an interrupt if WAKEUPE is one. This interrupt is generated even if the clock is frozen by the FRZCLK bit. • EORST: End of Reset Interrupt This bit is cleared when the UDINTCLR.EORSTC bit is written to one to acknowledge the interrupt. This bit is set when a USB “End of Reset” has been detected. This triggers a USB interrupt if EORSTE is one. • SOF: Start of Frame Interrupt This bit is cleared when the UDINTCLR.SOFC bit is written to one to acknowledge the interrupt. This bit is set when a USB “Start of Frame” PID (SOF) has been detected (every 1 ms). This triggers a USB interrupt if SOFE is one. The FNUM field is updated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INT(1) EP7INT(1) EP6INT(1) EP5INT(1) EP4INT(1) 15 14 13 12 11 10 9 8 EP3INT(1) EP2INT(1) EP1INT(1) EP0INT - - - - 76543210 - UPRSM EORSM WAKEUP EORST SOF - SUSP 115 32142D–06/2013 ATUC64/128/256L3/4U • SUSP: Suspend Interrupt This bit is cleared when the UDINTCLR.SUSPC bit is written to one to acknowledge the interrupt or when the Wakeup (WAKEUP) interrupt bit is set. This bit is set when a USB “Suspend” idle bus state has been detected for 3 frame periods (J state for 3 ms). This triggers a USB interrupt if SUSPE is one. 116 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.3 Device Global Interrupt Clear Register Register Name: UDINTCLR Access Type: Write-Only Offset: 0x0008 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UDINT. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - UPRSMC EORSMC WAKEUPC EORSTC SOFC - SUSPC 117 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.4 Device Global Interrupt Set Register Register Name: UDINTSET Access Type: Write-Only Offset: 0x000C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UDINT, which may be useful for test or debug purposes. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - UPRSMS EORSMS WAKEUPS EORSTS SOFS - SUSPS 118 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.5 Device Global Interrupt Enable Register Register Name: UDINTE Access Type: Read-Only Offset: 0x0010 Reset Value: 0x00000000 Note: 1. EPnINTE bits are within the range from EP0INTE to EP6INTE. 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in UDINTECLR is written to one. A bit in this register is set when the corresponding bit in UDINTESET is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTE(1) EP7INTE(1) EP6INTE(1) EP5INTE(1) EP4INTE(1) 15 14 13 12 11 10 9 8 EP3INTE(1) EP2INTE(1) EP1INTE(1) EP0INTE - - - - 76543210 - UPRSME EORSME WAKEUPE EORSTE SOFE - SUSPE 119 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.6 Device Global Interrupt Enable Clear Register Register Name: UDINTECLR Access Type: Write-Only Offset: 0x0014 Reset Value: 0x00000000 Note: 1. EPnINTEC bits are within the range from EP0INTEC to EP6INTEC. Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UDINTE. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTEC(1) EP7INTEC(1) EP6INTEC(1) EP5INTEC(1) EP4INTEC(1) 15 14 13 12 11 10 9 8 EP3INTEC(1) EP2INTEC(1) EP1INTEC(1) EP0INTEC - - - - 76543210 - UPRSMEC EORSMEC WAKEUPEC EORSTEC SOFEC - SUSPEC 120 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.7 Device Global Interrupt Enable Set Register Register Name: UDINTESET Access Type: Write-Only Offset: 0x0018 Reset Value: 0x00000000 Note: 1. EPnINTES bits are within the range from EP0INTES to EP6INTES. Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UDINTE. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - EP8INTES(1) EP7INTES(1) EP6INTES(1) EP5INTES(1) EP4INTES(1) 15 14 13 12 11 10 9 8 EP3INTES(1) EP2INTES(1) EP1INTES(1) EP0INTES - - - - 76543210 - UPRSMES EORSMES WAKEUPES EORSTES SOFES - SUSPES 121 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.8 Endpoint Enable/Reset Register Register Name: UERST Access Type: Read/Write Offset: 0x001C Reset Value: 0x00000000 • EPENn: Endpoint n Enable Note: 1. EPENn bits are within the range from EPEN0 to EPEN6. Writing a zero to this bit will disable the endpoint n (USB requests will be ignored), and resets the endpoints registers (UECFGn, UESTAn, UECONn), but not the endpoint configuration (EPBK, EPSIZE, EPDIR, EPTYPE). Writing a one to this bit will enable the endpoint n. 0: The endpoint n is disabled. 1: The endpoint n is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - EPEN8(1) 76543210 EPEN7(1) EPEN6(1) EPEN5(1) EPEN4(1) EPEN3(1) EPEN2(1) EPEN1(1) EPEN0 122 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.9 Device Frame Number Register Register Name: UDFNUM Access Type: Read-Only Offset: 0x0020 Reset Value: 0x00000000 • FNCERR: Frame Number CRC Error This bit is cleared upon receiving a USB reset. This bit is set when a corrupted frame number is received. This bit and the SOF interrupt bit are updated at the same time. • FNUM: Frame Number This field is cleared upon receiving a USB reset. This field contains the 11-bit frame number information, as provided from the last SOF packet. FNUM is updated even if a corrupted SOF is received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 FNCERR - FNUM[10:5] 76543210 FNUM[4:0] - - - 123 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.10 Endpoint n Configuration Register Register Name: UECFGn, n in [0..6] Access Type: Read/Write Offset: 0x0100 + (n * 0x04) Reset Value: 0x00000000 • EPTYPE: Endpoint Type This field selects the endpoint type: This field is cleared upon receiving a USB reset. • EPDIR: Endpoint Direction 0: The endpoint direction is OUT. 1: The endpoint direction is IN (nor for control endpoints). This bit is cleared upon receiving a USB reset. • EPSIZE: Endpoint Size This field determines the size of each endpoint bank: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - EPTYPE - - EPDIR 76543210 - EPSIZE - EPBK - - EPTYPE Endpoint Type 0 0 Control 0 1 Isochronous 1 0 Bulk 1 1 Interrupt EPSIZE Endpoint Size 0 0 0 8 bytes 0 0 1 16 bytes 0 1 0 32 bytes 0 1 1 64 bytes 1 0 0 128 bytes 124 32142D–06/2013 ATUC64/128/256L3/4U This field is cleared upon receiving a USB reset (except for the endpoint 0). • EPBK: Endpoint Banks This bit selects the number of banks for the endpoint: 0: single-bank endpoint 1: double-bank endpoint For control endpoints, a single-bank endpoint shall be selected. This field is cleared upon receiving a USB reset (except for the endpoint 0). 1 0 1 256 bytes 1 1 0 512 bytes 1 1 1 1024 bytes EPSIZE Endpoint Size 125 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.11 Endpoint n Status Register Register Name: UESTAn, n in [0..6] Access Type: Read-Only 0x0100 Offset: 0x0130 + (n * 0x04) Reset Value: 0x00000000 • CTRLDIR: Control Direction Writing a zero or a one to this bit has no effect. This bit is cleared after a SETUP packet to indicate that the following packet is an OUT packet. This bit is set after a SETUP packet to indicate that the following packet is an IN packet. • CURRBK: Current Bank This bit is set for non-control endpoints, indicating the current bank: This field may be updated one clock cycle after the RWALL bit changes, so the user should not poll this field as an interrupt bit. • NBUSYBK: Number of Busy Banks This field is set to indicate the number of busy banks: 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - CTRLDIR - 15 14 13 12 11 10 9 8 CURRBK NBUSYBK RAMACERI - DTSEQ 76543210 - STALLEDI/ CRCERRI - NAKINI NAKOUTI RXSTPI/ ERRORFI RXOUTI TXINI CURRBK Current Bank 0 0 Bank0 0 1 Bank1 1 0 Reserved 1 1 Reserved NBUSYBK Number of Busy Banks 0 0 0 (all banks free) 0 11 1 02 1 1 Reserved 126 32142D–06/2013 ATUC64/128/256L3/4U For IN endpoints, this indicates the number of banks filled by the user and ready for IN transfers. When all banks are free an EPnINT interrupt will be triggered if NBUSYBKE is one. For OUT endpoints, this indicates the number of banks filled by OUT transactions from the host. When all banks are busy an EPnINT interrupt will be triggered if NBUSYBKE is one. • RAMACERI: Ram Access Error Interrupt This bit is cleared when the RAMACERIC bit is written to one, acknowledging the interrupt. This bit is set when a RAM access underflow error occurs during an IN data stage. • DTSEQ: Data Toggle Sequence This field is set to indicate the PID of the current bank: For IN transfers, this indicates the data toggle sequence that will be used for the next packet to be sent. For OUT transfers, this value indicates the data toggle sequence of the data received in the current bank. • STALLEDI: STALLed Interrupt This bit is cleared when the STALLEDIC bit is written to one, acknowledging the interrupt. This bit is set when a STALL handshake has been sent and triggers an EPnINT interrupt if STALLEDE is one. • CRCERRI: CRC Error Interrupt This bit is cleared when the CRCERRIC bit is written to one, acknowledging the interrupt. This bit is set when a CRC error has been detected in an isochronous OUT endpoint bank, and triggers an EPnINT interrupt if CRCERRE is one. • NAKINI: NAKed IN Interrupt This bit is cleared when the NAKINIC bit is written to one, acknowledging the interrupt. This bit is set when a NAK handshake has been sent in response to an IN request from the host, and triggers an EPnINT interrupt if NAKINE is one. • NAKOUTI: NAKed OUT Interrupt This bit is cleared when the NAKOUTIC bit is written to one, acknowledging the interrupt. This bit is set when a NAK handshake has been sent in response to an OUT request from the host, and triggers an EPnINT interrupt if NAKOUTE is one. • ERRORFI: Isochronous Error flow Interrupt This bit is cleared when the ERRORFIC bit is written to one, acknowledging the interrupt. This bit is set, for isochronous IN/OUT endpoints, when an errorflow (underflow or overflow) error occurs, and triggers an EPnINT interrupt if ERRORFE is one. An underflow can occur during IN stage if the host attempts to read from an empty bank. A zero-length packet is then automatically sent by the USBC. An overflow can also occur during OUT stage if the host sends a packet while the bank is already full, resulting in the packet being lost. This is typically due to a CPU not being fast enough. This bit is inactive (cleared) for bulk and interrupt IN/OUT endpoints and it means RXSTPI for control endpoints. • RXSTPI: Received SETUP Interrupt This bit is cleared when the RXSTPIC bit is written to one, acknowledging the interrupt and freeing the bank. This bit is set, for control endpoints, to signal that the current bank contains a new valid SETUP packet, and triggers an EPnINT interrupt if RXSTPE is one. This bit is inactive (cleared) for bulk and interrupt IN/OUT endpoints and it means UNDERFI for isochronous IN/OUT endpoints. • RXOUTI: Received OUT Data Interrupt This bit is cleared when the RXOUTIC bit is written to one, acknowledging the interrupt. For control endpoints, it releases the bank. For other endpoint types, the user should clear the FIFOCON bit to free the bank. RXOUTI shall always be cleared before clearing FIFOCON to avoid missing an interrupt. DTSEQ Data Toggle Sequence 0 0 Data0 0 1 Data1 1 X Reserved 127 32142D–06/2013 ATUC64/128/256L3/4U This bit is set, for control endpoints, when the current bank contains a bulk OUT packet (data or status stage). This triggers an EPnINT interrupt if RXOUTE is one. This bit is set for isochronous, bulk and, interrupt OUT endpoints, at the same time as FIFOCON when the current bank is full. This triggers an EPnINT interrupt if RXOUTE is one. This bit is inactive (cleared) for isochronous, bulk and interrupt IN endpoints. • TXINI: Transmitted IN Data Interrupt This bit is cleared when the TXINIC bit is written to one, acknowledging the interrupt. For control endpoints, this will send the packet. For other endpoint types, the user should clear the FIFOCON to allow the USBC to send the data. TXINI shall always be cleared before clearing FIFOCON to avoid missing an interrupt. This bit is set for control endpoints, when the current bank is ready to accept a new IN packet. This triggers an EPnINT interrupt if TXINE is one. This bit is set for isochronous, bulk and interrupt IN endpoints, at the same time as FIFOCON when the current bank is free. This triggers an EPnINT interrupt if TXINE is one. This bit is inactive (cleared) for isochronous, bulk and interrupt OUT endpoints. 128 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.12 Endpoint n Status Clear Register Register Name: UESTAnCLR, n in [0..6] Access Type: Write-Only Offset: 0x0160 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UESTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - RAMACERIC - - - 76543210 - STALLEDIC/ CRCERRIC - NAKINIC NAKOUTIC RXSTPIC/ ERRORFIC RXOUTIC TXINIC 129 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.13 Endpoint n Status Set Register Register Name: UESTAnSET, n in [0..6] Access Type: Write-Only Offset: 0x0190 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UESTA. These bits always read as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - NBUSYBKS RAMACERIS - - 76543210 - STALLEDIS/ CRCERRIS - NAKINIS NAKOUTIS RXSTPIS/ ERRORFIS RXOUTIS TXINIS 130 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.14 Endpoint n Control Register Register Name: UECONn, n in [0..6] Access Type: Read-Only Offset: 0x01C0 + (n * 0x04) Reset Value: 0x00000000 • BUSY0E: Busy Bank0 Enable This bit is cleared when the BUSY0C bit is written to one. This bit is set when the BUSY0ES bit is written to one. This will set the bank 0 as “busy”. All transactions, except SETUP, destined to this bank will be rejected (i.e: NAK token will be answered). • BUSY1E: Busy Bank1 Enable This bit is cleared when the BUSY1C bit is written to one. This bit is set when the BUSY1ES bit is written to one. This will set the bank 1 as “busy”. All transactions, except SETUP, destined to this bank will be rejected (i.e: NAK token will be answered). • STALLRQ: STALL Request This bit is cleared when a new SETUP packet is received or when the STALLRQC bit is written to zero. This bit is set when the STALLRQS bit is written to one, requesting a STALL handshake to be sent to the host. • RSTDT: Reset Data Toggle The data toggle sequence is cleared when the RSTDTS bit is written to one (i.e., Data0 data toggle sequence will be selected for the next sent (IN endpoints) or received (OUT endpoints) packet. This bit is always read as zero. • FIFOCON: FIFO Control For control endpoints: The FIFOCON and RWALL bits are irrelevant. The software shall therefore never use them for these endpoints. When read, their value is always 0. For IN endpoints: This bit is cleared when the FIFOCONC bit is written to one, sending the FIFO data and switching to the next bank. This bit is set simultaneously to TXINI, when the current bank is free. For OUT endpoints: This bit is cleared when the FIFOCONC bit is written to one, freeing the current bank and switching to the next. This bit is set simultaneously to RXINI, when the current bank is full. 31 30 29 28 27 26 25 24 - - - - - - BUSY1E BUSY0E 23 22 21 20 19 18 17 16 - - - - STALLRQ RSTDT - - 15 14 13 12 11 10 9 8 - FIFOCON KILLBK NBUSYBKE RAMACERE - - 76543210 - STALLEDE/ CRCERRE - NAKINE NAKOUTE RXSTPE/ ERRORFE RXOUTE TXINE 131 32142D–06/2013 ATUC64/128/256L3/4U • KILLBK: Kill IN Bank This bit is cleared by hardware after the completion of the “kill packet procedure”. This bit is set when the KILLBKS bit is written to one, killing the last written bank. The user shall wait for this bit to be cleared before trying to process another IN packet. Caution: The bank is cleared when the “kill packet” procedure is completed by the USBC core: If the bank is really killed, the NBUSYBK field is decremented. If the bank sent instead of killed (IN transfer), the NBUSYBK field is decremented and the TXINI flag is set. This specific case can occur if an IN token comes while the user tries to kill the bank. Note: If two banks are ready to be sent, the above specific case will not occur, since the first bank is sent (IN transfer) while the last bank is killed. • NBUSYBKE: Number of Busy Banks Interrupt Enable This bit is cleared when the NBUSYBKEC bit is written to zero, disabling the Number of Busy Banks interrupt (NBUSYBK). This bit is set when the NBUSYBKES bit is written to one, enabling the Number of Busy Banks interrupt (NBUSYBK). • RAMACERE: RAMACER Interrupt Enable This bit is cleared when the RAMACEREC bit is written to one, disabling the RAMACER interrupt (RAMACERI). This bit is set when the RAMACERES bit is written to one, enabling the RAMACER interrupt (RAMACERI). • STALLEDE: STALLed Interrupt Enable This bit is cleared when the STALLEDEC bit is written to one, disabling the STALLed interrupt (STALLEDI). This bit is set when the STALLEDES bit is written to one, enabling the STALLed interrupt (STALLEDI). • CRCERRE: CRC Error Interrupt Enable This bit is cleared when the CRCERREC bit is written to one, disabling the CRC Error interrupt (CRCERRI). This bit is set when the CRCERRES bit is written to one, enabling the CRC Error interrupt (CRCERRI). • NAKINE: NAKed IN Interrupt Enable This bit is cleared when the NAKINEC bit is written to one, disabling the NAKed IN interrupt (NAKINI). This bit is set when the NAKINES bit is written to one, enabling the NAKed IN interrupt (NAKINI). • NAKOUTE: NAKed OUT Interrupt Enable This bit is cleared when the NAKOUTEC bit is written to one, disabling the NAKed OUT interrupt (NAKOUTI). This bit is set when the NAKOUTES bit is written to one, enabling the NAKed OUT interrupt (NAKOUTI). • RXSTPE: Received SETUP Interrupt Enable This bit is cleared when the RXSTPEC bit is written to one, disabling the Received SETUP interrupt (RXSTPI). This bit is set when the RXSTPES bit is written to one, enabling the Received SETUP interrupt (RXSTPI). • ERRORFE: Errorflow Interrupt Enable This bit is cleared when the ERRORFEC bit is written to one, disabling the Underflow interrupt (ERRORFI). This bit is set when the ERRORFES bit is written to one, enabling the Underflow interrupt (ERRORFI). • RXOUTE: Received OUT Data Interrupt Enable This bit is cleared when the RXOUTEC bit is written to one, disabling the Received OUT Data interrupt (RXOUT). This bit is set when the RXOUTES bit is written to one, enabling the Received OUT Data interrupt (RXOUT). • TXINE: Transmitted IN Data Interrupt Enable This bit is cleared when the TXINEC bit is written to one, disabling the Transmitted IN Data interrupt (TXINI). This bit is set when the TXINES bit is written to one, enabling the Transmitted IN Data interrupt (TXINI). 132 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.15 Endpoint n Control Clear Register Register Name: UECONnCLR, n in [0..6] Access Type: Write-Only Offset: 0x0220 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in UECONn. These bits always read as zero. 31 30 29 28 27 26 25 24 - - - - - - BUSY1EC BUSY0EC 23 22 21 20 19 18 17 16 - - - - STALLRQC - - - 15 14 13 12 11 10 9 8 - FIFOCONC - NBUSYBKEC RAMACEREC - - - 76543210 - STALLEDEC/ CRCERREC - NAKINEC NAKOUTEC RXSTPEC/ ERRORFEC RXOUTEC TXINEC 133 32142D–06/2013 ATUC64/128/256L3/4U 8.7.2.16 Endpoint n Control Set Register Register Name: UECONnSET, n in [0..6] Access Type: Write-Only Offset: 0x01F0 + (n * 0x04) Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in UECONn. These bits always read as zero. • • 31 30 29 28 27 26 25 24 - - - - - - BUSY1ES BUSY0ES 23 22 21 20 19 18 17 16 - - - - STALLRQS RSTDTS - - 15 14 13 12 11 10 9 8 - - KILLBKS NBUSYBKES RAMACERES --- 76543210 - STALLEDES/ CRCERRES - NAKINES NAKOUTES RXSTPES/ ERRORFES RXOUTES TXINES 134 32142D–06/2013 ATUC64/128/256L3/4U 8.8 Module Configuration The specific configuration for each USBC instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 8-6. USBC Clocks Clock Name Description CLK_USBC_PB Clock for the USBC PB interface CLK_USBC_HSB Clock for the USBC HSB interface GCLK_USBC The generic clock used for the USBC is GCLK7 Table 8-7. Register Reset Values Register Reset Value UVERS 0x00000200 UFEATURES 0x00000007 UADDRSIZE 0x00001000 UNAME1 0x48555342 UNAME2 0x00000000 135 32142D–06/2013 ATUC64/128/256L3/4U 9. Flash Controller (FLASHCDW) Rev: 1.2.0.0 9.1 Features • Controls on-chip flash memory • Supports 0 and 1 wait state bus access • Buffers reducing penalty of wait state in sequential code or loops • Allows interleaved burst reads for systems with one wait state, outputting one 32-bit word per clock cycle for sequential reads • Secure State for supporting FlashVault technology • 32-bit HSB interface for reads from flash and writes to page buffer • 32-bit PB interface for issuing commands to and configuration of the controller • Flash memory is divided into 16 regions can be individually protected or unprotected • Additional protection of the Boot Loader pages • Supports reads and writes of general-purpose Non Volatile Memory (NVM) bits • Supports reads and writes of additional NVM pages • Supports device protection through a security bit • Dedicated command for chip-erase, first erasing all on-chip volatile memories before erasing flash and clearing security bit 9.2 Overview The Flash Controller (FLASHCDW) interfaces the on-chip flash memory with the 32-bit internal HSB bus. The controller manages the reading, writing, erasing, locking, and unlocking sequences. 9.3 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 9.3.1 Power Management If the CPU enters a sleep mode that disables clocks used by the FLASHCDW, the FLASHCDW will stop functioning and resume operation after the system wakes up from sleep mode. 9.3.2 Clocks The FLASHCDW has two bus clocks connected: One High Speed Bus clock (CLK_FLASHCDW_HSB) and one Peripheral Bus clock (CLK_FLASHCDW_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by writing to the Power Manager. The user has to ensure that CLK_FLASHCDW_HSB is not turned off before reading the flash or writing the pagebuffer and that CLK_FLASHCDW_PB is not turned off before accessing the FLASHCDW configuration and control registers. Failing to do so may deadlock the bus. 9.3.3 Interrupts The FLASHCDW interrupt request lines are connected to the interrupt controller. Using the FLASHCDW interrupts requires the interrupt controller to be programmed first. 136 32142D–06/2013 ATUC64/128/256L3/4U 9.3.4 Debug Operation When an external debugger forces the CPU into debug mode, the FLASHCDW continues normal operation. If the FLASHCDW is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 9.4 Functional Description 9.4.1 Bus Interfaces The FLASHCDW has two bus interfaces, one High Speed Bus (HSB) interface for reads from the flash memory and writes to the page buffer, and one Peripheral Bus (PB) interface for issuing commands and reading status from the controller. 9.4.2 Memory Organization The flash memory is divided into a set of pages. A page is the basic unit addressed when programming the flash. A page consists of several words. The pages are grouped into 16 regions of equal size. Each of these regions can be locked by a dedicated fuse bit, protecting it from accidental modification. • p pages (FLASH_P) • w bytes in each page and in the page buffer (FLASH_W) • pw bytes in total (FLASH_PW) • f general-purpose fuse bits (FLASH_F), used as region lock bits and for other device-specific purposes • 1 security fuse bit • 1 User page 9.4.3 User Page The User page is an additional page, outside the regular flash array, that can be used to store various data, such as calibration data and serial numbers. This page is not erased by regular chip erase. The User page can only be written and erased by a special set of commands. Read accesses to the User page are performed just as any other read accesses to the flash. The address map of the User page is given in Figure 9-1 on page 138. 9.4.4 Read Operations The on-chip flash memory is typically used for storing instructions to be executed by the CPU. The CPU will address instructions using the HSB bus, and the FLASHCDW will access the flash memory and return the addressed 32-bit word. In systems where the HSB clock period is slower than the access time of the flash memory, the FLASHCDW can operate in 0 wait state mode, and output one 32-bit word on the bus per clock cycle. If the clock frequency allows, the user should use 0 wait state mode, because this gives the highest performance as no stall cycles are encountered. The FLASHCDW can also operate in systems where the HSB bus clock period is faster than the access speed of the flash memory. Wait state support and a read granularity of 64 bits ensure efficiency in such systems. Performance for systems with high clock frequency is increased since the internal read word width of the flash memory is 64 bits. When a 32-bit word is to be addressed, the word itself and 137 32142D–06/2013 ATUC64/128/256L3/4U also the other word in the same 64-bit location is read. The first word is output on the bus, and the other word is put into an internal buffer. If a read to a sequential address is to be performed in the next cycle, the buffered word is output on the bus, while the next 64-bit location is read from the flash memory. Thus, latency in 1 wait state mode is hidden for sequential fetches. The programmer can select the wait states required by writing to the FWS field in the Flash Control Register (FCR). It is the responsibility of the programmer to select a number of wait states compatible with the clock frequency and timing characteristics of the flash memory. In 0ws mode, no wait states are encountered on any flash read operations. In 1 ws mode, one stall cycle is encountered on the first access in a single or burst transfer. In 1 ws mode, if the first access in a burst access is to an address that is not 64-bit aligned, an additional stall cycle is also encountered when reading the second word in the burst. All subsequent words in the burst are accessed without any stall cycles. The Flash Controller provides two sets of buffers that can be enabled in order to speed up instruction fetching. These buffers can be enabled by writing a one to the FCR.SEQBUF and FCR.BRBUF bits. The SEQBUF bit enables buffering hardware optimizing sequential instruction fetches. The BRBUF bit enables buffering hardware optimizing tight inner loops. These buffers are never used when the flash is in 0 wait state mode. Usually, both these buffers should be enabled when operating in 1 wait state mode. Some users requiring absolute cycle determinism may want to keep the buffers disabled. The Flash Controller address space is displayed in Figure 9-1. The memory space between address pw and the User page is reserved, and reading addresses in this space returns an undefined result. The User page is permanently mapped to an offset of 0x00800000 from the start address of the flash memory. Table 9-1. User Page Addresses Memory type Start address, byte sized Size Main array 0 pw bytes User 0x00800000 w bytes 138 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-1. Memory Map for the Flash Memories 9.4.5 High Speed Read Mode The flash provides a High Speed Read Mode, offering slightly higher flash read speed at the cost of higher power consumption. Two dedicated commands, High Speed Read Mode Enable (HSEN) and High Speed Read Mode Disable (HSDIS) control the speed mode. The High Speed Mode (HSMODE) bit in the Flash Status Register (FSR) shows which mode the flash is in. After reset, the High Speed Mode is disabled, and must be manually enabled if the user wants to. Refer to the Electrical Characteristics chapter at the end of this datasheet for details on the maximum clock frequencies in Normal and High Speed Read Mode. 0 pw Reserved Flash data array Reserved User Page Flash with User Page 0x0080 0000 All addresses are byte addresses Flash base address Offset from base address 139 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-2. High Speed Mode 9.4.6 Quick Page Read A dedicated command, Quick Page Read (QPR), is provided to read all words in an addressed page. All bits in all words in this page are AND’ed together, returning a 1-bit result. This result is placed in the Quick Page Read Result (QPRR) bit in Flash Status Register (FSR). The QPR command is useful to check that a page is in an erased state. The QPR instruction is much faster than performing the erased-page check using a regular software subroutine. 9.4.7 Quick User Page Read A dedicated command, Quick User Page Read (QPRUP), is provided to read all words in the user page. All bits in all words in this page are AND’ed together, returning a 1-bit result. This result is placed in the Quick Page Read Result (QPRR) bit in Flash Status Register (FSR). The QPRUP command is useful to check that a page is in an erased state. The QPRUP instruction is much faster than performing the erased-page check using a regular software subroutine. 9.4.8 Page Buffer Operations The flash memory has a write and erase granularity of one page; data is written and erased in chunks of one page. When programming a page, the user must first write the new data into the Page Buffer. The contents of the entire Page Buffer is copied into the desired page in flash memory when the user issues the Write Page command, Refer to Section 9.5.1 on page 141. In order to program data into flash page Y, write the desired data to locations Y0 to Y31 in the regular flash memory map. Writing to an address A in the flash memory map will not update the flash memory, but will instead update location A%32 in the page buffer. The PAGEN field in the Flash Command (FCMD) register will at the same time be updated with the value A/32. Frequency Frequency limit for 0 wait state operation Normal High Speed mode 1 wait state 0 wait state 140 32142D–06/2013 ATUC64/128/256L3/4U Figure 9-3. Mapping from Page Buffer to Flash Internally, the flash memory stores data in 64-bit doublewords. Therefore, the native data size of the Page Buffer is also a 64-bit doubleword. All locations shown in Figure 9-3 are therefore doubleword locations. Since the HSB bus only has a 32-bit data width, two 32-bit HSB transfers must be performed to write a 64-bit doubleword into the Page Buffer. The FLASHCDW has logic to combine two 32-bit HSB transfers into a 64-bit data before writing this 64-bit data into the Page Buffer. This logic requires the word with the low address to be written to the HSB bus before the word with the high address. To exemplify, to write a 64-bit value to doubleword X0 residing in page X, first write a 32-bit word to the byte address pointing to address X0, thereafter write a word to the byte address pointing to address (X0+4). The page buffer is word-addressable and should only be written with aligned word transfers, never with byte or halfword transfers. The page buffer can not be read. The page buffer is also used for writes to the User page. Page buffer write operations are performed with 4 wait states. Any accesses attempted to the FLASHCDW on the HSB bus during these cycles will be automatically stalled. Writing to the page buffer can only change page buffer bits from one to zero, i.e. writing 0xAAAAAAAA to a page buffer location that has the value 0x00000000 will not change the page buffer value. The only way to change a bit from zero to one is to erase the entire page buffer with the Clear Page Buffer command. Z3 Z2 Z1 Z0 Z7 Z6 Z5 Z4 Z11 Z10 Z9 Z8 Z15 Z14 Z13 Z12 Z19 Z18 Z17 Z16 Z23 Z22 Z21 Z20 Z27 Z26 Z25 Z24 Z31 Z30 Z29 Z28 Y3 Y2 Y1 Y0 Y7 Y6 Y5 Y4 Y11 Y10 Y9 Y8 Y15 Y14 Y13 Y12 Y19 Y18 Y17 Y16 Y23 Y22 Y21 Y20 Y27 Y26 Y25 Y24 Y31 Y30 Y29 Y28 X3 X2 X1 X0 X7 X6 X5 X4 X11 X10 X9 X8 X15 X14 X13 X12 X19 X18 X17 X16 X23 X22 X21 X20 X27 X26 X25 X24 X31 X30 X29 X28 3 2 1 0 7 6 5 4 11 10 9 8 15 14 13 12 19 18 17 16 23 22 21 20 27 26 25 24 31 30 29 28 Page X Page Y Page Z Page Buffer 64-bit data Flash All locations are doubleword locations 141 32142D–06/2013 ATUC64/128/256L3/4U The page buffer is not automatically reset after a page write. The programmer should do this manually by issuing the Clear Page Buffer flash command. This can be done after a page write, or before the page buffer is loaded with data to be stored to the flash page. 9.5 Flash Commands The FLASHCDW offers a command set to manage programming of the flash memory, locking and unlocking of regions, and full flash erasing. See Section 9.8.2 for a complete list of commands. To run a command, the CMD field in the Flash Command Register (FCMD) has to be written with the command number. As soon as the FCMD register is written, the FRDY bit in the Flash Status Register (FSR) is automatically cleared. Once the current command is complete, the FSR.FRDY bit is automatically set. If an interrupt has been enabled by writing a one to FCR.FRDY, the interrupt request line of the Flash Controller is activated. All flash commands except for Quick Page Read (QPR) and Quick User Page Read (QPRUP) will generate an interrupt request upon completion if FCR.FRDY is one. Any HSB bus transfers attempting to read flash memory when the FLASHCDW is busy executing a flash command will be stalled, and allowed to continue when the flash command is complete. After a command has been written to FCMD, the programming algorithm should wait until the command has been executed before attempting to read instructions or data from the flash or writing to the page buffer, as the flash will be busy. The waiting can be performed either by polling the Flash Status Register (FSR) or by waiting for the flash ready interrupt. The command written to FCMD is initiated on the first clock cycle where the HSB bus interface in FLASHCDW is IDLE. The user must make sure that the access pattern to the FLASHCDW HSB interface contains an IDLE cycle so that the command is allowed to start. Make sure that no bus masters such as DMA controllers are performing endless burst transfers from the flash. Also, make sure that the CPU does not perform endless burst transfers from flash. This is done by letting the CPU enter sleep mode after writing to FCMD, or by polling FSR for command completion. This polling will result in an access pattern with IDLE HSB cycles. All the commands are protected by the same keyword, which has to be written in the eight highest bits of the FCMD register. Writing FCMD with data that does not contain the correct key and/or with an invalid command has no effect on the flash memory; however, the PROGE bit is set in the Flash Status Register (FSR). This bit is automatically cleared by a read access to the FSR register. Writing a command to FCMD while another command is being executed has no effect on the flash memory; however, the PROGE bit is set in the Flash Status Register (FSR). This bit is automatically cleared by a read access to the FSR register. If the current command writes or erases a page in a locked region, or a page protected by the BOOTPROT fuses, the command has no effect on the flash memory; however, the LOCKE bit is set in the FSR register. This bit is automatically cleared by a read access to the FSR register. 9.5.1 Write/Erase Page Operation Flash technology requires that an erase must be done before programming. The entire flash can be erased by an Erase All command. Alternatively, pages can be individually erased by the Erase Page command. The User page can be written and erased using the mechanisms described in this chapter. 142 32142D–06/2013 ATUC64/128/256L3/4U After programming, the page can be locked to prevent miscellaneous write or erase sequences. Locking is performed on a per-region basis, so locking a region locks all pages inside the region. Additional protection is provided for the lowermost address space of the flash. This address space is allocated for the Boot Loader, and is protected both by the lock bit(s) corresponding to this address space, and the BOOTPROT[2:0] fuses. Data to be written is stored in an internal buffer called the page buffer. The page buffer contains w words. The page buffer wraps around within the internal memory area address space and appears to be repeated by the number of pages in it. Writing of 8-bit and 16-bit data to the page buffer is not allowed and may lead to unpredictable data corruption. Data must be written to the page buffer before the programming command is written to the Flash Command Register (FCMD). The sequence is as follows: • Reset the page buffer with the Clear Page Buffer command. • Fill the page buffer with the desired contents as described in Section 9.4.8 on page 139. • Programming starts as soon as the programming key and the programming command are written to the Flash Command Register. The PAGEN field in the Flash Command Register (FCMD) must contain the address of the page to write. PAGEN is automatically updated when writing to the page buffer, but can also be written to directly. The FRDY bit in the Flash Status Register (FSR) is automatically cleared when the page write operation starts. • When programming is completed, the FRDY bit in the Flash Status Register (FSR) is set. If an interrupt was enabled by writing FCR.FRDY to one, an interrupt request is generated. Two errors can be detected in the FSR register after a programming sequence: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: Can have two different causes: – The page to be programmed belongs to a locked region. A command must be executed to unlock the corresponding region before programming can start. – A bus master without secure status attempted to program a page requiring secure privileges. 9.5.2 Erase All Operation The entire memory is erased if the Erase All command (EA) is written to the Flash Command Register (FCMD). Erase All erases all bits in the flash array. The User page is not erased. All flash memory locations, the general-purpose fuse bits, and the security bit are erased (reset to 0xFF) after an Erase All. The EA command also ensures that all volatile memories, such as register file and RAMs, are erased before the security bit is erased. Erase All operation is allowed only if no regions are locked, and the BOOTPROT fuses are configured with a BOOTPROT region size of 0. Thus, if at least one region is locked, the bit LOCKE in FSR is set and the command is cancelled. If the LOCKE bit in FCR is one, an interrupt request is set generated. When the command is complete, the FRDY bit in the Flash Status Register (FSR) is set. If an interrupt has been enabled by writing FCR.FRDY to one, an interrupt request is generated. Two errors can be detected in the FSR register after issuing the command: 143 32142D–06/2013 ATUC64/128/256L3/4U • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: At least one lock region is protected, or BOOTPROT is different from 0. The erase command has been aborted and no page has been erased. A “Unlock region containing given page” (UP) command must be executed to unlock any locked regions. 9.5.3 Region Lock Bits The flash memory has p pages, and these pages are grouped into 16 lock regions, each region containing p/16 pages. Each region has a dedicated lock bit preventing writing and erasing pages in the region. After production, the device may have some regions locked. These locked regions are reserved for a boot or default application. Locked regions can be unlocked to be erased and then programmed with another application or other data. To lock or unlock a region, the commands Lock Region Containing Page (LP) and Unlock Region Containing Page (UP) are provided. Writing one of these commands, together with the number of the page whose region should be locked/unlocked, performs the desired operation. One error can be detected in the FSR register after issuing the command: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. The lock bits are implemented using the lowest 16 general-purpose fuse bits. This means that lock bits can also be set/cleared using the commands for writing/erasing general-purpose fuse bits, see Section 9.6. The general-purpose bit being in an erased (1) state means that the region is unlocked. The lowermost pages in the flash can additionally be protected by the BOOTPROT fuses, see Section 9.6. 9.6 General-purpose Fuse Bits The flash memory has a number of general-purpose fuse bits that the application programmer can use freely. The fuse bits can be written and erased using dedicated commands, and read 144 32142D–06/2013 ATUC64/128/256L3/4U through a dedicated Peripheral Bus address. Some of the general-purpose fuse bits are reserved for special purposes, and should not be used for other functions: The BOOTPROT fuses protects the following address space for the Boot Loader: Table 9-2. General-purpose Fuses with Special Functions GeneralPurpose fuse number Name Usage 15:0 LOCK Region lock bits. 16 EPFL External Privileged Fetch Lock. Used to prevent the CPU from fetching instructions from external memories when in privileged mode. This bit can only be changed when the security bit is cleared. The address range corresponding to external memories is device-specific, and not known to the Flash Controller. This fuse bit is simply routed out of the CPU or bus system, the Flash Controller does not treat this fuse in any special way, except that it can not be altered when the security bit is set. If the security bit is set, only an external JTAG or aWire Chip Erase can clear EPFL. No internal commands can alter EPFL if the security bit is set. When the fuse is erased (i.e. "1"), the CPU can execute instructions fetched from external memories. When the fuse is programmed (i.e. "0"), instructions can not be executed from external memories. This fuse has no effect in devices with no External Memory Interface (EBI). 19:17 BOOTPROT Used to select one of eight different bootloader sizes. Pages included in the bootloader area can not be erased or programmed except by a JTAG or aWire chip erase. BOOTPROT can only be changed when the security bit is cleared. If the security bit is set, only an external JTAG or aWire Chip Erase can clear BOOTPROT, and thereby allow the pages protected by BOOTPROT to be programmed. No internal commands can alter BOOTPROT or the pages protected by BOOTPROT if the security bit is set. 21:20 SECURE Used to configure secure state and secure state debug capabilities. Decoded into SSE and SSDE signals as shown in Table 9-5. Refer to the AVR32 Architecture Manual and the AVR32UC Technical Reference Manual for more details on SSE and SSDE. 22 UPROT If programmed (i.e. “0”), the JTAG USER PROTECTION feature is enabled. If this fuse is programmed some HSB addresses will be accessible by JTAG access even if the flash security fuse is programmed. Refer to the JTAG documentation for more information on this functionality. This bit can only be changed when the security bit is cleared. 145 32142D–06/2013 ATUC64/128/256L3/4U The SECURE fuses have the following functionality: To erase or write a general-purpose fuse bit, the commands Write General-Purpose Fuse Bit (WGPB) and Erase General-Purpose Fuse Bit (EGPB) are provided. Writing one of these commands, together with the number of the fuse to write/erase, performs the desired operation. An entire General-Purpose Fuse byte can be written at a time by using the Program GP Fuse Byte (PGPFB) instruction. A PGPFB to GP fuse byte 2 is not allowed if the flash is locked by the security bit. The PFB command is issued with a parameter in the PAGEN field: • PAGEN[2:0] - byte to write • PAGEN[10:3] - Fuse value to write All general-purpose fuses can be erased by the Erase All General-Purpose fuses (EAGP) command. An EAGP command is not allowed if the flash is locked by the security bit. Two errors can be detected in the FSR register after issuing these commands: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. • Lock Error: – A write or erase of the BOOTPROT or EPFL or UPROT fuse bits was attempted while the flash is locked by the security bit. – A write or erase of the SECURE fuse bits was attempted when SECURE mode was enabled. The lock bits are implemented using the lowest 16 general-purpose fuse bits. This means that the 16 lowest general-purpose fuse bits can also be written/erased using the commands for locking/unlocking regions, see Section 9.5.3. Table 9-3. Boot Loader Area Specified by BOOTPROT BOOTPROT Pages protected by BOOTPROT Size of protected memory 7 None 0 6 0-1 1Kbyte 5 0-3 2Kbyte 4 0-7 4Kbyte 3 0-15 8Kbyte 2 0-31 16Kbyte 1 0-63 32Kbyte 0 0-127 64Kbyte Table 9-5. Secure State Configuration SECURE Functionality SSE SSDE 00 Secure state disabled 0 0 01 Secure enabled, secure state debug enabled 1 1 10 Secure enabled, secure state debug disabled 1 0 11 Secure state disabled 0 0 146 32142D–06/2013 ATUC64/128/256L3/4U 9.7 Security Bit The security bit allows the entire device to be locked from external JTAG, aWire, or other debug access for code security. The security bit can be written by a dedicated command, Set Security Bit (SSB). Once set, the only way to clear the security bit is through the JTAG or aWire Chip Erase command. Once the security bit is set, the following Flash Controller commands will be unavailable and return a lock error if attempted: • Write General-Purpose Fuse Bit (WGPB) to BOOTPROT or EPFL fuses • Erase General-Purpose Fuse Bit (EGPB) to BOOTPROT or EPFL fuses • Program General-Purpose Fuse Byte (PGPFB) of fuse byte 2 • Erase All General-Purpose Fuses (EAGPF) One error can be detected in the FSR register after issuing the command: • Programming Error: A bad keyword and/or an invalid command have been written in the FCMD register. 147 32142D–06/2013 ATUC64/128/256L3/4U 9.8 User Interface Note: 1. The value of the Lock bits depend on their programmed state. All other bits in FSR are 0. 2. All bits in FGPRHI/LO are dependent on the programmed state of the fuses they map to. Any bits in these registers not mapped to a fuse read as 0. 3. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 9-6. FLASHCDW Register Memory Map Offset Register Register Name Access Reset 0x00 Flash Control Register FCR Read/Write 0x00000000 0x04 Flash Command Register FCMD Read/Write 0x00000000 0x08 Flash Status Register FSR Read-only -(1) 0x0C Flash Parameter Register FPR Read-only -(3) 0x10 Flash Version Register FVR Read-only -(3) 0x14 Flash General Purpose Fuse Register Hi FGPFRHI Read-only -(2) 0x18 Flash General Purpose Fuse Register Lo FGPFRLO Read-only -(2) 148 32142D–06/2013 ATUC64/128/256L3/4U 9.8.1 Flash Control Register Name: FCR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • BRBUF: Branch Target Instruction Buffer Enable 0: The Branch Target Instruction Buffer is disabled. 1: The Branch Target Instruction Buffer is enabled. • SEQBUF: Sequential Instruction Fetch Buffer Enable 0: The Sequential Instruction Fetch Buffer is disabled. 1: The Sequential Instruction Fetch Buffer is enabled. • FWS: Flash Wait State 0: The flash is read with 0 wait states. 1: The flash is read with 1 wait state. • PROGE: Programming Error Interrupt Enable 0: Programming Error does not generate an interrupt request. 1: Programming Error generates an interrupt request. • LOCKE: Lock Error Interrupt Enable 0: Lock Error does not generate an interrupt request. 1: Lock Error generates an interrupt request. • FRDY: Flash Ready Interrupt Enable 0: Flash Ready does not generate an interrupt request. 1: Flash Ready generates an interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - BRBUF SEQBUF - 76543210 - FWS - - PROGE LOCKE - FRDY 149 32142D–06/2013 ATUC64/128/256L3/4U 9.8.2 Flash Command Register Name: FCMD Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 The FCMD can not be written if the flash is in the process of performing a flash command. Doing so will cause the FCR write to be ignored, and the PROGE bit in FSR to be set. • KEY: Write protection key This field should be written with the value 0xA5 to enable the command defined by the bits of the register. If the field is written with a different value, the write is not performed and no action is started. This field always reads as 0. • PAGEN: Page number The PAGEN field is used to address a page or fuse bit for certain operations. In order to simplify programming, the PAGEN field is automatically updated every time the page buffer is written to. For every page buffer write, the PAGEN field is updated with the page number of the address being written to. Hardware automatically masks writes to the PAGEN field so that only bits representing valid page numbers can be written, all other bits in PAGEN are always 0. As an example, in a flash with 1024 pages (page 0 - page 1023), bits 15:10 will always be 0. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 PAGEN [15:8] 15 14 13 12 11 10 9 8 PAGEN [7:0] 76543210 - - CMD Table 9-7. Semantic of PAGEN field in different commands Command PAGEN description No operation Not used Write Page The number of the page to write Clear Page Buffer Not used Lock region containing given Page Page number whose region should be locked Unlock region containing given Page Page number whose region should be unlocked Erase All Not used Write General-Purpose Fuse Bit GPFUSE # Erase General-Purpose Fuse Bit GPFUSE # Set Security Bit Not used 150 32142D–06/2013 ATUC64/128/256L3/4U • CMD: Command This field defines the flash command. Issuing any unused command will cause the Programming Error bit in FSR to be set, and the corresponding interrupt to be requested if the PROGE bit in FCR is one. Program GP Fuse Byte WriteData[7:0], ByteAddress[2:0] Erase All GP Fuses Not used Quick Page Read Page number Write User Page Not used Erase User Page Not used Quick Page Read User Page Not used High Speed Mode Enable Not used High Speed Mode Disable Not used Table 9-8. Set of commands Command Value Mnemonic No operation 0 NOP Write Page 1 WP Erase Page 2 EP Clear Page Buffer 3 CPB Lock region containing given Page 4 LP Unlock region containing given Page 5 UP Erase All 6 EA Write General-Purpose Fuse Bit 7 WGPB Erase General-Purpose Fuse Bit 8 EGPB Set Security Bit 9 SSB Program GP Fuse Byte 10 PGPFB Erase All GPFuses 11 EAGPF Quick Page Read 12 QPR Write User Page 13 WUP Erase User Page 14 EUP Quick Page Read User Page 15 QPRUP High Speed Mode Enable 16 HSEN High Speed Mode Disable 17 HSDIS RESERVED 16-31 Table 9-7. Semantic of PAGEN field in different commands Command PAGEN description 151 32142D–06/2013 ATUC64/128/256L3/4U 9.8.3 Flash Status Register Name: FSR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • LOCKx: Lock Region x Lock Status 0: The corresponding lock region is not locked. 1: The corresponding lock region is locked. • HSMODE: High-Speed Mode 0: High-speed mode disabled. 1: High-speed mode enabled. • QPRR: Quick Page Read Result 0: The result is zero, i.e. the page is not erased. 1: The result is one, i.e. the page is erased. • SECURITY: Security Bit Status 0: The security bit is inactive. 1: The security bit is active. • PROGE: Programming Error Status Automatically cleared when FSR is read. 0: No invalid commands and no bad keywords were written in the Flash Command Register FCMD. 1: An invalid command and/or a bad keyword was/were written in the Flash Command Register FCMD. • LOCKE: Lock Error Status Automatically cleared when FSR is read. 0: No programming of at least one locked lock region has happened since the last read of FSR. 1: Programming of at least one locked lock region has happened since the last read of FSR. • FRDY: Flash Ready Status 0: The Flash Controller is busy and the application must wait before running a new command. 1: The Flash Controller is ready to run a new command. 31 30 29 28 27 26 25 24 LOCK15 LOCK14 LOCK13 LOCK12 LOCK11 LOCK10 LOCK9 LOCK8 23 22 21 20 19 18 17 16 LOCK7 LOCK6 LOCK5 LOCK4 LOCK3 LOCK2 LOCK1 LOCK0 15 14 13 12 11 10 9 8 -------- 76543210 - HSMODE QPRR SECURITY PROGE LOCKE - FRDY 152 32142D–06/2013 ATUC64/128/256L3/4U 9.8.4 Flash Parameter Register Name: FPR Access Type: Read-only Offset: 0x0C Reset Value: - • PSZ: Page Size The size of each flash page. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - PSZ 76543210 - - - - FSZ Table 9-9. Flash Page Size PSZ Page Size 0 32 Byte 1 64 Byte 2 128 Byte 3 256 Byte 4 512 Byte 5 1024 Byte 6 2048 Byte 7 4096 Byte 153 32142D–06/2013 ATUC64/128/256L3/4U • FSZ: Flash Size The size of the flash. Not all device families will provide all flash sizes indicated in the table. Table 9-10. Flash Size FSZ Flash Size FSZ Flash Size 0 4 Kbyte 8 192 Kbyte 1 8 Kbyte 9 256 Kbyte 2 16 Kbyte 10 384 Kbyte 3 32 Kbyte 11 512 Kbyte 4 48 Kbyte 12 768 Kbyte 5 64 Kbyte 13 1024 Kbyte 6 96 Kbyte 14 2048 Kbyte 7 128 Kbyte 15 Reserved 154 32142D–06/2013 ATUC64/128/256L3/4U 9.8.5 Flash Version Register Name: FVR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 155 32142D–06/2013 ATUC64/128/256L3/4U 9.8.6 Flash General Purpose Fuse Register High Name: FGPFRHI Access Type: Read-only Offset: 0x14 Reset Value: - This register is only used in systems with more than 32 GP fuses. • GPFxx: General Purpose Fuse xx 0: The fuse has a written/programmed state. 1: The fuse has an erased state. 31 30 29 28 27 26 25 24 GPF63 GPF62 GPF61 GPF60 GPF59 GPF58 GPF57 GPF56 23 22 21 20 19 18 17 16 GPF55 GPF54 GPF53 GPF52 GPF51 GPF50 GPF49 GPF48 15 14 13 12 11 10 9 8 GPF47 GPF46 GPF45 GPF44 GPF43 GPF42 GPF41 GPF40 76543210 GPF39 GPF38 GPF37 GPF36 GPF35 GPF34 GPF33 GPF32 156 32142D–06/2013 ATUC64/128/256L3/4U 9.8.7 Flash General Purpose Fuse Register Low Name: FGPFRLO Access Type: Read-only Offset: 0x18 Reset Value: - • GPFxx: General Purpose Fuse xx 0: The fuse has a written/programmed state. 1: The fuse has an erased state. 31 30 29 28 27 26 25 24 GPF31 GPF30 GPF29 GPF28 GPF27 GPF26 GPF25 GPF24 23 22 21 20 19 18 17 16 GPF23 GPF22 GPF21 GPF20 GPF19 GPF18 GPF17 GPF16 15 14 13 12 11 10 9 8 GPF15 GPF14 GPF13 GPF12 GPF11 GPF10 GPF09 GPF08 76543210 GPF07 GPF06 GPF05 GPF04 GPF03 GPF02 GPF01 GPF00 157 32142D–06/2013 ATUC64/128/256L3/4U 9.9 Fuse Settings The flash contains 32 general purpose fuses. These 32 fuses can be found in the Flash General Purpose Fuse Register Low (FGPFRLO). The Flash General Purpose Fuse Register High (FGPFRHI) is not used. In addition to the general purpose fuses, parts of the flash user page can have a defined meaning outside of the flash controller and will also be described in this section. Note that when writing to the user page the values do not get loaded by the other modules on the device until a chip reset occurs. The general purpose fuses are erased by a JTAG or aWire chip erase. 158 32142D–06/2013 ATUC64/128/256L3/4U 9.9.1 Flash General Purpose Fuse Register Low (FGPFRLO) • BODEN: Brown Out Detector Enable • BODHYST: Brown Out Detector Hysteresis 0: The Brown out detector hysteresis is disabled 1: The Brown out detector hysteresis is enabled • BODLEVEL: Brown Out Detector Trigger Level This controls the voltage trigger level for the Brown out detector. Refer to ”Electrical Characteristics” on page 897. • UPROT, SECURE, BOOTPROT, EPFL, LOCK These are Flash Controller fuses and are described in the FLASHCDW section. 9.9.1.1 Default Fuse Value The devices are shipped with the FGPFRLO register value:0xE07FFFFF: • BODEN fuses set to 11. BOD is disabled. • BODHYST fuse set to 1. The BOD hysteresis is enabled. • BODLEVEL fuses set to 000000. This is the minimum voltage trigger level for BOD. This level is lower than the POR level, so when BOD is enabled, it will never trigger with this default value. • UPROT fuse set to 1. • SECURE fuse set to 11. • BOOTPROT fuses set to 111. The bootloader protection is disabled. • EPFL fuse set to 1. External privileged fetch is not locked. • LOCK fuses set to 1111111111111111. No region locked. After the JTAG or aWire chip erase command, the FGPFR register value is 0xFFFFFFFF. 31 30 29 28 27 26 25 24 BODEN BODHYST BODLEVEL[5:1] 23 22 21 20 19 18 17 16 BODLEVEL[0] UPROT SECURE BOOTPROT EPFL 15 14 13 12 11 10 9 8 LOCK[15:8] 7 6543210 LOCK[7:0] BODEN Description 00 BOD disabled 01 BOD enabled, BOD reset enabled 10 BOD enabled, BOD reset disabled 11 BOD disabled 159 32142D–06/2013 ATUC64/128/256L3/4U 9.9.2 First Word of the User Page (Address 0x80800000) • WDTAUTO: WatchDog Timer Auto Enable at Startup 0: The WDT is automatically enabled at startup. 1: The WDT is not automatically enabled at startup. Please refer to the WDT chapter for detail about timeout settings when the WDT is automatically enabled. 9.9.2.1 Default user page first word value The devices are shipped with the user page erased (all bits 1): • WDTAUTO set to 1, WDT disabled. 31 30 29 28 27 26 25 24 - ------- 23 22 21 20 19 18 17 16 - ------- 15 14 13 12 11 10 9 8 - ------- 7 6543210 - - - - - - - WDTAUTO 160 32142D–06/2013 ATUC64/128/256L3/4U 9.9.3 Second Word of the User Page (Address 0x80800004) • SSADRR: Secure State End Address for the RAM • SSADRF: Secure State End Address for the Flash 9.9.3.1 Default user page second word value The devices are shipped with the User page erased (all bits 1). 9.10 Serial Number Each device has a unique 120 bits serial number readable from address 0x8080020C to 0x8080021A. 9.11 Module Configuration The specific configuration for each FLASHCDW instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 31 30 29 28 27 26 25 24 SSADRR[15:8] 23 22 21 20 19 18 17 16 SSADRR[7:0] 15 14 13 12 11 10 9 8 SSADRF[15:8] 7 6543210 SSADRF[7:0] Table 9-11. Module Configuration Feature ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U Flash size 256Kbytes 128Kbytes 64Kbytes Number of pages 512 256 128 Page size 512 bytes 512 bytes 512 bytes Table 9-12. Module Clock Name Module Name Clock Name Description FLASHCDW CLK_FLASHCDW_HSB Clock for the FLASHCDW HSB interface CLK_FLASHCDW_PB Clock for the FLASHCDW PB interface 161 32142D–06/2013 ATUC64/128/256L3/4U Table 9-13. Register Reset Values Register ATUC256L3U, ATUC256L4U ATUC128L3U, ATUC128L4U ATUC64L3U, ATUC64L4U FVR 0x00000120 0x00000120 0x00000120 FPR 0x00000409 0x00000407 0x00000405 162 32142D–06/2013 ATUC64/128/256L3/4U 10. Secure Access Unit (SAU) Rev: 1.1.1.3 10.1 Features • Remaps registers in memory regions protected by the MPU to regions not protected by the MPU • Programmable physical address for each channel • Two modes of operation: Locked and Open – In Locked Mode, access to a channel must be preceded by an unlock action • An unlocked channel remains open only for a specific amount of time, if no access is performed during this time, the channel is relocked • Only one channel can be open at a time, opening a channel while another one is open locks the first one • Access to a locked channel is denied, a bus error and optionally an interrupt is returned • If a channel is relocked due to an unlock timeout, an interrupt can optionally be generated – In Open Mode, all channels are permanently unlocked 10.2 Overview In many systems, erroneous access to peripherals can lead to catastrophic failure. An example of such a peripheral is the Pulse Width Modulator (PWM) used to control electric motors. The PWM outputs a pulse train that controls the motor. If the control registers of the PWM module are inadvertently updated with wrong values, the motor can start operating out of control, possibly causing damage to the application and the surrounding environment. However, sometimes the PWM control registers must be updated with new values, for example when modifying the pulse train to accelerate the motor. A mechanism must be used to protect the PWM control registers from inadvertent access caused by for example: • Errors in the software code • Transient errors in the CPU caused by for example electrical noise altering the execution path of the program To improve the security in a computer system, the AVR32UC implements a Memory Protection Unit (MPU). The MPU can be set up to limit the accesses that can be performed to specific memory addresses. The MPU divides the memory space into regions, and assigns a set of access restrictions on each region. Access restrictions can for example be read/write if the CPU is in supervisor mode, and read-only if the CPU is in application mode. The regions can be of different size, but each region is usually quite large, e.g. protecting 1 kilobyte of address space or more. Furthermore, access to each region is often controlled by the execution state of the CPU, i.e. supervisor or application mode. Such a simple control mechanism is often too inflexible (too coarse-grained chunks) and with too much overhead (often requiring system calls to access protected memory locations) for simple or real-time systems such as embedded microcontrollers. Usually, the Secure Access Unit (SAU) is used together with the MPU to provide the required security and integrity. The MPU is set up to protect regions of memory, while the SAU is set up to provide a secure channel into specific memory locations that are protected by the MPU. These specific locations can be thought of as fine-grained overrides of the general coarsegrained protection provided by the MPU. 163 32142D–06/2013 ATUC64/128/256L3/4U 10.3 Block Diagram Figure 10-1 presents the SAU integrated in an example system with a CPU, some memories, some peripherals, and a bus system. The SAU is connected to both the Peripheral Bus (PB) and the High Speed Bus (HSB). Configuration of the SAU is done via the PB, while memory accesses are done via the HSB. The SAU receives an access on its HSB slave interface, remaps it, checks that the channel is unlocked, and if so, initiates a transfer on its HSB master interface to the remapped address. The thin arrows in Figure 10-1 exemplifies control flow when using the SAU. The CPU wants to read the RX Buffer in the USART. The MPU has been configured to protect all registers in the USART from user mode access, while the SAU has been configured to remap the RX Buffer into a memory space that is not protected by the MPU. This unprotected memory space is mapped into the SAU HSB slave space. When the CPU reads the appropriate address in the SAU, the SAU will perform an access to the desired RX buffer register in the USART, and thereafter return the read results to the CPU. The return data flow will follow the opposite direction of the control flow arrows in Figure 10-1. Figure 10-1. SAU Block Diagram SAU Channel Bus master MPU CPU Bus slave USART PWM Bus slave Bus master Bus slave Flash Bus slave RAM Bus bridge SAU Configuration Interrupt request High Speed Bus SAU Peripheral Bus 164 32142D–06/2013 ATUC64/128/256L3/4U 10.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 10.4.1 Power Management If the CPU enters a sleep mode that disables clocks used by the SAU, the SAU will stop functioning and resume operation after the system wakes up from sleep mode. 10.4.2 Clocks The SAU has two bus clocks connected: One High Speed Bus clock (CLK_SAU_HSB) and one Peripheral Bus clock (CLK_SAU_PB). These clocks are generated by the Power Manager. Both clocks are enabled at reset, and can be disabled by writing to the Power Manager. The user has to ensure that CLK_SAU_HSB is not turned off before accessing the SAU. Likewise, the user must ensure that no bus access is pending in the SAU before disabling CLK_SAU_HSB. Failing to do so may deadlock the High Speed Bus. 10.4.3 Interrupt The SAU interrupt request line is connected to the interrupt controller. Using the SAU interrupt requires the interrupt controller to be programmed first. 10.4.4 Debug Operation When an external debugger forces the CPU into debug mode, the SAU continues normal operation. If the SAU is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 10.5 Functional Description 10.5.1 Enabling the SAU The SAU is enabled by writing a one to the Enable (EN) bit in the Control Register (CR). This will set the SAU Enabled (EN) bit in the Status Register (SR). 10.5.2 Configuring the SAU Channels The SAU has a set of channels, mapped in the HSB memory space. These channels can be configured by a Remap Target Register (RTR), located at the same memory address. When the SAU is in normal mode, the SAU channel is addressed, and when the SAU is in setup mode, the RTR can be addressed. Before the SAU can be used, the channels must be configured and enabled. To configure a channel, the corresponding RTR must be programmed with the Remap Target Address. To do this, make sure the SAU is in setup mode by writing a one to the Setup Mode Enable (SEN) bit in CR. This makes sure that a write to the RTR address accesses the RTR, not the SAU channel. Thereafter, the RTR is written with the address to remap to, typically the address of a specific PB register. When all channels have been configured, return to normal mode by writing a one to the Setup Mode Disable (SDIS) in CR. The channels can now be enabled by writing ones to the corresponding bits in the Channel Enable Registers (CERH/L). The SAU is only able to remap addresses above 0xFFFC0000. 165 32142D–06/2013 ATUC64/128/256L3/4U 10.5.2.1 Protecting SAU configuration registers In order to prevent the SAU configuration registers to be changed by malicious or runaway code, they should be protected by the MPU as soon as they have been configured. Maximum security is provided in the system if program memory does not contain any code to unprotect the configuration registers in the MPU. This guarantees that runaway code can not accidentally unprotect and thereafter change the SAU configuration registers. 10.5.3 Lock Mechanism The SAU can be configured to use two different access mechanisms: Open and Locked. In Open Mode, SAU channels can be accessed freely after they have been configured and enabled. In order to prevent accidental accesses to remapped addresses, it is possible to configure the SAU in Locked Mode. Writing a one to the Open Mode bit in the CONFIG register (CONFIG.OPEN) will enable Open Mode. Writing a zero to CONFIG.OPEN will enable Locked Mode. When using Locked Mode, the lock mechanism must be configured by writing a user defined key value to the Unlock Key (UKEY) field in the Configuration Register (CONFIG). The number of CLK_SAU_HSB cycles the channel remains unlocked must be written to the Unlock Number of Clock Cycles (UCYC) field in CONFIG. Access control to the SAU channels is enabled by means of the Unlock Register (UR), which resides in the same address space as the SAU channels. Before a channel can be accessed, the unlock register must be written with th correct key and channel number (single write access). Access to the channel is then permitted for the next CONFIG.UCYC clock cycles, or until a successful access to the unlocked channel has been made. Only one channel can be unlocked at a time. If any other channel is unlocked at the time of writing UR, this channel will be automatically locked before the channel addressed by the UR write is unlocked. An attempted access to a locked channel will be aborted, and the Channel Access Unsuccessful bit (SR.CAU) will be set. Any pending errors bits in SR must be cleared before it is possible to access UR. The following SR bits are defined as error bits: EXP, CAU, URREAD, URKEY, URES, MBERROR, RTRADR. If any of these bits are set while writing to UR, the write is aborted and the Unlock Register Error Status (URES) bit in SR is set. 10.5.4 Normal Operation The following sequence must be used in order to access a SAU channel in normal operation (CR.SEN=0): 1. If not in Open Mode, write the unlock key to UR.KEY and the channel number to UR.CHANNEL. 2. Perform the read or write operation to the SAU channel. If not in Open Mode, this must be done within CONFIG.UCYC clock cycles of unlocking the channel. The SAU will use its HSB master interface to remap the access to the target address pointed to by the corresponding RTR. 3. To confirm that the access was successful, wait for the IDLE transfer status bit (SR.IDLE) to indicate the operation is completed. Then check SR for possible error conditions. The SAU can be configured to generate interrupt requests or a Bus Error Exception if the access failed. 166 32142D–06/2013 ATUC64/128/256L3/4U 10.5.4.1 Operation example Figure 10-2 shows a typical memory map, consisting of some memories, some simple peripherals, and a SAU with multiple channels and an Unlock Register (UR). Imagine that the MPU has been set up to disallow all accesses from the CPU to the grey modules. Thus the CPU has no way of accessing for example the Transmit Holding register in the UART, present on address X on the bus. Note that the SAU RTRs are not protected by the MPU, thus the RTRs can be accessed. If for example RTR0 is configured to point to address X, an access to RTR0 will be remapped by the SAU to address X according to the algorithm presented above. By programming the SAU RTRs, specific addresses in modules that have generally been protected by the MPU can be performed. Figure 10-2. Example Memory Map for a System with SAU 10.5.5 Interrupts The SAU can generate an interrupt request to signal different events. All events that can generate an interrupt request have dedicated bits in the Status Register (SR). An interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). The following SR bits are used for signalling the result of SAU accesses: • RTR Address Error (RTRADR) is set if an illegal address is written to the RTRs. Only addresses in the range 0xFFFC0000-0xFFFFFFFF are allowed. • Master Interface Bus Error (MBERROR) is set if any of the conditions listed in Section 10.5.7 occurred. Transmit Holding Baudrate Control Receive Holding Channel 1 RTR0 RTR1 Address X Address Z UART SAU CONFIG SAU CHANNEL UR RTR62 ... 167 32142D–06/2013 ATUC64/128/256L3/4U • Unlock Register Error Status (URES) is set if an attempt was made to unlock a channel by writing to the Unlock Register while one or more error bits in SR were set (see Section 10.5.6). The unlock operation was aborted. • Unlock Register Key Error (URKEY) is set if the Unlock Register was attempted written with an invalid key. • Unlock Register Read (URREAD) is set if the Unlock Register was attempted read. • Channel Access Unsuccessful (CAU) is set if the channel access was unsuccessful. • Channel Access Successful (CAS) is set if the channel access was successful. • Channel Unlock Expired (EXP) is set if the channel lock expired, with no channel being accessed after the channel was unlocked. 10.5.6 Error bits If error bits are set when attempting to unlock a channel, SR.URES will be set. The following SR bits are considered error bits: • EXP • CAU • URREAD • URKEY • URES • MBERROR • RTRADR 10.5.7 Bus Error Responses By writing a one to the Bus Error Response Enable bit (CR.BERREN), serious access errors will be configured to return a bus error to the CPU. This will cause the CPU to execute its Bus Error Data Fetch exception routine. The conditions that can generate a bus error response are: • Reading the Unlock Register • Trying to access a locked channel • The SAU HSB master receiving a bus error response from its addressed slave 10.5.8 Disabling the SAU To disable the SAU, the user must first ensure that no SAU bus operations are pending. This can be done by checking that the SR.IDLE bit is set. The SAU may then be disabled by writing a one to the Disable (DIS) bit in CR. 168 32142D–06/2013 ATUC64/128/256L3/4U 10.6 User Interface The following addresses are used by SAU channel configuration registers. All offsets are relative to the SAU’s PB base address. Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. The following addresses are used by SAU channel registers. All offsets are relative to the SAU’s HSB base address. The number of channels implemented is device specific, refer to the Module Configuration section at the end of this chapter. Table 10-1. SAU Configuration Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Configuration Register CONFIG Write-only 0x00000000 0x08 Channel Enable Register High CERH Read/Write 0x00000000 0x0C Channel Enable Register Low CERL Read/Write 0x00000000 0x10 Status Register SR Read-only 0x00000400 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Interrupt Clear Register ICR Write-only 0x00000000 0x24 Parameter Register PARAMETER Read-only -(1) 0x28 Version Register VERSION Read-only -(1) Table 10-2. SAU Channel Register Memory Map Offset Register Register Name Access Reset 0x00 Remap Target Register 0 RTR0 Read/Write N/A 0x04 Remap Target Register 1 RTR1 Read/Write N/A 0x08 Remap Target Register 2 RTR2 Read/Write N/A ... ... ... ... ... 0x04*n Remap Target Register n RTRn Read/Write N/A 0xFC Unlock Register UR Write-only N/A 169 32142D–06/2013 ATUC64/128/256L3/4U 10.6.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • BERRDIS: Bus Error Response Disable Writing a zero to this bit has no effect. Writing a one to this bit disables Bus Error Response from the SAU. • BERREN: Bus Error Response Enable Writing a zero to this bit has no effect. Writing a one to this bit enables Bus Error Response from the SAU. • SDIS: Setup Mode Disable Writing a zero to this bit has no effect. Writing a one to this bit exits setup mode. • SEN: Setup Mode Enable Writing a zero to this bit has no effect. Writing a one to this bit enters setup mode. • DIS: SAU Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the SAU. • EN: SAU Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the SAU. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - BERRDIS BERREN SDIS SEN DIS EN 170 32142D–06/2013 ATUC64/128/256L3/4U 10.6.2 Configuration Register Name: CONFIG Access Type: Write-only Offset: 0x04 Reset Value: 0x00000000 • OPEN: Open Mode Enable Writing a zero to this bit disables open mode. Writing a one to this bit enables open mode. • UCYC: Unlock Number of Clock Cycles Once a channel has been unlocked, it remains unlocked for this amount of CLK_SAU_HSB clock cycles or until one access to a channel has been made. • UKEY: Unlock Key The value in this field must be written to UR.KEY to unlock a channel. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - OPEN 15 14 13 12 11 10 9 8 UCYC 76543210 UKEY 171 32142D–06/2013 ATUC64/128/256L3/4U 10.6.3 Channel Enable Register High Name: CERH Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • CERH[n]: Channel Enable Register High 0: Channel (n+32) is not enabled. 1: Channel (n+32) is enabled. 31 30 29 28 27 26 25 24 - CERH[30:24] 23 22 21 20 19 18 17 16 CERH[23:16] 15 14 13 12 11 10 9 8 CERH[15:8] 76543210 CERH[7:0] 172 32142D–06/2013 ATUC64/128/256L3/4U 10.6.4 Channel Enable Register Low Name: CERL Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • CERL[n]: Channel Enable Register Low 0: Channel n is not enabled. 1: Channel n is enabled. 31 30 29 28 27 26 25 24 CERL[31:24] 23 22 21 20 19 18 17 16 CERL[23:16] 15 14 13 12 11 10 9 8 CERL[15:8] 76543210 CERL[7:0] 173 32142D–06/2013 ATUC64/128/256L3/4U 10.6.5 Status Register Name: SR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000400 • IDLE This bit is cleared when a read or write operation to the SAU channel is started. This bit is set when the operation is completed and no SAU bus operations are pending. • SEN: SAU Setup Mode Enable This bit is cleared when the SAU exits setup mode. This bit is set when the SAU enters setup mode. • EN: SAU Enabled This bit is cleared when the SAU is disabled. This bit is set when the SAU is enabled. • RTRADR: RTR Address Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if, in the configuration phase, an RTR was written with an illegal address, i.e. the upper 16 bits in the address were different from 0xFFFC, 0xFFFD, 0xFFFE or 0xFFFF. • MBERROR: Master Interface Bus Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if a channel access generated a transfer on the master interface that received a bus error response from the addressed slave. • URES: Unlock Register Error Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if an attempt was made to unlock a channel by writing to the Unlock Register while one or more error bits were set in SR. The unlock operation was aborted. • URKEY: Unlock Register Key Error This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if the Unlock Register was attempted written with an invalid key. • URREAD: Unlock Register Read This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if the Unlock Register was read. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - IDLE SEN EN 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 174 32142D–06/2013 ATUC64/128/256L3/4U • CAU: Channel Access Unsuccessful This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel access was unsuccessful, i.e. an access was attempted to a locked or disabled channel. • CAS: Channel Access Successful This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel access successful, i.e. one access was made after the channel was unlocked. • EXP: Channel Unlock Expired This bit is cleared when the corresponding bit in ICR is written to one. This bit is set if channel unlock has expired, i.e. no access being made after the channel was unlocked. 175 32142D–06/2013 ATUC64/128/256L3/4U 10.6.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 176 32142D–06/2013 ATUC64/128/256L3/4U 10.6.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 177 32142D–06/2013 ATUC64/128/256L3/4U 10.6.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 178 32142D–06/2013 ATUC64/128/256L3/4U 10.6.9 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and any corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RTRADR MBERROR URES URKEY URREAD CAU CAS EXP 179 32142D–06/2013 ATUC64/128/256L3/4U 10.6.10 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x24 Reset Value: - • CHANNELS: Number of channels implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CHANNELS 180 32142D–06/2013 ATUC64/128/256L3/4U 10.6.11 Version Register Name: VERSION Access Type: Write-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 181 32142D–06/2013 ATUC64/128/256L3/4U 10.6.12 Remap Target Register n Name: RTRn Access Type: Read/Write Offset: n*4 Reset Value: 0x00000000 • RTR: Remap Target Address for Channel n RTR[31:16] must have one of the following values, any other value will result in UNDEFINED behavior: 0xFFFC 0xFFFD 0xFFFE 0xFFFF RTR[1:0] must be written to 00, any other value will result in UNDEFINED behavior. 31 30 29 28 27 26 25 24 RTR[31:24] 23 22 21 20 19 18 17 16 RTR[23:16] 15 14 13 12 11 10 9 8 RTR[15:8] 76543210 RTR[7:0] 182 32142D–06/2013 ATUC64/128/256L3/4U 10.6.13 Unlock Register Name: UR Access Type : Write-only Offset: 0xFC Reset Value: 0x00000000 • KEY: Unlock Key The correct key must be written in order to unlock a channel. The key value written must correspond to the key value defined in CONFIG.UKEY. • CHANNEL: Channel Number Number of the channel to unlock. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 KEY 76543210 - - CHANNEL 183 32142D–06/2013 ATUC64/128/256L3/4U 10.7 Module Configuration The specific configuration for each SAU instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 10-3. SAU configuration Feature SAU SAU Channels 16 Table 10-4. SAU clock name Module name Clock name Description SAU CLK_SAU_HSB Clock for the SAU HSB interface SAU CLK_SAU_PB Clock for the SAU PB interface Table 10-5. Register Reset Values Register Reset Value VERSION 0x00000111 PARAMETER 0x00000010 184 32142D–06/2013 ATUC64/128/256L3/4U 11. HSB Bus Matrix (HMATRIXB) Rev: 1.3.0.3 11.1 Features • User Interface on peripheral bus • Configurable number of masters (up to 16) • Configurable number of slaves (up to 16) • One decoder for each master • Programmable arbitration for each slave – Round-Robin – Fixed priority • Programmable default master for each slave – No default master – Last accessed default master – Fixed default master • One cycle latency for the first access of a burst • Zero cycle latency for default master • One special function register for each slave (not dedicated) 11.2 Overview The Bus Matrix implements a multi-layer bus structure, that enables parallel access paths between multiple High Speed Bus (HSB) masters and slaves in a system, thus increasing the overall bandwidth. The Bus Matrix interconnects up to 16 HSB Masters to up to 16 HSB Slaves. The normal latency to connect a master to a slave is one cycle except for the default master of the accessed slave which is connected directly (zero cycle latency). The Bus Matrix provides 16 Special Function Registers (SFR) that allow the Bus Matrix to support application specific features. 11.3 Product Dependencies In order to configure this module by accessing the user registers, other parts of the system must be configured correctly, as described below. 11.3.1 Clocks The clock for the HMATRIX bus interface (CLK_HMATRIX) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. 11.4 Functional Description 11.4.1 Special Bus Granting Mechanism The Bus Matrix provides some speculative bus granting techniques in order to anticipate access requests from some masters. This mechanism reduces latency at first access of a burst or single transfer. This bus granting mechanism sets a different default master for every slave. At the end of the current access, if no other request is pending, the slave remains connected to its associated default master. A slave can be associated with three kinds of default masters: no default master, last access master, and fixed default master. 185 32142D–06/2013 ATUC64/128/256L3/4U To change from one kind of default master to another, the Bus Matrix user interface provides the Slave Configuration Registers, one for each slave, that set a default master for each slave. The Slave Configuration Register contains two fields: DEFMSTR_TYPE and FIXED_DEFMSTR. The 2-bit DEFMSTR_TYPE field selects the default master type (no default, last access master, fixed default master), whereas the 4-bit FIXED_DEFMSTR field selects a fixed default master provided that DEFMSTR_TYPE is set to fixed default master. Please refer to the Bus Matrix user interface description. 11.4.1.1 No Default Master At the end of the current access, if no other request is pending, the slave is disconnected from all masters. No Default Master suits low-power mode. 11.4.1.2 Last Access Master At the end of the current access, if no other request is pending, the slave remains connected to the last master that performed an access request. 11.4.1.3 Fixed Default Master At the end of the current access, if no other request is pending, the slave connects to its fixed default master. Unlike last access master, the fixed master does not change unless the user modifies it by a software action (field FIXED_DEFMSTR of the related SCFG). 11.4.2 Arbitration The Bus Matrix provides an arbitration mechanism that reduces latency when conflict cases occur, i.e. when two or more masters try to access the same slave at the same time. One arbiter per HSB slave is provided, thus arbitrating each slave differently. The Bus Matrix provides the user with the possibility of choosing between 2 arbitration types for each slave: 1. Round-Robin Arbitration (default) 2. Fixed Priority Arbitration This is selected by the ARBT field in the Slave Configuration Registers (SCFG). Each algorithm may be complemented by selecting a default master configuration for each slave. When a re-arbitration must be done, specific conditions apply. This is described in “Arbitration Rules” . 11.4.2.1 Arbitration Rules Each arbiter has the ability to arbitrate between two or more different master requests. In order to avoid burst breaking and also to provide the maximum throughput for slave interfaces, arbitration may only take place during the following cycles: 1. Idle Cycles: When a slave is not connected to any master or is connected to a master which is not currently accessing it. 2. Single Cycles: When a slave is currently doing a single access. 3. End of Burst Cycles: When the current cycle is the last cycle of a burst transfer. For defined length burst, predicted end of burst matches the size of the transfer but is managed differently for undefined length burst. This is described below. 4. Slot Cycle Limit: When the slot cycle counter has reached the limit value indicating that the current master access is too long and must be broken. This is described below. 186 32142D–06/2013 ATUC64/128/256L3/4U • Undefined Length Burst Arbitration In order to avoid long slave handling during undefined length bursts (INCR), the Bus Matrix provides specific logic in order to re-arbitrate before the end of the INCR transfer. A predicted end of burst is used as a defined length burst transfer and can be selected among the following five possibilities: 1. Infinite: No predicted end of burst is generated and therefore INCR burst transfer will never be broken. 2. One beat bursts: Predicted end of burst is generated at each single transfer inside the INCP transfer. 3. Four beat bursts: Predicted end of burst is generated at the end of each four beat boundary inside INCR transfer. 4. Eight beat bursts: Predicted end of burst is generated at the end of each eight beat boundary inside INCR transfer. 5. Sixteen beat bursts: Predicted end of burst is generated at the end of each sixteen beat boundary inside INCR transfer. This selection can be done through the ULBT field in the Master Configuration Registers (MCFG). • Slot Cycle Limit Arbitration The Bus Matrix contains specific logic to break long accesses, such as very long bursts on a very slow slave (e.g., an external low speed memory). At the beginning of the burst access, a counter is loaded with the value previously written in the SLOT_CYCLE field of the related Slave Configuration Register (SCFG) and decreased at each clock cycle. When the counter reaches zero, the arbiter has the ability to re-arbitrate at the end of the current byte, halfword, or word transfer. 11.4.2.2 Round-Robin Arbitration This algorithm allows the Bus Matrix arbiters to dispatch the requests from different masters to the same slave in a round-robin manner. If two or more master requests arise at the same time, the master with the lowest number is first serviced, then the others are serviced in a round-robin manner. There are three round-robin algorithms implemented: 1. Round-Robin arbitration without default master 2. Round-Robin arbitration with last default master 3. Round-Robin arbitration with fixed default master • Round-Robin Arbitration without Default Master This is the main algorithm used by Bus Matrix arbiters. It allows the Bus Matrix to dispatch requests from different masters to the same slave in a pure round-robin manner. At the end of the current access, if no other request is pending, the slave is disconnected from all masters. This configuration incurs one latency cycle for the first access of a burst. Arbitration without default master can be used for masters that perform significant bursts. • Round-Robin Arbitration with Last Default Master This is a biased round-robin algorithm used by Bus Matrix arbiters. It allows the Bus Matrix to remove the one latency cycle for the last master that accessed the slave. At the end of the cur- 187 32142D–06/2013 ATUC64/128/256L3/4U rent transfer, if no other master request is pending, the slave remains connected to the last master that performed the access. Other non privileged masters still get one latency cycle if they want to access the same slave. This technique can be used for masters that mainly perform single accesses. • Round-Robin Arbitration with Fixed Default Master This is another biased round-robin algorithm. It allows the Bus Matrix arbiters to remove the one latency cycle for the fixed default master per slave. At the end of the current access, the slave remains connected to its fixed default master. Every request attempted by this fixed default master will not cause any latency whereas other non privileged masters will still get one latency cycle. This technique can be used for masters that mainly perform single accesses. 11.4.2.3 Fixed Priority Arbitration This algorithm allows the Bus Matrix arbiters to dispatch the requests from different masters to the same slave by using the fixed priority defined by the user. If two or more master requests are active at the same time, the master with the highest priority number is serviced first. If two or more master requests with the same priority are active at the same time, the master with the highest number is serviced first. For each slave, the priority of each master may be defined through the Priority Registers for Slaves (PRAS and PRBS). 11.4.3 Slave and Master assignation The index number assigned to Bus Matrix slaves and masters are described in the Module Configuration section at the end of this chapter. 188 32142D–06/2013 ATUC64/128/256L3/4U 11.5 User Interface Table 11-1. HMATRIX Register Memory Map Offset Register Name Access Reset Value 0x0000 Master Configuration Register 0 MCFG0 Read/Write 0x00000002 0x0004 Master Configuration Register 1 MCFG1 Read/Write 0x00000002 0x0008 Master Configuration Register 2 MCFG2 Read/Write 0x00000002 0x000C Master Configuration Register 3 MCFG3 Read/Write 0x00000002 0x0010 Master Configuration Register 4 MCFG4 Read/Write 0x00000002 0x0014 Master Configuration Register 5 MCFG5 Read/Write 0x00000002 0x0018 Master Configuration Register 6 MCFG6 Read/Write 0x00000002 0x001C Master Configuration Register 7 MCFG7 Read/Write 0x00000002 0x0020 Master Configuration Register 8 MCFG8 Read/Write 0x00000002 0x0024 Master Configuration Register 9 MCFG9 Read/Write 0x00000002 0x0028 Master Configuration Register 10 MCFG10 Read/Write 0x00000002 0x002C Master Configuration Register 11 MCFG11 Read/Write 0x00000002 0x0030 Master Configuration Register 12 MCFG12 Read/Write 0x00000002 0x0034 Master Configuration Register 13 MCFG13 Read/Write 0x00000002 0x0038 Master Configuration Register 14 MCFG14 Read/Write 0x00000002 0x003C Master Configuration Register 15 MCFG15 Read/Write 0x00000002 0x0040 Slave Configuration Register 0 SCFG0 Read/Write 0x00000010 0x0044 Slave Configuration Register 1 SCFG1 Read/Write 0x00000010 0x0048 Slave Configuration Register 2 SCFG2 Read/Write 0x00000010 0x004C Slave Configuration Register 3 SCFG3 Read/Write 0x00000010 0x0050 Slave Configuration Register 4 SCFG4 Read/Write 0x00000010 0x0054 Slave Configuration Register 5 SCFG5 Read/Write 0x00000010 0x0058 Slave Configuration Register 6 SCFG6 Read/Write 0x00000010 0x005C Slave Configuration Register 7 SCFG7 Read/Write 0x00000010 0x0060 Slave Configuration Register 8 SCFG8 Read/Write 0x00000010 0x0064 Slave Configuration Register 9 SCFG9 Read/Write 0x00000010 0x0068 Slave Configuration Register 10 SCFG10 Read/Write 0x00000010 0x006C Slave Configuration Register 11 SCFG11 Read/Write 0x00000010 0x0070 Slave Configuration Register 12 SCFG12 Read/Write 0x00000010 0x0074 Slave Configuration Register 13 SCFG13 Read/Write 0x00000010 0x0078 Slave Configuration Register 14 SCFG14 Read/Write 0x00000010 0x007C Slave Configuration Register 15 SCFG15 Read/Write 0x00000010 0x0080 Priority Register A for Slave 0 PRAS0 Read/Write 0x00000000 0x0084 Priority Register B for Slave 0 PRBS0 Read/Write 0x00000000 0x0088 Priority Register A for Slave 1 PRAS1 Read/Write 0x00000000 189 32142D–06/2013 ATUC64/128/256L3/4U 0x008C Priority Register B for Slave 1 PRBS1 Read/Write 0x00000000 0x0090 Priority Register A for Slave 2 PRAS2 Read/Write 0x00000000 0x0094 Priority Register B for Slave 2 PRBS2 Read/Write 0x00000000 0x0098 Priority Register A for Slave 3 PRAS3 Read/Write 0x00000000 0x009C Priority Register B for Slave 3 PRBS3 Read/Write 0x00000000 0x00A0 Priority Register A for Slave 4 PRAS4 Read/Write 0x00000000 0x00A4 Priority Register B for Slave 4 PRBS4 Read/Write 0x00000000 0x00A8 Priority Register A for Slave 5 PRAS5 Read/Write 0x00000000 0x00AC Priority Register B for Slave 5 PRBS5 Read/Write 0x00000000 0x00B0 Priority Register A for Slave 6 PRAS6 Read/Write 0x00000000 0x00B4 Priority Register B for Slave 6 PRBS6 Read/Write 0x00000000 0x00B8 Priority Register A for Slave 7 PRAS7 Read/Write 0x00000000 0x00BC Priority Register B for Slave 7 PRBS7 Read/Write 0x00000000 0x00C0 Priority Register A for Slave 8 PRAS8 Read/Write 0x00000000 0x00C4 Priority Register B for Slave 8 PRBS8 Read/Write 0x00000000 0x00C8 Priority Register A for Slave 9 PRAS9 Read/Write 0x00000000 0x00CC Priority Register B for Slave 9 PRBS9 Read/Write 0x00000000 0x00D0 Priority Register A for Slave 10 PRAS10 Read/Write 0x00000000 0x00D4 Priority Register B for Slave 10 PRBS10 Read/Write 0x00000000 0x00D8 Priority Register A for Slave 11 PRAS11 Read/Write 0x00000000 0x00DC Priority Register B for Slave 11 PRBS11 Read/Write 0x00000000 0x00E0 Priority Register A for Slave 12 PRAS12 Read/Write 0x00000000 0x00E4 Priority Register B for Slave 12 PRBS12 Read/Write 0x00000000 0x00E8 Priority Register A for Slave 13 PRAS13 Read/Write 0x00000000 0x00EC Priority Register B for Slave 13 PRBS13 Read/Write 0x00000000 0x00F0 Priority Register A for Slave 14 PRAS14 Read/Write 0x00000000 0x00F4 Priority Register B for Slave 14 PRBS14 Read/Write 0x00000000 0x00F8 Priority Register A for Slave 15 PRAS15 Read/Write 0x00000000 0x00FC Priority Register B for Slave 15 PRBS15 Read/Write 0x00000000 0x0110 Special Function Register 0 SFR0 Read/Write – 0x0114 Special Function Register 1 SFR1 Read/Write – 0x0118 Special Function Register 2 SFR2 Read/Write – 0x011C Special Function Register 3 SFR3 Read/Write – 0x0120 Special Function Register 4 SFR4 Read/Write – 0x0124 Special Function Register 5 SFR5 Read/Write – 0x0128 Special Function Register 6 SFR6 Read/Write – Table 11-1. HMATRIX Register Memory Map (Continued) Offset Register Name Access Reset Value 190 32142D–06/2013 ATUC64/128/256L3/4U 0x012C Special Function Register 7 SFR7 Read/Write – 0x0130 Special Function Register 8 SFR8 Read/Write – 0x0134 Special Function Register 9 SFR9 Read/Write – 0x0138 Special Function Register 10 SFR10 Read/Write – 0x013C Special Function Register 11 SFR11 Read/Write – 0x0140 Special Function Register 12 SFR12 Read/Write – 0x0144 Special Function Register 13 SFR13 Read/Write – 0x0148 Special Function Register 14 SFR14 Read/Write – 0x014C Special Function Register 15 SFR15 Read/Write – Table 11-1. HMATRIX Register Memory Map (Continued) Offset Register Name Access Reset Value 191 32142D–06/2013 ATUC64/128/256L3/4U 11.5.1 Master Configuration Registers Name: MCFG0...MCFG15 Access Type: Read/Write Offset: 0x00 - 0x3C Reset Value: 0x00000002 • ULBT: Undefined Length Burst Type 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 – – – – – ULBT Table 11-2. Undefined Length Burst Type ULBT Undefined Length Burst Type Description 000 Inifinite Length Burst No predicted end of burst is generated and therefore INCR bursts coming from this master cannot be broken. 001 Single-Access The undefined length burst is treated as a succession of single accesses, allowing rearbitration at each beat of the INCR burst. 010 4 Beat Burst The undefined length burst is split into a four-beat burst, allowing re-arbitration at each four-beat burst end. 011 8 Beat Burst The undefined length burst is split into an eight-beat burst, allowing re-arbitration at each eight-beat burst end. 100 16 Beat Burst The undefined length burst is split into a sixteen-beat burst, allowing re-arbitration at each sixteen-beat burst end. 192 32142D–06/2013 ATUC64/128/256L3/4U 11.5.2 Slave Configuration Registers Name: SCFG0...SCFG15 Access Type: Read/Write Offset: 0x40 - 0x7C Reset Value: 0x00000010 • ARBT: Arbitration Type 0: Round-Robin Arbitration 1: Fixed Priority Arbitration • FIXED_DEFMSTR: Fixed Default Master This is the number of the Default Master for this slave. Only used if DEFMSTR_TYPE is 2. Specifying the number of a master which is not connected to the selected slave is equivalent to setting DEFMSTR_TYPE to 0. • DEFMSTR_TYPE: Default Master Type 0: No Default Master At the end of the current slave access, if no other master request is pending, the slave is disconnected from all masters. This results in a one cycle latency for the first access of a burst transfer or for a single access. 1: Last Default Master At the end of the current slave access, if no other master request is pending, the slave stays connected to the last master having accessed it. This results in not having one cycle latency when the last master tries to access the slave again. 2: Fixed Default Master At the end of the current slave access, if no other master request is pending, the slave connects to the fixed master the number that has been written in the FIXED_DEFMSTR field. This results in not having one cycle latency when the fixed master tries to access the slave again. • SLOT_CYCLE: Maximum Number of Allowed Cycles for a Burst When the SLOT_CYCLE limit is reached for a burst, it may be broken by another master trying to access this slave. This limit has been placed to avoid locking a very slow slave when very long bursts are used. This limit must not be very small. Unreasonably small values break every burst and the Bus Matrix arbitrates without performing any data transfer. 16 cycles is a reasonable value for SLOT_CYCLE. 31 30 29 28 27 26 25 24 – – – – – – – ARBT 23 22 21 20 19 18 17 16 – – FIXED_DEFMSTR DEFMSTR_TYPE 15 14 13 12 11 10 9 8 –––––––– 76543210 SLOT_CYCLE 193 32142D–06/2013 ATUC64/128/256L3/4U 11.5.3 Bus Matrix Priority Registers A For Slaves Register Name: PRAS0...PRAS15 Access Type: Read/Write Offset: - Reset Value: 0x00000000 • MxPR: Master x Priority Fixed priority of Master x for accessing the selected slave. The higher the number, the higher the priority. 31 30 29 28 27 26 25 24 - - M7PR - - M6PR 23 22 21 20 19 18 17 16 - - M5PR - - M4PR 15 14 13 12 11 10 9 8 - - M3PR - - M2PR 76543210 - - M1PR - - M0PR 194 32142D–06/2013 ATUC64/128/256L3/4U 11.5.4 Priority Registers B For Slaves Name: PRBS0...PRBS15 Access Type: Read/Write Offset: - Reset Value: 0x00000000 • MxPR: Master x Priority Fixed priority of Master x for accessing the selected slave. The higher the number, the higher the priority. 31 30 29 28 27 26 25 24 - - M15PR - - M14PR 23 22 21 20 19 18 17 16 - - M13PR - - M12PR 15 14 13 12 11 10 9 8 - - M11PR - - M10PR 76543210 - - M9PR - - M8PR 195 32142D–06/2013 ATUC64/128/256L3/4U 11.5.5 Special Function Registers Name: SFR0...SFR15 Access Type: Read/Write Offset: 0x110 - 0x14C Reset Value: - • SFR: Special Function Register Fields Those registers are not a HMATRIX specific register. The field of those will be defined where they are used. 31 30 29 28 27 26 25 24 SFR 23 22 21 20 19 18 17 16 SFR 15 14 13 12 11 10 9 8 SFR 76543210 SFR 196 32142D–06/2013 ATUC64/128/256L3/4U 11.6 Module Configuration The specific configuration for each HMATRIX instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 11.6.1 Bus Matrix Connections The bus matrix has the several masters and slaves. Each master has its own bus and its own decoder, thus allowing a different memory mapping per master. The master number in the table below can be used to index the HMATRIX control registers. For example, HMATRIX MCFG0 register is associated with the CPU Data master interface. Each slave has its own arbiter, thus allowing a different arbitration per slave. The slave number in the table below can be used to index the HMATRIX control registers. For example, SCFG3 is associated with the Internal SRAM Slave Interface. Accesses to unused areas returns an error result to the master requesting such an access. Table 11-3. HMATRIX Clocks Clock Name Description CLK_HMATRIX Clock for the HMATRIX bus interface Table 11-4. High Speed Bus Masters Master 0 CPU Data Master 1 CPU Instruction Master 2 CPU SAB Master 3 SAU Master 4 PDCA Master 5 USBC Table 11-5. High Speed Bus Slaves Slave 0 Internal Flash Slave 1 HSB-PB Bridge A Slave 2 HSB-PB Bridge B Slave 3 Internal SRAM Slave 4 SAU 197 32142D–06/2013 ATUC64/128/256L3/4U Figure 11-1. HMatrix Master / Slave Connections CPU Data 0 CPU Instruction 1 CPU SAB 2 SAU 3 Internal Flash 0 HSB-PB Bridge 0 1 HSB-PB Bridge 1 2 Internal SRAM 3 HMATRIX SLAVES HMATRIX MASTERS SAU 4 PDCA 4 USBC 5 198 32142D–06/2013 ATUC64/128/256L3/4U 12. Interrupt Controller (INTC) Rev: 1.0.2.5 12.1 Features • Autovectored low latency interrupt service with programmable priority – 4 priority levels for regular, maskable interrupts – One Non-Maskable Interrupt • Up to 64 groups of interrupts with up to 32 interrupt requests in each group 12.2 Overview The INTC collects interrupt requests from the peripherals, prioritizes them, and delivers an interrupt request and an autovector to the CPU. The AVR32 architecture supports 4 priority levels for regular, maskable interrupts, and a Non-Maskable Interrupt (NMI). The INTC supports up to 64 groups of interrupts. Each group can have up to 32 interrupt request lines, these lines are connected to the peripherals. Each group has an Interrupt Priority Register (IPR) and an Interrupt Request Register (IRR). The IPRs are used to assign a priority level and an autovector to each group, and the IRRs are used to identify the active interrupt request within each group. If a group has only one interrupt request line, an active interrupt group uniquely identifies the active interrupt request line, and the corresponding IRR is not needed. The INTC also provides one Interrupt Cause Register (ICR) per priority level. These registers identify the group that has a pending interrupt of the corresponding priority level. If several groups have a pending interrupt of the same level, the group with the lowest number takes priority. 12.3 Block Diagram Figure 12-1 gives an overview of the INTC. The grey boxes represent registers that can be accessed via the user interface. The interrupt requests from the peripherals (IREQn) and the NMI are input on the left side of the figure. Signals to and from the CPU are on the right side of the figure. 199 32142D–06/2013 ATUC64/128/256L3/4U Figure 12-1. INTC Block Diagram 12.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 12.4.1 Power Management If the CPU enters a sleep mode that disables CLK_SYNC, the INTC will stop functioning and resume operation after the system wakes up from sleep mode. 12.4.2 Clocks The clock for the INTC bus interface (CLK_INTC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. The INTC sampling logic runs on a clock which is stopped in any of the sleep modes where the system RC oscillator is not running. This clock is referred to as CLK_SYNC. This clock is enabled at reset, and only turned off in sleep modes where the system RC oscillator is stopped. 12.4.3 Debug Operation When an external debugger forces the CPU into debug mode, the INTC continues normal operation. 12.5 Functional Description All of the incoming interrupt requests (IREQs) are sampled into the corresponding Interrupt Request Register (IRR). The IRRs must be accessed to identify which IREQ within a group that is active. If several IREQs within the same group are active, the interrupt service routine must prioritize between them. All of the input lines in each group are logically ORed together to form the GrpReqN lines, indicating if there is a pending interrupt in the corresponding group. The Request Masking hardware maps each of the GrpReq lines to a priority level from INT0 to INT3 by associating each group with the Interrupt Level (INTLEVEL) field in the corresponding Request Masking OR IREQ0 IREQ1 IREQ2 IREQ31 GrpReq0 Masks SREG Masks I[3-0]M GM INTLEVEL AUTOVECTOR Prioritizer Interrupt Controller CPU OR GrpReqN NMIREQ OR IREQ32 IREQ33 IREQ34 IREQ63 GrpReq1 IRR Registers IPR Registers ICR Registers INT_level, offset INT_level, offset INT_level, offset IPR0 IPR1 IPRn IRR0 IRR1 IRRn ValReq0 ValReq1 ValReqN . . . . . . . . . 200 32142D–06/2013 ATUC64/128/256L3/4U Interrupt Priority Register (IPR). The GrpReq inputs are then masked by the mask bits from the CPU status register. Any interrupt group that has a pending interrupt of a priority level that is not masked by the CPU status register, gets its corresponding ValReq line asserted. Masking of the interrupt requests is done based on five interrupt mask bits of the CPU status register, namely Interrupt Level 3 Mask (I3M) to Interrupt Level 0 Mask (I0M), and Global Interrupt Mask (GM). An interrupt request is masked if either the GM or the corresponding interrupt level mask bit is set. The Prioritizer hardware uses the ValReq lines and the INTLEVEL field in the IPRs to select the pending interrupt of the highest priority. If an NMI interrupt request is pending, it automatically gets the highest priority of any pending interrupt. If several interrupt groups of the highest pending interrupt level have pending interrupts, the interrupt group with the lowest number is selected. The INTLEVEL and handler autovector offset (AUTOVECTOR) of the selected interrupt are transmitted to the CPU for interrupt handling and context switching. The CPU does not need to know which interrupt is requesting handling, but only the level and the offset of the handler address. The IRR registers contain the interrupt request lines of the groups and can be read via user interface registers for checking which interrupts of the group are actually active. The delay through the INTC from the peripheral interrupt request is set until the interrupt request to the CPU is set is three cycles of CLK_SYNC. 12.5.1 Non-Maskable Interrupts A NMI request has priority over all other interrupt requests. NMI has a dedicated exception vector address defined by the AVR32 architecture, so AUTOVECTOR is undefined when INTLEVEL indicates that an NMI is pending. 12.5.2 CPU Response When the CPU receives an interrupt request it checks if any other exceptions are pending. If no exceptions of higher priority are pending, interrupt handling is initiated. When initiating interrupt handling, the corresponding interrupt mask bit is set automatically for this and lower levels in status register. E.g, if an interrupt of level 3 is approved for handling, the interrupt mask bits I3M, I2M, I1M, and I0M are set in status register. If an interrupt of level 1 is approved, the masking bits I1M and I0M are set in status register. The handler address is calculated by logical OR of the AUTOVECTOR to the CPU system register Exception Vector Base Address (EVBA). The CPU will then jump to the calculated address and start executing the interrupt handler. Setting the interrupt mask bits prevents the interrupts from the same and lower levels to be passed through the interrupt controller. Setting of the same level mask bit prevents also multiple requests of the same interrupt to happen. It is the responsibility of the handler software to clear the interrupt request that caused the interrupt before returning from the interrupt handler. If the conditions that caused the interrupt are not cleared, the interrupt request remains active. 12.5.3 Clearing an Interrupt Request Clearing of the interrupt request is done by writing to registers in the corresponding peripheral module, which then clears the corresponding NMIREQ/IREQ signal. The recommended way of clearing an interrupt request is a store operation to the controlling peripheral register, followed by a dummy load operation from the same register. This causes a 201 32142D–06/2013 ATUC64/128/256L3/4U pipeline stall, which prevents the interrupt from accidentally re-triggering in case the handler is exited and the interrupt mask is cleared before the interrupt request is cleared. 202 32142D–06/2013 ATUC64/128/256L3/4U 12.6 User Interface Table 12-1. INTC Register Memory Map Offset Register Register Name Access Reset 0x000 Interrupt Priority Register 0 IPR0 Read/Write 0x00000000 0x004 Interrupt Priority Register 1 IPR1 Read/Write 0x00000000 ... ... ... ... ... 0x0FC Interrupt Priority Register 63 IPR63 Read/Write 0x00000000 0x100 Interrupt Request Register 0 IRR0 Read-only N/A 0x104 Interrupt Request Register 1 IRR1 Read-only N/A ... ... ... ... ... 0x1FC Interrupt Request Register 63 IRR63 Read-only N/A 0x200 Interrupt Cause Register 3 ICR3 Read-only N/A 0x204 Interrupt Cause Register 2 ICR2 Read-only N/A 0x208 Interrupt Cause Register 1 ICR1 Read-only N/A 0x20C Interrupt Cause Register 0 ICR0 Read-only N/A 203 32142D–06/2013 ATUC64/128/256L3/4U 12.6.1 Interrupt Priority Registers Name: IPR0...IPR63 Access Type: Read/Write Offset: 0x000 - 0x0FC Reset Value: 0x00000000 • INTLEVEL: Interrupt Level Indicates the EVBA-relative offset of the interrupt handler of the corresponding group: 00: INT0: Lowest priority 01: INT1 10: INT2 11: INT3: Highest priority • AUTOVECTOR: Autovector Address Handler offset is used to give the address of the interrupt handler. The least significant bit should be written to zero to give halfword alignment. 31 30 29 28 27 26 25 24 INTLEVEL - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - AUTOVECTOR[13:8] 76543210 AUTOVECTOR[7:0] 204 32142D–06/2013 ATUC64/128/256L3/4U 12.6.2 Interrupt Request Registers Name: IRR0...IRR63 Access Type: Read-only Offset: 0x0FF - 0x1FC Reset Value: N/A • IRR: Interrupt Request line This bit is cleared when no interrupt request is pending on this input request line. This bit is set when an interrupt request is pending on this input request line. The are 64 IRRs, one for each group. Each IRR has 32 bits, one for each possible interrupt request, for a total of 2048 possible input lines. The IRRs are read by the software interrupt handler in order to determine which interrupt request is pending. The IRRs are sampled continuously, and are read-only. 31 30 29 28 27 26 25 24 IRR[32*x+31] IRR[32*x+30] IRR[32*x+29] IRR[32*x+28] IRR[32*x+27] IRR[32*x+26] IRR[32*x+25] IRR[32*x+24] 23 22 21 20 19 18 17 16 IRR[32*x+23] IRR[32*x+22] IRR[32*x+21] IRR[32*x+20] IRR[32*x+19] IRR[32*x+18] IRR[32*x+17] IRR[32*x+16] 15 14 13 12 11 10 9 8 IRR[32*x+15] IRR[32*x+14] IRR[32*x+13] IRR[32*x+12] IRR[32*x+11] IRR[32*x+10] IRR[32*x+9] IRR[32*x+8] 76543210 IRR[32*x+7] IRR[32*x+6] IRR[32*x+5] IRR[32*x+4] IRR[32*x+3] IRR[32*x+2] IRR[32*x+1] IRR[32*x+0] 205 32142D–06/2013 ATUC64/128/256L3/4U 12.6.3 Interrupt Cause Registers Name: ICR0...ICR3 Access Type: Read-only Offset: 0x200 - 0x20C Reset Value: N/A • CAUSE: Interrupt Group Causing Interrupt of Priority n ICRn identifies the group with the highest priority that has a pending interrupt of level n. This value is only defined when at least one interrupt of level n is pending. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CAUSE 206 32142D–06/2013 ATUC64/128/256L3/4U 12.7 Module Configuration The specific configuration for each INTC instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 12.7.1 Interrupt Request Signal Map 12.8 Interrupt Request Signal Map The various modules may output Interrupt request signals. These signals are routed to the Interrupt Controller (INTC), described in a later chapter. The Interrupt Controller supports up to 64 groups of interrupt requests. Each group can have up to 32 interrupt request signals. All interrupt signals in the same group share the same autovector address and priority level. Refer to the documentation for the individual submodules for a description of the semantics of the different interrupt requests. The interrupt request signals are connected to the INTC as follows. Table 12-2. INTC Clock Name Module Name Clock Name Description INTC CLK_INTC Clock for the INTC bus interface Table 12-3. Interrupt Request Signal Map Group Line Module Signal 0 0 AVR32UC3 CPU SYSREG COMPARE 1 0 AVR32UC3 CPU OCD DCEMU_DIRTY 1 AVR32UC3 CPU OCD DCCPU_READ 2 0 Flash Controller FLASHCDW 3 0 Secure Access Unit SAU 4 0 Peripheral DMA Controller PDCA 0 1 Peripheral DMA Controller PDCA 1 2 Peripheral DMA Controller PDCA 2 3 Peripheral DMA Controller PDCA 3 5 0 Peripheral DMA Controller PDCA 4 1 Peripheral DMA Controller PDCA 5 2 Peripheral DMA Controller PDCA 6 3 Peripheral DMA Controller PDCA 7 6 0 Peripheral DMA Controller PDCA 8 1 Peripheral DMA Controller PDCA 9 2 Peripheral DMA Controller PDCA 10 3 Peripheral DMA Controller PDCA 11 7 0 Power Manager PM 207 32142D–06/2013 ATUC64/128/256L3/4U 8 0 System Control Interface SCIF 9 0 Asynchronous Timer AST ALARM 10 0 Asynchronous Timer AST PER 1 Asynchronous Timer AST OVF 2 Asynchronous Timer AST READY 3 Asynchronous Timer AST CLKREADY 11 0 External Interrupt Controller EIC 1 1 External Interrupt Controller EIC 2 2 External Interrupt Controller EIC 3 3 External Interrupt Controller EIC 4 12 0 External Interrupt Controller EIC 5 13 0 Frequency Meter FREQM 14 0 General-Purpose Input/Output Controller GPIO 0 1 General-Purpose Input/Output Controller GPIO 1 2 General-Purpose Input/Output Controller GPIO 2 3 General-Purpose Input/Output Controller GPIO 3 4 General-Purpose Input/Output Controller GPIO 4 5 General-Purpose Input/Output Controller GPIO 5 6 General-Purpose Input/Output Controller GPIO 6 7 General-Purpose Input/Output Controller GPIO 7 15 0 Universal Synchronous Asynchronous Receiver Transmitter USART0 16 0 Universal Synchronous Asynchronous Receiver Transmitter USART1 17 0 Universal Synchronous Asynchronous Receiver Transmitter USART2 18 0 Universal Synchronous Asynchronous Receiver Transmitter USART3 19 0 Serial Peripheral Interface SPI 20 0 Two-wire Master Interface TWIM0 21 0 Two-wire Master Interface TWIM1 22 0 Two-wire Slave Interface TWIS0 23 0 Two-wire Slave Interface TWIS1 24 0 Pulse Width Modulation Controller PWMA 25 0 Timer/Counter TC00 1 Timer/Counter TC01 2 Timer/Counter TC02 Table 12-3. Interrupt Request Signal Map 208 32142D–06/2013 ATUC64/128/256L3/4U 26 0 Timer/Counter TC10 1 Timer/Counter TC11 2 Timer/Counter TC12 27 0 ADC Interface ADCIFB 28 0 Analog Comparator Interface ACIFB 29 0 Capacitive Touch Module CAT 30 0 aWire AW 31 0 Audio Bitstream DAC ABDACB 32 0 USB 2.0 Interface USBC 33 0 Inter-IC Sound (I2S) Controller IISC Table 12-3. Interrupt Request Signal Map 209 32142D–06/2013 ATUC64/128/256L3/4U 13. Power Manager (PM) Rev: 4.2.0.4 13.1 Features • Generates clocks and resets for digital logic • On-the-fly frequency change of CPU, HSB and PBx clocks • Sleep modes allow simple disabling of logic clocks and clock sources • Module-level clock gating through maskable peripheral clocks • Wake-up from internal or external interrupts • Automatic identification of reset sources • Supports advanced Shutdown sleep mode 13.2 Overview The Power Manager (PM) provides synchronous clocks used to clock the main digital logic in the device, namely the CPU, and the modules and peripherals connected to the High Speed Bus (HSB) and the Peripheral Buses (PBx). The PM contains advanced power-saving features, allowing the user to optimize the power consumption for an application. The synchronous clocks are divided into a number of clock domains, one for the CPU and HSB, and one for each PBx. The clocks can run at different speeds, allowing the user to save power by running peripherals relatively slow, whilst maintaining high CPU performance. The clocks can be independently changed on-the-fly, without halting any peripherals. The user may adjust CPU and memory speeds according to the dynamic application load, without disturbing or re-configuring active peripherals. Each module has a separate clock, enabling the user to save power by switching off clocks to inactive modules. Clocks and oscillators can be automatically switched off during idle periods by the CPU sleep instruction. The system will return to normal operation when interrupts occur. To achieve minimal power usage, a special sleep mode, called Shutdown is available, where power on all internal logic (CPU, peripherals) and most of the I/O lines is removed, reducing current leakage. Only a small amount of logic, including the 32KHz crystal oscillator (OSC32K) and the AST remain powered. The Power Manager also contains a Reset Controller, which collects all possible reset sources, generates hard and soft resets, and allows the reset source to be identified by software. 210 32142D–06/2013 ATUC64/128/256L3/4U 13.3 Block Diagram Figure 13-1. PM Block Diagram 13.4 I/O Lines Description 13.5 Product Dependencies 13.5.1 Interrupt The PM interrupt line is connected to one of the interrupt controllers internal sources. Using the PM interrupt requires the interrupt controller to be configured first. 13.5.2 Clock Implementation In ATUC64/128/256L3/4U, the HSB shares source clock with the CPU. Write attempts to the HSB Clock Select register (HSBSEL) will be ignored, and it will always read the same as the CPU Clock Select register (CPUSEL). The PM bus interface clock (CLK_PM) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. If disabled it can only be reenabled by a reset. 13.5.3 Power Considerations The Shutdown mode is only available for the “3.3V supply mode, with 1.8V regulated I/O lines“ power configuration. Table 13-1. I/O Lines Description Name Description Type Active Level RESET_N Reset Input Low Sleep Controller Synchronous Clock Generator Reset Controller Main Clock Sources Sleep Instruction Power-on Reset Detector(s) Resets Synchronous clocks CPU, HSB, PBx Interrupts External Reset Pin Reset Sources 211 32142D–06/2013 ATUC64/128/256L3/4U 13.6 Functional Description 13.6.1 Synchronous Clocks The System RC Oscillator (RCSYS) and a selection of other clock sources can provide the source for the main clock, which is the origin for the synchronous CPU/HSB and PBx module clocks. For details about the other main clock sources, please refer to the Main Clock Control (MCCTRL) register description. The synchronous clocks can run of the main clock and all the 8- bit prescaler settings as long as fCPU  fPBx,. The synchronous clock source can be changed onthe fly, according to variations in application load. The clock domains can be shut down in sleep mode, as described in Section 13.6.3. The module clocks in every synchronous clock domain can be individually masked to minimize power consumption in inactive modules. Figure 13-2. Synchronous Clock Generation 13.6.1.1 Selecting the main clock source The common main clock can be connected to RCSYS or a selection of other clock sources. For details about the other main clock sources, please refer to the MCCTRL register description. By default, the main clock will be connected to RCSYS. The user can connect the main clock to another source by writing to the Main Clock Select (MCCTRL.MCSEL) field. The user must first assure that the source is enabled and ready in order to avoid a deadlock. Care should also be taken so that the new synchronous clock frequencies do not exceed the maximum frequency for each clock domain. 13.6.1.2 Selecting synchronous clock division ratio The main clock feeds an 8-bit prescaler, which can be used to generate the synchronous clocks. By default, the synchronous clocks run on the undivided main clock. The user can select a prescaler division for the CPU clock by writing a one to the CPU Division bit in the CPU Clock Select register (CPUSEL.CPUDIV), and a value to the CPU Clock Select field (CPUSEL.CPUSEL), resulting in a CPU clock frequency: fCPU = fmain / 2(CPUSEL+1) Mask Prescaler Main Clock Sources MCSEL 0 1 CPUSEL CPUDIV Main Clock Sleep Controller CPUMASK CPU Clocks HSB Clocks PBx Clocks Sleep Instruction 212 32142D–06/2013 ATUC64/128/256L3/4U Similarly, the PBx clocks can be divided by writing their respective Clock Select (PBxSEL) registers to get the divided PBx frequency: fPBx = fmain / 2(PBSEL+1) The PBx clock frequency can not exceed the CPU clock frequency. The user must select a PBxSEL.PBSEL value greater than or equal to the CPUSEL.CPUSEL value, so that fCPU  fPBx. If the user selects division factors that will result in fCPU< fPBx, the Power Manager will automatically change the PBxSEL.PBSEL/PBDIV values to ensure correct operation (fCPU  fPBx). The HSB clock will always be forced to the same division as the CPU clock. To ensure correct operation, the frequencies must never exceed the specified maximum frequency for each clock domain. For modules connected to the HSB bus, the PB clock frequency must be the same as the CPU clock frequency. 13.6.1.3 Clock Ready flag There is a slight delay from CPUSEL and PBxSEL being written to the new clock setting taking effect. During this interval, the Clock Ready bit in the Status Register (SR.CKRDY) will read as zero. When the clock settings change is completed, the bit will read as one. The Clock Select registers (CPUSEL, PBxSEL) must not be written to while SR.CKRDY is zero, or the system may become unstable or hang. The Clock Ready bit in the Interrupt Status Register (ISR.CKRDY) is set on a SR.CKRDY zeroto-one transition. If the Clock Ready bit in the Interrupt Mask Register (IMR.CKRDY) is set, an interrupt request is generated. IMR.CKRDY is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.CKRDY). 13.6.2 Peripheral Clock Masking By default, the clocks for all modules are enabled, regardless of which modules are actually being used. It is possible to disable the clock for a module in the CPU, HSB, or PBx clock domain by writing a zero to the corresponding bit in the corresponding Clock Mask (CPUMASK/HSBMASK/PBxMASK) register. When a module is not clocked, it will cease operation, and its registers cannot be read nor written. The module can be re-enabled later by writing a one to the corresponding mask bit. A module may be connected to several clock domains, in which case it will have several mask bits. The Maskable Module Clocks table in the Clock Mask register description contains a list of implemented maskable clocks. 13.6.2.1 Cautionary note Note that clocks should only be switched off if it is certain that the module will not be used. Switching off the clock for the Flash Controller will cause a problem if the CPU needs to read from the flash. Switching off the clock to the Power Manager, which contains the mask registers, or the corresponding PBx bridge, will make it impossible to write to the mask registers again. In this case, they can only be re-enabled by a system reset. 13.6.3 Sleep Modes In normal operation, all clock domains are active, allowing software execution and peripheral operation. When the CPU is idle, it is possible to switch it and other (optional) clock domains off to save power. This is done by the sleep instruction, which takes the sleep mode index number from Table 13-2 on page 213 as argument. 213 32142D–06/2013 ATUC64/128/256L3/4U 13.6.3.1 Entering and exiting sleep modes The sleep instruction will halt the CPU and all modules belonging to the stopped clock domains. The modules will be halted regardless of the bit settings in the mask registers. Clock sources can also be switched off to save power. Some of these have a relatively long start-up time, and are only switched off when very low power consumption is required. The CPU and affected modules are restarted when the sleep mode is exited. This occurs when an interrupt triggers. Note that even if an interrupt is enabled in sleep mode, it may not trigger if the source module is not clocked. 13.6.3.2 Supported sleep modes The following sleep modes are supported. These are detailed in Table 13-2 on page 213. • Idle: The CPU is stopped, the rest of the device is operational. • Frozen: The CPU and HSB modules are stopped, peripherals are operational. • Standby: All synchronous clocks are stopped, and the clock sources are running, allowing for a quick wake-up to normal mode. • Stop: As Standby, but oscillators, and other clock sources are also stopped. 32KHz Oscillator OSC32K(2), RCSYS, AST, and WDT will remain operational. • DeepStop: All synchronous clocks and clock sources are stopped. Bandgap voltage reference and BOD are turned off. OSC32K(2) and RCSYS remain operational. • Static: All clock sources, including RCSYS are stopped. Bandgap voltage reference and BOD are turned off. OSC32K(2) remains operational. • Shutdown: All clock sources, including RCSYS are stopped. Bandgap voltage reference, BOD detector, and Voltage regulator are turned off. OSC32K(2) remains operational. This mode can only be used in the “3.3V supply mode, with 1.8V regulated I/O lines“ configuration (described in Power Considerations chapter). Refer to Section 13.6.4 for more details. Notes: 1. The sleep mode index is used as argument for the sleep instruction. 2. OSC32K will only remain operational if pre-enabled. 3. Clock sources other than those specifically listed in the table. 4. SYSTIMER is the clock for the CPU COUNT and COMPARE registers. The internal voltage regulator is also adjusted according to the sleep mode in order to reduce its power consumption. Table 13-2. Sleep Modes Index(1) Sleep Mode CPU HSB PBx, GCLK Clock Sources(3), SYSTIMER(4) OSC32K(2) RCSYS BOD & Bandgap Voltage Regulator 0 Idle Stop Run Run Run Run Run On Normal mode 1 Frozen Stop Stop Run Run Run Run On Normal mode 2 Standby Stop Stop Stop Run Run Run On Normal mode 3 Stop Stop Stop Stop Stop Run Run On Low power mode 4 DeepStop Stop Stop Stop Stop Run Run Off Low power mode 5 Static Stop Stop Stop Stop Run Stop Off Low power mode 6 Shutdown Stop Stop Stop Stop Run Stop Off Off 214 32142D–06/2013 ATUC64/128/256L3/4U 13.6.3.3 Waking from sleep modes There are two types of wake-up sources from sleep mode, synchronous and asynchronous. Synchronous wake-up sources are all non-masked interrupts. Asynchronous wake-up sources are AST, WDT, external interrupts from EIC, external reset, external wake pin (WAKE_N), and all asynchronous wake-ups enabled in the Asynchronous Wake Up Enable (AWEN) register. The valid wake-up sources for each sleep mode are detailed in Table 13-3 on page 214. In Shutdown the only wake-up sources are external reset, external wake-up pin or AST. See Section 13.6.4.3 on page 216. Notes: 1. The sleep mode index is used as argument for the sleep instruction. 2. Only PB modules operational, as HSB module clocks are stopped. 3. WDT only available if clocked from pre-enabled OSC32K. 13.6.3.4 SleepWalking In all sleep modes where the PBx clocks are stopped, except for Shutdown mode, the device can partially wake up if a PBx module asynchronously discovers that it needs its clock. Only the requested clocks and clock sources needed will be started, all other clocks will remain masked to zero. E.g. if the main clock source is OSC0, only OSC0 will be started even if other clock sources were enabled in normal mode. Generic clocks can also be started in a similar way. The state where only requested clocks are running is referred to as SleepWalking. The time spent to start the requested clock is mostly limited by the startup time of the given clock source. This allows PBx modules to handle incoming requests, while still keeping the power consumption at a minimum. When the device is SleepWalking any asynchronous wake-up can wake the device up at any time without stopping the requested PBx clock. All requests to start clocks can be masked by writing to the Peripheral Power Control Register (PPCR), all requests are enabled at reset. During SleepWalking the interrupt controller clock will be running. If an interrupt is pending when entering SleepWalking, it will wake the whole device up. 13.6.3.5 Precautions when entering sleep mode Modules communicating with external circuits should normally be disabled before entering a sleep mode that will stop the module operation. This will prevent erratic behavior caused by entering or exiting sleep modes. Please refer to the relevant module documentation for recommended actions. Table 13-3. Wake-up Sources Index(1) Sleep Mode Wake-up Sources 0 Idle Synchronous, Asynchronous 1 Frozen Synchronous(2), Asynchronous 2 Standby Asynchronous 3 Stop Asynchronous 4 DeepStop Asynchronous 5 Static Asynchronous(3) 6 Shutdown External reset, External wake-up pin 215 32142D–06/2013 ATUC64/128/256L3/4U Communication between the synchronous clock domains is disturbed when entering and exiting sleep modes. Bus transactions over clock domains affected by the sleep mode are therefore not recommended. The system may hang if the bus clocks are stopped during a bus transaction. The CPU is automatically stopped in a safe state to ensure that all CPU bus operations are complete when the sleep mode goes into effect. Thus, when entering Idle mode, no further action is necessary. When entering a sleep mode (except Idle mode), all HSB masters must be stopped before entering the sleep mode. In order to let potential PBx write operations complete, the user should let the CPU perform a PBx register read operation before issuing the sleep instruction. This will stall the CPU until pending PBx operations have completed. The Shutdown sleep mode requires extra care. Please refer to Section 13.6.4. 13.6.4 Shutdown Sleep Mode 13.6.4.1 Description The Shutdown sleep mode is available only when the device is used in the “3.3V supply mode, with 1.8V regulated I/O lines“ configuration (refer to the Power Considerations chapter). In this configuration, the voltage regulator supplies both VDDCORE and VDDIO power supplies. When the device enters Shutdown mode, the regulator is turned off and only the following logic is kept powered by VDDIN: – OSC32K using alternate pinout PA13/PA20 – AST core logic (internal counter and alarm detection logic) – Backup Registers – I/O lines PA11, PA13, PA20, PA21, PB04, PB05, and PB10 – RESET_N line The table below lists I/O line functionality that remains operational during Shutdown sleep mode. If no special function is used the I/O line will keep its setting when entering the sleep mode 13.6.4.2 Entering Shutdown sleep mode Before entering the Shutdown sleep mode, a few actions are required: – All modules should normally be disabled before entering Shutdown sleep mode (see Section 13.6.3.5) Table 13-4. I/O Lines Usage During Shutdown Mode Pin Possible Usage During Shutdown Sleep Mode PA11 WAKE_N signal (active low wake-up) PA13 XIN32_2 (OSC32K using alternate pinout) PA20 XOUT32_2 (OSC32K using alternate pinout) PA21 PB04 PB05 PB10 RESET_N Reset pin 216 32142D–06/2013 ATUC64/128/256L3/4U – The POR33 must be masked to avoid spurious resets when the power is back. This must also be done when POR33 is disabled, as POR33 will be enabled automatically when the device wakes up from Shutdown mode. Disable the POR33 by writing a one to the POR33MASK bit in the SCIF.VREGCR register. Due to internal synchronisation, this bit must be read as a one before the sleep instruction is executed by the CPU. Refer to the System Control Interface (SCIF) chapter for more details. – The 32KHz RC oscillator (RC32K) must be running and stable. This is done by writing a one to the EN bit in the SCIF.RC32KCR register. Due to internal synchronisation, this bit must be read as a one to ensure that the oscillator is stable before the sleep instruction is executed by the CPU. As soon as the Shutdown sleep mode is entered, all CPU and peripherals are reset to ensure a consistent state. POR33 and RC32K are automatically disabled to save extra power. 13.6.4.3 Leaving Shutdown sleep mode Exiting Shutdown sleep mode can be done by the events described in Table 13-5. When a wake-up event occurs, the regulator is turned on and the device will wait for VDDCORE to be valid before starting. The Sleep Reset bit in the Reset Cause register (RCAUSE.SLEEP) is then set, allowing software running on the device to distinguish between the first power-up and a wake-up from Shutdown mode. 13.6.4.4 Special consideration regarding waking up from Shutdown sleep mode using the WAKE_N pin By default, the WAKE_N pin will only wake the device up if it is pulled low after entering Shutdown mode. If the WAKE_N is pulled low before the Shutdown mode is entered, it will not wake the device from the Shutdown sleep mode. In order to wake the device by pulling WAKE_N low before entering Shutdown mode, the user has to write a one to the bit corresponding to the WAKEN wake-up source in the AWEN register. In this scenario, the CPU execution will proceed with the next instruction, and the RCAUSE register content will not be altered. 13.6.5 Divided PB Clocks The clock generator in the Power Manager provides divided PBx clocks for use by peripherals that require a prescaled PBx clock. This is described in the documentation for the relevant modules. The divided clocks are directly maskable, and are stopped in sleep modes where the PBx clocks are stopped. Table 13-5. Events That Can Wake up the Device from Shutdown Mode Source How PA11 (WAKE_N) Pulling-down PA11 will wake up the device RESET_N Pulling-down RESET_N pin will wake up the device The device is kept under reset until RESET_N is tied high again AST OSC32K must be set-up to use alternate pinout (XIN32_2 and XOUT32_2) Refer to the SCIF Chapter AST must be configured to use the clock from OSC32K AST must be configured to allow alarm, periodic, or overflow wake-up 217 32142D–06/2013 ATUC64/128/256L3/4U 13.6.6 Reset Controller The Reset Controller collects the various reset sources in the system and generates hard and soft resets for the digital logic. The device contains a Power-on Reset (POR) detector, which keeps the system reset until power is stable. This eliminates the need for external reset circuitry to guarantee stable operation when powering up the device. It is also possible to reset the device by pulling the RESET_N pin low. This pin has an internal pull-up, and does not need to be driven externally during normal operation. Table 13-6 on page 217 lists these and other reset sources supported by the Reset Controller. Figure 13-3. Reset Controller Block Diagram In addition to the listed reset types, the JTAG & aWire can keep parts of the device statically reset. See JTAG and aWire documentation for details. Table 13-6. Reset Description Reset Source Description Power-on Reset Supply voltage below the Power-on Reset detector threshold voltage VPOT External Reset RESET_N pin asserted Brown-out Reset VDDCORE supply voltage below the Brown-out detector threshold voltage JTAG Reset Controller RESET_N Power-on Reset Detector(s) OCD Watchdog Reset RCAUSE CPU, HSB, PBx OCD, AST, WDT, Clock Generator Brown-out Detector AWIRE SM33 Detector 218 32142D–06/2013 ATUC64/128/256L3/4U Depending on the reset source, when a reset occurs, some parts of the device are not always reset. Only the Power-on Reset (POR) will force a whole device reset. Refer to the table in the Module Configuration section at the end of this chapter for further details. The latest reset cause can be read in the RCAUSE register, and can be read during the applications boot sequence in order to determine proper action. 13.6.6.1 Power-on Reset Detector The Power-on Reset 1.8V (POR18) detector monitors the VDDCORE supply pin and generates a Power-on Reset (POR) when the device is powered on. The POR is active until the VDDCORE voltage is above the power-on threshold level (VPOT). The POR will be re-generated if the voltage drops below the power-on threshold level. See Electrical Characteristics for parametric details. The Power-on Reset 3.3V (POR33) detector monitors the internal regulator supply pin and generates a Power-on Reset (POR) when the device is powered on. The POR is active until the internal regulator supply voltage is above the regulator power-on threshold level (VPOT). The POR will be re-generated if the voltage drops below the regulator power-on threshold level. See Electrical Characteristics for parametric details. 13.6.6.2 External Reset The external reset detector monitors the RESET_N pin state. By default, a low level on this pin will generate a reset. 13.6.7 Clock Failure Detector This mechanism automatically switches the main clock source to the safe RCSYS clock when the main clock source fails. This may happen when an external crystal is selected as a source for the main clock and the crystal is not mounted on the board. The main clock is compared with RCSYS, and if no rising edge of the main clock is detected during one RCSYS period, the clock is considered to have failed. The detector is enabled by writing a one to the Clock Failure Detection Enable bit in the Clock Failure Detector Control Register (CFDCTRL.CFDEN). As soon as the detector is enabled, the clock failure detector will monitor the divided main clock. Note that the detector does not monitor the main clock if RCSYS is the source of the main clock, or if the main clock is temporarily not available (startup-time after a wake-up, switching timing etc.), or in sleep mode where the main clock is driven by the RCSYS (Stop and DeepStop mode). When a clock failure is detected, the main clock automatically switches to the RCSYS clock and the Clock Failure Detected (CFD) interrupt is generated if enabled. The MCCTRL register is also changed by hardware to indicate that the main clock comes from RCSYS. 13.6.8 Interrupts The PM has a number of interrupt sources: • AE - Access Error, SM33 Reset Internal regulator supply voltage below the SM33 threshold voltage. This generates a Power-on Reset. Watchdog Timer See Watchdog Timer documentation OCD See On-Chip Debug documentation Reset Source Description 219 32142D–06/2013 ATUC64/128/256L3/4U – A lock protected register is written to without first being unlocked. • CKRDY - Clock Ready: – New Clock Select settings in the CPUSEL/PBxSEL registers have taken effect. (A zero-to-one transition on SR.CKRDY is detected). • CFD - Clock Failure Detected: – The system detects that the main clock is not running. The Interrupt Status Register contains one bit for each interrupt source. A bit in this register is set on a zero-to-one transition of the corresponding bit in the Status Register (SR), and cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). The interrupt sources will generate an interrupt request if the corresponding bit in the Interrupt Mask Register is set. The interrupt sources are ORed together to form one interrupt request. The Power Manager will generate an interrupt request if at least one of the bits in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in the Interrupt Status Register (ISR) is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). Because all the interrupt sources are ORed together, the interrupt request from the Power Manager will remain active until all the bits in ISR are cleared. 220 32142D–06/2013 ATUC64/128/256L3/4U 13.7 User Interface Note: 1. The reset value is device specific. Please refer to the Module Configuration section at the end of this chapter. 2. Latest Reset Source. 3. Latest Wake Source. Table 13-7. PM Register Memory Map Offset Register Register Name Access Reset 0x000 Main Clock Control MCCTRL Read/Write 0x00000000 0x004 CPU Clock Select CPUSEL Read/Write 0x00000000 0x008 HSB Clock Select HSBSEL Read-only 0x00000000 0x00C PBA Clock Select PBASEL Read/Write 0x00000000 0x010 PBB Clock Select PBBSEL Read/Write 0x00000000 0x014 - 0x01C Reserved 0x020 CPU Mask CPUMASK Read/Write 0x00010001 0x024 HSB Mask HSBMASK Read/Write 0x0000007F 0x028 PBA Mask PBAMASK Read/Write 0x0FFFFFFF 0x02C PBB Mask PBBMASK Read/Write 0x0000000F 0x030- 0x03C Reserved 0x040 PBA Divided Mask PBADIVMASK Read/Write 0x0000007F 0x044 - 0x050 Reserved 0x054 Clock Failure Detector Control CFDCTRL Read/Write 0x00000000 0x058 Unlock Register UNLOCK Write-only 0x00000000 0x05C - 0x0BC Reserved 0x0C0 Interrupt Enable Register IER Write-only 0x00000000 0x0C4 Interrupt Disable Register IDR Write-only 0x00000000 0x0C8 Interrupt Mask Register IMR Read-only 0x00000000 0x0CC Interrupt Status Register ISR Read-only 0x00000000 0x0D0 Interrupt Clear Register ICR Write-only 0x00000000 0x0D4 Status Register SR Read-only 0x00000020 0x0D8 - 0x15C Reserved 0x160 Peripheral Power Control Register PPCR Read/Write 0x000001FA 0x164 - 0x17C Reserved 0x180 Reset Cause Register RCAUSE Read-only -(2) 0x184 Wake Cause Register WCAUSE Read-only -(3) 0x188 Asynchronous Wake Up Enable Register AWEN Read/Write 0x00000000 0x18C - 0x3F4 Reserved 0x3F8 Configuration Register CONFIG Read-only 0x00000043 0x3FC Version Register VERSION Read-only -(1) 221 32142D–06/2013 ATUC64/128/256L3/4U 13.7.1 Main Clock Control Name: MCCTRL Access Type: Read/Write Offset: 0x000 Reset Value: 0x00000000 • MCSEL: Main Clock Select Note: 1. If the 120MHz RC oscillator is selected as main clock source, it must be divided by at least 4 before being used as clock source for the CPU. This division is selected by writing to the CPUSEL and CPUDIV bits in the CPUSEL register, before switching to RC120M as main clock source. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - MCSEL Table 13-8. Main clocks in ATUC64/128/256L3/4U. MCSEL[2:0] Main clock source 0 System RC oscillator (RCSYS) 1 Oscillator0 (OSC0) 2 DFLL 3 120MHz RC oscillator (RC120M)(1) 222 32142D–06/2013 ATUC64/128/256L3/4U 13.7.2 CPU Clock Select Name: CPUSEL Access Type: Read/Write Offset: 0x004 Reset Value: 0x00000000 • CPUDIV, CPUSEL: CPU Division and Clock Select CPUDIV = 0: CPU clock equals main clock. CPUDIV = 1: CPU clock equals main clock divided by 2(CPUSEL+1). Note that if CPUDIV is written to 0, CPUSEL should also be written to 0 to ensure correct operation. Also note that writing this register clears POSCSR.CKRDY. The register must not be re-written until CKRDY goes high. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 CPUDIV - - - - CPUSEL 223 32142D–06/2013 ATUC64/128/256L3/4U 13.7.3 HSB Clock Select Name: HSBSEL Access Type: Read Offset: 0x008 Reset Value: 0x00000000 This register is read-only and its content is always equal to CPUSEL. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 HSBDIV - - - - HSBSEL 224 32142D–06/2013 ATUC64/128/256L3/4U 13.7.4 PBx Clock Select Name: PBxSEL Access Type: Read/Write Offset: 0x00C-0x010 Reset Value: 0x00000000 • PBDIV, PBSEL: PBx Division and Clock Select PBDIV = 0: PBx clock equals main clock. PBDIV = 1: PBx clock equals main clock divided by 2(PBSEL+1). Note that if PBDIV is written to 0, PBSEL should also be written to 0 to ensure correct operation. Also note that writing this register clears SR.CKRDY. The register must not be re-written until SR.CKRDY is set. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PBDIV - - - - PBSEL 225 32142D–06/2013 ATUC64/128/256L3/4U 13.7.5 Clock Mask Name: CPUMASK/HSBMASK/PBAMASK/PBBMASK Access Type: Read/Write Offset: 0x020-0x02C Reset Value: - • MASK: Clock Mask If bit n is cleared, the clock for module n is stopped. If bit n is set, the clock for module n is enabled according to the current power mode. The number of implemented bits in each mask register, as well as which module clock is controlled by each bit, is shown in Table 13-9. 31 30 29 28 27 26 25 24 MASK[31:24] 23 22 21 20 19 18 17 16 MASK[23:16] 15 14 13 12 11 10 9 8 MASK[15:8] 76543210 MASK[7:0] Table 13-9. Maskable Module Clocks in ATUC64/128/256L3/4U. Bit CPUMASK HSBMASK PBAMASK PBBMASK 0 OCD PDCA PDCA FLASHCDW 1 - FLASHCDW INTC HMATRIX 2 - SAU PM SAU 3 - PBB bridge SCIF USBC 4 - PBA bridge AST - 5 - Peripheral Event System WDT - 6 - USBC EIC - 7 - - FREQM - 8 - - GPIO - 9 - - USART0 - 10 - - USART1 - 11 - - USART2 - 226 32142D–06/2013 ATUC64/128/256L3/4U Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 12 - - USART3 - 13 - - SPI - 14 - - TWIM0 - 15 - - TWIM1 - 16 SYSTIMER - TWIS0 - 17 - - TWIS1 - 18 - - PWMA - 19 - - TC0 - 20 - - TC1 - 21 - - ADCIFB - 22 - - ACIFB - 23 - - CAT - 24 - - GLOC - 25 - - AW - 26 - - ABDACB - 27 - - IISC - 31:28 - - - - Table 13-9. Maskable Module Clocks in ATUC64/128/256L3/4U. Bit CPUMASK HSBMASK PBAMASK PBBMASK 227 32142D–06/2013 ATUC64/128/256L3/4U 13.7.6 PBA Divided Mask Name: PBADIVMASK Access Type: Read/Write Offset: 0x040 Reset Value: 0x0000007F • MASK: Clock Mask If bit n is written to zero, the clock divided by 2(n+1) is stopped. If bit n is written to one, the clock divided by 2(n+1) is enabled according to the current power mode. Table 13-10 shows what clocks are affected by the different MASK bits. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - ------ 15 14 13 12 11 10 9 8 -------- 76543210 - MASK[6:0] Table 13-10. Divided Clock Mask Bit USART0 USART1 USART2 USART3 TC0 TC1 0 - - - - TIMER_CLOCK2 TIMER_CLOCK2 1- - - - - - 2 CLK_USART/ DIV CLK_USART/ DIV CLK_USART/ DIV CLK_USART/ DIV TIMER_CLOCK3 TIMER_CLOCK3 3- - - - - - 4 - - - - TIMER_CLOCK4 TIMER_CLOCK4 5- - - - - - 6 - - - - TIMER_CLOCK5 TIMER_CLOCK5 228 32142D–06/2013 ATUC64/128/256L3/4U 13.7.7 Clock Failure Detector Control Register Name: CFDCTRL Access Type: Read/Write Offset: 0x054 Reset Value: 0x00000000 • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. • CFDEN: Clock Failure Detection Enable 0: Clock Failure Detector is disabled 1: Clock Failure Detector is enabled Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 SFV - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - CFDEN 229 32142D–06/2013 ATUC64/128/256L3/4U 13.7.8 Unlock Register Name: UNLOCK Access Type: Write-only Offset: 0x058 Reset Value: 0x00000000 To unlock a write protected register, first write to the UNLOCK register with the address of the register to unlock in the ADDR field and 0xAA in the KEY field. Then, in the next PB access write to the register specified in the ADDR field. • KEY: Unlock Key Write this bit field to 0xAA to enable unlock. • ADDR: Unlock Address Write the address of the register to unlock to this field. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - ADDR[9:8] 76543210 ADDR[7:0] 230 32142D–06/2013 ATUC64/128/256L3/4U 13.7.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0C0 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 231 32142D–06/2013 ATUC64/128/256L3/4U 13.7.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x0C4 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 232 32142D–06/2013 ATUC64/128/256L3/4U 13.7.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x0C8 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 233 32142D–06/2013 ATUC64/128/256L3/4U 13.7.12 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x0CC Reset Value: 0x00000000 0: The corresponding interrupt is cleared. 1: The corresponding interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set on a zero-to-one transition of the corresponding bit in the Status Register (SR). 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 234 32142D–06/2013 ATUC64/128/256L3/4U 13.7.13 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x0D0 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 235 32142D–06/2013 ATUC64/128/256L3/4U 13.7.14 Status Register Name: SR Access Type: Read-only Offset: 0x0D4 Reset Value: 0x00000020 • AE: Access Error 0: No access error has occurred. 1: A write to lock protected register without unlocking it has occurred. • CKRDY: Clock Ready 0: One of the CPUSEL/PBxSEL registers has been written, and the new clock setting is not yet effective. 1: The synchronous clocks have frequencies as indicated in the CPUSEL/PBxSEL registers. • CFD: Clock Failure Detected 0: Main clock is running correctly. 1: Failure on main clock detected. Main clock is now running on RCSYS. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - CKRDY - - - - CFD 236 32142D–06/2013 ATUC64/128/256L3/4U 13.7.15 Peripheral Power Control Register Name: PPCR Access Type: Read/Write Offset: 0x004 Reset Value: 0x000001FA • RSTTM: Reset test mode 0: External reset not in test mode 1: External reset in test mode • FRC32: Force RC32 out 0: RC32 signal is not forced as output 1: RC32 signal is forced as output • RSTPUN: Reset Pull-up, active low 0: Pull-up for external reset on 1: Pull-up for external reset off 31 30 29 28 27 26 25 24 PPC[31:24] 23 22 21 20 19 18 17 16 PPC[23:16] 15 14 13 12 11 10 9 8 PPC[15:8] 76543210 PPC[7:0] Table 13-11. Peripheral Power Control Bit Name 0 RSTPUN 1 FRC32 2 RSTTM 3 CATRCMASK 4 ACIFBCRCMASK 5 ADCIFBRCMASK 6 ASTRCMASK 7 TWIS0RCMASK 8 TWIS1RCMASK 31:9 - 237 32142D–06/2013 ATUC64/128/256L3/4U • CATRCMASK: CAT Request Clock Mask 0: CAT Request Clock is disabled 1: CAT Request Clock is enabled • ACIFBRCMASK: ACIFB Request Clock Mask 0: ACIFB Request Clock is disabled 1: ACIFB Request Clock is enabled • ADCIFBRCMASK: ADCIFB Request Clock Mask 0: ADCIFB Request Clock is disabled 1: ADCIFB Request Clock is enabled • ASTRCMASK: AST Request Clock Mask 0: AST Request Clock is disabled 1: AST Request Clock is enabled • TWIS0RCMASK: TWIS0 Request Clock Mask 0: TWIS0 Request Clock is disabled 1: TWIS0 Request Clock is enabled • TWIS1RCMASK: TWIS1 Request Clock Mask 0: TWIS1 Request Clock is disabled 1: TWIS1 Request Clock is enabled Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 238 32142D–06/2013 ATUC64/128/256L3/4U 13.7.16 Reset Cause Register Name: RCAUSE Access Type: Read-only Offset: 0x180 Reset Value: Latest Reset Source • AWIRE: aWire Reset This bit is set when the last reset was caused by the aWire. • JTAG: JTAG Reset This bit is set when the last reset was caused by the JTAG. • OCDRST: OCD Reset This bit is set when the last reset was due to the RES bit in the OCD Development Control register having been written to one. • SLEEP: Sleep Reset This bit is set when the last reset was due to the device waking up from the Shutdown sleep mode. • WDT: Watchdog Reset This bit is set when the last reset was due to a watchdog time-out. • EXT: External Reset Pin This bit is set when the last reset was due to the RESET_N pin being pulled low. • BOD: Brown-out Reset This bit is set when the last reset was due to the core supply voltage being lower than the brown-out threshold level. • POR: Power-on Reset This bit is set when the last reset was due to the core supply voltage VDDCORE being lower than the power-on threshold level (the reset is generated by the POR18 detector), or the internal regulator supply voltage being lower than the regulator power-on threshold level (generated by the POR33 detector), or the internal regulator supply voltage being lower than the minimum required input voltage (generated by the 3.3V supply monitor SM33). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - AWIRE - JTAG OCDRST 76543210 - SLEEP - - WDT EXT BOD POR 239 32142D–06/2013 ATUC64/128/256L3/4U 13.7.17 Wake Cause Register Name: WCAUSE Access Type: Read-only Offset: 0x184 Reset Value: Latest Wake Source A bit in this register is set on wake up caused by the peripheral referred to in Table 13-12 on page 239. 31 30 29 28 27 26 25 24 WCAUSE[31:24] 23 22 21 20 19 18 17 16 WCAUSE[23:16] 15 14 13 12 11 10 9 8 WCAUSE[15:8] 76543210 WCAUSE[7:0] Table 13-12. Wake Cause Bit Wake Cause 0 CAT 1 ACIFB 2 ADCIFB 3 TWI Slave 0 4 TWI Slave 1 5 WAKE_N 6 ADCIFB Pen Detect 7 USBC 15:8 - 16 EIC 17 AST 31:18 - 240 32142D–06/2013 ATUC64/128/256L3/4U 13.7.18 Asynchronous Wake Up Enable Register Name: AWEN Access Type: Read/Write Offset: 0x188 Reset Value: 0x00000000 Each bit in this register corresponds to an asynchronous wake-up source, according to Table 13-13 on page 240. 0: The corresponding wake up is disabled. 1: The corresponding wake up is enabled 31 30 29 28 27 26 25 24 AWEN[31:24] 23 22 21 20 19 18 17 16 AWEN[23:16] 15 14 13 12 11 10 9 8 AWEN[15:8] 76543210 AWEN[7:0] Table 13-13. Asynchronous Wake-up Sources Bit Asynchronous Wake-up Source 0 CAT 1 ACIFB 2 ADCIFB 3 TWIS0 4 TWIS1 5 WAKEN 6 ADCIFBPD 7 USBC 31:8 - 241 32142D–06/2013 ATUC64/128/256L3/4U 13.7.19 Configuration Register Name: CONFIG Access Type: Read-Only Offset: 0x3F8 Reset Value: - This register shows the configuration of the PM. • HSBPEVC:HSB PEVC Clock Implemented 0: HSBPEVC not implemented. 1: HSBPEVC implemented. • PBD: PBD Implemented 0: PBD not implemented. 1: PBD implemented. • PBC: PBC Implemented 0: PBC not implemented. 1: PBC implemented. • PBB: PBB Implemented 0: PBB not implemented. 1: PBB implemented. • PBA: PBA Implemented 0: PBA not implemented. 1: PBA implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 HSBPEVC - - - PBD PBC PBB PBA 242 32142D–06/2013 ATUC64/128/256L3/4U 13.7.20 Version Register Name: VERSION Access Type: Read-Only Offset: 0x3FC Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 243 32142D–06/2013 ATUC64/128/256L3/4U 13.8 Module Configuration The specific configuration for each PM instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the “Synchronous Clocks”, “Peripheral Clock Masking” and “Sleep Modes” sections for details. Table 13-14. Power Manager Clocks Clock Name Description CLK_PM Clock for the PM bus interface Table 13-15. Register Reset Values Register Reset Value VERSION 0x00000420 Table 13-16. Effect of the Different Reset Events Power-on Reset External Reset Watchdog Reset BOD Reset SM33 Reset CPU Error Reset OCD Reset JTAG Reset CPU/HSB/PBx (excluding Power Manager) Y Y Y YY Y YY 32KHz oscillator Y N N N N N N N RC Oscillator Calibration register Y N N N N N N N Other oscillator control registers Y Y Y Y Y Y Y Y AST registers, except interrupt registers Y N N NN N NN Watchdog control register Y Y N Y Y Y Y Y Voltage Calibration register Y N N N N N N N SM33 control register Y Y Y Y Y Y Y Y BOD control register Y Y Y N Y Y Y Y Clock control registers Y Y Y Y Y Y Y Y OCD system and OCD registers Y Y N Y Y Y N Y 244 32142D–06/2013 ATUC64/128/256L3/4U 14. System Control Interface (SCIF) Rev: 1.1.0.0 14.1 Features • Supports crystal oscillator 0.45-16MHz (OSC0) • Supports Digital Frequency Locked Loop 20-150MHz (DFLL) • Supports Phase Locked Loop 80-240MHz (PLL) • Supports 32KHz ultra-low-power oscillator (OSC32K) • Supports 32kHz RC oscillator (RC32K) • Integrated low-power RC oscillator (RCSYS) • Generic clocks (GCLK) with wide frequency range provided • Generic Clock Prescaler • Controls Bandgap • Controls Brown-out detectors (BOD) and supply monitors • Controls Voltage Regulator (VREG) behavior and calibration • Controls Temperature Sensor • Controls Supply Monitor 33 (SM33) operating modes and calibration • Controls 120MHz integrated RC Oscillator (RC120M) • Four 32-bit general-purpose backup registers 14.2 Overview The System Control Interface (SCIF) controls the oscillators, Generic Clocks, BODs, Bandgap, VREG, Temperature Sensor, and Backup Registers. 14.3 I/O Lines Description 14.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 14-1. I/O Lines Description Pin Name Pin Description Type RC32OUT RC32 output at startup Output XIN0 Crystal 0 Input Analog/Digital XIN32 Crystal 32 Input (primary location) Analog/Digital XIN32_2 Crystal 32 Input (secondary location) Analog/Digital XOUT0 Crystal 0 Output Analog XOUT32 Crystal 32 Output (primary location) Analog XOUT32_2 Crystal 32 Output (secondary location) Analog GCLK9-GCLK0 Generic Clock Output Output GCLK_IN2-GCLK_IN0 Generic Clock Input Input 245 32142D–06/2013 ATUC64/128/256L3/4U 14.4.1 I/O Lines The SCIF provides a number of generic clock outputs, which can be connected to output pins, multiplexed with GPIO lines. The programmer must first program the GPIO controller to assign these pins to their peripheral function. If the I/O pins of the SCIF are not used by the application, they can be used for other purposes by the GPIO controller. Oscillator pins are also multiplexed with GPIO. When oscillators are used, the related pins are controlled directly by the SCIF, overriding GPIO settings. RC32OUT will be output after reset, and the GPIO controller can assign this pin to other peripheral function after start-up. 14.4.2 Power Management The BODs and all the oscillators, except the 32KHz oscillator (OSC32K) are turned off in some sleep modes and turned automatically on when the device wakes up. The Voltage Regulator is set in low power mode in some sleep modes and automatically set back in normal mode when the device wakes up. Please refer to the Power Manager chapter for details. The BOD control registers will not be reset by the Power Manager on a BOD reset. 14.4.3 Clocks The SCIF controls all oscillators in the device. The oscillators can be used as source for the CPU and peripherals. Selection of source is done in the Power Manager. The oscillators can also be used as source for generic clocks. 14.4.4 Interrupts The SCIF interrupt request line is connected to the interrupt controller. Using the SCIF interrupt requires the interrupt controller to be programmed first. 14.4.5 Debug Operation The SCIF does not interact with debug operations. 14.5 Functional Description 14.5.1 Oscillator (OSC) Operation Rev: 1.1.1.0 The main oscillator (OSCn) is designed to be used with an external 0.450 to 16MHz crystal and two biasing capacitors, as shown in the Electrical Characteristics chapter, or with an external clock connected to the XIN. The oscillator can be used as source for the main clock in the device, as described in the Power Manager chapter. The oscillator can be used as source for the generic clocks, as described in the Generic Clocks section. The oscillator is disabled by default after reset. When the oscillator is disabled, the XIN and XOUT pins can be used as general purpose I/Os. When the oscillator is enabled, the XIN and XOUT pins are controlled directly by the SCIF, overriding GPIO settings. When the oscillator is configured to use an external clock, the clock must be applied to the XIN pin while the XOUT pin can be used as general purpose I/O. The oscillator is enabled by writing a one to the Oscillator Enable bit in the Oscillator Control register (OSCCTRLn.OSCEN). Operation mode (external clock or crystal) is selected by writing to the Oscillator Mode bit in OSCCTRLn (OSCCTRLn.MODE). The oscillator is automatically dis- 246 32142D–06/2013 ATUC64/128/256L3/4U abled in certain sleep modes to reduce power consumption, as described in the Power Manager chapter. After a hard reset, or when waking up from a sleep mode where the oscillators were disabled, the oscillator will need a certain amount of time to stabilize on the correct frequency. This startup time can be set in the OSCCTRLn register. The SCIF masks the oscillator outputs during the start-up time, to ensure that no unstable clocks propagate to the digital logic. The OSCn Ready bit in the Power and Clock Status Register (PCLKSR.OSCnRDY) is set when the oscillator is stable and ready to be used as clock source. An interrupt can be generated on a zero-to-one transition on OSCnRDY if the OSCnRDY bit in the Interrupt Mask Register (IMR.OSCnRDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.OSCnRDY). 14.5.2 32KHz Oscillator (OSC32K) Operation Rev: 1.1.0.1 The 32KHz oscillator operates as described for the oscillator above. The 32KHz oscillator can be used as source clock for the Asynchronous Timer (AST) and the Watchdog Timer (WDT). The 32KHz oscillator can also be used as source for the generic clocks. The oscillator is disabled by default after reset. When the oscillator is disabled, the XIN32 and XOUT32 pins can be used as general-purpose I/Os. When the oscillator is enabled, the XIN32 and XOUT32 pins are controlled directly by the SCIF, overriding GPIO settings. When the oscillator is configured to use an external clock, the clock must be applied to the XIN32 pin while the XOUT32 pin can be used as general-purpose I/O. The oscillator is enabled writing a one to the OSC32 Enable bit in the 32KHz Oscillator Control Register (OSCCTRL32OSC32EN). The oscillator is disabled by writing a zero to the OSC32EN bit, while keeping the other bits unchanged. Writing to OSC32EN while also writing to other bits may result in unpredictable behavior. Operation mode (external clock or crystal) is selected by writing to the Oscillator Mode bit in OSCCTRL32 (OSCCTRL32.MODE). The oscillator is an ultra-low-power design and remains enabled in all sleep modes. The start-up time of the 32KHz oscillator is selected by writing to the Oscillator Start-up Time field in the OSCCTRL32 register (OSCCTRL32.STARTUP). The SCIF masks the oscillator output during the start-up time, to ensure that no unstable clock cycles propagate to the digital logic. The OSC32 Ready bit in the Power and Clock Status Register (PCLKSR.OSC32RDY) is set when the oscillator is stable and ready to be used as clock source. An interrupt can be generated on a zero-to-one transition on PCLKSR.OSC32RDY if the OSC32RDY bit in the Interrupt Mask Register (IMR.OSC32RDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.OSC32RDY). .As a crystal oscillator usually requires a very long start-up time (up to 1 second), the 32KHz oscillator will keep running across resets, except a Power-on Reset (POR). The 32KHz oscillator also has a 1KHz output. This is enabled by writing a one to the Enable 1KHz output bit in OSCCTRL32 register (OSCCTRL32.EN1K). If the 32KHz output clock is not needed when 1K is enabled, this can be disabled by writing a zero to the Enable 32KHz output bit in the OSCCTRL32 register (OSCCTRL32.EN32K). OSCCTRL32.EN32K is set after a POR. The 32KHz oscillator has two possible sets of pins. To select between them write to the Pin Select bit in the OSCCTRL32 register (OSCCTRL32.PINSEL). If the 32KHz oscillator is to be 247 32142D–06/2013 ATUC64/128/256L3/4U used in Shutdown mode, PINSEL must be written to one, and XIN32_2 and XOUT32_2 must be used. 14.5.3 PLL Operation Rev: 1.1.0.0 The device contains one Phase Locked Loop (PLL), which is controlled by the Phase Locked Loop Interface (PLLIF). The PLL is disabled by default, but can be enabled to provide high frequency source clocks for synchronous or generic clocks. The PLL can use different clock sources as reference clock, please refer to the “PLL Clock Sources” table in the SCIF Module Configuration section for details. The PLL output is divided by a multiplication factor, and the PLL compares the phase of the resulting clock to the reference clock. The PLL will adjust its output frequency until the two compared clocks phases are equal, thus locking the output frequency to a multiple of the reference clock frequency. When the PLL is switched on, or when changing the clock source or multiplication factor for the PLL, the PLL is unlocked and the output frequency is undefined. The PLL clock for the digital logic is automatically masked when the PLL is unlocked, to prevent the connected digital logic from receiving a too high frequency and thus become unstable. The PLL can be configured by writing the PLL Control Register (PLLn). To prevent unexpected writes due to software bugs, write access to the PLLn register is protected by a locking mechanism, for details please refer to the UNLOCK register description. Figure 14-1. PLL with Control Logic and Filters 14.5.3.1 Enabling the PLL Before the PLL is enabled it must be set up correctly. The PLL Oscillator Select field (PLLOSC) selects a source for the reference clock. The PLL Multiply Factor (PLLMUL) and PLL Division Phase Detector Output Divider Source clocks PLLOSC PLLOPT[0] PLLMUL Lock bit Mask PLL clock Input Divider PLLDIV 1/2 PLLOPT[1] 0 1 VCO fvco fPLL Lock Counter fREF 248 32142D–06/2013 ATUC64/128/256L3/4U Factor (PLLDIV) fields must be written with the multiplication and division factors, respectively. The PLLMUL must always be greater than 1, creating the PLL frequency: fvco = (PLLMUL+1)/PLLDIV • fREF, if PLLDIV >0 fvco = 2•(PLLMUL+1) • fREF, if PLLDIV = 0 The PLL Options (PLLOPT) field should be configured to proper values according to the PLL operating frequency. The PLLOPT field can also be configured to divide the output frequency of the PLL by 2 and Wide-Bandwidth mode, which allows faster startup time and out-of-lock time. It is not possible to change any of the PLL configuration bits when the PLL is enabled, Any write to PLLn while the PLL is enabled will be discarded. After setting up the PLL, the PLL is enabled by writing a one to the PLL Enable (PLLEN) bit in the PLLn register. 14.5.3.2 Disabling the PLL The PLL is disabled by writing a zero to the PLL Enable (PLLEN) bit in the PLLn register. After disabling the PLL, the PLL configuration fields becomes writable. 14.5.3.3 PLL Lock The lock signal for each PLL is available as a PLLLOCKn flag in the PCLKSR register. If the lock for some reason is lost, the PLLLOCKLOSTn flag in PCLKSR register will be set. An interrupt can be generated on a 0 to 1 transition of these bits. 14.5.4 Digital Frequency Locked Loop (DFLL) Operation Rev: 2.1.0.1 The DFLL is controlled by the Digital Frequency Locked Loop Interface (DFLLIF). The DFLL is disabled by default, but can be enabled to provide a high-frequency source clock for synchronous and generic clocks. Features: • Internal oscillator with no external components • 20-150MHz frequency in closed loop mode • Can operate standalone as a high-frequency programmable oscillator in open loop mode • Can operate as an accurate frequency multiplier against a known frequency in closed loop mode • Optional spread-spectrum clock generation • Very high-frequency multiplication supported - can generate all frequencies from a 32KHz clock The DFLL can operate in both open loop mode and closed loop mode. In closed loop mode a low frequency clock with high accuracy can be used as reference clock to get high accuracy on the output clock (CLK_DFLL). To prevent unexpected writes due to software bugs, write access to the configuration registers is protected by a locking mechanism. For details please refer to the UNLOCK register description. 249 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-2. DFLLIF Block Diagram 14.5.4.1 Enabling the DFLL The DFLL is enabled by writing a one to the Enable bit (EN) in the DFLLn Configuration Register (DFLLnCONF). No other bits or fields in DFLLnCONF must be changed simultaneously, or before the DFLL is enabled. 14.5.4.2 Internal synchronization Due to multiple clock domains in the DFLLIF, values in the DFLLIF configuration registers need to be synchronized to other clock domains. The status of this synchronization can be read from the Power and Clocks Status Register (PCLKSR). Before writing to a DFLLIF configuration register, the user must check that the DFLLn Synchronization Ready bit (DFLLnRDY) in PCLKSR is set. When this bit is set, the DFLL can be configured, and CLK_DFLL is ready to be used. Any write to a DFLLIF configuration register while DFLLnRDY is cleared will be ignored. Before reading the value in any of the DFLL configuration registers a one must be written to the Synchronization bit (SYNC) in the DFLLn Synchronization Register (DFLLnSYNC). The DFLL configuration registers are ready to be read when PCLKSR.DFLLnRDY is set. 14.5.4.3 Disabling the DFLL The DFLL is disabled by writing a zero to DFLLnCONF.EN. No other bits or fields in DFLLnCONF must be changed simultaneously. After disabling the DFLL, PCLKSR.DFLLnRDY will not be set. It is not required to wait for PCLKSR.DFLLnRDY to be set before re-enabling the DFLL. 14.5.4.4 Open loop operation After enabling the DFLL, open loop mode is selected by writing a zero to the Mode Selection bit (MODE) in DFLLnCONF. When operating in open loop mode the output frequency of the DFLL will be determined by the values written to the Coarse Calibration Value field (COARSE) and the Fine Calibration Value field (FINE) in the DFLLnCONF register. When writing to COARSE and DFLL COARSE FINE 8 9 CLK_DFLL IMUL FMUL 32 CLK_DFLLIF_REF FREQUENCY TUNER DFLLLOCKC DFLLLOCKLOSTC DFLLLOCKF DFLLLOCKLOSTF DFLLLOCKA DFLLLOCKLOSTA CSTEP FSTEP 8+9 CLK_DFLLIF_DITHER 250 32142D–06/2013 ATUC64/128/256L3/4U FINE, be aware that the output frequency must not exceed the maximum frequency of the device after the division in the clock generator. It is possible to change the value of COARSE and FINE, and thereby the output frequency of the DFLL, while the DFLL is enabled and in use. The DFLL clock is ready to be used when PCLKSR.DFLLnRDY is cleared after enabling the DFLL. The frequency range in open loop mode is 20-150MHz, but maximum frequency can be higher, and the minimum frequency can be lower. The best way to start the DFLL at a specific frequency in open loop mode is to first configure it for closed loop mode, see Section 14.5.4.5. When a lock is achieved, read back the COARSE and FINE values and switch to open loop mode using these values. An alternative approach is to use the Frequency Meter (FREQM) to monitor the DFLL frequency and adjust the COARSE and FINE values based on measurement results form the FREQM. Please refer to the FREQM chapter for more information on how to use it. Note that the output frequency of the DFLL will drift when in open loop mode due to temperature and voltage changes. Please refer to the Electrical Characteristics chapter for details. 14.5.4.5 Closed loop operation The DFLL must be correctly configured before closed loop operation can be enabled. After enabling the DFLL, enable and select a reference clock (CLK_DFLLIF_REF). CLK_DFLLIF_REF is a generic clock, please refer to Generic Clocks section for details. Then set the maximum step size allowed in finding the COARSE and FINE values by setting the Coarse Maximum Step field (CSTEP) and Fine Maximum Step field (FSTEP) in the DFLLn Maximum Step Register (DFLLnSTEP). A small step size will ensure low overshoot on the output frequency, but can typically result in longer lock times. A high value might give a big overshoot, but can typically give faster locking. DFLLnSTEP.CSTEP and DFLLnSTEP.FSTEP must be lower than 50% of the maximum value of DFLLnCONF.COARSE and DFLLnCONF.FINE respectively. Then select the multiplication factor in the Integer Multiply Factor field (IMUL) and the Fractional Multiply field (FMUL) in the DFLLn Multiplier Register (DFLLnMUL). Care must be taken when choosing IMUL and FMUL so the output frequency does not exceed the maximum frequency of the device. Start the closed loop mode by writing a one to DFLLnCONF.MODE bit. The frequency of CLK_DFLL (fDFLL) is given by: where fREF is the frequency of CLK_DFLLIF_REF. COARSE and FINE in DFLLnCONF are readonly in closed loop mode, and are controlled by the DFLLIF to meet user specified frequency. The values in COARSE when the closed loop mode is enabled is used by the frequency tuner as a starting point for COARSE. Setting COARSE to a value close to the final value will reduce the time needed to get a lock on COARSE. Frequency locking The locking of the frequency in closed loop mode is divided into three stages. In the COARSE stage the control logic quickly finds the correct value for DFLLnCONF.COARSE and thereby sets the output frequency to a value close to the correct frequency. The DFLLn Locked on Coarse Value bit (DFLLnLOCKC) in PCLKSR will be set when this is done. In the FINE stage the control logic tunes the value in DFLLnCONF.FINE so the output frequency will be very close to the desired frequency. DFLLn Locked on Fine Value bit (DFLLnLOCKF) in PCLKSR will be set when this is done. In the ACCURATE stage the DFLL frequency tuning mechanism uses dithering on the FINE bits to obtain an accurate average output frequency. DFLLn Locked on Accurate Value bit (DFLLnLOCKA) in PCLKSR will be set when this is done. The ACCURATE stage will f DFLL IMUL FMUL 216 + -----------------    f REF = 251 32142D–06/2013 ATUC64/128/256L3/4U only be executed if the Dithering Enable bit (DITHER) in DFLLnCONF has been written to a one. If DITHER is written to a zero DFLLnLOCKA will never occur. If dithering is enabled, the frequency of the dithering is decided by a generic clock (CLK_DFLLIF_DITHER). This clock has to be set up correctly before enabling dithering. Please refer to the Generic Clocks section for details. Figure 14-3. DFLL Closed loop State Diagram When dithering is enabled the accuracy of the average output frequency of the DFLL will be higher. However, the actual frequency will be alternating between two frequencies. If a fixed frequency is required, the dithering should not be enabled. Figure 14-4. DFLL Locking in Closed loop CLK_DFLL is ready to be used when the DFLLn Synchronization Ready bit (DFLLnRDY) in PCLKSR is set after enabling the DFLL. However, the accuracy of the output frequency depends on which locks are set. For lock times, please refer to the Electrical Characteristics chapter. Measure fDFLLn Calculate new COARSE value DFLLnLOCKC 0 Calculate new FINE value DFLLnLOCKF 0 1 1 DFLLnLOCKA Calculate new dithering dutycycle 0 Compensate for drift 1 DITHER 1 Compensate for drift 0 Initial frequency Target frequency DFLLnLOCKC DFLLnLOCKF DFLLnLOCKA 252 32142D–06/2013 ATUC64/128/256L3/4U Drift compensation The frequency tuner will automatically compensate for drift in the fDFLL without losing either of the locks. If the FINE value overflows or underflows, which should normally not happen, but could occur due to large drift in temperature and voltage, all locks will be lost, and the COARSE and FINE values will be recalibrated as described earlier. If any lock is lost the corresponding bit in PCLKSR will be set, DFLLn Lock Lost on Coarse Value bit (DFLLnLOCKLOSTC) for lock lost on COARSE value, DFLLn Lock Lost on Fine Value bit (DFLLnLOCKLOSTF) for lock lost on FINE value and DFLLn Lock Lost on Accurate Value bit (DFLLnLOCKLOSTA) for lock lost on ACCURATE value. The corresponding lock status bit will be cleared when the lock lost bit is set, and vice versa. Reference clock stop detection If CLK_DFLLIF_REF stops or is running at a very slow frequency, the DFLLn Reference Clock Stopped bit (DFLLnRCS) in PCLKSR will be set. Note that the detection of the clock stop will take a long time. The DFLLIF operate as if it was in open loop mode if it detects that the reference clock has stopped. This means that the COARSE and FINE values will be kept constant while PCLKSR.DFLLnRCS is set. Closed loop mode operation will automatically resume if the CLK_DFLLIF_REF is restarted, and compensate for any drift during the time CLK_DFLLIF_REF was stopped. No locks will be lost. Frequency error measurement The ratio between CLK_DFLLIF_REF and CLK_DFLL is measured automatically by the DFLLIF. The difference between this ratio and DFLLnMUL is stored in the Multiplication Ratio Difference field (RATIODIFF) in the DFLLn Ratio Register (DFLLnRATIO). The relative error on CLK_DFLL compared to the target frequency can be calculated as follows: where is the number of reference clock cycles the DFLLIF is using for calculating the ratio. 14.5.4.6 Dealing with delay in the DFLL The time from selecting a new frequency until this frequency is output by the DFLL, can be up to several micro seconds. If the difference between the desired output frequency (CLK_DFLL) and the frequency of CLK_DFLLIF_REF is small this can lead to an instability in the DFLLIF locking mechanism, which can prevent the DFLLIF from achieving locks. To avoid this, a chill cycle where the CLK_DFLL frequency is not measured can be enabled. The chill cycle is enabled by writing a one to the Chill Cycle Enable (CCEN) bit in the DFLLnCONF register. Enabling chill cycles might double the lock time, Another solution to the same problem can be to use less strict lock requirements. This is called Quick Lock (QL), which is enabled by writing a one to the Quick Lock Enable (QLEN) bit in the DFLLnCONF register. The QL might lead to bigger spread in the outputted frequency than chill cycles, but the average output frequency is the same. If the target frequency is below 40MHz, one of these methods should always be used. 14.5.4.7 Spread Spectrum Generator (SSG) When the DFLL is used as the main clock source for the device, the EMI radiated from the device will be synchronous to fDFLL. To provide better Electromagnetic Compatibility (EMC) the error RATIODIFF fREF  2NUMREF f DFLL  = ------------------------------------------------ 2NUMREF 253 32142D–06/2013 ATUC64/128/256L3/4U DFLLIF can provide a clock with the energy spread in the frequency domain. This is done by adding or subtracting values from the FINE value. SSG is enabled by writing a one to the Enable bit (EN) in the DFLLn Spread Spectrum Generator Control Register (DFLLnSSG). A generic clock sets the rate at which the SSG changes the frequency of the DFLL clock to generate a spread spectrum (CLK_DFLLIF_DITHER). This is the same clock used by the dithering mechanism. The frequency of this clock should be higher than fREF to ensure that the DFLLIF can lock. Please refer to the Generic clocks section for details. Optionally, the clock ticks can be qualified by a Pseudo Random Binary Sequence (PRBS) if the PRBS bit in DFLLnSSG is one. This reduces the modulation effect of CLK_DFLLIF_DITHER frequency onto fDFLL. The amplitude of the frequency variation can be selected by setting the SSG Amplitude field (AMPLITUDE) in DFLLnSSG. If AMPLITUDE is zero the SSG will toggle on the LSB of the FINE value. If AMPLITUDE is one the SSG will add the sequence {1,-1, 0} to FINE. The step size of the SSG is selected by writing to the SSG Step Size field (STEPSIZE) in DFLLnSSG. STEPSIZE equal to zero or one will result in a step size equal to one. If the step size is set to n, the output value from the SSG will be incremented/decremented by n on every tick of the source clock. The Spread Spectrum Generator is available in both open and closed loop mode. When spread spectrum is enabled in closed loop mode, and the AMPLITUDE is high, an overflow/underflow in FINE is more likely to occur. Figure 14-5. Spread Spectrum Generator Block Diagram. 14.5.4.8 Wake from sleep modes The DFLLIF may optionally reset its lock bits when waking from a sleep mode which disables the DFLL. This is configured by the Lose Lock After Wake (LLAW) bit in DFLLnCONF register. If DFLLnCONF.LLAW is written to zero the DFLL will be re-enabled and start running with the same configuration as before going to sleep even if the reference clock is not available. The locks will not be lost. When the reference clock has restarted, the FINE tracking will quickly compensate for any frequency drift during sleep. If a one is written to DFLLnCONF.LLAW before going to a sleep mode where the DFLL is turned off, the DFLLIF will lose all its locks when waking up, and needs to regain these through the full lock sequence. 14.5.4.9 Accuracy There are mainly three factors that decide the accuracy of the fDFLL. These can be tuned to obtain maximum accuracy when fine lock is achieved. Pseudorandom Binary Sequence Spread Spectrum Generator FINE 9 To DFLL CLK_DFLLIF_DITHER AMPLITUDE, STEPSIZE PRBS 1 0 254 32142D–06/2013 ATUC64/128/256L3/4U • FINE resolution: The frequency step between two FINE values. This is relatively smaller for high output frequencies. • Resolution of the measurement: If the resolution of the measured fDFLL is low, i.e. the ratio between CLK_DFLL frequency and CLK_DFLLIF_REF is small, then the DFLLIF might lock at a frequency that is lower than the targeted frequency. It is recommended to use a reference clock frequency of 32 KHz or lower to avoid this issue for low target frequencies. • The accuracy of the reference clock. 14.5.4.10 Interrupts A interrupt can be generated on a zero-to-one transaction on DFLLnLOCKC, DFLLnLOCKF, DFLLnLOCKA, DFLLnLOCKLOSTC, DFLLnLOCKLOSTF, DFLLnLOCKLOSTA, DFLLnRDY or DFLLnRCS. 14.5.5 Brown-Out Detection (BOD) Rev: 1.2.0.0 The Brown-Out Detector monitors the VDDCORE supply pin and compares the supply voltage to the brown-out detection level. The BOD is disabled by default, and is enabled by writing to the BOD Control field in the BOD Control Register (BOD.CTRL). This field can also be updated by flash fuses. The BOD is powered by VDDIO and will not be powered during Shutdown sleep mode. To prevent unexpected writes to the BOD register due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the BOD register can be set as readonly by writing a one to the Store Final Value bit (BOD.SFV). When this bit is one, software can not change the BOD register content. This bit is cleared after flash calibration and after a reset except after a BOD reset. The brown-out detection level is selected by writing to the BOD Level field in BOD (BOD.LEVEL). Please refer to the Electrical Characteristics chapter for parametric details. If the BOD is enabled (BOD.CTRL is one or two) and the supply voltage goes below the detection level, the Brown-Out Detection bit in the Power and Clocks Status Register (PCLKSR.BODDET) is set. This bit is cleared when the supply voltage goes above the detection level. An interrupt request will be generated on a zero-to-one transition on PCLKSR.BODDET if the Brown-Out Detection bit in the Interrupt Mask Register (IMR.BODDET) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.BODDET). If BOD.CTRL is one, a BOD reset will be generated when the supply voltage goes below the detection level. If BOD.CTRL is two, the device will not be reset. Writing a one to the BOD Hysteresis bit in BOD (BOD.HYST) will add a hysteresis on the BOD detection level. Note that the BOD must be disabled before changing BOD.LEVEL, to avoid spurious reset or interrupt. After enabling the BOD, the BOD output will be masked during one half of a RCSYS clock cycle and two main clocks cycles to avoid false results. When the JTAG or aWire is enabled, the BOD reset and interrupt are masked. 255 32142D–06/2013 ATUC64/128/256L3/4U The CTRL, HYST, and LEVEL fields in the BOD Control Register are loaded factory defined calibration values from flash fuses after a reset. If the Flash Calibration Done bit in the BOD Control Register (BOD.FCD) is zero, the flash calibration will be redone after any reset, and the BOD.FCD bit will be set before program execution starts in the CPU. If BOD.FCD is one, the flash calibration is redone after any reset except for a BOD reset. The BOD.FCD bit is cleared after a reset, except for a BOD reset. BOD.FCD is set when these fields have been updated after a flash calibration. It is possible to override the values in the BOD.CTRL, BOD.HYST, and BOD.LEVEL fields after reset by writing to the BOD Control Register. Please refer to the Fuse Settings chapter for more details about BOD fuses and how to program the fuses. Figure 14-6. BOD Block Diagram 14.5.6 Bandgap Rev: 1.2.0.0 The flash memory, the BOD, and the Temperature Sensor need a stable voltage reference to operate. This reference voltage is provided by an internal Bandgap voltage reference. This reference is automatically turned on at start-up and turned off during some sleep modes to save power. The Bandgap reference is powered by the internal regulator supply voltage and will not be powered during Shutdown sleep mode. Please refer to the Power Manager chapter for details. VDDCORE POR18 BOD SCIF POWER MANAGER(PM) INTC Reset Bod Detected Enable BO D Hyst BOD Level Reset In et rrupt 256 32142D–06/2013 ATUC64/128/256L3/4U 14.5.7 System RC Oscillator (RCSYS) Rev: 1.1.1.0 The system RC oscillator has a startup time of three cycles, and is always available except in some sleep modes. Please refer to the Power Manager chapter for details. The system RC oscillator operates at a nominal frequency of 115kHz, and is calibrated using the Calibration Value field (CALIB) in the RC Oscillator Calibration Register (RCCR). After a Power-on Reset (POR), the RCCR.CALIB field is loaded with a factory defined value stored in the Flash fuses. Please refer to the Fuse setting chapter for more details about RCCR fuses and how to program the fuses. If the Flash Calibration Done (FCD) bit in the RCCR is zero at any reset, the flash calibration will be redone and the RCCR.FCD bit will be set before program execution starts in the CPU. If the RCCR.FCD is one, the flash calibration will only be redone after a Power-on Reset. To prevent unexpected writes to RCCR due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. Although it is not recommended to override default factory settings, it is still possible to override the default values by writing to RCCR.CALIB. 14.5.8 Voltage Regulator (VREG) Rev: 1.1.0.0 The embedded voltage regulator can be used to provide the VDDCORE voltage from the internal regulator supply voltage. It is controlled by the Voltage Regulator Calibration Register (VREGCR). The voltage regulator is enabled by default at start-up but can be disabled by software if an external voltage is provided on the VDDCORE pin. The VREGCR also contains bits to control the POR18 detector and the POR33 detector. 14.5.8.1 Register protection To prevent unexpected writes to VREGCR due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the VREGCR register can be set as read-only by writing a one to the Store Final Value bit (VREGCR.SFV). Once this bit is set, software can not change the VREGCR content until a Power-on Reset (POR) is applied. 14.5.8.2 Controlling voltage regulator output The voltage regulator is always enabled at start-up, i.e. after a POR or when waking up from Shutdown mode. It can be disabled by software by writing a zero to the Enable bit (VREGCR.EN). This bit is set after a POR. Because of internal synchronization, the voltage regulator is not immediately enabled or disabled. The actual state of the voltage regulator can be read from the ON bit (VREGCR.ON). The voltage regulator output level is controlled by the Select VDD field (SELVDD) in VREGCR. The default value of this field corresponds to a regulator output voltage of 1.8V. Other values of this field are not defined, and it is not recommended to change the value of this field. The Voltage Regulator OK bit (VREGCR.VREGOK) bit indicates when the voltage regulator output has reached the voltage threshold level. 257 32142D–06/2013 ATUC64/128/256L3/4U 14.5.8.3 Factory calibration After a Power-on Reset (POR) the VREGCR.CALIB field is loaded with a factory defined calibration value. This value is chosen so that the normal output voltage of the regulator after a powerup is 1.8V. Although it is not recommended to override default factory settings, it is still possible to override these default values by writing to VREGCR.CALIB. If the Flash Calibration Done bit in VREGCR (VREGCR.FCD) is zero, the flash calibration will be redone after any reset, and the VREGCR.FCD bit will be set before program execution starts in the CPU. If VREGCR.FCD is one, the flash calibration will only be redone after a POR. 14.5.8.4 POR33 control VREGCR includes control bits for the Power-on Reset 3.3V (POR33) detector that monitors the internal regulator supply voltage. The POR33 detector is enabled by default but can be disabled by software to reduce power consumption. The 3.3V Supply Monitor (SM33) can then be used to monitor the regulator power supply. The POR33 detector is disabled by writing a zero to the POR33 Enable bit (VREGCR.POR33EN). Because of internal synchronisation, the POR33 detector is not immediately enabled or disabled. The actual state of the POR33 detector can be read from the POR33 Status bit (VREGCR.POR33STATUS). The 32kHz RC oscillator (RC32K) must be enabled before disabling the POR33 detector. Once the POR33 detector has been disabled, the RC32K oscillator can be disabled again. To avoid spurious resets, it is mandatory to mask the Power-on Reset when enabling or disabling the POR33 detector. The Power-on Reset generated by the POR33 detector can be ignored by writing a one to the POR33 Mask bit (VREGCR.POR33MASK). Because of internal synchronization, the masking is not immediately effective, so software should wait for the VREGCR.POR33MASK to read as a one before assuming the masking is effective. The output of the POR33 detector is zero if the internal regulator supply voltage is below the POR33 power-on threshold level, and one if the internal regulator supply voltage is above the POR33 power-on threshold level. This output (before masking) can be read from the POR33 Value bit (VREGCR.POR33VALUE). 14.5.8.5 POR18 control VREGCR includes control bits for the Power-on Reset 1.8V (POR18) detector that monitors the VDDCORE voltage. The POR18 detector is enabled by default but can be disabled by software to reduce power consumption. The POR18 detector is disabled by writing a zero to the POR18 Enable bit (VREGCR.POR18EN). Because of internal synchronization, the POR18 detector is not immediately enabled or disabled. The actual state of the POR18 detector can be read from the POR18 Status bit (VREGCR.POR18STATUS). Please note that the POR18 detector cannot be disabled while the JTAG or aWire debug interface is used. Writing a zero to VREGCR.POR18EN bit will have no effect. To avoid spurious resets, it is mandatory to mask the Power-on Reset when enabling or disabling the POR18 detector. The Power-on Reset generated by the POR18 detector can be ignored by writing a one to the POR18 Mask bit (VREGCR.POR18MASK). Because of internal 258 32142D–06/2013 ATUC64/128/256L3/4U synchronisation, the masking is not immediately effective, so software should wait for the VREGCR.POR18MASK to read as one before assuming the masking is effective. The output of the POR18 detector is zero if the VDDCORE voltage is below the POR18 poweron threshold level, and one if the VDDCORE voltage is above the POR18 power-on threshold level. The output of the POR18 detector (before masking) can be read from the POR18 Value bit (VREGCR.POR18VALUE). 14.5.9 3.3 V Supply Monitor (SM33) Rev: 1.1.0.0 The 3.3V supply monitor is a specific voltage detector for the internal regulator supply voltage. It will indicate if the internal regulator supply voltage is above the minimum required input voltage threshold. The user can choose to generate either a Power-on Reset (POR) and an interrupt request, or only an interrupt request, when the internal regulator supply voltage drops below this threshold. Please refer to the Electrical Characteristics chapter for parametric details. 14.5.9.1 Register protection To prevent unexpected writes to SM33 register due to software bugs, write access to this register is protected by a locking mechanism. For details please refer to the UNLOCK register description. To prevent further modifications by software, the content of the register can be set as read-only by writing a one to the Store Final Value bit (SM33.SFV). When this bit is one, software can not change the SM33 register content until the device is reset. 14.5.9.2 Operating modes The SM33 is disabled by default and is enabled by writing to the Supply Monitor Control field in the SM33 control register (SM33.CTRL). The current state of the SM33 can be read from the Supply Monitor On Indicator bit in SM33 (SM33.ONSM). Enabling the SM33 will disable the POR33 detector. The SM33 can operate in continuous mode or in sampling mode. In sampling mode, the SM33 is periodically enabled for a short period of time, just enough to make a a measurement, and then disabled for a longer time to reduce power consumption. By default, the SM33 operates in sampling mode during DeepStop and Static mode and in continuous mode for other sleep modes. Sampling mode can also be forced during sleep modes other than DeepStop and Static, and during normal operation, by writing a one to the Force Sampling Mode bit in the SM33 register (SM33.FS). The user can select the sampling frequency by writing to the Sampling Frequency field in SM33 (SM33.SAMPFREQ). The sampling mode uses the 32kHz RC oscillator (RC32K) as clock source. The 32kHz RC oscillator is automatically enabled when the SM33 operates in sampling mode. 14.5.9.3 Interrupt and reset generation If the SM33 is enabled (SM33.CTRL is one or two) and the regulator supply voltage drops below the SM33 threshold, the SM33DET bit in the Power and Clocks Status Register (PCLKSR.SM33DET) is set. This bit is cleared when the supply voltage goes above the threshold. An interrupt request is generated on a zer-to-one transition of PCLKSR.SM33DET if the 259 32142D–06/2013 ATUC64/128/256L3/4U Supply Monitor 3.3V Detection bit in the Interrupt Mask Register (IMR.SM33DET) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.SM33DET). If SM33.CTRL is one, a POR will be generated when the voltage drops below the threshold. If SM33.CTRL is two, the device will not be reset. 14.5.9.4 Factory calibration After a reset the SM33.CALIB field is loaded with a factory defined value. This value is chosen so that the nominal threshold value is 1.75V. The flash calibration is redone after any reset, and the Flash Calibration Done bit in SM33 (SM33.FCD) is set before program execution starts in the CPU. Although it is not recommended to override default factory settings, it is still possible to override the default value by writing to SM33.CALIB 14.5.10 Temperature Sensor Rev: 1.0.0.0 The Temperature Sensor is connected to an ADC channel, please refer to the ADC chapter for details. It is enabled by writing one to the Enable bit (EN) in the Temperature Sensor Configuration Register (TSENS). The Temperature Sensor can not be calibrated. Please refer to the Electrical Characteristics chapter for more details. 14.5.11 120MHz RC Oscillator (RC120M) Rev: 1.1.0.0 The 120MHz RC Oscillator can be used as source for the main clock in the device, as described in the Power Manager chapter. The oscillator can also be used as source for the generic clocks, as described in Generic Clock section. The RC120M must be enabled before it is used as a source clock. To enable the clock, the user must write a one to the Enable bit in the 120MHz RC Oscillator Control Register (RC120MCR.EN), and read back the RC120MCR register until the EN bit reads one. The clock is disabled by writing a zero to RC120MCR.EN. The EN bit must be read back as zero before the RC120M is re-enabled. If not, undefined behavior may occur. The oscillator is automatically disabled in certain sleep modes to reduce power consumption, as described in the Power Manager chapter. 14.5.12 Backup Registers (BR) Rev: 1.0.0.1 Four 32-bit backup registers are available to store values when the device is in Shutdown mode. These registers will keep their content even when the VDDCORE supply and the internal regulator supply voltage supplies are removed. The backup registers can be accessed by reading from and writing to the BR0, BR1, BR2, and BR3 registers. After writing to one of the backup registers the user must wait until the Backup Register Interface Ready bit in tne Power and Clocks Status Register (PCLKSR.BRIFARDY) is set before writing to another backup register. Writes to the backup register while PCLKSR.BRIFARDY is zero will be discarded. An interrupt can be generated on a zero-to-one transition on PCLKSR.BRIFARDY if 260 32142D–06/2013 ATUC64/128/256L3/4U the BRIFARDY bit in the Interrupt Mask Register (IMR.BRIFARDY) is set. This bit is set by writing a one to the corresponding bit in the Interrupt Enable Register (IER.BRIFARDY). After powering up the device the Backup Register Interface Valid bit in PCLKSR (PCLKSR.BRIFAVALID) is cleared, indicating that the content of the backup registers has not been written and contains the reset value. After writing to one of the backup registers the PCLKSR.BRIFAVALID bit is set. During writes to the backup registers (when BRIFARDY is zero) BRIFAVALID will be zero. If a reset occurs when BRIFARDY is zero, BRIFAVALID will be cleared after the reset, indicating that the content of the backup registers is not valid. If BRIFARDY is one when a reset occurs, BRIFAVALID will be one and the content is the same as before the reset. The user must ensure that BRIFAVALID and BRIFARDY are both set before reading the backup register values. 14.5.13 32kHz RC Oscillator (RC32K) Rev: 1.1.0.0 The RC32K can be used as source for the generic clocks, as described in The Generic Clocks section. The 32kHz RC oscillator (RC32K) is forced on after reset, and output on PA20. The clock is available on the pad until the PPCR.FRC32 bit in the Power Manager has been cleared or a different peripheral function has been chosen on PA20 (PA20 will start with peripheral function F by default). Note that the forcing will only enable the clock output. To be able to use the RC32K normally the oscillator must be enabled as described below. The oscillator is enabled by writing a one to the Enable bit in the 32kHz RC Oscillator Configuration Register (RC32KCR.EN) and disabled by writing a zero to RC32KCR.EN. The oscillator is also automatically enabled when the sampling mode is requested for the SM33. In this case, writing a zero to RC32KCR.EN will not disable the RC32K until the sampling mode is no longer requested. 14.5.14 Generic Clock Prescalers Rev: 1.0.0.0 The generic clocks can be sourced by two special prescalers to increase the generic clock frequency precision. These prescalers are named the High Resolution Prescaler (HRP) and the Fractional Prescaler (FP). 14.5.14.1 High resolution prescaler The HRP is a 24-bit counter that can generate a very accurate clock waveform. The clock obtained has 50% duty cycle. 261 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-7. High Resolution Prescaler Generation The HRP is enabled by writing a one to the High Resolution Prescaler Enable (HRPEN) bit in the High Resolution Prescaler Control Register (HRPCR). The user can select a clock source for the HRP by writing to the Clock Selection (CKSEL) field of the HRPCR register. The user must configure the High Resolution Prescaler Clock (HRPCLK) frequency by writing to the High Resolution Count (HRCOUNT) field of the High Resolution Counter (HRPCR) register. This results in the output frequency: fHRPCLK = fSRC / (2*(HRCOUNT+1)) The CKSEL field can not be changed dynamically but the HRCOUNT field can be changed onthe-fly. 14.5.14.2 Fractional prescaler The FP generates a clock whose average frequency is more precise than the HRP. However, this clock frequency is subject to jitter around the target clock frequency. This jitter influence can be decreased by dividing this clock with the GCLK divider. Moreover the duty cycle of this clock is not precisely 50%. Figure 14-8. Fractional Prescaler Generation The FP is enabled by writing a one to the FPEN bit in the Fractional Prescaler Control Register (FPCR). The user can select a clock source for the FP by writing to the CKSEL field of the FPCR register. Divider CKSEL HRPCLK HRCOUNT Mask HRPEN Divider CKSEL FPCLK FPDIV Mask FPMUL FPEN 262 32142D–06/2013 ATUC64/128/256L3/4U The user must configure the FP frequency by writing to the FPMUL and FPDIV fields of the FPMUL and FPDIV registers. FPMUL and FPDIV must not be equal to zero and FPDIV must be greater or equal to FPMUL. This results in the output frequency: fFPCLK = fSRC * FPMUL/ (2*FPDIV) The CKSEL field can not be changed dynamically but the FPMUL and FPDIV fields can be changed on-the-fly. • Jitter description As described in Figure 14-9, the CLKFP half period lengths are integer multiples of the source clock period but are not always equals. However the difference between the low level half period length and the high level half period length is at the most one source clock period. This induces when FPDIV is not an integer multiple of FPMUL a jitter on the FPCLK. The more the FPCLK frequency is low, the more the jitter incidence is reduced. Figure 14-9. Fractional Prescaler Jitter Examples 14.5.15 Generic Clocks Rev: 1.1.0.0 Timers, communication modules, and other modules connected to external circuitry may require specific clock frequencies to operate correctly. The SCIF defines a number of generic clocks that can provide a wide range of accurate clock frequencies. Each generic clock runs from either clock source listed in the “Generic Clock Sources” table in the SCIF Module Configuration section. The selected source can optionally be divided by any even integer up to 512. Each clock can be independently enabled and disabled, and is also automatically disabled along with peripheral clocks by the Sleep Controller in the Power Manager. SRC clock FPCLK FMUL= 5 FDIV=5 FMUL=3 FDIV=10 FMUL=7 FDIV=9 263 32142D–06/2013 ATUC64/128/256L3/4U Figure 14-10. Generic Clock Generation 14.5.15.1 Enabling a generic clock A generic clock is enabled by writing a one to the Clock Enable bit (CEN) in the Generic Clock Control Register (GCCTRL). Each generic clock can individually select a clock source by writing to the Oscillator Select field (OSCSEL). The source clock can optionally be divided by writing a one to the Divide Enable bit (DIVEN) and the Division Factor field (DIV), resulting in the output frequency: where fSRC is the frequency of the selected source clock, and fGCLK is the output frequency of the generic clock. 14.5.15.2 Disabling a generic clock A generic clock is disabled by writing a zero to CEN or entering a sleep mode that disables the PB clocks. In either case, the generic clock will be switched off on the first falling edge after the disabling event, to ensure that no glitches occur. After CEN has been written to zero, the bit will still read as one until the next falling edge occurs, and the clock is actually switched off. When writing a zero to CEN the other bits in GCCTRL should not be changed until CEN reads as zero, to avoid glitches on the generic clock. The generic clocks will be automatically re-enabled when waking from sleep. 14.5.15.3 Changing clock frequency When changing the generic clock frequency by changing OSCSEL or DIV, the clock should be disabled before being re-enabled with the new clock source or division setting. This prevents glitches during the transition. 14.5.15.4 Generic clock allocation The generic clocks are allocated to different functions as shown in the “Generic Clock Allocation” table in the SCIF Module Configuration section. 14.5.16 Interrupts The SCIF has the following interrupt sources: • AE - Access Error: – A protected SCIF register was accessed without first being correctly unlocked. Divider OSCSEL Generic Clock DIV 0 1 DIVEN Mask CEN Sleep Controller fSRC fGCLK Generic Clock Sources f GCLK f SRC 2  DIV + 1 = ---------------------------- 264 32142D–06/2013 ATUC64/128/256L3/4U • PLLLOCK - PLL Lock – A 0 to 1 transition on the PCLKSR.PLLLOCK bit is detected. • PLLLOCKLOST - PLL Lock Lost – A to 1 transition on the PCLKSR.PLLLOCKLOST bit is detected. • BRIFARDY - Backup Register Interface Ready. – A 0 to 1 transition on the PCLKSR.BRIFARDY bit is detected. • DFLL0RCS - DFLL Reference Clock Stopped: – A 0 to 1 transition on the PCLKSR.DFLLRCS bit is detected. • DFLL0RDY - DFLL Ready: – A 0 to 1 transition on the PCLKSR.DFLLRDY bit is detected. • DFLL0LOCKLOSTA - DFLL lock lost on Accurate value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTA bit is detected. • DFLL0LOCKLOSTF - DFLL lock lost on Fine value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTF bit is detected. • DFLL0LOCKLOSTC - DFLL lock lost on Coarse value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKLOSTC bit is detected. • DFLL0LOCKA - DFLL Locked on Accurate value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKA bit is detected. • DFLL0LOCKF - DFLL Locked on Fine value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKF bit is detected. • DFLL0LOCKC - DFLL Locked on Coarse value: – A 0 to 1 transition on the PCLKSR.DFLLLOCKC bit is detected. • BODDET - Brown out detection: – A 0 to 1 transition on the PCLKSR.BODDET bit is detected. • SM33DET - Supply Monitor 3.3V Detector: – A 0 to 1 transition on the PCLKSR.SM33DET bit is detected. • VREGOK - Voltage Regulator OK: – A 0 to 1 transition on the PCLKSR.VREGOK bit is detected. • OSC0RDY - Oscillator Ready: – A 0 to 1 transition on the PCLKSR.OSC0RDY bit is detected. • OSC32RDY - 32KHz Oscillator Ready: – A 0 to 1 transition on the PCLKSR.OSC32RDY bit is detected. The interrupt sources will generate an interrupt request if the corresponding bit in the Interrupt Mask Register is set. The interrupt sources are ORed together to form one interrupt request. The SCIF will generate an interrupt request if at least one of the bits in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in the Interrupt Status Register (ISR) is cleared by writing a one to the corresponding bit in the Interrupt Clear Register (ICR). Because all the interrupt sources are ORed together, the interrupt request from the SCIF will remain active until all the bits in ISR are cleared. 265 32142D–06/2013 ATUC64/128/256L3/4U 14.6 User Interface Table 14-2. SCIF Register Memory Map Offset Register Register Name Access Reset 0x0000 Interrupt Enable Register IER Write-only 0x00000000 0x0004 Interrupt Disable Register IDR Write-only 0x00000000 0x0008 Interrupt Mask Register IMR Read-only 0x00000000 0x000C Interrupt Status Register ISR Read-only 0x00000000 0x0010 Interrupt Clear Register ICR Write-only 0x00000000 0x0014 Power and Clocks Status Register PCLKSR Read-only 0x00000000 0x0018 Unlock Register UNLOCK Write-only 0x00000000 0x001C Oscillator 0 Control Register OSCCTRL0 Read/Write 0x00000000 0x0020 Oscillator 32 Control Register OSCCTRL32 Read/Write 0x00000004 0x0024 DFLL Config Register DFLL0CONF Read/Write 0x00000000 0x0028 DFLL Multiplier Register DFLL0MUL Write-only 0x00000000 0x002C DFLL Step Register DFLL0STEP Write-only 0x00000000 0x0030 DFLL Spread Spectrum Generator Control Register DFLL0SSG Write-only 0x00000000 0x0034 DFLL Ratio Register DFLL0RATIO Read-only 0x00000000 0x0038 DFLL Synchronization Register DFLL0SYNC Write-only 0x00000000 0x003C BOD Level Register BOD Read/Write -(2) 0x0044 Voltage Regulator Calibration Register VREGCR Read/Write -(2) 0x0048 System RC Oscillator Calibration Register RCCR Read/Write -(2) 0x004C Supply Monitor 33 Calibration Register SM33 Read/Write -(2) 0x0050 Temperature Sensor Calibration Register TSENS Read/Write 0x00000000 0x0058 120MHz RC Oscillator Control Register RC120MCR Read/Write 0x00000000 0x005C-0x0068 Backup Registers BR Read/Write 0x00000000 0x006C 32kHz RC Oscillator Control Register RC32KCR Read/Write 0x00000000 0x0070 Generic Clock Control0 GCCTRL0 Read/Write 0x00000000 0x0074 Generic Clock Control1 GCCTRL1 Read/Write 0x00000000 0x0078 Generic Clock Control2 GCCTRL2 Read/Write 0x00000000 0x007C Generic Clock Control3 GCCTRL3 Read/Write 0x00000000 0x0080 Generic Clock Control4 GCCTRL4 Read/Write 0x00000000 0x0084 Generic Clock Control5 GCCTRL5 Read/Write 0x00000000 0x0088 Generic Clock Control6 GCCTRL6 Read/Write 0x00000000 0x008C Generic Clock Control7 GCCTRL7 Read/Write 0x00000000 0x0090 Generic Clock Control8 GCCTRL8 Read/Write 0x00000000 0x0094 Generic Clock Control9 GCCTRL9 Read/Write 0x00000000 266 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. The reset value is device specific. Please refer to the Module Configuration section at the end of this chapter. 2. The reset value of this register depends on factory calibration. 0x0098 PLL0 Control Register PLL0 Read/Write 0x00000000 0x009C High Resolution Prescaler Control Register HRPCR Read/Write 0x00000000 0x00A0 Fractional Prescaler Control Register FPCR Read/Write 0x00000000 0x00A4 Fractional Prescaler Multiplier Register FPMUL Read/Write 0x00000000 0x00A8 Fractional Prescaler DIVIDER Register FPDIV Read/Write 0x00000000 0x03BC Commonly used Modules Version Register CMVERSION Read-only -(1) 0x03C0 Generic Clock Prescaler Version Register GCLKPRESCVERSION Read-only -(1) 0x03C4 PLL Version Register PLLVERSION Read-only -(1) 0x03C8 Oscillator0 Version Register OSC0VERSION Read-only -(1) 0x03CC 32 KHz Oscillator Version Register OSC32VERSION Read-only -(1) 0x03D0 DFLL Version Register DFLLIFVERSION Read-only -(1) 0x03D4 BOD Version Register BODIFAVERSION Read-only -(1) 0x03D8 Voltage Regulator Version Register VREGIFBVERSION Read-only -(1) 0x03DC System RC Oscillator Version Register RCOSCIFAVERSION Read-only -(1) 0x03E0 3.3V Supply Monitor Version Register SM33IFAVERSION Read-only -(1) 0x03E4 Temperature Sensor Version Register TSENSIFAVERSION Read-only -(1) 0x03EC 120MHz RC Oscillator Version Register RC120MIFAVERSION Read-only -(1) 0x03F0 Backup Register Interface Version Register BRIFAVERSION Read-only -(1) 0x03F4 32kHz RC Oscillator Version Register RC32KIFAVERSION Read-only -(1) 0x03F8 Generic Clock Version Register GCLKVERSION Read-only -(1) 0x03FC SCIF Version Register VERSION Read-only -(1) Table 14-2. SCIF Register Memory Map Offset Register Register Name Access Reset 267 32142D–06/2013 ATUC64/128/256L3/4U 14.6.1 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0000 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 268 32142D–06/2013 ATUC64/128/256L3/4U 14.6.2 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x0004 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 269 32142D–06/2013 ATUC64/128/256L3/4U 14.6.3 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x0008 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 270 32142D–06/2013 ATUC64/128/256L3/4U 14.6.4 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x000C Reset Value: 0x00000000 0: The corresponding interrupt is cleared. 1: The corresponding interrupt is pending. A bit in this register is cleared when the corresponding bit in ICR is written to one. A bit in this register is set when the corresponding interrupt occurs. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 271 32142D–06/2013 ATUC64/128/256L3/4U 14.6.5 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x0010 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR. 31 30 29 28 27 26 25 24 AE - - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 272 32142D–06/2013 ATUC64/128/256L3/4U 14.6.6 Power and Clocks Status Register Name: PCLKSR Access Type: Read-only Offset: 0x0014 Reset Value: 0x00000000 • BRIFAVALID: Backup Register Interface Valid 0: The values in the backup registers are not valid. 1: The values in the backup registers are valid. • PLLL0LOCKLOST: PLL0 lock lost value 0: PLL0 has not lost it’s lock or has never been enabled. 1: PLL0 has lost it’s lock, either by disabling the PLL0 or due to faulty operation. • PLL0LOCK: PLL0 Locked on Accurate value 0: PLL0 is unlocked on accurate value. 1: PLL0 is locked on accurate value, and is ready to be selected as clock source with an accurate output clock. • BRIFARDY: Backup Register Interface Ready 0: The backup register interface is busy updating the backup registers. Writes to BRn will be discarded. 1: The backup register interface is ready to accept new writes to the backup registers. • DFLL0RCS: DFLL0 Reference Clock Stopped 0: The DFLL reference clock is running, or has never been enabled. 1: The DFLL reference clock has stopped or is too slow. • DFLL0RDY: DFLL0 Synchronization Ready 0: Read or write to DFLL registers is invalid 1: Read or write to DFLL registers is valid • DFLL0LOCKLOSTA: DFLL0 Lock Lost on Accurate Value 0: DFLL has not lost its Accurate lock or has never been enabled. 1: DFLL has lost its Accurate lock, either by disabling the DFLL or due to faulty operation. • DFLL0LOCKLOSTF: DFLL0 Lock Lost on Fine Value 0: DFLL has not lost its Fine lock or has never been enabled. 1: DFLL has lost its Fine lock, either by disabling the DFLL or due to faulty operation. 31 30 29 28 27 26 25 24 - BRIFAVALID - - - - - - 23 22 21 20 19 18 17 16 ----- PLLLOCKLO ST0 PLLLOCK0 BRIFARDY 15 14 13 12 11 10 9 8 DFLL0RCS DFLL0RDY DFLL0LOCK LOSTA DFLL0LOCK LOSTF DFLL0LOCK LOSTC DFLL0LOCK A DFLL0LOCK F DFLL0LOCK C 76543210 BODDET SM33DET VREGOK - - - OSC0RDY OSC32RDY 273 32142D–06/2013 ATUC64/128/256L3/4U • DFLL0LOCKLOSTC: DFLL0 Lock Lost on Coarse Value 0: DFLL has not lost its Coarse lock or has never been enabled. 1: DFLL has lost its Coarse lock, either by disabling the DFLL or due to faulty operation. • DFLL0LOCKA: DFLL0 Locked on Accurate Value 0: DFLL is unlocked on Accurate value. 1: DFLL is locked on Accurate value, and is ready to be selected as clock source with an accurate output clock. • DFLL0LOCKF: DFLL0 Locked on Fine Value 0: DFLL is unlocked on Fine value. 1: DFLL is locked on Fine value, and is ready to be selected as clock source with a high accuracy on the output clock. • DFLL0LOCKC: DFLL0 Locked on Coarse Value 0: DFLL is unlocked on Coarse value. 1: DFLL is locked on Coarse value, and is ready to be selected as clock source with medium accuracy on the output clock. • BODDET: Brown-Out Detection 0: No BOD Event. 1: BOD has detected that the supply voltage is below the BOD reference value. • SM33DET: Supply Monitor 3.3V Detector 0: SM33 not enabled or the supply voltage is above the SM33 threshold. 1: SM33 enabled and the supply voltage is below the SM33 threshold. • VREGOK: Voltage Regulator OK 0: Voltage regulator not enabled or not ready. 1: Voltage regulator has reached its output threshold value after being enabled. • OSC0RDY: OSC0 Ready 0: Oscillator not enabled or not ready. 1: Oscillator is stable and ready to be used as clock source. • OSC32RDY: 32 KHz oscillator Ready 0: OSC32K not enabled or not ready. 1: OSC32K is stable and ready to be used as clock source. 274 32142D–06/2013 ATUC64/128/256L3/4U 14.6.7 Unlock Register Name: UNLOCK Access Type: Write-only Offset: 0x0018 Reset Value: 0x00000000 To unlock a write protected register, first write to the UNLOCK register with the address of the register to unlock in the ADDR field and 0xAA in the KEY field. Then, in the next PB access write to the register specified in the ADDR field. The LOCK is by default off. To turn on the LOCK, first write 0xAA to the KEY field and UNLOCK address offset to the ADDR field in the UNLOCK register, followed by writing 0x5A5A5A5A to the UNLOCK register. To turn off the LOCK, first write 0xAA to the KEY field and UNLOCK address offset to the ADDR field in the UNLOCK register, followed by writing 0xA5AA5A55 to the UNLOCK register. • KEY: Unlock Key Write this bit field to 0xAA to enable unlock. • ADDR: Unlock Address Write the address offset of the register to unlock to this field. 31 30 29 28 27 26 25 24 KEY 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - ADDR[9:8] 76543210 ADDR[7:0] 275 32142D–06/2013 ATUC64/128/256L3/4U 14.6.8 Oscillator Control Register Name: OSCCTRLn Access Type: Read/Write Reset Value: 0x00000000 • OSCEN: Oscillator Enable 0: The oscillator is disabled. 1: The oscillator is enabled. • STARTUP: Oscillator Start-up Time Select start-up time for the oscillator. Please refer to the “Oscillator Startup Time” table in the SCIF Module Configuration section for details. • AGC: Automatic Gain Control For test purposes. • GAIN: Gain Selects the gain for the oscillator. Please refer to the “Oscillator Gain Settings” table in the SCIF Module Configuration section for details. • MODE: Oscillator Mode 0: External clock connected on XIN. XOUT can be used as general-purpose I/O (no crystal). 1: Crystal is connected to XIN/XOUT. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - OSCEN 15 14 13 12 11 10 9 8 - - - - STARTUP[3:0] 76543210 - - - - AGC GAIN[1:0] MODE 276 32142D–06/2013 ATUC64/128/256L3/4U 14.6.9 32KHz Oscillator Control Register Name: OSCCTRL32 Access Type: Read/Write Reset Value: 0x00000004 Note: This register is only reset by Power-On Reset • RESERVED This bit must always be written to zero. • STARTUP: Oscillator Start-up Time Select start-up time for 32 KHz oscillator 31 30 29 28 27 26 25 24 RESERVED ------- 23 22 21 20 19 18 17 16 - - - - - STARTUP[2:0] 15 14 13 12 11 10 9 8 - - - - - MODE[2:0] 76543210 - - - - EN1K EN32K PINSEL OSC32EN Table 14-3. Start-up Time for 32 KHz Oscillator STARTUP Number of RCSYS Clock Cycle Approximative Equivalent Time (RCOSC = 115 kHz) 00 0 1 128 1.1 ms 2 8192 72.3 ms 3 16384 143 ms 4 65536 570 ms 5 131072 1.1 s 6 262144 2.3 s 7 524288 4.6 s 277 32142D–06/2013 ATUC64/128/256L3/4U • MODE: Oscillator Mode • EN1K: 1 KHz output Enable 0: The 1 KHz output is disabled. 1: The 1 KHz output is enabled. • EN32K: 32 KHz output Enable 0: The 32 KHz output is disabled. 1: The 32 KHz output is enabled. • PINSEL: Pins Select 0: Default pins used. 1: Alternate pins: XIN32_2 pin is used instead of XIN32 pin, XOUT32_2 pin is used instead of XOUT32. • OSC32EN: 32 KHz Oscillator Enable 0: The 32 KHz Oscillator is disabled 1: The 32 KHz Oscillator is enabled Table 14-4. Operation Mode for 32 KHz Oscillator MODE Description 0 External clock connected to XIN32, XOUT32 can be used as general-purpose I/O (no crystal) 1 Crystal mode. Crystal is connected to XIN32/XOUT32. 2 Reserved 3 Reserved 4 Crystal and high current mode. Crystal is connected to XIN32/XOUT32. 5 Reserved 6 Reserved 7 Reserved 278 32142D–06/2013 ATUC64/128/256L3/4U 14.6.10 DFLLn Configuration Register Name: DFLLnCONF Access Type: Read/Write Reset Value: 0x00000000 • COARSE: Coarse Calibration Value Set the value of the coarse calibration register. If in closed loop mode, this field is Read-only. • FINE: FINE Calibration Value Set the value of the fine calibration register. If in closed loop mode, this field is Read-only. • QLEN: Quick Lock Enable 0: Quick Lock is disabled. 1: Quick Lock is enabled. • CCEN: Chill Cycle Enable 0: Chill Cycle is disabled. 1: Chill Cycle is enabled. • LLAW: Lose Lock After Wake 0: Locks will not be lost after waking up from sleep modes. 1: Locks will be lost after waking up from sleep modes where the DFLL clock has been stopped. • DITHER: Enable Dithering 0: The fine LSB input to the VCO is constant. 1: The fine LSB input to the VCO is dithered to achieve sub-LSB approximation to the correct multiplication ratio. • MODE: Mode Selection 0: The DFLL is in open loop operation. 1: The DFLL is in closed loop operation. • EN: Enable 0: The DFLL is disabled. 1: The DFLL is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 COARSE[7:0] 23 22 21 20 19 18 17 16 - - - - - - - FINE[8] 15 14 13 12 11 10 9 8 FINE[7:0] 76543210 - QLEN CCEN - LLAW DITHER MODE EN 279 32142D–06/2013 ATUC64/128/256L3/4U 14.6.11 DFLLn Multiplier Register Name: DFLLnMUL Access Type: Read/Write Reset Value: 0x00000000 • IMUL: Integer Multiply Factor This field, together with FMUL, determines the ratio between fDFLL and fREFthe DFLL. IMUL is the integer part, while the FMUL is the fractional part. In open loop mode, writing to this register has no effect. • FMUL: Fractional Multiply Factor This field, together with IMUL, determines the ratio between fDFLL and fREFthe DFLL. IMUL is the integer part, while the FMUL is the fractional part. In open loop mode, writing to this register has no effect. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 IMUL[15:8] 23 22 21 20 19 18 17 16 IMUL[7:0] 15 14 13 12 11 10 9 8 FMUL[15:8] 76543210 FMUL[7:0] 280 32142D–06/2013 ATUC64/128/256L3/4U 14.6.12 DFLLn Maximum Step Register Name: DFLLnSTEP Access Type: Read/Write Reset Value: 0x00000000 • FSTEP: Fine Maximum Step This indicates the maximum step size during fine adjustment in closed-loop mode. When adjusting to a new frequency, the expected overshoot of that frequency depends on this step size. • CSTEP: Coarse Maximum Step This indicates the maximum step size during coarse adjustment in closed-loop mode. When adjusting to a new frequency, the expected overshoot of that frequency depends on this step size. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 - - - - - - - FSTEP[8] 23 22 21 20 19 18 17 16 FSTEP[7:0] 15 14 13 12 11 10 9 8 -------- 76543210 CSTEP[7:0] 281 32142D–06/2013 ATUC64/128/256L3/4U 14.6.13 DFLLn Spread Spectrum Generator Control Register Name: DFLLnSSG Access Type: Read/Write Reset Value: 0x00000000 • STEPSIZE: SSG Step Size Sets the step size of the spread spectrum. • AMPLITUDE: SSG Amplitude Sets the amplitude of the spread spectrum. • PRBS: Pseudo Random Bit Sequence 0: Each spread spectrum frequency is applied at constant intervals 1: Each spread spectrum frequency is applied at pseudo-random intervals • EN: Enable 0: SSG is disabled. 1: SSG is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 - ------- 23 22 21 20 19 18 17 16 - - - STEPSIZE[4:0] 15 14 13 12 11 10 9 8 - - - AMPLITUDE[4:0] 76543210 - - - - - - PRBS EN 282 32142D–06/2013 ATUC64/128/256L3/4U 14.6.14 DFLLn Ratio Register Name: DFLLnRATIO Access Type: Read-only Reset Value: 0x00000000 • RATIODIFF: Multiplication Ratio Difference In closed-loop mode, this field indicates the error in the ratio between the VCO frequency and the target frequency. • NUMREF: Numerical Reference The number of reference clock cycles used to measure the VCO frequency equals 2^NUMREF. 31 30 29 28 27 26 25 24 RATIODIFF[15:8] 23 22 21 20 19 18 17 16 RATIODIFF[7:0] 15 14 13 12 11 10 9 8 - ------- 76543210 - - - NUMREF[4:0] 283 32142D–06/2013 ATUC64/128/256L3/4U 14.6.15 DFLLn Synchronization Register Name: DFLLnSYNC Access Type: Write-only Reset Value: 0x00000000 • SYNC: Synchronization To be able to read the current value of DFLLnCONF or DFLLnRATIO in closed-loop mode, this bit should be written to one. The updated value is available in DFLLnCONF and DFLLnRATIO when PCLKSR.DFLLnRDY is set. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - SYNC 284 32142D–06/2013 ATUC64/128/256L3/4U 14.6.16 BOD Control Register Name: BOD Access Type: Read/Write Reset Value: - • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. This bit is cleared after any reset except for a BOD reset, and during flash calibration. • FCD: Fuse Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will be redone after any reset except for a BOD reset. This bit is cleared after any reset, except for a BOD reset. This bit is set when the CTRL, HYST and LEVEL fields have been updated by the flash fuses after a reset. • CTRL: BOD Control • HYST: BOD Hysteresis 0: No hysteresis. 1: Hysteresis on. • LEVEL: BOD Level This field sets the triggering threshold of the BOD. See Electrical Characteristics for actual voltage levels. Note that any change to the LEVEL field of the BOD register should be done with the BOD deactivated to avoid spurious reset or interrupt. 31 30 29 28 27 26 25 24 SFV - - - - - - - 23 22 21 20 19 18 17 16 - - - - - - - FCD 15 14 13 12 11 10 9 8 - - - - - - CTRL 76543210 - HYST LEVEL Table 14-5. Operation Mode for BOD CTRL Description 0 BOD is disabled. 1 BOD is enabled and can reset the device. An interrupt request will be generated, if enabled in the IMR register. 2 BOD is enabled but cannot reset the device. An interrupt request will be generated, if enabled in the IMR register. 3 Reserved. 285 32142D–06/2013 ATUC64/128/256L3/4U Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 286 32142D–06/2013 ATUC64/128/256L3/4U 14.6.17 Voltage Regulator Calibration Register Name: VREGCR Access Type: Read/Write Reset Value: - • SFV: Store Final Value 0: The register is read/write. 1: The register is read-only, to protect against further accidental writes. This bit is cleared by a Power-on Reset. • INTPD: Internal Pull-down This bit is used for test purposes only. 0: The voltage regulator output is not pulled to ground. 1: The voltage regulator output has a pull-down to ground. • POR18VALUE: Power-on Reset 1.8V Output Value 0: VDDCORE voltage is below the POR18 power-on threshold level. 1: VDDCORE voltage is above the POR18 power-on threshold level. This bit is read-only. Writing to this bit has no effect. • POR33VALUE: Power-on Reset 3.3V Output Value 0: Internal regulator supply voltage is below the POR33 power-on threshold level. 1: Internal regulator supply voltage is above the POR33 power-on threshold level. This bit is read-only. Writing to this bit has no effect. • POR18MASK: Power-on Reset 1.8V Output Mask 0: Power-on Reset is not masked. 1: Power-on Reset is masked. • POR18STATUS: Power-on Reset 1.8V Status 0: Power-on Reset is disabled. 1: Power-on Reset is enabled. This bit is read-only. Writing to this bit has no effect. • POR18EN: Power-on Reset 1.8V Enable Writing a zero to this bit disables the POR18 detector. Writing a one to this bit enables the POR18 detector. • POR33MASK: Power-on Reset 3.3V Output Mask 0: Power-on Reset 3.3V is not masked. 31 30 29 28 27 26 25 24 SFV INTPD - - - DBG- POR18VALUE POR33VALUE 23 22 21 20 19 18 17 16 POR18MASK POR18STAT US POR18EN POR33MASK POR33STAT US POR33EN DEEPDIS FCD 15 14 13 12 11 10 9 8 - - - - CALIB 76543210 ON VREGOK EN - - SELVDD 287 32142D–06/2013 ATUC64/128/256L3/4U 1: Power-on Reset 3.3V is masked. • POR33STATUS: Power-on Reset 3.3V Status 0: Power-on Reset is disabled. 1: Power-on Reset is enabled. This bit is read-only. Writing to this bit has no effect. • POR33EN: Power-on Reset 3.3V Enable 0: Writing a zero to this bit disables the POR33 detector. 1: Writing a one to this bit enables the POR33 detector. • DEEPDIS: Disable Regulator Deep Mode 0: Regulator will enter deep mode in low-power sleep modes for lower power consumption. 1: Regulator will stay in full-power mode in all sleep modes for shorter start-up time. • FCD: Flash Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will only be redone after a Power-on Reset. This bit is cleared after a Power-on Reset. This bit is set when the CALIB field has been updated by flash calibration after a reset. • CALIB: Calibration Value Calibration value for Voltage Regulator. This is calibrated during production and should not be changed. • ON: Voltage Regulator On Status 0: The voltage regulator is currently disabled. 1: The voltage regulator is currently enabled. This bit is read-only. Writing to this bit has no effect. • VREGOK: Voltage Regulator OK Status 0: The voltage regulator is disabled or has not yet reached a stable output voltage. 1: The voltage regulator has reached the output voltage threshold level after being enabled. This bit is read-only. Writing to this bit has no effect. • EN: Enable 0: The voltage regulator is disabled. 1: The voltage regulator is enabled. Note: This bit is set after a Power-on Reset (POR). • SELVDD: Select VDD Output voltage of the Voltage Regulator. The default value of this bit corresponds to an output voltage of 1.8V. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 288 32142D–06/2013 ATUC64/128/256L3/4U 14.6.18 System RC Oscillator Calibration Register Name: RCCR Access Type: Read/Write Reset Value: - • FCD: Flash Calibration Done 0: The flash calibration will be redone after any reset. 1: The flash calibration will only be redone after a Power-on Reset. This bit is cleared after a POR. This bit is set when the CALIB field has been updated by the flash fuses after a reset. • CALIB: Calibration Value Calibration Value for the System RC oscillator (RCSYS). Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - FCD 15 14 13 12 11 10 9 8 - - - - - - CALIB[9:8] 76543210 CALIB[7:0] 289 32142D–06/2013 ATUC64/128/256L3/4U 14.6.19 Supply Monitor 33 Calibration Register Name: SM33 Access Type: Read/Write Reset Value: - • SAMPFREQ: Sampling Frequency Selects the sampling mode frequency of the 3.3V supply monitor. In sampling mode, the SM33 performs a measurement every 2(SAMPFREQ+5) cycles of the internal 32kHz RC oscillator. • ONSM: Supply Monitor On Indicator 0: The supply monitor is disabled. 1: The supply monitor is enabled. This bit is read-only. Writing to this bit has no effect. • SFV: Store Final Value 0: The register is read/write 1: The register is read-only, to protect against further accidental writes. This bit is cleared after a reset. • FCD: Flash Calibration Done This bit is cleared after a reset. This bit is set when CALIB field has been updated after a reset. • CALIB: Calibration Value Calibration Value for the SM33. • FS: Force Sampling Mode 0: Sampling mode is enabled in DeepStop and Static mode only. 1: Sampling mode is always enabled. • CTRL: Supply Monitor Control 31 30 29 28 27 26 25 24 - - - - SAMPFREQ 23 22 21 20 19 18 17 16 - - - - - ONSM SFV FCD 15 14 13 12 11 10 9 8 - - - - CALIB 76543210 FS - - - CTRL 290 32142D–06/2013 ATUC64/128/256L3/4U Selects the operating mode for the SM33. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. Table 14-6. Operation Mode for SM33 CTRL Description 0 SM33 is disabled. 1 SM33 is enabled and can reset the device. An interrupt request will be generated if the corresponding interrupt is enabled in the IMR register. 2 SM33 is enabled and cannot reset the device. An interrupt request will be generated if the corresponding interrupt is enabled in the IMR register. 3 SM33 is disabled 4-7 Reserved 291 32142D–06/2013 ATUC64/128/256L3/4U 14.6.20 Temperature Sensor Configuration Register Name: TSENS Access Type: Read/Write Reset Value: 0x00000000 • EN: Temperature Sensor Enable 0: The Temperature Sensor is disabled. 1: The Temperature Sensor is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - EN 292 32142D–06/2013 ATUC64/128/256L3/4U 14.6.21 120MHz RC Oscillator Configuration Register Name: RC120MCR Access Type: Read/Write Reset Value: 0x00000000 • EN: RC120M Enable 0: The 120 MHz RC oscillator is disabled. 1: The 120 MHz RC oscillator is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - EN 293 32142D–06/2013 ATUC64/128/256L3/4U 14.6.22 Backup Register n Name: BRn Access Type: Read/Write Reset Value: 0x00000000 This is a set of general-purpose read/write registers. Data stored in these registers is retained when the device is in Shutdown. Before writing to these registers the user must ensure that PCLKSR.BRIFARDY is not set. Note that this registers are protected by a lock. To write to these registers the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 294 32142D–06/2013 ATUC64/128/256L3/4U 14.6.23 32kHz RC Oscillator Configuration Register Name: RC32KCR Access Type: Read/Write Reset Value: 0x00000000 • EN: RC32K Enable 0: The 32 kHz RC oscillator is disabled. 1: The 32 kHz RC oscillator is enabled. Note that this register is protected by a lock. To write to this register the UNLOCK register has to be written first. Please refer to the UNLOCK register description for details. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - EN 295 32142D–06/2013 ATUC64/128/256L3/4U 14.6.24 Generic Clock Control Name: GCCTRL Access Type: Read/Write Reset Value: 0x00000000 There is one GCCTRL register per generic clock in the design. • DIV: Division Factor The number of DIV bits for each generic clock is as shown in the “Generic Clock number of DIV bits” table in the SCIF Module Configuration section. • OSCSEL: Oscillator Select Selects the source clock for the generic clock. Please refer to the “Generic Clock Sources” table in the SCIF Module Configuration section. • DIVEN: Divide Enable 0: The generic clock equals the undivided source clock. 1: The generic clock equals the source clock divided by 2*(DIV+1). • CEN: Clock Enable 0: The generic clock is disabled. 1: The generic clock is enabled. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 - - - OSCSEL[4:0] 76543210 - - - - - - DIVEN CEN 296 32142D–06/2013 ATUC64/128/256L3/4U 14.6.25 PLL Control Register Name: PLLn Access Type: Read/Write Reset Value: 0x00000000 • PLLCOUNT: PLL Count Specifies the number of RCSYS clock cycles before ISR.PLLLOCKn will be set after PLLn has been written, or after PLLn has been automatically re-enabled after exiting a sleep mode. • PLLMUL: PLL Multiply Factor • PLLDIV: PLL Division Factor These fields determine the ratio of the PLL output frequency to the source oscillator frequency: fvco = (PLLMUL+1)/PLLDIV • fREF if PLLDIV >0 fvco = 2•(PLLMUL+1) • fREF if PLLDIV = 0 Note that the PLLMUL field should always be greater than 1 or the behavior of the PLL will be undefined. • PLLOPT: PLL Option PLLOPT[0]: Selects the VCO frequency range (fvco). 0: 80MHz1 1 1 0 0 BaudRate SelectedClock   8 2  – OVER CD = ----------------------------------------------- 438 32142D–06/2013 ATUC64/128/256L3/4U The baud rate is calculated with the following formula (OVER=0): The baud rate error is calculated with the following formula. It is not recommended to work with an error higher than 5%. 20.6.1.3 Fractional Baud Rate in Asynchronous Mode The baud rate generator has a limitation: the source frequency is always a multiple of the baud rate. An approach to this problem is to integrate a high resolution fractional N clock generator, outputting fractional multiples of the reference source clock. This fractional part is selected with the Fractional Part field (BRGR.FP), and is activated by giving it a non-zero value. The resolution is one eighth of CD. The resulting baud rate is calculated using the following formula: The modified architecture is presented below: Table 20-3. Baud Rate Example (OVER=0) Source Clock (Hz) Expected Baud Rate (bit/s) Calculation Result CD Actual Baud Rate (bit/s) Error 3 686 400 38 400 6.00 6 38 400.00 0.00% 4 915 200 38 400 8.00 8 38 400.00 0.00% 5 000 000 38 400 8.14 8 39 062.50 1.70% 7 372 800 38 400 12.00 12 38 400.00 0.00% 8 000 000 38 400 13.02 13 38 461.54 0.16% 12 000 000 38 400 19.53 20 37 500.00 2.40% 12 288 000 38 400 20.00 20 38 400.00 0.00% 14 318 180 38 400 23.30 23 38 908.10 1.31% 14 745 600 38 400 24.00 24 38 400.00 0.00% 18 432 000 38 400 30.00 30 38 400.00 0.00% 24 000 000 38 400 39.06 39 38 461.54 0.16% 24 576 000 38 400 40.00 40 38 400.00 0.00% 25 000 000 38 400 40.69 40 38 109.76 0.76% 32 000 000 38 400 52.08 52 38 461.54 0.16% 32 768 000 38 400 53.33 53 38 641.51 0.63% 33 000 000 38 400 53.71 54 38 194.44 0.54% 40 000 000 38 400 65.10 65 38 461.54 0.16% 50 000 000 38 400 81.38 81 38 580.25 0.47% 60 000 000 38 400 97.66 98 38 265.31 0.35% BaudRate CLKUSART =      CD  16 Error 1 ExpectedBaudRate ActualBaudRate --------------------------------------------------     = – BaudRate SelectedClock 8 2  – OVER CD FP 8 + -------         = -------------------------------------------------------------------- 439 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-3. Fractional Baud Rate Generator 20.6.1.4 Baud Rate in Synchronous and SPI Mode If the USART is configured to operate in synchronous mode, the selected clock is divided by the BRGR.CD field. This does not apply when CLK is selected. When CLK is selected the external frequency must be at least 4.5 times lower than the system clock, and when either CLK or CLK_USART/DIV are selected, CD must be even to ensure a 50/50 duty cycle. If CLK_USART is selected, the generator ensures this regardless of value. 20.6.2 Receiver and Transmitter Control After a reset, the transceiver is disabled. The receiver/transmitter is enabled by writing a one to either the Receiver Enable, or Transmitter Enable bit in the Control Register (CR.RXEN, or CR.TXEN). They may be enabled together and can be configured both before and after they have been enabled. The user can reset the USART receiver/transmitter at any time by writing a one to either the Reset Receiver (CR.RSTRX), or Reset Transmitter (CR.RSTTX) bit. This software reset clears status bits and resets internal state machines, immediately halting any communication. The user interface configuration registers will retain their values. The user can disable the receiver/transmitter by writing a one to either the Receiver Disable, or Transmitter Disable bit (CR.RXDIS, or CR.TXDIS). If the receiver is disabled during a character reception, the USART will wait for the current character to be received before disabling. If the transmitter is disabled during transmission, the USART will wait until both the current character and the character stored in the Transmitter Holding Register (THR) are transmitted before disabling. If a timeguard has been implemented it will remain functional during the transaction. USCLKS CD Modulus Control FP FP CD glitch-free logic 16-bit Counter OVER FIDI SYNC Sampling Divider CLK_USART CLK_USART/DIV Reserved CLK CLK BaudRate Clock Sampling Clock SYNC USCLKS = 3 >1 1 2 3 0 0 1 0 1 1 0 0 BaudRate SelectedClock CD = ------------------------------------- 440 32142D–06/2013 ATUC64/128/256L3/4U 20.6.3 Synchronous and Asynchronous Modes 20.6.3.1 Transmitter Operations The transmitter performs equally in both synchronous and asynchronous operating modes (MR.SYNC). One start bit, up to 9 data bits, an optional parity bit, and up to two stop bits are successively shifted out on the TXD pin at each falling edge of the serial clock. The number of data bits is selected by the Character Length field (MR.CHRL) and the MR.MODE9 bit. Nine bits are selected by writing a one to MODE9, overriding any value in CHRL. The parity bit configuration is selected in the MR.PAR field. The Most Significant Bit First bit (MR.MSBF) selects which data bit to send first. The number of stop bits is selected by the MR.NBSTOP field. The 1.5 stop bit configuration is only supported in asynchronous mode. Figure 20-4. Character Transmit The characters are sent by writing to the Character to be Transmitted field (THR.TXCHR). The transmitter reports status with the Transmitter Ready (TXRDY) and Transmitter Empty (TXEMPTY) bits in the Channel Status Register (CSR). TXRDY is set when THR is empty. TXEMPTY is set when both THR and the transmit shift register are empty (transmission complete). Both TXRDY and TXEMPTY are cleared when the transmitter is disabled. Writing a character to THR while TXRDY is zero has no effect and the written character will be lost. Figure 20-5. Transmitter Status 20.6.3.2 Asynchronous Receiver If the USART is configured in an asynchronous operating mode (MR.SYNC = 0), the receiver will oversample the RXD input line by either 8 or 16 times the baud rate clock, as selected by the Oversampling Mode bit (MR.OVER). If the line is zero for half a bit period (four or eight consecutive samples, respectively), a start bit will be assumed, and the following 8th or 16th sample will determine the logical value on the line, in effect resulting in bit values being determined at the middle of the bit period. D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Example: 8-bit, Parity Enabled One Stop Baud Rate Clock D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Start Bit Write THR D0 D1 D2 D3 D4 D5 D6 D7 Parity Bit Stop Bit TXRDY TXEMPTY 441 32142D–06/2013 ATUC64/128/256L3/4U The number of data bits, endianess, parity mode, and stop bits are selected by the same bits and fields as for the transmitter (MR.CHRL, MODE9, MSBF, PAR, and NBSTOP). The synchronization mechanism will only consider one stop bit, regardless of the used protocol, and when the first stop bit has been sampled, the receiver will automatically begin looking for a new start bit, enabling resynchronization even if there is a protocol miss-match. Figure 20-6 and Figure 20-7 illustrate start bit detection and character reception in asynchronous mode. Figure 20-6. Asynchronous Start Bit Detection Figure 20-7. Asynchronous Character Reception 20.6.3.3 Synchronous Receiver In synchronous mode (SYNC=1), the receiver samples the RXD signal on each rising edge of the Baud Rate Clock. If a low level is detected, it is considered as a start bit. Configuration bits and fields are the same as in asynchronous mode. Sampling Clock (x16) RXD Start Detection Sampling Baud Rate Clock RXD Start Rejection Sampling 12345678 12345670 1234 12345678 9 10 11 12 13 14 15 16 D0 Sampling D0 D1 D2 D3 D4 D5 D6 D7 RXD Parity Bit Stop Bit Example: 8-bit, Parity Enabled Baud Rate Clock Start Detection 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 16 samples 442 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-8. Synchronous Mode Character Reception 20.6.3.4 Receiver Operations When a character reception is completed, it is transferred to the Received Character field in the Receive Holding Register (RHR.RXCHR), and the Receiver Ready bit in the Channel Status Register (CSR.RXRDY) is set. If RXRDY is already set, RHR will be overwritten and the Overrun Error bit (CSR.OVRE) is set. Reading RHR will clear RXRDY, and writing a one to the Reset Status bit in the Control Register (CR.RSTSTA) will clear OVRE. Figure 20-9. Receiver Status 20.6.3.5 Parity The USART supports five parity modes selected by MR.PAR. The PAR field also enables the Multidrop mode, see ”Multidrop Mode” on page 443. If even parity is selected, the parity bit will be a zero if there is an even number of ones in the data character, and if there is an odd number it will be a one. For odd parity the reverse applies. If space or mark parity is chosen, the parity bit will always be a zero or one, respectively. See Table 20-4. D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Sampling Parity Bit Stop Bit Example: 8-bit, Parity Enabled 1 Stop Baud Rate Clock D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR RXRDY OVRE D0 D1 D2 D3 D4 D5 D6 D7 Start Bit Parity Bit Stop Bit RSTSTA = 1 Read RHR Table 20-4. Parity Bit Examples Alphanum Character Hex Bin Parity Mode Odd Even Mark Space None A 0x41 0100 0001 1 0 1 0 - V 0x56 0101 0110 1 0 1 0 - R 0x52 0101 0010 0 1 1 0 - 443 32142D–06/2013 ATUC64/128/256L3/4U The receiver will report parity errors in CSR.PARE, unless parity is disabled. Writing a one to CR.RSTSTA will clear PARE. See Figure 20-10 Figure 20-10. Parity Error 20.6.3.6 Multidrop Mode If PAR is either 0x6 or 0x7, the USART runs in Multidrop mode. This mode differentiates data and address characters. Data has the parity bit zero and addresses have a one. By writing a one to the Send Address bit (CR.SENDA) the user will cause the next character written to THR to be transmitted as an address. Receiving a character with a one as parity bit will set PARE. 20.6.3.7 Transmitter Timeguard The timeguard feature enables the USART to interface slow devices by inserting an idle state on the TXD line in between two characters. This idle state corresponds to a long stop bit, whose duration is selected by the Timeguard Value field in the Transmitter Timeguard Register (TTGR.TG). The transmitter will hold the TXD line high for TG bit periods, in addition to the number of stop bits. As illustrated in Figure 20-11, the behavior of TXRDY and TXEMPTY is modified when TG has a non-zero value. If a pending character has been written to THR, the TXRDY bit will not be set until this characters start bit has been sent. TXEMPTY will remain low until the timeguard transmission has completed. Figure 20-11. Timeguard Operation D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Bad Parity Bit Stop Bit Baud Rate Clock Write CR PARE RXRDY RSTSTA = 1 D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Start Bit TG = 4 Write THR D0 D1 D2 D3 D4 D5 D6 D7 Parity Bit Stop Bit TXRDY TXEMPTY TG = 4 444 32142D–06/2013 ATUC64/128/256L3/4U Table 20-5. Maximum Baud Rate Dependent Timeguard Durations 20.6.3.8 Receiver Time-out The Time-out Value field in the Receiver Time-out Register (RTOR.TO) enables handling of variable-length frames by detection of selectable idle durations on the RXD line. The value written to TO is loaded to a decremental counter, and unless it is zero, a time-out will occur when the amount of inactive bit periods match the initial counter value. If a time-out has not occurred, the counter will reload and restart every time a new character arrives. A time-out sets the TIMEOUT bit in CSR. Clearing TIMEOUT can be done in two ways: • Writing a one to the Start Time-out bit (CR.STTTO). This also aborts count down until the next character has been received. • Writing a one to the Reload and Start Time-out bit (CR.RETTO). This also reloads the counter and restarts count down immediately. Figure 20-12. Receiver Time-out Block Diagram Table 20-6. Maximum Time-out Period Baud Rate (bit/sec) Bit time (µs) Timeguard (ms) 1 200 833 212.50 9 600 104 26.56 14400 69.4 17.71 19200 52.1 13.28 28800 34.7 8.85 33400 29.9 7.63 56000 17.9 4.55 57600 17.4 4.43 115200 8.7 2.21 Baud Rate (bit/sec) Bit Time (µs) Time-out (ms) 600 1 667 109 225 1 200 833 54 613 2 400 417 27 306 4 800 208 13 653 16-bit Time-out Counter 0 TO TIMEOUT Baud Rate Clock = Character Received RETTO Load Clock 16-bit Value STTTO 1 D Q Clear 445 32142D–06/2013 ATUC64/128/256L3/4U 20.6.3.9 Framing Error The receiver is capable of detecting framing errors. A framing error has occurred if a stop bit reads as zero. This can occur if the transmitter and receiver are not synchronized. A framing error is reported by CSR.FRAME as soon as the error is detected, at the middle of the stop bit. Figure 20-13. Framing Error Status 20.6.3.10 Transmit Break When TXRDY is set, the user can request the transmitter to generate a break condition on the TXD line by writing a one to The Start Break bit (CR.STTBRK). The break is treated as a normal 0x00 character transmission, clearing TXRDY and TXEMPTY, but with zeroes for preambles, start, parity, stop, and time guard bits. Writing a one to the Stop Break bit (CR.STBRK) will stop the generation of new break characters, and send ones for TG duration or at least 12 bit periods, ensuring that the receiver detects end of break, before resuming normal operation. Figure 20-14 illustrates STTBRK and STPBRK effect on the TXD line. Writing to STTBRK and STPBRK simultaneously can lead to unpredictable results. Writes to THR before a pending break has started will be ignored. 9 600 104 6 827 14400 69 4 551 19200 52 3 413 28800 35 2 276 33400 30 1 962 56000 18 1 170 57600 17 1 138 200000 5 328 Baud Rate (bit/sec) Bit Time (µs) Time-out (ms) D0 D1 D2 D3 D4 D5 D6 D7 RXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR FRAME RXRDY RSTSTA = 1 446 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-14. Break Transmission 20.6.3.11 Receive Break A break condition is assumed when incoming data, parity, and stop bits are zero. This corresponds to a framing error, but FRAME will remain zero while the Break Received/End Of Break bit (CSR.RXBRK) is set. Writing a one to CR.RSTSTA will clear RXBRK. An end of break will also set RXBRK, and is assumed when TX is high for at least 2/16 of a bit period in asynchronous mode, or when a high level is sampled in synchronous mode. 20.6.3.12 Hardware Handshaking The USART features an out-of-band hardware handshaking flow control mechanism, implementable by connecting the RTS and CTS pins with the remote device, as shown in Figure 20- 15. Figure 20-15. Connection with a Remote Device for Hardware Handshaking Writing 0x2 to the MR.MODE field configures the USART to operate in this mode. The receiver will drive its RTS pin high when disabled or when the Reception Buffer Full bit (CSR.RXBUFF) is set by the Buffer Full signal from the Peripheral DMA controller. If the receivers RTS pin is high, the transmitters CTS pin will also be high and only the active character transactions will be completed. Allocating a new buffer to the DMA controller by clearing RXBUFF, will drive the RTS pin low, allowing the transmitter to resume transmission. Detected level changes on the CTS pin can trigger interrupts, and are reported by the CTS Input Change bit in the Channel Status Register (CSR.CTSIC). Figure 20-16 illustrates receiver functionality, and Figure 20-17 illustrates transmitter functionality. D0 D1 D2 D3 D4 D5 D6 D7 TXD Start Bit Parity Bit Stop Bit Baud Rate Clock Write CR TXRDY TXEMPTY STTBRK = 1 STPBRK = 1 Break Transmission End of Break USART TXD CTS Remote Device RXD RXD TXD RTS RTS CTS 447 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-16. Receiver Behavior when Operating with Hardware Handshaking Figure 20-17. Transmitter Behavior when Operating with Hardware Handshaking Figure 20-18. 20.6.4 SPI Mode The USART features a Serial Peripheral Interface (SPI) link compliant mode, supporting synchronous, full-duplex communication, in both master and slave mode. Writing 0xE (master) or 0xF (slave) to MR.MODE will enable this mode. A SPI in master mode controls the data flow to and from the other SPI devices, who are in slave mode. It is possible to let devices take turns being masters (aka multi-master protocol), and one master may shift data simultaneously into several slaves, but only one slave may respond at a time. A slave is selected when its slave select (NSS) signal has been raised by the master. The USART can only generate one NSS signal, and it is possible to use standard I/O lines to address more than one slave. 20.6.4.1 Modes of Operation The SPI system consists of two data lines and two control lines: • Master Out Slave In (MOSI): This line supplies the data shifted from master to slave. In master mode this is connected to TXD, and in slave mode to RXD. • Master In Slave Out (MISO): This line supplies the data shifted from slave to master. In master mode this is connected to RXD, and in slave mode to TXD. • Serial Clock (CLK): This is controlled by the master. One period per bit transmission. In both modes this is connected to CLK. • Slave Select (NSS): This control line allows the master to select or deselect a slave. In master mode this is connected to RTS, and in slave mode to CTS. Changing SPI mode after initial configuration has to be followed by a transceiver software reset in order to avoid unpredictable behavior. 20.6.4.2 Baud Rate The baud rate generator operates as described in ”Baud Rate in Synchronous and SPI Mode” on page 439, with the following requirements: In SPI Master Mode: RTS RXBUFF Write CR RXEN = 1 RXD RXDIS = 1 CTS TXD 448 32142D–06/2013 ATUC64/128/256L3/4U • The Clock Selection field (MR.USCLKS) must not equal 0x3 (external clock, CLK). • The Clock Output Select bit (MR.CLKO) must be one. • The BRGR.CD field must be at least 0x4. • If USCLKS is one (internal divided clock, CLK_USART/DIV), the value in CD has to be even, ensuring a 50:50 duty cycle. CD can be odd if USCLKS is zero (internal clock, CLK_USART). In SPI Slave Mode: • CLK frequency must be at least four times lower than the system clock. 20.6.4.3 Data Transfer • Up to nine data bits are successively shifted out on the TXD pin at each edge. There are no start, parity, or stop bits, and MSB is always sent first. The SPI Clock Polarity (MR.CPOL), and SPI Clock Phase (MR.CPHA) bits configure CLK by selecting the edges upon which bits are shifted and sampled, resulting in four non-interoperable protocol modes see Table 20-7. A master/slave pair must use the same configuration, and the master must be reconfigured if it is to communicate with slaves using different configurations. See Figures 20-19 and 20-20. Figure 20-19. SPI Transfer Format (CPHA=1, 8 bits per transfer) Table 20-7. SPI Bus Protocol Modes SPI Bus Protocol Mode CPOL CPHA 0 01 1 00 2 11 3 10 CLK cycle (for reference) CLK (CPOL= 1) MOSI SPI Master ->TXD SPI Slave ->RXD MISO SPI Master ->RXD SPI Slave ->TXD NSS SPI Master ->RTS SPI Slave ->CTS MSB MSB 1 CLK (CPOL= 0) 3 5 6 7 8 4 3 2 1 LSB 6 6 5 5 4 3 2 1 LSB 2 4 449 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-20. SPI Transfer Format (CPHA=0, 8 bits per transfer) 20.6.4.4 Receiver and Transmitter Control See ”Transmitter Operations” on page 440, and ”Receiver Operations” on page 442. 20.6.4.5 Character Transmission and Reception In SPI master mode, the slave select line (NSS) is asserted low one bit period before the start of transmission, and released high one bit period after every character transmission. A delay for at least three bit periods is always inserted in between characters. In order to address slave devices supporting the Chip Select Active After Transfer (CSAAT) mode, NSS can be forced low by writing a one to the Force SPI Chip Select bit (CR.RTSEN/FCS). Releasing NSS when FCS is one, is only possible by writing a one to the Release SPI Chip Select bit (CR.RTSDIS/RCS). In SPI slave mode, a low level on NSS for at least one bit period will allow the slave to initiate a transmission or reception. The Underrun Error bit (CSR.UNRE) is set if a character must be sent while THR is empty, and TXD will be high during character transmission, as if 0xFF was being sent. If a new character is written to THR it will be sent correctly during the next transmission slot. Writing a one to CR.RSTSTA will clear UNRE. To ensure correct behavior of the receiver in SPI slave mode, the master device sending the frame must ensure a minimum delay of one bit period in between each character transmission. 20.6.4.6 Receiver Time-out Receiver Time-out’s are not possible in SPI mode as the baud rate clock is only active during data transfers. 20.6.5 LIN Mode The USART features a LIN (Local Interconnect Network) 1.3 and 2.0 compliant mode, embedding full error checking and reporting, automatic frame processing with up to 256 data bytes, CLK cycle (for reference) CLK (CPOL= 0) CLK (CPOL= 1) MOSI SPI Master -> TXD SPI Slave -> RXD MISO SPI Master -> RXD SPI Slave -> TXD NSS SPI Master -> RTS SPI Slave -> CTS MSB 6 5 MSB 6 5 4 4 3 3 2 2 1 1 LSB LSB 1 2 3 4 5 6 7 8 450 32142D–06/2013 ATUC64/128/256L3/4U customizable response data lengths, and requires minimal CPU resources. Writing 0xA (master) or 0xB (slave) to MR.MODE enables this mode. 20.6.5.1 Modes of operation Changing LIN mode after initial configuration has to be followed by a transceiver software reset in order to avoid unpredictable behavior. 20.6.5.2 Receiver and Transmitter Control See Section “20.6.2” on page 439. 20.6.5.3 Baud Rate Configuration The LIN nodes baud rate is configured in the Baud Rate Generator Register (BRGR), See Section “20.6.1.1” on page 437. 20.6.5.4 Character Transmission and Reception See ”Transmitter Operations” on page 440, and ”Receiver Operations” on page 442. 20.6.5.5 Header Transmission (Master Node Configuration) All LIN frames start with a header sent by the master. As soon as the identifier has been written to the Identifier Character field in the LIN Identifier Register (LINIR.IDCHR), TXRDY is cleared and the header is sent. The header consists of a Break, Sync, and Identifier field. TXRDY is set when the identifier has been transferred into the transmitters shift register. The Break field consists of 13 dominant bits, the break, and one recessive bit, the break delimiter. The Sync field is the character 0x55. The Identifier field contains the Identifier as written to IDCHR. The identifier parity bits can be generated automatically (see Section 20.6.5.8). Figure 20-21. Header Transmission 20.6.5.6 Header Reception (Slave Node Configuration) The USART stays idle until it detects a break field, consisting of at least 11 consecutive dominant bits (zeroes) on the bus. A received break will set the Lin Break bit (CSR.LINBK). The Sync field is used to synchronize the baud rate (see Section 20.6.5.7). IDCHR is updated and the LIN Identifier bit (CSR.LINID) is set when the Identifier has been received. The Identifier parity bits can be automatically checked (see Section 20.6.5.8). Writing a one to RSTSTA will clear LINBK and LINID. TXD Baud Rate Clock Start Bit Write LINIR 10101010 TXRDY Stop Bit Start Bit Break Field ID0 ID1 ID2 ID3 ID4 ID5 ID6 ID7 13 dominant bits (at 0) Stop Bit Break Delimiter 1 recessive bit (at 1) Synch Byte = 0x55 LINIR ID 451 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-22. Header Reception 20.6.5.7 Slave Node Synchronization Synchronization is only done by the slave. If the Sync field is not 0x55, an Inconsistent Sync Field error (CSR.LINISFE) is generated. The time between falling edges is measured by a 19-bit counter, driven by the sampling clock (see Section 20.6.1). Figure 20-23. Sync Field The counter starts when the Sync field start bit is detected, and continues for eight bit periods. The 16 most significant bits (counter value divided by 8) becomes the new clock divider (BRGR.CD), and the three least significant bits (the remainder) becomes the new fractional part (BRGR.FP). Figure 20-24. Slave Node Synchronization The synchronization accuracy depends on: • The theoretical slave node clock frequency; nominal clock frequency (FNom) • The baud rate Break Field 13 dominant bits (at 0) Break Delimiter 1 recessive bit (at 1) Start Bit 10101010 Stop Bit Start Bit ID0 ID1 ID2 ID4 ID3 ID6 ID5 ID7 Stop Bit Synch Byte = 0x55 Baud Rate Clock RXD Write US_CR With RSTSTA=1 US_LINIR LINID Start bit Stop bit Synch Field 8 Tbit 2 Tbit 2 Tbit 2 Tbit 2 Tbit RXD Baud Rate Clock LINIDRX Synchro Counter 000_0011_0001_0110_1101 BRGR Clcok Divider (CD) 0000_0110_0010_1101 BRGR Fractional Part (FP) 101 Initial CD Initial FP Reset Start Bit 10101010 Stop Bit Start Bit Break Field ID0 ID1 ID2 ID3 ID4 ID5 ID6 ID7 13 dominant bits (at 0) Stop Bit Break Delimiter 1 recessive bit (at 1) Synch Byte = 0x55 452 32142D–06/2013 ATUC64/128/256L3/4U • The oversampling mode (OVER=0 => 16x, or OVER=1 => 8x) The following formula is used to calculate synchronization deviation, where FSLAVE is the real slave node clock frequency, and FTOL_UNSYNC is the difference between FNom and FSLAVE According to the LIN specification, FTOL_UNSYNCH may not exceed ±15%, and the bit rates between two nodes must be within ±2% of each other, resulting in a maximal BaudRate_deviation of ±1%. Minimum nominal clock frequency with a fractional part: Examples: • Baud rate = 20 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 2.64 MHz • Baud rate = 20 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 1.47 MHz • Baud rate = 1 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 132 kHz • Baud rate = 1 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 74 kHz If the fractional part is not used, the synchronization accuracy is much lower. The 16 most significant bits, added with the first least significant bit, becomes the new clock divider (CD). The equation of the baud rate deviation is the same as above, but the constants are: Minimum nominal clock frequency without a fractional part: Examples: • Baud rate = 20 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 19.12 MHz • Baud rate = 20 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 9.71 MHz • Baud rate = 1 kbit/s, OVER=0 (Oversampling 16x) => FNom(min) = 956 kHz • Baud rate = 1 kbit/s, OVER=1 (Oversampling 8x) => FNom(min) = 485 kHz 20.6.5.8 Identifier Parity An identifier field consists of two sub-fields; the identifier and its parity. Bits 0 to 5 are assigned to the identifier, while bits 6 and 7 are assigned to parity. Automatic parity management is disabled by writing a one to the Parity Disable bit in the LIN Mode register (LINMR.PARDIS). BaudRate_deviation 100   8 2 OVER    – +   BaudRate 8 FSLAVE   --------------------------------------------------------------------------------------------------   =   % BaudRate_deviation 100   8 2 OVER    – +   BaudRate 8 FTOL_UNSYNC 100 -----------------------------------     xFNom   --------------------------------------------------------------------------------------------------       = % –0.5    +0.5 -1    +1 FNom  min 100   0.5 8 2 OVER     – + 1  BaudRate 8 –15 100 --------- + 1       1%  ------------------------------------------------------------------------------------------------------       = Hz –4    +4 -1    +1 FNom  min 100   4 8 2 OVER     – + 1  Baudrate 8 –15 100 --------- + 1       1%  -----------------------------------------------------------------------------------------------       = Hz 453 32142D–06/2013 ATUC64/128/256L3/4U • PARDIS=0: During header transmission, the parity bits are computed and in the shift register they replace bits six and seven from IDCHR. During header reception, the parity bits are checked and can generate a LIN Identifier Parity Error (see Section 20.6.6). Bits six and seven in IDCHR read as zero when receiving. • PARDIS=1: During header transmission, all the bits in IDCHR are sent on the bus. During header reception, all the bits in IDCHR are updated with the received Identifier. 20.6.5.9 Node Action After an identifier transaction, a LIN response mode has to be selected. This is done in the Node Action field (LINMR.NACT). Below are some response modes exemplified in a small LIN cluster: • Response, from master to slave1: Master: NACT=PUBLISH Slave1: NACT=SUBSCRIBE Slave2: NACT=IGNORE • Response, from slave1 to master: Master: NACT=SUBSCRIBE Slave1: NACT=PUBLISH Slave2: NACT=IGNORE • Response, from slave1 to slave2: Master: NACT=IGNORE Slave1: NACT=PUBLISH Slave2: NACT=SUBSCRIBE 20.6.5.10 LIN Response Data Length The response data length is the number of data fields (bytes), excluding the checksum. Figure 20-25. Response Data Length The response data length can be configured, either by the user, or automatically by bits 4 and 5 in the Identifier (IDCHR), in accordance to LIN 1.1. The user selects mode by writing to the Data Length Mode bit (LINMR.DML): • DLM=0: the response data length is configured by the user by writing to the 8-bit Data Length Control field (LINMR.DLC). The response data length equals DLC + 1 bytes. User configuration: 1 - 256 data fields (DLC+1) Identifier configuration: 2/4/8 data fields Sync Break Sync Field Identifier Field Checksum Field Data Field Data Field Data Field Data Field 454 32142D–06/2013 ATUC64/128/256L3/4U • DLM=1: the response data length is defined by the Identifier bits according to the table below. 20.6.5.11 Checksum The last frame field is the checksum. It is configured by the Checksum Type (LINMR.CHKTYP), and the Checksum Disable (LINMR.CHKDIS) bits. TXRDY will not be set after the last THR data write if enabled. Writing a one to CHKDIS will disable the automatic checksum generation/checking, and the user may send/check this last byte manually, disguised as a normal data. The checksum is an inverted 8-bit sum with carry, either: • over all data bytes, called a classic checksum. This is used for LIN 1.3 compliant slaves, and automatically managed when CHKDIS=0, and CHKTYP=1. • over all data bytes and the protected identifier, called an enhanced checksum. This is used for LIN 2.0 compliant slaves, and automatically managed when CHKDIS=0, and CHKTYP=0. 20.6.5.12 Frame Slot Mode A LIN master can be configured to use frame slots with a pre-defined minimum length. Writing a one to the Frame Slot Mode Disable bit (LINMR.FSDIS) disables this mode. This mode will not allow TXRDY to be set after a frame transfer until the entire frame slot duration has elapsed, in effect preventing the master from sending a new header. The LIN Transfer Complete bit (CSR.LINTC) will still be set after the checksum has been sent. Writing a one to CR.RSTST clears LINTC. Figure 20-26. Frame Slot Mode with Automatic Checksum The minimum frame slot size is determined by TFrame_Maximum, and calculated below (all values in bit periods): • THeader_Nominal = 34 Table 20-8. Response Data Length if DLM = 1 IDCHR[5] IDCHR[4] Response Data Length [bytes] 00 2 01 2 10 4 11 8 Break Synch Protected Identifier Data N Checksum Header Interframe space Response space Frame Frame slot = TFrame_Maximum Response TXRDY Write THR Write LINID Data 1 Data 2 Data 3 Data3 Data N-1 Data N Frame Slot Mode Disabled Frame Slot Mode Enabled LINTC Data 1 455 32142D–06/2013 ATUC64/128/256L3/4U • TFrame_Maximum = 1.4 x (THeader_Nominal + TResponse_Nominal + 1)(Note:) Note: The term “+1” leads to an integer result for TFrame_Max (LIN Specification 1.3) If the Checksum is sent (CHKDIS=0): • TResponse_Nominal = 10 x (NData + 1) • TFrame_Maximum = 1.4 x (34 + 10 x (DLC + 1 + 1) + 1) • TFrame_Maximum = 77 + 14 x DLC If the Checksum is not sent (CHKDIS=1): • TResponse_Nominal = 10 x NData • TFrame_Maximum = 1.4 x (34 + 10 x (DLC + 1) + 1) • TFrame_Maximum = 63 + 14 x DLC 20.6.6 LIN Errors These error bits are cleared by writing a one to CSR.RSTSTA. 20.6.6.1 Slave Not Responding Error (CSR.LINSNRE) This error is generated if no valid message appears within the TFrame_Maximum time frame slot, while the USART is expecting a response from another node (NACT=SUBSCRIBE). 20.6.6.2 Checksum Error (CSR.LINCE) This error is generated if the received checksum is wrong. This error can only be generated if the checksum feature is enabled (CHKDIS=0). 20.6.6.3 Identifier Parity Error (CSR.LINIPE) This error is generated if the identifier parity is wrong. This error can only be generated if parity is enabled (PARDIS=0). 20.6.6.4 Inconsistent Sync Field Error (CSR.LINISFE) This error is generated in slave mode if the Sync Field character received is not 0x55. Synchronization procedure is aborted. 20.6.6.5 Bit Error (CSR.LINBE) This error is generated if the value transmitted by the USART on Tx differs from the value sampled on Rx. If a bit error is detected, the transmission is aborted at the next byte border. 20.6.7 LIN Frame Handling 20.6.7.1 Master Node Configuration • Write a one to CR.TXEN and CR.RXEN to enable both transmitter and receiver • Select LIN mode and master node by writing to MR.MODE • Configure the baud rate by writing to CD and FP in BRGR • Configure the frame transfer by writing to NACT, PARDIS, CHKDIS, CHKTYPE, DLCM, FSDIS, and DLC in LINMR • Check that CSR.TXRDY is one • Send the header by writing to LINIR.IDCHR The following procedure depends on the NACT setting: 456 32142D–06/2013 ATUC64/128/256L3/4U • Case 1: NACT=PUBLISH, the USART sends a response – Wait until TXRDY is a one – Send a byte by writing to THR.TXCHR – Repeat the two previous steps until there is no more data to send – Wait until CSR.LINTC is a one – Check for LIN errors • Case 2: NACT=SUBSCRIBE, the USART receives a response – Wait until RXRDY is a one – Read RHR.RXCHR – Repeat the two previous steps until there is no more data to read – Wait until LINTC is a one – Check for LIN errors • Case 3: NACT=IGNORE, the USART is not concerned by a response – Wait until LINTC is a one – Check for LIN errors Figure 20-27. Master Node Configuration, NACT=PUBLISH Frame Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Write THR Write LINIR Data 1 Data 2 Data 3 Data N-1 Data N RXRDY Header Interframe space Response space Frame slot = TFrame_Maximum Data3 Response LINTC FSDIS=1 FSDIS=0 457 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-28. Master Node Configuration, NACT=SUBSCRIBE Figure 20-29. Master Node Configuration, NACT=IGNORE 20.6.7.2 Slave Node Configuration This is identical to the master node configuration above, except for: • LIN mode selected in MR.MODE is slave • When the baud rate is configured, wait until CSR.LINID is a one, then; • Check for LINISFE and LINPE errors, clear errors and LINIDby writing a one to RSTSTA • Read IDCHR • Configure the frame transfer by writing to NACT, PARDIS, CHKDIS, CHKTYPE, DLCM, and DLC in LINMR IMPORTANT: if NACT=PUBLISH, and this field is already correct, the LINMR register must still be written with this value in order to set TXRDY, and to request the corresponding Peripheral DMA Controller write transfer. The different NACT settings result in the same procedure as for the master node, see page 455. Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Read RHR Write LINIR Data 1 Data N-1 Data N-1 RXRDY Data N-2 Data N Header Interframe Response space space Frame Frame slot = TFrame_Maximum Data3 Response LINTC FSDIS=1 FSDIS=0 TXRDY Write LINIR RXRDY LINTC Break Synch Protected Identifier Data 1 Data N-1 Data N Checksum Header Interframe Response space space Frame Frame slot = TFrame_Maximum Data3 Response FSDIS=1 FSDIS=0 458 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-30. Slave Node Configuration, NACT=PUBLISH Figure 20-31. Slave Node Configuration, NACT=SUBSCRIBE Figure 20-32. Slave Node Configuration, NACT=IGNORE 20.6.8 LIN Frame Handling With The Peripheral DMA Controller The USART can be used together with the Peripheral DMA Controller in order to transfer data without processor intervention. The DMA Controller uses the TXRDY and RXRDY bits, to trigger one byte writes or reads. It always writes to THR, and it always reads RHR. Break Synch Protected Identifier Data 1 Data N Checksum TXRDY Write THR Read LINID Data 1 Data 3 Data N-1 Data N RXRDY LINIDRX Data 2 LINTC TXRDY Read RHR Read LINID RXRDY LINIDRX LINTC Break Synch Protected Identifier Data 1 Data N Checksum Data 1 Data N-1 Data N-2 Data N-1 Data N TXRDY Read RHR Read LINID RXRDY LINIDRX LINTC Break Synch Protected Identifier Data 1 Data N Checksum Data N-1 459 32142D–06/2013 ATUC64/128/256L3/4U 20.6.8.1 Master Node Configuration The Peripheral DMA Controller Mode bit (LINMR.PDCM) allows the user to select configuration: • PDCM=0: LIN configuration must be written to LINMR, it is not stored in the write buffer. • PDCM=1: LIN configuration is written by the DMA Controller to THR, and is stored in the write buffer. Since data transfer size is a byte, the transfer is split into two accesses. The first writes the NACT, PARDIS, CHKDIS, CHKTYP, DLM and FSDIS bits, while the second writes the DLC field. If NACT=PUBLISH, the write buffer will also contain the Identifier. When NACT=SUBSCRIBE, the read buffer contains the data. Figure 20-33. Master Node with Peripheral DMA Controller (PDCM=0) Figure 20-34. Master Node with Peripheral DMA Controller (PDCM=1) | | | | RXRDY TXRDY Peripheral bus USART LIN CONTROLLER DATA 0 DATA N | | | | READ BUFFER NODE ACTION = PUBLISH NODE ACTION = SUBSCRIBE Peripheral DMA Controller RXRDY Peripheral bus DATA 0 DATA 1 DATA N WRITE BUFFER Peripheral DMA Controller USART LIN CONTROLLER | | | | | | | | NACT PARDIS CHKDIS CHKTYP DLM FSDIS DLC IDENTIFIER DATA 0 DATA N WRITE BUFFER RXRDY Peripheral bus DLC IDENTIFIER DATA 0 DATA N WRITE BUFFER RXRDY READ BUFFER NODE ACTION = PUBLISH NODE ACTION = SUBSCRIBE Peripheral DMA Controller Peripheral DMA Controller USART LIN CONTROLLER NACT PARDIS CHKDIS CHKTYP DLM FSDIS USART LIN CONTROLLER TXRDY Peripheral bus 460 32142D–06/2013 ATUC64/128/256L3/4U 20.6.8.2 Slave Node Configuration In this mode, the Peripheral DMA Controller transfers only data. The user reads the Identifier from LINIR, and selects LIN mode by writing to LINMR. When NACT=PUBLISH the data is in the write buffer, while the read buffer contains the data when NACT=SUBSCRIBE. IMPORTANT: if in slave mode, NACT is already configured correctly as PUBLISH, the LINMR register must still be written with this value in order to set TXRDY, and to request the corresponding Peripheral DMA Controller write transfer. Figure 20-35. Slave Node with Peripheral DMA Controller 20.6.9 Wake-up Request Any node in a sleeping LIN cluster may request a wake-up. By writing to the Wakeup Signal Type bit (LINMR.WKUPTYP), the user can choose to send either a LIN 1.3 (WKUPTYP=1), or a LIN 2.0 (WKUPTYP=0) compliant wakeup request. Writing a one to the Send LIN Wakeup Signal bit (CR.LINWKUP), transmits a wakeup, and when completed sets LINTC. According to LIN 1.3, the wakeup request should be generated with the character 0x80 in order to impose eight successive dominant bits. According to LIN 2.0, the wakeup request is issued by forcing the bus into the dominant state for 250µs to 5ms. Sending the character 0xF0 does this, regardless of baud rate. • Baud rate max = 20 kbit/s -> one bit period = 50µs -> five bit periods = 250µs • Baud rate min = 1 kbit/s -> one bit period = 1ms -> five bit periods = 5ms 20.6.10 Bus Idle Time-out LIN bus inactivity should eventually cause slaves to time-out and enter sleep mode. LIN 1.3 specifies this to 25000 bit periods, whilst LIN 2.0 specifies 4seconds. For the time-out counter operation see Section 20.6.3.8 ”Receiver Time-out” on page 444. | | | | | | | | DATA 0 DATA N RXRDY Peripheral Bus READ BUFFER NACT = SUBSCRIBE DATA 0 DATA N TXRDY Peripheral bus WRITE BUFFER USART LIN CONTROLLER USART LIN CONTROLLER Peripheral DMA Controller Peripheral DMA Controller Table 20-9. Receiver Time-out Values (RTOR.TO) LIN Specification Baud Rate Time-out period TO 2.0 1 000 bit/s 4s 4 000 2 400 bit/s 9 600 9 600 bit/s 38 400 19 200 bit/s 76 800 20 000 bit/s 80 000 1.3 - 25 000 bit periods 25 000 461 32142D–06/2013 ATUC64/128/256L3/4U 20.6.11 Test Modes The internal loopback feature enables on-board diagnostics, and allows the USART to operate in three different test modes, with reconfigured pin functionality, as shown below. 20.6.11.1 Normal Mode During normal operation, a receivers RXD pin is connected to a transmitters TXD pin. Figure 20-36. Normal Mode Configuration 20.6.11.2 Automatic Echo Mode Automatic echo mode allows bit-by-bit retransmission. When a bit is received on the RXD pin, it is also sent to the TXD pin, as shown in Figure 20-37. Transmitter configuration has no effect. Figure 20-37. Automatic Echo Mode Configuration 20.6.11.3 Local Loopback Mode Local loopback mode connects the output of the transmitter directly to the input of the receiver, as shown in Figure 20-38. The TXD and RXD pins are not used. The RXD pin has no effect on the receiver and the TXD pin is continuously driven high, as in idle state. Figure 20-38. Local Loopback Mode Configuration 20.6.11.4 Remote Loopback Mode Remote loopback mode connects the RXD pin to the TXD pin, as shown in Figure 20-39. The transmitter and the receiver are disabled and have no effect. This mode allows bit-by-bit retransmission. Receiver Transmitter RXD TXD Receiver Transmitter RXD TXD Receiver Transmitter RXD TXD 1 462 32142D–06/2013 ATUC64/128/256L3/4U Figure 20-39. Remote Loopback Mode Configuration 20.6.12 Write Protection Registers To prevent single software errors from corrupting USART behavior, certain address spaces can be write-protected by writing the correct Write Protect KEY and a one to the Write Protect Enable bit in the Write Protect Mode Register (WPMR.WPKEY, and WPMR.WPEN). Disabling the write protection is done by writing the correct key, and a zero to WPEN. Write attempts to a write protected register are detected and the Write Protect Violation Status bit in the Write Protect Status Register (WPSR.WPVS) is set, while the Write Protect Violation Source field (WPSR.WPVSRC) indicates the targeted register. Writing the correct key to the Write Protect KEY bit (WPMR.WPKEY) clears WPVSRC and WPVS. The protected registers are: • ”Mode Register” on page 466 • ”Baud Rate Generator Register” on page 476 • ”Receiver Time-out Register” on page 477 • ”Transmitter Timeguard Register” on page 478 Receiver Transmitter RXD TXD 1 463 32142D–06/2013 ATUC64/128/256L3/4U 20.7 User Interface Note: 1. Values in the Version Register vary with the version of the IP block implementation. Table 20-10. USART Register Memory Map Offset Register Name Access Reset 0x0000 Control Register CR Write-only 0x00000000 0x0004 Mode Register MR Read-write 0x00000000 0x0008 Interrupt Enable Register IER Write-only 0x00000000 0x000C Interrupt Disable Register IDR Write-only 0x00000000 0x0010 Interrupt Mask Register IMR Read-only 0x00000000 0x0014 Channel Status Register CSR Read-only 0x00000000 0x0018 Receiver Holding Register RHR Read-only 0x00000000 0x001C Transmitter Holding Register THR Write-only 0x00000000 0x0020 Baud Rate Generator Register BRGR Read-write 0x00000000 0x0024 Receiver Time-out Register RTOR Read-write 0x00000000 0x0028 Transmitter Timeguard Register TTGR Read-write 0x00000000 0x0054 LIN Mode Register LINMR Read-write 0x00000000 0x0058 LIN Identifier Register LINIR Read-write 0x00000000 0x00E4 Write Protect Mode Register WPMR Read-write 0x00000000 0x00E8 Write Protect Status Register WPSR Read-only 0x00000000 0x00FC Version Register VERSION Read-only 0x–(1) 464 32142D–06/2013 ATUC64/128/256L3/4U 20.7.1 Control Register Name: CR Access Type: Write-only Offset: 0x0 Reset Value: 0x00000000 • LINWKUP: Send LIN Wakeup Signal Writing a zero to this bit has no effect. Writing a one to this bit will sends a wakeup signal on the LIN bus. • LINABT: Abort LIN Transmission Writing a zero to this bit has no effect. Writing a one to this bit will abort the current LIN transmission. • RTSDIS/RCS: Request to Send Disable/Release SPI Chip Select Writing a zero to this bit has no effect. Writing a one to this bit when USART is not in SPI master mode drives RTS pin high. Writing a one to this bit when USART is in SPI master mode releases NSS (RTS pin). • RTSEN/FCS: Request to Send Enable/Force SPI Chip Select Writing a zero to this bit has no effect. Writing a one to this bit when USART is not in SPI master mode drives RTS low. Writing a one to this bit when USART is in SPI master mode when; FCS=0: has no effect. FCS=1: forces NSS (RTS pin) low, even if USART is not transmitting, in order to address SPI slave devices supporting the CSAAT Mode (Chip Select Active After Transfer). • RETTO: Rearm Time-out Writing a zero to this bit has no effect. Writing a one to this bit reloads the time-out counter and clears CSR.TIMEOUT. • RSTNACK: Reset Non Acknowledge Writing a zero to this bit has no effect. Writing a one to this bit clears CSR.NACK. • SENDA: Send Address Writing a zero to this bit has no effect. Writing a one to this bit will in multidrop mode send the next character written to THR as an address. • STTTO: Start Time-out Writing a zero to this bit has no effect. Writing a one to this bit will abort any current time-out count down, and trigger a new count down when the next character has been received. CSR.TIMEOUT is also cleared. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – LINWKUP LINABT RTSDIS/RCS RTSEN/FCS – – 15 14 13 12 11 10 9 8 RETTO RSTNACK – SENDA STTTO STPBRK STTBRK RSTSTA 76543210 TXDIS TXEN RXDIS RXEN RSTTX RSTRX – – 465 32142D–06/2013 ATUC64/128/256L3/4U • STPBRK: Stop Break Writing a zero to this bit has no effect. Writing a one to this bit will stop the generation of break signal characters, and then send ones for TTGR.TG duration, or at least 12 bit periods. No effect if no break is being transmitted. • STTBRK: Start Break Writing a zero to this bit has no effect. Writing a one to this bit will start transmission of break characters when current characters present in THR and the transmit shift register have been sent. No effect if a break signal is already being generated. • RSTSTA: Reset Status Bits Writing a zero to this bit has no effect. Writing a one to this bit will clear the following bits in CSR: PARE, FRAME, OVRE, LINBE, LINSFE, LINIPE, LINCE, LINSNRE, and RXBRK. • TXDIS: Transmitter Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the transmitter. • TXEN: Transmitter Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the transmitter if TXDIS is zero. • RXDIS: Receiver Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the receiver. • RXEN: Receiver Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the receiver if RXDIS is zero. • RSTTX: Reset Transmitter Writing a zero to this bit has no effect. Writing a one to this bit will reset the transmitter. • RSTRX: Reset Receiver Writing a zero to this bit has no effect. Writing a one to this bit will reset the receiver. 466 32142D–06/2013 ATUC64/128/256L3/4U 20.7.2 Mode Register Name: MR Access Type: Read-write Offset: 0x4 Reset Value: 0x00000000 This register can only be written if the WPEN bit is cleared in the Write Protect Mode Register. • INACK: Inhibit Non Acknowledge 0: The NACK is generated. 1: The NACK is not generated. • OVER: Oversampling Mode 0: Oversampling at 16 times the baud rate. 1: Oversampling at 8 times the baud rate. • CLKO: Clock Output Select 0: The USART does not drive the CLK pin. 1: The USART drives the CLK pin unless USCLKS selects the external clock. • MODE9: 9-bit Character Length 0: CHRL defines character length. 1: 9-bit character length. • MSBF/CPOL: Bit Order or SPI Clock Polarity If USART does not operate in SPI Mode: MSBF=0: Least Significant Bit is sent/received first. MSBF=1: Most Significant Bit is sent/received first. If USART operates in SPI Mode, CPOL is used with CPHA to produce the required clock/data relationship between devices. CPOL=0: The inactive state value of CLK is logic level zero. CPOL=1: The inactive state value of CLK is logic level one. 31 30 29 28 27 26 25 24 ––––– – 23 22 21 20 19 18 17 16 – – – INACK OVER CLKO MODE9 MSBF/CPOL 15 14 13 12 11 10 9 8 CHMODE NBSTOP PAR SYNC/CPHA 76543210 CHRL USCLKS MODE 467 32142D–06/2013 ATUC64/128/256L3/4U • CHMODE: Channel Mode • NBSTOP: Number of Stop Bits • PAR: Parity Type • SYNC/CPHA: Synchronous Mode Select or SPI Clock Phase If USART does not operate in SPI Mode (MODE is  0xE and 0xF): SYNC = 0: USART operates in Asynchronous Mode. SYNC = 1: USART operates in Synchronous Mode. If USART operates in SPI Mode, CPHA determines which edge of CLK causes data to change and which edge causes data to be captured. CPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. CPHA = 0: Data is changed on the leading edge of CLK and captured on the following edge of CLK. CPHA = 1: Data is captured on the leading edge of CLK and changed on the following edge of CLK. Table 20-11. CHMODE Mode Description 0 0 Normal Mode 0 1 Automatic Echo. Receiver input is connected to the TXD pin. 1 0 Local Loopback. Transmitter output is connected to the Receiver input. 1 1 Remote Loopback. RXD pin is internally connected to the TXD pin. Table 20-12. NBSTOP Asynchronous (SYNC=0) Synchronous (SYNC=1) 0 0 1 stop bit 1 stop bit 0 1 1.5 stop bits Reserved 1 0 2 stop bits 2 stop bits 1 1 Reserved Reserved Table 20-13. PAR Parity Type 0 0 0 Even parity 0 0 1 Odd parity 0 1 0 Parity forced to 0 (Space) 0 1 1 Parity forced to 1 (Mark) 1 0 x No parity 1 1 x Multidrop mode 468 32142D–06/2013 ATUC64/128/256L3/4U • CHRL: Character Length. • USCLKS: Clock Selection Note: 1. The value of DIV is device dependent. Please refer to the Module Configuration section at the end of this chapter. • MODE Table 20-14. CHRL Character Length 0 0 5 bits 0 1 6 bits 1 0 7 bits 1 1 8 bits Table 20-15. USCLKS Selected Clock 0 0 CLK_USART 0 1 CLK_USART/DIV(1) 1 0 Reserved 1 1 CLK Table 20-16. MODE Mode of the USART 0 0 0 0 Normal 0 0 1 0 Hardware Handshaking 1 0 1 0 LIN Master 1 0 1 1 LIN Slave 1 1 1 0 SPI Master 1 1 1 1 SPI Slave Others Reserved 469 32142D–06/2013 ATUC64/128/256L3/4U 20.7.3 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x8 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 470 32142D–06/2013 ATUC64/128/256L3/4U 20.7.4 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0xC Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 471 32142D–06/2013 ATUC64/128/256L3/4U 20.7.5 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 – – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 472 32142D–06/2013 ATUC64/128/256L3/4U 20.7.6 Channel Status Register Name: CSR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • LINSNRE: LIN Slave Not Responding Error 0: No LIN Slave Not Responding Error has been detected since the last RSTSTA. 1: A LIN Slave Not Responding Error has been detected since the last RSTSTA. • LINCE: LIN Checksum Error 0: No LIN Checksum Error has been detected since the last RSTSTA. 1: A LIN Checksum Error has been detected since the last RSTSTA. • LINIPE: LIN Identifier Parity Error 0: No LIN Identifier Parity Error has been detected since the last RSTSTA. 1: A LIN Identifier Parity Error has been detected since the last RSTSTA. • LINISFE: LIN Inconsistent Sync Field Error 0: No LIN Inconsistent Sync Field Error has been detected since the last RSTSTA 1: The USART is configured as a Slave node and a LIN Inconsistent Sync Field Error has been detected since the last RSTSTA. • LINBE: LIN Bit Error 0: No Bit Error has been detected since the last RSTSTA. 1: A Bit Error has been detected since the last RSTSTA. • CTS: Image of CTS Input 0: CTS is low. 1: CTS is high. • CTSIC: Clear to Send Input Change Flag 0: No change has been detected on the CTS pin since the last CSR read. 1: At least one change has been detected on the CTS pin since the last CSR read. • LINTC: LIN Transfer Completed 0: The USART is either idle or a LIN transfer is ongoing. 1: A LIN transfer has been completed since the last RSTSTA. • LINID: LIN Identifier 0: No LIN Identifier has been sent or received. 1: A LIN Identifier has been sent (master) or received (slave), since the last RSTSTA. • NACK: Non Acknowledge 0: No Non Acknowledge has been detected since the last RSTNACK. 1: At least one Non Acknowledge has been detected since the last RSTNACK. • RXBUFF: Reception Buffer Full 0: The Buffer Full signal from the Peripheral DMA Controller channel is inactive. 31 30 29 28 27 26 25 24 – – LINSNRE LINCE LINIPE LINISFE LINBE – 23 22 21 20 19 18 17 16 CTS – – – CTSIC – – – 15 14 13 12 11 10 9 8 LINTC LINID NACK/LINBK RXBUFF – ITER/UNRE TXEMPTY TIMEOUT 76543210 PARE FRAME OVRE – – RXBRK TXRDY RXRDY 473 32142D–06/2013 ATUC64/128/256L3/4U 1: The Buffer Full signal from the Peripheral DMA Controller channel is active. • ITER/UNRE: Max number of Repetitions Reached or SPI Underrun Error If USART does not operate in SPI Slave Mode: ITER=0: Maximum number of repetitions has not been reached since the last RSTSTA. ITER=1: Maximum number of repetitions has been reached since the last RSTSTA. If USART operates in SPI Slave Mode: UNRE=0: No SPI underrun error has occurred since the last RSTSTA. UNRE=1: At least one SPI underrun error has occurred since the last RSTSTA. • TXEMPTY: Transmitter Empty 0: The transmitter is either disabled or there are characters in THR, or in the transmit shift register. 1: There are no characters in neither THR, nor in the transmit shift register. • TIMEOUT: Receiver Time-out 0: There has not been a time-out since the last Start Time-out command (CR.STTTO), or RTOR.TO is zero. 1: There has been a time-out since the last Start Time-out command. • PARE: Parity Error 0: Either no parity error has been detected, or the parity bit is a zero in multidrop mode, since the last RSTSTA. 1: Either at least one parity error has been detected, or the parity bit is a one in multidrop mode, since the last RSTSTA. • FRAME: Framing Error 0: No stop bit has been found as low since the last RSTSTA. 1: At least one stop bit has been found as low since the last RSTSTA. • OVRE: Overrun Error 0: No overrun error has occurred since the last RSTSTA. 1: At least one overrun error has occurred since the last RSTSTA. • RXBRK: Break Received/End of Break 0: No Break received or End of Break detected since the last RSTSTA. 1: Break received or End of Break detected since the last RSTSTA. • TXRDY: Transmitter Ready 0: The transmitter is either disabled, or a character in THR is waiting to be transferred to the transmit shift register, or an STTBRK command has been requested. As soon as the transmitter is enabled, TXRDY becomes one. 1: There is no character in the THR. • RXRDY: Receiver Ready 0: The receiver is either disabled, or no complete character has been received since the last read of RHR. If characters were being received when the receiver was disabled, RXRDY changes to 1 when the receiver is enabled. 1: At least one complete character has been received and RHR has not yet been read. 474 32142D–06/2013 ATUC64/128/256L3/4U 20.7.7 Receiver Holding Register Name: RHR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • RXCHR: Received Character Last received character. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 – – – – – – – RXCHR[8] 76543210 RXCHR[7:0] 475 32142D–06/2013 ATUC64/128/256L3/4U 20.7.8 Transmitter Holding Register Name: THR Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 • TXCHR: Character to be Transmitted If TXRDY is zero this field contains the next character to be transmitted. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 – – – – – – – TXCHR[8] 76543210 TXCHR[7:0] 476 32142D–06/2013 ATUC64/128/256L3/4U 20.7.9 Baud Rate Generator Register Name: BRGR Access Type: Read-write Offset: 0x20 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • FP: Fractional Part 0: Fractional divider is disabled. 1 - 7: Baud rate resolution, defined by FP x 1/8. • CD: Clock Divider 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – FP 15 14 13 12 11 10 9 8 CD[15:8] 76543210 CD[7:0] Table 20-17. CD SYNC = 0 SYNC = 1 or MODE = SPI (Master or Slave) OVER = 0 OVER = 1 0 Baud Rate Clock Disabled 1 to 65535 Baud Rate = Selected Clock/16/CD Baud Rate = Selected Clock/8/CD Baud Rate = Selected Clock /CD 477 32142D–06/2013 ATUC64/128/256L3/4U 20.7.10 Receiver Time-out Register Name: RTOR Access Type: Read-write Offset: 0x24 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • TO: Time-out Value 0: The receiver Time-out is disabled. 1 - 131071: The receiver Time-out is enabled and the time-out delay is TO x bit period. Note that the size of the TO counter is device dependent, see the Module Configuration section. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – – – TO[16] 15 14 13 12 11 10 9 8 TO[15:8] 76543210 TO[7:0] 478 32142D–06/2013 ATUC64/128/256L3/4U 20.7.11 Transmitter Timeguard Register Name: TTGR Access Type: Read-write Offset: 0x28 Reset Value: 0x00000000 This register can only be written to if write protection is disabled, see ”Write Protect Mode Register” on page 482. • TG: Timeguard Value 0: The transmitter Timeguard is disabled. 1 - 255: The transmitter timeguard is enabled and the timeguard delay is TG x bit period. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 TG 479 32142D–06/2013 ATUC64/128/256L3/4U 20.7.12 LIN Mode Register Name: LINMR Access Type: Read-write Offset: 0x54 Reset Value: 0x00000000 • PDCM: Peripheral DMA Controller Mode 0: The LIN mode register is not written by the Peripheral DMA Controller. 1: The LIN mode register is, except for this bit, written by the Peripheral DMA Controller. • DLC: Data Length Control 0 - 255: If DLM=0 this field defines the response data length to DLC+1 bytes. • WKUPTYP: Wakeup Signal Type 0: Writing a one to CR.LINWKUP will send a LIN 2.0 wakeup signal. 1: Writing a one to CR.LINWKUP will send a LIN 1.3 wakeup signal. • FSDIS: Frame Slot Mode Disable 0: The Frame Slot mode is enabled. 1: The Frame Slot mode is disabled. • DLM: Data Length Mode 0: The response data length is defined by DLC. 1: The response data length is defined by bits 4 and 5 of the Identifier (LINIR.IDCHR). • CHKTYP: Checksum Type 0: LIN 2.0 “Enhanced” checksum 1: LIN 1.3 “Classic” checksum • CHKDIS: Checksum Disable 0: Checksum is automatically computed and sent when master, and checked when slave. 1: Checksum is not computed and sent, nor checked. • PARDIS: Parity Disable 0: Identifier parity is automatically computed and sent when master, and checked when slave. 1: Identifier parity is not computed and sent, nor checked. • NACT: LIN Node Action 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – – – – PDCM 15 14 13 12 11 10 9 8 DLC 76543210 WKUPTYP FSDIS DLM CHKTYP CHKDIS PARDIS NACT Table 20-18. NACT Mode Description 0 0 PUBLISH: The USART transmits the response. 480 32142D–06/2013 ATUC64/128/256L3/4U 0 1 SUBSCRIBE: The USART receives the response. 1 0 IGNORE: The USART does not transmit and does not receive the response. 1 1 Reserved Table 20-18. 481 32142D–06/2013 ATUC64/128/256L3/4U 20.7.13 LIN Identifier Register Name: LINIR Access Type: Read-write or Read-only Offset: 0x58 Reset Value: 0x00000000 • IDCHR: Identifier Character If USART is in LIN master mode, the IDCHR field is read-write, and its value is the Identifier character to be transmitted. If USART is in LIN slave mode, the IDCHR field is read-only, and its value is the last received Identifier character. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 –––––––– 15 14 13 12 11 10 9 8 –––––––– 76543210 IDCHR 482 32142D–06/2013 ATUC64/128/256L3/4U 20.7.14 Write Protect Mode Register Register Name: WPMR Access Type: Read-write Offset: 0xE4 Reset Value: See Table 20-10 • WPKEY: Write Protect KEY Has to be written to 0x555341 (“USA” in ASCII) in order to successfully write WPEN. Always reads as zero. • WPEN: Write Protect Enable 0 = Write protection disabled. 1 = Write protection enabled. Protects the registers: • ”Mode Register” on page 466 • ”Baud Rate Generator Register” on page 476 • ”Receiver Time-out Register” on page 477 • ”Transmitter Timeguard Register” on page 478 31 30 29 28 27 26 25 24 WPKEY[23:16] 23 22 21 20 19 18 17 16 WPKEY[15:8] 15 14 13 12 11 10 9 8 WPKEY[7:0] 76543210 — — — — — — — WPEN 483 32142D–06/2013 ATUC64/128/256L3/4U 20.7.15 Write Protect Status Register Register Name: WPSR Access Type: Read-only Offset: 0xE8 Reset Value: See Table 20-10 • WPVSRC: Write Protect Violation Source If WPVS=1 this field indicates which write-protected register was unsuccessfully written to, either by address offset or code. • WPVS: Write Protect Violation Status 0= No write protect violation has occurred since the last WPSR read. 1= A write protect violation has occurred since the last WPSR read. Note: Reading WPSR automatically clears all fields. 31 30 29 28 27 26 25 24 ———————— 23 22 21 20 19 18 17 16 WPVSRC[15:8] 15 14 13 12 11 10 9 8 WPVSRC[7:0] 76543210 — — — — — — — WPVS 484 32142D–06/2013 ATUC64/128/256L3/4U 20.7.16 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • MFN Reserved. No functionality associated. • VERSION Version of the module. No functionality associated. 31 30 29 28 27 26 25 24 –––––––– 23 22 21 20 19 18 17 16 – – – – MFN 15 14 13 12 11 10 9 8 – – – – VERSION[11:8] 76543210 VERSION[7:0] 485 32142D–06/2013 ATUC64/128/256L3/4U 20.8 Module Configuration The specific configuration for each USART instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 20-19. USART Configuration Feature USART0 USART1 USART2 USART3 Receiver Time-out Counter Size (Size of the RTOR.TO field) 17 bit 17 bit 17 bit 17 bit DIV Value for divided CLK_USART 8 8 8 8 Table 20-20. USART Clocks Module Name Clock Name Description USART0 CLK_USART0 Clock for the USART0 bus interface USART1 CLK_USART1 Clock for the USART1 bus interface USART2 CLK_USART2 Clock for the USART2 bus interface USART3 CLK_USART3 Clock for the USART3 bus interface Table 20-21. Register Reset Values Register Reset Value VERSION 0x00000440 486 32142D–06/2013 ATUC64/128/256L3/4U 21. Serial Peripheral Interface (SPI) Rev: 2.1.1.3 21.1 Features • Compatible with an embedded 32-bit microcontroller • Supports communication with serial external devices – Four chip selects with external decoder support allow communication with up to 15 peripherals – Serial memories, such as DataFlash and 3-wire EEPROMs – Serial peripherals, such as ADCs, DACs, LCD controllers, CAN controllers and Sensors – External co-processors • Master or Slave Serial Peripheral Bus Interface – 4 - to 16-bit programmable data length per chip select – Programmable phase and polarity per chip select – Programmable transfer delays between consecutive transfers and between clock and data per chip select – Programmable delay between consecutive transfers – Selectable mode fault detection • Connection to Peripheral DMA Controller channel capabilities optimizes data transfers – One channel for the receiver, one channel for the transmitter – Next buffer support – Four character FIFO in reception 21.2 Overview The Serial Peripheral Interface (SPI) circuit is a synchronous serial data link that provides communication with external devices in Master or Slave mode. It also enables communication between processors if an external processor is connected to the system. The Serial Peripheral Interface is essentially a shift register that serially transmits data bits to other SPIs. During a data transfer, one SPI system acts as the “master”' which controls the data flow, while the other devices act as “slaves'' which have data shifted into and out by the master. Different CPUs can take turn being masters (Multiple Master Protocol opposite to Single Master Protocol where one CPU is always the master while all of the others are always slaves) and one master may simultaneously shift data into multiple slaves. However, only one slave may drive its output to write data back to the master at any given time. A slave device is selected when the master asserts its NSS signal. If multiple slave devices exist, the master generates a separate slave select signal for each slave (NPCS). The SPI system consists of two data lines and two control lines: • Master Out Slave In (MOSI): this data line supplies the output data from the master shifted into the input(s) of the slave(s). • Master In Slave Out (MISO): this data line supplies the output data from a slave to the input of the master. There may be no more than one slave transmitting data during any particular transfer. • Serial Clock (SPCK): this control line is driven by the master and regulates the flow of the data bits. The master may transmit data at a variety of baud rates; the SPCK line cycles once for each bit that is transmitted. • Slave Select (NSS): this control line allows slaves to be turned on and off by hardware. 487 32142D–06/2013 ATUC64/128/256L3/4U 21.3 Block Diagram Figure 21-1. SPI Block Diagram 21.4 Application Block Diagram Figure 21-2. Application Block Diagram: Single Master/Multiple Slave Implementation Spi Interface Interrupt Control Peripheral DMA Controller I/O Controller CLK_SPI Peripheral Bus SPI Interrupt SPCK NPCS3 NPCS2 NPCS1 NPCS0/NSS MOSI MISO Slave 0 Slave 2 Slave 1 SPCK NPCS3 NPCS2 NPCS1 NPCS0 MOSI MISO Spi Master SPCK NSS MOSI MISO SPCK NSS MOSI MISO SPCK NSS MOSI MISO NC 488 32142D–06/2013 ATUC64/128/256L3/4U 21.5 I/O Lines Description 21.6 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 21.6.1 I/O Lines The pins used for interfacing the compliant external devices may be multiplexed with I/O lines. The user must first configure the I/O Controller to assign the SPI pins to their peripheral functions. 21.6.2 Clocks The clock for the SPI bus interface (CLK_SPI) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the SPI before disabling the clock, to avoid freezing the SPI in an undefined state. 21.6.3 Interrupts The SPI interrupt request line is connected to the interrupt controller. Using the SPI interrupt requires the interrupt controller to be programmed first. 21.7 Functional Description 21.7.1 Modes of Operation The SPI operates in master mode or in slave mode. Operation in master mode is configured by writing a one to the Master/Slave Mode bit in the Mode Register (MR.MSTR). The pins NPCS0 to NPCS3 are all configured as outputs, the SPCK pin is driven, the MISO line is wired on the receiver input and the MOSI line driven as an output by the transmitter. If the MR.MSTR bit is written to zero, the SPI operates in slave mode. The MISO line is driven by the transmitter output, the MOSI line is wired on the receiver input, the SPCK pin is driven by the transmitter to synchronize the receiver. The NPCS0 pin becomes an input, and is used as a Slave Select signal (NSS). The pins NPCS1 to NPCS3 are not driven and can be used for other purposes. The data transfers are identically programmable for both modes of operations. The baud rate generator is activated only in master mode. Table 21-1. I/O Lines Description Pin Name Pin Description Type Master Slave MISO Master In Slave Out Input Output MOSI Master Out Slave In Output Input SPCK Serial Clock Output Input NPCS1-NPCS3 Peripheral Chip Selects Output Unused NPCS0/NSS Peripheral Chip Select/Slave Select Output Input 489 32142D–06/2013 ATUC64/128/256L3/4U 21.7.2 Data Transfer Four combinations of polarity and phase are available for data transfers. The clock polarity is configured with the Clock Polarity bit in the Chip Select Registers (CSRn.CPOL). The clock phase is configured with the Clock Phase bit in the CSRn registers (CSRn.NCPHA). These two bits determine the edges of the clock signal on which data is driven and sampled. Each of the two bits has two possible states, resulting in four possible combinations that are incompatible with one another. Thus, a master/slave pair must use the same parameter pair values to communicate. If multiple slaves are used and fixed in different configurations, the master must reconfigure itself each time it needs to communicate with a different slave. Table 21-2 on page 489 shows the four modes and corresponding parameter settings. Figure 21-3 on page 489 and Figure 21-4 on page 490 show examples of data transfers. Figure 21-3. SPI Transfer Format (NCPHA = 1, 8 bits per transfer) Table 21-2. SPI modes SPI Mode CPOL NCPHA 0 01 1 00 2 11 3 10 SPCK cycle (for reference) 1 4 2 3 5 8 6 7 SPCK (CPOL = 0) NSS (to slave) MISO (from slave) MOSI (from master) SPCK (CPOL = 1) MSB 6 4 5 LSB 3 2 1 MSB 6 5 4 3 2 1 LSB *** *** Not Defined, but normaly MSB of previous character received 490 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-4. SPI Transfer Format (NCPHA = 0, 8 bits per transfer) 21.7.3 Master Mode Operations When configured in master mode, the SPI uses the internal programmable baud rate generator as clock source. It fully controls the data transfers to and from the slave(s) connected to the SPI bus. The SPI drives the chip select line to the slave and the serial clock signal (SPCK). The SPI features two holding registers, the Transmit Data Register (TDR) and the Receive Data Register (RDR), and a single Shift Register. The holding registers maintain the data flow at a constant rate. After enabling the SPI, a data transfer begins when the processor writes to the TDR register. The written data is immediately transferred in the Shift Register and transfer on the SPI bus starts. While the data in the Shift Register is shifted on the MOSI line, the MISO line is sampled and shifted in the Shift Register. Transmission cannot occur without reception. Before writing to the TDR, the Peripheral Chip Select field in TDR (TDR.PCS) must be written in order to select a slave. If new data is written to TDR during the transfer, it stays in it until the current transfer is completed. Then, the received data is transferred from the Shift Register to RDR, the data in TDR is loaded in the Shift Register and a new transfer starts. The transfer of a data written in TDR in the Shift Register is indicated by the Transmit Data Register Empty bit in the Status Register (SR.TDRE). When new data is written in TDR, this bit is cleared. The SR.TDRE bit is used to trigger the Transmit Peripheral DMA Controller channel. The end of transfer is indicated by the Transmission Registers Empty bit in the SR register (SR.TXEMPTY). If a transfer delay (CSRn.DLYBCT) is greater than zero for the last transfer, SR.TXEMPTY is set after the completion of said delay. The CLK_SPI can be switched off at this time. During reception, received data are transferred from the Shift Register to the reception FIFO. The FIFO can contain up to 4 characters (both Receive Data and Peripheral Chip Select fields). While a character of the FIFO is unread, the Receive Data Register Full bit in SR remains high (SR.RDRF). Characters are read through the RDR register. If the four characters stored in the FIFO are not read and if a new character is stored, this sets the Overrun Error Status bit in the SR register (SR.OVRES). The procedure to follow in such a case is described in Section 21.7.3.8. SPCK cycle (for reference) 1 4 2 3 5 8 6 7 SPCK (CPOL = 0) NSS (to slave) MISO (from slave) MOSI (from master) SPCK (CPOL = 1) MSB 6 4 5 LSB 3 2 1 6 5 4 3 2 1 LSB *** Not Defined, but normaly LSB of previous character transmitted *** MSB 491 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-5 on page 491shows a block diagram of the SPI when operating in master mode. Figure 21-6 on page 492 shows a flow chart describing how transfers are handled. 21.7.3.1 Master mode block diagram Figure 21-5. Master Mode Block Diagram Baud Rate Generator RXFIFOEN 4 – Character FIFO Shift Register TDRE RXFIFOEN 4 – Character FIFO PS PCSDEC Current Peripheral MODF MODFDIS MSTR SCBR CSR0..3 CSR0..3 CPOL NCPHA BITS RDR RD RDRF OVRES TD TDR RDR CSAAT CSNAAT CSR0..3 PCS MR PCS TDR SPCK CLK_SPI MISO MOSI LSB MSB NPCS1 NPCS2 NPCS3 NPCS0 SPI Clock 0 1 0 1 0 1 NPCS0 492 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.2 Master mode flow diagram Figure 21-6. Master Mode Flow Diagram SPI Enable CSAAT ? PS ? 1 0 0 1 1 NPCS = TDR(PCS) NPCS = MR(PCS) Delay DLYBS Serializer = TDR(TD) TDRE = 1 Data Transfer RDR(RD) = Serializer RDRF = 1 TDRE ? NPCS = 0xF Delay DLYBCS Fixed peripheral Variable peripheral Delay DLYBCT 0 1 CSAAT ? 0 TDRE ? 1 0 PS ? 0 1 TDR(PCS) = NPCS ? no yes MR(PCS) = NPCS ? no NPCS = 0xF Delay DLYBCS NPCS = TDR(PCS) NPCS = 0xF Delay DLYBCS NPCS = MR(PCS), TDR(PCS) Fixed peripheral Variable peripheral - NPCS defines the current Chip Select - CSAAT, DLYBS, DLYBCT refer to the fields of the Chip Select Register corresponding to the Current Chip Select - When NPCS is 0xF, CSAAT is 0. 493 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.3 Clock generation The SPI Baud rate clock is generated by dividing the CLK_SPI , by a value between 1 and 255. This allows a maximum operating baud rate at up to CLK_SPI and a minimum operating baud rate of CLK_SPI divided by 255. Writing the Serial Clock Baud Rate field in the CSRn registers (CSRn.SCBR) to zero is forbidden. Triggering a transfer while CSRn.SCBR is zero can lead to unpredictable results. At reset, CSRn.SCBR is zero and the user has to configure it at a valid value before performing the first transfer. The divisor can be defined independently for each chip select, as it has to be configured in the CSRn.SCBR field. This allows the SPI to automatically adapt the baud rate for each interfaced peripheral without reprogramming. 21.7.3.4 Transfer delays Figure 21-7 on page 493 shows a chip select transfer change and consecutive transfers on the same chip select. Three delays can be configured to modify the transfer waveforms: • The delay between chip selects, programmable only once for all the chip selects by writing to the Delay Between Chip Selects field in the MR register (MR.DLYBCS). Allows insertion of a delay between release of one chip select and before assertion of a new one. • The delay before SPCK, independently programmable for each chip select by writing the Delay Before SPCK field in the CSRn registers (CSRn.DLYBS). Allows the start of SPCK to be delayed after the chip select has been asserted. • The delay between consecutive transfers, independently programmable for each chip select by writing the Delay Between Consecutive Transfers field in the CSRn registers (CSRn.DLYBCT). Allows insertion of a delay between two transfers occurring on the same chip select These delays allow the SPI to be adapted to the interfaced peripherals and their speed and bus release time. Figure 21-7. Programmable Delays DLYBCS DLYBS DLYBCT DLYBCT Chip Select 1 Chip Select 2 SPCK 494 32142D–06/2013 ATUC64/128/256L3/4U 21.7.3.5 Peripheral selection The serial peripherals are selected through the assertion of the NPCS0 to NPCS3 signals. By default, all the NPCS signals are high before and after each transfer. The peripheral selection can be performed in two different ways: • Fixed Peripheral Select: SPI exchanges data with only one peripheral • Variable Peripheral Select: Data can be exchanged with more than one peripheral Fixed Peripheral Select is activated by writing a zero to the Peripheral Select bit in MR (MR.PS). In this case, the current peripheral is defined by the MR.PCS field and the TDR.PCS field has no effect. Variable Peripheral Select is activated by writing a one to the MR.PS bit . The TDR.PCS field is used to select the current peripheral. This means that the peripheral selection can be defined for each new data. The Fixed Peripheral Selection allows buffer transfers with a single peripheral. Using the Peripheral DMA Controller is an optimal means, as the size of the data transfer between the memory and the SPI is either 4 bits or 16 bits. However, changing the peripheral selection requires the Mode Register to be reprogrammed. The Variable Peripheral Selection allows buffer transfers with multiple peripherals without reprogramming the MR register. Data written to TDR is 32-bits wide and defines the real data to be transmitted and the peripheral it is destined to. Using the Peripheral DMA Controller in this mode requires 32-bit wide buffers, with the data in the LSBs and the PCS and LASTXFER fields in the MSBs, however the SPI still controls the number of bits (8 to16) to be transferred through MISO and MOSI lines with the CSRn registers. This is not the optimal means in term of memory size for the buffers, but it provides a very effective means to exchange data with several peripherals without any intervention of the processor. 21.7.3.6 Peripheral chip select decoding The user can configure the SPI to operate with up to 15 peripherals by decoding the four Chip Select lines, NPCS0 to NPCS3 with an external logic. This can be enabled by writing a one to the Chip Select Decode bit in the MR register (MR.PCSDEC). When operating without decoding, the SPI makes sure that in any case only one chip select line is activated, i.e. driven low at a time. If two bits are defined low in a PCS field, only the lowest numbered chip select is driven low. When operating with decoding, the SPI directly outputs the value defined by the PCS field of either the MR register or the TDR register (depending on PS). As the SPI sets a default value of 0xF on the chip select lines (i.e. all chip select lines at one) when not processing any transfer, only 15 peripherals can be decoded. The SPI has only four Chip Select Registers, not 15. As a result, when decoding is activated, each chip select defines the characteristics of up to four peripherals. As an example, the CRS0 register defines the characteristics of the externally decoded peripherals 0 to 3, corresponding to the PCS values 0x0 to 0x3. Thus, the user has to make sure to connect compatible peripherals on the decoded chip select lines 0 to 3, 4 to 7, 8 to 11 and 12 to 14. 21.7.3.7 Peripheral deselection When operating normally, as soon as the transfer of the last data written in TDR is completed, the NPCS lines all rise. This might lead to runtime error if the processor is too long in responding 495 32142D–06/2013 ATUC64/128/256L3/4U to an interrupt, and thus might lead to difficulties for interfacing with some serial peripherals requiring the chip select line to remain active during a full set of transfers. To facilitate interfacing with such devices, the CSRn registers can be configured with the Chip Select Active After Transfer bit written to one (CSRn.CSAAT) . This allows the chip select lines to remain in their current state (low = active) until transfer to another peripheral is required. When the CSRn.CSAAT bit is written to qero, the NPCS does not rise in all cases between two transfers on the same peripheral. During a transfer on a Chip Select, the SR.TDRE bit rises as soon as the content of the TDR is transferred into the internal shifter. When this bit is detected the TDR can be reloaded. If this reload occurs before the end of the current transfer and if the next transfer is performed on the same chip select as the current transfer, the Chip Select is not de-asserted between the two transfers. This might lead to difficulties for interfacing with some serial peripherals requiring the chip select to be de-asserted after each transfer. To facilitate interfacing with such devices, the CSRn registers can be configured with the Chip Select Not Active After Transfer bit (CSRn.CSNAAT) written to one. This allows to de-assert systematically the chip select lines during a time DLYBCS. (The value of the CSRn.CSNAAT bit is taken into account only if the CSRn.CSAAT bit is written to zero for the same Chip Select). Figure 21-8 on page 496 shows different peripheral deselection cases and the effect of the CSRn.CSAAT and CSRn.CSNAAT bits. 21.7.3.8 FIFO management A FIFO has been implemented in Reception FIFO (both in master and in slave mode), in order to be able to store up to 4 characters without causing an overrun error. If an attempt is made to store a fifth character, an overrun error rises. If such an event occurs, the FIFO must be flushed. There are two ways to Flush the FIFO: • By performing four read accesses of the RDR (the data read must be ignored) • By writing a one to the Flush Fifo Command bit in the CR register (CR.FLUSHFIFO). After that, the SPI is able to receive new data. 496 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-8. Peripheral Deselection Figure 21-8 on page 496 shows different peripheral deselection cases and the effect of the CSRn.CSAAT and CSRn.CSNAAT bits. 21.7.3.9 Mode fault detection The SPI is capable of detecting a mode fault when it is configured in master mode and NPCS0, MOSI, MISO, and SPCK are configured as open drain through the I/O Controller with either internal or external pullup resistors. If the I/O Controller does not have open-drain capability, mode fault detection must be disabled by writing a one to the Mode Fault Detection bit in the MR A NPCS[0..3] Write TDR TDRE NPCS[0..3] Write TDR TDRE NPCS[0..3] Write TDR TDRE DLYBCS PCS = A DLYBCS DLYBCT A PCS = B B DLYBCS PCS = A DLYBCS DLYBCT A PCS = B B DLYBCS DLYBCT PCS=A A DLYBCS DLYBCT A PCS = A A A DLYBCT A A CSAAT = 0 and CSNAAT = 0 DLYBCT A A CSAAT = 1 and CSNAAT= 0 / 1 A DLYBCS PCS = A DLYBCT A A CSAAT = 0 and CSNAAT = 1 NPCS[0..3] Write TDR TDRE PCS = A DLYBCT A A CSAAT = 0 and CSNAAT = 0 497 32142D–06/2013 ATUC64/128/256L3/4U register (MR.MODFDIS). In systems with open-drain I/O lines, a mode fault is detected when a low level is driven by an external master on the NPCS0/NSS signal. When a mode fault is detected, the Mode Fault Error bit in the SR (SR.MODF) is set until the SR is read and the SPI is automatically disabled until re-enabled by writing a one to the SPI Enable bit in the CR register (CR.SPIEN). By default, the mode fault detection circuitry is enabled. The user can disable mode fault detection by writing a one to the Mode Fault Detection bit in the MR register (MR.MODFDIS). 21.7.4 SPI Slave Mode When operating in slave mode, the SPI processes data bits on the clock provided on the SPI clock pin (SPCK). The SPI waits for NSS to go active before receiving the serial clock from an external master. When NSS falls, the clock is validated on the serializer, which processes the number of bits defined by the Bits Per Transfer field of the Chip Select Register 0 (CSR0.BITS). These bits are processed following a phase and a polarity defined respectively by the CSR0.NCPHA and CSR0.CPOL bits. Note that the BITS, CPOL, and NCPHA bits of the other Chip Select Registers have no effect when the SPI is configured in Slave Mode. The bits are shifted out on the MISO line and sampled on the MOSI line. When all the bits are processed, the received data is transferred in the Receive Data Register and the SR.RDRF bit rises. If the RDR register has not been read before new data is received, the SR.OVRES bit is set. Data is loaded in RDR even if this flag is set. The user has to read the SR register to clear the SR.OVRES bit. When a transfer starts, the data shifted out is the data present in the Shift Register. If no data has been written in the TDR register, the last data received is transferred. If no data has been received since the last reset, all bits are transmitted low, as the Shift Register resets to zero. When a first data is written in TDR, it is transferred immediately in the Shift Register and the SR.TDRE bit rises. If new data is written, it remains in TDR until a transfer occurs, i.e. NSS falls and there is a valid clock on the SPCK pin. When the transfer occurs, the last data written in TDR is transferred in the Shift Register and the SR.TDRE bit rises. This enables frequent updates of critical variables with single transfers. Then, a new data is loaded in the Shift Register from the TDR. In case no character is ready to be transmitted, i.e. no character has been written in TDR since the last load from TDR to the Shift Register, the Shift Register is not modified and the last received character is retransmitted. In this case the Underrun Error Status bit is set in SR (SR.UNDES). Figure 21-9 on page 498 shows a block diagram of the SPI when operating in slave mode. 498 32142D–06/2013 ATUC64/128/256L3/4U Figure 21-9. Slave Mode Functional Block Diagram Shift Register SPCK SPIENS LSB MSB NSS MOSI SPI Clock TDRE TDR TD RDRF OVRES CSR0 CPOL NCPHA BITS SPIEN SPIDIS MISO UNDES RDR RD 4 - Character FIFO 0 1 RXFIFOEN 499 32142D–06/2013 ATUC64/128/256L3/4U 21.8 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 21-3. SPI Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Mode Register MR Read/Write 0x00000000 0x08 Receive Data Register RDR Read-only 0x00000000 0x0C Transmit Data Register TDR Write-only 0x00000000 0x10 Status Register SR Read-only 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x30 Chip Select Register 0 CSR0 Read/Write 0x00000000 0x34 Chip Select Register 1 CSR1 Read/Write 0x00000000 0x38 Chip Select Register 2 CSR2 Read/Write 0x00000000 0x3C Chip Select Register 3 CSR3 Read/Write 0x00000000 0x E4 Write Protection Control Register WPCR Read/Write 0X00000000 0xE8 Write Protection Status Register WPSR Read-only 0x00000000 0xF8 Features Register FEATURES Read-only - (1) 0xFC Version Register VERSION Read-only - (1) 500 32142D–06/2013 ATUC64/128/256L3/4U 21.8.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • LASTXFER: Last Transfer 1: The current NPCS will be deasserted after the character written in TD has been transferred. When CSRn.CSAAT is one, this allows to close the communication with the current serial peripheral by raising the corresponding NPCS line as soon as TD transfer has completed. 0: Writing a zero to this bit has no effect. • FLUSHFIFO: Flush Fifo Command 1: If The FIFO Mode is enabled (MR.FIFOEN written to one) and if an overrun error has been detected, this command allows to empty the FIFO. 0: Writing a zero to this bit has no effect. • SWRST: SPI Software Reset 1: Writing a one to this bit will reset the SPI. A software-triggered hardware reset of the SPI interface is performed. The SPI is in slave mode after software reset. Peripheral DMA Controller channels are not affected by software reset. 0: Writing a zero to this bit has no effect. • SPIDIS: SPI Disable 1: Writing a one to this bit will disable the SPI. As soon as SPIDIS is written to one, the SPI finishes its transfer, all pins are set in input mode and no data is received or transmitted. If a transfer is in progress, the transfer is finished before the SPI is disabled. If both SPIEN and SPIDIS are equal to one when the CR register is written, the SPI is disabled. 0: Writing a zero to this bit has no effect. • SPIEN: SPI Enable 1: Writing a one to this bit will enable the SPI to transfer and receive data. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 - - - - - - - LASTXFER 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - FLUSHFIFO 76543210 SWRST - - - - - SPIDIS SPIEN 501 32142D–06/2013 ATUC64/128/256L3/4U 21.8.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • DLYBCS: Delay Between Chip Selects This field defines the delay from NPCS inactive to the activation of another NPCS. The DLYBCS time guarantees nonoverlapping chip selects and solves bus contentions in case of peripherals having long data float times. If DLYBCS is less than or equal to six, six CLK_SPI periods will be inserted by default. Otherwise, the following equation determines the delay: • PCS: Peripheral Chip Select This field is only used if Fixed Peripheral Select is active (PS = 0). If PCSDEC = 0: PCS = xxx0NPCS[3:0] = 1110 PCS = xx01NPCS[3:0] = 1101 PCS = x011NPCS[3:0] = 1011 PCS = 0111NPCS[3:0] = 0111 PCS = 1111forbidden (no peripheral is selected) (x = don’t care) If PCSDEC = 1: NPCS[3:0] output signals = PCS. • LLB: Local Loopback Enable 1: Local loopback path enabled. LLB controls the local loopback on the data serializer for testing in master mode only (MISO is internally connected on MOSI). 0: Local loopback path disabled. • RXFIFOEN: FIFO in Reception Enable 1: The FIFO is used in reception (four characters can be stored in the SPI). 31 30 29 28 27 26 25 24 DLYBCS 23 22 21 20 19 18 17 16 - - - - PCS 15 14 13 12 11 10 9 8 -------- 76543210 LLB RXFIFOEN - MODFDIS - PCSDEC PS MSTR Delay Between Chip Selects DLYBCS CLKSPI = ----------------------- 502 32142D–06/2013 ATUC64/128/256L3/4U 0: The FIFO is not used in reception (only one character can be stored in the SPI). • MODFDIS: Mode Fault Detection 1: Mode fault detection is disabled. If the I/O controller does not have open-drain capability, mode fault detection must be disabled for proper operation of the SPI. 0: Mode fault detection is enabled. • PCSDEC: Chip Select Decode 0: The chip selects are directly connected to a peripheral device. 1: The four chip select lines are connected to a 4- to 16-bit decoder. When PCSDEC equals one, up to 15 Chip Select signals can be generated with the four lines using an external 4- to 16-bit decoder. The CSRn registers define the characteristics of the 15 chip selects according to the following rules: CSR0 defines peripheral chip select signals 0 to 3. CSR1 defines peripheral chip select signals 4 to 7. CSR2 defines peripheral chip select signals 8 to 11. CSR3 defines peripheral chip select signals 12 to 14. • PS: Peripheral Select 1: Variable Peripheral Select. 0: Fixed Peripheral Select. • MSTR: Master/Slave Mode 1: SPI is in master mode. 0: SPI is in slave mode. 503 32142D–06/2013 ATUC64/128/256L3/4U 21.8.3 Receive Data Register Name: RDR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • RD: Receive Data Data received by the SPI Interface is stored in this register right-justified. Unused bits read zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RD[15:8] 76543210 RD[7:0] 504 32142D–06/2013 ATUC64/128/256L3/4U 21.8.4 Transmit Data Register Name: TDR Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 • LASTXFER: Last Transfer 1: The current NPCS will be deasserted after the character written in TD has been transferred. When CSRn.CSAAT is one, this allows to close the communication with the current serial peripheral by raising the corresponding NPCS line as soon as TD transfer has completed. 0: Writing a zero to this bit has no effect. This field is only used if Variable Peripheral Select is active (MR.PS = 1). • PCS: Peripheral Chip Select If PCSDEC = 0: PCS = xxx0NPCS[3:0] = 1110 PCS = xx01NPCS[3:0] = 1101 PCS = x011NPCS[3:0] = 1011 PCS = 0111NPCS[3:0] = 0111 PCS = 1111forbidden (no peripheral is selected) (x = don’t care) If PCSDEC = 1: NPCS[3:0] output signals = PCS This field is only used if Variable Peripheral Select is active (MR.PS = 1). • TD: Transmit Data Data to be transmitted by the SPI Interface is stored in this register. Information to be transmitted must be written to the TDR register in a right-justified format. 31 30 29 28 27 26 25 24 - - - - - - - LASTXFER 23 22 21 20 19 18 17 16 - - - - PCS 15 14 13 12 11 10 9 8 TD[15:8] 76543210 TD[7:0] 505 32142D–06/2013 ATUC64/128/256L3/4U 21.8.5 Status Register Name: SR Access Type: Read-only Offset: 0x10 Reset Value: 0x00000000 • SPIENS: SPI Enable Status 1: This bit is set when the SPI is enabled. 0: This bit is cleared when the SPI is disabled. • UNDES: Underrun Error Status (Slave Mode Only) 1: This bit is set when a transfer begins whereas no data has been loaded in the TDR register. 0: This bit is cleared when the SR register is read. • TXEMPTY: Transmission Registers Empty 1: This bit is set when TDR and internal shifter are empty. If a transfer delay has been defined, TXEMPTY is set after the completion of such delay. 0: This bit is cleared as soon as data is written in TDR. • NSSR: NSS Rising 1: A rising edge occurred on NSS pin since last read. 0: This bit is cleared when the SR register is read. • OVRES: Overrun Error Status 1: This bit is set when an overrun has occurred. An overrun occurs when RDR is loaded at least twice from the serializer since the last read of the RDR. 0: This bit is cleared when the SR register is read. • MODF: Mode Fault Error 1: This bit is set when a Mode Fault occurred. 0: This bit is cleared when the SR register is read. • TDRE: Transmit Data Register Empty 1: This bit is set when the last data written in the TDR register has been transferred to the serializer. 0: This bit is cleared when data has been written to TDR and not yet transferred to the serializer. TDRE equals zero when the SPI is disabled or at reset. The SPI enable command sets this bit to one. • RDRF: Receive Data Register Full 1: Data has been received and the received data has been transferred from the serializer to RDR since the last read of RDR. 0: No data has been received since the last read of RDR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - SPIENS 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 506 32142D–06/2013 ATUC64/128/256L3/4U 21.8.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 507 32142D–06/2013 ATUC64/128/256L3/4U 21.8.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 508 32142D–06/2013 ATUC64/128/256L3/4U 21.8.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - UNDES TXEMPTY NSSR 76543210 - - - - OVRES MODF TDRE RDRF 509 32142D–06/2013 ATUC64/128/256L3/4U 21.8.9 Chip Select Register 0 Name: CSR0 Access Type: Read/Write Offset: 0x30 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 510 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 511 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 512 32142D–06/2013 ATUC64/128/256L3/4U 21.8.10 Chip Select Register 1 Name: CSR1 Access Type: Read/Write Offset: 0x34 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 513 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 514 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 515 32142D–06/2013 ATUC64/128/256L3/4U 21.8.11 Chip Select Register 2 Name: CSR2 Access Type: Read/Write Offset: 0x38 Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 516 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 517 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 518 32142D–06/2013 ATUC64/128/256L3/4U 21.8.12 Chip Select Register 3 Name: CSR3 Access Type: Read/Write Offset: 0x3C Reset Value: 0x00000000 • DLYBCT: Delay Between Consecutive Transfers This field defines the delay between two consecutive transfers with the same peripheral without removing the chip select. The delay is always inserted after each transfer and before removing the chip select if needed. When DLYBCT equals zero, no delay between consecutive transfers is inserted and the clock keeps its duty cycle over the character transfers. Otherwise, the following equation determines the delay: • DLYBS: Delay Before SPCK This field defines the delay from NPCS valid to the first valid SPCK transition. When DLYBS equals zero, the NPCS valid to SPCK transition is 1/2 the SPCK clock period. Otherwise, the following equations determine the delay: • SCBR: Serial Clock Baud Rate In Master Mode, the SPI Interface uses a modulus counter to derive the SPCK baud rate from the CLK_SPI. The Baud rate is selected by writing a value from 1 to 255 in the SCBR field. The following equations determine the SPCK baud rate: Writing the SCBR field to zero is forbidden. Triggering a transfer while SCBR is zero can lead to unpredictable results. At reset, SCBR is zero and the user has to write it to a valid value before performing the first transfer. If a clock divider (SCBRn) field is set to one and the other SCBR fields differ from one, access on CSn is correct but no correct access will be possible on other CS. 31 30 29 28 27 26 25 24 DLYBCT 23 22 21 20 19 18 17 16 DLYBS 15 14 13 12 11 10 9 8 SCBR 76543210 BITS CSAAT CSNAAT NCPHA CPOL Delay Between Consecutive Transfers 32  DLYBCT CLKSPI = ------------------------------------ Delay Before SPCK DLYBS CLKSPI = --------------------- SPCK Baudrate CLKSPI SCBR = --------------------- 519 32142D–06/2013 ATUC64/128/256L3/4U • BITS: Bits Per Transfer The BITS field determines the number of data bits transferred. Reserved values should not be used. • CSAAT: Chip Select Active After Transfer 1: The Peripheral Chip Select does not rise after the last transfer is achieved. It remains active until a new transfer is requested on a different chip select. 0: The Peripheral Chip Select Line rises as soon as the last transfer is achieved. • CSNAAT: Chip Select Not Active After Transfer (Ignored if CSAAT = 1) 0: The Peripheral Chip Select does not rise between two transfers if the TDR is reloaded before the end of the first transfer and if the two transfers occur on the same Chip Select. 1: The Peripheral Chip Select rises systematically between each transfer performed on the same slave for a minimal duration of: (if DLYBCT field is different from 0) (if DLYBCT field equals 0) • NCPHA: Clock Phase 1: Data is captured after the leading (inactive-to-active) edge of SPCK and changed on the trailing (active-to-inactive) edge of SPCK. 0: Data is changed on the leading (inactive-to-active) edge of SPCK and captured after the trailing (active-to-inactive) edge of SPCK. NCPHA determines which edge of SPCK causes data to change and which edge causes data to be captured. NCPHA is used with CPOL to produce the required clock/data relationship between master and slave devices. • CPOL: Clock Polarity 1: The inactive state value of SPCK is logic level one. 0: The inactive state value of SPCK is logic level zero. BITS Bits Per Transfer 0000 8 0001 9 0010 10 0011 11 0100 12 0101 13 0110 14 0111 15 1000 16 1001 4 1010 5 1011 6 1100 7 1101 Reserved 1110 Reserved 1111 Reserved DLYBCS CLKSPI ----------------------- DLYBCS + 1 CLKSPI -------------------------------- 520 32142D–06/2013 ATUC64/128/256L3/4U CPOL is used to determine the inactive state value of the serial clock (SPCK). It is used with NCPHA to produce the required clock/data relationship between master and slave devices. 521 32142D–06/2013 ATUC64/128/256L3/4U 21.8.13 Write Protection Control Register Register Name: WPCR Access Type: Read-write Offset: 0xE4 Reset Value: 0x00000000 • SPIWPKEY: SPI Write Protection Key Password If a value is written in SPIWPEN, the value is taken into account only if SPIWPKEY is written with “SPI” (SPI written in ASCII Code, i.e. 0x535049 in hexadecimal). • SPIWPEN: SPI Write Protection Enable 1: The Write Protection is Enabled 0: The Write Protection is Disabled 31 30 29 28 27 26 25 24 SPIWPKEY[23:16] 23 22 21 20 19 18 17 16 SPIWPKEY[15:8] 15 14 13 12 11 10 9 8 SPIWPKEY[7:0] 76543210 - - - - - - - SPIWPEN 522 32142D–06/2013 ATUC64/128/256L3/4U 21.8.14 Write Protection Status Register Register Name: WPSR Access Type: Read-only Offset: 0xE8 Reset Value: 0x00000000 • SPIWPVSRC: SPI Write Protection Violation Source This Field indicates the Peripheral Bus Offset of the register concerned by the violation (MR or CSRx) • SPIWPVS: SPI Write Protection Violation Status 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SPIWPVSRC 76543210 - - - - - SPIWPVS SPIWPVS value Violation Type 1 The Write Protection has blocked a Write access to a protected register (since the last read). 2 Software Reset has been performed while Write Protection was enabled (since the last read or since the last write access on MR, IER, IDR or CSRx). 3 Both Write Protection violation and software reset with Write Protection enabled have occurred since the last read. 4 Write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 5 The Write Protection has blocked a Write access to a protected register and write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 6 Software Reset has been performed while Write Protection was enabled (since the last read or since the last write access on MR, IER, IDR or CSRx) and some write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 7 - The Write Protection has blocked a Write access to a protected register. and - Software Reset has been performed while Write Protection was enabled. and - Write accesses have been detected on MR (while a chip select was active) or on CSRi (while the Chip Select “i” was active) since the last read. 523 32142D–06/2013 ATUC64/128/256L3/4U 21.8.15 Features Register Register Name: FEATURES Access Type: Read-only Offset: 0xF8 Reset Value: – • SWIMPL: Spurious Write Protection Implemented 0: Spurious write protection is not implemented. 1: Spurious write protection is implemented. • FIFORIMPL: FIFO in Reception Implemented 0: FIFO in reception is not implemented. 1: FIFO in reception is implemented. • BRPBHSB: Bridge Type is PB to HSB 0: Bridge type is not PB to HSB. 1: Bridge type is PB to HSB. • CSNAATIMPL: CSNAAT Features Implemented 0: CSNAAT (Chip select not active after transfer) features are not implemented. 1: CSNAAT features are implemented. • EXTDEC: External Decoder True 0: External decoder capability is not implemented. 1: External decoder capability is implemented. • LENNCONF: Character Length if not Configurable If the character length is not configurable, this field specifies the fixed character length. • LENCONF: Character Length Configurable 0: The character length is not configurable. 1: The character length is configurable. • PHZNCONF: Phase is Zero if Phase not Configurable 0: If phase is not configurable, phase is non-zero. 1: If phase is not configurable, phase is zero. • PHCONF: Phase Configurable 0: Phase is not configurable. 1: Phase is configurable. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - SWIMPL FIFORIMPL BRPBHSB CSNAATIMPL EXTDEC 15 14 13 12 11 10 9 8 LENNCONF LENCONF 76543210 PHZNCONF PHCONF PPNCONF PCONF NCS 524 32142D–06/2013 ATUC64/128/256L3/4U • PPNCONF: Polarity Positive if Polarity not Configurable 0: If polarity is not configurable, polarity is negative. 1: If polarity is not configurable, polarity is positive. • PCONF: Polarity Configurable 0: Polarity is not configurable. 1: Polarity is configurable. • NCS: Number of Chip Selects This field indicates the number of chip selects implemented. 525 32142D–06/2013 ATUC64/128/256L3/4U 21.8.16 Version Register Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: – • MFN Reserved. No functionality associated. • VERSION Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - MFN 15 14 13 12 11 10 9 8 VERSION[11:8] 76543210 VERSION[7:0] 526 32142D–06/2013 ATUC64/128/256L3/4U 21.9 Module Configuration The specific configuration for each SPI instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 21-4. SPI Clock Name Module Name Clock Name Description SPI CLK_SPI Clock for the SPI bus interface Table 21-5. Register Reset Value FEATURES 0x001F0154 VERSION 0x00000211 527 32142D–06/2013 ATUC64/128/256L3/4U 22. Two-wire Master Interface (TWIM) Rev.: 1.1.0.1 22.1 Features • Compatible with I²C standard – Multi-master support – Transfer speeds of 100 and 400 kbit/s – 7- and 10-bit and General Call addressing • Compatible with SMBus standard – Hardware Packet Error Checking (CRC) generation and verification with ACK control – SMBus ALERT interface – 25 ms clock low timeout delay – 10 ms master cumulative clock low extend time – 25 ms slave cumulative clock low extend time • Compatible with PMBus • Compatible with Atmel Two-wire Interface Serial Memories • DMA interface for reducing CPU load • Arbitrary transfer lengths, including 0 data bytes • Optional clock stretching if transmit or receive buffers not ready for data transfer 22.2 Overview The Atmel Two-wire Master Interface (TWIM) interconnects components on a unique two-wire bus, made up of one clock line and one data line with speeds of up to 400 kbit/s, based on a byte-oriented transfer format. It can be used with any Atmel Two-wire Interface bus serial EEPROM and I²C compatible device such as a real time clock (RTC), dot matrix/graphic LCD controller, and temperature sensor, to name a few. The TWIM is always a bus master and can transfer sequential or single bytes. Multiple master capability is supported. Arbitration of the bus is performed internally and relinquishes the bus automatically if the bus arbitration is lost. A configurable baud rate generator permits the output data rate to be adapted to a wide range of core clock frequencies.Table 22-1 lists the compatibility level of the Atmel Two-wire Interface in Master Mode and a full I²C compatible device. Note: 1. START + b000000001 + Ack + Sr Table 22-1. Atmel TWIM Compatibility with I²C Standard I²C Standard Atmel TWIM Standard-mode (100 kbit/s) Supported Fast-mode (400 kbit/s) Supported Fast-mode Plus (1 Mbit/s) Supported 7- or 10-bits Slave Addressing Supported START BYTE(1) Not Supported Repeated Start (Sr) Condition Supported ACK and NACK Management Supported Slope Control and Input Filtering (Fast mode) Supported Clock Stretching Supported 528 32142D–06/2013 ATUC64/128/256L3/4U Table 22-2 lists the compatibility level of the Atmel Two-wire Master Interface and a full SMBus compatible master. 22.3 List of Abbreviations 22.4 Block Diagram Figure 22-1. Block Diagram Table 22-2. Atmel TWIM Compatibility with SMBus Standard SMBus Standard Atmel TWIM Bus Timeouts Supported Address Resolution Protocol Supported Alert Supported Host Functionality Supported Packet Error Checking Supported Table 22-3. Abbreviations Abbreviation Description TWI Two-wire Interface A Acknowledge NA Non Acknowledge P Stop S Start Sr Repeated Start SADR Slave Address ADR Any address except SADR R Read W Write Peripheral Bus Bridge Two-wire Interface I/O Controller TWCK TWD INTC TWI Interrupt Power Manager CLK_TWIM TWALM 529 32142D–06/2013 ATUC64/128/256L3/4U 22.5 Application Block Diagram Figure 22-2. Application Block Diagram 22.6 I/O Lines Description 22.7 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 22.7.1 I/O Lines TWD and TWCK are bidirectional lines, connected to a positive supply voltage via a current source or pull-up resistor (see Figure 22-4 on page 531). When the bus is free, both lines are high. The output stages of devices connected to the bus must have an open-drain or open-collector to perform the wired-AND function. TWALM is used to implement the optional SMBus SMBALERT signal. The TWALM, TWD, and TWCK pins may be multiplexed with I/O Controller lines. To enable the TWIM, the user must perform the following steps: • Program the I/O Controller to: – Dedicate TWD, TWCK, and optionally TWALM as peripheral lines. – Define TWD, TWCK, and optionally TWALM as open-drain. 22.7.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TWIM, the TWIM will stop functioning and resume operation after the system wakes up from sleep mode. TWI Master TWD TWCK Atmel TWI serial EEPROM I 2 C RTC I 2 C LCD controller I 2 C temp sensor Slave 2 Slave 3 Slave 4 VDD Rp: pull-up value as given by the I2C Standard TWALM Slave 1 Rp Rp Rp Table 22-4. I/O Lines Description Pin Name Pin Description Type TWD Two-wire Serial Data Input/Output TWCK Two-wire Serial Clock Input/Output TWALM SMBus SMBALERT Input/Output 530 32142D–06/2013 ATUC64/128/256L3/4U 22.7.3 Clocks The clock for the TWIM bus interface (CLK_TWIM) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TWIM before disabling the clock, to avoid freezing the TWIM in an undefined state. 22.7.4 DMA The TWIM DMA handshake interface is connected to the Peripheral DMA Controller. Using the TWIM DMA functionality requires the Peripheral DMA Controller to be programmed after setting up the TWIM. 22.7.5 Interrupts The TWIM interrupt request lines are connected to the interrupt controller. Using the TWIM interrupts requires the interrupt controller to be programmed first. 22.7.6 Debug Operation When an external debugger forces the CPU into debug mode, the TWIM continues normal operation. If the TWIM is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 531 32142D–06/2013 ATUC64/128/256L3/4U 22.8 Functional Description 22.8.1 Transfer Format The data put on the TWD line must be 8 bits long. Data is transferred MSB first; each byte must be followed by an acknowledgement. The number of bytes per transfer is unlimited (see Figure 22-4). Each transfer begins with a START condition and terminates with a STOP condition (see Figure 22-4). • A high-to-low transition on the TWD line while TWCK is high defines the START condition. • A low-to-high transition on the TWD line while TWCK is high defines a STOP condition. Figure 22-3. START and STOP Conditions Figure 22-4. Transfer Format 22.8.2 Operation The TWIM has two modes of operation: • Master transmitter mode • Master receiver mode The master is the device which starts and stops a transfer and generates the TWCK clock. These modes are described in the following chapters. TWD TWCK Start Stop TWD TWCK Start Address R/W Ack Data Ack Data Ack Stop 532 32142D–06/2013 ATUC64/128/256L3/4U 22.8.2.1 Clock Generation The Clock Waveform Generator Register (CWGR) is used to control the waveform of the TWCK clock. CWGR must be written so that the desired TWI bus timings are generated. CWGR describes bus timings as a function of cycles of a prescaled clock. The clock prescaling can be selected through the Clock Prescaler field in CWGR (CWGR.EXP). CWGR has the following fields: LOW: Prescaled clock cycles in clock low count. Used to time TLOW and TBUF. HIGH: Prescaled clock cycles in clock high count. Used to time THIGH. STASTO: Prescaled clock cycles in clock high count. Used to time THD_STA, TSU_STA, TSU_STO. DATA: Prescaled clock cycles for data setup and hold count. Used to time THD_DAT, TSU_DAT. EXP: Specifies the clock prescaler setting. Note that the total clock low time generated is the sum of THD_DAT + TSU_DAT + TLOW. Any slave or other bus master taking part in the transfer may extend the TWCK low period at any time. The TWIM hardware monitors the state of the TWCK line as required by the I²C specification. The clock generation counters are started when a high/low level is detected on the TWCK line, not when the TWIM hardware releases/drives the TWCK line. This means that the CWGR settings alone do not determine the TWCK frequency. The CWGR settings determine the clock low time and the clock high time, but the TWCK rise and fall times are determined by the external circuitry (capacitive load, etc.). Figure 22-5. Bus Timing Diagram f PRESCALER f CLK_TWIM 2  EXP 1 + = ------------------------- S t HD:STA t LOW t SU:DAT t HIGH t HD:DAT t LOW P t SU:STO Sr t SU:STA t SU:DAT 533 32142D–06/2013 ATUC64/128/256L3/4U 22.8.2.2 Setting up and Performing a Transfer Operation of the TWIM is mainly controlled by the Control Register (CR) and the Command Register (CMDR). TWIM status is provided in the Status Register (SR). The following list presents the main steps in a typical communication: 1. Before any transfers can be performed, bus timings must be configured by writing to the Clock Waveform Generator Register (CWGR). If operating in SMBus mode, the SMBus Timing Register (SMBTR) register must also be configured. 2. If the Peripheral DMA Controller is to be used for the transfers, it must be set up. 3. CMDR or NCMDR must be written with a value describing the transfer to be performed. The interrupt system can be set up to give interrupt requests on specific events or error conditions in the SR, for example when the transfer is complete or if arbitration is lost. The Interrupt Enable Register (IER) and Interrupt Disable Register (IDR) can be written to specify which bits in the SR will generate interrupt requests. The SR.BUSFREE bit is set when activity is completed on the two-wire bus. The SR.CRDY bit is set when CMDR and/or NCMDR is ready to receive one or more commands. The controller will refuse to start a new transfer while ANAK, DNAK, or ARBLST in the Status Register (SR) is one. This is necessary to avoid a race when the software issues a continuation of the current transfer at the same time as one of these errors happen. Also, if ANAK or DNAK occurs, a STOP condition is sent automatically. The user will have to restart the transmission by clearing the error bits in SR after resolving the cause for the NACK. After a data or address NACK from the slave, a STOP will be transmitted automatically. Note that the VALID bit in CMDR is NOT cleared in this case. If this transfer is to be discarded, the VALID bit can be cleared manually allowing any command in NCMDR to be copied into CMDR. When a data or address NACK is returned by the slave while the master is transmitting, it is possible that new data has already been written to the THR register. This data will be transferred out as the first data byte of the next transfer. If this behavior is to be avoided, the safest approach is to perform a software reset of the TWIM. 22.8.3 Master Transmitter Mode A START condition is transmitted and master transmitter mode is initiated when the bus is free and CMDR has been written with START=1 and READ=0. START and SADR+W will then be transmitted. During the address acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to acknowledge the address. The master polls the data line during this clock pulse and sets the Address Not Acknowledged bit (ANAK) in the Status Register if no slave acknowledges the address. After the address phase, the following is repeated: while (NBYTES>0) 1. Wait until THR contains a valid data byte, stretching low period of TWCK. SR.TXRDY indicates the state of THR. Software or the Peripheral DMA Controller must write the data byte to THR. 2. Transmit this data byte 3. Decrement NBYTES 4. If (NBYTES==0) and STOP=1, transmit STOP condition Writing CMDR with START=STOP=1 and NBYTES=0 will generate a transmission with no data bytes, ie START, SADR+W, STOP. 534 32142D–06/2013 ATUC64/128/256L3/4U TWI transfers require the slave to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to generate the acknowledge. The master polls the data line during this clock pulse and sets the Data Acknowledge bit (DNACK) in the Status Register if the slave does not acknowledge the data byte. As with the other status bits, an interrupt can be generated if enabled in the Interrupt Enable Register (IER). TXRDY is used as Transmit Ready for the Peripheral DMA Controller transmit channel. The end of a command is marked when the TWIM sets the SR.CCOMP bit. See Figure 22-6 and Figure 22-7. Figure 22-6. Master Write with One Data Byte Figure 22-7. Master Write with Multiple Data Bytes 22.8.4 Master Receiver Mode A START condition is transmitted and master receiver mode is initiated when the bus is free and CMDR has been written with START=1 and READ=1. START and SADR+R will then be transmitted. During the address acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the slave to pull it down in order to acknowledge the address. The master polls the data line during this clock pulse and sets the Address Not Acknowledged bit (ANAK) in the Status Register if no slave acknowledges the address. After the address phase, the following is repeated: while (NBYTES>0) TWD SR.IDLE TXRDY Write THR (DATA) NBYTES set to 1 STOP sent automatically (ACK received and NBYTES=0) S DADR W A DATA A P TWD SR.IDLE TXRDY Write THR (DATAn) NBYTES set to n STOP sent automatically (ACK received and NBYTES=0) S DADR W A DATAn A DATAn+5 A A DATAn+m P Write THR (DATAn+1) Write THR (DATAn+m) Last data sent 535 32142D–06/2013 ATUC64/128/256L3/4U 1. Wait until RHR is empty, stretching low period of TWCK. SR.RXRDY indicates the state of RHR. Software or the Peripheral DMA Controller must read any data byte present in RHR. 2. Release TWCK generating a clock that the slave uses to transmit a data byte. 3. Place the received data byte in RHR, set RXRDY. 4. If NBYTES=0, generate a NAK after the data byte, otherwise generate an ACK. 5. Decrement NBYTES 6. If (NBYTES==0) and STOP=1, transmit STOP condition. Writing CMDR with START=STOP=1 and NBYTES=0 will generate a transmission with no data bytes, ie START, DADR+R, STOP The TWI transfers require the master to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the slave releases the data line (HIGH), enabling the master to pull it down in order to generate the acknowledge. All data bytes except the last are acknowledged by the master. Not acknowledging the last byte informs the slave that the transfer is finished. RXRDY is used as Receive Ready for the Peripheral DMA Controller receive channel. Figure 22-8. Master Read with One Data Byte Figure 22-9. Master Read with Multiple Data Bytes TWD SR.IDLE RXRDY Write START & STOP bit NBYTES set to 1 Read RHR S DADR R A DATA N P TWD SR.IDLE RXRDY Write START + STOP bit NBYTES set to m S DADR R A DATAn A DATAn+m-1 A N DATAn+m P Read RHR DATAn DATAn+1 Read RHR DATAn+m-2 Read RHR DATAn+m-1 Read RHR DATAn+m Send STOP When NBYTES=0 536 32142D–06/2013 ATUC64/128/256L3/4U 22.8.5 Using the Peripheral DMA Controller The use of the Peripheral DMA Controller significantly reduces the CPU load. The user can set up ring buffers for the Peripheral DMA Controller, containing data to transmit or free buffer space to place received data. To assure correct behavior, respect the following programming sequences: 22.8.5.1 Data Transmit with the Peripheral DMA Controller 1. Initialize the transmit Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIM (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to transmit. 4. Wait for the Peripheral DMA Controller end-of-transmit flag. 5. Disable the Peripheral DMA Controller. 22.8.5.2 Data Receive with the Peripheral DMA Controller 1. Initialize the receive Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIM (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to receive. 4. Wait for the Peripheral DMA Controller end-of-receive flag. 5. Disable the Peripheral DMA Controller. 22.8.6 Multi-master Mode More than one master may access the bus at the same time without data corruption by using arbitration. Arbitration starts as soon as two or more masters place information on the bus at the same time, and stops (arbitration is lost) for the master that intends to send a logical one while the other master sends a logical zero. As soon as arbitration is lost by a master, it stops sending data and listens to the bus in order to detect a STOP. The SR.ARBLST flag will be set. When the STOP is detected, the master who lost arbitration may reinitiate the data transfer. Arbitration is illustrated in Figure 22-11. If the user starts a transfer and if the bus is busy, the TWIM automatically waits for a STOP condition on the bus before initiating the transfer (see Figure 22-10). Note: The state of the bus (busy or free) is not indicated in the user interface. 537 32142D–06/2013 ATUC64/128/256L3/4U Figure 22-10. User Sends Data While the Bus is Busy Figure 22-11. Arbitration Cases 22.8.7 Combined Transfers CMDR and NCMDR may be used to generate longer sequences of connected transfers, since generation of START and/or STOP conditions is programmable on a per-command basis. Writing NCMDR with START=1 when the previous transfer was written with STOP=0 will cause a REPEATED START on the bus. The ability to generate such connected transfers allows arbitrary transfer lengths, since it is legal to write CMDR with both START=0 and STOP=0. If this is done in master receiver mode, the CMDR.ACKLAST bit must also be controlled. TWCK TWD DATA sent by a master STOP sent by the master START sent by the TWI DATA sent by the TWI Bus is busy Bus is free A transfer is programmed (DADR + W + START + Write THR) Transfer is initiated TWI DATA transfer Transfer is kept Bus is considered as free TWCK Bus is busy Bus is free A transfer is programmed (DADR + W + START + Write THR) Transfer is initiated TWI DATA transfer Transfer is kept Bus is considered as free Data from a Master Data from TWI S 0 S 0 0 1 1 1 ARBLST S 0 S 0 0 1 1 1 TWD S 1 0 0 1 1 1 1 Arbitration is lost TWI stops sending data P P S 1 0 0 1 1 Data from the master 1 1 Data from the TWI Arbitration is lost The master stops sending data Transfer is stopped Transfer is programmed again (DADR + W + START + Write THR) TWCK TWD 538 32142D–06/2013 ATUC64/128/256L3/4U As for single data transfers, the TXRDY and RXRDY bits in the Status Register indicates when data to transmit can be written to THR, or when received data can be read from RHR. Transfer of data to THR and from RHR can also be done automatically by DMA, see Section 22.8.5 22.8.7.1 Write Followed by Write Consider the following transfer: START, DADR+W, DATA+A, DATA+A, REPSTART, DADR+W, DATA+A, DATA+A, STOP. To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=0. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=0. 3. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 4. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. 5. Wait until SR.TXRDY==1, then write third data byte to transfer to THR. 6. Wait until SR.TXRDY==1, then write fourth data byte to transfer to THR. 22.8.7.2 Read Followed by Read Consider the following transfer: START, DADR+R, DATA+A, DATA+NA, REPSTART, DADR+R, DATA+A, DATA+NA, STOP. To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=1. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=1. 3. Wait until SR.RXRDY==1, then read first data byte received from RHR. 4. Wait until SR.RXRDY==1, then read second data byte received from RHR. 5. Wait until SR.RXRDY==1, then read third data byte received from RHR. 6. Wait until SR.RXRDY==1, then read fourth data byte received from RHR. If combining several transfers, without any STOP or REPEATED START between them, remember to write a one to the ACKLAST bit in CMDR to keep from ending each of the partial transfers with a NACK. 22.8.7.3 Write Followed by Read Consider the following transfer: START, DADR+W, DATA+A, DATA+A, REPSTART, DADR+R, DATA+A, DATA+NA, STOP. 539 32142D–06/2013 ATUC64/128/256L3/4U Figure 22-12. Combining a Write and Read Transfer To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=0. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=1. 3. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 4. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. 5. Wait until SR.RXRDY==1, then read first data byte received from RHR. 6. Wait until SR.RXRDY==1, then read second data byte received from RHR. 22.8.7.4 Read Followed by Write Consider the following transfer: START, DADR+R, DATA+A, DATA+NA, REPSTART, DADR+W, DATA+A, DATA+A, STOP. Figure 22-13. Combining a Read and Write Transfer To generate this transfer: 1. Write CMDR with START=1, STOP=0, DADR, NBYTES=2 and READ=1. 2. Write NCMDR with START=1, STOP=1, DADR, NBYTES=2 and READ=0. 3. Wait until SR.RXRDY==1, then read first data byte received from RHR. 4. Wait until SR.RXRDY==1, then read second data byte received from RHR. 5. Wait until SR.TXRDY==1, then write first data byte to transfer to THR. 6. Wait until SR.TXRDY==1, then write second data byte to transfer to THR. TWD SR.IDLE TXRDY S DADR W A DATA0 A DATA1 NA Sr DADR R A DATA2 A DATA3 A P THR DATA0 DATA1 RXRDY 1 RHR DATA2 DATA3 TWD SR.IDLE TXRDY S SADR R A DATA0 A DATA1 Sr DADR W A DATA2 A DATA3 NA P THR DATA2 RXRDY RHR DATA0 DATA3 A 1 2 DATA3 Read TWI_RHR 540 32142D–06/2013 ATUC64/128/256L3/4U 22.8.8 Ten Bit Addressing Writing a one to CMDR.TENBIT enables 10-bit addressing in hardware. Performing transfers with 10-bit addressing is similar to transfers with 7-bit addresses, except that bits 9:7 of CMDR.SADR must be written appropriately. In Figure 22-14 and Figure 22-15, the grey boxes represent signals driven by the master, the white boxes are driven by the slave. 22.8.8.1 Master Transmitter To perform a master transmitter transfer: 1. Write CMDR with TENBIT=1, REPSAME=0, READ=0, START=1, STOP=1 and the desired address and NBYTES value. Figure 22-14. A Write Transfer with 10-bit Addressing 22.8.8.2 Master Receiver When using master receiver mode with 10-bit addressing, CMDR.REPSAME must also be controlled. CMDR.REPSAME must be written to one when the address phase of the transfer should consist of only 1 address byte (the 11110xx byte) and not 2 address bytes. The I²C standard specifies that such addressing is required when addressing a slave for reads using 10-bit addressing. To perform a master receiver transfer: 1. Write CMDR with TENBIT=1, REPSAME=0, READ=0, START=1, STOP=0, NBYTES=0 and the desired address. 2. Write NCMDR with TENBIT=1, REPSAME=1, READ=1, START=1, STOP=1 and the desired address and NBYTES value. Figure 22-15. A Read Transfer with 10-bit Addressing 22.8.9 SMBus Mode SMBus mode is enabled and disabled by writing to the SMEN and SMDIS bits in CR. SMBus mode operation is similar to I²C operation with the following exceptions: • Only 7-bit addressing can be used. • The SMBus standard describes a set of timeout values to ensure progress and throughput on the bus. These timeout values must be written into SMBTR. • Transmissions can optionally include a CRC byte, called Packet Error Check (PEC). • A dedicated bus line, SMBALERT, allows a slave to get a master’s attention. • A set of addresses have been reserved for protocol handling, such as Alert Response Address (ARA) and Host Header (HH) Address. S SLAVE ADDRESS 1st 7 bits RW A1 A2 DATA A P SLAVE ADDRESS 2nd byte DATA AA 11110XX0 S SLAVE ADDRESS 1st 7 bits RW A1 A2 DATA A P SLAVE ADDRESS 2nd byte DATA A 11110XX0 Sr SLAVE ADDRESS 1st 7 bits RW A3 11110XX1 541 32142D–06/2013 ATUC64/128/256L3/4U 22.8.9.1 Packet Error Checking Each SMBus transfer can optionally end with a CRC byte, called the PEC byte. Writing a one to CMDR.PECEN enables automatic PEC handling in the current transfer. Transfers with and without PEC can freely be intermixed in the same system, since some slaves may not support PEC. The PEC LFSR is always updated on every bit transmitted or received, so that PEC handling on combined transfers will be correct. In master transmitter mode, the master calculates a PEC value and transmits it to the slave after all data bytes have been transmitted. Upon reception of this PEC byte, the slave will compare it to the PEC value it has computed itself. If the values match, the data was received correctly, and the slave will return an ACK to the master. If the PEC values differ, data was corrupted, and the slave will return a NACK value. The DNAK bit in SR reflects the state of the last received ACK/NACK value. Some slaves may not be able to check the received PEC in time to return a NACK if an error occurred. In this case, the slave should always return an ACK after the PEC byte, and some other mechanism must be implemented to verify that the transmission was received correctly. In master receiver mode, the slave calculates a PEC value and transmits it to the master after all data bytes have been transmitted. Upon reception of this PEC byte, the master will compare it to the PEC value it has computed itself. If the values match, the data was received correctly. If the PEC values differ, data was corrupted, and SR.PECERR is set. In master receiver mode, the PEC byte is always followed by a NACK transmitted by the master, since it is the last byte in the transfer. The PEC byte is automatically inserted in a master transmitter transmission if PEC is enabled when NBYTES reaches zero. The PEC byte is identified in a master receiver transmission if PEC is enabled when NBYTES reaches zero. NBYTES must therefore be written with the total number of data bytes in the transmission, including the PEC byte. In combined transfers, the PECEN bit should only be written to one in the last of the combined transfers. Consider the following transfer: S, ADR+W, COMMAND_BYTE, ACK, SR, ADR+R, DATA_BYTE, ACK, PEC_BYTE, NACK, P This transfer is generated by writing two commands to the command registers. The first command is a write with NBYTES=1 and PECEN=0, and the second is a read with NBYTES=2 and PECEN=1. Writing a one to the STOP bit in CR will place a STOP condition on the bus after the current byte. No PEC byte will be sent in this case. 22.8.9.2 Timeouts The TLOWS and TLOWM fields in SMBTR configure the SMBus timeout values. If a timeout occurs, the master will transmit a STOP condition and leave the bus. The SR.TOUT bit is set. 22.8.9.3 SMBus ALERT Signal A slave can get the master’s attention by pulling the TWALM line low. The TWIM will then set the SR.SMBALERT bit. This can be set up to trigger an interrupt, and software can then take the appropriate action, as defined in the SMBus standard. 542 32142D–06/2013 ATUC64/128/256L3/4U 22.8.10 Identifying Bus Events This chapter lists the different bus events, and how they affect bits in the TWIM registers. This is intended to help writing drivers for the TWIM. Table 22-5. Bus Events Event Effect Master transmitter has sent a data byte SR.THR is cleared. Master receiver has received a data byte SR.RHR is set. Start+Sadr sent, no ack received from slave SR.ANAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Data byte sent to slave, no ack received from slave SR.DNAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Arbitration lost SR.ARBLST is set. SR.CCOMP not set. CMDR.VALID remains set. TWCK and TWD immediately released to a pulled-up state. SMBus Alert received SR.SMBALERT is set. SMBus timeout received SR.SMBTOUT is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Master transmitter receives SMBus PEC Error SR.DNAK is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. Master receiver discovers SMBus PEC Error SR.PECERR is set. SR.CCOMP not set. CMDR.VALID remains set. STOP automatically transmitted on bus. CR.STOP is written by user SR.STOP is set. SR.CCOMP set. CMDR.VALID remains set. STOP transmitted on bus after current byte transfer has finished. 543 32142D–06/2013 ATUC64/128/256L3/4U 22.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 22-6. TWIM Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Clock Waveform Generator Register CWGR Read/Write 0x00000000 0x08 SMBus Timing Register SMBTR Read/Write 0x00000000 0x0C Command Register CMDR Read/Write 0x00000000 0x10 Next Command Register NCMDR Read/Write 0x00000000 0x14 Receive Holding Register RHR Read-only 0x00000000 0x18 Transmit Holding Register THR Write-only 0x00000000 0x1C Status Register SR Read-only 0x00000002 0x20 Interrupt Enable Register IER Write-only 0x00000000 0x24 Interrupt Disable Register IDR Write-only 0x00000000 0x28 Interrupt Mask Register IMR Read-only 0x00000000 0x2C Status Clear Register SCR Write-only 0x00000000 0x30 Parameter Register PR Read-only -(1) 0x34 Version Register VR Read-only -(1) 544 32142D–06/2013 ATUC64/128/256L3/4U 22.9.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • STOP: Stop the Current Transfer Writing a one to this bit terminates the current transfer, sending a STOP condition after the shifter has become idle. If there are additional pending transfers, they will have to be explicitly restarted by software after the STOP condition has been successfully sent. Writing a zero to this bit has no effect. • SWRST: Software Reset If the TWIM master interface is enabled, writing a one to this bit resets the TWIM. All transfers are halted immediately, possibly violating the bus semantics. If the TWIM master interface is not enabled, it must first be enabled before writing a one to this bit. Writing a zero to this bit has no effect. • SMDIS: SMBus Disable Writing a one to this bit disables SMBus mode. Writing a zero to this bit has no effect. • SMEN: SMBus Enable Writing a one to this bit enables SMBus mode. Writing a zero to this bit has no effect. • MDIS: Master Disable Writing a one to this bit disables the master interface. Writing a zero to this bit has no effect. • MEN: Master Enable Writing a one to this bit enables the master interface. Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - STOP 76543210 SWRST - SMDIS SMEN - - MDIS MEN 545 32142D–06/2013 ATUC64/128/256L3/4U 22.9.2 Clock Waveform Generator Register Name: CWGR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • EXP: Clock Prescaler Used to specify how to prescale the TWCK clock. Counters are prescaled according to the following formula • DATA: Data Setup and Hold Cycles Clock cycles for data setup and hold count. Prescaled by CWGR.EXP. Used to time THD_DAT, TSU_DAT. • STASTO: START and STOP Cycles Clock cycles in clock high count. Prescaled by CWGR.EXP. Used to time THD_STA, TSU_STA, TSU_STO • HIGH: Clock High Cycles Clock cycles in clock high count. Prescaled by CWGR.EXP. Used to time THIGH. • LOW: Clock Low Cycles Clock cycles in clock low count. Prescaled by CWGR.EXP. Used to time TLOW, TBUF. 31 30 29 28 27 26 25 24 - EXP DATA 23 22 21 20 19 18 17 16 STASTO 15 14 13 12 11 10 9 8 HIGH 76543210 LOW f PRESCALER f CLK_TWIM 2  EXP 1 + = ------------------------- 546 32142D–06/2013 ATUC64/128/256L3/4U 22.9.3 SMBus Timing Register Name: SMBTR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • EXP: SMBus Timeout Clock Prescaler Used to specify how to prescale the TIM and TLOWM counters in SMBTR. Counters are prescaled according to the following formula • THMAX: Clock High Maximum Cycles Clock cycles in clock high maximum count. Prescaled by SMBTR.EXP. Used for bus free detection. Used to time THIGH:MAX. NOTE: Uses the prescaler specified by CWGR, NOT the prescaler specified by SMBTR. • TLOWM: Master Clock Stretch Maximum Cycles Clock cycles in master maximum clock stretch count. Prescaled by SMBTR.EXP. Used to time TLOW:MEXT • TLOWS: Slave Clock Stretch Maximum Cycles Clock cycles in slave maximum clock stretch count. Prescaled by SMBTR.EXP. Used to time TLOW:SEXT. 31 30 29 28 27 26 25 24 EXP - - - - 23 22 21 20 19 18 17 16 THMAX 15 14 13 12 11 10 9 8 TLOWM 76543210 TLOWS f prescaled SMBus  f CLKTWIM 2  EXP + 1 = ------------------------ 547 32142D–06/2013 ATUC64/128/256L3/4U 22.9.4 Command Register Name: CMDR Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • ACKLAST: ACK Last Master RX Byte 0: Causes the last byte in master receive mode (when NBYTES has reached 0) to be NACKed. This is the standard way of ending a master receiver transfer. 1: Causes the last byte in master receive mode (when NBYTES has reached 0) to be ACKed. Used for performing linked transfers in master receiver mode with no STOP or REPEATED START between the subtransfers. This is needed when more than 255 bytes are to be received in one single transmission. • PECEN: Packet Error Checking Enable 0: Causes the transfer not to use PEC byte verification. The PEC LFSR is still updated for every bit transmitted or received. Must be used if SMBus mode is disabled. 1: Causes the transfer to use PEC. PEC byte generation (if master transmitter) or PEC byte verification (if master receiver) will be performed. • NBYTES: Number of Data Bytes in Transfer The number of data bytes in the transfer. After the specified number of bytes have been transferred, a STOP condition is transmitted if CMDR.STOP is one. In SMBus mode, if PEC is used, NBYTES includes the PEC byte, i.e. there are NBYTES-1 data bytes and a PEC byte. • VALID: CMDR Valid 0: Indicates that CMDR does not contain a valid command. 1: Indicates that CMDR contains a valid command. This bit is cleared when the command is finished. • STOP: Send STOP Condition 0: Do not transmit a STOP condition after the data bytes have been transmitted. 1: Transmit a STOP condition after the data bytes have been transmitted. • START: Send START Condition 0: The transfer in CMDR should not commence with a START or REPEATED START condition. 1: The transfer in CMDR should commence with a START or REPEATED START condition. If the bus is free when the command is executed, a START condition is used. If the bus is busy, a REPEATED START is used. • REPSAME: Transfer is to Same Address as Previous Address Only used in 10-bit addressing mode, always write to 0 in 7-bit addressing mode. 31 30 29 28 27 26 25 24 - - - - ACKLAST PECEN 23 22 21 20 19 18 17 16 NBYTES 15 14 13 12 11 10 9 8 VALID STOP START REPSAME TENBIT SADR[9:7] 76543210 SADR[6:0] READ 548 32142D–06/2013 ATUC64/128/256L3/4U Write this bit to one if the command in CMDR performs a repeated start to the same slave address as addressed in the previous transfer in order to enter master receiver mode. Write this bit to zero otherwise. • TENBIT: Ten Bit Addressing Mode 0: Use 7-bit addressing mode. 1: Use 10-bit addressing mode. Must not be used when the TWIM is in SMBus mode. • SADR: Slave Address Address of the slave involved in the transfer. Bits 9-7 are don’t care if 7-bit addressing is used. • READ: Transfer Direction 0: Allow the master to transmit data. 1: Allow the master to receive data. 549 32142D–06/2013 ATUC64/128/256L3/4U 22.9.5 Next Command Register Name: NCMDR Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 This register is identical to CMDR. When the VALID bit in CMDR becomes 0, the content of NCMDR is copied into CMDR, clearing the VALID bit in NCMDR. If the VALID bit in CMDR is cleared when NCMDR is written, the content is copied immediately. 31 30 29 28 27 26 25 24 - - - - ACKLAST PECEN 23 22 21 20 19 18 17 16 NBYTES 15 14 13 12 11 10 9 8 VALID STOP START REPSAME TENBIT SADR[9:7] 76543210 SADR[6:0] READ 550 32142D–06/2013 ATUC64/128/256L3/4U 22.9.6 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • RXDATA: Received Data When the RXRDY bit in the Status Register (SR) is one, this field contains a byte received from the TWI bus. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 551 32142D–06/2013 ATUC64/128/256L3/4U 22.9.7 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 • TXDATA: Data to Transmit Write data to be transferred on the TWI bus here. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 552 32142D–06/2013 ATUC64/128/256L3/4U 22.9.8 Status Register Name: SR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000002 • MENB: Master Interface Enable 0: Master interface is disabled. 1: Master interface is enabled. • STOP: Stop Request Accepted This bit is one when a STOP request caused by writing a one to CR.STOP has been accepted, and transfer has stopped. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • PECERR: PEC Error This bit is one when a SMBus PEC error occurred. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • TOUT: Timeout This bit is one when a SMBus timeout occurred. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • SMBALERT: SMBus Alert This bit is one when an SMBus Alert was received. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • ARBLST: Arbitration Lost This bit is one when the actual state of the SDA line did not correspond to the data driven onto it, indicating a higher-priority transmission in progress by a different master. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • DNAK: NAK in Data Phase Received This bit is one when no ACK was received form slave during data transmission. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • ANAK: NAK in Address Phase Received This bit is one when no ACK was received from slave during address phase This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • BUSFREE: Two-wire Bus is Free This bit is one when activity has completed on the two-wire bus. Otherwise, this bit is cleared. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - MENB 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 553 32142D–06/2013 ATUC64/128/256L3/4U • IDLE: Master Interface is Idle This bit is one when no command is in progress, and no command waiting to be issued. Otherwise, this bit is cleared. • CCOMP: Command Complete This bit is one when the current command has completed successfully. This bit is zero if the command failed due to conditions such as a NAK receved from slave. This bit is cleared by writing 1 to the corresponding bit in the Status Clear Register (SCR). • CRDY: Ready for More Commands This bit is one when CMDR and/or NCMDR is ready to receive one or more commands. This bit is cleared when this is no longer true. • TXRDY: THR Data Ready This bit is one when THR is ready for one or more data bytes. This bit is cleared when this is no longer true (i.e. THR is full or transmission has stopped). • RXRDY: RHR Data Ready This bit is one when RX data are ready to be read from RHR. This bit is cleared when this is no longer true. 554 32142D–06/2013 ATUC64/128/256L3/4U 22.9.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 555 32142D–06/2013 ATUC64/128/256L3/4U 22.9.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 556 32142D–06/2013 ATUC64/128/256L3/4U 22.9.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - BUSFREE IDLE CCOMP CRDY TXRDY RXRDY 557 32142D–06/2013 ATUC64/128/256L3/4U 22.9.12 Status Clear Register Name: SCR Access Type : Write-only Offset: 0x2C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - STOP PECERR TOUT SMBALERT ARBLST DNAK ANAK 76543210 - - - - CCOMP - - - 558 32142D–06/2013 ATUC64/128/256L3/4U 22.9.13 Parameter Register (PR) Name: PR Access Type: Read-only Offset: 0x30 Reset Value: - 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 559 32142D–06/2013 ATUC64/128/256L3/4U 22.9.14 Version Register (VR) Name: VR Access Type: Read-only Offset: 0x34 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION [11:8] 76543210 VERSION [7:0] 560 32142D–06/2013 ATUC64/128/256L3/4U 22.10 Module Configuration The specific configuration for each TWIM instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 22-7. Module Clock Name Module Name Clock Name Description TWIM0 CLK_TWIM0 Clock for the TWIM0 bus interface TWIM1 CLK_TWIM1 Clock for the TWIM1 bus interface Table 22-8. Register Reset Values Register Reset Value VERSION 0x00000110 PARAMETER 0x00000000 561 32142D–06/2013 ATUC64/128/256L3/4U 23. Two-wire Slave Interface (TWIS) Rev.: 1.2.0.1 23.1 Features • Compatible with I²C standard – Transfer speeds of 100 and 400 kbit/s – 7 and 10-bit and General Call addressing • Compatible with SMBus standard – Hardware Packet Error Checking (CRC) generation and verification with ACK response – SMBALERT interface – 25 ms clock low timeout delay – 25 ms slave cumulative clock low extend time • Compatible with PMBus • DMA interface for reducing CPU load • Arbitrary transfer lengths, including 0 data bytes • Optional clock stretching if transmit or receive buffers not ready for data transfer • 32-bit Peripheral Bus interface for configuration of the interface 23.2 Overview The Atmel Two-wire Slave Interface (TWIS) interconnects components on a unique two-wire bus, made up of one clock line and one data line with speeds of up to 400 kbit/s, based on a byte-oriented transfer format. It can be used with any Atmel Two-wire Interface bus, I²C, or SMBus-compatible master. The TWIS is always a bus slave and can transfer sequential or single bytes. Below, Table 23-1 lists the compatibility level of the Atmel Two-wire Slave Interface and a full I²C compatible device. Note: 1. START + b000000001 + Ack + Sr Table 23-1. Atmel TWIS Compatibility with I²C Standard I²C Standard Atmel TWIS Standard-mode (100 kbit/s) Supported Fast-mode (400 kbit/s) Supported 7 or 10 bits Slave Addressing Supported START BYTE(1) Not Supported Repeated Start (Sr) Condition Supported ACK and NAK Management Supported Slope control and input filtering (Fast mode) Supported Clock stretching Supported 562 32142D–06/2013 ATUC64/128/256L3/4U Below, Table 23-2 lists the compatibility level of the Atmel Two-wire Slave Interface and a full SMBus compatible device. 23.3 List of Abbreviations 23.4 Block Diagram Figure 23-1. Block Diagram Table 23-2. Atmel TWIS Compatibility with SMBus Standard SMBus Standard Atmel TWIS Bus Timeouts Supported Address Resolution Protocol Supported Alert Supported Packet Error Checking Supported Table 23-3. Abbreviations Abbreviation Description TWI Two-wire Interface A Acknowledge NA Non Acknowledge P Stop S Start Sr Repeated Start SADR Slave Address ADR Any address except SADR R Read W Write Peripheral Bus Bridge Two-wire Interface I/O Controller TWCK TWD Interrupt Controller TWI Interrupt Power Manager CLK_TWIS TWALM 563 32142D–06/2013 ATUC64/128/256L3/4U 23.5 Application Block Diagram Figure 23-2. Application Block Diagram 23.6 I/O Lines Description 23.7 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 23.7.1 I/O Lines TWDand TWCK are bidirectional lines, connected to a positive supply voltage via a current source or pull-up resistor (see Figure 23-5 on page 565). When the bus is free, both lines are high. The output stages of devices connected to the bus must have an open-drain or open-collector to perform the wired-AND function. TWALM is used to implement the optional SMBus SMBALERT signal. TWALM, TWD, and TWCK pins may be multiplexed with I/O Controller lines. To enable the TWIS, the user must perform the following steps: • Program the I/O Controller to: – Dedicate TWD, TWCK, and optionally TWALM as peripheral lines. – Define TWD, TWCK, and optionally TWALM as open-drain. Host with TWI Interface TWD TWCK Atmel TWI serial EEPROM I²C RTC I²C LCD controller Slave 1 Slave 2 Slave 3 VDD I²C temp. sensor Slave 4 Rp: Pull up value as given by the I²C Standard Rp Rp Table 23-4. I/O Lines Description Pin Name Pin Description Type TWD Two-wire Serial Data Input/Output TWCK Two-wire Serial Clock Input/Output TWALM SMBus SMBALERT Input/Output 564 32142D–06/2013 ATUC64/128/256L3/4U 23.7.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TWIS, the TWIS will stop functioning and resume operation after the system wakes up from sleep mode. The TWIS is able to wake the system from sleep mode upon address match, see Section 23.8.8 on page 572. 23.7.3 Clocks The clock for the TWIS bus interface (CLK_TWIS) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TWIS before disabling the clock, to avoid freezing the TWIS in an undefined state. 23.7.4 DMA The TWIS DMA handshake interface is connected to the Peripheral DMA Controller. Using the TWIS DMA functionality requires the Peripheral DMA Controller to be programmed after setting up the TWIS. 23.7.5 Interrupts The TWIS interrupt request lines are connected to the interrupt controller. Using the TWIS interrupts requires the interrupt controller to be programmed first. 23.7.6 Debug Operation When an external debugger forces the CPU into debug mode, the TWIS continues normal operation. If the TWIS is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 23.8 Functional Description 23.8.1 Transfer Format The data put on the TWD line must be 8 bits long. Data is transferred MSB first; each byte must be followed by an acknowledgement. The number of bytes per transfer is unlimited (see Figure 23-4 on page 565). Each transfer begins with a START condition and terminates with a STOP condition (see Figure 23-3). • A high-to-low transition on the TWD line while TWCK is high defines the START condition. • A low-to-high transition on the TWD line while TWCK is high defines a STOP condition. Figure 23-3. START and STOP Conditions TWD TWCK Start Stop 565 32142D–06/2013 ATUC64/128/256L3/4U Figure 23-4. Transfer Format 23.8.2 Operation The TWIS has two modes of operation: • Slave transmitter mode • Slave receiver mode A master is a device which starts and stops a transfer and generates the TWCK clock. A slave is assigned an address and responds to requests from the master. These modes are described in the following chapters. Figure 23-5. Typical Application Block Diagram 23.8.2.1 Bus Timing The Timing Register (TR) is used to control the timing of bus signals driven by the TWIS. TR describes bus timings as a function of cycles of the prescaled CLK_TWIS. The clock prescaling can be selected through TR.EXP. TR has the following fields: TLOWS: Prescaled clock cycles used to time SMBUS timeout TLOW:SEXT. TWD TWCK Start Address R/W Ack Data Ack Data Ack Stop Host with TWI Interface TWD TWCK Atmel TWI Serial EEPROM I²C RTC I²C LCD Controller Slave 1 Slave 2 Slave 3 VDD I²C Temp. Sensor Slave 4 Rp: Pull up value as given by the I²C Standard Rp Rp fPRESCALED f CLK_TWIS 2  EXP 1 + = ------------------------ 566 32142D–06/2013 ATUC64/128/256L3/4U TTOUT: Prescaled clock cycles used to time SMBUS timeout TTIMEOUT. SUDAT: Non-prescaled clock cycles for data setup and hold count. Used to time TSU_DAT. EXP: Specifies the clock prescaler setting used for the SMBUS timeouts. Figure 23-6. Bus Timing Diagram 23.8.2.2 Setting Up and Performing a Transfer Operation of the TWIS is mainly controlled by the Control Register (CR). The following list presents the main steps in a typical communication: 3. Before any transfers can be performed, bus timings must be configured by writing to the Timing Register (TR).If the Peripheral DMA Controller is to be used for the transfers, it must be set up. 4. The Control Register (CR) must be configured with information such as the slave address, SMBus mode, Packet Error Checking (PEC), number of bytes to transfer, and which addresses to match. The interrupt system can be set up to generate interrupt request on specific events or error conditions, for example when a byte has been received. The NBYTES register is only used in SMBus mode, when PEC is enabled. In I²C mode or in SMBus mode when PEC is disabled, the NBYTES register is not used, and should be written to zero. NBYTES is updated by hardware, so in order to avoid hazards, software updates of NBYTES can only be done through writes to the NBYTES register. 23.8.2.3 Address Matching The TWIS can be set up to match several different addresses. More than one address match may be enabled simultaneously, allowing the TWIS to be assigned to several addresses. The address matching phase is initiated after a START or REPEATED START condition. When the TWIS receives an address that generates an address match, an ACK is automatically returned to the master. S t HD:STA t LOW t SU:DAT t HIGH t HD:DAT t LOW P t SU:STO Sr t SU:STA t SU:DAT 567 32142D–06/2013 ATUC64/128/256L3/4U In I²C mode: • The address in CR.ADR is checked for address match if CR.SMATCH is one. • The General Call address is checked for address match if CR.GCMATCH is one. In SMBus mode: • The address in CR.ADR is checked for address match if CR.SMATCH is one. • The Alert Response Address is checked for address match if CR.SMAL is one. • The Default Address is checked for address match if CR.SMDA is one. • The Host Header Address is checked for address match if CR.SMHH is one. 23.8.2.4 Clock Stretching Any slave or bus master taking part in a transfer may extend the TWCK low period at any time. The TWIS may extend the TWCK low period after each byte transfer if CR.STREN is one and: • Module is in slave transmitter mode, data should be transmitted, but THR is empty, or • Module is in slave receiver mode, a byte has been received and placed into the internal shifter, but the Receive Holding Register (RHR) is full, or • Stretch-on-address-match bit CR.SOAM=1 and slave was addressed. Bus clock remains stretched until all address match bits in the Status Register (SR) have been cleared. If CR.STREN is zero and: • Module is in slave transmitter mode, data should be transmitted but THR is empty: Transmit the value present in THR (the last transmitted byte or reset value), and set SR.URUN. • Module is in slave receiver mode, a byte has been received and placed into the internal shifter, but RHR is full: Discard the received byte and set SR.ORUN. 23.8.2.5 Bus Errors If a bus error (misplaced START or STOP) condition is detected, the SR.BUSERR bit is set and the TWIS waits for a new START condition. 23.8.3 Slave Transmitter Mode If the TWIS matches an address in which the R/W bit in the TWI address phase transfer is set, it will enter slave transmitter mode and set the SR.TRA bit (note that SR.TRA is set one CLK_TWIS cycle after the relevant address match bit in the same register is set). After the address phase, the following actions are performed: 1. If SMBus mode and PEC is used, NBYTES must be set up with the number of bytes to transmit. This is necessary in order to know when to transmit the PEC byte. NBYTES can also be used to count the number of bytes received if using DMA. 2. Byte to transmit depends on I²C/SMBus mode and CR.PEC: – If in I²C mode or CR.PEC is zero or NBYTES is non-zero: The TWIS waits until THR contains a valid data byte, possibly stretching the low period of TWCK. After THR contains a valid data byte, the data byte is transferred to a shifter, and then SR.TXRDY is changed to one because the THR is empty again. – SMBus mode and CR.PEC is one: If NBYTES is zero, the generated PEC byte is automatically transmitted instead of a data byte from THR. TWCK will not be stretched by the TWIS. 3. The data byte in the shifter is transmitted. 568 32142D–06/2013 ATUC64/128/256L3/4U 4. NBYTES is updated. If CR.CUP is one, NBYTES is incremented, otherwise NBYTES is decremented. 5. After each data byte has been transmitted, the master transmits an ACK (Acknowledge) or NAK (Not Acknowledge) bit. If a NAK bit is received by the TWIS, the SR.NAK bit is set. Note that this is done two CLK_TWIS cycles after TWCK has been sampled by the TWIS to be HIGH (see Figure 23-9). The NAK indicates that the transfer is finished, and the TWIS will wait for a STOP or REPEATED START. If an ACK bit is received, the SR.NAK bit remains LOW. The ACK indicates that more data should be transmitted, jump to step 2. At the end of the ACK/NAK clock cycle, the Byte Transfer Finished (SR.BTF) bit is set. Note that this is done two CLK_TWIS cycles after TWCK has been sampled by the TWIS to be LOW (see Figure 23-9). Also note that in the event that SR.NAK bit is set, it must not be cleared before the SR.BTF bit is set to ensure correct TWIS behavior. 6. If STOP is received, SR.TCOMP and SR.STO will be set. 7. If REPEATED START is received, SR.REP will be set. The TWI transfers require the receiver to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the slave releases the data line (HIGH), enabling the master to pull it down in order to generate the acknowledge. The slave polls the data line during this clock pulse and sets the NAK bit in SR if the master does not acknowledge the data byte. A NAK means that the master does not wish to receive additional data bytes. As with the other status bits, an interrupt can be generated if enabled in the Interrupt Enable Register (IER). SR.TXRDY is used as Transmit Ready for the Peripheral DMA Controller transmit channel. The end of the complete transfer is marked by the SR.TCOMP bit changing from zero to one. See Figure 23-7 and Figure 23-8. Figure 23-7. Slave Transmitter with One Data Byte TCOMP TXRDY Write THR (DATA) STOP sent by master TWD S DADR R P A DATA N NBYTES set to 1 569 32142D–06/2013 ATUC64/128/256L3/4U Figure 23-8. Slave Transmitter with Multiple Data Bytes Figure 23-9. Timing Relationship between TWCK, SR.NAK, and SR.BTF 23.8.4 Slave Receiver Mode If the TWIS matches an address in which the R/W bit in the TWI address phase transfer is cleared, it will enter slave receiver mode and clear SR.TRA (note that SR.TRA is cleared one CLK_TWIS cycle after the relevant address match bit in the same register is set). After the address phase, the following is repeated: 1. If SMBus mode and PEC is used, NBYTES must be set up with the number of bytes to receive. This is necessary in order to know which of the received bytes is the PEC byte. NBYTES can also be used to count the number of bytes received if using DMA. 2. Receive a byte. Set SR.BTF when done. 3. Update NBYTES. If CR.CUP is written to one, NBYTES is incremented, otherwise NBYTES is decremented. NBYTES is usually configured to count downwards if PEC is used. 4. After a data byte has been received, the slave transmits an ACK or NAK bit. For ordinary data bytes, the CR.ACK field controls if an ACK or NAK should be returned. If PEC is enabled and the last byte received was a PEC byte (indicated by NBYTES equal to zero), The TWIS will automatically return an ACK if the PEC value was correct, otherwise a NAK will be returned. 5. If STOP is received, SR.TCOMP will be set. 6. If REPEATED START is received, SR.REP will be set. The TWI transfers require the receiver to acknowledge each received data byte. During the acknowledge clock pulse (9th pulse), the master releases the data line (HIGH), enabling the S DADR R DATA n+5 A P A DATA n A DATA n+m N TCOMP TXRDY Write THR (Data n) NBYTES set to m STOP sent by master TWD Write THR (Data n+1) Write THR (Data n+m) Last data sent DATA (LSB) N P TWCK SR.NAK SR.BTF t1 t1 t1: (CLK_TWIS period) x 2 TWD 570 32142D–06/2013 ATUC64/128/256L3/4U slave to pull it down in order to generate the acknowledge. The master polls the data line during this clock pulse. The SR.RXRDY bit indicates that a data byte is available in the RHR. The RXRDY bit is also used as Receive Ready for the Peripheral DMA Controller receive channel. Figure 23-10. Slave Receiver with One Data Byte Figure 23-11. Slave Receiver with Multiple Data Bytes 23.8.5 Interactive ACKing Received Data Bytes When implementing a register interface over TWI, it may sometimes be necessary or just useful to report reads and writes to invalid register addresses by sending a NAK to the host. To be able to do this, one must first receive the register address from the TWI bus, and then tell the TWIS whether to ACK or NAK it. In normal operation of the TWIS, this is not possible because the controller will automatically ACK the byte at about the same time as the RXRDY bit changes from zero to one. Writing a one to the Stretch on Data Byte Received bit (CR.SODR) will stretch the clock allowing the user to update CR.ACK bit before returning the desired value. After the last bit in the data byte is received, the TWI bus clock is stretched, the received data byte is transferred to the RHR register, and SR.BTF is set. At this time, the user can examine the received byte and write the desired ACK or NACK value to CR.ACK. When the user clears SR.BTF, the desired ACK value is transferred on the TWI bus. This makes it possible to look at the byte received, determine if it is valid, and then decide to ACK or NAK it. 23.8.6 Using the Peripheral DMA Controller The use of the Peripheral DMA Controller significantly reduces the CPU load. The user can set up ring buffers for the Peripheral DMA Controller, containing data to transmit or free buffer space to place received data. By initializing NBYTES to zero before a transfer, and writing a one to CR.CUP, NBYTES is incremented by one each time a data has been transmitted or received. This allows the user to detect how much data was actually transferred by the DMA system. S DADR W DATA A P A TCOMP RXRDY Read RHR TWD TWD S DADR W DATA n A A A DATA (n+1) A DATA (n+m) DATA (n+m)-1 P A TCOMP RXRDY Read RHR DATA n Read RHR DATA (n+1) Read RHR DATA (n+m)-1 Read RHR DATA (n+m) 571 32142D–06/2013 ATUC64/128/256L3/4U To assure correct behavior, respect the following programming sequences: 23.8.6.1 Data Transmit with the Peripheral DMA Controller 1. Initialize the transmit Peripheral DMA Controller (memory pointers, size, etc.). 2. Configure the TWIS (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to transmit. 4. Wait for the Peripheral DMA Controller end-of-transmit flag. 5. Disable the Peripheral DMA Controller. 23.8.6.2 Data Receive with the Peripheral DMA Controller 1. Initialize the receive Peripheral DMA Controller (memory pointers, size - 1, etc.). 2. Configure the TWIS (ADR, NBYTES, etc.). 3. Start the transfer by enabling the Peripheral DMA Controller to receive. 4. Wait for the Peripheral DMA Controller end-of-receive flag. 5. Disable the Peripheral DMA Controller. 23.8.7 SMBus Mode SMBus mode is enabled by writing a one to the SMBus Mode Enable (SMEN) bit in CR. SMBus mode operation is similar to I²C operation with the following exceptions: • Only 7-bit addressing can be used. • The SMBus standard describes a set of timeout values to ensure progress and throughput on the bus. These timeout values must be written to TR. • Transmissions can optionally include a CRC byte, called Packet Error Check (PEC). • A dedicated bus line, SMBALERT, allows a slave to get a master’s attention. • A set of addresses have been reserved for protocol handling, such as Alert Response Address (ARA) and Host Header (HH) Address. Address matching on these addresses can be enabled by configuring CR appropriately. 23.8.7.1 Packet Error Checking (PEC) Each SMBus transfer can optionally end with a CRC byte, called the PEC byte. Writing a one to the Packet Error Checking Enable (PECEN) bit in CR enables automatic PEC handling in the current transfer. The PEC generator is always updated on every bit transmitted or received, so that PEC handling on following linked transfers will be correct. In slave receiver mode, the master calculates a PEC value and transmits it to the slave after all data bytes have been transmitted. Upon reception of this PEC byte, the slave will compare it to the PEC value it has computed itself. If the values match, the data was received correctly, and the slave will return an ACK to the master. If the PEC values differ, data was corrupted, and the slave will return a NAK value. The SR.SMBPECERR bit is set automatically if a PEC error occurred. In slave transmitter mode, the slave calculates a PEC value and transmits it to the master after all data bytes have been transmitted. Upon reception of this PEC byte, the master will compare it to the PEC value it has computed itself. If the values match, the data was received correctly. If the PEC values differ, data was corrupted, and the master must take appropriate action. The PEC byte is automatically inserted in a slave transmitter transmission if PEC enabled when NBYTES reaches zero. The PEC byte is identified in a slave receiver transmission if PEC 572 32142D–06/2013 ATUC64/128/256L3/4U enabled when NBYTES reaches zero. NBYTES must therefore be set to the total number of data bytes in the transmission, including the PEC byte. 23.8.7.2 Timeouts The Timing Register (TR) configures the SMBus timeout values. If a timeout occurs, the slave will leave the bus. The SR.SMBTOUT bit is also set. 23.8.7.3 SMBALERT A slave can get the master’s attention by pulling the SMBALERT line low. This is done by writing a one to the SMBus Alert (SMBALERT) bit in CR. This will also enable address match on the Alert Response Address (ARA). 23.8.8 Wakeup from Sleep Modes by TWI Address Match The TWIS is able to wake the device up from a sleep mode upon an address match, including sleep modes where CLK_TWIS is stopped. After detecting the START condition on the bus, The TWIS will stretch TWCK until CLK_TWIS has started. The time required for starting CLK_TWIS depends on which sleep mode the device is in. After CLK_TWIS has started, the TWIS releases its TWCK stretching and receives one byte of data on the bus. At this time, only a limited part of the device, including the TWIS, receives a clock, thus saving power. The TWIS goes on to receive the slave address. If the address phase causes a TWIS address match, the entire device is wakened and normal TWIS address matching actions are performed. Normal TWI transfer then follows. If the TWIS is not addressed, CLK_TWIS is automatically stopped and the device returns to its original sleep mode. 23.8.9 Identifying Bus Events This chapter lists the different bus events, and how these affects the bits in the TWIS registers. This is intended to help writing drivers for the TWIS. Table 23-5. Bus Events Event Effect Slave transmitter has sent a data byte SR.THR is cleared. SR.BTF is set. The value of the ACK bit sent immediately after the data byte is given by CR.ACK. Slave receiver has received a data byte SR.RHR is set. SR.BTF is set. SR.NAK updated according to value of ACK bit received from master. Start+Sadr on bus, but address is to another slave None. Start+Sadr on bus, current slave is addressed, but address match enable bit in CR is not set None. Start+Sadr on bus, current slave is addressed, corresponding address match enable bit in CR set Correct address match bit in SR is set. SR.TRA updated according to transfer direction (updating is done one CLK_TWIS cycle after address match bit is set) Slave enters appropriate transfer direction mode and data transfer can commence. 573 32142D–06/2013 ATUC64/128/256L3/4U Start+Sadr on bus, current slave is addressed, corresponding address match enable bit in CR set, SR.STREN and SR.SOAM are set. Correct address match bit in SR is set. SR.TRA updated according to transfer direction (updating is done one CLK_TWIS cycle after address match bit is set). Slave stretches TWCK immediately after transmitting the address ACK bit. TWCK remains stretched until all address match bits in SR have been cleared. Slave enters appropriate transfer direction mode and data transfer can commence. Repeated Start received after being addressed SR.REP set. SR.TCOMP unchanged. Stop received after being addressed SR.STO set. SR.TCOMP set. Start, Repeated Start, or Stop received in illegal position on bus SR.BUSERR set. SR.STO and SR.TCOMP may or may not be set depending on the exact position of an illegal stop. Data is to be received in slave receiver mode, SR.STREN is set, and RHR is full TWCK is stretched until RHR has been read. Data is to be transmitted in slave receiver mode, SR.STREN is set, and THR is empty TWCK is stretched until THR has been written. Data is to be received in slave receiver mode, SR.STREN is cleared, and RHR is full TWCK is not stretched, read data is discarded. SR.ORUN is set. Data is to be transmitted in slave receiver mode, SR.STREN is cleared, and THR is empty TWCK is not stretched, previous contents of THR is written to bus. SR.URUN is set. SMBus timeout received SR.SMBTOUT is set. TWCK and TWD are immediately released. Slave transmitter in SMBus PEC mode has transmitted a PEC byte, that was not identical to the PEC calculated by the master receiver. Master receiver will transmit a NAK as usual after the last byte of a master receiver transfer. Master receiver will retry the transfer at a later time. Slave receiver discovers SMBus PEC Error SR.SMBPECERR is set. NAK returned after the data byte. Table 23-5. Bus Events Event Effect 574 32142D–06/2013 ATUC64/128/256L3/4U 23.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 23-6. TWIS Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 NBYTES Register NBYTES Read/Write 0x00000000 0x08 Timing Register TR Read/Write 0x00000000 0x0C Receive Holding Register RHR Read-only 0x00000000 0x10 Transmit Holding Register THR Write-only 0x00000000 0x14 Packet Error Check Register PECR Read-only 0x00000000 0x18 Status Register SR Read-only 0x00000002 0x1C Interrupt Enable Register IER Write-only 0x00000000 0x20 Interrupt Disable Register IDR Write-only 0x00000000 0x24 Interrupt Mask Register IMR Read-only 0x00000000 0x28 Status Clear Register SCR Write-only 0x00000000 0x2C Parameter Register PR Read-only -(1) 0x30 Version Register VR Read-only -(1) 575 32142D–06/2013 ATUC64/128/256L3/4U 23.9.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • TENBIT: Ten Bit Address Match 0: Disables Ten Bit Address Match. 1: Enables Ten Bit Address Match. • ADR: Slave Address Slave address used in slave address match. Bits 9:0 are used if in 10-bit mode, bits 6:0 otherwise. • SODR: Stretch Clock on Data Byte Reception 0: Does not stretch bus clock immediately before ACKing a received data byte. 1: Stretches bus clock immediately before ACKing a received data byte. • SOAM: Stretch Clock on Address Match 0: Does not stretch bus clock after address match. 1: Stretches bus clock after address match. • CUP: NBYTES Count Up 0: Causes NBYTES to count down (decrement) per byte transferred. 1: Causes NBYTES to count up (increment) per byte transferred. • ACK: Slave Receiver Data Phase ACK Value 0: Causes a low value to be returned in the ACK cycle of the data phase in slave receiver mode. 1: Causes a high value to be returned in the ACK cycle of the data phase in slave receiver mode. • PECEN: Packet Error Checking Enable 0: Disables SMBus PEC (CRC) generation and check. 1: Enables SMBus PEC (CRC) generation and check. • SMHH: SMBus Host Header 0: Causes the TWIS not to acknowledge the SMBus Host Header. 1: Causes the TWIS to acknowledge the SMBus Host Header. • SMDA: SMBus Default Address 0: Causes the TWIS not to acknowledge the SMBus Default Address. 1: Causes the TWIS to acknowledge the SMBus Default Address. • SMBALERT: SMBus Alert 0: Causes the TWIS to release the SMBALERT line and not to acknowledge the SMBus Alert Response Address (ARA). 1: Causes the TWIS to pull down the SMBALERT line and to acknowledge the SMBus Alert Response Address (ARA). 31 30 29 28 27 26 25 24 - - - - - TENBIT ADR[9:8] 23 22 21 20 19 18 17 16 ADR[7:0] 15 14 13 12 11 10 9 8 SODR SOAM CUP ACK PECEN SMHH SMDA SMBALERT 76543210 SWRST - - STREN GCMATCH SMATCH SMEN SEN 576 32142D–06/2013 ATUC64/128/256L3/4U • SWRST: Software Reset This bit will always read as 0. Writing a zero to this bit has no effect. Writing a one to this bit resets the TWIS. • STREN: Clock Stretch Enable 0: Disables clock stretching if RHR/THR buffer full/empty. May cause over/underrun. 1: Enables clock stretching if RHR/THR buffer full/empty. • GCMATCH: General Call Address Match 0: Causes the TWIS not to acknowledge the General Call Address. 1: Causes the TWIS to acknowledge the General Call Address. • SMATCH: Slave Address Match 0: Causes the TWIS not to acknowledge the Slave Address. 1: Causes the TWIS to acknowledge the Slave Address. • SMEN: SMBus Mode Enable 0: Disables SMBus mode. 1: Enables SMBus mode. • SEN: Slave Enable 0: Disables the slave interface. 1: Enables the slave interface. 577 32142D–06/2013 ATUC64/128/256L3/4U 23.9.2 NBYTES Register Name: NBYTES Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • NBYTES: Number of Bytes to Transfer Writing to this field updates the NBYTES counter. The field can also be read to learn the progress of the transfer. NBYTES can be incremented or decremented automatically by hardware. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 NBYTES 578 32142D–06/2013 ATUC64/128/256L3/4U 23.9.3 Timing Register Name: TR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • EXP: Clock Prescaler Used to specify how to prescale the SMBus TLOWS counter. The counter is prescaled according to the following formula: • SUDAT: Data Setup Cycles Non-prescaled clock cycles for data setup count. Used to time TSU_DAT. Data is driven SUDAT cycles after TWCK low detected. This timing is used for timing the ACK/NAK bits, and any data bits driven in slave transmitter mode. • TTOUT: SMBus TTIMEOUT Cycles Prescaled clock cycles used to time SMBus TTIMEOUT. • TLOWS: SMBus TLOW:SEXT Cycles Prescaled clock cycles used to time SMBus TLOW:SEXT. 31 30 29 28 27 26 25 24 EXP - - - - 23 22 21 20 19 18 17 16 SUDAT 15 14 13 12 11 10 9 8 TTOUT 76543210 TLOWS f PRESCALED f CLK_TWIS 2  EXP 1 + = ------------------------ 579 32142D–06/2013 ATUC64/128/256L3/4U 23.9.4 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x0C Reset Value: 0x00000000 • RXDATA: Received Data Byte When the RXRDY bit in the Status Register (SR) is one, this field contains a byte received from the TWI bus. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 580 32142D–06/2013 ATUC64/128/256L3/4U 23.9.5 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 • TXDATA: Data Byte to Transmit Write data to be transferred on the TWI bus here. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 581 32142D–06/2013 ATUC64/128/256L3/4U 23.9.6 Packet Error Check Register Name: PECR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • PEC: Calculated PEC Value The calculated PEC value. Updated automatically by hardware after each byte has been transferred. Reset by hardware after a STOP condition. Provided if the user manually wishes to control when the PEC byte is transmitted, or wishes to access the PEC value for other reasons. In ordinary operation, the PEC handling is done automatically by hardware. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 PEC 582 32142D–06/2013 ATUC64/128/256L3/4U 23.9.7 Status Register Name: SR Access Type: Read-only Offset: 0x18 Reset Value: 0x000000002 • BTF: Byte Transfer Finished This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when byte transfer has completed. • REP: Repeated Start Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a REPEATED START condition is received. • STO: Stop Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the STOP condition is received. • SMBDAM: SMBus Default Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Default Address. • SMBHHM: SMBus Host Header Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Host Header Address. • SMBALERTM: SMBus Alert Response Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the SMBus Alert Response Address. • GCM: General Call Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the General Call Address. • SAM: Slave Address Match This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when the received address matched the Slave Address. • BUSERR: Bus Error This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a misplaced START or STOP condition has occurred. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN TRA - TCOMP SEN TXRDY RXRDY 583 32142D–06/2013 ATUC64/128/256L3/4U • SMBPECERR: SMBus PEC Error This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a SMBus PEC error has occurred. • SMBTOUT: SMBus Timeout This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a SMBus timeout has occurred. • NAK: NAK Received This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when a NAK was received from the master during slave transmitter operation. • ORUN: Overrun This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when an overrun has occurred in slave receiver mode. Can only occur if CR.STREN is zero. • URUN: Underrun This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when an underrun has occurred in slave transmitter mode. Can only occur if CR.STREN is zero. • TRA: Transmitter Mode 0: The slave is in slave receiver mode. 1: The slave is in slave transmitter mode. • TCOMP: Transmission Complete This bit is cleared when the corresponding bit in SCR is written to one. This bit is set when transmission is complete. Set after receiving a STOP after being addressed. • SEN: Slave Enabled 0: The slave interface is disabled. 1: The slave interface is enabled. • TXRDY: TX Buffer Ready 0: The TX buffer is full and should not be written to. 1: The TX buffer is empty, and can accept new data. • RXRDY: RX Buffer Ready 0: No RX data ready in RHR. 1: RX data is ready to be read from RHR. 584 32142D–06/2013 ATUC64/128/256L3/4U 23.9.8 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will write a one to the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 585 32142D–06/2013 ATUC64/128/256L3/4U 23.9.9 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 586 32142D–06/2013 ATUC64/128/256L3/4U 23.9.10 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x24 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - TXRDY RXRDY 587 32142D–06/2013 ATUC64/128/256L3/4U 23.9.11 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x28 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -- - ----- 23 22 21 20 19 18 17 16 BTF REP STO SMBDAM SMBHHM SMBALERTM GCM SAM 15 14 13 12 11 10 9 8 - BUSERR SMBPECERR SMBTOUT - - - NAK 76 5 43210 ORUN URUN - - TCOMP - - - 588 32142D–06/2013 ATUC64/128/256L3/4U 23.9.12 Parameter Register Name: PR Access Type: Read-only Offset: 0x2C Reset Value: - 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 589 32142D–06/2013 ATUC64/128/256L3/4U 23.9.13 Version Register (VR) Name: VR Access Type: Read-only Offset: 0x30 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION [11:8] 76543210 VERSION [7:0] 590 32142D–06/2013 ATUC64/128/256L3/4U 23.10 Module Configuration The specific configuration for each TWIS instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 23-7. Module Clock Name Module Name Clock Name Description TWIS0 CLK_TWIS0 Clock for the TWIS0 bus interface TWIS1 CLK_TWIS1 Clock for the TWIS1 bus interface Table 23-8. Register Reset Values Register Reset Value VERSION 0x00000120 PARAMETER 0x00000000 591 32142D–06/2013 ATUC64/128/256L3/4U 24. Inter-IC Sound Controller (IISC) Rev: 1.0.0.0 24.1 Features • Compliant with Inter-IC Sound (I2 S) bus specification • Master, slave, and controller modes: – Slave: data received/transmitted – Master: data received/transmitted and clocks generated – Controller: clocks generated • Individual enable and disable of receiver, transmitter, and clocks • Configurable clock generator common to receiver and transmitter: – Suitable for a wide range of sample frequencies (fs), including 32kHz, 44.1kHz, 48kHz, 88.2kHz, 96kHz, and 192kHz – 16fs to 1024fs Master Clock generated for external oversampling ADCs • Several data formats supported: – 32-, 24-, 20-, 18-, 16-, and 8-bit mono or stereo format – 16- and 8-bit compact stereo format, with left and right samples packed in the same word to reduce data transfers • DMA interfaces for receiver and transmitter to reduce processor overhead: – Either one DMA channel for both audio channels, or – One DMA channel per audio channel • Smart holding registers management to avoid audio channels mix after overrun or underrun 24.2 Overview The Inter-IC Sound Controller (IISC) provides a 5-wire, bidirectional, synchronous, digital audio link with external audio devices: ISDI, ISDO, IWS, ISCK, and IMCK pins. This controller is compliant with the Inter-IC Sound (I2 S) bus specification. The IISC consists of a Receiver, a Transmitter, and a common Clock Generator, that can be enabled separately, to provide Master, Slave, or Controller modes with Receiver, Transmitter, or both active. Peripheral DMA channels, separate for the Receiver and for the Transmitter, allow a continuous high bitrate data transfer without processor intervention to the following: • Audio CODECs in Master, Slave, or Controller mode • Stereo DAC or ADC through dedicated I2 S serial interface The IISC can use either a single DMA channel for both audio channels or one DMA channel per audio channel. The 8- and 16-bit compact stereo format allows reducing the required DMA bandwidth by transferring the left and right samples within the same data word. In Master Mode, the IISC allows outputting a 16 fs to 1024fs Master Clock, in order to provide an oversampling clock to an external audio codec or digital signal processor (DSP). 592 32142D–06/2013 ATUC64/128/256L3/4U 24.3 Block Diagram Figure 24-1. IISC Block Diagram 24.4 I/O Lines Description 24.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 24.5.1 I/O lines The IISC pins may be multiplexed with I/O Controller lines. The user must first program the I/O Controller to assign the desired IISC pins to their peripheral function. If the IISC I/O lines are not used by the application, they can be used for other purposes by the I/O Controller. It is required to enable only the IISC inputs and outputs actually in use. 24.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the IISC, the IISC will stop functioning and resume operation after the system wakes up from sleep mode.I/O Controller ISCK IWS ISDI ISDO IMCK Receiver Clocks Transmitter Peripheral Bus interface Generic clock PB Peripheral Bus Bridge Interrupt Controller SCIF Power Manager PB clock IRQ Peripheral DMA Controller Rx Tx IISC Table 24-1. I/O Lines Description Pin Name Pin Description Type IMCK Master Clock Output ISCK Serial Clock Input/Output IWS I2 S Word Select Input/Output ISDI Serial Data Input Input ISDO Serial Data Output Output 593 32142D–06/2013 ATUC64/128/256L3/4U 24.5.3 Clocks The clock for the IISC bus interface (CLK_IISC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the IISC before disabling the clock, to avoid freezing the IISC in an undefined state. One of the generic clocks is connected to the IISC. The generic clock (GCLK_IISC) can be set to a wide range of frequencies and clock sources. The GCLK_IISC must be enabled and configured before use. Refer to the module configuration section for details on the GCLK_IISC used for the IISC. The frequency for this clock has to be set as described in Table. 24.5.4 DMA The IISC DMA handshake interfaces are connected to the Peripheral DMA Controller. Using the IISC DMA functionality requires the Peripheral DMA Controller to be programmed first. 24.5.5 Interrupts The IISC interrupt line is connected to the Interrupt Controller. Using the IISC interrupt requires the Interrupt Controller to be programmed first. 24.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the IISC continues normal operation. If this module is configured in a way that requires it to be periodically serviced by the CPU through interrupt requests or similar, improper operation or data loss may result during debugging. 24.6 Functional Description 24.6.1 Initialization The IISC features a Receiver, a Transmitter, and, for Master and Controller modes, a Clock Generator. Receiver and Transmitter share the same Serial Clock and Word Select. Before enabling the IISC, the chosen configuration must be written to the Mode Register (MR). The IMCKMODE, MODE, and DATALENGTH fields in the MR register must be written. If the IMCKMODE field is written as one, then the IMCKFS field should be written with the chosen ratio, as described in Section 24.6.5 ”Serial Clock and Word Select Generation” on page 595. Once the Mode Register has been written, the IISC Clock Generator, Receiver, and Transmitter can be enabled by writing a one to the CKEN, RXEN, and TXEN bits in the Control Register (CR). The Clock Generator can be enabled alone, in Controller Mode, to output clocks to the IMCK, ISCK, and IWS pins. The Clock Generator must also be enabled if the Receiver or the Transmitter is enabled. The Clock Generator, Receiver, and Transmitter can be disabled independently by writing a one to CR.CXDIS, CR.RXDIS and/or CR.TXDIS respectively. Once requested to stop, they will only stop when the transmission of the pending frame transmission will be completed. 24.6.2 Basic Operation The Receiver can be operated by reading the Receiver Holding Register (RHR), whenever the Receive Ready (RXRDY) bit in the Status Register (SR) is set. Successive values read from RHR will correspond to the samples from the left and right audio channels for the successive frames. 594 32142D–06/2013 ATUC64/128/256L3/4U The Transmitter can be operated by writing to the Transmitter Holding Register (RHR), whenever the Transmit Ready (TXRDY) bit in the Status Register (SR) is set. Successive values written to THR should correspond to the samples from the left and right audio channels for the successive frames. The Receive Ready and Transmit Ready bits can be polled by reading the Status Register. The IISC processor load can be reduced by enabling interrupt-driven operation. The RXRDY and/or TXRDY interrupt requests can be enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER). The interrupt service routine associated to the IISC interrupt request will then be executed whenever the Receive Ready or the Transmit Ready status bit is set. 24.6.3 Master, Controller, and Slave Modes In Master and Controller modes, the IISC provides the Master Clock, the Serial Clock and the Word Select. IMCK, ISCK, and IWS pins are outputs. In Controller mode, the IISC Receiver and Transmitter are disabled. Only the clocks are enabled and used by an external receiver and/or transmitter. In Slave mode, the IISC receives the Serial Clock and the Word Select from an external master. ISCK and IWS pins are inputs. The mode is selected by writing the MODE field of the Mode Register (MR). Since the MODE field changes the direction of the IWS and ISCK pins, the Mode Register should only be written when the IISC is stopped, in order to avoid unwanted glitches on the IWS and ISCK pins. 24.6.4 I2 S Reception and Transmission Sequence As specified in the I2 S protocol, data bits are left-adjusted in the Word Select time slot, with the MSB transmitted first, starting one clock period after the transition on the Word Select line. Figure 24-2. I 2 S Reception and Transmission Sequence Data bits are sent on the falling edge of the Serial Clock and sampled on the rising edge of the Serial Clock. The Word Select line indicates the channel in transmission, a low level for the left channel and a high level for the right channel. The length of transmitted words can be chosen among 8, 16, 18, 20, 24, and 32 bits by writing the MR.DATALENGTH field. If the time slot allows for more data bits than written in the MR.DATALENGTH field, zeroes are appended to the transmitted data word or extra received bits are discarded. If the time slot allows for less data bits than written, the extra bits to be transmitted are not sent or the missing bits are set to zero in the received data word. Serial Clock ISCK Word Select IWS Data ISDI/ISDO MSB Left Channel LSB MSB Right Channel 595 32142D–06/2013 ATUC64/128/256L3/4U 24.6.5 Serial Clock and Word Select Generation The generation of clocks in the IISC is described in Figure 24-3 on page 596. In Slave mode, the Serial Clock and Word Select Clock are driven by an external master. ISCK and IWS pins are inputs and no generic clock is required by the IISC. In Master mode, the user can configure the Master Clock, Serial Clock, and Word Select Clock through the Mode Register (MR). IMCK, ISCK, and IWS pins are outputs and a generic clock is used to derive the IISC clocks. Audio codecs connected to the IISC pins may require a Master Clock signal with a frequency multiple of the audio sample frequency (fs), such as 256fs. When the IISC is in Master mode, writing a one to MR.IMCKMODE will output GCLK_IISC as Master Clock to the IMCK pin, and will divide GCLK_IISC to create the internal bit clock, output on the ISCK pin. The clock division factor is defined by writing to MR.IMCKFS and MR.DATALENGTH, as described ”IMCKFS: Master Clock to fs Ratio” on page 602. The Master Clock (IMCK) frequency is 16*(IMCKFS+1) times the sample frequency (fs), i.e. IWS frequency. The Serial Clock (ISCK) frequency is 2*Slot Length times the sample frequency (fs), where Slot Length is defined in Table 24-2 on page 595. Warning: MR.IMCKMODE should only be written as one if the Master Clock frequency is strictly higher than the Serial Clock. If a Master Clock output is not required, the GCLK_IISC generic clock is used as ISCK, by writing a zero to MR.IMCKMODE. Alternatively, if the frequency of the generic clock used is a multiple of the required ISCK frequency, the IMCK to ISCK divider can be used with the ratio defined by writing the MR.IMCKFS field. The IWS pin is used as Word Select as described in Section 24.6.4. Table 24-2. Slot Length MR.DATALENGTH Word Length Slot Length 0 32 bits 32 1 24 bits 32 if MR.IWS24 is zero 24 if MR.IWS24 is one 2 20 bits 3 18 bits 4 16 bits 16 5 16 bits compact stereo 6 8 bits 8 7 8 bits compact stereo 596 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-3. IISC Clocks Generation 24.6.6 Mono When the Transmit Mono (TXMONO) in the Mode Register is set, data written to the left channel is duplicated to the right output channel. When the Receive Mono (RXMONO) in the Mode Register is set, data received from the left channel is duplicated to the right channel. 24.6.7 Holding Registers The IISC user interface includes a Receive Holding Register (RHR) and a Transmit Holding Register (THR). RHR and THR are used to access audio samples for both audio channels. When a new data word is available in the RHR register, the Receive Ready bit (RXRDY) in the Status Register (SR) is set. Reading the RHR register will clear this bit. A receive overrun condition occurs if a new data word becomes available before the previous data word has been read from the RHR register. Then, the Receive Overrun bit in the Status Register will be set and bit i of the RXORCH field in the Status Register is set, where i is the current receive channel number. When the THR register is empty, the Transmit Ready bit (TXRDY) in the Status Register (SR) is set. Writing into the THR register will clear this bit. A transmit underrun condition occurs if a new data word needs to be transmitted before it has been written to the THR register. Then, the Transmit Underrun bit in the Status Register will be set and bit i of the TXORCH field in the Status Register is set, where i is the current transmit channel number. If the TXSAME bit in the Mode Register is zero, then a zero data word is transmitted in case of underrun. If MR.TXSAME is one, then the previous data word for the current transmit channel number is transmitted. MR.MODE = SLAVE Clock divider MR.DATALENGTH GCLK_IISC Clock enable Clock divider CR.CKEN/CKDIS MR.IMCKMODE MR.DATALENGTH MR.IMCKFS MR.IMCKMODE 0 1 IMCK pin output Clock enable CR.CKEN/CKDIS Internal bit clock ISCK pin input 1 0 ISCK pin output Internal word clock IWS pin input 1 0 IWS pin output 597 32142D–06/2013 ATUC64/128/256L3/4U Data words are right-justified in the RHR and THR registers. For 16-bit compact stereo, the left sample uses bits 15 through 0 and the right sample uses bits 31 through 16 of the same data word. For 8-bit compact stereo, the left sample uses bits 7 through 0 and the right sample uses bits 15 through 8 of the same data word. 24.6.8 DMA Operation The Receiver and the Transmitter can each be connected either to one single Peripheral DMA channel or to one Peripheral DMA channel per data channel. This is selected by writing to the MR.RXDMA and MR.TXDMA bits. If a single Peripheral DMA channel is selected, all data samples use IISC Receiver or Transmitter DMA channel 0. The Peripheral DMA reads from the RHR register and writes to the RHR register for both audio channels, successively. The Peripheral DMA transfers may use 32-bit word, 16-bit halfword, or 8-bit byte according to the value of the MR.DATALENGTH field. 24.6.9 Loop-back Mode For debugging purposes, the IISC can be configured to loop back the Transmitter to the Receiver. Writing a one to the MR.LOOP bit will internally connect ISDO to ISDI, so that the transmitted data is also received. Writing a zero to MR.LOOP will restore the normal behavior with independent Receiver and Transmitter. As for other changes to the Receiver or Transmitter configuration, the IISC Receiver and Transmitter must be disabled before writing to the MR register to update MR.LOOP. 24.6.10 Interrupts An IISC interrupt request can be triggered whenever one or several of the following bits are set in the Status Register (SR): Receive Ready (RXRDY), Receive Overrun (RXOR), Transmit Ready (TXRDY), or Transmit Underrun (TXOR). The interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one the corresponding bit in the Status Clear Register (SCR). For debugging purposes, interrupt requests can be simulated by writing a one to the corresponding bit in the Status Set Register (SSR). 598 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-4. Interrupt Block Diagram 24.7 IISC Application Examples The IISC can support several serial communication modes used in audio or high-speed serial links. Some standard applications are shown in the following figures. All serial link applications supported by the IISC are not listed here. Figure 24-5. Audio Application Block Diagram IER IDR IMR Set Clear Interrupt Control IISC Interrupt Request TXRDY TXUR Transmitter Receiver RXRDY RXOR Serial Clock Word Select Serial Data Out MSB LSB MSB Serial Data Out Word Select Serial Clock IISC ISCK IWS ISDO ISDI EXTERNAL I 2 S RECEIVER 599 32142D–06/2013 ATUC64/128/256L3/4U Figure 24-6. Codec Application Block Diagram Figure 24-7. Time Slot Application Block Diagram IISC Word Select Serial Data Out Serial Data In EXTERNAL AUDIO CODEC IMCK IWS ISDO ISDI Serial Clock Master Clock ISCK Right Time Slot Serial Clock Word Select Serial Data Out Serial Data In Dstart Dend Left Time Slot EXTERNAL AUDIO CODEC for Left Time Slot EXTERNAL AUDIO CODEC for Right Time Slot Serial Data In Serial Data Out Word Select Serial Clock Serial Clock Word Select Serial Data Out Serial Data In Dstart Left Time Slot Right Time Slot Dend IISC ISCK IWS ISDO ISDI Master Clock IMCK 600 32142D–06/2013 ATUC64/128/256L3/4U 24.8 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 24-3. IISC Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Write-only 0x00000000 0x04 Mode Register MR Read/Write 0x00000000 0x08 Status Register SR Read-only 0x00000000 0x0C Status Clear Register SCR Write-only 0x00000000 0x10 Status Set Register SSR Write-only 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Receiver Holding Register RHR Read-only 0x00000000 0x24 Transmitter Holding Register THR Write-only 0x00000000 0x28 Version Register VERSION Read-only - (1) 0x2C Parameter Register PARAMETER Read-only - (1) 601 32142D–06/2013 ATUC64/128/256L3/4U 24.8.1 Control Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 The Control Register should only be written to enable the IISC after the chosen configuration has been written to the Mode Register, in order to avoid unwanted glitches on the IWS, ISCK, and ISDO outputs. The proper sequence is to write the MR register, then write the CR register to enable the IISC, or to disable the IISC before writing a new value into MR. • SWRST: Software Reset Writing a zero to this bit has no effect. Writing a one to this bit resets all the registers in the module. The module will be disabled after the reset. This bit always reads as zero. • TXDIS: Transmitter Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC Transmitter. SR.TXEN will be cleared when the Transmitter is effectively stopped. • TXEN: Transmitter Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC Transmitter, if TXDIS is not one. SR.TXEN will be set when the Transmitter is effectively started. • CKDIS: Clocks Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC clocks generation. • CKEN: Clocks Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC clocks generation, if CKDIS is not one. • RXDIS: Receiver Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the IISC Receiver. SR.TXEN will be cleared when the Transmitter is effectively stopped. • RXEN: Receiver Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the IISC Receiver, if RXDIS is not one. SR.RXEN will be set when the Receiver is effectively started. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - TXDIS TXEN CKDIS CKEN RXDIS RXEN 602 32142D–06/2013 ATUC64/128/256L3/4U 24.8.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 The Mode Register should only be written when the IISC is stopped, in order to avoid unwanted glitches on the IWS, ISCK, and ISDO outputs. The proper sequence is to write the MR register, then write the CR register to enable the IISC, or to disable the IISC before writing a new value into MR. • IWS24: IWS TDM Slot Width 0: IWS slot is 32-bit wide for DATALENGTH=18/20/24-bit 1: IWS slot is 24-bit wide for DATALENGTH=18/20/24-bit Refer to Table 24-2, “Slot Length,” on page 595. • IMCKMODE: Master Clock Mode 0: No Master Clock generated (generic clock is used as ISCK output) 1: Master Clock generated (generic clock is used as IMCK output) Warning: if IMCK frequency is the same as ISCK, IMCKMODE should not be written as one. Refer to Section 24.6.5 ”Serial Clock and Word Select Generation” on page 595 and Table 24-2, “Slot Length,” on page 595. • IMCKFS: Master Clock to fs Ratio Master Clock frequency is 16*(IMCKFS+1) times the sample rate, i.e. IWS frequency: 31 30 29 28 27 26 25 24 IWS24 IMCKMODE IMCKFS 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - TXSAME TXDMA TXMONO RXLOOP RXDMA RXMONO 76543210 - - - DATALENGTH - MODE Table 24-4. Master Clock to Sample Frequency (fs) Ratio fs Ratio IMCKFS 16 fs 0 32 fs 1 48fs 2 64 fs 3 96fs 5 128 fs 7 192fs 11 256 fs 15 603 32142D–06/2013 ATUC64/128/256L3/4U • TXSAME: Transmit Data when Underrun 0: Zero sample transmitted when underrun 1: Previous sample transmitted when underrun • TXDMA: Single or multiple DMA Channels for Transmitter 0: Transmitter uses a single DMA channel for both audio channels 1: Transmitter uses one DMA channel per audio channel • TXMONO: Transmit Mono 0: Stereo 1: Mono, with left audio samples duplicated to right audio channel by the IISC • RXLOOP: Loop-back Test Mode 0: Normal mode 1: ISDO output of IISC is internally connected to ISDI input • RXMONO: Receive Mono 0: Stereo 1: Mono, with left audio samples duplicated to right audio channel by the IISC • RXDMA: Single or multiple DMA Channels for Receiver 0: Receiver uses a single DMA channel for both audio channels 1: Receiver uses one DMA channel per audio channel- • DATALENGTH: Data Word Length • MODE: Mode 384 fs 23 512 fs 31 768 fs 47 1024 fs 63 Table 24-5. Data Word Length DATALENGTH Word Length Comments 0 32 bits 1 24 bits 2 20 bits 3 18 bits 4 16 bits 5 16 bits compact stereo Left sample in bits 15 through 0 and right sample in bits 31 through 16 of the same word 6 8 bits 7 8 bits compact stereo Left sample in bits 7 through 0 and right sample in bits 15 through 8 of the same word Table 24-6. Mode MODE Comments 0 SLAVE ISCK and IWS pin inputs used as Bit Clock and Word Select/Frame Sync. 1 MASTER Bit Clock and Word Select/Frame Sync generated by IISC from GCLK_IISC and output to ISCK and IWS pins. GCLK_IISC is output as Master Clock on IMCK if MR.IMCKMODE is one. Table 24-4. Master Clock to Sample Frequency (fs) Ratio fs Ratio IMCKFS 604 32142D–06/2013 ATUC64/128/256L3/4U 24.8.3 Status Register Name: SR Access Type: Read-only Offset: 0x08 Reset Value: 0x00000000 • TXURCH: Transmit Underrun Channel This field is cleared when SCR.TXUR is written to one Bit i of this field is set when a transmit underrun error occurred in channel i (i=0 for first channel of the frame) • RXORCH: Receive Overrun Channel This field is cleared when SCR.RXOR is written to one Bit i of this field is set when a receive overrun error occurred in channel i (i=0 for first channel of the frame) • TXUR: Transmit Underrun This bit is cleared when the corresponding bit in SCR is written to one This bit is set when an underrun error occurs on the THR register or when the corresponding bit in SSR is written to one • TXRDY: Transmit Ready This bit is cleared when data is written to THR This bit is set when the THR register is empty and can be written with new data to be transmitted • TXEN: Transmitter Enabled This bit is cleared when the Transmitter is effectively disabled, following a CR.TXDIS or CR.SWRST request This bit is set when the Transmitter is effectively enabled, following a CR.TXEN request • RXOR: Receive Overrun This bit is cleared when the corresponding bit in SCR is written to one This bit is set when an overrun error occurs on the RHR register or when the corresponding bit in SSR is written to one • RXRDY: Receive Ready This bit is cleared when the RHR register is read This bit is set when received data is present in the RHR register • RXEN: Receiver Enabled This bit is cleared when the Receiver is effectively disabled, following a CR.RXDIS or CR.SWRST request This bit is set when the Receiver is effectively enabled, following a CR.RXEN request 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR TXRDY TXEN - RXOR RXRDY RXEN 605 32142D–06/2013 ATUC64/128/256L3/4U 24.8.4 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR - - - RXOR - - 606 32142D–06/2013 ATUC64/128/256L3/4U 24.8.5 Status Set Register Name: SSR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in SR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - TXURCH - - - - 15 14 13 12 11 10 9 8 - - - - - - RXORCH 76543210 - TXUR - - - RXOR - - 607 32142D–06/2013 ATUC64/128/256L3/4U 24.8.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 608 32142D–06/2013 ATUC64/128/256L3/4U 24.8.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 609 32142D–06/2013 ATUC64/128/256L3/4U 24.8.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - TXUR TXRDY - - RXOR RXRDY - 610 32142D–06/2013 ATUC64/128/256L3/4U 24.8.9 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x20 Reset Value: 0x00000000 • RHR: Received Word This field is set by hardware to the last received data word. If MR.DATALENGTH specifies less than 32 bits, data shall be rightjustified into the RHR field. 31 30 29 28 27 26 25 24 RHR[31:24] 23 22 21 20 19 18 17 16 RHR[23:16] 15 14 13 12 11 10 9 8 RHR[15:8] 76543210 RHR[7:0] 611 32142D–06/2013 ATUC64/128/256L3/4U 24.8.10 Transmit Holding Register Name: THR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 • THR: Data Word to Be Transmitted Next data word to be transmitted after the current word if TXRDY is not set. If MR.DATALENGTH specifies less than 32 bits, data shall be right-justified into the THR field. 31 30 29 28 27 26 25 24 THR[31:24] 23 22 21 20 19 18 17 16 THR[23:16] 15 14 13 12 11 10 9 8 THR[15:8] 76543210 THR[7:0] 612 32142D–06/2013 ATUC64/128/256L3/4U 24.8.11 Module Version Name: VERSION Access Type: Read-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 613 32142D–06/2013 ATUC64/128/256L3/4U 24.8.12 Module Parameters Name: PARAMETER Access Type: Read-only Offset: 0x2C Reset Value: - Reserved. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 614 32142D–06/2013 ATUC64/128/256L3/4U 24.9 Module configuration The specific configuration for each IISC instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 24-7. IISC Clocks Clock Name Description CLK_IISC Clock for the IISC bus interface GCLK The generic clock used for the IISC is GCLK6 Table 24-8. Register Reset Values Register Reset Value VERSION 0x00000100 615 32142D–06/2013 ATUC64/128/256L3/4U 25. Pulse Width Modulation Controller (PWMA) Rev: 2.0.1.0 25.1 Features • Left-aligned non-inverted 12-bit PWM • Common 12-bit timebase counter – Asynchronous clock source supported – Spread-spectrum counter to allow a constantly varying duty cycle • Separate 12-bit duty cycle register per channel • Synchronized channel updates – No glitches when changing the duty cycles • Interlinked operation supported – Up to 32 channels can be updated with the same duty cycle value at a time – Up to 4 channels can be updated with different duty cycle values at a time • Interrupt on PWM timebase overflow • Incoming peripheral events supported – Pre-defined channels support incoming (increase/decrease) peripheral events from the Peripheral Event System – Incoming increase/decrease event can either increase or decrease the duty cycle by one • One output peripheral event supported – Connected to channel 0 and asserted when the common timebase counter is equal to the programmed duty cycle for channel 0 • Output PWM waveforms – Support normal waveform output for each channel – Support composite waveform generation (XOR’ed) for each pair channels • Open drain driving on selected pins for 5V PWM operation 25.2 Overview The Pulse Width Modulation Controller (PWMA) controls several pulse width modulation (PWM) channels. The number of channels is specific to the device. Each channel controls one square output PWM waveform. Characteristics of the output PWM waveforms such as period and duty cycle are configured through the user interface. All user interface registers are mapped on the peripheral bus. The duty cycle value for each channel can be set independently, while the period is determined by a common timebase counter (TC). The timebase for the counter is selected by using the allocated asynchronous Generic Clock (GCLK). The user interface for the PWMA contains handshake and synchronizing logic to ensure that no glitches occur on the output PWM waveforms while changing the duty cycle values. PWMA duty cycle values can be changed using two approaches, either an interlinked singlevalue mode or an interlinked multi-value mode. In the interlinked single-value mode, any set of channels, up to 32 channels, can be updated simultaneously with the same value while the other channels remain unchanged. There is also an interlinked multi-value mode, where the 8 least significant bits of up to 4 channels can be updated with 4 different values while the other channels remain unchanged. Some pins can be driven in open drain mode, allowing the PWMA to generate a 5V waveform using an external pullup resistor. 616 32142D–06/2013 ATUC64/128/256L3/4U 25.3 Block Diagram Figure 25-1. PWMA Block Diagram 25.4 I/O Lines Description Each channel outputs one PWM waveform on one external I/O line. 25.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. PWM Blocks Channel m Channel 1 Channel 0 Duty Cycle Register COMP PWMA[m:0] Interrupt Handling IRQ PB TOP Timebase Counter SPREAD Adjust TOFL READY Channel_0 CLK_PWMA GCLK Domain PB Clock Domain Spread Spectrum Counter Sync GCLK ETV Control Duty Cycle Channel Select WAVEXOR CWG TCLR CHERR Table 25-1. I/O Line Description Pin Name Pin Description Type PWMA[n] Output PWM waveform for one channel n Output PWMMOD[n] Output PWM waveform for one channel n, open drain mode Output 617 32142D–06/2013 ATUC64/128/256L3/4U 25.5.1 I/O Lines The pins used for interfacing the PWMA may be multiplexed with I/O Controller lines. The programmer must first program the I/O Controller to assign the desired PWMA pins to their peripheral function. It is only required to enable the PWMA outputs actually in use. 25.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the PWMA, the PWMA will stop functioning and resume operation after the system wakes up from sleep mode. 25.5.3 Clocks The clock for the PWMA bus interface (CLK_PWMA) is controlled by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the PWMA before disabling the clock, to avoid freezing the PWMA in an undefined state. Additionally, the PWMA depends on a dedicated Generic Clock (GCLK). The GCLK can be set to a wide range of frequencies and clock sources and must be enabled in the System Control Interface (SCIF) before the PWMA can be used. 25.5.4 Interrupts The PWMA interrupt request lines are connected to the interrupt controller. Using the PWMA interrupts requires the interrupt controller to be programmed first. 25.5.5 Peripheral Events The PWMA peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 25.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the PWMA continues normal operation. If the PWMA is configured in a way that requires it to be periodically serviced by the CPU through interrupts, improper operation or data loss may result during debugging. 25.6 Functional Description The PWMA embeds a number of PWM channel submodules, each providing an output PWM waveform. Each PWM channel contains a duty cycle register and a comparator. A common timebase counter for all channels determines the frequency and the period for all the PWM waveforms. 25.6.1 Enabling the PWMA Once the GCLK has been enabled, the PWMA is enabled by writing a one to the EN bit in the Control Register (CR). 25.6.2 Timebase Counter The top value of the timebase counter defines the period of the PWMA output waveform. The timebase counter starts at zero when the PWMA is enabled and counts upwards until it reaches its effective top value (ETV). The effective top value is defined by specifying the desired number of GCLK clock cycles in the TOP field of Top Value Register (TVR.TOP) in normal operation (the 618 32142D–06/2013 ATUC64/128/256L3/4U SPREAD field of CR (CR.SPREAD) is zero). When the timebase counter reaches its effective top value, it restarts counting from zero. The period of the PWMA output waveform is then: The timebase counter can be reset by writing a one to the Timebase Clear bit in CR (CR.TCLR). Note that this can cause a glitch to the output PWM waveforms in use. 25.6.3 Spread Spectrum Counter The spread spectrum counter allows the generation of constantly varying duty cycles on the output PWM waveforms. This is achieved by varying the effective top value of the timebase counter in a range defined by the spread spectrum counter value. When CR.SPREAD is not zero, the spread spectrum counter is enabled. Its range is defined by CR.SPREAD. It starts to count from -CR.SPREAD when the PWMA is enabled or after reset and counts upwards. When it reaches CR.SPREAD, it restarts to count from -CR.SPREAD again. The spread spectrum counter will cause the effective top value to vary from TOPSPREAD to TOP+SPREAD. Figure 25-2 on page 618 illustrates this. This leads to a constantly varying duty cycle on the PWM output waveforms though the duty cycle values stored are unchanged. Figure 25-2. PWMA Adjusting Top Value for Timebase Counter 25.6.3.1 Special considerations The maximum value of the timebase counter is 0x0FFF. If SPREAD is written to a value that will cause the ETV to exceed this value, the spread spectrum counter’s range will be limited to prevent the timebase counter to exceed its maximum value. If SPREAD is written to a value causing (TOP-SPREAD) to be below zero, the spread spectrum counter’s range will be limited to prevent the timebase counter to count below zero. In both cases, the SPREAD value read from the Control Register will be the same value as written to the SPREAD field. TPWMA   ETV + 1 TGCLK =  0x0 0x0FFF Duty Cycle -SPREAD SPREAD TOP Adjusting top value range for the timerbase counter 619 32142D–06/2013 ATUC64/128/256L3/4U When writing a one to CR.TCLR, the timebase counter and the spread spectrum counter are reset at their lower limit values and the effective top value of the timebase counter will also be reset. 25.6.4 Duty Cycle and Waveform Properties Each PWM channel has its own duty cycle value (DCV) which is write-only and cannot be read out. The duty cycle value can be changed in two approaches as described in Section25.6.6. When the duty cycle value is zero, the PWM output is zero. Otherwise, the PWM output is set when the timebase counter is zero, and cleared when the timebase counter reaches the duty cycle value. This is summarized as: Note that when increasing the duty cycle value for one channel from 0 to 1, the number of GCLK cycles when the PWM waveform is high will jump from 0 to 2. When incrementing the duty cycle value by one for any other values, the number of GCLK cycle when the waveform is high will increase by one. This is summarized in Table 25-2. 25.6.5 Waveform Output PWMA waveforms are output to I/O lines. The output waveform properties are controlled by Composite Waveform Generation (CWG) register(s). If this register is cleared (by default), the channel waveforms are out directly to the I/O lines. To avoid too many I/O toggling simultaneously on the output I/O lines, every other output PWM waveform toggles on the negative edge of the GCLK instead of the positive edge. In CWG mode, all channels are paired and their outputs are XOR’ed together if the corresponding bit of CWG register is set. The even number of output is the XOR’ed output and the odd number of output is the inverse of its. Each bit of CWG register controls one pair channels and the least significant bit refers to the lowest number of pair channels. 25.6.6 Updating Duty Cycle Values 25.6.6.1 Interlinked Single Value PWM Operation The PWM channels can be interlinked to allow multiple channels to be updated simultaneously with the same duty cycle value. This value must be written to the Interlinked Single Value Duty Table 25-2. PMW Waveform Duty Cycles Duty Cycle Value #Clock Cycles When Waveform is High #Clock Cycles When Waveform is Low 0 0 ETV+1 1 2 ETV-1 2 3 ETV-2 ... ... ... ETV-1 ETV 1 ETV ETV+1 0 PWM Waveform = low when DCV = 0 or TC DCV  high when TC DCV  and DCV  0   620 32142D–06/2013 ATUC64/128/256L3/4U (ISDUTY) register. Each channel has a corresponding enabling bit in the Interlinked Single Value Channel Set (ISCHSET) register(s). When a bit is written to one in the ISCHSET register, the duty cycle register for the corresponding channel will be updated with the value stored in the ISDUTY register. It can only be updated when the READY bit in the Status Register (SR.READY) is one, indicating that the PWMA is ready for writing. Figure 25-3 on page 620 shows the writing procedure. It is thus possible to update the duty cycle values for up to 32 PWM channels within one ISCHSET register at a time. Figure 25-3. Interlinked Single Value PWM Operation Flow 25.6.6.2 Interlinked Multiple Value PWM Operation The interlinked multiple value PWM operation allows up to four channels to be updated simultaneously with different duty cycle values. The four duty cycle values are required to be written to the four registers, DUTY3, DUTY2, DUTY1 and DUTY0 , respectively. The index number of the four channels to be updated is written to the four SEL fields in the Interlinked Multiple Value Channel Select (IMCHSEL) register (IMCHSEL.SEL). When the IMCHSEL register is written, the values stored in the DUTY0/1/2/3 registers are synchronized to the duty cycle registers for the channels selected by the SEL fields. Figure 25-4 on page 620 shows the writing procedure. Note that only writes to the implemented channels will be effective. If one of the IMCHSEL.SEL fields points to a non-existing channel, the corresponding value in the DUTYx register will not be written. If the same channel is specified multiple times in the IMCHSEL.SEL fields, the channel will be updated with the value referred by the upper IMCHSEL.SEL field. When only the least significant 8-bits duty cycle value are considered for updating, the four duty cycle values can be written to the IMDUTY register once. This is equivalent to writing the four duty cycle values to the four DUTY registers one by one. Figure 25-4. Interlinked Multiple Value PWM Operation Flow ISCHSETm ... Write Enable Channeln DUTY Channel1 DUTY Channel0 DUTY ISDUTY Channel2 DUTY DUTY3/2/1/0 IMDUTY IMCHSEL Channeln DUTY ... MUX Channel1 DUTY Channel0 DUTY 621 32142D–06/2013 ATUC64/128/256L3/4U 25.6.7 Open Drain Mode Some pins can be used in open drain mode, allowing the PWMA waveform to toggle between 0V and up to 5V on these pins. In this mode the PWMA will drive the pin to zero or leave the output open. An external pullup can be used to pull the pin up to the desired voltage. To enable open drain mode on a pin the PWMAOD function must be selected instead of the PWMA function in the I/O Controller. Please refer to the Module Configuration chapter for information about which pins are available in open drain mode. 25.6.8 Synchronization Both the timebase counter and the spread spectrum counter can be reset and the duty cycle registers can be written through the user interface of the module. This requires a synchronization between the PB and GCLK clock domains, which takes a few clock cycles of each clock domain. The BUSY bit in SR indicates when the synchronization is ongoing. Writing to the module while the BUSY bit is set will result in discarding the new value. Note that the duty cycle registers will not be updated with the new values until the timebase counter reaches its top value, in order to avoid glitches. The BUSY bit in SR will always be set during this updating and synchronization period. 25.6.9 Interrupts When the timebase counter overflows, the Timebase Overflow bit in the Status Register (SR.TOFL) is set. If the corresponding bit in the Interrupt Mask Register (IMR) is set, an interrupt request will be generated. Since the user needs to wait until the user interface is available between each write due to synchronization, a READY bit is provided in SR, which can be used to generate an interrupt request. The interrupt request will be generated if the corresponding bit in IMR is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in SR is cleared by writing a one to the corresponding bit in the Status Clear Register (SCR). 25.6.10 Peripheral Events 25.6.10.1 Input Peripheral Events The pre-defined channels support input peripheral events from the Peripheral Event System. Input peripheral events must be enabled by writing a one to the corresponding bit in the Channel Event Enable Registers (CHEERs) before peripheral events can be used to control the duty cycle value. Each bit in the register corresponds to one channel, where bit 0 corresponds to channel 0 and so on. Both the increase and decrease events are enabled for the corresponding channel when a bit in the CHEER register is set. An increase or decrease event (event_incr/event_decr) can either increase or decrease the duty cycle value by one in a PWM period. The events are taken into account when the common timebase counter reaches its top. The behavior is defined by the Channel Event Response Register (CHERR). Each bit in the register corresponds to one channel, where bit 0 corresponds to channel 0 and so on. If the bit in CHERR is set to 0 (default) for a channel, the increase event will increase the duty cycle value and the decrease event will decrease the duty cycle value for that channel. If the bit is set to 1, the increase and decrease event will have reverse function so that 622 32142D–06/2013 ATUC64/128/256L3/4U the increase event will decrease the duty cycle value and decrease event will increase the duty cycle value. If both the increase event and the decrease event occur at the same time for a channel, the duty cycle value will not be changed. The number of channels supporting input peripheral events is device specific. Please refer to the Module Configuration section at the end of this chapter for details. 25.6.10.2 Output Peripheral Event The PWMA also supports one output peripheral event (event_ch0) to the Peripheral Event System. This output peripheral event is connected to channel 0 and will be asserted when the timebase counter reaches the duty cycle value for channel 0. This output event is always enabled. 623 32142D–06/2013 ATUC64/128/256L3/4U 25.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 25-3. PWMA Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 Interlinked Single Value Duty Register ISDUTY Write-only 0x00000000 0x08 Interlinked Multiple Value Duty Register IMDUTY Write-only 0x00000000 0x0C Interlinked Multiple Value Channel Select IMCHSEL Write-only 0x00000000 0x10 Interrupt Enable Register IER Write-only 0x00000000 0x14 Interrupt Disable Register IDR Write-only 0x00000000 0x18 Interrupt Mask Register IMR Read-only 0x00000000 0x1C Status Register SR Read-only 0x00000000 0x20 Status Clear Register SCR Write-only 0x00000000 0x24 Parameter Register PARAMETER Read-only - (1) 0x28 Version Register VERSION Read-only - (1) 0x2C Top Value Register TVR Read/Write 0x00000000 0x30+m*0x10 Interlinked Single Value Channel Set m ISCHSETm Write-only 0x00000000 0x34+m*0x10 Channel Event Response Register m CHERRm Read/Write 0x00000000 0x38+m*0x10 Channel Event Enable Register m CHEERm Read/Write 0x00000000 0x3C+k*0x10 CWG Register CWGk Read/Write 0x00000000 0x80 Interlinked Multiple Value Duty0 Register DUTY0 Write-only 0x00000000 0x84 Interlinked Multiple Value Duty1 Register DUTY1 Write-only 0x00000000 0x88 Interlinked Multiple Value Duty2 Register DUTY2 Write-only 0x00000000 0x8C Interlinked Multiple Value Duty3 Register DUTY3 Write-only 0x00000000 624 32142D–06/2013 ATUC64/128/256L3/4U 25.7.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SPREAD: Spread Spectrum Limit Value The spread spectrum limit value, together with the TOP field, defines the range for the spread spectrum counter. It is introduced in order to achieve constant varying duty cycles on the output PWM waveforms. Refer to Section25.6.3 for more information. • TOP: Timebase Counter Top Value The top value for the timebase counter. The value written to this field will update the least significant 8 bits of the TVR.TOP field in case only 8-bits resolution is required. The 4 most significant bits of TVR.TOP will be written to 0. When the TVR.TOP field is written, this CR.TOP field will also be updated with only the least significant 8 bits of TVR.TOP field. • TCLR: Timebase Clear Writing a zero to this bit has no effect. Writing a one to this bit will clear the timebase counter. This bit is always read as zero. • EN: Module Enable 0: The PWMA is disabled 1: The PWMA is enabled 31 30 29 28 27 26 25 24 - - - - - - - SPREAD[8] 23 22 21 20 19 18 17 16 SPREAD[7:0] 15 14 13 12 11 10 9 8 TOP 76543210 - - - - - - TCLR EN 625 32142D–06/2013 ATUC64/128/256L3/4U 25.7.2 Interlinked Single Value Duty Register Name: ISDUTY Access Type: Write-only Offset: 0x04 Reset Value: 0x00000000 • DUTY: Duty Cycle Value The duty cycle value written to this field is written simultaneously to all channels selected in the ISCHSETm register. If the value zero is written to DUTY all affected channels will be disabled. In this state the output waveform will be zero all the time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - DUTY[11:8] 76543210 DUTY[7:0] 626 32142D–06/2013 ATUC64/128/256L3/4U 25.7.3 Interlinked Multiple Value Duty Register Name: IMDUTY Access Type: Write-only Offset: 0x08 Reset Value: 0x00000000 • DUTYn: Duty Cycle The value written to DUTY field n will be automatically written to the least significant 8 bits of the DUTYn register for a PWMA channel while the most significant 4bits of the DUTYn register are unchanged. Which channel is selected for updating is defined by the corresponding SEL field in the IMCHSEL register. To write mulitple channels at a time with more than 8 bits of the duty cycle value, refer to DUTY3/2/1/0 registers. If the value zero is written to DUTY all affected channels will be disabled. In this state the output waveform will be zero all the time. 31 30 29 28 27 26 25 24 DUTY3 23 22 21 20 19 18 17 16 DUTY2 15 14 13 12 11 10 9 8 DUTY1 76543210 DUTY0 627 32142D–06/2013 ATUC64/128/256L3/4U 25.7.4 Interlinked Multiple Value Channel Select Name: IMCHSEL Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 • SELn: Channel Select The duty cycle of the PWMA channel SELn will be updated with the value stored in the DUTYn register when IMCHSEL is written. If SELn points to a non-implemented channel, the write will be discarded. Note: The duty registers will be updated with the value stored in the DUTY3, DUTY2, DUTY1 and DUTY0 registers when the IMCHSEL register is written. Synchronization takes place immediately when an IMCHSEL register is written. The duty cycle registers will, however, not be updated until the synchronization is completed and the timebase counter reaches its top value in order to avoid glitches. When only 8 bits duty cycle value are considered for updating, the four duty cycle values can be written to the IMDUTY register once. This is equivalent to writing the 8 bits four duty cycle values to the four DUTY registers one by one while the upper 4 bits remain unchanged. 31 30 29 28 27 26 25 24 SEL3 23 22 21 20 19 18 17 16 SEL2 15 14 13 12 11 10 9 8 SEL1 76543210 SEL0 628 32142D–06/2013 ATUC64/128/256L3/4U 25.7.5 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 629 32142D–06/2013 ATUC64/128/256L3/4U 25.7.6 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 630 32142D–06/2013 ATUC64/128/256L3/4U 25.7.7 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - READY - TOFL 631 32142D–06/2013 ATUC64/128/256L3/4U 25.7.8 Status Register Name: SR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 • BUSY: Interface Busy This bit is automatically cleared when the interface is no longer busy. This bit is set when the user interface is busy and will not respond to new write operations. • READY: Interface Ready This bit is cleared by writing a one to the corresponding bit in the SCR register. This bit is set when the BUSY bit has a 1-to-0 transition. • TOFL: Timebase Overflow This bit is cleared by writing a one to corresponding bit in the SCR register. This bit is set when the timebase counter has wrapped at its top value. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - BUSY READY - TOFL 632 32142D–06/2013 ATUC64/128/256L3/4U 25.7.9 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. This register always reads as zero. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 1 10 9 8 -------- 76543210 - - - - - READY - TOFL 633 32142D–06/2013 ATUC64/128/256L3/4U 25.7.10 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x24 Reset Value: - • CHANNELS: Channels Implemented This field contains the number of channels implemented on the device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 CHANNELS 634 32142D–06/2013 ATUC64/128/256L3/4U 25.7.11 Version Register Name: VERSION Access Type: Read-only Offset: 0x28 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 635 32142D–06/2013 ATUC64/128/256L3/4U 25.7.12 Top Value Register Name: TVR Access Type: Read/Write Offset: 0x2C Reset Value: 0x00000000 • TOP: Timebase Counter Top Value The top value for the timebase counter. The value written to the CR.TOP field will automatically be written to the 8 least significant bits of this field while the 4 most significant bits will be 0. When this register is written, it will also automatically update the CR.TOP field with the 8 least significant bits. The effective top value of the timebase counter is defined by both TVR.TOP and the CR.SPREAD. Refer to Section25.6.2 for more information. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - TOP[11:8] 76543210 TOP[7:0] 636 32142D–06/2013 ATUC64/128/256L3/4U 25.7.13 Interlinked Single Value Channel Set Name: ISCHSETm Access Type: Write-only Offset: 0x30+m*0x10 Reset Value: 0x00000000 • SET: Single Value Channel Set If the bit n in SET is one, the duty cycle of PWMA channel n will be updated with the value written to ISDUTY. If more than one ISCHSET register is present, ISCHSET0 controls channels 31 to 0 and ISCHSET1 controls channels 63 to 32. Note: The duty registers will be updated with the value stored in the ISDUTY register when any ISCHSETm register is written. Synchronization takes place immediately when an ISCHSET register is written. The duty cycle registers will, however, not be updated until the synchronization is completed and the timebase counter reaches its top value in order to avoid glitches. 31 30 29 28 27 26 25 24 SET 23 22 21 20 19 18 17 16 SET 15 14 13 12 11 10 9 8 SET 76543210 SET 637 32142D–06/2013 ATUC64/128/256L3/4U 25.7.14 Channel Event Response Register Name: CHERRm Access Type: Read/Write Offset: 0x34+m*0x10 Reset Value: 0x00000000 • CHER: Channel Event Response 0: The increase event will increase the duty cycle value by one in a PWM period for the corresponding channel and the decrease event will decrease the duty cycle value by one. 1: The increase event will decrease the duty cycle value by one in a PWM period for the corresponding channel and the decrease event will increase the duty cycle value by one. The events are taken into account when the common timebase counter reaches its top. If more than one CHERR register is present, CHERR0 controls channels 31-0 and CHERR1 controls channels 64-32 and so on. 31 30 29 28 27 26 25 24 CHER 23 22 21 20 19 18 17 16 CHER 15 14 13 12 11 10 9 8 CHER 76543210 CHER 638 32142D–06/2013 ATUC64/128/256L3/4U 25.7.15 Channel Event Enable Register Name: CHEERm Access Type: Read/Write Offset: 0x38+m*0x10 Reset Value: 0x00000000 • CHEE: Channel Event Enable 0: The input peripheral event for the corresponding channel is disabled. 1: The input peripheral event for the corresponding channel is enabled. Both increase and decrease events for channel n are enabled if bit n is one. If more than one CHEER register is present, CHEER0 controls channels 31-0 and CHEER1 controls channels 64-32 and so on. 31 30 29 28 27 26 25 24 CHEE 23 22 21 20 19 18 17 16 CHEE 15 14 13 12 11 10 9 8 CHEE 76543210 CHEE 639 32142D–06/2013 ATUC64/128/256L3/4U 25.7.16 Composite Waveform Generation Name: CWG Access Type: Read/Write Offset: 0x3C+k*0x10 Reset Value: 0x00000000 • XOR: Pair Waveform XOR’ed If the bit n in XOR field is one, the pair of PWMA output waveforms will be XORed before output. The even number output will be the XOR’ed output and the odd number output will be reverse of it. For example, if bit 0 in XOR is one, the pair of PWMA output waveforms for channel 0 and 1 will be XORed together. If bit n in XOR is zero, normal waveforms are output for that pair. Note that If more than one CWG register is present, CWG0 controls the first 32 pairs, corresponding to channels 63 downto 0, and CWG1 controls the second 32 pairs, corresponding to channels 127 downto 64. 31 30 29 28 27 26 25 24 XOR 23 22 21 20 19 18 17 16 XOR 15 14 13 12 11 10 9 8 XOR 76543210 XOR 640 32142D–06/2013 ATUC64/128/256L3/4U 25.7.17 Interlinked Multiple Value Duty0/1/2/3 Register Name: DUTY0/1/2/3 Access Type: Write-only Offset: 0x80-0x8C Reset Value: 0x00000000 These registers allows up to 4 channels to be updated with a common 12-bits duty cycle value at a time. They are the extension of the IMDUTY register which only supports updating the least significant 8 bits of the duty registers for up to 4 channels. • DUTY: Duty Cycle Value The duty cycle value written to this field will be updated to the channel specified by IMCHSEL. DUTY0 is specified by IMCHSEL.SEL0, DUTY1 is specified by IMCHSEL.SEL1, and so on. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - DUTY[11:8] 76543210 DUTY[7:0] 641 32142D–06/2013 ATUC64/128/256L3/4U 25.8 Module Configuration The specific configuration for each PWMA instance is listed in the following tables. The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 25-4. PWMA Configuration Feature PWMA Number of PWM channels 36 Channels supporting incoming peripheral events 0, 6, 8, 9, 11, 14, 19, and 20 PWMA channels with Open Drain mode 21, 27, and 28 Table 25-5. PWMA Clocks Clock Name Descripton CLK_PWMA Clock for the PWMA bus interface GCLK The generic clock used for the PWMA is GCLK3 Table 25-6. Register Reset Values Register Reset Value VERSION 0x00000201 PARAMETER 0x00000024 642 32142D–06/2013 ATUC64/128/256L3/4U 26. Timer/Counter (TC) Rev: 2.2.3.1.3 26.1 Features • Three 16-bit Timer Counter channels • A wide range of functions including: – Frequency measurement – Event counting – Interval measurement – Pulse generation – Delay timing – Pulse width modulation – Up/down capabilities • Each channel is user-configurable and contains: – Three external clock inputs – Five internal clock inputs – Two multi-purpose input/output signals • Internal interrupt signal • Two global registers that act on all three TC channels • Peripheral event input on all A lines in capture mode 26.2 Overview The Timer Counter (TC) includes three identical 16-bit Timer Counter channels. Each channel can be independently programmed to perform a wide range of functions including frequency measurement, event counting, interval measurement, pulse generation, delay timing, and pulse width modulation. Each channel has three external clock inputs, five internal clock inputs, and two multi-purpose input/output signals which can be configured by the user. Each channel drives an internal interrupt signal which can be programmed to generate processor interrupts. The TC block has two global registers which act upon all three TC channels. The Block Control Register (BCR) allows the three channels to be started simultaneously with the same instruction. The Block Mode Register (BMR) defines the external clock inputs for each channel, allowing them to be chained. 643 32142D–06/2013 ATUC64/128/256L3/4U 26.3 Block Diagram Figure 26-1. TC Block Diagram 26.4 I/O Lines Description 26.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 26.5.1 I/O Lines The pins used for interfacing the compliant external devices may be multiplexed with I/O lines. The user must first program the I/O Controller to assign the TC pins to their peripheral functions. I/O Controller TC2XC2S INT0 INT1 INT2 TIOA0 TIOA1 TIOA2 TIOB0 TIOB1 TIOB2 XC2 TCLK0 TCLK1 TCLK2 TCLK0 TCLK1 TCLK2 TCLK0 TCLK1 TCLK2 TIOA1 TIOA2 TIOA0 TIOA2 TIOA1 Interrupt Controller CLK0 CLK1 CLK2 A0 B0 A1 B1 A2 B2 Timer Count er TIOB TIOA TIOB SYNC TIMER_CLOCK1 TIOA SYNC SYNC TIOA TIOB TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 XC1 XC0 XC0 XC2 XC1 XC0 XC1 XC2 Timer/Counter Channel 2 Timer/Counter Channel 1 Timer/Counter Channel 0 TC1XC1S TC0XC0S TIOA0 Table 26-1. I/O Lines Description Pin Name Description Type CLK0-CLK2 External Clock Input Input A0-A2 I/O Line A Input/Output B0-B2 I/O Line B Input/Output 644 32142D–06/2013 ATUC64/128/256L3/4U When using the TIOA lines as inputs the user must make sure that no peripheral events are generated on the line. Refer to the Peripheral Event System chapter for details. 26.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the TC, the TC will stop functioning and resume operation after the system wakes up from sleep mode. 26.5.3 Clocks The clock for the TC bus interface (CLK_TC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the TC before disabling the clock, to avoid freezing the TC in an undefined state. 26.5.4 Interrupts The TC interrupt request line is connected to the interrupt controller. Using the TC interrupt requires the interrupt controller to be programmed first. 26.5.5 Peripheral Events The TC peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 26.5.6 Debug Operation The Timer Counter clocks are frozen during debug operation, unless the OCD system keeps peripherals running in debug operation. 26.6 Functional Description 26.6.1 TC Description The three channels of the Timer Counter are independent and identical in operation. The registers for channel programming are listed in Figure 26-3 on page 659. 26.6.1.1 Channel I/O Signals As described in Figure 26-1 on page 643, each Channel has the following I/O signals. 26.6.1.2 16-bit counter Each channel is organized around a 16-bit counter. The value of the counter is incremented at each positive edge of the selected clock. When the counter has reached the value 0xFFFF and passes to 0x0000, an overflow occurs and the Counter Overflow Status bit in the Channel n Status Register (SRn.COVFS) is set. Table 26-2. Channel I/O Signals Description Block/Channel Signal Name Description Channel Signal XC0, XC1, XC2 External Clock Inputs TIOA Capture mode: Timer Counter Input Waveform mode: Timer Counter Output TIOB Capture mode: Timer Counter Input Waveform mode: Timer Counter Input/Output INT Interrupt Signal Output SYNC Synchronization Input Signal 645 32142D–06/2013 ATUC64/128/256L3/4U The current value of the counter is accessible in real time by reading the Channel n Counter Value Register (CVn). The counter can be reset by a trigger. In this case, the counter value passes to 0x0000 on the next valid edge of the selected clock. 26.6.1.3 Clock selection At block level, input clock signals of each channel can either be connected to the external inputs TCLK0, TCLK1 or TCLK2, or be connected to the configurable I/O signals A0, A1 or A2 for chaining by writing to the BMR register. See Figure 26-2 on page 645. Each channel can independently select an internal or external clock source for its counter: • Internal clock signals: TIMER_CLOCK1, TIMER_CLOCK2, TIMER_CLOCK3, TIMER_CLOCK4, TIMER_CLOCK5. See the Module Configuration Chapter for details about the connection of these clock sources. • External clock signals: XC0, XC1 or XC2. See the Module Configuration Chapter for details about the connection of these clock sources. This selection is made by the Clock Selection field in the Channel n Mode Register (CMRn.TCCLKS). The selected clock can be inverted with the Clock Invert bit in CMRn (CMRn.CLKI). This allows counting on the opposite edges of the clock. The burst function allows the clock to be validated when an external signal is high. The Burst Signal Selection field in the CMRn register (CMRn.BURST) defines this signal. Note: In all cases, if an external clock is used, the duration of each of its levels must be longer than the CLK_TC period. The external clock frequency must be at least 2.5 times lower than the CLK_TC. Figure 26-2. Clock Selection TIMER_CLOCK5 XC2 TCCLKS CLKI BURST 1 Selected Clock XC1 XC0 TIMER_CLOCK4 TIMER_CLOCK3 TIMER_CLOCK2 TIMER_CLOCK1 646 32142D–06/2013 ATUC64/128/256L3/4U 26.6.1.4 Clock control The clock of each counter can be controlled in two different ways: it can be enabled/disabled and started/stopped. See Figure 26-3 on page 646. • The clock can be enabled or disabled by the user by writing to the Counter Clock Enable/Disable Command bits in the Channel n Clock Control Register (CCRn.CLKEN and CCRn.CLKDIS). In Capture mode it can be disabled by an RB load event if the Counter Clock Disable with RB Loading bit in CMRn is written to one (CMRn.LDBDIS). In Waveform mode, it can be disabled by an RC Compare event if the Counter Clock Disable with RC Compare bit in CMRn is written to one (CMRn.CPCDIS). When disabled, the start or the stop actions have no effect: only a CLKEN command in CCRn can re-enable the clock. When the clock is enabled, the Clock Enabling Status bit is set in SRn (SRn.CLKSTA). • The clock can also be started or stopped: a trigger (software, synchro, external or compare) always starts the clock. In Capture mode the clock can be stopped by an RB load event if the Counter Clock Stopped with RB Loading bit in CMRn is written to one (CMRn.LDBSTOP). In Waveform mode it can be stopped by an RC compare event if the Counter Clock Stopped with RC Compare bit in CMRn is written to one (CMRn.CPCSTOP). The start and the stop commands have effect only if the clock is enabled. Figure 26-3. Clock Control 26.6.1.5 TC operating modes Each channel can independently operate in two different modes: • Capture mode provides measurement on signals. • Waveform mode provides wave generation. The TC operating mode selection is done by writing to the Wave bit in the CCRn register (CCRn.WAVE). In Capture mode, TIOA and TIOB are configured as inputs. Q S R S R Q CLKSTA CLKEN CLKDIS Stop Event Disable Counter Clock Selected Clock Trigger Event 647 32142D–06/2013 ATUC64/128/256L3/4U In Waveform mode, TIOA is always configured to be an output and TIOB is an output if it is not selected to be the external trigger. 26.6.1.6 Trigger A trigger resets the counter and starts the counter clock. Three types of triggers are common to both modes, and a fourth external trigger is available to each mode. The following triggers are common to both modes: • Software Trigger: each channel has a software trigger, available by writing a one to the Software Trigger Command bit in CCRn (CCRn.SWTRG). • SYNC: each channel has a synchronization signal SYNC. When asserted, this signal has the same effect as a software trigger. The SYNC signals of all channels are asserted simultaneously by writing a one to the Synchro Command bit in the BCR register (BCR.SYNC). • Compare RC Trigger: RC is implemented in each channel and can provide a trigger when the counter value matches the RC value if the RC Compare Trigger Enable bit in CMRn (CMRn.CPCTRG) is written to one. The channel can also be configured to have an external trigger. In Capture mode, the external trigger signal can be selected between TIOA and TIOB. In Waveform mode, an external event can be programmed to be one of the following signals: TIOB, XC0, XC1, or XC2. This external event can then be programmed to perform a trigger by writing a one to the External Event Trigger Enable bit in CMRn (CMRn.ENETRG). If an external trigger is used, the duration of the pulses must be longer than the CLK_TC period in order to be detected. Regardless of the trigger used, it will be taken into account at the following active edge of the selected clock. This means that the counter value can be read differently from zero just after a trigger, especially when a low frequency signal is selected as the clock. 26.6.1.7 Peripheral events on TIOA inputs The TIOA input lines are ored internally with peripheral events from the Peripheral Event System. To capture using events the user must ensure that the corresponding pin functions for the TIOA line are disabled. When capturing on the external TIOA pin the user must ensure that no peripheral events are generated on this pin. 26.6.2 Capture Operating Mode This mode is entered by writing a zero to the CMRn.WAVE bit. Capture mode allows the TC channel to perform measurements such as pulse timing, frequency, period, duty cycle and phase on TIOA and TIOB signals which are considered as inputs. Figure 26-4 on page 649 shows the configuration of the TC channel when programmed in Capture mode. 26.6.2.1 Capture registers A and B Registers A and B (RA and RB) are used as capture registers. This means that they can be loaded with the counter value when a programmable event occurs on the signal TIOA. 648 32142D–06/2013 ATUC64/128/256L3/4U The RA Loading Selection field in CMRn (CMRn.LDRA) defines the TIOA edge for the loading of the RA register, and the RB Loading Selection field in CMRn (CMRn.LDRB) defines the TIOA edge for the loading of the RB register. RA is loaded only if it has not been loaded since the last trigger or if RB has been loaded since the last loading of RA. RB is loaded only if RA has been loaded since the last trigger or the last loading of RB. Loading RA or RB before the read of the last value loaded sets the Load Overrun Status bit in SRn (SRn.LOVRS). In this case, the old value is overwritten. 26.6.2.2 Trigger conditions In addition to the SYNC signal, the software trigger and the RC compare trigger, an external trigger can be defined. The TIOA or TIOB External Trigger Selection bit in CMRn (CMRn.ABETRG) selects TIOA or TIOB input signal as an external trigger. The External Trigger Edge Selection bit in CMRn (CMRn.ETREDG) defines the edge (rising, falling or both) detected to generate an external trigger. If CMRn.ETRGEDG is zero (none), the external trigger is disabled. 649 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-4. Capture Mode TIMER_CLOCK1 XC0 XC1 XC2 TCCLKS CLKI Q S R S R Q CLKSTA CLKEN CLKDIS BURST TIOB Capture Register A Compare RC = 16-bit Counter ABETRG SWTRG ETRGEDG CPCTRG IMR Trig LDRBS LDRAS ETRGS SR LOVRS COVFS SYNC 1 MTIOB TIOA MTIOA LDRA LDBSTOP If RA is not Loaded or RB is Loaded If RA is Loaded LDBDIS CPCS INT Edge Detector LDRB CLK OVF RESET Timer/Counter Channel Edge Detector Edge Detector Capture Register B Register C TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 650 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3 Waveform Operating Mode Waveform operating mode is entered by writing a one to the CMRn.WAVE bit. In Waveform operating mode the TC channel generates one or two PWM signals with the same frequency and independently programmable duty cycles, or generates different types of oneshot or repetitive pulses. In this mode, TIOA is configured as an output and TIOB is defined as an output if it is not used as an external event. Figure 26-5 on page 651 shows the configuration of the TC channel when programmed in Waveform operating mode. 26.6.3.1 Waveform selection Depending on the Waveform Selection field in CMRn (CMRn.WAVSEL), the behavior of CVn varies. With any selection, RA, RB and RC can all be used as compare registers. RA Compare is used to control the TIOA output, RB Compare is used to control the TIOB output (if correctly configured) and RC Compare is used to control TIOA and/or TIOB outputs. 651 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-5. Waveform Mode TCCLKS CLKI Q S R S R Q CLKSTA CLKEN CLKDIS CPCDIS BURST TIOB Register A Compare RC = CPCSTOP 16-bit Counter EEVT EEVTEDG SYNC SWTRG ENETRG WAVSEL IMR Trig ACPC ACPA AEEVT ASWTRG BCPC BCPB BEEVT BSWTRG TIOA MTIOA TIOB MTIOB CPAS COVFS ETRGS SR CPCS CPBS CLK OVF RESET Output Contr oller O utput Cont r oller INT 1 Edge Detector Timer/Counter Channel TIMER_CLOCK1 XC0 XC1 XC2 WAVSEL Register B Register C Compare RB = Compare RA = TIMER_CLOCK2 TIMER_CLOCK3 TIMER_CLOCK4 TIMER_CLOCK5 652 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3.2 WAVSEL = 0 When CMRn.WAVSEL is zero, the value of CVn is incremented from 0 to 0xFFFF. Once 0xFFFF has been reached, the value of CVn is reset. Incrementation of CVn starts again and the cycle continues. See Figure 26-6 on page 652. An external event trigger or a software trigger can reset the value of CVn. It is important to note that the trigger may occur at any time. See Figure 26-7 on page 653. RC Compare cannot be programmed to generate a trigger in this configuration. At the same time, RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-6. WAVSEL= 0 Without Trigger Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with 0xFFFF 0xFFFF Waveform Examples 653 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-7. WAVSEL= 0 With Trigger 26.6.3.3 WAVSEL = 2 When CMRn.WAVSEL is two, the value of CVn is incremented from zero to the value of RC, then automatically reset on a RC Compare. Once the value of CVn has been reset, it is then incremented and so on. See Figure 26-8 on page 654. It is important to note that CVn can be reset at any time by an external event or a software trigger if both are programmed correctly. See Figure 26-9 on page 654. In addition, RC Compare can stop the counter clock (CMRn.CPCSTOP) and/or disable the counter clock (CMRn.CPCDIS = 1). Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with 0xFFFF 0xFFFF Waveform Examples Counter cleared by trigger 654 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-8. WAVSEL = 2 Without Trigger Figure 26-9. WAVSEL = 2 With Trigger 26.6.3.4 WAVSEL = 1 When CMRn.WAVSEL is one, the value of CVn is incremented from 0 to 0xFFFF. Once 0xFFFF is reached, the value of CVn is decremented to 0, then re-incremented to 0xFFFF and so on. See Figure 26-10 on page 655. Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples Counter cleared by trigger 655 32142D–06/2013 ATUC64/128/256L3/4U A trigger such as an external event or a software trigger can modify CVn at any time. If a trigger occurs while CVn is incrementing, CVn then decrements. If a trigger is received while CVn is decrementing, CVn then increments. See Figure 26-11 on page 655. RC Compare cannot be programmed to generate a trigger in this configuration. At the same time, RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-10. WAVSEL = 1 Without Trigger Figure 26-11. WAVSEL = 1 With Trigger Time Counter Value RC RB RA TIOB TIOA Counter decremented by compare match with 0xFFFF 0xFFFF Waveform Examples Time Counter Value TIOB TIOA Counter decremented by compare match with 0xFFFF 0xFFFF Waveform Examples Counter decremented by trigger RC RB RA Counter incremented by trigger 656 32142D–06/2013 ATUC64/128/256L3/4U 26.6.3.5 WAVSEL = 3 When CMRn.WAVSEL is three, the value of CVn is incremented from zero to RC. Once RC is reached, the value of CVn is decremented to zero, then re-incremented to RC and so on. See Figure 26-12 on page 656. A trigger such as an external event or a software trigger can modify CVn at any time. If a trigger occurs while CVn is incrementing, CVn then decrements. If a trigger is received while CVn is decrementing, CVn then increments. See Figure 26-13 on page 657. RC Compare can stop the counter clock (CMRn.CPCSTOP = 1) and/or disable the counter clock (CMRn.CPCDIS = 1). Figure 26-12. WAVSEL = 3 Without Trigger Time Counter Value RC RB RA TIOB TIOA Counter cleared by compare match with RC 0xFFFF Waveform Examples 657 32142D–06/2013 ATUC64/128/256L3/4U Figure 26-13. WAVSEL = 3 With Trigger 26.6.3.6 External event/trigger conditions An external event can be programmed to be detected on one of the clock sources (XC0, XC1, XC2) or TIOB. The external event selected can then be used as a trigger. The External Event Selection field in CMRn (CMRn.EEVT) selects the external trigger. The External Event Edge Selection field in CMRn (CMRn.EEVTEDG) defines the trigger edge for each of the possible external triggers (rising, falling or both). If CMRn.EEVTEDG is written to zero, no external event is defined. If TIOB is defined as an external event signal (CMRn.EEVT = 0), TIOB is no longer used as an output and the compare register B is not used to generate waveforms and subsequently no IRQs. In this case the TC channel can only generate a waveform on TIOA. When an external event is defined, it can be used as a trigger by writing a one to the CMRn.ENETRG bit. As in Capture mode, the SYNC signal and the software trigger are also available as triggers. RC Compare can also be used as a trigger depending on the CMRn.WAVSEL field. 26.6.3.7 Output controller The output controller defines the output level changes on TIOA and TIOB following an event. TIOB control is used only if TIOB is defined as output (not as an external event). The following events control TIOA and TIOB: • software trigger • external event • RC compare RA compare controls TIOA and RB compare controls TIOB. Each of these events can be programmed to set, clear or toggle the output as defined in the following fields in CMRn: • RC Compare Effect on TIOB (CMRn.BCPC) Time Counter Value TIOB TIOA Counter decremented by compare match with RC 0xFFFF Waveform Examples RC RB RA Counter decremented by trigger Counter incremented by trigger 658 32142D–06/2013 ATUC64/128/256L3/4U • RB Compare Effect on TIOB (CMRn.BCPB) • RC Compare Effect on TIOA (CMRn.ACPC) • RA Compare Effect on TIOA (CMRn.ACPA) 659 32142D–06/2013 ATUC64/128/256L3/4U 26.7 User Interface Table 26-3. TC Register Memory Map Offset Register Register Name Access Reset 0x00 Channel 0 Control Register CCR0 Write-only 0x00000000 0x04 Channel 0 Mode Register CMR0 Read/Write 0x00000000 0x10 Channel 0 Counter Value CV0 Read-only 0x00000000 0x14 Channel 0 Register A RA0 Read/Write(1) 0x00000000 0x18 Channel 0 Register B RB0 Read/Write(1) 0x00000000 0x1C Channel 0 Register C RC0 Read/Write 0x00000000 0x20 Channel 0 Status Register SR0 Read-only 0x00000000 0x24 Interrupt Enable Register IER0 Write-only 0x00000000 0x28 Channel 0 Interrupt Disable Register IDR0 Write-only 0x00000000 0x2C Channel 0 Interrupt Mask Register IMR0 Read-only 0x00000000 0x40 Channel 1 Control Register CCR1 Write-only 0x00000000 0x44 Channel 1 Mode Register CMR1 Read/Write 0x00000000 0x50 Channel 1 Counter Value CV1 Read-only 0x00000000 0x54 Channel 1 Register A RA1 Read/Write(1) 0x00000000 0x58 Channel 1 Register B RB1 Read/Write(1) 0x00000000 0x5C Channel 1 Register C RC1 Read/Write 0x00000000 0x60 Channel 1 Status Register SR1 Read-only 0x00000000 0x64 Channel 1 Interrupt Enable Register IER1 Write-only 0x00000000 0x68 Channel 1 Interrupt Disable Register IDR1 Write-only 0x00000000 0x6C Channel 1 Interrupt Mask Register IMR1 Read-only 0x00000000 0x80 Channel 2 Control Register CCR2 Write-only 0x00000000 0x84 Channel 2 Mode Register CMR2 Read/Write 0x00000000 0x90 Channel 2 Counter Value CV2 Read-only 0x00000000 0x94 Channel 2 Register A RA2 Read/Write(1) 0x00000000 0x98 Channel 2 Register B RB2 Read/Write(1) 0x00000000 0x9C Channel 2 Register C RC2 Read/Write 0x00000000 0xA0 Channel 2 Status Register SR2 Read-only 0x00000000 0xA4 Channel 2 Interrupt Enable Register IER2 Write-only 0x00000000 0xA8 Channel 2 Interrupt Disable Register IDR2 Write-only 0x00000000 0xAC Channel 2 Interrupt Mask Register IMR2 Read-only 0x00000000 0xC0 Block Control Register BCR Write-only 0x00000000 0xC4 Block Mode Register BMR Read/Write 0x00000000 0xF8 Features Register FEATURES Read-only -(2) 0xFC Version Register VERSION Read-only -(2) 660 32142D–06/2013 ATUC64/128/256L3/4U Notes: 1. Read-only if CMRn.WAVE is zero. 2. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. 661 32142D–06/2013 ATUC64/128/256L3/4U 26.7.1 Channel Control Register Name: CCR Access Type: Write-only Offset: 0x00 + n * 0x40 Reset Value: 0x00000000 • SWTRG: Software Trigger Command 1: Writing a one to this bit will perform a software trigger: the counter is reset and the clock is started. 0: Writing a zero to this bit has no effect. • CLKDIS: Counter Clock Disable Command 1: Writing a one to this bit will disable the clock. 0: Writing a zero to this bit has no effect. • CLKEN: Counter Clock Enable Command 1: Writing a one to this bit will enable the clock if CLKDIS is not one. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - SWTRG CLKDIS CLKEN 662 32142D–06/2013 ATUC64/128/256L3/4U 26.7.2 Channel Mode Register: Capture Mode Name: CMR Access Type: Read/Write Offset: 0x04 + n * 0x40 Reset Value: 0x00000000 • LDRB: RB Loading Selection • LDRA: RA Loading Selection • WAVE 1: Capture mode is disabled (Waveform mode is enabled). 0: Capture mode is enabled. • CPCTRG: RC Compare Trigger Enable 1: RC Compare resets the counter and starts the counter clock. 0: RC Compare has no effect on the counter and its clock. • ABETRG: TIOA or TIOB External Trigger Selection 1: TIOA is used as an external trigger. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - LDRB LDRA 15 14 13 12 11 10 9 8 WAVE CPCTRG - - - ABETRG ETRGEDG 76543210 LDBDIS LDBSTOP BURST CLKI TCCLKS LDRB Edge 0 none 1 rising edge of TIOA 2 falling edge of TIOA 3 each edge of TIOA LDRA Edge 0 none 1 rising edge of TIOA 2 falling edge of TIOA 3 each edge of TIOA 663 32142D–06/2013 ATUC64/128/256L3/4U 0: TIOB is used as an external trigger. • ETRGEDG: External Trigger Edge Selection • LDBDIS: Counter Clock Disable with RB Loading 1: Counter clock is disabled when RB loading occurs. 0: Counter clock is not disabled when RB loading occurs. • LDBSTOP: Counter Clock Stopped with RB Loading 1: Counter clock is stopped when RB loading occurs. 0: Counter clock is not stopped when RB loading occurs. • BURST: Burst Signal Selection • CLKI: Clock Invert 1: The counter is incremented on falling edge of the clock. 0: The counter is incremented on rising edge of the clock. • TCCLKS: Clock Selection ETRGEDG Edge 0 none 1 rising edge 2 falling edge 3 each edge BURST Burst Signal Selection 0 The clock is not gated by an external signal 1 XC0 is ANDed with the selected clock 2 XC1 is ANDed with the selected clock 3 XC2 is ANDed with the selected clock TCCLKS Clock Selected 0 TIMER_CLOCK1 1 TIMER_CLOCK2 2 TIMER_CLOCK3 3 TIMER_CLOCK4 4 TIMER_CLOCK5 5 XC0 6 XC1 7 XC2 664 32142D–06/2013 ATUC64/128/256L3/4U 26.7.3 Channel Mode Register: Waveform Mode Name: CMR Access Type: Read/Write Offset: 0x04 + n * 0x40 Reset Value: 0x00000000 • BSWTRG: Software Trigger Effect on TIOB • BEEVT: External Event Effect on TIOB 31 30 29 28 27 26 25 24 BSWTRG BEEVT BCPC BCPB 23 22 21 20 19 18 17 16 ASWTRG AEEVT ACPC ACPA 15 14 13 12 11 10 9 8 WAVE WAVSEL ENETRG EEVT EEVTEDG 76543210 CPCDIS CPCSTOP BURST CLKI TCCLKS BSWTRG Effect 0 none 1 set 2 clear 3 toggle BEEVT Effect 0 none 1 set 2 clear 3 toggle 665 32142D–06/2013 ATUC64/128/256L3/4U • BCPC: RC Compare Effect on TIOB • BCPB: RB Compare Effect on TIOB • ASWTRG: Software Trigger Effect on TIOA • AEEVT: External Event Effect on TIOA • ACPC: RC Compare Effect on TIOA BCPC Effect 0 none 1 set 2 clear 3 toggle BCPB Effect 0 none 1 set 2 clear 3 toggle ASWTRG Effect 0 none 1 set 2 clear 3 toggle AEEVT Effect 0 none 1 set 2 clear 3 toggle ACPC Effect 0 none 1 set 2 clear 3 toggle 666 32142D–06/2013 ATUC64/128/256L3/4U • ACPA: RA Compare Effect on TIOA • WAVE 1: Waveform mode is enabled. 0: Waveform mode is disabled (Capture mode is enabled). • WAVSEL: Waveform Selection • ENETRG: External Event Trigger Enable 1: The external event resets the counter and starts the counter clock. 0: The external event has no effect on the counter and its clock. In this case, the selected external event only controls the TIOA output. • EEVT: External Event Selection Note: 1. If TIOB is chosen as the external event signal, it is configured as an input and no longer generates waveforms and subsequently no IRQs. • EEVTEDG: External Event Edge Selection • CPCDIS: Counter Clock Disable with RC Compare 1: Counter clock is disabled when counter reaches RC. 0: Counter clock is not disabled when counter reaches RC. ACPA Effect 0 none 1 set 2 clear 3 toggle WAVSEL Effect 0 UP mode without automatic trigger on RC Compare 1 UPDOWN mode without automatic trigger on RC Compare 2 UP mode with automatic trigger on RC Compare 3 UPDOWN mode with automatic trigger on RC Compare EEVT Signal selected as external event TIOB Direction 0 TIOB input(1) 1 XC0 output 2 XC1 output 3 XC2 output EEVTEDG Edge 0 none 1 rising edge 2 falling edge 3 each edge 667 32142D–06/2013 ATUC64/128/256L3/4U • CPCSTOP: Counter Clock Stopped with RC Compare 1: Counter clock is stopped when counter reaches RC. 0: Counter clock is not stopped when counter reaches RC. • BURST: Burst Signal Selection • CLKI: Clock Invert 1: Counter is incremented on falling edge of the clock. 0: Counter is incremented on rising edge of the clock. • TCCLKS: Clock Selection BURST Burst Signal Selection 0 The clock is not gated by an external signal. 1 XC0 is ANDed with the selected clock. 2 XC1 is ANDed with the selected clock. 3 XC2 is ANDed with the selected clock. TCCLKS Clock Selected 0 TIMER_CLOCK1 1 TIMER_CLOCK2 2 TIMER_CLOCK3 3 TIMER_CLOCK4 4 TIMER_CLOCK5 5 XC0 6 XC1 7 XC2 668 32142D–06/2013 ATUC64/128/256L3/4U 26.7.4 Channel Counter Value Register Name: CV Access Type: Read-only Offset: 0x10 + n * 0x40 Reset Value: 0x00000000 • CV: Counter Value CV contains the counter value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 CV[15:8] 76543210 CV[7:0] 669 32142D–06/2013 ATUC64/128/256L3/4U 26.7.5 Channel Register A Name: RA Access Type: Read-only if CMRn.WAVE = 0, Read/Write if CMRn.WAVE = 1 Offset: 0x14 + n * 0X40 Reset Value: 0x00000000 • RA: Register A RA contains the Register A value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RA[15:8] 76543210 RA[7:0] 670 32142D–06/2013 ATUC64/128/256L3/4U 26.7.6 Channel Register B Name: RB Access Type: Read-only if CMRn.WAVE = 0, Read/Write if CMRn.WAVE = 1 Offset: 0x18 + n * 0x40 Reset Value: 0x00000000 • RB: Register B RB contains the Register B value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RB[15:8] 76543210 RB[7:0] 671 32142D–06/2013 ATUC64/128/256L3/4U 26.7.7 Channel Register C Name: RC Access Type: Read/Write Offset: 0x1C + n * 0x40 Reset Value: 0x00000000 • RC: Register C RC contains the Register C value in real time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 RC[15:8] 76543210 RC[7:0] 672 32142D–06/2013 ATUC64/128/256L3/4U 26.7.8 Channel Status Register Name: SR Access Type: Read-only Offset: 0x20 + n * 0x40 Reset Value: 0x00000000 Note: Reading the Status Register will also clear the interrupt bit for the corresponding interrupts. • MTIOB: TIOB Mirror 1: TIOB is high. If CMRn.WAVE is zero, this means that TIOB pin is high. If CMRn.WAVE is one, this means that TIOB is driven high. 0: TIOB is low. If CMRn.WAVE is zero, this means that TIOB pin is low. If CMRn.WAVE is one, this means that TIOB is driven low. • MTIOA: TIOA Mirror 1: TIOA is high. If CMRn.WAVE is zero, this means that TIOA pin is high. If CMRn.WAVE is one, this means that TIOA is driven high. 0: TIOA is low. If CMRn.WAVE is zero, this means that TIOA pin is low. If CMRn.WAVE is one, this means that TIOA is driven low. • CLKSTA: Clock Enabling Status 1: This bit is set when the clock is enabled. 0: This bit is cleared when the clock is disabled. • ETRGS: External Trigger Status 1: This bit is set when an external trigger has occurred. 0: This bit is cleared when the SR register is read. • LDRBS: RB Loading Status 1: This bit is set when an RB Load has occurred and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • LDRAS: RA Loading Status 1: This bit is set when an RA Load has occurred and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • CPCS: RC Compare Status 1: This bit is set when an RC Compare has occurred. 0: This bit is cleared when the SR register is read. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - MTIOB MTIOA CLKSTA 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 673 32142D–06/2013 ATUC64/128/256L3/4U • CPBS: RB Compare Status 1: This bit is set when an RB Compare has occurred and CMRn.WAVE is one. 0: This bit is cleared when the SR register is read. • CPAS: RA Compare Status 1: This bit is set when an RA Compare has occurred and CMRn.WAVE is one. 0: This bit is cleared when the SR register is read. • LOVRS: Load Overrun Status 1: This bit is set when RA or RB have been loaded at least twice without any read of the corresponding register and CMRn.WAVE is zero. 0: This bit is cleared when the SR register is read. • COVFS: Counter Overflow Status 1: This bit is set when a counter overflow has occurred. 0: This bit is cleared when the SR register is read. 674 32142D–06/2013 ATUC64/128/256L3/4U 26.7.9 Channel Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x24 + n * 0x40 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 675 32142D–06/2013 ATUC64/128/256L3/4U 26.7.10 Channel Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x28 + n * 0x40 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 676 32142D–06/2013 ATUC64/128/256L3/4U 26.7.11 Channel Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x2C + n * 0x40 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ETRGS LDRBS LDRAS CPCS CPBS CPAS LOVRS COVFS 677 32142D–06/2013 ATUC64/128/256L3/4U 26.7.12 Block Control Register Name: BCR Access Type: Write-only Offset: 0xC0 Reset Value: 0x00000000 • SYNC: Synchro Command 1: Writing a one to this bit asserts the SYNC signal which generates a software trigger simultaneously for each of the channels. 0: Writing a zero to this bit has no effect. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - SYNC 678 32142D–06/2013 ATUC64/128/256L3/4U 26.7.13 Block Mode Register Name: BMR Access Type: Read/Write Offset: 0xC4 Reset Value: 0x00000000 • TC2XC2S: External Clock Signal 2 Selection • TC1XC1S: External Clock Signal 1 Selection 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - TC2XC2S TC1XC1S TC0XC0S TC2XC2S Signal Connected to XC2 0 TCLK2 1 none 2 TIOA0 3 TIOA1 TC1XC1S Signal Connected to XC1 0 TCLK1 1 none 2 TIOA0 3 TIOA2 679 32142D–06/2013 ATUC64/128/256L3/4U • TC0XC0S: External Clock Signal 0 Selection TC0XC0S Signal Connected to XC0 0 TCLK0 1 none 2 TIOA1 3 TIOA2 680 32142D–06/2013 ATUC64/128/256L3/4U 26.7.14 Features Register Name: FEATURES Access Type: Read-only Offset: 0xF8 Reset Value: - • BRPBHSB: Bridge type is PB to HSB 1: Bridge type is PB to HSB. 0: Bridge type is not PB to HSB. • UPDNIMPL: Up/down is implemented 1: Up/down counter capability is implemented. 0: Up/down counter capability is not implemented. • CTRSIZE: Counter size This field indicates the size of the counter in bits. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 ------- 15 14 13 12 11 10 9 8 - - - - - - BRPBHSB UPDNIMPL 76543210 CTRSIZE 681 32142D–06/2013 ATUC64/128/256L3/4U 26.7.15 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • VARIANT: Variant number Reserved. No functionality associated. • VERSION: Version number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 682 32142D–06/2013 ATUC64/128/256L3/4U 26.8 Module Configuration The specific configuration for each Timer/Counter instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 26.8.1 Clock Connections There are two Timer/Counter modules, TC0 and TC1, with three channels each, giving a total of six Timer/Counter channels. Each Timer/Counter channel can independently select an internal or external clock source for its counter: Table 26-4. TC Bus Interface Clocks Module name Clock Name Description TC0 CLK_TC0 Clock for the TC0 bus interface TC1 CLK_TC1 Clock for the TC1 bus interface Table 26-5. Timer/Counter Clock Connections Module Source Name Connection TC0 Internal TIMER_CLOCK1 32 KHz oscillator clock (CLK_32K) TIMER_CLOCK2 PBA Clock / 2 TIMER_CLOCK3 PBA Clock / 8 TIMER_CLOCK4 PBA Clock / 32 TIMER_CLOCK5 PBA Clock / 128 External XC0 See Section on page 10 XC1 XC2 TC1 Internal TIMER_CLOCK1 32 KHz oscillator clock (CLK_32K) TIMER_CLOCK2 PBA Clock / 2 TIMER_CLOCK3 PBA Clock / 8 TIMER_CLOCK4 PBA Clock / 32 TIMER_CLOCK5 PBA Clock / 128 External XC0 See Section on page 10 XC1 XC2 683 32142D–06/2013 ATUC64/128/256L3/4U 27. Peripheral Event System Rev: 1.0.0.1 27.1 Features • Direct peripheral to peripheral communication system • Allows peripherals to receive, react to, and send peripheral events without CPU intervention • Cycle deterministic event communication • Asynchronous interrupts allow advanced peripheral operation in low power sleep modes 27.2 Overview Several peripheral modules can be configured to emit or respond to signals known as peripheral events. The exact condition to trigger a peripheral event, or the action taken upon receiving a peripheral event, is specific to each module. Peripherals that respond to peripheral events are called peripheral event users and peripherals that emit peripheral events are called peripheral event generators. A single module can be both a peripheral event generator and user. The peripheral event generators and users are interconnected by a network known as the Peripheral Event System. This allows low latency peripheral-to-peripheral signaling without CPU intervention, and without consuming system resources such as bus or RAM bandwidth. This offloads the CPU and system resources compared to a traditional interrupt-based software driven system. 27.3 Peripheral Event System Block Diagram Figure 27-1. Peripheral Event System Block Diagram 27.4 Functional Description 27.4.1 Configuration The Peripheral Event System in the ATUC64/128/256L3/4U has a fixed mapping of peripheral events between generators and users, as described in Table 27-1 to Table 27-4. Thus, the user does not need to configure the interconnection between the modules, although each peripheral event can be enabled or disabled at the generator or user side as described in the peripheral chapter for each module. Peripheral Event System Generator Generator User Generator/ User 684 32142D–06/2013 ATUC64/128/256L3/4U Table 27-1. Peripheral Event Mapping from ACIFB to PWMA Generator Generated Event User Effect Asynchronous ACIFB channel 0 AC0 VINP > AC0 VINN PWMA channel 0 PWMA duty cycle value increased by one No AC0 VINN > AC0 VINP PWMA duty cycle value decreased by one ACIFB channel 1 AC1 VINP > AC1 VINN PWMA channel 6 PWMA duty cycle value increased by one AC1 VINN > AC1 VINP PWMA duty cycle value decreased by one ACIFB channel 2 AC2 VINP > AC2 VINN PWMA channel 8 PWMA duty cycle value increased by one AC2 VINN > AC2 VINP PWMA duty cycle value decreased by one ACIFB channel 3 AC3 VINP > AC3 VINN PWMA channel 9 PWMA duty cycle value increased by one AC3 VINN > AC3 VINP PWMA duty cycle value decreased by one ACIFB channel 4 AC4 VINP > AC4 VINN PWMA channel 11 PWMA duty cycle value increased by one AC4 VINN > AC4 VINP PWMA duty cycle value decreased by one ACIFB channel 5 AC5 VINP > AC5 VINN PWMA channel 14 PWMA duty cycle value increased by one AC5 VINN > AC5 VINP PWMA duty cycle value decreased by one ACIFB channel 6 AC6 VINP > AC6 VINN PWMA channel 19 PWMA duty cycle value increased by one AC6 VINN > AC6 VINP PWMA duty cycle value decreased by one ACIFB channel 7 AC7 VINP > AC7 VINN PWMA channel 20 PWMA duty cycle value increased by one AC7 VINN > AC7 VINP PWMA duty cycle value decreased by one ACIFB channel n ACn VINN > ACn VINP CAT Automatically used by the CAT when performing QMatrix acquisition. No Table 27-2. Peripheral Event Mapping from GPIO to TC Generator Generated Event User Effect Asynchronous GPIO Pin change on PA00-PA07 TC0 A0 capture No Pin change on PA08-PA15 A1 capture Pin change on PA16-PA23 A2 capture Pin change on PB00-PB07 TC1 A1 capture Pin change on PB08-PB15 A2 capture 685 32142D–06/2013 ATUC64/128/256L3/4U 27.4.2 Peripheral Event Connections Each generated peripheral event is connected to one or more users. If a peripheral event is connected to multiple users, the peripheral event can trigger actions in multiple modules. A peripheral event user can likewise be connected to one or more peripheral event generators. If a peripheral event user is connected to multiple generators, the peripheral events are OR’ed together to a single peripheral event. This means that peripheral events from either one of the generators will result in a peripheral event to the user. To configure a peripheral event, the peripheral event must be enabled at both the generator and user side. Even if a generator is connected to multiple users, only the users with the peripheral event enabled will trigger on the peripheral event. 27.4.3 Low Power Operation As the peripheral events do not require CPU intervention, they are available in Idle mode. They are also available in deeper sleep modes if both the generator and user remain clocked in that mode. Certain events are known as asynchronous peripheral events, as identified in Table 27-1 to Table 27-4. These can be issued even when the system clock is stopped, and revive unclocked user peripherals. The clock will be restarted for this module only, without waking the system from sleep mode. The clock remains active only as long as required by the triggered function, before being switched off again, and the system remains in the original sleep mode. The CPU and sysTable 27-3. Peripheral Event Mapping from AST Generator Generated Event User Effect Asynchronous AST Overflow event ACIFB Comparison is triggered if the ACIFB.CONFn register is written to 11 (Event Triggered Single Measurement Mode) and the EVENTEN bit in the ACIFB.CTRL register is written to 1. Yes Periodic event Alarm event Overflow event ADCIFB Conversion is triggered if the TRGMOD bit in the ADCIFB.TRGR register is written to 111 (Peripheral Event Trigger). Periodic event Alarm event Overflow event CAT Trigger one iteration of autonomous touch detection. Periodic event Alarm event Table 27-4. Peripheral Event Mapping from PWMA Generator Generated Event User Effect Asynchronous PWMA channel 0 Timebase counter reaches the duty cycle value. ACIFB Comparison is triggered if the ACIFB.CONFn register is written to 11 (Event Triggered Single Measurement Mode) and the EVENTEN bit in the ACIFB.CTRL register is written to 1. No ADCIFB Conversion is triggered if the TRGMOD bit in the ADCIFB.TRGR register is written to 111 (Peripheral Event Trigger). 686 32142D–06/2013 ATUC64/128/256L3/4U tem will only be woken up if the user peripheral generates an interrupt as a result of the operation. This concept is known as SleepWalking and is described in further detail in the Power Manager chapter. Note that asynchronous peripheral events may be associated with a delay due to the need to restart the system clock source if this has been stopped in the sleep mode. 27.5 Application Example This application example shows how the Peripheral Event System can be used to program the ADC Interface to perform ADC conversions at selected intervals. Conversions of the active analog channels are started with a software or a hardware trigger. One of the possible hardware triggers is a peripheral event trigger, allowing the Peripheral Event System to synchronize conversion with some configured peripheral event source. From Table 27-3 and Table 27-4, it can be read that this peripheral event source can be either an AST peripheral event, or an event from the PWM Controller. The AST can generate periodic peripheral events at selected intervals, among other types of peripheral events. The Peripheral Event System can then be used to set up the ADC Interface to sample an analog signal at regular intervals. The user must enable peripheral events in the AST and in the ADC Interface to accomplish this. The periodic peripheral event in the AST is enabled by writing a one to the corresponding bit in the AST Event Enable Register (EVE). To select the peripheral event trigger for the ADC Interface, the user must write the value 0x7 to the Trigger Mode (TRGMOD) field in the ADC Interface Trigger Register (TRGR). When the peripheral events are enabled, the AST will generate peripheral events at the selected intervals, and the Peripheral Event System will route the peripheral events to the ADC Interface, which will perform ADC conversions at the selected intervals. Figure 27-2. Application Example Since the AST peripheral event is asynchronous, the description above will also work in sleep modes where the ADC clock is stopped. In this case, the ADC clock (and clock source, if needed) will be restarted during the ADC conversion. After the conversion, the ADC clock and clock source will return to the sleep state, unless the ADC generates an interrupt, which in turn will wake up the system. Using asynchronous interrupts thus allows ADC operation in much lower power states than would otherwise be possible. Peripheral Event System AST ADC Interface Trigger conversion Periodic peripheral event 687 32142D–06/2013 ATUC64/128/256L3/4U 28. Audio Bit Stream DAC (ABDACB) Rev.: 1.0.0.0 28.1 Features • 16 bit digital stereo DAC • Oversampling D/A conversion architecture – Adjustable oversampling ratio – 3rd order Sigma-Delta D/A converters • Digital bitstream output • Parallel interface • Connects to DMA for background transfer without CPU intervention • Supported sampling frequencies – 8000Hz, 11025Hz, 12000Hz, 16000Hz, 22050Hz, 24000Hz, 32000Hz, 44100Hz, and 48000Hz • Supported data formats – 32-, 24-, 20-, 18-, 16-, and 8-bit stereo format – 16- and 8-bit compact stereo format, with left and right sample packed in the same word to reduce data transfers • Common mode offset control • Volume control 28.2 Overview The Audio Bitstream DAC (ABDACB) converts a 16-bit sample value to a digital bitstream with an average value proportional to the sample value. Two channels are supported making the Audio Bitstream DAC particularly suitable for stereo audio. Each channel has a pair of complementary digital outputs, DAC and DACN, which can be connected to an external high input impedance amplifier. The Audio Bitstream DAC is made up of several signal processing blocks and a 3rd order Sigma Delta D/A converter for each channel. The Sigma Delta modulator converts the parallel data to a bitstream, while the signal processing blocks perform volume control, offset control, upsampling, and filtering to compensate for the upsampling process. The upsampling is performed by a Cascaded Integrator-Comb (CIC) filter, and the compensation filter is a Finite Impulse Response (FIR) CIC compensation filter. 28.3 Block Diagram Figure 28-1. ABDACB Block Diagram User Inter af ce Synchronizer Volume control Offset control CIC Compensation filter (FIR) CIC Comb Section CIC Integrator section Clock divider Sigma Delta Modulator Sigma Delta Modulator clk_abdacb gclk Signal processing (before up-sampling) CLK DAC[0] DACN[0] DAC[1] DACN[1] PB 688 32142D–06/2013 ATUC64/128/256L3/4U 28.4 I/O Lines Description 28.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 28.5.1 I/O lines The output pins used for the output bitstream from the Audio Bitstream DAC may be multiplexed with I/O Controller lines. Before using the Audio Bitstream DAC, the I/O Controller must be configured in order for the Audio Bitstream DAC I/O lines to be in Audio Bitstream DAC peripheral mode. 28.5.2 Clocks The clock for the ABDACB bus interface (CLK_ABDACB) is generated by the Power Manager. This clock is turned on by default, and can be enabled and disabled in the Power Manager. It is recommended to disable the ABDACB before disabling the clock, to avoid freezing the ABDACB in an undefined state. Before using the Audio Bitstream DAC, the user must ensure that the Audio Bitstream DAC clock is enabled in the Power Manager. The Audio Bitstream DAC requires a separate clock for the D/A conversion. This clock is provided by a generic clock which has to be set up in the System Control Interface (SCIF). The frequency for this clock has to be set as described in Table 28-3 on page 697. It is important that this clock is accurate and has low jitter. Incorrect frequency will result in too fast or too slow playback (frequency shift), and too high jitter will add noise to the D/A conversion. For best performance one should trade frequency accuracy (within some limits) for low jitter to obtain the best performance as jitter will have large impact on the quality of the converted signal. 28.5.3 DMA The ABDACB is connected to the Peripheral DMA controller. Using DMA to transfer data samples requires the Peripheral DMA controller to be programmed before enabling the ABDACB. 28.5.4 Interrupts The ABDACB interrupt request line is connected to the interrupt controller. Using the ABDACB interrupt requires the interrupt controller to be programmed first. Table 28-1. I/O Lines Description Pin Name Pin Description Type DAC[0] Output for channel 0 Output DACN[0] Inverted output for channel 0 Output DAC[1] Output for channel 1 Output DACN[1] Inverted output for channel 1 Output CLK Clock output for DAC Output 689 32142D–06/2013 ATUC64/128/256L3/4U 28.6 Functional Description 28.6.1 Construction The Audio Bitstream DAC is divided into several parts, the user interface, the signal processing blocks, and the Sigma Delta modulator blocks. See Figure 28-1 on page 687. The user interface is used to configure the signal processing blocks and to input new data samples to the converter.The signal processing blocks manages volume control, offset control, and upsampling. The Sigma Delta blocks converts the parallel data to1-bit bitstreams. 28.6.1.1 CIC Interpolation Filter The interpolation filter in the system is a Cascaded Integrator-Comb (CIC) interpolation filter which interpolates from Fs to {125, 128, 136}xFs depending on the control settings. This filter is a 4th order CIC filter, and the basic building blocks of the filter is a comb part and an integrator part. Since the CIC interpolator has a sinc-function frequency response it is compensated by a linear phase CIC compensation filter to make the passband response more flat in the range 0- 20kHz, see figure Figure 28-4 on page 693. The frequency response of this type of interpolator has the first zero at the input sampling frequency. This means that the first repeated specters created by the upsampling process will not be fully rejected and the output signal will contain signals from these repeated specters. See Figure 28-6 on page 694. Since the human ear can not hear frequencies above 20kHz, we should not be affected by this when the sample rate is above 40kHz, but digital measurement equipment will be affected. This need to be accounted for when doing measurements on the system to prevent aliasing and incorrect measurement results. 28.6.1.2 Sigma Delta Modulator The Sigma Delta modulator is a 3rd order modulator consisting of three differentiators (delta blocks), three integrators (sigma blocks), and a one bit quantizer. The purpose of the integrators is to shape the noise, so that the noise is reduced in the audio passband and increased at the higher frequencies, where it can be filtered out by an analog low-pass filter. To be able to filter out all the noise at high frequencies the analog low-pass filter must be one order larger than the Sigma Delta modulator. 28.6.1.3 Recreating the Analog Signal Since the DAC and DACN outputs from the ABDAC are digital square wave signals, they have to be passed through a low pass filter to recreate the analog signal. This also means that noise on the IO voltage will couple through to the analog signal. To remove some of the IO noise the ABDAC can output a clock signal, CLK, which can be used to resample the DAC and DACN signals on external Flip-Flops powered by a clean supply. 28.6.2 Initialization Before enabling the ABDACB the correct configuration must be applied to the Control Register (CR). Configuring the Alternative Upsampling Ratio bit (CR.ALTUPR), Common Mode Offset Control bit (CR.CMOC), and the Sampling Frequency field (CR.FS) according to the sampling rate of the data that is converted and the type of amplifier the outputs are connected to is required to get the correct behavior of the system. When the correct configuration is applied the ABDACB can be enabled by writing a one to the Enable bit in the Control Register (CR.EN). The module is disabled by writing a zero to the Enable bit. The module should be disabled before entering sleep modes to ensure that the outputs are not left in an undesired state. 690 32142D–06/2013 ATUC64/128/256L3/4U 28.6.3 Basic operation To convert audio data to a digital bitstream the user must first initialize the ABDACB as described in Section 28.6.2. When the ABDACB is initialized and enabled it will indicate that it is ready to receive new data by setting the Transmit Ready bit in the Status Register (SR.TXRDY). When the TXRDY bit is set in the Status Register the user has to write new samples to Sample Data Register 0 (SDR0) and Sample Data Register 1 (SDR1). If the Mono Mode (MONO) bit in the Control Register (CR) is set, or one of the compact stereo formats are used by configuring the Data Word Format (DATAFORMAT) in the Control Register, only SDR0 has to be written. Failing to write to the sample data registers will result in an underrun indicated by the Transmit Underrun (TXUR) bit in the Status Register (SR.TXUR). When new samples are written to the sample data registers the TXRDY bit will be cleared. To increase performance of the system an interrupt handler or DMA transfer can be used to write new samples to the sample data registers. See Section 28.6.10 for details on DMA, and Section 28.6.11 for details on interrupt. 28.6.4 Data Format The input data type is two’s complement. The Audio Bitstream DAC can be configured to accept different audio formats. The format must be configured in the Data Word Format field in the Control Register. In regular operation data for the two channels are written to the sample data registers SDR0 and SDR1. If the data format field specifies a format using less than 32 bits, data must be written right-justified in SDR0 and SDR1. Sign extension into the unused bits is not necessary. Only the 16 most significant bits in the data will be used by the ABDACB. For data formats larger than 16 bits the least significant bits are ignored. For 8-bit data formats the 8 bits will be used as the most significant bits in the 16-bit samples, the additional bits will be zeros. The ABDACB also supports compact data formats for 16- and 8-bit samples. For 16-bit samples the sample for channel 0 must be written to bits 15 through 0 and the sample for channel 1 must be written to bits 31 through 16 in SDR0. For 8-bit samples the sample for channel 0 must be written to bits 7 through 0 and the sample for channel 1 must be written to bits 15 through 8 in SDR0. SDR1 is not used in this mode. See Table 28-5 on page 699. 28.6.5 Data Swapping When the Swap Channels (SWAP) bit in the Control Register (CR.SWAP) is one, writing to the Sample Data Register 0 (SDR0) will put the data in Sample Data Register 1 (SDR1). Writing SDR1 will put the data in SDR0. If one of the two compact stereo formats is used the lower and upper halfword of SDR0 will be swapped when writing to SDR0. 28.6.6 Common Mode Offset Control When the Common Mode Offset Control (CMOC) bit in the Control Register is one the input data will get a DC value applied to it and the amplitude will be scaled. This will make the common mode offset of the two corresponding outputs, DAC and DACN, to move away from each other so that the output signals are not overlapping. The result is that the two signals can be applied to a differential analog filter, and the difference will always be a positive value, removing the need for a negative voltage supply for the filter. The cost of doing this a 3dB loss in dynamic range. On the left side of Figure 28-2 one can see the filtered output from the DAC and DACN pins when a sine wave is played when CR.CMOC is zero. The waveform on the right side shows the output of the differential filter when the two outputs on the left side are used as inputs to the differential filter. Figure 28-3 show the corresponding outputs when CR.CMOC is one. 691 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-2. Output signals with CMOC=0 Figure 28-3. Output signals with CMOC=1 28.6.7 Volume Control The Audio Bitstream DAC have two volume control registers, Volume Control Register 0 (VCR0) and Volume Control Register 1 (VCR1), that can be used to adjust the volume for the corresponding channel. The volume control is linear and will only scale each sample according to the value in the Volume Control (VOLUME) field in the volume control registers. The register also has a Mute bit (MUTE) which can be used to mute the corresponding channel. The filtered out- 692 32142D–06/2013 ATUC64/128/256L3/4U put of the DAC pins will have a voltage given by the following equation, given that it is configured to run at the default upsampling ratio of 128: If one want to get coherence between the sign of the input data and the output voltage one can use the DATAN outputs or invert the sign of the input data by software. 28.6.8 Mono When the Mono bit (MONO) in the Control Register is set, data written to SDR0 will be used for both output channels. If one of the compact stereo formats are used only the data written to the part of SDR0 that corresponds with channel 0 is used. 28.6.9 Alternative Upsampling Ratio The digital filters and Sigma Delta modulators requires its own clock to perform the conversion at the correct speed, and this clock is provided by a generic clock in the SCIF. The frequency of this clock depends on the input sample rate and the upsampling ratio which is controlled by the Alternative Upsampling Ratio bit (ALTUPR) in the Control Register. The ABDACB supports three upsampling ratios, 125, 128, and 136. The default setting is a ratio of 128, and is used when CR.ALTUPR is zero. Using this ratio gives a clock frequency requirement that is common for audio products. In some cases one may want to use other clock frequencies that already are available in the system. By writing a one to CR.ALTUPR a upsampling ratio of 125 or 136 is used depending on the configuration of the Sampling Frequency field in the Control Register. Refer to Table 28-3 for required clock frequency and settings. The required clock frequency of the generic clock can be calculated from the following equation: R is the upsampling ratio of the converter. If CR.ALTUPR is zero the upsampling ratio is 128. If CR.ALTUPR is one, R will change to 125 when CR.FS is configured for 8kHz, 12kHz, 16kHz, 24kHz, 32kHz, and 48kHz. For the other configurations of CR.FS, 11.025kHz, 22.050kHz, and 44.100kHz, it will change to 136. 28.6.10 DMA operation The Audio Bitstream DAC is connected to the Peripheral DMA Controller. The Peripheral DMA Controller can be programmed to automatically transfer samples to the Sample Data Registers (SDR0 and SDR1) when the Audio Bitstream DAC is ready for new samples. Two DMA channels are used, one for each sample data register. If the Mono Mode bit in the Control Register (CR.MONO) is one, or one of the compact stereo formats is used, only the DMA channel connected to SDR0 will be used. When using DMA only the Control Register needs to be written in the Audio Bitstream DAC. This enables the Audio Bitstream DAC to operate without any CPU intervention such as polling the Status Register (SR) or using interrupts. See the Peripheral DMA Controller documentation for details on how to setup Peripheral DMA transfers. 28.6.11 Interrupts The ABDACB requires new data samples at a rate of FS. The interrupt status bits are used to indicate when the system is ready to receive new samples. The Transmit Ready Interrupt Status bit in the Status Register (SR.TXRDY) will be set whenever the ABDACB is ready to receive a new sample. A new sample value must be written to the sample data registers (SDR0 and VOUT 1 2 -- 33 128 – --------- SDR 215 ------------ VOLUME 215 – 1   ------------------------     VVDDIO =  GCLK[Hz] F = S   R 8 693 32142D–06/2013 ATUC64/128/256L3/4U SDR1) before 1/FS second, or an underrun will occur, as indicated by the Underrun Interrupt bit in SR (SR.TXUR). The interrupt bits in SR are cleared by writing a one to the corresponding bit in the Status Clear Register (SCR). 28.6.12 Frequency Response Figure Figure 28-4 to Figure 28-7 show the frequency response for the system. The sampling frequency used is 48kHz, but the response will be the same for other sampling frequencies, always having the first zero at FS. Figure 28-4. Passband Frequency Response 694 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-5. Frequency Response up to Sampling Frequency Figure 28-6. Frequency Response up to 3x Sampling Frequency 695 32142D–06/2013 ATUC64/128/256L3/4U Figure 28-7. Frequency Response up to 128x Sampling Frequency 696 32142D–06/2013 ATUC64/128/256L3/4U 28.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 28-2. ABDACB Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CR Read/Write 0x00000000 0x04 Sample Data Register 0 SDR0 Read/Write 0x00000000 0x08 Sample Data Register 1 SDR1 Read/Write 0x00000000 0x0C Volume Control Register 0 VCR0 Read/Write 0x00000000 0x10 Volume Control Register 1 VCR1 Read/Write 0x00000000 0x14 Interrupt Enable Register IER Write-only 0x00000000 0x18 Interrupt Disable Register IDR Write-only 0x00000000 0x1C Interrupt Mask Register IMR Read-only 0x00000000 0x20 Status Register SR Read-only 0x00000000 0x24 Status Clear Register SCR Write-only 0x00000000 0x28 Parameter Register PARAMETER Read-only - (1) 0x2C Version Register VERSION Read-only - (1) 697 32142D–06/2013 ATUC64/128/256L3/4U 28.7.1 Control Register Name: CR Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • FS: Sampling Frequency Must be set to the matching data sampling frequency, see Table 28-3. Note: 1. The actual clock requirement are 11.9952MHz, 23.9904MHz, and 47.9808MHz, but this is very close to the suggested clock frequencies, and will only result in a very small frequency shift. This need to be accounted for during testing if comparing to a reference signal. Notes: 1. 31 30 29 28 27 26 25 24 - - - - FS 23 22 21 20 19 18 17 16 - - - - - DATAFORMAT 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - MONO CMOC ALTUPR - SWAP EN Table 28-3. Generic Clock Requirements CR.FS Description GCLK (CR.ALTUPR=1) GCLK (CR.ALTUPR=0) 0 8000Hz sampling frequency 8.0MHz 8.1920MHz 1 11025Hz sampling frequency 12.0MHz(1) 11.2896MHz 2 12000Hz sampling frequency 12.0MHz 12.2880MHz 3 16000Hz sampling frequency 16.0MHz 16.3840MHz 4 22050Hz sampling frequency 24.0MHz(1) 22.5792MHz 5 24000Hz sampling frequency 24.0MHz 24.5760MHz 6 32000Hz sampling frequency 32.0MHz 32.7680MHz 7 44100Hz sampling frequency 48.0MHz(1) 45.1584MHz 8 48000Hz sampling frequency 48.0MHz 49.1520MHz Other Reserved - - 698 32142D–06/2013 ATUC64/128/256L3/4U • DATAFORMAT: Data Word Format • SWRST: Software Reset Writing a zero to this bit does not have any effect. Writing a one to this bit will reset the ABDACB as if a hardware reset was done. • MONO: Mono Mode 0: Mono mode is disabled. 1: Mono mode is enabled. • CMOC: Common Mode Offset Control 0: Common mode adjustment is disabled. 1: Common mode adjustment is enabled. • ALTUPR: Alternative Upsampling Ratio 0: Alternative upsampling is disabled. 1: Alternative upsampling is enabled. • SWAP: Swap Channels 0: Channel swap is disabled. 1: Channel swap is enabled. • EN: Enable 0: The ABDACB is disabled. 1: The ABDACB is enabled. Table 28-4. Data Word Format DATAFORMAT Word length Comment 0 32 bits 1 24 bits 2 20 bits 3 18 bits 4 16 bits 5 16 bits compact stereo Channel 1 sample in bits 31 through 16, channel 0 sample in bits 15 through 0 in SDR0 6 8 bits 7 8 bits compact stereo Channel 1 sample in bits 15 through 8, channel 0 sample in bits 7through 0 in SDR0 699 32142D–06/2013 ATUC64/128/256L3/4U 28.7.2 Sample Data Register 0 Name: SDR0 Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • DATA: Sample Data Sample Data for channel 0 in two’s complement format. Data must be right-justified, see Table 28-5. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] Table 28-5. Sample Data Register Formats Data Format SDR0 SDR1 Comment 32 bits CH0 sample in DATA[31:0] CH1 sample in DATA[31:0] 24 bits CH0 sample in DATA[23:0] CH1 sample in DATA[23:0] Remaining bits are ignored. 20 bits CH0 sample in DATA[19:0] CH1 sample in DATA[19:0] Remaining bits are ignored. 18 bits CH0 sample in DATA[17:0] CH1 sample in DATA[17:0] Remaining bits are ignored. 16 bits CH0 sample in DATA[15:0] CH1 sample in DATA[15:0] Remaining bits are ignored. 16 bits compact stereo CH0 sample in DATA[15:0] CH1 sample in DATA[31:16] Not used 8 bits CH0 sample in DATA[7:0] CH1 sample in DATA[7:0] Remaining bits are ignored. 8 bits compact stereo CH0 sample in DATA[7:0] CH1 sample in DATA[15:8] Not used Remaining bits are ignored. 700 32142D–06/2013 ATUC64/128/256L3/4U 28.7.3 Sample Data Register 1 Name: SDR1 Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • DATA: Sample Data Sample Data for channel 1 in two’s complement format. Data must be right-justified, see Table 28-5 on page 699. 31 30 29 28 27 26 25 24 DATA[31:24] 23 22 21 20 19 18 17 16 DATA[23:16] 15 14 13 12 11 10 9 8 DATA[15:8] 76543210 DATA[7:0] 701 32142D–06/2013 ATUC64/128/256L3/4U 28.7.4 Volume Control Register 0 Name: VCR0 Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • MUTE: Mute 0: Channel 0 is not muted. 1: Channel 0 is muted. • VOLUME: Volume Control 15-bit value adjusting the volume for channel 0. 31 30 29 28 27 26 25 24 MUTE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - VOLUME[14:8] 76543210 VOLUME[7:0] 702 32142D–06/2013 ATUC64/128/256L3/4U 28.7.5 Volume Control Register 1 Name: VCR1 Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • MUTE: Mute 0: Channel 1 is not muted. 1: Channel 1 is muted. • VOLUME: Volume Control 15-bit value adjusting the volume for channel 1. 31 30 29 28 27 26 25 24 MUTE - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - VOLUME[14:8] 76543210 VOLUME[7:0] 703 32142D–06/2013 ATUC64/128/256L3/4U 28.7.6 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 704 32142D–06/2013 ATUC64/128/256L3/4U 28.7.7 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x18 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 705 32142D–06/2013 ATUC64/128/256L3/4U 28.7.8 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 706 32142D–06/2013 ATUC64/128/256L3/4U 28.7.9 Status Register Name: SR Access Type: Read-only Offset: 0x20 Reset Value: 0x00000000 • TXUR: Transmit Underrun This bit is cleared when no underrun has occurred since the last time this bit was cleared (by reset or by writing to SCR). This bit is set when at least one underrun has occurred since the last time this bit was cleared (by reset or by writing to SCR). • TXRDY: Transmit Ready This bit is cleared when the ABDACB is not ready to receive a new data in SDR. This bit is set when the ABDACB is ready to receive a new data in SDR. • BUSY: ABDACB Busy This bit is set when the ABDACB is busy doing a data transfer between clock domains. CR, SDR0, and SDR1 can not be written during this time. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY BUSY 707 32142D–06/2013 ATUC64/128/256L3/4U 28.7.10 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TXUR TXRDY - 708 32142D–06/2013 ATUC64/128/256L3/4U 28.7.11 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 Reserved. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 -------- 709 32142D–06/2013 ATUC64/128/256L3/4U 28.7.12 Version Register Name: VERSION Access Type: Read-only Offset: 0x2C Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 710 32142D–06/2013 ATUC64/128/256L3/4U 28.8 Module Configuration The specific configuration for each ABDACB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 28-6. ABDACB Clocks Clock Name Description CLK_ABDACB Clock for the ABDACB bus interface GCLK The generic clock used for the ABDACB is GCLK6 Table 28-7. Register Reset Values Register Reset Value VERSION 0x00000100 PARAMETER 0x00000000 711 32142D–06/2013 ATUC64/128/256L3/4U 29. ADC Interface (ADCIFB) Rev:1.0.1.1 29.1 Features • Multi-channel Analog-to-Digital Converter with up to 12-bit resolution • Enhanced Resolution Mode – 11-bit resolution obtained by interpolating 4 samples – 12-bit resolution obtained by interpolating 16 samples • Glueless interface with resistive touch screen panel, allowing – Resistive Touch Screen position measurement – Pen detection and pen loss detection • Integrated enhanced sequencer – ADC Mode – Resistive Touch Screen Mode • Numerous trigger sources – Software – Embedded 16-bit timer for periodic trigger – Pen detect trigger – Continuous trigger – External trigger, rising, falling, or any-edge trigger – Peripheral event trigger • ADC Sleep Mode for low power ADC applications • Programmable ADC timings – Programmable ADC clock – Programmable startup time 29.2 Overview The ADC Interface (ADCIFB) converts analog input voltages to digital values. The ADCIFB is based on a Successive Approximation Register (SAR) 10-bit Analog-to-Digital Converter (ADC). The conversions extend from 0V to ADVREFP. The ADCIFB supports 8-bit and 10-bit resolution mode, in addition to enhanced resolution mode with 11-bit and 12-bit resolution. Conversion results are reported in a common register for all channels. The 11-bit and 12-bit resolution modes are obtained by interpolating multiple samples to acquire better accuracy. For 11-bit mode 4 samples are used, which gives an effective sample rate of 1/4 of the actual sample frequency. For 12-bit mode 16 samples are used, giving a effective sample rate of 1/16 of actual. This arrangement allows conversion speed to be traded for better accuracy. Conversions can be started for all enabled channels, either by a software trigger, by detection of a level change on the external trigger pin (TRIGGER), or by an integrated programmable timer. When the Resistive Touch Screen Mode is enabled, an integrated sequencer automatically configures the pad control signals and performs resistive touch screen conversions. The ADCIFB also integrates an ADC Sleep Mode, a Pen-Detect Mode, and an Analog Compare Mode, and connects with one Peripheral DMA Controller channel. These features reduce both power consumption and processor intervention. 712 32142D–06/2013 ATUC64/128/256L3/4U 29.3 Block Diagram Figure 29-1. ADCIFB Block Diagram ADVREFP Analog Multiplexer Successive Approximation Register Analog-to-Digital Converter Trigger ADC Control Logic Timer User Interface AD0 AD1 AD3 ADn AD2 Resisitve Touch Screen Sequencer CLK_ADCIFB .... ADCIFB ADP0 ADP1 I/O Controller TRIGGER Peripheral Bus DMA Request Interrupt Request CLK_ADC 713 32142D–06/2013 ATUC64/128/256L3/4U 29.4 I/O Lines Description 29.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 29.5.1 I/O Lines The analog input pins can be multiplexed with I/O Controller lines. The user must make sure the I/O Controller is configured correctly to allow the ADCIFB access to the AD pins before the ADCIFB is instructed to start converting data. If the user fails to do this the converted data may be wrong. The number of analog inputs is device dependent, please refer to the ADCIFB Module Configuration chapter for the number of available AD inputs on the current device. The ADVREFP pin must be connected correctly prior to using the ADCIFB. Failing to do so will result in invalid ADC operation. See the Electrical Characteristics chapter for details. If the TRIGGER, ADP0, and ADP1 pins are to be used in the application, the user must configure the I/O Controller to assign the needed pins to the ADCIFB function. 29.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the ADCIFB, the ADCIFB will stop functioning and resume operation after the system wakes up from sleep mode. If the Peripheral Event System is configured to send asynchronous peripheral events to the ADCIFB and the clock used by the ADCIFB is stopped, a local and temporary clock will automatically be requested so the event can be processed. Refer to Section 29.6.13, Section 29.6.12, and the Peripheral Event System chapter for details. Before entering a sleep mode where the clock to the ADCIFB is stopped, make sure the Analogto-Digital Converter cell is put in an inactive state. Refer to Section 29.6.13 for more information. 29.5.3 Clocks The clock for the ADCIFB bus interface (CLK_ADCIFB) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the ADCIFB before disabling the clock, to avoid freezing the ADCIFB in an undefined state. Table 29-1. I/O Lines Description Pin Name Description Type ADVREFP Reference voltage Analog TRIGGER External trigger Digital ADP0 Drive Pin 0 for Resistive Touch Screen top channel (Xp) Digital ADP1 Drive Pin 1 for Resistive Touch Screen right channel (Yp) Digital AD0-ADn Analog input channels 0 to n Analog 714 32142D–06/2013 ATUC64/128/256L3/4U 29.5.4 DMA The ADCIFB DMA handshake interface is connected to the Peripheral DMA Controller. Using the ADCIFB DMA functionality requires the Peripheral DMA Controller to be programmed first. 29.5.5 Interrupts The ADCIFB interrupt request line is connected to the interrupt controller. Using the ADCIFB interrupt request functionality requires the interrupt controller to be programmed first. 29.5.6 Peripheral Events The ADCIFB peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details 29.5.7 Debug Operation When an external debugger forces the CPU into debug mode, this module continues normal operation. If this module is configured in a way that requires it to be periodically serviced by the CPU through interrupt requests or similar, improper operation or data loss may result during debugging. 29.6 Functional Description The ADCIFB embeds a Successive Approximation Register (SAR) Analog-to-Digital Converter (ADC). The ADC supports 8-bit or 10-bit resolution, which can be extended to 11 or 12 bits by the Enhanced Resolution Mode. The conversion is performed on a full range between 0V and the reference voltage pin ADVREFP. Analog inputs between these voltages converts to digital values (codes) based on a linear conversion. This linear conversion is described in the expression below where M is the number of bits used to represent the analog value, Vin is the voltage of the analog value to convert, Vref is the maximum voltage, and Code is the converted digital value. 29.6.1 Initializing the ADCIFB The ADC Interface is enabled by writing a one to the Enable bit in the Control Register (CR.EN). After the ADC Interface is enabled, the ADC timings needs to be configured by writing the correct values to the RES, PRESCAL, and STARTUP fields in the ADC Configuration Register (ACR). See Section 29.6.5, and Section 29.6.7 for details. Before the ADCIFB can be used, the I/O Controller must be configured correctly and the Reference Voltage (ADVREFP) signal must be connected. Refer to Section 29.5.1 for details. 29.6.2 Basic Operation To convert analog values to digital values the user must first initialize the ADCIFB as described in Section 29.6.1. When the ADCIFB is initialized the channels to convert must be enabled by writing a one the corresponding bits in the Channel Enable Register (CHER). Enabling channel N instructs the ADCIFB to convert the analog voltage applied to AD pin N at each conversion sequence. Multiple channels can be enabled resulting in multiple AD pins being converted at each conversion sequence. Code 2M Vin  Vref = ------------------- 715 32142D–06/2013 ATUC64/128/256L3/4U To start converting data the user can either manually start a conversion sequence by writing a one to the START bit in the Control Register (CR.START) or configure an automatic trigger to initiate the conversions. The automatic trigger can be configured to trig on many different conditions. Refer to Section 29.8.1 for details. The result of the conversion is stored in the Last Converted Data Register (LCDR) as they become available, overwriting the result from the previous conversion. To avoid data loss if more than one channel is enabled, the user must read the conversion results as they become available either by using an interrupt handler or by using a Peripheral DMA channel to copy the results to memory. Failing to do so will result in an Overrun Error condition, indicated by the OVRE bit in the Status Register (SR). To use an interrupt handler the user must enable the Data Ready (DRDY) interrupt request by writing a one to the corresponding bit in the Interrupt Enable Register (IER). To clear the interrupt after the conversion result is read, the user must write a one to the corresponding bit in the Interrupt Clear Register (ICR). See Section 29.6.11 for details. To use a Peripheral DMA Controller channel the user must configure the Peripheral DMA Controller appropriately. The Peripheral DMA Controller will, when configured, automatically read converted data as they become available. There is no need to manually clear any bits in the Interrupt Status Register as this is performed by the hardware. If an Overrun Error condition happens during DMA operation, the OVRE bit in the SR will be set. 29.6.3 ADC Resolution The Analog-to-Digital Converter cell supports 8-bit or 10-bit resolution, which can be extended to 11-bit and 12-bit with the Enhanced Resolution Mode. The resolution is selected by writing the selected resolution value to the RES field in the ADC Configuration Register (ACR). See Section 29.9.3. By writing a zero to the RES field, the ADC switches to the lowest resolution and the conversion results can be read in the eight lowest significant bits of the Last Converted Data Register (LCDR). The four highest bits of the Last Converted Data (LDATA) field in the LCDR register reads as zero. Writing a one to the RES field enables 10-bit resolution, the optimal resolution for both sampling speed and accuracy. Writing two or three automatically enables Enhanced Resolution Mode with 11-bit or 12-bit resolution, see Section 29.6.4 for details. When a Peripheral DMA Controller channel is connected to the ADCIFB in 10-bit, 11-bit, or 12- bit resolution mode, a transfer size of 16 bits must be used. By writing a zero to the RES field, the destination buffers can be optimized for 8-bit transfers. 29.6.4 Enhanced Resolution Mode The Enhanced Resolution Mode is automatically enabled when 11-bit or 12-bit mode is selected in the ADC Configuration Register (ACR). In this mode the ADCIFB will trade conversion performance for accuracy by averaging multiple samples. To be able to increase the accuracy by averaging multiple samples it is important that some noise is present in the input signal. The noise level should be between one and two LSB peakto-peak to get good averaging performance. The performance cost of enabling 11-bit mode is 4 ADC samples, which reduces the effective ADC performance by a factor 4. For 12-bit mode this factor is 16. For 12-bit mode the effective sample rate is maximum ADC sample rate divided by 16. 716 32142D–06/2013 ATUC64/128/256L3/4U 29.6.5 ADC Clock The ADCIFB generates an internal clock named CLK_ADC that is used by the Analog-to-Digital Converter cell to perform conversions. The CLK_ADC frequency is selected by writing to the PRESCAL field in the ADC Configuration Register (ACR). The CLK_ADC range is between CLK_ADCIFB/2, if PRESCAL is 0, and CLK_ADCIFB/128, if PRESCAL is 63 (0x3F). A sensible PRESCAL value must be used in order to provide an ADC clock frequency according to the maximum sampling rate parameter given in the Electrical Characteristics section. Failing to do so may result in incorrect Analog-to-Digital Converter operation. 29.6.6 ADC Sleep Mode The ADC Sleep Mode maximizes power saving by automatically deactivating the Analog-to-Digital Converter cell when it is not being used for conversions. The ADC Sleep Mode is enabled by writing a one to the SLEEP bit in the ADC Configuration Register (ACR). When a trigger occurs while the ADC Sleep Mode is enabled, the Analog-to-Digital Converter cell is automatically activated. As the analog cell requires a startup time, the logic waits during this time and then starts the conversion of the enabled channels. When conversions of all enabled channels are complete, the ADC is deactivated until the next trigger. 29.6.7 Startup Time The Analog-to-Digital Converter cell has a minimal startup time when the cell is activated. This startup time is given in the Electrical Characteristics chapter and must be written to the STARTUP field in the ADC Configuration Register (ACR) to get correct conversion results. The STARTUP field expects the startup time to be represented as the number of CLK_ADC cycles between 8 and 1024 and in steps of 8 that is needed to cover the ADC startup time as specified in the Electrical Characteristics chapter. The Analog-to-Digital Converter cell is activated at the first conversion after reset and remains active if ACR.SLEEP is zero. If ACR.SLEEP is one, the Analog-to-Digital Converter cell is automatically deactivated when idle and thus each conversion sequence will have a initial startup time delay. 29.6.8 Sample and Hold Time A minimal Sample and Hold Time is necessary for the ADCIFB to guarantee the best converted final value when switching between ADC channels. This time depends on the input impedance of the analog input, but also on the output impedance of the driver providing the signal to the analog input, as there is no input buffer amplifier. The Sample and Hold time has to be programmed through the SHTIM field in the ADC Configuration Register (ACR). This field can define a Sample and Hold time between 1 and 16 CLK_ADC cycles. 29.6.9 ADC Conversion ADC conversions are performed on all enabled channels when a trigger condition is detected. For details regarding trigger conditions see Section 29.8.1. The term channel is used to identify a specific analog input pin so it can be included or excluded in an Analog-to-Digital conversion sequence and to identify which AD pin was used to convert the current value in the Last Converted Data Register (LCDR). Channel number N corresponding to AD pin number N. 717 32142D–06/2013 ATUC64/128/256L3/4U Channels are enabled by writing a one to the corresponding bit in the Channel Enable Register (CHER), and disabled by writing a one to the corresponding bit in the Channel Disable Register (CHDR). Active channels are listed in the Channel Status Register (CHSR). When a conversion sequence is started, all enabled channels will be converted in one sequence and the result will be placed in the Last Converted Data Register (LCDR) with the channel number used to produce the result. It is important to read out the results while the conversion sequence is ongoing, as new values will automatically overwrite any old value and the old value will be lost if not previously read by the user. If the Analog-to-Digital Converter cell is inactive when starting a conversion sequence, the conversion logic will wait a configurable number of CLK_ADC cycles as defined in the startup time field in the ADC Configuration Register (ACR). After the cell is activated all enabled channels is converted one by one until no more enabled channels exist. The conversion sequence converts each enabled channel in order starting with the channel with the lowest channel number. If the ACR.SLEEP bit is one, the Analog-to-Digital Converter cell is deactivated after the conversion sequence has finished. For each channel converted, the ADCIFB waits a Sample and Hold number of CLK_ADC cycles as defined in the SHTIM field in ACR, and then instructs the Analog-to-Digital Converter cell to start converting the analog voltage. The ADC cell requires 10 CLK_ADC cycles to actually convert the value, so the total time to convert a channel is Sample and Hold + 10 CLK_ADC cycles. 29.6.10 Analog Compare Mode The ADCIFB can test if the converted values, as they become available, are below, above, or inside a specified range and generate interrupt requests based on this information. This is useful for applications where the user wants to monitor some external analog signal and only initiate actions if the value is above, below, or inside some specified range. The Analog Compare mode is enabled by writing a one to the Analog Compare Enable (ACE) bit in the Mode Register (MR). The values to compare must be written to the Low Value (LV) field and the High Value (HV) field in the Compare Value Register (CVR). The Analog Compare mode will, when enabled, check all enabled channels against the pre-programmed high and low values and set status bits. To generate an interrupt request if a converted value is below a limit, write the limit to the CVR.LV field and enable interrupt request on the Compare Lesser Than (CLT) bit by writing a one to the corresponding bit in the Interrupt Enable Register (IER). To generate an interrupt request if a converted value is above a limit, write the limit to the CVR.HV field and enable interrupt for Compare Greater Than (CGT) bit. To generate an interrupt request if a converted value is inside a range, write the low and high limit to the LV and HV fields and enable the Compare Else (CELSE) interrupt. To generate an interrupt request if a value is outside a range, write the LV and HV fields to the low and high limits of the range and enable CGT and CLT interrupts. Note that the values written to LV and HV must match the resolution selected in the ADC Configuration Register (ACR). 29.6.11 Interrupt Operation Interrupt requests are enabled by writing a one to the corresponding bit in the Interrupt Enable Register (IER) and disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). Enabled interrupts can be read from the Interrupt Mask Register (IMR). Active interrupt requests, but potentially masked, are visible in the Interrupt Status Register (ISR). To 718 32142D–06/2013 ATUC64/128/256L3/4U clear an active interrupt request, write a one to the corresponding bit in the Interrupt Clear Register (ICR). The source for the interrupt requests are the status bits in the Status Register (SR). The SR shows the ADCIFB status at the time the register is read. The Interrupt Status Register (ISR) shows the status since the last write to the Interrupt Clear Register. The combination of ISR and SR allows the user to react to status change conditions but also allows the user to read the current status at any time. 29.6.12 Peripheral Events The Peripheral Event System can be used together with the ADCIFB to allow any peripheral event generator to be used as a trigger source. To enable peripheral events to trigger a conversion sequence the user must write the Peripheral Event Trigger value (0x7) to the Trigger Mode (TRGMOD) field in the Trigger Register (TRGR). Refer to Table 29-4 on page 730. The user must also configure a peripheral event generator to emit peripheral events for the ADCIFB to trigger on. Refer to the Peripheral Event System chapter for details. 29.6.13 Sleep Mode Before entering sleep modes the user must make sure the ADCIFB is idle and that the Analogto-Digital Converter cell is inactive. To deactivate the Analog-to-Digital Converter cell the SLEEP bit in the ADC Configuration Register (ACR) must be written to one and the ADCIFB must be idle. To make sure the ADCIFB is idle, write a zero the Trigger Mode (TRGMOD) field in the Trigger Register (TRGR) and wait for the READY bit in the Status Register (SR) to be set. Note that by deactivating the Analog-to-Digital Converter cell, a startup time penalty as defined in the STARTUP field in the ADC Configuration Register (ACR) will apply on the next conversion. 29.6.14 Conversion Performances For performance and electrical characteristics of the ADCIFB, refer to the Electrical Characteristics chapter. 29.7 Resistive Touch Screen The ADCIFB embeds an integrated Resistive Touch Screen Sequencer that can be used to calculate contact coordinates on a resistive touch screen film. When instructed to start, the integrated Resistive Touch Screen Sequencer automatically applies a sequence of voltage patterns to the resistive touch screen films and the Analog-to-Digital Conversion cell is used to measure the effects. The resulting measurements can be used to calculate the horizontal and vertical contact coordinates. It is recommended to use a high resistance touch screen for optimal resolution. The resistive touch screen film is connected to the ADCIFB using the AD and ADP pins. See Section 29.7.3 for details. Resistive Touch Screen Mode is enabled by writing a one to the Touch Screen ADC Mode field in the Mode Register (MR.TSAMOD). In this mode, channels TSPO+0 though TSPO+3 are automatically enabled where TSPO refers to the Touch Screen Pin Offset field in the Mode Register (MR.TSPO). For each conversion sequence, all enabled channels before TSPO+0 and after TSPO+3 are converted as ordinary ADC channels, producing 1 conversion result each. When the sequencer enters the TSPO+0 channel the Resistive Touch Screen Sequencer will take over control and convert the next 4 channels as described in Section 29.7.4. 719 32142D–06/2013 ATUC64/128/256L3/4U 29.7.1 Resistive Touch Screen Principles A resistive touch screen is based on two resistive films, each one fitted with a pair of electrodes, placed at the top and bottom on one film, and on the right and left on the other. Between the two, there is a layer that acts as an insulator, but makes a connection when pressure is applied to the screen. This is illustrated in Figure 29-2 on page 719. Figure 29-2. Resistive Touch Screen Position Measurement 29.7.2 Position Measurement Method As shown in Figure 29-2 on page 719, to detect the position of a contact, voltage is first applied to XP (top) and Xm (bottom) leaving Yp and Ym tristated. Due to the linear resistance of the film, there is a voltage gradient from top to bottom on the first film. When a contact is performed on the screen, the voltage at the contact point propagates to the second film. If the input impedance on the YP (right) and Ym (left) electrodes are high enough, no current will flow, allowing the voltage at the contact point to be measured at Yp. The value measured represents the vertical position component of the contact point. For the horizontal direction, the same method is used, but by applying voltage from YP (right) to Ym (left) and measuring at XP. In an ideal world (linear, with no loss), the vertical position is equal to: VYP / VDD To compensate for some of the real world imperfections, VXP and VXm can be measured and used to improve accuracy at the cost of two more conversions per axes. The new expression for the vertical position then becomes: (VYP - VXM) / (VXP - VXM) XM XP YM YP XP XM YP VDD GND Volt Horizontal Position Detection YP YM XP VDD GND Volt Vertical Position Detection Pen Contact 720 32142D–06/2013 ATUC64/128/256L3/4U 29.7.3 Resistive Touch Screen Pin Connections The resistive touch screen film signals connects to the ADCIFB using the AD and ADP pins. The XP (top) and XM (bottom) film signals are connected to ADtspo+0 and ADtspo+1 pins, and the YP (right) and YM (left) signals are connected to ADtspo+2 and ADtspo+3 pins. The tspo index is configurable through the Touch Screen Pin Offset (TSPO) field in the Mode Register (MR) and allows the user to configure which AD pins to use for resistive touch screen applications. Writing a zero to the TSPO field instructs the ADCIFB to use AD0 through AD3, where AD0 is connected to XP, AD1 is connected to XM and so on. Writing a one to the TSPO field instructs the ADCIFB to use AD1 through AD4 for resistive touch screen sequencing, where AD1 is connected to XP and AD0 is free to be used as an ordinary ADC channel. When the Analog Pin Output Enable (APOE) bit in the Mode Register (MR) is zero, the AD pins are used to measure input voltage and drive the GND sequences, while the ADP pins are used to drive the VDD sequences. This arrangement allows the user to reduce the voltage seen at the AD input pins by inserting external resistors between ADP0 and XP and ADP1 and YP signals which are again directly connected to the AD pins. It is important that the voltages observed at the AD pins are not higher than the maximum allowed ADC input voltage. See Figure 29-3 on page 721 for details regarding how to connect the resistive touch screen films to the AD and ADP pins. By adding a resistor between ADP0 and XP, and ADP1 and YP, the maximum voltage observed at the AD pins can be controlled by the following voltage divider expressions: The Rfilmx parameter is the film resistance observed when measuring between XP and XM. The Rresistorx parameter is the resistor size inserted between ADP0 and XP. The definition of Rfilmy and Rresistory is the same but for ADP1, YP, and YM instead. Table 29-2. Resistive Touch Screen Pin Connections ADCIFB Pin TS Signal, APOE == 0 TS Signal, APOE == 1 ADP0 Xp through a resistor No Connect ADP1 Yp through a resistor No Connect ADtspo+0 Xp Xp ADtspo+1 Xm Xm ADtspo+2 Yp Yp ADtspo+3 Ym Ym V ADtspo + 0   Rfilmx Rfilmx Rresistorx + -------------------------------------------- V DP0 =    721 32142D–06/2013 ATUC64/128/256L3/4U The ADP pins are used by default, as the APOE bit is zero after reset. Writing a one to the APOE bit instructs the ADCIFB Resistive Touch Screen Sequencer to use the already connected ADtspo+0 and ADtspo+2 pins to drive VDD to XP and YP signals directly. In this mode the ADP pins can be used as general purpose I/O pins. Before writing a one to the APOE bit the user must make sure that the I/O voltage is compatible with the ADC input voltage. If the I/O voltage is higher than the maximum input voltage of the ADC, permanent damage may occur. Refer to the Electrical Characteristics chapter for details. Figure 29-3. Resistive Touch Screen Pin Connections V ADtspo + 2   Rfilmy Rfilmy Rresistory + -------------------------------------------- V DP1 =    ADtspo+1 XM XP YM YP ADtspo+0 DP1 DP0 ADtspo+3 ADtspo+2 Analog Pin Output Enable (MR.APOE) == 0 ADtspo+1 XM XP YM YP ADtspo+0 DP1 DP0 ADtspo+3 ADtspo+2 Analog Pin Output Enable (MR.APOE) == 1 NC NC 722 32142D–06/2013 ATUC64/128/256L3/4U 29.7.4 Resistive Touch Screen Sequencer The Resistive Touch Screen Sequencer is responsible for applying voltage to the resistive touch screen films as described in Section 29.7.2. This is done by controlling the output enable and the output value of the ADP and AD pins. This allows the Resistive Touch Screen Sequencer to add a voltage gradient on one film while keeping the other film floating so a touch can be measured. The Resistive Touch Screen Sequencer will when measuring the vertical position, apply VDD and GND to the pins connected to XP and XM. The YP and YM pins are put in tristate mode so the measurement of YP can proceed without interference. To compensate for ADC offset errors and non ideal pad drivers, the actual voltage of XP and XM is measured as well, so the real values for VDD and GND can be used in the contact point calculation to increase accuracy. See second formula in Section 29.7.2. When the vertical values are converted the same setup is applies for the second axes, by setting XP and XM in tristate mode and applying VDD and GND to YP and YM. Refer to Section 29.8.3 for details. 29.7.5 Pen Detect If no contact is applied to the resistive touch screen films, any resistive touch screen conversion result will be undefined as the film being measured is floating. This can be avoided by enabling Pen Detect and only trigger resistive touch screen conversions when the Pen Contact (PENCNT) status bit in the Status Register (SR) is one. Pen Detect is enabled by writing a one to the Pen Detect (PENDET) bit in the Mode Register (MR). When Pen Detect is enabled, the ADCIFB grounds the vertical panel by applying GND to XP and XM and polarizes the horizontal panel by enabling pull-up on the pin connected to YP. The YM pin will in this mode be tristated. Since there is no contact, no current is flowing and there is no related power consumption. As soon as a contact occurs, GND will propagate to YM by pulling down YP, allowing the contact to be registered by the ADCIFB. A programmable debouncing filter can be used to filter out false pen detects because of noise. The debouncing filter is programmable from one CLK_ADC period and up to 215 CLK_ADC periods. The debouncer length is set by writing to the PENDBC field in MR. 723 32142D–06/2013 ATUC64/128/256L3/4U Figure 29-4. Resistive Touch Screen Pen Detect The Resistive Touch Screen Pen Detect can be used to generate an ADCIFB interrupt request or it can be used to trig a conversion, so that a position can be measured as soon as a contact is detected. The Pen Detect Mode generates two types of status signals, reported in the Status Register (SR): • The bit PENCNT is set when current flows and remains set until current stops. • The bit NOCNT is set when no current flows and remains set until current flows. Before a current change is reflected in the SR, the new status must be stable for the duration of the debouncing time. Both status conditions can generate an interrupt request if the corresponding bit in the Interrupt Mask Register (IMR) is one. Refer to Section 29.6.11 on page 717. XP XM YM YP Tristate GND Pullup T o the ADC Debouncer Pen Interrupt PENDBC GND Resistive Touch Screen Sequencer 724 32142D–06/2013 ATUC64/128/256L3/4U 29.8 Operating Modes The ADCIFB features two operating modes, each defining a separate conversion sequence: • ADC Mode: At each trigger, all the enabled channels are converted. • Resistive Touch Screen Mode: At each trigger, all enabled channels plus the resistive touch screen channels are converted as described in Section 29.8.3. If channels except the dedicated resistive touch screen channels are enabled, they are converted normally before and after the resistive touch screen channels are converted. The operating mode is selected by the TSAMOD field in the Mode Register (MR). 29.8.1 Conversion Triggers A conversion sequence is started either by a software or by a hardware trigger. When a conversion sequence is started, all enabled channels will be converted and made available in the shared Last Converted Register (LCDR). The software trigger is asserted by writing a one to the START field in the Control Register (CR). The hardware trigger can be selected by the TRGMOD field in the Trigger Register (TRGR). Different hardware triggers exist: • External trigger, either rising or falling or any, detected on the external trigger pin TRIGGER • Pen detect trigger, depending the PENDET bit in the Mode Register (MR) • Continuous trigger, meaning the ADCIFB restarts the next sequence as soon as it finishes the current one • Periodic trigger, which is defined by the TRGR.TRGPER field • Peripheral event trigger, allowing the Peripheral Event System to synchronize conversion with some configured peripheral event source. Enabling a hardware trigger does not disable the software trigger functionality. Thus, if a hardware trigger is selected, the start of a conversion can still be initiated by the software trigger. 29.8.2 ADC Mode In the ADC Mode, the active channels are defined by the Channel Status Register (CHSR). A channel is enabled by writing a one to the corresponding bit in the Channel Enable Register (CHER), and disabled by writing a one to the corresponding bit in the Channel Disable Register (CHDR). The conversion results are stored in the Last Converted Data Register (LCDR) as they become available, overwriting old conversions. At each trigger, the following sequence is performed: 1. If ACR.SLEEP is one, wake up the ADC and wait for the startup time. 2. If Channel 0 is enabled, convert Channel 0 and store result in LCDR. 3. If Channel 1 is enabled, convert Channel 1 and store result in LCDR. 4. If Channel N is enabled, convert Channel N and store result in LCDR. 5. If ACR.SLEEP is one, place the ADC cell in a low-power state. If the Peripheral DMA Controller is enabled, all converted values are transferred continuously into the memory buffer. 29.8.3 Resistive Touch Screen Mode Writing a one to the TSAMOD field in the Mode Register (MR) enables Resistive Touch Screen Mode. In this mode the channels TSPO+0 to TSPO+3, corresponding to the resistive touch 725 32142D–06/2013 ATUC64/128/256L3/4U screen inputs, are automatically activated. In addition, if any other channels are enabled, they will be converted before and after the resistive touch screen conversion. At each trigger, the following sequence is performed: 1. If ACR.SLEEP is one, wake up the ADC cell and wait for the startup time. 2. Convert all enabled channels before TSPO and store the results in the LCDR. 3. Apply supply on the inputs XP and XM during the Sample and Hold Time. 4. Convert Channel XM and store the result in TMP. 5. Apply supply on the inputs XP and XM during the Sample and Hold Time. 6. Convert Channel XP, subtract TMP from the result and store the subtracted result in LCDR. 7. Apply supply on the inputs XP and XM during the Sample and Hold Time. 8. Convert Channel YP, subtract TMP from the result and store the subtracted result in LCDR. 9. Apply supply on the inputs YP and YM during the Sample and Hold Time. 10. Convert Channel YM and store the result in TMP. 11. Apply supply on the inputs YP and YM during the Sample and Hold Time. 12. Convert Channel YP, subtract TMP from the result and store the subtracted result in LCDR. 13. Apply supply on the inputs YP and YM during the Sample and Hold Time. 14. Convert Channel XP, subtract TMP from the result and store the subtracted result in LCDR. 15. Convert all enabled channels after TSPO + 3 and store results in the LCDR. 16. If ACR.SLEEP is one, place the ADC cell in a low-power state. The resulting buffer structure stored in memory is: 1. XP - XM 2. YP - XM 3. YP - YM 4. XP - YM. The vertical position can be easily calculated by dividing the data at offset 1(XP - XM) by the data at offset 2(YP - XM). The horizontal position can be easily calculated by dividing the data at offset 3(YP - YM) by the data at offset 4(XP - YM). 726 32142D–06/2013 ATUC64/128/256L3/4U 29.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 29-3. ADCIFB Register Memory Map Offset Register Name Access Reset 0x00 Control Register CR Write-only - 0x04 Mode Register MR Read/Write 0x00000000 0x08 ADC Configuration Register ACR Read/Write 0x00000000 0x0C Trigger Register TRGR Read/Write 0x00000000 0x10 Compare Value Register CVR Read/Write 0x00000000 0x14 Status Register SR Read-only 0x00000000 0x18 Interrupt Status Register ISR Read-only 0x00000000 0x1C Interrupt Clear Register ICR Write-only - 0x20 Interrupt Enable Register IER Write-only - 0x24 Interrupt Disable Register IDR Write-only - 0x28 Interrupt Mask Register IMR Read-only 0x00000000 0x2C Last Converted Data Register LCDR Read-only 0x00000000 0x30 Parameter Register PARAMETER Read-only -(1) 0x34 Version Register VERSION Read-only -(1) 0x40 Channel Enable Register CHER Write-only - 0x44 Channel Disable Register CHDR Write-only - 0x48 Channel Status Register CHSR Read-only 0x00000000 727 32142D–06/2013 ATUC64/128/256L3/4U 29.9.1 Control Register Register Name: CR Access Type: Write-only Offset: 0x00 Reset Value: 0x00000000 • DIS: ADCDIFB Disable Writing a zero to this bit has no effect. Writing a one to this bit disables the ADCIFB. Note: Disabling the ADCIFB effectively stops all clocks in the module so the user must make sure the ADCIFB is idle before disabling the ADCIFB. • EN: ADCIFB Enable Writing a zero to this bit has no effect. Writing a one to this bit enables the ADCIFB. Note: The ADCIFB must be enabled before use. • START: Start Conversion Writing a zero to this bit has no effect. Writing a one to this bit starts an Analog-to-Digital conversion. • SWRST: Software Reset Writing a zero to this bit has no effect. Writing a one to this bit resets the ADCIFB, simulating a hardware reset. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - DIS EN 76543210 - - - - - - START SWRST 728 32142D–06/2013 ATUC64/128/256L3/4U 29.9.2 Mode Register Name: MR Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • PENDBC: Pen Detect Debouncing Period Period = 2PENDBC*TCLK_ADC • TSPO: Touch Screen Pin Offset The Touch Screen Pin Offset field is used to indicate which AD pins are connected to the resistive touch screen film edges. Only an offset is specified and it is assumed that the resistive touch screen films are connected sequentially from the specified offset pin and up to and including offset + 3 (4 pins). • APOE: Analog Pin Output Enable 0: AD pins are not used to drive VDD in resistive touch screen sequence. 1: AD pins are used to drive VDD in resistive touch screen sequence. Note: If the selected I/O voltage configuration is incompatible with the Analog-to-Digital converter cell voltage specification, this bit must stay cleared to avoid damaging the ADC. In this case the ADP pins must be used to drive VDD instead, as described in Section 29.7.3. If the I/O and ADC voltages are compatible, the AD pins can be used directly by writing a one to this bit. In this case the ADP pins can be ignored. • ACE: Analog Compare Enable 0: The analog compare functionality is disabled. 1: The analog compare functionality is enabled. • PENDET: Pen Detect 0: The pen detect functionality is disabled. 1: The pen detect functionality is enabled. Note: Touch detection logic can only be enabled when the ADC sequencer is idle. For successful pen detection the user must make sure there is enough idle time between consecutive scans for the touch detection logic to settle. • TSAMOD: Touch Screen ADC Mode 0: Touch Screen Mode is disabled. 1: Touch Screen Mode is enabled. 31 30 29 28 27 26 25 24 PENDBC - - - - 23 22 21 20 19 18 17 16 TSPO 15 14 13 12 11 10 9 8 -------- 76543210 - APOE ACE PENDET - - - TSAMOD 729 32142D–06/2013 ATUC64/128/256L3/4U 29.9.3 ADC Configuration Register Name: ACR Access Type: Read/Write Offset: 0x08 Reset Value: 0x00000000 • SHTIM: Sample & Hold Time for ADC Channels • STARTUP: Startup Time • PRESCAL: Prescaler Rate Selection • RES: Resolution Selection 0: 8-bit resolution. 1: 10-bit resolution. 2: 11-bit resolution, interpolated. 3: 12-bit resolution, interpolated. • SLEEP: ADC Sleep Mode 0: ADC Sleep Mode is disabled. 1: ADC Sleep Mode is enabled. 31 30 29 28 27 26 25 24 - - - - SHTIM 23 22 21 20 19 18 17 16 - STARTUP 15 14 13 12 11 10 9 8 - - PRESCAL 76543210 - - RES - - - SLEEP TSAMPLE&HOLD   SHTIM + 2 TCLK_ADC =  TARTUP   STARTUP + 1  8 TCLK_AD =  TCLK_ADC =   PRESCAL + 1  2 TCLK_ADCIFB  730 32142D–06/2013 ATUC64/128/256L3/4U 29.9.4 Trigger Register Name: TRGR Access Type: Read/Write Offset: 0x0C Reset Value: 0x00000000 • TRGPER: Trigger Period Effective only if TRGMOD defines a Periodic Trigger. Defines the periodic trigger period, with the following equations: Trigger Period = TRGPER *TCLK_ADC • TRGMOD: Trigger Mode 31 30 29 28 27 26 25 24 TRGPER[15:8] 23 22 21 20 19 18 17 16 TRGPER[7:0] 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - TRGMOD Table 29-4. Trigger Modes TRGMOD Selected Trigger Mode 0 0 0 No trigger, only software trigger can start conversions 0 0 1 External Trigger Rising Edge 0 1 0 External Trigger Falling Edge 0 1 1 External Trigger Any Edge 100 Pen Detect Trigger (shall be selected only if PENDET is set and TSAMOD = Touch Screen mode) 1 0 1 Periodic Trigger (TRGPER shall be initiated appropriately) 1 1 0 Continuous Mode 1 1 1 Peripheral Event Trigger 731 32142D–06/2013 ATUC64/128/256L3/4U 29.9.5 Compare Value Register Name: CVR Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • HV: High Value Defines the high value used when comparing analog input. • LV: Low Value Defines the low value used when comparing analog input. 31 30 29 28 27 26 25 24 - - - - HV[11:8] 23 22 21 20 19 18 17 16 HV[7:0] 15 14 13 12 11 10 9 8 - - - - LV[11:8] 76543210 LV[7:0] 732 32142D–06/2013 ATUC64/128/256L3/4U 29.9.6 Status Register Name: SR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 • EN: Enable Status 0: The ADCIFB is disabled. 1: The ADCIFB is enabled. This bit is cleared when CR.DIS is written to one. This bit is set when CR.EN is written to one. • CELSE: Compare Else Status This bit is cleared when either CLT or CGT are detected or when analog compare is disabled. This bit is set when no CLT or CGT are detected on the last converted data and analog compare is enabled. • CGT: Compare Greater Than Status This bit is cleared when no compare greater than CVR.HV is detected on the last converted data or when analog compare is disabled. This bit is set when compare greater than CVR.HV is detected on the last converted data and analog compare is enabled. • CLT: Compare Lesser Than Status This bit is cleared when no compare lesser than CVR.LV is detected on the last converted data or when analog compare is disabled. This bit is set when compare lesser than CVR.LV is detected on the last converted data and analog compare is enabled. • BUSY: Busy Status This bit is cleared when the ADCIFB is ready to perform a conversion sequence. This bit is set when the ADCIFB is busy performing a convention sequence. • READY: Ready Status This bit is cleared when the ADCIFB is busy performing a conversion sequence This bit is set when the ADCIFB is ready to perform a conversion sequence. • NOCNT: No Contact Status This bit is cleared when no contact loss is detected or pen detect is disabled This bit is set when contact loss is detected and pen detect is enabled. • PENCNT: Pen Contact Status This bit is cleared when no contact is detected or pen detect is disabled. 31 30 29 28 27 26 25 24 - - - - - - - EN 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 733 32142D–06/2013 ATUC64/128/256L3/4U This bit is set when pen contact is detected and pen detect is enabled. • OVRE: Overrun Error Status This bit is cleared when no Overrun Error has occurred since the start of a conversion sequence. This bit is set when one or more Overrun Error has occurred since the start of a conversion sequence. • DRDY: Data Ready Status 0: No data has been converted since the last reset. 1: One or more conversions have completed since the last reset and data is available in LCDR. This bit is cleared when CR.SWRST is written to one. This bit is set when one or more conversions have completed and data is available in LCDR. 734 32142D–06/2013 ATUC64/128/256L3/4U 29.9.7 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • CELSE: Compare Else Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • CGT: Compare Greater Than Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • CLT: Compare Lesser Than Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • BUSY: Busy Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • READY: Ready Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • NOCNT: No Contact Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • PENCNT: Pen Contact Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • OVRE: Overrun Error Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding bit in SR has a zero-to-one transition. • DRDY: Data Ready Status This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when a conversion has completed and new data is available in LCDR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 735 32142D–06/2013 ATUC64/128/256L3/4U 29.9.8 Interrupt Clear Register Name: ICR Access Type: Write-only Offset: 0x1C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 736 32142D–06/2013 ATUC64/128/256L3/4U 29.9.9 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 737 32142D–06/2013 ATUC64/128/256L3/4U 29.9.10 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x24 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 738 32142D–06/2013 ATUC64/128/256L3/4U 29.9.11 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x28 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared by writing a one to the corresponding bit in Interrupt Disable Register (IDR). A bit in this register is set by writing a one to the corresponding bit in Interrupt Enable Register (IER). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - CELSE CGT CLT - - BUSY READY 76543210 - - NOCNT PENCNT - - OVRE DRDY 739 32142D–06/2013 ATUC64/128/256L3/4U 29.9.12 Last Converted Data Register Name: LCDR Access Type: Read-only Offset: 0x2C Reset Value: 0x00000000 • LCCH: Last Converted Channel This field indicates what channel was last converted, i.e. what channel the LDATA represents. • LDATA: Last Data Converted The analog-to-digital conversion data is placed in this register at the end of a conversion on any analog channel and remains until a new conversion on any analog channel is completed. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 LCCH 15 14 13 12 11 10 9 8 - - - - LDATA[11:8] 76543210 LDATA[7:0] 740 32142D–06/2013 ATUC64/128/256L3/4U 29.9.13 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x30 Reset Value: 0x00000000 • CHn: Channel n Implemented 0: The corresponding channel is not implemented. 1: The corresponding channel is implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 741 32142D–06/2013 ATUC64/128/256L3/4U 29.9.14 Version Register Name: VERSION Access Type: Read-only Offset: 0x34 Reset Value: 0x00000000 • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the Module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 742 32142D–06/2013 ATUC64/128/256L3/4U 29.9.15 Channel Enable Register Name: CHER Access Type: Write-only Offset: 0x40 Reset Value: 0x00000000 • CHn: Channel n Enable Writing a zero to a bit in this register has no effect Writing a one to a bit in this register enables the corresponding channel The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding which channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 743 32142D–06/2013 ATUC64/128/256L3/4U 29.9.16 Channel Disable Register Name: CHDR Access Type: Write-only Offset: 0x44 Reset Value: 0x00000000 • CHn: Channel N Disable Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register disables the corresponding channel. Warning: If the corresponding channel is disabled during a conversion, or if it is disabled and then re-enabled during a conversion, its associated data and its corresponding DRDY and OVRE bits in SR are unpredictable. The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding how many channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 744 32142D–06/2013 ATUC64/128/256L3/4U 29.9.17 Channel Status Register Name: CHSR Access Type: Read-only Offset: 0x48 Reset Value: 0x00000000 • CHn: Channel N Status 0: The corresponding channel is disabled. 1: The corresponding channel is enabled. A bit in this register is cleared by writing a one to the corresponding bit in Channel Disable Register (CHDR). A bit in this register is set by writing a one to the corresponding bit in Channel Enable Register (CHER). The number of available channels is device dependent. Please refer to the Module Configuration section at the end of this chapter for information regarding how many channels are implemented. 31 30 29 28 27 26 25 24 CH31 CH30 CH29 CH28 CH27 CH26 CH25 CH24 23 22 21 20 19 18 17 16 CH23 CH22 CH21 CH20 CH19 CH18 CH17 CH16 15 14 13 12 11 10 9 8 CH15 CH14 CH13 CH12 CH11 CH10 CH9 CH8 76543210 CH7 CH6 CH5 CH4 CH3 CH2 CH1 CH0 745 32142D–06/2013 ATUC64/128/256L3/4U 29.10 Module Configuration The specific configuration for each ADCIFB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Note: 1. AD3 does not exist Table 29-5. Module Configuration Feature ADCIFB Number of ADC channels 9 (8 + 1 internal temperature sensor channel) Table 29-6. ADCIFB Clocks Clock Name Description CLK_ADCIFB Clock for the ADCIFB bus interface Table 29-7. Register Reset Values Register Reset Value VERSION 0x00000110 PARAMETER 0x000003FF Table 29-8. ADC Input Channels(1) Channel Input CH0 AD0 CH1 AD1 CH2 AD2 CH4 AD4 CH5 AD5 CH6 AD6 CH7 AD7 CH8 AD8 CH9 Temperature sensor 746 32142D–06/2013 ATUC64/128/256L3/4U 30. Analog Comparator Interface (ACIFB) Rev: 2.0.2.2 30.1 Features • Controls an array of Analog Comparators • Low power option – Single shot mode support • Selectable settings for filter option – Filter length and hysteresis • Window Mode – Detect inside/outside window – Detect above/below window • Interrupt – On comparator result rising edge, falling edge, toggle – Inside window, outside window, toggle – When startup time has passed • Can generate events to the peripheral event system 30.2 Overview The Analog Comparator Interface (ACIFB) is able to control a number of Analog Comparators (AC) with identical behavior. An Analog Comparator compares two voltages and gives a compare output depending on this comparison. The ACIFB can be configured in normal mode using each comparator independently or in window mode using defined comparator pairs to observe a window. The number of channels implemented is device specific. Refer to the Module Configuration section at the end of this chapter for details. 747 32142D–06/2013 ATUC64/128/256L3/4U 30.3 Block Diagram Figure 30-1. ACIFB Block Diagram 30.4 I/O Lines Description There are two groups of analog comparators, A and B, as shown in Table 30-1. In normal mode, this grouping does not have any meaning. In window mode, two analog comparators, one from group A and the corresponding comparator from group B, are paired. ……………... TRIGGER EVENTS IRQ GCLK Peripheral Bus ACIFB Analog Comparators PERIPHERAL EVENT GENERATION - + AC INN INP CONF0.INSELN - + AC INN INP CONFn.INSELN FILTER FILTER INTERRUPT GENERATION CLK_ACIFB CTRL.ACTEST TR.ACTESTn TR.ACTEST0 ACOUT0 ACOUTn ACP0 ACN0 ACREFN ACPn ACNn Table 30-1. Analog Comparator Groups for Window Mode Group A Group B Pair Number AC0 AC1 0 AC2 AC3 1 AC4 AC5 2 AC6 AC7 3 Table 30-2. I/O Line Description Pin Name Pin Description Type ACAPn Positive reference pin for Analog Comparator A n Analog ACANn Negative reference pin for Analog Comparator A n Analog 748 32142D–06/2013 ATUC64/128/256L3/4U The signal names corresponds to the groups A and B of analog comparators. For normal mode, the mapping from input signal names in the block diagram to the signal names is given in Table 30-3. 30.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 30.5.1 I/O Lines The ACIFB pins are multiplexed with other peripherals. The user must first program the I/O Controller to give control of the pins to the ACIFB. 30.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the ACIFB, the ACIFB will stop functioning and resume operation after the system wakes up from sleep mode. 30.5.3 Clocks The clock for the ACIFB bus interface (CLK_ACIFB) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the ACIFB before disabling the clock, to avoid freezing the ACIFB in an undefined state. The ACIFB uses a GCLK as clock source for the Analog Comparators. The user must set up this GCLK at the right frequency. The CLK_ACIFB clock of the interface must be at least 4x the GCLK frequency used in the comparators. The GCLK is used both for measuring the startup time of a comparator, and to give a frequency for the comparisons done in Continuous Measurement Mode, see Section 30.6. Refer to the Electrical Characteristics chapter for GCLK frequency limitations. ACBPn Positive reference pin for Analog Comparator B n Analog ACBNn Negative reference pin for Analog Comparator B n Analog ACREFN Reference Voltage for all comparators selectable for INN Analog Table 30-3. Signal Name Mapping Pin Name Channel Number Normal Mode ACAP0/ACAN0 0 ACP0/ACN0 ACBP0/ACBN0 1 ACP1/ACN1 ACAP1/ACAN1 2 ACP2/ACN2 ACBP1/ACBN1 3 ACP3/ACN3 ACAP2/ACAN2 4 ACP4/ACN4 ACBP2/ACBN2 5 ACP5/ACN5 ACAP3/ACAN3 6 ACP6/ACN6 ACBP3/ACBN3 7 ACP7/ACN7 Table 30-2. I/O Line Description Pin Name Pin Description Type 749 32142D–06/2013 ATUC64/128/256L3/4U 30.5.4 Interrupts The ACIFB interrupt request line is connected to the interrupt controller. Using the ACIFB interrupt requires the interrupt controller to be programmed first. 30.5.5 Peripheral Events The ACIFB peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 30.5.6 Debug Operation When an external debugger forces the CPU into debug mode, the ACIFB continues normal operation. If the ACIFB is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 30.6 Functional Description The ACIFB is enabled by writing a one to the Control Register Enable bit (CTRL.EN). Additionally, the comparators must be individually enabled by programming the MODE field in the AC Configuration Register (CONFn.MODE). The results from the individual comparators can either be used directly (normal mode), or the results from two comparators can be grouped to generate a comparison window (window mode). All comparators need not be in the same mode, some comparators may be in normal mode, while others are in window mode. There are restrictions on which AC channels that can be grouped together in a window pair, see Section 30.6.5. 30.6.1 Analog Comparator Operation Each AC channel can be in one of four different modes, determined by CONFn.MODE: • Off • Continuous Measurement Mode (CM) • User Triggered Single Measurement Mode (UT) • Event Triggered Single Measurement Mode (ET) After being enabled, a startup time defined in CTRL.SUT is required before the result of the comparison is ready. The GCLK is used for measuring the startup time of a comparator, During the startup time the AC output is not available. When the ACn Ready bit in the Status Register (SR.ACRDYn) is one, the output of ACn is ready. In window mode the result is available when both the comparator outputs are ready (SR.ACRDYn=1 and SR.ACRDYn+1=1). 30.6.1.1 Continuous Measurement Mode In CM, the Analog Comparator is continuously enabled and performing comparisons. This ensures that the result of the latest comparison is always available in the ACn Current Comparison Status bit in the Status Register (SR.ACCSn). Comparisons are done on every positive edge of GCLK. CM is enabled by writing CONFn.MODE to 1. After the startup time has passed, a comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. New comparisons are performed continuously until the CONFn.MODE field is written to 0. 750 32142D–06/2013 ATUC64/128/256L3/4U 30.6.1.2 User Triggered Single Measurement Mode In the UT mode, the user starts a single comparison by writing a one to the User Start Single Comparison bit (CTRL.USTART). This mode is enabled by writing CONFn.MODE to 2. After the startup time has passed, a single comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. No new comparisons will be performed. CTRL.USTART is cleared automatically by hardware when the single comparison has been done. 30.6.1.3 Event Triggered Single Measurement Mode This mode is enabled by writing CONFn.MODE to 3 and Peripheral Event Trigger Enable (CTRL.EVENTEN) to one. The ET mode is similar to the UT mode, the difference is that a peripheral event from another hardware module causes the hardware to automatically set the Peripheral Event Start Single Comparison bit (CTRL.ESTART). After the startup time has passed, a single comparison is done and SR is updated. Appropriate peripheral events and interrupts are also generated. No new comparisons will be performed. CTRL.ESTART is cleared automatically by hardware when the single comparison has been done. 30.6.1.4 Selecting Comparator Inputs Each Analog Comparator has one positive (INP) and one negative (INN) input. The positive input is fed from an external input pin (ACPn). The negative input can either be fed from an external input pin (ACNn) or from a reference voltage common to all ACs (ACREFN). The user selects the input source as follows: • In normal mode with the Negative Input Select and Positive Input Select fields (CONFn.INSELN and CONFn.INSELP). • In window mode with CONFn.INSELN, CONFn.INSELP and CONFn+1.INSELN, CONFn+1,INSELP. The user must configure CONFn.INSELN and CONFn+1.INSELP to the same source. 30.6.2 Interrupt Generation The interrupt request will be generated if the corresponding bit in the Interrupt Mask Register (IMR) is set. Bits in IMR are set by writing a one to the corresponding bit in the Interrupt Enable Register (IER), and cleared by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt request remains active until the corresponding bit in ISR is cleared by writing a one to the corresponding bit in the Interrupt Status Clear Register (ICR). 30.6.3 Peripheral Event Generation The ACIFB can be set up so that certain comparison results notify other parts of the device via the Peripheral Event system. Refer to Section 30.6.4.3 and Section 30.6.5.3 for information on which comparison results can generate events, and how to configure the ACIFB to achieve this. Zero or one event will be generated per comparison. 30.6.4 Normal Mode In normal mode all Analog Comparators are operating independently. 30.6.4.1 Normal Mode Output Each Analog Comparator generates one output ACOUT according to the input voltages on INP (AC positive input) and INN (AC negative input): 751 32142D–06/2013 ATUC64/128/256L3/4U • ACOUT = 1 if VINP > VINN • ACOUT = 0 if VINP < VINN • ACOUT = 0 if the AC output is not available (SR.ACRDY = 0) The output can optionally be filtered, as described in Section 30.6.6. 30.6.4.2 Normal Mode Interrupt The AC channels can generate interrupts. The Interrupt Settings field in the Configuration Register (CONFn.IS) can be configured to select when the AC will generate an interrupt: • When VINP > VINN • When VINP < VINN • On toggle of the AC output (ACOUT) • When comparison has been done 30.6.4.3 Normal Mode Peripheral Events The ACIFB can generate peripheral events according to the configuration of CONFn.EVENN and CONFn.EVENP. • When VINP > VINN or • When VINP < VINN or • On toggle of the AC output (ACOUT) 30.6.5 Window Mode In window mode, two ACs (an even and the following odd build up a pair) are grouped. The negative input of ACn (even) and the positive input of ACn+1 (odd) has to be connected together externally to the device and are controlled by the Input Select fields in the AC Configuration Registers (CONFn.INSELN and CONFn+1.INSELP). The positive input of ACn (even) and the negative input of ACn+1 (odd) can still be configured independently by CONFn.INSELP and CONFn+1.INSELN, respectively. 752 32142D–06/2013 ATUC64/128/256L3/4U Figure 30-2. Analog Comparator Interface in Window Mode 30.6.5.1 Window Mode Output When operating in window mode, each channel generates the same ACOUT outputs as in normal mode, see Section 30.6.4.1. Additionally, the ACIFB generates a window mode signal (acwout) according to the common input voltage to be compared: • ACWOUT = 1 if the common input voltage is inside the window, VACN(N+1) < Vcommon < VACP(N) • ACWOUT = 0 if the common input voltage is outside the window, Vcommon < VACN(N+1) or Vcommon > VACP(N) • ACWOUT = 0 if the window mode output is not available (SR.ACRDYn=0 or SR.ACRDYn+1=0) 30.6.5.2 Window Mode Interrupts When operating in window mode, each channel can generate the same interrupts as in normal mode, see Section 30.6.4.2. Additionally, when channels operate in window mode, programming Window Mode Interrupt Settings in the Window Mode Configuration Register (CONFWn.WIS) can cause interrupts to be generated when: • As soon as the common input voltage is inside the window. • As soon as the common input voltage is outside the window. • On toggle of the window compare output (ACWOUT). • When the comparison in both channels in the window pair is ready. Comparator pair 0 - + AC0 Interrupt Generator Window Module ACOUT0 Peripheral Event Generator Window window event - + AC1 Filter Filter SR.ACCS0 SR.WFCS0 ACAP0 ACAN0 ACBP0 COMMON ACWOUT ACBN0 IRQ ACOUT1 753 32142D–06/2013 ATUC64/128/256L3/4U 30.6.5.3 Window Mode Peripheral Events When operating in window mode, each channel can generate the same peripheral events as in normal mode, see Section 30.6.4.3. Additionally, when channels operate in window mode, programming Window Mode Event Selection Source (CONFWn.WEVSRC) can cause peripheral events to be generated when: • As soon as the common input voltage is inside the window. • As soon as the common input voltage is outside the window. • On toggle of the window compare output (ACWOUT) • Whenever a comparison is ready and the common input voltage is inside the window. • Whenever a comparison is ready and the common input voltage is outside the window. • When the comparison in both channels in the window pair is ready. 30.6.6 Filtering The output of the comparator can be filtered to reduce noise. The filter length is determined by the Filter Length field in the CONFn register (CONFn.FLEN). The filter samples the Analog Comparator output at the GCLK frequency for 2CONFn.FLEN samples. A separate counter (CNT) counts the number of cycles the AC output was one. This filter is deactivated if CONFn.FLEN equals 0. If the filter is enabled, the Hysteresis Value field HYS in the CONFn register (CONFn.HYS) can be used to define a hysteresis value. The hysteresis value should be chosen so that: The filter function is defined by: The filtering algorithm is explained in Figure 30-3. 2FLEN measurements are sampled. If the number of measurements that are zero is less than (2FLEN/2 - HYS), the filtered result is zero. If the number of measurements that are one is more than (2FLEN/2 + HYS), the filtered result is one. Otherwise, the result is unchanged. 2FLEN 2 ----------------  HYS CNT 2FLEN 2 ---------------- + HYS       comp = 1 2FLEN 2 ---------------- + HYS     CNT 2FLEN 2 ----------------–HYS        comp unchanged CNT 2FLEN 2 ----------------–HYS       comp = 0 754 32142D–06/2013 ATUC64/128/256L3/4U Figure 30-3. The Filtering Algorithm 30.7 Peripheral Event Triggers Peripheral events from other modules can trigger comparisons in the ACIFB. All channels that are set up in Event Triggered Single Measurement Mode will be started simultaneously when a peripheral event is received. Channels that are operating in Continuous Measurement Mode or User Triggered Single Measurement Mode will be unaffected by the received event. The software can still operate these channels independently of channels in Event Triggered Single Measurement Mode. A peripheral event will trigger one or more comparisons, in normal or window mode. 30.8 AC Test mode By writing the Analog Comparator Test Mode (CR.ACTEST) bit to one, the outputs from the ACs are overridden by the value in the Test Register (TR), see Figure 30-1. This is useful for software development. 2 FLEN 2 FLEN 2 HYS HYS ”Result=0" ”Result=1" Result = UNCHANGED 0 755 32142D–06/2013 ATUC64/128/256L3/4U 30.9 User Interface Note: 1. The reset values for these registers are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 30-4. ACIFB Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Status Register SR Read-only 0x00000000 0x10 Interrupt Enable Register IER Write-only 0x00000000 0x14 Interrupt Disable Register IDR Write-only 0x00000000 0x18 Interrupt Mask Register IMR Read-only 0x00000000 0x1C Interrupt Status Register ISR Read-only 0x00000000 0x20 Interrupt Status Clear Register ICR Write-only 0x00000000 0x24 Test Register TR Read/Write 0x00000000 0x30 Parameter Register PARAMETER Read-only -(1) 0x34 Version Register VERSION Read-only -(1) 0x80 Window0 Configuration Register CONFW0 Read/Write 0x00000000 0x84 Window1 Configuration Register CONFW1 Read/Write 0x00000000 0x88 Window2 Configuration Register CONFW2 Read/Write 0x00000000 0x8C Window3 Configuration Register CONFW3 Read/Write 0x00000000 0xD0 AC0 Configuration Register CONF0 Read/Write 0x00000000 0xD4 AC1 Configuration Register CONF1 Read/Write 0x00000000 0xD8 AC2 Configuration Register CONF2 Read/Write 0x00000000 0xDC AC3 Configuration Register CONF3 Read/Write 0x00000000 0xE0 AC4 Configuration Register CONF4 Read/Write 0x00000000 0xE4 AC5 Configuration Register CONF5 Read/Write 0x00000000 0xE8 AC6 Configuration Register CONF6 Read/Write 0x00000000 0xEC AC7 Configuration Register CONF7 Read/Write 0x00000000 756 32142D–06/2013 ATUC64/128/256L3/4U 30.9.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SUT: Startup Time Analog Comparator startup time = . Each time an AC is enabled, the AC comparison will be enabled after the startup time of the AC. • ACTEST: Analog Comparator Test Mode 0: The Analog Comparator outputs feeds the channel logic in ACIFB. 1: The Analog Comparator outputs are bypassed with the AC Test Register. • ESTART: Peripheral Event Start Single Comparison Writing a zero to this bit has no effect. Writing a one to this bit starts a comparison and can be used for test purposes. This bit is cleared when comparison is done. This bit is set when an enabled peripheral event is received. • USTART: User Start Single Comparison Writing a zero to this bit has no effect. Writing a one to this bit starts a Single Measurement Mode comparison. This bit is cleared when comparison is done. • EVENTEN: Peripheral Event Trigger Enable 0: A peripheral event will not trigger a comparison. 1: Enable comparison triggered by a peripheral event. • EN: ACIFB Enable 0: The ACIFB is disabled. 1: The ACIFB is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - SUT[9:8] 15 14 13 12 11 10 9 8 SUT[7:0] 76543210 ACTEST - ESTART USTART - - -EVENTEN EN SUT FGCLK ---------------- 757 32142D–06/2013 ATUC64/128/256L3/4U 30.9.2 Status Register Name: SR Access Type: Read-only Offset: 0x04 Reset Value: 0x00000000 • WFCSn: Window Mode Current Status This bit is cleared when the common input voltage is outside the window. This bit is set when the common input voltage is inside the window. • ACRDYn: ACn Ready This bit is cleared when the AC output (ACOUT) is not ready. This bit is set when the AC output (ACOUT) is ready, AC is enabled and its startup time is over. • ACCSn: ACn Current Comparison Status This bit is cleared when VINP is currently lower than VINN This bit is set when VINP is currently greater than VINN. 31 30 29 28 27 26 25 24 - - - - WFCS3 WFCS2 WFCS1 WFCS0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 ACRDY7 ACCS7 ACRDY6 ACCS6 ACRDY5 ACCS5 ACRDY4 ACCS4 76543210 ACRDY3 ACCS3 ACRDY2 ACCS2 ACRDY1 ACCS1 ACRDY0 ACCS0 758 32142D–06/2013 ATUC64/128/256L3/4U 30.9.3 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 759 32142D–06/2013 ATUC64/128/256L3/4U 30.9.4 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x14 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 760 32142D–06/2013 ATUC64/128/256L3/4U 30.9.5 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • WFINTn: Window Mode Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. • SUTINTn: ACn Startup Time Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. • ACINTn: ACn Interrupt Mask 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. This bit is cleared when the corresponding bit in IDR is written to one. This bit is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 761 32142D–06/2013 ATUC64/128/256L3/4U 30.9.6 Interrupt Status Register Name: ISR Access Type: Read-only Offset: 0x1C Reset Value: 0x00000000 • WFINTn: Window Mode Interrupt Status 0: No Window Mode Interrupt is pending. 1: Window Mode Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding channel pair operating in window mode generated an interrupt. • SUTINTn: ACn Startup Time Interrupt Status 0: No Startup Time Interrupt is pending. 1: Startup Time Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the startup time of the corresponding AC has passed. • ACINTn: ACn Interrupt Status 0: No Normal Mode Interrupt is pending. 1: Normal Mode Interrupt is pending. This bit is cleared when the corresponding bit in ICR is written to one. This bit is set when the corresponding channel generated an interrupt. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 762 32142D–06/2013 ATUC64/128/256L3/4U 30.9.7 Interrupt Status Clear Register Name: ICR Access Type: Write-only Offset: 0x20 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in ISR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 - - - - WFINT3 WFINT2 WFINT1 WFINT0 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 SUTINT7 ACINT7 SUTINT6 ACINT6 SUTINT5 ACINT5 SUTINT4 ACINT4 76543210 SUTINT3 ACINT3 SUTINT2 ACINT2 SUTINT1 ACINT1 SUTINT0 ACINT0 763 32142D–06/2013 ATUC64/128/256L3/4U 30.9.8 Test Register Name: TR Access Type: Read/Write Offset: 0x24 Reset Value: 0x00000000 • ACTESTn: AC Output Override Value If CTRL.ACTEST is set, the ACn output is overridden with the value of ACTESTn. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 ACTEST7 ACTEST6 ACTEST5 ACTEST4 ACTEST3 ACTEST2 ACTEST1 ACTEST0 764 32142D–06/2013 ATUC64/128/256L3/4U 30.9.9 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x30 Reset Value: - • WIMPLn: Window Pair n Implemented 0: Window Pair not implemented. 1: Window Pair implemented. • ACIMPLn: Analog Comparator n Implemented 0: Analog Comparator not implemented. 1: Analog Comparator implemented. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - WIMPL3 WIMPL2 WIMPL1 WIMPL0 15 14 13 12 11 10 9 8 -------- 76543210 ACIMPL7 ACIMPL6 ACIMPL5 ACIMPL4 ACIMPL3 ACIMPL2 ACIMPL1 ACIMPL0 765 32142D–06/2013 ATUC64/128/256L3/4U 30.9.10 Version Register Name: VERSION Access Type: Read-only Offset: 0x34 Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 766 32142D–06/2013 ATUC64/128/256L3/4U 30.9.11 Window Configuration Register Name: CONFWn Access Type: Read/Write Offset: 0x80,0x84,0x88,0x8C Reset Value: 0x00000000 • WFEN: Window Mode Enable 0: The window mode is disabled. 1: The window mode is enabled. • WEVEN: Window Event Enable 0: Event from awout is disabled. 1: Event from awout is enabled. • WEVSRC: Event Source Selection for Window Mode 000: Event on acwout rising edge. 001: Event on acwout falling edge. 010: Event on awout rising or falling edge. 011: Inside window. 100: Outside window. 101: Measure done. 110-111: Reserved. • WIS: Window Mode Interrupt Settings 00: Window interrupt as soon as the input voltage is inside the window. 01: Window interrupt as soon as the input voltage is outside the window. 10: Window interrupt on toggle of window compare output. 11: Window interrupt when evaluation of input voltage is done. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - - - - WFEN 15 14 13 12 11 10 9 8 - - - - WEVEN WEVSRC 7654321 0 - - - - - - WIS 767 32142D–06/2013 ATUC64/128/256L3/4U 30.9.12 AC Configuration Register Name: CONFn Access Type: Read/Write Offset: 0xD0,0xD4,0xD8,0xDC,0xE0,0xE4,0xE8,0xEC Reset Value: 0x00000000 • FLEN: Filter Length 000: Filter off. n: Number of samples to be averaged =2n . • HYS: Hysteresis Value 0000: No hysteresis. 1111: Max hysteresis. • EVENN: Event Enable Negative 0: Do not output event when ACOUT is zero. 1: Output event when ACOUT is zero. • EVENP: Event Enable Positive 0: Do not output event when ACOUT is one. 1: Output event when ACOUT is one. • INSELP: Positive Input Select 00: ACPn pin selected. 01: Reserved. 10: Reserved. 11: Reserved. • INSELN: Negative Input Select 00: ACNn pin selected. 01: ACREFN pin selected. 10: Reserved. 11: Reserved. • MODE: Mode 00: Off. 01: Continuous Measurement Mode. 10: User Triggered Single Measurement Mode. 11: Event Triggered Single Measurement Mode. 31 30 29 28 27 26 25 24 - FLEN HYS 23 22 21 20 19 18 17 16 - - - - - - EVENP EVENN 15 14 13 12 11 10 9 8 - - - - INSELP INSELN 7654321 0 - - MODE - - IS 768 32142D–06/2013 ATUC64/128/256L3/4U • IS: Interrupt Settings 00: Comparator interrupt when as VINP > VINN. 01: Comparator interrupt when as VINP < VINN. 10: Comparator interrupt on toggle of Analog Comparator output. 11: Comparator interrupt when comparison of VINP and VINN is done. 769 32142D–06/2013 ATUC64/128/256L3/4U 30.10 Module Configuration The specific configuration for each ACIFB instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Refer to the Power Manager chapter for details. Table 30-5. ACIFB Configuration Feature ACIFB Number of channels 8 Table 30-6. ACIFB Clocks Clock Name Description CLK_ACIFB Clock for the ACIFB bus interface GCLK The generic clock used for the ACIFB is GCLK4 Table 30-7. Register Reset Values Register Reset Value VERSION 0x00000202 PARAMETER 0x000F00FF 770 32142D–06/2013 ATUC64/128/256L3/4U 31. Capacitive Touch Module (CAT) Rev: 4.0.0.0 31.1 Features • QTouch® method allows N touch sensors to be implemented using 2N physical pins • QMatrix method allows X by Y matrix of sensors to be implemented using (X+2Y) physical pins • One autonomous QTouch sensor operates without DMA or CPU intervention • All QTouch sensors can operate in DMA-driven mode without CPU intervention • External synchronization to reduce 50 or 60 Hz mains interference • Spread spectrum sensor drive capability 31.2 Overview The Capacitive Touch Module (CAT) senses touch on external capacitive touch sensors. Capacitive touch sensors use no external mechanical components, and therefore demand less maintenance in the user application. The module implements the QTouch method of capturing signals from capacitive touch sensors. The QTouch method is generally suitable for small numbers of sensors since it requires 2 physical pins per sensor. The module also implements the QMatrix method, which is more appropriate for large numbers of sensors since it allows an X by Y matrix of sensors to be implemented using only (X+2Y) physical pins. The module allows methods to function together, so N touch sensors and an X by Y matrix of sensors can be implemented using (2N+X+2Y) physical pins. In addition, the module allows sensors using the QTouch method to be divided into two groups. Each QTouch group can be configured with different properties. This eases the implementation of multiple kinds of controls such as push buttons, wheels, and sliders. All of the QTouch sensors can operate in a DMA-driven mode, known as DMATouch, that allows detection of touch without CPU intervention. The module also implements one autonomous QTouch sensor that is capable of detecting touch without DMA or CPU intervention. This allows proximity or activation detection in low-power sleep modes. 771 32142D–06/2013 ATUC64/128/256L3/4U 31.3 Block Diagram Figure 31-1. CAT Block Diagram 31.4 I/O Lines Description Interface Registers Peripheral Bus Finite State Machine Capacitor Charge and Discharge Sequence Generator Counters CSAn SMP I/O Controller Pins Discharge Current Sources DIS Yn Analog Comparators Peripheral Event System CLK_CAT Analog Comparator Interface SYNC Capacitive Touch Module (CAT) CSBn GCLK_CAT VDIVEN NOTE: Italicized signals and blocks are used only for QMatrix operation Table 31-1. I/O Lines Description Name Description Type CSAn Capacitive sense A line n I/O CSBn Capacitive sense B line n I/O DIS Discharge current control (only used for QMatrix) Analog 772 32142D–06/2013 ATUC64/128/256L3/4U 31.5 Product Dependencies In order to use the CAT module, other parts of the system must be configured correctly, as described below. 31.5.1 I/O Lines The CAT pins may be multiplexed with other peripherals. The user must first program the I/O Controller to give control of the pins to the CAT module. In QMatrix mode, the Y lines must be driven by the CAT and analog comparators sense the voltage on the Y lines. Thus, the CAT (not the Analog Comparator Interface) must be the selected function for the Y lines in the I/O Controller. By writing ones and zeros to bits in the Pin Mode Registers (PINMODEx), most of the CAT pins can be individually selected to implement the QTouch method or the QMatrix method. Each pin has a different name and function depending on whether it is implementing the QTouch method or the QMatrix method. The following table shows the pin names for each method and the bits in the PINMODEx registers which control the selection of the QTouch or QMatrix method. SMP SMP line (only used for QMatrix) Output SYNC Synchronize signal Input VDIVEN Voltage divider enable (only used for QMatrix) Output Table 31-1. I/O Lines Description Name Description Type Table 31-2. Pin Selection Guide CAT Module Pin Name QTouch Method Pin Name QMatrix Method Pin Name Selection Bit in PINMODEx Register CSA0 SNS0 X0 SP0 CSB0 SNSK0 X1 SP0 CSA1 SNS1 Y0 SP1 CSB1 SNSK1 YK0 SP1 CSA2 SNS2 X2 SP2 CSB2 SNSK2 X3 SP2 CSA3 SNS3 Y1 SP3 CSB3 SNSK3 YK1 SP3 CSA4 SNS4 X4 SP4 CSB4 SNSK4 X5 SP4 CSA5 SNS5 Y2 SP5 CSB5 SNSK5 YK2 SP5 CSA6 SNS6 X6 SP6 CSB6 SNSK6 X7 SP6 CSA7 SNS7 Y3 SP7 CSB7 SNSK7 YK3 SP7 CSA8 SNS8 X8 SP8 773 32142D–06/2013 ATUC64/128/256L3/4U 31.5.2 Clocks The clock for the CAT module, CLK_CAT, is generated by the Power Manager (PM). This clock is turned on by default, and can be enabled and disabled in the PM. The user must ensure that CLK_CAT is enabled before using the CAT module. QMatrix operations also require the CAT generic clock, GCLK_CAT. This generic clock is generated by the System Control Interface (SCIF), and is shared between the CAT and the Analog Comparator Interface. The user must ensure that the GCLK_CAT is enabled in the SCIF before using QMatrix functionality in the CAT module. For proper QMatrix operation, the frequency of GCLK_CAT must be less than half the frequency of CLK_CAT. If only QTouch functionality is used, then GCLK_CAT is unnecessary. 31.5.3 Interrupts The CAT interrupt request line is connected to the interrupt controller. Using CAT interrupts requires the interrupt controller to be programmed first. 31.5.4 Peripheral Events The CAT peripheral events are connected via the Peripheral Event System. Refer to the Peripheral Event System chapter for details. 31.5.5 Peripheral Direct Memory Access The CAT module provides handshake capability for a Peripheral DMA Controller. One handshake controls transfers from the Acquired Count Register (ACOUNT) to memory. A second handshake requests burst lengths for each (X,Y) pair to the Matrix Burst Length Register CSB8 SNSK8 X9 SP8 CSA9 SNS9 Y4 SP9 CSB9 SNSK9 YK4 SP9 CSA10 SNS10 X10 SP10 CSB10 SNSK10 X11 SP10 CSA11 SNS11 Y5 SP11 CSB11 SNSK11 YK5 SP11 CSA12 SNS12 X12 SP12 CSB12 SNSK12 X13 SP12 CSA13 SNS13 Y6 SP13 CSB13 SNSK13 YK6 SP13 CSA14 SNS14 X14 SP14 CSB14 SNSK14 X15 SP14 CSA15 SNS15 Y7 SP15 CSB15 SNSK15 YK7 SP15 CSA16 SNS16 X16 SP16 CSB16 SNSK16 X17 SP16 Table 31-2. Pin Selection Guide CAT Module Pin Name QTouch Method Pin Name QMatrix Method Pin Name Selection Bit in PINMODEx Register 774 32142D–06/2013 ATUC64/128/256L3/4U (MBLEN) when using the QMatrix acquisition method. Two additional handshakes support DMATouch by regulating transfers from memory to the DMATouch State Write Register (DMATSW) and from the DMATouch State Read Register (DMATSR) to memory. The Peripheral DMA Controller must be configured properly and enabled in order to perform direct memory access transfers to/from the CAT module. 31.5.6 Analog Comparators When the CAT module is performing QMatrix acquisition, it requires that on-chip analog comparators be used as part of the process. These analog comparators are not controlled directly by the CAT module, but by a separate Analog Comparator (AC) Interface. This interface must be configured properly and enabled before the CAT module is used. This includes configuring the generic clock input for the analog comparators to the proper sampling frequency. The CAT will automatically use the negative peripheral events from the AC Interface on every Y pin in QMatrix mode. When QMatrix acquisition is used the analog comparator corresponding to the selected Y pins must be enabled and converting continuously, using the Y pin as the positive reference and the ACREFN as negative reference. 31.5.7 Debug Operation When an external debugger forces the CPU into debug mode, the CAT continues normal operation. If the CAT is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 31.6 Functional Description 31.6.1 Acquisition Types The CAT module can perform several types of QTouch acquisition from capacitive touch sensors: autonomous QTouch (one sensor only), DMATouch, QTouch group A, and QTouch group B. The CAT module can also perform QMatrix acquisition. Each type of acquisition has an associated set of pin selection and configuration registers that allow a large degree of flexibility. The following schematic diagrams show typical hardware connections for QTouch and QMatrix sensors, respectively: Figure 31-2. CAT Touch Connections AVR32 Chip QTouch Sensor Cs (Sense Capacitor) SNSKn SNSn 775 32142D–06/2013 ATUC64/128/256L3/4U Figure 31-3. CAT Matrix Connections In order to use the autonomous QTouch detection capability, the user must first set up the Autonomous Touch Pin Select Register (ATPINS) and Autonomous/DMA Touch Configuration Registers (ATCFG0 through 3) with appropriate values. The module can then be enabled using the Control Register (CTRL). After the module is enabled, the module will acquire data from the autonomous QTouch sensor and use it to determine whether the sensor is activated. The active/inactive status of the autonomous QTouch sensor is reported in the Status Register (SR), and it is also possible to configure the CAT to generate an interrupt whenever the status changes. The module will continue acquiring autonomous QTouch sensor data and updating autonomous QTouch status until the module is disabled or reset. In order to use the DMATouch capability, it is first necessary to set up the pin mode registers (PINMODE0, PINMODE1, and PINMODE2) so that the desired pins are specified as DMATouch. The Autonomous/DMA Touch Configuration Registers (ATCFG0 through 3) must also be configured with appropriate values. One channel of the Peripheral DMA Controller must be set up to transfer state words from a block of memory to the DMATSW register, and another channel must be set up to transfer state words from the DMATSR register back to the same block of memory. The module can then be enabled using the CTRL register. After the module is enabled, the module will acquire count values from each DMATouch sensor. Once the module has acquired a count value for a sensor, it will use a handshake interface to signal the Peripheral DMA controller to transfer a state word to the DMATSW register. The module will use the count value to update the state word, and then the updated state word will be transferred to the DMATSR register. Another handshake interface will signal the Peripheral DMA controller to transfer the contents of the DMATSR register back to memory. The status of the DMATouch sensors can be determined at any time by reading the DMATouch Sensor Status Register (DMATSS). AVR32 Chip Cs0 (Sense Capacitor) X3 YK0 X6 QMatrix Sensor Array X7 X2 Y0 YK1 Y1 Cs1 (Sense Capacitor) SMP Rsmp1 Rsmp0 VDIVEN DIS Rdis ACREFN Ra Rb NOTE: If the CAT internal current sources will be enabled, the SMP signal and Rsmp resistors should NOT be included in the design. If the CAT internal current sources will NOT be enabled, the DIS signal and Rdis resistor should NOT be included in the design. 776 32142D–06/2013 ATUC64/128/256L3/4U In order to use the QMatrix, QTouch group A, or QTouch group B acquisition capabilities, it is first necessary to set up the pin mode registers (PINMODE0, PINMODE1, and PINMODE2) and configuration registers (MGCFG0, MGCFG1, TGACFG0, TGACFG1, TGBCFG0, and TGBCFG1). The module must then be enabled using the CTRL register. In order to initiate acquisition, it is necessary to perform a write to the Acquisition Initiation and Selection Register (AISR). The specific value written to AISR determines which type of acquisition will be performed: QMatrix, QTouch group A, or QTouch group B. The CPU can initiate acquisition by writing to the AISR. While QMatrix, QTouch group A, or QTouch group B acquisition is in progress, the module collects count values from the sensors and buffers them. Availability of acquired count data is indicated by the Acquisition Ready (ACREADY) bit in the Status Register (SR). The CPU or the Peripheral DMA Controller can then read the acquired counts from the ACOUNT register. Because the CAT module is configured with Peripheral DMA Controller capability that can transfer data from memory to MBLEN and from ACOUNT to memory, the Peripheral DMA Controller can perform long acquisition sequences and store results in memory without CPU intervention. 31.6.2 Prescaler and Charge Length Each QTouch acquisition type (autonomous QTouch, QTouch group A, and QTouch group B) has its own prescaler. Each QTouch prescaler divides down the CLK_CAT clock to an appropriate sampling frequency for its particular acquisition type. Typical frequencies are 1MHz for QTouch acquisition and 4MHz for QMatrix burst timing control. Each QTouch prescaler is controlled by the DIV field in the appropriate Configuration Register 0 (ATCFG0, TGACFG0, or TGBCFG0). The QMatrix burst timing prescaler is controlled by the DIV field in MGCFG0. Each prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) The capacitive sensor charge length, discharge length, and settle length can be determined for each acquisition type using the CHLEN, DILEN, and SELEN fields in Configuration Registers 0 and 1. The lengths are specified in terms of prescaler clocks. In addition, the QMatrix Cx discharge length can be determined using the CXDILEN field in MGCFG2. For QMatrix acquisition, the duration of CHLEN should not be set to the same value as the period of any periodic signal on any other pin. If the duration of CHLEN is the same as the period of a signal on another pin, it is likely that the other signal will significantly affect measurements due to stray capacitive coupling. For example, if a 1 MHz signal is generated on another pin of the chip, then CHLEN should not be 1 microsecond. For the QMatrix method, burst and capture lengths are set for each (X,Y) pair by writing the desired length values to the MBLEN register. The write must be done before each X line can start its acquisition and is indicated by the status bit MBLREQ in the Status Register (SR). A DMA handshake interface is also connected to this status bit to reduce CPU overhead during QMatrix acquisitions. Four burst lengths (BURST0..3) can be written at one time into the MBLEN register. If the current configuration uses Y lines larger than Y3 the register has to be written a second time. The first write to MBLEN specifies the burst length for Y lines 0 to 3 in the BURST0 to BURST3 fields, respectively. The second write specifies the burst length for Y lines 4 to 7 in fields BURST0 to BURST3, respectively, and so on. 777 32142D–06/2013 ATUC64/128/256L3/4U The Y and YK pins remain clamped to ground apart from the specified number of burst pulses, when charge is transferred and captured into the sampling capacitor. 31.6.3 Capacitive Count Acquisition For the QMatrix, QTouch group A, and QTouch group B types of acquisition, the module acquires count values from the sensors, buffers them, and makes them available for reading in the ACOUNT register. Further processing of the count values must be performed by the CPU. When the module performs QMatrix acquisition using multiple Y lines, it starts the capture for each Y line at the appropriate time in the burst sequence so that all captures finish simultaneously. For example, suppose that an acquisition is performed on Y0 and Y1 with BURST0=53 and BURST1=60. The module will first toggle the X line 7 times while capturing on Y1 while Y0 and YK0 are clamped to ground. The module will then toggle the X line 53 times while capturing on both Y1 and Y0. 31.6.4 Autonomous QTouch and DMATouch For autonomous QTouch and DMATouch, a complete detection algorithm is implemented within the CAT module. The additional parameters needed to control the detection algorithm must be specified by the user in the ATCFG2 and ATCFG3 registers. Autonomous QTouch and DMATouch sensitivity and out-of-touch sensitivity can be adjusted with the SENSE and OUTSENS fields, respectively, in ATCFG2. Each field accepts values from one to 255 where 255 is the least sensitive setting. The value in the OUTSENS field should be smaller than the value in the SENSE field. To avoid false positives a detect integration filtering technique can be used. The number of successive detects required is specified in the FILTER field of the ATCFG2 register. To compensate for changes in capacitance the CAT can recalibrate the autonomous QTouch sensor periodically. The timing of this calibration is done with the NDRIFT and PDRIFT fields in the Configuration register, ATCFG3. It is recommended that the PDRIFT value is smaller than the NDRIFT value. The autonomous QTouch sensor and DMATouch sensors will also recalibrate if the count value goes too far positive beyond a threshold. This positive recalibration threshold is specified by the PTHR field in the ATCFG3 register. The following block diagram shows the sequence of acquisition and processing operations used by the CAT module. The AISR written bit is internal and not visible in the user interface. 778 32142D–06/2013 ATUC64/128/256L3/4U Figure 31-4. CAT Acquisition and Processing Sequence 31.6.5 Spread Spectrum Sensor Drive To reduce electromagnetic compatibility issues, the capacitive sensors can be driven with a spread spectrum signal. To enable spread spectrum drive for a specific acquisition type, the user must write a one to the SPREAD bit in the appropriate Configuration Register 1 (MGCFG1, ATCFG1, TGACFG1, or TGBCFG1). During spread spectrum operation, the length of each pulse within a burst is varied in a deterministic pattern, so that the exact same burst pattern is used for a specific burst length. The maximum spread is determined by the MAXDEV field in the Spread Spectrum Configuration Register (SSCFG) register. The prescaler divisor is varied in a sawtooth pattern from (2(DIV+1))-MAXDEV to (2(DIV+1))+MAXDEV and then back to (2(DIV+1))-MAXDEV. For example, if DIV is 2 and MAXDEV is 3, the prescaler divisor will have the following sequence: 6, 7, 8, Idle Acquire autonomous touch count Acquire counts Update autonomous touch detection algorithm Wait for all acquired counts to be transferred AISR written flag set? No Yes Clear AISR written flag No Yes Autonomous touch enabled (ATEN)? 779 32142D–06/2013 ATUC64/128/256L3/4U 9, 3, 4, 5, 6, 7, 8, 9, 3, 4, etc. MAXDEV must not exceed the value of (2(DIV+1)), or undefined behavior will occur. 31.6.6 Synchronization To prevent interference from the 50 or 60 Hz mains line the CAT can trigger acquisition on the SYNC signal. The SYNC signal should be derived from the mains line. The acquisition will trigger on a falling edge of this signal. To enable synchronization for a specific acquisition type, the user must write a one to the SYNC bit in the appropriate Configuration Register 1 (MGCFG1, ATCFG1, TGACFG1, or TGBCFG1). For QMatrix acquisition, all X lines must be sampled at a specific phase of the noise signal for the synchronization to be effective. This can be accomplished by the synchronization timer, which is enabled by writing a non-zero value to the SYNCTIM field in the MGCFG2 register. This ensures that the start of the acquisition of each X line is spaced at regular intervals, defined by the SYNCTIM field. 31.6.7 Resistive Drive By default, the CAT pins are driven with normal I/O drive properties. Some of the CSA and CSB pins can optionally drive with a 1k output resistance for improved EMC. The pins that have this capability are listed in the Module Configuration section. 31.6.8 Discharge Current Sources The device integrates discharge current sources, which can be used to discharge the sampling capacitors during the QMatrix measurement phase. The discharge current sources are enabled by writing the GLEN bit in the Discharge Current Source (DICS) register to one. This enables an internal reference voltage, which can be either the internal 1.1V band gap voltage or VDDIO/3, as selected by the INTVREFSEL bit in the DICS register. If the DICS.INTREFSEL bit is one, the reference voltage is applied across an internal resistor, Rint. Otherwise, the voltage is applied to the DIS pin, and an external reference resistor must be connected between DIS and ground. The nominal discharge current is given by the following formula, where Vref is the reference voltage, Rref is the value of the reference resistor, trim is the value written to the DICS.TRIM field, and k is a constant of proportionality: I = (Vref/Rref)*(1+(k*trim)) The values for the internal reference resistor, Rint, and the constant, k, may be found in the Electrical Characteristics section. The nominal discharge current may be programmed between 2 and 20 µA. The reference current can be fine-tuned by adjusting the trim value in the DICS.TRIM field. The reference current is mirrored to each Y-pin if the corresponding bit is written to one in the DICS.SOURCES field. 31.6.9 Voltage Divider Enable (VDIVEN) Capability In many QMatrix applications, the sense capacitors will be charged to 50 mV or more and the negative reference pin (ACREFN) of the analog comparators can be tied directly to ground. In that case, the relatively small input offset voltage of the comparators will not cause acquisition problems. However, in certain specialized QMatrix applications such as interpolated touch screens, it may be desirable for the sense capacitors to be charged to less than 25 mV. When such small voltages are used on the sense capacitors, the input offset voltage of the comparators becomes an issue and can cause QMatrix acquisition problems. 780 32142D–06/2013 ATUC64/128/256L3/4U Problems with QMatrix acquisition of small sense capacitor voltages can be solved by connecting the negative reference pin (ACREFN) to a voltage divider that produces a small positive voltage (20 mV, typically) to cancel any negative input offset voltage. With a 3.3V supply, recommended values for the voltage divider are Ra (resistor from positive supply to ACREFN) of 8200 ohm and Rb (resistor from ACREFN to ground) of 50 ohm. These recommended values will produce 20 mV on the ACREFN pin, which should generally be enough to compensate for the worst-case negative input offset of the analog comparators. Unfortunately, such a voltage divider constantly draws a small current from the power supply, reducing battery life in portable applications. In order to prevent this constant power drain, the CAT module provides a voltage divider enable pin (VDIVEN) that can be used for driving the voltage divider. The VDIVEN pin provides power to the voltage divider only when the comparators are actually performing QMatrix comparisons. When the comparators are inactive, the VDIVEN output is zero. This minimizes the power consumed by the voltage divider. 781 32142D–06/2013 ATUC64/128/256L3/4U 31.7 User Interface Table 31-3. CAT Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Autonomous Touch Pin Selection Register ATPINS Read/Write 0x00000000 0x08 Pin Mode Register 0 PINMODE0 Read/Write 0x00000000 0x0C Pin Mode Register 1 PINMODE1 Read/Write 0x00000000 0x10 Autonomous/DMA Touch Configuration Register 0 ATCFG0 Read/Write 0x00000000 0x14 Autonomous/DMA Touch Configuration Register 1 ATCFG1 Read/Write 0x00000000 0x18 Autonomous/DMA Touch Configuration Register 2 ATCFG2 Read/Write 0x00000000 0x1C Autonomous/DMA Touch Configuration Register 3 ATCFG3 Read/Write 0x00000000 0x20 Touch Group A Configuration Register 0 TGACFG0 Read/Write 0x00000000 0x24 Touch Group A Configuration Register 1 TGACFG1 Read/Write 0x00000000 0x28 Touch Group B Configuration Register 0 TGBCFG0 Read/Write 0x00000000 0x2C Touch Group B Configuration Register 1 TGBCFG1 Read/Write 0x00000000 0x30 Matrix Group Configuration Register 0 MGCFG0 Read/Write 0x00000000 0x34 Matrix Group Configuration Register 1 MGCFG1 Read/Write 0x00000000 0x38 Matrix Group Configuration Register 2 MGCFG2 Read/Write 0x00000000 0x3C Status Register SR Read-only 0x00000000 0x40 Status Clear Register SCR Write-only - 0x44 Interrupt Enable Register IER Write-only - 0x48 Interrupt Disable Register IDR Write-only - 0x4C Interrupt Mask Register IMR Read-only 0x00000000 0x50 Acquisition Initiation and Selection Register AISR Read/Write 0x00000000 0x54 Acquired Count Register ACOUNT Read-only 0x00000000 0x58 Matrix Burst Length Register MBLEN Write-only - 0x5C Discharge Current Source Register DICS Read/Write 0x00000000 0x60 Spread Spectrum Configuration Register SSCFG Read/Write 0x00000000 0x64 CSA Resistor Control Register CSARES Read/Write 0x00000000 0x68 CSB Resistor Control Register CSBRES Read/Write 0x00000000 0x6C Autonomous Touch Base Count Register ATBASE Read-only 0x00000000 0x70 Autonomous Touch Current Count Register ATCURR Read-only 0x00000000 0x74 Pin Mode Register 2 PINMODE2 Read/Write 0x00000000 0x78 DMATouch State Write Register DMATSW Write-only 0x00000000 0x7C DMATouch State Read Register DMATSR Read-only 0x00000000 0x80 Analog Comparator Shift Offset Register 0 ACSHI0 Read/Write 0x00000000 0x84 Analog Comparator Shift Offset Register 1 ACSHI1 Read/Write 0x00000000 0x88 Analog Comparator Shift Offset Register 2 ACSHI2 Read/Write 0x00000000 782 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. The reset value for this register is device specific. Please refer to the Module Configuration section at the end of this chapter. 0x8C Analog Comparator Shift Offset Register 3 ACSHI3 Read/Write 0x00000000 0x90 Analog Comparator Shift Offset Register 4 ACSHI4 Read/Write 0x00000000 0x94 Analog Comparator Shift Offset Register 5 ACSHI5 Read/Write 0x00000000 0x98 Analog Comparator Shift Offset Register 6 ACSHI6 Read/Write 0x00000000 0x9C Analog Comparator Shift Offset Register 7 ACSHI7 Read/Write 0x00000000 0xA0 DMATouch Sensor Status Register DMATSS Read-only 0x00000000 0xF8 Parameter Register PARAMETER Read-only -(1) 0xFC Version Register VERSION Read-only -(1) Table 31-3. CAT Register Memory Map Offset Register Register Name Access Reset 783 32142D–06/2013 ATUC64/128/256L3/4U 31.7.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • SWRST: Software reset Writing a zero to this bit has no effect. Writing a one to this bit resets the module. The module will be disabled after the reset. This bit always reads as zero. • EN: Module enable 0: Module is disabled. 1: Module is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 SWRST - - - - - - EN 784 32142D–06/2013 ATUC64/128/256L3/4U 31.7.2 Autonomous Touch Pin Selection Register Name: ATPINS Access Type: Read/Write Offset: 0x04 Reset Value: 0x00000000 • ATEN: Autonomous Touch Enable 0: Autonomous QTouch acquisition and detection is disabled. 1: Autonomous QTouch acquisition and detection is enabled using the sense pair specified in ATSP. • ATSP: Autonomous Touch Sense Pair Selects the sense pair that will be used by the autonomous QTouch sensor. A value of n will select sense pair n (CSAn and CSBn pins). 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - - - - ATEN 76543210 - - - ATSP 785 32142D–06/2013 ATUC64/128/256L3/4U 31.7.3 Pin Mode Registers 0, 1, and 2 Name: PINMODE0, PINMODE1, and PINMODE2 Access Type: Read/Write Offset: 0x08, 0x0C, 0x74 Reset Value: 0x00000000 • SP: Sense Pair Mode Selection Each SP[n] bit determines the operation mode of sense pair n (CSAn and CSBn pins). The (PINMODE2.SP[n] PINMODE1.SP[n] PINMODE0.SP[n]) bits have the following definitions: 000: Sense pair n disabled. 001: Sense pair n is assigned to QTouch Group A. 010: Sense pair n is assigned to QTouch Group B. 011: Sense pair n is assigned to the QMatrix Group. 100: Sense pair n is assigned to the DMATouch Group. 101: Reserved. 110: Reserved. 111: Reserved. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - SP[16] 15 14 13 12 11 10 9 8 SP[15:8] 76543210 SP[7:0] 786 32142D–06/2013 ATUC64/128/256L3/4U 31.7.4 Autonomous/DMA Touch Configuration Register 0 Name: ATCFG0 Access Type: Read/Write Offset: 0x10 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 1 MHz to produce the sampling clock.The prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 787 32142D–06/2013 ATUC64/128/256L3/4U 31.7.5 Autonomous/DMA Touch Configuration Register 1 Name: ATCFG1 Access Type: Read/Write Offset: 0x14 Reset Value: 0x00000000 • DISHIFT: Discharge Shift For the autonomous QTouch sensor and DMATouch sensors, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For the autonomous QTouch sensor and DMATouch sensors, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For the autonomous QTouch sensor and DMATouch sensors, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For the autonomous QTouch sensor and DMATouch sensors, specifies how many sample clock cycles the CAT should use to discharge the capacitors before charging them. • MAX: Maximum Count For the autonomous QTouch sensor and DMATouch sensors, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - DISHIFT - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 788 32142D–06/2013 ATUC64/128/256L3/4U 31.7.6 Autonomous/DMA Touch Configuration Register 2 Name: ATCFG2 Access Type: Read/Write Offset: 0x18 Reset Value: 0x00000000 • FILTER: Autonomous Touch Filter Setting For the autonomous QTouch sensor and DMATouch sensors, specifies how many positive detects in a row the CAT needs to have on the sensor before reporting it as a touch. A FILTER value of 0 is not allowed and will result in undefined behavior. • OUTSENS: Out-of-Touch Sensitivity For the autonomous QTouch sensor and DMATouch sensors, specifies how sensitive the out-of-touch detector should be. • SENSE: Sensitivity For the autonomous QTouch sensor and DMATouch sensors, specifies how sensitive the touch detector should be. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - FILTER 15 14 13 12 11 10 9 8 OUTSENS 76543210 SENSE 789 32142D–06/2013 ATUC64/128/256L3/4U 31.7.7 Autonomous/DMA Touch Configuration Register 3 Name: ATCFG3 Access Type: Read/Write Offset: 0x1C Reset Value: 0x00000000 • PTHR: Positive Recalibration Threshold For the autonomous QTouch sensor and DMATouch sensors, specifies how far a sensor’s signal must move in a positive direction from the reference in order to cause a recalibration. • PDRIFT: Positive Drift Compensation For the autonomous QTouch sensor and DMATouch sensors, specifies how often a positive drift compensation should be performed. When this field is zero, positive drift compensation will never be performed. When this field is non-zero, the positive drift compensation time interval is given by the following formula: Tpdrift = PDRIFT * 65536 * (sample clock period) • NDRIFT: Negative Drift Compensation For the autonomous QTouch sensor and DMATouch sensors, specifies how often a negative drift compensation should be performed. When this field is zero, negative drift compensation will never be performed. When this field is non-zero, the negative drift compensation time interval is given by the following formula: Tndrift = NDRIFT * 65536 * (sample clock period) With the typical sample clock frequency of 1 MHz, PDRIFT and NDRIFT can be set from 0.066 seconds to 16.7 seconds with 0.066 second resolution. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 PTHR 15 14 13 12 11 10 9 8 PDRIFT 76543210 NDRIFT 790 32142D–06/2013 ATUC64/128/256L3/4U 31.7.8 Touch Group x Configuration Register 0 Name: TGxCFG0 Access Type: Read/Write Offset: 0x20, 0x28 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 1 MHz to produce the sampling clock.The prescaler uses the following formula to generate the sampling clock: Sampling clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For the QTouch method, specifies how many sample clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For the QTouch method, specifies how many sample clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 791 32142D–06/2013 ATUC64/128/256L3/4U 31.7.9 Touch Group x Configuration Register 1 Name: TGxCFG1 Access Type: Read/Write Offset: 0x24, 0x2C Reset Value: 0x00000000 • DISHIFT: Discharge Shift For the sensors in QTouch group x, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For sensors in QTouch group x, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For sensors in QTouch group x, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For sensors in QTouch group x, specifies how many clock cycles the CAT should use to discharge the capacitors before charging them. • MAX: Touch Maximum Count For sensors in QTouch group x, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - - DISHIFT - - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 792 32142D–06/2013 ATUC64/128/256L3/4U 31.7.10 Matrix Group Configuration Register 0 Name: MGCFG0 Access Type: Read/Write Offset: 0x30 Reset Value: 0x00000000 • DIV: Clock Divider The prescaler is used to ensure that the CLK_CAT clock is divided to around 4 MHz to produce the burst timing clock.The prescaler uses the following formula to generate the burst timing clock: Burst timing clock = CLK_CAT / (2(DIV+1)) • CHLEN: Charge Length For QMatrix sensors, specifies how many burst prescaler clock cycles should be used for transferring charge to the sense capacitor. • SELEN: Settle Length For QMatrix sensors, specifies how many burst prescaler clock cycles should be used for settling after charge transfer. 31 30 29 28 27 26 25 24 DIV[15:8] 23 22 21 20 19 18 17 16 DIV[7:0] 15 14 13 12 11 10 9 8 CHLEN 76543210 SELEN 793 32142D–06/2013 ATUC64/128/256L3/4U 31.7.11 Matrix Group Configuration Register 1 Name: MGCFG1 Access Type: Read/Write Offset: 0x34 Reset Value: 0x00000000 • DISHIFT: Discharge Shift For QMatrix sensors, specifies how many bits the DILEN field should be shifted before using it to determine the discharge time. • SYNC: Sync Pin For QMatrix sensors, specifies that acquisition shall begin when a falling edge is received on the SYNC line. • SPREAD: Spread Spectrum Sensor Drive For QMatrix sensors, specifies that spread spectrum sensor drive shall be used. • DILEN: Discharge Length For QMatrix sensors, specifies how many burst prescaler clock cycles the CAT should use to discharge the capacitors at the beginning of a burst sequence. • MAX: Maximum Count For QMatrix sensors, specifies how many counts the maximum acquisition should be. 31 30 29 28 27 26 25 24 - DISHIFT - SYNC SPREAD 23 22 21 20 19 18 17 16 DILEN 15 14 13 12 11 10 9 8 MAX[15:8] 76543210 MAX[7:0] 794 32142D–06/2013 ATUC64/128/256L3/4U 31.7.12 Matrix Group Configuration Register 2 Name: MGCFG2 Access Type: Read/Write Offset: 0x38 Reset Value: 0x00000000 • ACCTRL: Analog Comparator Control When written to one, allows the CAT to disable the analog comparators when they are not needed. When written to zero, the analog comparators are always enabled. • CONSEN: Consensus Filter Length For QMatrix sensors, specifies that discharge will be terminated when CONSEN out of the most recent 5 comparator samples are positive. For example, a value of 3 in the CONSEN field will terminate discharge when 3 out of the most recent 5 comparator samples are positive. When CONSEN has the default value of 0, discharge will be terminated immediately when the comparator output goes positive. • CXDILEN: Cx Capacitor Discharge Length For QMatrix sensors, specifies how many burst prescaler clock cycles the CAT should use to discharge the Cx capacitor at the end of each burst cycle. • SYNCTIM: Sync Time Interval When non-zero, determines the number of prescaled clock cycles between the start of the acquisition on each X line for QMatrix acquisition. 31 30 29 28 27 26 25 24 ACCTRL CONSEN - 23 22 21 20 19 18 17 16 CXDILEN 15 14 13 12 11 10 9 8 - SYNCTIM[11:8] 76543210 SYNCTIM[7:0] 795 32142D–06/2013 ATUC64/128/256L3/4U 31.7.13 Status Register Name: SR Access Type: Read-only Offset: 0x3C Reset Value: 0x00000000 • DMATSC: DMATouch Sensor State Change 0: No change in the DMATSS register. 1: One or more bits have changed in the DMATSS register. • DMATSR: DMATouch State Read Register Ready 0: A new state word is not available in the DMATSR register. 1: A new state word is available in the DMATSR register. • DMATSW: DMATouch State Write Register Request 0: The DMATouch algorithm is not requesting that a state word be written to the DMATSW register. 1: The DMATouch algorithm is requesting that a state word be written to the DMATSW register. • ACQDONE: Acquisition Done 0: Acquisition is not done (still in progress). 1: Acquisition is complete. • ACREADY: Acquired Count Data is Ready 0: Acquired count data is not available in the ACOUNT register. 1: Acquired count data is available in the ACOUNT register. • MBLREQ: Matrix Burst Length Required 0: The QMatrix acquisition does not require any burst lengths. 1: The QMatrix acquisition requires burst lengths for the current X line. • ATSTATE: Autonomous Touch Sensor State 0: The autonomous QTouch sensor is not active. 1: The autonomous QTouch sensor is active. • ATSC: Autonomous Touch Sensor Status Interrupt 0: No status change in the autonomous QTouch sensor. 1: Status change in the autonomous QTouch sensor. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - DMATSR DMATSW 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - MBLREQ ATSTATE ATSC ATCAL ENABLED 796 32142D–06/2013 ATUC64/128/256L3/4U • ATCAL: Autonomous Touch Calibration Ongoing 0: The autonomous QTouch sensor is not calibrating. 1: The autonomous QTouch sensor is calibrating. • ENABLED: Module Enabled 0: The module is disabled. 1: The module is enabled. 797 32142D–06/2013 ATUC64/128/256L3/4U 31.7.14 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x40 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 798 32142D–06/2013 ATUC64/128/256L3/4U 31.7.15 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x44 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 799 32142D–06/2013 ATUC64/128/256L3/4U 31.7.16 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x48 Reset Value: - Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 800 32142D–06/2013 ATUC64/128/256L3/4U 31.7.17 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x4C Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 DMATSC - - - - - - - 15 14 13 12 11 10 9 8 - - - - - - ACQDONE ACREADY 76543210 - - - - - ATSC ATCAL - 801 32142D–06/2013 ATUC64/128/256L3/4U 31.7.18 Acquisition Initiation and Selection Register Name: AISR Access Type: Read/Write Offset: 0x50 Reset Value: 0x00000000 • ACQSEL: Acquisition Type Selection A write to this register initiates an acquisition of the following type: 00: QTouch Group A. 01: QTouch Group B. 10: QMatrix Group. 11: Undefined behavior. A read of this register will return the value that was previously written. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 - 76543210 - ACQSEL 802 32142D–06/2013 ATUC64/128/256L3/4U 31.7.19 Acquired Count Register Name: ACOUNT Access Type: Read-only Offset: 0x54 Reset Value: 0x00000000 • Y: Y index The Y index (for QMatrix method) associated with this count value. • SPORX: Sensor pair or X index The sensor pair index (for QTouch method) or X index (for QMatrix method) associated with this count value. • COUNT: Count value The signal (number of counts) acquired on the channel specified in the SPORX and Y fields. When multiple acquired count values are read from a QTouch acquisition, the Y field will always be 0 and the SPORX value will increase monotonically. For example, suppose a QTouch acquisition is performed using sensor pairs SP1, SP4, and SP9. The first count read will have SPORX=1, the second read will have SPORX=4, and the third read will have SPORX=9. When multiple acquired count values are read from a QMatrix acquisition, the SPORX value will stay the same while Y increases monotonically through all Y values in the group. Then SPORX will increase to the next X value in the group. For example, a QMatrix acquisition with X=2,3 and Y=4,7 would provide count values in the following order: X=2 and Y=4, then X=2 and Y=7, then X=3 and Y=4, and finally X=3 and Y=7. 31 30 29 28 27 26 25 24 Y 23 22 21 20 19 18 17 16 SPORX 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 803 32142D–06/2013 ATUC64/128/256L3/4U 31.7.20 Matrix Burst Length Register Name: MBLEN Access Type: Write-only Offset: 0x58 Reset Value: - • BURSTx: Burst Length x For QMatrix sensors, specifies how many times the switching sequence should be repeated before acquisition begins for each channel. Each count in the BURSTx field specifies 1 repeat of the switching sequence, so the actual burst length will be BURST. Before doing a QMatrix acquisition on one X line this register has to be written with the burst values for the current XY pairs. For each X line this register needs to be programmed with all the Y values. If Y values larger than 3 are used the register has to be written several times in order to specify all burst lengths. The Status Register bit MBLREQ is set to 1 when the CAT is waiting for values to be written into this register. 31 30 29 28 27 26 25 24 BURST0 23 22 21 20 19 18 17 16 BURST1 15 14 13 12 11 10 9 8 BURST2 76543210 BURST3 804 32142D–06/2013 ATUC64/128/256L3/4U 31.7.21 Discharge Current Source Register Name: DICS Access Type: Read/Write Offset: 0x5C Reset Value: 0x00000000 • FSOURCES: Force Discharge Current Sources When FSOURCES[n] is 0, the corresponding discharge current source behavior depends on SOURCES[n]. When FSOURCES[n] is 1, the corresponding discharge current source is forced to be enabled continuously. This is useful for testing or debugging but should not be done during normal acquisition. • GLEN: Global Enable 0: The current source module is globally disabled. 1: The current source module is globally enabled. • INTVREFSEL: Internal Voltage Reference Select 0: The voltage for the reference resistor is generated from the internal band gap circuit. 1: The voltage for the reference resistor is VDDIO/3. • INTREFSEL: Internal Reference Select 0: The reference current flows through an external resistor on the DIS pin. 1: The reference current flows through the internal reference resistor. • TRIM: Reference Current Trimming This field is used to trim the discharge current. 0x00 corresponds to the minimum current value, and 0x1F corresponds to the maximum current value. • SOURCES: Enable Discharge Current Sources When SOURCES[n] is 0, the corresponding discharge current source is disabled. When SOURCES[n] is 1, the corresponding discharge current source is enabled at appropriate times during acquisition. 31 30 29 28 27 26 25 24 FSOURCES[7:0] 23 22 21 20 19 18 17 16 GLEN - - - - - INTVREFSEL INTREFSEL 15 14 13 12 11 10 9 8 - - - TRIM 76543210 SOURCES[7:0] 805 32142D–06/2013 ATUC64/128/256L3/4U 31.7.22 Spread Spectrum Configuration Register Name: SSCFG Access Type: Read/Write Offset: 0x60 Reset Value: 0x00000000 • MAXDEV: Maximum Deviation When spread spectrum burst is enabled, MAXDEV indicates the maximum number of prescaled clock cycles the burst pulse will be extended or shortened. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 MAXDEV 806 32142D–06/2013 ATUC64/128/256L3/4U 31.7.23 CSA Resistor Control Register Name: CSARES Access Type: Read/Write Offset: 0x64 Reset Value: 0x00000000 • RES: Resistive Drive Enable When RES[n] is 0, CSA[n] has the same drive properties as normal I/O pads. When RES[n] is 1, CSA[n] has a nominal output resistance of 1kOhm during the burst phase. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - RES[16] 15 14 13 12 11 10 9 8 RES[15:8] 76543210 RES[7:0] 807 32142D–06/2013 ATUC64/128/256L3/4U 31.7.24 CSB Resistor Control Register Name: CSBRES Access Type: Read/Write Offset: 0x68 Reset Value: 0x00000000 • RES: Resistive Drive Enable When RES[n] is 0, CSB[n] has the same drive properties as normal I/O pads. When RES[n] is 1, CSB[n] has a nominal output resistance of 1kOhm during the burst phase. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - RES[16] 15 14 13 12 11 10 9 8 RES[15:8] 76543210 RES[7:0] 808 32142D–06/2013 ATUC64/128/256L3/4U 31.7.25 Autonomous Touch Base Count Register Name: ATBASE Access Type: Read-only Offset: 0x6C Reset Value: 0x00000000 • COUNT: Count value The base count currently stored by the autonomous touch sensor. This is useful for autonomous touch debugging purposes. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 809 32142D–06/2013 ATUC64/128/256L3/4U 31.7.26 Autonomous Touch Current Count Register Name: ATCURR Access Type: Read-only Offset: 0x70 Reset Value: 0x00000000 • COUNT: Count value The current count acquired by the autonomous touch sensor. This is useful for autonomous touch debugging purposes. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 COUNT[15:8] 76543210 COUNT[7:0] 810 32142D–06/2013 ATUC64/128/256L3/4U 31.7.27 DMATouch State Write Register Name: DMATSW Access Type: Write-only Offset: 0x78 Reset Value: 0x00000000 • NOTINCAL: Not in Calibration Mode 0: Calibration should be performed on the next iteration of the DMATouch algorithm. 1: Calibration should not be performed on the next iteration of the DMATouch algorithm. • DETCNT: Detection Count This count value is updated and used by the DMATouch algorithm in order to detect when a button has been pushed. • BASECNT: Base Count This count value represents the average expected acquired count when the sensor/button is not pushed. 31 30 29 28 27 26 25 24 - - - - - - - NOTINCAL 23 22 21 20 19 18 17 16 DETCNT[23:16] 15 14 13 12 11 10 9 8 BASECNT[15:8] 76543210 BASECNT[7:0] 811 32142D–06/2013 ATUC64/128/256L3/4U 31.7.28 DMA Touch State Read Register Name: DMATSR Access Type: Read/Write Offset: 0x7C Reset Value: 0x00000000 • NOTINCAL: Not in Calibration Mode 0: Calibration should be performed on the next iteration of the DMATouch algorithm. 1: Calibration should not be performed on the next iteration of the DMATouch algorithm. • DETCNT: Detection Count This count value is updated and used by the DMATouch algorithm in order to detect when a button has been pushed. • BASECNT: Base Count This count value represents the average expected acquired count when the sensor/button is not pushed. 31 30 29 28 27 26 25 24 - - - - - - - NOTINCAL 23 22 21 20 19 18 17 16 DETCNT[23:16] 15 14 13 12 11 10 9 8 BASECNT[15:8] 76543210 BASECNT[7:0] 812 32142D–06/2013 ATUC64/128/256L3/4U 31.7.29 Analog Comparator Shift Offset Register x Name: ACSHIx Access Type: Read/Write Offset: 0x80, 0x84, 0x88, 0x8C, 0x90, 0x94, 0x98, and 0x9C Reset Value: 0x00000000 • SHIVAL: Shift Offset Value Specifies the amount to shift the count value from each comparator. This allows the offset of each comparator to be compensated. 31 30 29 28 27 26 25 24 - 23 22 21 20 19 18 17 16 - 15 14 13 12 11 10 9 8 - SHIVAL[11:8] 76543210 SHIVAL[7:0] 813 32142D–06/2013 ATUC64/128/256L3/4U 31.7.30 DMATouch Sensor Status Register Name: DMATSS Access Type: Read-only Offset: 0xA0 Reset Value: 0x00000000 • SS: Sensor Status 0: The DMATouch sensor is not active, i.e. the button is currently not pushed. 1: The DMATouch sensor is active, i.e. the button is currently pushed. 31 30 29 28 27 26 25 24 SS[31:24] 23 22 21 20 19 18 17 16 SS[23:16] 15 14 13 12 11 10 9 8 SS[15:8] 76543210 SS[7:0] 814 32142D–06/2013 ATUC64/128/256L3/4U 31.7.31 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0xF8 Reset Value: - • SP[n]: Sensor pair implemented 0: The corresponding sensor pair is not implemented 1: The corresponding sensor pair is implemented. 31 30 29 28 27 26 25 24 SP[31:24] 23 22 21 20 19 18 17 16 SP[23:16] 15 14 13 12 11 10 9 8 SP[15:8] 76543210 SP[7:0] 815 32142D–06/2013 ATUC64/128/256L3/4U 31.7.32 Version Register Name: VERSION Access Type: Read-only Offset: 0xFC Reset Value: - • VARIANT: Variant number Reserved. No functionality associated. • VERSION: Version number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 816 32142D–06/2013 ATUC64/128/256L3/4U 31.8 Module Configuration The specific configuration the CAT module is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. 31.8.1 Resistive Drive By default, the CAT pins are driven with normal I/O drive properties. Some of the CSA and CSB pins can optionally drive with a 1k output resistance for improved EMC. To enable resistive drive on a pin, the user must write a one to the corresponding bit in the CSA Resistor Control Register (CSARES) or CSB Resistor Control Register (CSBRES) register. Table 31-4. CAT Configuration Feature CAT Number of touch sensors/Size of matrix Allows up to 17 touch sensors, or up to 16 by 8 matrix sensors to be interfaced. Table 31-5. CAT Clocks Clock Name Description CLK_CAT Clock for the CAT bus interface GCLK The generic clock used for the CAT is GCLK4 Table 31-6. Register Reset Values Register Reset Value VERSION 0x00000400 PARAMETER 0x0001FFFF 817 32142D–06/2013 ATUC64/128/256L3/4U 32. Glue Logic Controller (GLOC) Rev: 1.0.0.0 32.1 Features • Glue logic for general purpose PCB design • Programmable lookup table • Up to four inputs supported per lookup table • Optional filtering of output 32.2 Overview The Glue Logic Controller (GLOC) contains programmable logic which can be connected to the device pins. This allows the user to eliminate logic gates for simple glue logic functions on the PCB. The GLOC consists of a number of lookup table (LUT) units. Each LUT can generate an output as a user programmable logic expression with four inputs. Inputs can be individually masked. The output can be combinatorially generated from the inputs, or filtered to remove spikes. 32.3 Block Diagram Figure 32-1. GLOC Block Diagram PERIPHERAL BUS TRUTH FILTER OUT[0] ... OUT[n] FILTEN IN[3:0] … IN[(4n+3):4n] AEN CLK_GLOC GCLK 818 32142D–06/2013 ATUC64/128/256L3/4U 32.4 I/O Lines Description Each LUT have 4 inputs and one output. The inputs and outputs for the LUTs are mapped sequentially to the inputs and outputs. This means that LUT0 is connected to IN0 to IN3 and OUT0. LUT1 is connected to IN4 to IN7 and OUT1. In general, LUTn is connected to IN[4n] to IN[4n+3] and OUTn. 32.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 32.5.1 I/O Lines The pins used for interfacing the GLOC may be multiplexed with I/O Controller lines. The programmer must first program the I/O Controller to assign the desired GLOC pins to their peripheral function. If I/O lines of the GLOC are not used by the application, they can be used for other purposes by the I/O Controller. It is only required to enable the GLOC inputs and outputs actually in use. Pullups for pins configured to be used by the GLOC will be disabled. 32.5.2 Clocks The clock for the GLOC bus interface (CLK_GLOC) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the GLOC before disabling the clock, to avoid freezing the module in an undefined state. Additionally, the GLOC depends on a dedicated Generic Clock (GCLK). The GCLK can be set to a wide range of frequencies and clock sources, and must be enabled by the System Control Interface (SCIF) before the GLOC filter can be used. 32.5.3 Debug Operation When an external debugger forces the CPU into debug mode, the GLOC continues normal operation. 32.6 Functional Description 32.6.1 Enabling the Lookup Table Inputs Since the inputs to each lookup table (LUT) unit can be multiplexed with other peripherals, each input must be explicitly enabled by writing a one to the corresponding enable bit (AEN) in the corresponding Control Register (CR). If no inputs are enabled, the output OUTn will be the least significant bit in the TRUTHn register. Table 32-1. I/O Lines Description Pin Name Pin Description Type IN0-INm Inputs to lookup tables Input OUT0-OUTn Output from lookup tables Output 819 32142D–06/2013 ATUC64/128/256L3/4U 32.6.2 Configuring the Lookup Table The lookup table in each LUT unit can generate any logic expression OUT as a function of up to four inputs, IN[3:0]. The truth table for the expression is written to the TRUTH register for the LUT. Table 32-2 shows the truth table for LUT0. The truth table for LUTn is written to TRUTHn, and the corresponding input and outputs will be IN[4n] to IN[4n+3] and OUTn. 32.6.3 Output Filter By default, the output OUTn is a combinatorial function of the inputs IN[4n] to IN[4n+3]. This may cause some short glitches to occur when the inputs change value. It is also possible to clock the output through a filter to remove glitches. This requires that the corresponding generic clock (GCLK) has been enabled before use. The filter can then be enabled by writing a one to the Filter Enable (FILTEN) bit in CRn. The OUTn output will be delayed by three to four GCLK cycles when the filter is enabled. Table 32-2. Truth Table for the Lookup Table in LUT0 IN[3] IN[2] IN[1] IN[0] OUT[0] 0 0 0 0 TRUTH0[0] 0 0 0 1 TRUTH0[1] 0 0 1 0 TRUTH0[2] 0 0 1 1 TRUTH0[3] 0 1 0 0 TRUTH0[4] 0 1 0 1 TRUTH0[5] 0 1 1 0 TRUTH0[6] 0 1 1 1 TRUTH0[7] 1 0 0 0 TRUTH0[8] 1 0 0 1 TRUTH0[9] 1 0 1 0 TRUTH0[10] 1 0 1 1 TRUTH0[11] 1 1 0 0 TRUTH0[12] 1 1 0 1 TRUTH0[13] 1 1 1 0 TRUTH0[14] 1 1 1 1 TRUTH0[15] 820 32142D–06/2013 ATUC64/128/256L3/4U 32.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 32-3. GLOC Register Memory Map Offset Register Register Name Access Reset 0x00+n*0x08 Control Register n CRn Read/Write 0x00000000 0x04+n*0x08 Truth Table Register n TRUTHn Read/Write 0x00000000 0x38 Parameter Register PARAMETER Read-only - (1) 0x3C Version Register VERSION Read-only - (1) 821 32142D–06/2013 ATUC64/128/256L3/4U 32.7.1 Control Register n Name: CRn Access Type: Read/Write Offset: 0x00+n*0x08 Reset Value: 0x00000000 • FILTEN: Filter Enable 1: The output is glitch filtered 0: The output is not glitch filtered • AEN: Enable IN Inputs Input IN[n] is enabled when AEN[n] is one. Input IN[n] is disabled when AEN[n] is zero, and will not affect the OUT value. 31 30 29 28 27 26 25 24 FILTEN - - - - - - - 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - AEN 822 32142D–06/2013 ATUC64/128/256L3/4U 32.7.2 Truth Table Register n Name: TRUTHn Access Type: Read/Write Offset: 0x04+n*0x08 Reset Value: 0x00000000 • TRUTH: Truth Table Value This value defines the output OUT as a function of inputs IN: OUT = TRUTH[IN] 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 TRUTH[15:8] 76543210 TRUTH[7:0] 823 32142D–06/2013 ATUC64/128/256L3/4U 32.7.3 Parameter Register Name: PARAMETER Access Type: Read-only Offset: 0x38 Reset Value: - • LUTS: Lookup Table Units Implemented This field contains the number of lookup table units implemented in this device. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 LUTS 824 32142D–06/2013 ATUC64/128/256L3/4U 32.7.4 VERSION Register Name: VERSION Access Type: Read-only Offset: 0x3C Reset Value: - • VARIANT: Variant Number Reserved. No functionality associated. • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 - - - - VARIANT 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 825 32142D–06/2013 ATUC64/128/256L3/4U 32.8 Module Configuration The specific configuration for each GLOC instance is listed in the following tables.The GLOC bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 32-4. GLOC Configuration Feature GLOC Number of LUT units 2 Table 32-5. GLOC Clocks Clock Name Description CLK_GLOC Clock for the GLOC bus interface GCLK The generic clock used for the GLOC is GCLK5 Table 32-6. Register Reset Values Register Reset Value VERSION 0x00000100 PARAMETER 0x00000002 826 32142D–06/2013 ATUC64/128/256L3/4U 33. aWire UART (AW) Rev: 2.3.0.0 33.1 Features • Asynchronous receiver or transmitter when the aWire system is not used for debugging. • One- or two-pin operation supported. 33.2 Overview If the AW is not used for debugging, the aWire UART can be used by the user to send or receive data with one start bit, eight data bits, no parity bits, and one stop bit. This can be controlled through the aWire UART user interface. This chapter only describes the aWire UART user interface. For a description of the aWire Debug Interface, please see the Programming and Debugging chapter. 33.3 Block Diagram Figure 33-1. aWire Debug Interface Block Diagram UART Reset filter External reset AW_ENABLE RESET_N Baudrate Detector RW SZ ADDR DATA CRC AW CONTROL AW User Interface SAB interface RESET command Power Manager HALT command CPU Flash Controller CHIP_ERASE command aWire Debug Interface PB SAB 827 32142D–06/2013 ATUC64/128/256L3/4U 33.4 I/O Lines Description 33.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 33.5.1 I/O Lines The pin used by AW is multiplexed with the RESET_N pin. The reset functionality is the default function of this pin. To enable the aWire functionality on the RESET_N pin the user must enable the aWire UART user interface. 33.5.2 Power Management If the CPU enters a sleep mode that disables clocks used by the aWire UART user interface, the aWire UART user interface will stop functioning and resume operation after the system wakes up from sleep mode. 33.5.3 Clocks The aWire UART uses the internal 120 MHz RC oscillator (RC120M) as clock source for its operation. When using the aWire UART user interface RC120M must enabled using the Clock Request Register (see Section 33.6.1). The clock for the aWire UART user interface (CLK_AW) is generated by the Power Manager. This clock is enabled at reset, and can be disabled in the Power Manager. It is recommended to disable the aWire UART user interface before disabling the clock, to avoid freezing the aWire UART user interface in an undefined state. 33.5.4 Interrupts The aWire UART user interface interrupt request line is connected to the interrupt controller. Using the aWire UART user interface interrupt requires the interrupt controller to be programmed first. 33.5.5 Debug Operation If the AW is used for debugging the aWire UART user interface will not be usable. When an external debugger forces the CPU into debug mode, the aWire UART user interface continues normal operation. If the aWire UART user interface is configured in a way that requires it to be periodically serviced by the CPU through interrupts or similar, improper operation or data loss may result during debugging. 33.5.6 External Components The AW needs an external pullup on the RESET_N pin to ensure that the pin is pulled up when the bus is not driven. 33.6 Functional Description The aWire UART user interface can be used as a spare Asynchronous Receiver or Transmitter when AW is not used for debugging. Table 33-1. I/O Lines Description Name Description Type DATA aWire data multiplexed with the RESET_N pin. Input/Output 828 32142D–06/2013 ATUC64/128/256L3/4U 33.6.1 How to Initialize The Module To initialize the aWire UART user interface the user must first enable the clock by writing a one to the Clock Enable bit in the Clock Request Register (CLKR.CLKEN) and wait for the Clock Enable bit in the Status Register (SR.CENABLED) to be set. After doing this either receive, transmit or receive with resync must be selected by writing the corresponding value into the Mode field of the Control (CTRL.MODE) Register. Due to the RC120M being asynchronous with the system clock values must be allowed to propagate in the system. During this time the aWire master will set the Busy bit in the Status Register (SR.BUSY). After the SR.BUSY bit is cleared the Baud Rate field in the Baud Rate Register (BRR.BR) can be written with the wanted baudrate ( ) according to the following formula ( is the RC120M clock frequency): After this operation the user must wait until the SR.BUSY is cleared. The interface is now ready to be used. 33.6.2 Basic Asynchronous Receiver Operation The aWire UART user interface must be initialized according to the sequence above, but the CTRL.MODE field must be written to one (Receive mode). When a data byte arrives the aWire UART user interface will indicate this by setting the Data Ready Interrupt bit in the Status Register (SR.DREADYINT). The user must read the Data in the Receive Holding Register (RHR.RXDATA) and clear the Interrupt bit by writing a one to the Data Ready Interrupt Clear bit in the Status Clear Register (SCR.DREADYINT). The interface is now ready to receive another byte. 33.6.3 Basic Asynchronous Transmitter Operation The aWire UART user interface must be initialized according to the sequence above, but the CTRL.MODE field must be written to two (Transmit mode). To transmit a data byte the user must write the data to the Transmit Holding Register (THE.TXDATA). Before the next byte can be written the SR.BUSY must be cleared. 33.6.4 Basic Asynchronous Receiver with Resynchronization By writing three into CTRL.MODE the aWire UART user interface will assume that the first byte it receives is a sync byte (0x55) and set BRR.BR according to this. All subsequent transfers will assume this baudrate, unless BRR.BR is rewritten by the user. To make the aWire UART user interface accept a new sync resynchronization the aWire UART user interface must be disabled by writing zero to CTRL.MODE and then reenable the interface. 33.6.5 Overrun In Receive mode an overrun can occur if the user has not read the previous received data from the RHR.RXDATA when the newest data should be placed there. Such a condition is flagged by setting the Overrun bit in the Status Register (SR.OVERRUN). If SR.OVERRUN is set the newest data received is placed in RHR.RXDATA and the data that was there before is overwritten. f br f aw f br 8f aw BR = ----------- 829 32142D–06/2013 ATUC64/128/256L3/4U 33.6.6 Interrupts To make the CPU able to do other things while waiting for the aWire UART user interface to finish its operations the aWire UART user interface supports generating interrupts. All status bits in the Status Register can be used as interrupt sources, except the SR.BUSY and SR.CENABLED bits. To enable an interrupt the user must write a one to the corresponding bit in the Interrupt Enable Register (IER). Upon the next zero to one transition of this SR bit the aWire UART user interface will flag this interrupt to the CPU. To clear the interrupt the user must write a one to the corresponding bit in the Status Clear Register (SCR). Interrupts can be disabled by writing a one to the corresponding bit in the Interrupt Disable Register (IDR). The interrupt Mask Register (IMR) can be read to check if an interrupt is enabled or disabled. 33.6.7 Using the Peripheral DMA Controller To relieve the CPU of data transfers the aWire UART user interface support using the Peripheral DMA controller. To transmit using the Peripheral DMA Controller do the following: 1. Setup the aWire UART user interface in transmit mode. 2. Setup the Peripheral DMA Controller with buffer address and length, use byte as transfer size. 3. Enable the Peripheral DMA Controller. 4. Wait until the Peripheral DMA Controller is done. To receive using the Peripheral DMA Controller do the following: 1. Setup the aWire UART user interface in receive mode 2. Setup the Peripheral DMA Controller with buffer address and length, use byte as transfer size. 3. Enable the Peripheral DMA Controller. 4. Wait until the Peripheral DMA Controller is ready. 830 32142D–06/2013 ATUC64/128/256L3/4U 33.7 User Interface Note: 1. The reset values are device specific. Please refer to the Module Configuration section at the end of this chapter. Table 33-2. aWire UART user interface Register Memory Map Offset Register Register Name Access Reset 0x00 Control Register CTRL Read/Write 0x00000000 0x04 Status Register SR Read-only 0x00000000 0x08 Status Clear Register SCR Write-only - 0x0C Interrupt Enable Register IER Write-only - 0x10 Interrupt Disable Register IDR Write-only - 0x14 Interrupt Mask Register IMR Read-only 0x00000000 0x18 Receive Holding Register RHR Read-only 0x00000000 0x1C Transmit Holding Register THR Read/Write 0x00000000 0x20 Baud Rate Register BRR Read/Write 0x00000000 0x24 Version Register VERSION Read-only -(1) 0x28 Clock Request Register CLKR Read/Write 0x00000000 831 32142D–06/2013 ATUC64/128/256L3/4U 33.7.1 Control Register Name: CTRL Access Type: Read/Write Offset: 0x00 Reset Value: 0x00000000 • MODE: aWire UART user interface mode 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - MODE Table 33-3. aWire UART user interface Modes MODE Mode Description 0 Disabled 1 Receive 2 Transmit 3 Receive with resync. 832 32142D–06/2013 ATUC64/128/256L3/4U 33.7.2 Status Register Name: SR Access Type: Read-only Offset: 0x04 Reset Value: 0x00000000 • TRMIS: Transmit Mismatch 0: No transfers mismatches. 1: The transceiver was active when receiving. This bit is set when the transceiver is active when receiving. This bit is cleared when corresponding bit in SCR is written to one. • OVERRUN: Data Overrun 0: No data overwritten in RHR. 1: Data in RHR has been overwritten before it has been read. This bit is set when data in RHR is overwritten before it has been read. This bit is cleared when corresponding bit in SCR is written to one. • DREADYINT: Data Ready Interrupt 0: No new data in the RHR. 1: New data received and placed in the RHR. This bit is set when new data is received and placed in the RHR. This bit is cleared when corresponding bit in SCR is written to one. • READYINT: Ready Interrupt 0: The interface has not generated an ready interrupt. 1: The interface has had a transition from busy to not busy. This bit is set when the interface has transition from busy to not busy. This bit is cleared when corresponding bit in SCR is written to one. • CENABLED: Clock Enabled 0: The aWire clock is not enabled. 1: The aWire clock is enabled. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 - - - - - CENABLED - BUSY 833 32142D–06/2013 ATUC64/128/256L3/4U This bit is set when the clock is disabled. This bit is cleared when the clock is enabled. • BUSY: Synchronizer Busy 0: The asynchronous interface is ready to accept more data. 1: The asynchronous interface is busy and will block writes to CTRL, BRR, and THR. This bit is set when the asynchronous interface becomes busy. This bit is cleared when the asynchronous interface becomes ready. 834 32142D–06/2013 ATUC64/128/256L3/4U 33.7.3 Status Clear Register Name: SCR Access Type: Write-only Offset: 0x08 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in SR and the corresponding interrupt request. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 835 32142D–06/2013 ATUC64/128/256L3/4U 33.7.4 Interrupt Enable Register Name: IER Access Type: Write-only Offset: 0x0C Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will set the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 836 32142D–06/2013 ATUC64/128/256L3/4U 33.7.5 Interrupt Disable Register Name: IDR Access Type: Write-only Offset: 0x10 Reset Value: 0x00000000 Writing a zero to a bit in this register has no effect. Writing a one to a bit in this register will clear the corresponding bit in IMR. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 837 32142D–06/2013 ATUC64/128/256L3/4U 33.7.6 Interrupt Mask Register Name: IMR Access Type: Read-only Offset: 0x14 Reset Value: 0x00000000 0: The corresponding interrupt is disabled. 1: The corresponding interrupt is enabled. A bit in this register is cleared when the corresponding bit in IDR is written to one. A bit in this register is set when the corresponding bit in IER is written to one. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - TRMIS - - OVERRUN DREADYINT READYINT 76543210 -------- 838 32142D–06/2013 ATUC64/128/256L3/4U 33.7.7 Receive Holding Register Name: RHR Access Type: Read-only Offset: 0x18 Reset Value: 0x00000000 • RXDATA: Received Data The last byte received. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 RXDATA 839 32142D–06/2013 ATUC64/128/256L3/4U 33.7.8 Transmit Holding Register Name: THR Access Type: Read/Write Offset: 0x1C Reset Value: 0x00000000 • TXDATA: Transmit Data The data to send. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 TXDATA 840 32142D–06/2013 ATUC64/128/256L3/4U 33.7.9 Baud Rate Register Name: BRR Access Type: Read/Write Offset: 0x20 Reset Value: 0x00000000 • BR: Baud Rate The baud rate ( ) of the transmission, calculated using the following formula ( is the RC120M frequency): BR should not be set to a value smaller than 32. Writing a value to this field will update the baud rate of the transmission. Reading this field will give the current baud rate of the transmission. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 BR[15:8] 76543210 BR[7:0] f br f aw f br 8f aw BR = ----------- 841 32142D–06/2013 ATUC64/128/256L3/4U 33.7.10 Version Register Name: VERSION Access Type: Read-only Offset: 0x24 Reset Value: 0x00000200 • VERSION: Version Number Version number of the module. No functionality associated. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 - - - - VERSION[11:8] 76543210 VERSION[7:0] 842 32142D–06/2013 ATUC64/128/256L3/4U 33.7.11 Clock Request Register Name: CLKR Access Type: Read/Write Offset: 0x28 Reset Value: 0x00000000 • CLKEN: Clock Enable 0: The aWire clock is disabled. 1: The aWire clock is enabled. Writing a zero to this bit will disable the aWire clock. Writing a one to this bit will enable the aWire clock. 31 30 29 28 27 26 25 24 -------- 23 22 21 20 19 18 17 16 -------- 15 14 13 12 11 10 9 8 -------- 76543210 - - - - - - - CLKEN 843 32142D–06/2013 ATUC64/128/256L3/4U 33.8 Module Configuration The specific configuration for each aWire instance is listed in the following tables.The module bus clocks listed here are connected to the system bus clocks. Please refer to the Power Manager chapter for details. Table 33-4. AW Clocks Clock Name Description CLK_AW Clock for the AW bus interface Table 33-5. Register Reset Values Register Reset Value VERSION 0x00000230 844 32142D–06/2013 ATUC64/128/256L3/4U 34. Programming and Debugging 34.1 Overview The ATUC64/128/256L3/4U supports programming and debugging through two interfaces, JTAG or aWire. JTAG is an industry standard interface and allows boundary scan for PCB testing, as well as daisy-chaining of multiple devices on the PCB. aWire is an Atmel proprietary protocol which offers higher throughput and robust communication, and does not require application pins to be reserved. Either interface provides access to the internal Service Access Bus (SAB), which offers a bridge to the High Speed Bus, giving access to memories and peripherals in the device. By using this bridge to the bus system, the flash and fuses can thus be programmed by accessing the Flash Controller in the same manner as the CPU. The SAB also provides access to the Nexus-compliant On-chip Debug (OCD) system in the device, which gives the user non-intrusive run-time control of the program execution. Additionally, trace information can be output on the Auxiliary (AUX) debug port or buffered in internal RAM for later retrieval by JTAG or aWire. 34.2 Service Access Bus The AVR32 architecture offers a common interface for access to On-chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), which is linked to the JTAG and aWire port through a bus master module, which also handles synchronization between the debugger and SAB clocks. When accessing the SAB through the debugger there are no limitations on debugger frequency compared to chip frequency, although there must be an active system clock in order for the SAB accesses to complete. If the system clock is switched off in sleep mode, activity on the debugger will restart the system clock automatically, without waking the device from sleep. Debuggers may optimize the transfer rate by adjusting the frequency in relation to the system clock. This ratio can be measured with debug protocol specific instructions. The Service Access Bus uses 36 address bits to address memory or registers in any of the slaves on the bus. The bus supports sized accesses of bytes (8 bits), halfwords (16 bits), or words (32 bits). All accesses must be aligned to the size of the access, i.e. halfword accesses must have the lowest address bit cleared, and word accesses must have the two lowest address bits cleared. 34.2.1 SAB Address Map The SAB gives the user access to the internal address space and other features through a 36 bits address space. The 4 MSBs identify the slave number, while the 32 LSBs are decoded within the slave’s address space. The SAB slaves are shown in Table 34-1. Table 34-1. SAB Slaves, Addresses and Descriptions Slave Address [35:32] Description Unallocated 0x0 Intentionally unallocated OCD 0x1 OCD registers HSB 0x4 HSB memory space, as seen by the CPU 845 32142D–06/2013 ATUC64/128/256L3/4U 34.2.2 SAB Security Restrictions The Service Access bus can be restricted by internal security measures. A short description of the security measures are found in the table below. 34.2.2.1 Security measure and control location A security measure is a mechanism to either block or allow SAB access to a certain address or address range. A security measure is enabled or disabled by one or several control signals. This is called the control location for the security measure. These security measures can be used to prevent an end user from reading out the code programmed in the flash, for instance. Below follows a more in depth description of what locations are accessible when the security measures are active. Note: 1. Second Word of the User Page, refer to the Fuses Settings section for details. HSB 0x5 Alternative mapping for HSB space, for compatibility with other 32-bit AVR devices. Memory Service Unit 0x6 Memory Service Unit registers Reserved Other Unused Table 34-1. SAB Slaves, Addresses and Descriptions Slave Address [35:32] Description Table 34-2. SAB Security Measures Security Measure Control Location Description Secure mode FLASHCDW SECURE bits set Allocates a portion of the flash for secure code. This code cannot be read or debugged. The User page is also locked. Security bit FLASHCDW security bit set Programming and debugging not possible, very restricted access. User code programming FLASHCDW UPROT + security bit set Restricts all access except parts of the flash and the flash controller for programming user code. Debugging is not possible unless an OS running from the secure part of the flash supports it. Table 34-3. Secure Mode SAB Restrictions Name Address Start Address End Access Secure flash area 0x580000000 0x580000000 + (USERPAGE[15:0] << 10) Blocked Secure RAM area 0x500000000 0x500000000 + (USERPAGE[31:16] << 10) Blocked User page 0x580800000 0x581000000 Read Other accesses - - As normal 846 32142D–06/2013 ATUC64/128/256L3/4U Table 34-4. Security Bit SAB Restrictions Name Address start Address end Access OCD DCCPU, OCD DCEMU, OCD DCSR 0x100000110 0x100000118 Read/Write User page 0x580800000 0x581000000 Read Other accesses - - Blocked Table 34-5. User Code Programming SAB Restrictions Name Address start Address end Access OCD DCCPU, OCD DCEMU, OCD DCSR 0x100000110 0x100000118 Read/Write User page 0x580800000 0x581000000 Read FLASHCDW PB interface 0x5FFFE0000 0x5FFFE0400 Read/Write FLASH pages outside BOOTPROT 0x580000000 + BOOTPROT size 0x580000000 + Flash size Read/Write Other accesses - - Blocked 847 32142D–06/2013 ATUC64/128/256L3/4U 34.3 On-Chip Debug Rev: 2.1.2.0 34.3.1 Features • Debug interface in compliance with IEEE-ISTO 5001-2003 (Nexus 2.0) Class 2+ • JTAG or aWire access to all on-chip debug functions • Advanced Program, Data, Ownership, and Watchpoint trace supported • NanoTrace aWire- or JTAG-based trace access • Auxiliary port for high-speed trace information • Hardware support for 6 Program and 2 Data breakpoints • Unlimited number of software breakpoints supported • Automatic CRC check of memory regions 34.3.2 Overview Debugging on the ATUC64/128/256L3/4U is facilitated by a powerful On-Chip Debug (OCD) system. The user accesses this through an external debug tool which connects to the JTAG or aWire port and the Auxiliary (AUX) port if implemented. The AUX port is primarily used for trace functions, and an aWire- or JTAG-based debugger is sufficient for basic debugging. The debug system is based on the Nexus 2.0 standard, class 2+, which includes: • Basic run-time control • Program breakpoints • Data breakpoints • Program trace • Ownership trace • Data trace In addition to the mandatory Nexus debug features, the ATUC64/128/256L3/4U implements several useful OCD features, such as: • Debug Communication Channel between CPU and debugger • Run-time PC monitoring • CRC checking • NanoTrace • Software Quality Assurance (SQA) support The OCD features are controlled by OCD registers, which can be accessed by the debugger, for instance when the NEXUS_ACCESS JTAG instruction is loaded. The CPU can also access OCD registers directly using mtdr/mfdr instructions in any privileged mode. The OCD registers are implemented based on the recommendations in the Nexus 2.0 standard, and are detailed in the AVR32UC Technical Reference Manual. 34.3.3 I/O Lines Description The OCD AUX trace port contains a number of pins, as shown in Table 34-6 on page 848. These are multiplexed with I/O Controller lines, and must explicitly be enabled by writing OCD registers before the debug session starts. The AUX port is mapped to two different locations, 848 32142D–06/2013 ATUC64/128/256L3/4U selectable by OCD Registers, minimizing the chance that the AUX port will need to be shared with an application. 34.3.4 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. 34.3.4.1 Power Management The OCD clock operates independently of the CPU clock. If enabled in the Power Manager, the OCD clock (CLK_OCD) will continue running even if the CPU enters a sleep mode that disables the CPU clock. 34.3.4.2 Clocks The OCD has a clock (CLK_OCD) running synchronously with the CPU clock. This clock is generated by the Power Manager. The clock is enabled at reset, and can be disabled by writing to the Power Manager. 34.3.4.3 Interrupt The OCD system interrupt request lines are connected to the interrupt controller. Using the OCD interrupts requires the interrupt controller to be programmed first. Table 34-6. Auxiliary Port Signals Pin Name Pin Description Direction Active Level Type MCKO Trace data output clock Output Digital MDO[5:0] Trace data output Output Digital MSEO[1:0] Trace frame control Output Digital EVTI_N Event In Input Low Digital EVTO_N Event Out Output Low Digital 849 32142D–06/2013 ATUC64/128/256L3/4U 34.3.5 Block Diagram Figure 34-1. On-Chip Debug Block Diagram 34.3.6 SAB-based Debug Features A debugger can control all OCD features by writing OCD registers over the SAB interface. Many of these do not depend on output on the AUX port, allowing an aWire- or JTAG-based debugger to be used. A JTAG-based debugger should connect to the device through a standard 10-pin IDC connector as described in the AVR32UC Technical Reference Manual. An aWire-based debugger should connect to the device through the RESET_N pin. On-Chip Debug JTAG Debug PC Debug Instruction CPU Breakpoints Program Trace Data Trace Ownership Trace Transmit Queue Watchpoints AUX JTAG Internal SRAM Service Access Bus Memory Service Unit HSB Bus Matrix Memories and peripherals aWire aWire 850 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-2. JTAG-based Debugger Figure 34-3. aWire-based Debugger 34.3.6.1 Debug Communication Channel The Debug Communication Channel (DCC) consists of a pair OCD registers with associated handshake logic, accessible to both CPU and debugger. The registers can be used to exchange data between the CPU and the debugmaster, both runtime as well as in debug mode. 32-bit AVR JTAG-based debug tool PC JTAG 10-pin IDC 32-bit AVR aWire-based debug tool PC aWire 851 32142D–06/2013 ATUC64/128/256L3/4U The OCD system can generate an interrupt to the CPU when DCCPU is read and when DCEMU is written. This enables the user to build a custum debug protocol using only these registers. The DCCPU and DCEMU registers are available even when the security bit in the flash is active. For more information refer to the AVR32UC Technical Reference Manual. 34.3.6.2 Breakpoints One of the most fundamental debug features is the ability to halt the CPU, to examine registers and the state of the system. This is accomplished by breakpoints, of which many types are available: • Unconditional breakpoints are set by writing OCD registers by the debugger, halting the CPU immediately. • Program breakpoints halt the CPU when a specific address in the program is executed. • Data breakpoints halt the CPU when a specific memory address is read or written, allowing variables to be watched. • Software breakpoints halt the CPU when the breakpoint instruction is executed. When a breakpoint triggers, the CPU enters debug mode, and the D bit in the status register is set. This is a privileged mode with dedicated return address and return status registers. All privileged instructions are permitted. Debug mode can be entered as either OCD Mode, running instructions from the debugger, or Monitor Mode, running instructions from program memory. 34.3.6.3 OCD Mode When a breakpoint triggers, the CPU enters OCD mode, and instructions are fetched from the Debug Instruction OCD register. Each time this register is written by the debugger, the instruction is executed, allowing the debugger to execute CPU instructions directly. The debug master can e.g. read out the register file by issuing mtdr instructions to the CPU, writing each register to the Debug Communication Channel OCD registers. 34.3.6.4 Monitor Mode Since the OCD registers are directly accessible by the CPU, it is possible to build a softwarebased debugger that runs on the CPU itself. Setting the Monitor Mode bit in the Development Control register causes the CPU to enter Monitor Mode instead of OCD mode when a breakpoint triggers. Monitor Mode is similar to OCD mode, except that instructions are fetched from the debug exception vector in regular program memory, instead of issued by the debug master. 34.3.6.5 Program Counter Monitoring Normally, the CPU would need to be halted for a debugger to examine the current PC value. However, the ATUC64/128/256L3/4U also proves a Debug Program Counter OCD register, where the debugger can continuously read the current PC without affecting the CPU. This allows the debugger to generate a simple statistic of the time spent in various areas of the code, easing code optimization. 34.3.7 Memory Service Unit The Memory Service Unit (MSU) is a block dedicated to test and debug functionality. It is controlled through a dedicated set of registers addressed through the Service Access Bus. 852 32142D–06/2013 ATUC64/128/256L3/4U 34.3.7.1 Cyclic Redundancy Check (CRC) The MSU can be used to automatically calculate the CRC of a block of data in memory. The MSU will then read out each word in the specified memory block and report the CRC32-value in an MSU register. 34.3.7.2 NanoTrace The MSU additionally supports NanoTrace. This is a 32-bit AVR-specific feature, in which trace data is output to memory instead of the AUX port. This allows the trace data to be extracted by the debugger through the SAB, enabling trace features for aWire- or JTAG-based debuggers. The user must write MSU registers to configure the address and size of the memory block to be used for NanoTrace. The NanoTrace buffer can be anywhere in the physical address range, including internal and external RAM, through an EBI, if present. This area may not be used by the application running on the CPU. 34.3.8 AUX-based Debug Features Utilizing the Auxiliary (AUX) port gives access to a wide range of advanced debug features. Of prime importance are the trace features, which allow an external debugger to receive continuous information on the program execution in the CPU. Additionally, Event In and Event Out pins allow external events to be correlated with the program flow. Debug tools utilizing the AUX port should connect to the device through a Nexus-compliant Mictor-38 connector, as described in the AVR32UC Technical Reference manual. This connector includes the JTAG signals and the RESET_N pin, giving full access to the programming and debug features in the device. 853 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-4. AUX+JTAG Based Debugger 34.3.8.1 Trace Operation Trace features are enabled by writing OCD registers by the debugger. The OCD extracts the trace information from the CPU, compresses this information and formats it into variable-length messages according to the Nexus standard. The messages are buffered in a 16-frame transmit queue, and are output on the AUX port one frame at a time. The trace features can be configured to be very selective, to reduce the bandwidth on the AUX port. In case the transmit queue overflows, error messages are produced to indicate loss of data. The transmit queue module can optionally be configured to halt the CPU when an overflow occurs, to prevent the loss of messages, at the expense of longer run-time for the program. 34.3.8.2 Program Trace Program trace allows the debugger to continuously monitor the program execution in the CPU. Program trace messages are generated for every branch in the program, and contains compressed information, which allows the debugger to correlate the message with the source code to identify the branch instruction and target address. 34.3.8.3 Data Trace Data trace outputs a message every time a specific location is read or written. The message contains information about the type (read/write) and size of the access, as well as the address and data of the accessed location. The ATUC64/128/256L3/4U contains two data trace chanAVR32 AUX+JTAG debu g tool JTAG AUX h ig h s p e e d M ic to r3 8 T ra ce b u ffe r P C 854 32142D–06/2013 ATUC64/128/256L3/4U nels, each of which are controlled by a pair of OCD registers which determine the range of addresses (or single address) which should produce data trace messages. 34.3.8.4 Ownership Trace Program and data trace operate on virtual addresses. In cases where an operating system runs several processes in overlapping virtual memory segments, the Ownership Trace feature can be used to identify the process switch. When the O/S activates a process, it will write the process ID number to an OCD register, which produces an Ownership Trace Message, allowing the debugger to switch context for the subsequent program and data trace messages. As the use of this feature depends on the software running on the CPU, it can also be used to extract other types of information from the system. 34.3.8.5 Watchpoint Messages The breakpoint modules normally used to generate program and data breakpoints can also be used to generate Watchpoint messages, allowing a debugger to monitor program and data events without halting the CPU. Watchpoints can be enabled independently of breakpoints, so a breakpoint module can optionally halt the CPU when the trigger condition occurs. Data trace modules can also be configured to produce watchpoint messages instead of regular data trace messages. 34.3.8.6 Event In and Event Out Pins The AUX port also contains an Event In pin (EVTI_N) and an Event Out pin (EVTO_N). EVTI_N can be used to trigger a breakpoint when an external event occurs. It can also be used to trigger specific program and data trace synchronization messages, allowing an external event to be correlated to the program flow. When the CPU enters debug mode, a Debug Status message is transmitted on the trace port. All trace messages can be timestamped when they are received by the debug tool. However, due to the latency of the transmit queue buffering, the timestamp will not be 100% accurate. To improve this, EVTO_N can toggle every time a message is inserted into the transmit queue, allowing trace messages to be timestamped precisely. EVTO_N can also toggle when a breakpoint module triggers, or when the CPU enters debug mode, for any reason. This can be used to measure precisely when the respective internal event occurs. 34.3.8.7 Software Quality Analysis (SQA) Software Quality Analysis (SQA) deals with two important issues regarding embedded software development. Code coverage involves identifying untested parts of the embedded code, to improve test procedures and thus the quality of the released software. Performance analysis allows the developer to precisely quantify the time spent in various parts of the code, allowing bottlenecks to be identified and optimized. Program trace must be used to accomplish these tasks without instrumenting (altering) the code to be examined. However, traditional program trace cannot reconstruct the current PC value without correlating the trace information with the source code, which cannot be done on-the-fly. This limits program trace to a relatively short time segment, determined by the size of the trace buffer in the debug tool. The OCD system in ATUC64/128/256L3/4U extends program trace with SQA capabilities, allowing the debug tool to reconstruct the PC value on-the-fly. Code coverage and performance analysis can thus be reported for an unlimited execution sequence. 855 32142D–06/2013 ATUC64/128/256L3/4U 34.4 JTAG and Boundary-scan (JTAG) Rev: 2.2.2.4 34.4.1 Features • IEEE1149.1 compliant JTAG Interface • Boundary-scan Chain for board-level testing • Direct memory access and programming capabilities through JTAG Interface 34.4.2 Overview The JTAG Interface offers a four pin programming and debug solution, including boundary-scan support for board-level testing. Figure 34-5 on page 856 shows how the JTAG is connected in an 32-bit AVR device. The TAP Controller is a state machine controlled by the TCK and TMS signals. The TAP Controller selects either the JTAG Instruction Register or one of several Data Registers as the scan chain (shift register) between the TDI-input and TDO-output. The Instruction Register holds JTAG instructions controlling the behavior of a Data Register. The Device Identification Register, Bypass Register, and the boundary-scan chain are the Data Registers used for board-level testing. The Reset Register can be used to keep the device reset during test or programming. The Service Access Bus (SAB) interface contains address and data registers for the Service Access Bus, which gives access to On-Chip Debug, programming, and other functions in the device. The SAB offers several modes of access to the address and data registers, as described in Section 34.4.11. Section 34.5 lists the supported JTAG instructions, with references to the description in this document. 856 32142D–06/2013 ATUC64/128/256L3/4U 34.4.3 Block Diagram Figure 34-5. JTAG and Boundary-scan Access 34.4.4 I/O Lines Description 34.4.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 34-7. I/O Line Description Pin Name Pin Description Type Active Level RESET_N External reset pin. Used when enabling and disabling the JTAG. Input Low TCK Test Clock Input. Fully asynchronous to system clock frequency. Input TMS Test Mode Select, sampled on rising TCK. Input TDI Test Data In, sampled on rising TCK. Input TDO Test Data Out, driven on falling TCK. Output 32-bit AVR device JTAG data registers TAP Controller Instruction Register Device Identification Register By-pass Register Reset Register Service Access Bus interface Boundary Scan Chain Pins and analog blocks Data register scan enable JTAG Pins Boundary scan enable 2nd JTAG device JTAG master TDO TDI Part specific registers ... TMS TDO TDI TMS TCK TCK Instruction register scan enable SAB Internal I/O lines JTAG TMS TDI TDO TCK 857 32142D–06/2013 ATUC64/128/256L3/4U 34.4.5.1 I/O Lines The TMS, TDI, TDO, and TCK pins are multiplexed with I/O lines. When the JTAG is used the associated pins must be enabled. To enable the JTAG pins, refer to Section 34.4.7. While using the multiplexed JTAG lines all normal peripheral activity on these lines is disabled. The user must make sure that no external peripheral is blocking the JTAG lines while debugging. 34.4.5.2 Power Management When an instruction that accesses the SAB is loaded in the instruction register, before entering a sleep mode, the system clocks are not switched off to allow debugging in sleep modes. This can lead to a program behaving differently when debugging. 34.4.5.3 Clocks The JTAG Interface uses the external TCK pin as clock source. This clock must be provided by the JTAG master. Instructions that use the SAB bus requires the internal main clock to be running. 34.4.6 JTAG Interface The JTAG Interface is accessed through the dedicated JTAG pins shown in Table 34-7 on page 856. The TMS control line navigates the TAP controller, as shown in Figure 34-6 on page 858. The TAP controller manages the serial access to the JTAG Instruction and Data registers. Data is scanned into the selected instruction or data register on TDI, and out of the register on TDO, in the Shift-IR and Shift-DR states, respectively. The LSB is shifted in and out first. TDO is highZ in other states than Shift-IR and Shift-DR. The device implements a 5-bit Instruction Register (IR). A number of public JTAG instructions defined by the JTAG standard are supported, as described in Section 34.5.2, as well as a number of 32-bit AVR-specific private JTAG instructions described in Section 34.5.3. Each instruction selects a specific data register for the Shift-DR path, as described for each instruction. 858 32142D–06/2013 ATUC64/128/256L3/4U Figure 34-6. TAP Controller State Diagram Test-LogicReset Run-Test/ Idle Select-DR Scan Select-IR Scan Capture-DR Capture-IR Shift-DR Shift-IR Exit1-DR Exit1-IR Pause-DR Pause-IR Exit2-DR Exit2-IR Update-DR Update-IR 0 1 1 1 0 0 1 0 1 1 0 0 1 0 1 1 1 0 1 1 0 0 1 1 0 1 0 0 0 0 0 1 859 32142D–06/2013 ATUC64/128/256L3/4U 34.4.7 How to Initialize the Module To enable the JTAG pins the TCK pin must be held low while the RESET_N pin is released. After enabling the JTAG interface the halt bit is set automatically to prevent the system from running code after the interface is enabled. To make the CPU run again set halt to zero using the HALT command.. JTAG operation when RESET_N is pulled low is not possible. Independent of the initial state of the TAP Controller, the Test-Logic-Reset state can always be entered by holding TMS high for 5 TCK clock periods. This sequence should always be applied at the start of a JTAG session and after enabling the JTAG pins to bring the TAP Controller into a defined state before applying JTAG commands. Applying a 0 on TMS for 1 TCK period brings the TAP Controller to the Run-Test/Idle state, which is the starting point for JTAG operations. 34.4.8 How to disable the module To disable the JTAG pins the TCK pin must be held high while RESET_N pin is released. 34.4.9 Typical Sequence Assuming Run-Test/Idle is the present state, a typical scenario for using the JTAG Interface follows. 34.4.9.1 Scanning in JTAG Instruction At the TMS input, apply the sequence 1, 1, 0, 0 at the rising edges of TCK to enter the Shift Instruction Register (Shift-IR) state. While in this state, shift the 5 bits of the JTAG instructions into the JTAG instruction register from the TDI input at the rising edge of TCK. During shifting, the JTAG outputs status bits on TDO, refer to Section 34.5 for a description of these. The TMS input must be held low during input of the 4 LSBs in order to remain in the Shift-IR state. The JTAG Instruction selects a particular Data Register as path between TDI and TDO and controls the circuitry surrounding the selected Data Register. Apply the TMS sequence 1, 1, 0 to re-enter the Run-Test/Idle state. The instruction is latched onto the parallel output from the shift register path in the Update-IR state. The Exit-IR, Pause-IR, and Exit2-IR states are only used for navigating the state machine. Figure 34-7. Scanning in JTAG Instruction 34.4.9.2 Scanning in/out Data At the TMS input, apply the sequence 1, 0, 0 at the rising edges of TCK to enter the Shift Data Register (Shift-DR) state. While in this state, upload the selected Data Register (selected by the present JTAG instruction in the JTAG Instruction Register) from the TDI input at the rising edge TCK TAP State TLR RTI SelDR SelIR CapIR ShIR Ex1IR UpdIR RTI TMS TDI Instruction TDO ImplDefined 860 32142D–06/2013 ATUC64/128/256L3/4U of TCK. In order to remain in the Shift-DR state, the TMS input must be held low. While the Data Register is shifted in from the TDI pin, the parallel inputs to the Data Register captured in the Capture-DR state is shifted out on the TDO pin. Apply the TMS sequence 1, 1, 0 to re-enter the Run-Test/Idle state. If the selected Data Register has a latched parallel-output, the latching takes place in the Update-DR state. The Exit-DR, Pause-DR, and Exit2-DR states are only used for navigating the state machine. As shown in the state diagram, the Run-Test/Idle state need not be entered between selecting JTAG instruction and using Data Registers. 34.4.10 Boundary-scan The boundary-scan chain has the capability of driving and observing the logic levels on the digital I/O pins, as well as the boundary between digital and analog logic for analog circuitry having off-chip connections. At system level, all ICs having JTAG capabilities are connected serially by the TDI/TDO signals to form a long shift register. An external controller sets up the devices to drive values at their output pins, and observe the input values received from other devices. The controller compares the received data with the expected result. In this way, boundary-scan provides a mechanism for testing interconnections and integrity of components on Printed Circuits Boards by using the 4 TAP signals only. The four IEEE 1149.1 defined mandatory JTAG instructions IDCODE, BYPASS, SAMPLE/PRELOAD, and EXTEST can be used for testing the Printed Circuit Board. Initial scanning of the data register path will show the ID-code of the device, since IDCODE is the default JTAG instruction. It may be desirable to have the 32-bit AVR device in reset during test mode. If not reset, inputs to the device may be determined by the scan operations, and the internal software may be in an undetermined state when exiting the test mode. If needed, the BYPASS instruction can be issued to make the shortest possible scan chain through the device. The device can be set in the reset state either by pulling the external RESETn pin low, or issuing the AVR_RESET instruction with appropriate setting of the Reset Data Register. The EXTEST instruction is used for sampling external pins and loading output pins with data. The data from the output latch will be driven out on the pins as soon as the EXTEST instruction is loaded into the JTAG IR-register. Therefore, the SAMPLE/PRELOAD should also be used for setting initial values to the scan ring, to avoid damaging the board when issuing the EXTEST instruction for the first time. SAMPLE/PRELOAD can also be used for taking a snapshot of the external pins during normal operation of the part. When using the JTAG Interface for boundary-scan, the JTAG TCK clock is independent of the internal chip clock. The internal chip clock is not required to run during boundary-scan operations. NOTE: For pins connected to 5V lines care should be taken to not drive the pins to a logic one using boundary-scan, as this will create a current flowing from the 3,3V driver to the 5V pull-up on the line. Optionally a series resistor can be added between the line and the pin to reduce the current. Details about the boundary-scan chain can be found in the BSDL file for the device. This can be found on the Atmel website. 34.4.11 Service Access Bus The AVR32 architecture offers a common interface for access to On-Chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), 861 32142D–06/2013 ATUC64/128/256L3/4U which is linked to the JTAG through a bus master module, which also handles synchronization between the TCK and SAB clocks. For more information about the SAB and a list of SAB slaves see the Service Access Bus chapter. 34.4.11.1 SAB Address Mode The MEMORY_SIZED_ACCESS instruction allows a sized read or write to any 36-bit address on the bus. MEMORY_WORD_ACCESS is a shorthand instruction for 32-bit accesses to any 36-bit address, while the NEXUS_ACCESS instruction is a Nexus-compliant shorthand instruction for accessing the 32-bit OCD registers in the 7-bit address space reserved for these. These instructions require two passes through the Shift-DR TAP state: one for the address and control information, and one for data. 34.4.11.2 Block Transfer To increase the transfer rate, consecutive memory accesses can be accomplished by the MEMORY_BLOCK_ACCESS instruction, which only requires a single pass through Shift-DR for data transfer only. The address is automatically incremented according to the size of the last SAB transfer. 34.4.11.3 Canceling a SAB Access It is possible to abort an ongoing SAB access by the CANCEL_ACCESS instruction, to avoid hanging the bus due to an extremely slow slave. 34.4.11.4 Busy Reporting As the time taken to perform an access may vary depending on system activity and current chip frequency, all the SAB access JTAG instructions can return a busy indicator. This indicates whether a delay needs to be inserted, or an operation needs to be repeated in order to be successful. If a new access is requested while the SAB is busy, the request is ignored. The SAB becomes busy when: • Entering Update-DR in the address phase of any read operation, e.g., after scanning in a NEXUS_ACCESS address with the read bit set. • Entering Update-DR in the data phase of any write operation, e.g., after scanning in data for a NEXUS_ACCESS write. • Entering Update-DR during a MEMORY_BLOCK_ACCESS. • Entering Update-DR after scanning in a counter value for SYNC. • Entering Update-IR after scanning in a MEMORY_BLOCK_ACCESS if the previous access was a read and data was scanned after scanning the address. The SAB becomes ready again when: • A read or write operation completes. • A SYNC countdown completed. • A operation is cancelled by the CANCEL_ACCESS instruction. What to do if the busy bit is set: • During Shift-IR: The new instruction is selected, but the previous operation has not yet completed and will continue (unless the new instruction is CANCEL_ACCESS). You may 862 32142D–06/2013 ATUC64/128/256L3/4U continue shifting the same instruction until the busy bit clears, or start shifting data. If shifting data, you must be prepared that the data shift may also report busy. • During Shift-DR of an address: The new address is ignored. The SAB stays in address mode, so no data must be shifted. Repeat the address until the busy bit clears. • During Shift-DR of read data: The read data is invalid. The SAB stays in data mode. Repeat scanning until the busy bit clears. • During Shift-DR of write data: The write data is ignored. The SAB stays in data mode. Repeat scanning until the busy bit clears. 34.4.11.5 Error Reporting The Service Access Bus may not be able to complete all accesses as requested. This may be because the address is invalid, the addressed area is read-only or cannot handle byte/halfword accesses, or because the chip is set in a protected mode where only limited accesses are allowed. The error bit is updated when an access completes, and is cleared when a new access starts. What to do if the error bit is set: • During Shift-IR: The new instruction is selected. The last operation performed using the old instruction did not complete successfully. • During Shift-DR of an address: The previous operation failed. The new address is accepted. If the read bit is set, a read operation is started. • During Shift-DR of read data: The read operation failed, and the read data is invalid. • During Shift-DR of write data: The previous write operation failed. The new data is accepted and a write operation started. This should only occur during block writes or stream writes. No error can occur between scanning a write address and the following write data. • While polling with CANCEL_ACCESS: The previous access was cancelled. It may or may not have actually completed. • After power-up: The error bit is set after power up, but there has been no previous SAB instruction so this error can be discarded. 34.4.11.6 Protected Reporting A protected status may be reported during Shift-IR or Shift-DR. This indicates that the security bit in the Flash Controller is set and that the chip is locked for access, according to Section 34.5.1. The protected state is reported when: • The Flash Controller is under reset. This can be due to the AVR_RESET command or the RESET_N line. • The Flash Controller has not read the security bit from the flash yet (This will take a a few ms). Happens after the Flash Controller reset has been released. • The security bit in the Flash Controller is set. What to do if the protected bit is set: • Release all active AVR_RESET domains, if any. • Release the RESET_N line. • Wait a few ms for the security bit to clear. It can be set temporarily due to a reset. 863 32142D–06/2013 ATUC64/128/256L3/4U • Perform a CHIP_ERASE to clear the security bit. NOTE: This will erase all the contents of the non-volatile memory. 34.5 JTAG Instruction Summary The implemented JTAG instructions in the 32-bit AVR are shown in the table below. 34.5.1 Security Restrictions When the security fuse in the Flash is programmed, the following JTAG instructions are restricted: • NEXUS_ACCESS • MEMORY_WORD_ACCESS • MEMORY_BLOCK_ACCESS • MEMORY_SIZED_ACCESS For description of what memory locations remain accessible, please refer to the SAB address map. Full access to these instructions is re-enabled when the security fuse is erased by the CHIP_ERASE JTAG instruction. Table 34-8. JTAG Instruction Summary Instruction OPCODE Instruction Description 0x01 IDCODE Select the 32-bit Device Identification register as data register. 0x02 SAMPLE_PRELOAD Take a snapshot of external pin values without affecting system operation. 0x03 EXTEST Select boundary-scan chain as data register for testing circuitry external to the device. 0x04 INTEST Select boundary-scan chain for internal testing of the device. 0x06 CLAMP Bypass device through Bypass register, while driving outputs from boundaryscan register. 0x0C AVR_RESET Apply or remove a static reset to the device 0x0F CHIP_ERASE Erase the device 0x10 NEXUS_ACCESS Select the SAB Address and Data registers as data register for the TAP. The registers are accessed in Nexus mode. 0x11 MEMORY_WORD_ACCESS Select the SAB Address and Data registers as data register for the TAP. 0x12 MEMORY_BLOCK_ACCESS Select the SAB Data register as data register for the TAP. The address is auto-incremented. 0x13 CANCEL_ACCESS Cancel an ongoing Nexus or Memory access. 0x14 MEMORY_SERVICE Select the SAB Address and Data registers as data register for the TAP. The registers are accessed in Memory Service mode. 0x15 MEMORY_SIZED_ACCESS Select the SAB Address and Data registers as data register for the TAP. 0x17 SYNC Synchronization counter 0x1C HALT Halt the CPU for safe programming. 0x1F BYPASS Bypass this device through the bypass register. Others N/A Acts as BYPASS 864 32142D–06/2013 ATUC64/128/256L3/4U Note that the security bit will read as programmed and block these instructions also if the Flash Controller is statically reset. Other security mechanisms can also restrict these functions. If such mechanisms are present they are listed in the SAB address map section. 34.5.1.1 Notation Table 34-10 on page 864 shows bit patterns to be shifted in a format like "peb01". Each character corresponds to one bit, and eight bits are grouped together for readability. The least significantbit is always shifted first, and the most significant bit shifted last. The symbols used are shown in Table 34-9. In many cases, it is not required to shift all bits through the data register. Bit patterns are shown using the full width of the shift register, but the suggested or required bits are emphasized using bold text. I.e. given the pattern "aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx", the shift register is 34 bits, but the test or debug unit may choose to shift only 8 bits "aaaaaaar". The following describes how to interpret the fields in the instruction description tables: Table 34-9. Symbol Description Symbol Description 0 Constant low value - always reads as zero. 1 Constant high value - always reads as one. a An address bit - always scanned with the least significant bit first b A busy bit. Reads as one if the SAB was busy, or zero if it was not. See Section 34.4.11.4 for details on how the busy reporting works. d A data bit - always scanned with the least significant bit first. e An error bit. Reads as one if an error occurred, or zero if not. See Section 34.4.11.5 for details on how the error reporting works. p The chip protected bit. Some devices may be set in a protected state where access to chip internals are severely restricted. See the documentation for the specific device for details. On devices without this possibility, this bit always reads as zero. r A direction bit. Set to one to request a read, set to zero to request a write. s A size bit. The size encoding is described where used. x A don’t care bit. Any value can be shifted in, and output data should be ignored. Table 34-10. Instruction Description Instruction Description IR input value Shows the bit pattern to shift into IR in the Shift-IR state in order to select this instruction. The pattern is show both in binary and in hexadecimal form for convenience. Example: 10000 (0x10) IR output value Shows the bit pattern shifted out of IR in the Shift-IR state when this instruction is active. Example: peb01 865 32142D–06/2013 ATUC64/128/256L3/4U 34.5.2 Public JTAG Instructions The JTAG standard defines a number of public JTAG instructions. These instructions are described in the sections below. 34.5.2.1 IDCODE This instruction selects the 32 bit Device Identification register (DID) as Data Register. The DID register consists of a version number, a device number, and the manufacturer code chosen by JEDEC. This is the default instruction after a JTAG reset. Details about the DID register can be found in the module configuration section at the end of this chapter. Starting in Run-Test/Idle, the Device Identification register is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: The IDCODE value is latched into the shift register. 7. In Shift-DR: The IDCODE scan chain is shifted by the TCK input. 8. Return to Run-Test/Idle. 34.5.2.2 SAMPLE_PRELOAD This instruction takes a snap-shot of the input/output pins without affecting the system operation, and pre-loading the scan chain without updating the DR-latch. The boundary-scan chain is selected as Data Register. Starting in Run-Test/Idle, the Device Identification register is accessed in the following way: DR Size Shows the number of bits in the data register chain when this instruction is active. Example: 34 bits DR input value Shows which bit pattern to shift into the data register in the Shift-DR state when this instruction is active. Multiple such lines may exist, e.g., to distinguish between reads and writes. Example: aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR output value Shows the bit pattern shifted out of the data register in the Shift-DR state when this instruction is active. Multiple such lines may exist, e.g., to distinguish between reads and writes. Example: xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-10. Instruction Description (Continued) Instruction Description Table 34-11. IDCODE Details Instructions Details IR input value 00001 (0x01) IR output value p0001 DR Size 32 DR input value xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx DR output value Device Identification Register 866 32142D–06/2013 ATUC64/128/256L3/4U 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: The Data on the external pins are sampled into the boundary-scan chain. 7. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 8. Return to Run-Test/Idle. 34.5.2.3 EXTEST This instruction selects the boundary-scan chain as Data Register for testing circuitry external to the 32-bit AVR package. The contents of the latched outputs of the boundary-scan chain is driven out as soon as the JTAG IR-register is loaded with the EXTEST instruction. Starting in Run-Test/Idle, the EXTEST instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the output pins. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: The data on the external pins is sampled into the boundary-scan chain. 8. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 9. In Update-DR: The data from the scan chain is applied to the output pins. 10. Return to Run-Test/Idle. Table 34-12. SAMPLE_PRELOAD Details Instructions Details IR input value 00010 (0x02) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. Table 34-13. EXTEST Details Instructions Details IR input value 00011 (0x03) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. 867 32142D–06/2013 ATUC64/128/256L3/4U 34.5.2.4 INTEST This instruction selects the boundary-scan chain as Data Register for testing internal logic in the device. The logic inputs are determined by the boundary-scan chain, and the logic outputs are captured by the boundary-scan chain. The device output pins are driven from the boundary-scan chain. Starting in Run-Test/Idle, the INTEST instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the internal logic inputs. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: The data on the internal logic is sampled into the boundary-scan chain. 8. In Shift-DR: The boundary-scan chain is shifted by the TCK input. 9. In Update-DR: The data from the boundary-scan chain is applied to internal logic inputs. 10. Return to Run-Test/Idle. 34.5.2.5 CLAMP This instruction selects the Bypass register as Data Register. The device output pins are driven from the boundary-scan chain. Starting in Run-Test/Idle, the CLAMP instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. In Update-IR: The data from the boundary-scan chain is applied to the output pins. 5. Return to Run-Test/Idle. 6. Select the DR Scan path. 7. In Capture-DR: A logic ‘0’ is loaded into the Bypass Register. 8. In Shift-DR: Data is scanned from TDI to TDO through the Bypass register. Table 34-14. INTEST Details Instructions Details IR input value 00100 (0x04) IR output value p0001 DR Size Depending on boundary-scan chain, see BSDL-file. DR input value Depending on boundary-scan chain, see BSDL-file. DR output value Depending on boundary-scan chain, see BSDL-file. 868 32142D–06/2013 ATUC64/128/256L3/4U 9. Return to Run-Test/Idle. 34.5.2.6 BYPASS This instruction selects the 1-bit Bypass Register as Data Register. Starting in Run-Test/Idle, the CLAMP instruction is accessed the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Capture-DR: A logic ‘0’ is loaded into the Bypass Register. 7. In Shift-DR: Data is scanned from TDI to TDO through the Bypass register. 8. Return to Run-Test/Idle. 34.5.3 Private JTAG Instructions The 32-bit AVR defines a number of private JTAG instructions, not defined by the JTAG standard. Each instruction is briefly described in text, with details following in table form. 34.5.3.1 NEXUS_ACCESS This instruction allows Nexus-compliant access to the On-Chip Debug registers through the SAB. The 7-bit register index, a read/write control bit, and the 32-bit data is accessed through the JTAG port. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the NEXUS_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. NOTE: The polarity of the direction bit is inverse of the Nexus standard. Table 34-15. CLAMP Details Instructions Details IR input value 00110 (0x06) IR output value p0001 DR Size 1 DR input value x DR output value x Table 34-16. BYPASS Details Instructions Details IR input value 11111 (0x1F) IR output value p0001 DR Size 1 DR input value x DR output value x 869 32142D–06/2013 ATUC64/128/256L3/4U Starting in Run-Test/Idle, OCD registers are accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 7-bit address for the OCD register. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed register. For a write operation, scan in the new contents of the register. 9. Return to Run-Test/Idle. For any operation, the full 7 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. 34.5.3.2 MEMORY_SERVICE This instruction allows access to registers in an optional Memory Service Unit. The 7-bit register index, a read/write control bit, and the 32-bit data is accessed through the JTAG port. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_SERVICE instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Starting in Run-Test/Idle, Memory Service registers are accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 7-bit address for the Memory Service register. Table 34-17. NEXUS_ACCESS Details Instructions Details IR input value 10000 (0x10) IR output value peb01 DR Size 34 bits DR input value (Address phase) aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Address phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb 870 32142D–06/2013 ATUC64/128/256L3/4U 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed register. For a write operation, scan in the new contents of the register. 9. Return to Run-Test/Idle. For any operation, the full 7 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. 34.5.3.3 MEMORY_SIZED_ACCESS This instruction allows access to the entire Service Access Bus data area. Data is accessed through a 36-bit byte index, a 2-bit size, a direction bit, and 8, 16, or 32 bits of data. Not all units mapped on the SAB bus may support all sizes of accesses, e.g., some may only support word accesses. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_SIZED_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Table 34-18. MEMORY_SERVICE Details Instructions Details IR input value 10100 (0x14) IR output value peb01 DR Size 34 bits DR input value (Address phase) aaaaaaar xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Address phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb 871 32142D–06/2013 ATUC64/128/256L3/4U The size field is encoded as i Table 34-19. Starting in Run-Test/Idle, SAB data is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write), 2-bit access size, and the 36-bit address of the data to access. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed area. For a write operation, scan in the new contents of the area. 9. Return to Run-Test/Idle. For any operation, the full 36 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. Table 34-19. Size Field Semantics Size field value Access size Data alignment 00 Byte (8 bits) Address modulo 4 : data alignment 0: dddddddd xxxxxxxx xxxxxxxx xxxxxxxx 1: xxxxxxxx dddddddd xxxxxxxx xxxxxxxx 2: xxxxxxxx xxxxxxxx dddddddd xxxxxxxx 3: xxxxxxxx xxxxxxxx xxxxxxxx dddddddd 01 Halfword (16 bits) Address modulo 4 : data alignment 0: dddddddd dddddddd xxxxxxxx xxxxxxxx 1: Not allowed 2: xxxxxxxx xxxxxxxx dddddddd dddddddd 3: Not allowed 10 Word (32 bits) Address modulo 4 : data alignment 0: dddddddd dddddddd dddddddd dddddddd 1: Not allowed 2: Not allowed 3: Not allowed 11 Reserved N/A Table 34-20. MEMORY_SIZED_ACCESS Details Instructions Details IR input value 10101 (0x15) IR output value peb01 DR Size 39 bits DR input value (Address phase) aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa aaaassr DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xxxxxxx 872 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.4 MEMORY_WORD_ACCESS This instruction allows access to the entire Service Access Bus data area. Data is accessed through the 34 MSB of the SAB address, a direction bit, and 32 bits of data. This instruction is identical to MEMORY_SIZED_ACCESS except that it always does word sized accesses. The size field is implied, and the two lowest address bits are removed and not scanned in. Note: This instruction was previously known as MEMORY_ACCESS, and is provided for backwards compatibility. The data register is alternately interpreted by the SAB as an address register and a data register. The SAB starts in address mode after the MEMORY_WORD_ACCESS instruction is selected, and toggles between address and data mode each time a data scan completes with the busy bit cleared. Starting in Run-Test/Idle, SAB data is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the direction bit (1=read, 0=write) and the 34-bit address of the data to access. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: For a read operation, scan out the contents of the addressed area. For a write operation, scan in the new contents of the area. 9. Return to Run-Test/Idle. For any operation, the full 34 bits of the address must be provided. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. DR output value (Address phase) xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb DR output value (Data read phase) xxxxxeb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-20. MEMORY_SIZED_ACCESS Details (Continued) Instructions Details Table 34-21. MEMORY_WORD_ACCESS Details Instructions Details IR input value 10001 (0x11) IR output value peb01 DR Size 35 bits DR input value (Address phase) aaaaaaaa aaaaaaaa aaaaaaaa aaaaaaaa aar DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxx DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xxx 873 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.5 MEMORY_BLOCK_ACCESS This instruction allows access to the entire SAB data area. Up to 32 bits of data is accessed at a time, while the address is sequentially incremented from the previously used address. In this mode, the SAB address, size, and access direction is not provided with each access. Instead, the previous address is auto-incremented depending on the specified size and the previous operation repeated. The address must be set up in advance with MEMORY_SIZE_ACCESS or MEMORY_WORD_ACCESS. It is allowed, but not required, to shift data after shifting the address. This instruction is primarily intended to speed up large quantities of sequential word accesses. It is possible to use it also for byte and halfword accesses, but the overhead in this is case much larger as 32 bits must still be shifted for each access. The following sequence should be used: 1. Use the MEMORY_SIZE_ACCESS or MEMORY_WORD_ACCESS to read or write the first location. 2. Return to Run-Test/Idle. 3. Select the IR Scan path. 4. In Capture-IR: The IR output value is latched into the shift register. 5. In Shift-IR: The instruction register is shifted by the TCK input. 6. Return to Run-Test/Idle. 7. Select the DR Scan path. The address will now have incremented by 1, 2, or 4 (corresponding to the next byte, halfword, or word location). 8. In Shift-DR: For a read operation, scan out the contents of the next addressed location. For a write operation, scan in the new contents of the next addressed location. 9. Go to Update-DR. 10. If the block access is not complete, return to Select-DR Scan and repeat the access. 11. If the block access is complete, return to Run-Test/Idle. For write operations, 32 data bits must be provided, or the result will be undefined. For read operations, shifting may be terminated once the required number of bits have been acquired. DR output value (Address phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xeb DR output value (Data read phase) xeb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-21. MEMORY_WORD_ACCESS Details (Continued) Instructions Details Table 34-22. MEMORY_BLOCK_ACCESS Details Instructions Details IR input value 10010 (0x12) IR output value peb01 DR Size 34 bits DR input value (Data read phase) xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xx 874 32142D–06/2013 ATUC64/128/256L3/4U The overhead using block word access is 4 cycles per 32 bits of data, resulting in an 88% transfer efficiency, or 2.1 MBytes per second with a 20 MHz TCK frequency. 34.5.3.6 CANCEL_ACCESS If a very slow memory location is accessed during a SAB memory access, it could take a very long time until the busy bit is cleared, and the SAB becomes ready for the next operation. The CANCEL_ACCESS instruction provides a possibility to abort an ongoing transfer and report a timeout to the JTAG master. When the CANCEL_ACCESS instruction is selected, the current access will be terminated as soon as possible. There are no guarantees about how long this will take, as the hardware may not always be able to cancel the access immediately. The SAB is ready to respond to a new command when the busy bit clears. Starting in Run-Test/Idle, CANCEL_ACCESS is accessed in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 34.5.3.7 SYNC This instruction allows external debuggers and testers to measure the ratio between the external JTAG clock and the internal system clock. The SYNC data register is a 16-bit counter that counts down to zero using the internal system clock. The busy bit stays high until the counter reaches zero. Starting in Run-Test/Idle, SYNC instruction is used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. DR input value (Data write phase) dddddddd dddddddd dddddddd dddddddd xx DR output value (Data read phase) eb dddddddd dddddddd dddddddd dddddddd DR output value (Data write phase) xx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxeb Table 34-22. MEMORY_BLOCK_ACCESS Details (Continued) Instructions Details Table 34-23. CANCEL_ACCESS Details Instructions Details IR input value 10011 (0x13) IR output value peb01 DR Size 1 DR input value x DR output value 0 875 32142D–06/2013 ATUC64/128/256L3/4U 6. Scan in an 16-bit counter value. 7. Go to Update-DR and re-enter Select-DR Scan. 8. In Shift-DR: Scan out the busy bit, and until the busy bit clears goto 7. 9. Calculate an approximation to the internal clock speed using the elapsed time and the counter value. 10. Return to Run-Test/Idle. The full 16-bit counter value must be provided when starting the synch operation, or the result will be undefined. When reading status, shifting may be terminated once the required number of bits have been acquired. 34.5.3.8 AVR_RESET This instruction allows a debugger or tester to directly control separate reset domains inside the chip. The shift register contains one bit for each controllable reset domain. Setting a bit to one resets that domain and holds it in reset. Setting a bit to zero releases the reset for that domain. The AVR_RESET instruction can be used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. 6. In Shift-DR: Scan in the value corresponding to the reset domains the JTAG master wants to reset into the data register. 7. Return to Run-Test/Idle. 8. Stay in run test idle for at least 10 TCK clock cycles to let the reset propagate to the system. See the device specific documentation for the number of reset domains, and what these domains are. For any operation, all bits must be provided or the result will be undefined. Table 34-24. SYNC_ACCESS Details Instructions Details IR input value 10111 (0x17) IR output value peb01 DR Size 16 bits DR input value dddddddd dddddddd DR output value xxxxxxxx xxxxxxeb Table 34-25. AVR_RESET Details Instructions Details IR input value 01100 (0x0C) IR output value p0001 876 32142D–06/2013 ATUC64/128/256L3/4U 34.5.3.9 CHIP_ERASE This instruction allows a programmer to completely erase all nonvolatile memories in a chip. This will also clear any security bits that are set, so the device can be accessed normally. In devices without non-volatile memories this instruction does nothing, and appears to complete immediately. The erasing of non-volatile memories starts as soon as the CHIP_ERASE instruction is selected. The CHIP_ERASE instruction selects a 1 bit bypass data register. A chip erase operation should be performed as: 1. Reset the system and stop the CPU from executing. 2. Select the IR Scan path. 3. In Capture-IR: The IR output value is latched into the shift register. 4. In Shift-IR: The instruction register is shifted by the TCK input. 5. Check the busy bit that was scanned out during Shift-IR. If the busy bit was set goto 2. 6. Return to Run-Test/Idle. 34.5.3.10 HALT This instruction allows a programmer to easily stop the CPU to ensure that it does not execute invalid code during programming. This instruction selects a 1-bit halt register. Setting this bit to one halts the CPU. Setting this bit to zero releases the CPU to run normally. The value shifted out from the data register is one if the CPU is halted. Before releasing the halt command the CPU needs to be reset to ensure that it will start at the reset startup address. The HALT instruction can be used in the following way: 1. Select the IR Scan path. 2. In Capture-IR: The IR output value is latched into the shift register. 3. In Shift-IR: The instruction register is shifted by the TCK input. 4. Return to Run-Test/Idle. 5. Select the DR Scan path. DR Size Device specific. DR input value Device specific. DR output value Device specific. Table 34-25. AVR_RESET Details (Continued) Instructions Details Table 34-26. CHIP_ERASE Details Instructions Details IR input value 01111 (0x0F) IR output value p0b01 Where b is the busy bit. DR Size 1 bit DR input value x DR output value 0 877 32142D–06/2013 ATUC64/128/256L3/4U 6. In Shift-DR: Scan in the value 1 to halt the CPU, 0 to start CPU execution. 7. Return to Run-Test/Idle. Table 34-27. HALT Details Instructions Details IR input value 11100 (0x1C) IR output value p0001 DR Size 1 bit DR input value d DR output value d 878 32142D–06/2013 ATUC64/128/256L3/4U 34.5.4 JTAG Data Registers The following device specific registers can be selected as JTAG scan chain depending on the instruction loaded in the JTAG Instruction Register. Additional registers exist, but are implicitly described in the functional description of the relevant instructions. 34.5.4.1 Device Identification Register The Device Identification Register contains a unique identifier for each product. The register is selected by the IDCODE instruction, which is the default instruction after a JTAG reset. Device specific ID codes The different device configurations have different JTAG ID codes, as shown in Table 34-28. Note that if the flash controller is statically reset, the ID code will be undefined. 34.5.4.2 Reset Register The reset register is selected by the AVR_RESET instruction and contains one bit for each reset domain in the device. Setting each bit to one will keep that domain reset until the bit is cleared. MSB LSB Bit 31 28 27 12 11 1 0 Device ID Revision Part Number Manufacturer ID 1 4 bits 16 bits 11 bits 1 bit Revision This is a 4 bit number identifying the revision of the component. Rev A = 0x0, B = 0x1, etc. Part Number The part number is a 16 bit code identifying the component. Manufacturer ID The Manufacturer ID is a 11 bit code identifying the manufacturer. The JTAG manufacturer ID for ATMEL is 0x01F. Table 34-28. Device and JTAG ID Device Name JTAG ID Code (R is the revision number) ATUC256L3U 0xr21C303F ATUC128L3U 0xr21C403F ATUC64L3U 0xr21C503F ATUC256L4U 0xr21C603F ATUC128L4U 0xr21C703F ATUC64L4U 0xr21C803F Bit 0 Reset domain System 879 32142D–06/2013 ATUC64/128/256L3/4U 34.5.4.3 Boundary--scan Chain The boundary-scan chain has the capability of driving and observing the logic levels on the digital I/O pins, as well as driving and observing the logic levels between the digital I/O pins and the internal logic. Typically, output value, output enable, and input data are all available in the boundary-scan chain. The boundary-scan chain is described in the BSDL (Boundary Scan Description Language) file available at the Atmel web site. System Resets the whole chip, except the JTAG itself. 880 32142D–06/2013 ATUC64/128/256L3/4U 34.6 aWire Debug Interface (AW) Rev.: 2.3.0.1 34.6.1 Features • Single pin debug system. • Half Duplex asynchronous communication (UART compatible). • Full duplex mode for direct UART connection. • Compatible with JTAG functionality, except boundary scan. • Failsafe packet-oriented protocol. • Read and write on-chip memory and program on-chip flash and fuses through SAB interface. • On-Chip Debug access through SAB interface. • Asynchronous receiver or transmitter when the aWire system is not used for debugging. 34.6.2 Overview The aWire Debug Interface (AW) offers a single pin debug solution that is fully compatible with the functionality offered by the JTAG interface, except boundary scan. This functionality includes memory access, programming capabilities, and On-Chip Debug access. Figure 34-8 on page 881 shows how the AW is connected in a 32-bit AVR device. The RESET_N pin is used both as reset and debug pin. A special sequence on RESET_N is needed to block the normal reset functionality and enable the AW. The Service Access Bus (SAB) interface contains address and data registers for the Service Access Bus, which gives access to On-Chip Debug, programming, and other functions in the device. The SAB offers several modes of access to the address and data registers, as discussed in Section 34.6.6.8. Section 34.6.7 lists the supported aWire commands and responses, with references to the description in this document. If the AW is not used for debugging, the aWire UART can be used by the user to send or receive data with one stop bit, eight data bits, no parity bits, and one stop bit. This can be controlled through the aWire user interface. 881 32142D–06/2013 ATUC64/128/256L3/4U 34.6.3 Block Diagram Figure 34-8. aWire Debug Interface Block Diagram 34.6.4 I/O Lines Description 34.6.5 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Table 34-29. I/O Lines Description Name Description Type DATA aWire data multiplexed with the RESET_N pin. Input/Output DATAOUT aWire data output in 2-pin mode. Output UART Reset filter External reset AW_ENABLE RESET_N Baudrate Detector RW SZ ADDR DATA CRC AW CONTROL AW User Interface SAB interface RESET command Power Manager HALT command CPU Flash Controller CHIP_ERASE command aWire Debug Interface PB SAB 882 32142D–06/2013 ATUC64/128/256L3/4U 34.6.5.1 I/O Lines The pin used by AW is multiplexed with the RESET_N pin. The reset functionality is the default function of this pin. To enable the aWire functionality on the RESET_N pin the user must enable the AW either by sending the enable sequence over the RESET_N pin from an external aWire master or by enabling the aWire user interface. In 2-pin mode data is received on the RESET_N line, but transmitted on the DATAOUT line. After sending the 2_PIN_MODE command the DATAOUT line is automatically enabled. All other peripheral functions on this pin is disabled. 34.6.5.2 Power Management When debugging through AW the system clocks are automatically turned on to allow debugging in sleep modes. 34.6.5.3 Clocks The aWire UART uses the internal 120 MHz RC oscillator (RC120M) as clock source for its operation. When enabling the AW the RC120M is automatically started. 34.6.5.4 External Components The AW needs an external pullup on the RESET_N pin to ensure that the pin is pulled up when the bus is not driven. 34.6.6 Functional Description 34.6.6.1 aWire Communication Protocol The AW is accessed through the RESET_N pin shown in Table 34-29 on page 881. The AW communicates through a UART operating at variable baud rate (depending on a sync pattern) with one start bit, 8 data bits (LSB first), one stop bit, and no parity bits. The aWire protocol is based upon command packets from an externalmaster and response packets from the slave (AW). The master always initiates communication and decides the baud rate. The packet contains a sync byte (0x55), a command/response byte, two length bytes (optional), a number of data bytes as defined in the length field (optional), and two CRC bytes. If the command/response has the most significant bit set, the command/response also carries the optional length and data fields. The CRC field is not checked if the CRC value transmitted is 0x0000. Table 34-30. aWire Packet Format Field Number of bytes Description Comment Optional SYNC 1 Sync pattern (0x55). Used by the receiver to set the baud rate clock. No COMMAND/ RESPONSE 1 Command from the master or response from the slave. When the most significant bit is set the command/response has a length field. A response has the next most significant bit set. A command does not have this bit set. No 883 32142D–06/2013 ATUC64/128/256L3/4U CRC calculation The CRC is calculated from the command/response, length, and data fields. The polynomial used is the FCS16 (or CRC-16-CCIT) in reverse mode (0x8408) and the starting value is 0x0000. Example command Below is an example command from the master with additional data. Figure 34-9. Example Command Example response Below is an example response from the slave with additional data. Figure 34-10. Example Response LENGTH 2 The number of bytes in the DATA field. Yes DATA LENGTH Data according to command/ response. Yes CRC 2 CRC calculated with the FCS16 polynomial. CRC value of 0x0000 makes the aWire disregard the CRC if the master does not support it. No Table 34-30. aWire Packet Format Field Number of bytes Description Comment Optional baud_rate_clk data_pin ... field sync(0x55) command(0x81) length(MSB) length(lsb) ... data(MSB) data(LSB) CRC(MSB) CRC(lsb) baud_rate_clk data_pin ... field sync(0x55) response(0xC1) length(MSB) length(lsb) ... data(MSB) data(LSB) CRC(MSB) CRC(lsb) 884 32142D–06/2013 ATUC64/128/256L3/4U Avoiding drive contention when changing direction The aWire debug protocol uses one dataline in both directions. To avoid both the master and the slave to drive this line when changing direction the AW has a built in guard time before it starts to drive the line. At reset this guard time is set to maximum (128 bit cycles), but can be lowered by the master upon command. The AW will release the line immediately after the stop character has been transmitted. During the direction change there can be a period when the line is not driven. An external pullup has to be added to RESET_N to keep the signal stable when neither master or slave is actively driving the line. 34.6.6.2 The RESET_N pin Normal reset functionality on the RESET_N pin is disabled when using aWire. However, the user can reset the system through the RESET aWire command. During aWire operation the RESET_N pin should not be connected to an external reset circuitry, but disconnected via a switch or a jumper to avoid drive contention and speed problems. Figure 34-11. Reset Circuitry and aWire. 34.6.6.3 Initializing the AW To enable AW, the user has to send a 0x55 pattern with a baudrate of 1 kHz on the RESET_N pin. The AW is enabled after transmitting this pattern and the user can start transmitting commands. This pattern is not the sync pattern for the first command. After enabling the aWire debug interface the halt bit is set automatically to prevent the system from running code after the interface is enabled. To make the CPU run again set halt to zero using the HALT command. 34.6.6.4 Disabling the AW To disable AW, the user can keep the RESET_N pin low for 100 ms. This will disable the AW, return RESET_N to its normal function, and reset the device. An aWire master can also disable aWire by sending the DISABLE command. After acking the command the AW will be disabled and RESET_N returns to its normal function. RESET_N AW Debug Interface Jumper MCU Power Manager aWire master connector Board Reset Circuitry 885 32142D–06/2013 ATUC64/128/256L3/4U 34.6.6.5 Resetting the AW The aWire master can reset the AW slave by pulling the RESET_N pin low for 20 ms. This is equivalent to disabling and then enabling AW. 34.6.6.6 2-pin Mode To avoid using special hardware when using a normal UART device as aWire master, the aWire slave has a 2-pin mode where one pin is used as input and on pin is used as output. To enable this mode the 2_PIN_MODE command must be sent. After sending the command, all responses will be sent on the DATAOUT pin instead of the RESET_N pin. Commands are still received on the RESET_N pin. 34.6.6.7 Baud Rate Clock The communication speed is set by the master in the sync field of the command. The AW will use this to resynchronize its baud rate clock and reply on this frequency. The minimum frequency of the communication is 1 kHz. The maximum frequency depends on the internal clock source for the AW (RC120M). The baud rate clock is generated by AW with the following formula: Where is the baud rate frequency and is the frequency of the internal RC120M. TUNE is the value returned by the BAUD_RATE response. To find the max frequency the user can issue the TUNE command to the AW to make it return the TUNE value. This value can be used to compute the . The maximum operational frequency ( ) is then: 34.6.6.8 Service Access Bus The AVR32 architecture offers a common interface for access to On-Chip Debug, programming, and test functions. These are mapped on a common bus called the Service Access Bus (SAB), which is linked to the aWire through a bus master module, which also handles synchronization between the aWire and SAB clocks. For more information about the SAB and a list of SAB slaves see the Service Access Bus chapter. SAB Clock When accessing the SAB through the aWire there are no limitations on baud rate frequency compared to chip frequency, although there must be an active system clock in order for the SAB accesses to complete. If the system clock (CLK_SYS) is switched off in sleep mode, activity on the aWire pin will restart the CLK_SYS automatically, without waking the device from sleep. aWire masters may optimize the transfer rate by adjusting the baud rate frequency in relation to the CLK_SYS. This ratio can be measured with the MEMORY_SPEED_REQUEST command. When issuing the MEMORY_SPEED_REQUEST command a counter value CV is returned. CV can be used to calculate the SAB speed ( ) using this formula: f aw TUNE f  br 8 = ---------------------------- f br f aw f aw f brmax f brmax f aw 4 = ------- f sab 886 32142D–06/2013 ATUC64/128/256L3/4U SAB Address Mode The Service Access Bus uses 36 address bits to address memory or registers in any of the slaves on the bus. The bus supports sized accesses of bytes (8 bits), halfwords (16 bits), or words (32 bits). All accesses must be aligned to the size of the access, i.e. halfword accesses must have the lowest address bit cleared, and word accesses must have the two lowest address bits cleared. Two instructions exist to access the SAB: MEMORY_WRITE and MEMORY_READ. These two instructions write and read words, halfwords, and bytes from the SAB. Busy Reporting If the aWire master, during a MEMORY_WRITE or a MEMORY_READ command, transmit another byte when the aWire is still busy sending the previous byte to the SAB, the AW will respond with a MEMORY_READ_WRITE_STATUS error. See chapter Section 34.6.8.5 for more details. The aWire master should adjust its baudrate or delay between bytes when doing SAB accesses to ensure that the SAB is not overwhelmed with data. Error Reporting If a write is performed on a non-existing memory location the SAB interface will respond with an error. If this happens, all further writes in this command will not be performed and the error and number of bytes written is reported in the MEMORY_READWRITE_STATUS message from the AW after the write. If a read is performed on a non-existing memory location, the SAB interface will respond with an error. If this happens, the data bytes read after this event are not valid. The AW will include three extra bytes at the end of the transfer to indicate if the transfer was successful, or in the case of an error, how many valid bytes were received. 34.6.6.9 CRC Errors/NACK Response The AW will calculate a CRC value when receiving the command, length, and data fields of the command packets. If this value differs from the value from the CRC field of the packet, the AW will reply with a NACK response. Otherwise the command is carried out normally. An unknown command will be replied with a NACK response. In worst case a transmission error can happen in the length or command field of the packet. This can lead to the aWire slave trying to receive a command with or without length (opposite of what the master intended) or receive an incorrect number of bytes. The aWire slave will then either wait for more data when the master has finished or already have transmitted the NACK response in congestion with the master. The master can implement a timeout on every command and reset the slave if no response is returned after the timeout period has ended. f sab 3f aw CV – 3 = ---------------- 887 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7 aWire Command Summary The implemented aWire commands are shown in the table below. The responses from the AW are listed in Section 34.6.8. All aWire commands are described below, with a summary in table form. 34.6.7.1 AYA This command asks the AW: “Are you alive”, where the AW should respond with an acknowledge. Table 34-31. aWire Command Summary COMMAND Instruction Description 0x01 AYA “Are you alive”. 0x02 JTAG_ID Asks AW to return the JTAG IDCODE. 0x03 STATUS_REQUEST Request a status message from the AW. 0x04 TUNE Tell the AW to report the current baud rate. 0x05 MEMORY_SPEED_REQUEST Reports the speed difference between the aWire control and the SAB clock domains. 0x06 CHIP_ERASE Erases the flash and all volatile memories. 0x07 DISABLE Disables the AW. 0x08 2_PIN_MODE Enables the DATAOUT pin and puts the aWire in 2-pin mode, where all responses are sent on the DATAOUT pin. 0x80 MEMORY_WRITE Writes words, halfwords, or bytes to the SAB. 0x81 MEMORY_READ Reads words, halfwords, or bytes from the SAB. 0x82 HALT Issues a halt command to the device. 0x83 RESET Issues a reset to the Reset Controller. 0x84 SET_GUARD_TIME Sets the guard time for the AW. Table 34-32. Command/Response Description Notation Command/Response Description Command/Response value Shows the command/response value to put into the command/response field of the packet. Additional data Shows the format of the optional data field if applicable. Possible responses Shows the possible responses for this command. Table 34-33. AYA Details Command Details Command value 0x01 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 888 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7.2 JTAG_ID This command instructs the AW to output the JTAG idcode in the following response. 34.6.7.3 STATUS_REQUEST Asks the AW for a status message. 34.6.7.4 TUNE Asks the AW for the current baud rate counter value. 34.6.7.5 MEMORY_SPEED_REQUEST Asks the AW for the relative speed between the aWire clock (RC120M) and the SAB interface. 34.6.7.6 CHIP_ERASE This instruction allows a programmer to completely erase all nonvolatile memories in the chip. This will also clear any security bits that are set, so the device can be accessed normally. The command is acked immediately, but the status of the command can be monitored by checking Table 34-34. JTAG_ID Details Command Details Command value 0x02 Additional data N/A Possible responses 0xC0: IDCODE (Section 34.6.8.3) 0x41: NACK (Section 34.6.8.2) Table 34-35. STATUS_REQUEST Details Command Details Command value 0x03 Additional data N/A Possible responses 0xC4: STATUS_INFO (Section 34.6.8.7) 0x41: NACK (Section 34.6.8.2) Table 34-36. TUNE Details Command Details Command value 0x04 Additional data N/A Possible responses 0xC3: BAUD_RATE (Section 34.6.8.6) 0x41: NACK (Section 34.6.8.2) Table 34-37. MEMORY_SPEED_REQUEST Details Command Details Command value 0x05 Additional data N/A Possible responses 0xC5: MEMORY_SPEED (Section 34.6.8.8) 0x41: NACK (Section 34.6.8.2) 889 32142D–06/2013 ATUC64/128/256L3/4U the Chip Erase ongoing bit in the status bytes received after the STATUS_REQUEST command. 34.6.7.7 DISABLE Disables the AW. The AW will respond with an ACK response and then disable itself. 34.6.7.8 2_PIN_MODE Enables the DATAOUT pin as an output pin. All responses sent from the aWire slave will be sent on this pin, instead of the RESET_N pin, starting with the ACK for the 2_PIN_MODE command. 34.6.7.9 MEMORY_WRITE This command enables programming of memory/writing to registers on the SAB. The MEMORY_WRITE command allows words, halfwords, and bytes to be programmed to a continuous sequence of addresses in one operation. Before transferring the data, the user must supply: 1. The number of data bytes to write + 5 (size and starting address) in the length field. 2. The size of the transfer: words, halfwords, or bytes. 3. The starting address of the transfer. Table 34-38. CHIP_ERASE Details Command Details Command value 0x06 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-39. DISABLE Details Command Details Command value 0x07 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-40. DISABLE Details Command Details Command value 0x07 Additional data N/A Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 890 32142D–06/2013 ATUC64/128/256L3/4U The 4 MSB of the 36 bit SAB address are submitted together with the size field (2 bits). Then follows the 4 remaining address bytes and finally the data bytes. The size of the transfer is specified using the values from the following table: Below is an example write command: 1. 0x55 (sync) 2. 0x80 (command) 3. 0x00 (length MSB) 4. 0x09 (length LSB) 5. 0x25 (size and address MSB, the two MSB of this byte are unused and set to zero) 6. 0x00 7. 0x00 8. 0x00 9. 0x04 (address LSB) 10. 0xCA 11. 0xFE 12. 0xBA 13. 0xBE 14. 0xXX (CRC MSB) 15. 0xXX (CRC LSB) The length field is set to 0x0009 because there are 9 bytes of additional data: 5 address and size bytes and 4 bytes of data. The address and size field indicates that words should be written to address 0x500000004. The data written to 0x500000004 is 0xCAFEBABE. 34.6.7.10 MEMORY_READ This command enables reading of memory/registers on the Service Access Bus (SAB). The MEMORY_READ command allows words, halfwords, and bytes to be read from a continuous sequence of addresses in one operation. The user must supply: Table 34-41. Size Field Decoding Size field Description 00 Byte transfer 01 Halfword transfer 10 Word transfer 11 Reserved Table 34-42. MEMORY_WRITE Details Command Details Command value 0x80 Additional data Size, Address and Data Possible responses 0xC2: MEMORY_READWRITE_STATUS (Section 34.6.8.5) 0x41: NACK (Section 34.6.8.2) 891 32142D–06/2013 ATUC64/128/256L3/4U 1. The size of the data field: 7 (size and starting address + read length indicator) in the length field. 2. The size of the transfer: Words, halfwords, or bytes. 3. The starting address of the transfer. 4. The number of bytes to read (max 65532). The 4 MSB of the 36 bit SAB address are submitted together with the size field (2 bits). The 4 remaining address bytes are submitted before the number of bytes to read. The size of the transfer is specified using the values from the following table: Below is an example read command: 1. 0x55 (sync) 2. 0x81 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0x25 (size and address MSB, the two MSB of this byte are unused and set to zero) 6. 0x00 7. 0x00 8. 0x00 9. 0x04 (address LSB) 10. 0x00 11. 0x04 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The length field is set to 0x0007 because there are 7 bytes of additional data: 5 bytes of address and size and 2 bytes with the number of bytes to read. The address and size field indicates one word (four bytes) should be read from address 0x500000004. Table 34-43. Size Field Decoding Size field Description 00 Byte transfer 01 Halfword transfer 10 Word transfer 11 Reserved Table 34-44. MEMORY_READ Details Command Details Command value 0x81 Additional data Size, Address and Length Possible responses 0xC1: MEMDATA (Section 34.6.8.4) 0xC2: MEMORY_READWRITE_STATUS (Section 34.6.8.5) 0x41: NACK (Section 34.6.8.2) 892 32142D–06/2013 ATUC64/128/256L3/4U 34.6.7.11 HALT This command tells the CPU to halt code execution for safe programming. If the CPU is not halted during programming it can start executing partially loaded programs. To halt the processor, the aWire master should send 0x01 in the data field of the command. After programming the halting can be released by sending 0x00 in the data field of the command. 34.6.7.12 RESET This command resets different domains in the part. The aWire master sends a byte with the reset value. Each bit in the reset value byte corresponds to a reset domain in the chip. If a bit is set the reset is activated and if a bit is not set the reset is released. The number of reset domains and their destinations are identical to the resets described in the JTAG data registers chapter under reset register. 34.6.7.13 SET_GUARD_TIME Sets the guard time value in the AW, i.e. how long the AW will wait before starting its transfer after the master has finished. The guard time can be either 0x00 (128 bit lengths), 0x01 (16 bit lengths), 0x2 (4 bit lengths) or 0x3 (1 bit length). Table 34-45. HALT Details Command Details Command value 0x82 Additional data 0x01 to halt the CPU 0x00 to release the halt and reset the device. Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-46. RESET Details Command Details Command value 0x83 Additional data Reset value for each reset domain. The number of reset domains is part specific. Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) Table 34-47. SET_GUARD_TIME Details Command Details Command value 0x84 Additional data Guard time Possible responses 0x40: ACK (Section 34.6.8.1) 0x41: NACK (Section 34.6.8.2) 893 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8 aWire Response Summary The implemented aWire responses are shown in the table below. 34.6.8.1 ACK The AW has received the command successfully and performed the operation. 34.6.8.2 NACK The AW has received the command, but got a CRC mismatch. 34.6.8.3 IDCODE The JTAG idcode for this device. 34.6.8.4 MEMDATA The data read from the address specified by the MEMORY_READ command. The last 3 bytes are status bytes from the read. The first status byte is the status of the command described in the table below. The last 2 bytes are the number of remaining data bytes to be sent in the data field of the packet when the error occurred. If the read was not successful all data bytes after the failure are undefined. A successful word read (4 bytes) will look like this: Table 34-48. aWire Response Summary RESPONSE Instruction Description 0x40 ACK Acknowledge. 0x41 NACK Not acknowledge. Sent after CRC errors and after unknown commands. 0xC0 IDCODE The JTAG idcode. 0xC1 MEMDATA Values read from memory. 0xC2 MEMORY_READWRITE_STATUS Status after a MEMORY_WRITE or a MEMORY_READ command. OK, busy, error. 0xC3 BAUD_RATE The current baudrate. 0xC4 STATUS_INFO Status information. 0xC5 MEMORY_SPEED SAB to aWire speed information. Table 34-49. ACK Details Response Details Response value 0x40 Additional data N/A Table 34-50. NACK Details Response Details Response value 0x41 Additional data N/A Table 34-51. IDCODE Details Response Details Response value 0xC0 Additional data JTAG idcode 894 32142D–06/2013 ATUC64/128/256L3/4U 1. 0x55 (sync) 2. 0xC1 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0xCA (Data MSB) 6. 0xFE 7. 0xBA 8. 0xBE (Data LSB) 9. 0x00 (Status byte) 10. 0x00 (Bytes remaining MSB) 11. 0x00 (Bytes remaining LSB) 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The status is 0x00 and all data read are valid. An unsuccessful four byte read can look like this: 1. 0x55 (sync) 2. 0xC1 (command) 3. 0x00 (length MSB) 4. 0x07 (length LSB) 5. 0xCA (Data MSB) 6. 0xFE 7. 0xXX (An error has occurred. Data read is undefined. 5 bytes remaining of the Data field) 8. 0xXX (More undefined data) 9. 0x02 (Status byte) 10. 0x00 (Bytes remaining MSB) 11. 0x05 (Bytes remaining LSB) 12. 0xXX (CRC MSB) 13. 0xXX (CRC LSB) The error occurred after reading 2 bytes on the SAB. The rest of the bytes read are undefined. The status byte indicates the error and the bytes remaining indicates how many bytes were remaining to be sent of the data field of the packet when the error occurred. Table 34-52. MEMDATA Status Byte status byte Description 0x00 Read successful 0x01 SAB busy 0x02 Bus error (wrong address) Other Reserved Table 34-53. MEMDATA Details Response Details Response value 0xC1 Additional data Data read, status byte, and byte count (2 bytes) 895 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8.5 MEMORY_READWRITE_STATUS After a MEMORY_WRITE command this response is sent by AW. The response can also be sent after a MEMORY_READ command if AW encountered an error when receiving the address. The response contains 3 bytes, where the first is the status of the command and the 2 next contains the byte count when the first error occurred. The first byte is encoded this way: 34.6.8.6 BAUD_RATE The current baud rate in the AW. See Section 34.6.6.7 for more details. 34.6.8.7 STATUS_INFO A status message from AW. Table 34-54. MEMORY_READWRITE_STATUS Status Byte status byte Description 0x00 Write successful 0x01 SAB busy 0x02 Bus error (wrong address) Other Reserved Table 34-55. MEMORY_READWRITE_STATUS Details Response Details Response value 0xC2 Additional data Status byte and byte count (2 bytes) Table 34-56. BAUD_RATE Details Response Details Response value 0xC3 Additional data Baud rate Table 34-57. STATUS_INFO Contents Bit number Name Description 15-9 Reserved 8 Protected The protection bit in the internal flash is set. SAB access is restricted. This bit will read as one during reset. 7 SAB busy The SAB bus is busy with a previous transfer. This could indicate that the CPU is running on a very slow clock, the CPU clock has stopped for some reason or that the part is in constant reset. 6 Chip erase ongoing The Chip erase operation has not finished. 5 CPU halted This bit will be set if the CPU is halted. This bit will read as zero during reset. 4-1 Reserved 0 Reset status This bit will be set if AW has reset the CPU using the RESET command. 896 32142D–06/2013 ATUC64/128/256L3/4U 34.6.8.8 MEMORY_SPEED Counts the number of RC120M clock cycles it takes to sync one message to the SAB interface and back again. The SAB clock speed ( ) can be calculated using the following formula: 34.6.9 Security Restrictions When the security fuse in the Flash is programmed, the following aWire commands are limited: • MEMORY_WRITE • MEMORY_READ Unlimited access to these instructions is restored when the security fuse is erased by the CHIP_ERASE aWire command. Note that the security bit will read as programmed and block these instructions also if the Flash Controller is statically reset. Table 34-58. STATUS_INFO Details Response Details Response value 0xC4 Additional data 2 status bytes Table 34-59. MEMORY_SPEED Details Response Details Response value 0xC5 Additional data Clock cycle count (MS) f sab f sab 3f aw CV – 3 = ---------------- 897 32142D–06/2013 ATUC64/128/256L3/4U 35. Electrical Characteristics 35.1 Absolute Maximum Ratings* Notes: 1. 5V tolerant pins, see Section ”Peripheral Multiplexing on I/O lines” on page 10 2. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 35.2 Supply Characteristics The following characteristics are applicable to the operating temperature range: TA = -40°C to 85°C, unless otherwise specified and are valid for a junction temperature up to TJ = 100°C. Please refer to Section 6. ”Supply and Startup Considerations” on page 39. Table 35-1. Absolute Maximum Ratings Operating temperature..................................... -40C to +85C *NOTICE: Stresses beyond those listed under “Absolute Maximum Ratings” may cause permanent damage to the device. This is a stress rating only and functional operation of the device at these or other conditions beyond those indicated in the operational sections of this specification is not implied. Exposure to absolute maximum rating conditions for extended periods may affect device reliability. Storage temperature...................................... -60°C to +150°C Voltage on input pins (except for 5V pins) with respect to ground .................................................................-0.3V to VVDD(2)+0.3V Voltage on 5V tolerant(1) pins with respect to ground ............... .............................................................................-0.3V to 5.5V Total DC output current on all I/O pins - VDDIO, 64-pin package ............... ......................................................................141 mA Total DC output current on all I/O pins - VDDIN, 64-pin package ....................................................................................... 42 mA Total DC output current on all I/O pins - VDDIO, 48-pin package ........... ...........................................................................120mA Total DC output current on all I/O pins - VDDIN, 48-pin package ....................................................................................... 39 mA Maximum operating voltage VDDCORE......................... 1.98V Maximum operating voltage VDDIO, VDDIN .................... 3.6V Table 35-2. Supply Characteristics Symbol Parameter Voltage Min Max Unit VVDDIO DC supply peripheral I/Os 1.62 3.6 V VVDDIN DC supply peripheral I/Os, 1.8V single supply mode 1.62 1.98 V DC supply peripheral I/Os and internal regulator, 3.3V supply mode 1.98 3.6 V VVDDCORE DC supply core 1.62 1.98 V VVDDANA Analog supply voltage 1.62 1.98 V 898 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.3 Maximum Clock Frequencies These parameters are given in the following conditions: • VVDDCORE = 1.62V to 1.98V • Temperature = -40°C to 85°C 35.4 Power Consumption The values in Table 35-5 are measured values of power consumption under the following conditions, except where noted: • Operating conditions, internal core supply (Figure 35-1) - this is the default configuration – VVDDIN = 3.0V Table 35-3. Supply Rise Rates and Order(1) Symbol Parameter Rise Rate Min Max Unit Comment VVDDIO DC supply peripheral I/Os 0 2.5 V/µs VVDDIN DC supply peripheral I/Os and internal regulator 0.002 2.5 V/µs Slower rise time requires external power-on reset circuit. VVDDCORE DC supply core 0 2.5 V/µs Rise before or at the same time as VDDIO VVDDANA Analog supply voltage 0 2.5 V/µs Rise together with VDDCORE Table 35-4. Clock Frequencies Symbol Parameter Description Min Max Units fCPU CPU clock frequency 50 MHz fPBA PBA clock frequency 50 fPBB PBB clock frequency 50 fGCLK0 GCLK0 clock frequency DFLLIF main reference, GCLK0 pin 50 fGCLK1 GCLK1 clock frequency DFLLIF dithering and SSG reference, GCLK1 pin 50 fGCLK2 GCLK2 clock frequency AST, GCLK2 pin 20 fGCLK3 GCLK3 clock frequency PWMA, GCLK3 pin 140 fGCLK4 GCLK4 clock frequency CAT, ACIFB, GCLK4 pin 50 fGCLK5 GCLK5 clock frequency GLOC and GCLK5 pin 80 fGCLK6 GCLK6 clock frequency ABDACB, IISC, and GCLK6 pin 50 fGCLK7 GCLK7 clock frequency USBC and GCLK7 pin 50 fGCLK8 GCLK8 clock frequency PLL0 source clock and GCLK8 pin 50 fGCLK9 GCLK9 clock frequency FREQM, GCLK0-8, GCLK9 pin 150 899 32142D–06/2013 ATUC64/128/256L3/4U – VVDDCORE = 1.62V, supplied by the internal regulator – Corresponds to the 3.3V supply mode with 1.8V regulated I/O lines, please refer to the Supply and Startup Considerations section for more details • Equivalent to the 3.3V single supply mode • Consumption in 1.8V single supply mode can be estimated by subtracting the regulator static current • Operating conditions, external core supply (Figure 35-2) - used only when noted – VVDDIN = VVDDCORE = 1.8V – Corresponds to the 1.8V single supply mode, please refer to the Supply and Startup Considerations section for more details • TA = 25C • Oscillators – OSC0 (crystal oscillator) stopped – OSC32K (32KHz crystal oscillator) running with external 32KHz crystal – DFLL running at 50MHz with OSC32K as reference • Clocks – DFLL used as main clock source – CPU, HSB, and PBB clocks undivided – PBA clock divided by 4 – The following peripheral clocks running • PM, SCIF, AST, FLASHCDW, PBA bridge – All other peripheral clocks stopped • I/Os are inactive with internal pull-up • Flash enabled in high speed mode • POR18 enabled • POR33 disabled 900 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These numbers are valid for the measured condition only and must not be extrapolated to other frequencies. Figure 35-1. Measurement Schematic, Internal Core Supply Table 35-5. Power Consumption for Different Operating Modes Mode Conditions Measured on Consumption Typ Unit Active(1) CPU running a recursive Fibonacci algorithm Amp0 300 µA/MHz CPU running a division algorithm 174 Idle(1) 96 Frozen(1) 57 Standby(1) 46 Stop 38 µA DeepStop 25 Static -OSC32K and AST stopped -Internal core supply 14 -OSC32K running -AST running at 1KHz -External core supply (Figure 35-2) 7.3 -OSC32K and AST stopped -External core supply (Figure 35-2) 6.7 Shutdown -OSC32K running -AST running at 1KHz 800 nA AST and OSC32K stopped 220 Amp0 VDDIN VDDCORE VDDANA VDDIO 901 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-2. Measurement Schematic, External Core Supply Amp0 VDDIN VDDCORE VDDANA VDDIO 902 32142D–06/2013 ATUC64/128/256L3/4U 35.5 I/O Pin Characteristics Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-6. Normal I/O Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 75 100 145 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 VOL Output low-level voltage VVDD = 3.0V, IOL = 3mA 0.4 V VVDD = 1.62V, IOL = 2mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 3mA VVDD - 0.4 V VVDD = 1.62V, IOH = 2mA VVDD - 0.4 fMAX Output frequency(2) VVDD = 3.0V, load = 10pF 45 MHz VVDD = 3.0V, load = 30pF 23 tRISE Rise time(2) VVDD = 3.0V, load = 10pF 4.7 ns VVDD = 3.0V, load = 30pF 11.5 tFALL Fall time(2) VVDD = 3.0V, load = 10pF 4.8 VVDD = 3.0V, load = 30pF 12 ILEAK Input leakage current Pull-up resistors disabled 1 µA CIN Input capacitance, all normal I/O pins except PA05, PA07, PA17, PA20, PA21, PB04, PB05 TQFP48 package 1.4 pF QFN48 package 1.1 TLLGA48 package 1.1 TQFP64 package 1.5 QFN64 package 1.1 CIN Input capacitance, PA20 TQFP48 package 2.7 QFN48 package 2.4 TLLGA48 package 2.4 TQFP64 package 2.8 QFN64 package 2.4 CIN Input capacitance, PA05, PA07, PA17, PA21, PB04, PB05 TQFP48 package 3.8 QFN48 package 3.5 TLLGA48 package 3.5 TQFP64 package 3.9 QFN64 package 3.5 903 32142D–06/2013 ATUC64/128/256L3/4U Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. Table 35-7. High-drive I/O Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance PA06 30 50 110 PA02, PB01, RESET 75 100 145 kOhm PA08, PA09 10 20 45 VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 VOL Output low-level voltage VVDD = 3.0V, IOL = 6mA 0.4 V VVDD = 1.62V, IOL = 4mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 6mA VVDD - 0.4 V VVDD = 1.62V, IOH = 4mA VVDD - 0.4 fMAX Output frequency, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 45 MHz VVDD = 3.0V, load = 30pF 23 tRISE Rise time, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 4.7 ns VVDD = 3.0V, load = 30pF 11.5 tFALL Fall time, all High-drive I/O pins, except PA08 and PA09(2) VVDD = 3.0V, load = 10pF 4.8 VVDD = 3.0V, load = 30pF 12 fMAX Output frequency, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 54 MHz VVDD = 3.0V, load = 30pF 40 tRISE Rise time, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 2.8 ns VVDD = 3.0V, load = 30pF 4.9 tFALL Fall time, PA08 and PA09(2) VVDD = 3.0V, load = 10pF 2.4 VVDD = 3.0V, load = 30pF 4.6 ILEAK Input leakage current Pull-up resistors disabled 1 µA CIN Input capacitance, all High-drive I/O pins, except PA08 and PA09 TQFP48 package 2.2 pF QFN48 package 2.0 TLLGA48 package 2.0 TQFP64 package 2.3 QFN64 package 2.0 CIN Input capacitance, PA08 and PA09 TQFP48 package 7.0 QFN48 package 6.7 TLLGA48 package 6.7 TQFP64 package 7.1 QFN64 package 6.7 904 32142D–06/2013 ATUC64/128/256L3/4U 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Notes: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-8. High-drive I/O, 5V Tolerant, Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 30 50 110 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD 5.5 V VVDD = 1.98V 0.7 * VVDD 5.5 VOL Output low-level voltage VVDD = 3.0V, IOL = 6mA 0.4 V VVDD = 1.62V, IOL = 4mA 0.4 VOH Output high-level voltage VVDD = 3.0V, IOH = 6mA VVDD - 0.4 V VVDD = 1.62V, IOH = 4mA VVDD - 0.4 fMAX Output frequency(2) VVDD = 3.0V, load = 10pF 87 MHz VVDD = 3.0V, load = 30pF 58 tRISE Rise time(2) VVDD = 3.0V, load = 10pF 2.3 ns VVDD = 3.0V, load = 30pF 4.3 tFALL Fall time(2) VVDD = 3.0V, load = 10pF 1.9 VVDD = 3.0V, load = 30pF 3.7 ILEAK Input leakage current 5.5V, pull-up resistors disabled 10 µA CIN Input capacitance TQFP48 package 4.5 pF QFN48 package 4.2 TLLGA48 package 4.2 TQFP64 package 4.6 QFN64 package 4.2 Table 35-9. TWI Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units RPULLUP Pull-up resistance 25 35 60 kOhm VIL Input low-level voltage VVDD = 3.0V -0.3 0.3 * VVDD V VVDD = 1.62V -0.3 0.3 * VVDD VIH Input high-level voltage VVDD = 3.6V 0.7 * VVDD VVDD + 0.3 V VVDD = 1.98V 0.7 * VVDD VVDD + 0.3 Input high-level voltage, 5V tolerant SMBUS compliant pins VVDD = 3.6V 0.7 * VVDD 5.5 V VVDD = 1.98V 0.7 * VVDD 5.5 905 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. VVDD corresponds to either VVDDIN or VVDDIO, depending on the supply for the pin. Refer to Section on page 10 for details. 35.6 Oscillator Characteristics 35.6.1 Oscillator 0 (OSC0) Characteristics 35.6.1.1 Digital Clock Characteristics The following table describes the characteristics for the oscillator when a digital clock is applied on XIN. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.1.2 Crystal Oscillator Characteristics The following table describes the characteristics for the oscillator when a crystal is connected between XIN and XOUT as shown in Figure 35-3. The user must choose a crystal oscillator where the crystal load capacitance CL is within the range given in the table. The exact value of CL VOL Output low-level voltage IOL = 3mA 0.4 V ILEAK Input leakage current Pull-up resistors disabled 1 IIL Input low leakage 1 µA IIH Input high leakage 1 CIN Input capacitance TQFP48 package 3.8 pF QFN48 package 3.5 TLLGA48 package 3.5 TQFP64 package 3.9 QFN64 package 3.5 tFALL Fall time Cbus = 400pF, VVDD > 2.0V 250 ns Cbus = 400pF, VVDD > 1.62V 470 fMAX Max frequency Cbus = 400pF, VVDD > 2.0V 400 kHz Table 35-9. TWI Pin Characteristics(1) Symbol Parameter Condition Min Typ Max Units Table 35-10. Digital Clock Characteristics Symbol Parameter Conditions Min Typ Max Units fCPXIN XIN clock frequency 50 MHz tCPXIN XIN clock duty cycle(1) 40 60 % tSTARTUP Startup time 0 cycles CIN XIN input capacitance TQFP48 package 7.0 pF QFN48 package 6.7 TLLGA48 package 6.7 TQFP64 package 7.1 QFN64 package 6.7 906 32142D–06/2013 ATUC64/128/256L3/4U can be found in the crystal datasheet. The capacitance of the external capacitors (CLEXT) can then be computed as follows: where CPCB is the capacitance of the PCB and Ci is the internal equivalent load capacitance. Notes: 1. Please refer to the SCIF chapter for details. 2. Nominal crystal cycles. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Figure 35-3. Oscillator Connection CLEXT 2 CL Ci   – CPCB = – Table 35-11. Crystal Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Crystal oscillator frequency(3) 0.45 10 16 MHz CL Crystal load capacitance(3) 6 18 pF Ci Internal equivalent load capacitance 2 tSTARTUP Startup time SCIF.OSCCTRL.GAIN = 2(1) 30 000(2) cycles IOSC Current consumption Active mode, f = 0.45MHz, SCIF.OSCCTRL.GAIN = 0 30 µA Active mode, f = 10MHz, SCIF.OSCCTRL.GAIN = 2 220 XIN XOUT CLEXT CLEXT CL Ci UC3L 907 32142D–06/2013 ATUC64/128/256L3/4U 35.6.2 32KHz Crystal Oscillator (OSC32K) Characteristics Figure 35-3 and the equation above also applies to the 32KHz oscillator connection. The user must choose a crystal oscillator where the crystal load capacitance CL is within the range given in the table. The exact value of CL can then be found in the crystal datasheet. Notes: 1. Nominal crystal cycles. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.3 Phase Locked Loop (PLL) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-12. 32 KHz Crystal Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Crystal oscillator frequency 32 768 Hz tSTARTUP Startup time RS = 60kOhm, CL = 9pF 30 000(1) cycles CL Crystal load capacitance(2) 6 12.5 pF Ci Internal equivalent load capacitance 2 IOSC32 Current consumption 0.6 µA RS Equivalent series resistance(2) 32 768Hz 35 85 kOhm Table 35-13. Phase Locked Loop Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 40 240 MHz fIN Input frequency(1) 4 16 IPLL Current consumption 8 µA/MHz tSTARTUP Startup time, from enabling the PLL until the PLL is locked fIN= 4MHz 200 µs fIN= 16MHz 155 908 32142D–06/2013 ATUC64/128/256L3/4U 35.6.4 Digital Frequency Locked Loop (DFLL) Characteristics Notes: 1. Spread Spectrum Generator (SSG) is disabled by writing a zero to the EN bit in the DFLL0SSG register. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 3. The FINE and COARSE values are selected by wrirting to the DFLL0VAL.FINE and DFLL0VAL.COARSE field respectively. Table 35-14. Digital Frequency Locked Loop Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(2) 20 150 MHz fREF Reference frequency(2) 8 150 kHz FINE resolution step FINE > 100, all COARSE values (3) 0.38 % Frequency drift over voltage and temperature Open loop mode See Figure 35-4 Accuracy(2) FINE lock, fREF = 32kHz, SSG disabled 0.1 0.5 % ACCURATE lock, fREF = 32kHz, dither clk RCSYS/2, SSG disabled 0.06 0.5 FINE lock, fREF = 8-150kHz, SSG disabled 0.2 1 ACCURATE lock, fREF = 8-150kHz, dither clk RCSYS/2, SSG disabled 0.1 1 IDFLL Power consumption 25 µA/MHz tSTARTUP Startup time(2) Within 90% of final values 100 µs tLOCK Lock time fREF = 32kHz, FINE lock, SSG disabled 8 ms fREF = 32kHz, ACCURATE lock, dithering clock = RCSYS/2, SSG disabled 28 909 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-4. DFLL Open Loop Frequency Variation(1)(2) Notes: 1. The plot shows a typical open loop mode behavior with COARSE= 99 and FINE= 255. 2. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.5 120MHz RC Oscillator (RC120M) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. DFLL Open Loop Frequency variation 80 90 100 110 120 130 140 150 160 -40 -20 0 20 40 60 80 Temperature Frequencies (MHz) 1,98V 1,8V 1.62V Table 35-15. Internal 120MHz RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 88 120 152 MHz IRC120M Current consumption 1.2 mA tSTARTUP Startup time(1) VVDDCORE = 1.8V 3 µs 910 32142D–06/2013 ATUC64/128/256L3/4U 35.6.6 32kHz RC Oscillator (RC32K) Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.6.7 System RC Oscillator (RCSYS) Characteristics 35.7 Flash Characteristics Table 35-18 gives the device maximum operating frequency depending on the number of flash wait states and the flash read mode. The FSW bit in the FLASHCDW FSR register controls the number of wait states used when accessing the flash memory. Table 35-16. 32kHz RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency(1) 20 32 44 kHz IRC32K Current consumption 0.7 µA tSTARTUP Startup time(1) 100 µs Table 35-17. System RC Oscillator Characteristics Symbol Parameter Conditions Min Typ Max Unit fOUT Output frequency Calibrated at 85C 111.6 115 118.4 kHz Table 35-18. Maximum Operating Frequency Flash Wait States Read Mode Maximum Operating Frequency 1 High speed read mode 50MHz 0 25MHz 1 Normal read mode 30MHz 0 15MHz Table 35-19. Flash Characteristics Symbol Parameter Conditions Min Typ Max Unit tFPP Page programming time fCLK_HSB = 50MHz 5 ms tFPE Page erase time 5 tFFP Fuse programming time 1 tFEA Full chip erase time (EA) 6 tFCE JTAG chip erase time (CHIP_ERASE) fCLK_HSB = 115kHz 310 911 32142D–06/2013 ATUC64/128/256L3/4U 35.8 ABDACB Electrical Characteristics. Notes: 1. Test Condition: Common Mode Offset Control disabled (CR.CMOC = 0). Alternative Upsampling Ratio disabled (CR.ALTUPR = 0). Volume at maximum level (VCR0.VOLUME = 0x7FFF and VCR1.VOLUME = 0x7FFF). Device is battery powered (9V) through an LDO, VDDIO at 3.3V. Analog low pass filter as shown in Figure 35-5(1. order differential low pass filter followed by a 4. order low-pass), +VCC at +9V and -VCC at -9V. Test signal stored on a SD card and read by the SPI Interface. 2. Performance numbers for dynamic range, SNR, and THD performance are very dependent on the application and circuit board design. Since the design has 0dB Power Supply Rejection Ratio (PSRR), noise on the IO power supply will couple directly through to the output and be present in the audio signal. To get the best performance one should reduce toggling of other IO pins as much as possible and make sure the device has sufficient decoupling on the IO supply pins. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Figure 35-5. Differential Analog Low-pass Filter Table 35-20. Flash Endurance and Data Retention Symbol Parameter Conditions Min Typ Max Unit NFARRAY Array endurance (write/page) 100k cycles NFFUSE General Purpose fuses endurance (write/bit) 10k tRET Data retention 15 years Table 35-21. ABDACB Electrical Characteristics Symbol Parameter Conditions MIN TYP MAX Unit Resolution 16 Bits Dynamic range(1)(2)(3) FS = 48.000kHz > 76 dB SNR(1)(2)(3) FS = 48.000kHz > 46 dB THD(1)(2)(3) FS = 48.000kHz < 0.02 % PSRR 0 dB VOut maximum CR.CMOC = 0 97/128 * VDDIO V VOut minimum CR.CMOC = 0 31/128 * VDDIO V Common mode CR.CMOC = 0 CR.CMOC = 1, DAC_0 and DAC_1 pins CR.CMOC = 1, DACN_0 and DACN_1 pins 64/128 * VDDIO 80/128 * VDDIO 48/128 * VDDIO V R1, 22K C2 140p R2, 22K R4, 22K C1, 140p R3, 22K R6, 22K R5, 22K R7, 22K C4 270p C3 310p -Vcc +Vcc -Vcc +Vcc DAC DACN R8, 22K R9, 22K C6 110p C5 750p -Vcc +Vcc GND GND GND GND GND Out 912 32142D–06/2013 ATUC64/128/256L3/4U 35.9 Analog Characteristics 35.9.1 Voltage Regulator Characteristics Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Note: 1. Refer to Section 6.1.2 on page 39. Table 35-22. VREG Electrical Characteristics Symbol Parameter Condition Min Typ Max Units VVDDIN Input voltage range 1.98 3.3 3.6 V VVDDCORE Output voltage, calibrated value VVDDIN >= 1.98V 1.8 Output voltage accuracy(1) IOUT = 0.1mA to 60mA, VVDDIN > 1.98V 2 % IOUT = 0.1mA to 60mA, VVDDIN <1.98V 4 IOUT DC output current(1) Normal mode 60 mA Low power mode 1 IVREG Static current of internal regulator Normal mode 13 µA Low power mode 4 Table 35-23. Decoupling Requirements Symbol Parameter Condition Typ Techno. Units CIN1 Input regulator capacitor 1 33 nF CIN2 Input regulator capacitor 2 100 CIN3 Input regulator capacitor 3 10 µF COUT1 Output regulator capacitor 1 100 nF COUT2 Output regulator capacitor 2 2.2 Tantalum 0.5 3.0V, fADC = 6MHz, 12-bit resolution mode, low impedance source 28 kSPS VVDD > 3.0V, fADC = 6MHz, 10-bit resolution mode, low impedance source 460 VVDD > 3.0V, fADC = 6MHz, 8-bit resolution mode, low impedance source 460 VADVREFP Reference voltage range VADVREFP = VVDDANA 1.62 1.98 V IADC Current consumption on VVDDANA ADC Clock = 6MHz 350 µA IADVREFP Current consumption on ADVREFP pin fADC = 6MHz 150 Table 35-30. Analog Inputs Symbol Parameter Conditions Min Typ Max Units VADn Input Voltage Range 12-bit mode 10-bit mode 0 VADVREFP V 8-bit mode CONCHIP Internal Capacitance(1) 22.5 pF RONCHIP Internal Resistance(1) VVDDIO = 3.0V to 3.6V, VVDDCORE = 1.8V 3.15 kOhm VVDDIO = VVDDCORE = 1.62V to 1.98V 55.9 RONCHIP CONCHIP RSOURCE 917 32142D–06/2013 ATUC64/128/256L3/4U ( ) of the PCB and source must be taken into account when calculating the required sample and hold time. Figure 35-8 shows the ADC input channel equivalent circuit. Figure 35-8. ADC Input The minimum sample and hold time (in ns) can be found using this formula: Where n is the number of bits in the conversion. is defined by the SHTIM field in the ADCIFB ACR register. Please refer to the ADCIFB chapter for more information. 35.9.6.2 Applicable Conditions and Derating Data Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. CSOURCE ADCVREFP/2 CONCHIP RONCHIP R Positive Input SOURCE CSOURCE VIN t SAMPLEHOLD RONCHIP + RSOURCE   CONCHIP CSOURCE    + 2n + 1   ln  t SAMPLEHOLD Table 35-31. Transfer Characteristics 12-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 12 Bit Integral non-linearity ADC clock frequency = 6MHz, Input Voltage Range = 0 - VADVREFP +/-4 LSB ADC clock frequency = 6MHz, Input Voltage Range = (10% VADVREFP) - (90% VADVREFP) +/-2 Differential non-linearity ADC clock frequency = 6MHz -1.5 1.5 Offset error +/-3 Gain error +/-5 Table 35-32. Transfer Characteristics, 10-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 10 Bit Integral non-linearity ADC clock frequency = 6MHz +/-1 LSB Differential non-linearity -1.0 1.0 Offset error +/-1 Gain error +/-2 918 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.9.7 Temperature Sensor Characteristics Note: 1. The Temperature Sensor is not calibrated. The accuracy of the Temperature Sensor is governed by the ADC accuracy. Table 35-33. Transfer Characteristics, 8-bit Resolution Mode(1) Parameter Conditions Min Typ Max Units Resolution 8 Bit Integral non-linearity ADC clock frequency = 6MHz +/-0.5 LSB Differential non-linearity -0.3 0.3 Offset error +/-1 Gain error +/-1 Table 35-34. Temperature Sensor Characteristics(1) Symbol Parameter Condition Min Typ Max Units Gradient 1 mV/°C ITS Current consumption 1 µA tSTARTUP Startup time 0 µs 919 32142D–06/2013 ATUC64/128/256L3/4U 35.9.8 Analog Comparator Characteristics Notes: 1. AC.CONFn.FLEN and AC.CONFn.HYS fields, refer to the Analog Comparator Interface chapter. 2. Referring to fAC. 3. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.9.9 Capacitive Touch Characteristics 35.9.9.1 Discharge Current Source Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Table 35-35. Analog Comparator Characteristics Symbol Parameter Condition Min Typ Max Units Positive input voltage range(3) -0.2 VVDDIO + 0.3 V Negative input voltage range(3) -0.2 VVDDIO - 0.6 Statistical offset(3) VACREFN = 1.0V, fAC = 12MHz, filter length = 2, hysteresis = 0(1) 20 mV fAC Clock frequency for GCLK4(3) 12 MHz Throughput rate(3) fAC = 12MHz 12 000 000 Comparisons per second Propagation delay Delay from input change to Interrupt Status Register Changes ns IAC Current consumption(3) All channels, VDDIO = 3.3V, fA = 3MHz 420 µA tSTARTUP Startup time 3 cycles Input current per pin(3) 0.2 µA/MHz(2) Table 35-36. DICS Characteristics Symbol Parameter Min Typ Max Unit RREF Internal resistor 170 kOhm k Trim step size(1) 0.7 % 1 t CLKACIFB f AC  ---------------------------------------- + 3     t CLKACIFB  920 32142D–06/2013 ATUC64/128/256L3/4U 35.9.9.2 Strong Pull-up Pull-down 35.9.10 USB Transceiver Characteristics The USB on-chip buffers comply with the Universal Serial Bus (USB) v2.0 standard. All AC parameters related to these buffers can be found within the USB 2.0 electrical specifications. 35.9.10.1 Electrical Characteristics Table 35-37. Strong Pull-up Pull-down Parameter Min Typ Max Unit Pull-down resistor 1 kOhm Pull-up resistor 1 Table 35-38. Electrical Parameters Symbol Parameter Conditions Min Typ Max Unit REXT Recommended external USB series resistor In series with each USB pin with ±5% 39 Ohm 921 32142D–06/2013 ATUC64/128/256L3/4U 35.10 Timing Characteristics 35.10.1 Startup, Reset, and Wake-up Timing The startup, reset, and wake-up timings are calculated using the following formula: Where and are found in Table 35-39. is the period of the CPU clock. If a clock source other than RCSYS is selected as the CPU clock, the oscillator startup time, , must be added to the wake-up time from the stop, deepstop, and static sleep modes. Please refer to the source for the CPU clock in the ”Oscillator Characteristics” on page 905 for more details about oscillator startup times. Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 35.10.2 RESET_N Timing Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. t tCONST NCPU t CPU = +  t CONST NCPU t CPU t OSCSTART Table 35-39. Maximum Reset and Wake-up Timing(1) Parameter Measuring Max (in µs) Max Startup time from power-up, using regulator Time from VDDIN crossing the VPOT+ threshold of POR33 to the first instruction entering the decode stage of CPU. VDDCORE is supplied by the internal regulator. 2210 0 Startup time from power-up, no regulator Time from VDDIN crossing the VPOT+ threshold of POR33 to the first instruction entering the decode stage of CPU. VDDCORE is connected to VDDIN. 1810 0 Startup time from reset release Time from releasing a reset source (except POR18, POR33, and SM33) to the first instruction entering the decode stage of CPU. 170 0 Wake-up Idle From wake-up event to the first instruction of an interrupt routine entering the decode stage of the CPU. 0 19 Frozen 0 110 Standby 0 110 Stop 27 + 116 Deepstop 27 + 116 Static 97 + 116 Wake-up from shutdown From wake-up event to the first instruction entering the decode stage of the CPU. 1180 0 t CONST NCPU t OSCSTART t OSCSTART t OSCSTART Table 35-40. RESET_N Waveform Parameters(1) Symbol Parameter Conditions Min Max Units tRESET RESET_N minimum pulse length 10 ns 922 32142D–06/2013 ATUC64/128/256L3/4U 35.10.3 USART in SPI Mode Timing 35.10.3.1 Master mode Figure 35-9. USART in SPI Master Mode with (CPOL= CPHA= 0) or (CPOL= CPHA= 1) Figure 35-10. USART in SPI Master Mode with (CPOL= 0 and CPHA= 1) or (CPOL= 1 and CPHA= 0) Notes: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 2. Where: USPI0 USPI1 MISO SPCK MOSI USPI2 USPI3 USPI4 MISO SPCK MOSI USPI5 Table 35-41. USART in SPI Mode Timing, Master Mode(1) Symbol Parameter Conditions Min Max Units USPI0 MISO setup time before SPCK rises VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 28.7 + tSAMPLE(2) ns USPI1 MISO hold time after SPCK rises 0 USPI2 SPCK rising to MOSI delay 16.5 USPI3 MISO setup time before SPCK falls 25.8 + tSAMPLE(2) USPI4 MISO hold time after SPCK falls 0 USPI5 SPCK falling to MOSI delay 21.19 t SAMPLE t SPCK t SPCK 2 t CLKUSART  ------------------------------------ 1 2 --     t CLKUSART = –  923 32142D–06/2013 ATUC64/128/256L3/4U Maximum SPI Frequency, Master Output The maximum SPI master output frequency is given by the following formula: Where is the MOSI delay, USPI2 or USPI5 depending on CPOL and NCPHA. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Master Input The maximum SPI master input frequency is given by the following formula: Where is the MISO setup and hold time, USPI0 + USPI1 or USPI3 + USPI4 depending on CPOL and NCPHA. is the SPI slave response time. Please refer to the SPI slave datasheet for . is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. 35.10.3.2 Slave mode Figure 35-11. USART in SPI Slave Mode with (CPOL= 0 and CPHA= 1) or (CPOL= 1 and CPHA= 0) f SPCKMAX MIN fPINMAX 1 SPIn ------------ f CLKSPI  2 9 = (, )  ---------------------------- SPIn fPINMAX f CLKSPI f SPCKMAX MIN 1 SPIn tVALID + ----------------------------------- f CLKSPI  2 9 = ( ,) ----------------------------- SPIn TVALID TVALID f CLKSPI USPI7 USPI8 MISO SPCK MOSI USPI6 924 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-12. USART in SPI Slave Mode with (CPOL= CPHA= 0) or (CPOL= CPHA= 1) Figure 35-13. USART in SPI Slave Mode, NPCS Timing Notes: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. 2. Where: USPI10 USPI11 MISO SPCK MOSI USPI9 USPI14 USPI12 USPI15 USPI13 NSS SPCK, CPOL=0 SPCK, CPOL=1 Table 35-42. USART in SPI mode Timing, Slave Mode(1) Symbol Parameter Conditions Min Max Units USPI6 SPCK falling to MISO delay VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 37.3 ns USPI7 MOSI setup time before SPCK rises 2.6 + tSAMPLE(2) + tCLK_USART USPI8 MOSI hold time after SPCK rises 0 USPI9 SPCK rising to MISO delay 37.0 USPI10 MOSI setup time before SPCK falls 2.6 + tSAMPLE(2) + tCLK_USART USPI11 MOSI hold time after SPCK falls 0 USPI12 NSS setup time before SPCK rises 27.2 USPI13 NSS hold time after SPCK falls 0 USPI14 NSS setup time before SPCK falls 27.2 USPI15 NSS hold time after SPCK rises 0 t SAMPLE t SPCK t SPCK 2 tCLKUSART  ------------------------------------ 1 2 + --     t CLKUSART = –  925 32142D–06/2013 ATUC64/128/256L3/4U Maximum SPI Frequency, Slave Input Mode The maximum SPI slave input frequency is given by the following formula: Where is the MOSI setup and hold time, USPI7 + USPI8 or USPI10 + USPI11 depending on CPOL and NCPHA. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Slave Output Mode The maximum SPI slave output frequency is given by the following formula: Where is the MISO delay, USPI6 or USPI9 depending on CPOL and NCPHA. is the SPI master setup time. Please refer to the SPI master datasheet for . is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. 35.10.4 SPI Timing 35.10.4.1 Master mode Figure 35-14. SPI Master Mode with (CPOL= NCPHA= 0) or (CPOL= NCPHA= 1) f SPCKMAX MIN f CLKSPI  2 9 ----------------------------- 1 SPIn = ( ,) ------------ SPIn f CLKSPI f SPCKMAX MIN f CLKSPI  2 9 ---------------------------- f PINMAX  1 SPIn tSETUP + = ( ,) ------------------------------------ SPIn TSETUP TSETUP f CLKSPI f PINMAX SPI0 SPI1 MISO SPCK MOSI SPI2 926 32142D–06/2013 ATUC64/128/256L3/4U Figure 35-15. SPI Master Mode with (CPOL= 0 and NCPHA= 1) or (CPOL= 1 and NCPHA= 0) Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Maximum SPI Frequency, Master Output The maximum SPI master output frequency is given by the following formula: Where is the MOSI delay, SPI2 or SPI5 depending on CPOL and NCPHA. is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. Maximum SPI Frequency, Master Input The maximum SPI master input frequency is given by the following formula: Where is the MISO setup and hold time, SPI0 + SPI1 or SPI3 + SPI4 depending on CPOL and NCPHA. is the SPI slave response time. Please refer to the SPI slave datasheet for . SPI3 SPI4 MISO SPCK MOSI SPI5 Table 35-43. SPI Timing, Master Mode(1) Symbol Parameter Conditions Min Max Units SPI0 MISO setup time before SPCK rises VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 33.4 + (tCLK_SPI)/2 ns SPI1 MISO hold time after SPCK rises 0 SPI2 SPCK rising to MOSI delay 7.1 SPI3 MISO setup time before SPCK falls 29.2 + (tCLK_SPI)/2 SPI4 MISO hold time after SPCK falls 0 SPI5 SPCK falling to MOSI delay 8.63 f SPCKMAX MIN fPINMAX 1 SPIn = ( ,) ------------ SPIn f PINMAX f SPCKMAX 1 SPIn tVALID + = ----------------------------------- SPIn t VALID tVALID 927 32142D–06/2013 ATUC64/128/256L3/4U 35.10.4.2 Slave mode Figure 35-16. SPI Slave Mode with (CPOL= 0 and NCPHA= 1) or (CPOL= 1 and NCPHA= 0) Figure 35-17. SPI Slave Mode with (CPOL= NCPHA= 0) or (CPOL= NCPHA= 1) Figure 35-18. SPI Slave Mode, NPCS Timing SPI7 SPI8 MISO SPCK MOSI SPI6 SPI10 SPI11 MISO SPCK MOSI SPI9 SPI14 SPI12 SPI15 SPI13 NPCS SPCK, CPOL=0 SPCK, CPOL=1 928 32142D–06/2013 ATUC64/128/256L3/4U Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. Maximum SPI Frequency, Slave Input Mode The maximum SPI slave input frequency is given by the following formula: Where is the MOSI setup and hold time, SPI7 + SPI8 or SPI10 + SPI11 depending on CPOL and NCPHA. is the maximum frequency of the CLK_SPI. Refer to the SPI chapter for a description of this clock. Maximum SPI Frequency, Slave Output Mode The maximum SPI slave output frequency is given by the following formula: Where is the MISO delay, SPI6 or SPI9 depending on CPOL and NCPHA. is the SPI master setup time. Please refer to the SPI master datasheet for . is the maximum frequency of the SPI pins. Please refer to the I/O Pin Characteristics section for the maximum frequency of the pins. 35.10.5 TWIM/TWIS Timing Figure 35-45 shows the TWI-bus timing requirements and the compliance of the device with them. Some of these requirements (tr and tf ) are met by the device without requiring user intervention. Compliance with the other requirements (tHD-STA, tSU-STA, tSU-STO, tHD-DAT, tSU-DAT-TWI, tLOWTWI, tHIGH, and fTWCK) requires user intervention through appropriate programming of the relevant Table 35-44. SPI Timing, Slave Mode(1) Symbol Parameter Conditions Min Max Units SPI6 SPCK falling to MISO delay VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 29.4 ns SPI7 MOSI setup time before SPCK rises 0 SPI8 MOSI hold time after SPCK rises 6.0 SPI9 SPCK rising to MISO delay 29.0 SPI10 MOSI setup time before SPCK falls 0 SPI11 MOSI hold time after SPCK falls 5.5 SPI12 NPCS setup time before SPCK rises 3.4 SPI13 NPCS hold time after SPCK falls 1.1 SPI14 NPCS setup time before SPCK falls 3.3 SPI15 NPCS hold time after SPCK rises 0.7 f SPCKMAX MIN fCLKSPI 1 SPIn = ( ,) ------------ SPIn f CLKSPI f SPCKMAX MIN fPINMAX 1 SPIn tSETUP + = (, ) ------------------------------------ SPIn t SETUP t SETUP fPINMAX 929 32142D–06/2013 ATUC64/128/256L3/4U TWIM and TWIS user interface registers. Please refer to the TWIM and TWIS sections for more information. Notes: 1. Standard mode: ; fast mode: . 2. A device must internally provide a hold time of at least 300 ns for TWD with reference to the falling edge of TWCK. Notations: Cb = total capacitance of one bus line in pF tclkpb = period of TWI peripheral bus clock tprescaled = period of TWI internal prescaled clock (see chapters on TWIM and TWIS) The maximum tHD;DAT has only to be met if the device does not stretch the LOW period (tLOW-TWI) of TWCK. Table 35-45. TWI-Bus Timing Requirements Symbol Parameter Mode Minimum Maximum Uni Requirement Device Requirement Device t tr TWCK and TWD rise time Standard( 1) - 1000 ns Fast(1) 20 + 0.1Cb 300 tf TWCK and TWD fall time Standard - 300 ns Fast 20 + 0.1Cb 300 tHD-STA (Repeated) START hold time Standard 4 tclkpb - s Fast 0.6 tSU-STA (Repeated) START set-up time Standard 4.7 tclkpb - s Fast 0.6 tSU-STO STOP set-up time Standard 4.0 4tclkpb - s Fast 0.6 tHD-DAT Data hold time Standard 0.3(2) 2tclkpb 3.45() 15tprescaled + tclkpb s Fast 0.9() tSU-DATTWI Data set-up time Standard 250 2tclkpb - ns Fast 100 tSU-DAT - -tclkpb - - tLOW-TWI TWCK LOW period Standard 4.7 4tclkpb - s Fast 1.3 tLOW - -tclkpb - - tHIGH TWCK HIGH period Standard 4.0 8tclkpb - s Fast 0.6 fTWCK TWCK frequency Standard - 100 kHz Fast 400 1 12tclkpb ----------------------- fTWCK  100 kHz f TWCK  100 kHz 930 32142D–06/2013 ATUC64/128/256L3/4U 35.10.6 JTAG Timing Figure 35-19. JTAG Interface Signals Note: 1. These values are based on simulation and characterization of other AVR microcontrollers manufactured in the same process technology. These values are not covered by test limits in production. JTAG2 JTAG3 JTAG1 JTAG4 JTAG0 TMS/TDI TCK TDO JTAG5 JTAG6 JTAG7 JTAG8 JTAG9 JTAG10 Boundary Scan Inputs Boundary Scan Outputs Table 35-46. JTAG Timings(1) Symbol Parameter Conditions Min Max Units JTAG0 TCK Low Half-period VVDDIO from 3.0V to 3.6V, maximum external capacitor = 40pF 21.8 ns JTAG1 TCK High Half-period 8.6 JTAG2 TCK Period 30.3 JTAG3 TDI, TMS Setup before TCK High 2.0 JTAG4 TDI, TMS Hold after TCK High 2.3 JTAG5 TDO Hold Time 9.5 JTAG6 TCK Low to TDO Valid 21.8 JTAG7 Boundary Scan Inputs Setup Time 0.6 JTAG8 Boundary Scan Inputs Hold Time 6.9 JTAG9 Boundary Scan Outputs Hold Time 9.3 JTAG10 TCK to Boundary Scan Outputs Valid 32.2 931 32142D–06/2013 ATUC64/128/256L3/4U 36. Mechanical Characteristics 36.1 Thermal Considerations 36.1.1 Thermal Data Table 36-1 summarizes the thermal resistance data depending on the package. 36.1.2 Junction Temperature The average chip-junction temperature, TJ, in °C can be obtained from the following: 1. 2. where: • JA = package thermal resistance, Junction-to-ambient (°C/W), provided in Table 36-1. • JC = package thermal resistance, Junction-to-case thermal resistance (°C/W), provided in Table 36-1. • HEAT SINK = cooling device thermal resistance (°C/W), provided in the device datasheet. • PD = device power consumption (W) estimated from data provided in Section 35.4 on page 898. • TA = ambient temperature (°C). From the first equation, the user can derive the estimated lifetime of the chip and decide if a cooling device is necessary or not. If a cooling device is to be fitted on the chip, the second equation should be used to compute the resulting average chip-junction temperature TJ in °C. Table 36-1. Thermal Resistance Data Symbol Parameter Condition Package Typ Unit JA Junction-to-ambient thermal resistance Still Air TQFP48 54.4 C/W JC Junction-to-case thermal resistance TQFP48 15.7 JA Junction-to-ambient thermal resistance Still Air QFN48 26.0 C/W JC Junction-to-case thermal resistance QFN48 1.6 JA Junction-to-ambient thermal resistance Still Air TLLGA48 25.4 C/W JC Junction-to-case thermal resistance TLLGA48 12.7 JA Junction-to-ambient thermal resistance Still Air TQFP64 52.9 C/W JC Junction-to-case thermal resistance TQFP64 15.5 JA Junction-to-ambient thermal resistance Still Air QFN64 22.9 C/W JC Junction-to-case thermal resistance QFN64 1.6 TJ TA PD JA = +    TJ TA PD  HEATSINK  JC = + +   932 32142D–06/2013 ATUC64/128/256L3/4U 36.2 Package Drawings Figure 36-1. TQFP-48 Package Drawing Table 36-2. Device and Package Maximum Weight 140 mg Table 36-3. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-4. Package Reference JEDEC Drawing Reference MS-026 JESD97 Classification E3 933 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-2. QFN-48 Package Drawing Note: The exposed pad is not connected to anything internally, but should be soldered to ground to increase board level reliability. Table 36-5. Device and Package Maximum Weight 140 mg Table 36-6. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-7. Package Reference JEDEC Drawing Reference M0-220 JESD97 Classification E3 934 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-3. TLLGA-48 Package Drawing Table 36-8. Device and Package Maximum Weight 39.3 mg Table 36-9. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-10. Package Reference JEDEC Drawing Reference N/A JESD97 Classification E4 935 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-4. TQFP-64 Package Drawing Table 36-11. Device and Package Maximum Weight 300 mg Table 36-12. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-13. Package Reference JEDEC Drawing Reference MS-026 JESD97 Classification E3 936 32142D–06/2013 ATUC64/128/256L3/4U Figure 36-5. QFN-64 Package Drawing Note: The exposed pad is not connected to anything internally, but should be soldered to ground to increase board level reliability. Table 36-14. Device and Package Maximum Weight 200 mg Table 36-15. Package Characteristics Moisture Sensitivity Level MSL3 Table 36-16. Package Reference JEDEC Drawing Reference M0-220 JESD97 Classification E3 937 32142D–06/2013 ATUC64/128/256L3/4U 36.3 Soldering Profile Table 36-17 gives the recommended soldering profile from J-STD-20. A maximum of three reflow passes is allowed per component. Table 36-17. Soldering Profile Profile Feature Green Package Average Ramp-up Rate (217°C to Peak) 3°C/s max Preheat Temperature 175°C ±25°C 150-200°C Time Maintained Above 217°C 60-150 s Time within 5C of Actual Peak Temperature 30 s Peak Temperature Range 260°C Ramp-down Rate 6°C/s max Time 25C to Peak Temperature 8 minutes max 938 32142D–06/2013 ATUC64/128/256L3/4U 37. Ordering Information Table 37-1. Ordering Information Device Ordering Code Carrier Type Package Package Type Temperature Operating Range ATUC256L3U ATUC256L3U-AUTES ES TQFP 64 JESD97 Classification E3 N/A ATUC256L3U-AUT Tray Industrial (-40C to 85C) ATUC256L3U-AUR Tape & Reel ATUC256L3U-Z3UTES ES QFN 64 N/A ATUC256L3U-Z3UT Tray Industrial (-40C to 85C) ATUC256L3U-Z3UR Tape & Reel ATUC128L3U ATUC128L3U-AUT Tray TQFP 64 JESD97 Classification E3 Industrial (-40C to 85C) ATUC128L3U-AUR Tape & Reel ATUC128L3U-Z3UT Tray QFN 64 ATUC128L3U-Z3UR Tape & Reel ATUC64L3U ATUC64L3U-AUT Tray TQFP 64 JESD97 Classification E3 Industrial (-40C to 85C) ATUC64L3U-AUR Tape & Reel ATUC64L3U-Z3UT Tray QFN 64 ATUC64L3U-Z3UR Tape & Reel 939 32142D–06/2013 ATUC64/128/256L3/4U ATUC256L4U ATUC256L4U-AUTES ES TQFP 48 JESD97 Classification E3 N/A ATUC256L4U-AUT Tray Industrial (-40C to 85C) ATUC256L4U-AUR Tape & Reel ATUC256L4U-ZAUTES ES QFN 48 N/A ATUC256L4U-ZAUT Tray Industrial (-40C to 85C) ATUC256L4U-ZAUR Tape & Reel ATUC256L4U-D3HES ES TLLGA 48 JESD97 Classification E4 N/A ATUC256L4U-D3HT Tray Industrial (-40C to 85C) ATUC256L4U-D3HR Tape & Reel ATUC128L4U ATUC128L4U-AUT Tray TQFP 48 JESD97 Classification E3 ATUC128L4U-AUR Tape & Reel ATUC128L4U-ZAUT Tray QFN 48 ATUC128L4U-ZAUR Tape & Reel ATUC128L4U-D3HT Tray TLLGA 48 JESD97 Classification E4 ATUC128L4U-D3HR Tape & Reel ATUC64L4U ATUC64L4U-AUT Tray TQFP 48 JESD97 Classification E3 ATUC64L4U-AUR Tape & Reel ATUC64L4U-ZAUT Tray QFN 48 ATUC64L4U-ZAUR Tape & Reel ATUC64L4U-D3HT Tray TLLGA 48 JESD97 Classification E4 ATUC64L4U-D3HR Tape & Reel Table 37-1. Ordering Information Device Ordering Code Carrier Type Package Package Type Temperature Operating Range 940 32142D–06/2013 ATUC64/128/256L3/4U 38. Errata 38.1 Rev. C 38.1.1 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 3. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.1.2 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 941 32142D–06/2013 ATUC64/128/256L3/4U 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 38.1.3 TWI 1. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 2. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 38.1.4 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.1.5 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the periph- 942 32142D–06/2013 ATUC64/128/256L3/4U eral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 38.1.6 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.2 Flash 1. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.3 Rev. B 38.3.1 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one f sab 7f aw CV – 3 = ---------------- 943 32142D–06/2013 ATUC64/128/256L3/4U - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 3. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.3.2 WDT 1. WDT Control Register does not have synchronization feedback When writing to the Timeout Prescale Select (PSEL), Time Ban Prescale Select (TBAN), Enable (EN), or WDT Mode (MODE) fieldss of the WDT Control Register (CTRL), a synchronizer is started to propagate the values to the WDT clcok domain. This synchronization takes a finite amount of time, but only the status of the synchronization of the EN bit is reflected back to the user. Writing to the synchronized fields during synchronization can lead to undefined behavior. Fix/Workaround -When writing to the affected fields, the user must ensure a wait corresponding to 2 clock cycles of both the WDT peripheral bus clock and the selected WDT clock source. -When doing writes that changes the EN bit, the EN bit can be read back until it reflects the written value. 38.3.3 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 944 32142D–06/2013 ATUC64/128/256L3/4U 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 38.3.4 TWI 1. TWIS may not wake the device from sleep mode If the CPU is put to a sleep mode (except Idle and Frozen) directly after a TWI Start condition, the CPU may not wake upon a TWIS address match. The request is NACKed. Fix/Workaround When using the TWI address match to wake the device from sleep, do not switch to sleep modes deeper than Frozen. Another solution is to enable asynchronous EIC wake on the TWIS clock (TWCK) or TWIS data (TWD) pins, in order to wake the system up on bus events. 2. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 3. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 38.3.5 PWMA 1. The SR.READY bit cannot be cleared by writing to SCR.READY The Ready bit in the Status Register will not be cleared when writing a one to the corresponding bit in the Status Clear register. The Ready bit will be cleared when the Busy bit is set. Fix/Workaround 945 32142D–06/2013 ATUC64/128/256L3/4U Disable the Ready interrupt in the interrupt handler when receiving the interrupt. When an operation that triggers the Busy/Ready bit is started, wait until the ready bit is low in the Status Register before enabling the interrupt. 38.3.6 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.3.7 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the peripheral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 3. CAT consumes unnecessary power when disabled or when autonomous touch not used A CAT prescaler controlled by the ATCFG0.DIV field will be active even when the CAT module is disabled or when the autonomous touch feature is not used, thereby causing unnecessary power consumption. Fix/Workaround If the CAT module is not used, disable the CLK_CAT clock in the PM module. If the CAT module is used but the autonomous touch feature is not used, the power consumption of the CAT module may be reduced by writing 0xFFFF to the ATCFG0.DIV field. 38.3.8 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround 946 32142D–06/2013 ATUC64/128/256L3/4U Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.4 Flash 2. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.5 Rev. A 38.5.1 Device 3. JTAGID is wrong The JTAGID reads 0x021DF03F for all devices. Fix/Workaround None. 38.5.2 FLASHCDW 1. General-purpose fuse programming does not work The general-purpose fuses cannot be programmed and are stuck at 1. Please refer to the Fuse Settings chapter in the FLASHCDW for more information about what functions are affected. Fix/Workaround None. 2. Set Security Bit command does not work The Set Security Bit (SSB) command of the FLASHCDW does not work. The device cannot be locked from external JTAG, aWire, or other debug accesses. Fix/Workaround None. 3. Flash programming time is longer than specified f sab 7f aw CV – 3 = ---------------- 947 32142D–06/2013 ATUC64/128/256L3/4U The flash programming time is now: Fix/Workaround None. 4. Power Manager 5. Clock Failure Detector (CFD) can be issued while turning off the CFD While turning off the CFD, the CFD bit in the Status Register (SR) can be set. This will change the main clock source to RCSYS. Fix/Workaround Solution 1: Enable CFD interrupt. If CFD interrupt is issues after turning off the CFD, switch back to original main clock source. Solution 2: Only turn off the CFD while running the main clock on RCSYS. 6. Sleepwalking in idle and frozen sleep mode will mask all other PB clocks If the CPU is in idle or frozen sleep mode and a module is in a state that triggers sleep walking, all PB clocks will be masked except the PB clock to the sleepwalking module. Fix/Workaround Mask all clock requests in the PM.PPCR register before going into idle or frozen mode. 4. Unused PB clocks are running Three unused PBA clocks are enabled by default and will cause increased active power consumption. Fix/Workaround Disable the clocks by writing zeroes to bits [27:25] in the PBA clock mask register. 38.5.3 SCIF 1. The RC32K output on PA20 is not always permanently disabled The RC32K output on PA20 may sometimes re-appear. Fix/Workaround Before using RC32K for other purposes, the following procedure has to be followed in order to properly disable it: - Run the CPU on RCSYS - Disable the output to PA20 by writing a zero to PM.PPCR.RC32OUT - Enable RC32K by writing a one to SCIF.RC32KCR.EN, and wait for this bit to be read as one - Disable RC32K by writing a zero to SCIF.RC32KCR.EN, and wait for this bit to be read as zero. 2. PLL lock might not clear after disable Table 38-1. Flash Characteristics Symbol Parameter Conditions Min Typ Max Unit TFPP Page programming time fCLK_HSB= 50MHz 7.5 ms TFPE Page erase time 7.5 TFFP Fuse programming time 1 TFEA Full chip erase time (EA) 9 TFCE JTAG chip erase time (CHIP_ERASE) fCLK_HSB= 115kHz 250 948 32142D–06/2013 ATUC64/128/256L3/4U Under certain circumstances, the lock signal from the Phase Locked Loop (PLL) oscillator may not go back to zero after the PLL oscillator has been disabled. This can cause the propagation of clock signals with the wrong frequency to parts of the system that use the PLL clock. Fix/Workaround PLL must be turned off before entering STOP, DEEPSTOP or STATIC sleep modes. If PLL has been turned off, a delay of 30us must be observed after the PLL has been enabled again before the SCIF.PLL0LOCK bit can be used as a valid indication that the PLL is locked. 3. PLLCOUNT value larger than zero can cause PLLEN glitch Initializing the PLLCOUNT with a value greater than zero creates a glitch on the PLLEN signal during asynchronous wake up. Fix/Workaround The lock-masking mechanism for the PLL should not be used. The PLLCOUNT field of the PLL Control Register should always be written to zero. 4. RCSYS is not calibrated The RCSYS is not calibrated and will run faster than 115.2kHz. Frequencies around 150kHz can be expected. Fix/Workaround If a known clock source is available the RCSYS can be runtime calibrated by using the frequency meter (FREQM) and tuning the RCSYS by writing to the RCCR register in SCIF. 5. Writing 0x5A5A5A5A to the SCIF memory range will enable the SCIF UNLOCK feature The SCIF UNLOCK feature will be enabled if the value 0x5A5A5A5A is written to any location in the SCIF memory range. Fix/Workaround None. 38.5.4 WDT 1. Clearing the Watchdog Timer (WDT) counter in second half of timeout period will issue a Watchdog reset If the WDT counter is cleared in the second half of the timeout period, the WDT will immediately issue a Watchdog reset. Fix/Workaround Use twice as long timeout period as needed and clear the WDT counter within the first half of the timeout period. If the WDT counter is cleared after the first half of the timeout period, you will get a Watchdog reset immediately. If the WDT counter is not cleared at all, the time before the reset will be twice as long as needed. 2. WDT Control Register does not have synchronization feedback When writing to the Timeout Prescale Select (PSEL), Time Ban Prescale Select (TBAN), Enable (EN), or WDT Mode (MODE) fieldss of the WDT Control Register (CTRL), a synchronizer is started to propagate the values to the WDT clcok domain. This synchronization takes a finite amount of time, but only the status of the synchronization of the EN bit is reflected back to the user. Writing to the synchronized fields during synchronization can lead to undefined behavior. Fix/Workaround -When writing to the affected fields, the user must ensure a wait corresponding to 2 clock cycles of both the WDT peripheral bus clock and the selected WDT clock source. -When doing writes that changes the EN bit, the EN bit can be read back until it reflects the written value. 949 32142D–06/2013 ATUC64/128/256L3/4U 38.5.5 GPIO 1. Clearing Interrupt flags can mask other interrupts When clearing interrupt flags in a GPIO port, interrupts on other pins of that port, happening in the same clock cycle will not be registered. Fix/Workaround Read the PVR register of the port before and after clearing the interrupt to see if any pin change has happened while clearing the interrupt. If any change occurred in the PVR between the reads, they must be treated as an interrupt. 38.5.6 SPI 1. SPI data transfer hangs with CSR0.CSAAT==1 and MR.MODFDIS==0 When CSR0.CSAAT==1 and mode fault detection is enabled (MR.MODFDIS==0), the SPI module will not start a data transfer. Fix/Workaround Disable mode fault detection by writing a one to MR.MODFDIS. 2. Disabling SPI has no effect on the SR.TDRE bit Disabling SPI has no effect on the SR.TDRE bit whereas the write data command is filtered when SPI is disabled. Writing to TDR when SPI is disabled will not clear SR.TDRE. If SPI is disabled during a PDCA transfer, the PDCA will continue to write data to TDR until its buffer is empty, and this data will be lost. Fix/Workaround Disable the PDCA, add two NOPs, and disable the SPI. To continue the transfer, enable the SPI and PDCA. 3. SPI disable does not work in SLAVE mode SPI disable does not work in SLAVE mode. Fix/Workaround Read the last received data, then perform a software reset by writing a one to the Software Reset bit in the Control Register (CR.SWRST). 4. SPI bad serial clock generation on 2nd chip_select when SCBR=1, CPOL=1, and NCPHA=0 When multiple chip selects (CS) are in use, if one of the baudrates equal 1 while one (CSRn.SCBR=1) of the others do not equal 1, and CSRn.CPOL=1 and CSRn.NCPHA=0, then an additional pulse will be generated on SCK. Fix/Workaround When multiple CS are in use, if one of the baudrates equals 1, the others must also equal 1 if CSRn.CPOL=1 and CSRn.NCPHA=0. 5. SPI mode fault detection enable causes incorrect behavior When mode fault detection is enabled (MR.MODFDIS==0), the SPI module may not operate properly. Fix/Workaround Always disable mode fault detection before using the SPI by writing a one to MR.MODFDIS. 6. SPI RDR.PCS is not correct The PCS (Peripheral Chip Select) field in the SPI RDR (Receive Data Register) does not correctly indicate the value on the NPCS pins at the end of a transfer. Fix/Workaround Do not use the PCS field of the SPI RDR. 950 32142D–06/2013 ATUC64/128/256L3/4U 38.5.7 TWI 1. TWIS may not wake the device from sleep mode If the CPU is put to a sleep mode (except Idle and Frozen) directly after a TWI Start condition, the CPU may not wake upon a TWIS address match. The request is NACKed. Fix/Workaround When using the TWI address match to wake the device from sleep, do not switch to sleep modes deeper than Frozen. Another solution is to enable asynchronous EIC wake on the TWIS clock (TWCK) or TWIS data (TWD) pins, in order to wake the system up on bus events. 2. SMBALERT bit may be set after reset The SMBus Alert (SMBALERT) bit in the Status Register (SR) might be erroneously set after system reset. Fix/Workaround After system reset, clear the SR.SMBALERT bit before commencing any TWI transfer. 3. Clearing the NAK bit before the BTF bit is set locks up the TWI bus When the TWIS is in transmit mode, clearing the NAK Received (NAK) bit of the Status Register (SR) before the end of the Acknowledge/Not Acknowledge cycle will cause the TWIS to attempt to continue transmitting data, thus locking up the bus. Fix/Workaround Clear SR.NAK only after the Byte Transfer Finished (BTF) bit of the same register has been set. 4. TWIS stretch on Address match error When the TWIS stretches TWCK due to a slave address match, it also holds TWD low for the same duration if it is to be receiving data. When TWIS releases TWCK, it releases TWD at the same time. This can cause a TWI timing violation. Fix/Workaround None. 5. TWIM TWALM polarity is wrong The TWALM signal in the TWIM is active high instead of active low. Fix/Workaround Use an external inverter to invert the signal going into the TWIM. When using both TWIM and TWIS on the same pins, the TWALM cannot be used. 38.5.8 PWMA 1. The SR.READY bit cannot be cleared by writing to SCR.READY The Ready bit in the Status Register will not be cleared when writing a one to the corresponding bit in the Status Clear register. The Ready bit will be cleared when the Busy bit is set. Fix/Workaround Disable the Ready interrupt in the interrupt handler when receiving the interrupt. When an operation that triggers the Busy/Ready bit is started, wait until the ready bit is low in the Status Register before enabling the interrupt. 38.5.9 TC 1. Channel chaining skips first pulse for upper channel When chaining two channels using the Block Mode Register, the first pulse of the clock between the channels is skipped. 951 32142D–06/2013 ATUC64/128/256L3/4U Fix/Workaround Configure the lower channel with RA = 0x1 and RC = 0x2 to produce a dummy clock cycle for the upper channel. After the dummy cycle has been generated, indicated by the SR.CPCS bit, reconfigure the RA and RC registers for the lower channel with the real values. 38.5.10 ADCIFB 1. ADCIFB DMA transfer does not work with divided PBA clock DMA requests from the ADCIFB will not be performed when the PBA clock is slower than the HSB clock. Fix/Workaround Do not use divided PBA clock when the PDCA transfers from the ADCIFB. 38.5.11 CAT 1. CAT QMatrix sense capacitors discharged prematurely At the end of a QMatrix burst charging sequence that uses different burst count values for different Y lines, the Y lines may be incorrectly grounded for up to n-1 periods of the peripheral bus clock, where n is the ratio of the PB clock frequency to the GCLK_CAT frequency. This results in premature loss of charge from the sense capacitors and thus increased variability of the acquired count values. Fix/Workaround Enable the 1kOhm drive resistors on all implemented QMatrix Y lines (CSA 1, 3, 5, 7, 9, 11, 13, and/or 15) by writing ones to the corresponding odd bits of the CSARES register. 2. Autonomous CAT acquisition must be longer than AST source clock period When using the AST to trigger CAT autonomous touch acquisition in sleep modes where the CAT bus clock is turned off, the CAT will start several acquisitions if the period of the AST source clock is larger than one CAT acquisition. One AST clock period after the AST trigger, the CAT clock will automatically stop and the CAT acquisition can be stopped prematurely, ruining the result. Fix/Workaround Always ensure that the ATCFG1.max field is set so that the duration of the autonomous touch acquisition is greater than one clock period of the AST source clock. 3. CAT consumes unnecessary power when disabled or when autonomous touch not used A CAT prescaler controlled by the ATCFG0.DIV field will be active even when the CAT module is disabled or when the autonomous touch feature is not used, thereby causing unnecessary power consumption. Fix/Workaround If the CAT module is not used, disable the CLK_CAT clock in the PM module. If the CAT module is used but the autonomous touch feature is not used, the power consumption of the CAT module may be reduced by writing 0xFFFF to the ATCFG0.DIV field. 4. CAT module does not terminate QTouch burst on detect The CAT module does not terminate a QTouch burst when the detection voltage is reached on the sense capacitor. This can cause the sense capacitor to be charged more than necessary. Depending on the dielectric absorption characteristics of the capacitor, this can lead to unstable measurements. Fix/Workaround Use the minimum possible value for the MAX field in the ATCFG1, TG0CFG1, and TG1CFG1 registers. 952 32142D–06/2013 ATUC64/128/256L3/4U 38.5.12 aWire 1. aWire MEMORY_SPEED_REQUEST command does not return correct CV The aWire MEMORY_SPEED_REQUEST command does not return a CV corresponding to the formula in the aWire Debug Interface chapter. Fix/Workaround Issue a dummy read to address 0x100000000 before issuing the MEMORY_SPEED_REQUEST command and use this formula instead: 38.5.13 Flash 5. Corrupted data in flash may happen after flash page write operations After a flash page write operation from an external programmer, reading (data read or code fetch) in flash may fail. This may lead to an exception or to others errors derived from this corrupted read access. Fix/Workaround Before any flash page write operation, each write in the page buffer must preceded by a write in the page buffer with 0xFFFF_FFFF content at any address in the page. 38.5.14 I/O Pins 1. PA05 is not 3.3V tolerant. PA05 should be grounded on the PCB and left unused if VDDIO is above 1.8V. Fix/Workaround None. 2. No pull-up on pins that are not bonded PB13 to PB27 are not bonded on UC3L0256/128, but has no pull-up and can cause current consumption on VDDIO/VDDIN if left undriven. Fix/Workaround Enable pull-ups on PB13 to PB27 by writing 0x0FFFE000 to the PUERS1 register in the GPIO. 3. PA17 has low ESD tolerance PA17 only tolerates 500V ESD pulses (Human Body Model). Fix/Workaround Care must be taken during manufacturing and PCB design. f sab 7f aw CV – 3 = ---------------- 953 32142D–06/2013 ATUC64/128/256L3/4U 39. Datasheet Revision History Please note that the referring page numbers in this section are referred to this document. The referring revision in this section are referring to the document revision. 39.1 Rev. D – 06/2013 39.2 Rev. C – 01/2012 39.3 Rev. B – 12/2011 39.4 Rev. A – 12/2011 1. Updated the datasheet with a new ATmel blue logo and the last page. 2. Added Flash errata. 1. Description: DFLL frequency is 20 to 150MHz, not 40 to 150MHz. 2. Block Diagram: GCLK_IN is input, not output. CAT SMP corrected from I/O to output. SPI NPCS corrected from output to I/O. 3, Package and Pinout: EXTINT0 in Signal Descriptions table is NMI. 4, Supply and Startup Considerations: In 1.8V single supply mode figure, the input voltage is 1.62-1.98V, not 1.98-3.6V. “On system start-up, the DFLL is disabled” is replaced by “On system start-up, all high-speed clocks are disabled”. 5, ADCIFB: PRND signal removed from block diagram. 6, Electrical Charateristics: Added 64-pin package information to I/O Pin Characteristics tables and Digital Clock Characteristics table. 7, Mechanical Characteristics: QFN48 Package Drawing updated. Note that the package drawing for QFN48 is correct in datasheet rev A, but wrong in rev B. Added notes to package drawings. 8. Summary: Removed Programming and Debugging chapter, added Processor and Architecture chapter. 1. JTAG Data Registers subchapter added in the Programming and Debugging chapter, containing JTAG IDs. 1. Initial revision. i 32142D–06/2013 ATUC64/128/256L3/4U Table of Contents Features ..................................................................................................... 1 1 Description ............................................................................................... 3 2 Overview ................................................................................................... 5 2.1 Block Diagram ...................................................................................................5 2.2 Configuration Summary .....................................................................................6 3 Package and Pinout ................................................................................. 7 3.1 Package .............................................................................................................7 3.2 See Section 3.3 for a description of the various peripheral signals. ................12 3.3 Signal Descriptions ..........................................................................................15 3.4 I/O Line Considerations ...................................................................................18 4 Processor and Architecture .................................................................. 21 4.1 Features ..........................................................................................................21 4.2 AVR32 Architecture .........................................................................................21 4.3 The AVR32UC CPU ........................................................................................22 4.4 Programming Model ........................................................................................26 4.5 Exceptions and Interrupts ................................................................................30 5 Memories ................................................................................................ 35 5.1 Embedded Memories ......................................................................................35 5.2 Physical Memory Map .....................................................................................35 5.3 Peripheral Address Map ..................................................................................36 5.4 CPU Local Bus Mapping .................................................................................37 6 Supply and Startup Considerations ..................................................... 39 6.1 Supply Considerations .....................................................................................39 6.2 Startup Considerations ....................................................................................44 7 Peripheral DMA Controller (PDCA) ...................................................... 45 7.1 Features ..........................................................................................................45 7.2 Overview ..........................................................................................................45 7.3 Block Diagram .................................................................................................46 7.4 Product Dependencies ....................................................................................46 7.5 Functional Description .....................................................................................47 7.6 Performance Monitors .....................................................................................49 7.7 User Interface ..................................................................................................51 ii 32142D–06/2013 ATUC64/128/256L3/4U 7.8 Module Configuration ......................................................................................79 8 USB Interface (USBC) ............................................................................ 81 8.1 Features ..........................................................................................................81 8.2 Overview ..........................................................................................................81 8.3 Block Diagram .................................................................................................81 8.4 I/O Lines Description .......................................................................................83 8.5 Product Dependencies ....................................................................................84 8.6 Functional Description .....................................................................................85 8.7 User Interface ...............................................................................................101 8.8 Module Configuration ....................................................................................134 9 Flash Controller (FLASHCDW) ........................................................... 135 9.1 Features ........................................................................................................135 9.2 Overview ........................................................................................................135 9.3 Product Dependencies ..................................................................................135 9.4 Functional Description ...................................................................................136 9.5 Flash Commands ..........................................................................................141 9.6 General-purpose Fuse Bits ............................................................................143 9.7 Security Bit ....................................................................................................146 9.8 User Interface ................................................................................................147 9.9 Fuse Settings .................................................................................................157 9.10 Serial Number ................................................................................................160 9.11 Module Configuration ....................................................................................160 10 Secure Access Unit (SAU) .................................................................. 162 10.1 Features ........................................................................................................162 10.2 Overview ........................................................................................................162 10.3 Block Diagram ...............................................................................................163 10.4 Product Dependencies ..................................................................................164 10.5 Functional Description ...................................................................................164 10.6 User Interface ................................................................................................168 10.7 Module Configuration ....................................................................................183 11 HSB Bus Matrix (HMATRIXB) .............................................................. 184 11.1 Features ........................................................................................................184 11.2 Overview ........................................................................................................184 11.3 Product Dependencies ..................................................................................184 11.4 Functional Description ...................................................................................184 iii 32142D–06/2013 ATUC64/128/256L3/4U 11.5 User Interface ................................................................................................188 11.6 Module Configuration ....................................................................................196 12 Interrupt Controller (INTC) .................................................................. 198 12.1 Features ........................................................................................................198 12.2 Overview ........................................................................................................198 12.3 Block Diagram ...............................................................................................198 12.4 Product Dependencies ..................................................................................199 12.5 Functional Description ...................................................................................199 12.6 User Interface ................................................................................................202 12.7 Module Configuration ....................................................................................206 12.8 Interrupt Request Signal Map ........................................................................206 13 Power Manager (PM) ............................................................................ 209 13.1 Features ........................................................................................................209 13.2 Overview ........................................................................................................209 13.3 Block Diagram ...............................................................................................210 13.4 I/O Lines Description .....................................................................................210 13.5 Product Dependencies ..................................................................................210 13.6 Functional Description ...................................................................................211 13.7 User Interface ................................................................................................220 13.8 Module Configuration ....................................................................................243 14 System Control Interface (SCIF) ......................................................... 244 14.1 Features ........................................................................................................244 14.2 Overview ........................................................................................................244 14.3 I/O Lines Description .....................................................................................244 14.4 Product Dependencies ..................................................................................244 14.5 Functional Description ...................................................................................245 14.6 User Interface ................................................................................................265 14.7 Module Configuration ....................................................................................318 15 Asynchronous Timer (AST) ................................................................ 322 15.1 Features ........................................................................................................322 15.2 Overview ........................................................................................................322 15.3 Block Diagram ...............................................................................................323 15.4 Product Dependencies ..................................................................................323 15.5 Functional Description ...................................................................................324 15.6 User Interface ................................................................................................330 iv 32142D–06/2013 ATUC64/128/256L3/4U 15.7 Module Configuration ....................................................................................351 16 Watchdog Timer (WDT) ....................................................................... 352 16.1 Features ........................................................................................................352 16.2 Overview ........................................................................................................352 16.3 Block Diagram ...............................................................................................352 16.4 Product Dependencies ..................................................................................352 16.5 Functional Description ...................................................................................353 16.6 User Interface ................................................................................................358 16.7 Module Configuration ....................................................................................364 17 External Interrupt Controller (EIC) ..................................................... 365 17.1 Features ........................................................................................................365 17.2 Overview ........................................................................................................365 17.3 Block Diagram ...............................................................................................365 17.4 I/O Lines Description .....................................................................................366 17.5 Product Dependencies ..................................................................................366 17.6 Functional Description ...................................................................................366 17.7 User Interface ................................................................................................370 17.8 Module Configuration ....................................................................................386 18 Frequency Meter (FREQM) .................................................................. 387 18.1 Features ........................................................................................................387 18.2 Overview ........................................................................................................387 18.3 Block Diagram ...............................................................................................387 18.4 Product Dependencies ..................................................................................387 18.5 Functional Description ...................................................................................388 18.6 User Interface ................................................................................................390 18.7 Module Configuration ....................................................................................401 19 General-Purpose Input/Output Controller (GPIO) ............................. 403 19.1 Features ........................................................................................................403 19.2 Overview ........................................................................................................403 19.3 Block Diagram ...............................................................................................403 19.4 I/O Lines Description .....................................................................................404 19.5 Product Dependencies ..................................................................................404 19.6 Functional Description ...................................................................................405 19.7 User Interface ................................................................................................410 19.8 Module Configuration ....................................................................................433 v 32142D–06/2013 ATUC64/128/256L3/4U 20 Universal Synchronous Asynchronous Receiver Transmitter (USART) 434 20.1 Features ........................................................................................................434 20.2 Overview ........................................................................................................434 20.3 Block Diagram ...............................................................................................435 20.4 I/O Lines Description ....................................................................................436 20.5 Product Dependencies ..................................................................................436 20.6 Functional Description ...................................................................................437 20.7 User Interface ................................................................................................463 20.8 Module Configuration ....................................................................................485 21 Serial Peripheral Interface (SPI) ......................................................... 486 21.1 Features ........................................................................................................486 21.2 Overview ........................................................................................................486 21.3 Block Diagram ...............................................................................................487 21.4 Application Block Diagram .............................................................................487 21.5 I/O Lines Description .....................................................................................488 21.6 Product Dependencies ..................................................................................488 21.7 Functional Description ...................................................................................488 21.8 User Interface ................................................................................................499 21.9 Module Configuration ....................................................................................526 22 Two-wire Master Interface (TWIM) ...................................................... 527 22.1 Features ........................................................................................................527 22.2 Overview ........................................................................................................527 22.3 List of Abbreviations ......................................................................................528 22.4 Block Diagram ...............................................................................................528 22.5 Application Block Diagram .............................................................................529 22.6 I/O Lines Description .....................................................................................529 22.7 Product Dependencies ..................................................................................529 22.8 Functional Description ...................................................................................531 22.9 User Interface ................................................................................................543 22.10 Module Configuration ....................................................................................560 23 Two-wire Slave Interface (TWIS) ......................................................... 561 23.1 Features ........................................................................................................561 23.2 Overview ........................................................................................................561 23.3 List of Abbreviations ......................................................................................562 vi 32142D–06/2013 ATUC64/128/256L3/4U 23.4 Block Diagram ...............................................................................................562 23.5 Application Block Diagram .............................................................................563 23.6 I/O Lines Description .....................................................................................563 23.7 Product Dependencies ..................................................................................563 23.8 Functional Description ...................................................................................564 23.9 User Interface ................................................................................................574 23.10 Module Configuration ....................................................................................590 24 Inter-IC Sound Controller (IISC) .......................................................... 591 24.1 Features ........................................................................................................591 24.2 Overview ........................................................................................................591 24.3 Block Diagram ...............................................................................................592 24.4 I/O Lines Description .....................................................................................592 24.5 Product Dependencies ..................................................................................592 24.6 Functional Description ...................................................................................593 24.7 IISC Application Examples ............................................................................598 24.8 User Interface ................................................................................................600 24.9 Module configuration .....................................................................................614 25 Pulse Width Modulation Controller (PWMA) ..................................... 615 25.1 Features ........................................................................................................615 25.2 Overview ........................................................................................................615 25.3 Block Diagram ...............................................................................................616 25.4 I/O Lines Description .....................................................................................616 25.5 Product Dependencies ..................................................................................616 25.6 Functional Description ...................................................................................617 25.7 User Interface ................................................................................................623 25.8 Module Configuration ....................................................................................641 26 Timer/Counter (TC) .............................................................................. 642 26.1 Features ........................................................................................................642 26.2 Overview ........................................................................................................642 26.3 Block Diagram ...............................................................................................643 26.4 I/O Lines Description .....................................................................................643 26.5 Product Dependencies ..................................................................................643 26.6 Functional Description ...................................................................................644 26.7 User Interface ................................................................................................659 26.8 Module Configuration ....................................................................................682 vii 32142D–06/2013 ATUC64/128/256L3/4U 27 Peripheral Event System ..................................................................... 683 27.1 Features ........................................................................................................683 27.2 Overview ........................................................................................................683 27.3 Peripheral Event System Block Diagram .......................................................683 27.4 Functional Description ...................................................................................683 27.5 Application Example ......................................................................................686 28 Audio Bit Stream DAC (ABDACB) ...................................................... 687 28.1 Features ........................................................................................................687 28.2 Overview ........................................................................................................687 28.3 Block Diagram ...............................................................................................687 28.4 I/O Lines Description .....................................................................................688 28.5 Product Dependencies ..................................................................................688 28.6 Functional Description ...................................................................................689 28.7 User Interface ................................................................................................696 28.8 Module Configuration ....................................................................................710 29 ADC Interface (ADCIFB) ...................................................................... 711 29.1 Features ........................................................................................................711 29.2 Overview ........................................................................................................711 29.3 Block Diagram ...............................................................................................712 29.4 I/O Lines Description .....................................................................................713 29.5 Product Dependencies ..................................................................................713 29.6 Functional Description ...................................................................................714 29.7 Resistive Touch Screen .................................................................................718 29.8 Operating Modes ...........................................................................................724 29.9 User Interface ................................................................................................726 29.10 Module Configuration ....................................................................................745 30 Analog Comparator Interface (ACIFB) ............................................... 746 30.1 Features ........................................................................................................746 30.2 Overview ........................................................................................................746 30.3 Block Diagram ...............................................................................................747 30.4 I/O Lines Description .....................................................................................747 30.5 Product Dependencies ..................................................................................748 30.6 Functional Description ...................................................................................749 30.7 Peripheral Event Triggers ..............................................................................754 30.8 AC Test mode ................................................................................................754 viii 32142D–06/2013 ATUC64/128/256L3/4U 30.9 User Interface ................................................................................................755 30.10 Module Configuration ....................................................................................769 31 Capacitive Touch Module (CAT) ......................................................... 770 31.1 Features ........................................................................................................770 31.2 Overview ........................................................................................................770 31.3 Block Diagram ...............................................................................................771 31.4 I/O Lines Description .....................................................................................771 31.5 Product Dependencies ..................................................................................772 31.6 Functional Description ...................................................................................774 31.7 User Interface ................................................................................................781 31.8 Module Configuration ....................................................................................816 32 Glue Logic Controller (GLOC) ............................................................ 817 32.1 Features ........................................................................................................817 32.2 Overview ........................................................................................................817 32.3 Block Diagram ...............................................................................................817 32.4 I/O Lines Description .....................................................................................818 32.5 Product Dependencies ..................................................................................818 32.6 Functional Description ...................................................................................818 32.7 User Interface ................................................................................................820 32.8 Module Configuration ....................................................................................825 33 aWire UART (AW) ................................................................................. 826 33.1 Features ........................................................................................................826 33.2 Overview ........................................................................................................826 33.3 Block Diagram ...............................................................................................826 33.4 I/O Lines Description .....................................................................................827 33.5 Product Dependencies ..................................................................................827 33.6 Functional Description ...................................................................................827 33.7 User Interface ................................................................................................830 33.8 Module Configuration ....................................................................................843 34 Programming and Debugging ............................................................ 844 34.1 Overview ........................................................................................................844 34.2 Service Access Bus .......................................................................................844 34.3 On-Chip Debug ..............................................................................................847 34.4 JTAG and Boundary-scan (JTAG) .................................................................855 34.5 JTAG Instruction Summary ...........................................................................863 ix 32142D–06/2013 ATUC64/128/256L3/4U 34.6 aWire Debug Interface (AW) .........................................................................880 35 Electrical Characteristics .................................................................... 897 35.1 Absolute Maximum Ratings* .........................................................................897 35.2 Supply Characteristics ...................................................................................897 35.3 Maximum Clock Frequencies ........................................................................898 35.4 Power Consumption ......................................................................................898 35.5 I/O Pin Characteristics ...................................................................................902 35.6 Oscillator Characteristics ...............................................................................905 35.7 Flash Characteristics .....................................................................................910 35.8 ABDACB Electrical Characteristics. .............................................................911 35.9 Analog Characteristics ...................................................................................912 35.10 Timing Characteristics ...................................................................................921 36 Mechanical Characteristics ................................................................. 931 36.1 Thermal Considerations ................................................................................931 36.2 Package Drawings .........................................................................................932 36.3 Soldering Profile ............................................................................................937 37 Ordering Information ........................................................................... 938 38 Errata ..................................................................................................... 940 38.1 Rev. C ............................................................................................................940 38.2 Flash ..............................................................................................................942 38.3 Rev. B ............................................................................................................942 38.4 Flash .............................................................................................................946 38.5 Rev. A ............................................................................................................946 39 Datasheet Revision History ................................................................ 953 39.1 Rev. D – 06/2013 ...........................................................................................953 39.2 Rev. C – 01/2012 ...........................................................................................953 39.3 Rev. B – 12/2011 ...........................................................................................953 39.4 Rev. A – 12/2011 ...........................................................................................953 Table of Contents....................................................................................... i Atmel Corporation 1600 Technology Drive San Jose, CA 95110 USA Tel: (+1) (408) 441-0311 Fax: (+1) (408) 487-2600 www.atmel.com Atmel Asia Limited Unit 01-5 & 16, 19F BEA Tower, Millennium City 5 418 Kwun Tong Roa Kwun Tong, Kowloon HONG KONG Tel: (+852) 2245-6100 Fax: (+852) 2722-1369 Atmel Munich GmbH Business Campus Parkring 4 D-85748 Garching b. Munich GERMANY Tel: (+49) 89-31970-0 Fax: (+49) 89-3194621 Atmel Japan G.K. 16F Shin-Osaki Kangyo Bldg 1-6-4 Osaki, Shinagawa-ku Tokyo 141-0032 JAPAN Tel: (+81) (3) 6417-0300 Fax: (+81) (3) 6417-0370 © 2013 Atmel Corporation. All rights reserved. / Rev.: 32142D–AVR32–06/2013 Atmel®, logo and combinations thereof, AVR®, picoPower®, QTouch®, AKS® and others are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. Other terms and product names may be trademarks of others. Disclaimer: The information in this document is provided in connection with Atmel products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Atmel products. EXCEPT AS SET FORTH IN THE ATMEL TERMS AND CONDITIONS OF SALES LOCATED ON THE ATMEL WEBSITE, ATMEL ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS AND PROFITS, BUSINESS INTERRUPTION, OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF ATMEL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Atmel makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and products descriptions at any time without notice. Atmel does not make any commitment to update the information contained herein. Unless specifically provided otherwise, Atmel products are not suitable for, and shall not be used in, automotive applications. Atmel products are not intended, authorized, or warranted for use as components in applications intended to support or sustain life.  2015 Microchip Technology Inc. DS00001625B-page 1 General Description The CAP1133, which incorporates RightTouch® technology, is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains three (3) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1133 also contains three (3) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. The CAP1133 includes Multiple Pattern Touch recognition that allows the user to select a specific set of buttons to be touched simultaneously. If this pattern is detected, then a status bit is set and an interrupt generated. Additionally, the CAP1133 includes circuitry and support for enhanced sensor proximity detection. The CAP1133 offers multiple power states operating at low quiescent currents. In the Standby state of operation, one or more capacitive touch sensor inputs are active and all LEDs may be used. Deep Sleep is the lowest power state available, drawing 5uA (typical) of current. In this state, no sensor inputs are active. Communications will wake the device. Applications • Desktop and Notebook PCs • LCD Monitors • Consumer Electronics • Appliances Features • Three (3) Capacitive Touch Sensor Inputs - Programmable sensitivity - Automatic recalibration - Individual thresholds for each button • Proximity Detection • Multiple Button Pattern Detection • Calibrates for Parasitic Capacitance • Analog Filtering for System Noise Sources • Press and Hold feature for Volume-like Applications • SMBus / I2C Compliant Communication Interface • Low Power Operation - 5uA quiescent current in Deep Sleep - 50uA quiescent current in Standby (1 sensor input monitored) - Samples one or more channels in Standby • Three (3) LED Driver Outputs - Open Drain or Push-Pull - Programmable blink, breathe, and dimness controls - Can be linked to Capacitive Touch Sensor inputs • Available in 10-pin 3mm x 3mm RoHS compliant DFN package CAP1133 3 Channel Capacitive Touch Sensor with 3 LED Drivers CAP1133 DS00001625B-page 2  2015 Microchip Technology Inc. TO OUR VALUED CUSTOMERS It is our intention to provide our valued customers with the best documentation possible to ensure successful use of your Microchip products. To this end, we will continue to improve our publications to better suit your needs. Our publications will be refined and enhanced as new volumes and updates are introduced. If you have any questions or comments regarding this publication, please contact the Marketing Communications Department via E-mail at docerrors@microchip.com. We welcome your feedback. Most Current Data Sheet To obtain the most up-to-date version of this data sheet, please register at our Worldwide Web site at: http://www.microchip.com You can determine the version of a data sheet by examining its literature number found on the bottom outside corner of any page. The last character of the literature number is the version number, (e.g., DS30000000A is version A of document DS30000000). Errata An errata sheet, describing minor operational differences from the data sheet and recommended workarounds, may exist for current devices. As device/documentation issues become known to us, we will publish an errata sheet. The errata will specify the revision of silicon and revision of document to which it applies. To determine if an errata sheet exists for a particular device, please check with one of the following: • Microchip’s Worldwide Web site; http://www.microchip.com • Your local Microchip sales office (see last page) When contacting a sales office, please specify which device, revision of silicon and data sheet (include -literature number) you are using. Customer Notification System Register on our web site at www.microchip.com to receive the most current information on all of our products.  2015 Microchip Technology Inc. DS00001625B-page 3 CAP1133 Table of Contents 1.0 Block Diagram ................................................................................................................................................................................. 4 2.0 Pin Description ................................................................................................................................................................................ 5 3.0 Electrical Specifications .................................................................................................................................................................. 9 4.0 Communications ........................................................................................................................................................................... 12 5.0 General Description ...................................................................................................................................................................... 23 6.0 Register Description ...................................................................................................................................................................... 29 7.0 Package Information ..................................................................................................................................................................... 67 Appendix A: Device Delta ................................................................................................................................................................... 72 Appendix B: Data Sheet Revision History ........................................................................................................................................... 74 The Microchip Web Site ...................................................................................................................................................................... 76 Customer Change Notification Service ............................................................................................................................................... 76 Customer Support ............................................................................................................................................................................... 76 Product Identification System ............................................................................................................................................................. 77 CAP1133 DS00001625B-page 4  2015 Microchip Technology Inc. 1.0 BLOCK DIAGRAM SMBus Slave Protocol SMCLK SMDATA VDD GND ALERT# Capacitive Touch Sensing Algorithm CS1 CS2 CS3 LED1 LED Driver, Breathe, and Dimness control LED2 LED3  2015 Microchip Technology Inc. DS00001625B-page 5 CAP1133 2.0 PIN DESCRIPTION FIGURE 2-1: CAP1133 Pin Diagram (10-Pin DFN) TABLE 2-1: PIN DESCRIPTION FOR CAP1133 Pin Number Pin Name Pin Function Pin Type Unused Connection 1 ALERT# Active low alert / interrupt output usable for SMBus alert OD (5V) Connect to Ground Active high alert / interrupt output usable for SMBus alert DO leave open 2 SMDATA Bi-directional, open-drain SMBus data - requires pull-up DIOD (5V) n/a 3 SMCLK SMBus clock input - requires pull-up resistor DI (5V) 4 VDD Positive Power supply Power n/a 5 LED1 Open drain LED 1 driver (default) OD (5V) Connect to Ground Push-pull LED 1 driver DO leave open or connect to Ground 6 LED2 Open drain LED 2 driver (default) OD (5V) Connect to Ground Push-pull LED 2 driver DO leave open or connect to Ground 7 LED3 Open drain LED 3 driver (default) OD (5V) Connect to Ground Push-pull LED 3 driver DO leave open or connect to Ground GND CS2 1 CS1 2 3 4 5 CS3 LED1 ALERT# SMDATA VDD SMCLK LED3 LED2 CAP1133 3mm x 3mm DFN 10 9 8 7 6 CAP1133 DS00001625B-page 6  2015 Microchip Technology Inc. APPLICATION NOTE: When the ALERT# pinis configured as an active low output, it will be open drain. When it is configured as an active high output, it will be push-pull. APPLICATION NOTE: For the 5V tolerant pins that have a pull-up resistor, the pull-up voltage must not exceed 3.6V when the CAP1133 is unpowered. The pin types are described in Table 2-2. All pins labeled with (5V) are 5V tolerant. 8 CS3 Capacitive Touch Sensor Input 3 AIO Connect to Ground 9 CS2 Capacitive Touch Sensor Input 2 AIO Connect to Ground 10 CS1 Capacitive Touch Sensor Input 1 AIO Connect to Ground Bottom Pad GND Ground Power n/a TABLE 2-2: PIN TYPES Pin Type Description Power This pin is used to supply power or ground to the device. DI Digital Input - This pin is used as a digital input. This pin is 5V tolerant. AIO Analog Input / Output -This pin is used as an I/O for analog signals. DIOD Digital Input / Open Drain Output - This pin is used as a digital I/O. When it is used as an output, it is open drain and requires a pull-up resistor. This pin is 5V tolerant. OD Open Drain Digital Output - This pin is used as a digital output. It is open drain and requires a pull-up resistor. This pin is 5V tolerant. DO Push-pull Digital Output - This pin is used as a digital output and can sink and source current. DIO Push-pull Digital Input / Output - This pin is used as an I/O for digital signals. TABLE 2-1: PIN DESCRIPTION FOR CAP1133 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection  2015 Microchip Technology Inc. DS00001625B-page 7 CAP1133 3.0 ELECTRICAL SPECIFICATIONS Note 3-1 Stresses above those listed could cause permanent damage to the device. This is a stress rating only and functional operation of the device at any other condition above those indicated in the operation sections of this specification is not implied. Note 3-2 For the 5V tolerant pins that have a pull-up resistor, the voltage difference between V5VT_PIN and VDD must never exceed 3.6V. Note 3-3 The Package Power Dissipation specification assumes a recommended thermal via design consisting of a 2x2 matrix of 0.3mm (12mil) vias at 1.0mm pitch connected to the ground plane with a 1.6 x 2.3mm thermal landing. TABLE 3-1: ABSOLUTE MAXIMUM RATINGS Voltage on 5V tolerant pins (V5VT_PIN) -0.3 to 5.5 V Voltage on 5V tolerant pins (|V5VT_PIN - VDD|) Note 3-2 0 to 3.6 V Voltage on VDD pin -0.3 to 4 V Voltage on any other pin to GND -0.3 to VDD + 0.3 V Package Power Dissipation up to TA = 85°C for 10 pin DFN (see Note 3-3) 0.7 W Junction to Ambient (θJA) 77.7 °C/W Operating Ambient Temperature Range -40 to 125 °C Storage Temperature Range -55 to 150 °C ESD Rating, All Pins, HBM 8000 V CAP1133 DS00001625B-page 8  2015 Microchip Technology Inc. TABLE 3-2: ELECTRICAL SPECIFICATIONS VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions DC Power Supply Voltage VDD 3.0 3.3 3.6 V Supply Current ISTBY 120 170 uA Standby state active 1 sensor input monitored No LEDs active Default conditions (8 avg, 70ms cycle time) ISTBY 50 uA Standby state active 1 sensor input monitored No LEDs active 1 avg, 140ms cycle time, IDSLEEP 5 15 uA Deep Sleep state active LEDs at 100% or 0% Duty Cycle No communications TA < 40°C 3.135 < VDD < 3.465V IDD 500 600 uA Capacitive Sensing Active No LEDs active Capacitive Touch Sensor Inputs Maximum Base Capacitance CBASE 50 pF Pad untouched Minimum Detectable Capacitive Shift ΔCTOUCH 20 fF Pad touched - default conditions (1 avg, 35ms cycle time, 1x sensitivity) Recommended Cap Shift ΔCTOUCH 0.1 2 pF Pad touched - Not tested Power Supply Rejection PSR ±3 ±10 counts / V Untouched Current Counts Base Capacitance 5pF - 50pF Maximum sensitivity Negative Delta Counts disabled All other parameters default Timing Time to communications ready tCOMM_DLY 15 ms Time to first conversion ready tCONV_DLY 170 200 ms LED Drivers Duty Cycle DUTYLED 0 100 % Programmable Drive Frequency fLED 2 kHz Sinking Current ISINK 24 mA VOL = 0.4 Sourcing Current ISOURCE 24 mA VOH = VDD - 0.4 Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered I/O Pins Output Low Voltage VOL 0.4 V ISINK_IO = 8mA Output High Voltage VOH VDD - 0.4 V ISOURCE_IO = 8mA Input High Voltage VIH 2.0 V  2015 Microchip Technology Inc. DS00001625B-page 9 CAP1133 Note 3-4 The ALERT pin will not glitch high or low at power up if connected to VDD or another voltage. Note 3-5 The SMCLK and SMDATA pins will not glitch low at power up if connected to VDD or another voltage. Input Low Voltage VIL 0.8 V Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered SMBus Timing Input Capacitance CIN 5 pF Clock Frequency fSMB 10 400 kHz Spike Suppression tSP 50 ns Bus Free Time Stop to Start tBUF 1.3 us Start Setup Time tSU:STA 0.6 us Start Hold Time tHD:STA 0.6 us Stop Setup Time tSU:STO 0.6 us Data Hold Time tHD:DAT 0 us When transmitting to the master Data Hold Time tHD:DAT 0.3 us When receiving from the master Data Setup Time tSU:DAT 0.6 us Clock Low Period tLOW 1.3 us Clock High Period tHIGH 0.6 us Clock / Data Fall Time tFALL 300 ns Min = 20+0.1CLOAD ns Clock / Data Rise Time tRISE 300 ns Min = 20+0.1CLOAD ns Capacitive Load CLOAD 400 pF per bus line TABLE 3-2: ELECTRICAL SPECIFICATIONS (CONTINUED) VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions CAP1133 DS00001625B-page 10  2015 Microchip Technology Inc. 4.0 COMMUNICATIONS 4.1 Communications The CAP1133 communicates using the SMBus or I2C protocol. The supports the following protocols: Send Byte, Receive Byte, Read Byte, Write Byte, Read Block, and Write Block. In addition, the device supports I2C formatting for block read and block write protocols. 4.2 System Management Bus The CAP1133 communicates with a host controller, such as an SIO, through the SMBus. The SMBus is a two-wire serial communication protocol between a computer host and its peripheral devices. A detailed timing diagram is shown in Figure 4-1. Stretching of the SMCLK signal is supported; however, the CAP1133 will not stretch the clock signal. 4.2.1 SMBUS START BIT The SMBus Start bit is defined as a transition of the SMBus Data line from a logic ‘1’ state to a logic ‘0’ state while the SMBus Clock line is in a logic ‘1’ state. 4.2.2 SMBUS ADDRESS AND RD / WR BIT The SMBus Address Byte consists of the 7-bit slave address followed by the RD / WR indicator bit. If this RD / WR bit is a logic ‘0’, then the SMBus Host is writing data to the slave device. If this RD / WR bit is a logic ‘1’, then the SMBus Host is reading data from the slave device. The CAP1133 responds to SMBus address 0101_000(r/w). 4.2.3 SMBUS DATA BYTES All SMBus Data bytes are sent most significant bit first and composed of 8-bits of information. 4.2.4 SMBUS ACK AND NACK BITS The SMBus slave will acknowledge all data bytes that it receives. This is done by the slave device pulling the SMBus Data line low after the 8th bit of each byte that is transmitted. This applies to both the Write Byte and Block Write protocols. The Host will NACK (not acknowledge) the last data byte to be received from the slave by holding the SMBus data line high after the 8th data bit has been sent. For the Block Read protocol, the Host will ACK each data byte that it receives except the last data byte. FIGURE 4-1: SMBus Timing Diagram SMDATA SMCLK TLOW TRISE THIGH TFALL TBUF THD:STA P S S - Start Condition P - Stop Condition THD:DAT TSU:DAT TSU:STA THD:STA P TSU:STO S  2015 Microchip Technology Inc. DS00001625B-page 11 CAP1133 4.2.5 SMBUS STOP BIT The SMBus Stop bit is defined as a transition of the SMBus Data line from a logic ‘0’ state to a logic ‘1’ state while the SMBus clock line is in a logic ‘1’ state. When the CAP1133 detects an SMBus Stop bit and it has been communicating with the SMBus protocol, it will reset its slave interface and prepare to receive further communications. 4.2.6 SMBUS TIMEOUT The CAP1133 includes an SMBus timeout feature. Following a 30ms period of inactivity on the SMBus where the SMCLK pin is held low, the device will timeout and reset the SMBus interface. The timeout function defaults to disabled. It can be enabled by setting the TIMEOUT bit in the Configuration register (see Section 6.6, "Configuration Registers"). 4.2.7 SMBUS AND I2C COMPATIBILITY The major differences between SMBus and I2C devices are highlighted here. For more information, refer to the SMBus 2.0 and I2C specifications. For information on using the CAP1133 in an I2C system, refer to AN 14.0 Dedicated Slave Devices in I2C Systems. 1. CAP1133 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. 2. Minimum frequency for SMBus communications is 10kHz. 3. The SMBus slave protocol will reset if the clock is held at a logic ‘0’ for longer than 30ms. This timeout functionality is disabled by default in the CAP1133 and can be enabled by writing to the TIMEOUT bit. I2C does not have a timeout. 4. The SMBus slave protocol will reset if both the clock and data lines are held at a logic ‘1’ for longer than 200µs (idle condition). This function is disabled by default in the CAP1133 and can be enabled by writing to the TIMEOUT bit. I2C does not have an idle condition. 5. I2C devices do not support the Alert Response Address functionality (which is optional for SMBus). 6. I2C devices support block read and write differently. I2C protocol allows for unlimited number of bytes to be sent in either direction. The SMBus protocol requires that an additional data byte indicating number of bytes to read / write is transmitted. The CAP1133 supports I2C formatting only. 4.3 SMBus Protocols The CAP1133 is SMBus 2.0 compatible and supports Write Byte, Read Byte, Send Byte, and Receive Byte as valid protocols as shown below. All of the below protocols use the convention in Table 4-1. 4.3.1 SMBUS WRITE BYTE The Write Byte is used to write one byte of data to a specific register as shown in Table 4-2. 4.3.2 SMBUS READ BYTE The Read Byte protocol is used to read one byte of data from the registers as shown in Table 4-3. TABLE 4-1: PROTOCOL FORMAT Data Sent to Device Data Sent to the HOst Data sent Data sent TABLE 4-2: WRITE BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK Stop 1 ->0 0101_000 0 0 XXh 0 XXh 0 0 -> 1 CAP1133 DS00001625B-page 12  2015 Microchip Technology Inc. 4.3.3 SMBUS SEND BYTE The Send Byte protocol is used to set the internal address register pointer to the correct address location. No data is transferred during the Send Byte protocol as shown in Table 4-4. APPLICATION NOTE: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.3.4 SMBUS RECEIVE BYTE The Receive Byte protocol is used to read data from a register when the internal register address pointer is known to be at the right location (e.g., set via Send Byte). This is used for consecutive reads of the same register as shown in Table 4-5. APPLICATION NOTE: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.4 I2C Protocols The CAP1133 supports I2C Block Write and Block Read. The protocols listed below use the convention in Table 4-1. 4.4.1 BLOCK WRITE The Block Write is used to write multiple data bytes to a group of contiguous registers as shown in Table 4-6. APPLICATION NOTE: When using the Block Write protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.4.2 BLOCK READ The Block Read is used to read multiple data bytes from a group of contiguous registers as shown in Table 4-7. APPLICATION NOTE: When using the Block Read protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. TABLE 4-3: READ BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data NACK Stop 1->0 0101_000 0 0 XXh 0 1 ->0 0101_000 1 0 XXh 1 0 -> 1 TABLE 4-4: SEND BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Stop 1 -> 0 0101_000 0 0 XXh 0 0 -> 1 TABLE 4-5: RECEIVE BYTE PROTOCOL Start Slave Address RD ACK Register Data NACK Stop 1 -> 0 0101_000 1 0 XXh 1 0 -> 1 TABLE 4-6: BLOCK WRITE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK 1 ->0 0101_000 0 0 XXh 0 XXh 0 Register Data ACK Register Data ACK . . . Register Data ACK Stop XXh 0 XXh 0 . . . XXh 0 0 -> 1  2015 Microchip Technology Inc. DS00001625B-page 13 CAP1133 TABLE 4-7: BLOCK READ PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data 1->0 0101_000 0 0 XXh 0 1 ->0 0101_000 1 0 XXh ACK Register Data ACK Register Data ACK Register Data ACK . . . Register Data NACK Stop 0 XXh 0 XXh 0 XXh 0 . . . XXh 1 0 -> 1 CAP1133 DS00001625B-page 14  2015 Microchip Technology Inc. 5.0 GENERAL DESCRIPTION The CAP1133 is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains three (3) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1133 also contains three (3) low side (or push-pull) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. The CAP1133 offers multiple power states. It operates at the lowest quiescent current during its Deep Sleep state. In the low power Standby state, it can monitor one or more channels and respond to communications normally. The device communicates with a host controller using SMBus / I2C. The host controller may poll the device for updated information at any time or it may configure the device to flag an interrupt whenever a touch is detected on any sensor pad. A typical system diagram is shown in Figure 5-1. 5.1 Power States The CAP1133 has three operating states depending on the status of the STBY and DSLEEP bits. When the device transitions between power states, previously detected touches (for inactive channels) are cleared and the status bits reset. 1. Fully Active - The device is fully active. It is monitoring all active capacitive sensor inputs and driving all LED channels as defined. 2. Standby - The device is in a lower power state. It will measure a programmable number of channels using the Standby Configuration controls (see Section 6.20 through Section 6.22). Interrupts will still be generated based on the active channels. The device will still respond to communications normally and can be returned to the Fully Active state of operation by clearing the STBY bit. FIGURE 5-1: System Diagram for CAP1133 CAP1133 LED3 SMDATA SMCLK Embedded Controller VDD ALERT# LED2 LED1 CS3 CS2 CS1 Touch Button Touch Button Touch Button 3.3V – 5V  2015 Microchip Technology Inc. DS00001625B-page 15 CAP1133 3. Deep Sleep - The device is in its lowest power state. It is not monitoring any capacitive sensor inputs and not driving any LEDs. All LEDs will be driven to their programmed non-actuated state and no PWM operations will be done. While in Deep Sleep, the device can be awakened by SMBus communications targeting the device. This will not cause the DSLEEP to be cleared so the device will return to Deep Sleep once all communications have stopped. APPLICATION NOTE: In the Deep Sleep state, the LED output will be either high or low and will not be PWM’d at the min or max duty cycle. 5.2 LED Drivers The CAP1133 contains three (3) LED drivers. Each LED driver can be linked to its respective capacitive touch sensor input or it can be controlled by the host. Each LED driver can be configured to operate in one of the following modes with either push-pull or open drain drive. 1. Direct - The LED is configured to be on or off when the corresponding input stimulus is on or off (or inverted). The brightness of the LED can be programmed from full off to full on (default). Additionally, the LED contains controls to individually configure ramping on, off, and turn-off delay. 2. Pulse 1 - The LED is configured to “Pulse” (transition ON-OFF-ON) a programmable number of times with programmable rate and min / max brightness. This behavior may be actuated when a press is detected or when a release is detected. 3. Pulse 2 - The LED is configured to “Pulse” while actuated and then “Pulse” a programmable number of times with programmable rate and min / max brightness when the sensor pad is released. 4. Breathe - The LED is configured to transition continuously ON-OFF-ON (i.e. to “Breathe”) with a programmable rate and min / max brightness. When an LED is not linked to a sensor and is actuated by the host, there’s an option to assert the ALERT# pin when the initiated LED behavior has completed. 5.2.1 LINKING LEDS TO CAPACITIVE TOUCH SENSOR INPUTS All LEDs can be linked to the corresponding capacitive touch sensor input so that when the sensor input detects a touch, the corresponding LED will be actuated at one of the programmed responses. 5.3 Capacitive Touch Sensing The CAP1133 contains three (3) independent capacitive touch sensor inputs. Each sensor input has dynamic range to detect a change of capacitance due to a touch. Additionally, each sensor input can be configured to be automatically and routinely re-calibrated. 5.3.1 SENSING CYCLE Each capacitive touch sensor input has controls to be activated and included in the sensing cycle. When the device is active, it automatically initiates a sensing cycle and repeats the cycle every time it finishes. The cycle polls through each active sensor input starting with CS1 and extending through CS3. As each capacitive touch sensor input is polled, its measurement is compared against a baseline “Not Touched” measurement. If the delta measurement is large enough, a touch is detected and an interrupt is generated. The sensing cycle time is programmable (see Section 6.10, "Averaging and Sampling Configuration Register"). 5.3.2 RECALIBRATING SENSOR INPUTS There are various options for recalibrating the capacitive touch sensor inputs. Recalibration re-sets the Base Count Registers (Section 6.24, "Sensor Input Base Count Registers") which contain the “not touched” values used for touch detection comparisons. APPLICATION NOTE: The device will recalibrate all sensor inputs that were disabled when it transitions from Standby. Likewise, the device will recalibrate all sensor inputs when waking out of Deep Sleep. CAP1133 DS00001625B-page 16  2015 Microchip Technology Inc. 5.3.2.1 Manual Recalibration The Calibration Activate Registers (Section 6.11, "Calibration Activate Register") force recalibration of selected sensor inputs. When a bit is set, the corresponding capacitive touch sensor input will be recalibrated (both analog and digital). The bit is automatically cleared once the recalibration routine has finished. 5.3.2.2 Automatic Recalibration Each sensor input is regularly recalibrated at a programmable rate (see Section 6.17, "Recalibration Configuration Register"). By default, the recalibration routine stores the average 64 previous measurements and periodically updates the base “not touched” setting for the capacitive touch sensor input. 5.3.2.3 Negative Delta Count Recalibration It is possible that the device loses sensitivity to a touch. This may happen as a result of a noisy environment, an accidental recalibration during a touch, or other environmental changes. When this occurs, the base untouched sensor input may generate negative delta count values. The NEG_DELTA_CNT bits (see Section 6.17, "Recalibration Configuration Register") can be set to force a recalibration after a specified number of consecutive negative delta readings. 5.3.2.4 Delayed Recalibration It is possible that a “stuck button” occurs when something is placed on a button which causes a touch to be detected for a long period. By setting the MAX_DUR_EN bit (see Section 6.6, "Configuration Registers"), a recalibration can be forced when a touch is held on a button for longer than the duration specified in the MAX_DUR bits (see Section 6.8, "Sensor Input Configuration Register"). 5.3.3 PROXIMITY DETECTION Each sensor input can be configured to detect changes in capacitance due to proximity of a touch. This circuitry detects the change of capacitance that is generated as an object approaches, but does not physically touch, the enabled sensor pad(s). When a sensor input is selected to perform proximity detection, it will be sampled from 1x to 128x per sampling cycle. The larger the number of samples that are taken, the greater the range of proximity detection is available at the cost of an increased overall sampling time. 5.3.4 MULTIPLE TOUCH PATTERN DETECTION The multiple touch pattern (MTP) detection circuitry can be used to detect lid closure or other similar events. An event can be flagged based on either a minimum number of sensor inputs or on specific sensor inputs simultaneously exceeding an MTP threshold or having their Noise Flag Status Register bits set. An interrupt can also be generated. During an MTP event, all touches are blocked (see Section 6.15, "Multiple Touch Pattern Configuration Register"). 5.3.5 LOW FREQUENCY NOISE DETECTION Each sensor input has an EMI noise detector that will sense if low frequency noise is injected onto the input with sufficient power to corrupt the readings. If this occurs, the device will reject the corrupted sample and set the corresponding bit in the Noise Status register to a logic ‘1’. Note: During this recalibration routine, the sensor inputs will not detect a press for up to 200ms and the Sensor Base Count Register values will be invalid. In addition, any press on the corresponding sensor pads will invalidate the recalibration. Note: Automatic recalibration only works when the delta count is below the active sensor input threshold. It is disabled when a touch is detected. Note: During this recalibration, the device will not respond to touches. Note: Delayed recalibration only works when the delta count is above the active sensor input threshold. If enabled, it is invoked when a sensor pad touch is held longer than the MAX_DUR bit setting.  2015 Microchip Technology Inc. DS00001625B-page 17 CAP1133 5.3.6 RF NOISE DETECTION Each sensor input contains an integrated RF noise detector. This block will detect injected RF noise on the CS pin. The detector threshold is dependent upon the noise frequency. If RF noise is detected on a CS line, that sample is removed and not compared against the threshold. 5.4 ALERT# Pin The ALERT# pin is an active low (or active high when configured) output that is driven when an interrupt event is detected. Whenever an interrupt is generated, the INT bit (see Section 6.1, "Main Control Register") is set. The ALERT# pin is cleared when the INT bit is cleared by the user. Additionally, when the INT bit is cleared by the user, status bits are only cleared if no touch is detected. 5.4.1 SENSOR INTERRUPT BEHAVIOR The sensor interrupts are generated in one of two ways: 1. An interrupt is generated when a touch is detected and, as a user selectable option, when a release is detected (by default - see Section 6.6). See Figure 5-3. 2. If the repeat rate is enabled then, so long as the touch is held, another interrupt will be generated based on the programmed repeat rate (see Figure 5-2). When the repeat rate is enabled, the device uses an additional control called MPRESS that determines whether a touch is flagged as a simple “touch” or a “press and hold”. The MPRESS[3:0] bits set a minimum press timer. When the button is touched, the timer begins. If the sensor pad is released before the minimum press timer expires, it is flagged as a touch and an interrupt is generated upon release. If the sensor input detects a touch for longer than this timer value, it is flagged as a “press and hold” event. So long as the touch is held, interrupts will be generated at the programmed repeat rate and upon release (if enabled). APPLICATION NOTE: Figure 5-2 and Figure 5-3 show default operation which is to generate an interrupt upon sensor pad release and an active-low ALERT# pin. APPLICATION NOTE: The host may need to poll the device twice to determine that a release has been detected. FIGURE 5-2: Sensor Interrupt Behavior - Repeat Rate Enabled Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Min Press Setting (280ms) Interrupt on Touch Button Repeat Rate (175ms) Button Repeat Rate (175ms) Interrupt on Release (optional) ALERT# pin (active low) CAP1133 DS00001625B-page 18  2015 Microchip Technology Inc. FIGURE 5-3: Sensor Interrupt Behavior - No Repeat Rate Enabled Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Interrupt on Touch Interrupt on Release (optional) ALERT# pin (active low)  2015 Microchip Technology Inc. DS00001625B-page 19 CAP1133 6.0 REGISTER DESCRIPTION The registers shown in Table 6-1 are accessible through the communications protocol. An entry of ‘-’ indicates that the bit is not used and will always read ‘0’. TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER Register Address R/W Register Name Function Default Value Page 00h R/W Main Control Controls general power states and power dissipation 00h Page 21 02h R General Status Stores general status bits 00h Page 22 03h R Sensor Input Status Returns the state of the sampled capacitive touch sensor inputs 00h Page 22 04h R LED Status Stores status bits for LEDs 00h Page 22 0Ah R Noise Flag Status Stores the noise flags for sensor inputs 00h Page 23 10h R Sensor Input 1 Delta Count Stores the delta count for CS1 00h Page 23 11h R Sensor Input 2 Delta Count Stores the delta count for CS2 00h Page 23 12h R Sensor Input 3 Delta Count Stores the delta count for CS3 00h Page 23 1Fh R/W Sensitivity Control Controls the sensitivity of the threshold and delta counts and data scaling of the base counts 2Fh Page 24 20h R/W Configuration Controls general functionality 20h Page 25 21h R/W Sensor Input Enable Controls whether the capacitive touch sensor inputs are sampled 07h Page 26 22h R/W Sensor Input Configuration Controls max duration and auto-repeat delay for sensor inputs operating in the full power state A4h Page 27 23h R/W Sensor Input Configuration 2 Controls the MPRESS controls for all sensor inputs 07h Page 28 24h R/W Averaging and Sampling Config Controls averaging and sampling window 39h Page 28 26h R/W Calibration Activate Forces re-calibration for capacitive touch sensor inputs 00h Page 30 27h R/W Interrupt Enable Enables Interrupts associated with capacitive touch sensor inputs 07h Page 30 28h R/W Repeat Rate Enable Enables repeat rate for all sensor inputs 07h Page 30 2Ah R/W Multiple Touch Configuration Determines the number of simultaneous touches to flag a multiple touch condition 80h Page 31 2Bh R/W Multiple Touch Pattern Configuration Determines the multiple touch pattern (MTP) configuration 00h Page 31 2Dh R/W Multiple Touch Pattern Determines the pattern or number of sensor inputs used by the MTP circuitry 07h Page 32 2Fh R/W Recalibration Configuration Determines re-calibration timing and sampling window 8Ah Page 33 30h R/W Sensor Input 1 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 1 40h Page 34 CAP1133 DS00001625B-page 20  2015 Microchip Technology Inc. 31h R/W Sensor Input 2 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 2 40h Page 34 32h R/W Sensor Input 3 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 3 40h Page 34 38h R/W Sensor Input Noise Threshold Stores controls for selecting the noise threshold for all sensor inputs 01h Page 34 Standby Configuration Registers 40h R/W Standby Channel Controls which sensor inputs are enabled while in standby 00h Page 35 41h R/W Standby Configuration Controls averaging and cycle time while in standby 39h Page 35 42h R/W Standby Sensitivity Controls sensitivity settings used while in standby 02h Page 36 43h R/W Standby Threshold Stores the touch detection threshold for active sensor inputs in standby 40h Page 37 44h R/W Configuration 2 Stores additional configuration controls for the device 40h Page 25 Base Count Registers 50h R Sensor Input 1 Base Count Stores the reference count value for sensor input 1 C8h Page 37 51h R Sensor Input 2 Base Count Stores the reference count value for sensor input 2 C8h Page 37 52h R Sensor Input 3 Base Count Stores the reference count value for sensor input 3 C8h Page 37 LED Controls 71h R/W LED Output Type Controls the output type for the LED outputs 00h Page 38 72h R/W Sensor Input LED Linking Controls linking of sensor inputs to LED channels 00h Page 38 73h R/W LED Polarity Controls the output polarity of LEDs 00h Page 38 74h R/W LED Output Control Controls the output state of the LEDs 00h Page 39 77h R/W Linked LED Transition Control Controls the transition when LEDs are linked to CS channels 00h Page 40 79h R/W LED Mirror Control Controls the mirroring of duty cycles for the LEDs 00h Page 41 81h R/W LED Behavior 1 Controls the behavior and response of LEDs 1 - 3 00h Page 41 84h R/W LED Pulse 1 Period Controls the period of each breathe during a pulse 20h Page 43 85h R/W LED Pulse 2 Period Controls the period of the breathing during breathe and pulse operation 14h Page 45 86h R/W LED Breathe Period Controls the period of an LED breathe operation 5Dh Page 46 88h R/W LED Config Controls LED configuration 04h Page 46 90h R/W LED Pulse 1 Duty Cycle Determines the min and max duty cycle for the pulse operation F0h Page 47 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page  2015 Microchip Technology Inc. DS00001625B-page 21 CAP1133 During Power-On-Reset (POR), the default values are stored in the registers. A POR is initiated when power is first applied to the part and the voltage on the VDD supply surpasses the POR level as specified in the electrical characteristics. Any reads to undefined registers will return 00h. Writes to undefined registers will not have an effect. When a bit is “set”, this means that the user writes a logic ‘1’ to it. When a bit is “cleared”, this means that the user writes a logic ‘0’ to it. 6.1 Main Control Register The Main Control register controls the primary power state of the device. Bits 7 - 6 - GAIN[1:0] - Controls the gain used by the capacitive touch sensing circuitry. As the gain is increased, the effective sensitivity is likewise increased as a smaller delta capacitance is required to generate the same delta count values. The sensitivity settings may need to be adjusted along with the gain settings such that data overflow does not occur. APPLICATION NOTE: The gain settings apply to both Standby and Active states. 91h R/W LED Pulse 2 Duty Cycle Determines the min and max duty cycle for breathe and pulse operation F0h Page 47 92h R/W LED Breathe Duty Cycle Determines the min and max duty cycle for the breathe operation F0h Page 47 93h R/W LED Direct Duty Cycle Determines the min and max duty cycle for Direct mode LED operation F0h Page 47 94h R/W LED Direct Ramp Rates Determines the rising and falling edge ramp rates of the LEDs 00h Page 47 95h R/W LED Off Delay Determines the off delay for all LED behaviors 00h Page 48 B1h R Sensor Input 1 Calibration Stores the upper 8-bit calibration value for sensor input 1 00h Page 51 B2h R Sensor Input 2 Calibration Stores the upper 8-bit calibration value for sensor input 2 00h Page 51 B3h R Sensor Input 3 Calibration Stores the upper 8-bit calibration value for sensor input 3 00h Page 51 B9h R Sensor Input Calibration LSB 1 Stores the 2 LSBs of the calibration value for sensor inputs 1 - 3 00h Page 51 FDh R Product ID Stores a fixed value that identifies each product 54h Page 51 FEh R Manufacturer ID Stores a fixed value that identifies Microchip 5Dh Page 52 FFh R Revision Stores a fixed value that represents the revision number 83h Page 52 TABLE 6-2: MAIN CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 00h R/W Main Control GAIN[1:0] STBY DSLEEP - - - INT 00h TABLE 6-3: GAIN BIT DECODE GAIN[1:0] Capacitive Touch Sensor Gain 1 0 0 0 1 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1133 DS00001625B-page 22  2015 Microchip Technology Inc. Bit 5 - STBY - Enables Standby. • ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - Capacitive touch sensor input scanning is limited to the sensor inputs set in the Standby Channel register (see Section 6.20). The status registers will not be cleared until read. LEDs that are linked to capacitive touch sensor inputs will remain linked and active. Sensor inputs that are no longer sampled will flag a release and then remain in a non-touched state. LEDs that are manually controlled will be unaffected. • Bit 4 - DSLEEP - Enables Deep Sleep by deactivating all functions. ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - All sensor input scanning is disabled. All LEDs are driven to their programmed non-actuated state and no PWM operations will be done. The status registers are automatically cleared and the INT bit is cleared. Bit 0 - INT - Indicates that there is an interrupt. When this bit is set, it asserts the ALERT# pin. If a channel detects a touch and its associated interrupt enable bit is not set to a logic ‘1’, no action is taken. This bit is cleared by writing a logic ‘0’ to it. When this bit is cleared, the ALERT# pin will be deasserted and all status registers will be cleared if the condition has been removed. • ‘0’ - No interrupt pending. • ‘1’ - A touch has been detected on one or more channels and the interrupt has been asserted. 6.2 Status Registers All status bits are cleared when the device enters the Deep Sleep (DSLEEP = ‘1’ - see Section 6.1). 6.2.1 GENERAL STATUS - 02H Bit 4 - LED - Indicates that one or more LEDs have finished their programmed activity. This bit is set if any bit in the LED Status register is set. Bit 2 - MULT - Indicates that the device is blocking detected touches due to the Multiple Touch detection circuitry (see Section 6.14). This bit will not cause the INT bit to be set and hence will not cause an interrupt. Bit 1 - MTP - Indicates that the device has detected a number of sensor inputs that exceed the MTP threshold either via the pattern recognition or via the number of sensor inputs (see Section 6.15). This bit will cause the INT bit to be set if the MTP_ALERT bit is also set. This bit will not be cleared until the condition that caused it to be set has been removed. Bit 0 - TOUCH - Indicates that a touch was detected. This bit is set if any bit in the Sensor Input Status register is set. 6.2.2 SENSOR INPUT STATUS - 03H The Sensor Input Status Register stores status bits that indicate a touch has been detected. A value of ‘0’ in any bit indicates that no touch has been detected. A value of ‘1’ in any bit indicates that a touch has been detected. 01 2 10 4 11 8 TABLE 6-4: STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 02h R General Status - - - LED - MULT MTP TOUCH 00h 03h R Sensor Input Status - - - - - CS3 CS2 CS1 00h 04h R LED Status - - - - - LED3_ DN LED2_ DN LED1_ DN 00h TABLE 6-3: GAIN BIT DECODE (CONTINUED) GAIN[1:0] Capacitive Touch Sensor Gain 1 0  2015 Microchip Technology Inc. DS00001625B-page 23 CAP1133 All bits are cleared when the INT bit is cleared and if a touch on the respective capacitive touch sensor input is no longer present. If a touch is still detected, the bits will not be cleared (but this will not cause the interrupt to be asserted - see Section 6.6). Bit 2 - CS3 - Indicates that a touch was detected on Sensor Input 3. This sensor input can be linked to LED3. Bit 1 - CS2 - Indicates that a touch was detected on Sensor Input 2. This sensor input can be linked to LED2. Bit 0 - CS1 - Indicates that a touch was detected on Sensor Input 1. This sensor input can be linked to LED1. 6.2.3 LED STATUS - 04H The LED Status Registers indicate when an LED has completed its configured behavior (see Section 6.31, "LED Behavior Register") after being actuated by the host (see Section 6.28, "LED Output Control Register"). These bits are ignored when the LED is linked to a capacitive sensor input. All LED Status bits are cleared when the INT bit is cleared. Bit 2 - LED3_DN - Indicates that LED3 has finished its behavior after being actuated by the host. Bit 1 - LED2_DN - Indicates that LED2 has finished its behavior after being actuated by the host. Bit 0 - LED1_DN - Indicates that LED1 has finished its behavior after being actuated by the host. 6.3 Noise Flag Status Registers The Noise Flag Status registers store status bits that are generated from the analog block if the detected noise is above the operating region of the analog detector or the RF noise detector. These bits indicate that the most recently received data from the sensor input is invalid and should not be used for touch detection. So long as the bit is set for a particular channel, the delta count value is reset to 00h and thus no touch is detected. These bits are not sticky and will be cleared automatically if the analog block does not report a noise error. APPLICATION NOTE: If the MTP detection circuitry is enabled, these bits count as sensor inputs above the MTP threshold (see Section 5.3.4, "Multiple Touch Pattern Detection") even if the corresponding delta count is not. If the corresponding delta count also exceeds the MTP threshold, it is not counted twice. APPLICATION NOTE: Regardless of the state of the Noise Status bits, if low frequency noise is detected on a sensor input, that sample will be discarded unless the DIS_ANA_NOISE bit is set. As well, if RF noise is detected on a sensor input, that sample will be discarded unless the DIS_RF_NOISE bit is set. 6.4 Sensor Input Delta Count Registers The Sensor Input Delta Count registers store the delta count that is compared against the threshold used to determine if a touch has been detected. The count value represents a change in input due to the capacitance associated with a touch on one of the sensor inputs and is referenced to a calibrated base “Not Touched” count value. The delta is an instantaneous change and is updated once per sensor input per sensing cycle (see Section 5.3.1, "Sensing Cycle"). TABLE 6-5: NOISE FLAG STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 0Ah R Noise Flag Status - - - CS3_ NOISE CS2_ NOISE CS1_ NOISE 00h TABLE 6-6: SENSOR INPUT DELTA COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 10h R Sensor Input 1 Delta Count Sign 64 32 16 8 4 2 1 00h 11h R Sensor Input 2 Delta Count Sign 64 32 16 8 4 2 1 00h 12h R Sensor Input 3 Delta Count Sign 64 32 16 8 4 2 1 00h CAP1133 DS00001625B-page 24  2015 Microchip Technology Inc. The value presented is a standard 2’s complement number. In addition, the value is capped at a value of 7Fh. A reading of 7Fh indicates that the sensitivity settings are too high and should be adjusted accordingly (see Section 6.5). The value is also capped at a negative value of 80h for negative delta counts which may result upon a release. 6.5 Sensitivity Control Register The Sensitivity Control register controls the sensitivity of a touch detection. Bits 6-4 DELTA_SENSE[2:0] - Controls the sensitivity of a touch detection. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta capacitance corresponding to a “lighter” touch. These settings are more sensitive to noise, however, and a noisy environment may flag more false touches with higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely, a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). Bits 3 - 0 - BASE_SHIFT[3:0] - Controls the scaling and data presentation of the Base Count registers. The higher the value of these bits, the larger the range and the lower the resolution of the data presented. The scale factor represents the multiplier to the bit-weighting presented in these register descriptions. APPLICATION NOTE: The BASE_SHIFT[3:0] bits normally do not need to be updated. These settings will not affect touch detection or sensitivity. These bits are sometimes helpful in analyzing the Cap Sensing board performance and stability. TABLE 6-7: SENSITIVITY CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 1Fh R/W Sensitivity Control - DELTA_SENSE[2:0] BASE_SHIFT[3:0] 2Fh TABLE 6-8: DELTA_SENSE BIT DECODE DELTA_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-9: BASE_SHIFT BIT DECODE BASE_SHIFT[3:0] Data Scaling Factor 32 1 0 0 0 0 0 1x 0 0 0 1 2x 0 0 1 0 4x 0 0 1 1 8x  2015 Microchip Technology Inc. DS00001625B-page 25 CAP1133 6.6 Configuration Registers The Configuration registers control general global functionality that affects the entire device. 6.6.1 CONFIGURATION - 20H Bit 7 - TIMEOUT - Enables the timeout and idle functionality of the SMBus protocol. • ‘0’ (default for Functional Revision C) - The SMBus timeout and idle functionality are disabled. The SMBus interface will not time out if the clock line is held low. Likewise, it will not reset if both the data and clock lines are held high for longer than 200us. This is used for I2C compliance. • ‘1’ (default for Functional Revision B) - The SMBus timeout and idle functionality are enabled. The SMBus interface will time out if the clock line is held low for longer than 30ms. Likewise, it will reset if both the data and clock lines are held high for longer than 200us. Bit 5 - DIS_DIG_NOISE - Determines whether the digital noise threshold (see Section 6.19, "Sensor Input Noise Threshold Register") is used by the device. Setting this bit disables the feature. • ‘0’ - The digital noise threshold is used. If a delta count value exceeds the noise threshold but does not exceed the touch threshold, the sample is discarded and not used for the automatic re-calibration routine. • ‘1’ (default) - The noise threshold is disabled. Any delta count that is less than the touch threshold is used for the automatic re-calibration routine. Bit 4 - DIS_ANA_NOISE - Determines whether the analog noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If low frequency noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if low frequency noise is detected. Bit 3 - MAX_DUR_EN - Determines whether the maximum duration recalibration is enabled. • ‘0’ (default) - The maximum duration recalibration functionality is disabled. A touch may be held indefinitely and no re-calibration will be performed on any sensor input. • ‘1’ - The maximum duration recalibration functionality is enabled. If a touch is held for longer than the MAX_DUR bit settings, then the re-calibration routine will be restarted (see Section 6.8). 0 1 0 0 16x 0 1 0 1 32x 0 1 1 0 64x 0 1 1 1 128x 1 0 0 0 256x All others 256x (default = 1111b) TABLE 6-10: CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 20h R/W Configuration TIMEOUT - DIS_ DIG_ NOISE DIS_ ANA_ NOISE MAX_ DUR_EN - -- A0h (Rev B) 20h (rev C) 44h R/W Configuration 2 INV_LINK_ TRAN ALT_ POL BLK_PWR_ CTRL BLK_POL_ MIR SHOW_ RF_ NOISE DIS_ RF_ NOISE - INT_ REL_n 40h TABLE 6-9: BASE_SHIFT BIT DECODE (CONTINUED) BASE_SHIFT[3:0] Data Scaling Factor 32 1 0 CAP1133 DS00001625B-page 26  2015 Microchip Technology Inc. 6.6.2 CONFIGURATION 2 - 44H Bit 7 - INV_LINK_TRAN - Determines the behavior of the Linked LED Transition controls (see Section 6.29). • ‘0’ (default) - The Linked LED Transition controls set the min duty cycle equal to the max duty cycle. • ‘1’ - The Linked LED Transition controls will invert the touch signal. For example, a touch signal will be inverted to a non-touched signal. Bit 6 - ALT_POL - Determines the ALERT# pin polarity and behavior. • ‘0’ - The ALERT# pin is active high and push-pull. • ‘1’ (default) - The ALERT# pin is active low and open drain. Bit 5 - BLK_PWR_CTRL - Determines whether the device will reduce power consumption while waiting between conversion time completion and the end of the polling cycle. • ‘0’ (default) - The device will always power down as much as possible during the time between the end of the last conversion and the end of the polling cycle. • ‘1’ - The device will not power down the Cap Sensor during the time between the end of the last conversion and the end of the polling cycle. Bit 4 - BLK_POL_MIR - Determines whether the LED Mirror Control register bits are linked to the LED Polarity bits. Setting this bit blocks the normal behavior which is to automatically set and clear the LED Mirror Control bits when the LED Polarity bits are set or cleared. • ‘0’ (default) - When the LED Polarity controls are set, the corresponding LED Mirror control is automatically set. Likewise, when the LED Polarity controls are cleared, the corresponding LED Mirror control is also cleared. • ‘1’ - When the LED Polarity controls are set, the corresponding LED Mirror control is not automatically set. Bit 3 - SHOW_RF_NOISE - Determines whether the Noise Status bits will show RF Noise as the only input source. • ‘0’ (default) - The Noise Status registers will show both RF noise and low frequency EMI noise if either is detected on a capacitive touch sensor input. • ‘1’ - The Noise Status registers will only show RF noise if it is detected on a capacitive touch sensor input. EMI noise will still be detected and touches will be blocked normally; however, the status bits will not be updated. Bit 2 - DIS_RF_NOISE - Determines whether the RF noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If RF noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if RF noise is detected. Bit 0 - INT_REL_n - Controls the interrupt behavior when a release is detected on a button. • ‘0’ (default) - An interrupt is generated when a press is detected and again when a release is detected and at the repeat rate (if enabled - see Section 6.13). • ‘1’ - An interrupt is generated when a press is detected and at the repeat rate but not when a release is detected. 6.7 Sensor Input Enable Registers The Sensor Input Enable registers determine whether a capacitive touch sensor input is included in the sampling cycle. The length of the sampling cycle is not affected by the number of sensor inputs measured. Bit 2 - CS3_EN - Enables the CS3 input to be included during the sampling cycle. • ‘0’ - The CS3 input is not included in the sampling cycle. • ‘1’ (default) - The CS3 input is included in the sampling cycle. Bit 1 - CS2_EN - Enables the CS2 input to be included during the sampling cycle. Bit 0 - CS1_EN - Enables the CS1 input to be included during the sampling cycle. TABLE 6-11: SENSOR INPUT ENABLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 21h R/W Sensor Input Enable - - - - - CS3_EN CS2_EN CS1_EN 07h  2015 Microchip Technology Inc. DS00001625B-page 27 CAP1133 6.8 Sensor Input Configuration Register The Sensor Input Configuration Register controls timings associated with the Capacitive sensor inputs 1 - 3. Bits 7 - 4 - MAX_DUR[3:0] - (default 1010b) - Determines the maximum time that a sensor pad is allowed to be touched until the capacitive touch sensor input is recalibrated, as shown in Table 6-13. Bits 3 - 0 - RPT_RATE[3:0] - (default 0100b) Determines the time duration between interrupt assertions when auto repeat is enabled. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-14. TABLE 6-12: SENSOR INPUT CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 22h R/W Sensor Input Configuration MAX_DUR[3:0] RPT_RATE[3:0] A4h TABLE 6-13: MAX_DUR BIT DECODE MAX_DUR[3:0] Time Before Recalibration 32 1 0 0 0 0 0 560ms 0 0 0 1 840ms 0 0 1 0 1120ms 0 0 1 1 1400ms 0 1 0 0 1680ms 0 1 0 1 2240ms 0 1 1 0 2800ms 1 1 1 3360ms 1 0 0 0 3920ms 1 0 0 1 4480ms 1 0 1 0 5600ms (default) 1 0 1 1 6720ms 1 1 0 0 7840ms 1 1 0 1 8906ms 1 1 1 0 10080ms 1 1 1 1 11200ms TABLE 6-14: RPT_RATE BIT DECODE RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms (default) 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms CAP1133 DS00001625B-page 28  2015 Microchip Technology Inc. 6.9 Sensor Input Configuration 2 Register Bits 3 - 0 - M_PRESS[3:0] - (default 0111b) - Determines the minimum amount of time that sensor inputs configured to use auto repeat must detect a sensor pad touch to detect a “press and hold” event. If the sensor input detects a touch for longer than the M_PRESS[3:0] settings, a “press and hold” event is detected. If a sensor input detects a touch for less than or equal to the M_PRESS[3:0] settings, a touch event is detected. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-16. 6.10 Averaging and Sampling Configuration Register 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-15: SENSOR INPUT CONFIGURATION 2 REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 23h R/W Sensor Input Configuration 2 - - - - M_PRESS[3:0] 07h TABLE 6-16: M_PRESS BIT DECODE M_PRESS[3:0] M_PRESS SETTINGS 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms (default) 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-17: AVERAGING AND SAMPLING CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 24h R/W Averaging and Sampling Config AVG[2:0] SAMP_TIME[1:0] CYCLE_TIME [1:0] 39h TABLE 6-14: RPT_RATE BIT DECODE (CONTINUED) RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0  2015 Microchip Technology Inc. DS00001625B-page 29 CAP1133 The Averaging and Sampling Configuration register controls the number of samples taken and the total sensor input cycle time for all active sensor inputs while the device is functioning in Active state. Bits 6 - 4 - AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-18. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. For example, if CS1, CS2, and CS3 are sampled during the sensor cycle, and the AVG[2:0] bits are set to take 4 samples per channel, then the full sensor cycle will be: CS1, CS1, CS1, CS1, CS2, CS2, CS2, CS2, CS3, CS3, CS3, CS3. Bits 3 - 2 - SAMP_TIME[1:0] - Determines the time to take a single sample as shown in Table 6-19. Bits 1 - 0 - CYCLE_TIME[1:0] - Determines the overall cycle time for all measured channels during normal operation as shown in Table 6-20. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, then the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. TABLE 6-18: AVG BIT DECODE AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-19: SAMP_TIME BIT DECODE SAMP_TIME[1:0] Sample Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-20: CYCLE_TIME BIT DECODE CYCLE_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms CAP1133 DS00001625B-page 30  2015 Microchip Technology Inc. 6.11 Calibration Activate Register The Calibration Activate register forces the respective sensor inputs to be re-calibrated affecting both the analog and digital blocks. During the re-calibration routine, the sensor inputs will not detect a press for up to 600ms and the Sensor Input Base Count register values will be invalid. During this time, any press on the corresponding sensor pads will invalidate the re-calibration. When finished, the CALX[9:0] bits will be updated (see Section 6.39). When the corresponding bit is set, the device will perform the calibration and the bit will be automatically cleared once the re-calibration routine has finished. Bit 2 - CS3_CAL - When set, the CS3 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 1 - CS2_CAL - When set, the CS2 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 0 - CS1_CAL - When set, the CS1 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. 6.12 Interrupt Enable Register The Interrupt Enable register determines whether a sensor pad touch or release (if enabled) causes the interrupt pin to be asserted. Bit 2 - CS3_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS3 (associated with the CS3 status bit). • ‘0’ - The interrupt pin will not be asserted if a touch is detected on CS3 (associated with the CS6 status bit). • ‘1’ (default) - The interrupt pin will be asserted if a touch is detected on CS3 (associated with the CS6 status bit). Bit 1 - CS2_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS2 (associated with the CS2 status bit). Bit 0 - CS1_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS1 (associated with the CS1 status bit). 6.13 Repeat Rate Enable Register The Repeat Rate Enable register enables the repeat rate of the sensor inputs as described in Section 5.4.1. Bit 2 - CS3_RPT_EN - Enables the repeat rate for capacitive touch sensor input 3. • ‘0’ - The repeat rate for CS3 is disabled. It will only generate an interrupt when a touch is detected and when a release is detected no matter how long the touch is held for. • ‘1’ (default) - The repeat rate for CS3 is enabled. In the case of a “touch” event, it will generate an interrupt when a touch is detected and a release is detected (as determined by the INT_REL_n bit - see Section 6.6). In the case of a “press and hold” event, it will generate an interrupt when a touch is detected and at the repeat rate so long as TABLE 6-21: CALIBRATION ACTIVATE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 26h R/W Calibration Activate --- CS3_ CAL CS2_ CAL CS1_ CAL 00h TABLE 6-22: INTERRUPT ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 27h R/W Interrupt Enable --- CS3_ INT_EN CS2_ INT_EN CS1_ INT_EN 07h TABLE 6-23: REPEAT RATE ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 28h R/W Repeat Rate Enable ---- - CS3_ RPT_EN CS2_ RPT_EN CS1_ RPT_EN 07h  2015 Microchip Technology Inc. DS00001625B-page 31 CAP1133 the touch is held d. Bit 1 - CS2_RPT_EN - Enables the repeat rate for capacitive touch sensor input 2. Bit 0 - CS1_RPT_EN - Enables the repeat rate for capacitive touch sensor input 1. 6.14 Multiple Touch Configuration Register The Multiple Touch Configuration register controls the settings for the multiple touch detection circuitry. These settings determine the number of simultaneous buttons that may be pressed before additional buttons are blocked and the MULT status bit is set. Bit 7 - MULT_BLK_EN - Enables the multiple button blocking circuitry. • ‘0’ - The multiple touch circuitry is disabled. The device will not block multiple touches. • ‘1’ (default) - The multiple touch circuitry is enabled. The device will flag the number of touches equal to programmed multiple touch threshold and block all others. It will remember which sensor inputs are valid and block all others until that sensor pad has been released. Once a sensor pad has been released, the N detected touches (determined via the cycle order of CS1 - CS3) will be flagged and all others blocked. Bits 3 - 2 - B_MULT_T[1:0] - Determines the number of simultaneous touches on all sensor pads before a Multiple Touch Event is detected and sensor inputs are blocked. The bit decode is given by Table 6-25. 6.15 Multiple Touch Pattern Configuration Register The Multiple Touch Pattern Configuration register controls the settings for the multiple touch pattern detection circuitry. This circuitry works like the multiple touch detection circuitry with the following differences: 1. The detection threshold is a percentage of the touch detection threshold as defined by the MTP_TH[1:0] bits whereas the multiple touch circuitry uses the touch detection threshold. 2. The MTP detection circuitry either will detect a specific pattern of sensor inputs as determined by the Multiple Touch Pattern register settings or it will use the Multiple Touch Pattern register settings to determine a minimum number of sensor inputs that will cause the MTP circuitry to flag an event. When using pattern recognition mode, if all of the sensor inputs set by the Multiple Touch Pattern register have a delta count greater than the MTP threshold or have their corresponding Noise Flag Status bits set, the MTP bit will be set. When using the absolute number mode, if the number of sensor inputs with thresholds above the MTP threshold or with Noise Flag Status bits set is equal to or greater than this number, the MTP bit will be set. 3. When an MTP event occurs, all touches are blocked and an interrupt is generated. TABLE 6-24: MULTIPLE TOUCH CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Ah R/W Multiple Touch Config MULT_ BLK_ EN - - - B_MULT_T[1:0] - - 80h TABLE 6-25: B_MULT_T BIT DECODE B_MULT_T[1:0] Number of Simultaneous Touches 1 0 0 0 1 (default) 01 2 10 3 11 3 TABLE 6-26: MULTIPLE TOUCH PATTERN CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Bh R/W Multiple Touch Pattern Config MTP_ EN - - MTP_TH[1:0] COMP_ PTRN MTP_ ALERT 00h CAP1133 DS00001625B-page 32  2015 Microchip Technology Inc. 4. All sensor inputs will remain blocked so long as the requisite number of sensor inputs are above the MTP threshold or have Noise Flag Status bits set. Once this condition is removed, touch detection will be restored. Note that the MTP status bit is only cleared by writing a ‘0’ to the INT bit once the condition has been removed. Bit 7 - MTP_EN - Enables the multiple touch pattern detection circuitry. • ‘0’ (default) - The MTP detection circuitry is disabled. • ‘1’ - The MTP detection circuitry is enabled. Bits 3-2 - MTP_TH[1:0] - Determine the MTP threshold, as shown in Table 6-27. This threshold is a percentage of sensor input threshold (see Section 6.18, "Sensor Input Threshold Registers") when the device is in the Fully Active state or of the standby threshold (see Section 6.23, "Standby Threshold Register") when the device is in the Standby state. Bit 1 - COMP_PTRN - Determines whether the MTP detection circuitry will use the Multiple Touch Pattern register as a specific pattern of sensor inputs or as an absolute number of sensor inputs. • ‘0’ (default) - The MTP detection circuitry will use the Multiple Touch Pattern register bit settings as an absolute minimum number of sensor inputs that must be above the threshold or have Noise Flag Status bits set. The number will be equal to the number of bits set in the register. • ‘1’ - The MTP detection circuitry will use pattern recognition. Each bit set in the Multiple Touch Pattern register indicates a specific sensor input that must have a delta count greater than the MTP threshold or have a Noise Flag Status bit set. If the criteria are met, the MTP status bit will be set. Bit 0 - MTP_ALERT - Enables an interrupt if an MTP event occurs. In either condition, the MTP status bit will be set. • ‘0’ (default) - If an MTP event occurs, the ALERT# pin is not asserted. • ‘1’ - If an MTP event occurs, the ALERT# pin will be asserted. 6.16 Multiple Touch Pattern Register The Multiple Touch Pattern register acts as a pattern to identify an expected sensor input profile for diagnostics or other significant events. There are two methods for how the Multiple Touch Pattern register is used: as specific sensor inputs or number of sensor input that must exceed the MTP threshold or have Noise Flag Status bits set. Which method is used is based on the COMP_PTRN bit (see Section 6.15). The methods are described below. 1. Specific Sensor Inputs: If, during a single polling cycle, the specific sensor inputs above the MTP threshold or with Noise Flag Status bits set match those bits set in the Multiple Touch Pattern register, an MTP event is flagged. 2. Number of Sensor Inputs: If, during a single polling cycle, the number of sensor inputs with a delta count above the MTP threshold or with Noise Flag Status bits set is equal to or greater than the number of pattern bits set, an MTP event is flagged. Bit 2 - CS3_PTRN - Determines whether CS3 is considered as part of the Multiple Touch Pattern. • ‘0’ - CS3 is not considered a part of the pattern. • ‘1’ - CS3 is considered a part of the pattern or the absolute number of sensor inputs that must have a delta count greater than the MTP threshold or have the Noise Flag Status bit set is increased by 1. TABLE 6-27: MTP_TH BIT DECODE MTP_TH[1:0] Threshold Divide Setting 1 0 0 0 12.5% (default) 0 1 25% 1 0 37.5% 1 1 100% TABLE 6-28: MULTIPLE TOUCH PATTERN REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Dh R/W Multiple Touch Pattern --- CS3_ PTRN CS2_ PTRN CS1_ PTRN 07h  2015 Microchip Technology Inc. DS00001625B-page 33 CAP1133 Bit 1 - CS2_PTRN - Determines whether CS2 is considered as part of the Multiple Touch Pattern. Bit 0 - CS1_PTRN - Determines whether CS1 is considered as part of the Multiple Touch Pattern. 6.17 Recalibration Configuration Register The Recalibration Configuration register controls the automatic re-calibration routine settings as well as advanced controls to program the Sensor Input Threshold register settings. Bit 7 - BUT_LD_TH - Enables setting all Sensor Input Threshold registers by writing to the Sensor Input 1 Threshold register. • ‘0’ - Each Sensor Input X Threshold register is updated individually. • ‘1’ (default) - Writing the Sensor Input 1 Threshold register will automatically overwrite the Sensor Input Threshold registers for all sensor inputs (Sensor Input Threshold 1 through Sensor Input Threshold 3). The individual Sensor Input X Threshold registers (Sensor Input 2 Threshold and Sensor Input 3 Threshold) can be individually updated at any time. Bit 6 - NO_CLR_INTD - Controls whether the accumulation of intermediate data is cleared if the noise status bit is set. • ‘0’ (default) - The accumulation of intermediate data is cleared if the noise status bit is set. • ‘1’ - The accumulation of intermediate data is not cleared if the noise status bit is set. APPLICATION NOTE: Bits 5 and 6 should both be set to the same value. Either both should be set to ‘0’ or both should be set to ‘1’. Bit 5 - NO_CLR_NEG - Controls whether the consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘0’ (default) - The consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘1’ - The consecutive negative delta counts counter is not cleared if the noise status bit is set. Bits 4 - 3 - NEG_DELTA_CNT[1:0] - Determines the number of negative delta counts necessary to trigger a digital recalibration as shown in Table 6-30. Bits 2 - 0 - CAL_CFG[2:0] - Determines the update time and number of samples of the automatic re-calibration routine. The settings apply to all sensor inputs universally (though individual sensor inputs can be configured to support re-calibration - see Section 6.11). TABLE 6-29: RECALIBRATION CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Fh R/W Recalibration Configuration BUT_ LD_TH NO_ CLR_ INTD NO_ CLR_ NEG NEG_DELTA_ CNT[1:0] CAL_CFG[2:0] 8Ah TABLE 6-30: NEG_DELTA_CNT BIT DECODE NEG_DELTA_CNT[1:0] Number of Consecutive Negative Delta Count Values 1 0 00 8 0 1 16 (default) 1 0 32 1 1 None (disabled) TABLE 6-31: CAL_CFG BIT DECODE CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210 0 0 0 16 16 0 0 1 32 32 CAP1133 DS00001625B-page 34  2015 Microchip Technology Inc. Note 6-1 Recalibration Samples refers to the number of samples that are measured and averaged before the Base Count is updated however does not control the base count update period. Note 6-2 Update Time refers to the amount of time (in polling cycle periods) that elapses before the Base Count is updated. The time will depend upon the number of channels active, the averaging setting, and the programmed cycle time. 6.18 Sensor Input Threshold Registers The Sensor Input Threshold registers store the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. When the BUT_LD_TH bit is set (see Section 6.17 - bit 7), writing data to the Sensor Input 1 Threshold register will update all of the sensor input threshold registers (31h - 32h inclusive). 6.19 Sensor Input Noise Threshold Register The Sensor Input Noise Threshold register controls the value of a secondary internal threshold to detect noise and improve the automatic recalibration routine. If a capacitive touch sensor input exceeds the Sensor Input Noise Threshold but does not exceed the sensor input threshold, it is determined to be caused by a noise spike. That sample is not used by the automatic re-calibration routine. This feature can be disabled by setting the DIS_DIG_NOISE bit. Bits 1-0 - CS1_BN_TH[1:0] - Controls the noise threshold for all capacitive touch sensor inputs, as shown in Table 6-34. The threshold is proportional to the threshold setting. 0 1 0 64 64 (default) 0 1 1 128 128 1 0 0 256 256 1 0 1 256 1024 1 1 0 256 2048 1 1 1 256 4096 TABLE 6-32: SENSOR INPUT THRESHOLD REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 30h R/W Sensor Input 1 Threshold - 64 32 16 8 4 2 1 40h 31h R/W Sensor Input 2 Threshold - 64 32 16 8 4 2 1 40h 32h R/W Sensor Input 3 Threshold - 64 32 16 8 4 2 1 40h TABLE 6-33: SENSOR INPUT NOISE THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 38h R/W Sensor Input Noise Threshold CS_BN_TH [1:0] 01h TABLE 6-31: CAL_CFG BIT DECODE (CONTINUED) CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210  2015 Microchip Technology Inc. DS00001625B-page 35 CAP1133 6.20 Standby Channel Register The Standby Channel register controls which (if any) capacitive touch sensor inputs are active during Standby. Bit 2 - CS3_STBY - Controls whether the CS3 channel is active in Standby. • ‘0’ (default) - The CS3 channel not be sampled during Standby mode. • ‘1’ - The CS3 channel will be sampled during Standby Mode. It will use the Standby threshold setting, and the standby averaging and sensitivity settings. Bit 1 - CS2_STBY - Controls whether the CS2 channel is active in Standby. Bit 0 - CS1_STBY - Controls whether the CS1 channel is active in Standby. 6.21 Standby Configuration Register The Standby Configuration register controls averaging and cycle time for those sensor inputs that are active in Standby. This register is useful for detecting proximity on a small number of sensor inputs as it allows the user to change averaging and sample times on a limited number of sensor inputs and still maintain normal functionality in the fully active state. Bit 7 - AVG_SUM - Determines whether the active sensor inputs will average the programmed number of samples or whether they will accumulate for the programmed number of samples. • ‘0’ - (default) - The active sensor input delta count values will be based on the average of the programmed number of samples when compared against the threshold. • ‘1’ - The active sensor input delta count values will be based on the summation of the programmed number of samples when compared against the threshold. This bit should only be set when performing proximity detection as a physical touch will overflow the delta count registers and may result in false readings. Bits 6 - 4 - STBY_AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-37. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. TABLE 6-34: CSX_BN_TH BIT DECODE CS_BN_TH[1:0] Percent Threshold Setting 1 0 0 0 25% 0 1 37.5% (default) 1 0 50% 1 1 62.5% TABLE 6-35: STANDBY CHANNEL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 40h R/W Standby Channel - - - - - CS3_ STBY CS2_ STBY CS1_ STBY 00h TABLE 6-36: STANDBY CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 41h R/W Standby Configuration AVG_ SUM STBY_AVG[2:0] STBY_SAMP_ TIME[1:0] STBY_CY_TIME [1:0] 39h TABLE 6-37: STBY_AVG BIT DECODE STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 CAP1133 DS00001625B-page 36  2015 Microchip Technology Inc. Bit 3-2 - STBY SAMP_TIME[1:0] - Determines the time to take a single sample when the device is in Standby as shown in Table 6-38. Bits 1 - 0 - STBY_CY_TIME[2:0] - Determines the overall cycle time for all measured channels during standby operation as shown in Table 6-39. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The STBY_AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. 6.22 Standby Sensitivity Register The Standby Sensitivity register controls the sensitivity for sensor inputs that are active in Standby. 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-38: STBY_SAMP_TIME BIT DECODE STBY_SAMP_TIME[1:0] Sampling Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-39: STBY_CY_TIME BIT DECODE STBY_CY_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms TABLE 6-40: STANDBY SENSITIVITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 42h R/W Standby Sensitivity - - - - - STBY_SENSE[2:0] 02h TABLE 6-37: STBY_AVG BIT DECODE (CONTINUED) STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10  2015 Microchip Technology Inc. DS00001625B-page 37 CAP1133 Bits 2 - 0 - STBY_SENSE[2:0] - Controls the sensitivity for sensor inputs that are active in Standby. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta C corresponding to a “lighter” touch. These settings are more sensitive to noise however and a noisy environment may flag more false touches than higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). 6.23 Standby Threshold Register The Standby Threshold register stores the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. 6.24 Sensor Input Base Count Registers The Sensor Input Base Count registers store the calibrated “Not Touched” input value from the capacitive touch sensor inputs. These registers are periodically updated by the re-calibration routine. The routine uses an internal adder to add the current count value for each reading to the sum of the previous readings until sample size has been reached. At this point, the upper 16 bits are taken and used as the Sensor Input Base Count. The internal adder is then reset and the re-calibration routine continues. TABLE 6-41: STBY_SENSE BIT DECODE STBY_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-42: STANDBY THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 43h R/W Standby Threshold - 64 32 16 8 4 2 1 40h TABLE 6-43: SENSOR INPUT BASE COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 50h R Sensor Input 1 Base Count 128 64 32 16 8 4 2 1 C8h 51h R Sensor Input 2 Base Count 128 64 32 16 8 4 2 1 C8h 52h R Sensor Input 3 Base Count 128 64 32 16 8 4 2 1 C8h CAP1133 DS00001625B-page 38  2015 Microchip Technology Inc. The data presented is determined by the BASE_SHIFT[3:0] bits (see Section 6.5). 6.25 LED Output Type Register The LED Output Type register controls the type of output for the LED pins. Each pin is controlled by a single bit. Refer to application note 21.4 CAP1133Family LED Configuration Options for more information about implementing LEDs. Bit 2 - LED3_OT - Determines the output type of the LED3 pin. • ‘0’ (default) - The LED3 pin is an open-drain output with an external pull-up resistor. When the appropriate pin is set to the “active” state (logic ‘1’), the pin will be driven low. Conversely, when the pin is set to the “inactive” state (logic ‘0’), the pin will be left in a High Z state and pulled high via an external pull-up resistor. • ‘1’ - The LED3 pin is a push-pull output. When driving a logic ‘1’, the pin is driven high. When driving a logic ‘0’, the pin is driven low. Bit 1 - LED2_OT - Determines the output type of the LED2 pin. Bit 0 - LED1_OT - Determines the output type of the LED1 pin. 6.26 Sensor Input LED Linking Register The Sensor Input LED Linking register controls whether a capacitive touch sensor input is linked to an LED output. If the corresponding bit is set, then the appropriate LED output will change states defined by the LED Behavior controls (see Section 6.31) in response to the capacitive touch sensor input. Bit 2 - CS3_LED3 - Links the LED3 output to a detected touch on the CS3 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. • ‘0’ (default) - The LED 3 output is not associated with the CS3 input. If a touch is detected on the CS3 input, the LED will not automatically be actuated. The LED is enabled and controlled via the LED Output Control register (see Section 6.28) and the LED Behavior registers (see Section 6.31). • ‘1’ - The LED 3 output is associated with the CS3 input. If a touch is detected on the CS3 input, the LED will be actuated and behave as defined in Table 6-52. Bit 1 - CS2_LED2 - Links the LED2 output to a detected touch on the CS2 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. Bit 0 - CS1_LED1 - Links the LED1 output to a detected touch on the CS1 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. 6.27 LED Polarity Register TABLE 6-44: LED OUTPUT TYPE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 71h R/W LED Output Type ----- LED3_ OT LED2_ OT LED1_ OT 00h TABLE 6-45: SENSOR INPUT LED LINKING REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 72h R/W Sensor Input LED Linking - - - - - CS3_ LED3 CS2_ LED2 CS1_ LED1 00h TABLE 6-46: LED POLARITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 73h R/W LED Polarity - - - - - LED3_ POL LED2_ POL LED1_ POL 00h  2015 Microchip Technology Inc. DS00001625B-page 39 CAP1133 The LED Polarity register controls the logical polarity of the LED outputs. When these bits are set or cleared, the corresponding LED Mirror controls are also set or cleared (unless the BLK_POL_MIR bit is set - see Section 6.6, "Configuration Registers"). Table 6-48, "LED Polarity Behavior" shows the interaction between the polarity controls, output controls, and relative brightness. APPLICATION NOTE: The polarity controls determine the final LED pin drive. A touch on a linked capacitive touch sensor input is treated in the same way as the LED Output Control bit being set to a logic ‘1’. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’ then the LED will be on and that the CAP1133 LED pin is sinking the LED current. Conversely, if the LED pin is driven to a logic ‘1’, the LED will be off and there is no current flow. See Figure 5-1, "System Diagram for CAP1133". APPLICATION NOTE: This application note applies when the LED polarity is inverted (LEDx_POL = ‘0’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘0’ state in. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven low (i.e. maximum % of time that the LED is on) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven low (i.e. minimum % of time that the LED is on). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at the minimum duty cycle setting. Breathe operations will ramp the duty cycle from the minimum duty cycle to the maximum duty cycle. APPLICATION NOTE: This application note applies when the LED polarity is non-inverted (LEDx_POL = ‘1’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘1’ state. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven high (i.e. maximum % of time that the LED is off) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven high (i.e. minimum % of time that the LED is off). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at 100 minus the minimum duty cycle setting. Breathe operations will ramp the duty cycle from 100 minus the minimum duty cycle to 100 minus the maximum duty cycle. APPLICATION NOTE: The LED Mirror controls (see Section 6.30, "LED Mirror Control Register") work with the polarity controls with respect to LED brightness but will not have a direct effect on the output pin drive. Bit 2 - LED3_POL - Determines the polarity of the LED3 output. • ‘0’ (default) - The LED3 output is inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘0’. • ‘1’ - The LED3 output is non-inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘1’ or left in the high-z state as determined by its output type Bit 1 - LED2_POL - Determines the polarity of the LED2 output. Bit 0 - LED1_POL - Determines the polarity of the LED1 output. 6.28 LED Output Control Register The LED Output Control Register controls the output state of the LED pins that are not linked to sensor inputs. TABLE 6-47: LED OUTPUT CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 74h R/W LED Output Control ----- LED3_ DR LED2_ DR LED1_ DR 00h Note: If an LED is linked to a sensor input in the Sensor Input LED Linking Register (Section 6.26, "Sensor Input LED Linking Register"), the corresponding bit in the LED Output Control Register is ignored (i.e. a linked LED cannot be host controlled). CAP1133 DS00001625B-page 40  2015 Microchip Technology Inc. The LED Polarity Control Register will determine the non actuated state of the LED pins. The actuated LED behavior is determined by the LED behavior controls (see Section 6.31, "LED Behavior Register"). Table 6-48 shows the interaction between the polarity controls, output controls, and relative brightness. Bit 2 - LED3_DR - Determines whether LED3 output is driven high or low. • ‘0’ (default) - The LED3 output is driven at the minimum duty cycle or not actuated. • ‘1’ - The LED3 output is driven at the maximum duty cycle or is actuated. Bit 1 - LED2_DR - Determines whether LED2 output is driven high or low. Bit 0 - LED1_DR - Determines whether LED1 output is driven high or low. 6.29 Linked LED Transition Control Register The Linked LED Transition Control register controls the LED drive when the LED is linked to a capacitive touch sensor input. These controls work in conjunction with the INV_LINK_TRAN bit (see Section 6.6.2, "Configuration 2 - 44h") to create smooth transitions from host control to linked LEDs. Bit 2 - LED3_LTRAN - Determines the transition effect when LED3 is linked to CS3. • ‘0’ (default) - When the LED output control bit for LED3 is ‘1’, and then LED3 is linked to CS3 and no touch is detected, the LED will change states. • ‘1’ - If the INV_LINK_TRAN bit is ‘1’, when the LED output control bit for CS3 is ‘1’, and then CS3 is linked to LED3 and no touch is detected, the LED will not change states. In addition, the LED state will change when the sensor pad is touched. If the INV_LINK_TRAN bit is ‘0’, when the LED output control bit for CS3 is ‘1’, and then CS3 is linked to LED3 and no touch is detected, the LED will not change states. However, the LED state will not change TABLE 6-48: LED POLARITY BEHAVIOR LED Output Control Register or Touch Polarity Max Duty Min Duty Brightness LED Appearance 0 inverted (‘0’) not used minimum % of time that the LED is on (logic 0) maximum brightness at min duty cycle on at min duty cycle 1 inverted (‘0’) maximum % of time that the LED is on (logic 0) minimum % of time that the LED is on (logic 0) maximum brightness at max duty cycle. Brightness ramps from min duty cycle to max duty cycle according to LED behavior 0 non-inverted (‘1’) not used minimum % of time that the LED is off (logic 1) maximum brightness at 100 minus min duty cycle. on at 100 - min duty cycle 1 non-inverted (‘1’) maximum % of time that the LED is off (logic 1) minimum % of time that the LED is off (logic 1) For Direct behavior, maximum brightness is 100 minus max duty cycle. When breathing, max brightness is 100 minus min duty cycle. Brightness ramps from 100 - min duty cycle to 100 - max duty cycle. according to LED behavior TABLE 6-49: LINKED LED TRANSITION CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 77h R/W Linked LED Transition Control - ---- LED3_ LTRAN LED2_ LTRAN LED1_ LTRAN 00h  2015 Microchip Technology Inc. DS00001625B-page 41 CAP1133 when the sensor pad is touched. APPLICATION NOTE: If the LED behavior is not “Direct” and the INV_LINK_TRAN bit it ‘0’, the LED will not perform as expected when the LED3_LTRAN bit is set to ‘1’. Therefore, if breathe and pulse behaviors are used, set the INV_LINK_TRAN bit to ‘1’. Bit 1 - LED2_LTRAN - Determines the transition effect when LED2 is linked to CS2. Bit 0 - LED1_LTRAN - Determines the transition effect when LED1 is linked to CS1. 6.30 LED Mirror Control Register The LED Mirror Control Registers determine the meaning of duty cycle settings when polarity is non-inverted for each LED channel. When the polarity bit is set to ‘1’ (non-inverted), to obtain correct steps for LED ramping, pulse, and breathe behaviors, the min and max duty cycles need to be relative to 100%, rather than the default, which is relative to 0%. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’, the LED will be on and the CAP1133 LED pin is sinking the LED current. When the polarity bit is set to ‘1’, it is considered non-inverted. For systems using the opposite LED configuration, mirror controls would apply when the polarity bit is ‘0’. These bits are changed automatically if the corresponding LED Polarity bit is changed (unless the BLK_POL_MIR bit is set - see Section 6.6). Bit 2 - LED3_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. • ‘0’ (default) - The duty cycle settings are determined relative to 0% and are determined directly with the settings. • ‘1’ - The duty cycle settings are determined relative to 100%. Bit 1 - LED2_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. Bit 0 - LED1_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. 6.31 LED Behavior Register The LED Behavior register controls the operation of LEDs. Each LED pin is controlled by a 2-bit field and the behavior is determined by whether the LED is linked to a capacitive touch sensor input or not. If the corresponding LED output is linked to a capacitive touch sensor input, the appropriate behavior will be enabled / disabled based on touches and releases. If the LED output is not associated with a capacitive touch sensor input, the appropriate behavior will be enabled / disabled by the LED Output Control register. If the respective LEDx_DR bit is set to a logic ‘1’, this will be associated as a “touch”, and if the LEDx_DR bit is set to a logic ‘0’, this will be associated as a “release”. Table 6-52, "LEDx_CTL Bit Decode" shows the behavior triggers. The defined behavior will activate when the Start Trigger is met and will stop when the Stop Trigger is met. Note the behavior of the Breathe Hold and Pulse Release option. The LED Polarity Control register will determine the non actuated state of the LED outputs (see Section 6.27, "LED Polarity Register"). APPLICATION NOTE: If an LED is not linked to a capacitive touch sensor input and is breathing (via the Breathe or Pulse behaviors), it must be unactuated and then re-actuated before changes to behavior TABLE 6-50: LED MIRROR CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 79h R/W LED Mirror Control ----- LED3_ MIR_ EN LED2_ MIR _ EN LED1_ MIR _ EN 00h TABLE 6-51: LED BEHAVIOR REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 81h R/W LED Behavior 1 - - LED3_CTL[1:0] LED2_CTL[1:0] LED1_CTL[1:0] 00h CAP1133 DS00001625B-page 42  2015 Microchip Technology Inc. are processed. For example, if the LED output is breathing and the Maximum duty cycle is changed, this change will not take effect until the LED output control register is set to ‘0’ and then re-set to ‘1’. APPLICATION NOTE: If an LED is not linked to the capacitive touch sensor input and configured to operate using Pulse 1 Behavior, then the circuitry will only be actuated when the corresponding output control bit is set. It will not check the bit condition until the Pulse 1 behavior is finished. The device will not remember if the bit was cleared and reset while it was actuated. APPLICATION NOTE: If an LED is actuated and not linked and the desired LED behavior is changed, this new behavior will take effect immediately; however, the first instance of the changed behavior may act incorrectly (e.g. if changed from Direct to Pulse 1, the LED output may ‘breathe’ 4 times and then end at minimum duty cycle). LED Behaviors will operate normally once the LED has been un-actuated and then re-actuated. APPLICATION NOTE: If an LED is actuated and it is switched from linked to a capacitive touch sensor input to unlinked (or vice versa), the LED will respond to the new command source immediately if the behavior was Direct or Breathe. For Pulse behaviors, it will complete the behavior already in progress. For example, if a linked LED was actuated by a touch and the control is changed so that it is unlinked, it will check the status of the corresponding LED Output Control bit. If that bit is ‘0’, then the LED will behave as if a release was detected. Likewise, if an unlinked LED was actuated by the LED Output Control register and the control is changed so that it is linked and no touch is detected, then the LED will behave as if a release was detected. Bits 5 - 4 - LED3_CTL[1:0] - Determines the behavior of LED3 as shown in Table 6-52. Bits 3 - 2 - LED2_CTL[1:0] - Determines the behavior of LED2 as shown in Table 6-52. Bits 1 - 0 - LED1_CTL[1:0] - Determines the behavior of LED1 as shown in Table 6-52. TABLE 6-52: LEDX_CTL BIT DECODE LEDx_CTL [1:0] Operation Description Start TRigger Stop Trigger 1 0 0 0 Direct The LED is driven to the programmed state (active or inactive). See Figure 6-7 Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared 0 1 Pulse 1 The LED will “Pulse” a programmed number of times. During each “Pulse” the LED will breathe up to the maximum brightness and back down to the minimum brightness so that the total “Pulse” period matches the programmed value. Touch or Release Detected or LED Output Control bit set or cleared (see Section 6.32) n/a 1 0 Pulse 2 The LED will “Pulse” when the start trigger is detected. When the stop trigger is detected, it will “Pulse” a programmable number of times then return to its minimum brightness. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared  2015 Microchip Technology Inc. DS00001625B-page 43 CAP1133 APPLICATION NOTE: The PWM frequency is determined based on the selected LED behavior, the programmed breathe period, and the programmed min and max duty cycles. For the Direct behavior mode, the PWM frequency is calculated based on the programmed Rise and Fall times. If these are set at 0, then the maximum PWM frequency will be used based on the programmed duty cycle settings. 6.32 LED Pulse 1 Period Register The LED Pulse Period 1 register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 01b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms (24 x 32ms = 768ms). The total range is from 32ms to 4.064 seconds as shown in Table 6-54 with the default being 1024ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. Bit 7 - ST_TRIG - Determines the start trigger for the LED Pulse behavior. • ‘0’ (default) - The LED will Pulse when a touch is detected or the drive bit is set. • ‘1’ - The LED will Pulse when a release is detected or the drive bit is cleared. The Pulse 1 operation is shown in Figure 6-1 when the LED output is configured for non-inverted polarity (LEDx_POL = 1) and in Figure 6-2 for inverted polarity (LEDx_POL = 0). 1 1 Breathe The LED will breathe. It will be driven with a duty cycle that ramps up from the programmed minimum duty cycle (default 0%) to the programmed maximum duty cycle duty cycle (default 100%) and then back down. Each ramp takes up 50% of the programmed period. The total period of each “breath” is determined by the LED Breathe Period controls - see Section 6.34. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared TABLE 6-53: LED PULSE 1 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 84h R/W LED Pulse 1 Period ST_ TRIG P1_ PER6 P1_ PER5 P1_ PER4 P1_ PER3 P1_ PER2 P1_ PER1 P1_ PER0 20h TABLE 6-52: LEDX_CTL BIT DECODE (CONTINUED) LEDx_CTL [1:0] Operation Description Start TRigger Stop Trigger 1 0 CAP1133 DS00001625B-page 44  2015 Microchip Technology Inc. . FIGURE 6-1: Pulse 1 Behavior with Non-Inverted Polarity FIGURE 6-2: Pulse 1 Behavior with Inverted Polarity TABLE 6-54: LED PULSE / BREATHE PERIOD EXAMPLE Setting (HEX) Setting (Decimal) Total Breathe / Pulse Period (MS) 00h 0 32 01h 1 32 02h 2 64 03h 3 96 . . . . . . . . . 7Dh 125 4000 7Eh 126 4032 7Fh 127 4064 Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected (100% - Pulse 1 Max Duty Cycle) * Brightness X pulses after touch or after release Pulse 1 Period (P1_PER) (100% - Pulse 1 Min Duty Cycle) * Brightness LED Brightness Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected Pulse 1 Min Duty Cycle * Brightness X pulses after touch or after release Pulse Period (P1_PER) Pulse 1 Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001625B-page 45 CAP1133 6.33 LED Pulse 2 Period Register The LED Pulse 2 Period register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 10b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 640ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. The Pulse 2 Behavior is shown in Figure 6-3 for non-inverted polarity (LEDx_POL = 1) and in Figure 6-4 for inverted polarity (LEDx_POL = 0). TABLE 6-55: LED PULSE 2 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 85h R/W LED Pulse 2 Period - P2_ PER6 P2_ PER5 P2_ PER4 P2_ PER3 P2_ PER2 P2_ PER1 P2_ PER0 14h FIGURE 6-3: Pulse 2 Behavior with Non-Inverted Polarity FIGURE 6-4: Pulse 2 Behavior with Inverted Polarity . . . Normal – untouched operation Normal – untouched operation Touch Detected (100% - Pulse 2 Min Duty Cycle) * Brightness (100% - Pulse 2 Max Duty Cycle) * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness Normal – untouched operation Normal – untouched operation Touch Detected Pulse 2 Max Duty Cycle * Brightness Pulse 2 Min Duty Cycle * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness . . . CAP1133 DS00001625B-page 46  2015 Microchip Technology Inc. 6.34 LED Breathe Period Register The LED Breathe Period register determines the overall period of a breathe operation as determined by the LED_CTL registers (see Table 6-52 - setting 11b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 2976ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. 6.35 LED Configuration Register The LED Configuration register controls general LED behavior as well as the number of pulses that are sent for the PULSE LED output behavior. Bit 6 - RAMP_ALERT - Determines whether the device will assert the ALERT# pin when LEDs actuated by the LED Output Control register bits have finished their respective behaviors. Interrupts will only be generated if the LED activity is generated by writing the LED Output Control registers. Any LED activity associated with touch detection will not cause an interrupt to be generated when the LED behavior has been finished. • ‘0’ (default) - The ALERT# pin will not be asserted when LEDs actuated by the LED Output Control register have finished their programmed behaviors. • ‘1’ - The ALERT# pin will be asserted whenever any LED that is actuated by the LED Output Control register has finished its programmed behavior. Bits 5 - 3 - PULSE2_CNT[2:0] - Determines the number of pulses used for the Pulse 2 behavior as shown in Table 6-58. Bits 2 - 0 - PULSE1_CNT[2:0] - Determines the number of pulses used for the Pulse 1 behavior as shown in Table 6-58. TABLE 6-56: LED BREATHE PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 86h R/W LED Breathe Period - BR_ PER6 BR_ PER5 BR_ PER4 BR_ PER3 BR_ PER2 BR_ PER1 BR_ PER0 5Dh TABLE 6-57: LED CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 88h R/W LED Config - RAMP_ ALERT PULSE2_CNT[2:0] PULSE1_CNT[2:0] 04h TABLE 6-58: PULSEX_CNT DECODE PULSEX_CNT[2:0] Number of Breaths 21 0 0 0 0 1 (default - Pulse 2) 00 1 2 01 0 3 01 1 4 1 0 0 5 (default - Pulse 1) 10 1 6 11 0 7 11 1 8  2015 Microchip Technology Inc. DS00001625B-page 47 CAP1133 6.36 LED Duty Cycle Registers The LED Duty Cycle registers determine the minimum and maximum duty cycle settings used for the LED for each LED behavior. These settings affect the brightness of the LED when it is fully off and fully on. The LED driver duty cycle will ramp up from the minimum duty cycle to the maximum duty cycle and back down again. APPLICATION NOTE: When operating in Direct behavior mode, changes to the Duty Cycle settings will be applied immediately. When operating in Breathe, Pulse 1, or Pulse 2 modes, the LED must be unactuated and then re-actuated before changes to behavior are processed. Bits 7 - 4 - X_MAX_DUTY[3:0] - Determines the maximum PWM duty cycle for the LED drivers as shown in Table 6-60. Bits 3 - 0 - X_MIN_DUTY[3:0] - Determines the minimum PWM duty cycle for the LED drivers as shown in Table 6-60. 6.37 LED Direct Ramp Rates Register TABLE 6-59: LED DUTY CYCLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 90h R/W LED Pulse 1 Duty Cycle P1_MAX_DUTY[3:0] P1_MIN_DUTY[3:0] F0h 91h R/W LED Pulse 2 Duty Cycle P2_MAX_DUTY[3:0] P2_MIN_DUTY[3:0] F0h 92h R/W LED Breathe Duty Cycle BR_MAX_DUTY[3:0] BR_MIN_DUTY[3:0] F0h 93h R/W Direct Duty Cycle DR_MAX_DUTY[3:0] DR_MIN_DUTY[3:0] F0h TABLE 6-60: LED DUTY CYCLE DECODE x_MAX/MIN_Duty [3:0] Maximum Duty Cycle Minimum Duty Cycle 3 21 0 0 0 0 0 7% 0% 0 0 0 1 9% 7% 0 0 1 0 11% 9% 0 0 1 1 14% 11% 0 1 0 0 17% 14% 0 1 0 1 20% 17% 0 1 1 0 23% 20% 0 1 1 1 26% 23% 1 0 0 0 30% 26% 1 0 0 1 35% 30% 1 0 1 0 40% 35% 1 0 1 1 46% 40% 1 1 0 0 53% 46% 1 1 0 1 63% 53% 1 1 1 0 77% 63% 1 1 1 1 100% 77% TABLE 6-61: LED DIRECT RAMP RATES REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 94h R/W LED Direct Ramp Rates - - RISE_RATE[2:0] FALL_RATE[2:0] 00h CAP1133 DS00001625B-page 48  2015 Microchip Technology Inc. The LED Direct Ramp Rates register control the rising and falling edge time of an LED that is configured to operate in Direct behavior mode. The rising edge time corresponds to the amount of time the LED takes to transition from its minimum duty cycle to its maximum duty cycle. Conversely, the falling edge time corresponds to the amount of time that the LED takes to transition from its maximum duty cycle to its minimum duty cycle. Bits 5 - 3 - RISE_RATE[2:0] - Determines the rising edge time of an LED when it transitions from its minimum drive state to its maximum drive state as shown in Table 6-62. Bits 2 - 0 - FALL_RATE[2:0] - Determines the falling edge time of an LED when it transitions from its maximum drive state to its minimum drive state as shown in Table 6-62. 6.38 LED Off Delay Register The LED Off Delay register determines the amount of time that an LED remains at its maximum duty cycle (or minimum as determined by the polarity controls) before it starts to ramp down. If the LED is operating in Breathe mode, this delay is applied at the top of each “breath”. If the LED is operating in the Direct mode, this delay is applied when the LED is unactuated. Bits 6 - 4 - BR_OFF_DLY[2:0] - Determines the Breathe behavior mode off delay, which is the amount of time an LED in Breathe behavior mode remains inactive after it finishes a breathe pulse (ramp on and ramp off), as shown in Figure 6- 5 (non-inverted polarity LEDx_POL = 1) and Figure 6-6 (inverted polarity LEDx_POL = 0). Available settings are shown in Table 6-64. TABLE 6-62: RISE / FALL RATE DECODE RISE_RATE/ FALL_RATE/ Bit Decode Rise / Fall Time (TRISE / TFALL) 21 0 00 0 0 0 0 1 250ms 0 1 0 500ms 0 1 1 750ms 1 0 0 1s 1 0 1 1.25s 1 1 0 1.5s 1 1 1 2s TABLE 6-63: LED OFF DELAY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 95h R/W LED Off Delay Register - BR_OFF_DLY[2:0] DIR_OFF_DLY[3:0] 00h  2015 Microchip Technology Inc. DS00001625B-page 49 CAP1133 FIGURE 6-5: Breathe Behavior with Non-Inverted Polarity FIGURE 6-6: Breathe Behavior with Inverted Polarity TABLE 6-64: BREATHE OFF DELAY SETTINGS BR_OFF_DLY [2:0] OFF Delay 2 10 0 0 0 0 (default) 0 0 1 0.25s 0 1 0 0.5s 0 1 1 0.75s LED Actuated 100% - Breathe Max Min Cycle * Brightness 100% - Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER) LED Actuated Breathe Max Duty Cycle * Brightness Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER) CAP1133 DS00001625B-page 50  2015 Microchip Technology Inc. Bits 3 - 0 - DIR_OFF_DLY[3:0] - Determines the turn-off delay, as shown in Table 6-65, for all LEDs that are configured to operate in Direct behavior mode. The Direct behavior operation is determined by the combination of programmed Rise Time, Fall Time, Min and Max Duty cycles, Off Delay, and polarity. Figure 6-7 shows the behavior for non-inverted polarity (LEDx_POL = 1) while Figure 6- 8 shows the behavior for inverted polarity (LEDx_POL = 0). 1 0 0 1.0s 1 0 1 1.25s 1 1 0 1.5s 1 1 1 2.0s FIGURE 6-7: Direct Behavior for Non-Inverted Polarity FIGURE 6-8: Direct Behavior for Inverted Polarity TABLE 6-65: OFF DELAY DECODE OFF Delay[3:0] Bit Decode OFF Delay (tOFF_DLY) 32 1 0 00 0 0 0 0 0 0 1 250ms 0 0 1 0 500ms 0 0 1 1 750ms TABLE 6-64: BREATHE OFF DELAY SETTINGS (CONTINUED) BR_OFF_DLY [2:0] OFF Delay 2 10 Normal – untouched operation RISE_RATE Setting (tRISE) (100% - Max Duty Cycle) * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation (100% - Min Duty Cycle) * Brightness LED Brightness Normal – untouched operation RISE_RATE Setting (tRISE) Min Duty Cycle * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001625B-page 51 CAP1133 6.39 Sensor Input Calibration Registers The Sensor Input Calibration registers hold the 10-bit value that represents the last calibration value. 6.40 Product ID Register The Product ID register stores a unique 8-bit value that identifies the device. 6.41 Manufacturer ID Register The Vendor ID register stores an 8-bit value that represents Microchip. 0 1 0 0 1s 0 1 0 1 1.25s 0 1 1 0 1.5s 0 1 1 1 2s 1 0 0 0 2.5s 1 0 0 1 3.0s 1 0 1 0 3.5s 1 0 1 1 4.0s 1 1 0 0 4.5s All others 5.0s TABLE 6-66: SENSOR INPUT CALIBRATION REGISTERS ADDR Register R/W B7 B6 B5 B4 B3 B2 B1 B0 Default B1h Sensor Input 1 Calibration R CAL1_9 CAL1_8 CAL1_7 CAL1_6 CAL1_5 CAL1_4 CAL1_3 CAL1_2 00h B2h Sensor Input 2 Calibration R CAL2_9 CAL2_8 CAL2_7 CAL2_6 CAL2_5 CAL2_4 CAL2_3 CAL2_2 00h B3h Sensor Input 3 Calibration R CAL3_9 CAL3_8 CAL3_7 CAL3_6 CAL3_5 CAL3_4 CAL3_3 CAL3_2 00h B9h Sensor Input Calibration LSB 1 R - - CAL3_1 CAL3_0 CAL2_1 CAL2_0 CAL1_1 CAL1_0 00h TABLE 6-67: PRODUCT ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FDh R Product ID 0 1 0 1 0 1 0 0 54h TABLE 6-68: VENDOR ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FEh R Manufacturer ID 0 1 0 1 1 1 0 1 5Dh TABLE 6-65: OFF DELAY DECODE (CONTINUED) OFF Delay[3:0] Bit Decode OFF Delay (tOFF_DLY) 32 1 0 CAP1133 DS00001625B-page 52  2015 Microchip Technology Inc. 6.42 Revision Register The Revision register stores an 8-bit value that represents the part revision. TABLE 6-69: REVISION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FFh R Revision 1 0 0 0 0 0 1 1 83h  2015 Microchip Technology Inc. DS00001625B-page 53 CAP1133 7.0 PACKAGE INFORMATION 7.1 CAP1133 Package Drawings FIGURE 7-1: 10-Pin DFN 3mm x 3mm Package Drawings (1 of 2) Note: For the most current package drawings, see the Microchip Packaging Specification at http://www.microchip.com/packaging CAP1133 DS00001625B-page 54  2015 Microchip Technology Inc. FIGURE 7-2: 10-Pin DFN 3mm x 3mm Package Drawings (2 of 2) Note: For the most current package drawings, see the Microchip Packaging Specification at http://www.microchip.com/packaging  2015 Microchip Technology Inc. DS00001625B-page 55 CAP1133 7.2 Package Marking FIGURE 7-3: CAP1133 Package Marking 1 A W NNNA e4 TOP BOTTOM Bottom marking not allowed PB-FREE/GREEN SYMBOL PIN 1 (Ni/Pd PP-LF) Line 1 – Device Code, Week 2x 0.6 Line 2 – Alphanumeric Traceability Code W Lines 1-2: Line 3: Center Horizontal Alignment As Shown CAP1133 DS00001625B-page 56  2015 Microchip Technology Inc. APPENDIX A: DEVICE DELTA A.1 Delta from CAP1033 to CAP1133 1. Updated circuitry to improve power supply rejection. 2. Updated LED driver duty cycle decode values to have more distribution at lower values - closer to a logarithmic curve. See Table 6-60, "LED Duty Cycle Decode". 3. Updated bug that breathe periods were not correct above 2.6s. This includes rise / fall time decodes above 1.5s. 4. Added 1 bit to the LED Off Delay register (see Section 6.38, "LED Off Delay Register") to extend times from 2s to 5s in 0.5s intervals. 5. Breathe behavior modified. A breathe off delay control was added to the LED Off Delay Register (see Section 6.38, "LED Off Delay Register") so the LEDs can be configured to remain inactive between breathes. 6. Added controls for the LED transition effects when linking LEDs to capacitive sensor inputs. See Section 6.29, "Linked LED Transition Control Register". 7. Added controls to “mirror” the LED duty cycle outputs so that when polarity changes, the LED brightness levels look right. These bits are automatically set when polarity is set. Added control to break this auto-set behavior. See Section 6.30, "LED Mirror Control Register". 8. Added Multiple Touch Pattern detection circuitry. See Section 6.15, "Multiple Touch Pattern Configuration Register". 9. Added General Status register to flag Multiple touches, Multiple Touch Pattern issues and general touch detections. See Section 6.2, "Status Registers". 10. Added bits 6 and 5 to the Recalibration Configuration register (2Fh - see Section 6.17, "Recalibration Configuration Register"). These bits control whether the accumulation of intermediate data and the consecutive negative delta counts counter are cleared when the noise status bit is set. 11. Added Configuration 2 register for LED linking controls, noise detection controls, and control to interrupt on press but not on release. Added control to change alert pin polarity. See Section 6.6, "Configuration Registers". 12. Updated Deep Sleep behavior so that device does not clear DSLEEP bit on received communications but will wake to communicate. 13. Changed PWM frequency for LED drivers. The PWM frequency was derived from the programmed breathe period and duty cycle settings and it ranged from ~4Hz to ~8000 Hz. The PWM frequency has been updated to be a fixed value of ~2000Hz. 14. Register delta: Table A.1 Register Delta From CAP1033 to CAP1133 Address Register Delta Delta Default 00h Page 21 Changed - Main Status / Control added bits 7-6 to control gain 00h 02h Page 22 New - General Status new register to store MTP, MULT, LED, and general TOUCH bits 00h 44h Page 25 New - Configuration 2 new register to control alert polarity, LED touch linking behavior, LED output behavior, and noise detection, and interrupt on release 40h 24h Page 28 Changed - Averaging Control updated register bits - moved SAMP_AVG[2:0] bits and added SAMP_- TIME bit 1. Default changed 39h 2Bh Page 31 New - Multiple Touch Pattern Configuration new register for Multiple Touch Pattern configuration - enable and threshold settings 80h 2Dh Page 32 New - Multiple Touch Pattern Register new register for Multiple Touch Pattern detection circuitry - pattern or number of sensor inputs 07h  2015 Microchip Technology Inc. DS00001625B-page 57 CAP1133 2Fh Page 33 Changed - Recalibration Configuration updated register - updated CAL_CFG bit decode to add a 128 averages setting and removed highest time setting. Default changed. Added bit 6 NO_CLR_INTD and bit 5 NO_CLR_NEG. 8Ah 38h Page 34 Changed - Sensor Input Noise Threshold updated register bits - removed bits 7 - 3 and consolidated all controls into bits 1 - 0. These bits will set the noise threshold for all channels. Default changed 01h 39h Removed - Noise Threshold Register 2 removed register n/a 41h Page 35 Changed - Standby Configuration updated register bits - moved STBY_AVG[2:0] bits and added STBY_- TIME bit 1. Default changed 39h 77h Page 40 New - Linked LED Transition Control new register to control transition effect when LED linked to sensor inputs 00h 79h Page 41 New - LED Mirror Control new register to control LED output mirroring for brightness control when polarity changed 00h 90h Page 47 Changed - LED Pulse 1 Duty Cycle changed bit decode to be more logarithmic F0h 91h Page 47 Changed - LED Pulse 2 Duty Cycle changed bit decode to be more logarithmic F0h 92h Page 47 Changed - LED Breathe Duty Cycle changed bit decode to be more logarithmic F0h 93h Page 47 Changed - LED Direct Duty Cycle changed bit decode to be more logarithmic F0h 95h Added controls - LED Off Delay Added bits 6-4 BR_OFF_DLY[2:0] Added bit 3 DIR_OFF_DLY[3] 00h FDh Page 51 Changed - Product ID Changed bit decode for CAP1133 54h Table A.1 Register Delta From CAP1033 to CAP1133 (continued) Address Register Delta Delta Default CAP1133 DS00001625B-page 58  2015 Microchip Technology Inc. APPENDIX B: DATA SHEET REVISION HISTORY Revision Section/Figure/Entry Correction DS00001625B (02-09-15) Features, Table 2-2, Table 2- 2, "Pin Types", Section 5.0, "General Description" References to BC-Link Interface, BC_DATA, BC_- CLK, BC-IRQ#, BC-Link bus have been removed Application Note under Table 2-6 [BC-Link] hidden in data sheet Table 3-2, "Electrical Specifications" BC-Link Timing Section hidden in data sheet Table 4-1 Protocol Used for 68K Pull Down Resistor changed from “BC-Link Communications” to “Reserved” Section 4.2.2, "SMBus Address and RD / WR Bit" Replaced “client address” with “slave address” in this section. Section 4.2.4, SMBus ACK and NACK Bits, Section 4.2.5, SMBus Stop Bit,Section 4.2.7, SMBus and I2C Compatibility Replaced “client” with “slave” in these sections. Table 4-3, "Read Byte Protocol" Heading changed from “Client Address” to “Slave Address” Table 6-1 Register Name for Register Address 77h changed from “LED Linked Transition Control” to “Linked LED Transition Control” Section 6.30 changed CS3 to LED3 Section 7.7 Package Marking Updated package drawing Appendix A: Device Delta changed 2Dh to 2Fh in item #12 Product Identification System Removed BC-Link references REV A REV A replaces previous SMSC version Rev. 1.32 (01-05-12) Rev. 1.32 (01-05-12) Table 3-2, "Electrical Specifications" Added conditions for tHD:DAT. Section 4.2.7, "SMBus and I2C Compatibility" Renamed from “SMBus and I2C Compliance.” First paragraph, added last sentence: “For information on using the CAP1188 in an I2C system, refer to SMSC AN 14.0 SMSC Dedicated Slave Devices in I 2C Systems.” Added: CAP1188 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. Section 6.4, "Sensor Input Delta Count Registers" Changed negative value cap from FFh to 80h. Rev. 1.31 (08-18-11) Section 4.3.3, "SMBus Send Byte" Added an application note: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Section 4.3.4, "SMBus Receive Byte" Added an application note: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Section 6.2, "Status Registers" Removed RESET as bit 3 in register 02h. Rev. 1.3 (05-18-11) Section 6.42, "Revision Register" Updated revision ID from 82h to 83h. Section 6.2, "Status Registers" Added RESET as bit 3 in register 02h.  2015 Microchip Technology Inc. DS00001625B-page 59 CAP1133 Rev. 1.2 (02-10-11) Section A.8, "Delta from Rev B (Mask B0) to Rev C (Mask B1)" Added. Table 3-2, "Electrical Specifications" PSR improvements made in functional revision B. Changed PSR spec from ±100 typ and ±200 max counts / V to ±3 and ±10 counts / V. Conditions updated. Section 5.3.2, "Recalibrating Sensor Inputs" Added more detail with subheadings for each type of recalibration. Section 6.6, "Configuration Registers" Added bit 5 BLK_PWR_CTRL to the Configuration 2 Register 44h. The TIMEOUT bit is set to ‘1’ by default for functional revision B and is set to ‘0’ by default for functional revision C. Section 6.42, "Revision Register" Updated revision ID in register FFh from 81h to 82h. Rev. 1.1 (11-17-10) Document Updated for functional revision B. See Section A.7, "Delta from Rev A (Mask A0) to Rev B (Mask B0)". Cover Added to General Description: “includes circuitry and support for enhanced sensor proximity detection.” Added the following Features: Calibrates for Parasitic Capacitance Analog Filtering for System Noise Sources Press and Hold feature for Volume-like Applications Table 3-2, "Electrical Specifications" Conditions for Power Supply Rejection modified adding the following: Sampling time = 2.56ms Averaging = 1 Negative Delta Counts = Disabled All other parameters default Section 6.11, "Calibration Activate Register" Updated register description to indicate which re-calibration routine is used. Section 6.14, "Multiple Touch Configuration Register" Updated register description to indicate what will happen. Table 6-34, "CSx_BN_TH Bit Decode" Table heading changed from “Threshold Divide Setting” to “Percent Threshold Setting”. Rev. 1.0 (06-14-10) Initial release Revision Section/Figure/Entry Correction CAP1133 DS00001625B-page 60  2015 Microchip Technology Inc. THE MICROCHIP WEB SITE Microchip provides online support via our WWW site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support  2015 Microchip Technology Inc. DS00001625B-page 61 CAP1133 PRODUCT IDENTIFICATION SYSTEM To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. PART NO. [X] - [X] - XXX - [X](1) l l l l l Device Temperature Addressing Package Tape and Reel Range Option Option Example: Note 1: Tape and Reel identifier only appears in the catalog part number description. This identifier is used for ordering purposes and is not printed on the device package. Check with your Microchip Sales Office for package availability with the Tape and Reel option. Device: CAP1133 Temperature Range: Blank = 0°C to +85°C (Extended Commercial) Package: AIA = DFN Tape and Reel Option: TR = Tape and Reel(1) CAP1133-1-AIA-TR 10-pin DFN 3mm x 3mm (RoHS compliant) Three capacitive touch sensor inputs, Three LED drivers, SMBus interface Reel size is 4,000 pieces CAP1133 DS00001625B-page 62  2015 Microchip Technology Inc. Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication 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. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, flexPWR, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANCheck, MediaLB, MOST, MOST logo, MPLAB, OptoLyzer, PIC, PICSTART, PIC32 logo, RightTouch, SpyNIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. The Embedded Control Solutions Company and mTouch are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, ECAN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, KleerNet, KleerNet logo, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, RightTouch logo, REAL ICE, SQI, Serial Quad I/O, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2015, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 978632770356 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 ==  2015 Microchip Technology Inc. DS00001625B-page 63 AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Canada - Toronto Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2943-5100 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Dongguan Tel: 86-769-8702-9880 China - Hangzhou Tel: 86-571-8792-8115 Fax: 86-571-8792-8116 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 ASIA/PACIFIC China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7828 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 EUROPE Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Dusseldorf Tel: 49-2129-3766400 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Pforzheim Tel: 49-7231-424750 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Venice Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Poland - Warsaw Tel: 48-22-3325737 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service 01/27/15  2015 Microchip Technology Inc. DS00001624B-page 1 General Description The CAP1106, which incorporates RightTouch® technology, is a multiple channel Capacitive Touch sensor. The CAP1106 contains six (6) individual capacitive touch sensor inputs. The device offers programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1106 includes Multiple Pattern Touch recognition that allows the user to select a specific set of buttons to be touched simultaneously. If this pattern is detected, then a status bit is set and an interrupt generated. Additionally, the CAP1106 includes circuitry and support for enhanced sensor proximity detection. The CAP1106 offers multiple power states operating at low quiescent currents. In the Standby state of operation, one or more capacitive touch sensor inputs are active. Deep Sleep is the lowest power state available, drawing 5uA (typical) of current. In this state, no sensor inputs are active. Communications will wake the device. Applications • Desktop and Notebook PCs • LCD Monitors • Consumer Electronics • Appliances Features • Six (6) Capacitive Touch Sensor Inputs - CAP1106 - Programmable sensitivity - Automatic recalibration - Individual thresholds for each button • Proximity Detection • Multiple Button Pattern Detection • Calibrates for Parasitic Capacitance • Analog Filtering for System Noise Sources • Press and Hold feature for Volume-like Applications • Multiple Communication Interfaces - SMBus / I2C compliant interface • Low Power Operation - 5uA quiescent current in Deep Sleep - 50uA quiescent current in Standby (1 sensor input monitored) - Samples one or more channels in Standby • Available in 10-pin 3mm x 3mm RoHS compliant DFN package CAP1106 6 Channel Capacitive Touch Sensor CAP1106 DS00001624B-page 2  2015 Microchip Technology Inc. TO OUR VALUED CUSTOMERS It is our intention to provide our valued customers with the best documentation possible to ensure successful use of your Microchip products. To this end, we will continue to improve our publications to better suit your needs. Our publications will be refined and enhanced as new volumes and updates are introduced. If you have any questions or comments regarding this publication, please contact the Marketing Communications Department via E-mail at docerrors@microchip.com. We welcome your feedback. Most Current Data Sheet To obtain the most up-to-date version of this data sheet, please register at our Worldwide Web site at: http://www.microchip.com You can determine the version of a data sheet by examining its literature number found on the bottom outside corner of any page. The last character of the literature number is the version number, (e.g., DS30000000A is version A of document DS30000000). Errata An errata sheet, describing minor operational differences from the data sheet and recommended workarounds, may exist for current devices. As device/documentation issues become known to us, we will publish an errata sheet. The errata will specify the revision of silicon and revision of document to which it applies. To determine if an errata sheet exists for a particular device, please check with one of the following: • Microchip’s Worldwide Web site; http://www.microchip.com • Your local Microchip sales office (see last page) When contacting a sales office, please specify which device, revision of silicon and data sheet (include -literature number) you are using. Customer Notification System Register on our web site at www.microchip.com to receive the most current information on all of our products.  2015 Microchip Technology Inc. DS00001624B-page 3 CAP1106 Table of Contents 1.0 Block Diagram ................................................................................................................................................................................. 4 2.0 Pin Description ................................................................................................................................................................................ 5 3.0 Electrical Specifications .................................................................................................................................................................. 9 4.0 Communications ........................................................................................................................................................................... 12 5.0 General Description ...................................................................................................................................................................... 23 6.0 Register Description ...................................................................................................................................................................... 29 7.0 Package Information ..................................................................................................................................................................... 67 Appendix A: Device Delta ................................................................................................................................................................... 72 Appendix B: Data Sheet Revision History ........................................................................................................................................... 74 The Microchip Web Site ...................................................................................................................................................................... 76 Customer Change Notification Service ............................................................................................................................................... 76 Customer Support ............................................................................................................................................................................... 76 Product Identification System ............................................................................................................................................................. 77 CAP1106 DS00001624B-page 4  2015 Microchip Technology Inc. 1.0 BLOCK DIAGRAM SMBus / BC-Link Protocol VDD GND Capacitive Touch Sensing Algorithm CS1 CS2 CS3 CS4 CS5 SMCLK1 / BC_CLK2 SMDATA1 / BC_DATA2 ALERT#1 / BC_IRQ#2 1 = CAP1106-1 2 = CAP1106-2 CS6  2015 Microchip Technology Inc. DS00001624B-page 5 CAP1106 2.0 PIN DESCRIPTION FIGURE 2-1: CAP1106 Pin Diagram (10-Pin DFN) TABLE 2-1: PIN DESCRIPTION FOR CAP1106 Pin Number Pin Name Pin Function Pin Type Unused Connection 1 CS1 Capacitive Touch Sensor Input 1 AIO Connect to Ground 2 ALERT# ALERT# - Active low alert / interrupt output for SMBus alert OD (5V) Connect to Ground ALERT# - Active high alert / interrupt output for SMBus alert DO leave open 3 SMDATA SMDATA - Bi-directional, open-drain SMBus data - requires pull-up resistor DIOD (5V) n/a 4 SMCLK SMCLK - SMBus clock input - requires pull-up resistor DI (5V) n/a 5 VDD Positive Power supply Power n/a 6 CS6 Capacitive Touch Sensor Input 6 AIO Connect to Ground 7 CS5 Capacitive Touch Sensor Input 5 AIO Connect to Ground 8 CS4 Capacitive Touch Sensor Input 4 AIO Connect to Ground 9 CS3 Capacitive Touch Sensor Input 3 AIO Connect to Ground GND CS3 1 CS2 2 3 4 5 CS4 CS1 ALERT# / BC_IRQ# SMDATA / BC_DATA VDD SMCLK / BC_CLK CS5 CS6 CAP1106 3mm x 3mm DFN 10 9 8 7 6 CAP1106 DS00001624B-page 6  2015 Microchip Technology Inc. APPLICATION NOTE: When the ALERT# pin is configured as an active low output, it will be open drain. When it is configured as an active high output, it will be push-pull. APPLICATION NOTE: For the 5V tolerant pins that have a pull-up resistor, the pull-up voltage must not exceed 3.6V when the CAP1106 is unpowered. The pin types are described in Table 2-2. All pins labeled with (5V) are 5V tolerant. 10 CS2 Capacitive Touch Sensor Input 2 AIO Connect to Ground Bottom Pad GND Ground Power n/a TABLE 2-2: PIN TYPES Pin Type Description Power This pin is used to supply power or ground to the device. DI Digital Input - This pin is used as a digital input. This pin is 5V tolerant. AIO Analog Input / Output -This pin is used as an I/O for analog signals. DIOD Digital Input / Open Drain Output - This pin is used as a digital I/O. When it is used as an output, it is open drain and requires a pull-up resistor. This pin is 5V tolerant. OD Open Drain Digital Output - This pin is used as a digital output. It is open drain and requires a pull-up resistor. This pin is 5V tolerant. DO Push-pull Digital Output - This pin is used as a digital output and can sink and source current. DIO Push-pull Digital Input / Output - This pin is used as an I/O for digital signals. TABLE 2-1: PIN DESCRIPTION FOR CAP1106 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection  2015 Microchip Technology Inc. DS00001624B-page 7 CAP1106 3.0 ELECTRICAL SPECIFICATIONS Note 3-1 Stresses above those listed could cause permanent damage to the device. This is a stress rating only and functional operation of the device at any other condition above those indicated in the operation sections of this specification is not implied. Note 3-2 For the 5V tolerant pins that have a pull-up resistor, the voltage difference between V5VT_PIN and VDD must never exceed 3.6V. Note 3-3 The Package Power Dissipation specification assumes a recommended thermal via design consisting of a 2x2 matrix of 0.3mm (12mil) vias at 1.0mm pitch connected to the ground plane with a 1.6 x 2.3mm thermal landing. TABLE 3-1: ABSOLUTE MAXIMUM RATINGS Voltage on 5V tolerant pins (V5VT_PIN) -0.3 to 5.5 V Voltage on 5V tolerant pins (|V5VT_PIN - VDD|) Note 3-2 0 to 3.6 V Voltage on VDD pin -0.3 to 4 V Voltage on any other pin to GND -0.3 to VDD + 0.3 V Package Power Dissipation up to TA = 85°C for 10 pin DFN (see Note 3-3) 0.7 W Junction to Ambient (θJA) 77.7 °C/W Operating Ambient Temperature Range -40 to 125 °C Storage Temperature Range -55 to 150 °C ESD Rating, All Pins, HBM 8000 V CAP1106 DS00001624B-page 8  2015 Microchip Technology Inc. TABLE 3-2: ELECTRICAL SPECIFICATIONS VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions DC Power Supply Voltage VDD 3.0 3.3 3.6 V Supply Current ISTBY 120 170 uA Standby state active 1 sensor input monitored Default conditions (8 avg, 70ms cycle time) ISTBY 50 uA Standby state active 1 sensor input monitored 1 avg, 140ms cycle time, IDSLEEP 5 15 uA Deep Sleep state active No communications TA < 40°C 3.135 < VDD < 3.465V IDD 500 600 uA Capacitive Sensing Active Capacitive Touch Sensor Inputs Maximum Base Capacitance CBASE 50 pF Pad untouched Minimum Detectable Capacitive Shift ΔCTOUCH 20 fF Pad touched - default conditions (1 avg, 35ms cycle time, 1x sensitivity) Recommended Cap Shift ΔCTOUCH 0.1 2 pF Pad touched - Not tested Power Supply Rejection PSR ±3 ±10 counts / V Untouched Current Counts Base Capacitance 5pF - 50pF Maximum sensitivity Negative Delta Counts disabled All other parameters default Timing Time to communications ready tCOMM_DLY 15 ms Time to first conversion ready tCONV_DLY 170 200 ms I/O Pins Output Low Voltage VOL 0.4 V ISINK_IO = 8mA Output High Voltage VOH VDD - 0.4 V ISOURCE_IO = 8mA Input High Voltage VIH 2.0 V Input Low Voltage VIL 0.8 V Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered SMBus Timing Input Capacitance CIN 5 pF Clock Frequency fSMB 10 400 kHz Spike Suppression tSP 50 ns Bus Free Time Stop to Start tBUF 1.3 us Start Setup Time tSU:STA 0.6 us  2015 Microchip Technology Inc. DS00001624B-page 9 CAP1106 Note 3-4 The ALERT pin will not glitch high or low at power up if connected to VDD or another voltage. Note 3-5 The SMCLK and SMDATA pins will not glitch low at power up if connected to VDD or another voltage. Start Hold Time tHD:STA 0.6 us Stop Setup Time tSU:STO 0.6 us Data Hold Time tHD:DAT 0 us When transmitting to the master Data Hold Time tHD:DAT 0.3 us When receiving from the master Data Setup Time tSU:DAT 0.6 us Clock Low Period tLOW 1.3 us Clock High Period tHIGH 0.6 us Clock / Data Fall Time tFALL 300 ns Min = 20+0.1CLOAD ns Clock / Data Rise Time tRISE 300 ns Min = 20+0.1CLOAD ns Capacitive Load CLOAD 400 pF per bus line TABLE 3-2: ELECTRICAL SPECIFICATIONS (CONTINUED) VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions CAP1106 DS00001624B-page 10  2015 Microchip Technology Inc. 4.0 COMMUNICATIONS 4.1 Communications The CAP1106 communicates using the SMBus or I2C protocol. If the proprietary BC-Link protocol is required for your application, please contact your Microchip representative for ordering instructions. Regardless of the communications mechanism, the device functionality remains unchanged. 4.1.1 SMBUS (I2C) COMMUNICATIONS The supports the following protocols: Send Byte, Receive Byte, Read Byte, Write Byte, Read Block, and Write Block. In addition, the device supports I2C formatting for block read and block write protocols. See Section 4.2 and Section 4.3 for more information on the SMBus bus and protocols respectively. APPLICATION NOTE: Upon power up, the CAP1106 will not respond to any communications for up to 15ms. After this time, full functionality is available. 4.2 System Management Bus The CAP1106 communicates with a host controller, such as an SIO, through the SMBus. The SMBus is a two-wire serial communication protocol between a computer host and its peripheral devices. A detailed timing diagram is shown in Figure 4-1. Stretching of the SMCLK signal is supported; however, the CAP1106 will not stretch the clock signal. 4.2.1 SMBUS START BIT The SMBus Start bit is defined as a transition of the SMBus Data line from a logic ‘1’ state to a logic ‘0’ state while the SMBus Clock line is in a logic ‘1’ state. 4.2.2 SMBUS ADDRESS AND RD / WR BIT The SMBus Address Byte consists of the 7-bit slave address followed by the RD / WR indicator bit. If this RD / WR bit is a logic ‘0’, then the SMBus Host is writing data to the slave device. If this RD / WR bit is a logic ‘1’, then the SMBus Host is reading data from the slave device. The CAP1106 responds to SMBus address 0101_000(r/w). 4.2.3 SMBUS DATA BYTES All SMBus Data bytes are sent most significant bit first and composed of 8-bits of information. 4.2.4 SMBUS ACK AND NACK BITS The SMBus slave will acknowledge all data bytes that it receives. This is done by the slave device pulling the SMBus Data line low after the 8th bit of each byte that is transmitted. This applies to both the Write Byte and Block Write protocols. FIGURE 4-1: SMBus Timing Diagram SMDATA SMCLK TLOW TRISE THIGH TFALL TBUF THD:STA P S S - Start Condition P - Stop Condition THD:DAT TSU:DAT TSU:STA THD:STA P TSU:STO S  2015 Microchip Technology Inc. DS00001624B-page 11 CAP1106 The Host will NACK (not acknowledge) the last data byte to be received from the slave by holding the SMBus data line high after the 8th data bit has been sent. For the Block Read protocol, the Host will ACK each data byte that it receives except the last data byte. 4.2.5 SMBUS STOP BIT The SMBus Stop bit is defined as a transition of the SMBus Data line from a logic ‘0’ state to a logic ‘1’ state while the SMBus clock line is in a logic ‘1’ state. When the CAP1106 detects an SMBus Stop bit and it has been communicating with the SMBus protocol, it will reset its slave interface and prepare to receive further communications. 4.2.6 SMBUS TIMEOUT The CAP1106 includes an SMBus timeout feature. Following a 30ms period of inactivity on the SMBus where the SMCLK pin is held low, the device will timeout and reset the SMBus interface. The timeout function defaults to disabled. It can be enabled by setting the TIMEOUT bit in the Configuration register (see Section 6.6, "Configuration Registers"). 4.2.7 SMBUS AND I2C COMPATIBILITY The major differences between SMBus and I2C devices are highlighted here. For more information, refer to the SMBus 2.0 and I2C specifications. For information on using the CAP1106 in an I2C system, refer to AN 14.0 Dedicated Slave Devices in I2C Systems. 1. CAP1106 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. 2. Minimum frequency for SMBus communications is 10kHz. 3. The SMBus slave protocol will reset if the clock is held at a logic ‘0’ for longer than 30ms. This timeout functionality is disabled by default in the CAP1106 and can be enabled by writing to the TIMEOUT bit. I2C does not have a timeout. 4. The SMBus slave protocol will reset if both the clock and data lines are held at a logic ‘1’ for longer than 200µs (idle condition). This function is disabled by default in the CAP1106 and can be enabled by writing to the TIMEOUT bit. I2C does not have an idle condition. 5. I2C devices do not support the Alert Response Address functionality (which is optional for SMBus). 6. I2C devices support block read and write differently. I2C protocol allows for unlimited number of bytes to be sent in either direction. The SMBus protocol requires that an additional data byte indicating number of bytes to read / write is transmitted. The CAP1106 supports I2C formatting only. 4.3 SMBus Protocols The CAP1106 is SMBus 2.0 compatible and supports Write Byte, Read Byte, Send Byte, and Receive Byte as valid protocols as shown below. All of the below protocols use the convention in Table 4-1. 4.3.1 SMBUS WRITE BYTE The Write Byte is used to write one byte of data to a specific register as shown in Table 4-2. 4.3.2 SMBUS READ BYTE The Read Byte protocol is used to read one byte of data from the registers as shown in Table 4-3. TABLE 4-1: PROTOCOL FORMAT Data Sent to Device Data Sent to the HOst Data sent Data sent TABLE 4-2: WRITE BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK Stop 1 ->0 0101_000 0 0 XXh 0 XXh 0 0 -> 1 CAP1106 DS00001624B-page 12  2015 Microchip Technology Inc. 4.3.3 SMBUS SEND BYTE The Send Byte protocol is used to set the internal address register pointer to the correct address location. No data is transferred during the Send Byte protocol as shown in Table 4-4. APPLICATION NOTE: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.3.4 SMBUS RECEIVE BYTE The Receive Byte protocol is used to read data from a register when the internal register address pointer is known to be at the right location (e.g., set via Send Byte). This is used for consecutive reads of the same register as shown in Table 4-5. APPLICATION NOTE: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.4 I2C Protocols The CAP1106 supports I2C Block Write and Block Read. The protocols listed below use the convention in Table 4-1. 4.4.1 BLOCK WRITE The Block Write is used to write multiple data bytes to a group of contiguous registers as shown in Table 4-6. APPLICATION NOTE: When using the Block Write protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.4.2 BLOCK READ The Block Read is used to read multiple data bytes from a group of contiguous registers as shown in Table 4-7. APPLICATION NOTE: When using the Block Read protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. TABLE 4-3: READ BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data NACK Stop 1->0 0101_000 0 0 XXh 0 1 ->0 0101_000 1 0 XXh 1 0 -> 1 TABLE 4-4: SEND BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Stop 1 -> 0 0101_000 0 0 XXh 0 0 -> 1 TABLE 4-5: RECEIVE BYTE PROTOCOL Start Slave Address RD ACK Register Data NACK Stop 1 -> 0 0101_000 1 0 XXh 1 0 -> 1 TABLE 4-6: BLOCK WRITE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK 1 ->0 0101_000 0 0 XXh 0 XXh 0 Register Data ACK Register Data ACK . . . Register Data ACK Stop XXh 0 XXh 0 . . . XXh 0 0 -> 1  2015 Microchip Technology Inc. DS00001624B-page 13 CAP1106 4.5 BC-Link Interface The BC-Link is a proprietary bus developed to allow communication between a host controller device to a companion device. This device uses this serial bus to read and write registers and for interrupt processing. The interface uses a data port concept, where the base interface has an address register, data register and a control register, defined in the 8051’s SFR space. Refer to documentation for the BC-Link compatible host controller for details on how to access the CAP1106-2 via the BC-Link Interface. TABLE 4-7: BLOCK READ PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data 1->0 0101_000 0 0 XXh 0 1 ->0 0101_000 1 0 XXh ACK Register Data ACK Register Data ACK Register Data ACK . . . Register Data NACK Stop 0 XXh 0 XXh 0 XXh 0 . . . XXh 1 0 -> 1 CAP1106 DS00001624B-page 14  2015 Microchip Technology Inc. 5.0 GENERAL DESCRIPTION The CAP1106 is a multiple channel Capacitive Touch sensor. The CAP1106 contains six (6) individual capacitive touch sensor inputs. The device offers programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1106 offers multiple power states. It operates at the lowest quiescent current during its Deep Sleep state. In the low power Standby state, it can monitor one or more channels and respond to communications normally. The device communicates with a host controller using or via SMBus / I2C. The host controller may poll the device for updated information at any time or it may configure the device to flag an interrupt whenever a touch is detected on any sensor pad. A typical system diagram for the CAP1106 is shown in Figure 5-1. FIGURE 5-1: System Diagram for CAP1106 CAP1106 CS6 SMDATA1 / BC_DATA2 SMCLK1 / BC_CLK2 VDD Embedded Controller ALERT#1 / BC_IRQ#2 CS4 CS2 CS5 CS3 CS1 Touch Button Touch Button Touch Button Touch Button Touch Button Touch Button 1 = CAP1106-1 2 = CAP1106-2  2015 Microchip Technology Inc. DS00001624B-page 15 CAP1106 5.1 Power States The CAP1106 has three operating states depending on the status of the STBY and DSLEEP bits. When the device transitions between power states, previously detected touches (for inactive channels) are cleared and the status bits reset. 1. Fully Active - The device is fully active. It is monitoring all active capacitive sensor inputs. 2. Standby - The device is in a lower power state. It will measure a programmable number of channels using the Standby Configuration controls (see Section 6.20 through Section 6.22). Interrupts will still be generated based on the active channels. The device will still respond to communications normally and can be returned to the Fully Active state of operation by clearing the STBY bit. 3. Deep Sleep - The device is in its lowest power state. It is not monitoring any capacitive sensor inputs. While in Deep Sleep, the device can be awakened by SMBus or SPI communications targeting the device. This will not cause the DSLEEP to be cleared so the device will return to Deep Sleep once all communications have stopped. 5.2 Capacitive Touch Sensing The CAP1106 contains six (6) independent capacitive touch sensor inputs. Each sensor input has dynamic range to detect a change of capacitance due to a touch. Additionally, each sensor input can be configured to be automatically and routinely re-calibrated. 5.2.1 SENSING CYCLE Each capacitive touch sensor input has controls to be activated and included in the sensing cycle. When the device is active, it automatically initiates a sensing cycle and repeats the cycle every time it finishes. The cycle polls through each active sensor input starting with CS1 and extending through CS6. As each capacitive touch sensor input is polled, its measurement is compared against a baseline “Not Touched” measurement. If the delta measurement is large enough, a touch is detected and an interrupt is generated. The sensing cycle time is programmable (see Section 6.10, "Averaging and Sampling Configuration Register"). 5.2.2 RECALIBRATING SENSOR INPUTS There are various options for recalibrating the capacitive touch sensor inputs. Recalibration re-sets the Base Count Registers (Section 6.24, "Sensor Input Base Count Registers") which contain the “not touched” values used for touch detection comparisons. APPLICATION NOTE: The device will recalibrate all sensor inputs that were disabled when it transitions from Standby. Likewise, the device will recalibrate all sensor inputs when waking out of Deep Sleep. 5.2.2.1 Manual Recalibration The Calibration Activate Registers (Section 6.11, "Calibration Activate Register") force recalibration of selected sensor inputs. When a bit is set, the corresponding capacitive touch sensor input will be recalibrated (both analog and digital). The bit is automatically cleared once the recalibration routine has finished. 5.2.2.2 Automatic Recalibration Each sensor input is regularly recalibrated at a programmable rate (see Section 6.17, "Recalibration Configuration Register"). By default, the recalibration routine stores the average 64 previous measurements and periodically updates the base “not touched” setting for the capacitive touch sensor input. Note: During this recalibration routine, the sensor inputs will not detect a press for up to 200ms and the Sensor Base Count Register values will be invalid. In addition, any press on the corresponding sensor pads will invalidate the recalibration. Note: Automatic recalibration only works when the delta count is below the active sensor input threshold. It is disabled when a touch is detected. CAP1106 DS00001624B-page 16  2015 Microchip Technology Inc. 5.2.2.3 Negative Delta Count Recalibration It is possible that the device loses sensitivity to a touch. This may happen as a result of a noisy environment, an accidental recalibration during a touch, or other environmental changes. When this occurs, the base untouched sensor input may generate negative delta count values. The NEG_DELTA_CNT bits (see Section 6.17, "Recalibration Configuration Register") can be set to force a recalibration after a specified number of consecutive negative delta readings. 5.2.2.4 Delayed Recalibration It is possible that a “stuck button” occurs when something is placed on a button which causes a touch to be detected for a long period. By setting the MAX_DUR_EN bit (see Section 6.6, "Configuration Registers"), a recalibration can be forced when a touch is held on a button for longer than the duration specified in the MAX_DUR bits (see Section 6.8, "Sensor Input Configuration Register"). 5.2.3 PROXIMITY DETECTION Each sensor input can be configured to detect changes in capacitance due to proximity of a touch. This circuitry detects the change of capacitance that is generated as an object approaches, but does not physically touch, the enabled sensor pad(s). When a sensor input is selected to perform proximity detection, it will be sampled from 1x to 128x per sampling cycle. The larger the number of samples that are taken, the greater the range of proximity detection is available at the cost of an increased overall sampling time. 5.2.4 MULTIPLE TOUCH PATTERN DETECTION The multiple touch pattern (MTP) detection circuitry can be used to detect lid closure or other similar events. An event can be flagged based on either a minimum number of sensor inputs or on specific sensor inputs simultaneously exceeding an MTP threshold or having their Noise Flag Status Register bits set. An interrupt can also be generated. During an MTP event, all touches are blocked (see Section 6.15, "Multiple Touch Pattern Configuration Register"). 5.2.5 LOW FREQUENCY NOISE DETECTION Each sensor input has an EMI noise detector that will sense if low frequency noise is injected onto the input with sufficient power to corrupt the readings. If this occurs, the device will reject the corrupted sample and set the corresponding bit in the Noise Status register to a logic ‘1’. 5.2.6 RF NOISE DETECTION Each sensor input contains an integrated RF noise detector. This block will detect injected RF noise on the CS pin. The detector threshold is dependent upon the noise frequency. If RF noise is detected on a CS line, that sample is removed and not compared against the threshold. 5.3 ALERT# Pin The ALERT# pin is an active low (or active high when configured) output that is driven when an interrupt event is detected. Whenever an interrupt is generated, the INT bit (see Section 6.1, "Main Control Register") is set. The ALERT# pin is cleared when the INT bit is cleared by the user. Additionally, when the INT bit is cleared by the user, status bits are only cleared if no touch is detected. 5.3.1 SENSOR INTERRUPT BEHAVIOR The sensor interrupts are generated in one of two ways: 1. An interrupt is generated when a touch is detected and, as a user selectable option, when a release is detected (by default - see Section 6.6). See Figure 5-3. 2. If the repeat rate is enabled then, so long as the touch is held, another interrupt will be generated based on the programmed repeat rate (see Figure 5-2). Note: During this recalibration, the device will not respond to touches. Note: Delayed recalibration only works when the delta count is above the active sensor input threshold. If enabled, it is invoked when a sensor pad touch is held longer than the MAX_DUR bit setting.  2015 Microchip Technology Inc. DS00001624B-page 17 CAP1106 When the repeat rate is enabled, the device uses an additional control called MPRESS that determines whether a touch is flagged as a simple “touch” or a “press and hold”. The MPRESS[3:0] bits set a minimum press timer. When the button is touched, the timer begins. If the sensor pad is released before the minimum press timer expires, it is flagged as a touch and an interrupt is generated upon release. If the sensor input detects a touch for longer than this timer value, it is flagged as a “press and hold” event. So long as the touch is held, interrupts will be generated at the programmed repeat rate and upon release (if enabled). APPLICATION NOTE: Figure 5-2 and Figure 5-3 show default operation which is to generate an interrupt upon sensor pad release and an active-low ALERT# pin. APPLICATION NOTE: The host may need to poll the device twice to determine that a release has been detected. FIGURE 5-2: Sensor Interrupt Behavior - Repeat Rate Enabled FIGURE 5-3: Sensor Interrupt Behavior - No Repeat Rate Enabled Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Min Press Setting (280ms) Interrupt on Touch Button Repeat Rate (175ms) Button Repeat Rate (175ms) Interrupt on Release (optional) ALERT# pin (active low) Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Interrupt on Touch Interrupt on Release (optional) ALERT# pin (active low) CAP1106 DS00001624B-page 18  2015 Microchip Technology Inc. 6.0 REGISTER DESCRIPTION The registers shown in Table 6-1 are accessible through the communications protocol. An entry of ‘-’ indicates that the bit is not used and will always read ‘0’. TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER Register Address R/W Register Name Function Default Value Page 00h R/W Main Control Controls general power states and power dissipation 00h Page 20 02h R General Status Stores general status bits 00h Page 21 03h R Sensor Input Status Returns the state of the sampled capacitive touch sensor inputs 00h Page 21 0Ah R Noise Flag Status Stores the noise flags for sensor inputs 00h Page 22 10h R Sensor Input 1 Delta Count Stores the delta count for CS1 00h Page 22 11h R Sensor Input 2 Delta Count Stores the delta count for CS2 00h Page 22 12h R Sensor Input 3 Delta Count Stores the delta count for CS3 00h Page 22 13h R Sensor Input 4 Delta Count Stores the delta count for CS4 00h Page 22 14h R Sensor Input 5 Delta Count Stores the delta count for CS5 00h Page 22 15h R Sensor Input 6 Delta Count Stores the delta count for CS6 00h Page 22 1Fh R/W Sensitivity Control Controls the sensitivity of the threshold and delta counts and data scaling of the base counts 2Fh Page 22 20h R/W Configuration Controls general functionality 20h Page 24 21h R/W Sensor Input Enable Controls whether the capacitive touch sensor inputs are sampled 3Fh Page 25 22h R/W Sensor Input Configuration Controls max duration and auto-repeat delay for sensor inputs operating in the full power state A4h Page 25 23h R/W Sensor Input Configuration 2 Controls the MPRESS controls for all sensor inputs 07h Page 26 24h R/W Averaging and Sampling Config Controls averaging and sampling window 39h Page 27 26h R/W Calibration Activate Forces re-calibration for capacitive touch sensor inputs 00h Page 28 27h R/W Interrupt Enable Enables Interrupts associated with capacitive touch sensor inputs 3Fh Page 29 28h R/W Repeat Rate Enable Enables repeat rate for all sensor inputs 3Fh Page 29 2Ah R/W Multiple Touch Configuration Determines the number of simultaneous touches to flag a multiple touch condition 80h Page 30 2Bh R/W Multiple Touch Pattern Configuration Determines the multiple touch pattern (MTP) configuration 00h Page 30 2Dh R/W Multiple Touch Pattern Determines the pattern or number of sensor inputs used by the MTP circuitry 3Fh Page 31  2015 Microchip Technology Inc. DS00001624B-page 19 CAP1106 2Fh R/W Recalibration Configuration Determines re-calibration timing and sampling window 8Ah Page 32 30h R/W Sensor Input 1 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 1 40h Page 33 31h R/W Sensor Input 2 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 2 40h Page 33 32h R/W Sensor Input 3 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 3 40h Page 33 33h R/W Sensor Input 4 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 4 40h Page 33 34h R/W Sensor Input 5 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 5 40h Page 33 35h R/W Sensor Input 6 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 6 40h Page 33 38h R/W Sensor Input Noise Threshold Stores controls for selecting the noise threshold for all sensor inputs 01h Page 33 Standby Configuration Registers 40h R/W Standby Channel Controls which sensor inputs are enabled while in standby 00h Page 34 41h R/W Standby Configuration Controls averaging and cycle time while in standby 39h Page 34 42h R/W Standby Sensitivity Controls sensitivity settings used while in standby 02h Page 35 43h R/W Standby Threshold Stores the touch detection threshold for active sensor inputs in standby 40h Page 36 44h R/W Configuration 2 Stores additional configuration controls for the device 40h Page 24 Base Count Registers 50h R Sensor Input 1 Base Count Stores the reference count value for sensor input 1 C8h Page 36 51h R Sensor Input 2 Base Count Stores the reference count value for sensor input 2 C8h Page 36 52h R Sensor Input 3 Base Count Stores the reference count value for sensor input 3 C8h Page 36 53h R Sensor Input 4 Base Count Stores the reference count value for sensor input 4 C8h Page 36 54h R Sensor Input 5 Base Count Stores the reference count value for sensor input 5 C8h Page 36 55h R Sensor Input 6 Base Count Stores the reference count value for sensor input 6 C8h Page 36 B1h R Sensor Input 1 Calibration Stores the upper 8-bit calibration value for sensor input 1 00h Page 37 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1106 DS00001624B-page 20  2015 Microchip Technology Inc. During Power-On-Reset (POR), the default values are stored in the registers. A POR is initiated when power is first applied to the part and the voltage on the VDD supply surpasses the POR level as specified in the electrical characteristics. Any reads to undefined registers will return 00h. Writes to undefined registers will not have an effect. When a bit is “set”, this means that the user writes a logic ‘1’ to it. When a bit is “cleared”, this means that the user writes a logic ‘0’ to it. 6.1 Main Control Register The Main Control register controls the primary power state of the device. Bits 7 - 6 - GAIN[1:0] - Controls the gain used by the capacitive touch sensing circuitry. As the gain is increased, the effective sensitivity is likewise increased as a smaller delta capacitance is required to generate the same delta count values. The sensitivity settings may need to be adjusted along with the gain settings such that data overflow does not occur. APPLICATION NOTE: The gain settings apply to both Standby and Active states. B2h R Sensor Input 2 Calibration Stores the upper 8-bit calibration value for sensor input 2 00h Page 37 B3h R Sensor Input 3 Calibration Stores the upper 8-bit calibration value for sensor input 3 00h Page 37 B4h R Sensor Input 4 Calibration Stores the upper 8-bit calibration value for sensor input 4 00h Page 37 B5h R Sensor Input 5 Calibration Stores the upper 8-bit calibration value for sensor input 5 00h Page 37 B6h R Sensor Input 6 Calibration Stores the upper 8-bit calibration value for sensor input 6 00h Page 37 B9h R Sensor Input Calibration LSB 1 Stores the 2 LSBs of the calibration value for sensor inputs 1 - 4 00h Page 37 BAh R Sensor Input Calibration LSB 2 Stores the 2 LSBs of the calibration value for sensor inputs 5- 6 00h Page 37 FDh R Product ID CAP1106 Stores a fixed value that identifies each product 55h Page 37 FEh R Manufacturer ID Stores a fixed value that identifies Microchip 5Dh Page 38 FFh R Revision Stores a fixed value that represents the revision number 83h Page 38 TABLE 6-2: MAIN CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 00h R/W Main Control GAIN[1:0] STBY DSLEEP - - - INT 00h TABLE 6-3: GAIN BIT DECODE GAIN[1:0] Capacitive Touch Sensor Gain 1 0 0 0 1 01 2 10 4 11 8 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page  2015 Microchip Technology Inc. DS00001624B-page 21 CAP1106 Bit 5 - STBY - Enables Standby. • ‘0’ (default) - Sensor input scanning is active. • ‘1’ - Capacitive touch sensor input scanning is limited to the sensor inputs set in the Standby Channel register (see Section 6.20). The status registers will not be cleared until read. Sensor inputs that are no longer sampled will flag a release and then remain in a non-touched state. • Bit 4 - DSLEEP - Enables Deep Sleep by deactivating all functions. ‘0’ (default) - Sensor input scanning is active. • ‘1’ - All sensor input scanning is disabled.. The status registers are automatically cleared and the INT bit is cleared. Bit 0 - INT - Indicates that there is an interrupt. When this bit is set, it asserts the ALERT# pin. If a channel detects a touch and its associated interrupt enable bit is not set to a logic ‘1’, no action is taken. This bit is cleared by writing a logic ‘0’ to it. When this bit is cleared, the ALERT# pin will be deasserted and all status registers will be cleared if the condition has been removed. • ‘0’ - No interrupt pending. • ‘1’ - A touch has been detected on one or more channels and the interrupt has been asserted. 6.2 Status Registers All status bits are cleared when the device enters the Deep Sleep (DSLEEP = ‘1’ - see Section 6.1). 6.2.1 GENERAL STATUS - 02H Bit 2 - MULT - Indicates that the device is blocking detected touches due to the Multiple Touch detection circuitry (see Section 6.14). This bit will not cause the INT bit to be set and hence will not cause an interrupt. Bit 1 - MTP - Indicates that the device has detected a number of sensor inputs that exceed the MTP threshold either via the pattern recognition or via the number of sensor inputs (see Section 6.15). This bit will cause the INT bit to be set if the MTP_ALERT bit is also set. This bit will not be cleared until the condition that caused it to be set has been removed. Bit 0 - TOUCH - Indicates that a touch was detected. This bit is set if any bit in the Sensor Input Status register is set. 6.2.2 SENSOR INPUT STATUS - 03H The Sensor Input Status Register stores status bits that indicate a touch has been detected. A value of ‘0’ in any bit indicates that no touch has been detected. A value of ‘1’ in any bit indicates that a touch has been detected. All bits are cleared when the INT bit is cleared and if a touch on the respective capacitive touch sensor input is no longer present. If a touch is still detected, the bits will not be cleared (but this will not cause the interrupt to be asserted - see Section 6.6). Bit 5 - CS6 - Indicates that a touch was detected on Sensor Input 6. Bit 4 - CS5 - Indicates that a touch was detected on Sensor Input 5. Bit 3 - CS4 - Indicates that a touch was detected on Sensor Input 4. Bit 2 - CS3 - Indicates that a touch was detected on Sensor Input 3. Bit 1 - CS2 - Indicates that a touch was detected on Sensor Input 2. Bit 0 - CS1 - Indicates that a touch was detected on Sensor Input 1. TABLE 6-4: STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 02h R General Status - - - - - MULT MTP TOUCH 00h 03h R Sensor Input Status - - CS6 CS5 CS4 CS3 CS2 CS1 00h CAP1106 DS00001624B-page 22  2015 Microchip Technology Inc. 6.3 Noise Flag Status Registers The Noise Flag Status registers store status bits that are generated from the analog block if the detected noise is above the operating region of the analog detector or the RF noise detector. These bits indicate that the most recently received data from the sensor input is invalid and should not be used for touch detection. So long as the bit is set for a particular channel, the delta count value is reset to 00h and thus no touch is detected. These bits are not sticky and will be cleared automatically if the analog block does not report a noise error. APPLICATION NOTE: If the MTP detection circuitry is enabled, these bits count as sensor inputs above the MTP threshold (see Section 5.2.4, "Multiple Touch Pattern Detection") even if the corresponding delta count is not. If the corresponding delta count also exceeds the MTP threshold, it is not counted twice. APPLICATION NOTE: Regardless of the state of the Noise Status bits, if low frequency noise is detected on a sensor input, that sample will be discarded unless the DIS_ANA_NOISE bit is set. As well, if RF noise is detected on a sensor input, that sample will be discarded unless the DIS_RF_NOISE bit is set. 6.4 Sensor Input Delta Count Registers The Sensor Input Delta Count registers store the delta count that is compared against the threshold used to determine if a touch has been detected. The count value represents a change in input due to the capacitance associated with a touch on one of the sensor inputs and is referenced to a calibrated base “Not Touched” count value. The delta is an instantaneous change and is updated once per sensor input per sensing cycle (see Section 5.2.1, "Sensing Cycle"). The value presented is a standard 2’s complement number. In addition, the value is capped at a value of 7Fh. A reading of 7Fh indicates that the sensitivity settings are too high and should be adjusted accordingly (see Section 6.5). The value is also capped at a negative value of 80h for negative delta counts which may result upon a release. 6.5 Sensitivity Control Register TABLE 6-5: NOISE FLAG STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 0Ah R Noise Flag Status - - CS6_ NOISE CS5_ NOISE CS4_ NOISE CS3_ NOISE CS2_ NOISE CS1_ NOISE 00h TABLE 6-6: SENSOR INPUT DELTA COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 10h R Sensor Input 1 Delta Count Sign 64 32 16 8 4 2 1 00h 11h R Sensor Input 2 Delta Count Sign 64 32 16 8 4 2 1 00h 12h R Sensor Input 3 Delta Count Sign 64 32 16 8 4 2 1 00h 13h R Sensor Input 4 Delta Count Sign 64 32 16 8 4 2 1 00h 14h R Sensor Input 5 Delta Count Sign 64 32 16 8 4 2 1 00h 15h R Sensor Input 6 Delta Count Sign 64 32 16 8 4 2 1 00h TABLE 6-7: SENSITIVITY CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 1Fh R/W Sensitivity Control - DELTA_SENSE[2:0] BASE_SHIFT[3:0] 2Fh  2015 Microchip Technology Inc. DS00001624B-page 23 CAP1106 The Sensitivity Control register controls the sensitivity of a touch detection. Bits 6-4 DELTA_SENSE[2:0] - Controls the sensitivity of a touch detection. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta capacitance corresponding to a “lighter” touch. These settings are more sensitive to noise, however, and a noisy environment may flag more false touches with higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely, a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). Bits 3 - 0 - BASE_SHIFT[3:0] - Controls the scaling and data presentation of the Base Count registers. The higher the value of these bits, the larger the range and the lower the resolution of the data presented. The scale factor represents the multiplier to the bit-weighting presented in these register descriptions. APPLICATION NOTE: The BASE_SHIFT[3:0] bits normally do not need to be updated. These settings will not affect touch detection or sensitivity. These bits are sometimes helpful in analyzing the Cap Sensing board performance and stability. TABLE 6-8: DELTA_SENSE BIT DECODE DELTA_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-9: BASE_SHIFT BIT DECODE BASE_SHIFT[3:0] Data Scaling Factor 32 1 0 0 0 0 0 1x 0 0 0 1 2x 0 0 1 0 4x 0 0 1 1 8x 0 1 0 0 16x 0 1 0 1 32x 0 1 1 0 64x 0 1 1 1 128x 1 0 0 0 256x All others 256x (default = 1111b) CAP1106 DS00001624B-page 24  2015 Microchip Technology Inc. 6.6 Configuration Registers The Configuration registers control general global functionality that affects the entire device. 6.6.1 CONFIGURATION - 20H Bit 7 - TIMEOUT - Enables the timeout and idle functionality of the SMBus protocol. • ‘0’ (default for Functional Revision C) - The SMBus timeout and idle functionality are disabled. The SMBus interface will not time out if the clock line is held low. Likewise, it will not reset if both the data and clock lines are held high for longer than 200us. This is used for I2C compliance. • ‘1’ (default for Functional Revision B) - The SMBus timeout and idle functionality are enabled. The SMBus interface will time out if the clock line is held low for longer than 30ms. Likewise, it will reset if both the data and clock lines are held high for longer than 200us. Bit 5 - DIS_DIG_NOISE - Determines whether the digital noise threshold (see Section 6.19, "Sensor Input Noise Threshold Register") is used by the device. Setting this bit disables the feature. • ‘0’ - The digital noise threshold is used. If a delta count value exceeds the noise threshold but does not exceed the touch threshold, the sample is discarded and not used for the automatic re-calibration routine. • ‘1’ (default) - The noise threshold is disabled. Any delta count that is less than the touch threshold is used for the automatic re-calibration routine. Bit 4 - DIS_ANA_NOISE - Determines whether the analog noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If low frequency noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if low frequency noise is detected. Bit 3 - MAX_DUR_EN - Determines whether the maximum duration recalibration is enabled. • ‘0’ (default) - The maximum duration recalibration functionality is disabled. A touch may be held indefinitely and no re-calibration will be performed on any sensor input. • ‘1’ - The maximum duration recalibration functionality is enabled. If a touch is held for longer than the MAX_DUR bit settings, then the re-calibration routine will be restarted (see Section 6.8). 6.6.2 CONFIGURATION 2 - 44H Bit 6 - ALT_POL - Determines the ALERT# pin polarity and behavior. • ‘0’ - The ALERT# pin is active high and push-pull. • ‘1’ (default) - The ALERT# pin is active low and open drain. Bit 5 - BLK_PWR_CTRL - Determines whether the device will reduce power consumption while waiting between conversion time completion and the end of the polling cycle. • ‘0’ (default) - The device will always power down as much as possible during the time between the end of the last conversion and the end of the polling cycle. • ‘1’ - The device will not power down the Cap Sensor during the time between the end of the last conversion and the end of the polling cycle. Bit 3 - SHOW_RF_NOISE - Determines whether the Noise Status bits will show RF Noise as the only input source. • ‘0’ (default) - The Noise Status registers will show both RF noise and low frequency EMI noise if either is detected on a capacitive touch sensor input. • ‘1’ - The Noise Status registers will only show RF noise if it is detected on a capacitive touch sensor input. EMI TABLE 6-10: CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 20h R/W Configuration TIMEOUT - DIS_ DIG_ NOISE DIS_ ANA_ NOISE MAX_ DUR_EN - -- A0h (Rev B) 20h (rev C) 44h R/W Configuration 2 - ALT_ POL BLK_PWR_ CTRL - SHOW_ RF_ NOISE DIS_ RF_ NOISE - INT_ REL_n 40h  2015 Microchip Technology Inc. DS00001624B-page 25 CAP1106 noise will still be detected and touches will be blocked normally; however, the status bits will not be updated. Bit 2 - DIS_RF_NOISE - Determines whether the RF noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If RF noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if RF noise is detected. Bit 0 - INT_REL_n - Controls the interrupt behavior when a release is detected on a button. • ‘0’ (default) - An interrupt is generated when a press is detected and again when a release is detected and at the repeat rate (if enabled - see Section 6.13). • ‘1’ - An interrupt is generated when a press is detected and at the repeat rate but not when a release is detected. 6.7 Sensor Input Enable Registers The Sensor Input Enable registers determine whether a capacitive touch sensor input is included in the sampling cycle. The length of the sampling cycle is not affected by the number of sensor inputs measured. Bit 5 - CS6_EN - Enables the CS6 input to be included during the sampling cycle. • ‘0’ - The CS6 input is not included in the sampling cycle. • ‘1’ (default) - The CS6 input is included in the sampling cycle. Bit 4 - CS5_EN - Enables the CS5 input to be included during the sampling cycle. Bit 3 - CS4_EN - Enables the CS4 input to be included during the sampling cycle. Bit 2 - CS3_EN - Enables the CS3 input to be included during the sampling cycle. Bit 1 - CS2_EN - Enables the CS2 input to be included during the sampling cycle. Bit 0 - CS1_EN - Enables the CS1 input to be included during the sampling cycle. 6.8 Sensor Input Configuration Register The Sensor Input Configuration Register controls timings associated with the Capacitive sensor inputs 1 - 6. Bits 7 - 4 - MAX_DUR[3:0] - (default 1010b) - Determines the maximum time that a sensor pad is allowed to be touched until the capacitive touch sensor input is recalibrated, as shown in Table 6-13. TABLE 6-11: SENSOR INPUT ENABLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 21h R/W Sensor Input Enable - - CS6_EN CS5_EN CS4_EN CS3_EN CS2_EN CS1_EN 3Fh TABLE 6-12: SENSOR INPUT CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 22h R/W Sensor Input Configuration MAX_DUR[3:0] RPT_RATE[3:0] A4h TABLE 6-13: MAX_DUR BIT DECODE MAX_DUR[3:0] Time Before Recalibration 32 1 0 0 0 0 0 560ms 0 0 0 1 840ms 0 0 1 0 1120ms 0 0 1 1 1400ms 0 1 0 0 1680ms 0 1 0 1 2240ms 0 1 1 0 2800ms CAP1106 DS00001624B-page 26  2015 Microchip Technology Inc. Bits 3 - 0 - RPT_RATE[3:0] - (default 0100b) Determines the time duration between interrupt assertions when auto repeat is enabled. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-14. 6.9 Sensor Input Configuration 2 Register Bits 3 - 0 - M_PRESS[3:0] - (default 0111b) - Determines the minimum amount of time that sensor inputs configured to use auto repeat must detect a sensor pad touch to detect a “press and hold” event. If the sensor input detects a touch for longer than the M_PRESS[3:0] settings, a “press and hold” event is detected. If a sensor input detects a touch for less than or equal to the M_PRESS[3:0] settings, a touch event is detected. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-16. 1 1 1 3360ms 1 0 0 0 3920ms 1 0 0 1 4480ms 1 0 1 0 5600ms (default) 1 0 1 1 6720ms 1 1 0 0 7840ms 1 1 0 1 8906ms 1 1 1 0 10080ms 1 1 1 1 11200ms TABLE 6-14: RPT_RATE BIT DECODE RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms (default) 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-15: SENSOR INPUT CONFIGURATION 2 REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 23h R/W Sensor Input Configuration 2 - - - - M_PRESS[3:0] 07h TABLE 6-13: MAX_DUR BIT DECODE (CONTINUED) MAX_DUR[3:0] Time Before Recalibration 32 1 0  2015 Microchip Technology Inc. DS00001624B-page 27 CAP1106 6.10 Averaging and Sampling Configuration Register The Averaging and Sampling Configuration register controls the number of samples taken and the total sensor input cycle time for all active sensor inputs while the device is functioning in Active state. Bits 6 - 4 - AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-18. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. For example, if CS1, CS2, and CS3 are sampled during the sensor cycle, and the AVG[2:0] bits are set to take 4 samples per channel, then the full sensor cycle will be: CS1, CS1, CS1, CS1, CS2, CS2, CS2, CS2, CS3, CS3, CS3, CS3. Bits 3 - 2 - SAMP_TIME[1:0] - Determines the time to take a single sample as shown in Table 6-19. TABLE 6-16: M_PRESS BIT DECODE M_PRESS[3:0] M_PRESS SETTINGS 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms (default) 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-17: AVERAGING AND SAMPLING CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 24h R/W Averaging and Sampling Config AVG[2:0] SAMP_TIME[1:0] CYCLE_TIME [1:0] 39h TABLE 6-18: AVG BIT DECODE AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 CAP1106 DS00001624B-page 28  2015 Microchip Technology Inc. Bits 1 - 0 - CYCLE_TIME[1:0] - Determines the overall cycle time for all measured channels during normal operation as shown in Table 6-20. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, then the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. 6.11 Calibration Activate Register The Calibration Activate register forces the respective sensor inputs to be re-calibrated affecting both the analog and digital blocks. During the re-calibration routine, the sensor inputs will not detect a press for up to 600ms and the Sensor Input Base Count register values will be invalid. During this time, any press on the corresponding sensor pads will invalidate the re-calibration. When finished, the CALX[9:0] bits will be updated (see Section 6.25). When the corresponding bit is set, the device will perform the calibration and the bit will be automatically cleared once the re-calibration routine has finished. Bit 5 - CS6_CAL - When set, the CS6 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 4 - CS5_CAL - When set, the CS5 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 3 - CS4_CAL - When set, the CS4 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 2 - CS3_CAL - When set, the CS3 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 1 - CS2_CAL - When set, the CS2 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 0 - CS1_CAL - When set, the CS1 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. TABLE 6-19: SAMP_TIME BIT DECODE SAMP_TIME[1:0] Sample Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-20: CYCLE_TIME BIT DECODE CYCLE_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms TABLE 6-21: CALIBRATION ACTIVATE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 26h R/W Calibration Activate - - CS6_ CAL CS5_ CAL CS4_ CAL CS3_ CAL CS2_ CAL CS1_ CAL 00h  2015 Microchip Technology Inc. DS00001624B-page 29 CAP1106 6.12 Interrupt Enable Register The Interrupt Enable register determines whether a sensor pad touch or release (if enabled) causes the interrupt pin to be asserted. Bit 5 - CS6_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS6 (associated with the CS6 status bit). • ‘0’ - The interrupt pin will not be asserted if a touch is detected on CS6 (associated with the CS6 status bit). • ‘1’ (default) - The interrupt pin will be asserted if a touch is detected on CS6 (associated with the CS6 status bit). Bit 4 - CS5_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS5 (associated with the CS5 status bit). Bit 3 - CS4_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS4 (associated with the CS4 status bit). Bit 2 - CS3_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS3 (associated with the CS3 status bit). Bit 1 - CS2_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS2 (associated with the CS2 status bit). Bit 0 - CS1_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS1 (associated with the CS1 status bit). 6.13 Repeat Rate Enable Register The Repeat Rate Enable register enables the repeat rate of the sensor inputs as described in Section 5.3.1. Bit 5 - CS6_RPT_EN - Enables the repeat rate for capacitive touch sensor input 6. • ‘0’ - The repeat rate for CS6 is disabled. It will only generate an interrupt when a touch is detected and when a release is detected no matter how long the touch is held for. • ‘1’ (default) - The repeat rate for CS6 is enabled. In the case of a “touch” event, it will generate an interrupt when a touch is detected and a release is detected (as determined by the INT_REL_n bit - see Section 6.6). In the case of a “press and hold” event, it will generate an interrupt when a touch is detected and at the repeat rate so long as the touch is held. Bit 4 - CS5_RPT_EN - Enables the repeat rate for capacitive touch sensor input 5. Bit 3 - CS4_RPT_EN - Enables the repeat rate for capacitive touch sensor input 4. Bit 2 - CS3_RPT_EN - Enables the repeat rate for capacitive touch sensor input 3. Bit 1 - CS2_RPT_EN - Enables the repeat rate for capacitive touch sensor input 2. Bit 0 - CS1_RPT_EN - Enables the repeat rate for capacitive touch sensor input 1. TABLE 6-22: INTERRUPT ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 27h R/W Interrupt Enable - - CS6_ INT_EN CS5_ INT_EN CS4_ INT_EN CS3_ INT_EN CS2_ INT_EN CS1_ INT_EN 3Fh TABLE 6-23: REPEAT RATE ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 28h R/W Repeat Rate Enable - - CS6_ RPT_EN CS5_ RPT_EN CS4_ RPT_EN CS3_ RPT_EN CS2_ RPT_EN CS1_ RPT_EN 3Fh CAP1106 DS00001624B-page 30  2015 Microchip Technology Inc. 6.14 Multiple Touch Configuration Register The Multiple Touch Configuration register controls the settings for the multiple touch detection circuitry. These settings determine the number of simultaneous buttons that may be pressed before additional buttons are blocked and the MULT status bit is set. Bit 7 - MULT_BLK_EN - Enables the multiple button blocking circuitry. • ‘0’ - The multiple touch circuitry is disabled. The device will not block multiple touches. • ‘1’ (default) - The multiple touch circuitry is enabled. The device will flag the number of touches equal to programmed multiple touch threshold and block all others. It will remember which sensor inputs are valid and block all others until that sensor pad has been released. Once a sensor pad has been released, the N detected touches (determined via the cycle order of CS1 - CS6) will be flagged and all others blocked. Bits 3 - 2 - B_MULT_T[1:0] - Determines the number of simultaneous touches on all sensor pads before a Multiple Touch Event is detected and sensor inputs are blocked. The bit decode is given by Table 6-25. 6.15 Multiple Touch Pattern Configuration Register The Multiple Touch Pattern Configuration register controls the settings for the multiple touch pattern detection circuitry. This circuitry works like the multiple touch detection circuitry with the following differences: 1. The detection threshold is a percentage of the touch detection threshold as defined by the MTP_TH[1:0] bits whereas the multiple touch circuitry uses the touch detection threshold. 2. The MTP detection circuitry either will detect a specific pattern of sensor inputs as determined by the Multiple Touch Pattern register settings or it will use the Multiple Touch Pattern register settings to determine a minimum number of sensor inputs that will cause the MTP circuitry to flag an event. When using pattern recognition mode, if all of the sensor inputs set by the Multiple Touch Pattern register have a delta count greater than the MTP threshold or have their corresponding Noise Flag Status bits set, the MTP bit will be set. When using the absolute number mode, if the number of sensor inputs with thresholds above the MTP threshold or with Noise Flag Status bits set is equal to or greater than this number, the MTP bit will be set. 3. When an MTP event occurs, all touches are blocked and an interrupt is generated. 4. All sensor inputs will remain blocked so long as the requisite number of sensor inputs are above the MTP threshold or have Noise Flag Status bits set. Once this condition is removed, touch detection will be restored. Note that the MTP status bit is only cleared by writing a ‘0’ to the INT bit once the condition has been removed. TABLE 6-24: MULTIPLE TOUCH CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Ah R/W Multiple Touch Config MULT_ BLK_ EN - - - B_MULT_T[1:0] - - 80h TABLE 6-25: B_MULT_T BIT DECODE B_MULT_T[1:0] Number of Simultaneous Touches 1 0 0 0 1 (default) 01 2 10 3 11 4 TABLE 6-26: MULTIPLE TOUCH PATTERN CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Bh R/W Multiple Touch Pattern Config MTP_ EN - - MTP_TH[1:0] COMP_ PTRN MTP_ ALERT 00h  2015 Microchip Technology Inc. DS00001624B-page 31 CAP1106 Bit 7 - MTP_EN - Enables the multiple touch pattern detection circuitry. • ‘0’ (default) - The MTP detection circuitry is disabled. • ‘1’ - The MTP detection circuitry is enabled. Bits 3-2 - MTP_TH[1:0] - Determine the MTP threshold, as shown in Table 6-27. This threshold is a percentage of sensor input threshold (see Section 6.18, "Sensor Input Threshold Registers") when the device is in the Fully Active state or of the standby threshold (see Section 6.23, "Standby Threshold Register") when the device is in the Standby state. Bit 1 - COMP_PTRN - Determines whether the MTP detection circuitry will use the Multiple Touch Pattern register as a specific pattern of sensor inputs or as an absolute number of sensor inputs. • ‘0’ (default) - The MTP detection circuitry will use the Multiple Touch Pattern register bit settings as an absolute minimum number of sensor inputs that must be above the threshold or have Noise Flag Status bits set. The number will be equal to the number of bits set in the register. • ‘1’ - The MTP detection circuitry will use pattern recognition. Each bit set in the Multiple Touch Pattern register indicates a specific sensor input that must have a delta count greater than the MTP threshold or have a Noise Flag Status bit set. If the criteria are met, the MTP status bit will be set. Bit 0 - MTP_ALERT - Enables an interrupt if an MTP event occurs. In either condition, the MTP status bit will be set. • ‘0’ (default) - If an MTP event occurs, the ALERT# pin is not asserted. • ‘1’ - If an MTP event occurs, the ALERT# pin will be asserted. 6.16 Multiple Touch Pattern Register The Multiple Touch Pattern register acts as a pattern to identify an expected sensor input profile for diagnostics or other significant events. There are two methods for how the Multiple Touch Pattern register is used: as specific sensor inputs or number of sensor input that must exceed the MTP threshold or have Noise Flag Status bits set. Which method is used is based on the COMP_PTRN bit (see Section 6.15). The methods are described below. 1. Specific Sensor Inputs: If, during a single polling cycle, the specific sensor inputs above the MTP threshold or with Noise Flag Status bits set match those bits set in the Multiple Touch Pattern register, an MTP event is flagged. 2. Number of Sensor Inputs: If, during a single polling cycle, the number of sensor inputs with a delta count above the MTP threshold or with Noise Flag Status bits set is equal to or greater than the number of pattern bits set, an MTP event is flagged. Bit 5 - CS6_PTRN - Determines whether CS6 is considered as part of the Multiple Touch Pattern. • ‘0’ - CS6 is not considered a part of the pattern. • ‘1’ - CS6 is considered a part of the pattern or the absolute number of sensor inputs that must have a delta count greater than the MTP threshold or have the Noise Flag Status bit set is increased by 1. Bit 4 - CS5_PTRN - Determines whether CS5 is considered as part of the Multiple Touch Pattern. Bit 3 - CS4_PTRN - Determines whether CS4 is considered as part of the Multiple Touch Pattern. Bit 2 - CS3_PTRN - Determines whether CS3 is considered as part of the Multiple Touch Pattern. TABLE 6-27: MTP_TH BIT DECODE MTP_TH[1:0] Threshold Divide Setting 1 0 0 0 12.5% (default) 0 1 25% 1 0 37.5% 1 1 100% TABLE 6-28: MULTIPLE TOUCH PATTERN REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Dh R/W Multiple Touch Pattern - - CS6_ PTRN CS5_ PTRN CS4_ PTRN CS3_ PTRN CS2_ PTRN CS1_ PTRN 3Fh CAP1106 DS00001624B-page 32  2015 Microchip Technology Inc. Bit 1 - CS2_PTRN - Determines whether CS2 is considered as part of the Multiple Touch Pattern. Bit 0 - CS1_PTRN - Determines whether CS1 is considered as part of the Multiple Touch Pattern. 6.17 Recalibration Configuration Register The Recalibration Configuration register controls the automatic re-calibration routine settings as well as advanced controls to program the Sensor Input Threshold register settings. Bit 7 - BUT_LD_TH - Enables setting all Sensor Input Threshold registers by writing to the Sensor Input 1 Threshold register. • ‘0’ - Each Sensor Input X Threshold register is updated individually. • ‘1’ (default) - Writing the Sensor Input 1 Threshold register will automatically overwrite the Sensor Input Threshold registers for all sensor inputs (Sensor Input Threshold 1 through Sensor Input Threshold 6). The individual Sensor Input X Threshold registers (Sensor Input 2 Threshold through Sensor Input 6 Threshold) can be individually updated at any time. Bit 6 - NO_CLR_INTD - Controls whether the accumulation of intermediate data is cleared if the noise status bit is set. • ‘0’ (default) - The accumulation of intermediate data is cleared if the noise status bit is set. • ‘1’ - The accumulation of intermediate data is not cleared if the noise status bit is set. APPLICATION NOTE: Bits 5 and 6 should both be set to the same value. Either both should be set to ‘0’ or both should be set to ‘1’. Bit 5 - NO_CLR_NEG - Controls whether the consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘0’ (default) - The consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘1’ - The consecutive negative delta counts counter is not cleared if the noise status bit is set. Bits 4 - 3 - NEG_DELTA_CNT[1:0] - Determines the number of negative delta counts necessary to trigger a digital recalibration as shown in Table 6-30. Bits 2 - 0 - CAL_CFG[2:0] - Determines the update time and number of samples of the automatic re-calibration routine. The settings apply to all sensor inputs universally (though individual sensor inputs can be configured to support re-calibration - see Section 6.11). TABLE 6-29: RECALIBRATION CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Fh R/W Recalibration Configuration BUT_ LD_TH NO_ CLR_ INTD NO_ CLR_ NEG NEG_DELTA_ CNT[1:0] CAL_CFG[2:0] 8Ah TABLE 6-30: NEG_DELTA_CNT BIT DECODE NEG_DELTA_CNT[1:0] Number of Consecutive Negative Delta Count Values 1 0 00 8 0 1 16 (default) 1 0 32 1 1 None (disabled) TABLE 6-31: CAL_CFG BIT DECODE CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210 0 0 0 16 16 0 0 1 32 32  2015 Microchip Technology Inc. DS00001624B-page 33 CAP1106 Note 6-1 Recalibration Samples refers to the number of samples that are measured and averaged before the Base Count is updated however does not control the base count update period. Note 6-2 Update Time refers to the amount of time (in polling cycle periods) that elapses before the Base Count is updated. The time will depend upon the number of channels active, the averaging setting, and the programmed cycle time. 6.18 Sensor Input Threshold Registers The Sensor Input Threshold registers store the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. When the BUT_LD_TH bit is set (see Section 6.17 - bit 7), writing data to the Sensor Input 1 Threshold register will update all of the sensor input threshold registers (31h - 35h inclusive). 6.19 Sensor Input Noise Threshold Register The Sensor Input Noise Threshold register controls the value of a secondary internal threshold to detect noise and improve the automatic recalibration routine. If a capacitive touch sensor input exceeds the Sensor Input Noise Threshold but does not exceed the sensor input threshold, it is determined to be caused by a noise spike. That sample is not used by the automatic re-calibration routine. This feature can be disabled by setting the DIS_DIG_NOISE bit. 0 1 0 64 64 (default) 0 1 1 128 128 1 0 0 256 256 1 0 1 256 1024 1 1 0 256 2048 1 1 1 256 4096 TABLE 6-32: SENSOR INPUT THRESHOLD REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 30h R/W Sensor Input 1 Threshold - 64 32 16 8 4 2 1 40h 31h R/W Sensor Input 2 Threshold - 64 32 16 8 4 2 1 40h 32h R/W Sensor Input 3 Threshold - 64 32 16 8 4 2 1 40h 33h R/W Sensor Input 4 Threshold - 64 32 16 8 4 2 1 40h 34h R/W Sensor Input 5 Threshold - 64 32 16 8 4 2 1 40h 35h R/W Sensor Input 6 Threshold - 64 32 16 8 4 2 1 40h TABLE 6-33: SENSOR INPUT NOISE THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 38h R/W Sensor Input Noise Threshold CS_BN_TH [1:0] 01h TABLE 6-31: CAL_CFG BIT DECODE (CONTINUED) CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210 CAP1106 DS00001624B-page 34  2015 Microchip Technology Inc. Bits 1-0 - CS1_BN_TH[1:0] - Controls the noise threshold for all capacitive touch sensor inputs, as shown in Table 6-34. The threshold is proportional to the threshold setting. 6.20 Standby Channel Register The Standby Channel register controls which (if any) capacitive touch sensor inputs are active during Standby. Bit 5 - CS6_STBY - Controls whether the CS6 channel is active in Standby. • ‘0’ (default) - The CS6 channel not be sampled during Standby mode. • ‘1’ - The CS6 channel will be sampled during Standby Mode. It will use the Standby threshold setting, and the standby averaging and sensitivity settings. Bit 4 - CS5_STBY - Controls whether the CS5 channel is active in Standby. Bit 3 - CS4_STBY - Controls whether the CS4 channel is active in Standby. Bit 2 - CS3_STBY - Controls whether the CS3 channel is active in Standby. Bit 1 - CS2_STBY - Controls whether the CS2 channel is active in Standby. Bit 0 - CS1_STBY - Controls whether the CS1 channel is active in Standby. 6.21 Standby Configuration Register The Standby Configuration register controls averaging and cycle time for those sensor inputs that are active in Standby. This register is useful for detecting proximity on a small number of sensor inputs as it allows the user to change averaging and sample times on a limited number of sensor inputs and still maintain normal functionality in the fully active state. Bit 7 - AVG_SUM - Determines whether the active sensor inputs will average the programmed number of samples or whether they will accumulate for the programmed number of samples. • ‘0’ - (default) - The active sensor input delta count values will be based on the average of the programmed number of samples when compared against the threshold. • ‘1’ - The active sensor input delta count values will be based on the summation of the programmed number of samples when compared against the threshold. This bit should only be set when performing proximity detection as a physical touch will overflow the delta count registers and may result in false readings. Bits 6 - 4 - STBY_AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-37. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. TABLE 6-34: CSX_BN_TH BIT DECODE CS_BN_TH[1:0] Percent Threshold Setting 1 0 0 0 25% 0 1 37.5% (default) 1 0 50% 1 1 62.5% TABLE 6-35: STANDBY CHANNEL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 40h R/W Standby Channel - - CS6_ STBY CS5_ STBY CS4_ STBY CS3_ STBY CS2_ STBY CS1_ STBY 00h TABLE 6-36: STANDBY CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 41h R/W Standby Configuration AVG_ SUM STBY_AVG[2:0] STBY_SAMP_ TIME[1:0] STBY_CY_TIME [1:0] 39h  2015 Microchip Technology Inc. DS00001624B-page 35 CAP1106 Bit 3-2 - STBY SAMP_TIME[1:0] - Determines the time to take a single sample when the device is in Standby as shown in Table 6-38. Bits 1 - 0 - STBY_CY_TIME[2:0] - Determines the overall cycle time for all measured channels during standby operation as shown in Table 6-39. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The STBY_AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. 6.22 Standby Sensitivity Register The Standby Sensitivity register controls the sensitivity for sensor inputs that are active in Standby. TABLE 6-37: STBY_AVG BIT DECODE STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-38: STBY_SAMP_TIME BIT DECODE STBY_SAMP_TIME[1:0] Sampling Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-39: STBY_CY_TIME BIT DECODE STBY_CY_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms TABLE 6-40: STANDBY SENSITIVITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 42h R/W Standby Sensitivity - - - - - STBY_SENSE[2:0] 02h CAP1106 DS00001624B-page 36  2015 Microchip Technology Inc. Bits 2 - 0 - STBY_SENSE[2:0] - Controls the sensitivity for sensor inputs that are active in Standby. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta C corresponding to a “lighter” touch. These settings are more sensitive to noise however and a noisy environment may flag more false touches than higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). 6.23 Standby Threshold Register The Standby Threshold register stores the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. 6.24 Sensor Input Base Count Registers TABLE 6-41: STBY_SENSE BIT DECODE STBY_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-42: STANDBY THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 43h R/W Standby Threshold - 64 32 16 8 4 2 1 40h TABLE 6-43: SENSOR INPUT BASE COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 50h R Sensor Input 1 Base Count 128 64 32 16 8 4 2 1 C8h 51h R Sensor Input 2 Base Count 128 64 32 16 8 4 2 1 C8h 52h R Sensor Input 3 Base Count 128 64 32 16 8 4 2 1 C8h 53h R Sensor Input 4 Base Count 128 64 32 16 8 4 2 1 C8h 54h R Sensor Input 5 Base Count 128 64 32 16 8 4 2 1 C8h 55h R Sensor Input 6 Base Count 128 64 32 16 8 4 2 1 C8h  2015 Microchip Technology Inc. DS00001624B-page 37 CAP1106 The Sensor Input Base Count registers store the calibrated “Not Touched” input value from the capacitive touch sensor inputs. These registers are periodically updated by the re-calibration routine. The routine uses an internal adder to add the current count value for each reading to the sum of the previous readings until sample size has been reached. At this point, the upper 16 bits are taken and used as the Sensor Input Base Count. The internal adder is then reset and the re-calibration routine continues. The data presented is determined by the BASE_SHIFT[3:0] bits (see Section 6.5). 6.25 Sensor Input Calibration Registers The Sensor Input Calibration registers hold the 10-bit value that represents the last calibration value. 6.26 Product ID Register The Product ID register stores a unique 8-bit value that identifies the device. 6.27 Manufacturer ID Register The Vendor ID register stores an 8-bit value that represents Microchip. TABLE 6-44: SENSOR INPUT CALIBRATION REGISTERS ADDR Register R/W B7 B6 B5 B4 B3 B2 B1 B0 Default B1h Sensor Input 1 Calibration R CAL1_9 CAL1_8 CAL1_7 CAL1_6 CAL1_5 CAL1_4 CAL1_3 CAL1_2 00h B2h Sensor Input 2 Calibration R CAL2_9 CAL2_8 CAL2_7 CAL2_6 CAL2_5 CAL2_4 CAL2_3 CAL2_2 00h B3h Sensor Input 3 Calibration R CAL3_9 CAL3_8 CAL3_7 CAL3_6 CAL3_5 CAL3_4 CAL3_3 CAL3_2 00h B4h Sensor Input 4 Calibration R CAL4_9 CAL4_8 CAL4_7 CAL4_6 CAL4_5 CAL4_4 CAL4_3 CAL4_2 00h B5h Sensor Input 5 Calibration R CAL5_9 CAL5_8 CAL5_7 CAL5_6 CAL5_5 CAL5_4 CAL5_3 CAL5_2 00h B6h Sensor Input 6 Calibration R CAL6_9 CAL6_8 CAL6_7 CAL6_6 CAL6_5 CAL6_4 CAL6_3 CAL6_2 00h B9h Sensor Input Calibration LSB 1 R CAL4_1 CAL4_0 CAL3_1 CAL3_0 CAL2_1 CAL2_0 CAL1_1 CAL1_0 00h BAh Sensor Input Calibration LSB 2 R - - - - CAL6_1 CAL6_0 CAL5_1 CAL5_0 00h TABLE 6-45: PRODUCT ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FDh R Product ID CAP1106 0 1 0 1 0 1 0 1 55h TABLE 6-46: VENDOR ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FEh R Manufacturer ID 0 1 0 1 1 1 0 1 5Dh CAP1106 DS00001624B-page 38  2015 Microchip Technology Inc. 6.28 Revision Register The Revision register stores an 8-bit value that represents the part revision. TABLE 6-47: REVISION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FFh R Revision 1 0 0 0 0 0 1 1 83h  2015 Microchip Technology Inc. DS00001624B-page 39 CAP1106 7.0 PACKAGE INFORMATION 7.1 CAP1106 Package Drawings FIGURE 7-1: 10-Pin DFN 3mm x 3mm Package Drawings (1 of 2) Note: For the most current package drawings, see the Microchip Packaging Specification at http://www.microchip.com/packaging CAP1106 DS00001624B-page 40  2015 Microchip Technology Inc. FIGURE 7-2: 10-Pin DFN 3mm x 3mm Package Drawings (2 of 2) Note: For the most current package drawings, see the Microchip Packaging Specification at http://www.microchip.com/packaging  2015 Microchip Technology Inc. DS00001624B-page 41 CAP1106 7.2 Package Marking FIGURE 7-3: CAP1106 Package Markings 1 8 W NNNA e4 TOP BOTTOM Bottom marking not allowed PB-FREE/GREEN SYMBOL PIN 1 (Ni/Pd PP-LF) Line 1 – Device Code, Week 2x 0.6 Line 2 – Alphanumeric Traceability Code W Lines 1-2: Line 3: Center Horizontal Alignment As Shown CAP1106 DS00001624B-page 42  2015 Microchip Technology Inc. APPENDIX A: DEVICE DELTA A.1 Delta from CAP1006 to CAP1106 1. Updated circuitry to improve power supply rejection. 2. Added Multiple Touch Pattern detection circuitry. See Section 6.15, "Multiple Touch Pattern Configuration Register". 3. Added General Status register to flag Multiple touches, Multiple Touch Pattern issues and general touch detections. See Section 6.2, "Status Registers". 4. Added bits 6 and 5 to the Recalibration Configuration register (2Fh - see Section 6.17, "Recalibration Configuration Register"). These bits control whether the accumulation of intermediate data and the consecutive negative delta counts counter are cleared when the noise status bit is set. 5. Added Configuration 2 register for noise detection controls and control to interrupt on press but not on release. Added control to change alert pin polarity. See Section 6.6, "Configuration Registers". 6. Updated Deep Sleep behavior so that device does not clear DSLEEP bit on received communications but will wake to communicate. 7. Register delta: Table A.1 Register Delta From CAP1006 to CAP1106 Address Register Delta Delta Default 00h Page 20 Changed - Main Status / Control added bits 7-6 to control gain 00h 02h Page 21 New - General Status new register to store MTP, MULT, and general TOUCH bits 00h 44h Page 24 New - Configuration 2 new register to control alert polarity, and noise detection, and interrupt on release 00h 24h Page 27 Changed - Averaging Control updated register bits - moved SAMP_AVG[2:0] bits and added SAMP_- TIME bit 1. Default changed 39h 2Bh Page 30 New - Multiple Touch Pattern Configuration new register for Multiple Touch Pattern configuration - enable and threshold settings 80h 2Dh Page 31 New - Multiple Touch Pattern Register new register for Multiple Touch Pattern detection circuitry - pattern or number of sensor inputs 3Fh 2Fh Page 32 Changed - Recalibration Configuration updated register - updated CAL_CFG bit decode to add a 128 averages setting and removed highest time setting. Default changed. Added bit 6 NO_CLR_INTD and bit 5 NO_CLR_NEG. 8Ah 38h Page 33 Changed - Sensor Input Noise Threshold updated register bits - removed bits 7 - 3 and consolidated all controls into bits 1 - 0. These bits will set the noise threshold for all channels. Default changed 01h 39h Removed - Noise Threshold Register 2 removed register n/a 41h Page 34 Changed - Standby Configuration updated register bits - moved STBY_AVG[2:0] bits and added STBY_- TIME bit 1. Default changed 39h FDh Page 37 Changed - Product ID Changed bit decode for CAP1106 55h  2015 Microchip Technology Inc. DS00001624B-page 43 CAP1106 APPENDIX B: DATA SHEET REVISION HISTORY Revision Section/Figure/Entry Correction DS00001624B (02-09-15) Features, Table 2-2, Table 2- 2, "Pin Types", Section 5.0, "General Description" References to BC-Link Interface, BC_DATA, BC_- CLK, BC-IRQ#, BC-Link bus have been removed Application Note under Table 2-6 [BC-Link] hidden in data sheet Table 3-2, "Electrical Specifications" BC-Link Timing Section hidden in data sheet Table 4-1 Protocol Used for 68K Pull Down Resistor changed from “BC-Link Communications” to “Reserved” Section 4.1.3 BC-Link Communications Removed this section and Application Note Section 4.2.2, "SMBus Address and RD / WR Bit" Replaced “client address” with “slave address” in this section. Section 4.2.4, SMBus ACK and NACK Bits, Section 4.2.5, SMBus Stop Bit,Section 4.2.7, SMBus and I2C Compatibility Replaced “client” with “slave” in these sections. Table 4-3, "Read Byte Protocol" Heading changed from “Client Address” to “Slave Address” Section 5.1, Power States Removed “BC-Link” Application Notes Table 6-1 Register Name for Register Address 77h changed from “LED Linked Transition Control” to “Linked LED Transition Control” Section 6.1 Main Control Register BC-Link paragraph removed from Bit 4 under Table 6-3 Section 7.7 Package Marking Updated package drawing Figure 7-25 CAP1106 with BC-Link Support Package Markings Removed figure. Appendix A: Device Delta changed 2Dh to 2Fh in item #12 Product Identification System Removed BC-Link references REV A REV A replaces previous SMSC version Rev. 1.32 (01-05-12) Rev. 1.32 (01-05-12) Table 3-2, "Electrical Specifications" Added conditions for tHD:DAT. Section 4.2.7, "SMBus and I2C Compatibility" Renamed from “SMBus and I2C Compliance.” First paragraph, added last sentence: “For information on using the CAP1106 in an I2C system, refer to SMSC AN 14.0 SMSC Dedicated Slave Devices in I 2C Systems.” Added: CAP1106 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. Section 6.4, "Sensor Input Delta Count Registers" Changed negative value cap from FFh to 80h. Rev. 1.31 (08-18-11) Section 4.3.3, "SMBus Send Byte" Added an application note: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Section 4.3.4, "SMBus Receive Byte" Added an application note: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). CAP1106 DS00001624B-page 44  2015 Microchip Technology Inc. Section 6.2, "Status Registers" Removed RESET as bit 3 in register 02h. Rev. 1.3 (05-18-11) Section 6.28, "Revision Register" Updated revision ID from 82h to 83h. Section 6.2, "Status Registers" Added RESET as bit 3 in register 02h. Rev. 1.2 (02-10-11) Section A.8, "Delta from Rev B (Mask B0) to Rev C (Mask B1)" Added. Table 3-2, "Electrical Specifications" PSR improvements made in functional revision B. Changed PSR spec from ±100 typ and ±200 max counts / V to ±3 and ±10 counts / V. Conditions updated. Section 5.2.2, "Recalibrating Sensor Inputs" Added more detail with subheadings for each type of recalibration. Section 6.6, "Configuration Registers" Added bit 5 BLK_PWR_CTRL to the Configuration 2 Register 44h. The TIMEOUT bit is set to ‘1’ by default for functional revision B and is set to ‘0’ by default for functional revision C. Section 6.28, "Revision Register" Updated revision ID in register FFh from 81h to 82h. Rev. 1.1 (11-17-10) Document Updated for functional revision B. See Section A.7, "Delta from Rev A (Mask A0) to Rev B (Mask B0)". Cover Added to General Description: “includes circuitry and support for enhanced sensor proximity detection.” Added the following Features: Calibrates for Parasitic Capacitance Analog Filtering for System Noise Sources Press and Hold feature for Volume-like Applications Table 3-2, "Electrical Specifications" Conditions for Power Supply Rejection modified adding the following: Sampling time = 2.56ms Averaging = 1 Negative Delta Counts = Disabled All other parameters default Section 6.11, "Calibration Activate Register" Updated register description to indicate which re-calibration routine is used. Section 6.14, "Multiple Touch Configuration Register" Updated register description to indicate what will happen. Table 6-34, "CSx_BN_TH Bit Decode" Table heading changed from “Threshold Divide Setting” to “Percent Threshold Setting”. Rev. 1.0 (06-14-10) Initial release Revision Section/Figure/Entry Correction  2015 Microchip Technology Inc. DS00001624B-page 45 CAP1106 THE MICROCHIP WEB SITE Microchip provides online support via our WWW site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support CAP1106 DS00001624B-page 46  2015 Microchip Technology Inc. PRODUCT IDENTIFICATION SYSTEM To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. PART NO. [X] - [X] - XXX - [X](1) l l l l l Device Temperature Addressing Package Tape and Reel Range Option Option Example: Note 1: Tape and Reel identifier only appears in the catalog part number description. This identifier is used for ordering purposes and is not printed on the device package. Check with your Microchip Sales Office for package availability with the Tape and Reel option. Device: CAP1106 Temperature Range: Blank = 0°C to +85°C (Extended Commercial) Package: AIA = DFN Tape and Reel Option: TR = Tape and Reel(1) CAP1106-1-AIA-TR 10-pin DFN 3mm x 3mm (RoHS compliant) Six capacitive touch sensor inputs, SMBus interface Reel size is 4,000 pieces  2015 Microchip Technology Inc. DS00001624B-page 47 CAP1106 Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication 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. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, flexPWR, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANCheck, MediaLB, MOST, MOST logo, MPLAB, OptoLyzer, PIC, PICSTART, PIC32 logo, RightTouch, SpyNIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. The Embedded Control Solutions Company and mTouch are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, ECAN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, KleerNet, KleerNet logo, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, RightTouch logo, REAL ICE, SQI, Serial Quad I/O, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2015, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 9781632770349 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 ==  2015 Microchip Technology Inc. DS00001624B-page 48 AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Canada - Toronto Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2943-5100 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Dongguan Tel: 86-769-8702-9880 China - Hangzhou Tel: 86-571-8792-8115 Fax: 86-571-8792-8116 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 ASIA/PACIFIC China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7828 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 EUROPE Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Dusseldorf Tel: 49-2129-3766400 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Pforzheim Tel: 49-7231-424750 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Venice Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Poland - Warsaw Tel: 48-22-3325737 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service 01/27/15  2015 Microchip Technology Inc. DS00001623B-page 1 General Description The CAP1126, which incorporates RightTouch® technology, is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains six (6) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1126 also contains two (2) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. The CAP1126 includes Multiple Pattern Touch recognition that allows the user to select a specific set of buttons to be touched simultaneously. If this pattern is detected, then a status bit is set and an interrupt generated. Additionally, the CAP1126 includes circuitry and support for enhanced sensor proximity detection. The CAP1126 offers multiple power states operating at low quiescent currents. In the Standby state of operation, one or more capacitive touch sensor inputs are active and all LEDs may be used. If a touch is detected, it will wake the system using the WAKE/SPI_MOSI pin. Deep Sleep is the lowest power state available, drawing 5uA (typical) of current. In this state, no sensor inputs are active. Driving the WAKE/SPI_MOSI pin or communications will wake the device. Applications • Desktop and Notebook PCs • LCD Monitors • Consumer Electronics • Appliances Features • Six (6) Capacitive Touch Sensor Inputs - Programmable sensitivity - Automatic recalibration - Individual thresholds for each button • Proximity Detection • Multiple Button Pattern Detection • Calibrates for Parasitic Capacitance • Analog Filtering for System Noise Sources • Press and Hold feature for Volume-like Applications • Multiple Communication Interfaces - SMBus / I2C compliant interface - SPI communications - Pin selectable communications protocol and multiple slave addresses (SMBus / I2C only) • Low Power Operation - 5uA quiescent current in Deep Sleep - 50uA quiescent current in Standby (1 sensor input monitored) - Samples one or more channels in Standby • Two (2) LED Driver Outputs - Open Drain or Push-Pull - Programmable blink, breathe, and dimness controls - Can be linked to Capacitive Touch Sensor inputs • Dedicated Wake output flags touches in low power state • System RESET pin • Available in 16-pin 4mm x 4mm RoHS compliant QFN package CAP1126 6 Channel Capacitive Touch Sensor with 2 LED Drivers CAP1126 DS00001623B-page 2  2015 Microchip Technology Inc. TO OUR VALUED CUSTOMERS It is our intention to provide our valued customers with the best documentation possible to ensure successful use of your Microchip products. To this end, we will continue to improve our publications to better suit your needs. Our publications will be refined and enhanced as new volumes and updates are introduced. If you have any questions or comments regarding this publication, please contact the Marketing Communications Department via E-mail at docerrors@microchip.com. We welcome your feedback. Most Current Data Sheet To obtain the most up-to-date version of this data sheet, please register at our Worldwide Web site at: http://www.microchip.com You can determine the version of a data sheet by examining its literature number found on the bottom outside corner of any page. The last character of the literature number is the version number, (e.g., DS30000000A is version A of document DS30000000). Errata An errata sheet, describing minor operational differences from the data sheet and recommended workarounds, may exist for current devices. As device/documentation issues become known to us, we will publish an errata sheet. The errata will specify the revision of silicon and revision of document to which it applies. To determine if an errata sheet exists for a particular device, please check with one of the following: • Microchip’s Worldwide Web site; http://www.microchip.com • Your local Microchip sales office (see last page) When contacting a sales office, please specify which device, revision of silicon and data sheet (include -literature number) you are using. Customer Notification System Register on our web site at www.microchip.com to receive the most current information on all of our products.  2015 Microchip Technology Inc. DS00001623B-page 3 CAP1126 Table of Contents 1.0 Block Diagram ................................................................................................................................................................................. 4 2.0 Pin Description ................................................................................................................................................................................ 5 3.0 Electrical Specifications .................................................................................................................................................................. 9 4.0 Communications ........................................................................................................................................................................... 12 5.0 General Description ...................................................................................................................................................................... 23 6.0 Register Description ...................................................................................................................................................................... 29 7.0 Package Information ..................................................................................................................................................................... 67 Appendix A: Device Delta ................................................................................................................................................................... 72 Appendix B: Data Sheet Revision History ........................................................................................................................................... 74 The Microchip Web Site ...................................................................................................................................................................... 76 Customer Change Notification Service ............................................................................................................................................... 76 Customer Support ............................................................................................................................................................................... 76 Product Identification System ............................................................................................................................................................. 77 CAP1126 DS00001623B-page 4  2015 Microchip Technology Inc. 1.0 BLOCK DIAGRAM SMBus / BC-Link / SPI Slave Protocol SMCLK BC_CLK / SPI_CLK SMDATA BC_DATA / SPI_MSIO / SPI_MISO VDD GND ALERT# / BC_IRQ# Capacitive Touch Sensing Algorithm LED1 CS1 CS2 CS3 CS4 CS5 CS6 LED Driver, Breathe, and Dimness control RESET WAKE / SPI_MOSI ADDR_COMM SPI_CS# LED2  2015 Microchip Technology Inc. DS00001623B-page 5 CAP1126 2.0 PIN DESCRIPTION FIGURE 2-1: CAP1126 Pin Diagram (16-Pin QFN) TABLE 2-1: PIN DESCRIPTION FOR CAP1126 Pin Number Pin Name Pin Function Pin Type Unused Connection 1 SPI_CS# Active low chip-select for SPI bus DI (5V) Connect to Ground 2 WAKE / SPI_- MOSI WAKE - Active high wake / interrupt output Standby power state - requires pull-down resistor DO Pull-down WAKE - Active high wake input - requires pull-down Resistor resistor Deep Sleep power state DI SPI_MOSI - SPI Master-Out-Slave-In port when used in normal mode DI (5V) Connect to Ground 1 2 3 4 12 11 10 9 16 15 14 13 5 6 7 8 SMCLK / BC_CLK / SPI_CLK SMDATA / BC_DATA / SPI_MSIO / SPI_MISO WAKE / SPI_MOSI ADDR_COMM VDD CS6 SPI_CS# CS5 CS1 CS2 CS3 RESET LED1 LED2 CS4 ALERT# / BC_IRQ# CAP1126 16 pin QFN GND CAP1126 DS00001623B-page 6  2015 Microchip Technology Inc. 3 SMDATA / SPI_MSIO / SPI_MISO SMDATA - Bi-directional, open-drain SMBus data - requires pull-up resistor DIOD (5V) n/a SPI_MSIO - SPI Master-Slave-In-Out bidirectional port when used in bi-directional mode DIO SPI_MISO - SPI Master-In-Slave-Out port when used in normal mode DO 4 SMCLK / SPI_- CLK SMCLK - SMBus clock input - requires pull-up resistor DI (5V) SPI_CLK - SPI clock input DI (5V) n/a 5 LED1 Open drain LED 1 driver (default) OD (5V) Connect to Ground Push-pull LED 1 driver DO leave open or connect to Ground 6 LED2 Open drain LED 2 driver (default) OD (5V) Connect to Ground Push-pull LED 2 driver DO leave open or connect to Ground 7 RESET Active high soft reset for system - resets all registers to default values. If not used, connect to ground. DI (5V) Connect to Ground 8 ALERT# ALERT# - Active low alert / interrupt output for SMBus alert or SPI interrupt OD (5V) Connect to Ground ALERT# - Active high push-pull alert / interrupt output for SMBus alert or SPI interrupt DO leave open 9 ADDR_COMM Address / communications select pin - pull-down resistor determines address / communications mechanism AI n/a 10 CS6 Capacitive Touch Sensor Input 6 AIO Connect to Ground 11 CS5 Capacitive Touch Sensor Input 5 AIO Connect to Ground 12 CS4 Capacitive Touch Sensor Input 4 AIO Connect to Ground 13 CS3 Capacitive Touch Sensor Input 3 AIO Connect to Ground 14 CS2 Capacitive Touch Sensor Input 2 AIO Connect to Ground 15 CS1 Capacitive Touch Sensor Input 1 AIO Connect to Ground 16 VDD Positive Power supply Power n/a TABLE 2-1: PIN DESCRIPTION FOR CAP1126 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection  2015 Microchip Technology Inc. DS00001623B-page 7 CAP1126 APPLICATION NOTE: When the ALERT# pinis configured as an active low output, it will be open drain. When it is configured as an active high output, it will be push-pull. APPLICATION NOTE: For the 5V tolerant pins that have a pull-up resistor, the pull-up voltage must not exceed 3.6V when the CAP1126 is unpowered. APPLICATION NOTE: The SPI_CS# pin should be grounded when SMBus, or I2C,communications are used. The pin types are described in Table 2-2. All pins labeled with (5V) are 5V tolerant. Bottom Pad GND Ground Power n/a TABLE 2-2: PIN TYPES Pin Type Description Power This pin is used to supply power or ground to the device. DI Digital Input - This pin is used as a digital input. This pin is 5V tolerant. AIO Analog Input / Output -This pin is used as an I/O for analog signals. DIOD Digital Input / Open Drain Output - This pin is used as a digital I/O. When it is used as an output, it is open drain and requires a pull-up resistor. This pin is 5V tolerant. OD Open Drain Digital Output - This pin is used as a digital output. It is open drain and requires a pull-up resistor. This pin is 5V tolerant. DO Push-pull Digital Output - This pin is used as a digital output and can sink and source current. DIO Push-pull Digital Input / Output - This pin is used as an I/O for digital signals. TABLE 2-1: PIN DESCRIPTION FOR CAP1126 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection CAP1126 DS00001623B-page 8  2015 Microchip Technology Inc. 3.0 ELECTRICAL SPECIFICATIONS Note 3-1 Stresses above those listed could cause permanent damage to the device. This is a stress rating only and functional operation of the device at any other condition above those indicated in the operation sections of this specification is not implied. Note 3-2 For the 5V tolerant pins that have a pull-up resistor, the voltage difference between V5VT_PIN and VDD must never exceed 3.6V. Note 3-3 The Package Power Dissipation specification assumes a recommended thermal via design consisting of a 3x3 matrix of 0.3mm (12mil) vias at 1.0mm pitch connected to the ground plane with a 2.1mm x 2.1mm thermal landing. Note 3-4 Junction to Ambient (θJA) is dependent on the design of the thermal vias. Without thermal vias and a thermal landing, the θJA is approximately 60°C/W including localized PCB temperature increase. TABLE 3-1: ABSOLUTE MAXIMUM RATINGS Voltage on 5V tolerant pins (V5VT_PIN) -0.3 to 5.5 V Voltage on 5V tolerant pins (|V5VT_PIN - VDD|) Note 3-2 0 to 3.6 V Voltage on VDD pin -0.3 to 4 V Voltage on any other pin to GND -0.3 to VDD + 0.3 V Package Power Dissipation up to TA = 85°C for 16 pin QFN (see Note 3-3) 0.9 W Junction to Ambient (θJA) (see Note 3-4) 58 °C/W Operating Ambient Temperature Range -40 to 125 °C Storage Temperature Range -55 to 150 °C ESD Rating, All Pins, HBM 8000 V  2015 Microchip Technology Inc. DS00001623B-page 9 CAP1126 TABLE 3-2: ELECTRICAL SPECIFICATIONS VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions DC Power Supply Voltage VDD 3.0 3.3 3.6 V Supply Current ISTBY 120 170 uA Standby state active 1 sensor input monitored No LEDs active Default conditions (8 avg, 70ms cycle time) ISTBY 50 uA Standby state active 1 sensor input monitored No LEDs active 1 avg, 140ms cycle time, IDSLEEP 5 15 uA Deep Sleep state active LEDs at 100% or 0% Duty Cycle No communications TA < 40°C 3.135 < VDD < 3.465V IDD 500 600 uA Capacitive Sensing Active No LEDs active Capacitive Touch Sensor Inputs Maximum Base Capacitance CBASE 50 pF Pad untouched Minimum Detectable Capacitive Shift ΔCTOUCH 20 fF Pad touched - default conditions (1 avg, 35ms cycle time, 1x sensitivity) Recommended Cap Shift ΔCTOUCH 0.1 2 pF Pad touched - Not tested Power Supply Rejection PSR ±3 ±10 counts / V Untouched Current Counts Base Capacitance 5pF - 50pF Maximum sensitivity Negative Delta Counts disabled All other parameters default Timing RESET Pin Delay tRST_DLY 10 ms Time to communications ready tCOMM_DLY 15 ms Time to first conversion ready tCONV_DLY 170 200 ms LED Drivers Duty Cycle DUTYLED 0 100 % Programmable Drive Frequency fLED 2 kHz Sinking Current ISINK 24 mA VOL = 0.4 Sourcing Current ISOURCE 24 mA VOH = VDD - 0.4 Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered I/O Pins Output Low Voltage VOL 0.4 V ISINK_IO = 8mA Output High Voltage VOH VDD - 0.4 V ISOURCE_IO = 8mA CAP1126 DS00001623B-page 10  2015 Microchip Technology Inc. Note 3-5 The ALERT pin will not glitch high or low at power up if connected to VDD or another voltage. Note 3-6 The SMCLK and SMDATA pins will not glitch low at power up if connected to VDD or another voltage. Input High Voltage VIH 2.0 V Input Low Voltage VIL 0.8 V Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered RESET Pin Release to conversion ready tRESET 170 200 ms SMBus Timing Input Capacitance CIN 5 pF Clock Frequency fSMB 10 400 kHz Spike Suppression tSP 50 ns Bus Free Time Stop to Start tBUF 1.3 us Start Setup Time tSU:STA 0.6 us Start Hold Time tHD:STA 0.6 us Stop Setup Time tSU:STO 0.6 us Data Hold Time tHD:DAT 0 us When transmitting to the master Data Hold Time tHD:DAT 0.3 us When receiving from the master Data Setup Time tSU:DAT 0.6 us Clock Low Period tLOW 1.3 us Clock High Period tHIGH 0.6 us Clock / Data Fall Time tFALL 300 ns Min = 20+0.1CLOAD ns Clock / Data Rise Time tRISE 300 ns Min = 20+0.1CLOAD ns Capacitive Load CLOAD 400 pF per bus line SPI Timing Clock Period tP 250 ns Clock Low Period tLOW 0.4 x tP 0.6 x tP ns Clock High Period tHIGH 0.4 x tP 0.6 x tP ns Clock Rise / Fall time tRISE / tFALL 0.1 x tP ns Data Output Delay tD:CLK 10 ns Data Setup Time tSU:DAT 20 ns Data Hold Time tHD:DAT 20 ns SPI_CS# to SPI_CLK setup time tSU:CS 0 ns Wake Time tWAKE 10 20 us SPI_CS# asserted to CLK assert TABLE 3-2: ELECTRICAL SPECIFICATIONS (CONTINUED) VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions  2015 Microchip Technology Inc. DS00001623B-page 11 CAP1126 4.0 COMMUNICATIONS 4.1 Communications The CAP1126communicates using the 2-wire SMBus or I2C bus, the 2-wire proprietary BC-Link, or the SPI bus. If the proprietary BC-Link protocol is required for your application, please contact your Microchip representative for ordering instructions. Regardless of communication mechanism, the device functionality remains unchanged. The communications mechanism as well as the SMBus (or I2C) slave address is determined by the resistor connected between the ADDR_COMM pin and ground as shown in Table 4-1. 4.1.1 SMBUS (I2C) COMMUNICATIONS When configured to communicate via the SMBus, the CAP1126 supports the following protocols: Send Byte, Receive Byte, Read Byte, Write Byte, Read Block, and Write Block. In addition, the device supports I2C formatting for block read and block write protocols. APPLICATION NOTE: For SMBus/I2C communications, the SPI_CS# pin is not used and should be grounded; any data presented to this pin will be ignored. See Section 4.2 and Section 4.3 for more information on the SMBus bus and protocols respectively. 4.1.2 SPI COMMUNICATIONS When configured to communicate via the SPI bus, the CAP1126supports both bi-directional 3-wire and normal 4-wire protocols and uses the SPI_CS# pin to enable communications. APPLICATION NOTE: See Section 4.5 and Section 4.6 for more information on the SPI bus and protocols respectively.Upon power up, the CAP1126 will not respond to any communications for up to 15ms. After this time, full functionality is available. 4.2 System Management Bus The CAP1126 communicates with a host controller, such as an SIO, through the SMBus. The SMBus is a two-wire serial communication protocol between a computer host and its peripheral devices. A detailed timing diagram is shown in Figure 4-1. Stretching of the SMCLK signal is supported; however, the CAP1126 will not stretch the clock signal. TABLE 4-1: ADDR_COMM PIN DECODE Pull-Down Resistor (+/- 5%) Protocol Used SMBus Address GND SPI Communications using Normal 4-wire Protocol Used n/a 56k SPI Communications using BiDirectional 3-wire Protocol Used n/a 68k Reserved n/a 82k SMBus / I2C 0101_100(r/w) 100k SMBus / I2C 0101_011(r/w) 120k SMBus / I2C 0101_010(r/w) 150k SMBus / I2C 0101_001(r/w) VDD SMBus / I2C 0101_000(r/w) CAP1126 DS00001623B-page 12  2015 Microchip Technology Inc. 4.2.1 SMBUS START BIT The SMBus Start bit is defined as a transition of the SMBus Data line from a logic ‘1’ state to a logic ‘0’ state while the SMBus Clock line is in a logic ‘1’ state. 4.2.2 SMBUS ADDRESS AND RD / WR BIT The SMBus Address Byte consists of the 7-bit slave address followed by the RD / WR indicator bit. If this RD / WR bit is a logic ‘0’, then the SMBus Host is writing data to the slave device. If this RD / WR bit is a logic ‘1’, then the SMBus Host is reading data from the slave device. See Table 4-1 for available SMBus addresses. 4.2.3 SMBUS DATA BYTES All SMBus Data bytes are sent most significant bit first and composed of 8-bits of information. 4.2.4 SMBUS ACK AND NACK BITS The SMBus slave will acknowledge all data bytes that it receives. This is done by the slave device pulling the SMBus Data line low after the 8th bit of each byte that is transmitted. This applies to both the Write Byte and Block Write protocols. The Host will NACK (not acknowledge) the last data byte to be received from the slave by holding the SMBus data line high after the 8th data bit has been sent. For the Block Read protocol, the Host will ACK each data byte that it receives except the last data byte. 4.2.5 SMBUS STOP BIT The SMBus Stop bit is defined as a transition of the SMBus Data line from a logic ‘0’ state to a logic ‘1’ state while the SMBus clock line is in a logic ‘1’ state. When the CAP1126 detects an SMBus Stop bit and it has been communicating with the SMBus protocol, it will reset its slave interface and prepare to receive further communications. 4.2.6 SMBUS TIMEOUT The CAP1126 includes an SMBus timeout feature. Following a 30ms period of inactivity on the SMBus where the SMCLK pin is held low, the device will timeout and reset the SMBus interface. The timeout function defaults to disabled. It can be enabled by setting the TIMEOUT bit in the Configuration register (see Section 6.6, "Configuration Registers"). 4.2.7 SMBUS AND I2C COMPATIBILITY The major differences between SMBus and I2C devices are highlighted here. For more information, refer to the SMBus 2.0 and I2C specifications. For information on using the CAP1126 in an I2C system, refer to AN 14.0 Dedicated Slave Devices in I2C Systems. FIGURE 4-1: SMBus Timing Diagram SMDATA SMCLK TLOW TRISE THIGH TFALL TBUF THD:STA P S S - Start Condition P - Stop Condition THD:DAT TSU:DAT TSU:STA THD:STA P TSU:STO S  2015 Microchip Technology Inc. DS00001623B-page 13 CAP1126 1. CAP1126 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. 2. Minimum frequency for SMBus communications is 10kHz. 3. The SMBus slave protocol will reset if the clock is held at a logic ‘0’ for longer than 30ms. This timeout functionality is disabled by default in the CAP1126 and can be enabled by writing to the TIMEOUT bit. I2C does not have a timeout. 4. The SMBus slave protocol will reset if both the clock and data lines are held at a logic ‘1’ for longer than 200µs (idle condition). This function is disabled by default in the CAP1126 and can be enabled by writing to the TIMEOUT bit. I2C does not have an idle condition. 5. I2C devices do not support the Alert Response Address functionality (which is optional for SMBus). 6. I2C devices support block read and write differently. I2C protocol allows for unlimited number of bytes to be sent in either direction. The SMBus protocol requires that an additional data byte indicating number of bytes to read / write is transmitted. The CAP1126 supports I2C formatting only. 4.3 SMBus Protocols The CAP1126 is SMBus 2.0 compatible and supports Write Byte, Read Byte, Send Byte, and Receive Byte as valid protocols as shown below. All of the below protocols use the convention in Table 4-2. 4.3.1 SMBUS WRITE BYTE The Write Byte is used to write one byte of data to a specific register as shown in Table 4-3. 4.3.2 SMBUS READ BYTE The Read Byte protocol is used to read one byte of data from the registers as shown in Table 4-4. 4.3.3 SMBUS SEND BYTE The Send Byte protocol is used to set the internal address register pointer to the correct address location. No data is transferred during the Send Byte protocol as shown in Table 4-5. APPLICATION NOTE: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). TABLE 4-2: PROTOCOL FORMAT Data Sent to Device Data Sent to the HOst Data sent Data sent TABLE 4-3: WRITE BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK Stop 1 ->0 YYYY_YYY 0 0 XXh 0 XXh 0 0 -> 1 TABLE 4-4: READ BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data NACK Stop 1->0 YYYY_YYY 0 0 XXh 0 1 ->0 YYYY_YYY 1 0 XXh 1 0 -> 1 TABLE 4-5: SEND BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Stop 1 -> 0 YYYY_YYY 0 0 XXh 0 0 -> 1 CAP1126 DS00001623B-page 14  2015 Microchip Technology Inc. 4.3.4 SMBUS RECEIVE BYTE The Receive Byte protocol is used to read data from a register when the internal register address pointer is known to be at the right location (e.g., set via Send Byte). This is used for consecutive reads of the same register as shown in Table 4-6. APPLICATION NOTE: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.4 I2C Protocols The CAP1126 supports I2C Block Write and Block Read. The protocols listed below use the convention in Table 4-2. 4.4.1 BLOCK WRITE The Block Write is used to write multiple data bytes to a group of contiguous registers as shown in Table 4-7. APPLICATION NOTE: When using the Block Write protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.4.2 BLOCK READ The Block Read is used to read multiple data bytes from a group of contiguous registers as shown in Table 4-8. APPLICATION NOTE: When using the Block Read protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.5 SPI Interface The SMBus has a predefined packet structure, the SPI does not. The SPI Bus can operate in two modes of operation, normal 4-wire mode and bi-directional 3-wire mode. All SPI commands consist of 8-bit packets sent to a specific slave device (identified by the CS pin). The SPI bus will latch data on the rising edge of the clock and the clock and data both idle high. All commands are supported via both operating modes. The supported commands are: Reset Serial interface, set address pointer, write command and read command. Note that all other codes received during the command phase are ignored and have no effect on the operation of the device. TABLE 4-6: RECEIVE BYTE PROTOCOL Start Slave Address RD ACK Register Data NACK Stop 1 -> 0 YYYY_YYY 1 0 XXh 1 0 -> 1 TABLE 4-7: BLOCK WRITE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK 1 ->0 YYYY_YYY 0 0 XXh 0 XXh 0 Register Data ACK Register Data ACK . . . Register Data ACK Stop XXh 0 XXh 0 . . . XXh 0 0 -> 1 TABLE 4-8: BLOCK READ PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data 1->0 YYYY_YYY 0 0 XXh 0 1 ->0 YYYY_YYY 1 0 XXh ACK Register Data ACK Register Data ACK Register Data ACK . . . Register Data NACK Stop 0 XXh 0 XXh 0 XXh 0 . . . XXh 1 0 -> 1  2015 Microchip Technology Inc. DS00001623B-page 15 CAP1126 4.5.1 SPI NORMAL MODE The SPI Bus can operate in two modes of operation, normal and bi-directional mode. In the normal mode of operation, there are dedicated input and output data lines. The host communicates by sending a command along the CAP1126 SPI_MOSI data line and reading data on the SPI_MISO data line. Both communications occur simultaneously which allows for larger throughput of data transactions. All basic transfers consist of two 8 bit transactions from the Master device while the slave device is simultaneously sending data at the current address pointer value. Data writes consist of two or more 8-bit transactions. The host sends a specific write command followed by the data to write the address pointer. Data reads consist of one or more 8-bit transactions. The host sends the specific read data command and continues clocking for as many data bytes as it wishes to receive. 4.5.2 SPI BI-DIRECTIONAL MODE In the bi-directional mode of operation, the SPI data signals are combined into the SPI_MSIO line, which is shared for data received by the device and transmitted by the device. The protocol uses a simple handshake and turn around sequence for data communications based on the number of clocks transmitted during each phase. All basic transfers consist of two 8 bit transactions. The first is an 8 bit command phase driven by the Master device. The second is by an 8 bit data phase driven by the Master for writes, and by the CAP1126 for read operations. The auto increment feature of the address pointer allows for successive reads or writes. The address pointer will return to 00h after reaching FFh. 4.5.3 SPI_CS# PIN The SPI Bus is a single master, multiple slave serial bus. Each slave has a dedicated CS pin (chip select) that the master asserts low to identify that the slave is being addressed. There are no formal addressing options. 4.5.4 ADDRESS POINTER All data writes and reads are accessed from the current address pointer. In both Bi-directional mode and Full Duplex mode, the Address pointer is automatically incremented following every read command or every write command. The address pointer will return to 00h after reaching FFh. 4.5.5 SPI TIMEOUT The CAP1126 does not detect any timeout conditions on the SPI bus. FIGURE 4-2: SPI Timing SPI_MSIO or SPI_MOSI or SPI_MISO SPI_CLK tLOW tRISE tHIGH tFALL tD:CLK tHD:DAT tSU:DAT tP  2015 Microchip Technology Inc. DS00001623B-page 16 CAP1126 4.6 Normal SPI Protocols When operating in normal mode, the SPI bus internal address pointer is incremented depending upon which command has been transmitted. Multiple commands may be transmitted sequentually so long as the SPI_CS# pin is asserted low. Figure 4-3 shows an example of this operation. 4.6.1 RESET INTERFACE Resets the Serial interface whenever two successive 7Ah codes are received. Regardless of the current phase of the transaction - command or data, the receipt of the successive reset commands resets the Serial communication interface only. All other functions are not affected by the reset operation. FIGURE 4-3: Example SPI Bus Communication - Normal Mode SPI_CS# SPI_MISO SPI_MOSI SPI Address Pointer SPI Data output buffer Register Address / Data 7Ah XXh (invalid) XXh (invalid) YYh (invalid) 7Ah 7Dh 41h YYh (invalid) 7Eh 66h XXh (invalid) 45h 7Dh 41h AAh (invalid) AAh (invalid) 7Fh 7Fh 55h (invalid) 66h 7Fh AAh 7Dh 43h 40h 78h 7Fh XXh (invalid) 7Fh 56h 40h / 56h 41h / 45h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 45h 40h / 56h 41h / 45h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 42h AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 55h 7Fh AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 66h 42h AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 44h 80h 40h 80h 40h 56h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 43h 55h 7Fh 7Fh 55h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 80h 45h 43h 46h 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 00h XXh Indicates SPI Address pointer incremented  2015 Microchip Technology Inc. DS00001623B-page 17 CAP1126 4.6.2 SET ADDRESS POINTER The Set Address Pointer command sets the Address pointer for subsequent reads and writes of data. The pointer is set on the rising edge of the final data bit. At the same time, the data that is to be read is fetched and loaded into the internal output buffer but is not transmitted. 4.6.3 WRITE DATA The Write Data protocol updates the contents of the register referenced by the address pointer. As the command is processed, the data to be read is fetched and loaded into the internal output buffer but not transmitted. Then, the register is updated with the data to be written. Finally, the address pointer is incremented. FIGURE 4-4: SPI Reset Interface Command - Normal Mode FIGURE 4-5: SPI Set Address Pointer Command - Normal Mode Master SPDOUT SPI_MOSI SPI_CS# SPI_CLK Reset - 7Ah Reset - 7Ah Invalid register data 00h – Internal Data buffer empty SPI_MISO Master Drives Slave Drives ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘1’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘1’ ‘0’ Master SPDOUT SPI_MOSI Register Address SPI_CS# SPI_CLK Set Address Pointer – 7Dh SPI_MISO Unknown, Invalid Data Unknown, Invalid Data Master Drives Slave Drives Address pointer set ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ CAP1126 DS00001623B-page 18  2015 Microchip Technology Inc. 4.6.4 READ DATA The Read Data protocol is used to read data from the device. During the normal mode of operation, while the device is receiving data, the CAP1126 is simultaneously transmitting data to the host. For the Set Address commands and the Write Data commands, this data may be invalid and it is recommended that the Read Data command is used. FIGURE 4-6: SPI Write Command - Normal Mode FIGURE 4-7: SPI Read Command - Normal Mode Master SPDOUT SPI_MOSI Data to Write SPI_CS# SPI_CLK Write Command – 7Eh Unknown, Invalid Data Old Data at Current Address Pointer SPI_MISO Master Drives Slave Drives 1. Data written at current address pointer 2. Address pointer incremented Master SPDOUT SPI_MOSI Master Drives Slave Drives SPI_CLK First Read Command – 7Fh SPI_CS# SPI_MISO Invalid, Unknown Data * ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Subsequent Read Commands – 7F Data at Current Address Pointer Address Pointer Incremented ** ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ * The first read command after any other command will return invalid data for the first byte. Subsequent read commands will return the data at the Current Address Pointer ** The Address Pointer is incremented 8 clocks after the Read Command has been received. Therefore continually sending Read Commands will result in each command reporting new data. Once Read Commands have been finished, the last data byte will be read during the next 8 clocks for any command  2015 Microchip Technology Inc. DS00001623B-page 19 CAP1126 4.7 Bi-Directional SPI Protocols 4.7.1 RESET INTERFACE Resets the Serial interface whenever two successive 7Ah codes are received. Regardless of the current phase of the transaction - command or data, the receipt of the successive reset commands resets the Serial communication interface only. All other functions are not affected by the reset operation. 4.7.2 SET ADDRESS POINTER Sets the address pointer to the register to be accessed by a read or write command. This command overrides the autoincrementing of the address pointer. FIGURE 4-8: SPI Read Command - Normal Mode - Full FIGURE 4-9: SPI Reset Interface Command - Bi-directional Mode Master SPDOUT SPI_MOSI Master Drives Slave Drives SPI_CLK Read Command – 7Fh SPI_CS# Data at previously set register address = current address pointer SPI_MISO ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Data at previously set register address = current address pointer (SPI) XXh 1. Register Read Address updated to Current SPI Read Address pointer 1. Register data loaded into output buffer = data at current address pointer 1. Output buffer transmitted = data at previous address pointer + 1 = current address pointer 1. Register Read Address incremented = current address pointer + 1 1. SPI Read Address Incremented = new current address pointer 2. Register Read Address Incremented = current address pointer +1 Register Data loaded into Output buffer = data at current address pointer + 1 1. Output buffer transmitted = data at current address pointer + 1 2. Flag set to increment SPI Read Address at end of next 8 clocks ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Data at previously set register address = current address pointer (SPI) 1. Register data loaded into output buffer = data at current address pointer 1. Output buffer transmitted = data at previous register address pointer + 1 = current address pointer 1. Output buffer transmitted = data at current address pointer + 1 2. Flag set to increment SPI Read Address at end of next 8 clocks Subsequent Read Commands – 7Fh 1. Register Read Address updated to Current SPI Read Address pointer. 2. Register Read Address incremented = current address pointer +1 – end result = register address pointer doesn’t change Master SPDOUT SPI_MSIO SPI_CS# SPI_CLK Reset - 7Ah Reset - 7Ah ‘0’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ CAP1126 DS00001623B-page 20  2015 Microchip Technology Inc. 4.7.3 WRITE DATA Writes data value to the register address stored in the address pointer. Performs auto increment of address pointer after the data is loaded into the register. 4.7.4 READ DATA Reads data referenced by the address pointer. Performs auto increment of address pointer after the data is transferred to the Master. FIGURE 4-10: SPI Set Address Pointer Command - Bi-directional Mode FIGURE 4-11: SPI Write Data Command - Bi-directional Mode FIGURE 4-12: SPI Read Data Command - Bi-directional Mode Master SPDOUT SPI_MSIO Register Address SPI_CS# SPI_CLK Set Address Pointer – 7Dh ‘0’ ‘1’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Master SPDOUT SPI_MSIO Register Write Data SPI_CS# SPI_CLK Write Command – 7Eh ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ Master SPDOUT SPI_MSIO Master Drives Slave Drives Indeterminate Register Read Data SPI_CLK Read Command – 7Fh SPI_CS# ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’  2015 Microchip Technology Inc. DS00001623B-page 21 CAP1126 4.8 BC-Link Interface The BC-Link is a proprietary bus developed to allow communication between a host controller device to a companion device. This device uses this serial bus to read and write registers and for interrupt processing. The interface uses a data port concept, where the base interface has an address register, data register and a control register, defined in the 8051’s SFR space. Refer to documentation for the BC-Link compatible host controller for details on how to access the CAP1126 via the BCLink Interface. CAP1126 DS00001623B-page 22  2015 Microchip Technology Inc. 5.0 GENERAL DESCRIPTION The CAP1126 is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains six (6) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1126 also contains two (2) low side (or push-pull) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. Finally, the device contains a dedicated RESET pin to act as a soft reset by the system. The CAP1126 offers multiple power states. It operates at the lowest quiescent current during its Deep Sleep state. In the low power Standby state, it can monitor one or more channels and respond to communications normally. The device contains a wake pin (WAKE/SPI_MOSI) output to wake the system when a touch is detected in Standby and to wake the device from Deep Sleep. The device communicates with a host controller using the SPI bus, or via SMBus / I2C. The host controller may poll the device for updated information at any time or it may configure the device to flag an interrupt whenever a touch is detected on any sensor pad. A typical system diagram is shown in Figure 5-1.  2015 Microchip Technology Inc. DS00001623B-page 23 CAP1126 5.1 Power States The CAP1126 has three operating states depending on the status of the STBY and DSLEEP bits. When the device transitions between power states, previously detected touches (for inactive channels) are cleared and the status bits reset. 1. Fully Active - The device is fully active. It is monitoring all active capacitive sensor inputs and driving all LED channels as defined. 2. Standby - The device is in a lower power state. It will measure a programmable number of channels using the Standby Configuration controls (see Section 6.20 through Section 6.22). Interrupts will still be generated based on the active channels. The device will still respond to communications normally and can be returned to the Fully Active state of operation by clearing the STBY bit. FIGURE 5-1: System Diagram for CAP1126 CAP1126 CS6 SMDATA / BC_DATA / SPI_MSIO / SPI_MISO SMCLK / BC_CLK / SPI_CLK VDD Embedded Controller ALERT# / BC_IRQ# CS4 CS2 3.3V – 5V CS5 CS3 CS1 WAKE / SPI_MOSI RESET SPI_CS# ADDR_COMM LED1 LED2 3.3V – 5V Touch Button Touch Button Touch Button Touch Button Touch Button Touch Button CAP1126 DS00001623B-page 24  2015 Microchip Technology Inc. 3. Deep Sleep - The device is in its lowest power state. It is not monitoring any capacitive sensor inputs and not driving any LEDs. All LEDs will be driven to their programmed non-actuated state and no PWM operations will be done. While in Deep Sleep, the device can be awakened by SMBus or SPI communications targeting the device. This will not cause the DSLEEP to be cleared so the device will return to Deep Sleep once all communications have stopped. If the device is not communicating via the 4-wire SPI bus, then during this state of operation, if the WAKE/SPI_MOSI pin is driven high by an external source, the device will clear the DSLEEP bit and return to Fully Active. APPLICATION NOTE: In the Deep Sleep state, the LED output will be either high or low and will not be PWM’d at the min or max duty cycle. 5.2 RESET Pin The RESET pin is an active high reset that is driven from an external source. While it is asserted high, all the internal blocks will be held in reset including the communications protocol used. No capacitive touch sensor inputs will be sampled and the LEDs will not be driven. All configuration settings will be reset to default states and all readings will be cleared. The device will be held in Deep Sleep that can only be removed by driving the RESET pin low. This will cause the RESET status bit to be set to a logic ‘1’ and generate an interrupt. 5.3 WAKE/SPI_MOSI Pin Operation The WAKE / SPI_MOSI pin is a multi-function pin depending on device operation. When the device is configured to communicate using the 4-wire SPI bus, this pin is an input. However, when the CAP1126 is placed in Standby and is not communicating using the 4-wire SPI protocol, the WAKE pin is an active high output. In this condition, the device will assert the WAKE/SPI_MOSI pin when a touch is detected on one of its sampled sensor inputs. The pin will remain asserted until the INT bit has been cleared and then it will be de-asserted. When the CAP1126 is placed in Deep Sleep and it is not communicating using the 4-wire SPI protocol, the WAKE/SPI_- MOSI pin is monitored by the device as an input. If the WAKE/SPI_MOSI pin is driven high by an external source, the CAP1126will clear the DSLEEP bit causing the device to return to Fully Active. When the device is placed in Deep Sleep, this pin is a High-Z input and must have a pull-down resistor to GND for proper operation. 5.4 LED Drivers The CAP1126 contains two (2) LED drivers. Each LED driver can be linked to its respective capacitive touch sensor input or it can be controlled by the host. Each LED driver can be configured to operate in one of the following modes with either push-pull or open drain drive. 1. Direct - The LED is configured to be on or off when the corresponding input stimulus is on or off (or inverted). The brightness of the LED can be programmed from full off to full on (default). Additionally, the LED contains controls to individually configure ramping on, off, and turn-off delay. 2. Pulse 1 - The LED is configured to “Pulse” (transition ON-OFF-ON) a programmable number of times with programmable rate and min / max brightness. This behavior may be actuated when a press is detected or when a release is detected. 3. Pulse 2 - The LED is configured to “Pulse” while actuated and then “Pulse” a programmable number of times with programmable rate and min / max brightness when the sensor pad is released. 4. Breathe - The LED is configured to transition continuously ON-OFF-ON (i.e. to “Breathe”) with a programmable rate and min / max brightness. When an LED is not linked to a sensor and is actuated by the host, there’s an option to assert the ALERT# pin when the initiated LED behavior has completed. 5.4.1 LINKING LEDS TO CAPACITIVE TOUCH SENSOR INPUTS All LEDs can be linked to the corresponding capacitive touch sensor input so that when the sensor input detects a touch, the corresponding LED will be actuated at one of the programmed responses.  2015 Microchip Technology Inc. DS00001623B-page 25 CAP1126 5.5 Capacitive Touch Sensing The CAP1126 contains six (6) independent capacitive touch sensor inputs. Each sensor input has dynamic range to detect a change of capacitance due to a touch. Additionally, each sensor input can be configured to be automatically and routinely re-calibrated. 5.5.1 SENSING CYCLE Each capacitive touch sensor input has controls to be activated and included in the sensing cycle. When the device is active, it automatically initiates a sensing cycle and repeats the cycle every time it finishes. The cycle polls through each active sensor input starting with CS1 and extending through CS6. As each capacitive touch sensor input is polled, its measurement is compared against a baseline “Not Touched” measurement. If the delta measurement is large enough, a touch is detected and an interrupt is generated. The sensing cycle time is programmable (see Section 6.10, "Averaging and Sampling Configuration Register"). 5.5.2 RECALIBRATING SENSOR INPUTS There are various options for recalibrating the capacitive touch sensor inputs. Recalibration re-sets the Base Count Registers (Section 6.24, "Sensor Input Base Count Registers") which contain the “not touched” values used for touch detection comparisons. APPLICATION NOTE: The device will recalibrate all sensor inputs that were disabled when it transitions from Standby. Likewise, the device will recalibrate all sensor inputs when waking out of Deep Sleep. 5.5.2.1 Manual Recalibration The Calibration Activate Registers (Section 6.11, "Calibration Activate Register") force recalibration of selected sensor inputs. When a bit is set, the corresponding capacitive touch sensor input will be recalibrated (both analog and digital). The bit is automatically cleared once the recalibration routine has finished. 5.5.2.2 Automatic Recalibration Each sensor input is regularly recalibrated at a programmable rate (see Section 6.17, "Recalibration Configuration Register"). By default, the recalibration routine stores the average 64 previous measurements and periodically updates the base “not touched” setting for the capacitive touch sensor input. 5.5.2.3 Negative Delta Count Recalibration It is possible that the device loses sensitivity to a touch. This may happen as a result of a noisy environment, an accidental recalibration during a touch, or other environmental changes. When this occurs, the base untouched sensor input may generate negative delta count values. The NEG_DELTA_CNT bits (see Section 6.17, "Recalibration Configuration Register") can be set to force a recalibration after a specified number of consecutive negative delta readings. 5.5.2.4 Delayed Recalibration It is possible that a “stuck button” occurs when something is placed on a button which causes a touch to be detected for a long period. By setting the MAX_DUR_EN bit (see Section 6.6, "Configuration Registers"), a recalibration can be forced when a touch is held on a button for longer than the duration specified in the MAX_DUR bits (see Section 6.8, "Sensor Input Configuration Register"). Note: During this recalibration routine, the sensor inputs will not detect a press for up to 200ms and the Sensor Base Count Register values will be invalid. In addition, any press on the corresponding sensor pads will invalidate the recalibration. Note: Automatic recalibration only works when the delta count is below the active sensor input threshold. It is disabled when a touch is detected. Note: During this recalibration, the device will not respond to touches. CAP1126 DS00001623B-page 26  2015 Microchip Technology Inc. 5.5.3 PROXIMITY DETECTION Each sensor input can be configured to detect changes in capacitance due to proximity of a touch. This circuitry detects the change of capacitance that is generated as an object approaches, but does not physically touch, the enabled sensor pad(s). When a sensor input is selected to perform proximity detection, it will be sampled from 1x to 128x per sampling cycle. The larger the number of samples that are taken, the greater the range of proximity detection is available at the cost of an increased overall sampling time. 5.5.4 MULTIPLE TOUCH PATTERN DETECTION The multiple touch pattern (MTP) detection circuitry can be used to detect lid closure or other similar events. An event can be flagged based on either a minimum number of sensor inputs or on specific sensor inputs simultaneously exceeding an MTP threshold or having their Noise Flag Status Register bits set. An interrupt can also be generated. During an MTP event, all touches are blocked (see Section 6.15, "Multiple Touch Pattern Configuration Register"). 5.5.5 LOW FREQUENCY NOISE DETECTION Each sensor input has an EMI noise detector that will sense if low frequency noise is injected onto the input with sufficient power to corrupt the readings. If this occurs, the device will reject the corrupted sample and set the corresponding bit in the Noise Status register to a logic ‘1’. 5.5.6 RF NOISE DETECTION Each sensor input contains an integrated RF noise detector. This block will detect injected RF noise on the CS pin. The detector threshold is dependent upon the noise frequency. If RF noise is detected on a CS line, that sample is removed and not compared against the threshold. 5.6 ALERT# Pin The ALERT# pin is an active low (or active high when configured) output that is driven when an interrupt event is detected. Whenever an interrupt is generated, the INT bit (see Section 6.1, "Main Control Register") is set. The ALERT# pin is cleared when the INT bit is cleared by the user. Additionally, when the INT bit is cleared by the user, status bits are only cleared if no touch is detected. 5.6.1 SENSOR INTERRUPT BEHAVIOR The sensor interrupts are generated in one of two ways: 1. An interrupt is generated when a touch is detected and, as a user selectable option, when a release is detected (by default - see Section 6.6). See Figure 5-3. 2. If the repeat rate is enabled then, so long as the touch is held, another interrupt will be generated based on the programmed repeat rate (see Figure 5-2). When the repeat rate is enabled, the device uses an additional control called MPRESS that determines whether a touch is flagged as a simple “touch” or a “press and hold”. The MPRESS[3:0] bits set a minimum press timer. When the button is touched, the timer begins. If the sensor pad is released before the minimum press timer expires, it is flagged as a touch and an interrupt is generated upon release. If the sensor input detects a touch for longer than this timer value, it is flagged as a “press and hold” event. So long as the touch is held, interrupts will be generated at the programmed repeat rate and upon release (if enabled). APPLICATION NOTE: Figure 5-2 and Figure 5-3 show default operation which is to generate an interrupt upon sensor pad release and an active-low ALERT# pin. APPLICATION NOTE: The host may need to poll the device twice to determine that a release has been detected. Note: Delayed recalibration only works when the delta count is above the active sensor input threshold. If enabled, it is invoked when a sensor pad touch is held longer than the MAX_DUR bit setting.  2015 Microchip Technology Inc. DS00001623B-page 27 CAP1126 FIGURE 5-2: Sensor Interrupt Behavior - Repeat Rate Enabled FIGURE 5-3: Sensor Interrupt Behavior - No Repeat Rate Enabled Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Min Press Setting (280ms) Interrupt on Touch Button Repeat Rate (175ms) Button Repeat Rate (175ms) Interrupt on Release (optional) ALERT# pin (active low) Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Interrupt on Touch Interrupt on Release (optional) ALERT# pin (active low) CAP1126 DS00001623B-page 28  2015 Microchip Technology Inc. 6.0 REGISTER DESCRIPTION The registers shown in Table 6-1 are accessible through the communications protocol. An entry of ‘-’ indicates that the bit is not used and will always read ‘0’. TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER Register Address R/W Register Name Function Default Value Page 00h R/W Main Control Controls general power states and power dissipation 00h Page 31 02h R General Status Stores general status bits 00h Page 32 03h R Sensor Input Status Returns the state of the sampled capacitive touch sensor inputs 00h Page 32 04h R LED Status Stores status bits for LEDs 00h Page 32 0Ah R Noise Flag Status Stores the noise flags for sensor inputs 00h Page 33 10h R Sensor Input 1 Delta Count Stores the delta count for CS1 00h Page 33 11h R Sensor Input 2 Delta Count Stores the delta count for CS2 00h Page 33 12h R Sensor Input 3 Delta Count Stores the delta count for CS3 00h Page 33 13h R Sensor Input 4 Delta Count Stores the delta count for CS4 00h Page 33 14h R Sensor Input 5 Delta Count Stores the delta count for CS5 00h Page 33 15h R Sensor Input 6 Delta Count Stores the delta count for CS6 00h Page 33 1Fh R/W Sensitivity Control Controls the sensitivity of the threshold and delta counts and data scaling of the base counts 2Fh Page 33 20h R/W Configuration Controls general functionality 20h Page 35 21h R/W Sensor Input Enable Controls whether the capacitive touch sensor inputs are sampled 3Fh Page 36 22h R/W Sensor Input Configuration Controls max duration and auto-repeat delay for sensor inputs operating in the full power state A4h Page 36 23h R/W Sensor Input Configuration 2 Controls the MPRESS controls for all sensor inputs 07h Page 38 24h R/W Averaging and Sampling Config Controls averaging and sampling window 39h Page 38 26h R/W Calibration Activate Forces re-calibration for capacitive touch sensor inputs 00h Page 39 27h R/W Interrupt Enable Enables Interrupts associated with capacitive touch sensor inputs 3Fh Page 40 28h R/W Repeat Rate Enable Enables repeat rate for all sensor inputs 3Fh Page 40 2Ah R/W Multiple Touch Configuration Determines the number of simultaneous touches to flag a multiple touch condition 80h Page 41 2Bh R/W Multiple Touch Pattern Configuration Determines the multiple touch pattern (MTP) configuration 00h Page 41  2015 Microchip Technology Inc. DS00001623B-page 29 CAP1126 2Dh R/W Multiple Touch Pattern Determines the pattern or number of sensor inputs used by the MTP circuitry 3Fh Page 42 2Fh R/W Recalibration Configuration Determines re-calibration timing and sampling window 8Ah Page 43 30h R/W Sensor Input 1 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 1 40h Page 44 31h R/W Sensor Input 2 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 2 40h Page 44 32h R/W Sensor Input 3 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 3 40h Page 44 33h R/W Sensor Input 4 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 4 40h Page 44 34h R/W Sensor Input 5 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 5 40h Page 44 35h R/W Sensor Input 6 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 6 40h Page 44 38h R/W Sensor Input Noise Threshold Stores controls for selecting the noise threshold for all sensor inputs 01h Page 44 Standby Configuration Registers 40h R/W Standby Channel Controls which sensor inputs are enabled while in standby 00h Page 45 41h R/W Standby Configuration Controls averaging and cycle time while in standby 39h Page 45 42h R/W Standby Sensitivity Controls sensitivity settings used while in standby 02h Page 47 43h R/W Standby Threshold Stores the touch detection threshold for active sensor inputs in standby 40h Page 47 44h R/W Configuration 2 Stores additional configuration controls for the device 40h Page 35 Base Count Registers 50h R Sensor Input 1 Base Count Stores the reference count value for sensor input 1 C8h Page 47 51h R Sensor Input 2 Base Count Stores the reference count value for sensor input 2 C8h Page 47 52h R Sensor Input 3 Base Count Stores the reference count value for sensor input 3 C8h Page 47 53h R Sensor Input 4 Base Count Stores the reference count value for sensor input 4 C8h Page 47 54h R Sensor Input 5 Base Count Stores the reference count value for sensor input 5 C8h Page 47 55h R Sensor Input 6 Base Count Stores the reference count value for sensor input 6 C8h Page 47 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1126 DS00001623B-page 30  2015 Microchip Technology Inc. LED Controls 71h R/W LED Output Type Controls the output type for the LED outputs 00h Page 48 72h R/W Sensor Input LED Linking Controls linking of sensor inputs to LED channels 00h Page 48 73h R/W LED Polarity Controls the output polarity of LEDs 00h Page 49 74h R/W LED Output Control Controls the output state of the LEDs 00h Page 50 77h R/W Linked LED Transition Control Controls the transition when LEDs are linked to CS channels 00h Page 51 79h R/W LED Mirror Control Controls the mirroring of duty cycles for the LEDs 00h Page 51 81h R/W LED Behavior 1 Controls the behavior and response of LEDs 1 - 2 00h Page 51 84h R/W LED Pulse 1 Period Controls the period of each breathe during a pulse 20h Page 53 85h R/W LED Pulse 2 Period Controls the period of the breathing during breathe and pulse operation 14h Page 55 86h R/W LED Breathe Period Controls the period of an LED breathe operation 5Dh Page 56 88h R/W LED Config Controls LED configuration 04h Page 56 90h R/W LED Pulse 1 Duty Cycle Determines the min and max duty cycle for the pulse operation F0h Page 57 91h R/W LED Pulse 2 Duty Cycle Determines the min and max duty cycle for breathe and pulse operation F0h Page 57 92h R/W LED Breathe Duty Cycle Determines the min and max duty cycle for the breathe operation F0h Page 57 93h R/W LED Direct Duty Cycle Determines the min and max duty cycle for Direct mode LED operation F0h Page 57 94h R/W LED Direct Ramp Rates Determines the rising and falling edge ramp rates of the LEDs 00h Page 58 95h R/W LED Off Delay Determines the off delay for all LED behaviors 00h Page 58 B1h R Sensor Input 1 Calibration Stores the upper 8-bit calibration value for sensor input 1 00h Page 61 B2h R Sensor Input 2 Calibration Stores the upper 8-bit calibration value for sensor input 2 00h Page 61 B3h R Sensor Input 3 Calibration Stores the upper 8-bit calibration value for sensor input 3 00h Page 61 B4h R Sensor Input 4 Calibration Stores the upper 8-bit calibration value for sensor input 4 00h Page 61 B5h R Sensor Input 5 Calibration Stores the upper 8-bit calibration value for sensor input 5 00h Page 61 B6h R Sensor Input 6 Calibration Stores the upper 8-bit calibration value for sensor input 6 00h Page 61 B9h R Sensor Input Calibration LSB 1 Stores the 2 LSBs of the calibration value for sensor inputs 1 - 4 00h Page 61 BAh R Sensor Input Calibration LSB 2 Stores the 2 LSBs of the calibration value for sensor inputs 5 - 6 00h Page 61 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page  2015 Microchip Technology Inc. DS00001623B-page 31 CAP1126 During Power-On-Reset (POR), the default values are stored in the registers. A POR is initiated when power is first applied to the part and the voltage on the VDD supply surpasses the POR level as specified in the electrical characteristics. Any reads to undefined registers will return 00h. Writes to undefined registers will not have an effect. When a bit is “set”, this means that the user writes a logic ‘1’ to it. When a bit is “cleared”, this means that the user writes a logic ‘0’ to it. 6.1 Main Control Register The Main Control register controls the primary power state of the device. Bits 7 - 6 - GAIN[1:0] - Controls the gain used by the capacitive touch sensing circuitry. As the gain is increased, the effective sensitivity is likewise increased as a smaller delta capacitance is required to generate the same delta count values. The sensitivity settings may need to be adjusted along with the gain settings such that data overflow does not occur. APPLICATION NOTE: The gain settings apply to both Standby and Active states. Bit 5 - STBY - Enables Standby. • ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - Capacitive touch sensor input scanning is limited to the sensor inputs set in the Standby Channel register (see Section 6.20). The status registers will not be cleared until read. LEDs that are linked to capacitive touch sensor inputs will remain linked and active. Sensor inputs that are no longer sampled will flag a release and then remain in a non-touched state. LEDs that are manually controlled will be unaffected. • Bit 4 - DSLEEP - Enables Deep Sleep by deactivating all functions. This bit will be cleared when the WAKE pin is driven high. ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - All sensor input scanning is disabled. All LEDs are driven to their programmed non-actuated state and no PWM operations will be done. The status registers are automatically cleared and the INT bit is cleared. Bit 0 - INT - Indicates that there is an interrupt. When this bit is set, it asserts the ALERT# pin. If a channel detects a touch and its associated interrupt enable bit is not set to a logic ‘1’, no action is taken. FDh R Product ID Stores a fixed value that identifies each product 53h Page 62 FEh R Manufacturer ID Stores a fixed value that identifies Microchip 5Dh Page 62 FFh R Revision Stores a fixed value that represents the revision number 83h Page 62 TABLE 6-2: MAIN CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 00h R/W Main Control GAIN[1:0] STBY DSLEEP - - - INT 00h TABLE 6-3: GAIN BIT DECODE GAIN[1:0] Capacitive Touch Sensor Gain 1 0 0 0 1 01 2 10 4 11 8 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1126 DS00001623B-page 32  2015 Microchip Technology Inc. This bit is cleared by writing a logic ‘0’ to it. When this bit is cleared, the ALERT# pin will be deasserted and all status registers will be cleared if the condition has been removed. If the WAKE/SPI_MOSI pin is asserted as a result of a touch detected while in Standby, it will likewise be deasserted when this bit is cleared. Note that the WAKE / SPI_MOSI pin is not driven when communicating via the 4-wire SPI protocol. • ‘0’ - No interrupt pending. • ‘1’ - A touch has been detected on one or more channels and the interrupt has been asserted. 6.2 Status Registers All status bits are cleared when the device enters the Deep Sleep (DSLEEP = ‘1’ - see Section 6.1). 6.2.1 GENERAL STATUS - 02H Bit 4 - LED - Indicates that one or more LEDs have finished their programmed activity. This bit is set if any bit in the LED Status register is set. Bit 3 - RESET - Indicates that the device has come out of reset. This bit is set when the device exits a POR state or when the RESET pin has been deasserted and qualified via the RESET pin filter (see Section 5.2). This bit will cause the INT bit to be set and is cleared when the INT bit is cleared. Bit 2 - MULT - Indicates that the device is blocking detected touches due to the Multiple Touch detection circuitry (see Section 6.14). This bit will not cause the INT bit to be set and hence will not cause an interrupt. Bit 1 - MTP - Indicates that the device has detected a number of sensor inputs that exceed the MTP threshold either via the pattern recognition or via the number of sensor inputs (see Section 6.15). This bit will cause the INT bit to be set if the MTP_ALERT bit is also set. This bit will not be cleared until the condition that caused it to be set has been removed. Bit 0 - TOUCH - Indicates that a touch was detected. This bit is set if any bit in the Sensor Input Status register is set. 6.2.2 SENSOR INPUT STATUS - 03H The Sensor Input Status Register stores status bits that indicate a touch has been detected. A value of ‘0’ in any bit indicates that no touch has been detected. A value of ‘1’ in any bit indicates that a touch has been detected. All bits are cleared when the INT bit is cleared and if a touch on the respective capacitive touch sensor input is no longer present. If a touch is still detected, the bits will not be cleared (but this will not cause the interrupt to be asserted - see Section 6.6). Bit 5 - CS6 - Indicates that a touch was detected on Sensor Input 6. Bit 4 - CS5 - Indicates that a touch was detected on Sensor Input 5. Bit 3 - CS4 - Indicates that a touch was detected on Sensor Input 4. Bit 2 - CS3 - Indicates that a touch was detected on Sensor Input 3. Bit 1 - CS2 - Indicates that a touch was detected on Sensor Input 2. This sensor input can be linked to LED2. Bit 0 - CS1 - Indicates that a touch was detected on Sensor Input 1. This sensor input can be linked to LED1. 6.2.3 LED STATUS - 04H The LED Status Registers indicate when an LED has completed its configured behavior (see Section 6.31, "LED Behavior Register") after being actuated by the host (see Section 6.28, "LED Output Control Register"). These bits are ignored when the LED is linked to a capacitive sensor input. All LED Status bits are cleared when the INT bit is cleared. Bit 1 - LED2_DN - Indicates that LED2 has finished its behavior after being actuated by the host. Bit 0 - LED1_DN - Indicates that LED1 has finished its behavior after being actuated by the host. TABLE 6-4: STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 02h R General Status - - - LED RESET MULT MTP TOUCH 00h 03h R Sensor Input Status - - CS6 CS5 CS4 CS3 CS2 CS1 00h 04h R LED Status - - - - - - LED2_ DN LED1_ DN 00h  2015 Microchip Technology Inc. DS00001623B-page 33 CAP1126 6.3 Noise Flag Status Registers The Noise Flag Status registers store status bits that are generated from the analog block if the detected noise is above the operating region of the analog detector or the RF noise detector. These bits indicate that the most recently received data from the sensor input is invalid and should not be used for touch detection. So long as the bit is set for a particular channel, the delta count value is reset to 00h and thus no touch is detected. These bits are not sticky and will be cleared automatically if the analog block does not report a noise error. APPLICATION NOTE: If the MTP detection circuitry is enabled, these bits count as sensor inputs above the MTP threshold (see Section 5.5.4, "Multiple Touch Pattern Detection") even if the corresponding delta count is not. If the corresponding delta count also exceeds the MTP threshold, it is not counted twice. APPLICATION NOTE: Regardless of the state of the Noise Status bits, if low frequency noise is detected on a sensor input, that sample will be discarded unless the DIS_ANA_NOISE bit is set. As well, if RF noise is detected on a sensor input, that sample will be discarded unless the DIS_RF_NOISE bit is set. 6.4 Sensor Input Delta Count Registers The Sensor Input Delta Count registers store the delta count that is compared against the threshold used to determine if a touch has been detected. The count value represents a change in input due to the capacitance associated with a touch on one of the sensor inputs and is referenced to a calibrated base “Not Touched” count value. The delta is an instantaneous change and is updated once per sensor input per sensing cycle (see Section 5.5.1, "Sensing Cycle"). The value presented is a standard 2’s complement number. In addition, the value is capped at a value of 7Fh. A reading of 7Fh indicates that the sensitivity settings are too high and should be adjusted accordingly (see Section 6.5). The value is also capped at a negative value of 80h for negative delta counts which may result upon a release. 6.5 Sensitivity Control Register TABLE 6-5: NOISE FLAG STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 0Ah R Noise Flag Status - - CS6_ NOISE CS5_ NOISE CS4_ NOISE CS3_ NOISE CS2_ NOISE CS1_ NOISE 00h TABLE 6-6: SENSOR INPUT DELTA COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 10h R Sensor Input 1 Delta Count Sign 64 32 16 8 4 2 1 00h 11h R Sensor Input 2 Delta Count Sign 64 32 16 8 4 2 1 00h 12h R Sensor Input 3 Delta Count Sign 64 32 16 8 4 2 1 00h 13h R Sensor Input 4 Delta Count Sign 64 32 16 8 4 2 1 00h 14h R Sensor Input 5 Delta Count Sign 64 32 16 8 4 2 1 00h 15h R Sensor Input 6 Delta Count Sign 64 32 16 8 4 2 1 00h TABLE 6-7: SENSITIVITY CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 1Fh R/W Sensitivity Control - DELTA_SENSE[2:0] BASE_SHIFT[3:0] 2Fh CAP1126 DS00001623B-page 34  2015 Microchip Technology Inc. The Sensitivity Control register controls the sensitivity of a touch detection. Bits 6-4 DELTA_SENSE[2:0] - Controls the sensitivity of a touch detection. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta capacitance corresponding to a “lighter” touch. These settings are more sensitive to noise, however, and a noisy environment may flag more false touches with higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely, a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). Bits 3 - 0 - BASE_SHIFT[3:0] - Controls the scaling and data presentation of the Base Count registers. The higher the value of these bits, the larger the range and the lower the resolution of the data presented. The scale factor represents the multiplier to the bit-weighting presented in these register descriptions. APPLICATION NOTE: The BASE_SHIFT[3:0] bits normally do not need to be updated. These settings will not affect touch detection or sensitivity. These bits are sometimes helpful in analyzing the Cap Sensing board performance and stability. TABLE 6-8: DELTA_SENSE BIT DECODE DELTA_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-9: BASE_SHIFT BIT DECODE BASE_SHIFT[3:0] Data Scaling Factor 32 1 0 0 0 0 0 1x 0 0 0 1 2x 0 0 1 0 4x 0 0 1 1 8x 0 1 0 0 16x 0 1 0 1 32x 0 1 1 0 64x 0 1 1 1 128x 1 0 0 0 256x All others 256x (default = 1111b)  2015 Microchip Technology Inc. DS00001623B-page 35 CAP1126 6.6 Configuration Registers The Configuration registers control general global functionality that affects the entire device. 6.6.1 CONFIGURATION - 20H Bit 7 - TIMEOUT - Enables the timeout and idle functionality of the SMBus protocol. • ‘0’ (default for Functional Revision C) - The SMBus timeout and idle functionality are disabled. The SMBus interface will not time out if the clock line is held low. Likewise, it will not reset if both the data and clock lines are held high for longer than 200us. This is used for I2C compliance. • ‘1’ (default for Functional Revision B) - The SMBus timeout and idle functionality are enabled. The SMBus interface will time out if the clock line is held low for longer than 30ms. Likewise, it will reset if both the data and clock lines are held high for longer than 200us. Bit 6 - WAKE_CFG - Configures the operation of the WAKE pin. • ‘0’ (default) - The WAKE pin is not asserted when a touch is detected while the device is in Standby. It will still be used to wake the device from Deep Sleep when driven high. • ‘1’ - The WAKE pin will be asserted high when a touch is detected while the device is in Standby. It will also be used to wake the device from Deep Sleep when driven high. Bit 5 - DIS_DIG_NOISE - Determines whether the digital noise threshold (see Section 6.19, "Sensor Input Noise Threshold Register") is used by the device. Setting this bit disables the feature. • ‘0’ - The digital noise threshold is used. If a delta count value exceeds the noise threshold but does not exceed the touch threshold, the sample is discarded and not used for the automatic re-calibration routine. • ‘1’ (default) - The noise threshold is disabled. Any delta count that is less than the touch threshold is used for the automatic re-calibration routine. Bit 4 - DIS_ANA_NOISE - Determines whether the analog noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If low frequency noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if low frequency noise is detected. Bit 3 - MAX_DUR_EN - Determines whether the maximum duration recalibration is enabled. • ‘0’ (default) - The maximum duration recalibration functionality is disabled. A touch may be held indefinitely and no re-calibration will be performed on any sensor input. • ‘1’ - The maximum duration recalibration functionality is enabled. If a touch is held for longer than the MAX_DUR bit settings, then the re-calibration routine will be restarted (see Section 6.8). 6.6.2 CONFIGURATION 2 - 44H Bit 7 - INV_LINK_TRAN - Determines the behavior of the Linked LED Transition controls (see Section 6.29). • ‘0’ (default) - The Linked LED Transition controls set the min duty cycle equal to the max duty cycle. • ‘1’ - The Linked LED Transition controls will invert the touch signal. For example, a touch signal will be inverted to a non-touched signal. Bit 6 - ALT_POL - Determines the ALERT# pin polarity and behavior. • ‘0’ - The ALERT# pin is active high and push-pull. • ‘1’ (default) - The ALERT# pin is active low and open drain. TABLE 6-10: CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 20h R/W Configuration TIMEOUT WAKE_ CFG DIS_ DIG_ NOISE DIS_ ANA_ NOISE MAX_ DUR_EN - -- A0h (Rev B) 20h (rev C) 44h R/W Configuration 2 INV_LINK_ TRAN ALT_ POL BLK_PWR_ CTRL BLK_POL_ MIR SHOW_ RF_ NOISE DIS_ RF_ NOISE - INT_ REL_n 40h CAP1126 DS00001623B-page 36  2015 Microchip Technology Inc. Bit 5 - BLK_PWR_CTRL - Determines whether the device will reduce power consumption while waiting between conversion time completion and the end of the polling cycle. • ‘0’ (default) - The device will always power down as much as possible during the time between the end of the last conversion and the end of the polling cycle. • ‘1’ - The device will not power down the Cap Sensor during the time between the end of the last conversion and the end of the polling cycle. Bit 4 - BLK_POL_MIR - Determines whether the LED Mirror Control register bits are linked to the LED Polarity bits. Setting this bit blocks the normal behavior which is to automatically set and clear the LED Mirror Control bits when the LED Polarity bits are set or cleared. • ‘0’ (default) - When the LED Polarity controls are set, the corresponding LED Mirror control is automatically set. Likewise, when the LED Polarity controls are cleared, the corresponding LED Mirror control is also cleared. • ‘1’ - When the LED Polarity controls are set, the corresponding LED Mirror control is not automatically set. Bit 3 - SHOW_RF_NOISE - Determines whether the Noise Status bits will show RF Noise as the only input source. • ‘0’ (default) - The Noise Status registers will show both RF noise and low frequency EMI noise if either is detected on a capacitive touch sensor input. • ‘1’ - The Noise Status registers will only show RF noise if it is detected on a capacitive touch sensor input. EMI noise will still be detected and touches will be blocked normally; however, the status bits will not be updated. Bit 2 - DIS_RF_NOISE - Determines whether the RF noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If RF noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if RF noise is detected. Bit 0 - INT_REL_n - Controls the interrupt behavior when a release is detected on a button. • ‘0’ (default) - An interrupt is generated when a press is detected and again when a release is detected and at the repeat rate (if enabled - see Section 6.13). • ‘1’ - An interrupt is generated when a press is detected and at the repeat rate but not when a release is detected. 6.7 Sensor Input Enable Registers The Sensor Input Enable registers determine whether a capacitive touch sensor input is included in the sampling cycle. The length of the sampling cycle is not affected by the number of sensor inputs measured. Bit 5 - CS6_EN - Enables the CS6 input to be included during the sampling cycle. • ‘0’ - The CS6 input is not included in the sampling cycle. • ‘1’ (default) - The CS6 input is included in the sampling cycle. Bit 4 - CS5_EN - Enables the CS5 input to be included during the sampling cycle. Bit 3 - CS4_EN - Enables the CS4 input to be included during the sampling cycle. Bit 2 - CS3_EN - Enables the CS3 input to be included during the sampling cycle. Bit 1 - CS2_EN - Enables the CS2 input to be included during the sampling cycle. Bit 0 - CS1_EN - Enables the CS1 input to be included during the sampling cycle. 6.8 Sensor Input Configuration Register TABLE 6-11: SENSOR INPUT ENABLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 21h R/W Sensor Input Enable - - CS6_EN CS5_EN CS4_EN CS3_EN CS2_EN CS1_EN 3Fh TABLE 6-12: SENSOR INPUT CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 22h R/W Sensor Input Configuration MAX_DUR[3:0] RPT_RATE[3:0] A4h  2015 Microchip Technology Inc. DS00001623B-page 37 CAP1126 The Sensor Input Configuration Register controls timings associated with the Capacitive sensor inputs 1 - 6. Bits 7 - 4 - MAX_DUR[3:0] - (default 1010b) - Determines the maximum time that a sensor pad is allowed to be touched until the capacitive touch sensor input is recalibrated, as shown in Table 6-13. Bits 3 - 0 - RPT_RATE[3:0] - (default 0100b) Determines the time duration between interrupt assertions when auto repeat is enabled. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-14. TABLE 6-13: MAX_DUR BIT DECODE MAX_DUR[3:0] Time Before Recalibration 32 1 0 0 0 0 0 560ms 0 0 0 1 840ms 0 0 1 0 1120ms 0 0 1 1 1400ms 0 1 0 0 1680ms 0 1 0 1 2240ms 0 1 1 0 2800ms 1 1 1 3360ms 1 0 0 0 3920ms 1 0 0 1 4480ms 1 0 1 0 5600ms (default) 1 0 1 1 6720ms 1 1 0 0 7840ms 1 1 0 1 8906ms 1 1 1 0 10080ms 1 1 1 1 11200ms TABLE 6-14: RPT_RATE BIT DECODE RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms (default) 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms CAP1126 DS00001623B-page 38  2015 Microchip Technology Inc. 6.9 Sensor Input Configuration 2 Register Bits 3 - 0 - M_PRESS[3:0] - (default 0111b) - Determines the minimum amount of time that sensor inputs configured to use auto repeat must detect a sensor pad touch to detect a “press and hold” event. If the sensor input detects a touch for longer than the M_PRESS[3:0] settings, a “press and hold” event is detected. If a sensor input detects a touch for less than or equal to the M_PRESS[3:0] settings, a touch event is detected. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-16. 6.10 Averaging and Sampling Configuration Register The Averaging and Sampling Configuration register controls the number of samples taken and the total sensor input cycle time for all active sensor inputs while the device is functioning in Active state. Bits 6 - 4 - AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-18. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. For example, if CS1, CS2, and CS3 are sampled during the sensor cycle, and the AVG[2:0] bits are set to take 4 samples per channel, then the full sensor cycle will be: CS1, CS1, CS1, CS1, CS2, CS2, CS2, CS2, CS3, CS3, CS3, CS3. TABLE 6-15: SENSOR INPUT CONFIGURATION 2 REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 23h R/W Sensor Input Configuration 2 - - - - M_PRESS[3:0] 07h TABLE 6-16: M_PRESS BIT DECODE M_PRESS[3:0] M_PRESS SETTINGS 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms (default) 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-17: AVERAGING AND SAMPLING CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 24h R/W Averaging and Sampling Config AVG[2:0] SAMP_TIME[1:0] CYCLE_TIME [1:0] 39h  2015 Microchip Technology Inc. DS00001623B-page 39 CAP1126 Bits 3 - 2 - SAMP_TIME[1:0] - Determines the time to take a single sample as shown in Table 6-19. Bits 1 - 0 - CYCLE_TIME[1:0] - Determines the overall cycle time for all measured channels during normal operation as shown in Table 6-20. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, then the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. 6.11 Calibration Activate Register The Calibration Activate register forces the respective sensor inputs to be re-calibrated affecting both the analog and digital blocks. During the re-calibration routine, the sensor inputs will not detect a press for up to 600ms and the Sensor Input Base Count register values will be invalid. During this time, any press on the corresponding sensor pads will invalidate the re-calibration. When finished, the CALX[9:0] bits will be updated (see Section 6.39). TABLE 6-18: AVG BIT DECODE AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-19: SAMP_TIME BIT DECODE SAMP_TIME[1:0] Sample Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-20: CYCLE_TIME BIT DECODE CYCLE_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms TABLE 6-21: CALIBRATION ACTIVATE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 26h R/W Calibration Activate - - CS6_ CAL CS5_ CAL CS4_ CAL CS3_ CAL CS2_ CAL CS1_ CAL 00h CAP1126 DS00001623B-page 40  2015 Microchip Technology Inc. When the corresponding bit is set, the device will perform the calibration and the bit will be automatically cleared once the re-calibration routine has finished. Bit 5 - CS6_CAL - When set, the CS6 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 4 - CS5_CAL - When set, the CS5 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 3 - CS4_CAL - When set, the CS4 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 2 - CS3_CAL - When set, the CS3 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 1 - CS2_CAL - When set, the CS2 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 0 - CS1_CAL - When set, the CS1 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. 6.12 Interrupt Enable Register The Interrupt Enable register determines whether a sensor pad touch or release (if enabled) causes the interrupt pin to be asserted. Bit 5 - CS6_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS6 (associated with the CS6 status bit). • ‘0’ - The interrupt pin will not be asserted if a touch is detected on CS6 (associated with the CS6 status bit). • ‘1’ (default) - The interrupt pin will be asserted if a touch is detected on CS6 (associated with the CS6 status bit). Bit 4 - CS5_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS5 (associated with the CS5 status bit). Bit 3 - CS4_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS4 (associated with the CS4 status bit). Bit 2 - CS3_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS3 (associated with the CS3 status bit). Bit 1 - CS2_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS2 (associated with the CS2 status bit). Bit 0 - CS1_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS1 (associated with the CS1 status bit). 6.13 Repeat Rate Enable Register The Repeat Rate Enable register enables the repeat rate of the sensor inputs as described in Section 5.6.1. Bit 5 - CS6_RPT_EN - Enables the repeat rate for capacitive touch sensor input 6. • ‘0’ - The repeat rate for CS6 is disabled. It will only generate an interrupt when a touch is detected and when a release is detected no matter how long the touch is held for. • ‘1’ (default) - The repeat rate for CS6 is enabled. In the case of a “touch” event, it will generate an interrupt when a TABLE 6-22: INTERRUPT ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 27h R/W Interrupt Enable - - CS6_ INT_EN CS5_ INT_EN CS4_ INT_EN CS3_ INT_EN CS2_ INT_EN CS1_ INT_EN 3Fh TABLE 6-23: REPEAT RATE ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 28h R/W Repeat Rate Enable - - CS6_ RPT_EN CS5_ RPT_EN CS4_ RPT_EN CS3_ RPT_EN CS2_ RPT_EN CS1_ RPT_EN 3Fh  2015 Microchip Technology Inc. DS00001623B-page 41 CAP1126 touch is detected and a release is detected (as determined by the INT_REL_n bit - see Section 6.6). In the case of a “press and hold” event, it will generate an interrupt when a touch is detected and at the repeat rate so long as the touch is held. Bit 4 - CS5_RPT_EN - Enables the repeat rate for capacitive touch sensor input 5. Bit 3 - CS4_RPT_EN - Enables the repeat rate for capacitive touch sensor input 4. Bit 2 - CS3_RPT_EN - Enables the repeat rate for capacitive touch sensor input 3. Bit 1 - CS2_RPT_EN - Enables the repeat rate for capacitive touch sensor input 2. Bit 0 - CS1_RPT_EN - Enables the repeat rate for capacitive touch sensor input 1. 6.14 Multiple Touch Configuration Register The Multiple Touch Configuration register controls the settings for the multiple touch detection circuitry. These settings determine the number of simultaneous buttons that may be pressed before additional buttons are blocked and the MULT status bit is set. Bit 7 - MULT_BLK_EN - Enables the multiple button blocking circuitry. • ‘0’ - The multiple touch circuitry is disabled. The device will not block multiple touches. • ‘1’ (default) - The multiple touch circuitry is enabled. The device will flag the number of touches equal to programmed multiple touch threshold and block all others. It will remember which sensor inputs are valid and block all others until that sensor pad has been released. Once a sensor pad has been released, the N detected touches (determined via the cycle order of CS1 - CS6) will be flagged and all others blocked. Bits 3 - 2 - B_MULT_T[1:0] - Determines the number of simultaneous touches on all sensor pads before a Multiple Touch Event is detected and sensor inputs are blocked. The bit decode is given by Table 6-25. 6.15 Multiple Touch Pattern Configuration Register The Multiple Touch Pattern Configuration register controls the settings for the multiple touch pattern detection circuitry. This circuitry works like the multiple touch detection circuitry with the following differences: 1. The detection threshold is a percentage of the touch detection threshold as defined by the MTP_TH[1:0] bits whereas the multiple touch circuitry uses the touch detection threshold. 2. The MTP detection circuitry either will detect a specific pattern of sensor inputs as determined by the Multiple Touch Pattern register settings or it will use the Multiple Touch Pattern register settings to determine a minimum number of sensor inputs that will cause the MTP circuitry to flag an event. When using pattern recognition mode, TABLE 6-24: MULTIPLE TOUCH CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Ah R/W Multiple Touch Config MULT_ BLK_ EN - - - B_MULT_T[1:0] - - 80h TABLE 6-25: B_MULT_T BIT DECODE B_MULT_T[1:0] Number of Simultaneous Touches 1 0 0 0 1 (default) 01 2 10 3 11 4 TABLE 6-26: MULTIPLE TOUCH PATTERN CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Bh R/W Multiple Touch Pattern Config MTP_ EN - - MTP_TH[1:0] COMP_ PTRN MTP_ ALERT 00h CAP1126 DS00001623B-page 42  2015 Microchip Technology Inc. if all of the sensor inputs set by the Multiple Touch Pattern register have a delta count greater than the MTP threshold or have their corresponding Noise Flag Status bits set, the MTP bit will be set. When using the absolute number mode, if the number of sensor inputs with thresholds above the MTP threshold or with Noise Flag Status bits set is equal to or greater than this number, the MTP bit will be set. 3. When an MTP event occurs, all touches are blocked and an interrupt is generated. 4. All sensor inputs will remain blocked so long as the requisite number of sensor inputs are above the MTP threshold or have Noise Flag Status bits set. Once this condition is removed, touch detection will be restored. Note that the MTP status bit is only cleared by writing a ‘0’ to the INT bit once the condition has been removed. Bit 7 - MTP_EN - Enables the multiple touch pattern detection circuitry. • ‘0’ (default) - The MTP detection circuitry is disabled. • ‘1’ - The MTP detection circuitry is enabled. Bits 3-2 - MTP_TH[1:0] - Determine the MTP threshold, as shown in Table 6-27. This threshold is a percentage of sensor input threshold (see Section 6.18, "Sensor Input Threshold Registers") when the device is in the Fully Active state or of the standby threshold (see Section 6.23, "Standby Threshold Register") when the device is in the Standby state. Bit 1 - COMP_PTRN - Determines whether the MTP detection circuitry will use the Multiple Touch Pattern register as a specific pattern of sensor inputs or as an absolute number of sensor inputs. • ‘0’ (default) - The MTP detection circuitry will use the Multiple Touch Pattern register bit settings as an absolute minimum number of sensor inputs that must be above the threshold or have Noise Flag Status bits set. The number will be equal to the number of bits set in the register. • ‘1’ - The MTP detection circuitry will use pattern recognition. Each bit set in the Multiple Touch Pattern register indicates a specific sensor input that must have a delta count greater than the MTP threshold or have a Noise Flag Status bit set. If the criteria are met, the MTP status bit will be set. Bit 0 - MTP_ALERT - Enables an interrupt if an MTP event occurs. In either condition, the MTP status bit will be set. • ‘0’ (default) - If an MTP event occurs, the ALERT# pin is not asserted. • ‘1’ - If an MTP event occurs, the ALERT# pin will be asserted. 6.16 Multiple Touch Pattern Register The Multiple Touch Pattern register acts as a pattern to identify an expected sensor input profile for diagnostics or other significant events. There are two methods for how the Multiple Touch Pattern register is used: as specific sensor inputs or number of sensor input that must exceed the MTP threshold or have Noise Flag Status bits set. Which method is used is based on the COMP_PTRN bit (see Section 6.15). The methods are described below. 1. Specific Sensor Inputs: If, during a single polling cycle, the specific sensor inputs above the MTP threshold or with Noise Flag Status bits set match those bits set in the Multiple Touch Pattern register, an MTP event is flagged. 2. Number of Sensor Inputs: If, during a single polling cycle, the number of sensor inputs with a delta count above the MTP threshold or with Noise Flag Status bits set is equal to or greater than the number of pattern bits set, an MTP event is flagged. TABLE 6-27: MTP_TH BIT DECODE MTP_TH[1:0] Threshold Divide Setting 1 0 0 0 12.5% (default) 0 1 25% 1 0 37.5% 1 1 100% TABLE 6-28: MULTIPLE TOUCH PATTERN REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Dh R/W Multiple Touch Pattern - - CS6_ PTRN CS5_ PTRN CS4_ PTRN CS3_ PTRN CS2_ PTRN CS1_ PTRN 3Fh  2015 Microchip Technology Inc. DS00001623B-page 43 CAP1126 Bit 5 - CS6_PTRN - Determines whether CS6 is considered as part of the Multiple Touch Pattern. • ‘0’ - CS6 is not considered a part of the pattern. • ‘1’ - CS6 is considered a part of the pattern or the absolute number of sensor inputs that must have a delta count greater than the MTP threshold or have the Noise Flag Status bit set is increased by 1. Bit 4 - CS5_PTRN - Determines whether CS5 is considered as part of the Multiple Touch Pattern. Bit 3 - CS4_PTRN - Determines whether CS4 is considered as part of the Multiple Touch Pattern. Bit 2 - CS3_PTRN - Determines whether CS3 is considered as part of the Multiple Touch Pattern. Bit 1 - CS2_PTRN - Determines whether CS2 is considered as part of the Multiple Touch Pattern. Bit 0 - CS1_PTRN - Determines whether CS1 is considered as part of the Multiple Touch Pattern. 6.17 Recalibration Configuration Register The Recalibration Configuration register controls the automatic re-calibration routine settings as well as advanced controls to program the Sensor Input Threshold register settings. Bit 7 - BUT_LD_TH - Enables setting all Sensor Input Threshold registers by writing to the Sensor Input 1 Threshold register. • ‘0’ - Each Sensor Input X Threshold register is updated individually. • ‘1’ (default) - Writing the Sensor Input 1 Threshold register will automatically overwrite the Sensor Input Threshold registers for all sensor inputs (Sensor Input Threshold 1 through Sensor Input Threshold 6). The individual Sensor Input X Threshold registers (Sensor Input 2 Threshold through Sensor Input 6 Threshold) can be individually updated at any time. Bit 6 - NO_CLR_INTD - Controls whether the accumulation of intermediate data is cleared if the noise status bit is set. • ‘0’ (default) - The accumulation of intermediate data is cleared if the noise status bit is set. • ‘1’ - The accumulation of intermediate data is not cleared if the noise status bit is set. APPLICATION NOTE: Bits 5 and 6 should both be set to the same value. Either both should be set to ‘0’ or both should be set to ‘1’. Bit 5 - NO_CLR_NEG - Controls whether the consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘0’ (default) - The consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘1’ - The consecutive negative delta counts counter is not cleared if the noise status bit is set. Bits 4 - 3 - NEG_DELTA_CNT[1:0] - Determines the number of negative delta counts necessary to trigger a digital recalibration as shown in Table 6-30. TABLE 6-29: RECALIBRATION CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Fh R/W Recalibration Configuration BUT_ LD_TH NO_ CLR_ INTD NO_ CLR_ NEG NEG_DELTA_ CNT[1:0] CAL_CFG[2:0] 8Ah TABLE 6-30: NEG_DELTA_CNT BIT DECODE NEG_DELTA_CNT[1:0] Number of Consecutive Negative Delta Count Values 1 0 00 8 0 1 16 (default) 1 0 32 1 1 None (disabled) CAP1126 DS00001623B-page 44  2015 Microchip Technology Inc. Bits 2 - 0 - CAL_CFG[2:0] - Determines the update time and number of samples of the automatic re-calibration routine. The settings apply to all sensor inputs universally (though individual sensor inputs can be configured to support re-calibration - see Section 6.11). Note 6-1 Recalibration Samples refers to the number of samples that are measured and averaged before the Base Count is updated however does not control the base count update period. Note 6-2 Update Time refers to the amount of time (in polling cycle periods) that elapses before the Base Count is updated. The time will depend upon the number of channels active, the averaging setting, and the programmed cycle time. 6.18 Sensor Input Threshold Registers The Sensor Input Threshold registers store the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. When the BUT_LD_TH bit is set (see Section 6.17 - bit 7), writing data to the Sensor Input 1 Threshold register will update all of the sensor input threshold registers (31h - 35h inclusive). 6.19 Sensor Input Noise Threshold Register TABLE 6-31: CAL_CFG BIT DECODE CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210 0 0 0 16 16 0 0 1 32 32 0 1 0 64 64 (default) 0 1 1 128 128 1 0 0 256 256 1 0 1 256 1024 1 1 0 256 2048 1 1 1 256 4096 TABLE 6-32: SENSOR INPUT THRESHOLD REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 30h R/W Sensor Input 1 Threshold - 64 32 16 8 4 2 1 40h 31h R/W Sensor Input 2 Threshold - 64 32 16 8 4 2 1 40h 32h R/W Sensor Input 3 Threshold - 64 32 16 8 4 2 1 40h 33h R/W Sensor Input 4 Threshold - 64 32 16 8 4 2 1 40h 34h R/W Sensor Input 5 Threshold - 64 32 16 8 4 2 1 40h 35h R/W Sensor Input 6 Threshold - 64 32 16 8 4 2 1 40h TABLE 6-33: SENSOR INPUT NOISE THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 38h R/W Sensor Input Noise Threshold CS_BN_TH [1:0] 01h  2015 Microchip Technology Inc. DS00001623B-page 45 CAP1126 The Sensor Input Noise Threshold register controls the value of a secondary internal threshold to detect noise and improve the automatic recalibration routine. If a capacitive touch sensor input exceeds the Sensor Input Noise Threshold but does not exceed the sensor input threshold, it is determined to be caused by a noise spike. That sample is not used by the automatic re-calibration routine. This feature can be disabled by setting the DIS_DIG_NOISE bit. Bits 1-0 - CS1_BN_TH[1:0] - Controls the noise threshold for all capacitive touch sensor inputs, as shown in Table 6-34. The threshold is proportional to the threshold setting. 6.20 Standby Channel Register The Standby Channel register controls which (if any) capacitive touch sensor inputs are active during Standby. Bit 5 - CS6_STBY - Controls whether the CS6 channel is active in Standby. • ‘0’ (default) - The CS6 channel not be sampled during Standby mode. • ‘1’ - The CS6 channel will be sampled during Standby Mode. It will use the Standby threshold setting, and the standby averaging and sensitivity settings. Bit 4 - CS5_STBY - Controls whether the CS5 channel is active in Standby. Bit 3 - CS4_STBY - Controls whether the CS4 channel is active in Standby. Bit 2 - CS3_STBY - Controls whether the CS3 channel is active in Standby. Bit 1 - CS2_STBY - Controls whether the CS2 channel is active in Standby. Bit 0 - CS1_STBY - Controls whether the CS1 channel is active in Standby. 6.21 Standby Configuration Register The Standby Configuration register controls averaging and cycle time for those sensor inputs that are active in Standby. This register is useful for detecting proximity on a small number of sensor inputs as it allows the user to change averaging and sample times on a limited number of sensor inputs and still maintain normal functionality in the fully active state. Bit 7 - AVG_SUM - Determines whether the active sensor inputs will average the programmed number of samples or whether they will accumulate for the programmed number of samples. • ‘0’ - (default) - The active sensor input delta count values will be based on the average of the programmed number of samples when compared against the threshold. • ‘1’ - The active sensor input delta count values will be based on the summation of the programmed number of samples when compared against the threshold. This bit should only be set when performing proximity detection as TABLE 6-34: CSX_BN_TH BIT DECODE CS_BN_TH[1:0] Percent Threshold Setting 1 0 0 0 25% 0 1 37.5% (default) 1 0 50% 1 1 62.5% TABLE 6-35: STANDBY CHANNEL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 40h R/W Standby Channel - - CS6_ STBY CS5_ STBY CS4_ STBY CS3_ STBY CS2_ STBY CS1_ STBY 00h TABLE 6-36: STANDBY CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 41h R/W Standby Configuration AVG_ SUM STBY_AVG[2:0] STBY_SAMP_ TIME[1:0] STBY_CY_TIME [1:0] 39h CAP1126 DS00001623B-page 46  2015 Microchip Technology Inc. a physical touch will overflow the delta count registers and may result in false readings. Bits 6 - 4 - STBY_AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-37. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. Bit 3-2 - STBY SAMP_TIME[1:0] - Determines the time to take a single sample when the device is in Standby as shown in Table 6-38. Bits 1 - 0 - STBY_CY_TIME[2:0] - Determines the overall cycle time for all measured channels during standby operation as shown in Table 6-39. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The STBY_AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. TABLE 6-37: STBY_AVG BIT DECODE STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-38: STBY_SAMP_TIME BIT DECODE STBY_SAMP_TIME[1:0] Sampling Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-39: STBY_CY_TIME BIT DECODE STBY_CY_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms  2015 Microchip Technology Inc. DS00001623B-page 47 CAP1126 6.22 Standby Sensitivity Register The Standby Sensitivity register controls the sensitivity for sensor inputs that are active in Standby. Bits 2 - 0 - STBY_SENSE[2:0] - Controls the sensitivity for sensor inputs that are active in Standby. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta C corresponding to a “lighter” touch. These settings are more sensitive to noise however and a noisy environment may flag more false touches than higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). 6.23 Standby Threshold Register The Standby Threshold register stores the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. 6.24 Sensor Input Base Count Registers TABLE 6-40: STANDBY SENSITIVITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 42h R/W Standby Sensitivity - - - - - STBY_SENSE[2:0] 02h TABLE 6-41: STBY_SENSE BIT DECODE STBY_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-42: STANDBY THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 43h R/W Standby Threshold - 64 32 16 8 4 2 1 40h TABLE 6-43: SENSOR INPUT BASE COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 50h R Sensor Input 1 Base Count 128 64 32 16 8 4 2 1 C8h CAP1126 DS00001623B-page 48  2015 Microchip Technology Inc. The Sensor Input Base Count registers store the calibrated “Not Touched” input value from the capacitive touch sensor inputs. These registers are periodically updated by the re-calibration routine. The routine uses an internal adder to add the current count value for each reading to the sum of the previous readings until sample size has been reached. At this point, the upper 16 bits are taken and used as the Sensor Input Base Count. The internal adder is then reset and the re-calibration routine continues. The data presented is determined by the BASE_SHIFT[3:0] bits (see Section 6.5). 6.25 LED Output Type Register The LED Output Type register controls the type of output for the LED pins. Each pin is controlled by a single bit. Refer to application note 21.4 CAP1126Family LED Configuration Options for more information about implementing LEDs. Bit 1 - LED2_OT - Determines the output type of the LED2 pin. • ‘0’ (default) - The LED2 pin is an open-drain output with an external pull-up resistor. When the appropriate pin is set to the “active” state (logic ‘1’), the pin will be driven low. Conversely, when the pin is set to the “inactive” state (logic ‘0’), then the pin will be left in a High Z state and pulled high via an external pull-up resistor. • ‘1’ - The LED2 pin is a push-pull output. When driving a logic ‘1’, the pin is driven high. When driving a logic ‘0’, the pin is driven low. Bit 0 - LED1_OT - Determines the output type of the LED1 pin. 6.26 Sensor Input LED Linking Register The Sensor Input LED Linking register controls whether a capacitive touch sensor input is linked to an LED output. If the corresponding bit is set, then the appropriate LED output will change states defined by the LED Behavior controls (see Section 6.31) in response to the capacitive touch sensor input. Bit 1 - CS2_LED2 - Links the LED2 output to a detected touch on the CS2 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. • ‘0’ (default) - The LED 2 output is not associated with the CS2 input. If a touch is detected on the CS2 input, the LED will not automatically be actuated. The LED is enabled and controlled via the LED Output Control register (see Section 6.28) and the LED Behavior registers (see Section 6.31). 51h R Sensor Input 2 Base Count 128 64 32 16 8 4 2 1 C8h 52h R Sensor Input 3 Base Count 128 64 32 16 8 4 2 1 C8h 53h R Sensor Input 4 Base Count 128 64 32 16 8 4 2 1 C8h 54h R Sensor Input 5 Base Count 128 64 32 16 8 4 2 1 C8h 55h R Sensor Input 6 Base Count 128 64 32 16 8 4 2 1 C8h TABLE 6-44: LED OUTPUT TYPE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 71h R/W LED Output Type ----- - LED2_ OT LED1_ OT 00h TABLE 6-45: SENSOR INPUT LED LINKING REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 72h R/W Sensor Input LED Linking - - - - - - CS2_ LED2 CS1_ LED1 00h TABLE 6-43: SENSOR INPUT BASE COUNT REGISTERS (CONTINUED) ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default  2015 Microchip Technology Inc. DS00001623B-page 49 CAP1126 • ‘1’ - The LED 2 output is associated with the CS2 input. If a touch is detected on the CS2 input, the LED will be actuated and behave as defined in Table 6-52. Bit 0 - CS1_LED1 - Links the LED1 output to a detected touch on the CS1 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. 6.27 LED Polarity Register The LED Polarity register controls the logical polarity of the LED outputs. When these bits are set or cleared, the corresponding LED Mirror controls are also set or cleared (unless the BLK_POL_MIR bit is set - see Section 6.6, "Configuration Registers"). Table 6-48, "LED Polarity Behavior" shows the interaction between the polarity controls, output controls, and relative brightness. APPLICATION NOTE: The polarity controls determine the final LED pin drive. A touch on a linked capacitive touch sensor input is treated in the same way as the LED Output Control bit being set to a logic ‘1’. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’ then the LED will be on and that the CAP1126 LED pin is sinking the LED current. Conversely, if the LED pin is driven to a logic ‘1’, the LED will be off and there is no current flow. See Figure 5-1, "System Diagram for CAP1126". APPLICATION NOTE: This application note applies when the LED polarity is inverted (LEDx_POL = ‘0’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘0’ state in. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven low (i.e. maximum % of time that the LED is on) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven low (i.e. minimum % of time that the LED is on). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at the minimum duty cycle setting. Breathe operations will ramp the duty cycle from the minimum duty cycle to the maximum duty cycle. APPLICATION NOTE: This application note applies when the LED polarity is non-inverted (LEDx_POL = ‘1’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘1’ state. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven high (i.e. maximum % of time that the LED is off) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven high (i.e. minimum % of time that the LED is off). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at 100 minus the minimum duty cycle setting. Breathe operations will ramp the duty cycle from 100 minus the minimum duty cycle to 100 minus the maximum duty cycle. APPLICATION NOTE: The LED Mirror controls (see Section 6.30, "LED Mirror Control Register") work with the polarity controls with respect to LED brightness but will not have a direct effect on the output pin drive. Bit 1 - LED2_POL - Determines the polarity of the LED2 output. • ‘0’ (default) - The LED2 output is inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘0’. • ‘1’ - The LED2 output is non-inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘1’ or left in the high-z state as determined by its output type. Bit 0 - LED1_POL - Determines the polarity of the LED1 output. TABLE 6-46: LED POLARITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 73h R/W LED Polarity - - - - - - LED2_ POL LED1_ POL 00h CAP1126 DS00001623B-page 50  2015 Microchip Technology Inc. 6.28 LED Output Control Register The LED Output Control Register controls the output state of the LED pins that are not linked to sensor inputs. The LED Polarity Control Register will determine the non actuated state of the LED pins. The actuated LED behavior is determined by the LED behavior controls (see Section 6.31, "LED Behavior Register"). Table 6-48 shows the interaction between the polarity controls, output controls, and relative brightness. Bit 1 - LED2_DR - Determines whether LED2 output is driven high or low. • ‘0’ (default) - The LED2 output is driven at the minimum duty cycle or not actuated. • ‘1’ - The LED2 output is High Z or driven at the maximum duty cycle or actuated. Bit 0 - LED1_DR - Determines whether LED1 output is driven high or low. TABLE 6-47: LED OUTPUT CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 74h R/W LED Output Control --- - -- LED2_ DR LED1_ DR 00h Note: If an LED is linked to a sensor input in the Sensor Input LED Linking Register (Section 6.26, "Sensor Input LED Linking Register"), the corresponding bit in the LED Output Control Register is ignored (i.e. a linked LED cannot be host controlled). TABLE 6-48: LED POLARITY BEHAVIOR LED Output Control Register or Touch Polarity Max Duty Min Duty Brightness LED Appearance 0 inverted (‘0’) not used minimum % of time that the LED is on (logic 0) maximum brightness at min duty cycle on at min duty cycle 1 inverted (‘0’) maximum % of time that the LED is on (logic 0) minimum % of time that the LED is on (logic 0) maximum brightness at max duty cycle. Brightness ramps from min duty cycle to max duty cycle according to LED behavior 0 non-inverted (‘1’) not used minimum % of time that the LED is off (logic 1) maximum brightness at 100 minus min duty cycle. on at 100 - min duty cycle 1 non-inverted (‘1’) maximum % of time that the LED is off (logic 1) minimum % of time that the LED is off (logic 1) For Direct behavior, maximum brightness is 100 minus max duty cycle. When breathing, max brightness is 100 minus min duty cycle. Brightness ramps from 100 - min duty cycle to 100 - max duty cycle. according to LED behavior  2015 Microchip Technology Inc. DS00001623B-page 51 CAP1126 6.29 Linked LED Transition Control Register The Linked LED Transition Control register controls the LED drive when the LED is linked to a capacitive touch sensor input. These controls work in conjunction with the INV_LINK_TRAN bit (see Section 6.6.2, "Configuration 2 - 44h") to create smooth transitions from host control to linked LEDs. Bit 1 - LED2_LTRAN - Determines the transition effect when LED2 is linked to CS2. • ‘0’ (default) - When the LED output control bit for LED2 is ‘1’, and then LED2 is linked to CS2 and no touch is detected, the LED will change states. • ‘1’ - If the INV_LINK_TRAN bit is ‘1’, when the LED output control bit for CS2 is ‘1’, and then CS2 is linked to LED2 and no touch is detected, the LED will not change states. In addition, the LED state will change when the sensor pad is touched. If the INV_LINK_TRAN bit is ‘0’, when the LED output control bit for CS2 is ‘1’, and then CS2 is linked to LED2 and no touch is detected, the LED will not change states. However, the LED state will not change when the sensor pad is touched. APPLICATION NOTE: If the LED behavior is not “Direct” and the INV_LINK_TRAN bit it ‘0’, the LED will not perform as expected when the LED2_LTRAN bit is set to ‘1’. Therefore, if breathe and pulse behaviors are used, set the INV_LINK_TRAN bit to ‘1’. Bit 0 - LED1_LTRAN - Determines the transition effect when LED1 is linked to CS1. 6.30 LED Mirror Control Register The LED Mirror Control Registers determine the meaning of duty cycle settings when polarity is non-inverted for each LED channel. When the polarity bit is set to ‘1’ (non-inverted), to obtain correct steps for LED ramping, pulse, and breathe behaviors, the min and max duty cycles need to be relative to 100%, rather than the default, which is relative to 0%. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’, the LED will be on and the CAP1126 LED pin is sinking the LED current. When the polarity bit is set to ‘1’, it is considered non-inverted. For systems using the opposite LED configuration, mirror controls would apply when the polarity bit is ‘0’. These bits are changed automatically if the corresponding LED Polarity bit is changed (unless the BLK_POL_MIR bit is set - see Section 6.6). Bit 1 - LED2_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. • ‘0’ (default) - The duty cycle settings are determined relative to 0% and are determined directly with the settings. • ‘1’ - The duty cycle settings are determined relative to 100%. Bit 0 - LED1_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. 6.31 LED Behavior Register TABLE 6-49: LINKED LED TRANSITION CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 77h R/W Linked LED Transition Control - ----- LED2_ LTRAN LED1_ LTRAN 00h TABLE 6-50: LED MIRROR CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 79h R/W LED Mirror Control ------ LED2_ MIR _ EN LED1_ MIR _ EN 00h TABLE 6-51: LED BEHAVIOR REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 81h R/W LED Behavior 1 - - - - LED2_CTL[1:0] LED1_CTL[1:0] 00h CAP1126 DS00001623B-page 52  2015 Microchip Technology Inc. The LED Behavior register controls the operation of LEDs. Each LED pin is controlled by a 2-bit field and the behavior is determined by whether the LED is linked to a capacitive touch sensor input or not. If the corresponding LED output is linked to a capacitive touch sensor input, the appropriate behavior will be enabled / disabled based on touches and releases. If the LED output is not associated with a capacitive touch sensor input, the appropriate behavior will be enabled / disabled by the LED Output Control register. If the respective LEDx_DR bit is set to a logic ‘1’, this will be associated as a “touch”, and if the LEDx_DR bit is set to a logic ‘0’, this will be associated as a “release”. Table 6-52, "LEDx_CTL Bit Decode" shows the behavior triggers. The defined behavior will activate when the Start Trigger is met and will stop when the Stop Trigger is met. Note the behavior of the Breathe Hold and Pulse Release option. The LED Polarity Control register will determine the non actuated state of the LED outputs (see Section 6.27, "LED Polarity Register"). APPLICATION NOTE: If an LED is not linked to a capacitive touch sensor input and is breathing (via the Breathe or Pulse behaviors), it must be unactuated and then re-actuated before changes to behavior are processed. For example, if the LED output is breathing and the Maximum duty cycle is changed, this change will not take effect until the LED output control register is set to ‘0’ and then re-set to ‘1’. APPLICATION NOTE: If an LED is not linked to the capacitive touch sensor input and configured to operate using Pulse 1 Behavior, then the circuitry will only be actuated when the corresponding output control bit is set. It will not check the bit condition until the Pulse 1 behavior is finished. The device will not remember if the bit was cleared and reset while it was actuated. APPLICATION NOTE: If an LED is actuated and not linked and the desired LED behavior is changed, this new behavior will take effect immediately; however, the first instance of the changed behavior may act incorrectly (e.g. if changed from Direct to Pulse 1, the LED output may ‘breathe’ 4 times and then end at minimum duty cycle). LED Behaviors will operate normally once the LED has been un-actuated and then re-actuated. APPLICATION NOTE: If an LED is actuated and it is switched from linked to a capacitive touch sensor input to unlinked (or vice versa), the LED will respond to the new command source immediately if the behavior was Direct or Breathe. For Pulse behaviors, it will complete the behavior already in progress. For example, if a linked LED was actuated by a touch and the control is changed so that it is unlinked, it will check the status of the corresponding LED Output Control bit. If that bit is ‘0’, then the LED will behave as if a release was detected. Likewise, if an unlinked LED was actuated by the LED Output Control register and the control is changed so that it is linked and no touch is detected, then the LED will behave as if a release was detected. Bits 3 - 2 - LED2_CTL[1:0] - Determines the behavior of LED2 as shown in Table 6-52. Bits 1 - 0 - LED1_CTL[1:0] - Determines the behavior of LED1 as shown in Table 6-52.  2015 Microchip Technology Inc. DS00001623B-page 53 CAP1126 APPLICATION NOTE: The PWM frequency is determined based on the selected LED behavior, the programmed breathe period, and the programmed min and max duty cycles. For the Direct behavior mode, the PWM frequency is calculated based on the programmed Rise and Fall times. If these are set at 0, then the maximum PWM frequency will be used based on the programmed duty cycle settings. 6.32 LED Pulse 1 Period Register The LED Pulse Period 1 register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 01b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms (24 x 32ms = 768ms). The total range is from 32ms to 4.064 seconds as shown in Table 6-54 with the default being 1024ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. Bit 7 - ST_TRIG - Determines the start trigger for the LED Pulse behavior. • ‘0’ (default) - The LED will Pulse when a touch is detected or the drive bit is set. • ‘1’ - The LED will Pulse when a release is detected or the drive bit is cleared. TABLE 6-52: LEDX_CTL BIT DECODE LEDx_CTL [1:0] Operation Description Start TRigger Stop Trigger 1 0 0 0 Direct The LED is driven to the programmed state (active or inactive). See Figure 6-7 Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared 0 1 Pulse 1 The LED will “Pulse” a programmed number of times. During each “Pulse” the LED will breathe up to the maximum brightness and back down to the minimum brightness so that the total “Pulse” period matches the programmed value. Touch or Release Detected or LED Output Control bit set or cleared (see Section 6.32) n/a 1 0 Pulse 2 The LED will “Pulse” when the start trigger is detected. When the stop trigger is detected, it will “Pulse” a programmable number of times then return to its minimum brightness. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared 1 1 Breathe The LED will breathe. It will be driven with a duty cycle that ramps up from the programmed minimum duty cycle (default 0%) to the programmed maximum duty cycle duty cycle (default 100%) and then back down. Each ramp takes up 50% of the programmed period. The total period of each “breath” is determined by the LED Breathe Period controls - see Section 6.34. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared TABLE 6-53: LED PULSE 1 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 84h R/W LED Pulse 1 Period ST_ TRIG P1_ PER6 P1_ PER5 P1_ PER4 P1_ PER3 P1_ PER2 P1_ PER1 P1_ PER0 20h CAP1126 DS00001623B-page 54  2015 Microchip Technology Inc. The Pulse 1 operation is shown in Figure 6-1 when the LED output is configured for non-inverted polarity (LEDx_POL = 1) and in Figure 6-2 for inverted polarity (LEDx_POL = 0). . FIGURE 6-1: Pulse 1 Behavior with Non-Inverted Polarity FIGURE 6-2: Pulse 1 Behavior with Inverted Polarity TABLE 6-54: LED PULSE / BREATHE PERIOD EXAMPLE Setting (HEX) Setting (Decimal) Total Breathe / Pulse Period (MS) 00h 0 32 01h 1 32 02h 2 64 03h 3 96 . . . . . . . . . 7Dh 125 4000 Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected (100% - Pulse 1 Max Duty Cycle) * Brightness X pulses after touch or after release Pulse 1 Period (P1_PER) (100% - Pulse 1 Min Duty Cycle) * Brightness LED Brightness Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected Pulse 1 Min Duty Cycle * Brightness X pulses after touch or after release Pulse Period (P1_PER) Pulse 1 Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001623B-page 55 CAP1126 6.33 LED Pulse 2 Period Register The LED Pulse 2 Period register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 10b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 640ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. The Pulse 2 Behavior is shown in Figure 6-3 for non-inverted polarity (LEDx_POL = 1) and in Figure 6-4 for inverted polarity (LEDx_POL = 0). 7Eh 126 4032 7Fh 127 4064 TABLE 6-55: LED PULSE 2 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 85h R/W LED Pulse 2 Period - P2_ PER6 P2_ PER5 P2_ PER4 P2_ PER3 P2_ PER2 P2_ PER1 P2_ PER0 14h FIGURE 6-3: Pulse 2 Behavior with Non-Inverted Polarity TABLE 6-54: LED PULSE / BREATHE PERIOD EXAMPLE (CONTINUED) Setting (HEX) Setting (Decimal) Total Breathe / Pulse Period (MS) . . . Normal – untouched operation Normal – untouched operation Touch Detected (100% - Pulse 2 Min Duty Cycle) * Brightness (100% - Pulse 2 Max Duty Cycle) * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness CAP1126 DS00001623B-page 56  2015 Microchip Technology Inc. 6.34 LED Breathe Period Register The LED Breathe Period register determines the overall period of a breathe operation as determined by the LED_CTL registers (see Table 6-52 - setting 11b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 2976ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. 6.35 LED Configuration Register The LED Configuration register controls general LED behavior as well as the number of pulses that are sent for the PULSE LED output behavior. Bit 6 - RAMP_ALERT - Determines whether the device will assert the ALERT# pin when LEDs actuated by the LED Output Control register bits have finished their respective behaviors. Interrupts will only be generated if the LED activity is generated by writing the LED Output Control registers. Any LED activity associated with touch detection will not cause an interrupt to be generated when the LED behavior has been finished. • ‘0’ (default) - The ALERT# pin will not be asserted when LEDs actuated by the LED Output Control register have finished their programmed behaviors. • ‘1’ - The ALERT# pin will be asserted whenever any LED that is actuated by the LED Output Control register has finished its programmed behavior. Bits 5 - 3 - PULSE2_CNT[2:0] - Determines the number of pulses used for the Pulse 2 behavior as shown in Table 6-58. Bits 2 - 0 - PULSE1_CNT[2:0] - Determines the number of pulses used for the Pulse 1 behavior as shown in Table 6-58. FIGURE 6-4: Pulse 2 Behavior with Inverted Polarity TABLE 6-56: LED BREATHE PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 86h R/W LED Breathe Period - BR_ PER6 BR_ PER5 BR_ PER4 BR_ PER3 BR_ PER2 BR_ PER1 BR_ PER0 5Dh TABLE 6-57: LED CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 88h R/W LED Config - RAMP_ ALERT PULSE2_CNT[2:0] PULSE1_CNT[2:0] 04h Normal – untouched operation Normal – untouched operation Touch Detected Pulse 2 Max Duty Cycle * Brightness Pulse 2 Min Duty Cycle * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness . . .  2015 Microchip Technology Inc. DS00001623B-page 57 CAP1126 6.36 LED Duty Cycle Registers The LED Duty Cycle registers determine the minimum and maximum duty cycle settings used for the LED for each LED behavior. These settings affect the brightness of the LED when it is fully off and fully on. The LED driver duty cycle will ramp up from the minimum duty cycle to the maximum duty cycle and back down again. APPLICATION NOTE: When operating in Direct behavior mode, changes to the Duty Cycle settings will be applied immediately. When operating in Breathe, Pulse 1, or Pulse 2 modes, the LED must be unactuated and then re-actuated before changes to behavior are processed. Bits 7 - 4 - X_MAX_DUTY[3:0] - Determines the maximum PWM duty cycle for the LED drivers as shown in Table 6-60. Bits 3 - 0 - X_MIN_DUTY[3:0] - Determines the minimum PWM duty cycle for the LED drivers as shown in Table 6-60. TABLE 6-58: PULSEX_CNT DECODE PULSEX_CNT[2:0] Number of Breaths 21 0 0 0 0 1 (default - Pulse 2) 00 1 2 01 0 3 01 1 4 1 0 0 5 (default - Pulse 1) 10 1 6 11 0 7 11 1 8 TABLE 6-59: LED DUTY CYCLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 90h R/W LED Pulse 1 Duty Cycle P1_MAX_DUTY[3:0] P1_MIN_DUTY[3:0] F0h 91h R/W LED Pulse 2 Duty Cycle P2_MAX_DUTY[3:0] P2_MIN_DUTY[3:0] F0h 92h R/W LED Breathe Duty Cycle BR_MAX_DUTY[3:0] BR_MIN_DUTY[3:0] F0h 93h R/W Direct Duty Cycle DR_MAX_DUTY[3:0] DR_MIN_DUTY[3:0] F0h TABLE 6-60: LED DUTY CYCLE DECODE x_MAX/MIN_Duty [3:0] Maximum Duty Cycle Minimum Duty Cycle 3 21 0 0 0 0 0 7% 0% 0 0 0 1 9% 7% 0 0 1 0 11% 9% 0 0 1 1 14% 11% 0 1 0 0 17% 14% 0 1 0 1 20% 17% 0 1 1 0 23% 20% 0 1 1 1 26% 23% 1 0 0 0 30% 26% 1 0 0 1 35% 30% 1 0 1 0 40% 35% CAP1126 DS00001623B-page 58  2015 Microchip Technology Inc. 6.37 LED Direct Ramp Rates Register The LED Direct Ramp Rates register control the rising and falling edge time of an LED that is configured to operate in Direct behavior mode. The rising edge time corresponds to the amount of time the LED takes to transition from its minimum duty cycle to its maximum duty cycle. Conversely, the falling edge time corresponds to the amount of time that the LED takes to transition from its maximum duty cycle to its minimum duty cycle. Bits 5 - 3 - RISE_RATE[2:0] - Determines the rising edge time of an LED when it transitions from its minimum drive state to its maximum drive state as shown in Table 6-62. Bits 2 - 0 - FALL_RATE[2:0] - Determines the falling edge time of an LED when it transitions from its maximum drive state to its minimum drive state as shown in Table 6-62. 6.38 LED Off Delay Register The LED Off Delay register determines the amount of time that an LED remains at its maximum duty cycle (or minimum as determined by the polarity controls) before it starts to ramp down. If the LED is operating in Breathe mode, this delay is applied at the top of each “breath”. If the LED is operating in the Direct mode, this delay is applied when the LED is unactuated. 1 0 1 1 46% 40% 1 1 0 0 53% 46% 1 1 0 1 63% 53% 1 1 1 0 77% 63% 1 1 1 1 100% 77% TABLE 6-61: LED DIRECT RAMP RATES REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 94h R/W LED Direct Ramp Rates - - RISE_RATE[2:0] FALL_RATE[2:0] 00h TABLE 6-62: RISE / FALL RATE DECODE RISE_RATE/ FALL_RATE/ Bit Decode Rise / Fall Time (TRISE / TFALL) 21 0 00 0 0 0 0 1 250ms 0 1 0 500ms 0 1 1 750ms 1 0 0 1s 1 0 1 1.25s 1 1 0 1.5s 1 1 1 2s TABLE 6-63: LED OFF DELAY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 95h R/W LED Off Delay Register - BR_OFF_DLY[2:0] DIR_OFF_DLY[3:0] 00h TABLE 6-60: LED DUTY CYCLE DECODE (CONTINUED) x_MAX/MIN_Duty [3:0] Maximum Duty Cycle Minimum Duty Cycle 3 21 0  2015 Microchip Technology Inc. DS00001623B-page 59 CAP1126 Bits 6 - 4 - BR_OFF_DLY[2:0] - Determines the Breathe behavior mode off delay, which is the amount of time an LED in Breathe behavior mode remains inactive after it finishes a breathe pulse (ramp on and ramp off), as shown in Figure 6- 5 (non-inverted polarity LEDx_POL = 1) and Figure 6-6 (inverted polarity LEDx_POL = 0). Available settings are shown in Table 6-64. FIGURE 6-5: Breathe Behavior with Non-Inverted Polarity FIGURE 6-6: Breathe Behavior with Inverted Polarity LED Actuated 100% - Breathe Max Min Cycle * Brightness 100% - Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER) LED Actuated Breathe Max Duty Cycle * Brightness Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER) CAP1126 DS00001623B-page 60  2015 Microchip Technology Inc. Bits 3 - 0 - DIR_OFF_DLY[3:0] - Determines the turn-off delay, as shown in Table 6-65, for all LEDs that are configured to operate in Direct behavior mode. The Direct behavior operation is determined by the combination of programmed Rise Time, Fall Time, Min and Max Duty cycles, Off Delay, and polarity. Figure 6-7 shows the behavior for non-inverted polarity (LEDx_POL = 1) while Figure 6- 8 shows the behavior for inverted polarity (LEDx_POL = 0). TABLE 6-64: BREATHE OFF DELAY SETTINGS BR_OFF_DLY [2:0] OFF Delay 2 10 0 0 0 0 (default) 0 0 1 0.25s 0 1 0 0.5s 0 1 1 0.75s 1 0 0 1.0s 1 0 1 1.25s 1 1 0 1.5s 1 1 1 2.0s FIGURE 6-7: Direct Behavior for Non-Inverted Polarity FIGURE 6-8: Direct Behavior for Inverted Polarity Normal – untouched operation RISE_RATE Setting (tRISE) (100% - Max Duty Cycle) * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation (100% - Min Duty Cycle) * Brightness LED Brightness Normal – untouched operation RISE_RATE Setting (tRISE) Min Duty Cycle * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001623B-page 61 CAP1126 6.39 Sensor Input Calibration Registers The Sensor Input Calibration registers hold the 10-bit value that represents the last calibration value. TABLE 6-65: OFF DELAY DECODE OFF Delay[3:0] Bit Decode OFF Delay (tOFF_DLY) 32 1 0 00 0 0 0 0 0 0 1 250ms 0 0 1 0 500ms 0 0 1 1 750ms 0 1 0 0 1s 0 1 0 1 1.25s 0 1 1 0 1.5s 0 1 1 1 2s 1 0 0 0 2.5s 1 0 0 1 3.0s 1 0 1 0 3.5s 1 0 1 1 4.0s 1 1 0 0 4.5s All others 5.0s TABLE 6-66: SENSOR INPUT CALIBRATION REGISTERS ADDR Register R/W B7 B6 B5 B4 B3 B2 B1 B0 Default B1h Sensor Input 1 Calibration R CAL1_9 CAL1_8 CAL1_7 CAL1_6 CAL1_5 CAL1_4 CAL1_3 CAL1_2 00h B2h Sensor Input 2 Calibration R CAL2_9 CAL2_8 CAL2_7 CAL2_6 CAL2_5 CAL2_4 CAL2_3 CAL2_2 00h B3h Sensor Input 3 Calibration R CAL3_9 CAL3_8 CAL3_7 CAL3_6 CAL3_5 CAL3_4 CAL3_3 CAL3_2 00h B4h Sensor Input 4 Calibration R CAL4_9 CAL4_8 CAL4_7 CAL4_6 CAL4_5 CAL4_4 CAL4_3 CAL4_2 00h B5h Sensor Input 5 Calibration R CAL5_9 CAL5_8 CAL5_7 CAL5_6 CAL5_5 CAL5_4 CAL5_3 CAL5_2 00h B6h Sensor Input 6 Calibration R CAL6_9 CAL6_8 CAL6_7 CAL6_6 CAL6_5 CAL6_4 CAL6_3 CAL6_2 00h B9h Sensor Input Calibration LSB 1 R CAL4_1 CAL4_0 CAL3_1 CAL3_0 CAL2_1 CAL2_0 CAL1_1 CAL1_0 00h BAh Sensor Input Calibration LSB 2 R - - - - CAL6_1 CAL6_0 CAL5_1 CAL5_0 00h CAP1126 DS00001623B-page 62  2015 Microchip Technology Inc. 6.40 Product ID Register The Product ID register stores a unique 8-bit value that identifies the device. 6.41 Manufacturer ID Register The Vendor ID register stores an 8-bit value that represents Microchip. 6.42 Revision Register The Revision register stores an 8-bit value that represents the part revision. TABLE 6-67: PRODUCT ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FDh R Product ID 0 1 0 1 0 0 1 1 53h TABLE 6-68: VENDOR ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FEh R Manufacturer ID 0 1 0 1 1 1 0 1 5Dh TABLE 6-69: REVISION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FFh R Revision 1 0 0 0 0 0 1 1 83h  2015 Microchip Technology Inc. DS00001623B-page 63 CAP1126 7.0 PACKAGE INFORMATION 7.1 CAP1126 Package Drawings Note: For the most current package drawings, see the Microchip Packaging Specification at: http://www.microchip.com/packaging. FIGURE 7-1: 16-Pin QFN 4mm x 4mm Package Drawing CAP1126 DS00001623B-page 64  2015 Microchip Technology Inc. FIGURE 7-2: 16-Pin QFN 4mm x 4mm Package Dimensions FIGURE 7-3: 16-Pin QFN 4mm x 4mm PCB Footprint  2015 Microchip Technology Inc. DS00001623B-page 65 CAP1126 7.2 Package Marking FIGURE 7-4: CAP1126 Package Markings C 1 26 - 1 Y WWN N N A RCC e3 TOP BOTTOM Bottom marking not allowed PB-FREE/GREEN SYMBOL (Matte Sn) Lines 1-3: Line 4: Center Horizontal Alignment Left Horizontal Alignment PIN 1 0.41 3x 0.56 Line 1 – SMSC Logo without circled R symbol Line 2 – Device ID, Version Line 3 – Year, Week, Alphanumeric Traceability Code Line 4 – Revision, Country Code 1 CAP1126 DS00001623B-page 66  2015 Microchip Technology Inc. APPENDIX A: DEVICE DELTA A.1 Delta from CAP1026 to CAP1126 1. Updated circuitry to improve power supply rejection. 2. Updated LED driver duty cycle decode values to have more distribution at lower values - closer to a logarithmic curve. See Table 6-60, "LED Duty Cycle Decode". 3. Updated bug that breathe periods were not correct above 2.6s. This includes rise / fall time decodes above 1.5s. 4. Added filtering on RESET pin to prevent errant resets. 5. Updated controls so that the RESET pin assertion places the device into the lowest power state available and causes an interrupt when released. See Section 5.2, "RESET Pin". 6. Added 1 bit to the LED Off Delay register (see Section 6.38, "LED Off Delay Register") to extend times from 2s to 5s in 0.5s intervals. 7. Breathe behavior modified. A breathe off delay control was added to the LED Off Delay Register (see Section 6.38, "LED Off Delay Register") so the LEDs can be configured to remain inactive between breathes. 8. Added controls for the LED transition effects when linking LEDs to capacitive sensor inputs. See Section 6.29, "Linked LED Transition Control Register". 9. Added controls to “mirror” the LED duty cycle outputs so that when polarity changes, the LED brightness levels look right. These bits are automatically set when polarity is set. Added control to break this auto-set behavior. See Section 6.30, "LED Mirror Control Register". 10. Added Multiple Touch Pattern detection circuitry. See Section 6.15, "Multiple Touch Pattern Configuration Register". 11. Added General Status register to flag Multiple touches, Multiple Touch Pattern issues and general touch detections. See Section 6.2, "Status Registers". 12. Added bits 6 and 5 to the Recalibration Configuration register (2Fh - see Section 6.17, "Recalibration Configuration Register"). These bits control whether the accumulation of intermediate data and the consecutive negative delta counts counter are cleared when the noise status bit is set. 13. Added Configuration 2 register for LED linking controls, noise detection controls, and control to interrupt on press but not on release. Added control to change alert pin polarity. See Section 6.6, "Configuration Registers". 14. Updated Deep Sleep behavior so that device does not clear DSLEEP bit on received communications but will wake to communicate. 15. Changed PWM frequency for LED drivers. The PWM frequency was derived from the programmed breathe period and duty cycle settings and it ranged from ~4Hz to ~8000 Hz. The PWM frequency has been updated to be a fixed value of ~2000Hz. 16. Register delta: Table A.1 Register Delta From CAP1026 to CAP1126 Address Register Delta Delta Default 00h Page 31 Changed - Main Status / Control added bits 7-6 to control gain 00h 02h Page 32 New - General Status new register to store MTP, MULT, LED, RESET, and general TOUCH bits 00h 44h Page 35 New - Configuration 2 new register to control alert polarity, LED touch linking behavior, LED output behavior, and noise detection, and interrupt on release 40h 24h Page 38 Changed - Averaging Control updated register bits - moved SAMP_AVG[2:0] bits and added SAMP_- TIME bit 1. Default changed 39h 2Bh Page 41 New - Multiple Touch Pattern Configuration new register for Multiple Touch Pattern configuration - enable and threshold settings 80h  2015 Microchip Technology Inc. DS00001623B-page 67 CAP1126 2Dh Page 42 New - Multiple Touch Pattern Register new register for Multiple Touch Pattern detection circuitry - pattern or number of sensor inputs 3Fh 2Fh Page 43 Changed - Recalibration Configuration updated register - updated CAL_CFG bit decode to add a 128 averages setting and removed highest time setting. Default changed. Added bit 6 NO_CLR_INTD and bit 5 NO_CLR_NEG. 8Ah 38h Page 44 Changed - Sensor Input Noise Threshold updated register bits - removed bits 7 - 3 and consolidated all controls into bits 1 - 0. These bits will set the noise threshold for all channels. Default changed 01h 39h Removed - Noise Threshold Register 2 removed register n/a 41h Page 45 Changed - Standby Configuration updated register bits - moved STBY_AVG[2:0] bits and added STBY_- TIME bit 1. Default changed 39h 77h Page 51 New - Linked LED Transition Control new register to control transition effect when LED linked to sensor inputs 00h 79h Page 51 New - LED Mirror Control new register to control LED output mirroring for brightness control when polarity changed 00h 90h Page 57 Changed - LED Pulse 1 Duty Cycle changed bit decode to be more logarithmic F0h 91h Page 57 Changed - LED Pulse 2 Duty Cycle changed bit decode to be more logarithmic F0h 92h Page 57 Changed - LED Breathe Duty Cycle changed bit decode to be more logarithmic F0h 93h Page 57 Changed - LED Direct Duty Cycle changed bit decode to be more logarithmic F0h 95h Added controls - LED Off Delay Added bits 6-4 BR_OFF_DLY[2:0] Added bit 3 DIR_OFF_DLY[3] 00h FDh Page 62 Changed - Product ID Changed bit decode for CAP1126 53h Table A.1 Register Delta From CAP1026 to CAP1126 (continued) Address Register Delta Delta Default CAP1126 DS00001623B-page 68  2015 Microchip Technology Inc. APPENDIX B: DATA SHEET REVISION HISTORY Revision Section/Figure/Entry Correction DS00001623B (02-09-15) Features, Table 2-1, Table 2- 2, "Pin Types", Section 5.0, "General Description" References to BC-Link Interface, BC_DATA, BC_- CLK, BC-IRQ#, BC-Link bus have been removed Application Note under Table 2-6 [BC-Link] hidden in data sheet Table 3-2, "Electrical Specifications" BC-Link Timing Section hidden in data sheet Table 4-1 Protocol Used for 68K Pull Down Resistor changed from “BC-Link Communications” to “Reserved” Section 4.2.2, "SMBus Address and RD / WR Bit" Replaced “client address” with “slave address” in this section. Section 4.2.4, SMBus ACK and NACK Bits, Section 4.2.5, SMBus Stop Bit,Section 4.2.7, SMBus and I2C Compatibility Replaced “client” with “slave” in these sections. Table 4-4, "Read Byte Protocol" Heading changed from “Client Address” to “Slave Address” Table 6-1 Register Name for Register Address 77h changed from “LED Linked Transition Control” to “Linked LED Transition Control” Section 6.30 changed CS2 to LED2 Section 7.7 Package Marking Updated package drawing Appendix A: Device Delta changed 2Dh to 2Fh in item #12 Product Identification System Removed BC-Link references REV A REV A replaces previous SMSC version Rev. 1.32 (01-05-12) Rev. 1.32 (01-05-12) Table 3-2, "Electrical Specifications" Added conditions for tHD:DAT. Section 4.2.7, "SMBus and I2C Compatibility" Renamed from “SMBus and I2C Compliance.” First paragraph, added last sentence: “For information on using the CAP1188 in an I2C system, refer to SMSC AN 14.0 SMSC Dedicated Slave Devices in I 2C Systems.” Added: CAP1188 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. Section 6.4, "Sensor Input Delta Count Registers" Changed negative value cap from FFh to 80h. Rev. 1.31 (08-18-11) Section 4.3.3, "SMBus Send Byte" Added an application note: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Section 4.3.4, "SMBus Receive Byte" Added an application note: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Rev. 1.3 (05-18-11) Section 6.42, "Revision Register" Updated revision ID from 82h to 83h. Rev. 1.2 (02-10-11) Section A.8, "Delta from Rev B (Mask B0) to Rev C (Mask B1)" Added. Cover Corrected block diagram. ALERT#/BC_IRQ# is an output, not an input.  2015 Microchip Technology Inc. DS00001623B-page 69 CAP1126 Table 2-1, "Pin Description for CAP1126" Changed value in “Unused Connection” column for the ADDR_COMM pin from “Connect to Ground” to “n/a“. Table 3-2, "Electrical Specifications" PSR improvements made in functional revision B. Changed PSR spec from ±100 typ and ±200 max counts / V to ±3 and ±10 counts / V. Conditions updated. Section 5.5.2, "Recalibrating Sensor Inputs" Added more detail with subheadings for each type of recalibration. Section 6.6, "Configuration Registers" Added bit 5 BLK_PWR_CTRL to the Configuration 2 Register 44h. The TIMEOUT bit is set to ‘1’ by default for functional revision B and is set to ‘0’ by default for functional revision C. Section 6.42, "Revision Register" Updated revision ID in register FFh from 81h to 82h. Rev. 1.1 (11-17-10) Document Updated for functional revision B. See Section A.7, "Delta from Rev A (Mask A0) to Rev B (Mask B0)". Cover Added to General Description: “includes circuitry and support for enhanced sensor proximity detection.” Added the following Features: Calibrates for Parasitic Capacitance Analog Filtering for System Noise Sources Press and Hold feature for Volume-like Applications Table 3-2, "Electrical Specifications" Conditions for Power Supply Rejection modified adding the following: Sampling time = 2.56ms Averaging = 1 Negative Delta Counts = Disabled All other parameters default Section 6.11, "Calibration Activate Register" Updated register description to indicate which re-calibration routine is used. Section 6.14, "Multiple Touch Configuration Register" Updated register description to indicate what will happen. Table 6-34, "CSx_BN_TH Bit Decode" Table heading changed from “Threshold Divide Setting” to “Percent Threshold Setting”. Rev. 1.0 (06-14-10) Initial release Revision Section/Figure/Entry Correction CAP1126 DS00001623B-page 70  2015 Microchip Technology Inc. THE MICROCHIP WEB SITE Microchip provides online support via our WWW site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support  2015 Microchip Technology Inc. DS00001623B-page 71 CAP1126 PRODUCT IDENTIFICATION SYSTEM To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. PART NO. [X] - 1 - XXX - [X](1) l l l l Device Temperature Package Tape and Reel Range Option Example: Note 1: Tape and Reel identifier only appears in the catalog part number description. This identifier is used for ordering purposes and is not printed on the device package. Check with your Microchip Sales Office for package availability with the Tape and Reel option. Device: CAP1126 Temperature Range: Blank = 0°C to +85°C (Extended Commercial) Package: AP = QFN Tape and Reel Option: TR = Tape and Reel(1) CAP1126-1-AP-TR 16-pin QFN 4mm x 4mm (RoHS compliant) Six capacitive touch sensor inputs, Two LED drivers, Dedicated Wake, Reset, SMBus / BC-Link / SPI interfaces Reel size is 4,000 pieces CAP1126 DS00001623B-page 72  2015 Microchip Technology Inc. Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication 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. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, flexPWR, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANCheck, MediaLB, MOST, MOST logo, MPLAB, OptoLyzer, PIC, PICSTART, PIC32 logo, RightTouch, SpyNIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. The Embedded Control Solutions Company and mTouch are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, ECAN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, KleerNet, KleerNet logo, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, RightTouch logo, REAL ICE, SQI, Serial Quad I/O, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2015, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 9781632770332 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 ==  2015 Microchip Technology Inc. DS00001623B-page 73 AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Canada - Toronto Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2943-5100 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Dongguan Tel: 86-769-8702-9880 China - Hangzhou Tel: 86-571-8792-8115 Fax: 86-571-8792-8116 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 ASIA/PACIFIC China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7828 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 EUROPE Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Dusseldorf Tel: 49-2129-3766400 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Pforzheim Tel: 49-7231-424750 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Venice Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Poland - Warsaw Tel: 48-22-3325737 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service 01/27/15  2015 Microchip Technology Inc. DS00001622B-page 1 General Description The CAP1128, which incorporates RightTouch® technology, is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains eight (8) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1128 also contains two (2) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. The CAP1128 includes Multiple Pattern Touch recognition that allows the user to select a specific set of buttons to be touched simultaneously. If this pattern is detected, then a status bit is set and an interrupt generated. Additionally, the CAP1128 includes circuitry and support for enhanced sensor proximity detection. The CAP1128 offers multiple power states operating at low quiescent currents. In the Standby state of operation, one or more capacitive touch sensor inputs are active and all LEDs may be used. If a touch is detected, it will wake the system using the WAKE/SPI_MOSI pin. Deep Sleep is the lowest power state available, drawing 5uA (typical) of current. In this state, no sensor inputs are active. Driving the WAKE/SPI_MOSI pin or communications will wake the device. Applications • Desktop and Notebook PCs • LCD Monitors • Consumer Electronics • Appliances Features • Eight (8) Capacitive Touch Sensor Inputs - Programmable sensitivity - Automatic recalibration - Individual thresholds for each button • Proximity Detection • Multiple Button Pattern Detection • Calibrates for Parasitic Capacitance • Analog Filtering for System Noise Sources • Press and Hold feature for Volume-like Applications • Multiple Communication Interfaces - SMBus / I2C compliant interface - SPI communications - Pin selectable communications protocol and multiple slave addresses (SMBus / I2C only) • Low Power Operation - 5uA quiescent current in Deep Sleep - 50uA quiescent current in Standby (1 sensor input monitored) - Samples one or more channels in Standby • Two (2) LED Driver Outputs - Open Drain or Push-Pull - Programmable blink, breathe, and dimness controls - Can be linked to Capacitive Touch Sensor inputs • Dedicated Wake output flags touches in low power state • System RESET pin • Available in 20-pin 4mm x 4mm QFN RoHS compliant package CAP1128 8 Channel Capacitive Touch Sensor with 2 LED Drivers CAP1128 DS00001622B-page 2  2015 Microchip Technology Inc. TO OUR VALUED CUSTOMERS It is our intention to provide our valued customers with the best documentation possible to ensure successful use of your Microchip products. To this end, we will continue to improve our publications to better suit your needs. Our publications will be refined and enhanced as new volumes and updates are introduced. If you have any questions or comments regarding this publication, please contact the Marketing Communications Department via E-mail at docerrors@microchip.com. We welcome your feedback. Most Current Data Sheet To obtain the most up-to-date version of this data sheet, please register at our Worldwide Web site at: http://www.microchip.com You can determine the version of a data sheet by examining its literature number found on the bottom outside corner of any page. The last character of the literature number is the version number, (e.g., DS30000000A is version A of document DS30000000). Errata An errata sheet, describing minor operational differences from the data sheet and recommended workarounds, may exist for current devices. As device/documentation issues become known to us, we will publish an errata sheet. The errata will specify the revision of silicon and revision of document to which it applies. To determine if an errata sheet exists for a particular device, please check with one of the following: • Microchip’s Worldwide Web site; http://www.microchip.com • Your local Microchip sales office (see last page) When contacting a sales office, please specify which device, revision of silicon and data sheet (include -literature number) you are using. Customer Notification System Register on our web site at www.microchip.com to receive the most current information on all of our products.  2015 Microchip Technology Inc. DS00001622B-page 3 CAP1128 Table of Contents 1.0 Block Diagram ................................................................................................................................................................................. 4 2.0 Pin Description ................................................................................................................................................................................ 5 3.0 Electrical Specifications .................................................................................................................................................................. 9 4.0 Communications ........................................................................................................................................................................... 12 5.0 General Description ...................................................................................................................................................................... 23 6.0 Register Description ...................................................................................................................................................................... 29 7.0 Package Information ..................................................................................................................................................................... 67 Appendix A: Device Delta ................................................................................................................................................................... 72 Appendix B: Data Sheet Revision History ........................................................................................................................................... 74 The Microchip Web Site ...................................................................................................................................................................... 76 Customer Change Notification Service ............................................................................................................................................... 76 Customer Support ............................................................................................................................................................................... 76 Product Identification System ............................................................................................................................................................. 77 CAP1128 DS00001622B-page 4  2015 Microchip Technology Inc. 1.0 BLOCK DIAGRAM SMBus / BC-Link / SPI Slave Protocol SMCLK/ BC_CLK / SPI_CLK SMDATA / BC_DATA/ SPI_MSIO / SPI_MISO VDD GND ALERT# / BC_IRQ# Capacitive Touch Sensing Algorithm LED1 CS1 CS2 CS3 CS4 CS5 CS6 LED Driver, Breathe, and Dimness control WAKE / SPI_MOSI CS7 CS8 RESET ADDR_COMM SPI_CS# LED2  2015 Microchip Technology Inc. DS00001622B-page 5 CAP1128 2.0 PIN DESCRIPTION FIGURE 2-1: CAP1128 Pin Diagram (20-Pin QFN) TABLE 2-1: PIN DESCRIPTION FOR CAP1128 Pin Number Pin Name Pin Function Pin Type Unused Connection 1 SPI_CS# Active low chip-select for SPI bus DI (5V) Connect to Ground 2 WAKE / SPI_- MOSI WAKE - Active high wake / interrupt output Standby power state - requires pull-down resistor DO Pull-down WAKE - Active high wake input - requires pull-down Resistor resistor Deep Sleep power state DI SPI_MOSI - SPI Master-Out-Slave-In port when used in normal mode DI (5V) Connect to Ground 1 2 3 4 15 14 13 12 20 19 18 17 6 7 8 9 GND ALERT# / BC_IRQ# WAKE / SPI_MOSI SPI_CS# SMCLK / BC_CLK / SPI_CLK SMDAT / BC_DATA / SPI_MSIO / SPI_MISO CS7 RESET CS5 CS6 5 10 11 16 VDD CS1 CS2 CS4 CS8 CS3 N/C* LED1 LED2 ADDR_COMM CAP1128 20 pin QFN N/C* *N/C pins must be connected to ground CAP1128 DS00001622B-page 6  2015 Microchip Technology Inc. 3 SMDATA / SPI_MSIO / SPI_MISO SMDATA - Bi-directional, open-drain SMBus data - requires pull-up resistor DIOD (5V) n/a SPI_MSIO - SPI Master-Slave-In-Out bidirectional port when used in bi-directional mode DIO SPI_MISO - SPI Master-In-Slave-Out port when used in normal mode DO 4 SMCLK / SPI_- CLK SMCLK - SMBus clock input - requires pull-up resistor DI (5V) SPI_CLK - SPI clock input DI (5V) n/a 5 N/C Not Internally Connected n/a Connect to Ground 6 LED1 Open drain LED 1 driver (default) OD (5V) Connect to Ground Push-pull LED 1 driver DO leave open or connect to Ground 7 LED2 Open drain LED 2 driver (default) OD (5V) Connect to Ground Push-pull LED 2 driver DO leave open or connect to Ground 8 N/C Not Internally Connected n/a Connect to Ground 9 RESET Active high soft reset for system - resets all registers to default values. If not used, connect to ground. DI (5V) Connect to Ground 10 ALERT# ALERT# - Active low alert / interrupt output for SMBus alert or SPI interrupt OD (5V) Connect to Ground ALERT# - Active high push-pull alert / interrupt output for SMBus alert or SPI interrupt DO leave open 11 ADDR_COMM Address / communications select pin - pull-down resistor determines address / communications mechanism AI n/a 12 CS8 Capacitive Touch Sensor Input 8 AIO Connect to Ground 13 CS7 Capacitive Touch Sensor Input 7 AIO Connect to Ground 14 CS6 Capacitive Touch Sensor Input 6 AIO Connect to Ground 15 CS5 Capacitive Touch Sensor Input 5 AIO Connect to Ground 16 CS4 Capacitive Touch Sensor Input 4 AIO Connect to Ground TABLE 2-1: PIN DESCRIPTION FOR CAP1128 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection  2015 Microchip Technology Inc. DS00001622B-page 7 CAP1128 APPLICATION NOTE: When the ALERT# pinis configured as an active low output, it will be open drain. When it is configured as an active high output, it will be push-pull. APPLICATION NOTE: For the 5V tolerant pins that have a pull-up resistor, the pull-up voltage must not exceed 3.6V when the CAP1128 is unpowered. APPLICATION NOTE: The SPI_CS# pin should be grounded when SMBus, or I2C,communications are used. The pin types are described in Table 2-2. All pins labeled with (5V) are 5V tolerant. 17 CS3 Capacitive Touch Sensor Input 3 AIO Connect to Ground 18 CS2 Capacitive Touch Sensor Input 2 AIO Connect to Ground 19 CS1 Capacitive Touch Sensor Input 1 AIO Connect to Ground 20 VDD Positive Power supply Power n/a Bottom Pad GND Ground Power n/a TABLE 2-2: PIN TYPES Pin Type Description Power This pin is used to supply power or ground to the device. DI Digital Input - This pin is used as a digital input. This pin is 5V tolerant. AIO Analog Input / Output -This pin is used as an I/O for analog signals. DIOD Digital Input / Open Drain Output - This pin is used as a digital I/O. When it is used as an output, it is open drain and requires a pull-up resistor. This pin is 5V tolerant. OD Open Drain Digital Output - This pin is used as a digital output. It is open drain and requires a pull-up resistor. This pin is 5V tolerant. DO Push-pull Digital Output - This pin is used as a digital output and can sink and source current. DIO Push-pull Digital Input / Output - This pin is used as an I/O for digital signals. TABLE 2-1: PIN DESCRIPTION FOR CAP1128 (CONTINUED) Pin Number Pin Name Pin Function Pin Type Unused Connection CAP1128 DS00001622B-page 8  2015 Microchip Technology Inc. 3.0 ELECTRICAL SPECIFICATIONS Note 3-1 Stresses above those listed could cause permanent damage to the device. This is a stress rating only and functional operation of the device at any other condition above those indicated in the operation sections of this specification is not implied. Note 3-2 For the 5V tolerant pins that have a pull-up resistor, the voltage difference between V5VT_PIN and VDD must never exceed 3.6V. Note 3-3 The Package Power Dissipation specification assumes a recommended thermal via design consisting of a 3x3 matrix of 0.3mm (12mil) vias at 1.0mm pitch connected to the ground plane with a 2.5 x 2.5mm thermal landing. Note 3-4 Junction to Ambient (θJA) is dependent on the design of the thermal vias. Without thermal vias and a thermal landing, the θJA is approximately 60°C/W including localized PCB temperature increase. TABLE 3-1: ABSOLUTE MAXIMUM RATINGS Voltage on 5V tolerant pins (V5VT_PIN) -0.3 to 5.5 V Voltage on 5V tolerant pins (|V5VT_PIN - VDD|) Note 3-2 0 to 3.6 V Voltage on VDD pin -0.3 to 4 V Voltage on any other pin to GND -0.3 to VDD + 0.3 V Package Power Dissipation up to TA = 85°C for 20 pin QFN (see Note 3-3) 0.9 W Junction to Ambient (θJA) (see Note 3-4) 58 °C/W Operating Ambient Temperature Range -40 to 125 °C Storage Temperature Range -55 to 150 °C ESD Rating, All Pins, HBM 8000 V  2015 Microchip Technology Inc. DS00001622B-page 9 CAP1128 TABLE 3-2: ELECTRICAL SPECIFICATIONS VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions DC Power Supply Voltage VDD 3.0 3.3 3.6 V Supply Current ISTBY 120 170 uA Standby state active 1 sensor input monitored No LEDs active Default conditions (8 avg, 70ms cycle time) ISTBY 50 uA Standby state active 1 sensor input monitored No LEDs active 1 avg, 140ms cycle time, IDSLEEP 5 15 uA Deep Sleep state active LEDs at 100% or 0% Duty Cycle No communications TA < 40°C 3.135 < VDD < 3.465V IDD 500 600 uA Capacitive Sensing Active No LEDs active Capacitive Touch Sensor Inputs Maximum Base Capacitance CBASE 50 pF Pad untouched Minimum Detectable Capacitive Shift ΔCTOUCH 20 fF Pad touched - default conditions (1 avg, 35ms cycle time, 1x sensitivity) Recommended Cap Shift ΔCTOUCH 0.1 2 pF Pad touched - Not tested Power Supply Rejection PSR ±3 ±10 counts / V Untouched Current Counts Base Capacitance 5pF - 50pF Maximum sensitivity Negative Delta Counts disabled All other parameters default Timing RESET Pin Delay tRST_DLY 10 ms Time to communications ready tCOMM_DLY 15 ms Time to first conversion ready tCONV_DLY 170 200 ms LED Drivers Duty Cycle DUTYLED 0 100 % Programmable Drive Frequency fLED 2 kHz Sinking Current ISINK 24 mA VOL = 0.4 Sourcing Current ISOURCE 24 mA VOH = VDD - 0.4 Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered I/O Pins Output Low Voltage VOL 0.4 V ISINK_IO = 8mA Output High Voltage VOH VDD - 0.4 V ISOURCE_IO = 8mA CAP1128 DS00001622B-page 10  2015 Microchip Technology Inc. Note 3-5 The ALERT pin will not glitch high or low at power up if connected to VDD or another voltage. Note 3-6 The SMCLK and SMDATA pins will not glitch low at power up if connected to VDD or another voltage. Input High Voltage VIH 2.0 V Input Low Voltage VIL 0.8 V Leakage Current ILEAK ±5 uA powered or unpowered TA < 85°C pull-up voltage < 3.6V if unpowered RESET Pin Release to conversion ready tRESET 170 200 ms SMBus Timing Input Capacitance CIN 5 pF Clock Frequency fSMB 10 400 kHz Spike Suppression tSP 50 ns Bus Free Time Stop to Start tBUF 1.3 us Start Setup Time tSU:STA 0.6 us Start Hold Time tHD:STA 0.6 us Stop Setup Time tSU:STO 0.6 us Data Hold Time tHD:DAT 0 us When transmitting to the master Data Hold Time tHD:DAT 0.3 us When receiving from the master Data Setup Time tSU:DAT 0.6 us Clock Low Period tLOW 1.3 us Clock High Period tHIGH 0.6 us Clock / Data Fall Time tFALL 300 ns Min = 20+0.1CLOAD ns Clock / Data Rise Time tRISE 300 ns Min = 20+0.1CLOAD ns Capacitive Load CLOAD 400 pF per bus line SPI Timing Clock Period tP 250 ns Clock Low Period tLOW 0.4 x tP 0.6 x tP ns Clock High Period tHIGH 0.4 x tP 0.6 x tP ns Clock Rise / Fall time tRISE / tFALL 0.1 x tP ns Data Output Delay tD:CLK 10 ns Data Setup Time tSU:DAT 20 ns Data Hold Time tHD:DAT 20 ns SPI_CS# to SPI_CLK setup time tSU:CS 0 ns Wake Time tWAKE 10 20 us SPI_CS# asserted to CLK assert TABLE 3-2: ELECTRICAL SPECIFICATIONS (CONTINUED) VDD = 3V to 3.6V, TA = 0°C to 85°C, all typical values at TA = 27°C unless otherwise noted. Characteristic Symbol Min Typ Max Unit Conditions  2015 Microchip Technology Inc. DS00001622B-page 11 CAP1128 4.0 COMMUNICATIONS 4.1 Communications The CAP1128communicates using the 2-wire SMBus or I2C bus, the 2-wire proprietary BC-Link, or the SPI bus. If the proprietary BC-Link protocol is required for your application, please contact your Microchip representative for ordering instructions. Regardless of communication mechanism, the device functionality remains unchanged. The communications mechanism as well as the SMBus (or I2C) slave address is determined by the resistor connected between the ADDR_COMM pin and ground as shown in Table 4-1. 4.1.1 SMBUS (I2C) COMMUNICATIONS When configured to communicate via the SMBus, the CAP1128 supports the following protocols: Send Byte, Receive Byte, Read Byte, Write Byte, Read Block, and Write Block. In addition, the device supports I2C formatting for block read and block write protocols. APPLICATION NOTE: For SMBus/I2C communications, the SPI_CS# pin is not used and should be grounded; any data presented to this pin will be ignored. See Section 4.2 and Section 4.3 for more information on the SMBus bus and protocols respectively. 4.1.2 SPI COMMUNICATIONS When configured to communicate via the SPI bus, the CAP1128supports both bi-directional 3-wire and normal 4-wire protocols and uses the SPI_CS# pin to enable communications. APPLICATION NOTE: See Section 4.5 and Section 4.6 for more information on the SPI bus and protocols respectively.Upon power up, the CAP1128 will not respond to any communications for up to 15ms. After this time, full functionality is available. 4.2 System Management Bus The CAP1128 communicates with a host controller, such as an SIO, through the SMBus. The SMBus is a two-wire serial communication protocol between a computer host and its peripheral devices. A detailed timing diagram is shown in Figure 4-1. Stretching of the SMCLK signal is supported; however, the CAP1128 will not stretch the clock signal. TABLE 4-1: ADDR_COMM PIN DECODE Pull-Down Resistor (+/- 5%) Protocol Used SMBus Address GND SPI Communications using Normal 4-wire Protocol Used n/a 56k SPI Communications using BiDirectional 3-wire Protocol Used n/a 68k Reserved n/a 82k SMBus / I2C 0101_100(r/w) 100k SMBus / I2C 0101_011(r/w) 120k SMBus / I2C 0101_010(r/w) 150k SMBus / I2C 0101_001(r/w) VDD SMBus / I2C 0101_000(r/w) CAP1128 DS00001622B-page 12  2015 Microchip Technology Inc. 4.2.1 SMBUS START BIT The SMBus Start bit is defined as a transition of the SMBus Data line from a logic ‘1’ state to a logic ‘0’ state while the SMBus Clock line is in a logic ‘1’ state. 4.2.2 SMBUS ADDRESS AND RD / WR BIT The SMBus Address Byte consists of the 7-bit slave address followed by the RD / WR indicator bit. If this RD / WR bit is a logic ‘0’, then the SMBus Host is writing data to the slave device. If this RD / WR bit is a logic ‘1’, then the SMBus Host is reading data from the slave device. See Table 4-1 for available SMBus addresses. 4.2.3 SMBUS DATA BYTES All SMBus Data bytes are sent most significant bit first and composed of 8-bits of information. 4.2.4 SMBUS ACK AND NACK BITS The SMBus slave will acknowledge all data bytes that it receives. This is done by the slave device pulling the SMBus Data line low after the 8th bit of each byte that is transmitted. This applies to both the Write Byte and Block Write protocols. The Host will NACK (not acknowledge) the last data byte to be received from the slave by holding the SMBus data line high after the 8th data bit has been sent. For the Block Read protocol, the Host will ACK each data byte that it receives except the last data byte. 4.2.5 SMBUS STOP BIT The SMBus Stop bit is defined as a transition of the SMBus Data line from a logic ‘0’ state to a logic ‘1’ state while the SMBus clock line is in a logic ‘1’ state. When the CAP1128 detects an SMBus Stop bit and it has been communicating with the SMBus protocol, it will reset its slave interface and prepare to receive further communications. 4.2.6 SMBUS TIMEOUT The CAP1128 includes an SMBus timeout feature. Following a 30ms period of inactivity on the SMBus where the SMCLK pin is held low, the device will timeout and reset the SMBus interface. The timeout function defaults to disabled. It can be enabled by setting the TIMEOUT bit in the Configuration register (see Section 6.6, "Configuration Registers"). 4.2.7 SMBUS AND I2C COMPATIBILITY The major differences between SMBus and I2C devices are highlighted here. For more information, refer to the SMBus 2.0 and I2C specifications. For information on using the CAP1128 in an I2C system, refer to AN 14.0 Dedicated Slave Devices in I2C Systems. FIGURE 4-1: SMBus Timing Diagram SMDATA SMCLK TLOW TRISE THIGH TFALL TBUF THD:STA P S S - Start Condition P - Stop Condition THD:DAT TSU:DAT TSU:STA THD:STA P TSU:STO S  2015 Microchip Technology Inc. DS00001622B-page 13 CAP1128 1. CAP1128 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. 2. Minimum frequency for SMBus communications is 10kHz. 3. The SMBus slave protocol will reset if the clock is held at a logic ‘0’ for longer than 30ms. This timeout functionality is disabled by default in the CAP1128 and can be enabled by writing to the TIMEOUT bit. I2C does not have a timeout. 4. The SMBus slave protocol will reset if both the clock and data lines are held at a logic ‘1’ for longer than 200µs (idle condition). This function is disabled by default in the CAP1128 and can be enabled by writing to the TIMEOUT bit. I2C does not have an idle condition. 5. I2C devices do not support the Alert Response Address functionality (which is optional for SMBus). 6. I2C devices support block read and write differently. I2C protocol allows for unlimited number of bytes to be sent in either direction. The SMBus protocol requires that an additional data byte indicating number of bytes to read / write is transmitted. The CAP1128 supports I2C formatting only. 4.3 SMBus Protocols The CAP1128 is SMBus 2.0 compatible and supports Write Byte, Read Byte, Send Byte, and Receive Byte as valid protocols as shown below. All of the below protocols use the convention in Table 4-2. 4.3.1 SMBUS WRITE BYTE The Write Byte is used to write one byte of data to a specific register as shown in Table 4-3. 4.3.2 SMBUS READ BYTE The Read Byte protocol is used to read one byte of data from the registers as shown in Table 4-4. 4.3.3 SMBUS SEND BYTE The Send Byte protocol is used to set the internal address register pointer to the correct address location. No data is transferred during the Send Byte protocol as shown in Table 4-5. APPLICATION NOTE: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). TABLE 4-2: PROTOCOL FORMAT Data Sent to Device Data Sent to the HOst Data sent Data sent TABLE 4-3: WRITE BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK Stop 1 ->0 YYYY_YYY 0 0 XXh 0 XXh 0 0 -> 1 TABLE 4-4: READ BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data NACK Stop 1->0 YYYY_YYY 0 0 XXh 0 1 ->0 YYYY_YYY 1 0 XXh 1 0 -> 1 TABLE 4-5: SEND BYTE PROTOCOL Start Slave Address WR ACK Register Address ACK Stop 1 -> 0 YYYY_YYY 0 0 XXh 0 0 -> 1 CAP1128 DS00001622B-page 14  2015 Microchip Technology Inc. 4.3.4 SMBUS RECEIVE BYTE The Receive Byte protocol is used to read data from a register when the internal register address pointer is known to be at the right location (e.g., set via Send Byte). This is used for consecutive reads of the same register as shown in Table 4-6. APPLICATION NOTE: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). 4.4 I2C Protocols The CAP1128 supports I2C Block Write and Block Read. The protocols listed below use the convention in Table 4-2. 4.4.1 BLOCK WRITE The Block Write is used to write multiple data bytes to a group of contiguous registers as shown in Table 4-7. APPLICATION NOTE: When using the Block Write protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.4.2 BLOCK READ The Block Read is used to read multiple data bytes from a group of contiguous registers as shown in Table 4-8. APPLICATION NOTE: When using the Block Read protocol, the internal address pointer will be automatically incremented after every data byte is received. It will wrap from FFh to 00h. 4.5 SPI Interface The SMBus has a predefined packet structure, the SPI does not. The SPI Bus can operate in two modes of operation, normal 4-wire mode and bi-directional 3-wire mode. All SPI commands consist of 8-bit packets sent to a specific slave device (identified by the CS pin). The SPI bus will latch data on the rising edge of the clock and the clock and data both idle high. All commands are supported via both operating modes. The supported commands are: Reset Serial interface, set address pointer, write command and read command. Note that all other codes received during the command phase are ignored and have no effect on the operation of the device. TABLE 4-6: RECEIVE BYTE PROTOCOL Start Slave Address RD ACK Register Data NACK Stop 1 -> 0 YYYY_YYY 1 0 XXh 1 0 -> 1 TABLE 4-7: BLOCK WRITE PROTOCOL Start Slave Address WR ACK Register Address ACK Register Data ACK 1 ->0 YYYY_YYY 0 0 XXh 0 XXh 0 Register Data ACK Register Data ACK . . . Register Data ACK Stop XXh 0 XXh 0 . . . XXh 0 0 -> 1 TABLE 4-8: BLOCK READ PROTOCOL Start Slave Address WR ACK Register Address ACK Start Slave Address RD ACK Register Data 1->0 YYYY_YYY 0 0 XXh 0 1 ->0 YYYY_YYY 1 0 XXh ACK Register Data ACK Register Data ACK Register Data ACK . . . Register Data NACK Stop 0 XXh 0 XXh 0 XXh 0 . . . XXh 1 0 -> 1  2015 Microchip Technology Inc. DS00001622B-page 15 CAP1128 4.5.1 SPI NORMAL MODE The SPI Bus can operate in two modes of operation, normal and bi-directional mode. In the normal mode of operation, there are dedicated input and output data lines. The host communicates by sending a command along the CAP1128 SPI_MOSI data line and reading data on the SPI_MISO data line. Both communications occur simultaneously which allows for larger throughput of data transactions. All basic transfers consist of two 8 bit transactions from the Master device while the slave device is simultaneously sending data at the current address pointer value. Data writes consist of two or more 8-bit transactions. The host sends a specific write command followed by the data to write the address pointer. Data reads consist of one or more 8-bit transactions. The host sends the specific read data command and continues clocking for as many data bytes as it wishes to receive. 4.5.2 SPI BI-DIRECTIONAL MODE In the bi-directional mode of operation, the SPI data signals are combined into the SPI_MSIO line, which is shared for data received by the device and transmitted by the device. The protocol uses a simple handshake and turn around sequence for data communications based on the number of clocks transmitted during each phase. All basic transfers consist of two 8 bit transactions. The first is an 8 bit command phase driven by the Master device. The second is by an 8 bit data phase driven by the Master for writes, and by the CAP1128 for read operations. The auto increment feature of the address pointer allows for successive reads or writes. The address pointer will return to 00h after reaching FFh. 4.5.3 SPI_CS# PIN The SPI Bus is a single master, multiple slave serial bus. Each slave has a dedicated CS pin (chip select) that the master asserts low to identify that the slave is being addressed. There are no formal addressing options. 4.5.4 ADDRESS POINTER All data writes and reads are accessed from the current address pointer. In both Bi-directional mode and Full Duplex mode, the Address pointer is automatically incremented following every read command or every write command. The address pointer will return to 00h after reaching FFh. 4.5.5 SPI TIMEOUT The CAP1128 does not detect any timeout conditions on the SPI bus. FIGURE 4-2: SPI Timing SPI_MSIO or SPI_MOSI or SPI_MISO SPI_CLK tLOW tRISE tHIGH tFALL tD:CLK tHD:DAT tSU:DAT tP  2015 Microchip Technology Inc. DS00001622B-page 16 CAP1128 4.6 Normal SPI Protocols When operating in normal mode, the SPI bus internal address pointer is incremented depending upon which command has been transmitted. Multiple commands may be transmitted sequentually so long as the SPI_CS# pin is asserted low. Figure 4-3 shows an example of this operation. 4.6.1 RESET INTERFACE Resets the Serial interface whenever two successive 7Ah codes are received. Regardless of the current phase of the transaction - command or data, the receipt of the successive reset commands resets the Serial communication interface only. All other functions are not affected by the reset operation. FIGURE 4-3: Example SPI Bus Communication - Normal Mode SPI_CS# SPI_MISO SPI_MOSI SPI Address Pointer SPI Data output buffer Register Address / Data 7Ah XXh (invalid) XXh (invalid) YYh (invalid) 7Ah 7Dh 41h YYh (invalid) 7Eh 66h XXh (invalid) 45h 7Dh 41h AAh (invalid) AAh (invalid) 7Fh 7Fh 55h (invalid) 66h 7Fh AAh 7Dh 43h 40h 78h 7Fh XXh (invalid) 7Fh 56h 40h / 56h 41h / 45h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 45h 40h / 56h 41h / 45h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 42h AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 55h 7Fh AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 41h 66h 42h AAh 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 44h 80h 40h 80h 40h 56h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 43h 55h 7Fh 7Fh 55h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h /78h 80h 45h 43h 46h 78h 40h / 56h 41h / 66h 42h / AAh 43h / 55h 44h / 80h 45h / 43h 46h / 78h 00h XXh Indicates SPI Address pointer incremented  2015 Microchip Technology Inc. DS00001622B-page 17 CAP1128 4.6.2 SET ADDRESS POINTER The Set Address Pointer command sets the Address pointer for subsequent reads and writes of data. The pointer is set on the rising edge of the final data bit. At the same time, the data that is to be read is fetched and loaded into the internal output buffer but is not transmitted. 4.6.3 WRITE DATA The Write Data protocol updates the contents of the register referenced by the address pointer. As the command is processed, the data to be read is fetched and loaded into the internal output buffer but not transmitted. Then, the register is updated with the data to be written. Finally, the address pointer is incremented. FIGURE 4-4: SPI Reset Interface Command - Normal Mode FIGURE 4-5: SPI Set Address Pointer Command - Normal Mode Master SPDOUT SPI_MOSI SPI_CS# SPI_CLK Reset - 7Ah Reset - 7Ah Invalid register data 00h – Internal Data buffer empty SPI_MISO Master Drives Slave Drives ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘1’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘1’ ‘0’ Master SPDOUT SPI_MOSI Register Address SPI_CS# SPI_CLK Set Address Pointer – 7Dh SPI_MISO Unknown, Invalid Data Unknown, Invalid Data Master Drives Slave Drives Address pointer set ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ CAP1128 DS00001622B-page 18  2015 Microchip Technology Inc. 4.6.4 READ DATA The Read Data protocol is used to read data from the device. During the normal mode of operation, while the device is receiving data, the CAP1128 is simultaneously transmitting data to the host. For the Set Address commands and the Write Data commands, this data may be invalid and it is recommended that the Read Data command is used. FIGURE 4-6: SPI Write Command - Normal Mode FIGURE 4-7: SPI Read Command - Normal Mode Master SPDOUT SPI_MOSI Data to Write SPI_CS# SPI_CLK Write Command – 7Eh Unknown, Invalid Data Old Data at Current Address Pointer SPI_MISO Master Drives Slave Drives 1. Data written at current address pointer 2. Address pointer incremented Master SPDOUT SPI_MOSI Master Drives Slave Drives SPI_CLK First Read Command – 7Fh SPI_CS# SPI_MISO Invalid, Unknown Data * ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Subsequent Read Commands – 7F Data at Current Address Pointer Address Pointer Incremented ** ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ * The first read command after any other command will return invalid data for the first byte. Subsequent read commands will return the data at the Current Address Pointer ** The Address Pointer is incremented 8 clocks after the Read Command has been received. Therefore continually sending Read Commands will result in each command reporting new data. Once Read Commands have been finished, the last data byte will be read during the next 8 clocks for any command  2015 Microchip Technology Inc. DS00001622B-page 19 CAP1128 4.7 Bi-Directional SPI Protocols 4.7.1 RESET INTERFACE Resets the Serial interface whenever two successive 7Ah codes are received. Regardless of the current phase of the transaction - command or data, the receipt of the successive reset commands resets the Serial communication interface only. All other functions are not affected by the reset operation. 4.7.2 SET ADDRESS POINTER Sets the address pointer to the register to be accessed by a read or write command. This command overrides the autoincrementing of the address pointer. FIGURE 4-8: SPI Read Command - Normal Mode - Full FIGURE 4-9: SPI Reset Interface Command - Bi-directional Mode Master SPDOUT SPI_MOSI Master Drives Slave Drives SPI_CLK Read Command – 7Fh SPI_CS# Data at previously set register address = current address pointer SPI_MISO ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Data at previously set register address = current address pointer (SPI) XXh 1. Register Read Address updated to Current SPI Read Address pointer 1. Register data loaded into output buffer = data at current address pointer 1. Output buffer transmitted = data at previous address pointer + 1 = current address pointer 1. Register Read Address incremented = current address pointer + 1 1. SPI Read Address Incremented = new current address pointer 2. Register Read Address Incremented = current address pointer +1 Register Data loaded into Output buffer = data at current address pointer + 1 1. Output buffer transmitted = data at current address pointer + 1 2. Flag set to increment SPI Read Address at end of next 8 clocks ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Data at previously set register address = current address pointer (SPI) 1. Register data loaded into output buffer = data at current address pointer 1. Output buffer transmitted = data at previous register address pointer + 1 = current address pointer 1. Output buffer transmitted = data at current address pointer + 1 2. Flag set to increment SPI Read Address at end of next 8 clocks Subsequent Read Commands – 7Fh 1. Register Read Address updated to Current SPI Read Address pointer. 2. Register Read Address incremented = current address pointer +1 – end result = register address pointer doesn’t change Master SPDOUT SPI_MSIO SPI_CS# SPI_CLK Reset - 7Ah Reset - 7Ah ‘0’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ ‘0’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ CAP1128 DS00001622B-page 20  2015 Microchip Technology Inc. 4.7.3 WRITE DATA Writes data value to the register address stored in the address pointer. Performs auto increment of address pointer after the data is loaded into the register. 4.7.4 READ DATA Reads data referenced by the address pointer. Performs auto increment of address pointer after the data is transferred to the Master. FIGURE 4-10: SPI Set Address Pointer Command - Bi-directional Mode FIGURE 4-11: SPI Write Data Command - Bi-directional Mode FIGURE 4-12: SPI Read Data Command - Bi-directional Mode Master SPDOUT SPI_MSIO Register Address SPI_CS# SPI_CLK Set Address Pointer – 7Dh ‘0’ ‘1’ ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ Master SPDOUT SPI_MSIO Register Write Data SPI_CS# SPI_CLK Write Command – 7Eh ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘0’ Master SPDOUT SPI_MSIO Master Drives Slave Drives Indeterminate Register Read Data SPI_CLK Read Command – 7Fh SPI_CS# ‘0’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’ ‘1’  2015 Microchip Technology Inc. DS00001622B-page 21 CAP1128 4.8 BC-Link Interface The BC-Link is a proprietary bus developed to allow communication between a host controller device to a companion device. This device uses this serial bus to read and write registers and for interrupt processing. The interface uses a data port concept, where the base interface has an address register, data register and a control register, defined in the 8051’s SFR space. Refer to documentation for the BC-Link compatible host controller for details on how to access the CAP1128 via the BCLink Interface. CAP1128 DS00001622B-page 22  2015 Microchip Technology Inc. 5.0 GENERAL DESCRIPTION The CAP1128 is a multiple channel Capacitive Touch sensor with multiple power LED drivers. It contains eight (8) individual capacitive touch sensor inputs with programmable sensitivity for use in touch sensor applications. Each sensor input automatically recalibrates to compensate for gradual environmental changes. The CAP1128 also contains two (2) low side (or push-pull) LED drivers that offer full-on / off, variable rate blinking, dimness controls, and breathing. Each of the LED drivers may be linked to one of the sensor inputs to be actuated when a touch is detected. As well, each LED driver may be individually controlled via a host controller. Finally, the device contains a dedicated RESET pin to act as a soft reset by the system. The CAP1128 offers multiple power states. It operates at the lowest quiescent current during its Deep Sleep state. In the low power Standby state, it can monitor one or more channels and respond to communications normally. The device contains a wake pin (WAKE/SPI_MOSI) output to wake the system when a touch is detected in Standby and to wake the device from Deep Sleep. The device communicates with a host controller using the SPI bus, or via SMBus / I2C. The host controller may poll the device for updated information at any time or it may configure the device to flag an interrupt whenever a touch is detected on any sensor pad. A typical system diagram is shown in Figure 5-1.  2015 Microchip Technology Inc. DS00001622B-page 23 CAP1128 FIGURE 5-1: System Diagram for CAP1128 CAP1128 CS6 SMDATA / BC_DATA / SPI_MSIO / SPI_MISO SMCLK / BC_CLK / SPI_CLK VDD Embedded Controller ALERT# / BC_IRQ# CS4 CS2 3.3V – 5V CS5 CS3 CS1 WAKE / SPI_MOSI CS7 CS8 RESET SPI_CS# ADDR_COMM LED1 LED2 3.3V – 5V Touch Button Touch Button Touch Button Touch Button Touch Button Touch Button Touch Button Touch Button CAP1128 DS00001622B-page 24  2015 Microchip Technology Inc. 5.1 Power States The CAP1128 has three operating states depending on the status of the STBY and DSLEEP bits. When the device transitions between power states, previously detected touches (for inactive channels) are cleared and the status bits reset. 1. Fully Active - The device is fully active. It is monitoring all active capacitive sensor inputs and driving all LED channels as defined. 2. Standby - The device is in a lower power state. It will measure a programmable number of channels using the Standby Configuration controls (see Section 6.20 through Section 6.22). Interrupts will still be generated based on the active channels. The device will still respond to communications normally and can be returned to the Fully Active state of operation by clearing the STBY bit. 3. Deep Sleep - The device is in its lowest power state. It is not monitoring any capacitive sensor inputs and not driving any LEDs. All LEDs will be driven to their programmed non-actuated state and no PWM operations will be done. While in Deep Sleep, the device can be awakened by SMBus or SPI communications targeting the device. This will not cause the DSLEEP to be cleared so the device will return to Deep Sleep once all communications have stopped. If the device is not communicating via the 4-wire SPI bus, then during this state of operation, if the WAKE/SPI_MOSI pin is driven high by an external source, the device will clear the DSLEEP bit and return to Fully Active. APPLICATION NOTE: In the Deep Sleep state, the LED output will be either high or low and will not be PWM’d at the min or max duty cycle. 5.2 RESET Pin The RESET pin is an active high reset that is driven from an external source. While it is asserted high, all the internal blocks will be held in reset including the communications protocol used. No capacitive touch sensor inputs will be sampled and the LEDs will not be driven. All configuration settings will be reset to default states and all readings will be cleared. The device will be held in Deep Sleep that can only be removed by driving the RESET pin low. This will cause the RESET status bit to be set to a logic ‘1’ and generate an interrupt. 5.3 WAKE/SPI_MOSI Pin Operation The WAKE / SPI_MOSI pin is a multi-function pin depending on device operation. When the device is configured to communicate using the 4-wire SPI bus, this pin is an input. However, when the CAP1128 is placed in Standby and is not communicating using the 4-wire SPI protocol, the WAKE pin is an active high output. In this condition, the device will assert the WAKE/SPI_MOSI pin when a touch is detected on one of its sampled sensor inputs. The pin will remain asserted until the INT bit has been cleared and then it will be de-asserted. When the CAP1128 is placed in Deep Sleep and it is not communicating using the 4-wire SPI protocol, the WAKE/SPI_- MOSI pin is monitored by the device as an input. If the WAKE/SPI_MOSI pin is driven high by an external source, the CAP1128will clear the DSLEEP bit causing the device to return to Fully Active. When the device is placed in Deep Sleep, this pin is a High-Z input and must have a pull-down resistor to GND for proper operation. 5.4 LED Drivers The CAP1128 contains two (2) LED drivers. Each LED driver can be linked to its respective capacitive touch sensor input or it can be controlled by the host. Each LED driver can be configured to operate in one of the following modes with either push-pull or open drain drive. 1. Direct - The LED is configured to be on or off when the corresponding input stimulus is on or off (or inverted). The brightness of the LED can be programmed from full off to full on (default). Additionally, the LED contains controls to individually configure ramping on, off, and turn-off delay. 2. Pulse 1 - The LED is configured to “Pulse” (transition ON-OFF-ON) a programmable number of times with programmable rate and min / max brightness. This behavior may be actuated when a press is detected or when a release is detected. 3. Pulse 2 - The LED is configured to “Pulse” while actuated and then “Pulse” a programmable number of times with programmable rate and min / max brightness when the sensor pad is released.  2015 Microchip Technology Inc. DS00001622B-page 25 CAP1128 4. Breathe - The LED is configured to transition continuously ON-OFF-ON (i.e. to “Breathe”) with a programmable rate and min / max brightness. When an LED is not linked to a sensor and is actuated by the host, there’s an option to assert the ALERT# pin when the initiated LED behavior has completed. 5.4.1 LINKING LEDS TO CAPACITIVE TOUCH SENSOR INPUTS All LEDs can be linked to the corresponding capacitive touch sensor input so that when the sensor input detects a touch, the corresponding LED will be actuated at one of the programmed responses. 5.5 Capacitive Touch Sensing The CAP1128 contains eight (8) independent capacitive touch sensor inputs. Each sensor input has dynamic range to detect a change of capacitance due to a touch. Additionally, each sensor input can be configured to be automatically and routinely re-calibrated. 5.5.1 SENSING CYCLE Each capacitive touch sensor input has controls to be activated and included in the sensing cycle. When the device is active, it automatically initiates a sensing cycle and repeats the cycle every time it finishes. The cycle polls through each active sensor input starting with CS1 and extending through CS8. As each capacitive touch sensor input is polled, its measurement is compared against a baseline “Not Touched” measurement. If the delta measurement is large enough, a touch is detected and an interrupt is generated. The sensing cycle time is programmable (see Section 6.10, "Averaging and Sampling Configuration Register"). 5.5.2 RECALIBRATING SENSOR INPUTS There are various options for recalibrating the capacitive touch sensor inputs. Recalibration re-sets the Base Count Registers (Section 6.24, "Sensor Input Base Count Registers") which contain the “not touched” values used for touch detection comparisons. APPLICATION NOTE: The device will recalibrate all sensor inputs that were disabled when it transitions from Standby. Likewise, the device will recalibrate all sensor inputs when waking out of Deep Sleep. 5.5.2.1 Manual Recalibration The Calibration Activate Registers (Section 6.11, "Calibration Activate Register") force recalibration of selected sensor inputs. When a bit is set, the corresponding capacitive touch sensor input will be recalibrated (both analog and digital). The bit is automatically cleared once the recalibration routine has finished. 5.5.2.2 Automatic Recalibration Each sensor input is regularly recalibrated at a programmable rate (see Section 6.17, "Recalibration Configuration Register"). By default, the recalibration routine stores the average 64 previous measurements and periodically updates the base “not touched” setting for the capacitive touch sensor input. Note: During this recalibration routine, the sensor inputs will not detect a press for up to 200ms and the Sensor Base Count Register values will be invalid. In addition, any press on the corresponding sensor pads will invalidate the recalibration. Note: Automatic recalibration only works when the delta count is below the active sensor input threshold. It is disabled when a touch is detected. CAP1128 DS00001622B-page 26  2015 Microchip Technology Inc. 5.5.2.3 Negative Delta Count Recalibration It is possible that the device loses sensitivity to a touch. This may happen as a result of a noisy environment, an accidental recalibration during a touch, or other environmental changes. When this occurs, the base untouched sensor input may generate negative delta count values. The NEG_DELTA_CNT bits (see Section 6.17, "Recalibration Configuration Register") can be set to force a recalibration after a specified number of consecutive negative delta readings. 5.5.2.4 Delayed Recalibration It is possible that a “stuck button” occurs when something is placed on a button which causes a touch to be detected for a long period. By setting the MAX_DUR_EN bit (see Section 6.6, "Configuration Registers"), a recalibration can be forced when a touch is held on a button for longer than the duration specified in the MAX_DUR bits (see Section 6.8, "Sensor Input Configuration Register"). 5.5.3 PROXIMITY DETECTION Each sensor input can be configured to detect changes in capacitance due to proximity of a touch. This circuitry detects the change of capacitance that is generated as an object approaches, but does not physically touch, the enabled sensor pad(s). When a sensor input is selected to perform proximity detection, it will be sampled from 1x to 128x per sampling cycle. The larger the number of samples that are taken, the greater the range of proximity detection is available at the cost of an increased overall sampling time. 5.5.4 MULTIPLE TOUCH PATTERN DETECTION The multiple touch pattern (MTP) detection circuitry can be used to detect lid closure or other similar events. An event can be flagged based on either a minimum number of sensor inputs or on specific sensor inputs simultaneously exceeding an MTP threshold or having their Noise Flag Status Register bits set. An interrupt can also be generated. During an MTP event, all touches are blocked (see Section 6.15, "Multiple Touch Pattern Configuration Register"). 5.5.5 LOW FREQUENCY NOISE DETECTION Each sensor input has an EMI noise detector that will sense if low frequency noise is injected onto the input with sufficient power to corrupt the readings. If this occurs, the device will reject the corrupted sample and set the corresponding bit in the Noise Status register to a logic ‘1’. 5.5.6 RF NOISE DETECTION Each sensor input contains an integrated RF noise detector. This block will detect injected RF noise on the CS pin. The detector threshold is dependent upon the noise frequency. If RF noise is detected on a CS line, that sample is removed and not compared against the threshold. 5.6 ALERT# Pin The ALERT# pin is an active low (or active high when configured) output that is driven when an interrupt event is detected. Whenever an interrupt is generated, the INT bit (see Section 6.1, "Main Control Register") is set. The ALERT# pin is cleared when the INT bit is cleared by the user. Additionally, when the INT bit is cleared by the user, status bits are only cleared if no touch is detected. 5.6.1 SENSOR INTERRUPT BEHAVIOR The sensor interrupts are generated in one of two ways: 1. An interrupt is generated when a touch is detected and, as a user selectable option, when a release is detected (by default - see Section 6.6). See Figure 5-3. 2. If the repeat rate is enabled then, so long as the touch is held, another interrupt will be generated based on the programmed repeat rate (see Figure 5-2). Note: During this recalibration, the device will not respond to touches. Note: Delayed recalibration only works when the delta count is above the active sensor input threshold. If enabled, it is invoked when a sensor pad touch is held longer than the MAX_DUR bit setting.  2015 Microchip Technology Inc. DS00001622B-page 27 CAP1128 When the repeat rate is enabled, the device uses an additional control called MPRESS that determines whether a touch is flagged as a simple “touch” or a “press and hold”. The MPRESS[3:0] bits set a minimum press timer. When the button is touched, the timer begins. If the sensor pad is released before the minimum press timer expires, it is flagged as a touch and an interrupt is generated upon release. If the sensor input detects a touch for longer than this timer value, it is flagged as a “press and hold” event. So long as the touch is held, interrupts will be generated at the programmed repeat rate and upon release (if enabled). APPLICATION NOTE: Figure 5-2 and Figure 5-3 show default operation which is to generate an interrupt upon sensor pad release and an active-low ALERT# pin. APPLICATION NOTE: The host may need to poll the device twice to determine that a release has been detected. FIGURE 5-2: Sensor Interrupt Behavior - Repeat Rate Enabled FIGURE 5-3: Sensor Interrupt Behavior - No Repeat Rate Enabled Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Min Press Setting (280ms) Interrupt on Touch Button Repeat Rate (175ms) Button Repeat Rate (175ms) Interrupt on Release (optional) ALERT# pin (active low) Touch Detected INT bit Button Status Write to INT bit Polling Cycle (35ms) Interrupt on Touch Interrupt on Release (optional) ALERT# pin (active low) CAP1128 DS00001622B-page 28  2015 Microchip Technology Inc. 6.0 REGISTER DESCRIPTION The registers shown in Table 6-1 are accessible through the communications protocol. An entry of ‘-’ indicates that the bit is not used and will always read ‘0’. TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER Register Address R/W Register Name Function Default Value Page 00h R/W Main Control Controls general power states and power dissipation 00h Page 31 02h R General Status Stores general status bits 00h Page 32 03h R Sensor Input Status Returns the state of the sampled capacitive touch sensor inputs 00h Page 32 04h R LED Status Stores status bits for LEDs 00h Page 32 0Ah R Noise Flag Status Stores the noise flags for sensor inputs 00h Page 33 10h R Sensor Input 1 Delta Count Stores the delta count for CS1 00h Page 34 11h R Sensor Input 2 Delta Count Stores the delta count for CS2 00h Page 34 12h R Sensor Input 3 Delta Count Stores the delta count for CS3 00h Page 34 13h R Sensor Input 4 Delta Count Stores the delta count for CS4 00h Page 34 14h R Sensor Input 5 Delta Count Stores the delta count for CS5 00h Page 34 15h R Sensor Input 6 Delta Count Stores the delta count for CS6 00h Page 34 16h R Sensor Input 7 Delta Count Stores the delta count for CS7 00h Page 34 17h R Sensor Input 8 Delta Count Stores the delta count for CS8 00h Page 34 1Fh R/W Sensitivity Control Controls the sensitivity of the threshold and delta counts and data scaling of the base counts 2Fh Page 34 20h R/W Configuration Controls general functionality 20h Page 36 21h R/W Sensor Input Enable Controls whether the capacitive touch sensor inputs are sampled FFh Page 37 22h R/W Sensor Input Configuration Controls max duration and auto-repeat delay for sensor inputs operating in the full power state A4h Page 38 23h R/W Sensor Input Configuration 2 Controls the MPRESS controls for all sensor inputs 07h Page 39 24h R/W Averaging and Sampling Config Controls averaging and sampling window 39h Page 39 26h R/W Calibration Activate Forces re-calibration for capacitive touch sensor inputs 00h Page 41 27h R/W Interrupt Enable Enables Interrupts associated with capacitive touch sensor inputs FFh Page 41 28h R/W Repeat Rate Enable Enables repeat rate for all sensor inputs FFh Page 42 2Ah R/W Multiple Touch Configuration Determines the number of simultaneous touches to flag a multiple touch condition 80h Page 42  2015 Microchip Technology Inc. DS00001622B-page 29 CAP1128 2Bh R/W Multiple Touch Pattern Configuration Determines the multiple touch pattern (MTP) configuration 00h Page 43 2Dh R/W Multiple Touch Pattern Determines the pattern or number of sensor inputs used by the MTP circuitry FFh Page 44 2Fh R/W Recalibration Configuration Determines re-calibration timing and sampling window 8Ah Page 44 30h R/W Sensor Input 1 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 1 40h Page 46 31h R/W Sensor Input 2 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 2 40h Page 46 32h R/W Sensor Input 3 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 3 40h Page 46 33h R/W Sensor Input 4 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 4 40h Page 46 34h R/W Sensor Input 5 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 5 40h Page 46 35h R/W Sensor Input 6 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 6 40h Page 46 36h R/W Sensor Input 7 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 7 40h Page 46 37h R/W Sensor Input 8 Threshold Stores the delta count threshold to determine a touch for Capacitive Touch Sensor Input 8 40h 38h R/W Sensor Input Noise Threshold Stores controls for selecting the noise threshold for all sensor inputs 01h Page 46 Standby Configuration Registers 40h R/W Standby Channel Controls which sensor inputs are enabled while in standby 00h Page 47 41h R/W Standby Configuration Controls averaging and cycle time while in standby 39h Page 47 42h R/W Standby Sensitivity Controls sensitivity settings used while in standby 02h Page 48 43h R/W Standby Threshold Stores the touch detection threshold for active sensor inputs in standby 40h Page 49 44h R/W Configuration 2 Stores additional configuration controls for the device 40h Page 36 Base Count Registers 50h R Sensor Input 1 Base Count Stores the reference count value for sensor input 1 C8h Page 49 51h R Sensor Input 2 Base Count Stores the reference count value for sensor input 2 C8h Page 49 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1128 DS00001622B-page 30  2015 Microchip Technology Inc. 52h R Sensor Input 3 Base Count Stores the reference count value for sensor input 3 C8h Page 49 53h R Sensor Input 4 Base Count Stores the reference count value for sensor input 4 C8h Page 49 54h R Sensor Input 5 Base Count Stores the reference count value for sensor input 5 C8h Page 49 55h R Sensor Input 6 Base Count Stores the reference count value for sensor input 6 C8h Page 49 56h R Sensor Input 7 Base Count Stores the reference count value for sensor input 7 C8h Page 49 57h R Sensor Input 8 Base Count Stores the reference count value for sensor input 8 C8h Page 49 LED Controls 71h R/W LED Output Type Controls the output type for the LED outputs 00h Page 50 72h R/W Sensor Input LED Linking Controls linking of sensor inputs to LED channels 00h Page 50 73h R/W LED Polarity Controls the output polarity of LEDs 00h Page 50 74h R/W LED Output Control Controls the output state of the LEDs 00h Page 51 77h R/W Linked LED Transition Control Controls the transition when LEDs are linked to CS channels 00h Page 52 79h R/W LED Mirror Control Controls the mirroring of duty cycles for the LEDs 00h Page 53 81h R/W LED Behavior 1 Controls the behavior and response of LEDs 1 - 2 00h Page 53 84h R/W LED Pulse 1 Period Controls the period of each breathe during a pulse 20h Page 55 85h R/W LED Pulse 2 Period Controls the period of the breathing during breathe and pulse operation 14h Page 56 86h R/W LED Breathe Period Controls the period of an LED breathe operation 5Dh Page 57 88h R/W LED Config Controls LED configuration 04h Page 58 90h R/W LED Pulse 1 Duty Cycle Determines the min and max duty cycle for the pulse operation F0h Page 58 91h R/W LED Pulse 2 Duty Cycle Determines the min and max duty cycle for breathe and pulse operation F0h Page 58 92h R/W LED Breathe Duty Cycle Determines the min and max duty cycle for the breathe operation F0h Page 58 93h R/W LED Direct Duty Cycle Determines the min and max duty cycle for Direct mode LED operation F0h Page 58 94h R/W LED Direct Ramp Rates Determines the rising and falling edge ramp rates of the LEDs 00h Page 59 95h R/W LED Off Delay Determines the off delay for all LED behaviors 00h Page 60 B1h R Sensor Input 1 Calibration Stores the upper 8-bit calibration value for sensor input 1 00h Page 63 B2h R Sensor Input 2 Calibration Stores the upper 8-bit calibration value for sensor input 2 00h Page 63 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page  2015 Microchip Technology Inc. DS00001622B-page 31 CAP1128 During Power-On-Reset (POR), the default values are stored in the registers. A POR is initiated when power is first applied to the part and the voltage on the VDD supply surpasses the POR level as specified in the electrical characteristics. Any reads to undefined registers will return 00h. Writes to undefined registers will not have an effect. When a bit is “set”, this means that the user writes a logic ‘1’ to it. When a bit is “cleared”, this means that the user writes a logic ‘0’ to it. 6.1 Main Control Register The Main Control register controls the primary power state of the device. Bits 7 - 6 - GAIN[1:0] - Controls the gain used by the capacitive touch sensing circuitry. As the gain is increased, the effective sensitivity is likewise increased as a smaller delta capacitance is required to generate the same delta count values. The sensitivity settings may need to be adjusted along with the gain settings such that data overflow does not occur. APPLICATION NOTE: The gain settings apply to both Standby and Active states. B3h R Sensor Input 3 Calibration Stores the upper 8-bit calibration value for sensor input 3 00h Page 63 B4h R Sensor Input 4 Calibration Stores the upper 8-bit calibration value for sensor input 4 00h Page 63 B5h R Sensor Input 5 Calibration Stores the upper 8-bit calibration value for sensor input 5 00h Page 63 B6h R Sensor Input 6 Calibration Stores the upper 8-bit calibration value for sensor input 6 00h Page 63 B7h R Sensor Input 7 Calibration Stores the upper 8-bit calibration value for sensor input 7 00h Page 63 B8h R Sensor Input 8 Calibration Stores the upper 8-bit calibration value for sensor input 8 00h Page 63 B9h R Sensor Input Calibration LSB 1 Stores the 2 LSBs of the calibration value for sensor inputs 1 - 4 00h Page 63 BAh R Sensor Input Calibration LSB 2 Stores the 2 LSBs of the calibration value for sensor inputs 5 - 8 00h Page 63 FDh R Product ID Stores a fixed value that identifies each product 52h Page 63 FEh R Manufacturer ID Stores a fixed value that identifies Microchip 5Dh Page 64 FFh R Revision Stores a fixed value that represents the revision number 83h Page 64 TABLE 6-2: MAIN CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 00h R/W Main Control GAIN[1:0] STBY DSLEEP - - - INT 00h TABLE 6-3: GAIN BIT DECODE GAIN[1:0] Capacitive Touch Sensor Gain 1 0 0 0 1 01 2 TABLE 6-1: REGISTER SET IN HEXADECIMAL ORDER (CONTINUED) Register Address R/W Register Name Function Default Value Page CAP1128 DS00001622B-page 32  2015 Microchip Technology Inc. Bit 5 - STBY - Enables Standby. • ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - Capacitive touch sensor input scanning is limited to the sensor inputs set in the Standby Channel register (see Section 6.20). The status registers will not be cleared until read. LEDs that are linked to capacitive touch sensor inputs will remain linked and active. Sensor inputs that are no longer sampled will flag a release and then remain in a non-touched state. LEDs that are manually controlled will be unaffected. • Bit 4 - DSLEEP - Enables Deep Sleep by deactivating all functions. This bit will be cleared when the WAKE pin is driven high. ‘0’ (default) - Sensor input scanning is active and LEDs are functional. • ‘1’ - All sensor input scanning is disabled. All LEDs are driven to their programmed non-actuated state and no PWM operations will be done. The status registers are automatically cleared and the INT bit is cleared. Bit 0 - INT - Indicates that there is an interrupt. When this bit is set, it asserts the ALERT# pin. If a channel detects a touch and its associated interrupt enable bit is not set to a logic ‘1’, no action is taken. This bit is cleared by writing a logic ‘0’ to it. When this bit is cleared, the ALERT# pin will be deasserted and all status registers will be cleared if the condition has been removed. If the WAKE/SPI_MOSI pin is asserted as a result of a touch detected while in Standby, it will likewise be deasserted when this bit is cleared. Note that the WAKE / SPI_MOSI pin is not driven when communicating via the 4-wire SPI protocol. • ‘0’ - No interrupt pending. • ‘1’ - A touch has been detected on one or more channels and the interrupt has been asserted. 6.2 Status Registers All status bits are cleared when the device enters the Deep Sleep (DSLEEP = ‘1’ - see Section 6.1). 6.2.1 GENERAL STATUS - 02H Bit 4 - LED - Indicates that one or more LEDs have finished their programmed activity. This bit is set if any bit in the LED Status register is set. Bit 3 - RESET - Indicates that the device has come out of reset. This bit is set when the device exits a POR state or when the RESET pin has been deasserted and qualified via the RESET pin filter (see Section 5.2). This bit will cause the INT bit to be set and is cleared when the INT bit is cleared. Bit 2 - MULT - Indicates that the device is blocking detected touches due to the Multiple Touch detection circuitry (see Section 6.14). This bit will not cause the INT bit to be set and hence will not cause an interrupt. Bit 1 - MTP - Indicates that the device has detected a number of sensor inputs that exceed the MTP threshold either via the pattern recognition or via the number of sensor inputs (see Section 6.15). This bit will cause the INT bit to be set if the MTP_ALERT bit is also set. This bit will not be cleared until the condition that caused it to be set has been removed. Bit 0 - TOUCH - Indicates that a touch was detected. This bit is set if any bit in the Sensor Input Status register is set. 10 4 11 8 TABLE 6-4: STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 02h R General Status - - - LED RESET MULT MTP TOUCH 00h 03h R Sensor Input Status CS8 CS7 CS6 CS5 CS4 CS3 CS2 CS1 00h 04h R LED Status - - - - - - LED2_ DN LED1_ DN 00h TABLE 6-3: GAIN BIT DECODE (CONTINUED) GAIN[1:0] Capacitive Touch Sensor Gain 1 0  2015 Microchip Technology Inc. DS00001622B-page 33 CAP1128 6.2.2 SENSOR INPUT STATUS - 03H The Sensor Input Status Register stores status bits that indicate a touch has been detected. A value of ‘0’ in any bit indicates that no touch has been detected. A value of ‘1’ in any bit indicates that a touch has been detected. All bits are cleared when the INT bit is cleared and if a touch on the respective capacitive touch sensor input is no longer present. If a touch is still detected, the bits will not be cleared (but this will not cause the interrupt to be asserted - see Section 6.6). Bit 7 - CS8 - Indicates that a touch was detected on Sensor Input 8. Bit 6 - CS7 - Indicates that a touch was detected on Sensor Input 7. Bit 5 - CS6 - Indicates that a touch was detected on Sensor Input 6. Bit 4 - CS5 - Indicates that a touch was detected on Sensor Input 5. Bit 3 - CS4 - Indicates that a touch was detected on Sensor Input 4. Bit 2 - CS3 - Indicates that a touch was detected on Sensor Input 3. Bit 1 - CS2 - Indicates that a touch was detected on Sensor Input 2. This sensor input can be linked to LED2. Bit 0 - CS1 - Indicates that a touch was detected on Sensor Input 1. This sensor input can be linked to LED1. 6.2.3 LED STATUS - 04H The LED Status Registers indicate when an LED has completed its configured behavior (see Section 6.31, "LED Behavior Register") after being actuated by the host (see Section 6.28, "LED Output Control Register"). These bits are ignored when the LED is linked to a capacitive sensor input. All LED Status bits are cleared when the INT bit is cleared. Bit 1 - LED2_DN - Indicates that LED2 has finished its behavior after being actuated by the host. Bit 0 - LED1_DN - Indicates that LED1 has finished its behavior after being actuated by the host. 6.3 Noise Flag Status Registers The Noise Flag Status registers store status bits that are generated from the analog block if the detected noise is above the operating region of the analog detector or the RF noise detector. These bits indicate that the most recently received data from the sensor input is invalid and should not be used for touch detection. So long as the bit is set for a particular channel, the delta count value is reset to 00h and thus no touch is detected. These bits are not sticky and will be cleared automatically if the analog block does not report a noise error. APPLICATION NOTE: If the MTP detection circuitry is enabled, these bits count as sensor inputs above the MTP threshold (see Section 5.5.4, "Multiple Touch Pattern Detection") even if the corresponding delta count is not. If the corresponding delta count also exceeds the MTP threshold, it is not counted twice. APPLICATION NOTE: Regardless of the state of the Noise Status bits, if low frequency noise is detected on a sensor input, that sample will be discarded unless the DIS_ANA_NOISE bit is set. As well, if RF noise is detected on a sensor input, that sample will be discarded unless the DIS_RF_NOISE bit is set. TABLE 6-5: NOISE FLAG STATUS REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 0Ah R Noise Flag Status CS8_ NOISE CS7_ NOISE CS6_ NOISE CS5_ NOISE CS4_ NOISE CS3_ NOISE CS2_ NOISE CS1_ NOISE 00h CAP1128 DS00001622B-page 34  2015 Microchip Technology Inc. 6.4 Sensor Input Delta Count Registers The Sensor Input Delta Count registers store the delta count that is compared against the threshold used to determine if a touch has been detected. The count value represents a change in input due to the capacitance associated with a touch on one of the sensor inputs and is referenced to a calibrated base “Not Touched” count value. The delta is an instantaneous change and is updated once per sensor input per sensing cycle (see Section 5.5.1, "Sensing Cycle"). The value presented is a standard 2’s complement number. In addition, the value is capped at a value of 7Fh. A reading of 7Fh indicates that the sensitivity settings are too high and should be adjusted accordingly (see Section 6.5). The value is also capped at a negative value of 80h for negative delta counts which may result upon a release. 6.5 Sensitivity Control Register The Sensitivity Control register controls the sensitivity of a touch detection. Bits 6-4 DELTA_SENSE[2:0] - Controls the sensitivity of a touch detection. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta capacitance corresponding to a “lighter” touch. These settings are more sensitive to noise, however, and a noisy environment may flag more false touches with higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely, a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). TABLE 6-6: SENSOR INPUT DELTA COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 10h R Sensor Input 1 Delta Count Sign 64 32 16 8 4 2 1 00h 11h R Sensor Input 2 Delta Count Sign 64 32 16 8 4 2 1 00h 12h R Sensor Input 3 Delta Count Sign 64 32 16 8 4 2 1 00h 13h R Sensor Input 4 Delta Count Sign 64 32 16 8 4 2 1 00h 14h R Sensor Input 5 Delta Count Sign 64 32 16 8 4 2 1 00h 15h R Sensor Input 6 Delta Count Sign 64 32 16 8 4 2 1 00h 16h R Sensor Input 7 Delta Count Sign 64 32 16 8 4 2 1 00h 17h R Sensor Input 8 Delta Count Sign 64 32 16 8 4 2 1 00h TABLE 6-7: SENSITIVITY CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 1Fh R/W Sensitivity Control - DELTA_SENSE[2:0] BASE_SHIFT[3:0] 2Fh  2015 Microchip Technology Inc. DS00001622B-page 35 CAP1128 Bits 3 - 0 - BASE_SHIFT[3:0] - Controls the scaling and data presentation of the Base Count registers. The higher the value of these bits, the larger the range and the lower the resolution of the data presented. The scale factor represents the multiplier to the bit-weighting presented in these register descriptions. APPLICATION NOTE: The BASE_SHIFT[3:0] bits normally do not need to be updated. These settings will not affect touch detection or sensitivity. These bits are sometimes helpful in analyzing the Cap Sensing board performance and stability. TABLE 6-8: DELTA_SENSE BIT DECODE DELTA_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-9: BASE_SHIFT BIT DECODE BASE_SHIFT[3:0] Data Scaling Factor 32 1 0 0 0 0 0 1x 0 0 0 1 2x 0 0 1 0 4x 0 0 1 1 8x 0 1 0 0 16x 0 1 0 1 32x 0 1 1 0 64x 0 1 1 1 128x 1 0 0 0 256x All others 256x (default = 1111b) CAP1128 DS00001622B-page 36  2015 Microchip Technology Inc. 6.6 Configuration Registers The Configuration registers control general global functionality that affects the entire device. 6.6.1 CONFIGURATION - 20H Bit 7 - TIMEOUT - Enables the timeout and idle functionality of the SMBus protocol. • ‘0’ (default for Functional Revision C) - The SMBus timeout and idle functionality are disabled. The SMBus interface will not time out if the clock line is held low. Likewise, it will not reset if both the data and clock lines are held high for longer than 200us. This is used for I2C compliance. • ‘1’ (default for Functional Revision B) - The SMBus timeout and idle functionality are enabled. The SMBus interface will time out if the clock line is held low for longer than 30ms. Likewise, it will reset if both the data and clock lines are held high for longer than 200us. Bit 6 - WAKE_CFG - Configures the operation of the WAKE pin. • ‘0’ (default) - The WAKE pin is not asserted when a touch is detected while the device is in Standby. It will still be used to wake the device from Deep Sleep when driven high. • ‘1’ - The WAKE pin will be asserted high when a touch is detected while the device is in Standby. It will also be used to wake the device from Deep Sleep when driven high. Bit 5 - DIS_DIG_NOISE - Determines whether the digital noise threshold (see Section 6.19, "Sensor Input Noise Threshold Register") is used by the device. Setting this bit disables the feature. • ‘0’ - The digital noise threshold is used. If a delta count value exceeds the noise threshold but does not exceed the touch threshold, the sample is discarded and not used for the automatic re-calibration routine. • ‘1’ (default) - The noise threshold is disabled. Any delta count that is less than the touch threshold is used for the automatic re-calibration routine. Bit 4 - DIS_ANA_NOISE - Determines whether the analog noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If low frequency noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if low frequency noise is detected. Bit 3 - MAX_DUR_EN - Determines whether the maximum duration recalibration is enabled. • ‘0’ (default) - The maximum duration recalibration functionality is disabled. A touch may be held indefinitely and no re-calibration will be performed on any sensor input. • ‘1’ - The maximum duration recalibration functionality is enabled. If a touch is held for longer than the MAX_DUR bit settings, then the re-calibration routine will be restarted (see Section 6.8). 6.6.2 CONFIGURATION 2 - 44H Bit 7 - INV_LINK_TRAN - Determines the behavior of the Linked LED Transition controls (see Section 6.29). • ‘0’ (default) - The Linked LED Transition controls set the min duty cycle equal to the max duty cycle. • ‘1’ - The Linked LED Transition controls will invert the touch signal. For example, a touch signal will be inverted to a non-touched signal. Bit 6 - ALT_POL - Determines the ALERT# pin polarity and behavior. • ‘0’ - The ALERT# pin is active high and push-pull. • ‘1’ (default) - The ALERT# pin is active low and open drain. TABLE 6-10: CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 20h R/W Configuration TIMEOUT WAKE_ CFG DIS_ DIG_ NOISE DIS_ ANA_ NOISE MAX_ DUR_EN - -- A0h (Rev B) 20h (rev C) 44h R/W Configuration 2 INV_LINK_ TRAN ALT_ POL BLK_PWR_ CTRL BLK_POL_ MIR SHOW_ RF_ NOISE DIS_ RF_ NOISE - INT_ REL_n 40h  2015 Microchip Technology Inc. DS00001622B-page 37 CAP1128 Bit 5 - BLK_PWR_CTRL - Determines whether the device will reduce power consumption while waiting between conversion time completion and the end of the polling cycle. • ‘0’ (default) - The device will always power down as much as possible during the time between the end of the last conversion and the end of the polling cycle. • ‘1’ - The device will not power down the Cap Sensor during the time between the end of the last conversion and the end of the polling cycle. Bit 4 - BLK_POL_MIR - Determines whether the LED Mirror Control register bits are linked to the LED Polarity bits. Setting this bit blocks the normal behavior which is to automatically set and clear the LED Mirror Control bits when the LED Polarity bits are set or cleared. • ‘0’ (default) - When the LED Polarity controls are set, the corresponding LED Mirror control is automatically set. Likewise, when the LED Polarity controls are cleared, the corresponding LED Mirror control is also cleared. • ‘1’ - When the LED Polarity controls are set, the corresponding LED Mirror control is not automatically set. Bit 3 - SHOW_RF_NOISE - Determines whether the Noise Status bits will show RF Noise as the only input source. • ‘0’ (default) - The Noise Status registers will show both RF noise and low frequency EMI noise if either is detected on a capacitive touch sensor input. • ‘1’ - The Noise Status registers will only show RF noise if it is detected on a capacitive touch sensor input. EMI noise will still be detected and touches will be blocked normally; however, the status bits will not be updated. Bit 2 - DIS_RF_NOISE - Determines whether the RF noise filter is enabled. Setting this bit disables the feature. • ‘0’ (default) - If RF noise is detected by the analog block, the delta count on the corresponding channel is set to 0. Note that this does not require that Noise Status bits be set. • ‘1’ - A touch is not blocked even if RF noise is detected. Bit 0 - INT_REL_n - Controls the interrupt behavior when a release is detected on a button. • ‘0’ (default) - An interrupt is generated when a press is detected and again when a release is detected and at the repeat rate (if enabled - see Section 6.13). • ‘1’ - An interrupt is generated when a press is detected and at the repeat rate but not when a release is detected. 6.7 Sensor Input Enable Registers The Sensor Input Enable registers determine whether a capacitive touch sensor input is included in the sampling cycle. The length of the sampling cycle is not affected by the number of sensor inputs measured. Bit 7 - CS8_EN - Enables the CS8 input to be included during the sampling cycle. • ‘0’ - The CS8 input is not included in the sampling cycle. • ‘1’ (default) - The CS8 input is included in the sampling cycle. Bit 6 - CS7_EN - Enables the CS7 input to be included during the sampling cycle. Bit 5 - CS6_EN - Enables the CS6 input to be included during the sampling cycle. Bit 4 - CS5_EN - Enables the CS5 input to be included during the sampling cycle. Bit 3 - CS4_EN - Enables the CS4 input to be included during the sampling cycle. Bit 2 - CS3_EN - Enables the CS3 input to be included during the sampling cycle. Bit 1 - CS2_EN - Enables the CS2 input to be included during the sampling cycle. Bit 0 - CS1_EN - Enables the CS1 input to be included during the sampling cycle. TABLE 6-11: SENSOR INPUT ENABLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 21h R/W Sensor Input Enable CS8_EN CS7_EN CS6_EN CS5_EN CS4_EN CS3_EN CS2_EN CS1_EN FFh CAP1128 DS00001622B-page 38  2015 Microchip Technology Inc. 6.8 Sensor Input Configuration Register The Sensor Input Configuration Register controls timings associated with the Capacitive sensor inputs 1 - 8. Bits 7 - 4 - MAX_DUR[3:0] - (default 1010b) - Determines the maximum time that a sensor pad is allowed to be touched until the capacitive touch sensor input is recalibrated, as shown in Table 6-13. Bits 3 - 0 - RPT_RATE[3:0] - (default 0100b) Determines the time duration between interrupt assertions when auto repeat is enabled. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-14. TABLE 6-12: SENSOR INPUT CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 22h R/W Sensor Input Configuration MAX_DUR[3:0] RPT_RATE[3:0] A4h TABLE 6-13: MAX_DUR BIT DECODE MAX_DUR[3:0] Time Before Recalibration 32 1 0 0 0 0 0 560ms 0 0 0 1 840ms 0 0 1 0 1120ms 0 0 1 1 1400ms 0 1 0 0 1680ms 0 1 0 1 2240ms 0 1 1 0 2800ms 1 1 1 3360ms 1 0 0 0 3920ms 1 0 0 1 4480ms 1 0 1 0 5600ms (default) 1 0 1 1 6720ms 1 1 0 0 7840ms 1 1 0 1 8906ms 1 1 1 0 10080ms 1 1 1 1 11200ms TABLE 6-14: RPT_RATE BIT DECODE RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms (default) 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms  2015 Microchip Technology Inc. DS00001622B-page 39 CAP1128 6.9 Sensor Input Configuration 2 Register Bits 3 - 0 - M_PRESS[3:0] - (default 0111b) - Determines the minimum amount of time that sensor inputs configured to use auto repeat must detect a sensor pad touch to detect a “press and hold” event. If the sensor input detects a touch for longer than the M_PRESS[3:0] settings, a “press and hold” event is detected. If a sensor input detects a touch for less than or equal to the M_PRESS[3:0] settings, a touch event is detected. The resolution is 35ms the range is from 35ms to 560ms as shown in Table 6-16. 6.10 Averaging and Sampling Configuration Register 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-15: SENSOR INPUT CONFIGURATION 2 REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 23h R/W Sensor Input Configuration 2 - - - - M_PRESS[3:0] 07h TABLE 6-16: M_PRESS BIT DECODE M_PRESS[3:0] M_PRESS SETTINGS 3 21 0 0 0 0 0 35ms 0 0 0 1 70ms 0 0 1 0 105ms 0 0 1 1 140ms 0 1 0 0 175ms 0 1 0 1 210ms 0 1 1 0 245ms 0 1 1 1 280ms (default) 1 0 0 0 315ms 1 0 0 1 350ms 1 0 1 0 385ms 1 0 1 1 420ms 1 1 0 0 455ms 1 1 0 1 490ms 1 1 1 0 525ms 1 1 1 1 560ms TABLE 6-17: AVERAGING AND SAMPLING CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 24h R/W Averaging and Sampling Config AVG[2:0] SAMP_TIME[1:0] CYCLE_TIME [1:0] 39h TABLE 6-14: RPT_RATE BIT DECODE (CONTINUED) RPT_RATE[3:0] Interrupt Repeat RATE 3 21 0 CAP1128 DS00001622B-page 40  2015 Microchip Technology Inc. The Averaging and Sampling Configuration register controls the number of samples taken and the total sensor input cycle time for all active sensor inputs while the device is functioning in Active state. Bits 6 - 4 - AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-18. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. For example, if CS1, CS2, and CS3 are sampled during the sensor cycle, and the AVG[2:0] bits are set to take 4 samples per channel, then the full sensor cycle will be: CS1, CS1, CS1, CS1, CS2, CS2, CS2, CS2, CS3, CS3, CS3, CS3. Bits 3 - 2 - SAMP_TIME[1:0] - Determines the time to take a single sample as shown in Table 6-19. Bits 1 - 0 - CYCLE_TIME[1:0] - Determines the overall cycle time for all measured channels during normal operation as shown in Table 6-20. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, then the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. TABLE 6-18: AVG BIT DECODE AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-19: SAMP_TIME BIT DECODE SAMP_TIME[1:0] Sample Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-20: CYCLE_TIME BIT DECODE CYCLE_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms  2015 Microchip Technology Inc. DS00001622B-page 41 CAP1128 6.11 Calibration Activate Register The Calibration Activate register forces the respective sensor inputs to be re-calibrated affecting both the analog and digital blocks. During the re-calibration routine, the sensor inputs will not detect a press for up to 600ms and the Sensor Input Base Count register values will be invalid. During this time, any press on the corresponding sensor pads will invalidate the re-calibration. When finished, the CALX[9:0] bits will be updated (see Section 6.39). When the corresponding bit is set, the device will perform the calibration and the bit will be automatically cleared once the re-calibration routine has finished. Bit 7 - CS8_CAL - When set, the CS8 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 6 - CS7_CAL - When set, the CS7 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 5 - CS6_CAL - When set, the CS6 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 4 - CS5_CAL - When set, the CS5 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 3 - CS4_CAL - When set, the CS4 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 2 - CS3_CAL - When set, the CS3 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 1 - CS2_CAL - When set, the CS2 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. Bit 0 - CS1_CAL - When set, the CS1 input is re-calibrated. This bit is automatically cleared once the sensor input has been re-calibrated successfully. 6.12 Interrupt Enable Register The Interrupt Enable register determines whether a sensor pad touch or release (if enabled) causes the interrupt pin to be asserted. Bit 7 - CS8_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS8 (associated with the CS8 status bit). • ‘0’ - The interrupt pin will not be asserted if a touch is detected on CS8 (associated with the CS8 status bit). • ‘1’ (default) - The interrupt pin will be asserted if a touch is detected on CS8 (associated with the CS8 status bit). Bit 6 - CS7_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS7 (associated with the CS7 status bit). Bit 5 - CS6_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS6 (associated with the CS6 status bit). Bit 4 - CS5_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS5 (associated with the CS5 status bit). Bit 3 - CS4_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS4 (associated with the CS4 status bit). TABLE 6-21: CALIBRATION ACTIVATE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 26h R/W Calibration Activate CS8_ CAL CS7_ CAL CS6_ CAL CS5_ CAL CS4_ CAL CS3_ CAL CS2_ CAL CS1_ CAL 00h TABLE 6-22: INTERRUPT ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 27h R/W Interrupt Enable CS8_ INT_EN CS7_ INT_EN CS6_ INT_EN CS5_ INT_EN CS4_ INT_EN CS3_ INT_EN CS2_ INT_EN CS1_ INT_EN FFh CAP1128 DS00001622B-page 42  2015 Microchip Technology Inc. Bit 2 - CS3_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS3 (associated with the CS3 status bit). Bit 1 - CS2_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS2 (associated with the CS2 status bit). Bit 0 - CS1_INT_EN - Enables the interrupt pin to be asserted if a touch is detected on CS1 (associated with the CS1 status bit). 6.13 Repeat Rate Enable Register The Repeat Rate Enable register enables the repeat rate of the sensor inputs as described in Section 5.6.1. Bit 7 - CS8_RPT_EN - Enables the repeat rate for capacitive touch sensor input 8. • ‘0’ - The repeat rate for CS8 is disabled. It will only generate an interrupt when a touch is detected and when a release is detected (if enabled) no matter how long the touch is held for. • ‘1’ (default) - The repeat rate for CS8 is enabled. In the case of a “touch” event, it will generate an interrupt when a touch is detected and a release is detected (as determined by the INT_REL_n bit - see Section 6.6). In the case of a “press and hold” event, it will generate an interrupt when a touch is detected and at the repeat rate so long as the touch is held. Bit 6 - CS7_RPT_EN - Enables the repeat rate for capacitive touch sensor input 7. Bit 5 - CS6_RPT_EN - Enables the repeat rate for capacitive touch sensor input 6. Bit 4 - CS5_RPT_EN - Enables the repeat rate for capacitive touch sensor input 5. Bit 3 - CS4_RPT_EN - Enables the repeat rate for capacitive touch sensor input 4. Bit 2 - CS3_RPT_EN - Enables the repeat rate for capacitive touch sensor input 3. Bit 1 - CS2_RPT_EN - Enables the repeat rate for capacitive touch sensor input 2. Bit 0 - CS1_RPT_EN - Enables the repeat rate for capacitive touch sensor input 1. 6.14 Multiple Touch Configuration Register The Multiple Touch Configuration register controls the settings for the multiple touch detection circuitry. These settings determine the number of simultaneous buttons that may be pressed before additional buttons are blocked and the MULT status bit is set. Bit 7 - MULT_BLK_EN - Enables the multiple button blocking circuitry. • ‘0’ - The multiple touch circuitry is disabled. The device will not block multiple touches. • ‘1’ (default) - The multiple touch circuitry is enabled. The device will flag the number of touches equal to programmed multiple touch threshold and block all others. It will remember which sensor inputs are valid and block all others until that sensor pad has been released. Once a sensor pad has been released, the N detected touches (determined via the cycle order of CS1 - CS8) will be flagged and all others blocked. Bits 3 - 2 - B_MULT_T[1:0] - Determines the number of simultaneous touches on all sensor pads before a Multiple Touch Event is detected and sensor inputs are blocked. The bit decode is given by Table 6-25. TABLE 6-23: REPEAT RATE ENABLE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 28h R/W Repeat Rate Enable CS8_ RPT_EN CS7_ RPT_EN CS6_ RPT_EN CS5_ RPT_EN CS4_ RPT_EN CS3_ RPT_EN CS2_ RPT_EN CS1_ RPT_EN FFh TABLE 6-24: MULTIPLE TOUCH CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Ah R/W Multiple Touch Config MULT_ BLK_ EN - - - B_MULT_T[1:0] - - 80h  2015 Microchip Technology Inc. DS00001622B-page 43 CAP1128 6.15 Multiple Touch Pattern Configuration Register The Multiple Touch Pattern Configuration register controls the settings for the multiple touch pattern detection circuitry. This circuitry works like the multiple touch detection circuitry with the following differences: 1. The detection threshold is a percentage of the touch detection threshold as defined by the MTP_TH[1:0] bits whereas the multiple touch circuitry uses the touch detection threshold. 2. The MTP detection circuitry either will detect a specific pattern of sensor inputs as determined by the Multiple Touch Pattern register settings or it will use the Multiple Touch Pattern register settings to determine a minimum number of sensor inputs that will cause the MTP circuitry to flag an event. When using pattern recognition mode, if all of the sensor inputs set by the Multiple Touch Pattern register have a delta count greater than the MTP threshold or have their corresponding Noise Flag Status bits set, the MTP bit will be set. When using the absolute number mode, if the number of sensor inputs with thresholds above the MTP threshold or with Noise Flag Status bits set is equal to or greater than this number, the MTP bit will be set. 3. When an MTP event occurs, all touches are blocked and an interrupt is generated. 4. All sensor inputs will remain blocked so long as the requisite number of sensor inputs are above the MTP threshold or have Noise Flag Status bits set. Once this condition is removed, touch detection will be restored. Note that the MTP status bit is only cleared by writing a ‘0’ to the INT bit once the condition has been removed. Bit 7 - MTP_EN - Enables the multiple touch pattern detection circuitry. • ‘0’ (default) - The MTP detection circuitry is disabled. • ‘1’ - The MTP detection circuitry is enabled. Bits 3-2 - MTP_TH[1:0] - Determine the MTP threshold, as shown in Table 6-27. This threshold is a percentage of sensor input threshold (see Section 6.18, "Sensor Input Threshold Registers") when the device is in the Fully Active state or of the standby threshold (see Section 6.23, "Standby Threshold Register") when the device is in the Standby state. Bit 1 - COMP_PTRN - Determines whether the MTP detection circuitry will use the Multiple Touch Pattern register as a specific pattern of sensor inputs or as an absolute number of sensor inputs. • ‘0’ (default) - The MTP detection circuitry will use the Multiple Touch Pattern register bit settings as an absolute minimum number of sensor inputs that must be above the threshold or have Noise Flag Status bits set. The number will be equal to the number of bits set in the register. TABLE 6-25: B_MULT_T BIT DECODE B_MULT_T[1:0] Number of Simultaneous Touches 1 0 0 0 1 (default) 01 2 10 3 11 4 TABLE 6-26: MULTIPLE TOUCH PATTERN CONFIGURATION ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Bh R/W Multiple Touch Pattern Config MTP_ EN - - MTP_TH[1:0] COMP_ PTRN MTP_ ALERT 00h TABLE 6-27: MTP_TH BIT DECODE MTP_TH[1:0] Threshold Divide Setting 1 0 0 0 12.5% (default) 0 1 25% 1 0 37.5% 1 1 100% CAP1128 DS00001622B-page 44  2015 Microchip Technology Inc. • ‘1’ - The MTP detection circuitry will use pattern recognition. Each bit set in the Multiple Touch Pattern register indicates a specific sensor input that must have a delta count greater than the MTP threshold or have a Noise Flag Status bit set. If the criteria are met, the MTP status bit will be set. Bit 0 - MTP_ALERT - Enables an interrupt if an MTP event occurs. In either condition, the MTP status bit will be set. • ‘0’ (default) - If an MTP event occurs, the ALERT# pin is not asserted. • ‘1’ - If an MTP event occurs, the ALERT# pin will be asserted. 6.16 Multiple Touch Pattern Register The Multiple Touch Pattern register acts as a pattern to identify an expected sensor input profile for diagnostics or other significant events. There are two methods for how the Multiple Touch Pattern register is used: as specific sensor inputs or number of sensor input that must exceed the MTP threshold or have Noise Flag Status bits set. Which method is used is based on the COMP_PTRN bit (see Section 6.15). The methods are described below. 1. Specific Sensor Inputs: If, during a single polling cycle, the specific sensor inputs above the MTP threshold or with Noise Flag Status bits set match those bits set in the Multiple Touch Pattern register, an MTP event is flagged. 2. Number of Sensor Inputs: If, during a single polling cycle, the number of sensor inputs with a delta count above the MTP threshold or with Noise Flag Status bits set is equal to or greater than the number of pattern bits set, an MTP event is flagged. Bit 7 - CS8_PTRN - Determines whether CS8 is considered as part of the Multiple Touch Pattern. • ‘0’ - CS8 is not considered a part of the pattern. • ‘1’ - CS8 is considered a part of the pattern, or the absolute number of sensor inputs that must have a delta count greater than the MTP threshold or have the Noise Flag Status bit set is increased by 1. Bit 6 - CS7_PTRN - Determines whether CS7 is considered as part of the Multiple Touch Pattern. Bit 5 - CS6_PTRN - Determines whether CS6 is considered as part of the Multiple Touch Pattern. Bit 4 - CS5_PTRN - Determines whether CS5 is considered as part of the Multiple Touch Pattern. Bit 3 - CS4_PTRN - Determines whether CS4 is considered as part of the Multiple Touch Pattern. Bit 2 - CS3_PTRN - Determines whether CS3 is considered as part of the Multiple Touch Pattern. Bit 1 - CS2_PTRN - Determines whether CS2 is considered as part of the Multiple Touch Pattern. Bit 0 - CS1_PTRN - Determines whether CS1 is considered as part of the Multiple Touch Pattern. 6.17 Recalibration Configuration Register The Recalibration Configuration register controls the automatic re-calibration routine settings as well as advanced controls to program the Sensor Input Threshold register settings. Bit 7 - BUT_LD_TH - Enables setting all Sensor Input Threshold registers by writing to the Sensor Input 1 Threshold register. • ‘0’ - Each Sensor Input X Threshold register is updated individually. • ‘1’ (default) - Writing the Sensor Input 1 Threshold register will automatically overwrite the Sensor Input Threshold registers for all sensor inputs (Sensor Input Threshold 1 through Sensor Input Threshold 8). The individual Sensor TABLE 6-28: MULTIPLE TOUCH PATTERN REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Dh R/W Multiple Touch Pattern CS8_ PTRN CS7_ PTRN CS6_ PTRN CS5_ PTRN CS4_ PTRN CS3_ PTRN CS2_ PTRN CS1_ PTRN FFh TABLE 6-29: RECALIBRATION CONFIGURATION REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 2Fh R/W Recalibration Configuration BUT_ LD_TH NO_ CLR_ INTD NO_ CLR_ NEG NEG_DELTA_ CNT[1:0] CAL_CFG[2:0] 8Ah  2015 Microchip Technology Inc. DS00001622B-page 45 CAP1128 Input X Threshold registers (Sensor Input 2 Threshold through Sensor Input 8 Threshold) can be individually updated at any time. Bit 6 - NO_CLR_INTD - Controls whether the accumulation of intermediate data is cleared if the noise status bit is set. • ‘0’ (default) - The accumulation of intermediate data is cleared if the noise status bit is set. • ‘1’ - The accumulation of intermediate data is not cleared if the noise status bit is set. APPLICATION NOTE: Bits 5 and 6 should both be set to the same value. Either both should be set to ‘0’ or both should be set to ‘1’. Bit 5 - NO_CLR_NEG - Controls whether the consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘0’ (default) - The consecutive negative delta counts counter is cleared if the noise status bit is set. • ‘1’ - The consecutive negative delta counts counter is not cleared if the noise status bit is set. Bits 4 - 3 - NEG_DELTA_CNT[1:0] - Determines the number of negative delta counts necessary to trigger a digital recalibration as shown in Table 6-30. Bits 2 - 0 - CAL_CFG[2:0] - Determines the update time and number of samples of the automatic re-calibration routine. The settings apply to all sensor inputs universally (though individual sensor inputs can be configured to support re-calibration - see Section 6.11). Note 6-1 Recalibration Samples refers to the number of samples that are measured and averaged before the Base Count is updated however does not control the base count update period. Note 6-2 Update Time refers to the amount of time (in polling cycle periods) that elapses before the Base Count is updated. The time will depend upon the number of channels active, the averaging setting, and the programmed cycle time. TABLE 6-30: NEG_DELTA_CNT BIT DECODE NEG_DELTA_CNT[1:0] Number of Consecutive Negative Delta Count Values 1 0 00 8 0 1 16 (default) 1 0 32 1 1 None (disabled) TABLE 6-31: CAL_CFG BIT DECODE CAL_CFG[2:0] Recalibration Samples (see Note 6-1) Update Time (see Note 6-2) 210 0 0 0 16 16 0 0 1 32 32 0 1 0 64 64 (default) 0 1 1 128 128 1 0 0 256 256 1 0 1 256 1024 1 1 0 256 2048 1 1 1 256 4096 CAP1128 DS00001622B-page 46  2015 Microchip Technology Inc. 6.18 Sensor Input Threshold Registers The Sensor Input Threshold registers store the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. When the BUT_LD_TH bit is set (see Section 6.17 - bit 7), writing data to the Sensor Input 1 Threshold register will update all of the sensor input threshold registers (31h - 37h inclusive). 6.19 Sensor Input Noise Threshold Register The Sensor Input Noise Threshold register controls the value of a secondary internal threshold to detect noise and improve the automatic recalibration routine. If a capacitive touch sensor input exceeds the Sensor Input Noise Threshold but does not exceed the sensor input threshold, it is determined to be caused by a noise spike. That sample is not used by the automatic re-calibration routine. This feature can be disabled by setting the DIS_DIG_NOISE bit. Bits 1-0 - CS1_BN_TH[1:0] - Controls the noise threshold for all capacitive touch sensor inputs, as shown in Table 6-34. The threshold is proportional to the threshold setting. TABLE 6-32: SENSOR INPUT THRESHOLD REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 30h R/W Sensor Input 1 Threshold - 64 32 16 8 4 2 1 40h 31h R/W Sensor Input 2 Threshold - 64 32 16 8 4 2 1 40h 32h R/W Sensor Input 3 Threshold - 64 32 16 8 4 2 1 40h 33h R/W Sensor Input 4 Threshold - 64 32 16 8 4 2 1 40h 34h R/W Sensor Input 5 Threshold - 64 32 16 8 4 2 1 40h 35h R/W Sensor Input 6 Threshold - 64 32 16 8 4 2 1 40h 36h R/W Sensor Input 7 Threshold - 64 32 16 8 4 2 1 40h 37h R/W Sensor Input 8 Threshold - 64 32 16 8 4 2 1 40h TABLE 6-33: SENSOR INPUT NOISE THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 38h R/W Sensor Input Noise Threshold CS_BN_TH [1:0] 01h TABLE 6-34: CSX_BN_TH BIT DECODE CS_BN_TH[1:0] Percent Threshold Setting 1 0 0 0 25% 0 1 37.5% (default) 1 0 50% 1 1 62.5%  2015 Microchip Technology Inc. DS00001622B-page 47 CAP1128 6.20 Standby Channel Register The Standby Channel register controls which (if any) capacitive touch sensor inputs are active during Standby. Bit 7 - CS8_STBY - Controls whether the CS8 channel is active in Standby. • ‘0’ (default) - The CS8 channel not be sampled during Standby. • ‘1’ - The CS8 channel will be sampled during Standby. It will use the Standby threshold setting, and the standby averaging and sensitivity settings. Bit 6 - CS7_STBY - Controls whether the CS7 channel is active in Standby. Bit 5 - CS6_STBY - Controls whether the CS6 channel is active in Standby. Bit 4 - CS5_STBY - Controls whether the CS5 channel is active in Standby. Bit 3 - CS4_STBY - Controls whether the CS4 channel is active in Standby. Bit 2 - CS3_STBY - Controls whether the CS3 channel is active in Standby. Bit 1 - CS2_STBY - Controls whether the CS2 channel is active in Standby. Bit 0 - CS1_STBY - Controls whether the CS1 channel is active in Standby. 6.21 Standby Configuration Register The Standby Configuration register controls averaging and cycle time for those sensor inputs that are active in Standby. This register is useful for detecting proximity on a small number of sensor inputs as it allows the user to change averaging and sample times on a limited number of sensor inputs and still maintain normal functionality in the fully active state. Bit 7 - AVG_SUM - Determines whether the active sensor inputs will average the programmed number of samples or whether they will accumulate for the programmed number of samples. • ‘0’ - (default) - The active sensor input delta count values will be based on the average of the programmed number of samples when compared against the threshold. • ‘1’ - The active sensor input delta count values will be based on the summation of the programmed number of samples when compared against the threshold. This bit should only be set when performing proximity detection as a physical touch will overflow the delta count registers and may result in false readings. Bits 6 - 4 - STBY_AVG[2:0] - Determines the number of samples that are taken for all active channels during the sensor cycle as shown in Table 6-37. All samples are taken consecutively on the same channel before the next channel is sampled and the result is averaged over the number of samples measured before updating the measured results. TABLE 6-35: STANDBY CHANNEL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 40h R/W Standby Channel CS8_ STBY CS7_ STBY CS6_ STBY CS5_ STBY CS4_ STBY CS3_ STBY CS2_ STBY CS1_ STBY 00h TABLE 6-36: STANDBY CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 41h R/W Standby Configuration AVG_ SUM STBY_AVG[2:0] STBY_SAMP_ TIME[1:0] STBY_CY_TIME [1:0] 39h TABLE 6-37: STBY_AVG BIT DECODE STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10 0 0 0 1 0 01 2 0 10 4 0 1 1 8 (default) 1 0 0 16 CAP1128 DS00001622B-page 48  2015 Microchip Technology Inc. Bit 3-2 - STBY SAMP_TIME[1:0] - Determines the time to take a single sample when the device is in Standby as shown in Table 6-38. Bits 1 - 0 - STBY_CY_TIME[2:0] - Determines the overall cycle time for all measured channels during standby operation as shown in Table 6-39. All measured channels are sampled at the beginning of the cycle time. If additional time is remaining, the device is placed into a lower power state for the remaining duration of the cycle. APPLICATION NOTE: The programmed cycle time is only maintained if the total averaging time for all samples is less than the programmed cycle. The STBY_AVG[2:0] bits will take priority so that if more samples are required than would normally be allowed during the cycle time, the cycle time will be extended as necessary to accommodate the number of samples to be measured. 6.22 Standby Sensitivity Register The Standby Sensitivity register controls the sensitivity for sensor inputs that are active in Standby. Bits 2 - 0 - STBY_SENSE[2:0] - Controls the sensitivity for sensor inputs that are active in Standby. The sensitivity settings act to scale the relative delta count value higher or lower based on the system parameters. A setting of 000b is the most sensitive while a setting of 111b is the least sensitive. At the more sensitive settings, touches are detected for a smaller delta C corresponding to a “lighter” touch. These settings are more sensitive to noise however and a noisy environment may flag more false touches than higher sensitivity levels. APPLICATION NOTE: A value of 128x is the most sensitive setting available. At the most sensitivity settings, the MSB of the Delta Count register represents 64 out of ~25,000 which corresponds to a touch 1 0 1 32 1 1 0 64 1 1 1 128 TABLE 6-38: STBY_SAMP_TIME BIT DECODE STBY_SAMP_TIME[1:0] Sampling Time 1 0 0 0 320us 0 1 640us 1 0 1.28ms (default) 1 1 2.56ms TABLE 6-39: STBY_CY_TIME BIT DECODE STBY_CY_TIME[1:0] Overall Cycle Time 1 0 0 0 35ms 0 1 70ms (default) 1 0 105ms 1 1 140ms TABLE 6-40: STANDBY SENSITIVITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 42h R/W Standby Sensitivity - - - - - STBY_SENSE[2:0] 02h TABLE 6-37: STBY_AVG BIT DECODE (CONTINUED) STBY_AVG[2:0] Number of Samples Taken per Measurement 2 10  2015 Microchip Technology Inc. DS00001622B-page 49 CAP1128 of approximately 0.25% of the base capacitance (or a ΔC of 25fF from a 10pF base capacitance). Conversely a value of 1x is the least sensitive setting available. At these settings, the MSB of the Delta Count register corresponds to a delta count of 8192 counts out of ~25,000 which corresponds to a touch of approximately 33% of the base capacitance (or a ΔC of 3.33pF from a 10pF base capacitance). 6.23 Standby Threshold Register The Standby Threshold register stores the delta threshold that is used to determine if a touch has been detected. When a touch occurs, the input signal of the corresponding sensor pad changes due to the capacitance associated with a touch. If the sensor input change exceeds the threshold settings, a touch is detected. 6.24 Sensor Input Base Count Registers The Sensor Input Base Count registers store the calibrated “Not Touched” input value from the capacitive touch sensor inputs. These registers are periodically updated by the re-calibration routine. TABLE 6-41: STBY_SENSE BIT DECODE STBY_SENSE[2:0] Sensitivity Multiplier 210 0 0 0 128x (most sensitive) 0 0 1 64x 0 1 0 32x (default) 0 1 1 16x 1 0 0 8x 1 0 1 4x 1 1 0 2x 1 1 1 1x - (least sensitive) TABLE 6-42: STANDBY THRESHOLD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 43h R/W Standby Threshold - 64 32 16 8 4 2 1 40h TABLE 6-43: SENSOR INPUT BASE COUNT REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 50h R Sensor Input 1 Base Count 128 64 32 16 8 4 2 1 C8h 51h R Sensor Input 2 Base Count 128 64 32 16 8 4 2 1 C8h 52h R Sensor Input 3 Base Count 128 64 32 16 8 4 2 1 C8h 53h R Sensor Input 4 Base Count 128 64 32 16 8 4 2 1 C8h 54h R Sensor Input 5 Base Count 128 64 32 16 8 4 2 1 C8h 55h R Sensor Input 6 Base Count 128 64 32 16 8 4 2 1 C8h 56h R Sensor Input 7 Base Count 128 64 32 16 8 4 2 1 C8h 57h R Sensor Input 8 Base Count 128 64 32 16 8 4 2 1 C8h CAP1128 DS00001622B-page 50  2015 Microchip Technology Inc. The routine uses an internal adder to add the current count value for each reading to the sum of the previous readings until sample size has been reached. At this point, the upper 16 bits are taken and used as the Sensor Input Base Count. The internal adder is then reset and the re-calibration routine continues. The data presented is determined by the BASE_SHIFT[3:0] bits (see Section 6.5). 6.25 LED Output Type Register The LED Output Type register controls the type of output for the LED pins. Each pin is controlled by a single bit. Refer to application note 21.4 CAP1128Family LED Configuration Options for more information about implementing LEDs. Bit 1 - LED2_OT - Determines the output type of the LED2 pin. • ‘0’ (default) - The LED2 pin is an open-drain output with an external pull-up resistor. When the appropriate pin is set to the “active” state (logic ‘1’), the pin will be driven low. Conversely, when the pin is set to the “inactive” state (logic ‘0’), then the pin will be left in a High Z state and pulled high via an external pull-up resistor. • ‘1’ - The LED2 pin is a push-pull output. When driving a logic ‘1’, the pin is driven high. When driving a logic ‘0’, the pin is driven low. Bit 0 - LED1_OT - Determines the output type of the LED1 pin. 6.26 Sensor Input LED Linking Register The Sensor Input LED Linking register controls whether a capacitive touch sensor input is linked to an LED output. If the corresponding bit is set, then the appropriate LED output will change states defined by the LED Behavior controls (see Section 6.31) in response to the capacitive touch sensor input. Bit 1 - CS2_LED2 - Links the LED2 output to a detected touch on the CS2 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. • ‘0’ (default) - The LED 2 output is not associated with the CS2 input. If a touch is detected on the CS2 input, the LED will not automatically be actuated. The LED is enabled and controlled via the LED Output Control register (see Section 6.28) and the LED Behavior registers (see Section 6.31). • ‘1’ - The LED 2 output is associated with the CS2 input. If a touch is detected on the CS2 input, the LED will be actuated and behave as defined in Table 6-52. Bit 0 - CS1_LED1 - Links the LED1 output to a detected touch on the CS1 sensor input. When a touch is detected, the LED is actuated and will behave as determined by the LED Behavior controls. 6.27 LED Polarity Register The LED Polarity register controls the logical polarity of the LED outputs. When these bits are set or cleared, the corresponding LED Mirror controls are also set or cleared (unless the BLK_POL_MIR bit is set - see Section 6.6, "Configuration Registers"). Table 6-48, "LED Polarity Behavior" shows the interaction between the polarity controls, output controls, and relative brightness. TABLE 6-44: LED OUTPUT TYPE REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 71h R/W LED Output Type ----- - LED2_ OT LED1_ OT 00h TABLE 6-45: SENSOR INPUT LED LINKING REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 72h R/W Sensor Input LED Linking - - - - - - CS2_ LED2 CS1_ LED1 00h TABLE 6-46: LED POLARITY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 73h R/W LED Polarity - - - - - - LED2_ POL LED1_ POL 00h  2015 Microchip Technology Inc. DS00001622B-page 51 CAP1128 APPLICATION NOTE: The polarity controls determine the final LED pin drive. A touch on a linked capacitive touch sensor input is treated in the same way as the LED Output Control bit being set to a logic ‘1’. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’ then the LED will be on and that the CAP1128 LED pin is sinking the LED current. Conversely, if the LED pin is driven to a logic ‘1’, the LED will be off and there is no current flow. See Figure 5-1, "System Diagram for CAP1128". APPLICATION NOTE: This application note applies when the LED polarity is inverted (LEDx_POL = ‘0’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘0’ state in. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven low (i.e. maximum % of time that the LED is on) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven low (i.e. minimum % of time that the LED is on). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at the minimum duty cycle setting. Breathe operations will ramp the duty cycle from the minimum duty cycle to the maximum duty cycle. APPLICATION NOTE: This application note applies when the LED polarity is non-inverted (LEDx_POL = ‘1’). For LED operation, the duty cycle settings determine the % of time that the LED pin will be driven to a logic ‘1’ state. The Max Duty Cycle settings define the maximum % of time that the LED pin will be driven high (i.e. maximum % of time that the LED is off) while the Min Duty Cycle settings determine the minimum % of time that the LED pin will be driven high (i.e. minimum % of time that the LED is off). When there is no touch detected or the LED Output Control register bit is at a logic ‘0’, the LED output will be driven at 100 minus the minimum duty cycle setting. Breathe operations will ramp the duty cycle from 100 minus the minimum duty cycle to 100 minus the maximum duty cycle. APPLICATION NOTE: The LED Mirror controls (see Section 6.30, "LED Mirror Control Register") work with the polarity controls with respect to LED brightness but will not have a direct effect on the output pin drive. Bit 1 - LED2_POL - Determines the polarity of the LED2 output. • ‘0’ (default) - The LED2 output is inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘0’. • ‘1’ - The LED2 output is non-inverted. For example, a setting of ‘1’ in the LED Output Control register will cause the LED pin output to be driven to a logic ‘1’ or left in the high-z state as determined by its output type. Bit 0 - LED1_POL - Determines the polarity of the LED1 output. 6.28 LED Output Control Register The LED Output Control Register controls the output state of the LED pins that are not linked to sensor inputs. The LED Polarity Control Register will determine the non actuated state of the LED pins. The actuated LED behavior is determined by the LED behavior controls (see Section 6.31, "LED Behavior Register"). TABLE 6-47: LED OUTPUT CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 74h R/W LED Output Control --- - -- LED2_ DR LED1_ DR 00h Note: If an LED is linked to a sensor input in the Sensor Input LED Linking Register (Section 6.26, "Sensor Input LED Linking Register"), the corresponding bit in the LED Output Control Register is ignored (i.e. a linked LED cannot be host controlled). CAP1128 DS00001622B-page 52  2015 Microchip Technology Inc. Table 6-48 shows the interaction between the polarity controls, output controls, and relative brightness. Bit 1 - LED2_DR - Determines whether LED2 output is driven high or low. • ‘0’ (default) - The LED2 output is driven at the minimum duty cycle or not actuated. • ‘1’ - The LED2 output is High Z or driven at the maximum duty cycle or actuated. Bit 0 - LED1_DR - Determines whether LED1 output is driven high or low. 6.29 Linked LED Transition Control Register The Linked LED Transition Control register controls the LED drive when the LED is linked to a capacitive touch sensor input. These controls work in conjunction with the INV_LINK_TRAN bit (see Section 6.6.2, "Configuration 2 - 44h") to create smooth transitions from host control to linked LEDs. Bit 1 - LED2_LTRAN - Determines the transition effect when LED2 is linked to CS2. • ‘0’ (default) - When the LED output control bit for LED2 is ‘1’, and then LED2 is linked to CS2 and no touch is detected, the LED will change states. • ‘1’ - If the INV_LINK_TRAN bit is ‘1’, when the LED output control bit for CS2 is ‘1’, and then CS2 is linked to LED2 and no touch is detected, the LED will not change states. In addition, the LED state will change when the sensor pad is touched. If the INV_LINK_TRAN bit is ‘0’, when the LED output control bit for CS2 is ‘1’, and then CS2 is linked to LED2 and no touch is detected, the LED will not change states. However, the LED state will not change when the sensor pad is touched. APPLICATION NOTE: If the LED behavior is not “Direct” and the INV_LINK_TRAN bit it ‘0’, the LED will not perform as expected when the LED2_LTRAN bit is set to ‘1’. Therefore, if breathe and pulse behaviors are used, set the INV_LINK_TRAN bit to ‘1’. TABLE 6-48: LED POLARITY BEHAVIOR LED Output Control Register or Touch Polarity Max Duty Min Duty Brightness LED Appearance 0 inverted (‘0’) not used minimum % of time that the LED is on (logic 0) maximum brightness at min duty cycle on at min duty cycle 1 inverted (‘0’) maximum % of time that the LED is on (logic 0) minimum % of time that the LED is on (logic 0) maximum brightness at max duty cycle. Brightness ramps from min duty cycle to max duty cycle according to LED behavior 0 non-inverted (‘1’) not used minimum % of time that the LED is off (logic 1) maximum brightness at 100 minus min duty cycle. on at 100 - min duty cycle 1 non-inverted (‘1’) maximum % of time that the LED is off (logic 1) minimum % of time that the LED is off (logic 1) For Direct behavior, maximum brightness is 100 minus max duty cycle. When breathing, max brightness is 100 minus min duty cycle. Brightness ramps from 100 - min duty cycle to 100 - max duty cycle. according to LED behavior TABLE 6-49: LINKED LED TRANSITION CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 77h R/W Linked LED Transition Control - ----- LED2_ LTRAN LED1_ LTRAN 00h  2015 Microchip Technology Inc. DS00001622B-page 53 CAP1128 Bit 0 - LED1_LTRAN - Determines the transition effect when LED1 is linked to CS1. 6.30 LED Mirror Control Register The LED Mirror Control Registers determine the meaning of duty cycle settings when polarity is non-inverted for each LED channel. When the polarity bit is set to ‘1’ (non-inverted), to obtain correct steps for LED ramping, pulse, and breathe behaviors, the min and max duty cycles need to be relative to 100%, rather than the default, which is relative to 0%. APPLICATION NOTE: The LED drive assumes that the LEDs are configured such that if the LED pin is driven to a logic ‘0’, the LED will be on and the CAP1128 LED pin is sinking the LED current. When the polarity bit is set to ‘1’, it is considered non-inverted. For systems using the opposite LED configuration, mirror controls would apply when the polarity bit is ‘0’. These bits are changed automatically if the corresponding LED Polarity bit is changed (unless the BLK_POL_MIR bit is set - see Section 6.6). Bit 1 - LED2_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. • ‘0’ (default) - The duty cycle settings are determined relative to 0% and are determined directly with the settings. • ‘1’ - The duty cycle settings are determined relative to 100%. Bit 0 - LED1_MIR_EN - Determines whether the duty cycle settings are “biased” relative to 0% or 100% duty cycle. 6.31 LED Behavior Register The LED Behavior register controls the operation of LEDs. Each LED pin is controlled by a 2-bit field and the behavior is determined by whether the LED is linked to a capacitive touch sensor input or not. If the corresponding LED output is linked to a capacitive touch sensor input, the appropriate behavior will be enabled / disabled based on touches and releases. If the LED output is not associated with a capacitive touch sensor input, the appropriate behavior will be enabled / disabled by the LED Output Control register. If the respective LEDx_DR bit is set to a logic ‘1’, this will be associated as a “touch”, and if the LEDx_DR bit is set to a logic ‘0’, this will be associated as a “release”. Table 6-52, "LEDx_CTL Bit Decode" shows the behavior triggers. The defined behavior will activate when the Start Trigger is met and will stop when the Stop Trigger is met. Note the behavior of the Breathe Hold and Pulse Release option. The LED Polarity Control register will determine the non actuated state of the LED outputs (see Section 6.27, "LED Polarity Register"). APPLICATION NOTE: If an LED is not linked to a capacitive touch sensor input and is breathing (via the Breathe or Pulse behaviors), it must be unactuated and then re-actuated before changes to behavior are processed. For example, if the LED output is breathing and the Maximum duty cycle is changed, this change will not take effect until the LED output control register is set to ‘0’ and then re-set to ‘1’. APPLICATION NOTE: If an LED is not linked to the capacitive touch sensor input and configured to operate using Pulse 1 Behavior, then the circuitry will only be actuated when the corresponding output control bit is set. It will not check the bit condition until the Pulse 1 behavior is finished. The device will not remember if the bit was cleared and reset while it was actuated. TABLE 6-50: LED MIRROR CONTROL REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 79h R/W LED Mirror Control ------ LED2_ MIR _ EN LED1_ MIR _ EN 00h TABLE 6-51: LED BEHAVIOR REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 81h R/W LED Behavior 1 - - - - LED2_CTL[1:0] LED1_CTL[1:0] 00h CAP1128 DS00001622B-page 54  2015 Microchip Technology Inc. APPLICATION NOTE: If an LED is actuated and not linked and the desired LED behavior is changed, this new behavior will take effect immediately; however, the first instance of the changed behavior may act incorrectly (e.g. if changed from Direct to Pulse 1, the LED output may ‘breathe’ 4 times and then end at minimum duty cycle). LED Behaviors will operate normally once the LED has been un-actuated and then re-actuated. APPLICATION NOTE: If an LED is actuated and it is switched from linked to a capacitive touch sensor input to unlinked (or vice versa), the LED will respond to the new command source immediately if the behavior was Direct or Breathe. For Pulse behaviors, it will complete the behavior already in progress. For example, if a linked LED was actuated by a touch and the control is changed so that it is unlinked, it will check the status of the corresponding LED Output Control bit. If that bit is ‘0’, then the LED will behave as if a release was detected. Likewise, if an unlinked LED was actuated by the LED Output Control register and the control is changed so that it is linked and no touch is detected, then the LED will behave as if a release was detected. Bits 3 - 2 - LED2_CTL[1:0] - Determines the behavior of LED2 as shown in Table 6-52. Bits 1 - 0 - LED1_CTL[1:0] - Determines the behavior of LED1 as shown in Table 6-52. APPLICATION NOTE: The PWM frequency is determined based on the selected LED behavior, the programmed breathe period, and the programmed min and max duty cycles. For the Direct behavior mode, the PWM frequency is calculated based on the programmed Rise and Fall times. If these are set at 0, then the maximum PWM frequency will be used based on the programmed duty cycle settings. TABLE 6-52: LEDX_CTL BIT DECODE LEDx_CTL [1:0] Operation Description Start TRigger Stop Trigger 1 0 0 0 Direct The LED is driven to the programmed state (active or inactive). See Figure 6-7 Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared 0 1 Pulse 1 The LED will “Pulse” a programmed number of times. During each “Pulse” the LED will breathe up to the maximum brightness and back down to the minimum brightness so that the total “Pulse” period matches the programmed value. Touch or Release Detected or LED Output Control bit set or cleared (see Section 6.32) n/a 1 0 Pulse 2 The LED will “Pulse” when the start trigger is detected. When the stop trigger is detected, it will “Pulse” a programmable number of times then return to its minimum brightness. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared 1 1 Breathe The LED will breathe. It will be driven with a duty cycle that ramps up from the programmed minimum duty cycle (default 0%) to the programmed maximum duty cycle duty cycle (default 100%) and then back down. Each ramp takes up 50% of the programmed period. The total period of each “breath” is determined by the LED Breathe Period controls - see Section 6.34. Touch Detected or LED Output Control bit set Release Detected or LED Output Control bit cleared  2015 Microchip Technology Inc. DS00001622B-page 55 CAP1128 6.32 LED Pulse 1 Period Register The LED Pulse Period 1 register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 01b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms (24 x 32ms = 768ms). The total range is from 32ms to 4.064 seconds as shown in Table 6-54 with the default being 1024ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. Bit 7 - ST_TRIG - Determines the start trigger for the LED Pulse behavior. • ‘0’ (default) - The LED will Pulse when a touch is detected or the drive bit is set. • ‘1’ - The LED will Pulse when a release is detected or the drive bit is cleared. The Pulse 1 operation is shown in Figure 6-1 when the LED output is configured for non-inverted polarity (LEDx_POL = 1) and in Figure 6-2 for inverted polarity (LEDx_POL = 0). . TABLE 6-53: LED PULSE 1 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 84h R/W LED Pulse 1 Period ST_ TRIG P1_ PER6 P1_ PER5 P1_ PER4 P1_ PER3 P1_ PER2 P1_ PER1 P1_ PER0 20h FIGURE 6-1: Pulse 1 Behavior with Non-Inverted Polarity Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected (100% - Pulse 1 Max Duty Cycle) * Brightness X pulses after touch or after release Pulse 1 Period (P1_PER) (100% - Pulse 1 Min Duty Cycle) * Brightness LED Brightness CAP1128 DS00001622B-page 56  2015 Microchip Technology Inc. 6.33 LED Pulse 2 Period Register The LED Pulse 2 Period register determines the overall period of a pulse operation as determined by the LED_CTL registers (see Table 6-52 - setting 10b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 640ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. The Pulse 2 Behavior is shown in Figure 6-3 for non-inverted polarity (LEDx_POL = 1) and in Figure 6-4 for inverted polarity (LEDx_POL = 0). FIGURE 6-2: Pulse 1 Behavior with Inverted Polarity TABLE 6-54: LED PULSE / BREATHE PERIOD EXAMPLE Setting (HEX) Setting (Decimal) Total Breathe / Pulse Period (MS) 00h 0 32 01h 1 32 02h 2 64 03h 3 96 . . . . . . . . . 7Dh 125 4000 7Eh 126 4032 7Fh 127 4064 TABLE 6-55: LED PULSE 2 PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 85h R/W LED Pulse 2 Period - P2_ PER6 P2_ PER5 P2_ PER4 P2_ PER3 P2_ PER2 P2_ PER1 P2_ PER0 14h Normal – untouched operation Normal – untouched operation Touch Detected or Release Detected Pulse 1 Min Duty Cycle * Brightness X pulses after touch or after release Pulse Period (P1_PER) Pulse 1 Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001622B-page 57 CAP1128 6.34 LED Breathe Period Register The LED Breathe Period register determines the overall period of a breathe operation as determined by the LED_CTL registers (see Table 6-52 - setting 11b). The LSB represents 32ms so that a setting of 18h (24d) would represent a period of 768ms. The total range is from 32ms to 4.064 seconds (see Table 6-54) with a default of 2976ms. APPLICATION NOTE: Due to constraints on the LED Drive PWM operation, any Breathe Period less than 160ms (05h) may not be achievable. The device will breathe at the minimum period possible as determined by the period and min / max duty cycle settings. FIGURE 6-3: Pulse 2 Behavior with Non-Inverted Polarity FIGURE 6-4: Pulse 2 Behavior with Inverted Polarity TABLE 6-56: LED BREATHE PERIOD REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 86h R/W LED Breathe Period - BR_ PER6 BR_ PER5 BR_ PER4 BR_ PER3 BR_ PER2 BR_ PER1 BR_ PER0 5Dh . . . Normal – untouched operation Normal – untouched operation Touch Detected (100% - Pulse 2 Min Duty Cycle) * Brightness (100% - Pulse 2 Max Duty Cycle) * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness Normal – untouched operation Normal – untouched operation Touch Detected Pulse 2 Max Duty Cycle * Brightness Pulse 2 Min Duty Cycle * Brightness X additional pulses after release Release Detected Pulse Period (P2_PER) LED Brightness . . . CAP1128 DS00001622B-page 58  2015 Microchip Technology Inc. 6.35 LED Configuration Register The LED Configuration register controls general LED behavior as well as the number of pulses that are sent for the PULSE LED output behavior. Bit 6 - RAMP_ALERT - Determines whether the device will assert the ALERT# pin when LEDs actuated by the LED Output Control register bits have finished their respective behaviors. Interrupts will only be generated if the LED activity is generated by writing the LED Output Control registers. Any LED activity associated with touch detection will not cause an interrupt to be generated when the LED behavior has been finished. • ‘0’ (default) - The ALERT# pin will not be asserted when LEDs actuated by the LED Output Control register have finished their programmed behaviors. • ‘1’ - The ALERT# pin will be asserted whenever any LED that is actuated by the LED Output Control register has finished its programmed behavior. Bits 5 - 3 - PULSE2_CNT[2:0] - Determines the number of pulses used for the Pulse 2 behavior as shown in Table 6-58. Bits 2 - 0 - PULSE1_CNT[2:0] - Determines the number of pulses used for the Pulse 1 behavior as shown in Table 6-58. 6.36 LED Duty Cycle Registers The LED Duty Cycle registers determine the minimum and maximum duty cycle settings used for the LED for each LED behavior. These settings affect the brightness of the LED when it is fully off and fully on. The LED driver duty cycle will ramp up from the minimum duty cycle to the maximum duty cycle and back down again. APPLICATION NOTE: When operating in Direct behavior mode, changes to the Duty Cycle settings will be applied immediately. When operating in Breathe, Pulse 1, or Pulse 2 modes, the LED must be unactuated and then re-actuated before changes to behavior are processed. TABLE 6-57: LED CONFIGURATION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 88h R/W LED Config - RAMP_ ALERT PULSE2_CNT[2:0] PULSE1_CNT[2:0] 04h TABLE 6-58: PULSEX_CNT DECODE PULSEX_CNT[2:0] Number of Breaths 21 0 0 0 0 1 (default - Pulse 2) 00 1 2 01 0 3 01 1 4 1 0 0 5 (default - Pulse 1) 10 1 6 11 0 7 11 1 8 TABLE 6-59: LED DUTY CYCLE REGISTERS ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 90h R/W LED Pulse 1 Duty Cycle P1_MAX_DUTY[3:0] P1_MIN_DUTY[3:0] F0h 91h R/W LED Pulse 2 Duty Cycle P2_MAX_DUTY[3:0] P2_MIN_DUTY[3:0] F0h 92h R/W LED Breathe Duty Cycle BR_MAX_DUTY[3:0] BR_MIN_DUTY[3:0] F0h 93h R/W Direct Duty Cycle DR_MAX_DUTY[3:0] DR_MIN_DUTY[3:0] F0h  2015 Microchip Technology Inc. DS00001622B-page 59 CAP1128 Bits 7 - 4 - X_MAX_DUTY[3:0] - Determines the maximum PWM duty cycle for the LED drivers as shown in Table 6-60. Bits 3 - 0 - X_MIN_DUTY[3:0] - Determines the minimum PWM duty cycle for the LED drivers as shown in Table 6-60. 6.37 LED Direct Ramp Rates Register The LED Direct Ramp Rates register control the rising and falling edge time of an LED that is configured to operate in Direct behavior mode. The rising edge time corresponds to the amount of time the LED takes to transition from its minimum duty cycle to its maximum duty cycle. Conversely, the falling edge time corresponds to the amount of time that the LED takes to transition from its maximum duty cycle to its minimum duty cycle. Bits 5 - 3 - RISE_RATE[2:0] - Determines the rising edge time of an LED when it transitions from its minimum drive state to its maximum drive state as shown in Table 6-62. Bits 2 - 0 - FALL_RATE[2:0] - Determines the falling edge time of an LED when it transitions from its maximum drive state to its minimum drive state as shown in Table 6-62. TABLE 6-60: LED DUTY CYCLE DECODE x_MAX/MIN_Duty [3:0] Maximum Duty Cycle Minimum Duty Cycle 3 21 0 0 0 0 0 7% 0% 0 0 0 1 9% 7% 0 0 1 0 11% 9% 0 0 1 1 14% 11% 0 1 0 0 17% 14% 0 1 0 1 20% 17% 0 1 1 0 23% 20% 0 1 1 1 26% 23% 1 0 0 0 30% 26% 1 0 0 1 35% 30% 1 0 1 0 40% 35% 1 0 1 1 46% 40% 1 1 0 0 53% 46% 1 1 0 1 63% 53% 1 1 1 0 77% 63% 1 1 1 1 100% 77% TABLE 6-61: LED DIRECT RAMP RATES REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 94h R/W LED Direct Ramp Rates - - RISE_RATE[2:0] FALL_RATE[2:0] 00h TABLE 6-62: RISE / FALL RATE DECODE RISE_RATE/ FALL_RATE/ Bit Decode Rise / Fall Time (TRISE / TFALL) 21 0 00 0 0 0 0 1 250ms 0 1 0 500ms 0 1 1 750ms 1 0 0 1s 1 0 1 1.25s CAP1128 DS00001622B-page 60  2015 Microchip Technology Inc. 6.38 LED Off Delay Register The LED Off Delay register determines the amount of time that an LED remains at its maximum duty cycle (or minimum as determined by the polarity controls) before it starts to ramp down. If the LED is operating in Breathe mode, this delay is applied at the top of each “breath”. If the LED is operating in the Direct mode, this delay is applied when the LED is unactuated. Bits 6 - 4 - BR_OFF_DLY[2:0] - Determines the Breathe behavior mode off delay, which is the amount of time an LED in Breathe behavior mode remains inactive after it finishes a breathe pulse (ramp on and ramp off), as shown in Figure 6- 5 (non-inverted polarity LEDx_POL = 1) and Figure 6-6 (inverted polarity LEDx_POL = 0). Available settings are shown in Table 6-64. 1 1 0 1.5s 1 1 1 2s TABLE 6-63: LED OFF DELAY REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default 95h R/W LED Off Delay Register - BR_OFF_DLY[2:0] DIR_OFF_DLY[3:0] 00h FIGURE 6-5: Breathe Behavior with Non-Inverted Polarity TABLE 6-62: RISE / FALL RATE DECODE (CONTINUED) RISE_RATE/ FALL_RATE/ Bit Decode Rise / Fall Time (TRISE / TFALL) 21 0 LED Actuated 100% - Breathe Max Min Cycle * Brightness 100% - Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER)  2015 Microchip Technology Inc. DS00001622B-page 61 CAP1128 Bits 3 - 0 - DIR_OFF_DLY[3:0] - Determines the turn-off delay, as shown in Table 6-65, for all LEDs that are configured to operate in Direct behavior mode. The Direct behavior operation is determined by the combination of programmed Rise Time, Fall Time, Min and Max Duty cycles, Off Delay, and polarity. Figure 6-7 shows the behavior for non-inverted polarity (LEDx_POL = 1) while Figure 6- 8 shows the behavior for inverted polarity (LEDx_POL = 0). FIGURE 6-6: Breathe Behavior with Inverted Polarity TABLE 6-64: BREATHE OFF DELAY SETTINGS BR_OFF_DLY [2:0] OFF Delay 2 10 0 0 0 0 (default) 0 0 1 0.25s 0 1 0 0.5s 0 1 1 0.75s 1 0 0 1.0s 1 0 1 1.25s 1 1 0 1.5s 1 1 1 2.0s LED Actuated Breathe Max Duty Cycle * Brightness Breathe Min Duty Cycle * Brightness LED Unactuated Breathe Off Delay (BR_OFF_DLY) LED Brightness Breathe Period (BR_PER) CAP1128 DS00001622B-page 62  2015 Microchip Technology Inc. FIGURE 6-7: Direct Behavior for Non-Inverted Polarity FIGURE 6-8: Direct Behavior for Inverted Polarity TABLE 6-65: OFF DELAY DECODE OFF Delay[3:0] Bit Decode OFF Delay (tOFF_DLY) 32 1 0 00 0 0 0 0 0 0 1 250ms 0 0 1 0 500ms 0 0 1 1 750ms 0 1 0 0 1s 0 1 0 1 1.25s 0 1 1 0 1.5s 0 1 1 1 2s 1 0 0 0 2.5s 1 0 0 1 3.0s 1 0 1 0 3.5s 1 0 1 1 4.0s 1 1 0 0 4.5s All others 5.0s Normal – untouched operation RISE_RATE Setting (tRISE) (100% - Max Duty Cycle) * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation (100% - Min Duty Cycle) * Brightness LED Brightness Normal – untouched operation RISE_RATE Setting (tRISE) Min Duty Cycle * Brightness Touch Detected Release Detected Off Delay (tOFF_DLY) FALL_RATE Setting (tFALL) Normal – untouched operation Max Duty Cycle * Brightness LED Brightness  2015 Microchip Technology Inc. DS00001622B-page 63 CAP1128 6.39 Sensor Input Calibration Registers The Sensor Input Calibration registers hold the 10-bit value that represents the last calibration value. 6.40 Product ID Register The Product ID register stores a unique 8-bit value that identifies the device. 6.41 Manufacturer ID Register The Vendor ID register stores an 8-bit value that represents Microchip. TABLE 6-66: SENSOR INPUT CALIBRATION REGISTERS ADDR Register R/W B7 B6 B5 B4 B3 B2 B1 B0 Default B1h Sensor Input 1 Calibration R CAL1_9 CAL1_8 CAL1_7 CAL1_6 CAL1_5 CAL1_4 CAL1_3 CAL1_2 00h B2h Sensor Input 2 Calibration R CAL2_9 CAL2_8 CAL2_7 CAL2_6 CAL2_5 CAL2_4 CAL2_3 CAL2_2 00h B3h Sensor Input 3 Calibration R CAL3_9 CAL3_8 CAL3_7 CAL3_6 CAL3_5 CAL3_4 CAL3_3 CAL3_2 00h B4h Sensor Input 4 Calibration R CAL4_9 CAL4_8 CAL4_7 CAL4_6 CAL4_5 CAL4_4 CAL4_3 CAL4_2 00h B5h Sensor Input 5 Calibration R CAL5_9 CAL5_8 CAL5_7 CAL5_6 CAL5_5 CAL5_4 CAL5_3 CAL5_2 00h B6h Sensor Input 6 Calibration R CAL6_9 CAL6_8 CAL6_7 CAL6_6 CAL6_5 CAL6_4 CAL6_3 CAL6_2 00h B7h Sensor Input 7 Calibration R CAL7_9 CAL7_8 CAL7_7 CAL7_6 CAL7_5 CAL7_4 CAL7_3 CAL7_2 00h B8h Sensor Input 8 Calibration R CAL8_9 CAL8_8 CAL8_7 CAL8_6 CAL8_5 CAL8_4 CAL8_3 CAL8_2 00h B9h Sensor Input Calibration LSB 1 R CAL4_1 CAL4_0 CAL3_1 CAL3_0 CAL2_1 CAL2_0 CAL1_1 CAL1_0 00h BAh Sensor Input Calibration LSB 2 R CAL8_1 CAL8_0 CAL7_1 CAL7_0 CAL6_1 CAL6_0 CAL5_1 CAL5_0 00h TABLE 6-67: PRODUCT ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FDh R Product ID 0 1 0 1 0 0 1 0 52h TABLE 6-68: VENDOR ID REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FEh R Manufacturer ID 0 1 0 1 1 1 0 1 5Dh CAP1128 DS00001622B-page 64  2015 Microchip Technology Inc. 6.42 Revision Register The Revision register stores an 8-bit value that represents the part revision. TABLE 6-69: REVISION REGISTER ADDR R/W Register B7 B6 B5 B4 B3 B2 B1 B0 Default FFh R Revision 1 0 0 0 0 0 1 1 83h  2015 Microchip Technology Inc. DS00001622B-page 65 CAP1128 7.0 PACKAGE INFORMATION 7.1 CAP1128 Package Drawings Note: For the most current package drawings, see the Microchip Packaging Specification at: http://www.microchip.com/packaging. FIGURE 7-1: 20-Pin QFN 4mm x 4mm Package Drawing CAP1128 DS00001622B-page 66  2015 Microchip Technology Inc. FIGURE 7-2: 20-Pin QFN 4mm x 4mm Package Dimensions FIGURE 7-3: 20-Pin QFN 4mm x 4mm PCB Drawing  2015 Microchip Technology Inc. DS00001622B-page 67 CAP1128 7.2 Package Marking FIGURE 7-4: CAP1128 Package Markings C 1 28 - 1 Y WWN N N A RCC e3 TOP BOTTOM Bottom marking not allowed PB-FREE/GREEN SYMBOL (Matte Sn) Lines 1-3: Line 4: Center Horizontal Alignment Left Horizontal Alignment PIN 1 0.41 3x 0.56 Line 1 – SMSC Logo without circled R symbol Line 2 – Device ID, Version Line 3 – Year, Week, Alphanumeric Traceability Code Line 4 – Revision, Country Code 1 CAP1128 DS00001622B-page 68  2015 Microchip Technology Inc. APPENDIX A: DEVICE DELTA A.1 Delta from CAP1028 to CAP1128 1. Updated circuitry to improve power supply rejection. 2. Updated LED driver duty cycle decode values to have more distribution at lower values - closer to a logarithmic curve. See Table 6-60, "LED Duty Cycle Decode". 3. Updated bug that breathe periods were not correct above 2.6s. This includes rise / fall time decodes above 1.5s. 4. Added filtering on RESET pin to prevent errant resets. 5. Updated controls so that the RESET pin assertion places the device into the lowest power state available and causes an interrupt when released. See Section 5.2, "RESET Pin". 6. Added 1 bit to the LED Off Delay register (see Section 6.38, "LED Off Delay Register") to extend times from 2s to 5s in 0.5s intervals. 7. Breathe behavior modified. A breathe off delay control was added to the LED Off Delay Register (see Section 6.38, "LED Off Delay Register") so the LEDs can be configured to remain inactive between breathes. 8. Added controls for the LED transition effects when linking LEDs to capacitive sensor inputs. See Section 6.29, "Linked LED Transition Control Register". 9. Added controls to “mirror” the LED duty cycle outputs so that when polarity changes, the LED brightness levels look right. These bits are automatically set when polarity is set. Added control to break this auto-set behavior. See Section 6.30, "LED Mirror Control Register". 10. Added Multiple Touch Pattern detection circuitry. See Section 6.15, "Multiple Touch Pattern Configuration Register". 11. Added General Status register to flag Multiple touches, Multiple Touch Pattern issues and general touch detections. See Section 6.2, "Status Registers". 12. Added bits 6 and 5 to the Recalibration Configuration register (2Fh - see Section 6.17, "Recalibration Configuration Register"). These bits control whether the accumulation of intermediate data and the consecutive negative delta counts counter are cleared when the noise status bit is set. 13. Added Configuration 2 register for LED linking controls, noise detection controls, and control to interrupt on press but not on release. Added control to change alert pin polarity. See Section 6.6, "Configuration Registers". 14. Updated Deep Sleep behavior so that device does not clear DSLEEP bit on received communications but will wake to communicate. 15. Changed PWM frequency for LED drivers. The PWM frequency was derived from the programmed breathe period and duty cycle settings and it ranged from ~4Hz to ~8000 Hz. The PWM frequency has been updated to be a fixed value of ~2000Hz. 16. Register delta: Table A.1 Register Delta From CAP1028 to CAP1128 Address Register Delta Delta Default 00h Page 31 Changed - Main Status / Control added bits 7-6 to control gain 00h 02h Page 32 New - General Status new register to store MTP, MULT, LED, RESET, and general TOUCH bits 00h 44h Page 36 New - Configuration 2 new register to control alert polarity, LED touch linking behavior, LED output behavior, and noise detection, and interrupt on release 40h 24h Page 39 Changed - Averaging Control updated register bits - moved SAMP_AVG[2:0] bits and added SAMP_- TIME bit 1. Default changed 39h 2Bh Page 43 New - Multiple Touch Pattern Configuration new register for Multiple Touch Pattern configuration - enable and threshold settings 80h  2015 Microchip Technology Inc. DS00001622B-page 69 CAP1128 2Dh Page 44 New - Multiple Touch Pattern Register new register for Multiple Touch Pattern detection circuitry - pattern or number of sensor inputs FFh 2Fh Page 44 Changed - Recalibration Configuration updated register - updated CAL_CFG bit decode to add a 128 averages setting and removed highest time setting. Default changed. Added bit 6 NO_CLR_INTD and bit 5 NO_CLR_NEG. 8Ah 38h Page 46 Changed - Sensor Input Noise Threshold updated register bits - removed bits 7 - 3 and consolidated all controls into bits 1 - 0. These bits will set the noise threshold for all channels. Default changed 01h 39h Removed - Noise Threshold Register 2 removed register n/a 41h Page 47 Changed - Standby Configuration updated register bits - moved STBY_AVG[2:0] bits and added STBY_- TIME bit 1. Default changed 39h 77h Page 52 New - Linked LED Transition Control new register to control transition effect when LED linked to sensor inputs 00h 79h Page 53 New - LED Mirror Control new register to control LED output mirroring for brightness control when polarity changed 00h 90h Page 58 Changed - LED Pulse 1 Duty Cycle changed bit decode to be more logarithmic F0h 91h Page 58 Changed - LED Pulse 2 Duty Cycle changed bit decode to be more logarithmic F0h 92h Page 58 Changed - LED Breathe Duty Cycle changed bit decode to be more logarithmic F0h 93h Page 58 Changed - LED Direct Duty Cycle changed bit decode to be more logarithmic F0h 95h Added controls - LED Off Delay Added bits 6-4 BR_OFF_DLY[2:0] Added bit 3 DIR_OFF_DLY[3] 00h FDh Page 63 Changed - Product ID Changed bit decode for CAP1128 52h Table A.1 Register Delta From CAP1028 to CAP1128 (continued) Address Register Delta Delta Default CAP1128 DS00001622B-page 70  2015 Microchip Technology Inc. APPENDIX B: DATA SHEET REVISION HISTORY Revision Section/Figure/Entry Correction DS00001622B (02-09-15) Features, Table 2-1, Table 2- 2, "Pin Types", Section 5.0, "General Description" References to BC-Link Interface, BC_DATA, BC_- CLK, BC-IRQ#, BC-Link bus have been removed Application Note under Table 2-6 [BC-Link] hidden in data sheet Table 3-2, "Electrical Specifications" BC-Link Timing Section hidden in data sheet Table 4-1 Protocol Used for 68K Pull Down Resistor changed from “BC-Link Communications” to “Reserved” Section 4.2.2, "SMBus Address and RD / WR Bit" Replaced “client address” with “slave address” in this section. Section 4.2.4, SMBus ACK and NACK Bits, Section 4.2.5, SMBus Stop Bit,Section 4.2.7, SMBus and I2C Compatibility Replaced “client” with “slave” in these sections. Table 4-4, "Read Byte Protocol" Heading changed from “Client Address” to “Slave Address” Table 6-1 Register Name for Register Address 77h changed from “LED Linked Transition Control” to “Linked LED Transition Control” Section 6.30 changed CS2 to LED2 Section 7.7 Package Marking Updated package drawing Appendix A: Device Delta changed 2Dh to 2Fh in item #12 Product Identification System Removed BC-Link references REV A REV A replaces previous SMSC version Rev. 1.32 (01-05-12) Rev. 1.32 (01-05-12) Table 3-2, "Electrical Specifications" Added conditions for tHD:DAT. Section 4.2.7, "SMBus and I2C Compatibility" Renamed from “SMBus and I2C Compliance.” First paragraph, added last sentence: “For information on using the CAP1188 in an I2C system, refer to SMSC AN 14.0 SMSC Dedicated Slave Devices in I 2C Systems.” Added: CAP1188 supports I2C fast mode at 400kHz. This covers the SMBus max time of 100kHz. Section 6.4, "Sensor Input Delta Count Registers" Changed negative value cap from FFh to 80h. Rev. 1.31 (08-18-11) Section 4.3.3, "SMBus Send Byte" Added an application note: The Send Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Section 4.3.4, "SMBus Receive Byte" Added an application note: The Receive Byte protocol is not functional in Deep Sleep (i.e., DSLEEP bit is set). Rev. 1.3 (05-18-11) Section 6.42, "Revision Register" Updated revision ID from 82h to 83h. Rev. 1.2 (02-10-11) Section A.8, "Delta from Rev B (Mask B0) to Rev C (Mask B1)" Added. Table 2-1, "Pin Description for CAP1128" Changed value in “Unused Connection” column for the ADDR_COMM pin from “Connect to Ground” to “n/a“.  2015 Microchip Technology Inc. DS00001622B-page 71 CAP1128 Table 3-2, "Electrical Specifications" PSR improvements made in functional revision B. Changed PSR spec from ±100 typ and ±200 max counts / V to ±3 and ±10 counts / V. Conditions updated. Section 5.5.2, "Recalibrating Sensor Inputs" Added more detail with subheadings for each type of recalibration. Section 6.6, "Configuration Registers" Added bit 5 BLK_PWR_CTRL to the Configuration 2 Register 44h. The TIMEOUT bit is set to ‘1’ by default for functional revision B and is set to ‘0’ by default for functional revision C. Section 6.42, "Revision Register" Updated revision ID in register FFh from 81h to 82h. Rev. 1.1 (11-17-10) Document Updated for functional revision B. See Section A.7, "Delta from Rev A (Mask A0) to Rev B (Mask B0)". Cover Added to General Description: “includes circuitry and support for enhanced sensor proximity detection.” Added the following Features: Calibrates for Parasitic Capacitance Analog Filtering for System Noise Sources Press and Hold feature for Volume-like Applications Table 3-2, "Electrical Specifications" Conditions for Power Supply Rejection modified adding the following: Sampling time = 2.56ms Averaging = 1 Negative Delta Counts = Disabled All other parameters default Section 6.11, "Calibration Activate Register" Updated register description to indicate which re-calibration routine is used. Section 6.14, "Multiple Touch Configuration Register" Updated register description to indicate what will happen. Table 6-34, "CSx_BN_TH Bit Decode" Table heading changed from “Threshold Divide Setting” to “Percent Threshold Setting”. Rev. 1.0 (06-14-10) Initial release Revision Section/Figure/Entry Correction CAP1128 DS00001622B-page 72  2015 Microchip Technology Inc. THE MICROCHIP WEB SITE Microchip provides online support via our WWW site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support  2015 Microchip Technology Inc. DS00001622B-page 73 CAP1128 PRODUCT IDENTIFICATION SYSTEM To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. PART NO. [X] - 1 - XXX - [X](1) l l l l Device Temperature Package Tape and Reel Range Option Example: Note 1: Tape and Reel identifier only appears in the catalog part number description. This identifier is used for ordering purposes and is not printed on the device package. Check with your Microchip Sales Office for package availability with the Tape and Reel option. Device: CAP1128 Temperature Range: Blank = 0°C to +85°C (Extended Commercial) Package: BP = QFN Tape and Reel Option: TR = Tape and Reel(1) CAP1128-1-BP-TR 20-pin QFN 4mm x 4mm (RoHS compliant) Eight capacitive touch sensor inputs, Two LED drivers, Dedicated Wake, Reset, SMBus / BC-Link / SPI interfaces Reel size is 4,000 pieces CAP1128 DS00001622B-page 74  2015 Microchip Technology Inc. Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Information contained in this publication 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. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, flexPWR, JukeBlox, KEELOQ, KEELOQ logo, Kleer, LANCheck, MediaLB, MOST, MOST logo, MPLAB, OptoLyzer, PIC, PICSTART, PIC32 logo, RightTouch, SpyNIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. The Embedded Control Solutions Company and mTouch are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, ECAN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, KleerNet, KleerNet logo, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, RightTouch logo, REAL ICE, SQI, Serial Quad I/O, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2015, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 9781632770325 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 ==  2015 Microchip Technology Inc. DS00001622B-page 75 AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 New York, NY Tel: 631-435-6000 San Jose, CA Tel: 408-735-9110 Canada - Toronto Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2943-5100 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Dongguan Tel: 86-769-8702-9880 China - Hangzhou Tel: 86-571-8792-8115 Fax: 86-571-8792-8116 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 ASIA/PACIFIC China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7828 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 EUROPE Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Dusseldorf Tel: 49-2129-3766400 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Pforzheim Tel: 49-7231-424750 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Venice Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Poland - Warsaw Tel: 48-22-3325737 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service 01/27/15

Au format texte